@canonical/pragma-cli 0.32.0 → 0.34.0

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"
@@ -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.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

@@ -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.",
-  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.",
+  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,16 +26,28 @@ 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, 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_tier and config_channel.",
+    "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;
 
 /** The output modes v2 renders (dropped "text" → "plain"; condensed retired). */
@@ -79,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

@@ -7,11 +7,12 @@
  * 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,
- * graph_query, setup, upgrade, doctor, capabilities, prompt_*, token_add-config,
- * sources_*, tier_lookup, create_*) are authored here.
+ * shell's `domains/llm/data/toolCatalog.ts`; the net-new v2 tools (config_set,
+ * 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",
@@ -93,15 +94,19 @@ 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",
-    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",
@@ -166,29 +171,14 @@ 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",
-    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",
@@ -202,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/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[];