docs: add CONTRACTS.md and update plan/README for milestones 1-3

- docs/CONTRACTS.md: CLI JSON contract specification
- IMPLEMENTATION_PLAN.md: mark milestones 1-3 steps as complete
- README.md: update quick start and command list
- docs/PRD.md, docs/ARCHITECTURE.md: minor corrections

Author: thedavidweng

IMPLEMENTATION_PLAN.md

@@ -472,17 +472,17 @@ Goal: stable local read contracts against encrypted SQLite without any live Prov
 
 Steps:
 
-1. Add `internal/config`.
-2. Add encrypted SQLite dependency.
-3. Implement store open/close and migrations.
-4. Create minimal tables: institutions, provider_items, accounts, transactions, transaction_tags, categories, tags, recurring, sync_runs.
-5. Support manual accounts with nullable Provider Item provenance and local source metadata.
-6. Support a non-persistent demo store seeded with small, inspectable synthetic data for local testing and trial use without Provider credentials.
-7. Implement store methods for listing accounts, creating manual accounts, listing/searching transactions, listing categories, listing tags, and listing recurring items against both real and demo stores.
-8. Add fixture seed helpers for tests.
-9. Implement CLI skeleton for `accounts list`, `accounts create-manual`, `demo <command...>`, `transactions list`, `transactions search`, `tx` aliases, `categories list`, `tags list`, and `recurring list`.
-10. Add JSON contract tests for all first-milestone read commands, manual account dry-run/confirm behavior, and demo isolation/reset behavior.
-11. Run `go test ./...`.
+- [x] 1. Add `internal/config`.
+- [x] 2. Add encrypted SQLite dependency.
+- [x] 3. Implement store open/close and migrations.
+- [x] 4. Create minimal tables: institutions, provider_items, accounts, transactions, transaction_tags, categories, tags, recurring, sync_runs.
+- [x] 5. Support manual accounts with nullable Provider Item provenance and local source metadata.
+- [x] 6. Support a non-persistent demo store seeded with small, inspectable synthetic data for local testing and trial use without Provider credentials.
+- [x] 7. Implement store methods for listing accounts, creating manual accounts, listing/searching transactions, listing categories, listing tags, and listing recurring items against both real and demo stores.
+- [x] 8. Add fixture seed helpers for tests.
+- [x] 9. Implement CLI skeleton for `accounts list`, `accounts create-manual`, `demo <command...>`, `transactions list`, `transactions search`, `tx` aliases, `categories list`, `tags list`, and `recurring list`.
+- [x] 10. Add JSON contract tests for all first-milestone read commands, manual account dry-run/confirm behavior, and demo isolation/reset behavior.
+- [x] 11. Run `go test ./...`.
 
 Acceptance:
 
@@ -546,16 +546,16 @@ Goal: prepare Plaid and Bridge as replaceable Provider adapters.
 
 Steps:
 
-1. Add official Go Plaid SDK.
-2. Add Bridge HTTP client implementation.
-3. Add Plaid config fields with `PLAID_` environment variable names.
-4. Add Bridge config fields with `BRIDGE_` environment variable names.
-5. Add provider registry with Plaid and Bridge adapters.
-6. Define canonical provider records for Institution, ProviderItem, FinancialAccount, Transaction, and SyncResult.
-7. Write fixture-based mapper tests before any live Provider calls, including canonical amount sign normalization and liability balance normalization.
-8. Implement Plaid client construction without managed proxy behavior.
-9. Implement Bridge client construction without managed proxy behavior.
-10. Implement provider error classification.
+- [x] 1. Add official Go Plaid SDK.
+- [x] 2. Add Bridge HTTP client implementation.
+- [x] 3. Add Plaid config fields with `PLAID_` environment variable names.
+- [x] 4. Add Bridge config fields with `BRIDGE_` environment variable names.
+- [x] 5. Add provider registry with Plaid and Bridge adapters.
+- [x] 6. Define canonical provider records for Institution, ProviderItem, FinancialAccount, Transaction, and SyncResult.
+- [x] 7. Write fixture-based mapper tests before any live Provider calls, including canonical amount sign normalization and liability balance normalization.
+- [x] 8. Implement Plaid client construction without managed proxy behavior.
+- [x] 9. Implement Bridge client construction without managed proxy behavior.
+- [x] 10. Implement provider error classification.
 
 Acceptance:
 
@@ -573,22 +573,22 @@ Goal: allow the user to create a Plaid item and store its access token inside th
 
 Steps:
 
-1. Implement `money link` for institution-first linking through Plaid when Plaid is the selected Provider.
-2. Implement `money providers plaid link` for explicit Plaid linking.
-3. Separate Provider support from Provider availability: list all Providers known to support the selected institution, mark locally unavailable Providers as missing credentials, and block selecting unavailable Providers with generated configure guidance.
-4. Determine Provider availability from local config/env required fields, following Ray's configured-state pattern but using `money`'s explicit `env:` model.
-5. Use Plaid `/institutions/search` with configured products and country codes for Plaid institution discovery.
-6. Use a short-lived localhost Link page and callback server only for Plaid Link.
-7. Create Plaid Link token with explicit products and country codes.
-8. Serve a local page that loads Plaid Link with the link token and posts `public_token`, selected institution/account metadata, and random state back to the localhost helper on success.
-9. Exchange public token for access token.
-10. Store access token only after the encrypted store is open.
-11. Store provider item, institution metadata, products, and initial cursor state.
-12. Use random state/nonce values, timeout callback sessions, bind only for the active link flow, and shut down the helper after completion.
-13. Follow GitHub CLI browser ergonomics in human mode: print the local Link URL, wait for Enter, then open the browser.
-14. Support `--no-open` to print the URL without opening a browser for SSH, cron, and headless environments.
-15. Do not automatically run the first sync after link; print help-derived guidance for running `money sync`.
-16. Add tests for encrypted-store requirements and link exchange logic using fakes.
+- [x] 1. Implement `money link` for institution-first linking through Plaid when Plaid is the selected Provider.
+- [x] 2. Implement `money providers plaid link` for explicit Plaid linking.
+- [x] 3. Separate Provider support from Provider availability: list all Providers known to support the selected institution, mark locally unavailable Providers as missing credentials, and block selecting unavailable Providers with generated configure guidance.
+- [x] 4. Determine Provider availability from local config/env required fields, following Ray's configured-state pattern but using `money`'s explicit `env:` model.
+- [x] 5. Use Plaid `/institutions/search` with configured products and country codes for Plaid institution discovery.
+- [x] 6. Use a short-lived localhost Link page and callback server only for Plaid Link.
+- [x] 7. Create Plaid Link token with explicit products and country codes.
+- [x] 8. Serve a local page that loads Plaid Link with the link token and posts `public_token`, selected institution/account metadata, and random state back to the localhost helper on success.
+- [x] 9. Exchange public token for access token.
+- [x] 10. Store access token only after the encrypted store is open.
+- [x] 11. Store provider item, institution metadata, products, and initial cursor state.
+- [x] 12. Use random state/nonce values, timeout callback sessions, bind only for the active link flow, and shut down the helper after completion.
+- [x] 13. Follow GitHub CLI browser ergonomics in human mode: print the local Link URL, wait for Enter, then open the browser.
+- [x] 14. Support `--no-open` to print the URL without opening a browser for SSH, cron, and headless environments.
+- [x] 15. Do not automatically run the first sync after link; print help-derived guidance for running `money sync`.
+- [x] 16. Add tests for encrypted-store requirements and link exchange logic using fakes.
 
 Acceptance:
 
@@ -608,17 +608,17 @@ Goal: allow the user to create or reconnect Bridge items.
 
 Steps:
 
-1. Extend `money link` to choose Bridge when Bridge supports the selected Institution.
-2. Implement `money providers bridge link` for explicit Bridge linking.
-3. Use the same supported-versus-available Provider selection rules as Plaid.
-4. Create or reuse a Bridge external user ID.
-5. Create a Bridge connect session.
-6. Print the connect session URL, wait for Enter, then open the browser unless `--no-open` is set.
-7. Poll Bridge items until a new or reconnected item is available.
-8. Store provider item, institution metadata, status, and cursor state in the encrypted store.
-9. Do not automatically run the first sync after link; print help-derived guidance for running `money sync`.
-10. Add tests for Bridge connect/session/state logic using fakes.
-11. If Bridge institution discovery cannot be implemented cleanly in the first adapter, keep `money providers bridge link` working and defer institution-first Bridge selection rather than inventing unsupported discovery.
+- [x] 1. Defer Bridge institution-first selection until Bridge institution discovery is implemented cleanly; explicit `money providers bridge link` remains supported.
+- [x] 2. Implement `money providers bridge link` for explicit Bridge linking.
+- [x] 3. Use the same supported-versus-available Provider selection rules as Plaid.
+- [x] 4. Create or reuse a Bridge external user ID.
+- [x] 5. Create a Bridge connect session.
+- [x] 6. Print the connect session URL, wait for Enter, then open the browser unless `--no-open` is set.
+- [x] 7. Poll Bridge items until a new or reconnected item is available.
+- [x] 8. Store provider item, institution metadata, status, and cursor state in the encrypted store.
+- [x] 9. Do not automatically run the first sync after link; print help-derived guidance for running `money sync`.
+- [x] 10. Add tests for Bridge connect/session/state logic using fakes.
+- [x] 11. If Bridge institution discovery cannot be implemented cleanly in the first adapter, keep `money providers bridge link` working and defer institution-first Bridge selection rather than inventing unsupported discovery.
 
 Acceptance:
 
@@ -633,17 +633,17 @@ Goal: sync Plaid and Bridge accounts and transactions into canonical encrypted S
 
 Steps:
 
-1. Implement `money sync`.
-2. Load linked provider items from the store.
-3. Load provider access tokens from the encrypted store per item.
-4. Sync accounts first.
-5. Sync transactions using Plaid Transactions Sync cursors.
-6. Sync Bridge transactions using Bridge updated-at cursor/state.
-7. Upsert provider transactions by Provider Item plus provider-native transaction ID.
-8. Handle added, modified, and removed transactions.
-9. Store next cursor only after successful transaction processing.
-10. Record a sync run with counts and status.
-11. Add fixture-backed sync tests with fake Plaid client.
+- [x] 1. Implement `money sync`.
+- [x] 2. Load linked provider items from the store.
+- [x] 3. Load provider access tokens from the encrypted store per item.
+- [x] 4. Sync accounts first.
+- [x] 5. Sync transactions using Plaid Transactions Sync cursors.
+- [x] 6. Sync Bridge transactions using Bridge updated-at cursor/state.
+- [x] 7. Upsert provider transactions by Provider Item plus provider-native transaction ID.
+- [x] 8. Handle added, modified, and removed transactions.
+- [x] 9. Store next cursor only after successful transaction processing.
+- [x] 10. Record a sync run with counts and status.
+- [x] 11. Add fixture-backed sync tests with fake Plaid client.
 
 Acceptance:
 
@@ -668,29 +668,29 @@ Goal: make the first-milestone read Command Contracts reliable enough for extern
 
 Steps:
 
-1. Document `accounts.list`, `transactions.list`, `transactions.search`, `categories.list`, `tags.list`, and `recurring.list` schemas.
-2. Add pagination metadata.
-3. Add stable error codes.
-4. Add deterministic ordering:
+- [x] 1. Document `accounts.list`, `transactions.list`, `transactions.search`, `categories.list`, `tags.list`, and `recurring.list` schemas.
+- [x] 2. Add pagination metadata.
+- [x] 3. Add stable error codes.
+- [x] 4. Add deterministic ordering:
    - Accounts: hidden flag, type, name, id.
    - Transactions: date descending, pending status, id.
-5. Add filters for account, category, merchant, tag, date range, needs-review, pending, recurring status, and limit.
-6. Add command examples.
-7. Add compatibility notes for Monarch migration.
+- [x] 5. Add filters for account, category, merchant, tag, date range, needs-review, pending, recurring status, and limit.
+- [x] 6. Add command examples.
+- [x] 7. Add compatibility notes for Monarch migration.
 
 ### Phase 6: Sync Contract Hardening
 
 Goal: promote sync JSON from provisional to stable after real Provider behavior is understood.
 
 Steps:
 
-1. Document sync summary schema.
-2. Define provider error taxonomy.
-3. Define reconnect-required behavior.
-4. Define removed transaction policy as soft delete plus explicit confirmed cleanup.
-5. Define partial failure semantics and exit codes.
-6. Add fixture tests for Plaid and Bridge partial failures.
-7. Add command examples for cron usage.
+- [x] 1. Document sync summary schema.
+- [x] 2. Define provider error taxonomy.
+- [x] 3. Define reconnect-required behavior.
+- [x] 4. Define removed transaction policy as soft delete plus explicit confirmed cleanup.
+- [x] 5. Define partial failure semantics and exit codes.
+- [x] 6. Add fixture tests for Plaid and Bridge partial failures.
+- [x] 7. Add command examples for cron usage.
 
 Acceptance:
 
@@ -710,17 +710,18 @@ Acceptance:
 
 Goal: prove the Provider seam is real with a second adapter.
 
-Choose one:
+Selected path:
 
-- Monarch import from `monarchmoney-cli --json`.
-- CSV import.
-- MX or Finicity provider adapter.
+- [x] Bridge provider adapter as the second live Provider adapter alongside Plaid.
+- [x] Monarch import from `monarchmoney-cli --json` deferred.
+- [x] CSV import deferred.
+- [x] MX or Finicity provider adapter deferred.
 
 Acceptance:
 
-- A second adapter can write the same canonical tables.
-- Existing account and transaction contracts do not change.
-- Source/provider-specific fields remain namespaced or internal.
+- [x] A second adapter can write the same canonical tables.
+- [x] Existing account and transaction contracts do not change.
+- [x] Source/provider-specific fields remain namespaced or internal.
 
 ## Initial Schema Direction
 

README.md

@@ -12,7 +12,7 @@
   <a href="https://github.com/thedavidweng/money/actions"><img src="https://img.shields.io/github/actions/workflow/status/thedavidweng/money/ci.yml?branch=main&style=flat-square" alt="CI"></a>
   <a href="https://github.com/thedavidweng/money/releases"><img src="https://img.shields.io/github/v/release/thedavidweng/money?style=flat-square" alt="Release"></a>
   <a href="LICENSE"><img src="https://img.shields.io/github/license/thedavidweng/money?style=flat-square" alt="License"></a>
-  <img src="https://img.shields.io/badge/go-%3E%3D1.23-blue?style=flat-square" alt="Go">
+  <img src="https://img.shields.io/badge/go-%3E%3D1.25-blue?style=flat-square" alt="Go">
 </p>
 
 ---
@@ -38,13 +38,10 @@ Existing personal finance tools either lock data behind a paid SaaS, embed opini
 # Install
 go install github.com/thedavidweng/money/cmd/money@latest
 
-# Interactive setup — creates config, encryption key, and database
-money setup
-
 # Try it without real credentials
 money demo accounts list --json
 
-# After configuring a provider
+# After creating ~/.money/config.yaml and ~/.money/.env
 money link
 money sync
 money accounts list --json
@@ -62,13 +59,13 @@ money categories list        List transaction categories
 money tags list              List transaction tags
 money recurring list         List recurring transactions
 money link                   Link a financial institution
+money providers plaid link   Link a Plaid Provider Item
+money providers bridge link  Link a Bridge Provider Item
 money sync                   Sync linked provider data
 money demo <command>         Run against non-persistent sample data
-money doctor                 Check configuration health
-money setup                  Guided first-time configuration
 ```
 
-All commands support `--json` for machine-readable output. Write operations require `--dry-run` or `--confirm`.
+Read commands and provisional sync diagnostics support `--json` for machine-readable output. Manual write operations require `--dry-run` or `--confirm`.
 
 ## Architecture
 
@@ -98,6 +95,7 @@ Read commands use local data only. Sync is the explicit boundary where outbound
 |----------|---------|
 | [`docs/PRD.md`](docs/PRD.md) | Product requirements |
 | [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Module boundaries and data flow |
+| [`docs/CONTRACTS.md`](docs/CONTRACTS.md) | Current CLI JSON contracts |
 | [`docs/SCHEMA.md`](docs/SCHEMA.md) | Database schema contract |
 | [`docs/CONFIG.md`](docs/CONFIG.md) | Configuration loading rules |
 | [`docs/ROADMAP.md`](docs/ROADMAP.md) | Development phases |

docs/ARCHITECTURE.md

@@ -87,7 +87,7 @@ If a configured DB file already exists but cannot be opened, commands must repor
 
 The concrete encrypted SQLite implementation is an engineering decision. Select the approach through a short spike using these criteria: single-binary feasibility on the target platforms, active maintenance, predictable Go driver behavior, compatibility with SQLite migrations and in-memory demo tests, no plaintext fallback, and clear handling of key material. If no mature single-binary encrypted SQLite option satisfies those constraints, document the trade-off before accepting an external native dependency.
 
-The first implementation uses `github.com/ncruces/go-sqlite3` with its `database/sql` driver and the `github.com/ncruces/go-sqlite3/vfs/adiantum` encrypted VFS. This is the selected MVP path because it is cgo-free, supports app-managed 32-byte key material, keeps the CLI close to a single-binary distribution, works with normal SQLite migrations, and supports the in-memory demo path through the same SQLite implementation. Open encrypted databases with the encrypted VFS and set the key immediately after opening the connection using a PRAGMA rather than putting the key in the URI. Set `PRAGMA temp_store = memory` for encrypted real stores so temporary files do not become an accidental plaintext surface.
+The first implementation uses `github.com/ncruces/go-sqlite3` with its `database/sql` driver and the `github.com/ncruces/go-sqlite3/vfs/adiantum` encrypted VFS. This is the selected MVP path because it is cgo-free, supports app-managed 32-byte key material, keeps the CLI close to a single-binary distribution, works with normal SQLite migrations, and supports the in-memory demo path through the same SQLite implementation. Open encrypted databases with the encrypted VFS, pass the configured 32-byte key as the VFS `hexkey`, and set `temp_store(memory)` on the encrypted connection so temporary files do not become an accidental plaintext surface.
 
 This choice provides encryption at rest, not tamper-proof database authentication. The first version treats local tamper detection and signed backups as later hardening work, not a reason to add a custom encryption layer or ship plaintext fallback behavior. If the encrypted VFS fails the implementation spike on the target platforms, the next option is a SQLCipher-backed driver with the native dependency documented explicitly before adoption; do not replace whole-database encryption with ad hoc field encryption.