Add fuzzy matching for Amazon transaction linking, documentation and table aesthetic improvements

.gitignore

@@ -38,6 +38,7 @@ htmlcov/
 *.swp
 *.swo
 *~
+.#*
 .claude/settings.local.json
 
 # moneyflow specific

CLAUDE.md

@@ -14,6 +14,17 @@
 - "Should I switch to branch X to work on this?"
 - "Should I create a new branch for this feature?"
 
+## CRITICAL: Personal Data Protection
+
+**⚠️ NEVER include user's personal data in code, comments, or documentation.**
+
+This is a personal finance application. Users may share screenshots or logs containing real financial data (account names, transaction details, merchant names, etc.) when debugging issues.
+
+- ❌ **NEVER copy personal data** from screenshots/logs into code comments
+- ❌ **NEVER use real account names, card numbers, or transaction details** as examples
+- ✅ **Use generic examples** like "Account Name", "Example Merchant", etc.
+- ✅ **If you need to reference data formats**, use clearly fake data
+
 ## Project Overview
 
 moneyflow is a terminal-based UI for power users to manage personal finance transactions efficiently. Built with Python using Textual for the UI and Polars for data processing. Supports multiple backends including Monarch Money, with more platforms planned (YNAB, Lunch Money, etc.).
@@ -244,6 +255,55 @@ uv run ruff format moneyflow/ tests/
 uv run ruff check --fix moneyflow/ tests/
 ```
 
+### Working with Documentation
+
+The project uses MkDocs with Material theme for documentation.
+
+**Starting the docs server:**
+
+```bash
+# IMPORTANT: Always delete site/ first to avoid stale content
+rm -rf site/ && uv run mkdocs serve
+
+# Or on a specific port
+rm -rf site/ && uv run mkdocs serve -a 127.0.0.1:8002
+```
+
+**Generating/regenerating screenshots:**
+
+```bash
+# Generate all screenshots
+uv run python scripts/generate_screenshots.py
+
+# Generate only specific screenshots (by filename filter)
+uv run python scripts/generate_screenshots.py --filter amazon-matching
+
+# IMPORTANT: After regenerating, restart mkdocs for changes to appear
+```
+
+**Live Reload Configuration:**
+
+- `mkdocs.yml` includes a `watch` section that monitors `docs/assets/screenshots/`
+- Static assets (SVG, PNG) should auto-reload when changed
+- If live reload stops working, check the click version (see Known Issues below)
+
+**Known Issues:**
+
+- **Click 8.3.0 breaks live reload**: MkDocs file watching is broken with `click>=8.3.0`.
+  This is constrained in `pyproject.toml` (`click>=8.1.0,<8.3.0`). If the constraint is
+  removed in the future, check [mkdocs issue #4032](https://github.com/mkdocs/mkdocs/issues/4032)
+  for status before upgrading.
+
+- **Stale screenshots/images**: If docs show old images after regenerating:
+  1. Delete `site/` directory: `rm -rf site/`
+  2. Restart `mkdocs serve`
+  3. Hard refresh browser (`Cmd+Shift+R` / `Ctrl+Shift+R`)
+  4. Try a different port to bypass browser cache
+
+- **HTML img tags need different paths**: When using `<img>` tags in markdown (for tables),
+  paths resolve relative to the page URL, not the source file. Use `../../assets/` for
+  pages in subdirectories like `guide/navigation.md`.
+
 ### Configuration
 
 - `pyproject.toml` contains configuration for ruff and pyright

docs/config/advanced.md

@@ -27,17 +27,23 @@ most personal finance platforms.
 
 ## Data Caching
 
-Speed up startup by caching transaction data locally.
+Transaction data is cached locally by default for fast startup. The cache is encrypted with the same key as your
+credentials.
 
-**Usage:**
+**Cache behavior:**
+
+- First run: Downloads all transactions from your backend
+- Subsequent runs: Uses cached data instantly
+- Cache auto-refreshes when you make edits that sync to the backend
+
+**Options:**
 
 ```bash
-moneyflow --cache              # Enable caching (uses ~/.moneyflow/cache/)
-moneyflow --cache ~/my-cache   # Custom cache location
-moneyflow --refresh            # Force refresh, skip cache
+moneyflow --refresh            # Force refresh from API (ignore cache)
+moneyflow --no-cache           # Disable caching entirely for this session
 ```
 
-**See:** [Caching Guide](caching.md) for details.
+**See:** [Caching Guide](caching.md) for details on cache location and management.
 
 ## Configuration Directory
 
@@ -49,7 +55,7 @@ All moneyflow configuration is stored in `~/.moneyflow/`:
 ├── credentials.enc    # Encrypted credentials
 ├── salt               # Encryption salt
 ├── merchants.json     # Merchant name cache
-├── cache/             # Transaction cache (if --cache enabled)
+├── cache/             # Encrypted transaction cache
 └── moneyflow.log      # Application logs
 ```
 

docs/config/caching.md

@@ -1,5 +1,57 @@
 # Caching
 
-Speed up startup with transaction caching.
+moneyflow caches your transaction data locally for fast startup. Caching is **enabled by default**.
 
-[Documentation coming soon]
+## How It Works
+
+1. **First run**: Downloads all transactions from your backend (Monarch Money, YNAB, etc.)
+2. **Subsequent runs**: Loads instantly from encrypted local cache
+3. **Auto-refresh**: Cache updates when you commit changes to your backend
+
+## Cache Location
+
+```text
+~/.moneyflow/cache/
+```
+
+Or within your profile directory if using multiple accounts:
+
+```text
+~/.moneyflow/profiles/<profile-name>/cache/
+```
+
+## Security
+
+The cache is **encrypted** using the same AES-128 encryption as your credentials. Your transaction data is never
+stored in plain text.
+
+## CLI Options
+
+| Option | Description |
+|--------|-------------|
+| `--refresh` | Force download from API, ignoring cache |
+| `--no-cache` | Disable caching for this session |
+
+## Common Scenarios
+
+### Force a fresh download
+
+```bash
+moneyflow --refresh
+```
+
+Use this when you've made changes directly in your finance platform and want to see them immediately.
+
+### Troubleshoot cache issues
+
+```bash
+# Run without cache to see if issue is cache-related
+moneyflow --no-cache
+
+# Or delete the cache directory
+rm -rf ~/.moneyflow/cache/
+```
+
+### Check cache status
+
+The cache status is shown in the application logs at `~/.moneyflow/moneyflow.log`.

docs/development/developing.md

@@ -142,6 +142,9 @@ uv run pytest -x
 # With coverage
 uv run pytest --cov --cov-report=html
 open htmlcov/index.html
+
+# Integration tests (Textual)
+uv run pytest -m integration tests/integration -v -o addopts=
 ```
 
 ## CI/CD

docs/getting-started/quickstart.md

@@ -14,6 +14,8 @@ moneyflow --demo
 
 This loads synthetic spending data so you can explore all features risk-free.
 
+![Merchants view](../assets/screenshots/cycle-1-merchants.svg)
+
 **What you'll see:**
 
 - ~3,000 transactions across 3 years (2023-2025)
@@ -25,6 +27,26 @@ Press ++g++ to cycle through views, ++slash++ to search, ++q++ to quit.
 
 ---
 
+## Explore the Views
+
+Press ++g++ to cycle through different aggregation views:
+
+<div class="screenshot-grid" markdown>
+
+![Categories view](../assets/screenshots/cycle-2-categories.svg)
+*Categories - See spending by category*
+
+![Time view](../assets/screenshots/cycle-5-time-years.svg)
+*Time - Analyze spending over time*
+
+</div>
+
+Press ++enter++ on any row to drill down into transaction details:
+
+![Drill down to transactions](../assets/screenshots/drill-down-detail.svg)
+
+---
+
 ## With Your Finance Platform
 
 Choose your platform:
@@ -56,7 +78,9 @@ Choose your platform:
 moneyflow
 ```
 
-On first run, you'll be prompted for:
+On first run, you'll be prompted for credentials:
+
+![Monarch credentials](../assets/screenshots/monarch-credentials.svg)
 
 1. **Monarch Money email** - Your login email
 2. **Monarch Money password** - Your account password
@@ -68,62 +92,7 @@ On first run, you'll be prompted for:
 
     Choose something you'll remember - you'll need it each time you launch moneyflow.
 
-### Wait for Initial Data Load
-
-First run downloads all your transactions:
-
-- **Small accounts** (<1k transactions): ~10 seconds
-- **Medium accounts** (1k-10k): ~30 seconds
-- **Large accounts** (10k+): ~1-2 minutes
-
-!!! success "One-Time Download"
-    After the first load, all operations are instant! moneyflow works offline with your data cached locally.
-
-### Explore
-
-You're in! Here's what to try:
-
-- Press ++g++ to cycle views: Merchants, Categories, Groups, Accounts, Time
-- In Time view: Press ++t++ to cycle through Year, Month, and Day granularities
-- Press ++enter++ on any row to drill down
-- Press ++escape++ to go back
-- Press ++question++ for help
-
----
-
-## Common First Commands
-
-```bash
-# Fetch only current year from API (faster for large Monarch/YNAB accounts)
-moneyflow --year 2025
-
-# Enable caching for even faster startup next time
-moneyflow --cache
-
-# Fetch recent data + enable cache
-moneyflow --year 2025 --cache
-```
-
-!!! note
-    By default, all fetched data is shown in the view. Use TIME view to analyze specific periods.
-
----
-
-## Quick Edit Example
-
-Let's rename a merchant:
-
-1. Launch: `moneyflow`
-2. Press ++g++ until you see "Merchants" view
-3. Use arrow keys to find a merchant
-4. Press ++m++ to edit merchant name
-5. Type the new name, press ++enter++
-6. Press ++w++ to review changes
-7. Press ++enter++ to commit to your backend (Monarch/YNAB)
-
-Done! The change is now saved.
-
----
+Transactions are cached locally after the initial download for instant startup.
 
 ---
 
@@ -148,38 +117,50 @@ moneyflow
 
 On first run, you'll be prompted for:
 
+![YNAB credentials](../assets/screenshots/ynab-credentials.svg)
+
 1. **Backend selection** - Choose **YNAB**
 2. **Personal Access Token** - Paste the token from Step 1
 3. **Encryption password** - Create a NEW password to encrypt your stored credentials
 
-!!! tip "Encryption Password"
-    This is a **new password** just for moneyflow, not your YNAB password.
-
-    Choose something you'll remember - you'll need it each time you launch moneyflow.
-
 !!! info "Multiple Budgets"
     If you have multiple YNAB budgets, moneyflow will automatically use the first one. Multi-budget selection UI is
     not yet implemented.
 
-### Wait for Initial Data Load (YNAB)
+Transactions are cached locally after the initial download for instant startup.
 
-First run downloads all your transactions:
+---
+
+## Common First Commands
 
-- **Small budgets** (<1k transactions): ~5 seconds
-- **Medium budgets** (1k-10k): ~15 seconds
-- **Large budgets** (10k+): ~30-60 seconds
+```bash
+# Fetch only current year from API (faster for large accounts)
+moneyflow --year 2025
 
-!!! success "One-Time Download"
-    After the first load, all operations are instant! moneyflow works offline with your data cached locally.
+# Force refresh from API (ignore cache)
+moneyflow --refresh
+```
 
-### Explore (YNAB)
+!!! note
+    Caching is enabled by default. Your transactions are stored in an encrypted local cache for fast startup.
+    Use `--refresh` to force a fresh download from your backend.
 
-You're in! Here's what to try:
+---
 
-- Press ++g++ to cycle views: Merchants, Categories, Groups, Accounts
-- Press ++enter++ on any row to drill down
-- Press ++escape++ to go back
-- Press ++question++ for help
+## Quick Edit Example
+
+Let's rename a merchant:
+
+1. Press ++g++ until you see "Merchants" view
+2. Use arrow keys to find a merchant
+3. Press ++m++ to edit merchant name
+4. Type the new name, press ++enter++
+5. Press ++w++ to review changes
+6. Press ++enter++ to commit to your backend (Monarch/YNAB)
+
+![Edit merchant](../assets/screenshots/drill-down-bulk-edit-merchant.svg)
+
+Done! The change is now saved.
 
 ---