Initial commit

2025-11-30 08:57:54 +08:00
commit 8f952ee727
50 changed files with 11199 additions and 0 deletions
--- a/skills/agent-smith/.env.sample
+++ b/skills/agent-smith/.env.sample
@@ -0,0 +1,28 @@
+# PocketSmith API Authentication
+# Get your API key from: https://my.pocketsmith.com/user_settings/developer
+POCKETSMITH_API_KEY=<Your Developer API Key>
+
+# Agent Smith Configuration
+TAX_INTELLIGENCE_LEVEL=smart          # reference|smart|full
+DEFAULT_INTELLIGENCE_MODE=smart       # conservative|smart|aggressive
+AUTO_BACKUP=true
+AUTO_ARCHIVE=true
+ALERT_NOTIFICATIONS=true
+
+# Tax Configuration (Australia)
+TAX_JURISDICTION=AU
+FINANCIAL_YEAR_END=06-30             # June 30 (MM-DD format)
+GST_REGISTERED=false
+
+# Reporting Preferences
+DEFAULT_REPORT_FORMAT=all            # markdown|csv|json|html|excel|all
+CURRENCY=AUD
+
+# Advanced Settings
+API_RATE_LIMIT_DELAY=100             # milliseconds between API calls
+CACHE_TTL_DAYS=7                     # days to keep cached API responses
+SUBAGENT_MAX_PARALLEL=5              # maximum parallel subagent processes
+LOG_LEVEL=INFO                       # DEBUG|INFO|WARNING|ERROR
+
+# Python Execution
+PYTHONUNBUFFERED=1                   # disable output buffering (real-time progress)
--- a/skills/agent-smith/.gitignore
+++ b/skills/agent-smith/.gitignore
@@ -0,0 +1,61 @@
+# Sensitive - NEVER commit
+.env
+*.key
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+venv/
+env/
+ENV/
+*.egg-info/
+dist/
+build-python/
+.pytest_cache/
+.coverage
+.mypy_cache/
+.tox/
+htmlcov/
+
+# Agent Smith working data (not for git)
+*.log
+*_analysis.json
+*_data.json
+backups/*
+!backups/INDEX.md
+reports/*
+!reports/INDEX.md
+data/cache/
+logs/*
+!logs/INDEX.md
+
+# Onboarding state (tracked as template, but user's state will be overwritten)
+# Note: data/onboarding_state.json is committed as a template, but the user's
+# actual state will modify this file during onboarding. This is intentional.
+
+# Build reference (temporary - remove before publishing)
+build/
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Temporary files
+*.tmp
+*.temp
+*.bak
--- a/skills/agent-smith/README.md
+++ b/skills/agent-smith/README.md
@@ -0,0 +1,165 @@
+# Agent Smith - Claude Code Skill Source
+
+This directory contains the source files for the Agent Smith Claude Code skill.
+
+## Directory Structure
+
+```
+skill/
+├── SKILL.md                    # Main skill definition (required)
+├── .env.sample                 # Configuration template
+├── pyproject.toml              # Python dependencies
+├── uv.lock                     # Dependency lock file
+├── .gitignore                  # Git ignore patterns
+│
+├── scripts/                    # Python code (copied from ../scripts/)
+│   ├── core/                   # API client, rule engine, unified rules
+│   ├── operations/             # Categorization, batch processing
+│   ├── analysis/               # Spending analysis, trends
+│   ├── reporting/              # Report generation
+│   ├── tax/                    # Tax intelligence (3-tier)
+│   ├── scenarios/              # Scenario analysis
+│   ├── orchestration/          # Subagent conductor
+│   ├── workflows/              # Interactive workflows
+│   ├── features/               # Advanced features
+│   ├── health/                 # Health check system
+│   └── utils/                  # Utilities
+│
+├── references/                 # Documentation (loaded on-demand)
+│   ├── pocketsmith-api.md      # PocketSmith API reference
+│   ├── design.md               # Complete system architecture
+│   ├── unified-rules-guide.md  # Rule system documentation
+│   ├── onboarding-guide.md     # First-time setup guide
+│   ├── health-check-guide.md   # Health system details
+│   └── LESSONS_LEARNED.md      # Migration insights
+│
+├── assets/                     # Templates and samples
+│   ├── templates/              # Pre-built rule templates
+│   ├── .env.sample             # Configuration template
+│   └── config.json.sample      # User preferences template
+│
+└── data/                       # Working directories (empty, created at runtime)
+    ├── templates/
+    ├── merchants/
+    ├── tax/
+    └── [other runtime directories]
+```
+
+## Building the Skill Package
+
+To rebuild the `agent-smith.skill` package after making changes:
+
+```bash
+# From the repository root
+./build-skill.sh
+```
+
+Or manually:
+
+```bash
+cd /path/to/agent-smith
+zip -r agent-smith.skill skill/ \
+  -x "*.pyc" \
+  -x "*__pycache__*" \
+  -x "*.git*" \
+  -x "skill/data/*" \
+  -x "skill/logs/*" \
+  -x "skill/backups/*" \
+  -x "skill/reports/*"
+```
+
+The packaged `.skill` file will be created in the repository root.
+
+## Development Workflow
+
+1. **Make changes** to files in this directory
+2. **Test changes** by copying to `~/.claude/skills/agent-smith/` and testing in Claude Code
+3. **Rebuild the package** using the build script
+4. **Commit changes** to the repository
+
+## What Gets Packaged
+
+**Included:**
+- ✅ SKILL.md (required)
+- ✅ All Python scripts
+- ✅ All reference documentation
+- ✅ Asset templates and samples
+- ✅ Configuration templates
+- ✅ Dependency files (pyproject.toml, uv.lock)
+- ✅ Empty data directories (structure only)
+
+**Excluded:**
+- ❌ Python cache files (*.pyc, __pycache__)
+- ❌ Git files
+- ❌ Runtime data (data/, logs/, backups/, reports/ contents)
+- ❌ User-specific configuration (.env)
+
+## File Organization
+
+Following Claude Code skill best practices:
+
+- **Progressive Disclosure**: SKILL.md is concise (~500 lines), detailed docs in references/
+- **Bundled Scripts**: All executable Python code in scripts/
+- **Reference Documentation**: Detailed guides loaded on-demand from references/
+- **Asset Templates**: Pre-built templates and configuration samples in assets/
+
+## Updating the Skill
+
+### Adding New Scripts
+
+1. Add/update scripts in `../scripts/`
+2. Copy to `skill/scripts/`:
+   ```bash
+   cp -r ../scripts/* skill/scripts/
+   ```
+3. Rebuild the package
+
+### Adding New Documentation
+
+1. Add documentation to `skill/references/`
+2. Reference it from SKILL.md if needed
+3. Rebuild the package
+
+### Updating SKILL.md
+
+1. Edit `skill/SKILL.md`
+2. Ensure frontmatter is valid YAML
+3. Keep instructions concise (<500 lines)
+4. Rebuild the package
+
+## Testing the Skill
+
+### Local Testing
+
+```bash
+# Install the skill locally
+/plugin install /path/to/agent-smith.skill
+
+# Or extract and copy manually
+cd ~/.claude/skills/
+unzip /path/to/agent-smith.skill
+cd agent-smith/
+cp .env.sample .env
+# Edit .env with your API key
+uv sync
+```
+
+### Run Tests
+
+```bash
+cd ~/.claude/skills/agent-smith/
+uv run python -u scripts/operations/batch_categorize.py --mode=dry_run
+```
+
+## Version History
+
+- **1.3.8** - Complete implementation (all 8 phases)
+- **1.0.0** - Initial skill package
+
+## Notes
+
+- This is the **source directory** for the skill - the actual skill package is `../agent-smith.skill`
+- Always rebuild the package after making changes
+- Test changes locally before distributing
+- Keep SKILL.md focused and concise
+- Move detailed documentation to references/
--- a/skills/agent-smith/SKILL.md
+++ b/skills/agent-smith/SKILL.md
@@ -0,0 +1,517 @@
+---
+name: agent-smith
+description: Intelligent financial management skill for Claude Code that provides comprehensive PocketSmith API integration with AI-powered analysis, transaction categorization, rule management, tax intelligence, and scenario planning. Use when working with PocketSmith data for (1) Transaction categorization and rule management, (2) Financial analysis and reporting, (3) Australian tax compliance (ATO) and deduction tracking, (4) Scenario analysis and forecasting, (5) PocketSmith setup health checks, (6) Budget optimization and spending insights.
+---
+
+# Agent Smith
+
+An intelligent financial management skill for Claude Code that transforms PocketSmith from a passive tracking tool into an active financial intelligence system.
+
+## Core Capabilities
+
+### 1. Hybrid Rule Engine
+- **Platform Rules**: Simple keyword patterns synced to PocketSmith API
+- **Local Rules**: Advanced regex, multi-condition logic, confidence scoring
+- **Intelligence Modes**: Conservative (manual approval), Smart (auto-apply ≥90%), Aggressive (auto-apply ≥80%)
+- **Performance Tracking**: Rule accuracy, matches, user overrides
+
+### 2. 3-Tier Tax Intelligence (Australian ATO)
+- **Level 1 (Reference)**: ATO category mappings, basic tax reports, GST tracking
+- **Level 2 (Smart)**: Deduction detection, CGT tracking, confidence scoring, expense splitting
+- **Level 3 (Full)**: BAS preparation, compliance checks, scenario planning, audit-ready documentation
+
+### 3. Transaction Categorization
+- **Batch Processing**: Categorize uncategorized transactions with AI assistance
+- **Merchant Intelligence**: Automatic payee normalization and variation detection
+- **AI Fallback**: LLM-powered categorization when rules don't match
+- **Dry-Run Mode**: Preview categorization before applying
+
+### 4. Financial Analysis & Reporting
+- **Spending Analysis**: By category, merchant, time period
+- **Trend Detection**: Increasing/decreasing categories, anomaly detection
+- **Multi-Format Reports**: Markdown, CSV/JSON, HTML dashboards, Excel
+- **Comparative Analysis**: YoY, QoQ, MoM comparisons
+
+### 5. Scenario Analysis
+- **Historical**: What-if replays ("What if I cut dining by 30% last year?")
+- **Projections**: Spending forecasts, affordability analysis, goal modeling
+- **Optimization**: Subscription analysis, expense rationalization, tax optimization
+- **Tax Planning**: Purchase timing, income deferral, CGT scenarios
+
+### 6. Health Check System
+- **6 Health Dimensions**: Data Quality, Category Structure, Rule Engine, Tax Readiness, Automation, Budget Alignment
+- **Automated Monitoring**: Weekly checks, EOFY prep, post-operation validation
+- **Prioritized Recommendations**: Top 3 highest-impact improvements
+
+### 7. Advanced Features
+- **Smart Alerts**: Budget overruns, tax thresholds, pattern detection
+- **Document Tracking**: Receipt requirements ($300 ATO threshold)
+- **Multi-User**: Shared expense tracking and settlement
+- **Audit Trail**: Complete activity log with undo capability
+
+## Quick Start
+
+### First-Time Setup
+
+1. **Prerequisites**:
+   - PocketSmith account with API access
+   - Developer API key from PocketSmith (Settings > Security)
+   - Python 3.9+ with uv package manager
+
+2. **Configuration**:
+   - Copy `.env.sample` to `.env`
+   - Add `POCKETSMITH_API_KEY=<your_key>`
+   - Set `TAX_INTELLIGENCE_LEVEL=smart` (reference|smart|full)
+   - Set `DEFAULT_INTELLIGENCE_MODE=smart` (conservative|smart|aggressive)
+
+3. **Installation**:
+   ```bash
+   # From the skill directory
+   uv sync
+   ```
+
+4. **Guided Onboarding**:
+   ```bash
+   # Launch integrated onboarding (8 stages)
+   /agent-smith:install
+   ```
+
+The onboarding process will:
+- Discover your PocketSmith account structure
+- Recommend and apply a rule template
+- Help customize rules for your needs
+- Configure intelligence modes
+- Incrementally categorize transactions
+- Show measurable improvement with health scores
+- Provide ongoing usage guidance
+- Generate intelligent suggestions
+
+**Time required**: 30-60 minutes for first-time setup
+
+### Daily Usage
+
+**Two Usage Modes:**
+
+1. **Guided Journey Mode** - When you start Claude Code, Agent Smith displays a status dashboard with:
+   - Your health score
+   - Uncategorized transaction count
+   - Conflicts awaiting review
+   - Suggested next steps with both natural language and command options
+
+2. **Power User Mode** - Use slash commands directly for specific operations.
+
+**Slash Commands** (7 specialized commands):
+- `/smith:install` - Installation and onboarding wizard
+- `/smith:categorize [--mode] [--period]` - Transaction categorization
+- `/smith:review-conflicts` - Review transactions flagged for review
+- `/smith:health [--full|--quick]` - Health check and recommendations
+- `/smith:insights <spending|trends|scenario|report>` - Financial analysis and reports
+- `/smith:tax <deductions|cgt|bas|eofy>` - Tax intelligence (ATO)
+- `/smith:schedule [--setup|--status|--remove]` - Automated categorization scheduling
+
+## Python Scripts
+
+All Python scripts are in `scripts/` directory. **Always run with `uv run python -u`** for proper dependency resolution and unbuffered output.
+
+### Core Operations
+
+```bash
+# Categorize transactions
+uv run python -u scripts/operations/batch_categorize.py --mode=smart --period=2025-11
+
+# Run health check
+uv run python -u scripts/health/check.py --full
+
+# Generate spending report
+uv run python -u scripts/reporting/generate.py --period=2025 --format=all
+
+# Tax deduction analysis
+uv run python -u scripts/tax/deduction_detector.py --period=2024-25
+```
+
+### Script Organization
+
+- **`scripts/core/`** - API client, rule engine, unified rules
+- **`scripts/operations/`** - Categorization, batch processing, transaction updates
+- **`scripts/analysis/`** - Spending analysis, trend detection
+- **`scripts/reporting/`** - Multi-format report generation
+- **`scripts/tax/`** - ATO mappings, deductions, CGT, BAS preparation
+- **`scripts/scenarios/`** - Historical, projections, optimization, tax scenarios
+- **`scripts/status/`** - Status dashboard for SessionStart hook
+- **`scripts/scheduled/`** - Automated scheduled tasks (cron/launchd)
+- **`scripts/health/`** - Health check engine, recommendations, monitoring
+- **`scripts/workflows/`** - Interactive categorization workflows
+- **`scripts/utils/`** - Backup, validation, logging, merchant normalization
+
+## Unified Rule System
+
+Agent Smith uses a YAML-based unified rule system for transaction categorization and labeling.
+
+### Quick Start with Rules
+
+```bash
+# 1. Choose a template for your household type
+uv run python scripts/setup/template_selector.py
+
+# 2. Customize rules in data/rules.yaml
+
+# 3. Test with dry run
+uv run python scripts/operations/batch_categorize.py --mode=dry_run --period=2025-11
+
+# 4. Apply to transactions
+uv run python scripts/operations/batch_categorize.py --mode=apply --period=2025-11
+```
+
+### Example Rule
+
+```yaml
+rules:
+  # Category rule - categorize transactions
+  - type: category
+    name: WOOLWORTHS → Groceries
+    patterns: [WOOLWORTHS, COLES, ALDI]
+    category: Food & Dining > Groceries
+    confidence: 95
+
+  # Label rule - apply labels based on context
+  - type: label
+    name: Shared Groceries
+    when:
+      categories: [Groceries]
+      accounts: [Shared Bills]
+    labels: [Shared Expense, Essential]
+```
+
+### Key Features
+- **Two-phase execution**: Categories first, then labels
+- **Pattern matching**: Regex patterns with exclusions
+- **Confidence scoring**: 0-100% for auto-apply logic
+- **LLM fallback**: AI categorization when rules don't match
+- **Intelligence modes**: Conservative/Smart/Aggressive
+- **Template system**: Pre-built rules for common household types
+- **Operational modes**: DRY_RUN/VALIDATE/APPLY for safe testing
+
+See [references/unified-rules-guide.md](references/unified-rules-guide.md) for complete documentation.
+
+## Tax Intelligence
+
+### ATO Compliance (Australian Tax Office)
+
+**Three Levels**:
+
+1. **Reference (Level 1)**:
+   - ATO category mappings
+   - Basic tax reports
+   - GST tracking
+   - Resource links
+
+2. **Smart (Level 2)** - Recommended:
+   - Deduction detection (14 pattern-based rules)
+   - CGT tracking with FIFO matching
+   - Confidence scoring
+   - Substantiation threshold checking ($300, $75 taxi/Uber)
+   - Time-based commuting detection
+   - Instant asset write-off tracking
+
+3. **Full (Level 3)** - Power Users:
+   - BAS preparation with GST calculations
+   - Compliance checks
+   - Scenario planning
+   - Audit-ready documentation
+   - Professional advice disclaimers
+
+**Configure Tax Level**:
+```bash
+# In .env file
+TAX_INTELLIGENCE_LEVEL=smart  # reference|smart|full
+TAX_JURISDICTION=AU
+FINANCIAL_YEAR_END=06-30
+```
+
+### Deduction Detection Example
+
+```python
+from scripts.tax.deduction_detector import DeductionDetector
+
+detector = DeductionDetector()
+result = detector.detect_deduction(transaction)
+# Returns: {"is_deductible": True, "confidence": "high",
+#           "reason": "Office supplies", "substantiation_required": True}
+```
+
+### CGT Tracking Example
+
+```python
+from scripts.tax.cgt_tracker import CGTTracker, AssetType
+from decimal import Decimal
+from datetime import date
+
+tracker = CGTTracker()
+tracker.track_purchase(
+    asset_type=AssetType.SHARES,
+    name="BHP Group",
+    quantity=Decimal("100"),
+    purchase_date=date(2023, 1, 1),
+    purchase_price=Decimal("45.50"),
+    fees=Decimal("19.95")
+)
+
+event = tracker.track_sale(
+    asset_type=AssetType.SHARES,
+    name="BHP Group",
+    quantity=Decimal("100"),
+    sale_date=date(2024, 6, 1),
+    sale_price=Decimal("52.00"),
+    fees=Decimal("19.95")
+)
+# Returns CGTEvent with capital_gain, discount_eligible, holding_period_days
+```
+
+## Scenario Analysis
+
+### Historical Analysis
+```python
+from scripts.scenarios.historical import calculate_what_if_spending
+
+scenario = calculate_what_if_spending(
+    transactions=transactions,
+    category_name="Dining",
+    adjustment_percent=-30.0,  # 30% reduction
+    start_date="2025-01-01",
+    end_date="2025-12-31"
+)
+print(f"Savings: ${scenario['savings']:.2f}")
+```
+
+### Spending Forecast
+```python
+from scripts.scenarios.projections import forecast_spending
+
+forecast = forecast_spending(
+    transactions=transactions,
+    category_name="Groceries",
+    months_forward=6,
+    inflation_rate=3.0
+)
+```
+
+### Optimization Suggestions
+```python
+from scripts.scenarios.optimization import suggest_optimizations
+
+optimizations = suggest_optimizations(transactions=transactions)
+print(f"Potential savings: ${optimizations['potential_annual_savings']:.2f}")
+```
+
+## Subagent Orchestration
+
+Agent Smith uses intelligent subagent orchestration for complex operations:
+
+**When to delegate to subagents**:
+- Transaction count > 100
+- Estimated tokens > 5000
+- Bulk processing or deep analysis
+- Multi-period operations
+- Parallelization opportunities
+
+**Subagent types**:
+- `categorization-agent` - Transaction categorization
+- `analysis-agent` - Financial analysis
+- `reporting-agent` - Report generation
+- `tax-agent` - Tax intelligence operations
+- `optimization-agent` - Category/rule optimization
+- `scenario-agent` - Scenario modeling
+
+**Context preservation**: Main skill maintains user preferences, session state, and high-level decisions while subagents handle heavy processing.
+
+## Health Check System
+
+```bash
+# Run comprehensive health check
+uv run python scripts/health/check.py --full
+```
+
+**6 Health Dimensions** (scored 0-100):
+1. **Data Quality (25%)** - Uncategorized rate, duplicates, gaps
+2. **Category Structure (20%)** - Depth, unused categories, distribution
+3. **Rule Engine (15%)** - Coverage, efficiency, conflicts
+4. **Tax Readiness (15%)** - Tax categorization, compliance
+5. **Automation (10%)** - Savings automation, bill scheduling
+6. **Budget Alignment (15%)** - Variance, overspending
+
+**Output includes**:
+- Overall score with status (Poor/Fair/Good/Excellent)
+- Individual dimension scores
+- Top 3 prioritized recommendations
+- Projected score after improvements
+
+**Automated monitoring**:
+- Weekly quick health checks
+- Monthly full health analysis
+- Pre-EOFY comprehensive check
+- Post-major-operation validation
+
+## Configuration Files
+
+### `.env` (Required)
+```bash
+# PocketSmith API
+POCKETSMITH_API_KEY=<Your Developer API Key>
+
+# Agent Smith Configuration
+TAX_INTELLIGENCE_LEVEL=smart          # reference|smart|full
+DEFAULT_INTELLIGENCE_MODE=smart       # conservative|smart|aggressive
+AUTO_BACKUP=true
+AUTO_ARCHIVE=true
+ALERT_NOTIFICATIONS=true
+
+# Tax Configuration (Australia)
+TAX_JURISDICTION=AU
+FINANCIAL_YEAR_END=06-30             # June 30
+GST_REGISTERED=false
+
+# Reporting Preferences
+DEFAULT_REPORT_FORMAT=all            # markdown|csv|json|html|excel|all
+CURRENCY=AUD
+
+# Advanced
+API_RATE_LIMIT_DELAY=100             # ms between calls
+CACHE_TTL_DAYS=7
+SUBAGENT_MAX_PARALLEL=5
+```
+
+### `data/config.json` (User Preferences)
+```json
+{
+  "user_id": 217031,
+  "tax_level": "smart",
+  "intelligence_mode": "smart",
+  "alerts_enabled": true,
+  "backup_before_mutations": true,
+  "auto_archive": true,
+  "default_report_formats": ["markdown", "csv", "html"]
+}
+```
+
+### `data/rules.yaml` (Unified Rules)
+See references/unified-rules-guide.md for complete schema and examples.
+
+## Directory Structure
+
+```
+agent-smith/
+├── SKILL.md                    # This file
+├── .env                        # API configuration (not committed)
+├── .env.sample                 # Configuration template
+├── data/                       # Working data and state
+│   ├── config.json             # User preferences
+│   ├── rules.yaml              # Unified categorization rules
+│   ├── templates/              # Pre-built rule templates
+│   └── [other runtime data]
+├── scripts/                    # Python code
+│   ├── core/                   # API client, rule engine, utilities
+│   ├── operations/             # Categorization, batch processing
+│   ├── analysis/               # Spending analysis, trends
+│   ├── reporting/              # Multi-format reports
+│   ├── tax/                    # Tax intelligence (3-tier)
+│   ├── scenarios/              # Scenario analysis
+│   ├── orchestration/          # Subagent conductor
+│   ├── workflows/              # Interactive workflows
+│   ├── features/               # Advanced features
+│   ├── health/                 # Health check system
+│   └── utils/                  # Utilities
+├── references/                 # Documentation
+│   ├── pocketsmith-api.md      # PocketSmith API reference
+│   ├── unified-rules-guide.md  # Complete rules documentation
+│   ├── onboarding-guide.md     # First-time setup guide
+│   └── health-check-guide.md   # Health check documentation
+├── backups/                    # Timestamped backups (30-day retention)
+├── logs/                       # Execution logs (14-day retention)
+└── reports/                    # Generated reports (90-day retention)
+```
+
+## Critical Operating Rules
+
+**NEVER create custom one-off scripts for core Agent Smith operations.**
+
+Agent Smith has a complete architecture with:
+- Slash commands (`/smith:categorize`, `/smith:analyze`, etc.)
+- Python workflows in `scripts/workflows/`
+- Core operations in `scripts/operations/`
+- Proper API client with correct endpoints in `scripts/core/api_client.py`
+
+**If you find yourself writing a new Python script to:**
+- Categorize transactions
+- Analyze spending
+- Generate reports
+- Update PocketSmith data
+- Run health checks
+
+**STOP. You are reinventing the wheel.**
+
+**Instead:**
+1. Check if a slash command exists (`/smith:*`)
+2. Check if a workflow exists in `scripts/workflows/`
+3. Check if a core operation exists in `scripts/operations/`
+4. Use the existing code that has been tested and uses correct API endpoints
+
+**Why this matters:**
+- Custom scripts may use wrong API endpoints (e.g., `/users/{id}/transactions/{id}` instead of `/transactions/{id}`)
+- Custom scripts bypass rule engine, validation, backup, and audit systems
+- Custom scripts duplicate functionality that already exists
+- Custom scripts won't benefit from future improvements
+
+**Exception:** Only create new scripts when building NEW features not yet in the design, and always place them in the correct `scripts/` subdirectory.
+
+## Best Practices
+
+### Transaction Categorization
+1. **Always use `/smith:categorize`** - Never create custom categorization scripts
+2. Start with a rule template matching your household type
+3. Use dry-run mode to preview categorization
+4. Review and adjust rules based on results
+5. Monitor rule performance metrics
+6. Let AI handle edge cases (LLM fallback)
+
+### Tax Compliance
+1. Configure appropriate tax level for your needs
+2. Track all deductible expenses as they occur
+3. Maintain receipt documentation (>$300 ATO requirement)
+4. Review tax reports before EOFY (June 30)
+5. Consult registered tax agent for complex situations
+
+### Financial Health
+1. Run health checks monthly
+2. Address high-priority recommendations first
+3. Maintain 95%+ categorization rate
+4. Review and clean up unused categories
+5. Set up automated alerts for budget overruns
+
+### Backup and Safety
+1. Always backup before bulk operations (automatic)
+2. Use dry-run mode for untested operations
+3. Review audit trail for unexpected changes
+4. Maintain 30 days of recent backups
+5. Export tax reports for 7-year ATO retention
+
+## References
+
+For detailed documentation, see the `references/` directory:
+
+- **[PocketSmith API](references/pocketsmith-api.md)** - Complete API reference
+- **[Unified Rules Guide](references/unified-rules-guide.md)** - Rule system documentation
+- **[Onboarding Guide](references/onboarding-guide.md)** - First-time setup walkthrough
+- **[Health Check Guide](references/health-check-guide.md)** - Health system details
+- **[Design Document](references/design.md)** - Complete system architecture
+
+## Support
+
+**Version**: 1.6.0
+
+**Documentation**: See references/ directory for comprehensive guides
+
+**Issues**: For questions or issues, refer to the design documentation or create an issue in the repository.
+
+---
+
+**Note**: Agent Smith is designed for Australian tax compliance (ATO). Adapting for other jurisdictions requires updating tax intelligence modules and reference documentation.
--- a/skills/agent-smith/assets/.env.sample
+++ b/skills/agent-smith/assets/.env.sample
@@ -0,0 +1,28 @@
+# PocketSmith API Authentication
+# Get your API key from: https://my.pocketsmith.com/user_settings/developer
+POCKETSMITH_API_KEY=<Your Developer API Key>
+
+# Agent Smith Configuration
+TAX_INTELLIGENCE_LEVEL=smart          # reference|smart|full
+DEFAULT_INTELLIGENCE_MODE=smart       # conservative|smart|aggressive
+AUTO_BACKUP=true
+AUTO_ARCHIVE=true
+ALERT_NOTIFICATIONS=true
+
+# Tax Configuration (Australia)
+TAX_JURISDICTION=AU
+FINANCIAL_YEAR_END=06-30             # June 30 (MM-DD format)
+GST_REGISTERED=false
+
+# Reporting Preferences
+DEFAULT_REPORT_FORMAT=all            # markdown|csv|json|html|excel|all
+CURRENCY=AUD
+
+# Advanced Settings
+API_RATE_LIMIT_DELAY=100             # milliseconds between API calls
+CACHE_TTL_DAYS=7                     # days to keep cached API responses
+SUBAGENT_MAX_PARALLEL=5              # maximum parallel subagent processes
+LOG_LEVEL=INFO                       # DEBUG|INFO|WARNING|ERROR
+
+# Python Execution
+PYTHONUNBUFFERED=1                   # disable output buffering (real-time progress)
--- a/skills/agent-smith/assets/config.json
+++ b/skills/agent-smith/assets/config.json
@@ -0,0 +1,28 @@
+{
+  "user_id": null,
+  "tax_level": "smart",
+  "intelligence_mode": "smart",
+  "alerts_enabled": true,
+  "alert_preferences": {
+    "budget": true,
+    "tax": true,
+    "patterns": true,
+    "optimization": true,
+    "frequency": "weekly"
+  },
+  "backup_before_mutations": true,
+  "auto_archive": true,
+  "default_report_formats": [
+    "markdown",
+    "csv"
+  ],
+  "household": {
+    "enabled": false,
+    "members": [],
+    "split_method": "proportional"
+  },
+  "benchmarking": {
+    "enabled": false,
+    "criteria": {}
+  }
+}
--- a/skills/agent-smith/assets/config.json.sample
+++ b/skills/agent-smith/assets/config.json.sample
@@ -0,0 +1,28 @@
+{
+  "user_id": null,
+  "tax_level": "smart",
+  "intelligence_mode": "smart",
+  "alerts_enabled": true,
+  "alert_preferences": {
+    "budget": true,
+    "tax": true,
+    "patterns": true,
+    "optimization": true,
+    "frequency": "weekly"
+  },
+  "backup_before_mutations": true,
+  "auto_archive": true,
+  "default_report_formats": [
+    "markdown",
+    "csv"
+  ],
+  "household": {
+    "enabled": false,
+    "members": [],
+    "split_method": "proportional"
+  },
+  "benchmarking": {
+    "enabled": false,
+    "criteria": {}
+  }
+}
--- a/skills/agent-smith/assets/local_rules.json
+++ b/skills/agent-smith/assets/local_rules.json
@@ -0,0 +1 @@
+[]
--- a/skills/agent-smith/assets/merchants/merchant_mappings.json
+++ b/skills/agent-smith/assets/merchants/merchant_mappings.json
@@ -0,0 +1 @@
+{}
--- a/skills/agent-smith/assets/onboarding_state.json
+++ b/skills/agent-smith/assets/onboarding_state.json
@@ -0,0 +1,11 @@
+{
+  "current_stage": "not_started",
+  "completed_stages": [],
+  "discovery_report": null,
+  "template_selected": null,
+  "intelligence_mode": null,
+  "tax_level": null,
+  "baseline_health_score": null,
+  "current_health_score": null,
+  "categorization_batches": []
+}
--- a/skills/agent-smith/assets/platform_rules.json
+++ b/skills/agent-smith/assets/platform_rules.json
@@ -0,0 +1 @@
+[]
--- a/skills/agent-smith/assets/tax/ato_category_mappings.json
+++ b/skills/agent-smith/assets/tax/ato_category_mappings.json
@@ -0,0 +1,55 @@
+{
+  "mappings": [
+    {
+      "pocketsmith_category": "Groceries",
+      "ato_code": null,
+      "ato_category": "Personal expense",
+      "deductible": false,
+      "notes": "Not deductible for individuals. Business owners: keep receipts for food provided to staff.",
+      "substantiation_required": false
+    },
+    {
+      "pocketsmith_category": "Office Supplies",
+      "ato_code": "D5",
+      "ato_category": "Work-related other expenses",
+      "deductible": true,
+      "notes": "Keep receipts if under $300 total. Retain for 5 years.",
+      "substantiation_required": true,
+      "threshold": 300.0
+    },
+    {
+      "pocketsmith_category": "Transport",
+      "ato_code": "D1",
+      "ato_category": "Work-related car expenses",
+      "deductible": true,
+      "notes": "Must substantiate if using logbook or actual costs method. $0.78/km for cents per km method (2024-25).",
+      "substantiation_required": true
+    },
+    {
+      "pocketsmith_category": "Home & Utilities",
+      "ato_code": "D5",
+      "ato_category": "Work-related other expenses",
+      "deductible": true,
+      "notes": "Only home office portion deductible. Use fixed rate method (67c/hour) or actual costs method.",
+      "substantiation_required": true
+    },
+    {
+      "pocketsmith_category": "Professional Development",
+      "ato_code": "D4",
+      "ato_category": "Work-related self-education expenses",
+      "deductible": true,
+      "notes": "Must have sufficient connection to current income-earning activities.",
+      "substantiation_required": true
+    }
+  ],
+  "ato_categories": [
+    {"code": "D1", "name": "Work-related car expenses", "schedule": "D"},
+    {"code": "D2", "name": "Work-related travel expenses", "schedule": "D"},
+    {"code": "D3", "name": "Work-related clothing, laundry and dry-cleaning expenses", "schedule": "D"},
+    {"code": "D4", "name": "Work-related self-education expenses", "schedule": "D"},
+    {"code": "D5", "name": "Work-related other expenses", "schedule": "D"},
+    {"code": "D6", "name": "Work-related interest, dividend and other investment income deductions", "schedule": "D"},
+    {"code": "CGT", "name": "Capital gains tax", "schedule": "CGT"},
+    {"code": "BAS", "name": "Business activity statement", "schedule": "BAS"}
+  ]
+}
--- a/skills/agent-smith/assets/tax/deduction_patterns.json
+++ b/skills/agent-smith/assets/tax/deduction_patterns.json
@@ -0,0 +1,200 @@
+{
+  "version": "1.0.0",
+  "last_updated": "2025-11-20",
+  "description": "Pattern-based deduction detection rules for Australian tax compliance (Level 2)",
+
+  "patterns": [
+    {
+      "id": "office_supplies",
+      "category_patterns": ["Office Supplies", "Stationery", "Business Supplies"],
+      "payee_patterns": ["Officeworks", "Office Depot", "Staples"],
+      "deductible": true,
+      "confidence": "high",
+      "ato_category": "Work-related other expenses",
+      "ato_code": "D5",
+      "reason": "Office supplies and stationery for work purposes",
+      "substantiation_notes": "Keep receipts for items over $300"
+    },
+    {
+      "id": "computer_equipment",
+      "category_patterns": ["Computer Equipment", "Electronics", "Technology"],
+      "payee_patterns": ["Apple Store", "JB Hi-Fi", "Harvey Norman"],
+      "keywords": ["laptop", "computer", "monitor", "keyboard", "mouse"],
+      "deductible": true,
+      "confidence": "medium",
+      "ato_category": "Work-related other expenses",
+      "ato_code": "D5",
+      "reason": "Computer equipment for work purposes",
+      "substantiation_notes": "Items over $300 require receipts. May qualify for instant asset write-off if under threshold.",
+      "instant_asset_write_off_eligible": true
+    },
+    {
+      "id": "professional_development",
+      "category_patterns": ["Professional Development", "Education", "Training", "Courses"],
+      "payee_patterns": ["LinkedIn", "Coursera", "Udemy", "Professional Association"],
+      "deductible": true,
+      "confidence": "high",
+      "ato_category": "Self-education expenses",
+      "ato_code": "D4",
+      "reason": "Professional development and education expenses",
+      "substantiation_notes": "Keep certificates and receipts"
+    },
+    {
+      "id": "home_office_furniture",
+      "category_patterns": ["Furniture", "Home Office"],
+      "keywords": ["desk", "chair", "office", "filing cabinet", "bookshelf"],
+      "deductible": true,
+      "confidence": "medium",
+      "ato_category": "Home office expenses",
+      "ato_code": "D2",
+      "reason": "Home office furniture and equipment",
+      "substantiation_notes": "Must be used primarily for work. Consider depreciation for items over $300."
+    },
+    {
+      "id": "mobile_phone",
+      "category_patterns": ["Mobile Phone", "Phone", "Telecommunications"],
+      "payee_patterns": ["Telstra", "Optus", "Vodafone"],
+      "deductible": true,
+      "confidence": "low",
+      "ato_category": "Work-related other expenses",
+      "ato_code": "D5",
+      "reason": "Mobile phone expenses - consider work/personal usage split",
+      "substantiation_notes": "Calculate work-related percentage. May need to apportion costs.",
+      "requires_apportionment": true
+    },
+    {
+      "id": "internet",
+      "category_patterns": ["Internet", "Utilities"],
+      "payee_patterns": ["Telstra", "Optus", "TPG", "Aussie Broadband"],
+      "keywords": ["internet", "broadband", "nbn"],
+      "deductible": true,
+      "confidence": "low",
+      "ato_category": "Home office expenses",
+      "ato_code": "D2",
+      "reason": "Internet expenses - consider work/personal usage split",
+      "substantiation_notes": "Calculate work-related percentage based on usage.",
+      "requires_apportionment": true
+    },
+    {
+      "id": "business_travel_taxi",
+      "category_patterns": ["Transport", "Taxi", "Rideshare"],
+      "payee_patterns": ["Uber", "DiDi", "Taxi", "Ola", "13CABS"],
+      "deductible": true,
+      "confidence": "medium",
+      "ato_category": "Work-related travel expenses",
+      "ato_code": "D1",
+      "reason": "Business travel - taxi/rideshare",
+      "substantiation_notes": "Trips over $75 require written evidence. Commuting to/from regular workplace NOT deductible.",
+      "special_threshold": 75,
+      "commuting_detection": true
+    },
+    {
+      "id": "vehicle_expenses",
+      "category_patterns": ["Fuel", "Car Maintenance", "Vehicle"],
+      "payee_patterns": ["BP", "Shell", "Caltex", "7-Eleven", "United Petroleum"],
+      "deductible": true,
+      "confidence": "low",
+      "ato_category": "Work-related car expenses",
+      "ato_code": "D2",
+      "reason": "Vehicle expenses - consider cents per km or logbook method",
+      "substantiation_notes": "Keep logbook or calculate km. Commuting NOT deductible.",
+      "requires_apportionment": true
+    },
+    {
+      "id": "groceries_personal",
+      "category_patterns": ["Groceries", "Food", "Supermarket"],
+      "payee_patterns": ["Woolworths", "Coles", "IGA", "Aldi"],
+      "deductible": false,
+      "confidence": "high",
+      "ato_category": "Personal expense",
+      "reason": "Personal groceries and food are not tax deductible for individuals",
+      "substantiation_notes": "Not deductible for individuals. May be deductible for businesses in specific circumstances."
+    },
+    {
+      "id": "clothing_personal",
+      "category_patterns": ["Clothing", "Fashion"],
+      "deductible": false,
+      "confidence": "high",
+      "ato_category": "Personal expense",
+      "reason": "Personal clothing is not tax deductible unless it is protective, occupation-specific, or uniform",
+      "substantiation_notes": "Only protective clothing, occupation-specific clothing, or registered uniforms are deductible."
+    },
+    {
+      "id": "protective_clothing",
+      "category_patterns": ["Work Clothing", "Safety Equipment"],
+      "keywords": ["uniform", "safety", "protective", "hi-vis", "steel cap"],
+      "deductible": true,
+      "confidence": "high",
+      "ato_category": "Work-related clothing expenses",
+      "ato_code": "D6",
+      "reason": "Protective clothing and occupation-specific uniforms",
+      "substantiation_notes": "Must be occupation-specific or protective. Conventional clothing not deductible."
+    },
+    {
+      "id": "subscriptions_professional",
+      "category_patterns": ["Subscriptions", "Professional Services"],
+      "keywords": ["professional", "membership", "association", "subscription"],
+      "deductible": true,
+      "confidence": "medium",
+      "ato_category": "Work-related other expenses",
+      "ato_code": "D5",
+      "reason": "Professional memberships and subscriptions",
+      "substantiation_notes": "Must be directly related to earning income."
+    },
+    {
+      "id": "entertainment_personal",
+      "category_patterns": ["Entertainment", "Dining", "Recreation"],
+      "deductible": false,
+      "confidence": "high",
+      "ato_category": "Personal expense",
+      "reason": "Personal entertainment and dining expenses are not deductible",
+      "substantiation_notes": "Not deductible unless it is a valid business meal meeting specific criteria."
+    },
+    {
+      "id": "books_technical",
+      "category_patterns": ["Books", "Media"],
+      "keywords": ["technical", "professional", "textbook", "reference"],
+      "deductible": true,
+      "confidence": "medium",
+      "ato_category": "Self-education expenses",
+      "ato_code": "D4",
+      "reason": "Technical and professional reference books",
+      "substantiation_notes": "Must be directly related to current work or income-earning activities."
+    }
+  ],
+
+  "substantiation_thresholds": {
+    "default": 300,
+    "taxi_rideshare": 75,
+    "laundry": 150,
+    "description": "ATO substantiation thresholds - amounts requiring written evidence"
+  },
+
+  "commuting_hours": {
+    "weekday_morning": {
+      "start": "06:00",
+      "end": "09:30",
+      "description": "Typical morning commute period"
+    },
+    "weekday_evening": {
+      "start": "16:30",
+      "end": "19:00",
+      "description": "Typical evening commute period"
+    },
+    "description": "Time periods indicating likely commuting (NOT deductible)"
+  },
+
+  "instant_asset_write_off": {
+    "threshold": 20000,
+    "description": "Instant asset write-off threshold (check current ATO guidelines)",
+    "notes": "Assets under this amount may be immediately deductible. Verify current year threshold."
+  },
+
+  "confidence_scoring": {
+    "high": "Clear patterns matching deductible/non-deductible categories with minimal ambiguity",
+    "medium": "Likely deductible but requires additional context or apportionment",
+    "low": "Ambiguous - needs manual review or additional information"
+  },
+
+  "disclaimer": "This is automated pattern matching only. Rules are based on general ATO guidelines and may not apply to individual circumstances. Always consult a registered tax agent for specific advice."
+}
--- a/skills/agent-smith/assets/templates/README.md
+++ b/skills/agent-smith/assets/templates/README.md
@@ -0,0 +1,23 @@
+# Agent Smith Templates
+
+This directory contains composable template configurations for PocketSmith onboarding.
+
+## Structure
+
+- **primary/** - Primary income structure templates (choose ONE)
+- **living/** - Living arrangement templates (choose ONE)
+- **additional/** - Additional income source templates (choose MULTIPLE)
+
+## Usage
+
+Templates are YAML files that define:
+- Categories to create
+- Categorization rules
+- Tax tracking configuration
+- Smart alerts
+
+During onboarding, templates are selected and merged using `scripts/setup/template_merger.py`.
+
+## Template Schema
+
+See individual layer README files for YAML schema details.
--- a/skills/agent-smith/assets/templates/additional/README.md
+++ b/skills/agent-smith/assets/templates/additional/README.md
@@ -0,0 +1,15 @@
+# Additional Income Templates
+
+Select MULTIPLE templates for additional income sources beyond your primary income.
+
+## Available Templates
+
+- `side-hustle.yaml` - Freelancing, consulting, gig work
+- `property-investor.yaml` - Rental income, negative gearing, CGT
+- `share-investor.yaml` - Dividends, franking credits, share CGT
+- `crypto-investor.yaml` - Cryptocurrency trading and staking
+- `trust-structures.yaml` - Family trust, company distributions
+
+## YAML Schema
+
+Same structure as primary templates, with `layer: additional` and higher priority values (3+).
--- a/skills/agent-smith/assets/templates/additional/airbnb-host.yaml
+++ b/skills/agent-smith/assets/templates/additional/airbnb-host.yaml
@@ -0,0 +1,175 @@
+name: Airbnb Host
+layer: additional
+description: |
+  Short-term rental income tracking for Airbnb, Stayz, and similar platforms.
+  Includes expense apportionment for owner-occupied properties and CGT considerations.
+
+categories:
+  - name: "Airbnb:Income"
+    parent: null
+    description: "Short-term rental income from Airbnb, Stayz, etc."
+
+  - name: "Airbnb:Cleaning & Laundry"
+    parent: null
+    description: "Cleaning services and laundry for guests"
+
+  - name: "Airbnb:Guest Amenities"
+    parent: null
+    description: "Toiletries, coffee, tea, snacks for guests"
+
+  - name: "Airbnb:Linen & Towels"
+    parent: null
+    description: "Linen, towels, bedding for guest accommodation"
+
+  - name: "Airbnb:Platform Fees"
+    parent: null
+    description: "Airbnb/Stayz service fees and commissions"
+
+  - name: "Airbnb:Repairs & Maintenance"
+    parent: null
+    description: "Repairs and maintenance related to rental use"
+
+  - name: "Airbnb:Utilities"
+    parent: null
+    description: "Utilities attributable to rental use (apportioned)"
+
+  - name: "Airbnb:Insurance"
+    parent: null
+    description: "Host insurance and additional coverage"
+
+  - name: "Airbnb:Marketing & Listings"
+    parent: null
+    description: "Photography, listing fees, advertising"
+
+rules:
+  - id: airbnb-income
+    pattern: "Airbnb.*payout|Airbnb.*income|Stayz.*payout|booking.com.*payout|short.*term.*rental.*income"
+    category: "Airbnb:Income"
+    confidence: high
+    labels: ["Assessable Income", "Rental Income"]
+    description: "Detect short-term rental income"
+
+  - id: airbnb-cleaning
+    pattern: "cleaning.*Airbnb|laundry.*guest|linen.*service|professional.*clean.*rental"
+    category: "Airbnb:Cleaning & Laundry"
+    confidence: high
+    labels: ["Tax Deductible", "Apportioned"]
+    description: "Detect cleaning and laundry expenses"
+
+  - id: guest-amenities
+    pattern: "toiletries.*guest|coffee.*Airbnb|tea.*guest|snacks.*guest|welcome.*pack"
+    category: "Airbnb:Guest Amenities"
+    confidence: medium
+    labels: ["Tax Deductible", "Apportioned"]
+    description: "Detect guest amenity purchases"
+
+  - id: linen-towels
+    pattern: "linen.*rental|towels.*guest|bedding.*Airbnb|sheets.*accommodation"
+    category: "Airbnb:Linen & Towels"
+    confidence: high
+    labels: ["Tax Deductible", "Apportioned"]
+    description: "Detect linen and towel purchases"
+
+  - id: platform-fees
+    pattern: "Airbnb.*service.*fee|Airbnb.*commission|Stayz.*fee|booking.*commission"
+    category: "Airbnb:Platform Fees"
+    confidence: high
+    labels: ["Tax Deductible"]
+    description: "Detect platform service fees"
+
+  - id: rental-repairs
+    pattern: "repair.*rental|maintenance.*Airbnb|fix.*guest.*room|handyman.*rental"
+    category: "Airbnb:Repairs & Maintenance"
+    confidence: medium
+    labels: ["Tax Deductible", "Apportioned", "Repairs vs Improvements"]
+    description: "Detect repairs related to rental use"
+
+  - id: rental-utilities
+    pattern: "electricity.*rental|gas.*rental|water.*rental|internet.*rental"
+    category: "Airbnb:Utilities"
+    confidence: low
+    labels: ["Tax Deductible", "Apportioned"]
+    description: "Detect utilities for apportionment (requires manual review)"
+
+  - id: host-insurance
+    pattern: "Airbnb.*insurance|host.*insurance|short.*term.*rental.*insurance"
+    category: "Airbnb:Insurance"
+    confidence: high
+    labels: ["Tax Deductible", "Apportioned"]
+    description: "Detect host insurance premiums"
+
+  - id: listing-marketing
+    pattern: "photography.*listing|Airbnb.*listing|property.*photos.*rental"
+    category: "Airbnb:Marketing & Listings"
+    confidence: medium
+    labels: ["Tax Deductible"]
+    description: "Detect marketing and listing expenses"
+
+tax_tracking:
+  income_tracking: true
+  expense_apportionment_required: true
+  apportionment_basis: "days_rented"
+  cgt_main_residence_exemption_impact: true
+  record_keeping_days_rented: true
+  record_keeping_days_personal: true
+
+alerts:
+  - type: apportionment_reminder
+    schedule: quarterly
+    message: "Calculate expense apportionment: days rented vs personal use"
+
+  - type: days_rented_tracker
+    schedule: monthly
+    message: "Record days rented this month for expense apportionment"
+
+  - type: eofy_airbnb_reminder
+    schedule: annual
+    before_date: "06-15"
+    message: "EOFY - compile Airbnb income, calculate apportioned expenses, document days rented vs personal use"
+
+  - type: cgt_exemption_warning
+    trigger: annual
+    message: "Using main residence for income may affect CGT main residence exemption. Keep detailed records."
+
+  - type: gst_threshold_warning
+    trigger: annual_income_exceeds
+    threshold: 75000
+    message: "Airbnb income + other business income exceeds $75k - GST registration may be required"
+
+labels:
+  - name: "Assessable Income"
+    description: "Income assessable for tax purposes"
+    color: "green"
+    auto_apply: true
+
+  - name: "Rental Income"
+    description: "Short-term rental income"
+    color: "lightgreen"
+    auto_apply: false
+
+  - name: "Tax Deductible"
+    description: "Deductible expense (may require apportionment)"
+    color: "green"
+    auto_apply: false
+
+  - name: "Apportioned"
+    description: "Expense requiring apportionment by rental vs personal use"
+    color: "orange"
+    auto_apply: true
+
+  - name: "Repairs vs Improvements"
+    description: "Requires classification: repairs (deductible) vs improvements (capital)"
+    color: "orange"
+    auto_apply: false
+
+dependencies:
+  requires: []
+  conflicts_with: ["property-investor"]
+  notes: "Use property-investor for long-term rentals. Use airbnb-host for short-term/part-time hosting."
+
+metadata:
+  created: "2025-11-25"
+  version: "1.0.0"
+  author: "Agent Smith"
+  priority: 3
+  ato_guidance: "Airbnb income is assessable. Expenses must be apportioned if property is also used privately. Keep records of days rented vs personal use."
--- a/skills/agent-smith/assets/templates/additional/crypto-investor.yaml
+++ b/skills/agent-smith/assets/templates/additional/crypto-investor.yaml
@@ -0,0 +1,175 @@
+name: Crypto Investor
+layer: additional
+description: |
+  Cryptocurrency investment tracking with ATO-compliant CGT and income reporting.
+  Covers exchanges, staking, DeFi yields, and NFT transactions.
+
+categories:
+  - name: "Crypto:Purchases"
+    parent: null
+    description: "Cryptocurrency purchases (establishes cost base)"
+
+  - name: "Crypto:Sales"
+    parent: null
+    description: "Cryptocurrency sales (CGT events)"
+
+  - name: "Crypto:Staking Income"
+    parent: null
+    description: "Staking rewards and interest (ordinary income)"
+
+  - name: "Crypto:DeFi Yields"
+    parent: null
+    description: "DeFi protocol yields and liquidity rewards (ordinary income)"
+
+  - name: "Crypto:Airdrops & Forks"
+    parent: null
+    description: "Airdropped tokens and fork distributions (ordinary income at receipt)"
+
+  - name: "Crypto:NFT Purchases"
+    parent: null
+    description: "NFT purchases (establishes cost base)"
+
+  - name: "Crypto:NFT Sales"
+    parent: null
+    description: "NFT sales (CGT events)"
+
+  - name: "Crypto:Gas Fees"
+    parent: null
+    description: "Network gas fees (adds to cost base)"
+
+  - name: "Crypto:Exchange Fees"
+    parent: null
+    description: "Trading and platform fees"
+
+rules:
+  - id: crypto-purchase
+    pattern: "CoinSpot|Binance|Coinbase|Kraken|Independent.*Reserve|Swyftx|BTC.*Markets|crypto.*buy|BTC.*purchase|ETH.*purchase"
+    category: "Crypto:Purchases"
+    confidence: medium
+    labels: ["Crypto", "Cost Base"]
+    description: "Detect cryptocurrency purchases on Australian exchanges"
+
+  - id: crypto-sale
+    pattern: "crypto.*sell|BTC.*sale|ETH.*sale|sold.*crypto"
+    category: "Crypto:Sales"
+    confidence: medium
+    labels: ["Crypto", "CGT Event"]
+    description: "Detect cryptocurrency sales (CGT event)"
+
+  - id: staking-rewards
+    pattern: "staking.*reward|staked.*income|validator.*reward|POS.*reward"
+    category: "Crypto:Staking Income"
+    confidence: high
+    labels: ["Crypto", "Ordinary Income"]
+    description: "Detect staking rewards (ordinary income)"
+
+  - id: defi-yields
+    pattern: "DeFi|yield.*farming|liquidity.*pool|lending.*interest|Aave|Compound|Uniswap.*reward"
+    category: "Crypto:DeFi Yields"
+    confidence: medium
+    labels: ["Crypto", "Ordinary Income"]
+    description: "Detect DeFi protocol yields"
+
+  - id: airdrops
+    pattern: "airdrop|token.*distribution|fork.*distribution"
+    category: "Crypto:Airdrops & Forks"
+    confidence: high
+    labels: ["Crypto", "Ordinary Income"]
+    description: "Detect airdrops and fork distributions"
+
+  - id: nft-purchase
+    pattern: "NFT.*purchase|OpenSea.*buy|Rarible.*buy|digital.*art.*purchase"
+    category: "Crypto:NFT Purchases"
+    confidence: medium
+    labels: ["Crypto", "NFT", "Cost Base"]
+    description: "Detect NFT purchases"
+
+  - id: nft-sale
+    pattern: "NFT.*sale|OpenSea.*sale|sold.*NFT"
+    category: "Crypto:NFT Sales"
+    confidence: medium
+    labels: ["Crypto", "NFT", "CGT Event"]
+    description: "Detect NFT sales"
+
+  - id: gas-fees
+    pattern: "gas.*fee|network.*fee|ETH.*fee|transaction.*fee.*crypto"
+    category: "Crypto:Gas Fees"
+    confidence: high
+    labels: ["Crypto", "Cost Base Addition"]
+    description: "Detect blockchain gas fees"
+
+  - id: exchange-fees
+    pattern: "trading.*fee.*crypto|exchange.*fee|platform.*fee.*crypto"
+    category: "Crypto:Exchange Fees"
+    confidence: high
+    labels: ["Crypto"]
+    description: "Detect exchange and trading fees"
+
+tax_tracking:
+  cgt_tracking: true
+  cgt_discount_eligible: true
+  cgt_discount_holding_period: 365
+  cost_base_tracking: true
+  cost_base_includes_fees: true
+  income_tracking: true
+  separate_income_vs_capital: true
+
+alerts:
+  - type: crypto_cgt_event
+    trigger: sale_detected
+    message: "Crypto sale detected - calculate CGT (12-month holding = 50% discount)"
+
+  - type: crypto_income_reminder
+    schedule: quarterly
+    message: "Report crypto staking/DeFi income on quarterly basis"
+
+  - type: eofy_crypto_reminder
+    schedule: annual
+    before_date: "06-15"
+    message: "EOFY - compile all crypto CGT events and income. ATO requires detailed records."
+
+  - type: cost_base_reminder
+    trigger: purchase_detected
+    message: "Record AUD value at time of purchase for accurate cost base"
+
+labels:
+  - name: "Crypto"
+    description: "Cryptocurrency transaction"
+    color: "bitcoin-orange"
+    auto_apply: false
+
+  - name: "CGT Event"
+    description: "Capital gains tax event (crypto disposal)"
+    color: "gold"
+    auto_apply: true
+
+  - name: "Cost Base"
+    description: "Establishes or adds to CGT cost base"
+    color: "lightblue"
+    auto_apply: false
+
+  - name: "Cost Base Addition"
+    description: "Expense that adds to CGT cost base"
+    color: "skyblue"
+    auto_apply: false
+
+  - name: "Ordinary Income"
+    description: "Taxed as ordinary income (not CGT)"
+    color: "green"
+    auto_apply: true
+
+  - name: "NFT"
+    description: "Non-fungible token transaction"
+    color: "purple"
+    auto_apply: false
+
+dependencies:
+  requires: []
+  conflicts_with: []
+
+metadata:
+  created: "2025-11-25"
+  version: "1.0.0"
+  author: "Agent Smith"
+  priority: 3
+  ato_guidance: "ATO treats cryptocurrency as CGT asset. Staking/interest = ordinary income. Keep records of all transactions in AUD."
--- a/skills/agent-smith/assets/templates/additional/property-investor.yaml
+++ b/skills/agent-smith/assets/templates/additional/property-investor.yaml
@@ -0,0 +1,129 @@
+name: Property Investor
+layer: additional
+description: |
+  Rental property income and expenses tracking.
+  Includes negative gearing calculation and CGT cost base tracking.
+
+categories:
+  - name: "Rental Income"
+    parent: null
+    description: "Rent received from investment properties"
+
+  - name: "Property:Interest"
+    parent: null
+    description: "Mortgage interest on investment loans"
+
+  - name: "Property:Rates & Strata"
+    parent: null
+    description: "Council rates and strata fees"
+
+  - name: "Property:Repairs & Maintenance"
+    parent: null
+    description: "Repairs and maintenance expenses"
+
+  - name: "Property:Property Management"
+    parent: null
+    description: "Property management fees"
+
+  - name: "Property:Insurance"
+    parent: null
+    description: "Landlord insurance premiums"
+
+  - name: "Property:Depreciation"
+    parent: null
+    description: "Depreciation (manual entry from schedule)"
+
+rules:
+  - id: rental-income
+    pattern: "rent.*received|rental.*income|tenant.*payment"
+    category: "Rental Income"
+    confidence: high
+    labels: ["Property: {address}"]
+    description: "Detect rental income payments"
+
+  - id: property-loan-interest
+    pattern: "investment.*loan|property.*mortgage|loan.*interest"
+    category: "Property:Interest"
+    confidence: medium
+    labels: ["Tax Deductible", "Property: {address}"]
+    description: "Detect investment property loan interest"
+
+  - id: council-rates
+    pattern: "council.*rates|strata|body.*corporate"
+    category: "Property:Rates & Strata"
+    confidence: high
+    labels: ["Tax Deductible", "Property: {address}"]
+    description: "Detect rates and strata fees"
+
+  - id: property-repairs
+    pattern: "plumber|electrician|handyman|repairs.*property|maintenance.*rental"
+    category: "Property:Repairs & Maintenance"
+    confidence: medium
+    labels: ["Tax Deductible", "Property: {address}", "Repairs vs Improvements"]
+    description: "Detect repair and maintenance expenses"
+
+  - id: property-management-fee
+    pattern: "property.*management|real.*estate.*fee|letting.*fee"
+    category: "Property:Property Management"
+    confidence: high
+    labels: ["Tax Deductible", "Property: {address}"]
+    description: "Detect property management fees"
+
+tax_tracking:
+  negative_gearing_calculation: true
+  cgt_cost_base_tracking: true
+  cgt_discount_eligible: true
+  cgt_discount_holding_period: 365
+  depreciation_schedule_tracking: true
+
+alerts:
+  - type: rental_schedule_reminder
+    schedule: annual
+    before_date: "06-15"
+    message: "EOFY - prepare rental property income/expense schedule for tax return"
+
+  - type: cgt_event_reminder
+    trigger: property_sale_detected
+    message: "Property sale detected - calculate CGT on disposal"
+
+  - type: negative_gearing_summary
+    schedule: quarterly
+    message: "Quarterly negative gearing summary available"
+
+labels:
+  - name: "Tax Deductible"
+    description: "Property expense claimable on tax return"
+    color: "green"
+    auto_apply: false
+
+  - name: "Negative Gearing"
+    description: "Deductible loss against other income"
+    color: "darkgreen"
+    auto_apply: false
+
+  - name: "Capital Improvement"
+    description: "Adds to CGT cost base (not immediately deductible)"
+    color: "gold"
+    auto_apply: false
+
+  - name: "Repairs vs Improvements"
+    description: "Requires classification for tax treatment"
+    color: "orange"
+    auto_apply: false
+
+  - name: "Property: {address}"
+    description: "Expense for property at {address}"
+    color: "brown"
+    auto_apply: false
+    requires_configuration: true
+    configuration_prompt: "Enter property address:"
+
+dependencies:
+  requires: []
+  conflicts_with: []
+
+metadata:
+  created: "2025-11-22"
+  version: "1.0.0"
+  author: "Agent Smith"
+  priority: 3
--- a/skills/agent-smith/assets/templates/additional/share-investor.yaml
+++ b/skills/agent-smith/assets/templates/additional/share-investor.yaml
@@ -0,0 +1,103 @@
+name: Share/ETF Investor
+layer: additional
+description: |
+  Share and ETF portfolio tracking with dividend income and CGT events.
+  Includes franking credit extraction and wash sale detection.
+
+categories:
+  - name: "Dividends:Franked"
+    parent: null
+    description: "Fully franked dividend income"
+
+  - name: "Dividends:Unfranked"
+    parent: null
+    description: "Unfranked dividend income"
+
+  - name: "Share Sales"
+    parent: null
+    description: "Capital gains/losses from share sales"
+
+  - name: "Brokerage Fees"
+    parent: null
+    description: "Trading and brokerage fees"
+
+rules:
+  - id: franked-dividends
+    pattern: "dividend.*franked|franking.*credit|DRP|dividend.*reinvestment"
+    category: "Dividends:Franked"
+    confidence: high
+    labels: ["Franked Dividend"]
+    description: "Detect franked dividend payments"
+
+  - id: unfranked-dividends
+    pattern: "dividend.*unfranked|distribution.*trust"
+    category: "Dividends:Unfranked"
+    confidence: high
+    description: "Detect unfranked dividend payments"
+
+  - id: share-sale
+    pattern: "share.*sale|stock.*sale|sold.*shares|CGT.*event"
+    category: "Share Sales"
+    confidence: medium
+    labels: ["Capital Gain"]
+    description: "Detect share sale transactions (CGT event)"
+
+  - id: brokerage
+    pattern: "CommSec|SelfWealth|Stake|brokerage|trading.*fee"
+    category: "Brokerage Fees"
+    confidence: high
+    labels: ["Tax Deductible"]
+    description: "Detect brokerage and trading fees"
+
+tax_tracking:
+  dividend_tracking: true
+  franking_credit_extraction: true
+  cgt_tracking: true
+  cgt_discount_eligible: true
+  cgt_discount_holding_period: 365
+  wash_sale_detection: true
+  wash_sale_period: 30
+
+alerts:
+  - type: dividend_income_summary
+    schedule: quarterly
+    message: "Quarterly dividend income summary with franking credits"
+
+  - type: cgt_event_detected
+    trigger: share_sale_detected
+    message: "Share sale detected - track CGT event and holding period"
+
+  - type: wash_sale_warning
+    trigger: repurchase_within_30_days
+    message: "Warning: Share repurchased within 30 days - potential wash sale"
+
+labels:
+  - name: "Tax Deductible"
+    description: "Share trading expense claimable"
+    color: "green"
+    auto_apply: false
+
+  - name: "Capital Gain"
+    description: "Capital gains event (CGT applicable)"
+    color: "gold"
+    auto_apply: true
+
+  - name: "Capital Loss"
+    description: "Capital loss (offset against gains)"
+    color: "brown"
+    auto_apply: false
+
+  - name: "Franked Dividend"
+    description: "Dividend with franking credits attached"
+    color: "teal"
+    auto_apply: true
+
+dependencies:
+  requires: []
+  conflicts_with: []
+
+metadata:
+  created: "2025-11-22"
+  version: "1.0.0"
+  author: "Agent Smith"
+  priority: 3
--- a/skills/agent-smith/assets/templates/archive/comprehensive.yaml.archived
+++ b/skills/agent-smith/assets/templates/archive/comprehensive.yaml.archived
@@ -0,0 +1,832 @@
+name: Comprehensive Foundation
+layer: foundation
+description: |
+  Detailed category structure with deep hierarchies for granular tracking.
+  Best for detail-oriented people, business owners, or those optimizing tax deductions.
+
+  80+ categories with 2-3 levels of hierarchy for precise expense tracking.
+
+categories:
+  # ============================================================
+  # INCOME
+  # ============================================================
+  - name: "Income"
+    parent: null
+    description: "All income sources"
+
+  - name: "Income:Employment"
+    parent: "Income"
+    description: "Employment income"
+
+  - name: "Income:Employment:Salary & Wages"
+    parent: "Income:Employment"
+    description: "Regular salary and wage payments"
+
+  - name: "Income:Employment:Bonuses & Commissions"
+    parent: "Income:Employment"
+    description: "Performance bonuses, sales commissions"
+
+  - name: "Income:Employment:Allowances"
+    parent: "Income:Employment"
+    description: "Travel allowance, car allowance, other"
+
+  - name: "Income:Government Benefits"
+    parent: "Income"
+    description: "Centrelink and government payments"
+
+  - name: "Income:Government Benefits:Family Benefits"
+    parent: "Income:Government Benefits"
+    description: "Family Tax Benefit, Child Care Subsidy"
+
+  - name: "Income:Government Benefits:Income Support"
+    parent: "Income:Government Benefits"
+    description: "JobSeeker, Disability Support, Age Pension"
+
+  - name: "Income:Government Benefits:Child Support"
+    parent: "Income:Government Benefits"
+    description: "Child support received"
+
+  - name: "Income:Other Income"
+    parent: "Income"
+    description: "Miscellaneous income"
+
+  - name: "Income:Other Income:Tax Refunds"
+    parent: "Income:Other Income"
+    description: "ATO tax refunds, GST refunds"
+
+  - name: "Income:Other Income:Gifts & Winnings"
+    parent: "Income:Other Income"
+    description: "Cash gifts, competition winnings, lottery"
+
+  - name: "Income:Other Income:Reimbursements"
+    parent: "Income:Other Income"
+    description: "Work reimbursements, refunds"
+
+  # ============================================================
+  # HOUSING
+  # ============================================================
+  - name: "Housing"
+    parent: null
+    description: "Home-related expenses"
+
+  - name: "Housing:Rent or Mortgage"
+    parent: "Housing"
+    description: "Rent or mortgage payments"
+
+  - name: "Housing:Rent or Mortgage:Rent"
+    parent: "Housing:Rent or Mortgage"
+    description: "Rental payments"
+
+  - name: "Housing:Rent or Mortgage:Mortgage Repayments"
+    parent: "Housing:Rent or Mortgage"
+    description: "Principal and interest payments"
+
+  - name: "Housing:Rates & Levies"
+    parent: "Housing"
+    description: "Government and strata charges"
+
+  - name: "Housing:Rates & Levies:Council Rates"
+    parent: "Housing:Rates & Levies"
+    description: "Municipal council rates"
+
+  - name: "Housing:Rates & Levies:Water Rates"
+    parent: "Housing:Rates & Levies"
+    description: "Water service charges"
+
+  - name: "Housing:Rates & Levies:Strata Levies"
+    parent: "Housing:Rates & Levies"
+    description: "Body corporate, strata fees"
+
+  - name: "Housing:Maintenance & Repairs"
+    parent: "Housing"
+    description: "Home maintenance costs"
+
+  - name: "Housing:Maintenance & Repairs:Repairs"
+    parent: "Housing:Maintenance & Repairs"
+    description: "Plumbing, electrical, emergency repairs"
+
+  - name: "Housing:Maintenance & Repairs:Improvements"
+    parent: "Housing:Maintenance & Repairs"
+    description: "Renovations, upgrades, capital improvements"
+
+  - name: "Housing:Maintenance & Repairs:Garden & Lawn"
+    parent: "Housing:Maintenance & Repairs"
+    description: "Gardening, lawn care, landscaping"
+
+  - name: "Housing:Home Insurance"
+    parent: "Housing"
+    description: "Home and contents insurance"
+
+  - name: "Housing:Furnishings"
+    parent: "Housing"
+    description: "Furniture, appliances, home setup"
+
+  # ============================================================
+  # UTILITIES
+  # ============================================================
+  - name: "Utilities"
+    parent: null
+    description: "Essential household services"
+
+  - name: "Utilities:Electricity"
+    parent: "Utilities"
+    description: "Electricity bills and charges"
+
+  - name: "Utilities:Gas"
+    parent: "Utilities"
+    description: "Natural gas, LPG"
+
+  - name: "Utilities:Water"
+    parent: "Utilities"
+    description: "Water usage charges"
+
+  - name: "Utilities:Internet"
+    parent: "Utilities"
+    description: "Home internet, NBN"
+
+  - name: "Utilities:Phone"
+    parent: "Utilities"
+    description: "Mobile and landline"
+
+  - name: "Utilities:Phone:Mobile"
+    parent: "Utilities:Phone"
+    description: "Mobile phone plans, prepaid"
+
+  - name: "Utilities:Phone:Landline"
+    parent: "Utilities:Phone"
+    description: "Home phone service"
+
+  # ============================================================
+  # FOOD & DINING
+  # ============================================================
+  - name: "Food & Dining"
+    parent: null
+    description: "Food and beverage expenses"
+
+  - name: "Food & Dining:Groceries"
+    parent: "Food & Dining"
+    description: "Food shopping"
+
+  - name: "Food & Dining:Groceries:Supermarket"
+    parent: "Food & Dining:Groceries"
+    description: "Woolworths, Coles, Aldi, IGA"
+
+  - name: "Food & Dining:Groceries:Specialty Stores"
+    parent: "Food & Dining:Groceries"
+    description: "Butcher, baker, deli, fruit shop"
+
+  - name: "Food & Dining:Groceries:Online Delivery"
+    parent: "Food & Dining:Groceries"
+    description: "Online grocery delivery services"
+
+  - name: "Food & Dining:Restaurants"
+    parent: "Food & Dining"
+    description: "Dining out"
+
+  - name: "Food & Dining:Takeaway & Delivery"
+    parent: "Food & Dining"
+    description: "Takeaway food"
+
+  - name: "Food & Dining:Takeaway & Delivery:Fast Food"
+    parent: "Food & Dining:Takeaway & Delivery"
+    description: "McDonald's, KFC, etc."
+
+  - name: "Food & Dining:Takeaway & Delivery:Food Delivery"
+    parent: "Food & Dining:Takeaway & Delivery"
+    description: "Uber Eats, Menulog, DoorDash"
+
+  - name: "Food & Dining:Coffee & Cafes"
+    parent: "Food & Dining"
+    description: "Coffee shops, cafe visits"
+
+  - name: "Food & Dining:Alcohol & Beverages"
+    parent: "Food & Dining"
+    description: "Bottleshops, liquor, soft drinks"
+
+  # ============================================================
+  # TRANSPORTATION
+  # ============================================================
+  - name: "Transportation"
+    parent: null
+    description: "Transport and vehicle expenses"
+
+  - name: "Transportation:Vehicle Ownership"
+    parent: "Transportation"
+    description: "Owning and running a vehicle"
+
+  - name: "Transportation:Vehicle Ownership:Fuel"
+    parent: "Transportation:Vehicle Ownership"
+    description: "Petrol, diesel, LPG"
+
+  - name: "Transportation:Vehicle Ownership:Maintenance & Servicing"
+    parent: "Transportation:Vehicle Ownership"
+    description: "Regular servicing, oil changes"
+
+  - name: "Transportation:Vehicle Ownership:Repairs"
+    parent: "Transportation:Vehicle Ownership"
+    description: "Breakdowns, accident repairs, tyres"
+
+  - name: "Transportation:Vehicle Ownership:Registration & Insurance"
+    parent: "Transportation:Vehicle Ownership"
+    description: "Rego, CTP, comprehensive insurance"
+
+  - name: "Transportation:Vehicle Ownership:Car Wash & Detailing"
+    parent: "Transportation:Vehicle Ownership"
+    description: "Cleaning, detailing, car care"
+
+  - name: "Transportation:Parking & Tolls"
+    parent: "Transportation"
+    description: "Parking and road tolls"
+
+  - name: "Transportation:Parking & Tolls:Parking"
+    parent: "Transportation:Parking & Tolls"
+    description: "Street parking, parking meters, car parks"
+
+  - name: "Transportation:Parking & Tolls:Tolls"
+    parent: "Transportation:Parking & Tolls"
+    description: "E-tag, toll roads, M1, M2, etc."
+
+  - name: "Transportation:Public Transport"
+    parent: "Transportation"
+    description: "Buses, trains, trams, ferries"
+
+  - name: "Transportation:Public Transport:Opal/Myki Card"
+    parent: "Transportation:Public Transport"
+    description: "Prepaid transport cards"
+
+  - name: "Transportation:Public Transport:Tickets"
+    parent: "Transportation:Public Transport"
+    description: "Single tickets, day passes"
+
+  - name: "Transportation:Rideshare & Taxis"
+    parent: "Transportation"
+    description: "Uber, Didi, taxis"
+
+  # ============================================================
+  # HEALTHCARE
+  # ============================================================
+  - name: "Healthcare"
+    parent: null
+    description: "Medical and health expenses"
+
+  - name: "Healthcare:Medical Services"
+    parent: "Healthcare"
+    description: "Doctor visits and medical care"
+
+  - name: "Healthcare:Medical Services:GP & Specialists"
+    parent: "Healthcare:Medical Services"
+    description: "General practitioner, specialist doctors"
+
+  - name: "Healthcare:Medical Services:Tests & Pathology"
+    parent: "Healthcare:Medical Services"
+    description: "Blood tests, x-rays, scans, pathology"
+
+  - name: "Healthcare:Medical Services:Hospital & Emergency"
+    parent: "Healthcare:Medical Services"
+    description: "Hospital visits, emergency care, ambulance"
+
+  - name: "Healthcare:Dental"
+    parent: "Healthcare"
+    description: "Dental care"
+
+  - name: "Healthcare:Dental:General Dental"
+    parent: "Healthcare:Dental"
+    description: "Check-ups, cleaning, fillings"
+
+  - name: "Healthcare:Dental:Orthodontics"
+    parent: "Healthcare:Dental"
+    description: "Braces, Invisalign, orthodontic treatment"
+
+  - name: "Healthcare:Pharmacy"
+    parent: "Healthcare"
+    description: "Pharmacy and medications"
+
+  - name: "Healthcare:Pharmacy:Prescriptions"
+    parent: "Healthcare:Pharmacy"
+    description: "PBS prescriptions, scripts"
+
+  - name: "Healthcare:Pharmacy:Over the Counter"
+    parent: "Healthcare:Pharmacy"
+    description: "Non-prescription medicines, first aid"
+
+  - name: "Healthcare:Allied Health"
+    parent: "Healthcare"
+    description: "Other health services"
+
+  - name: "Healthcare:Allied Health:Physiotherapy"
+    parent: "Healthcare:Allied Health"
+    description: "Physio, exercise physiology"
+
+  - name: "Healthcare:Allied Health:Psychology & Counselling"
+    parent: "Healthcare:Allied Health"
+    description: "Psychologist, counsellor, mental health"
+
+  - name: "Healthcare:Allied Health:Other Therapies"
+    parent: "Healthcare:Allied Health"
+    description: "Chiro, osteo, massage, acupuncture"
+
+  - name: "Healthcare:Optical"
+    parent: "Healthcare"
+    description: "Eye care, glasses, contacts"
+
+  - name: "Healthcare:Health Insurance"
+    parent: "Healthcare"
+    description: "Private health insurance premiums"
+
+  # ============================================================
+  # PERSONAL CARE & APPEARANCE
+  # ============================================================
+  - name: "Personal Care"
+    parent: null
+    description: "Personal grooming and care"
+
+  - name: "Personal Care:Hair & Beauty"
+    parent: "Personal Care"
+    description: "Hair and beauty services"
+
+  - name: "Personal Care:Hair & Beauty:Haircuts & Styling"
+    parent: "Personal Care:Hair & Beauty"
+    description: "Barber, hairdresser, hair treatments"
+
+  - name: "Personal Care:Hair & Beauty:Beauty Services"
+    parent: "Personal Care:Hair & Beauty"
+    description: "Nails, waxing, facials, beauty treatments"
+
+  - name: "Personal Care:Toiletries & Cosmetics"
+    parent: "Personal Care"
+    description: "Personal hygiene products"
+
+  - name: "Personal Care:Toiletries & Cosmetics:Skincare & Cosmetics"
+    parent: "Personal Care:Toiletries & Cosmetics"
+    description: "Makeup, skincare, fragrances"
+
+  - name: "Personal Care:Toiletries & Cosmetics:Personal Hygiene"
+    parent: "Personal Care:Toiletries & Cosmetics"
+    description: "Shampoo, soap, deodorant, dental care"
+
+  - name: "Clothing & Footwear"
+    parent: null
+    description: "Clothes and shoes"
+
+  - name: "Clothing & Footwear:Adults"
+    parent: "Clothing & Footwear"
+    description: "Adult clothing and shoes"
+
+  - name: "Clothing & Footwear:Kids"
+    parent: "Clothing & Footwear"
+    description: "Children's clothing and shoes"
+
+  - name: "Clothing & Footwear:Accessories"
+    parent: "Clothing & Footwear"
+    description: "Bags, wallets, jewellery, watches"
+
+  # ============================================================
+  # ENTERTAINMENT & RECREATION
+  # ============================================================
+  - name: "Entertainment & Recreation"
+    parent: null
+    description: "Entertainment and leisure"
+
+  - name: "Entertainment & Recreation:Subscriptions"
+    parent: "Entertainment & Recreation"
+    description: "Streaming and digital services"
+
+  - name: "Entertainment & Recreation:Subscriptions:Streaming Video"
+    parent: "Entertainment & Recreation:Subscriptions"
+    description: "Netflix, Stan, Disney+, Binge"
+
+  - name: "Entertainment & Recreation:Subscriptions:Streaming Music"
+    parent: "Entertainment & Recreation:Subscriptions"
+    description: "Spotify, Apple Music, YouTube Music"
+
+  - name: "Entertainment & Recreation:Subscriptions:Gaming"
+    parent: "Entertainment & Recreation:Subscriptions"
+    description: "PlayStation Plus, Xbox Game Pass, etc."
+
+  - name: "Entertainment & Recreation:Subscriptions:News & Publications"
+    parent: "Entertainment & Recreation:Subscriptions"
+    description: "Newspapers, magazines, digital subscriptions"
+
+  - name: "Entertainment & Recreation:Fitness & Sport"
+    parent: "Entertainment & Recreation"
+    description: "Fitness and sports activities"
+
+  - name: "Entertainment & Recreation:Fitness & Sport:Gym Membership"
+    parent: "Entertainment & Recreation:Fitness & Sport"
+    description: "Gym, fitness classes, personal training"
+
+  - name: "Entertainment & Recreation:Fitness & Sport:Sports & Activities"
+    parent: "Entertainment & Recreation:Fitness & Sport"
+    description: "Sports clubs, equipment, registration fees"
+
+  - name: "Entertainment & Recreation:Events & Outings"
+    parent: "Entertainment & Recreation"
+    description: "Events and activities"
+
+  - name: "Entertainment & Recreation:Events & Outings:Movies & Cinema"
+    parent: "Entertainment & Recreation:Events & Outings"
+    description: "Movie tickets, cinema"
+
+  - name: "Entertainment & Recreation:Events & Outings:Concerts & Theatre"
+    parent: "Entertainment & Recreation:Events & Outings"
+    description: "Live music, theatre, performances"
+
+  - name: "Entertainment & Recreation:Events & Outings:Sports Events"
+    parent: "Entertainment & Recreation:Events & Outings"
+    description: "AFL, NRL, cricket, sports tickets"
+
+  - name: "Entertainment & Recreation:Hobbies"
+    parent: "Entertainment & Recreation"
+    description: "Hobby-related expenses"
+
+  - name: "Entertainment & Recreation:Books & Media"
+    parent: "Entertainment & Recreation"
+    description: "Books, audiobooks, magazines, DVDs"
+
+  - name: "Entertainment & Recreation:Gaming"
+    parent: "Entertainment & Recreation"
+    description: "Video games, board games, gaming gear"
+
+  # ============================================================
+  # EDUCATION & DEVELOPMENT
+  # ============================================================
+  - name: "Education"
+    parent: null
+    description: "Education and learning"
+
+  - name: "Education:School"
+    parent: "Education"
+    description: "Primary and secondary school"
+
+  - name: "Education:School:School Fees"
+    parent: "Education:School"
+    description: "Tuition fees, private school fees"
+
+  - name: "Education:School:School Uniforms"
+    parent: "Education:School"
+    description: "Uniforms, sports gear"
+
+  - name: "Education:School:Excursions & Activities"
+    parent: "Education:School"
+    description: "School camps, excursions, activities"
+
+  - name: "Education:Tertiary Education"
+    parent: "Education"
+    description: "University, TAFE, higher education"
+
+  - name: "Education:Tertiary Education:Tuition Fees"
+    parent: "Education:Tertiary Education"
+    description: "HECS, course fees, semester fees"
+
+  - name: "Education:Tertiary Education:Textbooks & Materials"
+    parent: "Education:Tertiary Education"
+    description: "Textbooks, course materials, stationery"
+
+  - name: "Education:Courses & Training"
+    parent: "Education"
+    description: "Professional development, short courses"
+
+  - name: "Education:Tutoring"
+    parent: "Education"
+    description: "Private tutoring, coaching"
+
+  # ============================================================
+  # KIDS & FAMILY
+  # ============================================================
+  - name: "Kids & Family"
+    parent: null
+    description: "Child-related expenses"
+
+  - name: "Kids & Family:Childcare & Education"
+    parent: "Kids & Family"
+    description: "Childcare services"
+
+  - name: "Kids & Family:Childcare & Education:Daycare"
+    parent: "Kids & Family:Childcare & Education"
+    description: "Long day care, family day care"
+
+  - name: "Kids & Family:Childcare & Education:Before/After School Care"
+    parent: "Kids & Family:Childcare & Education"
+    description: "OOSH, vacation care"
+
+  - name: "Kids & Family:Activities"
+    parent: "Kids & Family"
+    description: "Kids activities and sports"
+
+  - name: "Kids & Family:Activities:Sports"
+    parent: "Kids & Family:Activities"
+    description: "Kids sports, swimming lessons, team fees"
+
+  - name: "Kids & Family:Activities:Music & Arts"
+    parent: "Kids & Family:Activities"
+    description: "Music lessons, art classes, dance"
+
+  - name: "Kids & Family:Toys & Entertainment"
+    parent: "Kids & Family"
+    description: "Toys, games, kid entertainment"
+
+  - name: "Kids & Family:Baby Supplies"
+    parent: "Kids & Family"
+    description: "Nappies, formula, baby products"
+
+  - name: "Kids & Family:Pocket Money & Allowances"
+    parent: "Kids & Family"
+    description: "Kids pocket money, allowances"
+
+  # ============================================================
+  # FINANCIAL SERVICES
+  # ============================================================
+  - name: "Financial Services"
+    parent: null
+    description: "Banking and financial costs"
+
+  - name: "Financial Services:Bank Fees"
+    parent: "Financial Services"
+    description: "Banking fees and charges"
+
+  - name: "Financial Services:Bank Fees:Account Fees"
+    parent: "Financial Services:Bank Fees"
+    description: "Monthly account fees, transaction fees"
+
+  - name: "Financial Services:Bank Fees:ATM Fees"
+    parent: "Financial Services:Bank Fees"
+    description: "ATM withdrawal fees, foreign ATM fees"
+
+  - name: "Financial Services:Interest & Finance Charges"
+    parent: "Financial Services"
+    description: "Interest and finance costs"
+
+  - name: "Financial Services:Interest & Finance Charges:Credit Card Interest"
+    parent: "Financial Services:Interest & Finance Charges"
+    description: "Credit card interest charges"
+
+  - name: "Financial Services:Interest & Finance Charges:Loan Interest"
+    parent: "Financial Services:Interest & Finance Charges"
+    description: "Personal loan interest, other loan costs"
+
+  - name: "Financial Services:Accounting & Tax"
+    parent: "Financial Services"
+    description: "Accountant, tax agent, bookkeeping"
+
+  # ============================================================
+  # INSURANCE
+  # ============================================================
+  - name: "Insurance"
+    parent: null
+    description: "Insurance premiums (non-health, non-vehicle)"
+
+  - name: "Insurance:Life & Income Protection"
+    parent: "Insurance"
+    description: "Life insurance and income protection"
+
+  - name: "Insurance:Life & Income Protection:Life Insurance"
+    parent: "Insurance:Life & Income Protection"
+    description: "Life insurance premiums"
+
+  - name: "Insurance:Life & Income Protection:Income Protection"
+    parent: "Insurance:Life & Income Protection"
+    description: "Income protection, TPD, trauma insurance"
+
+  - name: "Insurance:Pet Insurance"
+    parent: "Insurance"
+    description: "Pet insurance premiums"
+
+  - name: "Insurance:Travel Insurance"
+    parent: "Insurance"
+    description: "Travel insurance, overseas coverage"
+
+  - name: "Insurance:Other Insurance"
+    parent: "Insurance"
+    description: "Other insurance policies"
+
+  # ============================================================
+  # SHOPPING & HOUSEHOLD
+  # ============================================================
+  - name: "Shopping"
+    parent: null
+    description: "General retail and household"
+
+  - name: "Shopping:Household Items"
+    parent: "Shopping"
+    description: "Household goods and supplies"
+
+  - name: "Shopping:Household Items:Furniture"
+    parent: "Shopping:Household Items"
+    description: "Furniture, beds, sofas, tables"
+
+  - name: "Shopping:Household Items:Appliances"
+    parent: "Shopping:Household Items"
+    description: "Fridges, washing machines, electronics"
+
+  - name: "Shopping:Household Items:Homewares"
+    parent: "Shopping:Household Items"
+    description: "Kitchen items, bedding, décor, storage"
+
+  - name: "Shopping:Household Items:Cleaning Supplies"
+    parent: "Shopping:Household Items"
+    description: "Cleaning products, laundry detergent"
+
+  - name: "Shopping:General Retail"
+    parent: "Shopping"
+    description: "Department stores and misc purchases"
+
+  - name: "Shopping:Electronics"
+    parent: "Shopping"
+    description: "Computers, phones, tablets, tech"
+
+  - name: "Shopping:Hardware & DIY"
+    parent: "Shopping"
+    description: "Bunnings, hardware, DIY supplies"
+
+  # ============================================================
+  # GIFTS & DONATIONS
+  # ============================================================
+  - name: "Gifts & Donations"
+    parent: null
+    description: "Gifts and charitable giving"
+
+  - name: "Gifts & Donations:Gifts"
+    parent: "Gifts & Donations"
+    description: "Birthday, Christmas, special occasion gifts"
+
+  - name: "Gifts & Donations:Charitable Donations"
+    parent: "Gifts & Donations"
+    description: "Charity donations, sponsorships"
+
+  # ============================================================
+  # PETS
+  # ============================================================
+  - name: "Pets"
+    parent: null
+    description: "Pet-related expenses"
+
+  - name: "Pets:Food & Supplies"
+    parent: "Pets"
+    description: "Pet food, litter, supplies"
+
+  - name: "Pets:Veterinary"
+    parent: "Pets"
+    description: "Vet visits, medications, surgery"
+
+  - name: "Pets:Grooming & Boarding"
+    parent: "Pets"
+    description: "Grooming, pet sitting, boarding kennels"
+
+  # ============================================================
+  # TRAVEL & HOLIDAYS
+  # ============================================================
+  - name: "Travel & Holidays"
+    parent: null
+    description: "Travel and holiday expenses"
+
+  - name: "Travel & Holidays:Accommodation"
+    parent: "Travel & Holidays"
+    description: "Hotels, Airbnb, holiday rentals"
+
+  - name: "Travel & Holidays:Flights & Transport"
+    parent: "Travel & Holidays"
+    description: "Airfares and transport"
+
+  - name: "Travel & Holidays:Flights & Transport:Airfares"
+    parent: "Travel & Holidays:Flights & Transport"
+    description: "Domestic and international flights"
+
+  - name: "Travel & Holidays:Flights & Transport:Car Hire"
+    parent: "Travel & Holidays:Flights & Transport"
+    description: "Rental cars, car hire"
+
+  - name: "Travel & Holidays:Activities & Tours"
+    parent: "Travel & Holidays"
+    description: "Tours, attractions, activities"
+
+  - name: "Travel & Holidays:Holiday Spending"
+    parent: "Travel & Holidays"
+    description: "Meals, shopping, misc while on holiday"
+
+  # ============================================================
+  # GOVERNMENT & ADMIN
+  # ============================================================
+  - name: "Government & Fees"
+    parent: null
+    description: "Government charges and official fees"
+
+  - name: "Government & Fees:Fines & Penalties"
+    parent: "Government & Fees"
+    description: "Fines and late fees"
+
+  - name: "Government & Fees:Fines & Penalties:Traffic Fines"
+    parent: "Government & Fees:Fines & Penalties"
+    description: "Speeding, parking, traffic infringements"
+
+  - name: "Government & Fees:Fines & Penalties:Other Fines"
+    parent: "Government & Fees:Fines & Penalties"
+    description: "Library fines, other penalties"
+
+  - name: "Government & Fees:Licences & Registration"
+    parent: "Government & Fees"
+    description: "Licences and registrations"
+
+  - name: "Government & Fees:Licences & Registration:Driver Licence"
+    parent: "Government & Fees:Licences & Registration"
+    description: "Licence renewal, learner's permit"
+
+  - name: "Government & Fees:Licences & Registration:Professional Registration"
+    parent: "Government & Fees:Licences & Registration"
+    description: "Trade licences, professional registrations"
+
+  - name: "Government & Fees:Legal & Professional"
+    parent: "Government & Fees"
+    description: "Legal fees, solicitors, conveyancing"
+
+  # ============================================================
+  # DEBT & SAVINGS
+  # ============================================================
+  - name: "Debt Payments"
+    parent: null
+    description: "Loan and debt repayments"
+
+  - name: "Debt Payments:Personal Loans"
+    parent: "Debt Payments"
+    description: "Personal loan repayments"
+
+  - name: "Debt Payments:Credit Cards"
+    parent: "Debt Payments"
+    description: "Credit card payments"
+
+  - name: "Debt Payments:BNPL"
+    parent: "Debt Payments"
+    description: "Afterpay, Zip Pay, buy now pay later"
+
+  - name: "Debt Payments:Other Debt"
+    parent: "Debt Payments"
+    description: "Other debt repayments"
+
+  # ============================================================
+  # TRANSFERS & OTHER
+  # ============================================================
+  - name: "Transfers & Adjustments"
+    parent: null
+    description: "Account transfers and movements"
+
+  - name: "Transfers & Adjustments:Savings Transfers"
+    parent: "Transfers & Adjustments"
+    description: "Transfers to savings accounts"
+
+  - name: "Transfers & Adjustments:Investment Contributions"
+    parent: "Transfers & Adjustments"
+    description: "Super contributions, shares, investments"
+
+  - name: "Transfers & Adjustments:Internal Transfers"
+    parent: "Transfers & Adjustments"
+    description: "Transfers between own accounts"
+
+  - name: "Uncategorised"
+    parent: null
+    description: "Transactions not yet categorised"
+
+rules:
+  # ============================================================
+  # COMMON GROCERY STORES (Australia)
+  # ============================================================
+  - type: category
+    name: Woolworths → Groceries
+    patterns: [Woolworths, WOOLWORTHS]
+    category: Food & Dining > Groceries
+    confidence: 95
+
+  - type: category
+    name: Coles → Groceries
+    patterns: [Coles, COLES]
+    category: Food & Dining > Groceries
+    confidence: 95
+
+  - type: category
+    name: Aldi → Groceries
+    patterns: [Aldi, ALDI]
+    category: Food & Dining > Groceries
+    confidence: 95
+
+  - type: category
+    name: IGA → Groceries
+    patterns: [IGA]
+    category: Food & Dining > Groceries
+    confidence: 95
+
+labels: []
+
+tax_tracking:
+  detailed_expense_tracking: true
+  receipt_tracking_enabled: true
+
+alerts: []
+
+dependencies:
+  requires: []
+  conflicts_with: ["minimal", "standard"]
+
+metadata:
+  created: "2025-11-23"
+  version: "1.0.0"
+  author: "Agent Smith"
+  priority: 0
+  category_count: 186
--- a/skills/agent-smith/assets/templates/archive/minimal.yaml.archived
+++ b/skills/agent-smith/assets/templates/archive/minimal.yaml.archived
@@ -0,0 +1,121 @@
+name: Minimal Foundation
+layer: foundation
+description: |
+  Simple, broad category structure for basic expense tracking.
+  Best for people who prefer simplicity and don't need detailed breakdowns.
+
+  20 top-level categories covering essential expense areas.
+
+categories:
+  # Income
+  - name: "Income"
+    parent: null
+    description: "All income sources"
+
+  # Housing & Home
+  - name: "Housing"
+    parent: null
+    description: "Rent, mortgage, rates, home expenses"
+
+  - name: "Utilities"
+    parent: null
+    description: "Electricity, gas, water, internet, phone"
+
+  # Food
+  - name: "Food & Dining"
+    parent: null
+    description: "Groceries, restaurants, takeaway"
+
+  # Transportation
+  - name: "Transportation"
+    parent: null
+    description: "Fuel, public transport, vehicle costs"
+
+  # Health
+  - name: "Healthcare"
+    parent: null
+    description: "Medical, dental, pharmacy, Medicare gap"
+
+  # Personal & Lifestyle
+  - name: "Personal Care"
+    parent: null
+    description: "Haircuts, cosmetics, toiletries"
+
+  - name: "Clothing"
+    parent: null
+    description: "Clothes, shoes, accessories"
+
+  - name: "Entertainment"
+    parent: null
+    description: "Movies, streaming, hobbies, recreation"
+
+  - name: "Education"
+    parent: null
+    description: "School fees, courses, textbooks"
+
+  # Financial
+  - name: "Insurance"
+    parent: null
+    description: "Health, car, home, life insurance"
+
+  - name: "Banking & Fees"
+    parent: null
+    description: "Bank fees, account charges, ATM fees"
+
+  - name: "Debt Payments"
+    parent: null
+    description: "Loan repayments, credit card payments"
+
+  # Discretionary
+  - name: "Shopping"
+    parent: null
+    description: "General retail, online shopping, household items"
+
+  - name: "Gifts & Donations"
+    parent: null
+    description: "Presents, charity donations"
+
+  - name: "Pets"
+    parent: null
+    description: "Pet food, vet, supplies"
+
+  # Special
+  - name: "Travel & Holidays"
+    parent: null
+    description: "Flights, accommodation, holiday expenses"
+
+  - name: "Subscriptions"
+    parent: null
+    description: "Streaming, memberships, recurring services"
+
+  # Other
+  - name: "Government & Fees"
+    parent: null
+    description: "Rates, fines, registration, licences"
+
+  - name: "Uncategorised"
+    parent: null
+    description: "Transactions not yet categorised"
+
+rules: []
+  # No rules in foundation - rules come from primary/living/additional templates
+
+labels: []
+  # No labels in foundation
+
+tax_tracking:
+  basic_expense_tracking: true
+
+alerts: []
+
+dependencies:
+  requires: []
+  conflicts_with: ["standard", "comprehensive"]
+  note: "Foundation templates are mutually exclusive - choose only one"
+
+metadata:
+  created: "2025-11-23"
+  version: "1.0.0"
+  author: "Agent Smith"
+  priority: 0  # Lowest priority - applied first
+  category_count: 20
--- a/skills/agent-smith/assets/templates/archive/single.yaml.archived
+++ b/skills/agent-smith/assets/templates/archive/single.yaml.archived
@@ -0,0 +1,65 @@
+name: Single Person
+layer: living
+description: |
+  Managing finances independently without shared household expenses.
+  Adds simple rules for common single-person expense patterns.
+
+  Note: Categories are provided by Foundation template. This template adds
+  only rules to help categorize common single-person expenses.
+
+categories: []
+  # No special categories needed - Foundation provides Housing, Utilities, Groceries, etc.
+  # Living templates add labels and rules, not categories.
+
+rules:
+  - id: rent-payment
+    pattern: "rent|rental.*payment|real.*estate"
+    category: "Rent/Mortgage"
+    confidence: high
+    description: "Detect rent payments"
+
+  - id: electricity-bill
+    pattern: "electricity|power.*bill|energy.*australia"
+    category: "Electricity"
+    confidence: high
+    description: "Detect electricity bills"
+
+  - id: gas-bill
+    pattern: "gas.*bill|natural.*gas"
+    category: "Gas"
+    confidence: high
+    description: "Detect gas bills"
+
+  - id: water-bill
+    pattern: "water.*bill|water.*rates"
+    category: "Water"
+    confidence: high
+    description: "Detect water bills"
+
+  - id: internet-phone
+    pattern: "internet|telstra|optus|vodafone|phone.*bill|mobile"
+    category: "Internet & Phone"
+    confidence: high
+    description: "Detect internet and phone bills"
+
+  - id: groceries
+    pattern: "woolworths|coles|aldi|iga|grocery"
+    category: "Groceries"
+    confidence: high
+    description: "Detect grocery shopping"
+
+tax_tracking: {}
+
+alerts: []
+
+labels: []
+
+dependencies:
+  requires: []
+  conflicts_with: ["shared-joint", "shared-hybrid", "separated-parents", "sharehouse"]
+
+metadata:
+  created: "2025-11-22"
+  version: "1.0.0"
+  author: "Agent Smith"
+  priority: 2
--- a/skills/agent-smith/assets/templates/archive/standard.yaml.archived
+++ b/skills/agent-smith/assets/templates/archive/standard.yaml.archived
@@ -0,0 +1,361 @@
+name: Standard Foundation
+layer: foundation
+description: |
+  Balanced category structure with 1-2 levels of hierarchy.
+  Best for most people - detailed enough for insights, simple enough to maintain.
+
+  45 categories with logical groupings for common Australian expenses.
+
+categories:
+  # ============================================================
+  # INCOME
+  # ============================================================
+  - name: "Income"
+    parent: null
+    description: "All income sources"
+
+  - name: "Income:Employment"
+    parent: "Income"
+    description: "Salary, wages, bonuses"
+
+  - name: "Income:Government Benefits"
+    parent: "Income"
+    description: "Centrelink, Family Tax Benefit, Child Support"
+
+  - name: "Income:Other"
+    parent: "Income"
+    description: "Gifts, refunds, miscellaneous income"
+
+  # ============================================================
+  # HOUSING
+  # ============================================================
+  - name: "Housing"
+    parent: null
+    description: "Home-related expenses"
+
+  - name: "Housing:Rent or Mortgage"
+    parent: "Housing"
+    description: "Rent payments or mortgage repayments"
+
+  - name: "Housing:Rates & Levies"
+    parent: "Housing"
+    description: "Council rates, water rates, strata levies"
+
+  - name: "Housing:Maintenance & Repairs"
+    parent: "Housing"
+    description: "Home repairs, maintenance, improvements"
+
+  - name: "Housing:Home Insurance"
+    parent: "Housing"
+    description: "Home and contents insurance"
+
+  # ============================================================
+  # UTILITIES
+  # ============================================================
+  - name: "Utilities"
+    parent: null
+    description: "Essential household services"
+
+  - name: "Utilities:Electricity"
+    parent: "Utilities"
+    description: "Electricity bills"
+
+  - name: "Utilities:Gas"
+    parent: "Utilities"
+    description: "Gas bills"
+
+  - name: "Utilities:Water"
+    parent: "Utilities"
+    description: "Water bills"
+
+  - name: "Utilities:Internet & Phone"
+    parent: "Utilities"
+    description: "Internet, mobile, landline"
+
+  # ============================================================
+  # FOOD & DINING
+  # ============================================================
+  - name: "Food & Dining"
+    parent: null
+    description: "Food and beverage expenses"
+
+  - name: "Food & Dining:Groceries"
+    parent: "Food & Dining"
+    description: "Supermarket, grocery shopping"
+
+  - name: "Food & Dining:Restaurants"
+    parent: "Food & Dining"
+    description: "Dining out, cafes"
+
+  - name: "Food & Dining:Takeaway & Delivery"
+    parent: "Food & Dining"
+    description: "Takeaway, food delivery services"
+
+  # ============================================================
+  # TRANSPORTATION
+  # ============================================================
+  - name: "Transportation"
+    parent: null
+    description: "Transport and vehicle expenses"
+
+  - name: "Transportation:Fuel"
+    parent: "Transportation"
+    description: "Petrol, diesel"
+
+  - name: "Transportation:Public Transport"
+    parent: "Transportation"
+    description: "Trains, buses, trams, ferries, Opal/Myki"
+
+  - name: "Transportation:Vehicle Maintenance"
+    parent: "Transportation"
+    description: "Repairs, servicing, tyres"
+
+  - name: "Transportation:Registration & Insurance"
+    parent: "Transportation"
+    description: "Rego, CTP, car insurance"
+
+  - name: "Transportation:Parking & Tolls"
+    parent: "Transportation"
+    description: "Parking fees, tolls, e-tags"
+
+  - name: "Transportation:Rideshare & Taxis"
+    parent: "Transportation"
+    description: "Uber, taxis, rideshare"
+
+  # ============================================================
+  # HEALTHCARE
+  # ============================================================
+  - name: "Healthcare"
+    parent: null
+    description: "Medical and health expenses"
+
+  - name: "Healthcare:Medical"
+    parent: "Healthcare"
+    description: "GP visits, specialists, Medicare gap"
+
+  - name: "Healthcare:Dental"
+    parent: "Healthcare"
+    description: "Dentist, orthodontist"
+
+  - name: "Healthcare:Pharmacy & Prescriptions"
+    parent: "Healthcare"
+    description: "Medications, pharmacy items, PBS"
+
+  - name: "Healthcare:Health Insurance"
+    parent: "Healthcare"
+    description: "Private health insurance premiums"
+
+  - name: "Healthcare:Other Health"
+    parent: "Healthcare"
+    description: "Physio, chiro, optical, allied health"
+
+  # ============================================================
+  # PERSONAL & LIFESTYLE
+  # ============================================================
+  - name: "Personal Care"
+    parent: null
+    description: "Personal grooming and care"
+
+  - name: "Personal Care:Hair & Beauty"
+    parent: "Personal Care"
+    description: "Haircuts, salons, beauty treatments"
+
+  - name: "Personal Care:Toiletries & Cosmetics"
+    parent: "Personal Care"
+    description: "Personal hygiene products, cosmetics"
+
+  - name: "Clothing & Footwear"
+    parent: null
+    description: "Clothes, shoes, accessories"
+
+  - name: "Entertainment & Recreation"
+    parent: null
+    description: "Entertainment, hobbies, recreation"
+
+  - name: "Entertainment & Recreation:Streaming & Subscriptions"
+    parent: "Entertainment & Recreation"
+    description: "Netflix, Spotify, Stan, gaming subscriptions"
+
+  - name: "Entertainment & Recreation:Hobbies & Activities"
+    parent: "Entertainment & Recreation"
+    description: "Sports, gym, clubs, hobbies"
+
+  - name: "Entertainment & Recreation:Events & Outings"
+    parent: "Entertainment & Recreation"
+    description: "Movies, concerts, sports events, activities"
+
+  # ============================================================
+  # EDUCATION & DEVELOPMENT
+  # ============================================================
+  - name: "Education"
+    parent: null
+    description: "Education expenses"
+
+  - name: "Education:School Fees & Costs"
+    parent: "Education"
+    description: "School fees, uniforms, excursions"
+
+  - name: "Education:Courses & Training"
+    parent: "Education"
+    description: "TAFE, uni, online courses, professional development"
+
+  - name: "Education:Books & Supplies"
+    parent: "Education"
+    description: "Textbooks, stationery, learning materials"
+
+  # ============================================================
+  # FINANCIAL
+  # ============================================================
+  - name: "Financial Services"
+    parent: null
+    description: "Banking, fees, and financial costs"
+
+  - name: "Financial Services:Bank Fees"
+    parent: "Financial Services"
+    description: "Account fees, ATM fees, transaction charges"
+
+  - name: "Financial Services:Interest & Charges"
+    parent: "Financial Services"
+    description: "Credit card interest, loan fees"
+
+  - name: "Insurance"
+    parent: null
+    description: "Insurance premiums (non-health, non-vehicle)"
+
+  - name: "Insurance:Life Insurance"
+    parent: "Insurance"
+    description: "Life, income protection, TPD"
+
+  - name: "Insurance:Other Insurance"
+    parent: "Insurance"
+    description: "Pet insurance, travel insurance, other"
+
+  # ============================================================
+  # DISCRETIONARY
+  # ============================================================
+  - name: "Shopping"
+    parent: null
+    description: "General retail and household items"
+
+  - name: "Shopping:Household Items"
+    parent: "Shopping"
+    description: "Furniture, appliances, homewares"
+
+  - name: "Shopping:General Retail"
+    parent: "Shopping"
+    description: "Department stores, online shopping, misc purchases"
+
+  - name: "Gifts & Donations"
+    parent: null
+    description: "Gifts and charitable giving"
+
+  - name: "Pets"
+    parent: null
+    description: "Pet food, vet, grooming, supplies"
+
+  # ============================================================
+  # TRAVEL
+  # ============================================================
+  - name: "Travel & Holidays"
+    parent: null
+    description: "Travel and holiday expenses"
+
+  - name: "Travel & Holidays:Accommodation"
+    parent: "Travel & Holidays"
+    description: "Hotels, Airbnb, holiday rentals"
+
+  - name: "Travel & Holidays:Flights & Transport"
+    parent: "Travel & Holidays"
+    description: "Airfares, car hire, transfers"
+
+  # ============================================================
+  # KIDS (if applicable)
+  # ============================================================
+  - name: "Kids & Family"
+    parent: null
+    description: "Child-related expenses"
+
+  - name: "Kids & Family:Childcare"
+    parent: "Kids & Family"
+    description: "Daycare, before/after school care, vacation care"
+
+  - name: "Kids & Family:Activities & Sports"
+    parent: "Kids & Family"
+    description: "Kids sports, music lessons, activities"
+
+  - name: "Kids & Family:Other Kid Expenses"
+    parent: "Kids & Family"
+    description: "Toys, birthday parties, kid-specific costs"
+
+  # ============================================================
+  # GOVERNMENT & ADMIN
+  # ============================================================
+  - name: "Government & Fees"
+    parent: null
+    description: "Government charges and official fees"
+
+  - name: "Government & Fees:Fines & Penalties"
+    parent: "Government & Fees"
+    description: "Traffic fines, parking fines, late fees"
+
+  - name: "Government & Fees:Licences & Registration"
+    parent: "Government & Fees"
+    description: "Driver licence, professional registrations"
+
+  # ============================================================
+  # OTHER
+  # ============================================================
+  - name: "Transfers & Adjustments"
+    parent: null
+    description: "Account transfers, savings, investments"
+
+  - name: "Uncategorised"
+    parent: null
+    description: "Transactions not yet categorised"
+
+rules:
+  # ============================================================
+  # COMMON GROCERY STORES (Australia)
+  # ============================================================
+  - type: category
+    name: Woolworths → Groceries
+    patterns: [Woolworths, WOOLWORTHS]
+    category: Food & Dining > Groceries
+    confidence: 95
+
+  - type: category
+    name: Coles → Groceries
+    patterns: [Coles, COLES]
+    category: Food & Dining > Groceries
+    confidence: 95
+
+  - type: category
+    name: Aldi → Groceries
+    patterns: [Aldi, ALDI]
+    category: Food & Dining > Groceries
+    confidence: 95
+
+  - type: category
+    name: IGA → Groceries
+    patterns: [IGA]
+    category: Food & Dining > Groceries
+    confidence: 95
+
+labels: []
+
+tax_tracking:
+  basic_expense_tracking: true
+
+alerts: []
+
+dependencies:
+  requires: []
+  conflicts_with: ["minimal", "comprehensive"]
+
+metadata:
+  created: "2025-11-23"
+  version: "1.0.0"
+  author: "Agent Smith"
+  priority: 0
+  category_count: 65
+  recommended: true
--- a/skills/agent-smith/assets/templates/foundation/personal-living.json
+++ b/skills/agent-smith/assets/templates/foundation/personal-living.json
@@ -0,0 +1,349 @@
+{
+  "name": "Foundation: Personal Living",
+  "description": "Core personal expense categories for everyday living, aligned with ATO guidance",
+  "layer": "foundation",
+  "priority": 0,
+  "applies_to": ["all"],
+  "ato_aligned": true,
+  "categories": [
+    {
+      "name": "Income",
+      "parent": null,
+      "description": "All income sources",
+      "ato_section": "Income"
+    },
+    {
+      "name": "Salary/Wages",
+      "parent": "Income",
+      "description": "Employment income from salary or wages",
+      "ato_section": "Item 1"
+    },
+    {
+      "name": "Other Income",
+      "parent": "Income",
+      "description": "Income not covered by other categories",
+      "ato_section": "Item 24"
+    },
+    {
+      "name": "Interest Income",
+      "parent": "Income",
+      "description": "Interest from bank accounts and investments",
+      "ato_section": "Item 10"
+    },
+    {
+      "name": "Food & Dining",
+      "parent": null,
+      "description": "Food and meal expenses"
+    },
+    {
+      "name": "Groceries",
+      "parent": "Food & Dining",
+      "description": "Supermarket and grocery shopping"
+    },
+    {
+      "name": "Restaurants",
+      "parent": "Food & Dining",
+      "description": "Dining out at restaurants"
+    },
+    {
+      "name": "Cafes & Takeaway",
+      "parent": "Food & Dining",
+      "description": "Coffee shops and takeaway food"
+    },
+    {
+      "name": "Housing & Utilities",
+      "parent": null,
+      "description": "Housing costs and utilities"
+    },
+    {
+      "name": "Rent/Mortgage",
+      "parent": "Housing & Utilities",
+      "description": "Rent or mortgage payments"
+    },
+    {
+      "name": "Electricity",
+      "parent": "Housing & Utilities",
+      "description": "Electricity bills"
+    },
+    {
+      "name": "Gas",
+      "parent": "Housing & Utilities",
+      "description": "Gas bills"
+    },
+    {
+      "name": "Water",
+      "parent": "Housing & Utilities",
+      "description": "Water bills"
+    },
+    {
+      "name": "Internet & Phone",
+      "parent": "Housing & Utilities",
+      "description": "Internet and phone services"
+    },
+    {
+      "name": "Home Maintenance",
+      "parent": "Housing & Utilities",
+      "description": "Repairs and maintenance for your home"
+    },
+    {
+      "name": "Transportation",
+      "parent": null,
+      "description": "Transport and vehicle expenses"
+    },
+    {
+      "name": "Fuel",
+      "parent": "Transportation",
+      "description": "Petrol and diesel for personal vehicles"
+    },
+    {
+      "name": "Public Transport",
+      "parent": "Transportation",
+      "description": "Buses, trains, trams, ferries"
+    },
+    {
+      "name": "Vehicle Registration",
+      "parent": "Transportation",
+      "description": "Vehicle registration and CTP insurance"
+    },
+    {
+      "name": "Vehicle Maintenance",
+      "parent": "Transportation",
+      "description": "Car servicing and repairs"
+    },
+    {
+      "name": "Parking & Tolls",
+      "parent": "Transportation",
+      "description": "Parking fees and road tolls"
+    },
+    {
+      "name": "Healthcare & Insurance",
+      "parent": null,
+      "description": "Medical expenses and insurance"
+    },
+    {
+      "name": "Medical",
+      "parent": "Healthcare & Insurance",
+      "description": "Doctor visits and medical expenses"
+    },
+    {
+      "name": "Dental",
+      "parent": "Healthcare & Insurance",
+      "description": "Dental care expenses"
+    },
+    {
+      "name": "Pharmacy",
+      "parent": "Healthcare & Insurance",
+      "description": "Prescription and over-the-counter medications"
+    },
+    {
+      "name": "Health Insurance",
+      "parent": "Healthcare & Insurance",
+      "description": "Private health insurance premiums"
+    },
+    {
+      "name": "Life Insurance",
+      "parent": "Healthcare & Insurance",
+      "description": "Life and income protection insurance"
+    },
+    {
+      "name": "Personal & Lifestyle",
+      "parent": null,
+      "description": "Personal care and lifestyle expenses"
+    },
+    {
+      "name": "Clothing & Footwear",
+      "parent": "Personal & Lifestyle",
+      "description": "Clothing and shoes for personal use"
+    },
+    {
+      "name": "Personal Care",
+      "parent": "Personal & Lifestyle",
+      "description": "Haircuts, cosmetics, toiletries"
+    },
+    {
+      "name": "Entertainment & Recreation",
+      "parent": "Personal & Lifestyle",
+      "description": "Entertainment, hobbies, and recreation"
+    },
+    {
+      "name": "Fitness & Wellness",
+      "parent": "Personal & Lifestyle",
+      "description": "Gym memberships, fitness activities, wellness"
+    },
+    {
+      "name": "Gifts & Donations",
+      "parent": "Personal & Lifestyle",
+      "description": "Gifts and charitable donations (donations may be tax deductible)",
+      "ato_section": "D9"
+    },
+    {
+      "name": "Shopping",
+      "parent": null,
+      "description": "Online shopping and retail purchases"
+    },
+    {
+      "name": "Online Services",
+      "parent": "Shopping",
+      "description": "Online payment services and digital purchases"
+    },
+    {
+      "name": "Banking & Fees",
+      "parent": null,
+      "description": "Banking fees and charges"
+    },
+    {
+      "name": "Bank Fees",
+      "parent": "Banking & Fees",
+      "description": "Account keeping fees and transaction fees"
+    },
+    {
+      "name": "Interest Charges",
+      "parent": "Banking & Fees",
+      "description": "Interest on personal loans and credit cards"
+    },
+    {
+      "name": "Transfers",
+      "parent": "Banking & Fees",
+      "description": "Transfers between accounts"
+    }
+  ],
+  "rules": [
+    {
+      "name": "groceries-supermarkets",
+      "payee_pattern": "woolworths|coles|aldi|iga|foodland|costco|harris farm|fruit market|drakes|supa.*iga|ritchies|foodworks|friendly grocer",
+      "category": "Groceries",
+      "confidence": 0.95
+    },
+    {
+      "name": "restaurants-dining",
+      "payee_pattern": "restaurant|bistro|steakhouse|italian|chinese|thai|indian|japanese|korean|vietnamese|cafe.*restaurant",
+      "category": "Restaurants",
+      "confidence": 0.90
+    },
+    {
+      "name": "cafes-coffee",
+      "payee_pattern": "cafe|coffee|starbucks|gloria jeans|mccafe|donut king|boost juice",
+      "category": "Cafes & Takeaway",
+      "confidence": 0.90
+    },
+    {
+      "name": "fast-food-takeaway",
+      "payee_pattern": "mcdonald|kfc|hungry jack|domino|pizza hut|subway|nando|red rooster|grill'd|guzman|schnitz",
+      "category": "Cafes & Takeaway",
+      "confidence": 0.95
+    },
+    {
+      "name": "fuel-petrol",
+      "payee_pattern": "shell|bp|caltex|ampol|7-eleven|united.*petrol|metro.*petrol|mobil|esso",
+      "category": "Fuel",
+      "confidence": 0.95
+    },
+    {
+      "name": "electricity-providers",
+      "payee_pattern": "agl|origin|energy australia|red energy|alinta|simply energy|powershop|momentum energy|click energy|sumo|dodo.*power|lumo|people.*energy|diamond.*energy",
+      "category": "Electricity",
+      "confidence": 0.95
+    },
+    {
+      "name": "gas-providers",
+      "payee_pattern": "agl.*gas|origin.*gas|energy australia.*gas|simply energy.*gas|sumo.*gas",
+      "category": "Gas",
+      "confidence": 0.90
+    },
+    {
+      "name": "water-providers",
+      "payee_pattern": "water.*corporation|sydney.*water|yarra.*valley.*water|sa.*water|icon.*water|unitywater|hunter.*water|city west.*water",
+      "category": "Water",
+      "confidence": 0.95
+    },
+    {
+      "name": "internet-telco",
+      "payee_pattern": "telstra|optus|vodafone|tpg|iinet|aussie.*broadband|dodo|belong|internode|southern.*phone|exetel|spintel|tangerine|superloop|mate.*communicate",
+      "category": "Internet & Phone",
+      "confidence": 0.95
+    },
+    {
+      "name": "public-transport",
+      "payee_pattern": "opal|myki|go card|translink|metro.*trains|bus.*service|citylink",
+      "category": "Public Transport",
+      "confidence": 0.95
+    },
+    {
+      "name": "parking-tolls",
+      "payee_pattern": "secure.*parking|wilson.*parking|toll|e-tag|linkt|citylink|eastlink|go via",
+      "category": "Parking & Tolls",
+      "confidence": 0.95
+    },
+    {
+      "name": "pharmacy-chemist",
+      "payee_pattern": "chemist|pharmacy|priceline|terry white|amcal|blooms|soul pattinson|discount.*drug",
+      "category": "Pharmacy",
+      "confidence": 0.95
+    },
+    {
+      "name": "health-insurance",
+      "payee_pattern": "bupa|medibank|hcf|nib|ahm|health.*fund|health.*insurance",
+      "category": "Health Insurance",
+      "confidence": 0.95
+    },
+    {
+      "name": "gym-fitness",
+      "payee_pattern": "gym|fitness|anytime.*fitness|goodlife|f45|jetts|snap.*fitness|crossfit|yoga|pilates",
+      "category": "Fitness & Wellness",
+      "confidence": 0.90
+    },
+    {
+      "name": "entertainment-streaming",
+      "payee_pattern": "netflix|spotify|disney|stan|amazon.*prime|apple.*music|youtube.*premium|paramount|binge",
+      "category": "Entertainment & Recreation",
+      "confidence": 0.95
+    },
+    {
+      "name": "entertainment-cinema",
+      "payee_pattern": "hoyts|event.*cinema|village.*cinema|reading.*cinema|movie.*ticket",
+      "category": "Entertainment & Recreation",
+      "confidence": 0.95
+    },
+    {
+      "name": "clothing-retail",
+      "payee_pattern": "myer|david jones|target|kmart|big w|uniqlo|h&m|zara|cotton on|rebel.*sport|nike|adidas",
+      "category": "Clothing & Footwear",
+      "confidence": 0.85
+    },
+    {
+      "name": "personal-care-services",
+      "payee_pattern": "hair.*salon|barber|hairdresser|beauty|nail.*salon|spa|massage",
+      "category": "Personal Care",
+      "confidence": 0.90
+    },
+    {
+      "name": "bank-fees",
+      "payee_pattern": "account.*fee|monthly.*fee|transaction.*fee|atm.*fee|overdraft.*fee|international.*transaction.*fee",
+      "category": "Bank Fees",
+      "confidence": 0.95
+    },
+    {
+      "name": "transfers-generic",
+      "payee_pattern": "transfer|bpay|osko",
+      "category": "Transfers",
+      "confidence": 0.80
+    },
+    {
+      "name": "paypal-generic",
+      "payee_pattern": "PAYPAL",
+      "category": "Online Services",
+      "confidence": 0.60,
+      "labels": ["$LABEL_GENERIC_PAYPAL"]
+    }
+  ],
+  "labels": [],
+  "name": "Foundation: Personal Living",
+  "layer": "foundation",
+  "metadata": {
+    "version": "1.0.0",
+    "priority": 0,
+    "created": "2025-11-25",
+    "ato_alignment": "2024-25 tax year",
+    "recommended_for": ["new_users", "migration_users"]
+  }
+}
--- a/skills/agent-smith/assets/templates/living/README.md
+++ b/skills/agent-smith/assets/templates/living/README.md
@@ -0,0 +1,15 @@
+# Living Arrangement Templates
+
+Choose ONE template that matches how you manage household finances.
+
+## Available Templates
+
+- `single.yaml` - Managing finances alone
+- `shared-joint.yaml` - Partner/spouse, pooled income, joint accounts
+- `shared-hybrid.yaml` - Some joint accounts, some separate
+- `separated-parents.yaml` - Child support, shared custody expenses
+- `sharehouse.yaml` - Splitting bills with roommates
+
+## YAML Schema
+
+Same structure as primary templates, with `layer: living`.
--- a/skills/agent-smith/assets/templates/living/separated-parents.yaml
+++ b/skills/agent-smith/assets/templates/living/separated-parents.yaml
@@ -0,0 +1,114 @@
+name: Separated/Divorced Parents
+layer: living
+description: |
+  Managing finances with child support obligations and shared custody expenses.
+  Tracks child-related spending for tax and legal documentation.
+
+categories: []
+  # No special categories needed - use standard expense categories
+  # Labels indicate child-related expenses and which parent paid
+
+rules:
+  - id: child-support-payment
+    pattern: "child.*support|CSA.*payment|maintenance.*payment"
+    # No category override - transactions should be categorized as Transfer or similar
+    confidence: high
+    description: "Label child support payments"
+    labels: ["Child Support", "Child Support Paid"]
+
+  - id: child-support-received
+    pattern: "child.*support.*received|CSA.*deposit"
+    # No category override - transactions should be categorized as Transfer or Income
+    confidence: high
+    description: "Label child support receipts"
+    labels: ["Child Support", "Child Support Received"]
+
+  - id: kids-activities
+    pattern: "sport|swimming|dance|music.*lessons|scouts|karate"
+    # No category override - use standard Entertainment/Recreation category
+    confidence: medium
+    description: "Label children's activity expenses"
+    labels: ["Kids Expense"]
+
+  - id: kids-medical
+    pattern: "pediatric|child.*doctor|dentist.*kids|orthodontist|therapy.*child"
+    # No category override - use standard Medical/Health category
+    confidence: medium
+    description: "Label children's medical expenses"
+    labels: ["Kids Expense", "Medical"]
+
+  - id: kids-education
+    pattern: "school.*fees|uniform.*school|textbook|excursion|tuckshop"
+    # No category override - use standard Education category
+    confidence: high
+    description: "Label education-related expenses"
+    labels: ["Kids Expense", "Education"]
+
+tax_tracking:
+  child_support_documentation: true
+  custody_expense_tracking: true
+
+alerts:
+  - type: child_support_reconciliation
+    schedule: monthly
+    message: "Reconcile child support payments and custody expenses"
+
+  - type: ato_documentation_reminder
+    schedule: annual
+    before_date: "06-15"
+    message: "EOFY - compile child-related expenses for tax return"
+
+labels:
+  - name: "Child Support"
+    description: "Child support payment or receipt"
+    color: "skyblue"
+    auto_apply: false
+
+  - name: "Custody Period"
+    description: "Expense during custody period"
+    color: "lightpurple"
+    auto_apply: false
+
+  - name: "Shared Child Expense"
+    description: "Child expense split with ex-partner"
+    color: "coral"
+    auto_apply: false
+
+  - name: "Contributor: {parent_a_name}"
+    description: "Paid by {parent_a_name}"
+    color: "orange"
+    auto_apply: false
+    requires_configuration: true
+    configuration_prompt: "Enter name for Parent A:"
+
+  - name: "Contributor: {parent_b_name}"
+    description: "Paid by {parent_b_name}"
+    color: "cyan"
+    auto_apply: false
+    requires_configuration: true
+    configuration_prompt: "Enter name for Parent B:"
+
+  - name: "Kids: {child_1_name}"
+    description: "Expense for {child_1_name}"
+    color: "pink"
+    auto_apply: false
+    requires_configuration: true
+    configuration_prompt: "Enter name for first child:"
+
+  - name: "Kids: {child_2_name}"
+    description: "Expense for {child_2_name}"
+    color: "lightgreen"
+    auto_apply: false
+    requires_configuration: true
+    configuration_prompt: "Enter name for second child:"
+
+dependencies:
+  requires: []
+  conflicts_with: ["single", "shared-joint", "sharehouse"]
+  # Note: Can be combined with shared-hybrid for divorced parents now living with new partner
+
+metadata:
+  created: "2025-11-22"
+  version: "1.0.0"
+  author: "Agent Smith"
+  priority: 2
--- a/skills/agent-smith/assets/templates/living/shared-hybrid.yaml
+++ b/skills/agent-smith/assets/templates/living/shared-hybrid.yaml
@@ -0,0 +1,73 @@
+name: Shared Household - Hybrid Finances
+layer: living
+description: |
+  Living with partner/spouse with mix of joint and separate accounts.
+  Some expenses shared (bills, groceries), some kept separate (personal spending).
+
+categories: []
+  # No special categories needed - use standard expense categories
+  # Account indicates if shared, labels indicate who paid
+
+rules:
+  - id: shared-expense-labeling
+    pattern: ".*"
+    # No category override - use existing categorization
+    # Just apply labels based on account and contributor
+    confidence: high
+    split_percentage: 50
+    description: "Label shared expenses with contributor info"
+    labels: ["Shared Expense"]
+
+tax_tracking:
+  expense_splitting_enabled: true
+  default_split_ratio: 0.5
+
+alerts:
+  - type: split_expense_reconciliation
+    schedule: monthly
+    message: "Time to reconcile shared expenses with partner"
+
+labels:
+  - name: "Shared Expense"
+    description: "Expense split with partner"
+    color: "purple"
+    auto_apply: false
+
+  - name: "Contributor: {partner_a_name}"
+    description: "Paid by {partner_a_name}"
+    color: "orange"
+    auto_apply: false
+    requires_configuration: true
+    configuration_prompt: "Enter name for Partner A:"
+
+  - name: "Contributor: {partner_b_name}"
+    description: "Paid by {partner_b_name}"
+    color: "cyan"
+    auto_apply: false
+    requires_configuration: true
+    configuration_prompt: "Enter name for Partner B:"
+
+  - name: "Personal: {partner_a_name}"
+    description: "{partner_a_name} personal spending"
+    color: "lightorange"
+    auto_apply: false
+    requires_configuration: true
+    configuration_prompt: "Enter name for Partner A:"
+
+  - name: "Personal: {partner_b_name}"
+    description: "{partner_b_name} personal spending"
+    color: "lightcyan"
+    auto_apply: false
+    requires_configuration: true
+    configuration_prompt: "Enter name for Partner B:"
+
+dependencies:
+  requires: []
+  conflicts_with: ["single", "shared-joint", "sharehouse"]
+  # Note: Can be combined with separated-parents for new relationships after divorce
+
+metadata:
+  created: "2025-11-22"
+  version: "1.0.0"
+  author: "Agent Smith"
+  priority: 2
--- a/skills/agent-smith/assets/templates/primary/README.md
+++ b/skills/agent-smith/assets/templates/primary/README.md
@@ -0,0 +1,51 @@
+# Primary Income Templates
+
+Choose ONE template that matches your main source of income.
+
+## Available Templates
+
+- `payg-employee.yaml` - Salary/wage earner
+- `sole-trader.yaml` - ABN holder, contractor, quarterly BAS
+- `small-business.yaml` - Business owner with employees
+- `retiree.yaml` - Superannuation/pension income
+- `student.yaml` - Minimal income, government payments, HECS
+
+## YAML Schema
+
+```yaml
+name: Template Name
+layer: primary
+description: |
+  Multi-line description of this template.
+
+categories:
+  - name: "Category Name"
+    parent: null  # or "Parent Category Name"
+    description: "Category purpose"
+
+rules:
+  - id: unique-rule-id
+    pattern: "regex pattern"
+    category: "Target Category"
+    confidence: high|medium|low
+    description: "What this rule does"
+
+tax_tracking:
+  bas_enabled: true|false
+  gst_method: cash|accrual
+  # ... other tax config
+
+alerts:
+  - type: alert_type
+    schedule: quarterly|monthly
+    message: "Alert message"
+
+dependencies:
+  requires: []
+  conflicts_with: ["other-template-id"]
+
+metadata:
+  created: "YYYY-MM-DD"
+  version: "1.0.0"
+  priority: 1
+```
--- a/skills/agent-smith/assets/templates/primary/payg-employee.yaml
+++ b/skills/agent-smith/assets/templates/primary/payg-employee.yaml
@@ -0,0 +1,112 @@
+name: PAYG Employee
+layer: primary
+description: |
+  Salary or wage earner with tax withheld by employer.
+  Suitable for standard employment situations with work-related expense deductions.
+
+categories:
+  - name: "Salary/Wages"
+    parent: null
+    description: "Employment income from salary or wages"
+
+  - name: "PAYG Tax Withheld"
+    parent: null
+    description: "Tax withheld from salary by employer"
+
+  - name: "Work Expenses"
+    parent: null
+    description: "Work-related expenses that may be tax deductible"
+
+  - name: "Work Expenses:Uniforms"
+    parent: "Work Expenses"
+    description: "Uniforms, protective clothing, laundry"
+
+  - name: "Work Expenses:Tools & Equipment"
+    parent: "Work Expenses"
+    description: "Tools and equipment required for work"
+
+  - name: "Work Expenses:Vehicle"
+    parent: "Work Expenses"
+    description: "Vehicle expenses for work travel (excl. commuting)"
+
+  - name: "Work Expenses:Self-Education"
+    parent: "Work Expenses"
+    description: "Study directly related to current employment"
+
+labels:
+  - name: "Tax Deductible"
+    description: "Work-related expense claimable on tax return"
+    color: "green"
+    auto_apply: false
+
+  - name: "Requires Receipt"
+    description: "Receipt required for ATO substantiation"
+    color: "yellow"
+    auto_apply: false
+
+  - name: "Work Expense"
+    description: "Work-related expense"
+    color: "purple"
+    auto_apply: true
+
+rules:
+  - id: salary-payment
+    pattern: "salary|wage.*payment|payroll|fortnightly.*pay"
+    category: "Salary/Wages"
+    confidence: high
+    description: "Detect regular salary/wage payments"
+
+  - id: payg-tax
+    pattern: "PAYG.*tax|tax.*withheld|ATO.*payment"
+    category: "PAYG Tax Withheld"
+    confidence: high
+    description: "Detect PAYG tax withholding"
+
+  - id: uniform-expense
+    pattern: "uniform|workwear|protective.*clothing|laundry.*work"
+    category: "Work Expenses:Uniforms"
+    confidence: medium
+    description: "Detect uniform and protective clothing expenses"
+    labels: ["Tax Deductible", "Work Expense"]
+
+  - id: work-tools
+    pattern: "tools?|equipment|laptop.*work|computer.*work"
+    category: "Work Expenses:Tools & Equipment"
+    confidence: medium
+    description: "Detect work tool and equipment purchases"
+    labels: ["Tax Deductible", "Requires Receipt", "Work Expense"]
+
+  - id: work-vehicle
+    pattern: "fuel.*work|parking.*work|tolls.*work|uber.*work"
+    category: "Work Expenses:Vehicle"
+    confidence: low
+    description: "Detect work-related vehicle expenses (requires verification)"
+    labels: ["Tax Deductible", "Requires Receipt", "Work Expense"]
+
+tax_tracking:
+  bas_enabled: false
+  payment_summary_reconciliation: true
+  work_expense_threshold: 300
+  logbook_required: false
+
+alerts:
+  - type: work_expense_threshold
+    trigger: annual_total_exceeds
+    threshold: 300
+    category: "Work Expenses"
+    message: "Work expenses exceed $300 - ensure you have receipts for all claims"
+
+  - type: eofy_reminder
+    schedule: annual
+    before_date: "06-15"
+    message: "EOFY approaching - gather payment summary and work expense receipts"
+
+dependencies:
+  requires: []
+  conflicts_with: ["sole-trader", "small-business"]
+
+metadata:
+  created: "2025-11-22"
+  version: "1.0.0"
+  author: "Agent Smith"
+  priority: 1
--- a/skills/agent-smith/assets/templates/primary/sole-trader.yaml
+++ b/skills/agent-smith/assets/templates/primary/sole-trader.yaml
@@ -0,0 +1,141 @@
+name: Sole Trader / Contractor
+layer: primary
+description: |
+  ABN holder running a business as a sole trader or independent contractor.
+  Includes quarterly BAS obligations and GST tracking.
+
+categories:
+  - name: "Business Income"
+    parent: null
+    description: "Income from ABN-related business activities"
+
+  - name: "Business Expenses"
+    parent: null
+    description: "Tax-deductible business expenses"
+
+  - name: "Business Expenses:Office Supplies"
+    parent: "Business Expenses"
+    description: "Stationery, software, subscriptions"
+
+  - name: "Business Expenses:Travel"
+    parent: "Business Expenses"
+    description: "Business travel and accommodation"
+
+  - name: "Business Expenses:Home Office"
+    parent: "Business Expenses"
+    description: "Home office expenses (percentage allocation)"
+
+  - name: "Business Expenses:Professional Development"
+    parent: "Business Expenses"
+    description: "Training, courses, professional memberships"
+
+  - name: "Business Expenses:Marketing"
+    parent: "Business Expenses"
+    description: "Advertising, website, business cards"
+
+  - name: "GST Collected"
+    parent: "Business Income"
+    description: "GST component of business income"
+
+  - name: "GST Paid"
+    parent: "Business Expenses"
+    description: "GST component of business expenses"
+
+labels:
+  - name: "Tax Deductible"
+    description: "Business expense claimable on tax return"
+    color: "green"
+    auto_apply: false
+
+  - name: "GST Applicable"
+    description: "Includes GST component for BAS"
+    color: "blue"
+    auto_apply: true
+
+  - name: "Business Use"
+    description: "Business-related expense or income"
+    color: "purple"
+    auto_apply: true
+
+  - name: "Home Office"
+    description: "Home office percentage claim"
+    color: "brown"
+    auto_apply: false
+
+  - name: "Input Tax Credit"
+    description: "Eligible for GST credit on BAS"
+    color: "darkblue"
+    auto_apply: false
+
+rules:
+  - id: abn-payment-detection
+    pattern: "ABN.*payment|invoice.*paid|client.*payment|contractor.*payment"
+    category: "Business Income"
+    confidence: high
+    description: "Detect ABN payments from clients"
+    labels: ["Business Use", "GST Applicable"]
+
+  - id: home-office-percentage
+    pattern: "electricity|internet|rent|mortgage.*interest"
+    category: "Business Expenses:Home Office"
+    confidence: medium
+    percentage: 20
+    description: "Allocate home expenses to business use"
+    requires_user_confirmation: true
+    labels: ["Tax Deductible", "Business Use", "Home Office"]
+
+  - id: office-supplies
+    pattern: "officeworks|staples|adobe|microsoft.*365|canva|software"
+    category: "Business Expenses:Office Supplies"
+    confidence: high
+    description: "Detect office supply and software purchases"
+    labels: ["Tax Deductible", "Business Use", "GST Applicable"]
+
+  - id: professional-development
+    pattern: "course|training|conference|webinar|udemy|coursera|linkedin.*learning"
+    category: "Business Expenses:Professional Development"
+    confidence: medium
+    description: "Detect professional development expenses"
+    labels: ["Tax Deductible", "Business Use", "GST Applicable"]
+
+  - id: marketing-expense
+    pattern: "google.*ads|facebook.*ads|instagram.*ads|domain.*registration|web.*hosting|vistaprint"
+    category: "Business Expenses:Marketing"
+    confidence: high
+    description: "Detect marketing and advertising expenses"
+    labels: ["Tax Deductible", "Business Use", "GST Applicable"]
+
+tax_tracking:
+  bas_enabled: true
+  bas_frequency: quarterly
+  gst_method: cash
+  instant_asset_writeoff: true
+  instant_asset_threshold: 20000
+  home_office_percentage: 20
+
+alerts:
+  - type: quarterly_bas_reminder
+    schedule: quarterly
+    before_days: 14
+    message: "BAS due in 14 days - ensure all invoices and expenses are recorded"
+
+  - type: instant_asset_threshold
+    trigger: transaction_over_threshold
+    threshold: 20000
+    message: "Purchase over $20k - may require depreciation schedule instead of instant write-off"
+
+  - type: gst_registration_threshold
+    trigger: annual_income_exceeds
+    threshold: 75000
+    category: "Business Income"
+    message: "Business income approaching $75k - GST registration may be required"
+
+dependencies:
+  requires: []
+  conflicts_with: ["payg-employee", "small-business"]
+
+metadata:
+  created: "2025-11-22"
+  version: "1.0.0"
+  author: "Agent Smith"
+  priority: 1
--- a/skills/agent-smith/pyproject.toml
+++ b/skills/agent-smith/pyproject.toml
@@ -0,0 +1,110 @@
+[tool.black]
+line-length = 100
+target-version = ['py310', 'py311', 'py312']
+include = '\.pyi?$'
+extend-exclude = '''
+/(
+  # directories
+  \.eggs
+  | \.git
+  | \.hg
+  | \.mypy_cache
+  | \.tox
+  | \.venv
+  | build
+  | dist
+)/
+'''
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_unreachable = true
+strict_equality = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+
+[[tool.mypy.overrides]]
+module = "claude_agent_sdk.*"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "-v --strict-markers --tb=short"
+markers = [
+    "unit: Unit tests",
+    "integration: Integration tests requiring API access",
+    "slow: Tests that take significant time"
+]
+
+[build-system]
+requires = ["setuptools>=45", "wheel", "setuptools_scm[toml]>=6.2"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agent-smith"
+version = "1.4.1"
+description = "Intelligent financial management skill for Claude Code with PocketSmith API integration"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    {name = "Your Name", email = "your.email@example.com"}
+]
+keywords = ["pocketsmith", "finance", "ai", "claude-code", "financial-management"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "requests>=2.31.0",
+    "python-dateutil>=2.8.2",
+    "python-dotenv>=1.0.0",
+    "pyyaml>=6.0.3",
+    "claude-agent-sdk>=0.1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+    "black>=23.7.0",
+    "flake8>=6.1.0",
+    "mypy>=1.5.0",
+    "ipython>=8.14.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/slamb2k/agent-smith"
+Repository = "https://github.com/slamb2k/agent-smith"
+Issues = "https://github.com/slamb2k/agent-smith/issues"
+
+[dependency-groups]
+dev = [
+    "types-pyyaml>=6.0.12.20250915",
+    "types-python-dateutil>=2.9.0",
+    "types-requests>=2.32.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["scripts*"]
+exclude = ["tests*", "docs*", "build*", "ai_docs*", "data*", "logs*", "reports*", "backups*"]
--- a/skills/agent-smith/pytest.ini
+++ b/skills/agent-smith/pytest.ini
@@ -0,0 +1,13 @@
+[pytest]
+testpaths = tests
+python_files = test_*.py
+python_classes = Test*
+python_functions = test_*
+addopts =
+    -v
+    --strict-markers
+    --tb=short
+markers =
+    unit: Unit tests
+    integration: Integration tests requiring API access
+    slow: Tests that take significant time
--- a/skills/agent-smith/references/LESSONS_LEARNED.md
+++ b/skills/agent-smith/references/LESSONS_LEARNED.md
@@ -0,0 +1,327 @@
+# Lessons Learned from PocketSmith Migration
+
+**Date:** 2025-11-23
+**Source:** build/ directory reference materials (now archived)
+
+This document captures key insights from a previous PocketSmith category migration project that informed Agent Smith's design.
+
+---
+
+## Table of Contents
+
+1. [API Quirks and Workarounds](#api-quirks-and-workarounds)
+2. [Category Hierarchy Best Practices](#category-hierarchy-best-practices)
+3. [Transaction Categorization Patterns](#transaction-categorization-patterns)
+4. [Merchant Name Normalization](#merchant-name-normalization)
+5. [User Experience Lessons](#user-experience-lessons)
+
+---
+
+## API Quirks and Workarounds
+
+### Category Rules API Limitations
+
+**Issue:** PocketSmith API does not support updating or deleting category rules.
+- GET `/categories/{id}/category_rules` works
+- POST works (create only)
+- PUT/PATCH/DELETE return 404 errors
+
+**Impact:** Rules created via API cannot be modified programmatically.
+
+**Agent Smith Solution:** Hybrid rule engine with local rules for complex logic, platform rules for simple keywords only.
+
+### Transaction Migration 500 Errors
+
+**Issue:** Bulk transaction updates sometimes fail with 500 Internal Server Errors.
+
+**Root Cause:** Likely API rate limiting or server-side stability issues.
+
+**Agent Smith Solution:**
+- Implement rate limiting (0.1-0.5s delay between requests)
+- Batch processing with progress tracking
+- Retry logic with exponential backoff
+- Always backup before bulk operations
+
+### Special Characters in Category Names
+
+**Issue:** Using "&" in category names causes 422 Unprocessable Entity errors.
+
+**Workaround:** Replace "&" with "and" in all category names.
+
+**Example:**
+- ❌ "Takeaway & Food Delivery" → 422 error
+- ✅ "Takeaway and Food Delivery" → Success
+
+### Use PUT instead of PATCH
+
+**Issue:** PATCH for transaction updates is unreliable in PocketSmith API.
+
+**Solution:** Always use PUT for transaction updates.
+
+```python
+# ✅ Correct
+response = requests.put(
+    f'https://api.pocketsmith.com/v2/transactions/{txn_id}',
+    headers=headers,
+    json={'category_id': category_id}
+)
+
+# ❌ Avoid (unreliable)
+response = requests.patch(...)
+```
+
+---
+
+## Category Hierarchy Best Practices
+
+### Parent-Child Structure
+
+**Recommendation:** Use 2-level hierarchy maximum.
+- 12-15 parent categories for broad grouping
+- 2-5 children per parent for specific tracking
+- Avoid 3+ levels (PocketSmith UI gets cluttered)
+
+**Example Structure:**
+```
+Food & Dining (parent)
+├── Groceries
+├── Restaurants
+├── Takeaway and Food Delivery
+└── Coffee Shops
+```
+
+### Duplicate Category Detection
+
+**Problem:** Duplicate categories accumulate over time, causing confusion.
+
+**Solution:** Before creating categories, check for existing matches:
+1. Flatten nested category structure
+2. Check both exact matches and case-insensitive matches
+3. Check for variations (e.g., "Takeaway" vs "Takeaways")
+
+**Agent Smith Implementation:** Category validation in health check system.
+
+### Consolidation Strategy
+
+**Insight:** Merging duplicate categories is risky:
+- Requires migrating all associated transactions
+- Transaction updates can fail (500 errors)
+- Better to prevent duplicates than merge later
+
+**Agent Smith Approach:** Template-based setup with validation prevents duplicates upfront.
+
+---
+
+## Transaction Categorization Patterns
+
+### Pattern Matching Complexity
+
+**Observation:** Transaction categorization evolved through multiple rounds:
+- Round 1: Simple keyword matching (60% coverage)
+- Round 2: Pattern matching with normalization (80% coverage)
+- Round 3: User clarifications + edge cases (90% coverage)
+- Round 4: Manual review of exceptions (95% coverage)
+
+**Lesson:** Need both automated rules AND user override capability.
+
+**Agent Smith Solution:** Tiered intelligence modes (Conservative/Smart/Aggressive) with confidence scoring.
+
+### Confidence-Based Auto-Apply
+
+**Insight:** Not all matches are equal:
+- High confidence (95%+): Auto-apply safe (e.g., "WOOLWORTHS" → Groceries)
+- Medium confidence (70-94%): Ask user (e.g., "LS DOLLI PL" → Coffee?)
+- Low confidence (<70%): Always ask (e.g., "Purchase At Kac" → ???)
+
+**Agent Smith Implementation:**
+```python
+if confidence >= 90:  # Smart mode threshold
+    apply_automatically()
+elif confidence >= 70:
+    ask_user_for_approval()
+else:
+    skip_or_manual_review()
+```
+
+### Dry-Run Mode is Critical
+
+**Lesson:** Always preview before bulk operations.
+
+**Pattern from migration:**
+```python
+class BulkCategorizer:
+    def __init__(self, dry_run=True):  # Default to dry-run!
+        self.dry_run = dry_run
+
+    def categorize_transactions(self):
+        if self.dry_run:
+            # Show what WOULD happen
+            return preview
+        else:
+            # Actually execute
+            return results
+```
+
+**Agent Smith Implementation:** All bulk operations support `--mode=dry_run` flag.
+
+---
+
+## Merchant Name Normalization
+
+### Common Payee Patterns
+
+**Observations from transaction data:**
+
+1. **Location codes:** "WOOLWORTHS 1234" → "WOOLWORTHS"
+2. **Legal suffixes:** "COLES PTY LTD" → "COLES"
+3. **Country codes:** "UBER AU" → "UBER"
+4. **Transaction codes:** "PURCHASE NSWxxx123" → "PURCHASE"
+5. **Direct debit patterns:** "DIRECT DEBIT 12345" → "DIRECT DEBIT"
+
+**Agent Smith Patterns:**
+```python
+LOCATION_CODE_PATTERN = r"\s+\d{4,}$"
+SUFFIX_PATTERNS = [
+    r"\s+PTY\s+LTD$",
+    r"\s+LIMITED$",
+    r"\s+LTD$",
+    r"\s+AU$",
+]
+```
+
+### Merchant Variation Grouping
+
+**Problem:** Same merchant appears with multiple names:
+- "woolworths"
+- "WOOLWORTHS PTY LTD"
+- "Woolworths 1234"
+- "WOOLWORTHS SUPERMARKETS"
+
+**Solution:** Learn canonical names from transaction history.
+
+**Agent Smith Implementation:** `MerchantNormalizer.learn_from_transactions()` in scripts/utils/merchant_normalizer.py:101-130
+
+---
+
+## User Experience Lessons
+
+### Backups are Non-Negotiable
+
+**Critical Lesson:** ALWAYS backup before mutations.
+
+**Migration practice:**
+```python
+def categorize_transactions(self):
+    # Step 1: Always backup first
+    self.backup_transactions()
+
+    # Step 2: Then execute
+    self.apply_changes()
+```
+
+**Agent Smith Policy:** Automatic backups before all mutation operations, tracked in backups/ directory.
+
+### Progress Visibility Matters
+
+**Problem:** Long-running operations feel broken without progress indicators.
+
+**Solution:** Show progress every N iterations:
+```python
+for i, txn in enumerate(transactions, 1):
+    # Process transaction
+
+    if i % 100 == 0:
+        print(f"Progress: {i}/{total} ({i/total*100:.1f}%)")
+```
+
+**Agent Smith Implementation:** All batch operations show real-time progress.
+
+### Manual Cleanup is Inevitable
+
+**Reality Check:** Even after 5+ rounds of automated categorization, ~5% of transactions needed manual review.
+
+**Reasons:**
+- Genuinely ambiguous merchants ("Purchase At Kac" = gambling)
+- One-off transactions (unique payees)
+- Data quality issues (missing/incorrect payee names)
+
+**Agent Smith Approach:** Make manual review easy with health check reports showing uncategorized transactions.
+
+### Weekly Review Habit
+
+**Post-migration recommendation:** Review recent transactions weekly for first month.
+
+**Why:** Helps catch:
+- Miscategorized transactions
+- New merchants needing rules
+- Changes in spending patterns
+
+**Agent Smith Feature:** Smart alerts with weekly budget reviews (Phase 7).
+
+---
+
+## Implementation Timelines
+
+### Migration Timeline (Reality vs Plan)
+
+**Planned:** 35 minutes total
+**Actual:** 3+ hours over multiple days
+
+**Breakdown:**
+- Category structure migration: 10 minutes (as planned)
+- Rule recreation: 20 minutes (10 minutes planned - API limitations doubled time)
+- Transaction categorization Round 1: 30 minutes
+- Transaction categorization Round 2: 45 minutes
+- Transaction categorization Round 3: 60 minutes
+- Manual cleanup and verification: 90 minutes
+
+**Lesson:** Budget 3-5x estimated time for data migration projects.
+
+**Agent Smith Design:** Incremental onboarding (30-60 minutes initial setup, ongoing refinement).
+
+---
+
+## Key Takeaways for Agent Smith
+
+### What We Built Better
+
+1. **Hybrid Rule Engine:** Local + Platform rules overcome API limitations
+2. **Confidence Scoring:** Tiered auto-apply based on pattern strength
+3. **Merchant Intelligence:** Learned normalization from transaction history
+4. **Health Checks:** Proactive detection of category/rule issues
+5. **Template System:** Pre-built rule sets prevent common mistakes
+
+### What We Avoided
+
+1. **Manual rule migration** - Templates and import/export instead
+2. **Duplicate categories** - Validation and health checks
+3. **Bulk update failures** - Rate limiting, retry logic, batching
+4. **Lost context** - Comprehensive backups with metadata
+5. **User fatigue** - Incremental categorization, not all-at-once
+
+### Core Principles
+
+✅ **Backup before mutations**
+✅ **Dry-run before execute**
+✅ **Progress visibility**
+✅ **Confidence-based automation**
+✅ **User choice over forced automation**
+✅ **Learn from transaction history**
+✅ **Graceful degradation** (LLM fallback when rules don't match)
+
+---
+
+## Reference
+
+**Original Materials:** Archived from `build/` directory (removed 2025-11-23)
+
+**Full backup available at:** `../budget-smith-backup-20251120_093733/`
+
+**See Also:**
+- [Agent Smith Design](2025-11-20-agent-smith-design.md) - Complete system design
+- [Unified Rules Guide](../guides/unified-rules-guide.md) - Rule engine documentation
+- [Health Check Guide](../guides/health-check-guide.md) - Health scoring system
+
+---
+
+**Last Updated:** 2025-11-23
--- a/skills/agent-smith/references/design.md
+++ b/skills/agent-smith/references/design.md
--- a/skills/agent-smith/references/health-check-guide.md
+++ b/skills/agent-smith/references/health-check-guide.md
@@ -0,0 +1,408 @@
+# Agent Smith Health Check Guide
+
+## Introduction
+
+The Agent Smith health check system provides a comprehensive assessment of your PocketSmith financial setup. It analyzes six key dimensions of your financial data management, identifies issues, and provides prioritized recommendations for improvement.
+
+**Why use health checks?**
+
+- **Proactive Issue Detection**: Catch problems before they affect your financial tracking
+- **Continuous Improvement**: Track your setup quality over time with actionable metrics
+- **Tax Readiness**: Ensure your categorization and data quality meet compliance requirements
+- **Optimization Guidance**: Get specific recommendations to improve automation and accuracy
+
+---
+
+## The Six Health Dimensions
+
+Agent Smith evaluates your PocketSmith setup across six weighted dimensions:
+
+### 1. Data Quality (25% weight)
+
+The foundation of accurate financial tracking. This dimension measures:
+
+| Metric | Description | Target |
+|--------|-------------|--------|
+| Uncategorized Rate | Percentage of transactions without categories | < 5% |
+| Duplicate Detection | Potential duplicate transactions identified | 0 |
+| Data Gaps | Missing transaction periods | None |
+| Description Quality | Transactions with meaningful descriptions | > 90% |
+
+**Why it matters**: Poor data quality cascades into inaccurate reports, missed deductions, and unreliable budgets.
+
+### 2. Category Structure (20% weight)
+
+How well your category hierarchy is organized:
+
+| Metric | Description | Target |
+|--------|-------------|--------|
+| Category Depth | Optimal nesting (2-4 levels) | Balanced |
+| Unused Categories | Categories with no transactions | < 10% |
+| Unclassified Amounts | Money in catch-all categories | < 3% |
+| Category Distribution | Even spread across categories | No outliers |
+
+**Why it matters**: A well-structured category system makes analysis meaningful and tax preparation straightforward.
+
+### 3. Rule Engine (15% weight)
+
+Effectiveness of your categorization rules:
+
+| Metric | Description | Target |
+|--------|-------------|--------|
+| Rule Coverage | Transactions matched by rules | > 80% |
+| Rule Efficiency | Rules that actively match transactions | > 70% |
+| Conflict Detection | Rules with overlapping patterns | 0 |
+| Pattern Quality | Specificity of rule patterns | High |
+
+**Why it matters**: Strong rules reduce manual categorization work and ensure consistency.
+
+### 4. Tax Readiness (15% weight)
+
+Preparedness for tax reporting and compliance:
+
+| Metric | Description | Target |
+|--------|-------------|--------|
+| Tax Category Coverage | Deductible expenses properly categorized | > 95% |
+| Business/Personal Split | Clear separation where required | Complete |
+| Receipt Documentation | Transactions over $82.50 with receipts | 100% |
+| GST Tracking | GST amounts recorded where applicable | Complete |
+
+**Why it matters**: Poor tax categorization means missed deductions and compliance risks.
+
+### 5. Automation (10% weight)
+
+Level of automated financial management:
+
+| Metric | Description | Target |
+|--------|-------------|--------|
+| Savings Automation | Automated transfers to savings | Active |
+| Bill Scheduling | Recurring bills tracked | > 90% |
+| Account Sync Freshness | Time since last sync | < 24 hours |
+| Auto-categorization Rate | Transactions auto-categorized | > 85% |
+
+**Why it matters**: Automation reduces manual effort and prevents missed payments.
+
+### 6. Budget Alignment (15% weight)
+
+How well actual spending matches budgets:
+
+| Metric | Description | Target |
+|--------|-------------|--------|
+| Budget Variance | Difference from planned amounts | < 10% |
+| Overspending Categories | Categories over budget | < 20% |
+| Budget Coverage | Expenses covered by budgets | > 80% |
+| Forecast Accuracy | Predicted vs actual spending | > 85% |
+
+**Why it matters**: Budget alignment indicates financial discipline and planning accuracy.
+
+---
+
+## How to Run Health Checks
+
+### Using the Slash Command
+
+Run a health check using the Agent Smith command:
+
+```
+/agent-smith-health
+```
+
+### Command Options
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| `full` | Complete analysis of all dimensions | `/agent-smith-health full` |
+| `quick` | Fast check of critical metrics only | `/agent-smith-health quick` |
+| `dimension` | Check specific dimension | `/agent-smith-health data-quality` |
+| `compare` | Compare to previous check | `/agent-smith-health compare` |
+
+### What Happens During a Health Check
+
+1. **Data Collection**: Agent Smith queries your PocketSmith account
+2. **Analysis**: Each dimension is evaluated against benchmarks
+3. **Scoring**: Individual and overall scores are calculated
+4. **Recommendations**: Prioritized action items are generated
+5. **Report**: Results are displayed and optionally saved
+
+---
+
+## Interpreting Scores
+
+### Score Ranges
+
+| Range | Rating | Meaning |
+|-------|--------|---------|
+| 90-100 | Excellent | Your setup is optimized and well-maintained |
+| 70-89 | Good | Solid foundation with minor improvements possible |
+| 50-69 | Needs Attention | Several areas require improvement |
+| 0-49 | Critical | Significant issues affecting financial tracking |
+
+### Status Indicators
+
+Throughout health check results, you will see these status indicators:
+
+| Indicator | Meaning |
+|-----------|---------|
+| `[PASS]` | Metric meets or exceeds target |
+| `[WARN]` | Metric is below target but not critical |
+| `[FAIL]` | Metric requires immediate attention |
+
+### Dimension Breakdown
+
+Each dimension shows:
+- **Score**: 0-100 for that dimension
+- **Weight**: How much it contributes to overall score
+- **Contribution**: Weighted points added to total
+- **Status**: Overall health of that dimension
+
+---
+
+## Understanding Recommendations
+
+Health checks generate prioritized recommendations to improve your score.
+
+### Priority Levels
+
+| Priority | Description | Action Timeframe |
+|----------|-------------|------------------|
+| **Critical** | Issues affecting data integrity or compliance | Immediate (today) |
+| **High** | Significant impact on accuracy or efficiency | This week |
+| **Medium** | Improvements for better organization | This month |
+| **Low** | Nice-to-have optimizations | When convenient |
+
+### Effort Estimates
+
+Each recommendation includes an effort estimate:
+
+| Effort | Typical Time | Examples |
+|--------|--------------|----------|
+| **Quick Win** | < 15 minutes | Enable a setting, create one rule |
+| **Moderate** | 15-60 minutes | Reorganize categories, review duplicates |
+| **Significant** | 1-4 hours | Major category restructure, bulk updates |
+
+### Acting on Recommendations
+
+Recommendations follow this format:
+
+```
+[PRIORITY] Recommendation Title
+  Issue: What the problem is
+  Impact: Why it matters
+  Action: Specific steps to fix it
+  Effort: Time estimate
+```
+
+**Best practice**: Start with critical/quick-win items for maximum impact with minimum effort.
+
+---
+
+## Automated Monitoring
+
+### Weekly Health Checks
+
+Agent Smith can run automated weekly health checks:
+
+- **Schedule**: Every Sunday at midnight (configurable)
+- **Storage**: Results saved to `data/health/weekly/`
+- **Comparison**: Automatic comparison to previous week
+
+### Score Drop Alerts
+
+Get notified when your health score changes significantly:
+
+| Alert Type | Trigger | Priority |
+|------------|---------|----------|
+| Critical Drop | Score falls below 50 | High |
+| Significant Drop | Score drops > 15 points | Medium |
+| Dimension Alert | Any dimension falls to Critical | High |
+| Improvement | Score increases > 10 points | Info |
+
+### Configuring Alerts
+
+Set alert preferences in your environment or config:
+
+```bash
+# .env
+HEALTH_CHECK_ALERTS=true
+HEALTH_CHECK_THRESHOLD=15
+```
+
+Or in `data/config.json`:
+
+```json
+{
+  "healthCheck": {
+    "weeklyEnabled": true,
+    "alertOnDrop": true,
+    "dropThreshold": 15,
+    "notificationMethod": "summary"
+  }
+}
+```
+
+---
+
+## Example Output
+
+Here is a sample health check result:
+
+```
+================================================================================
+                        AGENT SMITH HEALTH CHECK
+                           2025-01-15 09:30 AM
+================================================================================
+
+OVERALL SCORE: 74/100 [GOOD]
+
+--------------------------------------------------------------------------------
+DIMENSION BREAKDOWN
+--------------------------------------------------------------------------------
+
+  Data Quality          [################----]  80/100  (25%)  = 20.0 pts
+  Category Structure    [###############-----]  75/100  (20%)  = 15.0 pts
+  Rule Engine           [############--------]  60/100  (15%)  =  9.0 pts  [WARN]
+  Tax Readiness         [################----]  82/100  (15%)  = 12.3 pts
+  Automation            [##############------]  70/100  (10%)  =  7.0 pts
+  Budget Alignment      [##############------]  72/100  (15%)  = 10.8 pts
+
+--------------------------------------------------------------------------------
+KEY METRICS
+--------------------------------------------------------------------------------
+
+  [PASS] Uncategorized transactions: 3.2% (target: <5%)
+  [PASS] Duplicate transactions: 0 found
+  [WARN] Rule coverage: 68% (target: >80%)
+  [PASS] Tax categories mapped: 94%
+  [WARN] Budget variance: 12% (target: <10%)
+
+--------------------------------------------------------------------------------
+RECOMMENDATIONS (5)
+--------------------------------------------------------------------------------
+
+  [CRITICAL] Quick Win
+    Create rules for top 10 uncategorized merchants
+    Issue: 15 merchants account for 60% of uncategorized transactions
+    Impact: Could improve rule coverage by 12%
+    Action: Run `/agent-smith-categorize analyze` to generate rules
+    Effort: 15 minutes
+
+  [HIGH] Moderate
+    Review category "Other Expenses"
+    Issue: $2,340 in catch-all category this month
+    Impact: Affects reporting accuracy and tax deduction tracking
+    Action: Recategorize transactions or create more specific categories
+    Effort: 30 minutes
+
+  [MEDIUM] Quick Win
+    Enable automatic account sync
+    Issue: Manual sync causing 2-3 day delays
+    Impact: Budgets and forecasts using stale data
+    Action: Enable daily sync in PocketSmith settings
+    Effort: 5 minutes
+
+  [MEDIUM] Moderate
+    Reduce budget variance in "Dining Out"
+    Issue: Consistently 25% over budget
+    Impact: Unrealistic budget affecting financial planning
+    Action: Adjust budget or implement spending alerts
+    Effort: 15 minutes
+
+  [LOW] Quick Win
+    Archive unused categories
+    Issue: 8 categories with no transactions in 6+ months
+    Impact: Clutters category picker, minor UX issue
+    Action: Review and archive or delete unused categories
+    Effort: 10 minutes
+
+--------------------------------------------------------------------------------
+TREND (Last 4 Weeks)
+--------------------------------------------------------------------------------
+
+  Week 1: 68  ████████████████░░░░
+  Week 2: 71  █████████████████░░░  (+3)
+  Week 3: 72  █████████████████░░░  (+1)
+  Week 4: 74  ██████████████████░░  (+2)  <- Current
+
+  Trend: Improving (+6 over 4 weeks)
+
+================================================================================
+Next scheduled check: 2025-01-22 00:00
+Run `/agent-smith-health compare` to see detailed changes
+================================================================================
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+#### "Unable to connect to PocketSmith"
+
+**Cause**: API key missing or invalid
+
+**Solution**:
+1. Check `.env` file contains `POCKETSMITH_API_KEY`
+2. Verify the key is valid at PocketSmith Developer Settings
+3. Ensure no extra whitespace around the key
+
+#### "Health check taking too long"
+
+**Cause**: Large transaction history or slow API response
+
+**Solution**:
+1. Use `/agent-smith-health quick` for faster results
+2. Check your internet connection
+3. Try again during off-peak hours
+
+#### "Scores seem inaccurate"
+
+**Cause**: Stale cached data or sync issues
+
+**Solution**:
+1. Force sync your PocketSmith accounts
+2. Clear Agent Smith cache: check `data/cache/`
+3. Run a full health check: `/agent-smith-health full`
+
+#### "Recommendations don't apply to my situation"
+
+**Cause**: Generic recommendations may not fit all users
+
+**Solution**:
+1. Adjust targets in `data/config.json`
+2. Use `/agent-smith configure` to set your preferences
+3. Dismiss inapplicable recommendations
+
+#### "Missing dimension scores"
+
+**Cause**: Insufficient data for analysis
+
+**Solution**:
+1. Ensure you have at least 30 days of transaction history
+2. Verify all accounts are synced
+3. Check that categories are set up in PocketSmith
+
+### Getting Help
+
+If issues persist:
+
+1. Check `data/logs/` for error details
+2. Run `/agent-smith-health --debug` for verbose output
+3. Review the design documentation at `docs/design/`
+
+---
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Run full health check | `/agent-smith-health` |
+| Quick check | `/agent-smith-health quick` |
+| Check specific dimension | `/agent-smith-health data-quality` |
+| Compare to last check | `/agent-smith-health compare` |
+| View trends | `/agent-smith-health trends` |
+| Configure alerts | `/agent-smith configure alerts` |
+
+---
+
+*For more information, see the complete [Agent Smith Design Document](../design/2025-11-20-agent-smith-design.md).*
--- a/skills/agent-smith/references/onboarding-guide.md
+++ b/skills/agent-smith/references/onboarding-guide.md
@@ -0,0 +1,344 @@
+# Agent Smith Onboarding Guide
+
+Welcome to Agent Smith! This guide walks you through your first-time setup and helps you get the most out of your PocketSmith integration.
+
+## Before You Begin
+
+**Prerequisites:**
+1. ✅ Agent Smith installed (see [INSTALL.md](../../INSTALL.md))
+2. ✅ PocketSmith account with API access
+3. ✅ API key configured in `.env` file
+4. ✅ Python 3.9+ and `uv` installed
+
+**Time Required:** 30-60 minutes (depending on transaction volume)
+
+---
+
+## The Onboarding Journey
+
+Agent Smith's onboarding is an 8-stage interactive process that:
+- Discovers your PocketSmith account structure
+- Recommends and customizes rule templates
+- Incrementally categorizes your transactions
+- Shows measurable improvement with health scores
+
+### Quick Start
+
+```bash
+# Launch the onboarding wizard
+/agent-smith-onboard
+```
+
+Claude will guide you through each stage interactively.
+
+---
+
+## Stage 1: Prerequisites Check
+
+**What happens:**
+- Verifies Agent Smith installation
+- Checks API key configuration
+- Tests PocketSmith connection
+
+**If something is missing:**
+- Follow the prompts to complete installation
+- Refer to [INSTALL.md](../../INSTALL.md) for detailed setup
+
+**Time:** 2 minutes
+
+---
+
+## Stage 2: Discovery
+
+**What happens:**
+- Analyzes your PocketSmith account structure
+- Counts accounts, categories, and transactions
+- Identifies uncategorized transactions
+- Calculates baseline health score
+
+**What you'll see:**
+```
+✓ Connected as: your@email.com
+✓ Accounts: 3 (Checking, Savings, Credit Card)
+✓ Categories: 47
+✓ Transactions: 2,387
+✓ Uncategorized: 1,245 (52%)
+✓ Date Range: Jan 2023 - Nov 2025
+✓ Baseline Health Score: 45/100 (Critical)
+✓ Recommended Template: shared-household
+```
+
+**Time:** 5-10 minutes (depends on data volume)
+
+---
+
+## Stage 3: Template Selection
+
+**What happens:**
+- Shows 4 template options
+- Recommends best fit based on discovery
+- Applies selected template to `data/rules.yaml`
+
+**Templates:**
+
+| Template | Best For | Includes |
+|----------|----------|----------|
+| **Simple** | Single person, basic tracking | Common categories, essential rules |
+| **Separated Families** | Child support, shared custody | Kids expenses, contributor tracking |
+| **Shared Household** | Couples, roommates | Shared expense tracking, approval workflows |
+| **Advanced** | Business owners, investors | Tax optimization, investment tracking, CGT |
+
+**What you'll do:**
+- Review the recommendation
+- Choose a template (or browse all)
+- Confirm application
+
+**Time:** 3-5 minutes
+
+---
+
+## Stage 4: Template Customization
+
+**What happens:**
+- Guides you to customize the template for your needs
+
+**Customizations needed:**
+
+1. **Account Mapping**
+   - Template uses generic names like "Shared Bills", "Personal"
+   - Update to match your actual account names
+
+2. **Category Validation**
+   - Check if template categories exist in PocketSmith
+   - Create missing categories or map to existing ones
+
+3. **Merchant Localization**
+   - Template has Australian merchants (WOOLWORTHS, COLES)
+   - Update for your region (SAFEWAY, KROGER, etc.)
+
+**How to customize:**
+- Edit `data/rules.yaml` manually (for now)
+- Future versions will have interactive customization tool
+
+**Example:**
+```yaml
+# Before (template)
+- type: category
+  patterns: [WOOLWORTHS, COLES]
+  category: Food & Dining > Groceries
+
+# After (customized for US)
+- type: category
+  patterns: [SAFEWAY, KROGER, WHOLE FOODS]
+  category: Food & Dining > Groceries
+```
+
+**Time:** 10-20 minutes
+
+---
+
+## Stage 5: Intelligence Mode Selection
+
+**What happens:**
+- Configure AI categorization behavior
+- Set tax intelligence level
+
+**Categorization Mode:**
+
+| Mode | Auto-Apply Threshold | Best For |
+|------|---------------------|----------|
+| Conservative | 100% (manual approval all) | First-time setup, learning |
+| **Smart** (default) | ≥90% confidence | Most users, balanced |
+| Aggressive | ≥80% confidence | High volume, trust AI |
+
+**Tax Intelligence Level:**
+
+| Level | Capabilities | Best For |
+|-------|-------------|----------|
+| Reference | ATO category mapping, basic reports | Users with accountants |
+| **Smart** (default) | Deduction detection, thresholds | Most taxpayers |
+| Full | BAS prep, compliance checks | Business owners, power users |
+
+**Time:** 2 minutes
+
+---
+
+## Stage 6: Incremental Categorization
+
+**What happens:**
+- Categorize transactions in manageable batches
+- Start recent, expand to historical
+
+**Recommended Strategy:**
+
+1. **Current Month** (test rules on small dataset)
+   ```bash
+   uv run python scripts/operations/batch_categorize.py --mode=dry_run --period=2025-11
+   uv run python scripts/operations/batch_categorize.py --mode=apply --period=2025-11
+   ```
+
+2. **Last 3 Months** (validate at scale)
+   ```bash
+   uv run python scripts/operations/batch_categorize.py --mode=apply --period=2025-09:2025-11
+   ```
+
+3. **Full Backfill** (complete the archive)
+   ```bash
+   uv run python scripts/operations/batch_categorize.py --mode=apply --period=2023-01:2025-11
+   ```
+
+**After Each Batch:**
+- Review results (matched, auto-applied, needs review)
+- Approve medium-confidence suggestions
+- Agent Smith learns new rules from your corrections
+
+**Time:** 20-60 minutes (depends on volume and mode)
+
+---
+
+## Stage 7: Health Check & Progress
+
+**What happens:**
+- Run post-categorization health check
+- Show before/after improvement
+- Identify remaining priorities
+
+**What you'll see:**
+```
+═══════════════════════════════════════════════
+AGENT SMITH HEALTH CHECK - PROGRESS REPORT
+═══════════════════════════════════════════════
+
+Baseline (before):    45/100 (Critical)
+Current:              78/100 (Good) ⬆ +33 points
+
+Improvements:
+• Data Quality:        42 → 88 (+46) ✅
+• Rule Engine:         15 → 72 (+57) ✅
+• Category Structure:  58 → 81 (+23) ✅
+
+Remaining priorities:
+1. Review tax category mappings
+2. Add 3 more rules for recurring merchants
+3. Create budgets for top 5 categories
+```
+
+**Time:** 5 minutes
+
+---
+
+## Stage 8: Ongoing Usage
+
+**What happens:**
+- Receive guidance on regular Agent Smith usage
+- Get quick reference for common operations
+
+**Daily/Weekly:**
+```bash
+/agent-smith-categorize --mode=smart --period=2025-11
+```
+
+**Monthly:**
+```bash
+/agent-smith-analyze spending --period=2025-11
+/agent-smith-health --quick
+```
+
+**Quarterly:**
+```bash
+/agent-smith-tax deductions --period=2024-25
+```
+
+**Annual (EOFY):**
+```bash
+/agent-smith-tax eofy
+```
+
+**Time:** 2 minutes
+
+---
+
+## Troubleshooting
+
+### Onboarding Interrupted
+
+If onboarding is interrupted, your progress is saved in `data/onboarding_state.json`.
+
+**Resume:**
+```bash
+/agent-smith-onboard
+```
+
+Claude will detect saved state and offer to resume from where you left off.
+
+**Start Over:**
+```bash
+uv run python -c "from scripts.onboarding.state import OnboardingState; OnboardingState().reset()"
+/agent-smith-onboard
+```
+
+### Discovery Fails
+
+**Problem:** "Error during discovery: ..."
+
+**Solutions:**
+- Check `.env` has valid `POCKETSMITH_API_KEY`
+- Verify PocketSmith account has API access enabled
+- Check internet connection to api.pocketsmith.com
+
+### Template Customization Unclear
+
+**Problem:** Not sure how to customize `data/rules.yaml`
+
+**Solutions:**
+- Review [Unified Rules Guide](unified-rules-guide.md) for YAML syntax
+- Check [Example Files](../examples/) for patterns
+- Start with dry-run to test rules before applying
+
+### Categorization Too Slow
+
+**Problem:** Batch categorization taking too long
+
+**Solutions:**
+- Use smaller date ranges (1 month at a time)
+- Switch to "Aggressive" mode for faster auto-apply
+- Run in background with progress monitoring
+
+---
+
+## Next Steps
+
+After completing onboarding:
+
+1. **Set Up Alerts**
+   - Weekly budget reviews
+   - Monthly trend analysis
+   - Tax deadline reminders
+
+2. **Create Budgets**
+   - Use health check recommendations
+   - Focus on top spending categories
+   - Track vs. budget monthly
+
+3. **Optimize Rules**
+   - Review rule performance metrics
+   - Add rules for recurring merchants
+   - Refine confidence scores
+
+4. **Explore Advanced Features**
+   - Scenario analysis
+   - Tax optimization
+   - Investment tracking
+
+---
+
+## Getting Help
+
+- **Documentation:** [docs/](../INDEX.md)
+- **API Reference:** [ai_docs/pocketsmith-api-documentation.md](../../ai_docs/pocketsmith-api-documentation.md)
+- **Health Check Guide:** [health-check-guide.md](health-check-guide.md)
+- **GitHub Issues:** [github.com/slamb2k/agent-smith/issues](https://github.com/slamb2k/agent-smith/issues)
+
+---
+
+**Welcome to Agent Smith! Let's transform your PocketSmith into an intelligent financial system.**
--- a/skills/agent-smith/references/pocketsmith-api.md
+++ b/skills/agent-smith/references/pocketsmith-api.md
@@ -0,0 +1,293 @@
+# PocketSmith API Documentation (Offline Reference)
+
+**API Version:** v2.0
+**Base URL:** `https://api.pocketsmith.com/v2`
+**Documentation Source:** https://developers.pocketsmith.com/
+**Last Updated:** 2025-11-16
+
+---
+
+## Table of Contents
+
+1. [Introduction](#introduction)
+2. [Authentication](#authentication)
+   - [Developer Keys](#developer-keys-personal-tools)
+   - [OAuth 2.0](#oauth-20-multi-user-apps)
+3. [API Reference](#api-reference)
+   - [Users](#users)
+   - [Institutions](#institutions)
+   - [Accounts](#accounts)
+   - [Transaction Accounts](#transaction-accounts)
+   - [Transactions](#transactions)
+   - [Categories](#categories)
+   - [Budgeting](#budgeting)
+   - [Supporting Resources](#supporting-resources)
+4. [Common Topics](#common-topics)
+   - [Pagination](#pagination)
+   - [Error Handling](#error-handling)
+5. [Changelog](#changelog)
+6. [Support](#support)
+
+---
+
+## Introduction
+
+The PocketSmith API is freely available to all developers without restrictions. The platform welcomes developers to build tools and integrations using their services.
+
+**Developer Hub:** https://developers.pocketsmith.com/
+
+---
+
+## Authentication
+
+PocketSmith provides two authentication methods depending on your use case.
+
+### Developer Keys (Personal Tools)
+
+For building personal tools like dashboard widgets or transaction importers, use developer keys.
+
+**Configuration:**
+- Manage keys in: Settings > Security within your PocketSmith account
+- **Header:** `X-Developer-Key`
+- **Access:** Persistent API access to your own account
+
+**Example Request:**
+```bash
+curl --header "X-Developer-Key: YOUR_KEY_HERE" \
+  https://api.pocketsmith.com/v2/me
+```
+
+**Supported Languages:**
+- Shell (curl)
+- Node.js
+- JavaScript
+- PHP
+- Python
+
+### OAuth 2.0 (Multi-User Apps)
+
+To create applications that other PocketSmith users can access, you'll need to use OAuth 2.0.
+
+**Setup Process:**
+
+1. **Register your application** by contacting the team at [email protected]
+2. **Provide details** about yourself and your planned integration
+3. **Receive credentials:** `client_id` and `client_secret` upon approval
+4. **Implement authentication** using the OAuth integration guide
+
+**OAuth Flow:**
+- Standard OAuth 2.0 authorization code flow
+- Detailed integration instructions available in the OAuth documentation section
+
+---
+
+## API Reference
+
+The PocketSmith API v2.0 is organized around the following resource categories:
+
+### Users
+
+**Endpoints:**
+- Get authorised user
+- Get user by ID
+- Update user information
+
+**Example - Get the Authorised User:**
+```
+GET https://api.pocketsmith.com/v2/me
+```
+
+**Purpose:** Gets the user that corresponds to the access token used in the request.
+
+**Authentication Required:** Yes (Header-based credentials)
+
+---
+
+### Institutions
+
+Manage financial institutions connected to user accounts.
+
+**Operations:**
+- Create institution
+- Read institution details
+- Update institution information
+- Delete institution
+- List all institutions within a user account
+
+---
+
+### Accounts
+
+Complete account management functionality.
+
+**Operations:**
+- Get account details
+- Update account information
+- Delete account
+- Create new account
+- Manage account ordering within users
+- List accounts by institution
+
+---
+
+### Transaction Accounts
+
+Transaction accounts are the specific accounts where transactions are recorded.
+
+**Operations:**
+- Get transaction account details
+- Update transaction account
+- List transaction accounts by user
+
+---
+
+### Transactions
+
+Complete transaction lifecycle management with multi-context querying.
+
+**Query Contexts:**
+- By user
+- By account
+- By category
+- By transaction account
+
+**Operations:**
+- Create transactions within transaction accounts
+- Read transaction details
+- Update transactions
+- Delete transactions
+- Query and filter transactions
+
+---
+
+### Categories
+
+Manage and organize transaction categories.
+
+**Operations:**
+- Category management and organization
+- List user-specific categories
+- Create category rules
+- Update categories
+- Delete categories
+
+---
+
+### Budgeting
+
+Budget management and analysis features.
+
+**Features:**
+- Budget retrieval and summaries
+- Trend analysis
+- Forecast cache management
+
+---
+
+### Supporting Resources
+
+Additional resources for comprehensive financial data management:
+
+- **Events** - Manage financial events
+- **Attachments** - Attach files to transactions
+- **Labels** - Label and tag transactions
+- **Saved Searches** - Save frequently used search queries
+- **Currencies** - Handle multi-currency support
+- **Time Zones** - Manage timezone settings
+
+---
+
+## Common Topics
+
+### Pagination
+
+The API uses pagination for endpoints that return multiple records.
+
+**Implementation Details:**
+- Refer to the pagination documentation section for page size limits and navigation
+- Response headers typically include pagination metadata
+
+### Error Handling
+
+The API returns standard HTTP status codes.
+
+**Common Status Codes:**
+- `200 OK` - Successful request
+- `400 Bad Request` - Invalid request parameters
+- `401 Unauthorized` - Authentication failure
+- `403 Forbidden` - Insufficient permissions
+- `404 Not Found` - Resource not found
+- `500 Internal Server Error` - Server error
+
+**Error Response Format:**
+Detailed error handling documentation available at: https://developers.pocketsmith.com/docs
+
+---
+
+## Changelog
+
+### v2.0 - Welcome to the new PocketSmith developer hub
+**Posted:** Almost 7 years ago by Regan McEntyre
+
+The development team announced an updated documentation portal: "We've given our developer documentation a bit of a spruce up. Come on in and check it out, and let us know what you think!"
+
+**Current Status:**
+- API Version 2.0 is the current stable version
+- Interactive API documentation powered by OpenAPI 3 specification
+
+---
+
+## Support
+
+**Contact the Development Team:**
+- **Email:** [email protected]
+
+**Resources:**
+- **Interactive API Reference:** https://developers.pocketsmith.com/reference
+- **Complete Guides:** https://developers.pocketsmith.com/docs
+- **Changelog:** https://developers.pocketsmith.com/changelog
+
+---
+
+## Quick Start Guide
+
+1. **For Personal Tools:**
+   ```bash
+   # Get your developer key from Settings > Security
+   curl --header "X-Developer-Key: YOUR_KEY_HERE" \
+     https://api.pocketsmith.com/v2/me
+   ```
+
+2. **For Multi-User Applications:**
+   - Email [email protected] to register your app
+   - Implement OAuth 2.0 flow once approved
+
+3. **Explore the API:**
+   - Start with the `/me` endpoint to verify authentication
+   - Review the resource categories that match your use case
+   - Test endpoints using the interactive reference
+
+---
+
+## Additional Notes
+
+**OpenAPI Specification:**
+The API documentation is built using OpenAPI 3, which means:
+- Interactive testing tools available in the web interface
+- Machine-readable API specifications
+- Auto-generated client libraries possible
+
+**Rate Limiting:**
+Check the full documentation for any rate limiting policies.
+
+**Best Practices:**
+- Always handle errors gracefully
+- Use pagination for large datasets
+- Cache responses where appropriate
+- Follow OAuth 2.0 best practices for multi-user apps
+
+---
+
+**End of Documentation**
+
+For the most up-to-date information and interactive API testing, visit: https://developers.pocketsmith.com/
--- a/skills/agent-smith/references/unified-rules-guide.md
+++ b/skills/agent-smith/references/unified-rules-guide.md