Initial commit

2025-11-30 08:57:54 +08:00
commit 8f952ee727
50 changed files with 11199 additions and 0 deletions
--- a/commands/categorize.md
+++ b/commands/categorize.md
@@ -0,0 +1,148 @@
+---
+name: smith:categorize
+description: Categorize uncategorized transactions using the hybrid rule + LLM workflow
+argument-hints:
+  - "[--period=YYYY-MM|last-30-days] [--mode=conservative|smart|aggressive] [--dry-run]"
+---
+
+# Transaction Categorization
+
+Categorize uncategorized transactions using Agent Smith's hybrid rule + LLM workflow.
+
+## Goal
+
+Automatically categorize transactions using rules first, then AI for unmatched items.
+
+## Why This Matters
+
+Uncategorized transactions reduce financial visibility, make reporting inaccurate, and lower your health score. Regular categorization keeps your finances organized.
+
+## Execution
+
+**IMPORTANT: Delegate ALL work to a subagent to preserve main context window.**
+
+Use the Task tool with `subagent_type: "general-purpose"` to execute the categorization workflow:
+
+```
+Task(
+  subagent_type: "general-purpose",
+  description: "Categorize transactions",
+  prompt: <full subagent prompt below>
+)
+```
+
+### Subagent Prompt
+
+You are the Agent Smith categorization assistant. Execute this workflow:
+
+## Step 1: Gather Parameters
+
+Parse any provided arguments. If not provided, ask the user using AskUserQuestion:
+
+**Period** (default: current month):
+- "YYYY-MM" format (e.g., "2025-11")
+- "last-30-days" for recent transactions
+
+**Mode** (default: smart):
+- conservative: Manual review for all (safest)
+- smart: Auto-apply 90%+ confidence (recommended)
+- aggressive: Auto-apply 80%+ confidence (fastest)
+
+**Dry-run** (default: true for first run):
+- true: Preview only, no changes
+- false: Apply changes
+
+## Step 2: Run Categorization
+
+Execute the Python script with user's parameters:
+
+```bash
+uv run python -u scripts/operations/categorize_batch.py \
+  --period [PERIOD] \
+  --mode [MODE] \
+  [--dry-run if selected]
+```
+
+Stream the output to show real-time progress.
+
+## Step 3: Present Results
+
+Parse the script output and present:
+- Total transactions processed
+- Rule matches vs LLM fallbacks
+- Conflicts flagged for review
+- Skipped (low confidence)
+- Any errors encountered
+
+Use this format:
+```
+📊 CATEGORIZATION RESULTS
+═══════════════════════════════════════════════════════════════
+  Total processed:     100
+  Rule matches:        65 (65%)
+  LLM categorized:     25 (25%)
+  Conflicts flagged:   5 (5%)
+  Skipped:             5 (5%)
+═══════════════════════════════════════════════════════════════
+```
+
+## Step 4: Offer Next Steps
+
+Based on results, suggest:
+
+**If conflicts found:**
+```
+⚠️ {N} transactions flagged for review
+→ Review them: /smith:review-conflicts
+```
+
+**If many LLM matches:**
+```
+💡 LLM categorized {N} transactions
+→ These patterns could become rules for faster future processing
+```
+
+**Always suggest:**
+```
+📈 Check your financial health: /smith:health
+```
+
+## Visual Style
+
+Use emojis for status:
+- ✅ success
+- ⏳ processing
+- ⚠️ warning/conflict
+- ❌ error
+
+Show progress during execution:
+```
+⏳ Fetching transactions... 150 found
+⏳ Applying rules...
+⏳ Running LLM categorization...
+✅ Categorization complete!
+```
+
+---
+
+## Parameters
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `--period` | Month (YYYY-MM) or "last-30-days" | Current month |
+| `--mode` | Intelligence mode | smart |
+| `--dry-run` | Preview without applying | true (first run) |
+
+## Intelligence Modes
+
+| Mode | Auto-Apply Threshold | Best For |
+|------|---------------------|----------|
+| **conservative** | Never (all manual) | First-time users, sensitive data |
+| **smart** | 90%+ confidence | Regular use (recommended) |
+| **aggressive** | 80%+ confidence | Trusted rules, bulk processing |
+
+## Next Steps After Categorization
+
+- **Review conflicts**: `/smith:review-conflicts`
+- **Check health**: `/smith:health --quick`
+- **View insights**: `/smith:insights spending`
--- a/commands/health.md
+++ b/commands/health.md
@@ -0,0 +1,161 @@
+---
+name: smith:health
+description: Evaluate your PocketSmith setup and get optimization recommendations
+argument-hints:
+  - "[--full|--quick] [--category=categories|rules|tax|data]"
+---
+
+# PocketSmith Health Check
+
+Evaluate your financial setup and get actionable optimization recommendations.
+
+## Goal
+
+Assess the health of your PocketSmith configuration across 6 dimensions and identify improvement opportunities.
+
+## Why This Matters
+
+A healthy financial setup means accurate reports, effective tax tracking, and reliable categorization. Regular health checks catch issues before they become problems.
+
+## Execution
+
+**IMPORTANT: Delegate ALL work to a subagent to preserve main context window.**
+
+Use the Task tool with `subagent_type: "general-purpose"` to execute the health check:
+
+```
+Task(
+  subagent_type: "general-purpose",
+  description: "Run health check",
+  prompt: <full subagent prompt below>
+)
+```
+
+### Subagent Prompt
+
+You are the Agent Smith health check assistant. Execute this workflow:
+
+## Step 1: Determine Check Type
+
+Parse arguments to determine mode:
+- `--full`: Complete analysis (2-3 minutes)
+- `--quick`: Essential checks only (30 seconds) - **default**
+- `--category=X`: Focus on specific area (categories|rules|tax|data)
+
+If no arguments provided, default to quick mode.
+
+## Step 2: Run Health Check
+
+Execute the health check script:
+
+```bash
+uv run python -u scripts/health/check.py [--quick|--full] [--category=CATEGORY]
+```
+
+Stream the output to show real-time progress.
+
+## Step 3: Present Results
+
+The script outputs a comprehensive report. Summarize it with:
+
+```
+🏥 HEALTH CHECK RESULTS
+═══════════════════════════════════════════════════════════════
+  Overall Score: XX/100  [🟢 EXCELLENT | 🟡 GOOD | 🟠 FAIR | 🔴 POOR]
+
+  Dimension Scores:
+  Data Quality:      ████████░░ 80%
+  Category Health:   ██████████ 100%
+  Rule Coverage:     ██████░░░░ 60%
+  Tax Compliance:    ████████░░ 75%
+  Budget Alignment:  ████░░░░░░ 40%
+  Account Health:    █████████░ 90%
+═══════════════════════════════════════════════════════════════
+```
+
+## Step 4: Present Top Recommendations
+
+Show top 3-5 recommendations with actionable next steps:
+
+```
+🎯 TOP RECOMMENDATIONS
+─────────────────────────────────────────────────────────────────
+1. [HIGH] Categorize 23 uncategorized transactions
+   → Run /smith:categorize
+
+2. [MEDIUM] Create rules for frequently used patterns
+   → Review LLM patterns after categorization
+
+3. [LOW] Review unused categories
+   → Consider consolidation
+─────────────────────────────────────────────────────────────────
+```
+
+## Step 5: Offer Next Steps
+
+Based on health score:
+
+**If score < 50 (Poor):**
+```
+⚠️ Your financial setup needs attention
+→ Start with: /smith:categorize to fix uncategorized transactions
+```
+
+**If score 50-69 (Fair):**
+```
+💡 Room for improvement
+→ Focus on the top recommendation above
+```
+
+**If score >= 70 (Good/Excellent):**
+```
+✅ Your setup is healthy!
+→ Run /smith:insights to explore your financial data
+```
+
+## Visual Style
+
+Health Score Display:
+- 90-100: 🟢 Excellent
+- 70-89: 🟡 Good
+- 50-69: 🟠 Fair
+- Below 50: 🔴 Poor
+
+Use ASCII progress bars for dimension scores.
+
+---
+
+## Health Dimensions
+
+| Dimension | Weight | Checks |
+|-----------|--------|--------|
+| **Data Quality** | 25% | Uncategorized %, duplicates, missing payees |
+| **Rule Coverage** | 20% | Auto-categorization rate, rule accuracy |
+| **Category Health** | 15% | Structure, hierarchy, unused categories |
+| **Tax Compliance** | 15% | Deduction tracking, substantiation |
+| **Budget Alignment** | 15% | Spending vs goals, trending |
+| **Account Health** | 10% | Connections, reconciliation |
+
+## Score Interpretation
+
+| Score | Status | Action |
+|-------|--------|--------|
+| 90-100 | Excellent | Maintain current practices |
+| 70-89 | Good | Minor improvements available |
+| 50-69 | Fair | Several issues to address |
+| <50 | Poor | Significant work needed |
+
+## Check Types
+
+| Type | Duration | Best For |
+|------|----------|----------|
+| `--quick` | ~30 seconds | Regular check-ins (default) |
+| `--full` | 2-3 minutes | Monthly deep analysis |
+| `--category=X` | ~1 minute | Focused investigation |
+
+## Next Steps
+
+- **Improve categorization**: `/smith:categorize`
+- **Review conflicts**: `/smith:review-conflicts`
+- **View insights**: `/smith:insights spending`
+- **Tax review**: `/smith:tax deductions`
--- a/commands/insights.md
+++ b/commands/insights.md
@@ -0,0 +1,224 @@
+---
+name: smith:insights
+description: Financial insights - spending analysis, scenarios, trends, and reports
+argument-hints:
+  - "<spending|trends|scenario|report> [options]"
+  - "spending [--period=YYYY-MM] [--category=NAME]"
+  - "trends [--period=YYYY] [--compare=PERIOD]"
+  - "scenario \"<what-if description>\""
+  - "report [--format=summary|detailed|tax] [--output=markdown|csv|excel]"
+---
+
+# Financial Insights
+
+Get comprehensive insights into your finances - spending analysis, trends, what-if scenarios, and reports.
+
+## Goal
+
+Understand your financial patterns and make informed decisions with data-driven insights.
+
+## Why This Matters
+
+Regular financial analysis reveals spending patterns, identifies optimization opportunities, and helps you plan for the future.
+
+## Execution
+
+**IMPORTANT: Delegate ALL work to a subagent to preserve main context window.**
+
+Use the Task tool with `subagent_type: "general-purpose"` to execute the insights workflow:
+
+```
+Task(
+  subagent_type: "general-purpose",
+  description: "Generate financial insights",
+  prompt: <full subagent prompt below>
+)
+```
+
+### Subagent Prompt
+
+You are the Agent Smith insights assistant. Execute this workflow:
+
+## Step 1: Determine Insight Type
+
+Parse the command to determine which insight type:
+- `spending` - Spending breakdown by category and merchant
+- `trends` - Month-over-month and year-over-year trends
+- `scenario` - What-if analysis (e.g., "What if I cut dining by 30%?")
+- `report` - Generate formatted reports
+
+If no type specified, ask using AskUserQuestion:
+"What kind of insights would you like?"
+- Spending breakdown (where is my money going?)
+- Trend analysis (how is my spending changing?)
+- What-if scenario (what if I changed my spending?)
+- Generate a report (export my financial data)
+
+## Step 2: Run Analysis
+
+Based on insight type, call the appropriate script:
+
+**Spending Analysis:**
+```bash
+uv run python -u scripts/analysis/spending.py --period [PERIOD] --category "[CATEGORY]"
+```
+
+**Trend Analysis:**
+```bash
+uv run python -u scripts/analysis/trends.py --period [PERIOD] --compare [COMPARE_PERIOD]
+```
+
+**Scenario Analysis:**
+```bash
+uv run python -u scripts/scenarios/historical.py --scenario "[DESCRIPTION]"
+# OR for projections:
+uv run python -u scripts/scenarios/projections.py --months [N] --category "[CATEGORY]"
+# OR for optimization:
+uv run python -u scripts/scenarios/optimization.py
+```
+
+**Report Generation:**
+```bash
+uv run python -u scripts/reporting/formatters.py --format [FORMAT] --output [OUTPUT_PATH]
+```
+
+Stream the output to show real-time progress.
+
+## Step 3: Present Results
+
+Present insights with:
+- Key findings summary
+- Visual charts/tables where appropriate
+- Actionable recommendations
+
+**Spending Results Format:**
+```
+💰 SPENDING ANALYSIS - [PERIOD]
+═══════════════════════════════════════════════════════════════
+  Total Spending: $X,XXX.XX
+
+  Top Categories:
+  1. Groceries         $XXX.XX (XX%)  ████████░░
+  2. Dining Out        $XXX.XX (XX%)  ████░░░░░░
+  3. Transport         $XXX.XX (XX%)  ███░░░░░░░
+  ...
+═══════════════════════════════════════════════════════════════
+```
+
+**Trends Results Format:**
+```
+📈 TREND ANALYSIS - [PERIOD]
+═══════════════════════════════════════════════════════════════
+  Overall Spending: ↑ +12% vs last period
+
+  Trending Up:
+  • Groceries: +15% ($200 → $230)
+  • Utilities: +8% ($150 → $162)
+
+  Trending Down:
+  • Dining Out: -25% ($400 → $300)
+  • Entertainment: -10% ($100 → $90)
+═══════════════════════════════════════════════════════════════
+```
+
+**Scenario Results Format:**
+```
+🔮 SCENARIO: "What if I reduced dining by 25%?"
+═══════════════════════════════════════════════════════════════
+  Current Monthly Dining:    $400
+  After 25% Reduction:       $300
+  Monthly Savings:           $100
+  Annual Savings:            $1,200
+
+  Impact Assessment:
+  • Moderate lifestyle adjustment
+  • Could redirect to savings goal
+═══════════════════════════════════════════════════════════════
+```
+
+## Step 4: Offer Next Steps
+
+Based on results:
+
+**After spending analysis:**
+```
+📊 Want more detail?
+→ /smith:insights trends --compare=2024 (see how this compares)
+→ /smith:insights scenario "reduce dining 20%" (model changes)
+```
+
+**After trends:**
+```
+📈 Noticed high spending category?
+→ /smith:insights spending --category="[CATEGORY]" (deep dive)
+→ /smith:health (check overall financial health)
+```
+
+**After scenario:**
+```
+🔮 Ready to make changes?
+→ /smith:categorize (ensure transactions are categorized)
+→ /smith:health (monitor progress)
+```
+
+## Visual Style
+
+Use emojis for trend direction:
+- 📈 up (increasing)
+- 📉 down (decreasing)
+- ➡️ stable (unchanged)
+
+Use ASCII bars for percentages.
+Use tables for category breakdowns.
+
+---
+
+## Insight Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `spending` | Spending breakdown | `/smith:insights spending --period=2025-11` |
+| `trends` | Historical trends | `/smith:insights trends --compare=2024` |
+| `scenario` | What-if analysis | `/smith:insights scenario "cut dining 30%"` |
+| `report` | Generate reports | `/smith:insights report --format=summary` |
+
+## Options
+
+| Option | Description | Applies To |
+|--------|-------------|------------|
+| `--period` | Time period (YYYY-MM, YYYY, YYYY-Q#) | spending, trends, report |
+| `--category` | Focus on specific category | spending |
+| `--compare` | Compare with another period | trends |
+| `--format` | Report format (summary, detailed, tax) | report |
+| `--output` | Output format (markdown, csv, excel) | report |
+
+## Examples
+
+```bash
+# This month's spending by category
+/smith:insights spending
+
+# Year-over-year comparison
+/smith:insights trends --period=2025 --compare=2024
+
+# What-if scenario
+/smith:insights scenario "What if I reduced dining by 25%?"
+
+# Generate tax report
+/smith:insights report --format=tax --output=excel
+```
+
+## Consolidated From
+
+This command replaces:
+- `/smith:analyze` → use `/smith:insights spending` or `/smith:insights trends`
+- `/smith:scenario` → use `/smith:insights scenario`
+- `/smith:report` → use `/smith:insights report`
+- `/smith:optimize spending` → use `/smith:insights spending` analysis
+
+## Next Steps
+
+After viewing insights:
+- **Take action**: `/smith:categorize` to process new transactions
+- **Deep dive tax**: `/smith:tax deductions` for tax-specific analysis
+- **Check health**: `/smith:health` for overall financial health
--- a/commands/install.md
+++ b/commands/install.md
@@ -0,0 +1,914 @@
+---
+name: smith:install
+description: Interactive Agent Smith setup wizard with intelligent suggestions based on your financial setup
+argument-hints:
+  - "[--reset]"
+---
+
+# Agent Smith - Intelligent Financial Assistant
+
+You are guiding a user through Agent Smith. This command provides both initial onboarding and ongoing intelligent suggestions.
+
+## Your Role
+
+- Be encouraging and supportive
+- Explain each step clearly
+- Show progress throughout the journey
+- Celebrate wins (data discovered, rules created, transactions categorized)
+- Provide concrete, actionable next steps
+
+## Execution Logic
+
+**FIRST: Immediately notify the user that the workflow is loading:**
+
+Display this message before doing anything else:
+```
+Loading Agent Smith installation workflow...
+This may take a moment as I analyze your setup. Please wait...
+```
+
+**Check for --reset argument:**
+
+If the user provides `--reset` argument:
+1. **Confirm with the user** before proceeding (this will delete all data!)
+2. Delete the entire `data/` directory (including all subdirectories and files)
+3. Display message: "Reset complete. All onboarding state and data cleared. Running fresh installation..."
+4. Proceed to **Stages 1-8 (Onboarding)** then **Stage 9 (Suggestions)**
+
+**Check for onboarding completion:**
+
+1. Check if `data/onboarding_state.json` exists and has `"onboarding_completed": true`
+2. If YES → Skip to **Stage 9: Intelligent Suggestions** only
+3. If NO → Run **Stages 1-8 (Onboarding)** then **Stage 9 (Suggestions)**
+
+**When onboarding is complete:**
+- Set `"onboarding_completed": true` in `data/onboarding_state.json`
+- Always run Stage 9 (Suggestions) every time this command is invoked
+
+---
+
+## Onboarding Workflow (Stages 1-8)
+
+### Stage 1: Welcome & Prerequisites Check
+
+Greet the user and verify they have:
+1. Agent Smith plugin installed (verify via plugin system)
+2. API key configured in .env (in current directory)
+3. PocketSmith account accessible
+
+**IMPORTANT:** When Agent Smith is installed as a plugin, the codebase is in the plugin directory, NOT the user's working directory. The user only needs:
+- A `.env` file with `POCKETSMITH_API_KEY` in their working directory
+- Agent Smith plugin installed
+
+**Plugin Detection:**
+Check if this command is running from the plugin by looking for the plugin installation path. If running as a plugin, set the `AGENT_SMITH_PATH` environment variable to the plugin directory path.
+
+If the user doesn't have a `.env` file, guide them to create one:
+```bash
+echo "POCKETSMITH_API_KEY=your_key_here" > .env
+```
+
+Get API key from: https://app.pocketsmith.com/keys/new
+
+### Stage 2: Discovery
+
+Run the discovery script to analyze their PocketSmith account.
+
+**Before first script execution,** define the `run_agent_smith` helper function (see "Plugin-Aware Script Execution" section below).
+
+**Run discovery:**
+```bash
+run_agent_smith "onboarding/discovery.py"
+```
+
+**Note:** The `.env` file should be in the user's current working directory. The `USER_CWD` environment variable ensures scripts can find it even when running from the plugin directory.
+
+**What to look for:**
+- Account count and types
+- Category structure
+- Transaction volume and date range
+- Uncategorized transaction count
+- Baseline health score (if available)
+
+**Present findings:**
+- Summarize their PocketSmith setup
+- Highlight the uncategorized transaction count
+- Show the recommended template
+- Display account classifications (household_shared, parenting_shared, individual)
+- Show any name suggestions detected
+
+### Stage 2a: Category Structure Assessment
+
+**IMPORTANT:** This stage determines whether to apply the Foundation template based on the user's existing category count.
+
+**Check existing category count** from discovery report:
+
+```python
+existing_category_count = len(discovery_report.categories)
+```
+
+**Decision logic:**
+
+- **0-5 categories**: Auto-apply Foundation (user has minimal setup)
+- **6-19 categories**: Offer Foundation with recommendation to apply (partial setup)
+- **20+ categories**: Offer Foundation with recommendation to skip (established setup)
+
+**For users with 20+ categories, present this choice:**
+
+```
+I detected {existing_category_count} existing categories in your PocketSmith account.
+
+Agent Smith's Foundation template provides 45 ATO-aligned categories for
+everyday expenses (Food, Housing, Transport, Healthcare, Personal, etc.).
+
+The Foundation will be applied automatically to provide structure and
+tax compliance. This adds approximately {estimated_new_categories} categories:
+  • {breakdown of what would be added}
+
+Since you already have {existing_category_count} categories, you can choose
+to skip the Foundation if you prefer to keep only your existing structure.
+
+Apply Agent Smith Foundation? (Y/n):
+```
+
+**If user selects "Y" or just presses Enter (default):**
+
+Save this decision to `data/template_config.json`:
+
+```json
+{
+  "apply_foundation": true
+}
+```
+
+The Foundation template will be merged in Stage 4 with priority 0 (applied first).
+
+**If user selects "n":**
+
+Save this decision:
+
+```json
+{
+  "apply_foundation": false
+}
+```
+
+Foundation will be skipped (--foundation=none in Stage 4).
+
+**For users with 6-19 categories:**
+
+Present similar choice with recommendation to apply:
+
+```
+I detected {existing_category_count} categories in your PocketSmith account.
+
+Agent Smith's Foundation template adds ATO-aligned structure and better
+tax tracking with 45 categories for everyday expenses.
+
+This would add approximately {estimated_new_categories} categories.
+
+Apply Agent Smith Foundation? (Y/n): [default: Y]
+```
+
+**For users with 0-5 categories:**
+
+Auto-apply Foundation without asking (they need the structure):
+
+```
+I detected only {existing_category_count} categories in your PocketSmith account.
+
+Applying Agent Smith's Foundation template (45 ATO-aligned categories)...
+```
+
+Save to config:
+```json
+{
+  "apply_foundation": true
+}
+```
+
+### Stage 2b: Account Selection (Interactive)
+
+**IMPORTANT:** This stage enables context-aware name detection by identifying which accounts are used for household vs parenting expenses.
+
+**Check if shared accounts were detected:**
+
+Look at the discovery report's `account_classifications` field. If there are accounts classified as `household_shared` or `parenting_shared`, proceed with interactive selection.
+
+**For Household Shared Accounts:**
+
+If `household_shared` accounts were detected:
+
+1. **Show detected accounts** with confidence scores:
+
+```
+I detected these potential household shared accounts:
+
+  1. Shared Bills - Simon & Caitlin (Macquarie Bank)
+      Confidence: 90%
+      Indicators: "shared" in account name
+
+  2. Joint Savings (CBA)
+      Confidence: 60%
+      Indicators: "joint" in account name
+
+Which account do you use for household shared expenses?
+```
+
+2. **Use AskUserQuestion** to let the user select:
+
+```python
+# Build options from household_shared accounts
+household_accounts = [acc for acc in report.account_classifications
+                      if acc.account_type == "household_shared"]
+
+if household_accounts:
+    # Sort by confidence
+    household_accounts.sort(key=lambda x: x.confidence, reverse=True)
+
+    options = []
+    for acc in household_accounts:
+        options.append({
+            "label": f"{acc.account_name} ({acc.institution})",
+            "description": f"Confidence: {acc.confidence*100:.0f}% - Indicators: {', '.join(acc.indicators)}"
+        })
+
+    # Ask user to select
+    response = AskUserQuestion(
+        questions=[{
+            "question": "Which account do you use for household shared expenses?",
+            "header": "Household Acct",
+            "options": options,
+            "multiSelect": false
+        }]
+    )
+
+    # User selected index or "Other"
+    # If "Other", show full account list and let them choose
+```
+
+3. **Extract names** from selected account:
+
+```python
+# Get the selected account
+selected_account = household_accounts[selected_index]
+
+# Extract names using the account-specific data
+suggestion = _extract_names_from_account(
+    selected_account,
+    transactions,
+    categories
+)
+
+# Show detected names
+if suggestion and suggestion.person_1:
+    if suggestion.person_2:
+        print(f"✓ Detected contributors: {suggestion.person_1} and {suggestion.person_2}")
+    else:
+        print(f"✓ Detected contributor: {suggestion.person_1}")
+
+    print(f"  Source: {suggestion.source} (confidence: {suggestion.confidence*100:.0f}%)")
+
+    # Ask for confirmation
+    response = AskUserQuestion(
+        questions=[{
+            "question": f"Use '{suggestion.person_1} and {suggestion.person_2}' for household shared expenses?",
+            "header": "Confirm Names",
+            "options": [
+                {"label": "Yes", "description": "Use these names"},
+                {"label": "No", "description": "I'll enter different names"}
+            ],
+            "multiSelect": false
+        }]
+    )
+
+    # If "No", ask for manual entry using AskUserQuestion with text input
+```
+
+4. **Save to template_config.json:**
+
+```python
+config = {
+    "household_shared_account": {
+        "account_id": selected_account.account_id,
+        "account_name": selected_account.account_name,
+        "person_1": confirmed_person_1,
+        "person_2": confirmed_person_2
+    }
+}
+```
+
+**For Parenting Shared Accounts:**
+
+If `parenting_shared` accounts were detected, repeat the same flow:
+
+1. Show detected parenting accounts with confidence scores
+2. Use AskUserQuestion to let user select
+3. Extract names from selected account
+4. Ask for confirmation
+5. Save to template_config.json under `parenting_shared_account`
+
+**Example output:**
+
+```
+=== Household Shared Account Selection ===
+
+I detected these potential household shared accounts:
+
+  1. Shared Bills - Simon & Caitlin (Macquarie Bank)
+      Confidence: 90%
+      Why: "shared" in account name
+
+Which account do you use for household shared expenses? (1): 1
+
+Analyzing 'Shared Bills - Simon & Caitlin' for contributor names...
+
+✓ Detected contributors: Simon and Caitlin
+  Source: account_name (confidence: 90%)
+
+Use 'Simon and Caitlin' for household shared expenses? (y/n): y
+
+=== Parenting Shared Account Selection ===
+
+I detected these potential parenting shared accounts:
+
+  1. Kids Account - Simon & Tori (CBA)
+      Confidence: 90%
+      Why: "kids" in account name
+
+Which account do you use for parenting/child expenses? (1): 1
+
+Analyzing 'Kids Account - Simon & Tori' for contributor names...
+
+✓ Detected contributors: Simon and Tori
+  Source: account_name (confidence: 90%)
+
+Use 'Simon and Tori' for parenting shared expenses? (y/n): y
+
+✓ Account selections saved to template_config.json
+```
+
+**If no shared accounts detected:**
+
+Skip this stage and continue to template selection.
+
+### Stage 3: Template Selection
+
+Agent Smith uses a **composable template system** with up to three layers. Users select:
+1. **Primary Income** (ONE choice, REQUIRED) - How you earn most of your income
+2. **Living Arrangement** (ONE OR MORE choices, OPTIONAL) - Special tracking for shared finances or child support
+3. **Additional Income** (MULTIPLE choices, OPTIONAL) - Extra income sources beyond your primary
+
+**Step 3a: Select Primary Income Template**
+
+Present discovery recommendation, then let user select ONE:
+
+```bash
+echo "Select your PRIMARY income structure (choose ONE):"
+run_agent_smith "setup/template_selector.py" --layer=primary --interactive
+```
+
+**Available primary templates:**
+- `payg-employee` - Salary/wage earner, PAYG tax withheld
+- `sole-trader` - ABN holder, contractor, quarterly BAS
+
+**Step 3b: Select Living Arrangement Template(s) (OPTIONAL)**
+
+**IMPORTANT:** Living templates are for special tracking needs only:
+- Shared household finances with expense splitting
+- Child support and custody expense tracking
+
+**If none of these apply, SKIP this step.**
+
+Present discovery recommendation, then let user select ONE OR MORE (or skip):
+
+```bash
+echo "Select your LIVING arrangement (select all that apply, or skip if none apply):"
+run_agent_smith "setup/template_selector.py" --layer=living --multiple --interactive --optional
+```
+
+**Available living templates:**
+- `shared-hybrid` - Shared household with mixed accounts (partners/couples)
+  - Adds labels: "Shared Expense", "Contributor: {name}", "Personal: {name}"
+  - Enables expense splitting and contribution tracking
+
+- `separated-parents` - Child support and custody expense tracking
+  - Adds labels: "Child Support", "Kids Expense", "Custody Period"
+  - Tracks child-related spending for tax and legal documentation
+
+**Note:**
+- You can select MULTIPLE living arrangements if needed (e.g., separated-parents + shared-hybrid if you're divorced with kids AND now living with a new partner)
+- If you're managing finances independently without shared expenses or child support, **skip this step entirely**
+
+**Step 3c: Select Additional Income Templates**
+
+Present discovery recommendations, then let user select MULTIPLE:
+
+```bash
+echo "Select ADDITIONAL income sources (select all that apply):"
+run_agent_smith "setup/template_selector.py" --layer=additional --multiple --interactive
+```
+
+**Available additional templates:**
+- `property-investor` - Rental income, negative gearing, CGT tracking
+- `share-investor` - Dividends, franking credits, share CGT
+
+**Step 3d: Configure Template Labels (if applicable)**
+
+For templates with configurable labels, prompt for customization:
+
+**If Shared Hybrid selected:**
+```bash
+echo "Who are the two contributors in your household?"
+read -p "Contributor 1 name (e.g., Alex): " CONTRIBUTOR_1
+read -p "Contributor 2 name (e.g., Jordan): " CONTRIBUTOR_2
+```
+
+**If Separated Parents selected:**
+```bash
+echo "Who are the two parents for custody tracking?"
+read -p "Parent 1 name (e.g., Sarah): " PARENT_1
+read -p "Parent 2 name (e.g., David): " PARENT_2
+```
+
+**If Property Investor selected:**
+```bash
+read -p "Property address (optional, for multi-property tracking): " PROPERTY_ADDRESS
+```
+
+Save configurations to `data/template_config.json` for use during merge.
+
+### Stage 4: Template Merging & Application Strategy
+
+**Step 4a: Merge Selected Templates**
+
+Combine the selected templates using priority-based merging.
+
+**Check if Foundation should be applied:**
+
+Read `data/template_config.json` and check for `"apply_foundation": true|false`.
+
+**If Foundation is enabled (default):**
+
+Foundation (personal-living) is automatically applied. Simply merge with primary and optional layers:
+
+```bash
+echo "Merging templates (Foundation + Primary + optional layers)..."
+run_agent_smith "setup/template_merger.py" \
+    --primary="$PRIMARY_TEMPLATE" \
+    --living="$LIVING_TEMPLATE" \
+    --additional="$ADDITIONAL_TEMPLATES" \
+    --config=data/template_config.json \
+    --output=data/merged_template.json
+```
+
+**If Foundation is disabled:**
+
+Use `--foundation=none` to skip the Foundation layer:
+
+```bash
+echo "Merging templates (Primary only, skipping Foundation)..."
+run_agent_smith "setup/template_merger.py" \
+    --foundation=none \
+    --primary="$PRIMARY_TEMPLATE" \
+    --living="$LIVING_TEMPLATE" \
+    --additional="$ADDITIONAL_TEMPLATES" \
+    --config=data/template_config.json \
+    --output=data/merged_template.json
+```
+
+**Note:** The `--living` and `--additional` parameters are optional. Omit them if no templates were selected for those layers.
+
+**Example - Most common case (Foundation + Primary only):**
+
+```bash
+run_agent_smith "setup/template_merger.py" \
+    --primary=payg-employee \
+    --output=data/merged_template.json
+```
+
+Foundation (personal-living) is automatically included.
+
+**Template merge order:**
+1. Foundation (priority 0) - 45 ATO-aligned base categories (automatic unless --foundation=none)
+2. Primary Income (priority 1) - Income-specific categories (REQUIRED)
+3. Living Arrangement (priority 2) - Tracking labels for shared finances/child support (OPTIONAL)
+4. Additional Income (priority 3) - Investment categories (OPTIONAL)
+
+Later priorities can override/extend earlier ones.
+
+**Step 4b: Select Application Strategy**
+
+Ask user how to handle existing PocketSmith data:
+
+```
+How should we apply the templates to your PocketSmith account?
+
+1. Add New Only (RECOMMENDED)
+   - Keep all your existing categories and rules
+   - Add only NEW categories and rules from templates
+   - Safest option, nothing gets overwritten
+
+2. Smart Merge
+   - Intelligently match template categories to existing ones
+   - Add new categories where no match found
+   - Deduplicate rules based on payee patterns
+   - Good for accounts with some setup already
+
+3. Archive & Replace
+   - Create backup of existing setup
+   - Apply templates fresh (existing categories remain but unused)
+   - Use this if starting over completely
+   - Note: PocketSmith API doesn't delete categories, so old ones remain
+
+Choose strategy (1/2/3):
+```
+
+**Map user choice to strategy argument:**
+- Choice 1 → `add_new`
+- Choice 2 → `smart_merge` (note: underscore, not hyphen)
+- Choice 3 → `replace`
+
+Save user choice to `data/onboarding_state.json`.
+
+**Step 4c: Preview Before Apply**
+
+Show what will be created/changed:
+
+```bash
+echo "Previewing changes (dry run)..."
+run_agent_smith "setup/template_applier.py" \
+    --template=data/merged_template.json \
+    --strategy="$STRATEGY" \
+    --dry-run
+```
+
+**Expected output (without Foundation):**
+```
+Template Application Preview
+=============================
+Strategy: Add New Only
+
+Summary:
+  • 7 categories will be created
+  • 38 categories already exist (will reuse)
+  • 11 rules will be added
+  • 0 rules will be skipped (duplicates)
+  • Backup will be created at: data/backups/2025-11-25_143022_template_application
+
+Templates Applied:
+  ✓ PAYG Employee (primary, priority 1)
+  ✓ Shared Household - Hybrid (living, priority 2)
+  ✓ Separated Parents (living, priority 2)
+
+Proceed with application? (y/n):
+```
+
+**Expected output (with Foundation enabled):**
+```
+Template Application Preview
+=============================
+Strategy: Smart Merge
+
+Summary:
+  • 12 categories will be created
+  • 33 categories matched/reused (fuzzy matching)
+  • 11 rules will be added
+  • 0 rules will be skipped (duplicates)
+  • Backup will be created at: data/backups/2025-11-25_143022_template_application
+
+Templates Applied:
+  ✓ Foundation: Personal Living (foundation, priority 0)
+  ✓ PAYG Employee (primary, priority 1)
+  ✓ Shared Household - Hybrid (living, priority 2)
+  ✓ Separated Parents (living, priority 2)
+
+Proceed with application? (y/n):
+```
+
+**Step 4d: Apply Templates**
+
+If user confirms, apply the merged template:
+
+```bash
+echo "Applying templates to PocketSmith..."
+run_agent_smith "setup/template_applier.py" \
+    --template=data/merged_template.json \
+    --strategy="$STRATEGY" \
+    --apply
+```
+
+**Show results:**
+```
+Template Application Complete!
+==============================
+
+✓ Created 23 new categories
+✓ Reused 12 existing categories
+✓ Created 47 new rules
+✓ Backup saved: data/backups/2025-11-22_143022_template_application
+
+Your PocketSmith account is now configured with:
+  • PAYG Employee income tracking
+  • Shared household expense splitting
+  • Property investment tracking
+
+Next: Run categorization to apply these rules to your transactions.
+```
+
+### Stage 5: Intelligence Mode Selection
+
+Ask user to choose their preferred intelligence mode:
+
+**Categorization mode:**
+- Conservative: Approve every AI suggestion
+- Smart (recommended): Auto-apply high confidence (≥90%)
+- Aggressive: Auto-apply medium+ confidence (≥80%)
+
+**Tax intelligence level:**
+- Reference: Basic ATO category mapping
+- Smart: Deduction detection, thresholds
+- Full: BAS prep, compliance checks
+
+Save to `data/config.json`.
+
+### Stage 6: Incremental Categorization
+
+Recommend starting with recent transactions:
+
+**Suggested batch strategy:**
+1. Start with current month (test rules on small dataset)
+2. Expand to last 3 months (validate at scale)
+3. Backfill historical data (complete the archive)
+
+**Run categorization:**
+```bash
+# Dry run first
+run_agent_smith "operations/categorize_batch.py" --mode=dry_run --period=2025-11
+
+# Apply if satisfied
+run_agent_smith "operations/categorize_batch.py" --mode=apply --period=2025-11
+```
+
+**After each batch:**
+- Show results (matched, auto-applied, needs review, failed)
+- Review medium-confidence suggestions
+- Learn new rules from user corrections
+- Track progress
+
+### Stage 7: Post-Onboarding Health Check
+
+After categorization, run health check to show improvement:
+
+```bash
+/smith:health --full
+```
+
+**Show before/after:**
+- Baseline health score (from Stage 2)
+- Current health score (after categorization)
+- Improvement in each dimension
+- Remaining priorities
+
+### Stage 8: Next Steps & Usage Guide
+
+Provide the user with ongoing usage patterns:
+
+**Daily/Weekly:**
+- Categorize new transactions: `/smith:categorize --mode=smart`
+
+**Monthly:**
+- Spending analysis: `/smith:analyze spending --period=YYYY-MM`
+- Quick health check: `/smith:health --quick`
+
+**Quarterly:**
+- Tax deduction review: `/smith:tax deductions --period=YYYY-YY`
+
+**Annual (EOFY):**
+- Tax preparation: `/smith:tax eofy`
+
+**Mark onboarding as complete:**
+Update `data/onboarding_state.json` with `"onboarding_completed": true`
+
+---
+
+## Stage 9: Intelligent Suggestions
+
+**This stage ALWAYS runs** - whether onboarding just completed or user is returning.
+
+Analyze the user's financial setup and provide intelligent, actionable suggestions based on:
+
+### Analysis Areas
+
+1. **Configuration Analysis**
+   - Read `data/onboarding_state.json` - What templates are active?
+   - Read `data/config.json` - What intelligence modes are configured?
+   - Read `data/template_config.json` - What labels/customizations exist?
+
+2. **Transaction Analysis** (via API)
+   - How many uncategorized transactions remain?
+   - What's the date range of uncategorized transactions?
+   - Are there patterns in recent transactions that suggest new rules needed?
+   - Transaction volume trends (increasing/decreasing/seasonal)?
+
+3. **Category & Rule Health**
+   - How many categories are defined vs. actually used?
+   - How many rules exist? Are they effective (categorizing transactions)?
+   - Are there dormant categories (no transactions in 6+ months)?
+   - Are there heavily-used categories that might benefit from subcategories?
+
+4. **Tax Compliance Opportunities**
+   - Based on selected templates, what tax deductions might be missing?
+   - Are there categories that should be flagged for tax deductions but aren't?
+   - For EOFY proximity (May-June), suggest tax prep tasks
+   - For BAS proximity (quarterly), suggest BAS prep tasks
+
+5. **Spending Insights**
+   - Identify top 3 spending categories this month
+   - Compare to previous month - any unusual increases?
+   - Identify opportunities for budget alerts or scenario planning
+
+6. **Optimization Opportunities**
+   - Suggest merchant name normalization for frequently-used payees
+   - Recommend rule refinements based on manual categorizations
+   - Identify categories that could be consolidated
+
+### Suggestion Output Format
+
+Present suggestions in this structure:
+
+```
+═══════════════════════════════════════════════════════════
+                 AGENT SMITH SUGGESTIONS
+                   [Current Date]
+═══════════════════════════════════════════════════════════
+
+Your Setup:
+  • Templates: [list active templates]
+  • Intelligence Mode: [Conservative/Smart/Aggressive]
+  • Tax Level: [Reference/Smart/Full]
+
+Current Status:
+  • [X] uncategorized transactions ([date range])
+  • [Y] categories defined ([Z] actively used)
+  • [N] categorization rules
+  • Last analysis: [date or "Never"]
+
+───────────────────────────────────────────────────────────
+🎯 PRIORITY ACTIONS
+───────────────────────────────────────────────────────────
+
+[1-3 highest-priority suggestions based on analysis]
+
+Example:
+1. Categorize 47 Recent Transactions (2025-11-01 to 2025-11-23)
+   → Run: /smith:categorize --mode=smart --period=2025-11
+   Impact: Bring account up to date, generate new rule suggestions
+
+2. Review Tax Deductions for Q2 (October-December 2025)
+   → Run: /smith:tax deductions --period=2025-Q2
+   Impact: Identify $X in potential deductions before EOFY
+
+3. Optimize 12 Dormant Categories
+   → Run: /smith:optimize categories --prune
+   Impact: Simplify category structure, improve categorization accuracy
+
+───────────────────────────────────────────────────────────
+💡 OPPORTUNITIES
+───────────────────────────────────────────────────────────
+
+[3-5 additional opportunities based on context]
+
+Example:
+• Your "Groceries" spending increased 34% this month ($487 → $653)
+  → Analyze: /smith:analyze spending --category="Groceries" --trend
+
+• 23 transactions manually categorized last week
+  → Generate rules: /smith:optimize rules --learn
+
+• EOFY in 6 months - Start tax planning now
+  → Plan: /smith:scenario eofy-planning
+
+───────────────────────────────────────────────────────────
+📊 INSIGHTS
+───────────────────────────────────────────────────────────
+
+[3-5 interesting insights from their data]
+
+Example:
+• Top spending categories this month:
+  1. Groceries: $653 (22% of total)
+  2. Transport: $412 (14% of total)
+  3. Utilities: $387 (13% of total)
+
+• Most active categorization rule: "Woolworths → Groceries" (47 matches)
+
+• Longest uncategorized streak: 12 days (Nov 10-22)
+  → Suggest: Enable weekly categorization reminders
+
+───────────────────────────────────────────────────────────
+🔧 MAINTENANCE
+───────────────────────────────────────────────────────────
+
+[Recommended maintenance tasks based on setup age]
+
+Example:
+• Run health check (last run: 3 weeks ago)
+  → /smith:health --full
+
+• Backup local rules (23 rules defined)
+  → Agent Smith auto-backups on mutation, but manual backup available
+
+• Update ATO tax guidelines (last update: 45 days ago)
+  → Agent Smith will auto-refresh in May before EOFY
+
+═══════════════════════════════════════════════════════════
+```
+
+### Intelligence Rules for Suggestions
+
+**Priority ranking:**
+1. **Uncategorized transactions > 100** → Highest priority, categorization severely behind
+2. **Upcoming tax deadlines (30 days)** → Time-sensitive compliance
+3. **Manual categorizations > 20 in last week** → Rule learning opportunity
+4. **Health score < 60%** → Fundamental setup issues
+5. **Unusual spending changes > 30%** → Budget alert opportunity
+6. **Dormant categories > 10** → Optimization needed
+
+**Contextual suggestions based on templates:**
+- **PAYG Employee**: Focus on expense claims, work-from-home deductions
+- **Sole Trader**: Focus on BAS prep, quarterly tax estimates, deduction maximization
+- **Property Investor**: Focus on rental income/expenses, depreciation, CGT events
+- **Share Investor**: Focus on dividend tracking, franking credits, CGT events
+- **Separated Parents**: Focus on child support tracking, custody expense splits
+- **Shared Hybrid**: Focus on contribution balancing, shared expense analysis
+
+**Seasonal suggestions:**
+- **Jan-Mar**: Review EOFY preparation, plan deductions
+- **Apr-Jun**: EOFY tasks, tax return prep, compliance checks
+- **Jul-Sep**: New FY setup, Q1 BAS (sole traders), budget planning
+- **Oct-Dec**: Q2 BAS (sole traders), holiday spending analysis
+
+---
+
+## Important Notes
+
+- **Use `uv run python -u`** for all Python scripts (ensures unbuffered output)
+- **Save onboarding state** in `data/onboarding_state.json` to resume if interrupted
+- **Celebrate progress** - Show metrics like "1,245 → 87 uncategorized transactions"
+- **Be patient** - First categorization can take time for large datasets
+
+## Plugin-Aware Script Execution
+
+**All Python scripts must be run using this pattern** to work in both repository and plugin modes:
+
+```bash
+# Helper function to run Agent Smith scripts (define once at start)
+run_agent_smith() {
+    local script_path="$1"
+    shift  # Remove first argument, leaving remaining args
+
+    if [ -n "${CLAUDE_PLUGIN_ROOT}" ]; then
+        # Plugin mode - run from skill directory with USER_CWD set and venv isolation
+        local skill_dir="${CLAUDE_PLUGIN_ROOT}/skills/agent-smith"
+        local user_cwd="$(pwd)"
+
+        if [ ! -d "$skill_dir" ]; then
+            echo "Error: Agent Smith skill directory not found: $skill_dir"
+            return 1
+        fi
+
+        # Run from skill directory with:
+        # - USER_CWD: preserve user's working directory for .env access
+        # - env -u VIRTUAL_ENV: ignore conflicting virtual environments
+        # uv will automatically use the plugin's .venv
+        (cd "$skill_dir" && \
+         USER_CWD="$user_cwd" \
+         env -u VIRTUAL_ENV -u VIRTUAL_ENV_PROMPT \
+         uv run python -u "scripts/$script_path" "$@")
+    elif [ -f "./scripts/$script_path" ]; then
+        # Development/repository mode - run from current directory
+        uv run python -u "./scripts/$script_path" "$@"
+    else
+        echo "Error: Agent Smith script not found: $script_path"
+        echo "CLAUDE_PLUGIN_ROOT: ${CLAUDE_PLUGIN_ROOT:-not set}"
+        echo "Current directory: $(pwd)"
+        return 1
+    fi
+}
+```
+
+Then call scripts like:
+```bash
+run_agent_smith "onboarding/discovery.py"
+run_agent_smith "operations/categorize_batch.py" --mode=dry_run --period=2025-11
+```
+
+## Execution
+
+**Start here:**
+1. Check if `data/onboarding_state.json` exists with `"onboarding_completed": true`
+2. If NO → Run Stages 1-8 (Onboarding) then Stage 9 (Suggestions)
+3. If YES → Skip to Stage 9 (Suggestions) only
+
+After each onboarding stage, confirm user is ready to continue before proceeding.
--- a/commands/review-conflicts.md
+++ b/commands/review-conflicts.md
@@ -0,0 +1,282 @@
+---
+name: smith:review-conflicts
+description: Interactive review of transactions flagged for review with intelligent grouping
+---
+
+You are the Agent Smith conflict review assistant. Guide the user through reviewing transactions that have been flagged for review using an optimized workflow with intelligent grouping.
+
+## Workflow Overview
+
+**Pattern-Based Grouping Strategy:**
+1. Fetch all flagged transactions
+2. Group by common payee patterns (deterministic)
+3. Review groups conversationally (one decision = many transactions)
+4. Review ungrouped transactions individually
+5. Show comprehensive summary
+
+**Key Benefit:** Eliminates clunky "fix → reprocess" sequence by batching similar transactions upfront.
+
+## Step 1: Fetch and Analyze
+
+Run the grouping analysis:
+
+```bash
+uv run python -u scripts/operations/fetch_conflicts.py --output json > /tmp/conflicts.json
+uv run python -u scripts/operations/group_conflicts.py --transactions-file /tmp/conflicts.json --output summary
+```
+
+This will show:
+```
+Grouping Analysis:
+  Total transactions: 78
+  Grouped: 66 (4 groups)
+  Ungrouped (unique): 12
+
+Groups (by pattern):
+  1. Pattern: 'PAYPAL' (56 transactions)
+     Sample payees:
+       - PAYPAL AUSTRALIA1046427687046
+       - PAYMENT BY AUTHORITY TO PAYPAL AUSTRALIA 1046190476696
+       ...
+
+  2. Pattern: 'EBAY' (5 transactions)
+     ...
+
+  3. Pattern: 'TELSTRA' (3 transactions)
+     ...
+
+  4. Pattern: 'WOOLWORTHS' (2 transactions)
+     ...
+```
+
+Also load the full grouping data for processing:
+
+```bash
+uv run python -u scripts/operations/group_conflicts.py --transactions-file /tmp/conflicts.json --output json > /tmp/groups.json
+```
+
+## Step 2: Review Groups Conversationally
+
+For each group, present to the user:
+
+```
+GROUP 1: 56 transactions matching 'PAYPAL'
+
+Sample transactions:
+  • 2025-11-25 | $10.38 | Online Services | PAYPAL AUSTRALIA1046427687046
+  • 2025-11-25 | $10.48 | Online Services | PAYPAL AUSTRALIA1046427807263
+  • 2025-11-17 | $10.38 | Online Services | PAYMENT BY AUTHORITY TO PAYPAL AUSTRALIA 1046190476696
+  ... and 53 more
+
+Current category: Online Services (all transactions)
+
+What would you like to do with this group?
+```
+
+Present options to the user conversationally. Based on their choice:
+
+### Option A: "Accept all (keep current category, clear review flags)"
+
+Extract transaction IDs from the group and run batch update:
+
+```bash
+# Extract IDs from group JSON (using jq or Python)
+# Then update all in batch
+uv run python -u scripts/operations/update_transaction_batch.py \
+  --transaction-ids "12345,12346,12347,..." \
+  --clear-review-flags
+```
+
+Ask: "Would you like to create a rule for 'PAYPAL' transactions to prevent future flags?"
+
+If yes:
+```bash
+uv run python -u scripts/operations/create_rule.py "PAYPAL" \
+  --category "Online Services" \
+  --pattern-type keyword \
+  --confidence 85
+```
+
+Show result: "✓ Updated 56 transactions and created rule: PAYPAL → Online Services"
+
+### Option B: "Recategorize all to [category]"
+
+Let user select category conversationally, then:
+
+```bash
+# Get category ID by name
+uv run python -u scripts/find_category.py "[CategoryName]"
+
+# Batch update with new category
+uv run python -u scripts/operations/update_transaction_batch.py \
+  --transaction-ids "12345,12346,12347,..." \
+  --category-id [ID] \
+  --clear-review-flags
+```
+
+Ask about rule creation (same as Option A).
+
+### Option C: "Skip this group (review individually later)"
+
+Add these transactions to the ungrouped list for individual review.
+
+### Option D: "Exit review"
+
+Stop processing, show summary of what's been completed so far.
+
+## Step 3: Review Ungrouped Transactions
+
+**IMPORTANT: Show ALL remaining transactions at once - don't iterate one by one.**
+
+Present all ungrouped transactions in a single list:
+
+```
+Remaining transactions to review (12):
+
+1. 2025-01-20 | $45.67 | Shopping | ACME STORE #123
+2. 2025-02-15 | $123.45 | Food & Dining | UNIQUE RESTAURANT
+3. 2025-03-10 | $78.90 | Online Services | PAYPAL *RAREMERCHANT
+... (show all)
+```
+
+Then provide options:
+
+**Available actions:**
+- "Accept all remaining (keep current categories)" - Batch clear all flags
+- "Recategorize transaction N to [category]" - Update single transaction, then re-show list
+- "Show final summary" - Exit review
+
+**When user recategorizes a transaction:**
+1. Update the transaction with the new category
+2. Remove it from the list
+3. Re-show the updated list with remaining transactions
+4. Continue until user accepts all or exits
+
+**Implementation:**
+
+**Batch accept all:**
+```bash
+# Extract all remaining IDs
+uv run python -u scripts/operations/update_transaction_batch.py \
+  --transaction-ids "[comma-separated IDs]" \
+  --clear-review-flags
+```
+
+**Single recategorize:**
+```bash
+uv run python -u scripts/operations/update_transaction.py [ID] \
+  --category-id [ID] \
+  --clear-conflict
+```
+
+After each update, re-display the remaining list until empty or user exits.
+
+## Step 4: Final Summary
+
+Track throughout the conversation:
+- Groups processed
+- Groups skipped
+- Total transactions updated
+- Rules created
+- Individual transactions (accepted/recategorized/skipped)
+
+Present final summary:
+
+```
+Review Complete!
+
+Groups:
+  Processed: 3 out of 4
+  Skipped: 1
+
+Individual Transactions:
+  Accepted: 8
+  Recategorized: 3
+  Skipped: 1
+
+Total:
+  Transactions updated: 67 out of 78
+  Rules created: 3
+  Remaining flagged: 11
+```
+
+## Deterministic Operations Scripts
+
+All data access uses git-tracked Python scripts:
+
+**Data Retrieval:**
+- `fetch_conflicts.py` - Get all flagged transactions
+- `group_conflicts.py` - Analyze and group by patterns
+
+**Data Updates:**
+- `update_transaction.py` - Update single transaction
+- `update_transaction_batch.py` - Update multiple transactions at once
+- `create_rule.py` - Create categorization rule
+
+**Category Lookup:**
+- `find_category.py` - Search for category by name
+
+**Benefits:**
+- All operations are version-controlled and testable
+- Scripts can be run independently for debugging
+- Deterministic: same inputs = same outputs
+- No hidden state or interactive prompts in scripts
+- Slash command orchestrates conversationally
+
+## Implementation Notes
+
+1. **Parse JSON outputs** from scripts to access transaction data
+2. **Build transaction ID lists** for batch operations
+3. **Track state** conversationally (which groups processed, etc.)
+4. **Handle errors gracefully** - if batch update fails partially, show which succeeded
+5. **Allow resume** - user can exit and re-run to continue where they left off
+
+## Example Conversation Flow
+
+```
+Agent: I found 78 transactions flagged for review. Analyzing patterns...
+
+Agent: Great news! I've grouped them:
+- 4 groups (66 transactions) - can batch process
+- 12 ungrouped (unique patterns) - review individually
+
+Let's start with the groups!
+
+Agent: GROUP 1: 56 transactions matching 'PAYPAL'
+[shows sample transactions]
+All are currently in "Online Services".
+
+What would you like to do?
+1. Accept all (they're correctly categorized)
+2. Recategorize all to a different category
+3. Skip (review individually)
+4. Exit
+
+User: Accept all
+
+Agent: Great! Updating all 56 PayPal transactions and clearing review flags...
+✓ Updated 56 transactions
+
+Would you like to create a rule for PAYPAL → Online Services to prevent future flags?
+
+User: Yes
+
+Agent: ✓ Created rule: PAYPAL → Online Services (confidence: 85)
+
+Agent: GROUP 2: 5 transactions matching 'EBAY'
+[continues...]
+```
+
+## Key Advantages Over Old Workflow
+
+❌ **Old:** Review 56 transactions one-by-one, create rule, reprocess, repeat
+✅ **New:** One decision processes 56 transactions immediately
+
+❌ **Old:** Multiple fetch/reprocess cycles
+✅ **New:** Single fetch, single pass
+
+❌ **Old:** Interactive Python script with input() prompts
+✅ **New:** Conversational slash command + deterministic scripts
+
+❌ **Old:** Hard to debug or test
+✅ **New:** All data operations are git-tracked and testable
--- a/commands/schedule.md
+++ b/commands/schedule.md
@@ -0,0 +1,138 @@
+---
+name: smith:schedule
+description: Configure automated categorization scheduling
+argument-hints:
+  - "[--setup|--status|--remove] [--frequency=daily|weekly] [--time=HH:MM]"
+---
+
+# Automated Categorization Scheduling
+
+Set up automatic categorization to run on a schedule without manual intervention.
+
+## Goal
+
+Keep your transactions categorized automatically in the background.
+
+## Why This Matters
+
+Regular categorization prevents backlogs and keeps your financial data current. Scheduled runs ensure you never fall behind, and conflicts are ready for quick review when you open Claude Code.
+
+## Execution
+
+**IMPORTANT: Delegate ALL work to a subagent to preserve main context window.**
+
+Use the Task tool with `subagent_type: "general-purpose"` to manage scheduling:
+
+```
+Task(
+  subagent_type: "general-purpose",
+  description: "Manage scheduling",
+  prompt: <full subagent prompt below>
+)
+```
+
+### Subagent Prompt
+
+You are the Agent Smith scheduling assistant.
+
+## Step 1: Check Current Status
+
+First, check if scheduling is already configured:
+
+```bash
+uv run python -u scripts/setup/schedule.py --status
+```
+
+## Step 2: Based on Arguments
+
+**--status (or no args):**
+Display current schedule status and recent activity.
+
+**--setup:**
+Ask user preferences using AskUserQuestion:
+
+1. **Frequency**: How often?
+   - Daily (recommended for most users)
+   - Weekly (for low-volume accounts)
+   - Hourly (for high-volume business accounts)
+
+2. **Time**: What time? (default: 6:00am)
+   - Suggest early morning before user typically opens Claude Code
+
+Then run:
+```bash
+uv run python -u scripts/setup/schedule.py --frequency [FREQ] --time [TIME]
+```
+
+**--remove:**
+```bash
+uv run python -u scripts/setup/schedule.py --remove
+```
+
+## Step 3: Present Results
+
+Show confirmation with:
+- Schedule details (frequency, time)
+- How it works (runs in background, logs results)
+- How to check status
+- How to remove if needed
+
+```
+✅ AUTO-CATEGORIZATION SCHEDULED
+═══════════════════════════════════════════════════════════════
+  Frequency: Daily
+  Time: 6:00 AM
+  Mode: Smart (auto-apply 90%+ confidence)
+
+  How it works:
+  - Runs automatically in the background
+  - Logs results to data/auto_categorize.log
+  - SessionStart dashboard shows last run status
+  - Conflicts flagged for /smith:review-conflicts
+
+  Commands:
+  - Check status: /smith:schedule --status
+  - Remove: /smith:schedule --remove
+═══════════════════════════════════════════════════════════════
+```
+
+## Visual Style
+
+Use emojis for status:
+- ✅ Scheduled/active
+- ⚠️ Configured but not active
+- ❌ Not configured
+
+---
+
+## Scheduling Options
+
+| Frequency | When | Best For |
+|-----------|------|----------|
+| **hourly** | Every hour | High-volume accounts |
+| **daily** | Once per day (default: 6am) | Most users |
+| **weekly** | Once per week (Sunday 6am) | Low-volume accounts |
+
+## Platform Support
+
+| Platform | Method | Setup |
+|----------|--------|-------|
+| **macOS** | launchd | Automatic |
+| **Linux (systemd)** | systemd timer | Automatic |
+| **Linux (other)** | cron | Manual (shows crontab entry) |
+
+## How It Works
+
+1. **Background Execution**: Runs without Claude Code open
+2. **Smart Mode**: Auto-applies 90%+ confidence categorizations
+3. **Conflict Flagging**: Low confidence items flagged for review
+4. **Activity Logging**: Results logged for SessionStart dashboard
+5. **No Duplicates**: Skips already-categorized transactions
+
+## Next Steps
+
+After scheduling:
+- **Check logs**: View `data/auto_categorize.log`
+- **Review flagged**: `/smith:review-conflicts`
+- **Manual run**: `/smith:categorize`
+- **Check status**: `/smith:schedule --status`
--- a/commands/tax.md
+++ b/commands/tax.md
@@ -0,0 +1,191 @@
+---
+name: smith:tax
+description: Tax-focused analysis and compliance for Australian tax requirements
+argument-hints:
+  - "<deductions|cgt|bas|eofy|scenario> [--period=YYYY-YY] [--level=smart|full]"
+---
+
+# Tax Intelligence
+
+Tax-focused analysis and compliance for Australian tax requirements (ATO).
+
+## Goal
+
+Track tax-deductible expenses, capital gains, and prepare for tax obligations with confidence.
+
+## Why This Matters
+
+Proper tax tracking throughout the year maximizes legitimate deductions, ensures compliance, and reduces stress at EOFY. Agent Smith helps you stay organized and audit-ready.
+
+## Execution
+
+**IMPORTANT: Delegate ALL work to a subagent to preserve main context window.**
+
+Use the Task tool with `subagent_type: "general-purpose"` to execute tax operations:
+
+```
+Task(
+  subagent_type: "general-purpose",
+  description: "Tax analysis",
+  prompt: <full subagent prompt below>
+)
+```
+
+### Subagent Prompt
+
+You are the Agent Smith tax intelligence assistant. Execute this workflow:
+
+## Step 1: Determine Operation
+
+Parse the command to determine which operation:
+- `deductions` - Track tax-deductible expenses
+- `cgt` - Capital gains tax tracking
+- `bas` - BAS preparation (GST calculations)
+- `eofy` - End of financial year prep
+- `scenario` - Tax scenario planning
+
+If no operation specified, ask using AskUserQuestion:
+"What tax operation would you like?"
+- Review my deductions (most common)
+- Track capital gains/losses
+- Prepare BAS worksheet
+- EOFY checklist
+- Run a tax scenario
+
+## Step 2: Run Tax Analysis
+
+Based on operation, call the appropriate script:
+
+**Deduction Tracking:**
+```bash
+uv run python -u scripts/tax/deduction_detector.py --period [PERIOD]
+```
+
+**CGT Analysis:**
+```bash
+uv run python -u scripts/tax/cgt_tracker.py --period [PERIOD]
+```
+
+**BAS Preparation:**
+```bash
+uv run python -u scripts/tax/bas_preparation.py --quarter [QUARTER]
+```
+
+**Tax Reporting:**
+```bash
+uv run python -u scripts/tax/reporting.py --period [PERIOD] --format [FORMAT]
+```
+
+Stream the output to show real-time progress.
+
+## Step 3: Present Results
+
+Present tax information with appropriate formatting:
+
+**Deductions Format:**
+```
+🧾 DEDUCTION SUMMARY - FY 2024-25
+═══════════════════════════════════════════════════════════════
+  Total Potential Deductions: $X,XXX.XX
+
+  By ATO Category:
+  D1 - Work-related expenses     $XXX.XX  ⚠️ Needs substantiation
+  D2 - Work-related car          $XXX.XX  ✅ Documented
+  D3 - Work-related travel       $XXX.XX  ✅ Documented
+  D5 - Self-education            $XXX.XX  ✅ Documented
+  ...
+
+  ⚠️ Substantiation Required:
+  • 3 items over $300 need receipts
+  • Review before October 31
+═══════════════════════════════════════════════════════════════
+```
+
+**CGT Format:**
+```
+📈 CAPITAL GAINS SUMMARY - FY 2024-25
+═══════════════════════════════════════════════════════════════
+  Gross Capital Gain:    $X,XXX.XX
+  50% CGT Discount:     -$X,XXX.XX  (held >12 months)
+  Net Capital Gain:      $X,XXX.XX
+
+  Events:
+  • BHP sold 01/15/2025: Gain $500 (eligible for discount)
+  • ETH sold 03/20/2025: Loss -$200 (offset)
+═══════════════════════════════════════════════════════════════
+```
+
+## Step 4: Tax Disclaimer (Level 3 only)
+
+For full tax intelligence operations, include:
+```
+⚠️ IMPORTANT: This analysis is for informational purposes only.
+Please consult a registered tax agent for professional advice
+specific to your situation before making tax decisions.
+```
+
+## Step 5: Offer Next Steps
+
+Based on operation:
+
+**After deductions review:**
+```
+🧾 Next Steps:
+→ /smith:categorize (ensure all transactions categorized)
+→ Upload missing receipts to PocketSmith
+→ Review flagged items before EOFY
+```
+
+**After CGT analysis:**
+```
+📈 Next Steps:
+→ Review unrealized gains for timing optimization
+→ Consider tax-loss harvesting if applicable
+```
+
+## Visual Style
+
+Use emojis for status:
+- ✅ Documented/substantiated
+- ⚠️ Needs attention/documentation
+- ❌ Missing/compliance issue
+
+Use tables for category breakdowns.
+Include ATO category codes (D1, D2, etc.).
+
+---
+
+## Tax Operations
+
+| Operation | Description | Script |
+|-----------|-------------|--------|
+| `deductions` | Track deductible expenses | `deduction_detector.py` |
+| `cgt` | Capital gains tracking | `cgt_tracker.py` |
+| `bas` | BAS worksheet prep | `bas_preparation.py` |
+| `eofy` | Year-end checklist | `reporting.py --format=eofy` |
+| `scenario` | Tax planning scenarios | `scenarios/tax_scenarios.py` |
+
+## Tax Intelligence Levels
+
+| Level | Features | Best For |
+|-------|----------|----------|
+| **smart** (default) | Deduction detection, CGT tracking, substantiation alerts | Most users |
+| **full** | BAS prep, compliance checks, audit-ready docs | GST registered, complex situations |
+
+## Australian Tax Compliance
+
+**Key Thresholds:**
+- $300: Substantiation required above this
+- $75: Taxi/Uber receipt threshold
+- $20,000: Instant asset write-off
+- 12 months: CGT 50% discount eligibility
+
+**Financial Year:**
+- July 1 - June 30
+- EOFY lodgment deadline: October 31
+
+## Next Steps
+
+- **Categorize transactions**: `/smith:categorize`
+- **Check health**: `/smith:health --category=tax`
+- **View spending**: `/smith:insights spending`