@canonical/pragma-cli 0.33.0 → 0.35.0

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

@@ -1,57 +1,47 @@
 import { spawnSync } from "node:child_process";
-import {
-  existsSync,
-  mkdirSync,
-  mkdtempSync,
-  rmSync,
-  writeFileSync,
-} from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 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",
@@ -64,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 {
@@ -74,27 +64,32 @@ describe("oxigraph WASM + embedded pack embed in the compiled binary (PROTECTED)
       triples: string;
     };
     expect(out.ok).toBe(true);
-    expect(out.entities).toBe(6);
-    expect(Number(out.triples)).toBeGreaterThan(0);
+    // 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 {
       ok: boolean;
-      data: { lockPresent: boolean; cached: boolean };
+      data: { store: string };
     };
     expect(envelope.ok).toBe(true);
-    // A fresh install: no lock, store not yet built.
-    expect(envelope.data.lockPresent).toBe(false);
-    expect(envelope.data.cached).toBe(false);
+    // A fresh install: nothing built here, so the embedded pack answers reads.
+    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 + lock + 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 });
@@ -110,7 +105,7 @@ ex:one a ex:Widget ; rdfs:label "One" .
     );
     writeFileSync(
       join(proj, "pragma.config.ts"),
-      `export default { packages: [{ name: "pkg-a", source: "file://${pkg}" }] };\n`,
+      `export default { packs: [{ name: "pkg-a", source: "file://${pkg}" }] };\n`,
     );
 
     const env = {
@@ -120,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",
@@ -129,14 +124,20 @@ ex:one a ex:Widget ; rdfs:label "One" .
 
     const update = inProj(["sources", "update", "--yes", "--format", "json"]);
     expect(update.status, update.stderr).toBe(0);
-    expect(existsSync(join(proj, "pragma.lock.json"))).toBe(true);
+    const built = (
+      JSON.parse(update.stdout.trim()) as {
+        data: { contentHash: string };
+      }
+    ).data.contentHash;
+    expect(built).toMatch(/^[0-9a-f]{64}$/);
 
     const status = inProj(["sources", "status", "--format", "json"]);
     const envelope = JSON.parse(status.stdout.trim()) as {
-      data: { lockPresent: boolean; cached: boolean; entityCount: number };
+      data: { store: string; contentHash: string; entityCount: number };
     };
-    expect(envelope.data.lockPresent).toBe(true);
-    expect(envelope.data.cached).toBe(true);
+    // The project now reads its OWN pack — the one the update just built.
+    expect(envelope.data.store).toBe("built");
+    expect(envelope.data.contentHash).toBe(built);
     // 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

@@ -6,8 +6,8 @@ import {
 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"];
+/** The five pages every reference doc set carries. */
+const PAGES = ["index.md", "commands.md", "tools.md", "errors.md", "config.md"];
 
 describe("emitReference", () => {
   const docs = emitReference([fixtureReferenceModule]);
@@ -16,7 +16,7 @@ describe("emitReference", () => {
   const tools = docs.get("tools.md") ?? "";
   const errors = docs.get("errors.md") ?? "";
 
-  it("emits exactly the four reference pages", () => {
+  it("emits exactly the five reference pages", () => {
     expect([...docs.keys()].sort()).toEqual([...PAGES].sort());
   });
 

package/src/kernel/spec/emitReference.ts

@@ -15,7 +15,9 @@
  * NOT imported — this is a kernel-layer emitter).
  */
 
-import { ERROR_CODES } from "../error/constants.js";
+import { BIN_NAME, PROJECT_CONFIG_FILENAME } from "../../constants.js";
+import type { RawConfig } from "../config/types.js";
+import { ERROR_CODES } from "../error/index.js";
 import {
   FIXED_SURFACE,
   kebabCase,
@@ -26,6 +28,7 @@ import type {
   CapabilityModule,
   Example,
   ParamSpec,
+  ReferenceCliSyntax,
   VerbSpec,
 } from "./types.js";
 
@@ -47,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.",
 };
 
@@ -86,12 +89,12 @@ function compareDocVerbs(a: VerbSpec, b: VerbSpec): number {
   return labelA < labelB ? -1 : 1;
 }
 
-/** The full CLI invocation head for a verb (`pragma <noun>` or `pragma <noun> <verb>`). */
+/** The full CLI invocation head for a verb (`<bin> <noun>` or `<bin> <noun> <verb>`). */
 function formatInvocation(verb: VerbSpec): string {
   const sub = verb.path[1];
   return sub === undefined
-    ? `pragma ${verb.path[0]}`
-    : `pragma ${verb.path[0]} ${sub}`;
+    ? `${BIN_NAME} ${verb.path[0]}`
+    : `${BIN_NAME} ${verb.path[0]} ${sub}`;
 }
 
 /** Format a positional param as its usage token (`<name>`/`[name]`, `...` when variadic). */
@@ -163,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 |", "| --- | --- | --- |"];
@@ -187,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")}`;
 }
@@ -211,7 +230,7 @@ function formatExamples(examples: readonly Example[] | undefined): string {
 function formatVerbAttributes(verb: VerbSpec): string {
   const bullets = [
     verb.capability.needsStore
-      ? "- Store: reads the local store (`pragma sources update` builds it)."
+      ? `- Store: reads the local store (\`${BIN_NAME} sources update\` builds it).`
       : "- Store: storeless.",
   ];
   if (verb.capability.mutates) {
@@ -233,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 `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>`.",
+    `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`, `--no-headers`, `--quiet`, and `--detail <summary|standard|detailed>`.",
   ];
   let currentNoun = "";
   for (const verb of verbs) {
@@ -260,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;
@@ -377,12 +442,12 @@ function renderNonToolSurface(modules: readonly CapabilityModule[]): string {
   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).`,
+      `- **Resources**: ${resources.map((r) => `\`${r}\``).join(", ")} — entity reads addressed by URI (listing and autocomplete are storeless over the pack index). The template — its scheme and the \`_meta\` taxonomy keys its entries carry — is frozen protocol identity, served unchanged by every distribution: clients persist resource URIs, so the scheme never follows a fork's name.`,
     );
   }
   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.",
+      "- **Prompts**: the workflow prompt templates the active graph declares are offered natively over `prompts/list` and `prompts/get`, and as the `prompt_list` / `prompt_lookup` content tools. A graph declaring none leaves both views empty.",
     );
   }
   bullets.push(
@@ -399,7 +464,7 @@ function renderToolsPage(
   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.",
+    `Every tool the ${BIN_NAME} MCP server exposes, plus its non-tool surface. Generated from the live capability grammar — do not edit by hand. The server's \`serverInfo\` is a projection, not a constant: it introduces itself on the wire under the distribution's declared name at the package version, so a client should read \`serverInfo\` rather than assume a name.`,
     "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) {
@@ -442,6 +507,140 @@ function renderErrorsPage(): string {
   ]);
 }
 
+/** One documented config field: the type label a user sees, and the prose. */
+interface ConfigFieldDoc {
+  /** The type as a reader needs it, e.g. `string (optional)`. */
+  readonly type: string;
+  /** What the field does, and anything true about it a reader would not guess. */
+  readonly notes: string;
+}
+
+/**
+ * Every field a config layer may declare. Typed as an exhaustive `Record` over
+ * `keyof RawConfig`, so a field added to the type without a row here — or a row
+ * left behind by a field that was removed — is a COMPILE error, exactly as
+ * {@link ERROR_CODE_DESCRIPTIONS} works for the error kernel. Colocated
+ * (single-use) rather than in a module of its own: only `renderConfigPage`
+ * reads it, and a third artifact for two consumers to keep in step is what this
+ * discipline exists to avoid.
+ *
+ * The `type` column is authored prose; the page says so. Its OPTIONALITY is
+ * checked against the zod validator by `kernel/config/schema.test.ts`.
+ */
+const CONFIG_FIELD_DOCS: Record<keyof RawConfig, ConfigFieldDoc> = {
+  name: {
+    type: "string (optional)",
+    notes:
+      "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:
+      "Distribution-only — see below. The toolchain's own story, rendered first by the `colophon` verb and titled with the distribution's name: `{ markdown, summary? }`, both Markdown bodies with no leading H1 (`summary` is the condensed `--format llm` form). Declared content, not code — a fork edits it to tell its own story.",
+  },
+  issuesUrl: {
+    type: "URL string (optional)",
+    notes:
+      "Distribution-only — see below. Where the first-run note asks users to report problems.",
+  },
+  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>` 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)",
+    notes:
+      "Selects the npm dist-tag `upgrade` and `info` check the registry with. It no longer scopes graph reads — no read filters by channel. Defaults to `normal`. Set it with `config set channel <name>`.",
+  },
+  detail: {
+    type: "`summary` | `standard` | `detailed` (optional)",
+    notes:
+      "Default progressive-disclosure level. A closed enum, like `channel`: any other value fails at load with a `CONFIG_ERROR` naming the file and the three levels. Set it with `config set detail <level>`.",
+  },
+  packs: {
+    type: "array (optional)",
+    notes:
+      "Semantic pack sources built by `sources update`. Each entry is a bare npm name or `{ name, source, stories? }`; `stories` are read stories the pack supplies, in the pack grammar.",
+  },
+  stories: {
+    type: "array (optional)",
+    notes:
+      "Read stories not attached to any pack, in the pack grammar. Compiled at dispatch, and they win over the same noun declared under `packs[].stories`.",
+  },
+  prefixes: {
+    type: "record (optional)",
+    notes:
+      "Namespace prefixes the pack is built with — they win every harvest, so this decides which IRI a prefix binds in the store and the index. Every surface uses the compiled-in display/expansion map to compact and expand prefixed names; only the DISTRIBUTION layer seeds it, because it is also read on the storeless fast path, before any config layer exists.",
+  },
+  completion: {
+    type: "object (optional)",
+    notes:
+      "Completion policy read when `setup completions` emits a script: `minChars` and a per-noun `families` opt-out. It is the one field `config show` carries with NO origin at all.",
+  },
+};
+
+/**
+ * The fields `config show` prints with the layer that supplied them, in the
+ * order it prints them. NOT every field: `prefixes` and `completion` reach only
+ * the JSON payload, `stories` reaches only its `origins` key, and the four
+ * distribution-only fields reach neither. The page said the opposite — that
+ * every field but `completion` was reported — which is the claim this whole
+ * reference exists to make true rather than plausible.
+ *
+ * A literal, because the kernel emitter may not import a capability renderer.
+ * `capabilities/config/show.render.test.ts` derives the same list from the real
+ * formatter and fails if this page and that renderer disagree.
+ */
+const REPORTED_FIELDS = ["tier", "channel", "detail", "packs"];
+
+/** Render the layered-configuration reference: the layers, then the fields. */
+function renderConfigPage(): string {
+  const rows = ["| Field | Type | Notes |", "| --- | --- | --- |"];
+  for (const [field, doc] of Object.entries(CONFIG_FIELD_DOCS)) {
+    rows.push(
+      `| \`${field}\` | ${escapeCell(doc.type)} | ${escapeCell(doc.notes)} |`,
+    );
+  }
+  return assemblePage([
+    "# Configuration reference",
+    `Every field a \`${BIN_NAME}\` config layer may declare. Generated from the config type — do not edit by hand. See [config-model.md](../config-model.md) for the authoring guide.`,
+    "## Layers",
+    "From lowest to highest precedence:",
+    [
+      `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 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\`, \`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 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 (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",
+    `\`${BIN_NAME} config show\` prints the resolved config and each field's layer. \`${BIN_NAME} config set <key> <value>\` writes to the **global** layer only — project configs are authored by hand. Both are documented in the [command reference](./commands.md).`,
+  ]);
+}
+
 /** Render the reference index: overview, derived counts, and links. */
 function renderIndexPage(
   verbs: readonly VerbSpec[],
@@ -450,8 +649,8 @@ function renderIndexPage(
   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.",
+    `# ${BIN_NAME} reference`,
+    `Machine-generated reference for the \`${BIN_NAME}\` 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`,
@@ -461,9 +660,10 @@ function renderIndexPage(
     ].join("\n"),
     "## Pages",
     [
-      "- [CLI command reference](./commands.md) — every `pragma <noun> <verb>`, its arguments, flags, and examples.",
+      `- [CLI command reference](./commands.md) — every \`${BIN_NAME} <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.",
+      "- [Configuration reference](./config.md) — every config field, the three layers, and how they combine.",
     ].join("\n"),
   ]);
 }
@@ -484,8 +684,16 @@ 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()],
   ]);
 }