feat: add crab tax plugin (#66)

## Why
Crabcode already had plugin-based workflows for promptfoo and
Excalidraw, but there was no tax workflow for organizing personal tax
documents into a reviewable filing handoff. This adds the new tax
plugin, wires it into `crab`, and documents it where plugin-specific
users will actually look.

## What
- add the `crab tax` plugin with inventory, extraction, reconciliation,
deterministic estimate, and TurboTax handoff generation
- wire install, uninstall, update, help, and execution commands into
`src/crabcode`
- add top-level docs for `crab tax` and a plugin-local README at
`plugins/tax/README.md`
- add fixture-based tests and testdata for supported flows and failure
cases
- add plugin-local `.gitignore` so build artifacts and dependencies stay
out of the repo

## How to Test
- run `cd plugins/tax && npm test`
- run `cd plugins/tax && npm run build`
- run `bash -n src/crabcode`
- note: `pnpm exec biome check --write .` is not runnable in this repo
because there is no root package/workspace for `pnpm exec` to target

Author: MrFlounder

README.md

@@ -197,6 +197,39 @@ pf: My API is at http://localhost:8080/chat, POST with JSON { "message": "the pr
 
 File attachments (API specs, curl commands) are also supported. Results are posted back to the Slack thread as downloadable files.
 
+### Tax Organizer (`crab tax`)
+
+Tax document organizer and deterministic filing handoff generator for supported 2025 federal + California personal return scenarios.
+
+```bash
+crab tax install                               # Install the plugin
+crab tax ./my-tax-docs                         # Process a folder of tax documents
+crab tax ./my-tax-docs --output ./tax-output   # Write outputs to a directory
+crab tax ./my-tax-docs --profile ./profile.json
+crab tax uninstall                             # Remove the plugin
+```
+
+**Supported inputs today:** `W-2`, `1099-INT`, `1099-DIV`, `1098`, `1099-B`, `1099-R`, `5498`, `1099-composite`, `property-tax-bill`
+
+**Outputs:**
+- `taxpayer_profile.json`
+- `documents.json`
+- `reconciliation.json`
+- `issues_to_review.json`
+- `federal_return_inputs.json`
+- `ca_return_inputs.json`
+- `estimate_summary.json`
+- `turbotax_handoff.md`
+
+See [plugins/tax/README.md](plugins/tax/README.md) for plugin-specific details.
+
+**Modes:**
+- Mock extraction via `.mock.json` sidecars for deterministic fixture testing
+- Live OpenAI extraction for supported PDFs/images when `OPENAI_API_KEY` is set
+- Bounded agent research for unknown or unsupported forms using tool calls plus official-source web search
+
+**Current scope:** single or MFJ, full-year California resident, no dependent-related federal credits, no RSU/ESPP handling, deterministic estimation for supported scenarios only
+
 ### Excalidraw Whiteboard (`crab draw`)
 
 Collaborative whiteboarding with real-time collab via Excalidraw.

plugins/tax/.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+dist/

plugins/tax/README.md

@@ -0,0 +1,99 @@
+# Crab Tax Plugin
+
+`crab tax` organizes tax documents, extracts supported fields, computes deterministic 2025 federal and California estimates for supported scenarios, and writes a TurboTax-oriented handoff packet.
+
+## Installation
+
+```bash
+crab tax install
+```
+
+## Usage
+
+```bash
+crab tax ./my-tax-docs
+crab tax ./my-tax-docs --output ./tax-output
+crab tax ./my-tax-docs --profile ./profile.json
+crab tax uninstall
+```
+
+## Outputs
+
+The plugin writes:
+
+```text
+tax-output/
+├── taxpayer_profile.json
+├── documents.json
+├── extracted/
+├── reconciliation.json
+├── issues_to_review.json
+├── federal_return_inputs.json
+├── ca_return_inputs.json
+├── estimate_summary.json
+└── turbotax_handoff.md
+```
+
+## Supported Inputs
+
+- `W-2`
+- `1099-INT`
+- `1099-DIV`
+- `1098`
+- `1099-B`
+- `1099-R`
+- `5498`
+- `1099-composite`
+- `property-tax-bill`
+
+## Extraction Modes
+
+### Mock Sidecars
+
+For deterministic local tests, place a `.mock.json` file beside the document:
+
+```text
+w2-2025.pdf
+w2-2025.pdf.mock.json
+```
+
+### Deterministic Parsers
+
+The plugin prefers deterministic extraction for supported document layouts such as composite brokerage statements and property tax bills.
+
+### Live OpenAI Extraction
+
+If no mock sidecar is present and deterministic parsing does not apply, the plugin attempts live extraction for supported PDFs and images when `OPENAI_API_KEY` is set. The current default model is `gpt-5.4`.
+
+## Agent Research Loop
+
+For unknown or unsupported tax forms, the plugin runs a bounded agent research pass:
+
+- the agent inspects the unknown document inventory
+- it uses tool calls to perform official-source research
+- it records a handling strategy
+- unsupported forms remain blocking unless deterministic handling exists
+
+This is intentionally different from letting an agent improvise tax math. The deterministic engine still owns reconciliation and final computations.
+
+## Current Supported Scenario
+
+The deterministic estimation path currently targets:
+
+- 2025 tax year
+- `single` or `mfj`
+- California full-year resident
+- no dependent-related federal credits
+- no RSU / ESPP / inherited-share handling
+- no Schedule C, rental, or K-1 support
+
+Unsupported scenarios are surfaced as blocking issues rather than silently guessed.
+
+## Development
+
+Run fixture-based end-to-end tests:
+
+```bash
+cd plugins/tax
+npm test
+```

plugins/tax/bin/crab-tax.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/cli.js');

plugins/tax/package-lock.json

@@ -0,0 +1,23 @@
+{
+  "name": "@crabcode/tax",
+  "version": "0.1.0",
+  "description": "Tax document organizer and filing handoff plugin for crabcode",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "crab-tax": "./bin/crab-tax.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "node test/e2e.mjs && node test/classify.mjs && node test/deterministic.mjs"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}