Merge branch 'main' into website

docs/handoff/20260612-handoff-68.md

@@ -0,0 +1,173 @@
+# Session handoff — 2026-06-12 (68)
+
+Sixty-eighth handover. Continues directly from handoff-67 (which
+triaged a manual-testing pass into fixes + filed issues). This was an
+**issue-burndown session**: six Gitea issues closed across five
+commits, each landed with the full phased workflow + a `/runda` +
+Devil's-Advocate pass before commit. Net: **six issues closed, five
+commits, +29 tests, zero regressions.**
+
+## §1. State at handoff
+
+**Branch:** `main`. Working tree **clean**; all work committed.
+**Five unpushed commits** (push is the user's step).
+
+**Tests: 2436 passing / 0 failing / 0 skipped / 1 ignored** (the
+long-standing `friendly` doctest). **Clippy clean** (nursery, all
+targets). Breakdown: 1730 lib + 506 integration (`it`) + 200
+typing-surface-matrix. +29 over handoff-67's 2407.
+
+**Commits since handoff-67:**
+```
+ee3ccd8 feat(hint): advertise the optional seed count in the hint panel (#26)
+deb0948 feat(seed): year-as-int + conventional choice-set heuristics (#33, #34)
+fde50ce fix(ui): mark sidebar focus with an accent colour, not bold (#25)
+3d4a0fd fix(render): trim IEEE-754 noise from displayed decimal arithmetic (#32)
+7e4bc12 fix(completion): treat a bare in-scope table alias as an alias, not an unknown column (#31)
+```
+
+## §2. Issues closed this session (all committed, all tested, all `/runda`-reviewed)
+
+Each closed on `git.lazyeval.net/oli/rdbms-playground` with a summary
+comment. The `/runda` pass earned its keep on every one — see the
+"DA caught" notes.
+
+1. **#31 (`7e4bc12`) — bare table alias treated as unknown column.**
+   A bare in-scope table alias in a SQL expression (`… GROUP BY o`,
+   `o` aliasing `FROM Orders o`) got `no such column o on table …` and
+   zero completions. Now: completion offers each FROM source's
+   *qualifier* (alias-if-present-else-table) at a bare `sql_expr_ident`
+   slot; the `matched.len()==0` arm emits a targeted
+   `alias_used_as_column` / `table_used_as_column` hint after the
+   projection-alias check. **DA caught** two real bugs pre-commit: a
+   DSL leak (the hint fired for simple-mode `expr_column` refs, which
+   have no `table.column` syntax) and wrong advice for an
+   aliased-table-by-real-name — both fixed by gating on
+   `role == "sql_expr_ident"` + matching the *effective qualifier*.
+   ADR-0032 Amendment 3.
+
+2. **#32 (`3d4a0fd`) — decimal aggregation float noise.** `decimal`
+   is exact TEXT, but SQLite has no decimal type, so arithmetic
+   coerces to IEEE-754 double; `sum(price*qty)` rendered
+   `298.59999999999997`. Now `format_real_display` (db.rs) rounds REAL
+   to 15 sig figs **for display only**, wired into `format_cell`.
+   **DA caught** a real regression: I'd also wired it into
+   `render_value`, which is a *canonical identity key* for the
+   uniqueness dry-runs (`dry_run_unique`, `check_uniqueness_collisions`)
+   — rounding there would report collisions the exact-valued engine
+   wouldn't. Reverted `render_value` to exact; locked with a
+   regression test. CSV/FK-key/EXPLAIN paths stay exact. ADR-0005
+   Amendment 1.
+
+3. **#25 (`fde50ce`) — sidebar focus accent colour, not bold.** Bold
+   box-drawing glyphs render broken in asciinema casts.
+   `panel_border_style` now uses a non-bold accent colour
+   (`theme.mode_simple`); bold stays fine on text spans. **DA caught**
+   that the issue's "Tier-2 snapshots need re-accepting" was wrong —
+   `render_to_string` is text-only, so no snapshot changed. Added a
+   render-level test that inspects the actual border *cells*.
+   User visually confirmed. ADR-0046 Amendment 1.
+
+4. **#33 + #34 (`deb0948`) — seed heuristics: year-as-int + choice
+   sets.** Two additive D7 catalogue rules. **#33:** `year`/`*_year`/
+   `published`/`founded` → bounded `int` year (1950–2025, or the
+   `dob`-style birth window 1945–2007 for `birth`/`born`/`dob`); new
+   `YearRecent`/`YearBirth` generators. Placed *after* the quantity
+   rule so `year_count` stays a count. **#34:** type-gated `PickFrom`
+   sets for `priority`/`prio`, `severity`, `rating`/`stars`; `status`
+   **deliberately excluded** (user-confirmed on the issue — values too
+   domain-specific). `priority` left `ENUM_TOKENS`. A user `IN`-CHECK
+   still wins. **DA/process caught** that I'd skipped reading the issue
+   *comments* (where the `status` decision + a website cast note lived)
+   — **lesson: always read issue comments**. Also closed a
+   pre-existing column-fill integration-test gap. ADR-0048 Amendment 1.
+
+5. **#26 (`ee3ccd8`) — optional `count` advertised in the hint panel.**
+   At `seed <table> ▮` only `set`/`--seed` chips showed; the optional
+   row count (a bare positional number) was invisible, and the prior
+   `IntroProse` attempt was reverted because `pending_hint_mode` is
+   cleared by the trailing optionals. Now `walk_optional` stashes a
+   skipped inner's `IntroProse` key into a new
+   `WalkContext.surviving_intro_hint` (key + position) before the empty
+   match clears it; a **position guard** (`pos == cursor`) stops it
+   leaking past a later `set …` clause or once the count is given. Tab
+   still cycles the keywords. Prose mentions the count, `.column`
+   column-fill, `set`, and `--seed` (user-chosen scope). **DA caught**
+   a coverage gap (advanced-mode path untested — seed runs in both
+   modes); added the test. ADR-0022 Amendment 7.
+
+## §3. Open issues — next session's candidates
+
+Four open, all on `git.lazyeval.net/oli/rdbms-playground`. **All four
+are interaction/UX design changes that need a decision or two from the
+user up front — none is a pure mechanical fix.** Read each issue body
+**and its comments** before starting (the #33/#34 lesson).
+
+- **#28 — Reconsider relationship prose in `add column` (incidental
+  DDL) confirmations** *(enhancement)*. **Revisits a decided area** →
+  needs a **new ADR** superseding the relevant part of ADR-0016 §5 /
+  ADR-0044 §1. User preference (from the issue): do **not** show the
+  `References:` / `Referenced by:` block in the add-column
+  confirmation. Confirm scope with the user (just `add column`, or all
+  incidental DDL). The highest-ceremony of the four.
+
+- **#27 — Bottom status line: keybindings-only, context- and
+  state-aware; add `mode advanced` to empty hint** *(enhancement)*.
+  Per-nav-focus keybindings (Input vs sidebar), **including transient
+  states** (Tab-cycle, history) per user preference. May warrant a
+  small ADR. Touches `src/ui.rs` rendering + the nav-focus model
+  (ADR-0046).
+
+- **#29 — Command input keystroke support.** Esc / double-Esc to clear
+  a partly-typed command; possibly Ctrl-A/Ctrl-E (Home/End). Relates
+  to the deferred **I1b readline shortcuts** (`requirements.md`).
+  **Needs a key-set decision** from the user before coding.
+
+- **#30 — History brings back all commands in both modes.**
+  Advanced-mode history entries can't replay in simple mode; proposal:
+  if we can distinguish them, prepend `:` to reuse advanced history
+  from simple mode. Interaction design; touches the input-history +
+  mode model (ADR-0003).
+
+No strong ordering. **#28** is the only one that *must* produce an ADR.
+**#29** is closest to "small once the key-set is decided." **#27** and
+**#30** are medium UX work.
+
+## §4. Carried-over follow-up (not a `main`-branch task)
+
+- **Website `seed` cast re-record** (from #34's comment thread). The
+  `website` branch ships a `seed` cast exercising a `tickets` table
+  with `priority`; now that `priority` collapses to `low/medium/high`,
+  the cast should be re-recorded (`cd website && pnpm casts seed`,
+  needs a `../target/debug` binary) so the table tightens. The issue
+  comment notes it is **likely redundant** — casts get a full
+  re-record sweep before publication. Tracked on the `website` branch,
+  **not** here. `website/` is not in the `main` tree.
+
+## §5. Other open roadmap (unchanged from handoff-67 §5)
+
+`seed` is feature-complete (`requirements.md` SD1/SD2 `[x]`, now with
+the #33/#34 catalogue refinements noted inline). User's call:
+
+- **H2 `hint`** — the last A1 gap (its own ADR).
+- **TT5 CI** — test infra exists; no CI workflow yet (the `ci` branch
+  exists — check its state before starting).
+- **TT4 PTY (Tier-4)** — ADR-0008 specifies it; not wired.
+- Larger: **V4 journal**, **tutorial/lesson system** (each needs an ADR).
+
+## §6. How to take over
+
+1. Read handoffs 66 → 67 → 68, `CLAUDE.md`, `docs/requirements.md`.
+2. Confirm green baseline: `cargo test` (expect 2436 pass / 1 ignored)
+   + `cargo clippy --all-targets` (clean).
+3. Pick from §3 (#28/#27/#29/#30). **For each, read the issue body AND
+   its comments** before designing, and **escalate the design fork to
+   the user** before coding — all four have genuine UX decisions. #28
+   needs a new ADR.
+4. Follow the project workflow: phased (requirements → divergent →
+   eval → execute → verify), test-first (failing test before the fix),
+   `/runda` + DA pass before every commit, ADR amendment for any
+   decided-area change + the README index-upkeep rule, and confirm the
+   commit message with the user before committing.
+5. Consider a `cargo sweep` at this milestone (`target/` grows across
+   sessions; see CLAUDE.md "Build hygiene").

docs/handoff/20260614-handoff-69.md

@@ -0,0 +1,203 @@
+# Session handoff — 2026-06-14 (69)
+
+Sixty-ninth handover. Continues from handoff-68 (an issue-burndown that
+closed #25/#26/#31/#32/#33/#34). This session **closed the four
+remaining open issues** — #29, #28, #27, #30 — each landed with the full
+phased workflow + `/runda` + Devil's-Advocate passes before commit, and
+each producing a new ADR. Net: **four issues closed, four commits, four
+new ADRs (0049–0052), +63 tests, zero regressions, the tracker is now
+empty.**
+
+The four interlock: **#29** added the input-field readline keys, **#27**
+advertises them in a state-aware status strip, and **#30**'s history
+recall now respects modes. **#30** also turned into a real architecture
+change (journaling relocation) — read §2.4 carefully before touching that
+area.
+
+## §1. State at handoff
+
+**Branch:** `main`. Working tree **clean**; all work committed. The two
+most recent commits are local (normal working state — push is the user's
+step).
+
+**Tests: 2471 passing / 0 failing / 0 skipped / 1 ignored** (the
+long-standing `friendly` doctest). **Clippy clean** (nursery, all
+targets). Breakdown: 1771 lib + 500 integration (`it`) + 200
+typing-surface-matrix. **+35 over handoff-68's 2436** (net: #29 +22, #28
++0, #27 +9, #30 +4 — its new history.rs/app.rs/iteration6 tests minus the
+15 retired worker-journaling tests; trust the live `cargo test` count).
+
+**Commits this session:**
+```
+4aeea55 feat(history): mode-tagged history + top-of-chain journaling (#30)
+eceedc1 feat(ui): context- and state-aware bottom keybinding strip (#27)
+8ac3537 feat(render): incidental-DDL confirmations show structure only, no relationships (#28)
+66c8bda feat(input): readline keymap — Esc-clear + Ctrl-A/E/W/K/U (#29)
+```
+
+**Open Gitea issues: none.** `tea issues list --state open` is empty.
+
+## §2. Issues closed this session (all committed, tested, `/runda`-reviewed)
+
+Each closed on `git.lazyeval.net/oli/rdbms-playground` with a summary
+comment.
+
+### 2.1 — #29 (`66c8bda`) — input-field readline keymap (ADR-0049)
+
+Implements the deferred **I1b** readline shortcuts: `Esc` clears a
+partly-typed command (only when no completion memo is alive — the memo
+wins first, ADR-0022); `Ctrl-A`/`Ctrl-E` = Home/End; `Ctrl-W` deletes
+the previous word (readline-style, UTF-8 safe); `Ctrl-K`/`Ctrl-U` kill to
+end/start. Cursor-only keys leave history nav intact; buffer-mutating
+keys end it. **DA caught** the need for the `Ctrl-O`+`Esc` (sidebar
+nav-exit) interaction not to clear the draft — locked with a regression
+test. `requirements.md` I1b → `[x]`.
+
+### 2.2 — #28 (`8ac3537`) — incidental-DDL confirmations: structure-only (ADR-0050)
+
+Incidental-DDL confirmation echoes (`create table`, `add`/`drop`/
+`rename`/`change column`, `add`/`drop index`) now render **structure
+only** — no `References:` / `Referenced by:` block. Relationship-subject
+surfaces (`show table`, `add`/`drop relationship`) keep their ADR-0044
+diagrams. The prose renderer (`relationship_prose_lines` + `cols_disp`)
+was deleted. **Supersedes** ADR-0044 §1's incidental-DDL prose clause and
+the relationship-block half of ADR-0016 §5 (both annotated).
+
+### 2.3 — #27 (`eceedc1`) — context- and state-aware keybinding strip (ADR-0051)
+
+The bottom status line is now keystrokes-only and **state-selected** by
+priority (sidebar focus / completion-memo / history-nav / editing /
+default). The editing state surfaces the #29 keys (closing ADR-0049's
+deferred advertisement). Mode-switch advertisements left the strip; the
+empty-input hint gained a simple-mode `` `mode advanced` for SQL `` pointer
+(advanced mode shows none — user decision). New `App::is_browsing_history()`
+exposes the private `history_cursor`. 15 full-panel snapshots re-accepted.
+
+### 2.4 — #30 (`4aeea55`) — mode-tagged history + top-of-chain journaling (ADR-0052) **← read before touching journaling**
+
+Closed both the feature (advanced history reusable in simple mode) and
+the bug (the `:` one-shot prefix lost across sessions). Two halves:
+
+1. **Mode-tagged history.** The `history.log` status token gains an
+   optional `:adv` suffix (`ok` / `ok:adv` / `err` / `err:adv`); `source`
+   stays last + canonical so replay is unaffected. The in-memory ring
+   (still `Vec<String>`) stores advanced entries in their `: `-prefixed
+   simple-mode runnable form; recall **strips the `:` in advanced mode**
+   and keeps it in simple; hydration reconstructs the prefix from the tag.
+   App commands journal simple and are excluded from the ring's advanced
+   flag, so they recall bare.
+
+2. **Journaling relocation (the architecture change).** Success
+   journaling **moved out of the worker** to the dispatch layer
+   (`spawn_dsl_dispatch` / `run_replay` / the app-command sites), next to
+   the already-top-level failure journaling — so the submission mode is in
+   scope with no worker plumbing. `finalize_persistence` now writes only
+   the **state** sources (yaml/csv); the journal write is **best-effort**
+   (the command is already committed — consistent with the failure path).
+   **Amends ADR-0015 §6** (history.log out of the worker tx; commit-db-last
+   scopes yaml/csv/db only), **ADR-0034** (status tag + journaling
+   location), **ADR-0040** (journal-write best-effort, not fatal).
+
+   **Two DA findings, both resolved:** (a) the app-command `advanced` flag
+   must exclude app commands (else `: save as` diverges); (b) the spawn
+   journals on `outcome.is_ok()`, so journaling is now **uniform** — read
+   commands that didn't journal before (`show tables`/`show relationships`/
+   `show indexes`, `show relationship <name>`, `explain`) now do, matching
+   ADR-0034 §1. **User-confirmed** as the more-correct behaviour (harmless
+   on replay — reads/`explain` don't mutate).
+
+   **Test migration:** 15 worker-level journaling tests were retired (the
+   worker no longer journals — their yaml/csv/operation assertions were
+   kept) and re-covered at the new layer: `history.rs` status-tag +
+   `:`-reconstruct; `app.rs` recall matrix; the cross-session regression
+   `advanced_command_journalled_then_hydrated_recalls_with_colon_in_simple`
+   in `iteration6_resume_history`; the replay tests cover `run_replay`
+   journaling.
+
+   Plan: `docs/plans/20260613-issue-30-top-of-chain-journaling.md`.
+
+## §3. Next session — start here
+
+The user's stated plan for the next session, in order:
+
+1. **Pick up the ADR-0052 follow-up** (below).
+2. **Check for any newly-filed open issues** (`tea issues list --state
+   open`) — none at handoff, but check fresh.
+3. **Then** take on remaining open tasks from the general requirements
+   (`docs/requirements.md`) — see §5.
+
+### The ADR-0052 follow-up — unwind the vestigial worker `source` plumbing
+
+When journaling moved out of the worker, the `source` that the worker
+threaded purely for journaling became dead. To avoid orphaning the param
+across ~28 handlers, the refactor **left it in place** as vestigial:
+
+- `finalize_persistence(conn, persistence, _source, changes)` — the
+  `_source` param is now unused (kept so its ~28 callers still pass
+  `source`, which they otherwise also use for `snapshot_then`).
+- `do_rebuild_from_text(conn, _persistence, _source, project_path)` —
+  both `_persistence` and `_source` vestigial.
+- Three thin read-only wrappers in `db.rs` —
+  `do_describe_table_request`, `do_query_data_request`,
+  `do_run_select_request` — now just delegate to their non-`_request`
+  twin (`do_describe_table` / `do_query_data` / `do_run_select`) with
+  vestigial `_persistence` / `_source` params and one caller each
+  (`db.rs` Request arms ~2409 / ~2749 / ~2759).
+
+**The cleanup:** remove `_source` from `finalize_persistence` + drop the
+arg at its ~28 callers (the callers keep `source` for `snapshot_then`, so
+only the `finalize_persistence(...)` call loses the arg); remove the
+`_persistence`/`_source` params from `do_rebuild_from_text`; and inline
+the three `*_request` wrappers at their single call sites (replace
+`do_describe_table_request(conn, persistence, source, name)` with
+`do_describe_table(conn, &name)`, etc.), deleting the wrappers. Purely
+mechanical, compiler-guided, no behaviour change. Establish the green
+baseline first (`cargo test`), then verify nothing moved.
+
+## §4. Carried-over follow-up (website branch, not `main`)
+
+- **Website `seed` cast re-record** (from #34, handoff-68 §4) — still
+  tracked on the `website` branch, not here. Likely redundant (full
+  re-record sweep before publication).
+
+## §5. Remaining roadmap — `docs/requirements.md` (next session's §3-step 3)
+
+With the issue tracker empty, the next work comes from the document-based
+requirements. Open / partial items worth weighing (the user picks):
+
+- **H2 `hint`** — the last A1 gap (contextual help for the current
+  command); its own ADR. (`requirements.md` H2.)
+- **TT5 CI** — runs all tiers on Linux/macOS/Windows; no CI workflow yet
+  (a `ci` branch reportedly exists — check its state first). Couples with
+  **D1–D3** (cross-platform prebuilt binaries + Homebrew/Scoop).
+- **TT4 PTY (Tier-4)** — ADR-0008 specifies the PTY harness + four
+  critical flows; still not wired (no PTY deps/tests).
+- **I1 multi-line input** (Ctrl-Enter submits, Enter inserts newline) and
+  **I5 / B3 in-flight cancellation** (Ctrl-C cancels a running command).
+- **V4 session journal** — scrollable per-session log + Markdown export
+  (the bigger UX project; own ADR).
+- **TU1 tutorial / lesson system** — design + ADR pending (acknowledged
+  in scope).
+- Smaller partials: **C3a** modify relationship (drop+add covers it
+  today), **C4** m:n convenience, **V3** ER-diagram export, the **NFR-***
+  performance/visual targets (mostly unmeasured), **N4** global rolling
+  history (OOS for v1).
+
+No strong ordering — these are the user's call. Several need a new ADR
+(H2, V4, TU1); CI/release (TT5/D1–D3) is the most "shippable-product"
+track if that's the priority.
+
+## §6. How to take over
+
+1. Read handoffs 67 → 68 → 69, `CLAUDE.md`, `docs/requirements.md`.
+2. Confirm green baseline: `cargo test` (expect **2471 pass / 1 ignored**)
+   + `cargo clippy --all-targets` (clean).
+3. `tea issues list --state open` — pick up anything new first.
+4. Then the ADR-0052 follow-up (§3), then requirements (§5).
+5. Follow the project workflow: phased (requirements → divergent → eval →
+   execute → verify), test-first, `/runda` + DA pass before every commit,
+   ADR amendment for any decided-area change + the README index-upkeep
+   rule, and confirm the commit message with the user before committing.
+6. Consider a `cargo sweep` at this milestone (`target/` grows across
+   sessions; see CLAUDE.md "Build hygiene"). (`sweep.timestamp` was
+   removed this session.)

docs/handoff/20260615-handoff-70.md

@@ -0,0 +1,165 @@
+# Session handoff — 2026-06-15 (70)
+
+Seventieth handover. Continues from handoff-69 (which closed the last
+four Gitea issues and left the tracker empty). This session did the
+**ADR-0052 follow-up** (unwinding vestigial worker `source` plumbing),
+then **designed and fully implemented H2 — the contextual `hint`
+command + F1 keybinding (ADR-0053)** end to end (Phases A–D). The CI
+branch was also merged into `main` mid-session (not my work — see §5).
+
+Net: **2 feature areas shipped, 1 new ADR (0053) + 1 ADR amendment
+(0052), 4 new Gitea issues (#35–#38), the `hint` corpus (~57 teaching
+blocks), and A1 + H2 closed in `requirements.md`.**
+
+## §1. State at handoff
+
+**Branch:** `main`. Working tree **clean**; all work committed. Commits
+are local (push is the user's step).
+
+**Tests: 2499 passing / 0 failing / 0 skipped / 1 ignored** (the
+long-standing `friendly` doctest). **Clippy clean** (nursery, all
+targets). Breakdown: 1799 lib + 500 `it` + 200 typing-surface-matrix.
+
+**Open Gitea issues (4, all enhancement, all filed this session):**
+- **#35** — enforce `cargo fmt` across the codebase (single reformat +
+  CI gate). The tree is *not* fmt-clean (~1800 pre-existing diffs); do it
+  once, coordinated with CI, before first publication.
+- **#36** — `help` collapses advanced-SQL forms onto their simple sibling
+  (a `help`-list dedup artifact); they deserve distinct help content.
+- **#37** — `hint` clause-concept hints (`on delete` actions, constraint
+  slots, `with pk`, cardinality) — a deferred `hint.concept.<topic>`
+  layer.
+- **#38** — `hint` pre-submit-diagnostic route + the ~33 `diagnostic.*`
+  tier-3 blocks (deferred; `Diagnostic` carries no class key).
+
+## §2. ADR-0052 follow-up — vestigial worker `source` unwind (`e8fa859`)
+
+The first task from handoff-69 §3. ADR-0052 moved success-journaling out
+of the worker, leaving the `source` that handlers threaded purely for the
+old `history.log` write dead. **Bigger than the handoff estimated** (it
+framed it as ~28 call-site edits): the cascade ran through ~30 worker
+handlers + the `DescribeTable`/`QueryData`/`RunSelect` request fields +
+their `DatabaseHandle` methods (~164 mostly-test call sites). Fully
+unwound, compiler-guided, **no behaviour change** (journaling uses a
+`source_for_journal` clone at the spawn, independent of the worker). The
+only worker `source` left is the snapshot/undo label. Amended ADR-0052
+*Consequences* + README. (Two scope forks escalated + user-approved.)
+
+## §3. H2 — contextual `hint` (ADR-0053), Phases A–D — **shipped**
+
+The bulk of the session. ADR-0053 settles the `hint` slot ADR-0003 left
+"ADR pending"; **closes A1** (all 15 app commands now exist) and
+**requirements H2**. Read ADR-0053 before touching this area — it went
+through three revisions and several user decisions.
+
+### The design (all user-chosen)
+- **Two surfaces:** an **F1 keybinding** → tier-3 hint for the *live*
+  partial input (read-only overlay — never touches buffer/cursor/memo);
+  a submitted **`hint` command** → expands on the *most recent runtime
+  error*. No topic arg (contextual only; `help <topic>` owns reference).
+- **Tier-3 teaching layer** beneath the existing tier-1 (colour / error
+  headline) and tier-2 (ambient one-liner; the error `hint:` shown **by
+  default** since `Verbosity::Verbose` is the default). Each block is
+  `what` / `example` / `concept`, rendered as a `Hint` heading + aligned
+  labels.
+- **Per-form keying** (Phase-B revision — the original per-node `hint_id`
+  was too coarse for multi-form commands like `add`/`drop`/`show`): a new
+  **`hint_ids: &[&str]`** field on `CommandNode` mirroring `usage_ids`,
+  resolved by `hint_key_for_input_in_mode` (reuses `usage_key`'s
+  form-word disambiguation + a mode-primary fallback for shared entry
+  words so advanced `insert` → `sql_insert`, simple → `insert`).
+- **Comprehensive for v1 = command forms + 9 runtime error classes**
+  (the ~33 `diagnostic.*` classes were **deferred**, #38 — see §4).
+
+### Key files
+- `src/dsl/command.rs` — `AppCommand::Hint`.
+- `src/dsl/grammar/app.rs` — `HINT` node + `build_hint`.
+- `src/dsl/grammar/mod.rs` — the `hint_ids` field, `hint_key_for_input_in_mode`,
+  the factored `pick_form_key`, and the two **comprehensiveness coverage
+  tests** (every node has a resolving `hint.cmd.*`; every runtime error
+  class has a `hint.err.*`).
+- `src/app.rs` — F1 arm in `handle_key` (read-only overlay, placed before
+  the completion-memo clear); `note_hint_for_input` / `note_hint_for_recent_error`
+  / `note_getting_started` / `emit_tier3_block`; `last_error_hint_key`
+  state (set in `handle_dsl_failure`, cleared in `submit` for DSL
+  commands).
+- `src/friendly/translate.rs` — `error_hint_class` (maps a `DbError` +
+  ctx to its `hint.err.<class>`; mirrors `translate`'s dispatch — keep in
+  sync, unit-tested).
+- `src/friendly/strings/en-US.yaml` + `keys.rs` — the corpus under
+  `hint.cmd.<form>` / `hint.err.<class>` + `hint.block.*` labels +
+  `shortcut.hint`.
+- `src/ui.rs` — ADR-0051 strip advertises **F1** (editing + default
+  states); 12 full-panel snapshots re-accepted.
+
+### Phases (one commit each unless noted)
+- **A** (`050b363`) skeleton + tier-2 fallback; **B** (`4a5fd1b`) per-form
+  keying + 3 exemplars; **C** content in 5 batches (`4bdfce6` app,
+  `6429b56` DDL, `9c4d520` DML, `97970f2` advanced-SQL, `b6b98ad` runtime
+  errors) + `417cbc8` diagnostic deferral; **D** (`447112b`) coverage gate
+  + F1 strip + status flips; **/runda fix** (`329adfc`) — see §3.1.
+
+### 3.1 — what the final `/runda` caught (don't skip)
+Per-batch substring tests masked a **presentation gap**: `emit_tier3_block`
+was emitting three *bare, unlabelled* lines, deviating from the approved
+exemplar format. Fixed to render a `Hint` heading + aligned `What:` /
+`Example:` / `Concept:` lines, **locked by an `insta` snapshot**
+(`hint_block_insert`). Also confirmed the `Next:` line (ADR D2 exemplar)
+is correctly **omitted** — tier-2 ambient already owns live
+position-awareness. Lesson for the next content/UI work: **add a rendered
+snapshot early**; substring asserts don't see layout.
+
+## §4. Deferrals (all tracked, all user-confirmed)
+
+- **#38 diagnostic route + `diagnostic.*` blocks** — `Diagnostic`
+  (`walker/outcome.rs`) carries only its rendered `message`, not a class
+  key, so the F1 diagnostic route would need a `class` field threaded
+  through every diagnostic site (broad) for marginal value (tier-2
+  already surfaces diagnostics; many duplicate runtime classes). F1 still
+  shows the useful command block when a diagnostic is present.
+- **#37 clause-concept hints** — per-form is the right tier-3 granularity;
+  clause-level concepts are a separate `hint.concept.<topic>` layer for
+  later.
+- **#36 `help` advanced-SQL** — out of H2's scope (touches shipped `help`).
+
+## §5. CI branch merged into `main` (not my work)
+
+Mid-session the **`ci` branch was merged** (commits `47a0816`, `138e766`
++ the `ci:`/`build:`/`docs(ci):` commits). `main` now carries a CI
+pipeline, a nix flake, and **D1 cross-platform release builds** (matrix +
+macOS), documented under a **new `docs/ci/adr/` namespace** (ci-001..003).
+Implications for the roadmap: **D1 (cross-platform binaries) is now
+substantially underway** — re-assess D1/D2/D3 status against what landed
+before treating them as open. My H2 work is layered cleanly on top (all
+green post-merge).
+
+## §6. Next session — start here
+
+1. **Push** (user step) — 30-odd local commits incl. the CI merge + all
+   of H2.
+2. **Re-baseline the roadmap** against the merged CI work: D1/D2/D3 and
+   **TT5 CI** are partly/largely done now — read `docs/ci/adr/` and the
+   workflows before assuming they're open (handoff-69 §5 predates this).
+3. **#35 (cargo fmt gate)** is the natural pairing with the now-merged CI
+   — the user wanted it done once, before first publication.
+4. Other `requirements.md` open items (verify against CI merge first):
+   **TT4** PTY tier-4 (still unwired), **I1** multi-line input, **I5/B3**
+   in-flight cancellation, **V4** session journal (own ADR), **TU1**
+   tutorial system (own ADR). H2/A1 are now **done**.
+5. The H2 deferrals (#36/#37/#38) are available if the user wants to
+   round out the hint/help surface.
+
+## §7. How to take over
+
+1. Read handoffs 68 → 69 → 70, `CLAUDE.md`, `docs/requirements.md`.
+2. Confirm green: `cargo test` (expect **2499 pass / 1 ignored**) +
+   `cargo clippy --all-targets` (clean).
+3. Read `docs/ci/adr/` (the merged CI work) before touching CI/release/D*.
+4. For anything in the `hint` area, read **ADR-0053** first (3 revisions
+   + deferrals #37/#38). For journaling, ADR-0052 (+ its 2026-06-14
+   follow-up note).
+5. Project workflow unchanged: phased, test-first, `/runda` + DA before
+   commits, ADR amendment + README index-upkeep for decided-area changes,
+   confirm commit messages with the user.
+6. Consider a `cargo sweep` at this milestone (`target/` grows; see
+   CLAUDE.md "Build hygiene").

docs/handoff/20260615-handoff-71.md

@@ -0,0 +1,120 @@
+# Session handoff — 2026-06-15 (71)
+
+Short, focused handover. Continues immediately from handoff-70 (which
+shipped H2 / the contextual `hint`, ADR-0053). **A user smoke-test
+surfaced a correctness bug in the hint content, and it implicates the
+whole corpus.** This handoff exists so the next session does a
+**systematic semantic verification pass over every hint block** — context
+ran too low to do it now.
+
+## §1. State
+
+**Branch:** `main`, clean, all committed (local; push pending). **2499
+pass / 1 ignored, clippy clean.** Open issues: #35–#38 (see handoff-70).
+H2 / ADR-0053 is *functionally* complete; the **content is not
+trustworthy** until the pass below is done.
+
+## §2. The bug (confirmed)
+
+`hint.cmd.create_table` (in `src/friendly/strings/en-US.yaml`) reads:
+
+```
+What:    Create a new table — its columns, their types, and a primary key.
+Example: create table Customers with pk id(serial), name(text), email(text)
+Concept: A table is a set of rows that share the same columns. The primary
+         key uniquely identifies each row; a `serial` key numbers the rows for you.
+```
+
+**This is wrong.** In the DSL, **everything after `with pk` is the
+primary-key column list** (a possibly *compound* PK, ADR-0005). So the
+example does **not** create a table with `pk=id` plus regular columns
+`name`/`email` — it creates a table whose **compound primary key is
+(id, name, email)**. Non-key columns are added *separately* with
+`add column`. The `what` ("its columns, their types") and the example
+both mislead a learner badly.
+
+- **Evidence:** real test usage is `create table Orders with pk
+  id(serial), CustId(int)` (a 2-column *compound PK*) and the common form
+  `create table X with pk id(int)` (single-column PK only). The usage
+  template `create table <Name> with pk [<col>(<type>)[, ...]]` is itself
+  misleading — the `[, ...]` is the PK list, not regular columns.
+- **Correct mental model:** `create table <T> with pk <pk-cols…>` then
+  `add column <T>: <name> (<type>)` for each non-key column. Confirm
+  against ADR-0005 (compound PK) and ADR-0009 (DSL syntax) when fixing.
+
+## §3. Root cause — why this needs a *full* pass
+
+During Phase C I verified *some* examples against `parse.usage.*`
+templates and real test greps, but for others I **extrapolated** beyond
+verified syntax. For `create_table` I saw `... with pk id(int)` (single
+col) and wrongly generalised to "pk + more columns," misreading the
+`with pk` list as a column list. The examples are **syntactically**
+checked but not **semantically** — i.e. not verified to *do what the
+`what`/`concept` claims*.
+
+So the corpus needs a pass that, for **every** `hint.cmd.*` and
+`hint.err.*` block, checks:
+1. the `example` parses **and runs**, and
+2. it actually demonstrates what `what`/`concept` says, and
+3. `what`/`concept` are factually true of the real behaviour.
+
+**Don't trust grep+extrapolation.** Prefer: run the example in the app
+(or a Tier-3 test), or check it against the authoritative ADR.
+
+## §4. The pass — how to do it (next session)
+
+The corpus lives in `src/friendly/strings/en-US.yaml` under `hint.cmd.*`
+(per command form) and `hint.err.*` (per runtime error class). The
+inventory and authoritative syntax sources:
+
+- **`hint.cmd.<form>`** — for each, cross-check the example against the
+  matching `parse.usage.<form>` template **and** the form's ADR, and run
+  it. Highest-risk (extrapolated, verify first): **DDL** — `create_table`
+  (known wrong), `add_column`, `add_index`, `add_constraint`,
+  `change_column`, `drop_*`, `create_m2n`; **advanced-SQL** — confirm
+  each is in the supported SQL subset (`select`, `with` CTE,
+  `sql_insert/update/delete`, `sql_create_table`, `sql_alter_table`,
+  `sql_create_index/drop_index/drop_table`, `explain_sql`); **DML** —
+  `seed` forms, `explain`, `show_*`, `update`/`delete` (`--all-rows` /
+  required-WHERE wording). App commands are lower-risk (reference-style).
+- **`hint.err.<class>`** — verify the fix recipe in `example` is actually
+  the right remedy and `concept` matches the engine's real behaviour
+  (FK sides, `on delete` actions, check/not_null/unique semantics).
+- Relevant ADRs: 0005 (types + compound PK), 0009 (DSL syntax), 0011 (FK
+  type compat), 0013 (relationships/rebuild), 0014 (data ops +
+  required-WHERE), 0025 (indexes), 0028/0039 (explain), 0030–0036 (SQL
+  subset), 0048 (seed). `docs/requirements.md` for scope.
+
+**Suggested method:** drive the app (`/run` or a small PTY/Tier-3 harness)
+and actually execute each example; or add a test that parses+runs every
+`hint.cmd.*` example and asserts success. The latter would also be a
+durable regression guard — consider adding it as part of the pass (it
+upgrades the comprehensiveness coverage test from "a block exists" to
+"the example actually works").
+
+## §5. Immediate fix ready to apply
+
+`create_table` is diagnosed (§2). The corrected block should make the
+example a PK-only `create table` and move the regular columns to a
+follow-up `add column`, e.g.:
+
+```
+What:    Create a new table with its primary key.
+Example: create table Customers with pk id(serial)
+Concept: A table is a set of rows sharing the same columns. `with pk`
+         declares the primary key (one column, or several for a compound
+         key); add the other columns afterwards with `add column`.
+```
+
+Apply this (and re-check `create_m2n` / `add_*` while there), but only as
+part of the systematic pass — a one-off fix risks leaving siblings wrong.
+
+## §6. How to take over
+
+1. Read handoffs 70 → 71, `CLAUDE.md`.
+2. Confirm green: `cargo test` (2499 / 1 ignored), `cargo clippy
+   --all-targets`.
+3. Do the §4 pass (consider the run-every-example test in §4). Test-first,
+   `/runda` before commit, confirm the commit message with the user.
+4. Pedagogy wins — these are teaching strings; correctness and clarity
+   over cleverness.