Ensure that Amazon mode uses config.yaml categories, does not overwrite. Remove unneeded "legacy" categories.yaml handling (#22)

I ran into some minor issues when loading up Amazon mode that arose from
recent changes. This normalizes behavior and makes sure that if you have
synced Monarch or YNAB categories to config.yaml, that these will be
used for categorization in Amazon mode, rather than the default/built-in
categories which may be more limited.

---------

Co-authored-by: Claude <[email protected]>

Author: wesm

docs/categories.md

@@ -86,32 +86,43 @@ This shows the actual categories being used (fetched from backend or defaults).
 
 ---
 
-## Advanced: Manual Category Customization (Legacy)
+## Advanced: Custom Category Overrides
 
-!!! 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.
+!!! info "Only for advanced users"
+    Most users don't need this. Monarch/YNAB categories are automatically fetched and synced.
 
-    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`:
+You can customize how categories are organized by editing `~/.moneyflow/config.yaml`:
 
 ```yaml
 version: 1
 
-# Manually defined categories (overrides fetched_categories if present)
-custom_categories:
-  Food:
+# Backend categories (auto-populated by Monarch/YNAB)
+fetched_categories:
+  Food & Dining:
     - Groceries
     - Restaurants
-  Shopping:
-    - Clothing
-    - Electronics
+
+# Optional: Custom overrides (applied on top of fetched_categories)
+categories:
+  rename_groups:
+    "Food & Dining": "Food"
+  add_to_groups:
+    Food:
+      - Fast Food
 ```
 
-**Note:** Manual customization is rarely needed with the new auto-fetch system.
+**Available customizations:**
+
+- `rename_groups` - Rename category groups
+- `rename_categories` - Rename individual categories
+- `add_to_groups` - Add categories to existing groups
+- `custom_groups` - Create entirely new groups
+- `move_categories` - Move categories between groups
+
+**Which backends write to config.yaml:**
+
+- Monarch/YNAB: Write `fetched_categories` on every startup
+- Amazon/Demo: Only read, never write
 
 ---
 
@@ -166,7 +177,12 @@ fetched_categories:
     - Category 2
 ```
 
-**Fallback order:**
+**Category resolution (two-step process):**
+
+1. **Base categories** (one or the other, NOT merged):
+   - `fetched_categories` from config.yaml (if present)
+   - OR built-in `DEFAULT_CATEGORY_GROUPS` from `categories.py`
 
-1. `fetched_categories` from config.yaml
-2. Built-in `DEFAULT_CATEGORY_GROUPS` from `categories.py`
+2. **Custom overrides** (merged on top of base):
+   - `categories` section from config.yaml (if present)
+   - Applied via rename_groups, add_to_groups, etc.

docs/config/advanced.md

@@ -54,5 +54,3 @@ All moneyflow configuration is stored in `~/.moneyflow/`:
 ```
 
 **Security note:** credentials.enc is encrypted with AES-128. Safe to backup but keep private.
-
-**Backward compatibility:** Legacy `categories.yaml` files are still supported.

moneyflow/app.py

@@ -1915,12 +1915,13 @@ def launch_monarch_mode(
         sys.exit(1)
 
 
-def launch_amazon_mode(db_path: Optional[str] = None) -> None:
+def launch_amazon_mode(db_path: Optional[str] = None, config_dir: Optional[str] = None) -> None:
     """
     Launch moneyflow in Amazon purchase analysis mode.
 
     Args:
         db_path: Path to Amazon SQLite database (default: ~/.moneyflow/amazon.db)
+        config_dir: Config directory for loading categories (default: ~/.moneyflow)
 
     Uses the AmazonBackend with data stored in SQLite.
     Data must be imported first using: moneyflow amazon import <csv>
@@ -1929,12 +1930,14 @@ def launch_amazon_mode(db_path: Optional[str] = None) -> None:
     from moneyflow.backends.amazon import AmazonBackend
 
     # Initialize logging
-    logger = setup_logging(console_output=False, config_dir=None)
+    logger = setup_logging(console_output=False, config_dir=config_dir)
     logger.info("Starting moneyflow in Amazon mode")
+    if config_dir:
+        logger.info(f"Using custom config directory: {config_dir}")
 
     try:
         # Create Amazon backend and config
-        backend = AmazonBackend(db_path=db_path)
+        backend = AmazonBackend(db_path=db_path, config_dir=config_dir)
         config = BackendConfig.for_amazon()
 
         # Create MoneyflowApp in Amazon mode

moneyflow/backends/amazon.py

@@ -10,7 +10,7 @@
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
-from ..categories import DEFAULT_CATEGORY_GROUPS
+from ..categories import get_effective_category_groups
 from .base import FinanceBackend
 
 
@@ -25,19 +25,21 @@ class AmazonBackend(FinanceBackend):
     imported from CSV files exported from Amazon.com.
     """
 
-    def __init__(self, db_path: Optional[str] = None):
+    def __init__(self, db_path: Optional[str] = None, config_dir: Optional[str] = None):
         """
         Initialize the Amazon backend.
 
         Args:
             db_path: Path to SQLite database. Defaults to ~/.moneyflow/amazon.db
+            config_dir: Config directory for loading categories. Defaults to ~/.moneyflow
 
         Note: Database file is not created until first access (lazy initialization).
         """
         if db_path is None:
             db_path = str(Path.home() / ".moneyflow" / "amazon.db")
 
         self.db_path = Path(db_path).expanduser()
+        self.config_dir = config_dir
         self._db_initialized = False
 
     def _ensure_db_initialized(self) -> None:
@@ -282,19 +284,24 @@ async def get_transactions(
 
     async def get_transaction_categories(self) -> Dict[str, Any]:
         """
-        Fetch all categories from centralized category list.
+        Fetch all categories from config.yaml (or defaults if not present).
 
-        Returns categories from categories.py (not database) to avoid data duplication
-        and allow easy updates via config file.
+        Returns categories from config.yaml if available (e.g., fetched from Monarch),
+        otherwise uses built-in defaults. This allows Amazon mode to use the same
+        category structure as your primary backend.
 
         Returns:
             Dictionary containing categories in standard format
         """
         categories = []
         cat_id_counter = 1
 
-        # Build categories from DEFAULT_CATEGORY_GROUPS
-        for group_name, category_names in DEFAULT_CATEGORY_GROUPS.items():
+        # Load category groups from config.yaml if available, otherwise use built-in defaults
+        # Note: This is NOT a merge - it's one or the other (priority: config.yaml > defaults)
+        category_groups = get_effective_category_groups(self.config_dir)
+
+        # Build categories from loaded category groups
+        for group_name, category_names in category_groups.items():
             for cat_name in category_names:
                 cat_id = f"cat_{cat_name.lower().replace(' ', '_').replace('&', 'and')}"
                 categories.append(
@@ -348,11 +355,12 @@ async def update_transaction(
         if category_id is not None:
             updates.append("category_id = ?")
             params.append(category_id)
-            # Also update category name from DEFAULT_CATEGORY_GROUPS
+            # Also update category name from effective category groups
             # (group is derived from category by data_manager, not stored)
             # Build category_id → category_name lookup
+            category_groups = get_effective_category_groups(self.config_dir)
             category_name = None
-            for group_name, category_names in DEFAULT_CATEGORY_GROUPS.items():
+            for group_name, category_names in category_groups.items():
                 for cat_name in category_names:
                     cat_id = f"cat_{cat_name.lower().replace(' ', '_').replace('&', 'and')}"
                     if cat_id == category_id:

moneyflow/categories.py

@@ -137,9 +137,6 @@ def load_custom_categories(config_dir: Optional[str] = None) -> Optional[Dict[st
     """
     Load custom category configuration from ~/.moneyflow/config.yaml.
 
-    Supports both new config.yaml format (with categories: section) and
-    legacy categories.yaml format (for backward compatibility).
-
     Args:
         config_dir: Optional custom config directory (default: ~/.moneyflow)
 
@@ -166,9 +163,7 @@ def load_custom_categories(config_dir: Optional[str] = None) -> Optional[Dict[st
         config_dir = str(Path.home() / ".moneyflow")
 
     config_path = Path(config_dir) / "config.yaml"
-    legacy_path = Path(config_dir) / "categories.yaml"
 
-    # Try new config.yaml format first
     if config_path.exists():
         try:
             with open(config_path, "r") as f:
@@ -199,39 +194,8 @@ def load_custom_categories(config_dir: Optional[str] = None) -> Optional[Dict[st
         except Exception as e:
             logger.error(f"Failed to load config: {e}")
             return None
-
-    # Fall back to legacy categories.yaml
-    elif legacy_path.exists():
-        logger.warning(
-            "Using legacy categories.yaml. Please rename to config.yaml and nest under 'categories:' section"
-        )
-        try:
-            with open(legacy_path, "r") as f:
-                config = yaml.safe_load(f)
-
-            if not config:
-                logger.warning(f"Empty categories config at {legacy_path}")
-                return None
-
-            # Validate version
-            version = config.get("version")
-            if version != 1:
-                logger.warning(f"Unsupported categories.yaml version: {version} (expected 1)")
-                return None
-
-            logger.info(f"Loaded custom categories from {legacy_path} (legacy format)")
-            # Return config directly (legacy format has categories at top level)
-            return config
-
-        except yaml.YAMLError as e:
-            logger.error(f"Failed to parse {legacy_path}: {e}")
-            return None
-        except Exception as e:
-            logger.error(f"Failed to load legacy categories: {e}")
-            return None
-
     else:
-        logger.debug(f"No config file at {config_path} or {legacy_path}")
+        logger.debug(f"No config file at {config_path}")
         return None
 
 
@@ -417,10 +381,10 @@ def save_categories_to_config(
     # Ensure version is set
     config["version"] = 1
 
-    # Store fetched categories
+    # Store fetched categories (preserves all other existing keys in config)
     config["fetched_categories"] = category_groups
 
-    # Write back to file
+    # Write back to file (preserving all existing keys like 'categories', etc.)
     Path(config_dir).mkdir(parents=True, exist_ok=True, mode=0o700)
     with open(config_path, "w") as f:
         yaml.dump(config, f, default_flow_style=False, sort_keys=False)
@@ -450,18 +414,20 @@ def build_category_to_group_mapping(category_groups: Dict[str, List[str]]) -> Di
 
 def get_effective_category_groups(config_dir: Optional[str] = None) -> Dict[str, List[str]]:
     """
-    Get effective category groups with priority order:
+    Get category groups (NOT a merge - returns one or the other).
+
+    Priority order:
     1. Fetched categories from backend API (stored in config.yaml)
     2. Built-in defaults from categories.py
 
-    For Monarch/YNAB: Uses fetched_categories from config.yaml (populated on every startup)
+    For Monarch/YNAB: Uses fetched_categories from config.yaml (populated on startup)
     For Demo/Amazon: Uses fetched_categories if available, otherwise built-in defaults
 
     Args:
         config_dir: Optional custom config directory (default: ~/.moneyflow)
 
     Returns:
-        Final category groups dict
+        Category groups dict (either from config.yaml OR defaults, never merged)
     """
     if config_dir is None:
         config_dir = str(Path.home() / ".moneyflow")

moneyflow/cli.py

@@ -81,23 +81,30 @@ def cli(ctx, year, since, mtd, cache, refresh, demo, config_dir):
     default=None,
     help="Path to Amazon SQLite database (default: ~/.moneyflow/amazon.db)",
 )
+@click.option(
+    "--config-dir",
+    type=click.Path(),
+    default=None,
+    help="Config directory (default: ~/.moneyflow). Used for loading categories from config.yaml.",
+)
 @click.pass_context
-def amazon(ctx, db_path):
+def amazon(ctx, db_path, config_dir):
     """Amazon purchase analysis mode.
 
     Run 'moneyflow amazon' to launch the UI.
     Use subcommands for import/status operations.
     """
-    # Store db_path in context for subcommands
+    # Store db_path and config_dir in context for subcommands
     ctx.ensure_object(dict)
     ctx.obj["db_path"] = db_path
+    ctx.obj["config_dir"] = config_dir
 
     # If no subcommand, launch the UI
     if ctx.invoked_subcommand is None:
         from moneyflow.app import launch_amazon_mode
         from moneyflow.backends.amazon import AmazonBackend
 
-        backend = AmazonBackend(db_path=db_path)
+        backend = AmazonBackend(db_path=db_path, config_dir=config_dir)
 
         # Check if database exists
         if not backend.db_path.exists():
@@ -117,7 +124,7 @@ def amazon(ctx, db_path):
             raise click.Abort()
 
         # Launch the UI
-        launch_amazon_mode(db_path=db_path)
+        launch_amazon_mode(db_path=db_path, config_dir=config_dir)
 
 
 @amazon.command(name="import")
@@ -245,12 +252,11 @@ def categories():
     help="Output format: yaml (copy-pastable) or readable (with counts)",
 )
 def categories_dump(config_dir, format):
-    """Display current category hierarchy (defaults + custom from config.yaml).
+    """Display current category hierarchy.
 
-    Shows the effective category structure including:
-    - Built-in defaults
-    - Custom categories from ~/.moneyflow/config.yaml
-    - Category renames and moves
+    Shows categories from config.yaml if available (fetched from backend),
+    otherwise shows built-in defaults. This is NOT a merge - it's one or
+    the other (priority: config.yaml > defaults).
 
     Default output is YAML format (copy-pastable into config.yaml under 'categories:').
     Use --format=readable for human-readable format with counts.
@@ -300,16 +306,12 @@ def categories_dump(config_dir, format):
         # Show config file location
         if config_dir:
             config_path = Path(config_dir) / "config.yaml"
-            legacy_path = Path(config_dir) / "categories.yaml"
         else:
             config_path = Path.home() / ".moneyflow" / "config.yaml"
-            legacy_path = Path.home() / ".moneyflow" / "categories.yaml"
 
         click.echo(f"\n# {'=' * 58}")
         if config_path.exists():
             click.echo(f"# Custom config: {config_path}")
-        elif legacy_path.exists():
-            click.echo(f"# Custom config: {legacy_path} (legacy format)")
         else:
             click.echo(f"# Using built-in defaults (no custom config at {config_path})")
 

moneyflow/data_manager.py

@@ -78,7 +78,7 @@ def __init__(
         Args:
             mm: Backend instance (must implement FinanceBackend interface)
             merchant_cache_dir: Directory for merchant cache (defaults to ~/.moneyflow/)
-            config_dir: Optional config directory for categories.yaml (defaults to ~/.moneyflow/)
+            config_dir: Optional config directory for config.yaml (defaults to ~/.moneyflow/)
         """
         self.mm = mm
         self.config_dir = config_dir  # Store for apply_category_groups
@@ -407,7 +407,7 @@ def _transactions_to_dataframe(
         Convert raw transaction data to Polars DataFrame with enriched fields.
 
         Note: Does NOT include 'group' field - groups are applied dynamically
-        via apply_category_groups() so changes to categories.yaml take effect
+        via apply_category_groups() so changes to config.yaml take effect
         on cached data.
         """
         if not transactions:
@@ -458,9 +458,9 @@ def apply_category_groups(self, df: pl.DataFrame) -> pl.DataFrame:
         Apply category-to-group mapping to a DataFrame.
 
         This adds/updates the 'group' column based on category groups from
-        categories module (defaults + custom from ~/.moneyflow/categories.yaml).
+        config.yaml (or built-in defaults if config.yaml not present).
         Called after loading data (from API or cache) so that changes to
-        categories.yaml always take effect.
+        config.yaml always take effect.
 
         Args:
             df: DataFrame with 'category' column