some initial docs

Author: heskew

.gitignore

@@ -15,6 +15,10 @@
 # UI
 ui/node_modules/
 ui/dist/
+
+# Docs
+docs/site/node_modules/
+docs/site/_site/
 ui/.vite/
 ui/test-results/
 ui/playwright-report/
@@ -41,7 +45,3 @@ logs/
 # Backups
 *.bak
 backups/
-
-# Private docs (not yet public)
-docs/
-CLAUDE.md

CLAUDE.md

@@ -0,0 +1,208 @@
+# CLAUDE.md - Development Context for Hone
+
+This file provides context for AI-assisted development sessions.
+
+## Project Overview
+
+Hone is a self-hosted personal finance tool that detects wasteful spending:
+- Zombie subscriptions (forgotten recurring charges)
+- Price increases (services that quietly raised prices)
+- Duplicate services (multiple streaming/storage/etc)
+
+## Architecture
+
+See `README.md` for architecture diagram. Stack: React + Vite frontend, Axum REST API, SQLite database.
+
+## Crate Structure
+
+- **hone-core**: Shared library
+  - `db/` - SQLite with r2d2 pooling, SQLCipher encryption
+  - `backup/` - Pluggable backup system (local filesystem, R2 stub)
+  - `models.rs` - Domain types
+  - `import.rs` - CSV parsers for major US banks
+  - `export.rs` - Transaction CSV export, full JSON backup/restore
+  - `detect.rs` - Waste detection algorithms
+  - `tags.rs` - Tag assignment engine
+  - `ai/` - Pluggable local AI backend (Ollama, OpenAI-compatible, Mock)
+  - `prompts.rs` - Prompt library with override support
+  - `model_router.rs` - Task-based model routing with health tracking
+  - `context.rs` - Context assembler for LLM prompts
+  - `training.rs`, `training_pipeline.rs` - Fine-tuning infrastructure
+  - `insights/` - Proactive financial insights engine
+
+- **hone-cli**: Command-line interface
+  - `commands/` - Command implementations split by domain
+  - Commands: init, import, detect, serve, dashboard, status, accounts, transactions, subscriptions, alerts, entities, tags, rules, tag, untag, report, receipts, ollama, prompts, training, export, import-full, backup, rebuild, reset
+
+- **hone-server**: Axum REST API
+  - `lib.rs` - Server config, router, auth middleware, security headers
+  - `handlers/` - Domain-specific HTTP handlers (22 modules)
+  - `mcp/` - MCP server for LLM tool access (enable with `--mcp-port 3001`)
+  - Cloudflare Access authentication, audit logging
+
+## Key Design Decisions
+
+1. **CSV-only import** - No bank credentials stored, privacy-first
+2. **Encryption required** - SQLCipher encryption by default (`HONE_DB_KEY`); `--no-encrypt` for dev
+3. **Local AI only** - Ollama and OpenAI-compatible servers. No cloud APIs
+4. **Deduplication** - SHA256 hash of (date, description, amount) prevents double-imports
+5. **Secure by default** - Cloudflare Access auth required; `--no-auth` for local dev
+6. **Audit logging** - All API access logged
+7. **Full processing by default** - Import runs tagging + detection automatically
+8. **Raw data preservation** - Original CSV data stored as JSON for reprocessing
+
+## Development Stage
+
+**Pre-shipping**: We are NOT yet at the "shipping" stage. This means:
+- **No migrations required** - Schema changes can be made directly; just reset the database
+- **No backwards compatibility** - APIs, data formats, and behavior can change freely
+- **No deprecation cycles** - Old code/approaches can be removed immediately
+
+When we explicitly agree to enter the "shipping" stage, we'll add migrations and maintain backwards compatibility.
+
+## Database Schema
+
+Key tables (see `docs/SPLITS_DESIGN.md` for entity/split schema):
+- `accounts` - Bank accounts with optional `entity_id`
+- `transactions` - Individual charges (with `archived`, `original_data`, `import_format`)
+- `subscriptions` - Detected recurring patterns with `account_id`
+- `alerts` - Waste detection findings
+- `tags` - Hierarchical category tags (17 root tags seeded)
+- `transaction_tags` - Transaction-to-tag mapping with source tracking
+- `tag_rules` - User-defined patterns for auto-tagging
+- `audit_log` - API access history
+- `entities` - People, pets, vehicles, properties
+- `locations`, `trips`, `mileage_logs` - Location and travel tracking
+- `receipts` - Receipt storage with status workflow
+- `merchant_*_cache` - Learned merchant classifications, names, tags
+- `import_sessions`, `import_skipped_transactions` - Import tracking
+- `user_feedback` - Feedback on AI-generated content
+- `training_experiments` - Fine-tuning experiment tracking
+- `reprocess_runs`, `reprocess_snapshots` - Reprocess comparison
+- `insight_findings` - Proactive financial insights
+- `ollama_metrics` - AI call tracking (latency, success, tool calls metadata for explore queries)
+
+## Current State
+
+See `docs/FEATURES.md` for comprehensive feature list.
+
+**Test coverage**: 788 Rust tests, Playwright UX tests
+
+**Not yet implemented**: Cloud backup to Cloudflare R2 (stub ready)
+
+## Detection Algorithms
+
+See `docs/DETECTION.md` for algorithm details. Six algorithms:
+- Zombie Detection - forgotten recurring charges
+- Price Increase Detection - subscription price changes
+- Duplicate Detection - multiple services in same category
+- Auto-Cancellation Detection - stopped subscriptions
+- Resume Detection - reactivated subscriptions
+- Spending Anomaly Detection - unusual spending patterns
+
+## AI Integration
+
+See `docs/ollama.md` for setup and configuration.
+
+**Three modes:**
+1. **Classification Mode** (`OLLAMA_HOST`) - merchant classification, normalization, subscription detection
+2. **Agentic Mode** (`ANTHROPIC_COMPATIBLE_HOST`) - tool-calling for deeper analysis
+3. **Explore Mode** - conversational interface using agentic mode to answer financial questions
+   - Multi-turn conversations with session persistence
+   - Model selector to switch between available Ollama models at runtime
+   - Queries tracked in AI Metrics as `explore_query` operations with tool call history
+
+**Prompts**: Stored in `prompts/` with override support (`~/.local/share/hone/prompts/overrides/`)
+
+**Model routing**: Config in `config/models.toml` with task-based routing and health tracking
+
+## Development Commands
+
+```bash
+# Build
+make build
+
+# Run backend (port 3000)
+export HONE_DB_KEY="your-passphrase-here"
+cargo run -- serve --port 3000
+
+# Run frontend dev server (port 5173)
+cd ui && npm run dev
+
+# Enable Ollama
+export OLLAMA_HOST="http://localhost:11434"
+export OLLAMA_MODEL="gemma3"
+
+# Quick test flow
+cargo run -- --no-encrypt init
+cargo run -- --no-encrypt import --file samples/sample.csv
+cargo run -- --no-encrypt dashboard
+
+# Reset database
+cargo run -- --no-encrypt reset --soft -y
+
+# Run tests
+cd ui && npm run test:ux
+```
+
+## UI Structure
+
+```
+ui/src/
+├── components/
+│   ├── common/         # Shared UI components
+│   ├── Dashboard/      # Dashboard view
+│   ├── Transactions/   # Transaction list, detail tabs
+│   ├── Subscriptions/  # Subscription management
+│   ├── Alerts/         # Alert cards with detail modal
+│   ├── Insights/       # Proactive insights
+│   ├── Import/         # CSV import, history
+│   ├── Tags/           # Tag tree management
+│   ├── Reports/        # Charts and reports (Recharts)
+│   ├── Receipts/       # Receipt upload, linking
+│   ├── Ollama/         # AI Metrics page (all AI call tracking)
+│   ├── Feedback/       # Feedback history page
+│   └── Explore/        # Conversational query interface with model selector
+├── hooks/              # Custom React hooks
+├── App.tsx             # Layout and routing
+├── api.ts              # API client
+└── types.ts            # TypeScript interfaces
+```
+
+## Code Style
+
+- Rust: Follow standard idioms, use Result types, propagate errors with `?`
+- TypeScript: Strict mode, prefer named exports
+- CSS: Tailwind utilities, custom components in index.css
+- Comments: Explain "why" not "what"
+
+## UI Design Principles
+
+- Clean, confident typography - numbers feel important
+- Semantic color: green=income, amber=attention, red=waste (not all expenses)
+- Normal expenses use neutral colors
+- Subtle motion - alive but not distracting
+- Satisfying interactions
+- No clutter - every element earns its place
+
+## Dark Mode Patterns
+
+Tailwind dark mode uses `dark:` prefix (follows system preference).
+
+- Primary text: `text-hone-900 dark:text-hone-100`
+- Secondary text: `text-hone-600 dark:text-hone-400`
+- Cards: `bg-white dark:bg-hone-900` (via `.card` class)
+- Table headers: `bg-hone-50 dark:bg-hone-800`
+- Hover: `hover:bg-hone-50 dark:hover:bg-hone-800`
+
+## Test Data Guidelines
+
+- Major public company names are fine (Netflix, Amazon, Costco)
+- Avoid small regional/local business names
+- Use fictional names for non-public entities
+
+## Deployment
+
+See `docs/deployment.md` for Docker deployment guide.
+
+Docker images: `ghcr.io/heskew/hone-money` (multi-arch: amd64, arm64)

docs/.eleventyignore

@@ -0,0 +1,12 @@
+# Uppercase docs are internal reference only
+FEATURES.md
+DETECTION.md
+SPLITS_DESIGN.md
+
+# Site build artifacts
+site/
+_site/
+
+# Other ignores
+node_modules/
+README.md

docs/DETECTION.md

@@ -0,0 +1,105 @@
+---
+title: Detection Algorithms
+description: How Hone identifies wasteful spending
+date: 2026-01-24
+---
+
+# Detection Algorithms
+
+Hone uses six detection algorithms to identify wasteful spending.
+
+## Subscription Pre-Filter
+
+Before creating subscriptions, a two-layer filter reduces false positives:
+
+1. Check `merchant_subscription_cache` for cached classifications
+2. User exclusions (`source='user_override'`) take precedence over Ollama
+3. Ollama classifies unknown merchants as SUBSCRIPTION or RETAIL
+4. Retail merchants (grocery stores, gas stations) are skipped
+
+## Zombie Detection
+
+Identifies forgotten recurring charges.
+
+1. Group transactions by (account_id, merchant) for account-specific subscriptions
+2. Identify recurring patterns (consistent amount, regular interval)
+3. Flag if: recurring 3+ months AND user hasn't acknowledged
+4. Skip excluded subscriptions (user marked "not a subscription")
+
+### Stale Acknowledgment Re-check
+
+Acknowledged subscriptions are re-checked after 90 days (configurable via `acknowledgment_stale_days`):
+
+1. Track `acknowledged_at` timestamp when user acknowledges subscription
+2. If acknowledgment is older than threshold (default 90 days), treat as unacknowledged
+3. Subscription will be flagged as zombie again, prompting user to re-confirm
+4. Re-acknowledging updates the timestamp, resetting the 90-day window
+5. Legacy subscriptions without timestamp are treated as freshly acknowledged
+
+## Price Increase Detection
+
+Tracks subscription price changes.
+
+1. Track subscription amounts over time
+2. Alert if: current > 3-months-ago by >5% or >$1
+3. Skip excluded subscriptions
+
+## Duplicate Detection
+
+Finds multiple services in the same category.
+
+1. Categorize subscriptions (streaming, music, cloud storage, etc.)
+2. Alert if: 2+ active subscriptions in same category
+3. Ollama explains overlap and unique features (when enabled)
+
+## Auto-Cancellation Detection
+
+Detects subscriptions that stopped charging.
+
+1. Check acknowledged subscriptions for missed expected charges
+2. Apply grace period:
+   - 7 days for monthly
+   - 3 days for weekly
+   - 30 days for yearly
+3. Auto-mark as cancelled if expected charge date + grace period has passed
+4. Feeds into savings report
+
+## Resume Detection
+
+Catches reactivated subscriptions.
+
+1. Check cancelled subscriptions for new matching transactions
+2. If new charge found after cancellation, reactivate subscription
+3. Create Resume alert to notify user
+4. Mark as acknowledged to prevent immediate zombie flagging
+
+## Spending Anomaly Detection
+
+Flags unusual spending patterns.
+
+1. Compare current month spending by category vs 3-month rolling average baseline
+2. Alert if: increase >30% OR decrease >40% from baseline
+3. Only trigger if baseline >= $50 (avoid noise from low-spend categories)
+4. Ollama provides explanation with summary and reasons when available
+5. Re-analysis: can re-run with different models via API/UI
+
+## Subscription Detection Thresholds
+
+### Strict Pattern Matching (Default)
+- Requires 3+ transactions
+- 5% max amount variance
+- 70% interval consistency
+- Reduces false positives from regular shopping
+
+### Smart Detection (Ollama-Enhanced)
+When Ollama confirms merchant is a subscription service (>=70% confidence):
+- 50% amount variance allowed (for variable charges like utilities)
+- 50% interval consistency
+- 2 minimum transactions
+- Catches metered services (AWS, utility bills)
+
+Configuration via `DetectionConfig`:
+- `smart_amount_variance`
+- `smart_interval_consistency`
+- `smart_min_transactions`
+- `ollama_confidence_threshold`