Merge branch 'main' into website

docs/adr/0047-demonstration-overlay-layer.md

@@ -414,5 +414,41 @@ time-boxed-`recv` path. We therefore test the **pure pieces**
 exhaustively (label fn, capture state machine, nearest-deadline helper)
 and assert plumbing via Tier-3, rather than over-claiming an integration
 test of the `tokio` timeout itself.
-</content>
-</invoke>
+
+## Amendment 1 — `Ctrl-G` demo-mode alias for F1 (2026-06-15)
+
+**Context.** The contextual `hint` overlay (ADR-0053 / H2) is opened with
+**F1**. But F1 reaches the app only as an escape sequence (`\eOP` /
+`\e[11~`), and the `autocast` recorder used for our screencasts **cannot
+emit escape sequences** — so a cast can never trigger F1, and the single
+most teaching-relevant overlay is unreachable in recordings. The same
+wall already bit step-captions (which is why `Ctrl+]`, a single control
+byte, was chosen over `Ctrl+!`).
+
+**Decision.** In **demo mode only**, **`Ctrl-G`** is an alias for F1. It
+runs the exact F1 hint logic (live-input → form hint; empty input →
+recent-error / getting-started) and is **badged as `[F1]`** (not
+`[CTRL-G]`) so a recorded cast is visually identical to a genuine F1
+press. `Ctrl-G` is the only viable choice: it is a single legacy control
+byte autocast can send, whereas `Ctrl`+digit (e.g. the mnemonic `Ctrl-1`)
+is **not encodable in a legacy terminal at all** — digits have no control
+byte, so `Ctrl-1` arrives as a bare `1`; the kitty protocol *would* encode
+it but only as an escape sequence (the very thing autocast can't send),
+and this app deliberately does not enable keyboard-enhancement flags.
+
+**Why demo-gated.** The shipped keymap stays F1-only — a real user never
+trips the alias, and demo mode is also the mode teachers/presenters run,
+so the alias is available exactly where it's wanted. Outside demo mode
+`Ctrl-G` falls through to the inert catch-all (the `Char(c)` insert arm
+excludes CONTROL, so no `g` is typed).
+
+**Scope.** `hint_key` guard in `App::handle_key` gains the demo-gated
+`Ctrl-G` disjunct; `demo_badge_label` maps `Ctrl-G → [F1]` (consulted
+only in demo mode). Test-first: three `app.rs` Tier-1 tests (alias fires
+on input + on empty input; inert when demo off) + the badge-map
+assertion. The keybinding strip (ADR-0051) is **not** changed — F1 stays
+the advertised key; `Ctrl-G` is a recorder aid, and the badge already
+reads `[F1]`.
+
+*(Editorial: this amendment also removed two stray `</content>` /
+`</invoke>` lines accidentally committed at the end of this file.)*

docs/handoff/20260615-handoff-72.md

@@ -0,0 +1,113 @@
+# Session handoff — 2026-06-15 (72)
+
+Short, focused handover. Continues from handoff-71, which asked the next
+session to run a **systematic semantic verification pass over every
+`hint` block** (handoff-70 shipped H2 / ADR-0053, but a user smoke-test
+found a wrong hint and implicated the whole corpus). **That pass is now
+done.** Four content errors fixed, a durable parse-guard added, two stale
+docs corrected. Commit `5a37437`.
+
+## §1. State
+
+**Branch:** `main`, clean, all committed (local; **push pending** — your
+step). **2500 pass / 0 fail / 1 ignored** (the long-standing `friendly`
+doctest), **clippy clean** (nursery, all targets). The +1 vs handoff-71's
+2499 is the new guard test. Open Gitea issues unchanged: **#35–#38**.
+
+## §2. The verification pass (commit `5a37437`)
+
+Method: cross-checked every `hint.cmd.*` example against its
+`parse.usage.*` template, ground-truthed every concept claim against the
+authoritative ADR **and a named existing test** (not grep+extrapolation —
+the trap handoff-71 §3 warned about), and parse-validated all 49 command
+examples via a new guard.
+
+### Four content errors fixed (`src/friendly/strings/en-US.yaml`)
+
+| Block | Bug | Fix |
+|---|---|---|
+| `cmd.create_table` | Example `with pk id(serial), name(text), email(text)` declares a **3-column compound PK**, not a PK + regular columns. Every `with pk` column is a key member — confirmed by the grammar test comment *"Every `create table` column is a primary-key column"* (`ddl.rs`), ADR-0005. | Single-column PK + `add column` for the rest; `what`/`concept` aligned. |
+| `cmd.save` | `save as my-shop` **does not parse** — `build_save` yields `AppCommand::SaveAs` with **no inline name**; `save as` opens a path-entry modal (`iteration4b` tests). | Example → `save as`; `what` de-implied; added an accurate temp-vs-named-auto-save `concept`. |
+| `cmd.import` | Target `shop-copy` **does not parse** — the `as <target>` slot is an `IdentSource::NewName` ident that tokenises only up to the hyphen. (The zip path is a BarePath and *does* accept hyphens, hence `export my-shop.zip` is fine.) | → `shop_copy`. |
+| `err.foreign_key.child_side.concept` | Offered `on delete set null/cascade` as the remedy — but `error_hint_class` maps child_side to **insert/update** violations; `on delete` governs the **parent** direction. The tier-1 hint (line 64) correctly omits it. | Corrected: parent must exist first; clarified `on delete` is the *other* direction. |
+
+### Durable guard added
+
+`every_cmd_hint_example_parses_in_its_mode` (`src/dsl/grammar/mod.rs`,
+in the `hint_key_tests` module). **Catalog-driven** — it iterates
+`catalog().keys()` for `hint.cmd.*.example` rather than the REGISTRY, so
+an orphaned/mis-keyed block can't slip past; floor-asserts ≥49 examples.
+Each parses in its taught mode (advanced for the SQL surface, simple
+otherwise). It caught the `save` and `import` errors **test-first** (red
+before the YAML fix). Registered the new `hint.cmd.save.concept` key in
+`keys.rs` (the `keys_validate_against_catalog` test requires every catalog
+key be declared).
+
+### Verified correct (not changed)
+
+All other `cmd`/`err` blocks. Notably the guard-*concept* claims were each
+confirmed against a named runtime test, not assumed:
+`drop_column_refuses_primary_key` / `…_column_in_a_relationship`,
+`drop_table_with_inbound_relationship_errors`,
+`add_not_null_column_without_default_to_populated_table_is_refused`. The
+corrected `create_table` story stays coherent with the `Customers`-
+referencing examples (id serial PK → `add column` name/email → `insert`
+skips the auto id).
+
+## §3. Docs corrected (same commit)
+
+Discovered while verifying `create_m2n` (which **is** implemented —
+`db.rs::do_create_m2n_relationship` + `tests/it/m2n.rs`):
+
+- **CLAUDE.md** carried two **stale "deferred" claims**, both already
+  implemented. Removed/updated: (a) the at-a-glance project-format line
+  said export/import (Iter 5) + `--resume`/input-history/migration (Iter
+  6) were "pending" — all `[x]` in `requirements.md` (ADR-0015); (b) the
+  "Things deliberately deferred" list still had the **m:n convenience
+  (C4)** bullet and the same project-storage bullet. `requirements.md`
+  was already correct (C4 done 2026-06-10, ADR-0045), so only a
+  verification-pass note was appended to its **H2** entry.
+
+## §4. Scope note — what the guard does *not* do
+
+The bug class here is **semantic** (an example that parses and runs but
+misrepresents the prose — e.g. `create_table`). The guard enforces only
+the **syntactic floor**: examples parse in their mode. It backstops
+future typos/clause-drift but cannot police meaning. Semantic correctness
+of the current corpus rests on this session's review (recorded in the
+commit + requirements.md H2). A stronger-but-brittler option was offered
+to the user and **not built pending their call**: per-form assertions
+that each example resolves to the *expected command shape* (e.g.
+create_table → single-column PK). `hint.err.*` examples are fix-recipe
+prose, not runnable, so they're verified by review only — inherent.
+
+## §5. Next session — start here
+
+The hint corpus is now trustworthy. Open roadmap (verify against the CI
+merge first, per handoff-70 §5):
+
+1. **Push** (your step) — this commit + the still-unpushed backlog from
+   handoffs 70/71 (the CI merge + all of H2).
+2. **#35 (cargo fmt gate)** — the natural pairing with the merged CI; the
+   user wanted it done once, before first publication. The tree is **not**
+   fmt-clean (~1800 pre-existing diffs).
+3. Other `requirements.md` open items: **TT4** PTY tier-4 (unwired),
+   **I1** multi-line input, **I5/B3** in-flight cancellation, **V4**
+   session journal (own ADR), **TU1** tutorial system (own ADR).
+4. Hint follow-ups if wanted: **#37** clause-concept hints, **#38**
+   diagnostic route + `diagnostic.*` blocks, **#36** `help` advanced-SQL.
+
+## §6. How to take over
+
+1. Read handoffs 70 → 71 → 72, `CLAUDE.md`, `docs/requirements.md`.
+2. Confirm green: `cargo test` (**2500 / 1 ignored**) + `cargo clippy
+   --all-targets` (clean).
+3. For anything in the `hint` area, read **ADR-0053** first. For the
+   corpus, `src/friendly/strings/en-US.yaml` (`hint.cmd.*` / `hint.err.*`)
+   is the content; the guard in `src/dsl/grammar/mod.rs` is the regression
+   net.
+4. Workflow unchanged: phased, test-first, `/runda` + DA before commits,
+   ADR amendment + README index-upkeep for decided-area changes, confirm
+   commit messages with the user.
+5. Consider a `cargo sweep` at this milestone (`target/` grows; see
+   CLAUDE.md "Build hygiene").

docs/requirements.md

@@ -820,7 +820,12 @@ since ADR-0027.)
   (`what`/`example`/`concept`) covers every command form + the 9 runtime
   error classes, enforced by a comprehensiveness coverage test. Deferred:
   the pre-submit-diagnostic route + `diagnostic.*` blocks (#38),
-  clause-concept hints (#37).)*
+  clause-concept hints (#37). **Content verified 2026-06-15 (handoff-71):**
+  a semantic pass over every `hint.cmd.*`/`hint.err.*` block fixed four
+  errors — `create_table` (compound-PK misread), `save` (no inline name),
+  `import` (hyphen-rejecting target), and `foreign_key.child_side` (wrong
+  `on delete` remedy) — and added a catalogue-driven guard test that parses
+  every command example in its taught mode.)*
 - [x] **H3** `help` provides general reference and per-command
   help.
   *(Done 2026-06-07: the **general reference** is `help` (no arg) —