feat: ledger-gui — a read-only, live desktop view of the books

egui/wgpu app for owners and their accountant: Overview, Cash, Profit,
Transactions (with rendered receipts and journal history), Reports
(statements with interval columns, comparisons, drill-down), Accounts,
Documents, Company, Journal; Ctrl+K palette; back/forward; light/dark.
Follows the journal live (~30 ms from write to screen). --demo opens a
deterministic demo company, also used for screenshot tests.

Engine: ledger-store Snapshot (read-only, incremental, tolerant of a
half-written tail); ledger-core analysis (intervals, balance series,
P&L by interval, cash flows); ledger-config extracted from ledger-mcp
with the full company profile and cash_accounts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MtYEaR6M6Ybdhm6X98BWNu

plan/STATUS.md

@@ -249,3 +249,21 @@ interface is MCP, not a cloned GUI. The first storage + MCP slice is done
   Journal events vendor.1099_set and entry.vendor_set. Schema v7. 64 tools.
   Also: requirements and parity no longer list finished R-FUTURE work as
   future (only budgets remain, declined).
+- 2026-10-12: ledger-gui, the read-only desktop view (egui 0.36, wgpu).
+  Overview (the answer in a sentence, KPI tiles with honest comparisons,
+  cash chart, needs-attention with copyable agent prompts, recent
+  activity), Cash (accounts, in/out, burn and runway, coming up), Profit
+  (by month with margin, spending vs. its recent average, by customer and
+  class), Transactions (search, filters, cash direction, detail with
+  lines, the rendered receipt via hayro, and journal history), Reports
+  (P&L, balance sheet, cash flow, owners' equity, trial balance, GL, tax
+  summary, 1099, agings; date presets, month/quarter/year columns, prior
+  period/year comparison, % of income, drill-down to the account register
+  for exactly those dates, copy as TSV), Accounts and registers,
+  Documents, Company, Journal (every event, hash, payload), Ctrl+K
+  palette, back/forward, light/dark. Live: notify-driven, ~30 ms from
+  write to screen. Engine additions: ledger-store Snapshot (read-only,
+  incremental, torn-tail tolerant), ledger-core analysis (intervals,
+  balance series and history, P&L by interval, flows), ledger-config
+  (extracted from ledger-mcp; full profile, cash_accounts). Fonts: Inter
+  with tnum frozen in and private-use glyphs removed (Phosphor icons).

plan/gui.md

@@ -0,0 +1,111 @@
+# ledger-gui — design
+
+Phase 4 of the roadmap. A desktop app (egui/eframe; web later) for the
+people who own the books and the accountant who checks them. Same
+audience as QuickBooks, none of its visual language.
+
+## What it is for
+
+It answers the questions an owner actually has, then shows the evidence:
+
+- **How much money do we have, and how long does it last?** Cash today,
+  the trend, burn, runway, what's coming due.
+- **Are we making money?** Revenue, spending, and profit by month; what
+  changed and why.
+- **Where does the money go?** Spending by category and vendor, over time.
+- **Who owes whom?** Payables, receivables, cards, money owed to members.
+- **Is anything wrong or missing?** Entries without receipts, drafts never
+  posted, unreconciled accounts, uncategorized tax lines, 1099 vendors with
+  no W-9, past periods left open, a journal that fails verification.
+- **Can I trust this number?** Every number drills down to the lines that
+  make it, each line to its entry, each entry to its rendered receipt and
+  its complete journal history (who did what, when, hash-chained).
+
+An accountant gets the same data at full depth: statements with interval
+columns and comparisons, the general ledger, trial balance, the raw
+journal with its verification status.
+
+## Principles
+
+1. **Answer first.** Every screen leads with the answer in words and one
+   big number, then the chart, then the table, then the raw data.
+2. **Everything drills down.** Any amount is a link. Navigation is a
+   history stack (back/forward, like a browser) with a breadcrumb.
+3. **All the data, nothing hidden.** Withdrawn attachments, reversals,
+   drafts, every journal event: visible, marked for what they are.
+4. **Read-only by construction.** The GUI has no write path: it reads the
+   hash-chained journal and the blob store and builds its own in-memory
+   view (`ledger_store::Snapshot`). Changes happen through the agent (MCP).
+   Where the GUI finds something to fix, it offers a ready-to-paste prompt
+   for the agent ("Attach the receipt for entry 12 — Anthropic, $5.82").
+5. **Live.** It follows the journal: a change made by the agent appears
+   within a second, highlighted as new.
+6. **Numbers are typography.** Tabular figures everywhere (Inter with
+   `tnum` frozen in), right-aligned, parentheses for negatives in
+   statements, a minus sign elsewhere, never a float.
+7. **No accounting logic in the GUI.** Statements, balances, and series
+   come from `ledger-core` (new reports land there, where MCP can use
+   them too). The GUI arranges and draws.
+
+## Screens
+
+- **Overview** — KPI tiles with sparkline and change vs. the prior period
+  (cash, runway, revenue, spending, net income, owed by / owed to);
+  cash over time; income vs. spending by month; spending by category;
+  needs-attention list; recent activity from the journal.
+- **Cash** — every cash and card account with balance and trend; inflows
+  and outflows by month; burn and runway; known upcoming outflows
+  (recurring entries, bills due, schedules).
+- **Profit** — P&L by month as chart and table, spending breakdown with
+  month-over-month change, by class.
+- **Transactions** — the register of every entry: search, filters
+  (account, vendor, class, date, status, receipt yes/no, amount), and a
+  detail pane with lines, the rendered receipt (PDF pages, images),
+  vendor, reversal links, and the entry's journal history.
+- **Reports** — P&L, balance sheet, cash flow, trial balance, general
+  ledger, members' equity, tax summary, A/R and A/P aging, 1099
+  worksheet. Date presets, interval columns (total / month / quarter /
+  year), comparison to the prior period or year. Every amount drills down.
+- **Accounts** — the chart with balances and tax categories; an account
+  opens its register with a running balance and a balance chart.
+- **Documents** — every receipt and company document, rendered, with its
+  category, entry link, and withdrawal status.
+- **Company** — profile, members and capital, periods, fixed assets,
+  amortization schedules, recurring entries, vendors and 1099 status.
+- **Journal** — the raw event log, filterable, each event expandable to
+  its JSON, with the hash-chain verification result.
+
+Global: command palette (Ctrl+K) to jump to any account, entry, vendor,
+document, or report; back/forward (Alt+←/→); light and dark themes.
+
+## Architecture
+
+- `ledger-store::Snapshot`: read-only. Verifies the journal chain,
+  replays it into a `Ledger`, projects it into an in-memory SQLite with
+  the same code the writer uses, reads blobs. `refresh()` applies only
+  new journal lines (or reloads if the file was rewritten).
+- `ledger-config` (moved out of `ledger-mcp`): `wanderbooks.toml`.
+- `ledger-gui`:
+  - `data` — a loader thread polls the journal and sends new snapshots.
+  - `model` — view models built from a snapshot (pure, unit-tested).
+  - `ui/*` — one module per screen; `widgets` (money, tiles, sparkline,
+    tables, charts); `theme`; `receipts` (PDF via `hayro`, images via
+    `image`; textures cached by blob hash).
+  - Tests: model unit tests, `egui_kittest` screenshots of every screen
+    against a fixture book.
+- Web build later: the model is plain data, so a server can ship it.
+
+## Status (2026-10-12)
+
+Built: every screen above, the palette, history, themes, live updates
+(tested end to end: a store write reaches the view model in ~30 ms),
+receipt rendering for PDFs and images, a deterministic demo company
+(`ledger-gui --demo`; also the screenshot fixture), and a screenshot test
+(`SHOT_DIR=… cargo test -p ledger-gui --test screens`, optionally
+`SHOT_BOOKS`, `SHOT_ONLY`, `SHOT_DARK`).
+
+Next, in rough order: a budget-free cash forecast with a confidence band;
+reconciliation view (cleared vs. uncleared per bank account); receipt
+zoom and multi-page navigation; keyboard navigation in lists;
+virtualized lists for very large books; the web build (ship the view
+model from a server).

plan/roadmap.md

@@ -31,7 +31,9 @@ The primary interface is MCP, not a cloned GUI (Stephen's call, 2026-10-10).
 - Done when: a fixture book produces byte-identical snapshots from both
   engines with zero manual steps.
 
-## Phase 4 — Read-only GUI
+## Phase 4 — Read-only GUI (first version done, 2026-10-12)
+
+`ledger-gui`: see `plan/gui.md` for the design and what's built.
 
 - Consumes the `ledger-store` event log: live updates — the answer to
   "watch its files to update live."