tax-organizer

What this skill does

# Tax Organizer

Maintain a flat, year-by-year tax document folder structure. Track which institutions need documents each year, identify what's missing, file incoming documents, and provide retrieval URLs.

If `$ARGUMENTS` is provided, interpret as an action:
- A year (e.g., `2025`) — show status for that tax year
- `status` — show status for all years
- `file` — process incoming folder
- `setup` — initialize a new tax year
- `setup 2025` — initialize a specific year

## Paths

```
BASE_DIR = ~/Library/CloudStorage/[email protected]/My Drive/TRAVIS_Taxes/
```

| Path | Purpose |
|---|---|
| `BASE_DIR/<YYYY>/` | Tax documents for that year (flat — no subfolders) |
| `BASE_DIR/incoming/` | Drop zone for new documents to be filed |
| `BASE_DIR/.tax-organizer/tax_tracker.sqlite` | Tracking database |

## Folder Structure (Flat)

Each year folder is **flat** — no subfolders. Files are named with a consistent prefix pattern:

```
<YYYY>/
  <institution>-<doc_type>-<detail>.pdf
  <institution>-<doc_type>-<detail>.pdf
  ...
```

### File Naming Convention

```
<institution>-<doc_type>[-<detail>].<ext>
```

**institution** (lowercase): `amex`, `chase`, `etrade`, `schwab`, `fidelity`, `paypal`, `venmo`, `amazon`, `godaddy`, `aws`, `lowes`, `usaa`, `irs`, `texas`, `travis-county`, `hays-county`, `williamson-county`, etc.

**doc_type** (lowercase):
| Type | Description |
|---|---|
| `1099-int` | Interest income |
| `1099-div` | Dividends |
| `1099-b` | Brokerage/capital gains |
| `1099-r` | Retirement distributions |
| `1099-misc` | Miscellaneous income |
| `1099-nec` | Nonemployee compensation |
| `1099-k` | Payment card/third-party network |
| `1098` | Mortgage interest |
| `1098-t` | Tuition |
| `w2` | Wage statement |
| `1095-a/b/c` | Health coverage |
| `5498` | IRA contributions |
| `statement-annual` | Year-end statement |
| `statement-q1/q2/q3/q4` | Quarterly statements |
| `statement-01..12` | Monthly statements |
| `property-tax` | Property tax bill/receipt |
| `property-insurance` | Insurance declaration page |
| `hoa` | HOA annual statement |
| `k1` | Partnership/S-corp schedule |
| `receipt` | Business receipt |
| `summary` | Annual summary |
| `sales-report` | Sales tax report (for eBay/resale) |

**detail** (optional): account last 4, property address slug, etc.

### Examples

```
2024/
  amex-statement-annual-9878.pdf
  amex-1099-int.pdf
  chase-statement-annual-4589.pdf
  chase-1099-int.pdf
  etrade-1099-b.pdf
  etrade-1099-div.pdf
  etrade-5498.pdf
  paypal-1099-k.pdf
  ebay-1099-k.pdf
  irs-1040-filed.pdf
  texas-franchise-tax.pdf
  travis-county-property-tax-7207.pdf
  hays-county-property-tax-1913.pdf
  usaa-1098-7207.pdf
  usaa-1098-1913.pdf
  gravhl-k1.pdf
  tmctech-k1.pdf
```

## Database

**Path**: `BASE_DIR/.tax-organizer/tax_tracker.sqlite`

Use `sqlite3` CLI or Python `sqlite3` module.

### Schema

```sql
CREATE TABLE IF NOT EXISTS institutions (
    id              INTEGER PRIMARY KEY AUTOINCREMENT,
    code            TEXT NOT NULL UNIQUE,        -- 'amex', 'chase', 'etrade'
    name            TEXT NOT NULL,                -- 'American Express', 'Chase Bank'
    institution_type TEXT NOT NULL,               -- 'bank', 'brokerage', 'payment', 'government', 'insurance', 'employer', 'property'
    portal_url      TEXT,                         -- URL to log in and download docs
    doc_retrieval_notes TEXT,                     -- step-by-step instructions
    first_year      INTEGER,                      -- first year this institution appears
    last_year       INTEGER,                      -- NULL = still active
    discontinued_at TEXT,                         -- date user said "no longer have"
    ask_until_year  INTEGER,                      -- stop asking after this year (discontinued_at year + 3)
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE IF NOT EXISTS institution_docs (
    id              INTEGER PRIMARY KEY AUTOINCREMENT,
    institution_id  INTEGER NOT NULL REFERENCES institutions(id),
    doc_type        TEXT NOT NULL,                -- '1099-int', 'statement-annual', 'property-tax'
    description     TEXT,                         -- 'Interest income statement'
    is_required     BOOLEAN DEFAULT 1,            -- required for tax filing?
    is_conditional  BOOLEAN DEFAULT 0,            -- only needed if threshold met (e.g., 1099-K > $600)
    condition_notes TEXT,                         -- 'Only issued if payments > $600'
    UNIQUE(institution_id, doc_type)
);

CREATE TABLE IF NOT EXISTS year_institutions (
    id              INTEGER PRIMARY KEY AUTOINCREMENT,
    year            INTEGER NOT NULL,
    institution_id  INTEGER NOT NULL REFERENCES institutions(id),
    status          TEXT DEFAULT 'expected',      -- 'expected', 'received', 'not-applicable', 'waived'
    notes           TEXT,
    UNIQUE(year, institution_id)
);

CREATE TABLE IF NOT EXISTS year_documents (
    id              INTEGER PRIMARY KEY AUTOINCREMENT,
    year            INTEGER NOT NULL,
    institution_id  INTEGER NOT NULL REFERENCES institutions(id),
    doc_type        TEXT NOT NULL,
    filename        TEXT,                         -- actual filename in the year folder
    status          TEXT DEFAULT 'missing',       -- 'missing', 'received', 'not-applicable', 'waived'
    received_at     TEXT,                         -- date filed
    notes           TEXT,
    UNIQUE(year, institution_id, doc_type)
);

CREATE TABLE IF NOT EXISTS filing_log (
    id              INTEGER PRIMARY KEY AUTOINCREMENT,
    year            INTEGER NOT NULL,
    filename        TEXT NOT NULL,
    institution_code TEXT,
    doc_type        TEXT,
    action          TEXT NOT NULL,                -- 'filed', 'renamed', 'skipped'
    source_filename TEXT,                         -- original name from incoming/
    filed_at        DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE IF NOT EXISTS discontinuation_log (
    id              INTEGER PRIMARY KEY AUTOINCREMENT,
    institution_id  INTEGER NOT NULL REFERENCES institutions(id),
    year_asked      INTEGER NOT NULL,
    response        TEXT NOT NULL,                -- 'confirmed-gone', 'still-active', 'deferred'
    asked_at        DATETIME DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(institution_id, year_asked)
);

CREATE TABLE IF NOT EXISTS brokerage_accounts (
    id              INTEGER PRIMARY KEY AUTOINCREMENT,
    institution_id  INTEGER NOT NULL REFERENCES institutions(id),
    account_last4   TEXT NOT NULL,
    account_name    TEXT NOT NULL,          -- 'LOGI', 'MJoint', 'TRoth'
    account_type    TEXT NOT NULL,          -- 'brokerage', 'bank', 'ira-roth', 'ira-traditional'
    owner           TEXT,                   -- 'Travis', 'Melissa', 'Joint'
    full_account    TEXT,                   -- full account number if known
    migrated_from   TEXT,                   -- old account last4 for migration tracking
    notes           TEXT,
    first_year      INTEGER,
    last_year       INTEGER,
    UNIQUE(institution_id, account_last4)
);
```

### Seed Data — Known Institutions

Seed these on first run (adjust URLs to match actual portals):

```sql
-- Financial Institutions
INSERT INTO institutions (code, name, institution_type, portal_url, doc_retrieval_notes, first_year) VALUES
('amex',     'American Express',  'bank',      'https://www.americanexpress.com/us/customer-service/statements-tax-forms.html', 'Login > Statements & Activity > Tax Forms > Download 1099', 2021),
('chase',    'Chase Bank',        'bank',      'https://www.chase.com/digital/login', 'Login > Statements > Tax Documents > Download', 2021),
('etrade',   'E*TRADE / Morgan Stanley', 'brokerage', 'https://us.etrade.com/etx/pxy/my-account/tax-center', 'Login > Tax Center > Tax Forms > Download all', 2021),
('paypal',   'PayPal',            'payment',   'https://www.paypal.com/myaccount/taxes/', 'Login > Activity > Statements & Tax > Tax Documents', 2021),
('venmo',    'Venmo',             'payme