Everything written down about Hudson, organized by what you are trying to do.
| If you want to… | Read |
|---|---|
| Use Hudson | README.md |
| Work in this codebase (human or AI) | CLAUDE.md |
| Understand how it fits together | ARCHITECTURE.md |
| Run the Mac app | ui/running-the-app.md |
One page per module. Types, signatures, behavior, and the tests that cover it.
| Module | Owns |
|---|---|
| GmailKit | OAuth, Keychain, the Gmail API client, quota |
| Store | SQLite schema, migrations, reads/writes, FTS, queues |
| SyncEngine | Backfill, history polling, hydration, mutation flush |
| Outbox | MIME building, reply threading, the send state machine |
| AIKit | LLM providers, the egress choke point, the four AI features |
| HudsonCLI | The hudson executable and every subcommand |
| HudsonUI | SwiftUI views, view models, theme, keyboard routing |
The reasoning you cannot reconstruct from reading the code.
- Why the mailbox is a local database — backfill windows, cursor discipline, the version guard, and what local-first costs
- Why triage is a queue, not a write — instant archive that cannot corrupt server truth, and why the simpler designs fail
- How "no background AI egress" is enforced — a private initializer and a fail-closed opt-in, instead of a policy
- Add a CLI command
- Build and release — dev build →
.app→ signed, notarized DMG
- UI design brief — the design system
- Running the app — keyboard map, demo mode, screenshots
The spec is authoritative for intent. Code comments reference it by section
(§4.2, §7.3); milestone tags (M1–M7, U1, U2, D1) reference the
plans.
- Foundation system design — the spec
- Speed & AI architecture
- Seamless sharing & distribution
- Milestone plans — M1 auth · M2 store/backfill · M3 mutations · M4 query layer · M5 send · M7 AIKit · U1 SwiftUI shell · U2 compose · D1 onboarding
- STATUS.md — distribution state, credentials, known follow-ups
A doc that lies is worse than no doc. When you change behavior a page
describes, update the page in the same commit. The reference pages name the
files they describe, so git grep for a filename will find its docs.