@canonical/pragma-cli 0.32.0 → 0.33.0

package/README.md

@@ -0,0 +1,72 @@
+# @canonical/pragma-cli
+
+`pragma` is a command-line tool **and** a Model Context Protocol (MCP) server over Canonical's design-system knowledge graph. A single grammar of capabilities is projected two ways — as CLI commands for humans and as MCP tools for agents — both reading the same local, content-addressed store built from your design-system packages.
+
+## Install
+
+```bash
+npm install -g @canonical/pragma-cli
+```
+
+This installs the `pragma` binary: a prebuilt, standalone executable (`dist/pragma`). The package publishes for **Linux x64 only** (`"os": ["linux"]`, `"cpu": ["x64"]`) — other platforms are not yet shipped.
+
+Check your environment and confirm the install:
+
+```bash
+pragma doctor
+```
+
+## Quickstart
+
+```bash
+pragma sources update
+pragma sources status
+pragma block list
+pragma block lookup Button
+pragma capabilities
+```
+
+`pragma sources update` resolves the design-system packages named in your `pragma.config.ts`, builds one local store, and writes `pragma.lock.json`. Once built, every read command answers from the store with no network access.
+
+To register pragma with a detected AI harness as an MCP server:
+
+```bash
+pragma setup mcp
+```
+
+See [docs/mcp-integration.md](./docs/mcp-integration.md) for the full MCP surface, and the [command & tool reference](./docs/reference/index.md) for every command and tool.
+
+## Two planes
+
+pragma is extended along two independent planes:
+
+- **Data plane — the content.** Your design system is a set of semantic packages listed in `pragma.config.ts` (`packages: [...]`). `pragma sources update` compiles them into the local knowledge graph the read commands query. Point pragma at different packages and every `list` / `lookup` / `sample` command answers from that graph.
+- **Behaviour plane — the capabilities.** Every command and MCP tool is one entry in a single capability grammar, projected to both the CLI and the MCP server. The [reference](./docs/reference/index.md) is generated from that grammar, so it can never drift from the code.
+
+## Relationship to summon
+
+`@canonical/summon` is a separate scaffolding product. pragma reuses summon's generator core so that its scaffolding commands —
+
+```bash
+pragma create component src/components/Button --framework react
+```
+
+— produce output byte-identical to summon's own `component`, `package`, and `application` generators. summon is not a runtime dependency: the generators are embedded in the `pragma` binary, so `pragma create component` runs from a clean install.
+
+## MCP
+
+Run pragma as an MCP server over stdio via `pragma setup mcp` (automatic harness registration) or the manual `pragma mcp` entry point. The server exposes the read and scaffold tools, a `pragma:{+uri}` resource surface for entity reads, the design system's workflow prompts, and handshake instructions describing the discovery sequence. Mutating tools are plan-first — they return the plan they would apply until called with `confirm: true`. See [docs/mcp-integration.md](./docs/mcp-integration.md).
+
+## Documentation
+
+- [Getting started](./docs/getting-started.md)
+- [MCP integration](./docs/mcp-integration.md)
+- [Configuration model](./docs/config-model.md)
+- [Architecture](./docs/architecture.md)
+- [Skills](./docs/skills.md)
+- [Command & tool reference](./docs/reference/index.md)
+- [Changelog](./CHANGELOG.md)
+
+## License
+
+GPL-3.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@canonical/pragma-cli",
   "description": "Next-generation CLI and MCP kernel for Canonical's design system (pragma v2).",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "type": "module",
   "module": "src/index.ts",
   "types": "src/index.ts",
@@ -36,6 +36,7 @@
   },
   "scripts": {
     "build": "bun run scripts/build.ts",
+    "gen:reference": "bun run scripts/genReference.ts",
     "build:compile": "bun build --compile --minify --target=bun-linux-x64 src/bin.ts --outfile dist/pragma",
     "check": "bun run check:biome && bun run check:ts && bun run check:webarchitect",
     "check:webarchitect": "webarchitect tool-ts",
@@ -51,14 +52,14 @@
     "eval": "bun run src/testing/eval/report.ts"
   },
   "dependencies": {
-    "@canonical/harnesses": "^0.32.0",
-    "@canonical/ke": "^0.32.0",
-    "@canonical/ke-graphql": "^0.32.0",
-    "@canonical/summon-application": "^0.32.0",
-    "@canonical/summon-component": "^0.32.0",
-    "@canonical/summon-core": "^0.32.0",
-    "@canonical/summon-package": "^0.32.0",
-    "@canonical/task": "^0.32.0",
+    "@canonical/harnesses": "^0.33.0",
+    "@canonical/ke": "^0.33.0",
+    "@canonical/ke-graphql": "^0.33.0",
+    "@canonical/summon-application": "^0.33.0",
+    "@canonical/summon-component": "^0.33.0",
+    "@canonical/summon-core": "^0.33.0",
+    "@canonical/summon-package": "^0.33.0",
+    "@canonical/task": "^0.33.0",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
@@ -68,14 +69,14 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.9",
-    "@canonical/biome-config": "^0.32.0",
-    "@canonical/typescript-config": "^0.32.0",
-    "@canonical/webarchitect": "^0.32.0",
+    "@canonical/biome-config": "^0.33.0",
+    "@canonical/typescript-config": "^0.33.0",
+    "@canonical/webarchitect": "^0.33.0",
     "@types/bun": "^1.3.10",
     "@types/node": "^24.12.0",
     "@vitest/coverage-v8": "^4.0.18",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
-  "gitHead": "5b279d8150e3988c68c6c2a741046bcd425624ca"
+  "gitHead": "fca2bc4440fff2d511fc8db6686f9b19222fdbc7"
 }

package/src/bin.ts

@@ -77,7 +77,7 @@ async function main(): Promise<void> {
   if (
     !explicitHelp &&
     rawFormat !== undefined &&
-    !["plain", "json", "text"].includes(rawFormat)
+    !["plain", "llm", "json", "text"].includes(rawFormat)
   ) {
     const [
       { PragmaError },
@@ -89,7 +89,7 @@ async function main(): Promise<void> {
       import("./kernel/project/cli/exitCodes.js"),
     ]);
     const error = PragmaError.invalidInput("format", rawFormat, {
-      validOptions: ["plain", "json"],
+      validOptions: ["plain", "llm", "json"],
     });
     const rendered =
       globalFlags.format === "json"

package/src/capabilities/block/blockList.test.ts

@@ -0,0 +1,79 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { verbKey } from "../../kernel/packs/uniqueness.js";
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import { OWL_EXPORT_TTL } from "../../testing/fixtures/graph/owlExport.js";
+import { bootFixtureRuntime } from "../../testing/helpers/fixtureGraph.js";
+import type { BlockRow } from "./blockList.verb.js";
+import { blockModule } from "./index.js";
+
+const listVerb = blockModule.verbs.find(
+  (verb) => verbKey(verb.path) === "block list",
+) as VerbSpec;
+
+const names = (rows: BlockRow[]): string[] =>
+  rows.map((row) => row.name).sort();
+
+/**
+ * The OWL-export fixture ships an UNTIERED `ds:Component` (`ds:datePicker`, no
+ * `ds:tier`) beside a tiered one (`ds:button`). The pre-fix `block list` gated
+ * on a REQUIRED `ds:tier` triple pattern, so `--all-tiers` — which drops the
+ * FILTER but not the pattern — still hid the untiered block, contradicting the
+ * flag's promise to show every block (A2). A tier-scoped view legitimately
+ * omits an untiered block (it joins the list through its tier); `--all-tiers`
+ * is the escape that reveals it.
+ */
+describe("block list — untiered blocks under --all-tiers (A2)", () => {
+  describe("no tier configured", () => {
+    let runtime: PragmaRuntime;
+    let dispose: () => Promise<void>;
+
+    beforeAll(async () => {
+      const fixture = await bootFixtureRuntime({ ttl: OWL_EXPORT_TTL });
+      runtime = fixture.runtime;
+      dispose = fixture.dispose;
+    });
+    afterAll(() => dispose());
+
+    it("the default view still omits the untiered block", async () => {
+      const rows = (await listVerb.run({}, runtime)) as BlockRow[];
+      expect(names(rows)).toEqual(["Button"]);
+    });
+
+    it("--all-tiers reveals the untiered block", async () => {
+      const rows = (await listVerb.run(
+        { allTiers: true },
+        runtime,
+      )) as BlockRow[];
+      expect(names(rows)).toEqual(["Button", "Date Picker"]);
+    });
+  });
+
+  describe("a tier IS configured", () => {
+    let runtime: PragmaRuntime;
+    let dispose: () => Promise<void>;
+
+    beforeAll(async () => {
+      const fixture = await bootFixtureRuntime({
+        ttl: OWL_EXPORT_TTL,
+        config: { tier: "global", channel: "normal" },
+      });
+      runtime = fixture.runtime;
+      dispose = fixture.dispose;
+    });
+    afterAll(() => dispose());
+
+    it("a scoped tier lists its tiered block, not the untiered one", async () => {
+      const rows = (await listVerb.run({}, runtime)) as BlockRow[];
+      expect(names(rows)).toEqual(["Button"]);
+    });
+
+    it("--all-tiers overrides the scope and reveals the untiered block", async () => {
+      const rows = (await listVerb.run(
+        { allTiers: true },
+        runtime,
+      )) as BlockRow[];
+      expect(names(rows)).toContain("Date Picker");
+    });
+  });
+});

package/src/capabilities/block/blockList.verb.ts

@@ -84,14 +84,25 @@ function buildQuery(
 ): string {
   const tierFilter = allTiers ? "" : buildTierFilter(tier);
   const channelFilter = buildChannelFilter(channel);
+  // Under --all-tiers, `ds:name`/`ds:tier` become OPTIONAL so a real block that
+  // ships without either is no longer hidden — the flag promises "all blocks",
+  // yet the pre-fix query gated on those as REQUIRED patterns, dropping the
+  // FILTER but not the pattern (A2). In the scoped/default view they stay
+  // required: a block joins the list through its tier, so an untiered block is
+  // intentionally out of a tier-scoped view (and --all-tiers is the escape).
+  const nameTierPatterns = allTiers
+    ? [
+        "  OPTIONAL { ?component ds:name ?name }",
+        "  OPTIONAL { ?component ds:tier ?tier }",
+      ]
+    : ["  ?component ds:name ?name ; ds:tier ?tier ."];
   return [
     "SELECT ?component ?type ?name ?tier",
     '       (GROUP_CONCAT(DISTINCT ?modName; separator=", ") AS ?modifiers)',
     "WHERE {",
     "  VALUES ?type { ds:Component ds:Pattern ds:Layout ds:Subcomponent }",
-    "  ?component a ?type ;",
-    "             ds:name ?name ;",
-    "             ds:tier ?tier .",
+    "  ?component a ?type .",
+    ...nameTierPatterns,
     tierFilter ? `  ${tierFilter}` : "",
     `  ${channelFilter}`,
     "  OPTIONAL { ?component ds:hasModifierFamily ?mod . ?mod ds:name ?modName }",
@@ -118,7 +129,7 @@ const listVerb: VerbSpec<Record<string, unknown>, BlockRow[]> = {
   examples: [
     { cmd: "pragma block list" },
     { cmd: "pragma block list --all-tiers" },
-    { cmd: "pragma block list --llm" },
+    { cmd: "pragma block list --format llm" },
   ],
   capability: {
     needsStore: true,
@@ -138,7 +149,9 @@ const listVerb: VerbSpec<Record<string, unknown>, BlockRow[]> = {
     const rows = await runSelect(rt, query, "block");
     return rows.map((row) => ({
       uri: row.component ?? "",
-      name: row.name ?? "",
+      // An unnamed block still needs a token to show — fall back to its IRI's
+      // local name rather than rendering a blank row (A2).
+      name: row.name ?? localName(row.component ?? ""),
       type: normalizeType(row.type),
       tier: localName(row.tier ?? ""),
       modifiers: row.modifiers ?? "",

package/src/capabilities/block/pack.ts

@@ -9,6 +9,14 @@
  * which rendered anatomy and modifiers without a flag. A derived name that maps
  * onto no schema field is omitted (OPTIONAL parity), so a graph lacking
  * whenToUse/whenNotToUse degrades gracefully.
+ *
+ * Disclosure declares the FULL canonical ladder `[summary, standard, detailed]`
+ * (B4), the same set `standard` declares, so a config `detail=standard` names a
+ * level `block` advertises rather than one it silently accepts-then-degrades.
+ * Block carries no `standard`-tier content of its own — gating is by canonical
+ * index, so `standard` resolves to the base view — but the declared set now
+ * matches its sibling reads. The per-noun DEFAULT stays domain-tuned (`block`
+ * rich-by-default, `standard` terse-by-default); only the level SET is aligned.
  */
 
 import type { PackDefinition } from "../../kernel/packs/types.js";
@@ -145,7 +153,10 @@ export const blockPack: PackDefinition = {
         ],
       },
     ],
-    disclosure: { levels: ["summary", "detailed"], default: "detailed" },
+    disclosure: {
+      levels: ["summary", "standard", "detailed"],
+      default: "detailed",
+    },
     sample: {
       fixedCount: true,
       toolDescription:

package/src/capabilities/block/parity.test.ts

@@ -173,8 +173,15 @@ describe("block list — hand-written tier/channel filtering", () => {
     ]);
   });
 
-  it("--all-tiers returns the same global blocks (no tier configured)", async () => {
+  it("--all-tiers also reveals the untiered subcomponent (A2)", async () => {
+    // Button Icon is a ds:Subcomponent with NO ds:tier: the scoped/default view
+    // omits it (a block joins the list through its tier), but --all-tiers must
+    // surface every block, including untiered ones.
     const rows = (await listVerb.run({ allTiers: true }, rt)) as BlockRow[];
-    expect(rows.map((r) => r.name).sort()).toEqual(["Button", "Modal"]);
+    expect(rows.map((r) => r.name).sort()).toEqual([
+      "Button",
+      "Button Icon",
+      "Modal",
+    ]);
   });
 });

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

@@ -99,10 +99,19 @@ describe("capabilities catalog — grammar-derived, drift-guarded (PROTECTED)",
     expect(data.limits.condensed_available).toBe(false);
   });
 
-  it("carries the three orientation conventions", () => {
+  it("carries the four orientation conventions", () => {
     expect(data.conventions.system.length).toBeGreaterThan(0);
     expect(data.conventions.model).toContain("tier");
     expect(data.conventions.querying).toContain("RDF");
+    expect(data.conventions.mutations.length).toBeGreaterThan(0);
+  });
+
+  it("surfaces the plan-first/confirm convention so the confirm gate isn't trial-and-error (D2)", () => {
+    // A mutating tool without `confirm` returns a plan and writes nothing; agents
+    // must learn this from orientation, not by tripping the gate.
+    const { mutations } = data.conventions;
+    expect(mutations).toMatch(/plan/i);
+    expect(mutations).toContain("confirm");
   });
 });
 

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

@@ -22,7 +22,7 @@ const capabilitiesVerb: VerbSpec<Record<string, unknown>, CapabilitiesData> = {
   path: ["capabilities"],
   summary:
     "Discover pragma conventions, the annotated tool catalog, and the discovery sequence.",
-  doc: "Storeless orientation for agents. Returns the conventions (KG / tier-channel / SPARQL model), a 3-stage discovery sequence, and every live tool with a behavioural use_when hint and category — all derived from the live grammar, so it never drifts. Call it first at session start.",
+  doc: "Storeless orientation for agents. Returns the conventions (KG / tier-channel / SPARQL model), a four-stage discovery sequence, and every live tool with a behavioural use_when hint and category — all derived from the live grammar, so it never drifts. Call it first at session start.",
   params: [],
   output: { formatters: capabilitiesFormatters },
   examples: [

package/src/capabilities/capabilities/catalog.ts

@@ -26,16 +26,20 @@ import type {
 } from "./types.js";
 
 /**
- * The three orientation conventions, verbatim from the old shell. They describe
- * the KG / tier-channel / SPARQL model and are still accurate for v2.
+ * The four orientation conventions. The first three (system/model/querying) are
+ * verbatim from the old shell — they describe the KG / tier-channel / SPARQL
+ * model and are still accurate for v2; `mutations` is new in v2, surfacing the
+ * plan-first/confirm gate.
  */
 export const CONVENTIONS = {
   system:
     "Pragma is a CLI and MCP server for querying a design system knowledge graph — blocks, tokens, modifiers, standards, and ontologies.",
   model:
-    "Data is scoped by tier (hierarchical, e.g. global > apps > apps/lxd) and channel (normal, experimental, prerelease). Set these via config_tier and config_channel.",
+    "Data is scoped by tier (hierarchical, e.g. global > apps > apps/lxd) and channel (normal, experimental, prerelease). Set these via config_set (e.g. config_set tier apps/lxd, config_set channel experimental).",
   querying:
     "All queries run against an RDF triple store. Prefixed IRIs (e.g. ds:global.component.button) identify entities. Use ontology_list to discover namespaces.",
+  mutations:
+    "Mutating tools are plan-first: call once WITHOUT confirm to get a plan (meta.planOnly, no writes), then repeat the call with confirm: true to execute.",
 } as const;
 
 /** The output modes v2 renders (dropped "text" → "plain"; condensed retired). */

package/src/capabilities/capabilities/hints.ts

@@ -7,7 +7,7 @@
  * exists, or a hint's category disagrees with the tool's real `mutates` flag.
  *
  * `use_when` strings for the surviving tools are ported verbatim from the old
- * shell's `domains/llm/data/toolCatalog.ts`; the net-new v2 tools (config_detail,
+ * shell's `domains/llm/data/toolCatalog.ts`; the net-new v2 tools (config_set,
  * graph_query, setup, upgrade, doctor, capabilities, prompt_*, token_add-config,
  * sources_*, tier_lookup, create_*) are authored here.
  */
@@ -93,10 +93,15 @@ export const TOOL_HINTS: Record<string, ToolHint> = {
     use_when:
       "Discovering loaded namespaces, prefixes, and class/property counts",
   },
+  ontology_lookup: {
+    category: "read",
+    use_when:
+      "Exploring the full schema of a namespace by name — classes, properties, and hierarchy",
+  },
   ontology_show: {
     category: "read",
     use_when:
-      "Exploring the full schema of a namespace — classes, properties, and hierarchy",
+      "Deprecated alias of ontology_lookup — exploring a namespace's schema (prefer ontology_lookup)",
   },
   prompt_list: {
     category: "read",
@@ -166,24 +171,10 @@ export const TOOL_HINTS: Record<string, ToolHint> = {
   },
 
   // — Write ——————————————————————————————————————————————————————————————————
-  config_tier: {
-    category: "write",
-    use_when: "Setting or resetting the active tier filter",
-  },
-  config_channel: {
-    category: "write",
-    use_when:
-      "Setting the release channel (normal, experimental, or prerelease)",
-  },
-  config_detail: {
-    category: "write",
-    use_when:
-      "Setting the default progressive-disclosure level (summary, standard, detailed)",
-  },
   config_set: {
     category: "write",
     use_when:
-      "Setting any config field by name in one call — tier, channel, or detail",
+      "Setting any config field by name — tier, channel, or detail (e.g. `config set tier apps/lxd`)",
   },
   create_component: {
     category: "write",

package/src/capabilities/capabilities/types.ts

@@ -47,6 +47,8 @@ export interface CapabilitiesData {
     readonly system: string;
     readonly model: string;
     readonly querying: string;
+    /** The plan-first/confirm gate every mutating tool follows (D2). */
+    readonly mutations: string;
   };
   readonly discovery_sequence: readonly DiscoveryStage[];
   readonly tools: readonly CatalogTool[];

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

@@ -78,10 +78,37 @@ describe("colophon render golden — color-free (chalk.level = 0)", () => {
   });
 });
 
-describe("colophon render — color ON", () => {
-  it("plain emits ANSI escapes when chalk color is enabled", () => {
+/** Run `body` with stdout's `isTTY` forced to `value`, then restore it. */
+function withStdoutTty(value: boolean | undefined, body: () => void): void {
+  const stream = process.stdout as { isTTY?: boolean };
+  const saved = stream.isTTY;
+  stream.isTTY = value;
+  try {
+    body();
+  } finally {
+    stream.isTTY = saved;
+  }
+}
+
+describe("colophon render — color ON (attended TTY)", () => {
+  it("plain emits ANSI escapes on a color-capable TTY", () => {
     chalk.level = 1;
-    // biome-ignore lint/suspicious/noControlCharactersInRegex: asserting the literal ESC byte is the point
-    expect(colophonFormatters.plain(FIXTURE)).toMatch(/\x1b\[/);
+    withStdoutTty(true, () => {
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: asserting the literal ESC byte is the point
+      expect(colophonFormatters.plain(FIXTURE)).toMatch(/\x1b\[/);
+    });
+  });
+});
+
+describe("colophon render — piped output is ANSI-free (F1)", () => {
+  it("plain emits ZERO ANSI off a TTY even when chalk reports color (CI/FORCE_COLOR)", () => {
+    // The CI leak: `supports-color` sets a non-zero level off a TTY under
+    // GITHUB_ACTIONS / FORCE_COLOR, so gating on `chalk.level` alone bled ANSI
+    // into `colophon --format plain | tee`. The isTTY gate closes it.
+    chalk.level = 3;
+    withStdoutTty(undefined, () => {
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: asserting NO ESC byte survives
+      expect(colophonFormatters.plain(FIXTURE)).not.toMatch(/\x1b\[/);
+    });
   });
 });

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

@@ -9,23 +9,32 @@
  * (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): string {
-  return renderMarkdownToTerminal(`# ${section.title}\n\n${section.markdown}`);
+function plainSection(section: ColophonSection, style: RenderStyle): string {
+  return renderMarkdownToTerminal(
+    `# ${section.title}\n\n${section.markdown}`,
+    style,
+  );
 }
 
-/** Render one section as condensed Markdown for `--llm` (summary preferred). */
+/** 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) {
-    return data.sections.map(plainSection).join("\n\n");
+    // 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) {

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

@@ -4,7 +4,7 @@
  * 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`/`--llm` precedence, holds CLI-json ≡ MCP
+ * three formatter modes + `--format` precedence, holds CLI-json ≡ MCP
  * parity, and checks the pack-grammar accepts a `colophon` field (rejecting a
  * non-string).
  */
@@ -47,7 +47,7 @@ const FLAGS: GlobalFlags = {
   verbose: false,
 };
 const FLAGS_JSON: GlobalFlags = { ...FLAGS, format: "json" };
-const FLAGS_LLM: GlobalFlags = { ...FLAGS, llm: true };
+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. */
@@ -170,7 +170,7 @@ describe("colophon — formatter modes", () => {
     expect((envelope.data as ColophonData).sections[0]?.kind).toBe("pragma");
   });
 
-  it("--llm selects the condensed Markdown form", async () => {
+  it("--format llm selects the condensed Markdown form", async () => {
     const outcome = await executeVerb(
       colophonVerb,
       {},

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

@@ -20,7 +20,10 @@ const colophonVerb: VerbSpec<Record<string, unknown>, ColophonData> = {
   output: { formatters: colophonFormatters },
   examples: [
     { cmd: "pragma colophon", note: "the toolchain + active domain story" },
-    { cmd: "pragma colophon --llm", note: "condensed Markdown for agents" },
+    {
+      cmd: "pragma colophon --format llm",
+      note: "condensed Markdown for agents",
+    },
   ],
   capability: {
     needsStore: false,