feat(hint): H2 Phase A — hint command + F1 keybinding skeleton (ADR-0053)

The mechanism for the contextual hint, with tier-2 fallback; the
tier-3 corpus lands in later phases.

- new CommandNode `hint_id` field (all None for now)
- AppCommand::Hint + HINT grammar node + REGISTRY + dispatch
- F1 read-only overlay in handle_key (buffer/cursor/memo untouched)
- note_hint* renderers; hint_id_for_input_in_mode (shared selection
  helper refactored out of usage_keys_for_input_in_mode)
- last_error_hint_key + friendly::error_hint_class classifier
- catalogue: help.app.hint / parse.usage.hint / hint.getting_started
- +12 tests; 2483 pass / 1 ignored, clippy clean

src/dsl/grammar/mod.rs

@@ -530,6 +530,15 @@ pub struct CommandNode {
     /// so a newly-registered command appears in `help`
     /// automatically (ADR-0024 §help_id).
     pub help_id: Option<&'static str>,
+    /// Catalog key stem (`hint.cmd.<id>`) for this command form's
+    /// **tier-3** contextual hint (ADR-0053 / H2). Unlike `help_id`
+    /// — which is `None` on advanced-SQL forms purely to dedup the
+    /// `help` list — `hint_id` is 1:1 with command *forms*, so each
+    /// advanced-SQL form carries its own id and renders SQL-syntax
+    /// content distinct from its simple-DSL sibling. `None` until a
+    /// form's tier-3 block is authored (the surface falls back to
+    /// tier-2 ambient/error text).
+    pub hint_id: Option<&'static str>,
     /// Catalog keys under `parse.usage.*` to render in the
     /// "usage:" block when a parse error fires for this command
     /// (ADR-0021 §1, ADR-0024 §architecture). Multi-form families
@@ -574,32 +583,69 @@ pub fn usage_keys_for_input_in_mode(
     source: &str,
     mode: crate::mode::Mode,
 ) -> Option<(&'static str, Vec<&'static str>)> {
+    let pick = selected_nodes_for_input_in_mode(source, mode);
+    if pick.is_empty() {
+        return None;
+    }
+    let mut keys: Vec<&'static str> = Vec::new();
+    for (_, node, _) in &pick {
+        for k in node.usage_ids {
+            if !keys.contains(k) {
+                keys.push(*k);
+            }
+        }
+    }
+    if keys.is_empty() {
+        return None;
+    }
+    let entry = pick[0].1.entry.primary;
+    Some((entry, keys))
+}
+
+/// The tier-3 `hint_id` of the command form `source` is currently
+/// typing, in `mode` (H2 / ADR-0053).
+///
+/// Reuses the same mode-aware
+/// selection as [`usage_keys_for_input_in_mode`] and returns the
+/// **mode-primary** node's `hint_id` — so an advanced-SQL form
+/// resolves to its *own* id, not its simple-DSL sibling's. `None` if
+/// no entry word matches, or the chosen form has no tier-3 block yet
+/// (the caller then falls back to tier-2 ambient text).
+#[must_use]
+pub fn hint_id_for_input_in_mode(source: &str, mode: crate::mode::Mode) -> Option<&'static str> {
+    selected_nodes_for_input_in_mode(source, mode)
+        .first()
+        .and_then(|(_, node, _)| node.hint_id)
+}
+
+/// Shared mode-aware command-form selection for the entry word at the
+/// start of `source`.
+///
+/// Extracted so the usage-key and hint-id lookups agree on which form
+/// the user is typing.
+///
+/// Advanced mode: every candidate form is reachable — the SQL nodes
+/// are primary, and the DSL nodes remain valid via fallback (verified:
+/// `create table … with pk` and `drop column …` both run in advanced
+/// mode). Mode-primary (Advanced) first, so a hint never hides input
+/// that works. Simple mode: only the DSL forms — the SQL-only forms
+/// hit the "this is SQL" rail and are not reachable. (ADR-0042 G3.)
+/// Degenerate guard: an advanced-only word in simple mode leaves the
+/// selection empty; fall back to all candidates.
+fn selected_nodes_for_input_in_mode(
+    source: &str,
+    mode: crate::mode::Mode,
+) -> Vec<(usize, &'static CommandNode, CommandCategory)> {
     use crate::dsl::walker::lex_helpers::{consume_ident, skip_whitespace};
     let start = skip_whitespace(source, 0);
-    let (kw_start, kw_end) = consume_ident(source, start)?;
+    let Some((kw_start, kw_end)) = consume_ident(source, start) else {
+        return Vec::new();
+    };
     let word = &source[kw_start..kw_end];
     let candidates = commands_for_entry_word(word);
     if candidates.is_empty() {
-        return None;
+        return Vec::new();
     }
-    let union = |nodes: &[(usize, &'static CommandNode, CommandCategory)]| -> Vec<&'static str> {
-        let mut keys: Vec<&'static str> = Vec::new();
-        for (_, node, _) in nodes {
-            for k in node.usage_ids {
-                if !keys.contains(k) {
-                    keys.push(*k);
-                }
-            }
-        }
-        keys
-    };
-    // Advanced mode: every candidate form is reachable — the SQL
-    // nodes are primary, and the DSL nodes remain valid via fallback
-    // (verified: `create table … with pk` and `drop column …` both
-    // run in advanced mode). Show them all, mode-primary (Advanced)
-    // first, so the usage hint never hides input that works. Simple
-    // mode: only the DSL forms — the SQL-only forms hit the "this is
-    // SQL" rail and are not reachable. (ADR-0042 G3.)
     let selected: Vec<(usize, &'static CommandNode, CommandCategory)> =
         if mode == crate::mode::Mode::Advanced {
             let mut v: Vec<_> = candidates
@@ -621,17 +667,7 @@ pub fn usage_keys_for_input_in_mode(
                 .filter(|(_, _, c)| *c == CommandCategory::Simple)
                 .collect()
         };
-    // Degenerate guard: an advanced-only word in simple mode (not
-    // normally reachable — it hits the SQL rail first) leaves
-    // `selected` empty; fall back to all candidates so a usage block
-    // still renders rather than the available-commands fallback.
-    let pick = if selected.is_empty() { candidates } else { selected };
-    let keys = union(&pick);
-    if keys.is_empty() {
-        return None;
-    }
-    let entry = pick[0].1.entry.primary;
-    Some((entry, keys))
+    if selected.is_empty() { candidates } else { selected }
 }
 
 /// The single usage template most relevant to `source`, when
@@ -712,6 +748,7 @@ pub fn entry_words_alphabetised() -> Vec<&'static str> {
 pub static REGISTRY: &[(&CommandNode, CommandCategory)] = &[
     (&app::QUIT, CommandCategory::Simple),
     (&app::HELP, CommandCategory::Simple),
+    (&app::HINT, CommandCategory::Simple),
     (&app::REBUILD, CommandCategory::Simple),
     (&app::SAVE, CommandCategory::Simple),
     (&app::NEW, CommandCategory::Simple),