@canonical/pragma-cli 0.31.0 → 0.33.0

package/src/capabilities/colophon/colophon.render.ts

@@ -0,0 +1,47 @@
+/**
+ * Formatters for `pragma colophon` — plain (styled Markdown), llm (condensed
+ * Markdown passthrough), json (the structured envelope). Pure and dependency-
+ * light: the plain path routes through the `chalk`-only {@link
+ * renderMarkdownToTerminal}; there is NO Ink here.
+ *
+ * The section title is composed as an H1 (`# <title>`) and fed through the ONE
+ * styler, so all heading styling lives in a single place and the authored body
+ * (which carries no leading H1) is never double-titled.
+ */
+
+import { defaultStyle, type RenderStyle } from "../../kernel/render/style.js";
+import type { Formatters } from "../../kernel/spec/types.js";
+import { renderMarkdownToTerminal } from "./markdownTerminal.js";
+import type { ColophonData, ColophonSection } from "./types.js";
+
+/** Render one section (title as H1 + body) as styled terminal Markdown. */
+function plainSection(section: ColophonSection, style: RenderStyle): string {
+  return renderMarkdownToTerminal(
+    `# ${section.title}\n\n${section.markdown}`,
+    style,
+  );
+}
+
+/** Render one section as condensed Markdown for `--format llm` (summary preferred). */
+function llmSection(section: ColophonSection): string {
+  return `## ${section.title}\n\n${section.summary ?? section.markdown}`;
+}
+
+export const colophonFormatters: Formatters<ColophonData> = {
+  plain(data) {
+    // Resolve the TTY decision ONCE (impure: reads stdout.isTTY + chalk level),
+    // then render every section through the same inert-off-a-TTY styler.
+    const style = defaultStyle();
+    return data.sections
+      .map((section) => plainSection(section, style))
+      .join("\n\n");
+  },
+
+  llm(data) {
+    return data.sections.map(llmSection).join("\n\n");
+  },
+
+  json(data) {
+    return JSON.stringify(data);
+  },
+};

package/src/capabilities/colophon/colophon.test.ts

@@ -0,0 +1,241 @@
+/**
+ * `pragma colophon` — the storeless, pack-extensible toolchain colophon (PR10).
+ *
+ * Pins the covenant-exact emitted slice (`{ v:"colophon", mcp:"colophon" }`),
+ * proves the collector is storeless and combines pragma's built-in section with
+ * the active pack's (the bundled `block` design-system colophon), exercises the
+ * three formatter modes + `--format` precedence, holds CLI-json ≡ MCP
+ * parity, and checks the pack-grammar accepts a `colophon` field (rejecting a
+ * non-string).
+ */
+
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { PragmaError } from "../../kernel/error/PragmaError.js";
+import { parsePackDefinition } from "../../kernel/packs/schema.js";
+import { executeVerb } from "../../kernel/project/cli/dispatch.js";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import { emitSurface, emitVerb } from "../../kernel/spec/emitSurface.js";
+import {
+  assertConforms,
+  type Covenant,
+} from "../../kernel/spec/surfaceConformance.js";
+import type { GlobalFlags, VerbSpec } from "../../kernel/spec/types.js";
+import { projectMcp } from "../../testing/helpers/projectMcp.js";
+import { collectColophon } from "./collectColophon.js";
+import { colophonFormatters } from "./colophon.render.js";
+import { colophonModule } from "./index.js";
+import type { ColophonData } from "./types.js";
+
+/** The committed covenant, read from disk exactly as a consumer would. */
+const golden = JSON.parse(
+  readFileSync(
+    fileURLToPath(new URL("../../../surface/surface.v2.json", import.meta.url)),
+    "utf-8",
+  ),
+) as Covenant;
+
+const colophonVerb = colophonModule.verbs[0] as VerbSpec;
+
+const FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "plain",
+  verbose: false,
+};
+const FLAGS_JSON: GlobalFlags = { ...FLAGS, format: "json" };
+const FLAGS_LLM: GlobalFlags = { ...FLAGS, format: "llm", llm: true };
+const NO_MUT = { dryRun: false, undo: false, yes: false };
+
+/** A deterministic two-section fixture for pure formatter assertions. */
+const FIXTURE: ColophonData = {
+  sections: [
+    {
+      kind: "pragma",
+      title: "pragma",
+      markdown: "Intro **bold** line.\n\n## Section\n- one\n- two",
+      summary: "condensed pragma story",
+      source: "built-in",
+    },
+    {
+      kind: "pack",
+      title: "block",
+      markdown: "The domain body, no summary.",
+      source: "pack:block",
+    },
+  ],
+};
+
+const roots: string[] = [];
+let prevXdg: string | undefined;
+const tmpCwd = (): string => {
+  const dir = mkdtempSync(join(tmpdir(), "pragma-colophon-"));
+  roots.push(dir);
+  return dir;
+};
+
+beforeEach(() => {
+  // Isolate the global config layer so the collector reads defaults (no stories)
+  // and the run is hermetic.
+  prevXdg = process.env.XDG_CONFIG_HOME;
+  process.env.XDG_CONFIG_HOME = tmpCwd();
+});
+afterEach(() => {
+  process.env.XDG_CONFIG_HOME = prevXdg;
+  for (const dir of roots) rmSync(dir, { recursive: true, force: true });
+  roots.length = 0;
+});
+
+describe("colophon — covenant-exact emission (PROTECTED)", () => {
+  it("emits the self-verb slice { v: colophon, mcp: colophon }", () => {
+    expect(emitVerb(colophonVerb)).toEqual({ v: "colophon", mcp: "colophon" });
+  });
+
+  it("the emitted colophon slice conforms to the frozen covenant", () => {
+    expect(() =>
+      assertConforms(emitSurface([colophonModule]), golden),
+    ).not.toThrow();
+  });
+});
+
+describe("colophon — storeless collector (PROTECTED)", () => {
+  it("collectColophon never boots the store", async () => {
+    const rt = bootRuntime(FLAGS, tmpCwd());
+    await collectColophon(rt);
+    expect(rt.store.booted).toBe(false);
+  });
+
+  it("the verb runs without booting the store", async () => {
+    const rt = bootRuntime(FLAGS, tmpCwd());
+    const outcome = await executeVerb(colophonVerb, {}, NO_MUT, rt);
+    expect(outcome.exitCode).toBe(0);
+    expect(rt.store.booted).toBe(false);
+  });
+});
+
+describe("colophon — combined content (pragma + active domain)", () => {
+  it("leads with pragma's built-in section", async () => {
+    const data = await collectColophon(bootRuntime(FLAGS, tmpCwd()));
+    const first = data.sections[0];
+    expect(first?.kind).toBe("pragma");
+    expect(first?.title).toBe("pragma");
+    expect(first?.source).toBe("built-in");
+    expect(first?.markdown.length).toBeGreaterThan(0);
+    expect(first?.summary?.length).toBeGreaterThan(0);
+  });
+
+  it("appends the bundled design-system (block) domain section", async () => {
+    const data = await collectColophon(bootRuntime(FLAGS, tmpCwd()));
+    const block = data.sections.find((section) => section.title === "block");
+    expect(block?.kind).toBe("pack");
+    expect(block?.source).toBe("pack:block");
+    expect(block?.markdown).toContain("knowledge graph");
+  });
+});
+
+describe("colophon — formatter modes", () => {
+  it("plain styles headings/bullets and titles every section", () => {
+    const out = colophonFormatters.plain(FIXTURE);
+    expect(out).toContain("pragma");
+    expect(out).toContain("block");
+    expect(out).toContain("•"); // the `-` bullet transform
+    expect(out).not.toContain("**bold**"); // inline markers are consumed
+  });
+
+  it("llm prefers the summary, else the markdown body", () => {
+    const out = colophonFormatters.llm(FIXTURE);
+    expect(out).toContain("## pragma");
+    expect(out).toContain("condensed pragma story"); // summary used
+    expect(out).not.toContain("Intro **bold** line"); // full body NOT used
+    expect(out).toContain("## block");
+    expect(out).toContain("The domain body, no summary."); // markdown used
+  });
+
+  it("json round-trips the ColophonData", () => {
+    expect(JSON.parse(colophonFormatters.json(FIXTURE))).toEqual(FIXTURE);
+  });
+
+  it("--format json wins: executeVerb returns the {ok,data} envelope", async () => {
+    const outcome = await executeVerb(
+      colophonVerb,
+      {},
+      NO_MUT,
+      bootRuntime(FLAGS_JSON, tmpCwd()),
+    );
+    const envelope = JSON.parse(outcome.stdout as string);
+    expect(envelope.ok).toBe(true);
+    expect((envelope.data as ColophonData).sections[0]?.kind).toBe("pragma");
+  });
+
+  it("--format llm selects the condensed Markdown form", async () => {
+    const outcome = await executeVerb(
+      colophonVerb,
+      {},
+      NO_MUT,
+      bootRuntime(FLAGS_LLM, tmpCwd()),
+    );
+    expect(outcome.stdout).toContain("## pragma");
+  });
+});
+
+describe("colophon — MCP parity", () => {
+  it("projects a read-only `colophon` tool that returns the pragma section", async () => {
+    const cwd = tmpCwd();
+    const mcp = await projectMcp([colophonModule], cwd);
+    const tool = (await mcp.listTools()).find((t) => t.name === "colophon");
+    const envelope = await mcp.callTool("colophon");
+    await mcp.cleanup();
+
+    expect(tool).toBeDefined();
+    expect(tool?.annotations).toMatchObject({
+      readOnlyHint: true,
+      openWorldHint: false,
+    });
+    expect(envelope.ok).toBe(true);
+    expect((envelope.data as ColophonData).sections[0]?.kind).toBe("pragma");
+  });
+
+  it("CLI --format json ≡ MCP colophon (same envelope)", async () => {
+    const cwd = tmpCwd();
+    const cli = await executeVerb(
+      colophonVerb,
+      {},
+      NO_MUT,
+      bootRuntime(FLAGS_JSON, cwd),
+    );
+    const cliEnvelope = JSON.parse(cli.stdout as string);
+
+    const mcp = await projectMcp([colophonModule], cwd);
+    const mcpEnvelope = await mcp.callTool("colophon");
+    await mcp.cleanup();
+
+    expect(cliEnvelope).toEqual(mcpEnvelope);
+    expect(cliEnvelope.ok).toBe(true);
+  });
+});
+
+describe("colophon — pack-grammar `colophon` field", () => {
+  it("parsePackDefinition accepts a string colophon", () => {
+    const def = parsePackDefinition(
+      {
+        noun: "demo",
+        lookup: { by: "ds:name" },
+        colophon: "How the demo domain is made.",
+      },
+      "config",
+    );
+    expect(def.colophon).toBe("How the demo domain is made.");
+  });
+
+  it("rejects a non-string colophon (the schema is strict)", () => {
+    expect(() =>
+      parsePackDefinition(
+        { noun: "demo", lookup: { by: "ds:name" }, colophon: 123 },
+        "config",
+      ),
+    ).toThrow(PragmaError);
+  });
+});

package/src/capabilities/colophon/colophon.verb.ts

@@ -0,0 +1,44 @@
+/**
+ * The `colophon` verb spec (noun `colophon`, self-verb).
+ *
+ * `run` is a lazy thunk: it dynamic-imports the collector, so building the
+ * command tree (help, completion, surface emit) reads this spec without pulling
+ * the config reader or the registry onto the fast path — identical to
+ * `infoVerb` / `doctorVerb` / `capabilitiesVerb`.
+ */
+
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import type { CapabilityModule, VerbSpec } from "../../kernel/spec/types.js";
+import { colophonFormatters } from "./colophon.render.js";
+import type { ColophonData } from "./types.js";
+
+const colophonVerb: VerbSpec<Record<string, unknown>, ColophonData> = {
+  path: ["colophon"],
+  summary: "Narrate how pragma and the active domain are made.",
+  doc: "Storeless — a colophon for the toolchain. Prints pragma's own story (the effect monad, one-grammar-many-projections, the render/LLM-output model, storeless modularity, and the domain-as-data pack model) followed by the active pack's domain colophon. Also available as a condensed Markdown narration for agents, or as a structured JSON projection of the sections.",
+  params: [],
+  output: { formatters: colophonFormatters },
+  examples: [
+    { cmd: "pragma colophon", note: "the toolchain + active domain story" },
+    {
+      cmd: "pragma colophon --format llm",
+      note: "condensed Markdown for agents",
+    },
+  ],
+  capability: {
+    needsStore: false,
+    mutates: false,
+    mcp: {
+      expose: true,
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+  },
+  run: (_params, runtime) =>
+    import("./collectColophon.js").then((m) => m.collectColophon(runtime)),
+};
+
+/** The `colophon` capability module (a single storeless self-verb). */
+export const colophonModule: CapabilityModule = {
+  name: "colophon",
+  verbs: [asVerb(colophonVerb)],
+};

package/src/capabilities/colophon/index.ts

@@ -0,0 +1,6 @@
+/**
+ * The `colophon` capability barrel.
+ */
+
+export { colophonModule } from "./colophon.verb.js";
+export type { ColophonData, ColophonSection } from "./types.js";

package/src/capabilities/colophon/markdownTerminal.test.ts

@@ -0,0 +1,50 @@
+/**
+ * `markdownTerminal` — the tiny Markdown→terminal styler for `pragma colophon`.
+ *
+ * Forces `chalk.level = 0` for deterministic, color-free assertions. Focuses on
+ * the control-char scrub (F4): the colophon body is domain-as-data (pack
+ * authored), so a hostile/careless pack must not smuggle raw ANSI escapes or C0
+ * control bytes to the terminal through it — every line is scrubbed BEFORE our
+ * own chalk styling. Also pins that clean Markdown still styles as before.
+ */
+
+import chalk from "chalk";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { renderMarkdownToTerminal } from "./markdownTerminal.js";
+
+let prevLevel: number;
+beforeAll(() => {
+  prevLevel = chalk.level;
+  chalk.level = 0;
+});
+afterAll(() => {
+  chalk.level = prevLevel;
+});
+
+describe("markdownTerminal — strips pack-authored control codes (F4)", () => {
+  it("removes ANSI escapes and stray C0/DEL controls before styling", () => {
+    // One hostile line: SGR colour codes, a NUL, a BEL, a CSI screen-clear, and
+    // a lone ESC — all wrapped around real text.
+    const hostile = "safe\x1b[31mRED\x1b[0m\x00\x07 text\x1b[2J\x1bmore";
+    const out = renderMarkdownToTerminal(hostile);
+    // The control codes are gone; the visible text survives verbatim.
+    expect(out).toBe("safeRED textmore");
+    // Belt and braces: not a single C0/DEL control byte remains.
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: asserting the scrub removed control bytes
+    expect(out).not.toMatch(/[\x00-\x08\x0b-\x1f\x7f]/);
+  });
+
+  it("scrubs control codes hidden inside a fenced code block too", () => {
+    const out = renderMarkdownToTerminal("```\nrm -rf /\x1b[2K\x07\n```");
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: asserting the scrub removed control bytes
+    expect(out).not.toMatch(/[\x00-\x08\x0b-\x1f\x7f]/);
+    expect(out).toContain("rm -rf /");
+  });
+
+  it("preserves the structural styling for clean Markdown", () => {
+    // Heading + bullet + inline markers still render exactly as before the scrub.
+    expect(renderMarkdownToTerminal("# Title\n- an **item** with `code`")).toBe(
+      ["Title", "  • an item with code"].join("\n"),
+    );
+  });
+});

package/src/capabilities/colophon/markdownTerminal.ts

@@ -0,0 +1,104 @@
+/**
+ * A tiny, self-contained Markdown→terminal styler — `chalk` only, no parser, no
+ * new dependency. It covers exactly the constructs the colophon Markdown uses:
+ * ATX headings, `-`/`*` bullets, fenced ```code``` blocks, and inline
+ * `**bold**` / `` `code` `` spans. Deliberately minimal: no wrapping, no tables,
+ * no nested lists.
+ *
+ * Single consumer today (`pragma colophon`); a promotion candidate to
+ * `kernel/render/` if another verb ever wants the same helper. Determinism note:
+ * styling routes through the shared {@link RenderStyle} seam (color only on a
+ * color-capable TTY), so piped / redirected / CI output — where `supports-color`
+ * can report a level with no TTY — stays byte-for-byte the color-free structural
+ * transform, and a test can force either mode by passing an explicit style.
+ */
+
+import chalk from "chalk";
+import { defaultStyle, type RenderStyle } from "../../kernel/render/style.js";
+
+/** Full ANSI escape sequences (`ESC [ … final-letter`) — colour/cursor codes. */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: deliberate control-char scrub
+const ANSI_ESCAPE = /\x1b\[[0-9;]*[A-Za-z]/g;
+/** Stray C0 control chars + DEL, keeping tab (`\x09`) and newline (`\x0a`). */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: deliberate control-char scrub
+const C0_CONTROLS = /[\x00-\x08\x0b-\x1f\x7f]/g;
+
+/**
+ * Strip ANSI escape sequences and stray C0/DEL control characters from a line.
+ *
+ * The colophon body carries pack-authored domain text (the "domain-as-data"
+ * model), so a hostile or careless pack could otherwise smuggle raw terminal
+ * control codes — cursor moves, colour resets, screen clears — straight to the
+ * terminal. We apply our OWN styling via `chalk` afterwards, so any control char
+ * in the source is unwanted; scrub each line before styling.
+ */
+function stripControl(line: string): string {
+  return line.replace(ANSI_ESCAPE, "").replace(C0_CONTROLS, "");
+}
+
+/**
+ * Style inline `**bold**` and `` `code` `` spans within one line. The `**` / `` ` ``
+ * markers are ALWAYS consumed; off a TTY the styler is inert, so the markers drop
+ * with no color (byte-identical to the pre-seam `chalk.level = 0` behavior).
+ */
+function styleInline(text: string, style: RenderStyle): string {
+  return text
+    .replace(/\*\*([^*]+)\*\*/g, (_match, inner: string) => style.bold(inner))
+    .replace(/`([^`]+)`/g, (_match, inner: string) => style.cyan(inner));
+}
+
+/**
+ * Render a Markdown string to styled terminal text.
+ *
+ * @param markdown - The authored Markdown body.
+ * @param style - The TTY styler; defaults to the process style. On a color-capable
+ *   terminal headings/bullets/inline spans are tinted; off a TTY the styler is
+ *   inert, so the output is byte-identical to the color-free structural form.
+ * @returns The styled terminal string (no trailing newline).
+ */
+export function renderMarkdownToTerminal(
+  markdown: string,
+  style: RenderStyle = defaultStyle(),
+): string {
+  const lines: string[] = [];
+  let inFence = false;
+
+  for (const rawLine of markdown.split("\n")) {
+    // Scrub pack-authored terminal control codes BEFORE our own styling
+    // (colophon bodies are domain-as-data — never a channel for raw ANSI).
+    const raw = stripControl(rawLine);
+    // A fence toggles code mode; the ``` markers themselves are dropped.
+    if (raw.trimStart().startsWith("```")) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) {
+      lines.push(style.dim(`  ${raw}`));
+      continue;
+    }
+
+    const heading = /^(#{1,6})\s+(.+)$/.exec(raw);
+    if (heading) {
+      const level = heading[1]?.length ?? 1;
+      const text = styleInline(heading[2] ?? "", style);
+      // H1 earns bold+underline on a TTY; underline is outside the RenderStyle
+      // seam, so reach for chalk only when the styler is enabled.
+      lines.push(
+        level === 1 && style.enabled
+          ? chalk.bold.underline(text)
+          : style.bold(text),
+      );
+      continue;
+    }
+
+    const bullet = /^\s*[-*]\s+(.+)$/.exec(raw);
+    if (bullet) {
+      lines.push(`  ${style.cyan("•")} ${styleInline(bullet[1] ?? "", style)}`);
+      continue;
+    }
+
+    lines.push(styleInline(raw, style));
+  }
+
+  return lines.join("\n");
+}

package/src/capabilities/colophon/pragmaColophon.ts

@@ -0,0 +1,66 @@
+/**
+ * The built-in pragma colophon — how the toolchain itself is made. Authored
+ * Markdown grounded in this tree's real architecture; surfaced by `pragma
+ * colophon` as the first section, before any active pack's domain colophon.
+ *
+ * `PRAGMA_COLOPHON` is the full narrative for humans; `PRAGMA_COLOPHON_SUMMARY`
+ * is the condensed form `--format llm` emits (Markdown IS the agent-optimal shape).
+ * Both are BODIES with no leading H1 — the renderer supplies the "pragma"
+ * heading, so the section is never double-titled.
+ */
+
+/** The full built-in colophon (Markdown body). */
+export const PRAGMA_COLOPHON = `pragma is a **domain-based toolchain**: one CLI and one MCP server projected
+from a single grammar, serving a knowledge-graph domain that reads as data.
+
+## The effect monad
+
+Reads are plain \`async\` functions; a mutation instead *describes* its effects
+as a \`Task\` (\`@canonical/task\`) that is interpreted — under the real node
+interpreter, a \`--dry-run\` planner, or an \`--undo\` reverser. Describe-then-
+interpret means dry-run and undo come for free, and the dispatcher tells the two
+worlds apart on one bit: \`capability.mutates\`.
+
+## One grammar, many projections
+
+Every capability is a \`VerbSpec\` — a noun, its params, its effect profile, its
+formatters. The CLI commands, the MCP tools, shell completion, and the
+surface/docs are all *projections* of that one shape, so they cannot drift. The
+projected surface is frozen in a covenant (\`surface/surface.v2.json\`): a single
+source of truth a test asserts the live grammar still emits, tool for tool.
+
+## LLM-optimized output
+
+Each verb renders three ways — \`plain\` for a terminal, \`json\` for the machine
+envelope, and \`llm\` for condensed Markdown. \`--format llm\` (or a non-interactive
+stdout) selects the agent form: the same data, shaped for a model to read. This
+colophon is itself a showcase of that render model.
+
+## Modular, storeless by construction
+
+Capabilities ship as **modules** — named bundles of verbs with optional
+boot / resource / prompt hooks. A verb declares whether it \`needsStore\`, and
+the dispatcher boots the triple store *only* for those; a storeless verb
+(\`info\`, \`config\`, \`capabilities\`, \`colophon\`) never pays for the graph.
+
+## Scaffolding
+
+\`pragma create\` scaffolds components, packages, and applications through the
+\`@canonical/summon-*\` generators, reusing summon's rich Ink wizard when it runs
+interactively.
+
+## The domain reads as data
+
+A domain is a **pack**: a declarative \`PackDefinition\` (its list / lookup
+queries) compiled into verbs, backed by a content-addressed graphpack that
+\`sources update\` builds once. Swap the pack and the same pragma serves a
+different domain — including the domain colophon printed below this one.`;
+
+/** The condensed colophon for `--format llm` (Markdown body, no leading H1). */
+export const PRAGMA_COLOPHON_SUMMARY = `pragma is a domain-based toolchain: one CLI + MCP server projected from a single \`VerbSpec\` grammar.
+
+- **Effect monad** (\`@canonical/task\`): reads are async; a mutation returns an interpreted \`Task\`, so \`--dry-run\` and \`--undo\` are free. The dispatcher branches on \`capability.mutates\`.
+- **One grammar, many projections**: CLI, MCP tools, completion, and docs all project one \`VerbSpec\`; the emitted surface is frozen in a covenant so the projections never drift.
+- **LLM-optimized output**: every verb renders \`plain\` / \`json\` / \`llm\`; \`--format llm\` (or a piped stdout) emits condensed Markdown for agents.
+- **Modular + storeless**: capability modules; the triple store boots only for \`needsStore\` verbs.
+- **Domain as data**: a pack is a declarative \`PackDefinition\` compiled to verbs over a content-addressed graph built by \`sources update\`.`;

package/src/capabilities/colophon/types.ts

@@ -0,0 +1,29 @@
+/**
+ * Data shapes for `pragma colophon`.
+ *
+ * A colophon (the printer's end-note on how a book is made) for the toolchain:
+ * one section narrating how pragma itself is built, followed by one section per
+ * active pack/domain that declares a `colophon`. Storeless and read-only.
+ */
+
+/** One colophon section — pragma's own, or an active pack's domain story. */
+export interface ColophonSection {
+  /** Whether this is pragma's built-in section or an active pack's. */
+  readonly kind: "pragma" | "pack";
+  /** Section heading — `"pragma"`, or the pack's noun/name. */
+  readonly title: string;
+  /**
+   * The authored Markdown BODY (no leading H1 — the renderer supplies the
+   * heading from {@link title}, so a section is never double-titled).
+   */
+  readonly markdown: string;
+  /** Optional condensed body for `--format llm` (pragma supplies one). */
+  readonly summary?: string;
+  /** Provenance: `"built-in"`, or `"pack:<name>"`. */
+  readonly source?: string;
+}
+
+/** The full `colophon` payload: pragma's section first, then active packs'. */
+export interface ColophonData {
+  readonly sections: readonly ColophonSection[];
+}

package/src/capabilities/config/collectConfigShow.ts

@@ -0,0 +1,32 @@
+/**
+ * Collect the `config show` payload — the verb's run body (lazily imported).
+ *
+ * Storeless: read the layered config and pass it through with its provenance.
+ * Dynamic-imported by the spec so building the tree never pulls the config
+ * reader (or zod) onto the fast path.
+ */
+
+import { readConfig } from "../../kernel/config/readConfig.js";
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import type { ConfigShowData } from "./types.js";
+
+/**
+ * Assemble the resolved config with provenance for the current runtime.
+ *
+ * @param runtime - The per-invocation runtime.
+ * @returns The config-show payload.
+ * @note Impure — reads the config layers from disk.
+ */
+export async function collectConfigShow(
+  runtime: PragmaRuntime,
+): Promise<ConfigShowData> {
+  const layers = await readConfig(runtime.cwd);
+  return {
+    config: layers.config,
+    origins: layers.origins,
+    ...(layers.project.path ? { projectConfigPath: layers.project.path } : {}),
+    globalConfigPath: layers.global.path,
+    projectExists: layers.project.exists,
+    globalExists: layers.global.exists,
+  };
+}

package/src/capabilities/config/field.render.ts

@@ -0,0 +1,28 @@
+/**
+ * Formatters for a `config <field>` setter — plain, llm, json (no ink).
+ *
+ * One shared formatter across all three setters (the field-table pattern): a
+ * set reports the value and the file it landed in; a reset reports the removed
+ * field.
+ */
+
+import type { Formatters } from "../../kernel/spec/types.js";
+import type { ConfigFieldResult } from "./types.js";
+
+export const configFieldFormatters: Formatters<ConfigFieldResult> = {
+  plain(data) {
+    return data.reset
+      ? `Reset ${data.field} (removed from ${data.path})`
+      : `Set ${data.field} = ${data.value} (written to ${data.path})`;
+  },
+
+  llm(data) {
+    return data.reset
+      ? `Reset \`${data.field}\` — removed from the global config.`
+      : `Set \`${data.field}\` = \`${data.value}\` in the global config.`;
+  },
+
+  json(data) {
+    return JSON.stringify(data);
+  },
+};