@canonical/pragma-cli 0.32.0 → 0.33.0

package/src/kernel/runtime/wasmEmbed.test.ts

@@ -137,6 +137,8 @@ ex:one a ex:Widget ; rdfs:label "One" .
     };
     expect(envelope.data.lockPresent).toBe(true);
     expect(envelope.data.cached).toBe(true);
-    expect(envelope.data.entityCount).toBe(2);
+    // Distinct abox subjects: the one individual (ex:one). The ex:Widget class
+    // is tbox schema, not an entity — the raw entity count would double this (A1).
+    expect(envelope.data.entityCount).toBe(1);
   });
 });

package/src/kernel/spec/emitReference.test.ts

@@ -0,0 +1,196 @@
+import { describe, expect, it } from "vitest";
+import {
+  fixtureModule,
+  fixtureReferenceModule,
+} from "../../testing/fixtures/fixtureCapability.js";
+import { ERROR_CODES } from "../error/constants.js";
+import { emitReference } from "./emitReference.js";
+
+/** The four pages every reference doc set carries. */
+const PAGES = ["index.md", "commands.md", "tools.md", "errors.md"];
+
+describe("emitReference", () => {
+  const docs = emitReference([fixtureReferenceModule]);
+  const index = docs.get("index.md") ?? "";
+  const commands = docs.get("commands.md") ?? "";
+  const tools = docs.get("tools.md") ?? "";
+  const errors = docs.get("errors.md") ?? "";
+
+  it("emits exactly the four reference pages", () => {
+    expect([...docs.keys()].sort()).toEqual([...PAGES].sort());
+  });
+
+  it("ends every page in exactly one trailing newline", () => {
+    for (const content of docs.values()) {
+      expect(content.endsWith("\n")).toBe(true);
+      expect(content.endsWith("\n\n")).toBe(false);
+    }
+  });
+
+  it("is deterministic — the same catalog yields byte-identical pages", () => {
+    const again = emitReference([fixtureReferenceModule]);
+    for (const page of PAGES) {
+      expect(again.get(page)).toBe(docs.get(page));
+    }
+  });
+
+  describe("index.md", () => {
+    it("reports counts derived from the live grammar", () => {
+      // gizmo + ping = 2 nouns; local/scan/tidy/wipe/ping = 5 commands (hidden
+      // dropped); scan/tidy/wipe/ping = 4 tools (local withheld); 1 resource
+      // template (the module's `mcpResources` surface).
+      expect(index).toContain("**2** command nouns");
+      expect(index).toContain("**5** CLI commands");
+      expect(index).toContain("**4** MCP tools");
+      expect(index).toContain("**1** resource template(s)");
+    });
+
+    it("links the three sibling pages with relative paths", () => {
+      expect(index).toContain("(./commands.md)");
+      expect(index).toContain("(./tools.md)");
+      expect(index).toContain("(./errors.md)");
+    });
+  });
+
+  describe("commands.md", () => {
+    it("groups verbs under noun headings, sorted, hidden excluded", () => {
+      expect(commands).toContain("## gizmo");
+      expect(commands).toContain("## ping");
+      expect(commands.indexOf("## gizmo")).toBeLessThan(
+        commands.indexOf("## ping"),
+      );
+      expect(commands).not.toContain("hidden");
+    });
+
+    it("renders a read verb's usage, args, flags, attributes, and examples", () => {
+      expect(commands).toContain("### pragma gizmo scan");
+      expect(commands).toContain("pragma gizmo scan [targets...] [options]");
+      // Optional variadic positional token.
+      expect(commands).toContain("| `[targets...]` | no |");
+      // Enum flag: escaped pipe token, enum values, and default in the description.
+      expect(commands).toContain("| `--mode` | `<fast\\|slow>` |");
+      expect(commands).toContain("(one of: fast, slow) (default: fast)");
+      // Each flag kind renders its value placeholder.
+      expect(commands).toContain("| `--limit` | `<number>` |");
+      expect(commands).toContain("| `--label` | `<string>` |");
+      expect(commands).toContain("| `--include` | `<value...>` |");
+      // A bare boolean switch has no value placeholder.
+      expect(commands).toContain("| `--deep` | — |");
+      expect(commands).toContain("- Store: storeless.");
+      expect(commands).toContain("- MCP: exposed as the `gizmo_scan` tool.");
+      // A note becomes a trailing comment; a noteless example stays bare.
+      expect(commands).toContain("pragma gizmo scan  # scan everything");
+      expect(commands).toContain("pragma gizmo scan alpha --mode slow");
+    });
+
+    it("marks a store-backed destructive mutation's CLI attributes", () => {
+      expect(commands).toContain("### pragma gizmo wipe");
+      expect(commands).toContain("pragma gizmo wipe <path>");
+      expect(commands).toContain(
+        "- Store: reads the local store (`pragma sources update` builds it).",
+      );
+      expect(commands).toContain("- Mutation: plan-first");
+    });
+
+    it("marks a visible verb withheld from MCP", () => {
+      expect(commands).toContain("### pragma gizmo local");
+      expect(commands).toContain("- MCP: not exposed (CLI-only).");
+    });
+
+    it("renders a self-verb with no sub-command in its invocation", () => {
+      expect(commands).toContain("### pragma ping");
+      expect(commands).toContain("```\npragma ping\n```");
+    });
+
+    it("falls back to the summary when a verb has no doc", () => {
+      // `ping` has no `doc`; its summary is the section body.
+      const pingSection = commands.slice(commands.indexOf("### pragma ping"));
+      expect(pingSection).toContain("Ping the gizmo host.");
+    });
+  });
+
+  describe("tools.md", () => {
+    it("adds the disclosure `detail` param and comma-joined enum types", () => {
+      expect(tools).toContain("### gizmo_scan");
+      expect(tools).toContain("| `mode` | enum(fast, slow) | no |");
+      expect(tools).toContain("| `include` | string[] | no |");
+      expect(tools).toContain(
+        "| `detail` | enum(summary, detailed) | no | Progressive-disclosure level (default summary). |",
+      );
+    });
+
+    it("adds confirm + cwd to a mutating tool and flags it destructive", () => {
+      const wipe = tools.slice(tools.indexOf("### gizmo_wipe"));
+      expect(wipe).toContain("| `confirm` | boolean | no |");
+      expect(wipe).toContain("| `cwd` | string | no |");
+      expect(tools).toContain(
+        "Mutation — plan-first (set `confirm: true` to apply). Marked destructive.",
+      );
+    });
+
+    it("marks a non-destructive mutating tool as such", () => {
+      const tidy = tools.slice(tools.indexOf("### gizmo_tidy"));
+      expect(tidy).toContain("| `confirm` | boolean | no |");
+      // The `destructive: false` branch of `formatToolAnnotations`.
+      expect(tools).toContain(
+        "Mutation — plan-first (set `confirm: true` to apply). Non-destructive.",
+      );
+    });
+
+    it("omits verbs withheld from MCP", () => {
+      expect(tools).not.toContain("gizmo_local");
+    });
+
+    it("marks a no-param tool as taking no input", () => {
+      const ping = tools.slice(tools.indexOf("### ping"));
+      expect(ping.slice(0, 200)).toContain("_No input parameters._");
+    });
+
+    it("renders every non-tool surface bullet the module declares", () => {
+      expect(tools).toContain("## Non-tool surface");
+      // The module declares an `mcpResources` template surface (its `surface.
+      // templates` id) and an `mcpPrompts` native surface, so all three bullets
+      // render — exercising both optional branches of `renderNonToolSurface`.
+      expect(tools).toContain("- **Resources**: `gizmo:{+uri}`");
+      expect(tools).toContain("- **Prompts**:");
+      expect(tools).toContain("- **Instructions**:");
+    });
+  });
+
+  describe("errors.md", () => {
+    it("renders the exit-code table and the full error catalog", () => {
+      expect(errors).toContain("| `0` | success |");
+      expect(errors).toContain("| `3` | store unavailable |");
+      expect(errors).toContain("| `ENTITY_NOT_FOUND` |");
+      expect(errors).toContain("| `UNSUPPORTED` |");
+    });
+
+    it("lists every code in the closed ERROR_CODES tuple (exhaustive)", () => {
+      // Non-circular exhaustiveness: iterate the source-of-truth tuple and
+      // assert each code's `catalog` row is present, so a code added to the
+      // kernel without a catalog entry fails here (not just the 2 spot-checks).
+      for (const code of ERROR_CODES) {
+        expect(errors, `errors.md is missing \`${code}\``).toContain(
+          `\`${code}\``,
+        );
+      }
+    });
+
+    it("embeds the response envelope as a JSON block", () => {
+      expect(errors).toContain("```json");
+      expect(errors).toContain('"ok": true');
+      expect(errors).toContain('"code": "<ErrorCode>"');
+    });
+  });
+});
+
+describe("emitReference — MCP annotation branches", () => {
+  it("renders a destructive fixture tool and a native-prompt-free surface", () => {
+    // `fixtureModule.make` is exposed, mutating, and destructive — the same
+    // `Marked destructive.` branch, driven from the emitSurface fixture.
+    const tools = emitReference([fixtureModule]).get("tools.md") ?? "";
+    expect(tools).toContain("### widget_make");
+    expect(tools).toContain("Marked destructive.");
+    expect(tools).not.toContain("- **Prompts**:");
+  });
+});

package/src/kernel/spec/emitReference.ts

@@ -0,0 +1,491 @@
+/**
+ * Reference emitter: project the live capability grammar into the committed
+ * Markdown reference under `docs/reference/`.
+ *
+ * A sibling of `emitSurface` — same input (the `CapabilityModule[]` catalog),
+ * same discipline: pure, zod-free, and reads ONLY the grammar (never a run
+ * body). Where `emitSurface` freezes the machine covenant, this renders the
+ * human/agent-facing pages the build hook writes back to disk and the
+ * drift-guard (`capabilities/reference.test.ts`) pins byte-for-byte.
+ *
+ * DETERMINISM is the contract: stable sort, params in declared order, no
+ * version, no dates, no `Date.now()` — the same catalog always yields the same
+ * bytes, so a rebuild is a no-op and the drift-guard stays green. `doc` strings
+ * are kept verbatim (the project-layer `stripToolCallExample` is deliberately
+ * NOT imported — this is a kernel-layer emitter).
+ */
+
+import { ERROR_CODES } from "../error/constants.js";
+import {
+  FIXED_SURFACE,
+  kebabCase,
+  toolName,
+  verbLabel,
+} from "./emitSurface.js";
+import type {
+  CapabilityModule,
+  Example,
+  ParamSpec,
+  VerbSpec,
+} from "./types.js";
+
+/** The reference doc set: relative path under `docs/reference/` → file content. */
+export type ReferenceDocs = ReadonlyMap<string, string>;
+
+/**
+ * The closed error-code → one-line meaning map. Typed as an exhaustive
+ * `Record` over the `ERROR_CODES` tuple, so a code added to the tuple without a
+ * description here is a COMPILE error — the single authoring point stays in
+ * lockstep with the error kernel. Colocated (single-use) rather than in
+ * `constants.ts`: it is only read by `renderErrorsPage`.
+ */
+const ERROR_CODE_DESCRIPTIONS: Record<(typeof ERROR_CODES)[number], string> = {
+  ENTITY_NOT_FOUND: "A named entity (block, standard, token, …) was not found.",
+  EMPTY_RESULTS:
+    "A query or listing resolved to nothing under the active scope.",
+  INVALID_INPUT: "An argument was malformed, out of range, or the wrong shape.",
+  AMBIGUOUS_INPUT:
+    "A name resolved to several entities (reserved; not yet raised).",
+  UNKNOWN_VERB: "The command noun or verb is not recognized.",
+  STORE_UNAVAILABLE: "The local store could not be reached or is not built.",
+  CONFIG_ERROR: "The layered configuration could not be resolved.",
+  INTERNAL_ERROR: "An unexpected failure — please report it.",
+  UNSUPPORTED: "A capability is unavailable in this build or environment.",
+};
+
+/** Escape a value for a Markdown table cell (pipes, then newlines to spaces). */
+function escapeCell(text: string): string {
+  return text.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+
+/** Flatten every non-hidden verb, sorted by noun ascending then verb-label ascending. */
+function collectDocVerbs(
+  modules: readonly CapabilityModule[],
+): readonly VerbSpec[] {
+  const verbs: VerbSpec[] = [];
+  for (const module of modules) {
+    for (const verb of module.verbs) {
+      if (verb.hidden) continue;
+      verbs.push(verb);
+    }
+  }
+  return verbs.sort(compareDocVerbs);
+}
+
+/** Order two verbs by noun, then by verb-label — a total, locale-free order. */
+function compareDocVerbs(a: VerbSpec, b: VerbSpec): number {
+  const nounA = a.path[0];
+  const nounB = b.path[0];
+  if (nounA !== nounB) return nounA < nounB ? -1 : 1;
+  const labelA = verbLabel(a.path);
+  const labelB = verbLabel(b.path);
+  /* v8 ignore next -- unreachable: no registered grammar produces a `[noun,
+     noun]` path (a verb equal to its own noun), so within one noun every
+     verb-label is unique and this equal tie-break never fires. */
+  if (labelA === labelB) return 0;
+  return labelA < labelB ? -1 : 1;
+}
+
+/** The full CLI invocation head for a verb (`pragma <noun>` or `pragma <noun> <verb>`). */
+function formatInvocation(verb: VerbSpec): string {
+  const sub = verb.path[1];
+  return sub === undefined
+    ? `pragma ${verb.path[0]}`
+    : `pragma ${verb.path[0]} ${sub}`;
+}
+
+/** Format a positional param as its usage token (`<name>`/`[name]`, `...` when variadic). */
+function formatPositionalToken(param: ParamSpec): string {
+  const variadic = param.kind === "string[]" ? "..." : "";
+  return param.required
+    ? `<${param.name}${variadic}>`
+    : `[${param.name}${variadic}]`;
+}
+
+/** The value placeholder a flag takes (empty for a bare boolean switch). */
+function formatFlagValue(param: ParamSpec): string {
+  switch (param.kind) {
+    case "boolean":
+      return "";
+    case "enum":
+      return `<${param.values.join("|")}>`;
+    case "number":
+      return "<number>";
+    case "string":
+      return "<string>";
+    case "string[]":
+      return "<value...>";
+  }
+}
+
+/**
+ * The tool-schema type label a param projects to (mirrors `buildZodSchema`).
+ * Enum values are comma-joined (never pipe-joined) so the label is safe inside
+ * a Markdown table cell without escaping.
+ */
+function formatParamType(param: ParamSpec): string {
+  switch (param.kind) {
+    case "enum":
+      return `enum(${param.values.join(", ")})`;
+    case "string[]":
+      return "string[]";
+    default:
+      return param.kind;
+  }
+}
+
+/** Render a default value for prose (strings verbatim, everything else stringified). */
+function formatDefault(value: unknown): string {
+  return typeof value === "string" ? value : String(value);
+}
+
+/** A param's description cell: its doc, plus enum values and any default. */
+function describeParam(param: ParamSpec): string {
+  let description = escapeCell(param.doc);
+  if (param.kind === "enum") {
+    description += ` (one of: ${param.values.join(", ")})`;
+  }
+  if ("default" in param && param.default !== undefined) {
+    description += ` (default: ${escapeCell(formatDefault(param.default))})`;
+  }
+  return description;
+}
+
+/** The single-line usage string: invocation + positionals + `[options]`. */
+function formatUsage(verb: VerbSpec): string {
+  const positionals = verb.params.filter((p) => p.positional);
+  const flags = verb.params.filter((p) => !p.positional);
+  const segments = [formatInvocation(verb)];
+  for (const positional of positionals) {
+    segments.push(formatPositionalToken(positional));
+  }
+  if (flags.length > 0) segments.push("[options]");
+  return segments.join(" ");
+}
+
+/** The Args table for a verb's positionals, or `""` when it has none. */
+function formatArgsTable(params: readonly ParamSpec[]): string {
+  const positionals = params.filter((p) => p.positional);
+  if (positionals.length === 0) return "";
+  const rows = ["| Argument | Required | Description |", "| --- | --- | --- |"];
+  for (const param of positionals) {
+    const required = param.required ? "yes" : "no";
+    rows.push(
+      `| \`${formatPositionalToken(param)}\` | ${required} | ${describeParam(param)} |`,
+    );
+  }
+  return `**Arguments**\n\n${rows.join("\n")}`;
+}
+
+/** The Flags table for a verb's non-positional params, or `""` when it has none. */
+function formatFlagsTable(params: readonly ParamSpec[]): string {
+  const flags = params.filter((p) => !p.positional);
+  if (flags.length === 0) return "";
+  const rows = ["| Flag | Value | Description |", "| --- | --- | --- |"];
+  for (const param of flags) {
+    // The `<a|b|c>` enum token carries pipes — escape them so the code-span cell
+    // does not split the table column.
+    const value = formatFlagValue(param);
+    const valueCell = value === "" ? "—" : `\`${escapeCell(value)}\``;
+    rows.push(
+      `| \`--${kebabCase(param.name)}\` | ${valueCell} | ${describeParam(param)} |`,
+    );
+  }
+  return `**Flags**\n\n${rows.join("\n")}`;
+}
+
+/** The Examples block for a verb, or `""` when none are declared. */
+function formatExamples(examples: readonly Example[] | undefined): string {
+  if (!examples || examples.length === 0) return "";
+  const lines = ["```bash"];
+  for (const example of examples) {
+    lines.push(
+      example.note ? `${example.cmd}  # ${example.note}` : example.cmd,
+    );
+  }
+  lines.push("```");
+  return `**Examples**\n\n${lines.join("\n")}`;
+}
+
+/** The Store / Mutation / MCP attribute bullets for one verb. */
+function formatVerbAttributes(verb: VerbSpec): string {
+  const bullets = [
+    verb.capability.needsStore
+      ? "- Store: reads the local store (`pragma sources update` builds it)."
+      : "- Store: storeless.",
+  ];
+  if (verb.capability.mutates) {
+    bullets.push(
+      "- Mutation: plan-first — preview with `--dry-run`, apply with `--yes`, reverse with `--undo`.",
+    );
+  }
+  bullets.push(
+    verb.capability.mcp.expose
+      ? `- MCP: exposed as the \`${toolName(verb.path)}\` tool.`
+      : "- MCP: not exposed (CLI-only).",
+  );
+  return bullets.join("\n");
+}
+
+/** Join page blocks with blank lines, dropping empties, and end in ONE newline. */
+function assemblePage(blocks: readonly string[]): string {
+  return `${blocks.filter((block) => block.length > 0).join("\n\n")}\n`;
+}
+
+/** Render one verb's `commands.md` section (heading through examples). */
+function renderCommandSection(verb: VerbSpec): string {
+  const blocks = [
+    `### ${formatInvocation(verb)}`,
+    verb.summary,
+    verb.doc ?? "",
+    `\`\`\`\n${formatUsage(verb)}\n\`\`\``,
+    formatArgsTable(verb.params),
+    formatFlagsTable(verb.params),
+    formatVerbAttributes(verb),
+    formatExamples(verb.examples),
+  ];
+  return blocks.filter((block) => block.length > 0).join("\n\n");
+}
+
+/** Render the CLI command reference, grouped by noun. */
+function renderCommandsPage(verbs: readonly VerbSpec[]): string {
+  const blocks = [
+    "# CLI command reference",
+    "Every `pragma` command, grouped by noun. Generated from the live capability grammar — do not edit by hand.",
+    "Global flags apply to every command: `--format <plain|llm|json>` (auto-detected — the llm/condensed-Markdown form turns on when output is piped), `--verbose`, and `--detail <summary|standard|detailed>`.",
+  ];
+  let currentNoun = "";
+  for (const verb of verbs) {
+    const noun = verb.path[0];
+    if (noun !== currentNoun) {
+      currentNoun = noun;
+      blocks.push(`## ${noun}`);
+    }
+    blocks.push(renderCommandSection(verb));
+  }
+  return assemblePage(blocks);
+}
+
+/** One MCP tool input row: name, projected type, requiredness, description. */
+interface ToolParamRow {
+  readonly name: string;
+  readonly type: string;
+  readonly required: boolean;
+  readonly description: string;
+}
+
+/** Collect a tool's input rows: the verb's params plus the injected MCP-only ones. */
+function collectToolParams(verb: VerbSpec): readonly ToolParamRow[] {
+  const rows: ToolParamRow[] = [];
+  for (const param of verb.params) {
+    rows.push({
+      name: param.name,
+      type: formatParamType(param),
+      required: param.required === true,
+      description: describeParam(param),
+    });
+  }
+  if (verb.disclosure) {
+    rows.push({
+      name: "detail",
+      type: `enum(${verb.disclosure.levels.join(", ")})`,
+      required: false,
+      description: `Progressive-disclosure level (default ${verb.disclosure.default}).`,
+    });
+  }
+  if (verb.capability.mutates) {
+    rows.push({
+      name: "confirm",
+      type: "boolean",
+      required: false,
+      description:
+        "Set true to execute; otherwise a plan is returned (default false).",
+    });
+    rows.push({
+      name: "cwd",
+      type: "string",
+      required: false,
+      description:
+        "Absolute project directory to write into; defaults to the server's working directory.",
+    });
+  }
+  return rows;
+}
+
+/** The input-params table for a tool, or a storeless-note when it takes none. */
+function formatToolParams(verb: VerbSpec): string {
+  const rows = collectToolParams(verb);
+  if (rows.length === 0) return "_No input parameters._";
+  const table = [
+    "| Parameter | Type | Required | Description |",
+    "| --- | --- | --- | --- |",
+  ];
+  for (const row of rows) {
+    const required = row.required ? "yes" : "no";
+    table.push(
+      `| \`${row.name}\` | ${row.type} | ${required} | ${row.description} |`,
+    );
+  }
+  return table.join("\n");
+}
+
+/** The read-only / mutation + destructive annotation line for a tool. */
+function formatToolAnnotations(verb: VerbSpec): string {
+  if (!verb.capability.mutates) return "Read-only.";
+  const destructive =
+    verb.capability.destructive === true
+      ? " Marked destructive."
+      : verb.capability.destructive === false
+        ? " Non-destructive."
+        : "";
+  return `Mutation — plan-first (set \`confirm: true\` to apply).${destructive}`;
+}
+
+/** Render one tool's `tools.md` section. */
+function renderToolSection(verb: VerbSpec): string {
+  const blocks = [
+    `### ${toolName(verb.path)}`,
+    verb.doc ?? verb.summary,
+    formatToolAnnotations(verb),
+    "**Input**",
+    formatToolParams(verb),
+  ];
+  return blocks.join("\n\n");
+}
+
+/** The non-tool MCP surface (resources + native prompts) declared by the modules. */
+function collectMcpExtras(modules: readonly CapabilityModule[]): {
+  readonly resources: readonly string[];
+  readonly prompts: boolean;
+} {
+  const resources: string[] = [];
+  let prompts = false;
+  for (const module of modules) {
+    if (module.mcpResources?.surface) {
+      resources.push(...module.mcpResources.surface.templates);
+    }
+    if (module.mcpPrompts) prompts = true;
+  }
+  // Default lexicographic sort — deterministic, and the same idiom `emitSurface`
+  // uses for its `resources`/`tools` lists.
+  return { resources: [...resources].sort(), prompts };
+}
+
+/** Render the non-tool MCP surface section for `tools.md`. */
+function renderNonToolSurface(modules: readonly CapabilityModule[]): string {
+  const { resources, prompts } = collectMcpExtras(modules);
+  const bullets: string[] = [];
+  if (resources.length > 0) {
+    bullets.push(
+      `- **Resources**: ${resources.map((r) => `\`${r}\``).join(", ")} — entity reads addressed by URI (listing and autocomplete are storeless over the pack index).`,
+    );
+  }
+  if (prompts) {
+    bullets.push(
+      "- **Prompts**: the design system's workflow templates are offered natively over `prompts/list` and `prompts/get`, and as the `prompt_list` / `prompt_lookup` content tools.",
+    );
+  }
+  bullets.push(
+    "- **Instructions**: the server always sends handshake instructions describing the conventions and the discovery sequence.",
+  );
+  return `## Non-tool surface\n\n${bullets.join("\n")}`;
+}
+
+/** Render the MCP tool reference plus the non-tool surface. */
+function renderToolsPage(
+  verbs: readonly VerbSpec[],
+  modules: readonly CapabilityModule[],
+): string {
+  const tools = verbs.filter((verb) => verb.capability.mcp.expose);
+  const blocks = [
+    "# MCP tool reference",
+    "Every tool the pragma MCP server exposes, plus its non-tool surface. Generated from the live capability grammar — do not edit by hand.",
+    "Mutating tools are plan-first: called without `confirm: true` they return the plan they WOULD apply; called with `confirm: true` they execute. A mutating tool also accepts an optional absolute `cwd`.",
+  ];
+  for (const verb of tools) {
+    blocks.push(renderToolSection(verb));
+  }
+  blocks.push(renderNonToolSurface(modules));
+  return assemblePage(blocks);
+}
+
+/** Render the exit-code table, the response envelope, and the error catalog. */
+function renderErrorsPage(): string {
+  const exitRows = ["| Exit code | Meaning |", "| --- | --- |"];
+  // Integer-like keys ("0".."3") are iterated in ascending numeric order by the
+  // ECMAScript own-key ordering rule, so `Object.entries` is already sorted.
+  for (const [code, meaning] of Object.entries(FIXED_SURFACE.exitCodes)) {
+    exitRows.push(`| \`${code}\` | ${meaning} |`);
+  }
+
+  const catalogRows = ["| Code | Meaning |", "| --- | --- |"];
+  for (const code of ERROR_CODES) {
+    const meaning = ERROR_CODE_DESCRIPTIONS[code];
+    /* v8 ignore next 3 -- exhaustiveness: ERROR_CODE_DESCRIPTIONS is a Record
+       over the ERROR_CODES tuple, so every code is present by construction. */
+    if (meaning === undefined) {
+      throw new Error(`missing error-code description for ${code}`);
+    }
+    catalogRows.push(`| \`${code}\` | ${meaning} |`);
+  }
+
+  return assemblePage([
+    "# Errors & exit codes",
+    "Every command returns a `{ ok, ... }` envelope and maps its failure to one of four process exit codes. Generated from the live error kernel — do not edit by hand.",
+    "## Exit codes",
+    exitRows.join("\n"),
+    "## Response envelope",
+    `\`\`\`json\n${JSON.stringify(FIXED_SURFACE.envelope, null, 2)}\n\`\`\``,
+    "## Error codes",
+    "Every `error.code` in a failure envelope is one of the following:",
+    catalogRows.join("\n"),
+  ]);
+}
+
+/** Render the reference index: overview, derived counts, and links. */
+function renderIndexPage(
+  verbs: readonly VerbSpec[],
+  modules: readonly CapabilityModule[],
+): string {
+  const nouns = new Set(verbs.map((verb) => verb.path[0]));
+  const toolCount = verbs.filter((verb) => verb.capability.mcp.expose).length;
+  return assemblePage([
+    "# pragma reference",
+    "Machine-generated reference for the `pragma` CLI and MCP server, projected from the live capability grammar. Every page here is regenerated by the build and pinned by a drift-guard test, so it can never fall out of step with the code.",
+    "## At a glance",
+    [
+      `- **${nouns.size}** command nouns`,
+      `- **${verbs.length}** CLI commands`,
+      `- **${toolCount}** MCP tools`,
+      `- **${collectMcpExtras(modules).resources.length}** resource template(s)`,
+    ].join("\n"),
+    "## Pages",
+    [
+      "- [CLI command reference](./commands.md) — every `pragma <noun> <verb>`, its arguments, flags, and examples.",
+      "- [MCP tool reference](./tools.md) — every exposed tool, its input schema, and the non-tool surface.",
+      "- [Errors & exit codes](./errors.md) — the exit-code table, response envelope, and error catalog.",
+    ].join("\n"),
+  ]);
+}
+
+/**
+ * Emit the Markdown reference doc set for a set of capability modules.
+ *
+ * Pure and deterministic: the same catalog always yields byte-identical pages
+ * (stable sort, declared param order, no version or timestamps).
+ *
+ * @param modules - The capability modules to project (hidden verbs excluded).
+ * @returns A map of `docs/reference/`-relative path → Markdown content, each
+ *   ending in exactly one trailing newline.
+ */
+export function emitReference(
+  modules: readonly CapabilityModule[],
+): ReferenceDocs {
+  const verbs = collectDocVerbs(modules);
+  return new Map<string, string>([
+    ["index.md", renderIndexPage(verbs, modules)],
+    ["commands.md", renderCommandsPage(verbs)],
+    ["tools.md", renderToolsPage(verbs, modules)],
+    ["errors.md", renderErrorsPage()],
+  ]);
+}