@canonical/pragma-cli 0.34.0 → 0.35.0

package/src/kernel/runtime/refs/parseRef.ts

@@ -8,8 +8,8 @@
  * exactly what the config declared.
  */
 
-import type { PackDeclaration } from "../../config/types.js";
-import { PragmaError } from "../../error/PragmaError.js";
+import type { PackDeclaration } from "../../config/index.js";
+import { PragmaError } from "../../error/index.js";
 
 /** A parsed, validated package reference — discriminated by `kind`. */
 export type PackageRef =

package/src/kernel/runtime/refs/resolve.ts

@@ -13,7 +13,7 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, join, relative } from "node:path";
-import { PragmaError } from "../../error/PragmaError.js";
+import { PragmaError } from "../../error/index.js";
 import { refsCacheDir } from "../paths.js";
 import { cloneRef, fetchRef, headCommit } from "./gitOps.js";
 import { type PackageRef, redactUrl } from "./parseRef.js";
@@ -75,7 +75,7 @@ function errorDetail(error: unknown): string {
 }
 
 /** Recursively collect `*.ttl` files under a directory (a manual walk — the
- * compiled binary's node:fs globSync mishandles `**`, so we avoid it). */
+ * node:fs globSync has mishandled `**` under a shipped runtime, so we avoid it). */
 function walkTtl(
   dir: string,
   base: string,
@@ -95,7 +95,7 @@ function walkTtl(
     // symlinked `.ttl` was silently skipped (L6). Follow the link to recover a
     // symlinked FILE, but NEVER recurse into a symlinked DIRECTORY: a symlink
     // cycle (a link to an ancestor dir) would recurse without bound — a
-    // stack-overflow RangeError surfacing as an INTERNAL "please report" — and a
+    // stack-overflow RangeError surfacing as an INTERNAL "report" — and a
     // linked directory could pull `.ttl` from OUTSIDE the package root. Linking
     // individual source files (all L6 needs) stays supported; a dangling link is
     // skipped, not fatal.
@@ -343,7 +343,7 @@ export async function resolvePackage(
           "0.0.0";
       } catch (error) {
         // A malformed `package.json` for an otherwise-installed package: name it
-        // as a data error, not an INTERNAL_ERROR "please report this issue".
+        // as a data error, not an INTERNAL_ERROR "report this issue".
         throw PragmaError.configError(
           `Package "${ref.pkg}" has an invalid package.json (${pkgJsonPath}): ${errorDetail(error)}`,
         );

package/src/kernel/runtime/storeReadiness.ts

@@ -18,8 +18,7 @@
  */
 
 import type { ConfigLayers } from "../config/types.js";
-import { PragmaError } from "../error/PragmaError.js";
-import { cliRecovery } from "../error/recovery.js";
+import { cliRecovery, PragmaError } from "../error/index.js";
 import { resolveSources } from "./resolveSources.js";
 
 /**

package/src/kernel/runtime/types.ts

@@ -21,10 +21,14 @@ export interface GlobalFlags {
   readonly llm: boolean;
   /** True when `llm` was inferred from a non-interactive stdout, not requested. */
   readonly autoLlm?: boolean;
-  /** Selected output format; `--format text` is normalised to `plain`. */
+  /** Selected output format (`plain`, `llm`, or `json` — the full set). */
   readonly format: OutputFormat;
   /** Diagnostic output to stderr. */
   readonly verbose: boolean;
+  /** True when `--no-headers` suppressed the plain-table header row. */
+  readonly noHeaders?: boolean;
+  /** True when `--quiet` suppresses success/progress output (errors keep printing). */
+  readonly quiet?: boolean;
   /** Explicit progressive-disclosure level from `--detail`, if any. */
   readonly detail?: DetailLevel;
 }
@@ -94,6 +98,8 @@ export interface QueryFacade {
 export interface MutationRuntime {
   /** True for a plan-only preview; false for a real execution. */
   readonly preview: boolean;
+  /** True when this invocation reverses a previous run (`--undo`). */
+  readonly undo?: boolean;
 }
 
 /**
@@ -207,4 +213,12 @@ export interface PragmaRuntime {
    * returning the Task, and the projector reads it back on the real-run branch.
    */
   exec?: RunnerOptions;
+  /**
+   * Structured plan data a mutating verb stashes for the `--dry-run` branch to
+   * render through its `output.formatPlan` seam, and to carry verbatim in the
+   * JSON dry-run envelope. NOT readonly, and set the same way `exec` is: the
+   * verb writes it before returning its Task. Unset on every verb that has no
+   * plan of its own, which is what keeps the raw-effect render the default.
+   */
+  planData?: unknown;
 }

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

@@ -7,46 +7,41 @@ import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { embeddedManifest } from "./graphpack/embedded.js";
 
 /**
- * The store-boot path only fully lives in the standalone binary: this is the
- * one thing vitest's in-process suite cannot catch — whether oxigraph's WASM
- * and the embedded pack survive `bun build --compile`. So compile a fresh
- * binary from the current source and spawn it. If the WASM did not embed, the
- * probe crashes and this fails loudly (rather than the compiled CLI silently
- * failing every store-backed command in production).
+ * The store-boot path at the PROCESS BOUNDARY: whether oxigraph's WASM and the
+ * embedded pack actually load from the shipped artifact. vitest's in-process
+ * suite cannot catch this — it imports the source tree directly, so a break in
+ * how the emit resolves the WASM or the inlined pack would leave it green while
+ * every store-backed command failed for a consumer.
+ *
+ * It used to compile a `bun build --compile` binary and spawn that, because the
+ * shipped artifact WAS that binary and the question was whether the WASM
+ * survived embedding. The package now ships emitted JavaScript, so the same
+ * guard points at the same place it always did — what a consumer runs — which is
+ * `node dist/src/bin.js`. Compiling a binary here would test an artifact nobody
+ * receives.
+ *
+ * Every spawn runs in a scratch cwd with `HOME` and all three XDG roots inside
+ * it, so anything the CLI answers it answered from its own shipped state.
  */
-const packageRoot = fileURLToPath(new URL("../../../", import.meta.url));
-
 let workdir: string;
-let binary: string;
+
+/** The shipped entry, provisioned by `testing/perf/globalSetup.ts`. */
+const shippedEntry = fileURLToPath(
+  new URL("../../../dist/src/bin.js", import.meta.url),
+);
 
 beforeAll(() => {
   workdir = mkdtempSync(join(tmpdir(), "pragma-wasm-smoke-"));
-  binary = join(workdir, "pragma-smoke");
-  const build = spawnSync(
-    "bun",
-    [
-      "build",
-      "--compile",
-      "--target=bun-linux-x64",
-      "src/bin.ts",
-      "--outfile",
-      binary,
-    ],
-    { cwd: packageRoot, stdio: "pipe", encoding: "utf-8" },
-  );
-  if (build.status !== 0) {
-    throw new Error(`smoke build failed:\n${build.stderr}`);
-  }
-}, 120_000);
+});
 
 afterAll(() => {
   rmSync(workdir, { recursive: true, force: true });
 });
 
-/** Run the compiled binary in a scratch cwd with isolated XDG dirs (no local
- * node_modules, no real cache) — proves the binary is self-contained. */
+/** Run the shipped entry in a scratch cwd with isolated XDG dirs (no real
+ * config, cache or state) — anything it answers, it answered from itself. */
 const runBinary = (args: string[]) =>
-  spawnSync(binary, args, {
+  spawnSync(process.execPath, [shippedEntry, ...args], {
     cwd: workdir,
     stdio: "pipe",
     encoding: "utf-8",
@@ -59,8 +54,8 @@ const runBinary = (args: string[]) =>
     },
   });
 
-describe("oxigraph WASM + embedded pack embed in the compiled binary (PROTECTED)", () => {
-  it("dist binary boots the embedded store via __store-probe (needsStore path)", () => {
+describe("oxigraph WASM + embedded pack load from the shipped entry (PROTECTED)", () => {
+  it("the shipped entry boots the embedded store via __store-probe (needsStore path)", () => {
     const run = runBinary(["__store-probe"]);
     expect(run.status, run.stderr).toBe(0);
     const out = JSON.parse(run.stdout.trim()) as {
@@ -69,14 +64,14 @@ describe("oxigraph WASM + embedded pack embed in the compiled binary (PROTECTED)
       triples: string;
     };
     expect(out.ok).toBe(true);
-    // The compiled binary is the only place this is worth asserting: the store
-    // it booted from the inlined `data.nq` must hold exactly what the committed
+    // Worth asserting only across the process boundary: the store booted from
+    // the inlined `data.nq` must hold exactly what the committed
     // `manifest.json` claims was built into it.
     expect(Number(out.triples)).toBe(embeddedManifest().tripleCount);
     expect(out.entities).toBeGreaterThan(0);
   });
 
-  it("dist binary runs storeless sources status", () => {
+  it("the shipped entry runs storeless sources status", () => {
     const run = runBinary(["sources", "status", "--format", "json"]);
     expect(run.status, run.stderr).toBe(0);
     const envelope = JSON.parse(run.stdout.trim()) as {
@@ -88,10 +83,13 @@ describe("oxigraph WASM + embedded pack embed in the compiled binary (PROTECTED)
     expect(envelope.data.store).toBe("embedded");
   });
 
-  // Regression guard: `sources update` walks a package's TTL directories. The
-  // compiled binary's node:fs globSync mishandles `**` (returns bogus paths),
-  // which the in-process suite could not catch — so exercise the real binary.
-  it("dist binary runs sources update end-to-end (build + point + status)", () => {
+  // Regression guard: `sources update` walks a package's TTL directories with
+  // `node:fs` globSync, whose `**` handling has broken under a shipped runtime
+  // before (returning bogus paths) where the in-process suite stayed green — so
+  // exercise it through the real entry. This case also writes a real
+  // `pragma.config.ts`, which the shipped entry loads through node's TypeScript
+  // type stripping: the one test that exercises that path end-to-end.
+  it("the shipped entry runs sources update end-to-end (build + point + status)", () => {
     const pkg = join(workdir, "pkg");
     const proj = join(workdir, "proj");
     mkdirSync(join(pkg, "definitions"), { recursive: true });
@@ -117,7 +115,7 @@ ex:one a ex:Widget ; rdfs:label "One" .
       XDG_CONFIG_HOME: join(workdir, "config"),
     };
     const inProj = (args: string[]) =>
-      spawnSync(binary, args, {
+      spawnSync(process.execPath, [shippedEntry, ...args], {
         cwd: proj,
         stdio: "pipe",
         encoding: "utf-8",

package/src/kernel/spec/emitReference.ts

@@ -17,7 +17,7 @@
 
 import { BIN_NAME, PROJECT_CONFIG_FILENAME } from "../../constants.js";
 import type { RawConfig } from "../config/types.js";
-import { ERROR_CODES } from "../error/constants.js";
+import { ERROR_CODES } from "../error/index.js";
 import {
   FIXED_SURFACE,
   kebabCase,
@@ -28,6 +28,7 @@ import type {
   CapabilityModule,
   Example,
   ParamSpec,
+  ReferenceCliSyntax,
   VerbSpec,
 } from "./types.js";
 
@@ -49,9 +50,9 @@ const ERROR_CODE_DESCRIPTIONS: Record<(typeof ERROR_CODES)[number], string> = {
   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.",
+  STORE_UNAVAILABLE: "The local store cannot be reached or is not built.",
+  CONFIG_ERROR: "The layered configuration cannot be resolved.",
+  INTERNAL_ERROR: "An unexpected failure — report it as a bug.",
   UNSUPPORTED: "A capability is unavailable in this build or environment.",
 };
 
@@ -165,22 +166,39 @@ function formatUsage(verb: VerbSpec): string {
   return segments.join(" ");
 }
 
-/** The Args table for a verb's positionals, or `""` when it has none. */
-function formatArgsTable(params: readonly ParamSpec[]): string {
+/**
+ * The Args table for a verb's positionals, or `""` when it has none. A
+ * mounted verb's {@link ReferenceCliSyntax.positionalTokens} supplies the
+ * REGISTERED token per param — the one its usage line prints — so the
+ * Argument column and the synopsis agree on the same spelling; without one,
+ * the token derives from the param name.
+ */
+function formatArgsTable(
+  params: readonly ParamSpec[],
+  positionalTokens?: Readonly<Record<string, string>>,
+): 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)} |`,
-    );
+    const token =
+      positionalTokens?.[param.name] ?? formatPositionalToken(param);
+    rows.push(`| \`${token}\` | ${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 {
+/**
+ * The Flags table for a verb's non-positional params, or `""` when it has
+ * none. A mounted verb's {@link ReferenceCliSyntax.flagTokens} supplies the
+ * REGISTERED token per param (e.g. a default-true boolean's `--no-` form);
+ * without one, the token derives from the param name.
+ */
+function formatFlagsTable(
+  params: readonly ParamSpec[],
+  flagTokens?: Readonly<Record<string, string>>,
+): string {
   const flags = params.filter((p) => !p.positional);
   if (flags.length === 0) return "";
   const rows = ["| Flag | Value | Description |", "| --- | --- | --- |"];
@@ -189,9 +207,8 @@ function formatFlagsTable(params: readonly ParamSpec[]): string {
     // does not split the table column.
     const value = formatFlagValue(param);
     const valueCell = value === "" ? "—" : `\`${escapeCell(value)}\``;
-    rows.push(
-      `| \`--${kebabCase(param.name)}\` | ${valueCell} | ${describeParam(param)} |`,
-    );
+    const token = flagTokens?.[param.name] ?? `--${kebabCase(param.name)}`;
+    rows.push(`| \`${token}\` | ${valueCell} | ${describeParam(param)} |`);
   }
   return `**Flags**\n\n${rows.join("\n")}`;
 }
@@ -235,26 +252,39 @@ function assemblePage(blocks: readonly string[]): string {
 }
 
 /** Render one verb's `commands.md` section (heading through examples). */
-function renderCommandSection(verb: VerbSpec): string {
+function renderCommandSection(
+  verb: VerbSpec,
+  syntax?: ReferenceCliSyntax,
+): string {
   const blocks = [
     `### ${formatInvocation(verb)}`,
     verb.summary,
     verb.doc ?? "",
-    `\`\`\`\n${formatUsage(verb)}\n\`\`\``,
-    formatArgsTable(verb.params),
-    formatFlagsTable(verb.params),
+    `\`\`\`\n${syntax ? `${BIN_NAME} ${syntax.usage}` : formatUsage(verb)}\n\`\`\``,
+    formatArgsTable(verb.params, syntax?.positionalTokens),
+    formatFlagsTable(verb.params, syntax?.flagTokens),
     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 {
+/**
+ * Render the CLI command reference, grouped by noun. A noun whose module
+ * declares a `cliProjection.referenceIntro` gets that Markdown inserted
+ * directly under its heading, and a verb its module supplies a
+ * `cliProjection.referenceSyntax` for renders the MOUNTED usage/flag
+ * spelling (generic module fields — the kernel renders, the module authors).
+ */
+function renderCommandsPage(
+  verbs: readonly VerbSpec[],
+  nounIntros: ReadonlyMap<string, string>,
+  verbSyntax: ReadonlyMap<VerbSpec, ReferenceCliSyntax>,
+): string {
   const blocks = [
     "# CLI command reference",
     `Every \`${BIN_NAME}\` 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>`.",
+    "Global flags apply to every command: `--format <plain|llm|json>` (auto-detected — the llm/condensed-Markdown form turns on when output is piped), `--verbose`, `--no-headers`, `--quiet`, and `--detail <summary|standard|detailed>`.",
   ];
   let currentNoun = "";
   for (const verb of verbs) {
@@ -262,12 +292,45 @@ function renderCommandsPage(verbs: readonly VerbSpec[]): string {
     if (noun !== currentNoun) {
       currentNoun = noun;
       blocks.push(`## ${noun}`);
+      const intro = nounIntros.get(noun);
+      if (intro) blocks.push(intro);
     }
-    blocks.push(renderCommandSection(verb));
+    blocks.push(renderCommandSection(verb, verbSyntax.get(verb)));
   }
   return assemblePage(blocks);
 }
 
+/** Collect each noun's declared reference intro from its module's mount. */
+function collectNounIntros(
+  modules: readonly CapabilityModule[],
+): Map<string, string> {
+  const intros = new Map<string, string>();
+  for (const module of modules) {
+    const intro = module.cliProjection?.referenceIntro;
+    if (!intro) continue;
+    for (const verb of module.verbs) {
+      intros.set(verb.path[0], intro);
+    }
+  }
+  return intros;
+}
+
+/** Collect each mounted verb's registered CLI syntax from its module. */
+function collectVerbSyntax(
+  modules: readonly CapabilityModule[],
+): Map<VerbSpec, ReferenceCliSyntax> {
+  const syntax = new Map<VerbSpec, ReferenceCliSyntax>();
+  for (const module of modules) {
+    const provider = module.cliProjection?.referenceSyntax;
+    if (!provider) continue;
+    for (const verb of module.verbs) {
+      const entry = provider(verb.path);
+      if (entry) syntax.set(verb, entry);
+    }
+  }
+  return syntax;
+}
+
 /** One MCP tool input row: name, projected type, requiredness, description. */
 interface ToolParamRow {
   readonly name: string;
@@ -468,13 +531,18 @@ const CONFIG_FIELD_DOCS: Record<keyof RawConfig, ConfigFieldDoc> = {
   name: {
     type: "string (optional)",
     notes:
-      "Distribution-only — see below. The binary's own name, read from the distribution config at module load.",
+      "Distribution-only — see below. The program's own name, read from the distribution config at module load.",
   },
   help: {
     type: "string (optional)",
     notes:
       "Distribution-only — see below. The one-line blurb on the front door and in the MCP handshake.",
   },
+  logo: {
+    type: "string[] (optional)",
+    notes:
+      "Distribution-only — see below. ASCII-art wordmark lines shown above the header on root `--help`, tinted with the terminal palette's orange slot. Declared content, not code: a wordmark spells the distribution's name, so a fork ships its own art or omits the field and gets no wordmark. Omit or leave empty for a bare header.",
+  },
   colophon: {
     type: "object (optional)",
     notes:
@@ -488,7 +556,7 @@ const CONFIG_FIELD_DOCS: Record<keyof RawConfig, ConfigFieldDoc> = {
   tier: {
     type: "string (optional)",
     notes:
-      "Accepted by the validator and SCOPES NOTHING: since the block list became declared content, no read filters by tier — the value is only reported by `config show` and `info`. Set it with `config set tier <path>`; `none`, `default` or `-` clear it.",
+      "Accepted by the validator and SCOPES NOTHING: since the block list became declared content, no read filters by tier — the value is only reported by `config show` and `info`. Set it with `config set tier <path>` and clear it with `config unset tier`; `none`, `default` and `-` are refused as values, so no string doubles as a remove-marker.",
   },
   channel: {
     type: "`normal` | `experimental` | `prerelease` (optional)",
@@ -550,22 +618,22 @@ function renderConfigPage(): string {
     "## Layers",
     "From lowest to highest precedence:",
     [
-      `1. **Built-in defaults** — the distribution config compiled into the binary.`,
+      `1. **Built-in defaults** — the distribution config shipped with the package.`,
       `2. **Global config** — \`$XDG_CONFIG_HOME/${BIN_NAME}/config.json\`, written by \`${BIN_NAME} config set\`.`,
-      `3. **Project config** — the nearest \`${PROJECT_CONFIG_FILENAME}\` (or \`${BIN_NAME}.config.js\`, the compiled-binary fallback), walking up from the working directory.`,
+      `3. **Project config** — the nearest \`${PROJECT_CONFIG_FILENAME}\` (or \`${BIN_NAME}.config.js\`, the JavaScript fallback), walking up from the working directory.`,
     ].join("\n"),
     "A higher layer REPLACES a lower one field by field. No field is deep-merged — not `packs`, not `prefixes`, not `completion`. A project declaring one prefix therefore replaces the distribution's whole prefix map, including the namespaces its own packs are built with; declare every prefix you need, not only the new one.",
     "## Fields",
     "The `Type` column is prose; the field set and each field's optionality are checked against the validator.",
     rows.join("\n"),
     "## Distribution-only fields",
-    `\`name\`, \`help\` and \`issuesUrl\` are read from the distribution config when the program loads, because the surfaces that need them — \`--help\`, shell completion, the MCP handshake, the first-run note — run before or without the config layer. \`colophon\` is read from the same file at render time: the \`colophon\` verb narrates whatever the distribution declares there. The validator ACCEPTS all four in a global or project layer, and they have **no effect there and are not reported** by \`config show\`. Changing them means forking: edit the distribution config and rebuild the binary. The distribution config's \`vocabulary\` export is not a config field at all — no layer may declare it, and a fork changes it in the same file it changes \`name\` in.`,
+    `\`name\`, \`help\`, \`logo\` and \`issuesUrl\` are read from the distribution config when the program loads, because the surfaces that need them — \`--help\`, shell completion, the MCP handshake, the first-run note — run before or without the config layer. \`colophon\` is read from the same file at render time: the \`colophon\` verb narrates whatever the distribution declares there. The validator ACCEPTS all five in a global or project layer, and they have **no effect there and are not reported** by \`config show\`. Changing them means forking: edit the distribution config and rebuild the package. The distribution config's \`vocabulary\` export is not a config field at all — no layer may declare it, and a fork changes it in the same file it changes \`name\` in.`,
     "## What `config show` reports",
-    `\`${BIN_NAME} config show\` prints ${REPORTED_FIELDS.map((field) => `\`${field}\``).join(", ")} — those and only those — each with the layer that supplied it. The rest resolve without being reported that way: \`prefixes\` and \`completion\` appear only in the \`--format json\` payload, \`prefixes\` with an origin and \`completion\` with none; \`stories\` carries an origin whose value the payload leaves out; and the four distribution-only fields above carry neither. The plain and llm forms print those rows and nothing else; \`--format json\` returns the resolved config and the origin map whole.`,
+    `\`${BIN_NAME} config show\` prints ${REPORTED_FIELDS.map((field) => `\`${field}\``).join(", ")} — those and only those — each with the layer that supplied it. The rest resolve without being reported that way: \`prefixes\` and \`completion\` appear only in the \`--format json\` payload, \`prefixes\` with an origin and \`completion\` with none; \`stories\` carries an origin whose value the payload leaves out; and the five distribution-only fields above carry neither. The plain and llm forms print those rows and nothing else; \`--format json\` returns the resolved config and the origin map whole.`,
     "## Renamed: `packages` → `packs`",
     "The `packages` field was renamed to `packs`. A layer that still declares `packages:` fails loudly: the rename is detected before the schema's unknown-key stripping could hide it, and the error names it. Rename the key — the entry shape is unchanged.",
     "## Removed: `generators`",
-    "The `generators` field was removed: it was accepted by the validator, layered, and read by nothing — the `create` verbs resolve their generators statically (a compiled binary can only run generators it was linked with), so declaring it changed only what `config show` printed. A layer that still declares it fails loudly at load with an error naming the removed field; delete it. Declared generators may return as a working feature in a later program.",
+    "The `generators` field was removed: it was accepted by the validator, layered, and read by nothing — the `create` verbs resolve their generators statically (they are imported by name, not looked up at run time), so declaring it changed only what `config show` printed. A layer that still declares it fails loudly at load with an error naming the removed field; delete it. Declared generators may return as a working feature in a later program.",
     "## Removed: `completion.caseSensitive`",
     "The `completion.caseSensitive` field was removed: it was accepted by the validator and read by nothing — completion matching is declared per parameter by the capability grammar, never configured. A layer that still sets it fails loudly at load with an error naming the removed field; delete the key. `completion.minChars` and `completion.families` are unchanged.",
     "## Reading and writing",
@@ -616,7 +684,14 @@ export function emitReference(
   const verbs = collectDocVerbs(modules);
   return new Map<string, string>([
     ["index.md", renderIndexPage(verbs, modules)],
-    ["commands.md", renderCommandsPage(verbs)],
+    [
+      "commands.md",
+      renderCommandsPage(
+        verbs,
+        collectNounIntros(modules),
+        collectVerbSyntax(modules),
+      ),
+    ],
     ["tools.md", renderToolsPage(verbs, modules)],
     ["errors.md", renderErrorsPage()],
     ["config.md", renderConfigPage()],

package/src/kernel/spec/emitSurface.ts

@@ -82,11 +82,19 @@ export const FIXED_SURFACE = {
       flag: "--format <plain|llm|json>",
       doc: "Select output format (llm = condensed Markdown for agents)",
     },
-    { flag: "--verbose", doc: "Diagnostic output on stderr" },
+    { flag: "--verbose", doc: "Diagnostic output on stderr (sources update)" },
     {
       flag: "--detail <level>",
       doc: "Progressive-disclosure level (summary, standard, detailed)",
     },
+    {
+      flag: "--no-headers",
+      doc: "Hide the table header row in plain output",
+    },
+    {
+      flag: "--quiet",
+      doc: "Suppress success and progress output (errors still print)",
+    },
   ],
   detailLevels: ["summary", "standard", "detailed"],
   envelope: {
@@ -151,8 +159,30 @@ function positionalToken(param: ParamSpec): string {
     : `[${param.name}${variadic}]`;
 }
 
-/** Project one verb into its surface entry, omitting default/falsy fields. */
-export function emitVerb(verb: VerbSpec): EmittedVerb {
+/**
+ * Project one verb into its surface entry, omitting default/falsy fields.
+ *
+ * `flagTokens` is a MOUNTED verb's registered spelling per param name — the
+ * same `ReferenceCliSyntax.flagTokens` seam the reference emitter consumes,
+ * supplied by the module's `cliProjection` and derived there from
+ * `buildOptionInfo` (the single flag-shape authority both binaries register
+ * from; a default-`true` confirm registers ONLY its `--no-<kebab>` form).
+ * Without it the token derives from the param name — the kernel convention,
+ * sound for kernel-registered verbs where B9 ADDS the `--no-` negation
+ * beside the positive form; false for a mounted noun, where kebab-casing
+ * wrote seven covenant tokens the CLI rejects (`--with-styles`, `--ssr`, …).
+ *
+ * `positionalTokens` is the same seam's registered POSITIONAL spelling per
+ * param name (`componentPath` → `[component-path]` — the token the usage
+ * line and the Args tables print), preferred for `args` exactly as
+ * `flagTokens` is for `flags`; a param absent there keeps the kernel
+ * `<name>`/`[name]` derivation.
+ */
+export function emitVerb(
+  verb: VerbSpec,
+  flagTokens?: Readonly<Record<string, string>>,
+  positionalTokens?: Readonly<Record<string, string>>,
+): EmittedVerb {
   const positionals = verb.params.filter((p) => p.positional);
   const flags = verb.params.filter((p) => !p.positional);
 
@@ -165,9 +195,14 @@ export function emitVerb(verb: VerbSpec): EmittedVerb {
     mcp?: string | false;
   } = { v: verbLabel(verb.path) };
 
-  if (positionals.length > 0) entry.args = positionals.map(positionalToken);
+  if (positionals.length > 0)
+    entry.args = positionals.map(
+      (p) => positionalTokens?.[p.name] ?? positionalToken(p),
+    );
   if (flags.length > 0)
-    entry.flags = flags.map((p) => `--${kebabCase(p.name)}`);
+    entry.flags = flags.map(
+      (p) => flagTokens?.[p.name] ?? `--${kebabCase(p.name)}`,
+    );
   if (verb.capability.mutates) entry.mutates = true;
   if (verb.capability.needsStore) entry.needsStore = true;
   entry.mcp = verb.capability.mcp.expose ? toolName(verb.path) : false;
@@ -195,7 +230,14 @@ export function emitSurface(
       const noun = verb.path[0];
       const bucket = nouns[noun] ?? { verbs: [] };
       nouns[noun] = bucket;
-      bucket.verbs.push(emitVerb(verb));
+      // A mounted verb's covenant flags AND args are its REGISTERED
+      // spellings, from the module's own syntax seam (see emitVerb) — the
+      // covenant must name tokens the CLI parses (`--no-with-styles`,
+      // `[component-path]`), not camelCase param names its help never prints.
+      const syntax = module.cliProjection?.referenceSyntax?.(verb.path);
+      bucket.verbs.push(
+        emitVerb(verb, syntax?.flagTokens, syntax?.positionalTokens),
+      );
       if (verb.capability.mcp.expose) tools.push(toolName(verb.path));
     }
     // Non-tool MCP surfaces (module hooks, NOT verbs): the resource template ids

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

@@ -84,11 +84,13 @@ describe("surface conformance (PROTECTED)", () => {
     );
   });
 
-  it("freezes exactly 37 designed MCP tools including info, config_show, config_set, colophon", () => {
-    expect(golden.mcpSurface.tools).toHaveLength(37);
+  it("freezes exactly 42 designed MCP tools including info, the config family, colophon", () => {
+    expect(golden.mcpSurface.tools).toHaveLength(42);
     expect(golden.mcpSurface.tools).toContain("info");
     expect(golden.mcpSurface.tools).toContain("config_show");
+    expect(golden.mcpSurface.tools).toContain("config_get");
     expect(golden.mcpSurface.tools).toContain("config_set");
+    expect(golden.mcpSurface.tools).toContain("config_unset");
     expect(golden.mcpSurface.tools).toContain("colophon");
   });
 });