@hraness/dawg 0.6.0 → 0.7.0

package/src/commands/help.ts

@@ -1,12 +1,29 @@
 /**
  * The command reference, in one place: `/help` renders it in the overlay,
- * `dawg --help` prints it, and the docs mirror it. Music words are bare;
- * app commands take a slash (bare aliases keep working but are listed once,
- * in their canonical form).
+ * `dawg --help` prints it, and the docs mirror it. Groups are the ten topic
+ * ids (src/lang/glossary.ts), the same ids `/guide` and `/menu` take.
+ * A topic may have sub-groups (`sound · performance`) so no group runs
+ * past about fifteen rows. Commands are written bare, since the slash is
+ * optional; only the free-text window verbs (`/rename`, `/fork`,
+ * `/resume`), `/auth`, `/bpm` (a sample's tempo; bare `bpm` is song tempo)
+ * and `/play` (play mode; bare `play` is the transport) keep it.
  */
+import { GUITAR_TUNING_NAMES } from "../../core/chords.ts";
+import { KEYS, type KeyScreen } from "../../tui/grammar.ts";
+import { displayWidth, truncate } from "../../tui/text.ts";
+import {
+  resolveTopic,
+  topicMiss,
+  TOPIC_SUMMARY,
+  TOPICS,
+  type TopicId,
+} from "../lang/glossary.ts";
 import { EXPRESSION_USAGE } from "./expression.ts";
+import { editDistance } from "./nearest.ts";
+import { VOCAL_VERBS } from "./vocal.ts";
 
-export type HelpGroup = "music" | "session" | "window" | "keys";
+/** A topic id, or a heading of the start page. */
+export type HelpGroup = string;
 
 export type HelpEntry = Readonly<{
   /** Canonical form, e.g. `pan <-1..1>`. */
@@ -22,29 +39,16 @@ export type HelpSection = Readonly<{
 
 export const HELP_SECTIONS: readonly HelpSection[] = [
   {
-    group: "music",
+    group: "sound",
     entries: [
-      { command: "play", summary: "start the transport" },
-      { command: "pause", summary: "stop the transport" },
-      { command: "tempo <bpm>", summary: "20–300 BPM" },
-      { command: "add <note> at <beat> [for <beats>]", summary: "add C4 at 0" },
-      { command: "remove <id>", summary: "delete a note" },
-      { command: "move <id> to <beat>", summary: "shift a note" },
-      { command: "length <id> <beats>", summary: "resize a note" },
-      { command: "velocity <id> <0..1>", summary: "note loudness" },
-      { command: "bars <count>", summary: "loop length, 1–256" },
-      { command: "extend <count> bars", summary: "lengthen the loop" },
       {
         command: "instrument <name>",
-        summary: "sine piano pluck bass saw square triangle wavetable kit",
+        summary: "sine piano pluck bass sawtooth square triangle wavetable kit",
+      },
+      {
+        command: "synth <param> <value> | preset <name>",
+        summary: "the synth · synth lpf 1200 · synth alone lists every param",
       },
-      { command: "volume <0..1>", summary: "track level" },
-      { command: "pan <-1..1>", summary: "left … right" },
-      { command: "mute", summary: "silence this track" },
-      { command: "unmute", summary: "hear it again" },
-      { command: "solo", summary: "only this track" },
-      { command: "unsolo", summary: "every track again" },
-      { command: "clear", summary: "remove this track's notes" },
       {
         command: "wt <table> | wt <0..1> | wt list",
         summary: "wavetable synth · wt basic · wt wt_digital:2 · wt 0.5",
@@ -55,51 +59,68 @@ export const HELP_SECTIONS: readonly HelpSection[] = [
       },
       {
         command:
-          "grain <preset> | <param> <value> | on [voice V] | src synth:<name>|voice V | reset | off",
+          "grain <preset> | <param> <value> | on [voice V] | src synth:<name>|voice V",
         summary:
           "granular cloud · grain cloud · grain scan 0.2 · track swarm-2 · grain presets",
       },
       {
-        command: "fx <effect> <param> <value> | on | off | preset <name>",
-        summary: "effects · fx delay mix 0.3 · fx reverb on · fx lists them",
+        command: "piano [<preset>] | grand | upright | felt | honkytonk",
+        summary: "modeled piano · piano ballad · piano lofi · piano prepared",
       },
       {
-        command: "synth <param> <value> | preset <name>",
-        summary: "synth voice · synth lpf 1200 · synth lists every param",
+        command: "keys <param> <value> | preset <name> | reset",
+        summary: "piano params · keys hardness 0.3 decay 1.5 · keys lists them",
       },
       {
-        command: "string <preset> | <param> <value> | presets | reset | off",
+        command: "epiano|wurli|clav [preset <name>] | <param> <value>",
         summary:
-          "plucked strings · string sitar · string buzz 0.8 · string ring 6",
+          "electric keys · suitcase dyno funkclav · epiano vibe 0.6 · clav pickup bridge",
       },
       {
-        command: "rig <preset> | reset",
+        command:
+          "tonewheel [<drawbars>] | combo [<tabs>] [<register>] | pipe [<stops>]",
         summary:
-          "guitar rig · rig crunch · rig metal · rig funk · rig lists them",
+          "organs · tonewheel 888800008 perc 3rd · gospel · combo 08880 flute · pipe plenum · keys perc 3rd",
       },
       {
-        command: "track jangle|punk|funk|ragged|gtr-lead|gtr-metal|bachata",
-        summary: "new guitar track with that rig",
+        command: "rotary slow|fast|stop [at <beat>]",
+        summary:
+          "organ rotary speaker speed · rotary fast at 16 writes the keys-rotary lane",
       },
       {
-        command: "stomp|head|cab <type> | <param> <value>",
+        command: "string <preset> | <param> <value> | presets | reset | off",
         summary:
-          "pedal, amp, cabinet · stomp rat · head gain 7 gate -55 · cab 4x12",
+          "plucked strings · string sitar · string buzz 0.8 · string ring 6",
       },
       {
-        command: "piano [<preset>] | grand | upright | felt | honkytonk",
-        summary: "modelled piano · piano ballad · piano lofi · piano prepared",
+        command: "bowed [<preset>] | <param> <value> | presets",
+        summary:
+          "bowed strings · bowed violin · bowed cellos · bowed pressure 0.7 · bowed sord 1",
       },
       {
-        command: "keys <param> <value> | preset <name> | reset",
-        summary: "piano params · keys hardness 0.3 decay 1.5 · keys lists them",
+        command:
+          "guitar tune <name|notes> | capo | hand | ring | position | reset",
+        summary: "guitar fretting · guitar tune dadgad · guitar capo 2",
       },
       {
         command:
           "modal <preset> | <param> <value> | mallet <name> | reset | off",
+        summary: "mallets · modal vibes · modal hardness 0.8 · modal presets",
+      },
+      {
+        command: "wind <preset> | <param> <value> | mute <name> | reset | off",
         summary:
-          "mallets and bells · modal vibes · modal hardness 0.8 · modal presets",
+          "winds and brass · wind flute · wind sax · wind players 4 · wind presets",
       },
+      {
+        command: "/try <sound command>",
+        summary: "hear it on a loop first · a A/B · enter keep",
+      },
+    ],
+  },
+  {
+    group: "sound · performance",
+    entries: [
       {
         command: "art <articulation>|off [target]",
         summary:
@@ -122,6 +143,11 @@ export const HELP_SECTIONS: readonly HelpSection[] = [
         command: "pedal <beat>-<beat>... | bars | down|half|up <beat> | off",
         summary: "sustain pedal · pedal 0-3.5 4-7.5 · pedal bars",
       },
+      {
+        command: "pedal soft|sost <beat>-<beat>... | bars | off",
+        summary:
+          "piano una corda and sostenuto · pedal soft 0-8 · pedal sost 0-4",
+      },
       {
         command: "velcurve linear|soft|hard|fixed [<v>]",
         summary: "how velocity maps to level · velcurve fixed 0.6 (0..1)",
@@ -132,361 +158,511 @@ export const HELP_SECTIONS: readonly HelpSection[] = [
           "seeded feel at render · humanize 10 8 5 · humanize 20 bars 2-3",
       },
       { command: "expression", summary: "this track's performance settings" },
-      { command: "filter <hz> [res]", summary: "low-pass · filter off" },
-      { command: "delay <beats> [fb] [mix]", summary: "ping-pong · delay off" },
-      { command: "reverb <mix> [size]", summary: "room · reverb off" },
+    ],
+  },
+  {
+    group: "sound · samples",
+    entries: [
       {
-        command: "automate <lane> at <beat> <value>",
-        summary: "volume pan filter resonance delay-feedback delay-mix wt",
+        command: "/sample [<path> [as <sample>]]",
+        summary: "add a sample · alone lists the samples",
       },
       {
-        command: "automate <lane> points <b:v>...",
-        summary: "several points · automate pan points 0:-1 4:1",
+        command: "/bpm <n> [<sample>]",
+        summary: "a sample's own tempo (the slash matters: bare bpm is tempo)",
       },
       {
-        command: "automate <lane> remove <beat>",
-        summary: "drop one point",
+        command: "fitmode [repitch|beats|tones|auto] [<sample>]",
+        summary: "how it fits · alone suggests one from the sound",
       },
-      { command: "clear [<lane>] automation", summary: "drop a lane's points" },
       {
-        command: "master <unit> on|off | preset <name> | <param> <value>",
-        summary:
-          "song master · eq glue tape width limiter · master glue ratio 4",
+        command: "len <beats> [<sample>]",
+        summary: "the sample lasts n beats of the song",
       },
       {
-        command: "master <target> | target <lufs> | measure | off",
+        command: "shift <semitones> [formant keep|follow|<n>] [<sample>]",
         summary:
-          "loudness · master streaming · master target -9 · master measure",
+          "a sample's pitch without changing its length · shift 0 clears",
       },
-      { command: "track name <text>", summary: "rename this track" },
-      { command: "meter <1..16>", summary: "beats per bar" },
       {
-        command: "tempo <bpm> at <beat>|bar <n> [ramp|exp]",
-        summary: "tempo change · tempo 90 at bar 9 ramp · tempo clear",
+        command: "fade [in|out] <seconds> [<sample>]",
+        summary: "a sample's fade in and out (Strudel fadeInTime/fadeTime)",
       },
       {
-        command: "rit|accel [<n> bars] [to <bpm>] [at bar <n>]",
-        summary: "gradual · rit 4 bars to 80 · a tempo · tempo primo",
+        command:
+          "resample <track>|orbit <n>|master [section <name>|bars a-b] [grain]",
+        summary: "render to a pinned WAV on a new sampler (or granular) track",
       },
+    ],
+  },
+  {
+    group: "voice",
+    entries: [
       {
-        command: "fermata [at <beat>|at bar <n>|at end] [<extra beats>]",
-        summary: "hold a beat · fermata at 31 2 · fermata clear",
+        command: "sing [preset] [param value]",
+        summary:
+          "built-in singing voice: aah ooh choir chorale airy glass lament soprano basso, throat: drone khoomei sygyt kargyraa",
       },
       {
-        command: "meter <n>/<d> [at bar <n>]",
-        summary: "meter change · meter 7/8 at bar 5 · meter clear",
+        command: "sing vowels <v> …",
+        summary:
+          "vowels for the track's notes in order, cycled · sing vowels a e i o",
       },
       {
-        command: "track rate|phase|cycle <n> | off",
-        summary: "polytempo · track rate 3/2 · track cycle 3",
+        command: "note vowel <v|a>u> [target]",
+        summary: "sung vowel for selected notes · note vowel o bar 2",
       },
       {
-        command: "track phasing <beats> [over <beats>|hold <n>]",
-        summary: "Reich phasing · track phasing 3 hold 8 · track time off",
+        command: "lyrics [bar] sun-lit morn-ing",
+        summary: "syllables onto the notes (- splits, _ holds, ~ skips)",
       },
       {
-        command: "key <tonic> <mode> | none",
-        summary: "song key · key A minor · key F# dorian",
+        command: "autotune [preset] [field value …] | off | presets",
+        summary:
+          "pitch correction · autotune hard · autotune gentle · autotune to notes melody · autotune key D bayati",
       },
       {
-        command: "scale [<tonic>] <name> | list",
-        summary: "song scale · scale D hijaz · scale yaman · scale list",
+        command:
+          "/formant <-12..12> [mix] | deep | giant | bright | tiny | on | off",
+        summary:
+          "formant shift at constant pitch · /formant -4 deeper · /formant 3 smaller",
       },
       {
-        command: "tuning <name> | edo <n> | scl <file> | off",
-        summary: "song tuning · tuning 19-edo · tuning just · tuning list",
+        command:
+          "/vowel <v> [<to> [<morph>]] | ee | to <v>|off | morph <0..1> | off",
+        summary: "vowel filter · /vowel a · /vowel a o 0.5 morphs a toward o",
       },
       {
-        command: "tuning ref <hz> | root <note> | map linear|nearest",
-        summary: "A4 reference · degree-0 key · keys per step",
+        command:
+          "vocoder [preset] | src <track> | <param> <value|reset> | off | presets",
+        summary:
+          "vocode the focused voice onto a synth (classic robot talkbox choir glass whisper smear lofi) · help vocoder lists params",
       },
+    ],
+  },
+  {
+    group: "voice · clips",
+    entries: [
+      { command: "vocal", summary: "voice tools: lists every verb" },
       {
-        command: "tuning track <…> | track off",
-        summary: "this track's tuning · off follows the song",
+        command:
+          "clip [id] gain -3 | gain by -3 | fade .01 .2 | fade in .01 | split 7",
+        summary: "edit an audio clip (dB, seconds, 1-based bars)",
       },
       {
-        command: "cents <id> <±c>",
-        summary: "detune one note · cents n3 -14 · add E4-14c at 0",
+        command:
+          "clip [id] trim offset 1 dur 4|end | rev | repeat 2 [to 32] | mute | rm",
+        summary: "trim, reverse, repeat, mute or remove a clip",
       },
+      ...VOCAL_VERBS.map((verb) => ({
+        command: `vocal ${verb.usage}`,
+        summary: verb.summary,
+      })),
+    ],
+  },
+  {
+    group: "effects",
+    entries: [
       {
-        command: "section <name> <a>-<b> | add | dup | move | rename | delete",
-        summary: "song sections · section chorus 9-16 · section lists them",
+        command: "fx <effect> <param> <value> | on | off | preset <name>",
+        summary:
+          "effects · fx delay mix 0.3 · fx reverb on · fx alone lists them",
       },
       {
-        command: "section loop | jump | mute | vary <name>",
-        summary: "section loop chorus · section mute verse drums",
+        command: "filter <hz> [res] · delay <beats> [fb] [mix] · reverb <mix>",
+        summary:
+          "shortcuts for fx filter, delay and reverb · filter 1200 · delay 0.5 · reverb 0.3",
       },
       {
-        command: "form <section…> | off | bake",
-        summary: "song form · form intro verse chorus*2 outro",
+        command: "rig <preset> | reset",
+        summary:
+          "guitar amp and pedals · rig crunch · rig jangle · rig metal · rig alone lists them",
       },
       {
-        command: "build | drop | fill [<section> | <a>-<b>]",
-        summary: "riser, roll, sweep · pre-drop cut and impact · drum fill",
+        command: "stomp|head|cab <type> | <param> <value>",
+        summary:
+          "pedal, amp, cabinet · stomp rat · head gain 7 gate -55 · cab 4x12",
       },
       {
-        command: "hit <voice> at <beat>",
-        summary: "kit tracks · hit kick at 0",
+        command: "fx wobble|bloom|swell|double [param value]",
+        summary:
+          "shoegaze · fx wobble depth 30 · fx double · fx reverb ir builtin:reverse",
       },
+    ],
+  },
+  {
+    group: "rhythm",
+    entries: [
       {
-        command: "pattern <voice> <beats...> | every <step>",
-        summary: "pattern kick every 1",
+        command: "hit <drum> at <beat>",
+        summary: "one hit on a kit track · hit kick at 0",
       },
-      { command: "clear <voice>", summary: "remove one drum voice" },
       {
-        command: "euclid <voice> <pulses> [<steps>] [rotate <n>]",
-        summary: "generated rhythm · euclid hat 7 16 rotate 2",
+        command: "pattern <drum> <beats...> | every <step>",
+        summary: "a drum on beats · pattern kick every 1",
       },
+      { command: "clear <drum>", summary: "remove one drum's hits" },
       {
-        command: "euclid <voice> <field> <value> | off | freeze",
-        summary: "repeats pace accent prob swing …",
+        command: "euclid <drum> <pulses> [<steps>] [rotate <n>]",
+        summary: "generated rhythm · euclid hat 7 16 rotate 2",
       },
-      { command: "grid <voice> <x.X.>", summary: "explicit steps · X accent" },
-      { command: "undo", summary: "step back · Ctrl-Z" },
-      { command: "redo", summary: "step forward · Ctrl-Y" },
-    ],
-  },
-  {
-    group: "session",
-    entries: [
-      { command: "/sessions", summary: "list sessions in this workspace" },
-      { command: "/resume [<n>|<name>|<id>]", summary: "switch session" },
-      { command: "/rename <name>|--auto", summary: "name this session" },
-      { command: "/fork [<name>]", summary: "copy into a new session" },
-      { command: "/status", summary: "name · revision · digest · storage" },
       {
-        command: "/export <file>",
-        summary: "write track.loop/v1 JSON, or MIDI for .mid",
+        command: "euclid <drum> <field> <value> | off | freeze",
+        summary: "repeats pace accent prob swing …",
       },
-      { command: "/import <file>", summary: "replace the score from a file" },
+      { command: "grid <drum> <x.X.>", summary: "explicit steps · X accent" },
       {
-        command: "/sample [<path> [as <voice>]]",
-        summary: "add a sample voice · list voices",
+        command: "pattern [name]",
+        summary: "groove picker · hear each groove move",
       },
       {
-        command: "/bpm <n> [<voice>]",
-        summary:
-          "the sample's own tempo (slash needed: bare bpm is song tempo)",
+        command: "/kit [name]",
+        summary: "kit picker · synth kits, then sample kits",
       },
       {
-        command: "/fitmode [repitch|beats|tones|auto] [<voice>]",
-        summary: "how it fits · alone suggests one from the sound",
+        command: "pack list|info|use|add",
+        summary: "sample packs · pack use 909/bd",
       },
       {
-        command: "/len <beats> [<voice>]",
-        summary: "the sample lasts n beats of the song",
+        command: "euclid [drum]",
+        summary: "euclid rhythm editor · Ctrl-K › Rhythm",
       },
     ],
   },
   {
-    group: "window",
+    group: "chords",
     entries: [
       {
-        command: "/track <name>",
-        summary: "focus a track, creating it if new",
+        command: "key <tonic> <mode> | none",
+        summary: "song key · key A minor · key F# dorian",
       },
-      { command: "/tracks", summary: "list tracks" },
-      { command: "/view focus|all", summary: "one track or every track" },
-      { command: "/transcript", summary: "scrollable log · Ctrl-O" },
-      { command: "/theme default|high-contrast|mono", summary: "colors" },
-      { command: "/motion on|off", summary: "animation" },
-      { command: "/model [alias]", summary: "pick a model · cost per prompt" },
       {
-        command: "/login [gateway|openrouter|codex|claude]",
-        summary: "sign in to a provider",
+        command: "scale [<tonic>] <name> | list",
+        summary: "song scale · scale D hijaz · scale yaman · scale list",
       },
       {
-        command: "/logout [provider]",
-        summary: "forget keys and the saved choice",
+        command: "tuning <name> | edo <n> | scl <file> | off",
+        summary: "song tuning · tuning 19-edo · tuning just · tuning list",
       },
-      { command: "/auth [--check]", summary: "provider and audio status" },
-      { command: "/play [on|off]", summary: "keyboard play mode · Ctrl-P" },
       {
-        command: "/play degrees|chromatic",
-        summary: "home row plays the key's scale degrees (any tuning) · i",
+        command: "tuning ref <hz> | root <note> | map linear|nearest",
+        summary: "A4 reference · degree-0 key · keys per step",
       },
       {
-        command: "/pattern [name]",
-        summary: "drum groove picker · moving previews",
+        command: "tuning track <…> | track off",
+        summary: "this track's tuning · off follows the song",
       },
       {
-        command: "/kit [name]",
-        summary: "drum kit picker · synth kits, then samples",
+        command: "cents <id> <±c>",
+        summary: "detune one note · cents n3 -14 · add E4-14c at 0",
       },
       {
-        command: "/pack list|info|use|add",
-        summary: "sample packs · /pack use 909/bd",
+        command: "progression <chords> [each 4] [at 0] [bass]",
+        summary:
+          "sustained voice-led chords · progression i7 IV7 each 8 · progression Am7 D9 bass",
       },
       {
-        command: "/euclid [voice]",
-        summary: "T-1 style rhythm editor · Rhythm in /menu",
+        command: "strum [chords] [pattern] [strokes D-DU-UDU] [speed 22ms]",
+        summary:
+          "strummed guitar chords · strum G D Em C folk · strum I V vi IV · strum alone strums the track's chords",
       },
       {
-        command: "/menu [section]",
-        summary: "every setting by hand · Ctrl-K",
+        command: "/chords auto|manual|off",
+        summary: "chords in play mode · /chords alone shows settings",
       },
       {
-        command: "/try <sound command>",
-        summary: "hear it on a loop first · a A/B · enter keep",
+        command: "play degrees|in-key|chromatic",
+        summary:
+          "in play mode the home row plays the key's degrees (any tuning)",
       },
+    ],
+  },
+  {
+    group: "mix",
+    entries: [
+      { command: "volume <0..1>", summary: "track level" },
+      { command: "pan <-1..1>", summary: "left … right" },
+      { command: "mute", summary: "silence this track" },
+      { command: "unmute", summary: "hear it again" },
+      { command: "solo", summary: "only this track" },
+      { command: "unsolo", summary: "every track again" },
       {
-        command: "/click on|off|<volume>",
-        summary: "metronome · /count-in 0-2 · /grid 1/16",
+        command: "automate <lane> at <beat> <value>",
+        summary: "volume pan filter resonance delay-feedback delay-mix wt",
       },
       {
-        command: "/chords auto|manual|off",
-        summary: "play-mode chords · /chords for settings",
+        command: "automate <lane> points <b:v>...",
+        summary: "several points · automate pan points 0:-1 4:1",
       },
+      { command: "automate <lane> remove <beat>", summary: "drop one point" },
+      { command: "clear [<lane>] automation", summary: "drop a lane's points" },
       {
-        command: "/help [topic]",
-        summary: "start here · /help all for everything",
+        command: "master <unit> on|off | preset <name> | <param> <value>",
+        summary:
+          "song master · eq glue tape width limiter · master glue ratio 4",
       },
       {
-        command: "/guide [topic]",
-        summary: "short how-to guides · F1",
+        command: "master <target> | target <lufs> | measure | off",
+        summary:
+          "loudness · master streaming · master target -9 · master measure",
       },
     ],
   },
   {
-    group: "keys",
+    group: "arrange",
     entries: [
-      { command: "Enter", summary: "submit" },
-      { command: "Shift-Enter", summary: "newline" },
-      { command: "Alt-Enter", summary: "queue the request" },
-      { command: "Ctrl-Q", summary: "toggle queue mode" },
-      { command: "Ctrl-Z / Ctrl-Y", summary: "undo / redo" },
-      { command: "Ctrl-O", summary: "transcript" },
-      { command: "Esc", summary: "cancel the agent · back one level" },
-      { command: "?", summary: "keys for the screen you are on" },
-      { command: "Space", summary: "play/pause on an empty prompt" },
+      { command: "add <note> at <beat> [for <beats>]", summary: "add C4 at 0" },
+      { command: "remove <id>", summary: "delete a note" },
+      { command: "move <id> to <beat>", summary: "shift a note" },
+      { command: "length <id> <beats>", summary: "resize a note" },
+      { command: "velocity <id> <0..1>", summary: "note loudness" },
+      { command: "clear", summary: "remove this track's notes" },
+      { command: "track <name>", summary: "focus a track, creating it if new" },
+      { command: "tracks", summary: "list tracks" },
       {
-        command: "Ctrl-P",
-        summary: "play mode · Z/X octave · R record · Q chords",
+        command: "track rm|move <name> [<position>]",
+        summary:
+          "remove a track (Ctrl-Z undoes) or move it · rm and delete are aliases",
       },
+      { command: "track name <text>", summary: "rename this track" },
       {
-        command: "Ctrl-K",
-        summary: "menu · ←→ adjust · / filter · x reset",
+        command: "track rate|phase|loop <n> | off",
+        summary: "polytempo · track rate 3/2 · track loop 3",
       },
-      { command: "Ctrl-C", summary: "exit" },
-    ],
-  },
-];
-
-/**
- * `/help` with no topic: a short, task-first guide. Each row is something to
- * type or press, then what it does. The full reference is `/help all` (or one
- * group: `/help music`).
- */
-export const HELP_GUIDE: readonly HelpSection[] = [
-  {
-    group: "start here" as HelpGroup,
-    entries: [
-      { command: "type a request", summary: "“add a walking bass in A minor”" },
-      { command: "ctrl-p", summary: "play notes on the computer keyboard" },
       {
-        command: "ctrl-k",
-        summary: "menu: sound, effects, performance, mix, master, arrange …",
+        command: "track phasing <beats> [over <beats>|hold <n>]",
+        summary: "Reich phasing · track phasing 3 hold 8 · track time off",
       },
-      { command: "? · ctrl-z · ctrl-y", summary: "keys here · undo · redo" },
     ],
   },
   {
-    group: "play notes" as HelpGroup,
+    group: "arrange · song",
     entries: [
       {
-        command: "ctrl-p, a s d f …",
-        summary: "piano keys · z x octave · esc leave",
+        command: "section <name> <a>-<b> | add | dup | move | rename | remove",
+        summary:
+          "song sections · section chorus 9-16 · section alone lists them",
       },
       {
-        command: "r, then space",
-        summary: "record over the loop (one undo a bar)",
+        command: "section loop | jump | mute | vary <name>",
+        summary: "section loop chorus · section mute verse drums",
+      },
+      {
+        command: "form <section…> | off | bake",
+        summary: "song form · form intro verse chorus*2 outro",
+      },
+      {
+        command: "build | drop | fill [<section> | <a>-<b>]",
+        summary: "riser, roll, sweep · pre-drop cut and impact · drum fill",
+      },
+      {
+        command: "style <id> [bars] [seed]",
+        summary: "a whole song in a style · style bebop 16 3 · style again",
       },
-    ],
-  },
-  {
-    group: "make drums" as HelpGroup,
-    entries: [
       {
-        command: "/pattern · /kit",
-        summary: "pick a groove · pick a drum kit",
+        command: "style list|search|info · style blend <a> <b> [w]",
+        summary: "the style tree · style search maqam",
       },
-      { command: "/euclid", summary: "rhythm editor: pulses, steps, rotation" },
+      { command: "bars <count>", summary: "loop length, 1–256" },
+      { command: "extend <count> bars", summary: "lengthen the loop" },
     ],
   },
   {
-    group: "shape the sound" as HelpGroup,
+    group: "project",
     entries: [
+      { command: "play", summary: "start the transport" },
+      { command: "pause", summary: "stop the transport" },
       {
-        command: "ctrl-k › Sound",
-        summary: "instrument, strings, envelope, filter, wavetable",
+        command: "/play [on|off]",
+        summary: "play mode: the computer keyboard plays notes · ctrl-p",
       },
-      { command: "ctrl-k › Effects", summary: "delay, reverb, distortion …" },
+      { command: "tempo <bpm>", summary: "20–300 BPM" },
       {
-        command: "master streaming",
-        summary: "finish: -14 LUFS, limiter · master measure",
+        command: "tempo <bpm> at <beat>|bar <n> [ramp|exp]",
+        summary: "tempo change · tempo 90 at bar 9 ramp · tempo clear",
+      },
+      {
+        command: "rit|accel [<n> bars] [to <bpm>] [at bar <n>]",
+        summary: "gradual · rit 4 bars to 80 · a tempo · tempo primo",
       },
-      { command: "/try fx reverb mix 0.6", summary: "hear it before keeping" },
+      {
+        command: "fermata [at <beat>|at bar <n>|at end] [<extra beats>]",
+        summary: "hold a beat · fermata at 31 2 · fermata clear",
+      },
+      { command: "meter <1..16>", summary: "beats per bar" },
+      {
+        command: "meter <n>/<d> [at bar <n>]",
+        summary: "meter change · meter 7/8 at bar 5 · meter clear",
+      },
+      {
+        command: "/click on|off|<volume>",
+        summary: "metronome · /count-in 0-2 · grid 1/16",
+      },
+      {
+        command: "export <file> [stems]",
+        summary:
+          "JSON, MIDI for .mid, WAV for .wav · export song.wav · export mix.wav stems",
+      },
+      { command: "import <file>", summary: "replace the score from a file" },
+      {
+        command: "calibration [0|1|latest|off]",
+        summary: "sound fixes · 1 chokes hats, levels keys · 0 legacy",
+      },
+      { command: "undo", summary: "step back · Ctrl-Z" },
+      { command: "redo", summary: "step forward · Ctrl-Y" },
+      { command: "/status", summary: "name · revision · digest · storage" },
     ],
   },
   {
-    group: "shape the performance" as HelpGroup,
+    group: "project · window",
     entries: [
+      { command: "/view focus|all", summary: "one track or every track" },
+      { command: "/transcript", summary: "scrollable log · Ctrl-O" },
+      { command: "/theme default|high-contrast|mono", summary: "colors" },
+      { command: "/motion on|off", summary: "animation" },
+      {
+        command: "/menu [section]",
+        summary: "every setting by hand · Ctrl-K · /menu <topic>",
+      },
       {
-        command: "art staccato bar 2",
-        summary: "humanize 8 5 · ctrl-k › Sound › performance",
+        command: "help [topic]",
+        summary: "start here · help <topic> · help all for everything",
       },
+      { command: "/guide [topic]", summary: "short how-to guides · F1" },
     ],
   },
   {
-    group: "chords" as HelpGroup,
+    group: "project · session",
     entries: [
-      { command: "key A minor", summary: "set the song key" },
-      {
-        command: "ctrl-p, then q",
-        summary: "chord mode · 1–4 type · 5–8 extension · n next",
-      },
+      { command: "/sessions", summary: "list sessions in this workspace" },
+      { command: "/resume [<n>|<name>|<id>]", summary: "switch session" },
+      { command: "/rename <name>|--auto", summary: "name this session" },
+      { command: "/fork [<name>]", summary: "copy into a new session" },
     ],
   },
   {
-    group: "song structure" as HelpGroup,
+    group: "agent",
     entries: [
       {
-        command: "section verse 1-8",
-        summary: "name bars · form verse chorus*2 orders them",
+        command: "/model [alias]",
+        summary: "pick the agent's model · /model lists them · /model fast",
       },
       {
-        command: "build · drop · fill",
-        summary: "transitions · ctrl-k › Arrange · /help arrange",
+        command: "/model key [gateway|openrouter|codex|claude]",
+        summary: "add an agent key (optional) · finds existing setups first",
+      },
+      {
+        command: "/logout [provider]",
+        summary: "forget keys and the saved choice",
+      },
+      { command: "/auth [--check]", summary: "provider and audio status" },
+      {
+        command: "/showme on|quiet|off",
+        summary:
+          "the agent types its commands in your prompt bar as it streams",
       },
     ],
   },
+];
+
+/**
+ * `/help` with no topic: start here, then the ten topics. Each row is
+ * something to type or press, then what it does. The full reference is
+ * `/help all`; one topic is `/help <topic>`.
+ */
+export const HELP_GUIDE: readonly HelpSection[] = [
   {
-    group: "more" as HelpGroup,
+    group: "start here",
     entries: [
       {
-        command: "rit 4 bars to 80",
-        summary: "tempo, fermatas, meter · tuning pelog · scale yaman",
+        command: "type a request",
+        summary: "“add a walking bass in A minor” (with an agent)",
+      },
+      {
+        command: "style deep-house",
+        summary: "a whole song in a style · style list",
       },
       {
-        command: "/help all",
-        summary: "every command and key · /guide feature guides · F1",
+        command: "space · ctrl-p",
+        summary: "play · play mode: the keyboard plays notes",
       },
+      { command: "ctrl-k", summary: "menu: every setting by hand" },
+      { command: "? · ctrl-z · ctrl-y", summary: "keys here · undo · redo" },
+    ],
+  },
+  {
+    group: "topics · help <topic>",
+    entries: [
+      ...TOPICS.map((id) => ({ command: id, summary: TOPIC_SUMMARY[id] })),
+      { command: "all", summary: "every command · /guide <topic> · F1" },
     ],
   },
 ];
 
-/** Topics `/help <topic>` takes, besides `all`. */
-export const HELP_TOPICS = [
-  "music",
-  "session",
-  "window",
-  "keys",
-  "arrange",
-] as const;
+/** Topics `/help <topic>` takes, besides `all` (aliases resolve too). */
+export const HELP_TOPICS = TOPICS;
+
+/**
+ * `/help keys`: every screen's `?` panel, straight from tui/grammar.ts
+ * KEYS, so the reference and the panels never disagree.
+ */
+export function keysLines(width = 80): string[] {
+  const seen = new Set<string>();
+  const sections = (Object.keys(KEYS) as KeyScreen[]).flatMap((screen) =>
+    KEYS[screen].map((section) => ({
+      title:
+        section.title === screen || screen === "prompt"
+          ? section.title
+          : `${screen} · ${section.title}`,
+      rows: section.rows,
+    })),
+  );
+  const column =
+    Math.min(
+      24,
+      Math.max(
+        ...sections.flatMap((s) => s.rows.map(([keys]) => displayWidth(keys))),
+      ),
+    ) + 2;
+  const lines = ["── keys"];
+  for (const section of sections) {
+    const key = JSON.stringify(section.rows);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    lines.push("", truncate(`── ${section.title}`, width));
+    for (const [keys, action] of section.rows)
+      lines.push(
+        truncate(
+          `${keys}${" ".repeat(Math.max(1, column - displayWidth(keys)))}${action}`,
+          width,
+        ),
+      );
+  }
+  return lines;
+}
+
+/** The last rows of a topic page: the same id in the other two doors. */
+function doors(id: TopicId, width: number): string[] {
+  return ["", truncate(`guide ${id} · menu ${id} · help all`, width)];
+}
+
+/** A topic's groups: `sound`, then `sound · performance`, `sound · samples`. */
+export function topicSections(id: TopicId): readonly HelpSection[] {
+  return HELP_SECTIONS.filter(
+    (section) => section.group === id || section.group.startsWith(`${id} · `),
+  );
+}
+
+/** One topic's page: its groups, then where else the topic opens. */
+function topicLines(id: TopicId, width: number): string[] {
+  if (id === "keys") return [...keysLines(width), ...doors(id, width)];
+  return [...sectionLines(topicSections(id), width), ...doors(id, width)];
+}
 
 /**
- * Rows for `/help [topic]`: the guide with no topic, the full reference for
- * `all`, one group for its name; undefined for an unknown topic.
+ * Rows for `/help [topic]`: the start page with no topic, the full
+ * reference for `all`, a topic for its id or an alias, a command's rows
+ * for its verb (`/help vocoder`); undefined for an unknown word.
  */
 export function helpTopicLines(
   topic: string | undefined,
@@ -496,34 +672,91 @@ export function helpTopicLines(
   if (!name) return sectionLines(HELP_GUIDE, width, 20);
   if (name === "all" || name === "commands" || name === "reference")
     return helpLines(width);
-  if (name === "arrange" || name === "arrangement" || name === "sections")
-    return sectionLines([arrangeSection()], width);
-  const group = HELP_SECTIONS.find((section) => section.group === name);
-  return group ? sectionLines([group], width) : undefined;
+  if ((TOPICS as readonly string[]).includes(name))
+    return topicLines(name as TopicId, width);
+  const spelled = HELP_COMMAND_ALIASES[name];
+  if (spelled) return commandTopic(spelled, width, name);
+  const alias = resolveTopic(name);
+  // A topic alias wins unless a reference row starts with the word:
+  // `/help sections` is the arrange topic, `/help scale` the command.
+  const command =
+    alias && !hasRow(name) ? undefined : commandTopic(name, width);
+  if (command)
+    return alias
+      ? [...command, "", truncate(`see also help ${alias}`, width)]
+      : command;
+  return alias ? topicLines(alias, width) : undefined;
 }
 
-/** `/help arrange`: every arranging command with its full usage. */
-function arrangeSection(): HelpSection {
-  const verbs = ["section", "sections", "form", "build", "drop", "fill"];
-  return {
-    group: "arrange" as HelpGroup,
-    entries: [
-      // Usage strings run long: wrapped onto continuation rows.
-      ...verbs.flatMap((verb) =>
-        wrapWords(USAGE[verb] ?? "", 46).map((summary, index) => ({
-          command: index === 0 ? verb : "",
-          summary,
-        })),
-      ),
-      { command: "/menu arrange", summary: "the Arrange menu (ctrl-k)" },
-      {
-        command: "dawg render --section <name>",
-        summary: "export one section",
-      },
-    ],
-  };
+/** True when a reference row starts with `name` (`/scale`, `scale …`). */
+function hasRow(name: string): boolean {
+  const verb = name.replace(/[^a-z0-9-]/g, "");
+  return HELP_SECTIONS.some((section) =>
+    section.entries.some((entry) =>
+      new RegExp(`^/?${verb}(\\s|$)`, "i").test(entry.command),
+    ),
+  );
 }
 
+/**
+ * `/help <command>` (`/help vocoder`, `/help clip`): the command's rows
+ * from every group, then its full usage wrapped; undefined when no command
+ * has that name.
+ */
+function commandTopic(
+  name: string,
+  width: number,
+  usageKey = name,
+): string[] | undefined {
+  const pattern = name
+    .replace(/[^a-z0-9 -]/g, "")
+    .trim()
+    .replace(/ +/g, "\\s+");
+  const own = (command: string) =>
+    new RegExp(`^/?${pattern}(\\s|$)`, "i").test(command);
+  const rows = HELP_SECTIONS.flatMap((section) =>
+    section.entries.filter((entry) => own(entry.command)),
+  );
+  const usage = USAGE[usageKey] ?? USAGE[name];
+  if (rows.length === 0 && !usage) return undefined;
+  const wrap = Math.max(30, width - 2);
+  // A usage line that repeats a row keeps only what it adds (examples).
+  const extra = usage
+    ? rows.reduce((text, entry) => {
+        const bare = (value: string) =>
+          value.replace(/^\//, "").replace(/\s*\|\s*/g, "|");
+        return bare(text).startsWith(bare(entry.command))
+          ? bare(text)
+              .slice(bare(entry.command).length)
+              .replace(/^\s*·\s*/, "")
+          : text;
+      }, usage)
+    : "";
+  // Examples a row summary already shows are not repeated.
+  const shown = rows.map((entry) => entry.summary).join(" · ");
+  const added = extra
+    .split(" · ")
+    .filter((part) => part && !shown.split(" · ").includes(part))
+    .join(" · ");
+  return [
+    `── ${name}`,
+    ...rows.flatMap((entry) => [
+      ...wrapWords(entry.command, wrap),
+      ...wrapWords(entry.summary, wrap - 2).map((line) => `  ${line}`),
+    ]),
+    ...(added ? ["", ...wrapWords(added, wrap)] : []),
+  ];
+}
+
+/**
+ * Typed aliases that /help shows under their one word (design §8.2): the
+ * alias opens the page and the title, heading and rows name the canonical
+ * command.
+ */
+export const HELP_COMMAND_ALIASES: Readonly<Record<string, string>> = {
+  login: "model key",
+};
+
 function wrapWords(text: string, width: number): string[] {
   const rows: string[] = [];
   let row = "";
@@ -553,18 +786,21 @@ function sectionLines(
     );
   for (const section of sections) {
     if (lines.length > 0) lines.push("");
-    lines.push(`── ${section.group}`);
+    lines.push(truncate(`── ${section.group}`, width));
     for (const entry of section.entries) {
       const pad = Math.max(1, column - entry.command.length);
       lines.push(
-        `${entry.command}${" ".repeat(pad)}${entry.summary}`.slice(0, width),
+        truncate(`${entry.command}${" ".repeat(pad)}${entry.summary}`, width),
       );
     }
   }
   return lines;
 }
 
-/** Overlay rows: a heading per group, then `command  summary` lines. */
+/**
+ * `/help all`: a heading per topic, then `command  summary` lines, then
+ * the keys of every screen.
+ */
 export function helpLines(width = 80): string[] {
   const lines: string[] = [];
   const column = Math.min(
@@ -575,27 +811,25 @@ export function helpLines(width = 80): string[] {
   );
   for (const section of HELP_SECTIONS) {
     if (lines.length > 0) lines.push("");
-    lines.push(`── ${section.group}`);
+    lines.push(truncate(`── ${section.group}`, width));
     for (const entry of section.entries) {
       const pad = Math.max(1, column - entry.command.length);
       lines.push(
-        `${entry.command}${" ".repeat(pad)}${entry.summary}`.slice(0, width),
+        truncate(`${entry.command}${" ".repeat(pad)}${entry.summary}`, width),
       );
     }
   }
-  return lines;
+  return [...lines, "", ...keysLines(width)];
 }
 
 /** The `Commands:` block of `dawg --help`. */
 export function helpText(): string {
-  return HELP_SECTIONS.filter((section) => section.group !== "keys")
-    .map(
-      (section) =>
-        `${section.group}:\n${section.entries
-          .map((entry) => `  ${entry.command}`)
-          .join("\n")}`,
-    )
-    .join("\n");
+  return HELP_SECTIONS.map(
+    (section) =>
+      `${section.group}:\n${section.entries
+        .map((entry) => `  ${entry.command}`)
+        .join("\n")}`,
+  ).join("\n");
 }
 
 /** Usage for a known verb, shown instead of sending a near-miss to the agent. */
@@ -603,17 +837,20 @@ export const USAGE: Readonly<Record<string, string>> = {
   click: "/click on|off|<volume> · /click 50%",
   "count-in": "/count-in 0|1|2",
   chords:
-    "/chords auto|manual|off · voicing <n> · spread · bass · perform · rate · octaves · sevenths · preset · style",
+    "/chords auto|manual|off · voicing <n> · spread · bass · perform · rate · octaves · sevenths · preset · style · strokes · speed",
   key: "key <tonic> <mode> | none · key A minor",
   scale: "scale [<tonic>] <name> | list · scale D hijaz",
   tuning:
     "tuning <name> | edo <n> | ratios … | cents … | scl <file> [kbm <file>] | ref <hz> | root <note> | map linear|nearest | track … | off · tuning 19-edo",
-  tune: "tuning <name> | edo <n> | scl <file> | off · tuning list",
+  calibration: "calibration [0|1|latest|off] · calibration latest",
+  tune: "tuning <name> | edo <n> | scl <file> | off · tuning list · pitch correction is autotune",
+  autotune:
+    "autotune [hard|robot|warble|trap|pop|natural|gentle|guided|locked] | to scale|chromatic|chord|notes [track] | key <key> | speed hold glide <ms> | relax amount center drift <0..1> | flex <0..100> | vib <Hz> vibmod <st> | voice auto|bass|tenor|alto|soprano | reset | off | presets · autotune hard · autotune natural flex 40",
   cents: "cents <id> <±cents> · cents n3 -14",
-  grid: "/grid 1/4|1/8|1/8T|1/16|1/16T|1/32",
+  grid: "grid 1/4|1/8|1/8T|1/16|1/16T|1/32",
   tempo:
     "tempo takes 20…300 · tempo 120 · tempo 90 at bar 9 [ramp|exp] · tempo remove bar 9 · tempo clear · tempo map",
-  bpm: "tempo takes 20…300 · tempo 120 · a sample's own tempo: /bpm 174 [<voice>] · /bpm off",
+  bpm: "tempo takes 20…300 · tempo 120 · a sample's own tempo: /bpm 174 [<sample>] · /bpm off",
   rit: "rit [<n> bars|beats] [to <bpm>] [at bar <n>|<beat>] [exp] · rit 4 bars to 80",
   ritardando:
     "rit [<n> bars|beats] [to <bpm>] [at bar <n>|<beat>] [exp] · rit 4 bars to 80",
@@ -635,14 +872,14 @@ export const USAGE: Readonly<Record<string, string>> = {
   bars: "bars takes 1…256 · bars 8",
   extend: "extend <count> bars · extend 4 bars",
   instrument:
-    "instrument <name> · sine piano pluck bass saw square triangle wavetable kit · pianos: grand upright felt honkytonk prepared · synth: sawtooth supersaw pulse white pink z_square…",
+    "instrument <name> · sine piano pluck bass sawtooth square triangle wavetable kit · pianos: grand upright felt honkytonk prepared · electric: epiano suitcase dyno wurli clav funkclav · synth: supersaw pulse white pink z_square · voices: vocal aah ooh choir chorale khoomei sygyt kargyraa vocoder…",
   volume: "volume takes 0…1 · volume 0.8",
   vol: "volume takes 0…1 · volume 0.8",
   pan: "pan takes -1…1 · pan -0.5",
   wt: "wt <table> | wt <0..1> | wt list · wt basic · wt wt_digital:2",
   wavetable: "wt <table> | wt <0..1> | wt list · wt basic · wt wt_digital:2",
   grain:
-    "grain <preset> | <param> <value> | on [voice V] | src synth:<name>|voice V | reset | off | presets · grain cloud · grain pitch 12",
+    "grain <preset> | <param> <value> | on [voice V] | src synth:<name>|voice V | reset | off | presets · sync 1/64…1/1 (t triplet, d or . dotted) · grain cloud · grain pitch 12 · grain sync 1/8.",
   granular:
     "grain <preset> | <param> <value> | on [voice V] | src synth:<name>|voice V | reset | off | presets · grain cloud",
   warpmode: "warpmode none|asym|bendp|bendm|bendmp|sync|quant",
@@ -651,58 +888,95 @@ export const USAGE: Readonly<Record<string, string>> = {
   reverb: "reverb <mix> [size] · reverb 0.3 0.6 · reverb off",
   automate: "automate <lane> at <beat> <value> · automate volume at 0 0.5",
   automation: "automate <lane> at <beat> <value> · automate volume at 0 0.5",
-  hit: "hit <voice> at <beat> · hit kick at 0",
-  pattern: "pattern <voice> <beats...> | every <step> · pattern kick every 1",
-  clear: "clear · clear <voice> · clear [<lane>] automation",
+  hit: "hit <drum> at <beat> · hit kick at 0",
+  pattern: "pattern <drum> <beats...> | every <step> · pattern kick every 1",
+  clear: "clear · clear <drum> · clear [<lane>] automation",
   track:
-    "/track <name> · /track drums · track rate <0.125..8>|<a>/<b>|off · track phase <beats> · track cycle <beats> · track phasing <beats> [over <beats>]",
-  tracks: "/tracks",
+    "track <name> · track drums · track rm <name> · track move <name> <position> · track rate <0.125..8>|<a>/<b>|off · track phase <beats> · track loop <beats> · track phasing <beats> [over <beats>]",
+  tracks: "tracks",
   sessions: "/sessions",
   resume: "/resume [<n>|<name>|<id>]",
   rename: "/rename <name> | --auto",
   fork: "/fork [<name>]",
   status: "/status",
-  export: "/export <file> · /export loop.track.json",
-  import: "/import <file> · /import loop.track.json",
+  export: "export <file> · export loop.track.json",
+  import: "import <file> · import loop.track.json",
   sample:
-    "/sample <path> [as <voice>] · /sample set <voice> <control> <value>… · /sample set brk fit on clip 1",
-  samples: "/sample · lists the focused track's voices",
+    "/sample <path> [as <sample>] · /sample set <sample> <control> <value>… · /sample set brk fit on clip 1 · /sample set soft vel 0-63 rr a",
+  samples: "/sample · lists the focused track's samples",
   fitmode:
-    "/fitmode [repitch|beats|tones|auto|off] [<voice>] · /fitmode beats · /fitmode auto brk",
-  len: "/len <beats> [<voice>] · /len 16 · /len off",
+    "fitmode [repitch|beats|tones|auto|off] [<sample>] · fitmode beats · fitmode auto brk",
+  len: "len <beats> [<sample>] · len 16 · len off",
+  shift:
+    "shift <semitones> [formant keep|follow|<n>] [<sample>] · shift 7 formant keep · shift 0",
+  fade: "fade [in|out] <seconds> [<sample>] · fade out 0.5 · fade in 0.05 · fade off",
+  resample:
+    "resample <track>|orbit <n>|master [section <name>|bars a-b] [post] [grain] [as <id>] · resample lead · resample drums bars 1-2 grain · resample master section chorus",
+  bounce: "resample <track>|orbit <n>|master [section <name>|bars a-b] [grain]",
   view: "/view focus | all",
   transcript: "/transcript",
   log: "/transcript",
   theme: "/theme default | high-contrast | mono",
   motion: "/motion on | off",
-  model: "/model [alias | vendor/model]",
-  login: "/login [gateway | openrouter | codex | claude]",
+  model:
+    "/model [fast | alias | vendor/model] · /model key [gateway | openrouter | codex | claude]",
+  models: "/model [fast | alias | vendor/model] · /model key [provider]",
+  login: "/model key [gateway | openrouter | codex | claude]",
   logout: "/logout [provider]",
   auth: "/auth [--check]",
-  help: "/help [topic] · /help all · /help music|session|window|keys",
-  guide: "/guide [topic] · /guide chords · F1",
+  help: "help [topic] · help all · help sound|voice|effects|rhythm|chords|mix|arrange|project|keys|agent",
+  guide: "/guide [topic] · /guide voice · F1 · the same topics as help",
   fx: "fx <effect> <param> <value> | on | off | preset <name> · fx delay mix 0.3",
   synth: "synth <param> <value> | preset <name> · synth lpf 1200",
   string:
     "string <preset> | preset <name> | <param> <value> | presets | reset | off · string koto",
-  rig: "rig clean|crunch|punk|ragged|lead|metal|fuzz|octave|funk|wah|bachata|spring|bassdrive|reese|jangle|alt | reset",
+  bowed:
+    "bowed [violin|viola|cello|contrabass|fiddle|erhu|kamancheh|violins|violas|cellos|contrabasses|pizz|trem] | <param> <value> | presets · bowed violin · bowed pressure 0.7",
+  rig: "rig clean|crunch|punk|ragged|lead|metal|fuzz|octave|funk|wah|bachata|spring|bassdrive|reese|jangle|alt|shoegaze|glide|dreampop|swell|ebow | reset",
+  guitar: `guitar tune ${GUITAR_TUNING_NAMES.join("|")} | E A D G B E · capo 0..12 · hand 3..6 · ring 0..1 · position · reset`,
+  progression:
+    "progression i7 IV7 i7 IV7 [each 8] [at 0] [bass] · numerals in the song key or symbols (Am7 D9) · block chords that hold for each span",
+  strum:
+    "strum G D Em C [folk|pop|punk|…] [strokes D-DU-UDU] [speed 22ms] [each 4] [at 0] · strum alone strums the track's chords",
   stomp:
     "stomp fuzz|face|od|rat|octave | gain <0-10> tone <0-1> level <dB> | off",
   head: "head clean|chime|crunch|lead|high|solid|bass | gain bass mid treble presence master <0-10> | gate <dB> | off",
   cab: "cab 1x12|2x12|4x12|1x10|open|8x10|1x15|di | mic <0-1> | off",
-  keys: "keys <param> <value> | preset <name> | reset | presets · keys hardness 0.3 · keys stretch 0",
+  keys: "keys <param> <value> | preset <name> | reset | presets · keys hardness 0.3 · keys stretch 0 · keys sym 0.5 (sympathetic bloom under the sustain pedal)",
   piano:
     "piano [grand|ballad|upright|felt|lofi|honkytonk|prepared] · piano ballad",
+  epiano:
+    "epiano [preset epiano|suitcase|dyno] | bark bell tone vibe vibehz decay release <value> · epiano vibe 0.6 · rhodes",
+  wurli:
+    "wurli [preset wurli] | bark bell tone trem decay release <value> · wurli trem 0.5",
+  clav: "clav [preset clav|funkclav] | pickup neck|bridge|both|out | mute tone decay release <value> · clav pickup bridge",
+  tonewheel:
+    "tonewheel [<9 drawbar digits>] | hammond | b3 | gospel | jazzorgan · tonewheel 888800008",
+  combo: "combo [<5 register digits>] | farfisa | vox · combo 08880",
+  pipe: "pipe [plenum|flutes|cornet|reeds|strings|full | <stop> …] | church · pipe principal8,octave4",
+  rotary: "rotary slow|fast|stop [at <beat>] · rotary fast · rotary fast at 16",
   modal:
-    "modal <preset> | <body> | <param> <value> | mallet <name> | reset | off | presets · modal vibes · modal saron · modal ring 3",
-  pack: "/pack list | info <name> | use <pack>/<sound> | add <url>",
+    "modal <preset> | <body> | <param> <value> | mallet <name> | pair <track> | gamelan | reset | off | presets · modal vibes · modal gangsa · modal ring 3",
+  wind: "wind <preset> | <param> <value> | mute <name> | reset | off | presets · wind flute · wind trumpet mute harmon · wind players 4",
+  formant:
+    "/formant <-12..12> [mix] | deep|giant|bright|tiny | on | off · /formant -4 · /formant 3 0.5",
+  vowel:
+    "/vowel <v> [<to> [<morph 0..1>]] | ee | to <v>|off | morph <0..1> | mix <0..1> | off · /vowel a o 0.5",
+  lyrics:
+    'lyrics [bar] <syllables> | clear [bar] · lyrics "sun-lit morn-ing" (- splits, _ holds, ~ skips)',
+  sing: "sing <preset> | <param> <value> | drone <D3> | vowels a e i … | reset | off | presets · sing choir · sing khoomei drone D3 · sing vowel o voices 6",
+  vocoder:
+    "vocoder [preset] | src <track> | <param> <value|reset> | reset | off | presets · vocoder talkbox · vocoder src vox · vocoder formant +3 · vocoder gate auto · params: tap mode carrier follow root spread bands lo hi width attack release formant unvoiced sens hiss gate enhance depth freeze mix gain seed",
+  pack: "pack list | info <name> | use <pack>/<sound> | add <url>",
   kit: "/kit [name] · /kit syn909",
-  euclid: "/euclid [voice] · euclid hat 7 16",
-  menu: "/menu [sound|effects|rhythm|chords|mix|master|project|tuning]",
+  euclid: "euclid [drum] · euclid hat 7 16",
+  menu: "/menu [sound|voice|effects|rhythm|chords|mix|arrange|project|keys|agent] or any row name · /menu tuning · Ctrl-K",
+  style:
+    "style [list [id]|search <words>|info <id>|<id> [bars] [seed]|blend <a> <b> [w] [bars] [seed]|again] · style deep-house 16 · style blend bebop bossa-nova 0.3",
   master:
     "master <unit> on|off|preset <name>|<param> <value> · master streaming|club|loud · master target -14 · master measure · master off",
   try: "/try <sound command> · /try fx reverb mix 0.6",
-  play: "/play [on|off|degrees|chromatic] · Ctrl-P · i toggles degrees",
+  play: "/play [on|off|degrees|in-key|chromatic] · ctrl-p play mode · i toggles degrees",
   meter:
     "meter <1..16> · meter 3 · meter 7/8 [at bar <n>] · meter remove bar <n> · meter clear",
   art: EXPRESSION_USAGE.art,
@@ -727,37 +1001,32 @@ export const USAGE: Readonly<Record<string, string>> = {
   redo: "redo · Ctrl-Y",
 };
 
-/** Verbs a typo can be matched against, slash or bare as they are typed. */
+/** Verbs a typo can be matched against, without their slash. */
 const KNOWN_VERBS: readonly string[] = [
   ...new Set(
     [
       ...HELP_SECTIONS.flatMap((section) =>
-        section.group === "keys"
-          ? []
-          : section.entries.map((entry) => entry.command.split(/[\s|[]/)[0]!),
+        section.entries.map((entry) => entry.command.split(/[\s|[]/)[0]!),
       ),
       ...Object.values(USAGE).map((usage) => usage.split(/[\s|[]/)[0]!),
-    ].filter((verb) => /^\/?[a-z][\w-]*$/i.test(verb)),
+    ]
+      .map((verb) => verb.replace(/^\//, ""))
+      .filter((verb) => /^[a-z][\w-]*$/i.test(verb)),
   ),
 ];
 
-function editDistance(a: string, b: string): number {
-  const row = Array.from({ length: b.length + 1 }, (_, index) => index);
-  for (let i = 1; i <= a.length; i += 1) {
-    let previous = row[0]!;
-    row[0] = i;
-    for (let j = 1; j <= b.length; j += 1) {
-      const current = row[j]!;
-      row[j] = Math.min(
-        row[j]! + 1,
-        row[j - 1]! + 1,
-        previous + (a[i - 1] === b[j - 1] ? 0 : 1),
-      );
-      previous = current;
-    }
-  }
-  return row[b.length]!;
-}
+/** Window verbs whose free text would otherwise read as a typo fix. */
+const SLASH_ONLY: ReadonlySet<string> = new Set([
+  "rename",
+  "fork",
+  "resume",
+  "login",
+  "logout",
+  "auth",
+  "bpm",
+]);
+
+export { editDistance } from "./nearest.ts";
 
 /**
  * The known command nearest to the first word of `command` (`/clik` →
@@ -765,19 +1034,25 @@ function editDistance(a: string, b: string): number {
  */
 export function nearestCommand(command: string): string | undefined {
   const word = command.trim().split(/\s+/)[0]?.toLowerCase() ?? "";
+  const slash = word.startsWith("/");
   const bare = word.replace(/^\//, "");
   if (!bare) return undefined;
   let best: { verb: string; distance: number; score: number } | undefined;
   for (const verb of KNOWN_VERBS) {
-    const distance = editDistance(bare, verb.replace(/^\//, ""));
-    if (distance === 0 && verb === word) continue;
-    // Ties go to the form typed: `/patern` → `/pattern`, not `pattern`.
-    const sameForm = verb.startsWith("/") === word.startsWith("/");
-    const score = distance * 2 + (sameForm ? 0 : 1);
+    const distance = editDistance(bare, verb);
+    if (distance === 0 && !slash) continue;
+    // Ties go to a dropped letter (`/clik` → `/click`, not `/clip`), the
+    // commonest slip, then a changed one, then an extra one.
+    const shape =
+      verb.length > bare.length ? 0 : verb.length === bare.length ? 1 : 2;
+    const score = distance * 3 + shape;
     if (!best || score < best.score) best = { verb, distance, score };
   }
   const limit = bare.length <= 4 ? 1 : 2;
-  return best && best.distance <= limit ? best.verb : undefined;
+  if (!best || best.distance > limit) return undefined;
+  // Answer in the form typed (`/clik` → `/click`), except an exact word
+  // that failed with a slash (`/fx delay on` → `fx`): its slash was wrong.
+  return slash && best.distance > 0 ? `/${best.verb}` : best.verb;
 }
 
 /**
@@ -794,7 +1069,7 @@ export function typoFix(
   const [first, ...rest] = text.split(/\s+/);
   const word = first!.toLowerCase();
   for (const verb of KNOWN_VERBS) {
-    if (verb.startsWith("/") || verb === word) continue;
+    if (SLASH_ONLY.has(verb) || verb === word) continue;
     if (editDistance(word, verb) !== 1) continue;
     const candidate = [verb, ...rest].join(" ");
     if (parses(candidate)) return candidate;
@@ -834,7 +1109,18 @@ export function usageHint(command: string): string | undefined {
     !words.slice(1).some((word) => /\d/.test(word) || ARRANGE_WORDS.has(word))
   )
     return undefined;
-  return USAGE[verb];
+  const usage = USAGE[verb];
+  return usage === undefined ? undefined : usageForm(usage);
+}
+
+/**
+ * Every usage line reads `usage · <cmd> <args>`; a range refusal keeps
+ * its own template (`pan takes -1…1 · pan -0.5`).
+ */
+export function usageForm(usage: string): string {
+  return / takes /.test(usage) || usage.startsWith("usage · ")
+    ? usage
+    : `usage · ${usage}`;
 }
 
 const ARRANGE_VERBS: ReadonlySet<string> = new Set([
@@ -861,3 +1147,30 @@ const ARRANGE_WORDS: ReadonlySet<string> = new Set([
   "bake",
   "off",
 ]);
+
+/** The overlay title for `/help [topic]`: an alias shows its topic. */
+export function helpTitle(topic: string | undefined): string {
+  const name = topic?.trim().toLowerCase().replace(/^\//, "");
+  if (!name) return "help";
+  const spelled = HELP_COMMAND_ALIASES[name];
+  if (spelled) return `help · ${spelled}`;
+  const id = (TOPICS as readonly string[]).includes(name)
+    ? name
+    : USAGE[name] || commandHelpExists(name)
+      ? name
+      : (resolveTopic(name) ?? name);
+  return `help · ${id}`;
+}
+
+function commandHelpExists(name: string): boolean {
+  return HELP_SECTIONS.some((section) =>
+    section.entries.some((entry) =>
+      entry.command.replace(/^\//, "").startsWith(`${name} `),
+    ),
+  );
+}
+
+/** `no topic X · did you mean Y · /help`, for `/help X` with no page. */
+export function helpMiss(topic: string): string {
+  return topicMiss(topic, ["all"]);
+}