docs(hint): defer pre-submit-diagnostic route + diagnostic.* blocks (ADR-0053)

Phase C scope decision: Diagnostic carries no class key, so the F1
diagnostic route would need a class field threaded through every
diagnostic site (broad change) for marginal value — tier-2 already
surfaces diagnostics and many duplicate the runtime error classes. Defer
the route + the ~33 diagnostic.* tier-3 blocks to issue #38. v1 ships
command-form hints + 9 runtime error-class hints (comprehensive for
those). Updates ADR-0053 D2/D6/Status/OOS + README.

docs/adr/0053-contextual-hint-command-and-keybinding.md

@@ -10,10 +10,13 @@ Phase B implementation (2026-06-15): the first exemplar showed per-*node*
 keying is too coarse for multi-form commands (`add`/`drop`/`show`/
 `create`), so D3 now keys tier-3 content **per form** via a
 `hint_ids: &[&str]` array mirroring `usage_ids` — and **clause-concept
-hints** are recorded as a deferred extension (separate tracking issue).
+hints** are recorded as a deferred extension (issue #37). During Phase C
-The parallel question of whether the in-app `help` command should
+the **pre-submit-diagnostic route + the ~33 `diagnostic.*` blocks** were
-likewise distinguish advanced-SQL forms is tracked **separately** as
+**deferred** (issue #38) — `Diagnostic` doesn't carry its class key, so
-Gitea issue #36 (it touches shipped, ADR-backed `help` behaviour).
+the route needs a broad change for marginal value (D6). v1 therefore
+ships command-form hints + the 9 runtime error-class hints. The parallel
+question of whether the in-app `help` command should likewise distinguish
+advanced-SQL forms is tracked **separately** as Gitea issue #36.
 
 Decided in conversation 2026-06-14. Closes the last open piece of **A1**
 (the canonical app-command set, ADR-0003): every app command is
@@ -112,19 +115,13 @@ F1 is inert behind a modal and while a sidebar panel holds navigation
 focus (consistent with the existing `handle_key` gates, ADR-0046); it is
 active in the input context in both Simple and Advanced mode.
 
-**Two error sources, one namespace.** Errors come in two kinds and reach
+**Error routes.** **Runtime errors** (the 9 `translate_error` classes)
-`hint` by different routes:
+occur *after* submit; the **`hint` command / empty-input F1** path reads
-
+them via the stored `last_error_hint_key` (D5) and renders their
-- **Pre-submit diagnostics** (the ~33 `diagnostic.*` classes — arity,
+`hint.err.<class>` block. (A second route for **pre-submit diagnostics**
-  type, unknown table/column) are computed *while typing* by the walker.
+on the F1 live-input path was specified but is **deferred** — D6 / issue
-  The **F1 live-input path** reads the current under-cursor diagnostic
+#38; with a diagnostic present, F1 shows the command block and tier-2
-  directly from the walker (the same source the ambient panel uses) and
+shows the diagnostic.) **`:`-prefix handling:**
-  renders its `hint.err.<class>` block — no stored state needed.
-- **Runtime errors** (the 9 `translate_error` classes) occur *after*
-  submit. The **`hint` command / empty-input F1** path reads them via the
-  stored `last_error_hint_key` (D5).
-
-Both render from the same `hint.err.*` namespace. **`:`-prefix handling:**
 on the simple-mode one-shot escape (`: SELECT …`), command
 identification for the F1 path strips the leading `:` first, so the
 advanced form is matched.
@@ -220,26 +217,37 @@ Option<String>`** — set at the `translate_error` call sites
 cleared when a later command succeeds. Absent → the "getting started"
 pointer.
 
-The **pre-submit-diagnostic route** (the F1 live-input path) needs no
+The **pre-submit-diagnostic route** (the F1 live-input path reading the
-stored state: it reads the current diagnostic from the walker at F1 time
+under-cursor diagnostic) is **deferred** — see the scope note in D6.
-(D2). This is the cleaner split the `/runda` pass surfaced — typing-time
-diagnostics and post-submit runtime errors are genuinely different
-sources and should not be funnelled through one stored key.
 
-### D6 — Content scope: comprehensive for v1
+### D6 — Content scope for v1
 
-v1 ships tier-3 content for the **whole inventory**, not a subset (the
+v1 ships tier-3 content for the **command forms and runtime error
-graceful tier-2 fallback below is a safety net, not the plan):
+classes** — comprehensive for those (the graceful tier-2 fallback below
+is a safety net, not the plan):
 
 - **~37 command forms** — every distinct node in `REGISTRY` gets its own
   `hint.cmd.<hint_id>` block (app + DSL + DDL + advanced-mode SQL forms),
   each with a **mode-correct example** (the advanced-SQL forms show SQL
   syntax, their simple siblings show DSL — no sharing).
-- **9 runtime error classes** — `unique`, `foreign_key` (×4 sides),
+- **9 runtime error classes** — `unique`, `foreign_key` (child/parent
-  `not_null`, `check`, `type_mismatch`, `not_found`, `already_exists`,
+  side), `not_null`, `check`, `type_mismatch`, `not_found`,
-  `generic`, `invalid_value` — each gets a `hint.err.*` block.
+  `already_exists`, `generic`, `invalid_value` — each gets a
-- **~33 `diagnostic.*` pre-submit classes** — arity, type, unknown
+  `hint.err.*` block.
-  table/column, etc. — each gets a `hint.err.*` block.
+
+**Deferred — the ~33 `diagnostic.*` pre-submit classes and the F1
+diagnostic route** *(Phase C scope decision, 2026-06-15; issue #38)*. The
+original "comprehensive" scope included them, but implementation revealed
+`Diagnostic` (`walker/outcome.rs`) carries only its rendered `message`,
+not its class key — so a live diagnostic can't be mapped to
+`hint.err.<class>` without adding a `class` field threaded through every
+diagnostic-creation site (a broad change). Weighed against the value, it
+isn't worth it for v1: pre-submit diagnostics are already surfaced by
+tier-2 (ambient message + validity indicator, ADR-0027); F1 still shows
+the useful command block when a diagnostic is present; and many
+diagnostic classes duplicate runtime classes already covered
+(`type_mismatch`, `unknown_table`↔`not_found`, arity↔`invalid_value`).
+Deferred to issue #38, additively (the keying doesn't lock it out).
 
 The full enumerated checklist is the implementation plan's tracking
 artifact (see *Content inventory*, below).
@@ -339,26 +347,26 @@ Hint — add relationship
   `App` state (`last_error_hint_key`), and one new renderer family
   (`note_hint*`); the `AppCommand` enum gains `Hint`, the grammar a `HINT`
   node, the REGISTRY one entry.
-- **A large, durable content corpus** (~37 command blocks + ~42 error/
+- **A durable content corpus** (~37 command blocks + 10 runtime
-  diagnostic blocks ≈ 80) enters the catalogue under `hint.cmd.*` /
+  error-class blocks) enters the catalogue under `hint.cmd.*` /
   `hint.err.*`, validated by `keys.rs`. This is ongoing surface area: new
   commands/error classes should ship with their tier-3 hint (a checklist
-  item for future feature ADRs).
+  item for future feature ADRs). (Diagnostic-class blocks deferred — #38.)
 - **Testing:** Tier-1 unit tests for the trigger matrix (F1 with
   empty/non-empty input; `hint` with/without a recent error;
   `last_error_hint_key` set on the `translate_error` sites and cleared on
-  success; the pre-submit-diagnostic vs runtime-error routing; the `:`
+  success; the mode-aware form resolution; the `:` strip), the
-  strip), the command-identification logic, and the tier-2 fallback;
+  command-identification logic, and the tier-2 fallback; Tier-2 `insta`
-  Tier-2 `insta` snapshots for a representative rendered hint block;
+  snapshots for a representative rendered hint block; Tier-3 integration
-  Tier-3 integration tests for the end-to-end flows (type a partial
+  tests for the end-to-end flows (type a partial command → F1 → block
-  command → F1 → block appears, **buffer and completion memo untouched**;
+  appears, **buffer and completion memo untouched**; run a failing
-  run a failing command → `hint` → error expansion). **A
+  command → `hint` → error expansion). **A comprehensiveness coverage
-  comprehensiveness coverage test** (enforces D6): iterate the REGISTRY
+  test** (enforces D6): iterate the REGISTRY and assert every node with a
-  and assert every node has a `hint_id` resolving to a `hint.cmd.*` block,
+  `hint_ids` entry resolves to a `hint.cmd.*` block, and every runtime
-  and every runtime-error/diagnostic class has a `hint.err.*` block —
+  error class resolves to a `hint.err.*` block — `keys.rs` only checks
-  `keys.rs` only checks that *referenced* keys resolve, not that every
+  that *referenced* keys resolve, not that every command/error *has* one,
-  command/error *has* one, so this test is what makes "comprehensive"
+  so this test is what makes the scope enforceable rather than
-  enforceable rather than aspirational.
+  aspirational. (Diagnostic classes are out of this scope — D6 / #38.)
 
 ## Out of scope
 
@@ -381,6 +389,11 @@ Hint — add relationship
   recognized clause, deeper than tier-2's candidate list but narrower than
   the per-form block. Per-form keying (D3) does not lock it out. To be
   tackled as a deliberate follow-up job, not gated on usage statistics.
+- **Pre-submit-diagnostic route + `diagnostic.*` tier-3 blocks** — OOS
+  (deferred, issue #38): needs a class field on `Diagnostic` threaded
+  through every creation site (broad change) for marginal value, since
+  tier-2 already surfaces diagnostics and many duplicate runtime classes
+  (D6).
 
 ## Content inventory (implementation tracking)
 
@@ -401,4 +414,5 @@ The implementation plan enumerates and checks off every block:
 - **`hint.err.*`** — one per runtime error class (`unique`,
   `foreign_key.{child,parent}_side`, `not_null`, `check`,
   `type_mismatch`, `not_found`, `already_exists`, `generic`,
-  `invalid_value`) and per `diagnostic.*` pre-submit class.
+  `invalid_value`). The `diagnostic.*` pre-submit classes are **deferred**
+  (D6 / issue #38).

docs/adr/README.md

@@ -58,4 +58,4 @@ This directory contains the project's ADRs, recorded per
 - [ADR-0050 — Incidental-DDL confirmations omit relationship info (structure-only)](0050-incidental-ddl-confirmations-omit-relationships.md) — **Accepted + implemented 2026-06-12 (issue #28)**, closes Gitea **#28**. **Supersedes** the incidental-DDL clause of **ADR-0044 §1** and the relationship-block half of **ADR-0016 §5**. Incidental-DDL confirmation echoes (`create table`, `add`/`drop`/`rename`/`change column`, `add`/`drop index`) now render **structure only** — header + column box + `Indexes:` + constraints — with **no `References:` / `Referenced by:` block** (neither prose nor diagram), even when the table carries relationships the user did not touch. Rationale (owner): a confirmation echo reports the change just made, not untouched relationships; ADR-0044's terse prose was the lesser of "prose vs diagram", but the right answer for these surfaces is **neither**. **Relationship-subject surfaces are unchanged** — `show table`, `add`/`drop relationship`, `show relationship` still render ADR-0044 diagrams; relationships appear only when the user asks for (`show table`) or acts on (`add`/`drop relationship`) one, and are one `show table <T>` away — **no information lost**. Forks both user-chosen: **scope = all incidental DDL** (not just `add column` — the rationale is uniform, the mental model clean, and it's the simpler edit) and **delete the prose renderer** (not retain it dormant — no dead code). **Mechanism:** the `handle_dsl_success` `matches!` routing is unchanged (relationship-subject → diagrams; else → `render_structure`); the change is one line inside `render_structure` (`output_render.rs` — drop the relationship-block call) since all its callers are incidental DDL, plus deletion of the orphaned `relationship_prose_lines` + `cols_disp` helpers. The prose format survives in ADR-0016 §5 + git history for a future OOS-7 always-prose setting. **Tests:** the prose-presence unit test + its snapshot removed; a new unit test asserts `render_structure` on a description carrying **both** inbound and outbound relationships emits the box but no prose; the misnamed `add_relationship_flow_shows_inbound_section_on_parent` integration test (which sent an `AddColumn`) inverted + renamed to assert the add-column echo omits the prose; the diagram tests (`show table`, `add relationship`) unaffected. **2458 pass / 0 fail / 0 skip (1 ignored), clippy clean**. `requirements.md` unaffected (ADR-tracked refinement of a decided area, like ADR-0044 itself)
 - [ADR-0051 — Bottom keybinding strip: context- and state-aware](0051-context-state-aware-keybinding-strip.md) — **Accepted + implemented 2026-06-13 (issue #27)**, closes Gitea **#27**. Repurposes the bottom status line into a **keystrokes-only, state-selected** strip (builds on ADR-0046 nav focus, ADR-0003 modes, ADR-0049 the #29 readline keys it now advertises, ADR-0022 the completion memo). A pure `status_bar_bindings(app) -> Vec<(key,label)>` chooses the strip by **priority, first match wins**: (1) **sidebar focus** → `Ctrl-O next pane · ↑↓/PgUp/PgDn scroll · Esc input`; (2) **completion memo live** (`last_completion`) → `Tab/Shift-Tab cycle · Esc cancel · Enter run`; (3) **history navigation** (new `App::is_browsing_history()` exposing the private `history_cursor`) → `↑↓ browse · Esc clear · Enter run`; (4) **editing** (input non-empty) → `Esc clear · Ctrl-A/E home/end · Ctrl-W del word · Enter run` (surfaces the #29 keys, closing ADR-0049's deferred advertisement); (5) **default** (empty) → `Ctrl-O sidebar · Tab complete · ↑ history · Enter run`. Priority is correct because Up clears the completion memo and Tab cancels history nav, so states 2/3 never co-occur, and the five are exhaustive for Input focus. **Typed-command words leave the strip** (`mode advanced`/`mode simple` switch, `:` one-shot) and **mode discovery moves to the empty-input hint** (`resolve_hint_lines`), **simple mode only**: `\`mode advanced\` for SQL` (the verb "type" omitted — the prompt implies it; advanced mode shows **no** pointer per a post-trial user decision — a switcher knows how they got there and `help` covers the way back). The one-shot's old `Backspace cancel one-shot` label is subsumed by the editing state (behaviour intact). Forks all user-chosen: **editing state shows the #29 keys** (vs unadvertised); **`Ctrl-C quit` omitted** from the strip (vs always shown); **no width-drop machinery** — the longest strip (~65 cols) fits all supported widths, so a **width-budget unit test** keeps it lean by construction instead (the user's own observation). Catalog: 12 new `shortcut.*` labels + the `panel.hint_mode_advanced` string added to `en-US.yaml`+`keys.rs` (validator-checked 1:1), 5 now-dead strip strings removed. **Modal-aware strip is OOS** (pre-existing: a modal owns the keyboard and carries its own hints; the strip under it is unchanged-in-kind, not worsened). Tests: 9 Tier-1 unit (per-state key sets — completion/history driven through real key events; width budget; mode-pointer presence/absence), 1 Tier-3 rewritten (`status_bar_is_keystroke_only_and_state_aware`), 15 full-panel snapshots re-accepted (reviewed — strip/hint only). **2467 pass / 0 fail / 0 skip (1 ignored), clippy clean.** OOS: modal-aware strip; a full-key cheatsheet overlay; Ctrl-K/U advertisement (editing strip shows the highest-value subset within the width budget)
 - [ADR-0052 — Mode-tagged history for cross-mode recall](0052-mode-tagged-history-cross-mode-recall.md) — **Accepted + implemented 2026-06-13 (issue #30)**, closes Gitea **#30** — the feature (advanced history reusable in simple mode) **and** the bug in its comment (the `:` one-shot prefix lost across sessions). **Amends ADR-0034** (status field gains a `:adv` tag; **journaling moves from the worker to the dispatch layer**), **ADR-0015 §5/§6** (history.log leaves the worker transaction — `commit-db-last` now scopes yaml/csv/db only), and **ADR-0040** (a success-path journal-write failure is best-effort, not fatal); references ADR-0003. **Root cause:** history carried no mode, and the in-memory ring stored the raw `:select 1` while the worker journalled the *stripped* `select 1`, so the `:` was lost on disk. **Fix:** record the submission mode per entry as a **`:adv` suffix on the status token** (`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 (a leading `:` unambiguously marks advanced since simple DSL never starts with `:`); recall **strips the `:` in advanced mode** (runs as bare SQL) and keeps it in simple mode (runs via the one-shot escape); hydration reconstructs the `: `-prefix from the tag, so cross-session = in-session. **The architectural turn (user's call):** the first draft kept journaling in the worker + threaded the mode down (~30-site plumbing); on review the user asked why the journal is written deep in the worker when the *failure* path already journals at the top of the chain — it shouldn't (history.log is a journal, not state). So **success journaling moved up** to `spawn_dsl_dispatch` / `run_replay` / the app-command sites (next to the failure path), the worker's `finalize_persistence` now writes only yaml/csv, and the journal write became **best-effort** (the command is already committed — consistent with the failure path; a rare disk-full leaves a committed command unjournalled, state intact). **App commands** journal simple (dispatched outside the spawn) and `submit` excludes them from the ring's advanced flag, so `undo`/`mode advanced` recall bare. Forks user-chosen: status-tag format (vs 4th field / `:`-in-source); unified scope; **dispatch-layer best-effort journaling** (vs worker-coupled-fatal). Two `/runda` passes (the second drove the relocation + app-command exclusion). Tests: the 15 worker-level journaling tests retired (worker no longer journals — yaml/csv/operation checks kept), re-covered at the new layer (history.rs status-tag + `:`-reconstruct; app.rs recall matrix; the #30 cross-session regression in `iteration6`; replay tests cover `run_replay` journaling). **2471 pass / 0 fail / 0 skip (1 ignored), clippy clean.** replay re-journaling mode-fidelity (a replayed advanced line re-journals simple — not a regression). **Follow-up done 2026-06-14:** the vestigial worker `source` plumbing was fully unwound (compiler-guided, no behaviour change) — `_source` removed from `finalize_persistence`/`do_rebuild_from_text`, the three `*_request` wrappers inlined+deleted, the dead `source` param dropped from the ~30 forwarding worker handlers, and the `source` field removed from the `DescribeTable`/`QueryData`/`RunSelect` requests + their `DatabaseHandle` methods (~164 mostly-test call sites); the only worker `source` left is the snapshot/undo label (see ADR-0052 *Consequences*)
-- [ADR-0053 — Contextual `hint` command and keybinding](0053-contextual-hint-command-and-keybinding.md) — **Accepted, implementation in progress (2026-06-14; Phase A done, Phase B underway)**. Settles the `hint` slot ADR-0003 left "ADR pending"; closes the last open piece of **A1** and tracks requirements **H2**. **Two surfaces:** an **F1 keybinding** that renders a deep hint for the *live* partial input without submitting (the primary path — a submitted `hint` command can't see the buffer it would help with, since Enter empties it), and a submitted **`hint` command** that expands on the *most recent error*. **No topic argument** (contextual only — `help <topic>` already owns explicit reference). Introduces a **tier-3 teaching layer**, deeper than the existing tier-1 (colour / error headline) and tier-2 (ambient one-liner; and the error `hint:`, which is shown **by default** since `Verbosity::Verbose` is the default — `messages short` is the opt-*out*); without it `hint` would just duplicate what's already on screen. Tier-3 content lives in the catalogue under `hint.cmd.<hint_id>` (per command form) and `hint.err.<class>` (per error/diagnostic class), each a structured `what`/`example`/`concept` block rendered via a new `note_hint*` family with `OutputStyleClass::Hint`. **Keyed per-form via a new `hint_ids: &[&str]` field on `CommandNode` mirroring `usage_ids`** (revised in Phase B): a per-*node* key proved too coarse — `add`/`drop`/`show`/`create` are each one node spanning many forms, and a live-input hint for `add 1:n relationship` must be specific to relationships; `hint_key_for_input_in_mode` reuses `usage_key_for_input_in_mode`'s form-word disambiguation, and covers the advanced-SQL forms whose `usage_ids` are empty. Not keyed off `help_id` (it is `None` on the advanced-SQL nodes purely to dedup the `help` list; that parallel gap is issue **#36**). **Clause-concept hints** (`on delete` actions, constraint slots, `with pk`, cardinality) are a recorded **deferred extension** (`hint.concept.<topic>`, issue **#37**) — per-form is the right tier-3 granularity, with position-awareness owned by tier-2 + the live `Next:` line. Two error routes share `hint.err.*`: pre-submit `diagnostic.*` read live from the walker (F1 path), runtime `translate_error` classes via stored `last_error_hint_key` (`hint` command / empty-F1). Adds `AppCommand::Hint`, a `HINT` grammar node + REGISTRY entry, the `hint_ids` field, and `last_error_hint_key`; F1 is a read-only overlay (buffer + completion memo untouched). **Content is the bulk of the work** (the mechanism is ~a day): **comprehensive for v1** — ~37 command forms + 9 runtime error classes + ~33 `diagnostic.*` classes ≈ 80 teaching blocks — authored **exemplars-first** (voice approved in this ADR's `/runda` review, then mass-authored in batches), enforced by a **comprehensiveness coverage test** (every node/error class has a key), with graceful fall-back to tier-2 if a key is ever missing. Forks user-chosen: two-surface model; **F1** (vs `?` / a chord); no-arg; comprehensive scope; exemplars-first. OOS: per-topic `hint <topic>` (rejected — overlaps `help`); always-on tier-3 (rejected — keeps ambient terse); non-`en-US` locales + success-command teaching (deferred); the `help`-side advanced-SQL gap (issue #36)
+- [ADR-0053 — Contextual `hint` command and keybinding](0053-contextual-hint-command-and-keybinding.md) — **Accepted, implementation in progress (Phases A–C done 2026-06-15: mechanism + per-form keying + the command-form & runtime-error content; Phase D polish next)**. Settles the `hint` slot ADR-0003 left "ADR pending"; closes the last open piece of **A1** and tracks requirements **H2**. **Two surfaces:** an **F1 keybinding** that renders a deep hint for the *live* partial input without submitting (the primary path — a submitted `hint` command can't see the buffer it would help with, since Enter empties it), and a submitted **`hint` command** that expands on the *most recent error*. **No topic argument** (contextual only — `help <topic>` already owns explicit reference). Introduces a **tier-3 teaching layer**, deeper than the existing tier-1 (colour / error headline) and tier-2 (ambient one-liner; and the error `hint:`, which is shown **by default** since `Verbosity::Verbose` is the default — `messages short` is the opt-*out*); without it `hint` would just duplicate what's already on screen. Tier-3 content lives in the catalogue under `hint.cmd.<hint_id>` (per command form) and `hint.err.<class>` (per error/diagnostic class), each a structured `what`/`example`/`concept` block rendered via a new `note_hint*` family with `OutputStyleClass::Hint`. **Keyed per-form via a new `hint_ids: &[&str]` field on `CommandNode` mirroring `usage_ids`** (revised in Phase B): a per-*node* key proved too coarse — `add`/`drop`/`show`/`create` are each one node spanning many forms, and a live-input hint for `add 1:n relationship` must be specific to relationships; `hint_key_for_input_in_mode` reuses `usage_key_for_input_in_mode`'s form-word disambiguation, and covers the advanced-SQL forms whose `usage_ids` are empty. Not keyed off `help_id` (it is `None` on the advanced-SQL nodes purely to dedup the `help` list; that parallel gap is issue **#36**). **Clause-concept hints** (`on delete` actions, constraint slots, `with pk`, cardinality) are a recorded **deferred extension** (`hint.concept.<topic>`, issue **#37**) — per-form is the right tier-3 granularity, with position-awareness owned by tier-2 + the live `Next:` line. Runtime `translate_error` classes resolve via stored `last_error_hint_key` (`hint` command / empty-F1). (The second route — pre-submit `diagnostic.*` read live from the walker on the F1 path — is **deferred**, issue **#38**: `Diagnostic` carries no class key.) Adds `AppCommand::Hint`, a `HINT` grammar node + REGISTRY entry, the `hint_ids` field, and `last_error_hint_key`; F1 is a read-only overlay (buffer + completion memo untouched). **Content is the bulk of the work** (the mechanism is ~a day): v1 scope = ~37 command forms + 9 runtime error classes (comprehensive for those, ~57 blocks), authored **exemplars-first** (voice approved in this ADR's `/runda` review, then mass-authored in batches), enforced by a **comprehensiveness coverage test**, with graceful fall-back to tier-2 if a key is ever missing. The **pre-submit-diagnostic route + ~33 `diagnostic.*` blocks were deferred** (issue **#38**) — `Diagnostic` carries no class key, so the route needs a broad change for marginal value (tier-2 already surfaces diagnostics; many duplicate runtime classes). Forks user-chosen: two-surface model; **F1** (vs `?` / a chord); no-arg; comprehensive-for-commands-and-errors scope; exemplars-first; diagnostics deferred. OOS: per-topic `hint <topic>` (rejected — overlaps `help`); always-on tier-3 (rejected — keeps ambient terse); non-`en-US` locales + success-command teaching (deferred); clause-concept hints (issue #37); the diagnostic route (issue #38); the `help`-side advanced-SQL gap (issue #36)