@canonical/pragma-cli 0.33.0 → 0.34.0

package/src/bin.ts

@@ -129,16 +129,25 @@ async function main(): Promise<void> {
     return;
   }
 
-  // A real command merges config-declared story packs into the tree (DISPATCH
-  // only); `--help` stays on the static, storeless capabilities so its budget
-  // and the golden hold. An invalid config story surfaces as a rendered error.
+  // A real command merges the package- and config-declared story packs into the
+  // tree (DISPATCH only); `--help` stays on the static, storeless capabilities
+  // so its budget and the golden hold. An invalid CONFIG story surfaces as a
+  // rendered error; a package story that cannot be used is named on stderr and
+  // the command carries on (it is third-party data, and failing here would take
+  // `sources update` and `doctor` — the only recoveries — down with it).
   let modules = capabilities;
   if (!explicitHelp) {
     try {
       const { loadEffectiveModules } = await import(
         "./kernel/packs/collect.js"
       );
-      modules = await loadEffectiveModules(capabilities, process.cwd());
+      const effective = await loadEffectiveModules(capabilities, process.cwd());
+      modules = effective.modules;
+      for (const problem of effective.problems) {
+        process.stderr.write(
+          `Ignored story ${problem.source}: ${problem.message}\n`,
+        );
+      }
     } catch (error) {
       await renderStartupError(error, globalFlags.format === "json");
       return;

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

@@ -0,0 +1,250 @@
+/**
+ * Block-noun semantic parity (PROTECTED) — the `block` story `pragma.conf.ts`
+ * declares, over the shared block fixture graph (the standard-noun pattern).
+ *
+ * The `block` noun has no hand-written code left (L-OPEN-9): `list` and
+ * `lookup` both compile from the declared story, so parity is asserted directly
+ * against the graph. Two halves:
+ *
+ * - `block list` — the UNFILTERED list. Every block in the store, whatever the
+ *   tier or channel, including the UNTIERED subcomponent the old hand-written
+ *   query's required `ds:tier` join dropped (A2, formerly reachable only under
+ *   `--all-tiers`). The row shape the hand-written verb built in TypeScript —
+ *   the name fallback, the lowercased type, the tier's local name — is now
+ *   derived IN SPARQL by `BIND`/`COALESCE`, and this file is what holds those
+ *   BINDs to the shapes the old `blockList.verb.ts` produced.
+ * - `block lookup` — unchanged GraphQL content parity, moved here from the
+ *   deleted `capabilities/block/parity.test.ts`. Button and Modal resolve with
+ *   the same content a direct SPARQL oracle returns (summary, guidance,
+ *   anatomy, tier, modifier families with values, properties, subcomponents).
+ *   The fixture DECLARES whenToUse/whenNotToUse (which the live graph superseded
+ *   with ds:usage), so those sections are exercised here.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import type { LookupOutput } from "../kernel/packs/resolveEntity.js";
+import type { PackRow } from "../kernel/packs/types.js";
+import { verbKey } from "../kernel/packs/uniqueness.js";
+import type { PragmaRuntime } from "../kernel/runtime/types.js";
+import type { VerbSpec } from "../kernel/spec/types.js";
+import { BLOCK_PREFIXES, BLOCK_TTL } from "../testing/fixtures/blockGraph.js";
+import { buildFixtureRuntime } from "../testing/helpers/packRuntime.js";
+import { storyModules } from "./distribution.js";
+
+const blockModule = storyModules.get("block");
+if (!blockModule) {
+  throw new Error('pragma.conf.ts declares no story for "block"');
+}
+
+const DS = "https://ds.canonical.com/";
+
+const verb = (label: string): VerbSpec =>
+  blockModule.verbs.find(
+    (v) => verbKey(v.path) === `block ${label}`,
+  ) as VerbSpec;
+
+let rt: PragmaRuntime;
+
+beforeAll(async () => {
+  ({ rt } = await buildFixtureRuntime({
+    ttl: BLOCK_TTL,
+    prefixes: BLOCK_PREFIXES,
+    detail: "detailed",
+  }));
+});
+
+afterAll(async () => {
+  (await rt.store.get()).store.dispose();
+});
+
+async function lookup(name: string): Promise<Record<string, unknown>> {
+  const out = (await verb("lookup").run({ name: [name] }, rt)) as LookupOutput;
+  expect(out.errors).toEqual([]);
+  return out.results.at(0) as Record<string, unknown>;
+}
+
+describe("block list parity — the declared, unfiltered list", () => {
+  it("lists EVERY block, including the untiered subcomponent (A2)", async () => {
+    // `ds:button.icon` is a `ds:Subcomponent` with NO `ds:tier`. The
+    // hand-written query inner-joined `?c ds:tier ?t` in its default view and
+    // surfaced it only under `--all-tiers`; the declared query's OPTIONAL join
+    // means there is no view it can fall out of.
+    const rows = (await verb("list").run({}, rt)) as PackRow[];
+    expect(rows.map((row) => row.name)).toEqual([
+      "Button",
+      "Button Icon",
+      "Modal",
+    ]);
+  });
+
+  it("derives the summary row shape in SPARQL, matching the old hand-built row", async () => {
+    const rows = (await verb("list").run({}, rt)) as PackRow[];
+    const byName = new Map(rows.map((row) => [row.name, row]));
+    const button = byName.get("Button");
+    // `type`: the LOWERCASED local name of the matched class — the BIND that
+    // replaced `normalizeType`.
+    expect(button?.type).toBe("component");
+    expect(byName.get("Button Icon")?.type).toBe("subcomponent");
+    // `tier`: the tier IRI's local name — the BIND that replaced `localName`.
+    expect(button?.tier).toBe("global");
+    expect(button?.uri).toBe(`${DS}button`);
+    // GROUP_CONCAT of the family names (order-independent).
+    expect(String(button?.modifiers).split(", ").sort()).toEqual([
+      "density",
+      "importance",
+    ]);
+  });
+
+  it("an untiered block simply carries no tier — it is not dropped or blanked", async () => {
+    const rows = (await verb("list").run({}, rt)) as PackRow[];
+    const icon = rows.find((row) => row.name === "Button Icon");
+    expect(icon).toBeDefined();
+    expect(icon?.tier).toBeUndefined();
+    expect(icon?.uri).toBe(`${DS}button.icon`);
+  });
+
+  it("is CONFIG-INDEPENDENT: a configured tier and channel change nothing", async () => {
+    // The signed-off consequence of L-OPEN-9, pinned at the verb: the run body
+    // never reads `loadConfig()`, so the same rows come back under any scope.
+    const scoped = {
+      ...rt,
+      loadConfig: async () => ({
+        ...(await rt.loadConfig()),
+        config: {
+          ...(await rt.loadConfig()).config,
+          tier: "apps/lxd",
+          channel: "experimental" as const,
+        },
+      }),
+    } as PragmaRuntime;
+    const scopedRows = (await verb("list").run({}, scoped)) as PackRow[];
+    const plainRows = (await verb("list").run({}, rt)) as PackRow[];
+    expect(scopedRows).toEqual(plainRows);
+  });
+
+  it("zero rows is a calm empty list, not an error (the declared-family semantics)", async () => {
+    // D10-A, measured: `makeListRun` returns `[]` and never throws on
+    // emptiness — identical exit-code behaviour to the hand-written verb, which
+    // also returned an empty array. Only the empty MESSAGE changed (the pack's
+    // `emptyRecovery` replaces the `--all-tiers` hint that no longer exists).
+    const { rt: emptyRt } = await buildFixtureRuntime({
+      ttl: `
+@prefix ds: <${DS}> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+ds:Component a owl:Class .
+`,
+      prefixes: BLOCK_PREFIXES,
+    });
+    try {
+      const rows = (await verb("list").run({}, emptyRt)) as PackRow[];
+      expect(rows).toEqual([]);
+      const plain = verb("list").output.formatters.plain(rows);
+      expect(plain).toContain("No blocks in the store.");
+      expect(plain).toContain("pragma sources update");
+    } finally {
+      (await emptyRt.store.get()).store.dispose();
+    }
+  });
+});
+
+describe("block lookup — Button content parity (GraphQL, detailed)", () => {
+  it("resolves the full Button spec with content matching the SPARQL oracle", async () => {
+    const button = await lookup("Button");
+    expect(button.uri).toBe(`${DS}button`);
+    expect(button.name).toBe("Button");
+    expect(button.tier).toBe(`${DS}global`);
+
+    // Guidance + anatomy sections — each cross-checked against the graph.
+    expect(button.summary).toBe(await oracle(`${DS}button`, "ds:summary"));
+    expect(button.whenToUse).toBe(await oracle(`${DS}button`, "ds:whenToUse"));
+    expect(button.whenNotToUse).toBe(
+      await oracle(`${DS}button`, "ds:whenNotToUse"),
+    );
+    expect(button.guidelines).toBe(
+      await oracle(`${DS}button`, "ds:guidelines"),
+    );
+    expect(button.anatomyDsl).toBe(
+      await oracle(`${DS}button`, "ds:anatomyDsl"),
+    );
+    expect(button.figmaLink).toBe(await oracle(`${DS}button`, "ds:figmaLink"));
+  });
+
+  it("resolves the nested modifier families with values (inverse union)", async () => {
+    const button = await lookup("Button");
+    const families = button.modifierFamilies as {
+      name: string;
+      values?: string[];
+    }[];
+    expect(families.map((f) => f.name).sort()).toEqual([
+      "density",
+      "importance",
+    ]);
+    const importance = families.find((f) => f.name === "importance");
+    expect(importance?.values?.sort()).toEqual(["primary", "secondary"]);
+  });
+
+  it("resolves properties and the subtype-scoped subcomponents identity field", async () => {
+    const button = await lookup("Button");
+    expect(button.properties).toEqual([
+      { name: "disabled", type: "boolean", optional: "true" },
+    ]);
+    expect(button.subcomponents).toEqual([
+      { name: "Button Icon", uri: `${DS}button.icon` },
+    ]);
+  });
+
+  it("renders every declared section in the llm output", async () => {
+    const out = (await verb("lookup").run({ name: ["Button"] }, rt)) as never;
+    const llm = verb("lookup").output.formatters.llm(out);
+    expect(llm).toContain("## Button");
+    expect(llm).toContain("### When to use");
+    expect(llm).toContain("### Anatomy (DSL)");
+    expect(llm).toContain("### Modifier Families");
+    expect(llm).toContain("primary");
+  });
+});
+
+describe("block lookup — Modal content parity (GraphQL, detailed)", () => {
+  it("resolves the full Modal spec (a different block, same document engine)", async () => {
+    const modal = await lookup("Modal");
+    expect(modal.uri).toBe(`${DS}modal`);
+    expect(modal.name).toBe("Modal");
+    expect(modal.summary).toBe(await oracle(`${DS}modal`, "ds:summary"));
+    expect(modal.whenToUse).toBe(await oracle(`${DS}modal`, "ds:whenToUse"));
+    const families = modal.modifierFamilies as {
+      name: string;
+      values?: string[];
+    }[];
+    expect(families.map((f) => f.name)).toEqual(["size"]);
+    expect(families[0]?.values?.sort()).toEqual(["large", "small"]);
+    expect(modal.properties).toEqual([
+      { name: "open", type: "boolean", optional: "false" },
+    ]);
+    // Modal has no subcomponents — the subtype-scoped selection is simply absent.
+    expect(modal.subcomponents).toEqual([]);
+  });
+});
+
+describe("block lookup — disclosure trims to the base view at summary", () => {
+  it("summary keeps name/tier/summary and drops the detailed sections/expands", async () => {
+    const out = (await verb("lookup").run(
+      { name: ["Button"] },
+      { ...rt, globalFlags: { ...rt.globalFlags, detail: "summary" } },
+    )) as LookupOutput;
+    const button = out.results.at(0) as Record<string, unknown>;
+    expect(button.name).toBe("Button");
+    expect(button.summary).toBeDefined();
+    expect(button.whenToUse).toBeUndefined();
+    expect(button.anatomyDsl).toBeUndefined();
+    expect(button.modifierFamilies).toBeUndefined();
+    expect(button.figmaLink).toBeUndefined();
+  });
+});
+
+/** Oracle: a single scalar from the graph, queried directly. */
+async function oracle(subject: string, predicate: string): Promise<string> {
+  const result = await rt.query.sparql(
+    `SELECT ?v WHERE { <${subject}> ${predicate} ?v }`,
+  );
+  return result.type === "select" ? (result.bindings[0]?.v ?? "") : "";
+}

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

@@ -6,6 +6,7 @@
  * (what the MCP tool returns through the envelope).
  */
 
+import { BIN_NAME } from "../../constants.js";
 import type { Formatters } from "../../kernel/spec/types.js";
 import type { CapabilitiesData, ToolCategory } from "./types.js";
 
@@ -19,7 +20,7 @@ const CATEGORY_ORDER: readonly ToolCategory[] = [
 
 export const capabilitiesFormatters: Formatters<CapabilitiesData> = {
   plain(data) {
-    const lines: string[] = [`pragma v${data.version}`, ""];
+    const lines: string[] = [`${BIN_NAME} v${data.version}`, ""];
 
     lines.push("Conventions");
     lines.push(`  ${data.conventions.system}`);
@@ -53,7 +54,7 @@ export const capabilitiesFormatters: Formatters<CapabilitiesData> = {
   },
 
   llm(data) {
-    const lines: string[] = [`# pragma v${data.version}`, ""];
+    const lines: string[] = [`# ${BIN_NAME} v${data.version}`, ""];
 
     lines.push("## Conventions");
     lines.push(`- ${data.conventions.system}`);

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

@@ -7,12 +7,21 @@
  * counts) is deliberately DROPPED here (it would require a store boot at
  * orientation) and lives in `info` / `config show` / `sources status` instead.
  *
- * `run` is a lazy thunk that dynamic-imports the catalog + the capability
- * registry barrel, so building the command tree never pulls the derivation onto
- * the `--help`/`__complete` fast path, and the tool never boots the store
- * (`store.booted` stays false — the storeless-spy invariant).
+ * `run` is a lazy thunk that dynamic-imports the catalog, the capability
+ * registry barrel and the dispatch-time merge, so building the command tree
+ * never pulls the derivation onto the `--help`/`__complete` fast path, and the
+ * tool never boots the store (`store.booted` stays false — the storeless-spy
+ * invariant).
+ *
+ * It reports the EFFECTIVE modules, not the static registry: the MCP server
+ * registers its tools from the same merge, so a catalog built from the static
+ * set would omit exactly the config- and package-declared nouns `tools/list`
+ * advertises — the hand-maintained drift this catalog exists to end. With no
+ * declared stories the merge returns the registry by identity, so the payload is
+ * unchanged.
  */
 
+import { BIN_NAME } from "../../constants.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
 import type { VerbSpec } from "../../kernel/spec/types.js";
 import { capabilitiesFormatters } from "./capabilities.render.js";
@@ -20,14 +29,16 @@ import type { CapabilitiesData } from "./types.js";
 
 const capabilitiesVerb: VerbSpec<Record<string, unknown>, CapabilitiesData> = {
   path: ["capabilities"],
-  summary:
-    "Discover pragma conventions, the annotated tool catalog, and the discovery sequence.",
+  summary: `Discover ${BIN_NAME} conventions, the annotated tool catalog, and the discovery sequence.`,
   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: [
-    { cmd: "pragma capabilities", note: "the annotated tool catalog" },
-    { cmd: "pragma capabilities --format json", note: "the structured map" },
+    { cmd: `${BIN_NAME} capabilities`, note: "the annotated tool catalog" },
+    {
+      cmd: `${BIN_NAME} capabilities --format json`,
+      note: "the structured map",
+    },
   ],
   capability: {
     needsStore: false,
@@ -37,11 +48,18 @@ const capabilitiesVerb: VerbSpec<Record<string, unknown>, CapabilitiesData> = {
       annotations: { readOnlyHint: true, openWorldHint: false },
     },
   },
-  run: (_params, _runtime) =>
-    Promise.all([import("./catalog.js"), import("../index.js")]).then(
-      ([catalog, registry]) =>
-        catalog.buildCapabilitiesData(registry.capabilities),
-    ),
+  run: async (_params, runtime) => {
+    const [catalog, registry, collect] = await Promise.all([
+      import("./catalog.js"),
+      import("../index.js"),
+      import("../../kernel/packs/collect.js"),
+    ]);
+    const { modules } = await collect.loadEffectiveModules(
+      registry.capabilities,
+      runtime.cwd,
+    );
+    return catalog.buildCapabilitiesData(modules);
+  },
 };
 
 /** The `capabilities` verb, widened for registry composition. */

package/src/capabilities/capabilities/catalog.ts

@@ -14,7 +14,7 @@
  * orientation from the SAME source and the two can never diverge.
  */
 
-import { VERSION } from "../../constants.js";
+import { BIN_NAME, PROGRAM_DESCRIPTION, VERSION } from "../../constants.js";
 import { emitSurface } from "../../kernel/spec/emitSurface.js";
 import type { CapabilityModule } from "../../kernel/spec/types.js";
 import { TOOL_HINTS } from "./hints.js";
@@ -26,18 +26,26 @@ import type {
 } from "./types.js";
 
 /**
- * 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.
+ * The four orientation conventions, and the single source both the
+ * `capabilities` tool and the MCP handshake read, so the two cannot contradict
+ * each other. `system` projects the distribution's identity rather than naming
+ * a domain — the live tool catalog the same handshake carries already says
+ * which nouns exist. `querying` is verbatim from the old shell (the SPARQL
+ * model is still accurate for v2); `model` stopped claiming reads are
+ * tier/channel-SCOPED when the hand-written filtering was removed (L-OPEN-9)
+ * — the hierarchy is graph data now, not a query gate; `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.",
+  // `help` is authored as a bare phrase (`--help` renders it as one), so the
+  // self-description trails in parentheses rather than after a period this
+  // string would have to add — a fork writing "Explore the recipe graph."
+  // otherwise reads "recipe graph.. A CLI and MCP server…".
+  system: `${BIN_NAME} — ${PROGRAM_DESCRIPTION} (a CLI and MCP server over a knowledge graph).`,
   model:
-    "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).",
+    "The graph models a tier hierarchy (e.g. global > apps > apps/lxd) and release channels (normal, experimental, prerelease) as DATA on each entity. Reads are unscoped — every list shows everything; filter by inspecting an entity's tier/release fields or with graph_query.",
   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.",
+    "All queries run against an RDF triple store. Prefixed IRIs (e.g. prefix:name) identify entities. Use ontology_list to discover the active 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;
@@ -83,7 +91,7 @@ export function buildDiscoverySequence(
       stage: 2,
       tool: "sources_status",
       purpose:
-        "Confirm the store is built before any query. If it reports unavailable, call sources_update (confirm: true) first — otherwise the sample and domain reads below fail with STORE_UNAVAILABLE.",
+        "See which pack is answering. A fresh install answers reads from the snapshot embedded in the binary and needs no build; only an `unavailable` status requires sources_update (confirm: true), which is a project that declared its own packs and has not built them.",
     },
     {
       stage: 3,

package/src/capabilities/capabilities/hints.ts

@@ -8,10 +8,11 @@
  *
  * `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_set,
- * graph_query, setup, upgrade, doctor, capabilities, prompt_*, token_add-config,
- * sources_*, tier_lookup, create_*) are authored here.
+ * graph_query, setup, upgrade, doctor, capabilities, prompt_*, sources_*,
+ * tier_lookup, create_*) are authored here.
  */
 
+import { BIN_NAME } from "../../constants.js";
 import type { ToolHint } from "./types.js";
 
 /**
@@ -36,14 +37,14 @@ export const TOOL_HINTS: Record<string, ToolHint> = {
   },
   info: {
     category: "diagnostic",
-    use_when: "Checking pragma version, configuration summary, and store state",
+    use_when: `Checking ${BIN_NAME} version, configuration summary, and store state`,
   },
 
   // — Read ——————————————————————————————————————————————————————————————————
   block_list: {
     category: "read",
     use_when:
-      "Browsing available components, patterns, layouts under current tier/channel",
+      "Browsing all components, patterns, layouts, and subcomponents in the store",
   },
   block_lookup: {
     category: "read",
@@ -57,12 +58,12 @@ export const TOOL_HINTS: Record<string, ToolHint> = {
   },
   colophon: {
     category: "read",
-    use_when:
-      "Understanding how pragma and the active domain are built — the toolchain + design-system colophon, for onboarding or a demo",
+    use_when: `Understanding how ${BIN_NAME} and the active domain are built — the toolchain + domain colophon, for onboarding or a demo`,
   },
   config_show: {
     category: "read",
-    use_when: "Checking active tier and channel before querying",
+    use_when:
+      "Checking the active configuration (tier, channel, detail) and which layer set each field",
   },
   graph_inspect: {
     category: "read",
@@ -105,8 +106,7 @@ export const TOOL_HINTS: Record<string, ToolHint> = {
   },
   prompt_list: {
     category: "read",
-    use_when:
-      "Browsing the workflow prompt templates the design-system graph offers",
+    use_when: "Browsing the workflow prompt templates the active graph offers",
   },
   prompt_lookup: {
     category: "read",
@@ -178,8 +178,7 @@ export const TOOL_HINTS: Record<string, ToolHint> = {
   },
   create_component: {
     category: "write",
-    use_when:
-      "Scaffolding a new design-system component (React, Svelte, or Lit)",
+    use_when: "Scaffolding a new component (React, Svelte, or Lit)",
   },
   create_package: {
     category: "write",
@@ -193,20 +192,15 @@ export const TOOL_HINTS: Record<string, ToolHint> = {
   },
   setup: {
     category: "write",
-    use_when:
-      "Installing pragma's shell completions, MCP config, skills, and LSP into the environment",
+    use_when: `Installing ${BIN_NAME}'s shell completions, MCP config, skills, and LSP into the environment`,
   },
   sources_update: {
     category: "write",
     use_when:
-      "Building or refreshing the knowledge-graph pack from the configured packages",
-  },
-  "token_add-config": {
-    category: "write",
-    use_when: "Generating a tokens.config.mjs for the terrazzo token pipeline",
+      "Building or refreshing the knowledge-graph pack from the configured packs",
   },
   upgrade: {
     category: "write",
-    use_when: "Upgrading the pragma CLI itself to the latest release",
+    use_when: `Upgrading the ${BIN_NAME} CLI itself to the latest release`,
   },
 };

package/src/capabilities/colophon/collectColophon.ts

@@ -1,11 +1,14 @@
 /**
  * Collect the `colophon` payload — the verb's run body (lazily imported).
  *
- * STORELESS: it reads the layered config (memoized) and resolves the EFFECTIVE
- * capability modules exactly as a real command would, so a config story that
- * overrides a bundled pack is reflected here — "active domain" is expressed the
- * way the rest of the CLI expresses it. It never boots the triple store, so the
- * storeless-guarantee spy still sees `store.booted === false`.
+ * STORELESS: it resolves the EFFECTIVE capability modules exactly as a real
+ * command would — through `loadEffectiveModules`, so a story declared by a
+ * PACKAGE the active pack carries surfaces its colophon here too, not only a
+ * config-declared one. It never boots the triple store, so the
+ * storeless-guarantee spy still sees `store.booted === false`. The static
+ * import of the validated distribution config (`config/defaults.js`) is safe
+ * here because this module sits behind the verb's dynamic `import()` — it
+ * never lands on the `--help`/`__complete` fast path.
  *
  * The registry is reached through a RUNTIME dynamic `import("../index.js")`
  * inside this async body — never a static import — so the static
@@ -13,44 +16,56 @@
  * into a static import.
  */
 
+import { BIN_NAME } from "../../constants.js";
+import distribution from "../../kernel/config/defaults.js";
 import type { PragmaRuntime } from "../../kernel/runtime/types.js";
 import type { CapabilityModule } from "../../kernel/spec/types.js";
-import { PRAGMA_COLOPHON, PRAGMA_COLOPHON_SUMMARY } from "./pragmaColophon.js";
 import type { ColophonData, ColophonSection } from "./types.js";
 
 /**
  * Assemble the colophon data for the current runtime.
  *
+ * The toolchain section is DECLARED, not authored here: the distribution
+ * config's `colophon` field carries the narrative (and its condensed summary),
+ * and this collector renders whatever it declares under the distribution's own
+ * name — a fork edits its config, never this module. A distribution declaring
+ * no `colophon` gets no toolchain section: the packs' domain colophons stand
+ * alone. The `kind: "pragma"` value is a frozen JSON discriminant (wire
+ * compatibility), not the distribution's name.
+ *
  * @param runtime - The per-invocation runtime.
- * @returns The storeless colophon payload: pragma's section, then each active
- *   pack/domain that declares a `colophon`.
+ * @returns The storeless colophon payload: the distribution's declared section,
+ *   then each active pack/domain that declares a `colophon`.
  * @note Impure — reads the config layers (never boots the store).
  */
 export async function collectColophon(
   runtime: PragmaRuntime,
 ): Promise<ColophonData> {
-  const sections: ColophonSection[] = [
-    {
+  const sections: ColophonSection[] = [];
+  if (distribution.colophon) {
+    sections.push({
       kind: "pragma",
-      title: "pragma",
-      markdown: PRAGMA_COLOPHON,
-      summary: PRAGMA_COLOPHON_SUMMARY,
+      title: BIN_NAME,
+      markdown: distribution.colophon.markdown,
+      ...(distribution.colophon.summary === undefined
+        ? {}
+        : { summary: distribution.colophon.summary }),
       source: "built-in",
-    },
-  ];
+    });
+  }
 
-  const { assembleEffectiveModules } = await import(
+  const { loadEffectiveModules } = await import(
     "../../kernel/packs/collect.js"
   );
   const { capabilities } = await import("../index.js");
 
   let modules: readonly CapabilityModule[] = capabilities;
   try {
-    const layers = await runtime.loadConfig();
-    modules = assembleEffectiveModules(capabilities, layers);
+    modules = (await loadEffectiveModules(capabilities, runtime.cwd)).modules;
   } catch {
     // A bad config story is surfaced by the real commands; the colophon degrades
-    // to the static (bundled) modules rather than failing the narrative.
+    // to the static modules rather than failing the narrative. (A bad PACKAGE
+    // story never throws — it is dropped and reported by doctor.)
   }
 
   for (const module of modules) {

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

@@ -7,6 +7,7 @@
  * `infoVerb` / `doctorVerb` / `capabilitiesVerb`.
  */
 
+import { BIN_NAME } from "../../constants.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
 import type { CapabilityModule, VerbSpec } from "../../kernel/spec/types.js";
 import { colophonFormatters } from "./colophon.render.js";
@@ -14,14 +15,17 @@ 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.",
+  summary: `Narrate how ${BIN_NAME} and the active domain are made.`,
+  doc: `Storeless — a colophon for the toolchain. Prints the story the distribution declares for itself (its config's \`colophon\`) 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",
+      cmd: `${BIN_NAME} colophon`,
+      note: "the toolchain + active domain story",
+    },
+    {
+      cmd: `${BIN_NAME} colophon --format llm`,
       note: "condensed Markdown for agents",
     },
   ],