# Category Configuration

## Overview

moneyflow automatically uses your backend's category structure:

- **Monarch Money** - Fetches your actual Monarch categories on every startup
- **YNAB** - Fetches your actual YNAB budget categories on every startup
- **Amazon Mode** - Uses categories from your Monarch/YNAB account (if previously configured), otherwise uses built-in defaults
- **Demo Mode** - Uses built-in default categories

**No manual configuration needed!** Categories are automatically synced from your finance platform.

---

## How It Works

### For Monarch Money and YNAB Users

On every startup, moneyflow:

1. **Fetches your categories** from Monarch/YNAB API
2. **Saves them to `~/.moneyflow/config.yaml`** under `fetched_categories`
3. **Uses them throughout the session** for grouping and filtering

Your categories are always up-to-date with your finance platform. If you add or rename categories in
Monarch or YNAB, they'll automatically appear in moneyflow on next launch.

**Example config.yaml (auto-generated):**

```yaml
version: 1
fetched_categories:
  Food & Dining:
    - Groceries
    - Restaurants & Bars
    - Coffee Shops
  Shopping:
    - Clothing
    - Electronics
  Auto & Transport:
    - Gas
    - Auto Payment
    - Parking
```

### For Amazon Mode Users

When you launch Amazon mode, moneyflow:

1. **Checks for `fetched_categories` in config.yaml**
2. If found (from a previous Monarch/YNAB setup), uses those categories
3. If not found, uses built-in default categories

This means Amazon purchases are categorized using the same category structure as your main finance platform.

### For Demo Mode Users

Demo mode always uses the built-in default categories (~60 categories in 15 groups). This provides a consistent demo experience.

---

## Built-in Default Categories

If no `fetched_categories` exist in config.yaml, moneyflow uses built-in defaults:

- **15 groups**: Income, Food & Dining, Shopping, Auto & Transport, Housing, Bills & Utilities,
  Travel & Lifestyle, Health & Wellness, Children, Education, Gifts & Donations, Financial,
  Business, Uncategorized, Transfers
- **~60 categories**: Groceries, Restaurants, Gas, Shopping, Medical, etc.

These defaults are based on Monarch Money's category structure and work well for most personal finance scenarios.

---

## Viewing Your Categories

**View your current category structure:**

```bash
moneyflow categories dump              # YAML format
moneyflow categories dump --format=readable  # Human-readable with counts
```

This shows the actual categories being used (fetched from backend or defaults).

---

## Advanced: Manual Category Customization (Legacy)

!!! warning "Not recommended for Monarch/YNAB users"
    For Monarch and YNAB users, we recommend using your backend's categories directly.
    They're automatically fetched and synced on every startup.

    Manual customization is primarily useful for Amazon mode users who want to define their
    own category structure.

If you need to manually define categories (e.g., for Amazon-only usage without Monarch/YNAB),
you can create a custom category structure in `config.yaml`:

```yaml
version: 1

# Manually defined categories (overrides fetched_categories if present)
custom_categories:
  Food:
    - Groceries
    - Restaurants
  Shopping:
    - Clothing
    - Electronics
```

**Note:** Manual customization is rarely needed with the new auto-fetch system.

---

## Troubleshooting

### Categories don't match my Monarch/YNAB account

**Solution:** Restart moneyflow. Categories are fetched fresh on every startup.

### I want to use Monarch categories in Amazon mode

**Solution:** Run moneyflow with Monarch at least once. The categories will be saved to
`config.yaml` and automatically used by Amazon mode.

### I see "Using built-in default categories" in logs

This is normal for:

- First run before connecting to Monarch/YNAB
- Demo mode
- Amazon mode without previous Monarch/YNAB setup

To get your actual categories, connect to Monarch or YNAB.

### How do I reset to defaults?

Delete the fetched categories from config.yaml:

```bash
# Remove fetched_categories section
# Edit ~/.moneyflow/config.yaml and delete the 'fetched_categories:' section

# Or delete entire config
rm ~/.moneyflow/config.yaml
```

---

## Technical Details

**Storage location:** `~/.moneyflow/config.yaml`

**Update frequency:** On every Monarch/YNAB startup (keeps categories in sync)

**Format:**

```yaml
version: 1
fetched_categories:
  Group Name:
    - Category 1
    - Category 2
```

**Fallback order:**

1. `fetched_categories` from config.yaml
2. Built-in `DEFAULT_CATEGORY_GROUPS` from `categories.py`
