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.)*