@@ -32,7 +32,7 @@ import { completionScript } from "../src/completion.mjs";
 import { CORE_CLI_COMMAND_NAMES } from "../src/cli-schema.mjs";
 import {
   findCommand, findVerb, helpModel, renderAll, renderCommand, renderOverview,
-  renderMarkdown, suggest, wantsHelp, withoutHelp,
+  renderMarkdown, renderScriptVerb, suggest, wantsHelp, withoutHelp,
 } from "../src/help.mjs";
 import { moshcodeVersion } from "../src/ui.mjs";
 
@@ -216,7 +216,16 @@ function handledHelp(cmd, rest) {
         console.log(`see also: moshcode help tools · moshcode help install`);
         return true;
       }
-      const near = suggest(args[0], [...Object.keys(ENGINES), ...Object.keys(TOOLS)]);
+      // A moshscript verb is a fair thing to ask about — `ask()` is as much
+      // part of the interface as `moshcode prd` (R14).
+      const verbHelp = renderScriptVerb(moshVocabulary().get(args[0]));
+      if (verbHelp) {
+        console.log(verbHelp);
+        return true;
+      }
+      const near = suggest(args[0], [
+        ...Object.keys(ENGINES), ...Object.keys(TOOLS), ...moshVocabulary().names(),
+      ]);
       console.error(`✗ no help for ${JSON.stringify(args[0])}${near ? ` — did you mean ${near}?` : ""}`);
       console.error("  moshcode help          list commands");
       process.exitCode = 1;
 
@@ -60,7 +60,17 @@ export function runMoshcode(cmd, args, ctx) {
 
 /** A vocabulary command mapping `name(...args)` → `moshcode name ...args`. */
 export function cliVerb(name, summary) {
-  return { name, summary, run: (ctx, ...args) => runMoshcode(name, args, ctx) };
+  // `usage` is the call signature `moshcode help <verb>` renders (PRD 0006
+  // R14). Every CLI verb has the same one — it forwards its arguments to
+  // `moshcode <name>` — so deriving it here means a verb added below is
+  // documented by the act of adding it.
+  return {
+    name,
+    summary,
+    usage: `${name}(...args)`,
+    detail: `runs \`moshcode ${name} ...args\` and returns { ok, code }`,
+    run: (ctx, ...args) => runMoshcode(name, args, ctx),
+  };
 }
 
 /**
@@ -102,5 +112,7 @@ export function runAi(ctx, prompt, opts = {}) {
 export const aiVerb = {
   name: "ai",
   summary: "run a coding engine on a prompt and return its output (shortcut)",
+  usage: "ai(prompt, { engine })",
+  detail: "blocking; returns the engine's stdout as a string. engine defaults to the first installed one. needs await",
   run: (ctx, prompt, opts) => runAi(ctx, prompt, opts),
 };
@@ -67,6 +67,8 @@ const COMMANDS = [
   {
     name: "code",
     summary: "compile features (no bugs)",
+    usage: "code()",
+    detail: "narrates a build step; takes no arguments",
     run(ctx, ...args) {
       expectNoArgs("code", args);
       ctx.out("  ⌨  code()    → compiling features (no bugs)…");
@@ -75,6 +77,8 @@ const COMMANDS = [
   {
     name: "mosh",
     summary: "open the pit + blast the moshcoding playlist",
+    usage: "mosh()",
+    detail: "opens the pit and starts the playlist",
     run(ctx, ...args) {
       expectNoArgs("mosh", args);
       ctx.out("  🤘 mosh()    → opening the pit");
@@ -91,6 +95,8 @@ const COMMANDS = [
   {
     name: "notify",
     summary: "ping the operator via app.moshcode.sh (email/SMS/Slack/Telegram/push)",
+    usage: "notify(...message)",
+    detail: "returns { id, url } — fire and forget, no reply awaited",
     // Fire-and-forget. Posts the approval to the app, which fans it out to the
     // operator's channels. Returns { id, url } so a script can hand the link off.
     async run(ctx, ...args) {
@@ -107,6 +113,8 @@ const COMMANDS = [
   {
     name: "ask",
     summary: "notify + BLOCK until the human approves/instructs at app.moshcode.sh",
+    usage: "ask(...prompt)",
+    detail: "BLOCKS until a human answers at app.moshcode.sh; returns their reply or null. needs await",
     // The human-in-the-loop gate. Posts the approval to the app, then waits for
     // the operator to open app.moshcode.sh/approve/:id, read the context, and
     // submit. Resolves with their instructions (or null). Requires `await`.
@@ -130,6 +138,8 @@ const COMMANDS = [
   {
     name: "repeat",
     summary: "back to the top of the loop",
+    usage: "repeat()",
+    detail: "jumps back to the top of the loop",
     run(ctx, ...args) {
       expectNoArgs("repeat", args);
       ctx.out("  ↻  repeat()  → back to the top");
@@ -138,13 +148,17 @@ const COMMANDS = [
   {
     name: "say",
     summary: "print a line",
+    usage: "say(...parts)",
+    detail: "prints one line",
     run(ctx, ...args) {
       ctx.out(`  💬 ${args.join(" ")}`);
     },
   },
   {
     name: "sleep",
     summary: "pause for N milliseconds (blocking)",
+    usage: "sleep(ms)",
+    detail: "blocks for ms milliseconds",
     // Synchronous/blocking so it pauses inline in the simple no-`await` style:
     // `while (alive) { work(); sleep(1000); }` actually waits each iteration.
     run(ctx, ...args) {
@@ -163,6 +177,8 @@ const COMMANDS = [
   {
     name: "stop",
     summary: "end the loop (alive = false)",
+    usage: "stop()",
+    detail: "ends the loop (alive = false)",
     run(ctx, ...args) {
       expectNoArgs("stop", args);
       ctx.stop();
@@ -173,6 +189,8 @@ const COMMANDS = [
   {
     name: "shell",
     summary: "run a shell command (blocking, cmd.exe on Windows or $SHELL -c elsewhere)",
+    usage: "shell(cmd)",
+    detail: "runs cmd in $SHELL; returns { ok, code, signal }",
     // The moshscript system verb for arbitrary shell commands. Blocking
     // (spawnSync + inherited stdio) so it runs inline in the no-`await` style,
     // and the child owns the terminal for interactive commands. Returns
 
@@ -6,6 +6,7 @@ import {
 } from "./cli-schema.mjs";
 import { ENGINES, ENGINE_ALIASES } from "./engines.mjs";
 import { TOOLS } from "./tools.mjs";
+import { moshVocabulary } from "./commands.mjs";
 
 export const COMPLETION_SHELLS = ["bash", "zsh", "fish", "powershell"];
 
@@ -54,6 +55,16 @@ export function completionModel() {
     skills: uniqueEntries(SKILL_VERBS),
     skillSources: uniqueEntries(SKILL_VERBS.filter(({ acceptsSource }) => acceptsSource)),
     shells: COMPLETION_SHELLS.map((name) => entry(name, `generate ${name} completion`)),
+    // `moshcode help <topic>` accepts anything help can answer for: a command,
+    // an engine, a tool, or a moshscript verb (PRD 0006 R16). Offering the same
+    // set here is what keeps tab-completion and help one discoverability
+    // surface rather than two that disagree.
+    helpTopics: uniqueEntries([
+      ...CORE_CLI_COMMANDS.filter(({ name }) => !name.startsWith("-")),
+      ...engines,
+      ...tools,
+      ...moshVocabulary().all().map((c) => entry(c.name, c.summary || "moshscript verb")),
+    ]),
   };
 }
 
@@ -110,6 +121,7 @@ ${powershellEntries("MoshcodeCompletionMcpServerSpecs", model.mcpServerSpecs)}
 ${powershellEntries("MoshcodeCompletionSkills", model.skills)}
 ${powershellEntries("MoshcodeCompletionSkillSources", model.skillSources)}
 ${powershellEntries("MoshcodeCompletionShells", model.shells)}
+${powershellEntries("MoshcodeCompletionHelpTopics", model.helpTopics)}
 ${powershellEntries("MoshcodeCompletionJson", optionEntries("--json", "print JSON"))}
 ${powershellEntries("MoshcodeCompletionLogin", optionEntries("--browser -b --device -d", "authentication mode"))}
 ${powershellEntries("MoshcodeCompletionRun", optionEntries("--dry-run --max -n", "run option"))}
@@ -154,6 +166,9 @@ Register-ArgumentCompleter -Native -CommandName moshcode -ScriptBlock {
       { $_ -in @('upgrade', 'update') } {
         $choices = $script:MoshcodeCompletionUpgrade
       }
+      'help' {
+        if ($argumentIndex -eq 2) { $choices = $script:MoshcodeCompletionHelpTopics }
+      }
       'completion' {
         if ($argumentIndex -eq 2) { $choices = $script:MoshcodeCompletionShells }
       }
@@ -244,6 +259,9 @@ _moshcode_completion() {
       completion)
         (( COMP_CWORD == 2 )) && choices="${names(model.shells)}"
         ;;
+      help)
+        (( COMP_CWORD == 2 )) && choices="${names(model.helpTopics)}"
+        ;;
       mcp)
         if (( COMP_CWORD == 2 )); then
           choices="${names(model.mcp)}"
@@ -350,6 +368,12 @@ _moshcode() {
         _describe "shell" choices
       fi
       ;;
+    help)
+      if (( CURRENT == 3 )); then
+        choices=(${zshValues(model.helpTopics)})
+        _describe "help topic" choices
+      fi
+      ;;
     mcp)
       if (( CURRENT == 3 )); then
         choices=(${zshValues(model.mcp)})
@@ -458,6 +482,7 @@ ${fishEntries(atSecondToken("install"), model.install)}
 ${fishEntries(atSecondToken("uninstall remove"), model.uninstall)}
 ${fishEntries("__moshcode_command_is upgrade update", model.upgrade)}
 ${fishEntries(atSecondToken("completion"), model.shells)}
+${fishEntries(atSecondToken("help"), model.helpTopics)}
 ${fishEntries(atSecondToken("mcp"), model.mcp)}
 ${fishEntries(atSecondToken("skill skills"), model.skills)}
 complete -c moshcode -n '__moshcode_nested_is mcp list' -l json -d 'print JSON'
 
@@ -308,6 +308,29 @@ export function helpModel({ engines = [], tools = [], version = "" } = {}) {
  * to stderr and exit 1; `renderCommand` on stdout is the same text for the
  * person who asked politely.
  */
+/* ------------------------------------------------------- moshscript verbs */
+
+/**
+ * A moshscript verb, rendered from the registry (PRD 0006 R14).
+ *
+ * `moshcode help ask` is a fair question — `ask()` is as much part of the
+ * interface as `moshcode prd` — and it used to answer "no help for ask",
+ * because the vocabulary lives in a registry that help had never been
+ * introduced to.
+ *
+ * `usage` is optional on a command object, so a verb registered by a host that
+ * has not declared one still renders: the signature falls back to `name(…)` and
+ * the summary carries the meaning.
+ */
+export function renderScriptVerb(command) {
+  if (!command) return null;
+  const out = [`${command.usage || `${command.name}(…)`} — ${command.summary || "a moshscript verb"}`];
+  if (command.detail) out.push("", wrap(command.detail, 0));
+  out.push("", "a moshscript verb — call it from a .mosh file, not from the shell.");
+  out.push("", "see also: moshcode help run · moshcode help commands");
+  return out.join("\n");
+}
+
 /* ---------------------------------------------------------------- markdown */
 
 export const README_START = "<!-- COMMANDS:START -->";
 
@@ -11,7 +11,7 @@
 // code, one shape, at every depth.
 import assert from "node:assert/strict";
 import test from "node:test";
-import { execFile } from "node:child_process";
+import { execFile, spawnSync } from "node:child_process";
 import { promisify } from "node:util";
 import fs from "node:fs";
 import path from "node:path";
@@ -24,10 +24,13 @@ import {
 } from "../src/cli-schema.mjs";
 import {
   WIDTH, findCommand, findPitCommand, helpModel, pitHelpModel, renderCommand, renderOverview,
-  renderPitCommand, README_START, README_END, suggest, wantsHelp, withCommandTable, wrap,
+  renderPitCommand, renderScriptVerb, README_START, README_END, suggest, wantsHelp,
+  withCommandTable, wrap,
 } from "../src/help.mjs";
 import { ENGINES } from "../src/engines.mjs";
 import { TOOLS } from "../src/tools.mjs";
+import { moshVocabulary } from "../src/commands.mjs";
+import { completionModel } from "../src/completion.mjs";
 
 const run = promisify(execFile);
 const BIN = fileURLToPath(new URL("../bin/moshcode.mjs", import.meta.url));
@@ -395,3 +398,100 @@ test("help --markdown emits the same table the README carries", async () => {
   const readme = fs.readFileSync(path.join(ROOT, "README.md"), "utf8");
   assert.ok(readme.includes(stdout.trim()), "the generator and the README disagree");
 });
+
+/* ------------------------------------------------- R14: moshscript verbs */
+
+const ESC = "[";
+
+test("moshcode help <verb> answers for a moshscript verb", async () => {
+  // `ask()` is as much part of the interface as `moshcode prd`, and used to
+  // answer "no help for ask" because the vocabulary lives in a registry help
+  // had never been introduced to.
+  const { code, stdout, stderr } = await cli(["help", "ask"]);
+  assert.equal(code, 0);
+  assert.equal(stderr, "");
+  assert.match(stdout, /^ask\(\.\.\.prompt\) —/, "the call signature leads");
+  assert.match(stdout, /moshscript verb/);
+});
+
+test("the signature comes from the registry, including its options", async () => {
+  const { stdout } = await cli(["help", "ai"]);
+  assert.match(stdout, /ai\(prompt, \{ engine \}\)/, "R14's worked example");
+});
+
+test("every moshscript verb renders, with or without a declared usage", () => {
+  for (const command of moshVocabulary().all()) {
+    const text = renderScriptVerb(command);
+    assert.ok(text, `${command.name} rendered nothing`);
+    assert.match(text, /moshscript verb/, `${command.name} lost its footer`);
+  }
+  // A host may register a verb with no usage at all; it must still render.
+  assert.match(renderScriptVerb({ name: "custom", summary: "" }), /^custom\(…\)/);
+  assert.equal(renderScriptVerb(null), null);
+});
+
+test("a CLI verb's usage is derived, so adding one documents it", () => {
+  const gh = moshVocabulary().get("gh");
+  assert.equal(gh.usage, "gh(...args)");
+  assert.match(gh.detail, /moshcode gh/);
+});
+
+test("a command and a verb of the same name resolve to the command", async () => {
+  // `run` and `pwd` are both. The CLI command is what `moshcode help run`
+  // means — the verb is reachable through `moshcode commands`.
+  const { stdout } = await cli(["help", "run"]);
+  assert.match(stdout, /^moshcode run —/);
+});
+
+/* --------------------------------------------------------- R15: terminal */
+
+test("help is plain text when the terminal is not one", async () => {
+  // execFile gives the child a pipe, not a TTY — the non-TTY half of R15.
+  for (const args of [["--help"], ["help", "prd"], ["help", "ask"], ["help", "--all"]]) {
+    const { stdout } = await cli(args);
+    assert.ok(!stdout.includes(ESC), `${args.join(" ")} emitted ANSI to a pipe`);
+  }
+});
+
+test("NO_COLOR is honoured", async () => {
+  const env = { ...process.env, NO_COLOR: "1" };
+  delete env.FORCE_COLOR;
+  const { stdout } = await cli(["--help"], { env });
+  assert.ok(!stdout.includes(ESC), "NO_COLOR still produced escapes");
+});
+
+test("the pit's help is plain when piped", () => {
+  // spawnSync, not the execFile helper: the pit reads stdin, and execFile has
+  // no way to supply it — the child sits waiting for a prompt that never comes.
+  const { stdout } = spawnSync(process.execPath, [BIN], {
+    cwd: ROOT, input: "/help\n/quit\n", encoding: "utf8", timeout: 30_000,
+  });
+  assert.ok(!stdout.includes(ESC), "the pit coloured a pipe");
+  assert.match(stdout, /not in the pit/, "and still rendered");
+});
+
+/* ------------------------------------------------------ R16: completion */
+
+test("completion offers help topics in every shell", async () => {
+  for (const shell of ["bash", "zsh", "fish", "powershell"]) {
+    const { code, stdout } = await cli(["completion", shell]);
+    assert.equal(code, 0, `${shell} completion failed`);
+    // The topics are the surface help itself accepts: a command, an engine, a
+    // tool, and a moshscript verb.
+    for (const topic of ["install", "claude", "gh", "ask"]) {
+      assert.ok(stdout.includes(topic), `${shell} completion offers no "${topic}" help topic`);
+    }
+  }
+});
+
+test("every completion help topic is one help can actually answer", () => {
+  const model = completionModel();
+  assert.ok(model.helpTopics.length >= 30, "the topic list looks empty");
+  const engines = new Set(Object.keys(ENGINES));
+  const tools = new Set(Object.keys(TOOLS));
+  const verbs = new Set(moshVocabulary().names());
+  for (const { name } of model.helpTopics) {
+    const answerable = findCommand(name) || engines.has(name) || tools.has(name) || verbs.has(name);
+    assert.ok(answerable, `completion offers "${name}" but help cannot answer it`);
+  }
+});