# 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.**