docs: generate README's command table from the schema (PRD 0006 R13) (#260)

* docs: generate README's command table from the schema (PRD 0006 R13)

The README described the CLI from memory. Nothing connected its command
listings to the table the dispatcher actually reads, so a renamed verb
stayed documented and a new one stayed invisible — the same drift that had
already happened inside `moshcode help` itself.

Generated rather than checked, which R13 offers as the alternative and is
the better half of it: a checker tells you the README is wrong, a generator
makes it right. `moshcode help --markdown` emits the table, and it goes
between markers in README.md exactly like the PRD index this repo already
maintains, so the convention is one people here already know.

Three tests, in both directions:

  - the table is regenerated and compared, so adding a verb without
    regenerating fails with the command that fixes it;
  - every command named in the table resolves in the schema;
  - every `moshcode <verb>` invoked in a fenced code block anywhere in the
    README is a real command, engine or tool. Scoped to fenced blocks
    because the prose also contains sentences like "moshcode warns you",
    and a grep that cannot tell those apart is a test nobody trusts.

Verified the guard bites: adding a command to the schema without
regenerating fails the suite, and the failure names `moshcode help
--markdown` as the fix.

1089 tests, 877 pass, 0 fail.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* feat(help): moshscript verbs, terminal manners, and completable topics (#263)

The tail of PRD 0006 — R14, R15, R16.

R14. `moshcode help ask` answered "no help for ask". `ask()` is as much
part of the interface as `moshcode prd`, but the vocabulary lives in a
registry help had never been introduced to. Verbs now carry an optional
`usage` — `ai(prompt, { engine })`, `ask(...prompt)` — and help renders it
with the summary and a note that this one is called from a .mosh file, not
a shell. `usage` stays optional, so a verb registered by a host that has
not declared one still renders as `name(…)`.

cliVerb() derives its own signature rather than repeating it twenty times:
every CLI verb forwards its arguments to `moshcode <name>`, so adding a
line to the vocabulary documents it.

R15 turned out to be already true and is now nailed down. src/ui.mjs
gates colour on `NO_COLOR == null && process.stdout.isTTY`, so both the CLI
and the pit already emit plain text to a pipe. Three tests keep it that
way, including one for the pit — which needs spawnSync rather than the
execFile helper the rest of the file uses, because the pit reads stdin and
execFile has no way to supply it. Nothing paginates.

R16. `moshcode help <tab>` now completes topics, in all four shells. The
list is what help itself accepts — commands, engines, tools and moshscript
verbs — so tab-completion and help cannot disagree about what is
answerable. A test asserts exactly that: every offered topic resolves.

1099 tests, 887 pass, 0 fail.

That closes PRD 0006. R1–R16 are implemented across #257, #258, #260 and
this.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: ralyodio

README.md

@@ -14,6 +14,44 @@ curl -fsSL https://moshcoding.com/install.sh | sh
 Zero-dependency ESM — all it needs is Node.js 18+. Later: `… | sh -s -- update`
 to upgrade, `… | sh -s -- remove` to uninstall.
 
+## Commands
+
+`moshcode help <command>` drills into any of these — flags, examples and all.
+`moshcode help --json` is the same thing for a machine.
+
+This table is generated from the command table the CLI itself dispatches from
+(`moshcode help --markdown`), so it cannot describe a verb that does not exist
+or miss one that does. A test fails the build when it drifts.
+
+<!-- COMMANDS:START -->
+| command | group | what it does |
+|---|---|---|
+| `moshcode agents` | engines | list engines or launch one autonomously |
+| `moshcode start` | engines | launch an engine with its native defaults |
+| `moshcode install` | engines | install an engine or workflow tool |
+| `moshcode uninstall` <br>`remove` | engines | take an engine or workflow tool off this machine |
+| `moshcode upgrade` <br>`update` | engines | update moshcode, engines, or tools |
+| `moshcode mcp` | extend | register and inspect MCP servers |
+| `moshcode skill` <br>`skills` | extend | install and inspect agent skills |
+| `moshcode prd` | script | publish or list product requirement documents |
+| `moshcode login` | account | authenticate with app.moshcode.sh |
+| `moshcode whoami` | account | show the logged-in account |
+| `moshcode logout` | account | clear the logged-in account |
+| `moshcode console` | account | serve or connect to the browser terminal |
+| `moshcode dns` | hosting | resolve Moshpit names on this machine |
+| `moshcode doh` | hosting | run the DNS-over-HTTPS resolver |
+| `moshcode site` <br>`serve` | hosting | install web-server config for a Moshpit name |
+| `moshcode template` <br>`templates` | hosting | scaffold a stack for a Moshpit-hosted service |
+| `moshcode pwd` <br>`where` | system | show the current directory and git context |
+| `moshcode engines` | engines | list engines and installation status |
+| `moshcode tools` | tools | list workflow tools and installation status |
+| `moshcode commands` | script | list built-in moshscript commands |
+| `moshcode completion` | extend | print a shell completion script |
+| `moshcode run` | script | run a moshscript |
+| `moshcode help` <br>`--help` `-h` | system | show command help |
+| `moshcode version` <br>`--version` `-v` | system | show the installed version |
+<!-- COMMANDS:END -->
+
 ## Engines
 
 ```sh

bin/moshcode.mjs

@@ -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,
-  suggest, wantsHelp, withoutHelp,
+  renderMarkdown, renderScriptVerb, suggest, wantsHelp, withoutHelp,
 } from "../src/help.mjs";
 import { moshcodeVersion } from "../src/ui.mjs";
 
@@ -179,6 +179,13 @@ function handledHelp(cmd, rest) {
   const topLevel = ["help", "--help", "-h"].includes(cmd);
 
   if (topLevel) {
+    // `--markdown` is the generator behind README.md's command table (R13). A
+    // build-time convenience, deliberately not a docs pipeline: it emits one
+    // table, and the test that keeps README.md honest calls the same function.
+    if (rest.includes("--markdown")) {
+      console.log(renderMarkdown());
+      return true;
+    }
     const args = withoutHelp(rest).filter((a) => a !== "--json" && a !== "--all");
     // `moshcode help --help` asks about `help` itself, and R4 says every
     // command answers for itself. Only the spelled-out verb: `moshcode --help`
@@ -209,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;

src/cli-schema.mjs

@@ -309,6 +309,7 @@ export const CORE_CLI_COMMANDS = [
     flags: [
       ["--all", "render every command instead of the overview", ""],
       ["--json", "emit the help model as JSON", ""],
+      ["--markdown", "emit the command table for README.md", ""],
     ],
     examples: [
       ["moshcode help mcp install", "a sub-verb"],

src/cli.mjs

@@ -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),
 };

src/commands.mjs

@@ -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

src/completion.mjs

@@ -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'

src/help.mjs

@@ -308,6 +308,72 @@ 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 -->";
+export const README_END = "<!-- COMMANDS:END -->";
+
+/**
+ * The command table as markdown, for README.md (PRD 0006 R13).
+ *
+ * Generated rather than checked against a hand-written list, and the difference
+ * matters: a checker tells you the README is wrong, a generator makes it right.
+ * Same shape as the PRD index this repo already keeps between markers, so the
+ * convention is one people here already know.
+ *
+ * Aliases ride along in their target's row instead of getting rows of their
+ * own — six extra lines saying "alias for X" is how a table stops being read.
+ */
+export function renderMarkdown() {
+  const rows = primaryCommands().map((command) => {
+    const aliases = aliasesFor(command.name);
+    const name = `\`moshcode ${command.name}\`${aliases.length ? ` <br>${aliases.map((a) => `\`${a}\``).join(" ")}` : ""}`;
+    return `| ${name} | ${command.group} | ${command.description} |`;
+  });
+  return [
+    "| command | group | what it does |",
+    "|---|---|---|",
+    ...rows,
+  ].join("\n");
+}
+
+/**
+ * Put the generated table between the markers in `markdown`.
+ *
+ * Returns the document unchanged when it carries no markers, so this can be
+ * pointed at a file that has not opted in without mangling it.
+ */
+export function withCommandTable(markdown) {
+  const text = String(markdown);
+  const from = text.indexOf(README_START);
+  const to = text.indexOf(README_END);
+  if (from < 0 || to < 0 || to < from) return text;
+  return `${text.slice(0, from + README_START.length)}\n${renderMarkdown()}\n${text.slice(to)}`;
+}
+
 /* ------------------------------------------------------------------ the pit */
 
 /** Resolve a pit command, following its aliases. */