@canonical/pragma-cli 0.38.0 → 0.40.0

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

@@ -137,7 +137,7 @@ describe("block list parity — the declared, tier-scoped list", () => {
       {},
       withConfig("global", "experimental"),
     )) as PackPage;
-    expect(scoped.scope).toEqual({ tiers: ["global"] });
+    expect(scoped.scope?.tiers).toEqual(["global"]);
     expect(scoped.rows.map((row) => row.name)).toEqual([
       "Button",
       "Button Icon",

package/src/capabilities/callRule.test.ts

@@ -0,0 +1,147 @@
+/**
+ * The rule every tool is held to.
+ *
+ * 1. Every registered verb states the question it answers (`useWhen`, as a
+ *    bare clause), and declares an example call when it has a required param —
+ *    a verb callable with no arguments has nothing an example would teach.
+ * 2. Every call anywhere names a registered verb and carries params that
+ *    validate against that verb's OWN MCP input schema, so none can rot.
+ *
+ * The verbs, their examples and the stories' empty-state recoveries are DERIVED
+ * from the registry and `declaredStories`. The generic dead ends are constants
+ * their renderers export, and are imported below by name: a new one has to be
+ * added here. Error recoveries are built where they are thrown and cannot be
+ * listed at all; `testing/setupCallChecking.ts` holds each to the same
+ * validator as it is constructed, and the last case proves that is live.
+ */
+
+import { describe, expect, it } from "vitest";
+import { DEFAULT_EMPTY_RECOVERY } from "../kernel/packs/renderPack.js";
+import { renderCall } from "../kernel/spec/call.js";
+import { exampleCall } from "../kernel/spec/guidance.js";
+import type { Call, VerbSpec } from "../kernel/spec/index.js";
+import { wireType } from "../kernel/spec/wireType.js";
+import { findCallProblem } from "../testing/helpers/callSchema.js";
+import { declaredStories } from "./distribution.js";
+import { EMPTY_QUERY_CALLS } from "./graph/query.render.js";
+import { capabilities } from "./index.js";
+import {
+  BUILD_STORE_CALL,
+  LINK_SKILLS_CALL,
+  VERBOSE_BUILD_CALL,
+} from "./shared/calls.js";
+
+const verbs: readonly VerbSpec[] = capabilities
+  .flatMap((module) => module.verbs)
+  .filter((verb) => !verb.hidden);
+const byPath = new Map(verbs.map((verb) => [verb.path.join(" "), verb]));
+const findProblem = (call: Call): string | undefined =>
+  findCallProblem(call, byPath.get(call.verb));
+const label = (verb: VerbSpec): string => verb.path.join(" ");
+
+const storyEmpties = [...declaredStories.values()].flatMap((story) =>
+  [story.list, ...(story.verbs ?? [])].flatMap((half) =>
+    half?.emptyRecovery?.call ? [half.emptyRecovery.call] : [],
+  ),
+);
+
+describe("every tool states the question it answers", () => {
+  it("every registered verb declares useWhen, as a clause the prose can lead", () => {
+    expect(verbs.filter((verb) => !verb.useWhen).map(label)).toEqual([]);
+    // The lead ("Use …") is added where prose needs it; stored, it would be
+    // said twice in the catalogue's `use_when` field.
+    expect(
+      verbs.filter((verb) => /^use\b|\.$/i.test(verb.useWhen ?? "")).map(label),
+    ).toEqual([]);
+  });
+
+  it("every verb with a required param declares an example, and none is empty", () => {
+    const needs = verbs.filter((verb) => verb.params.some((p) => p.required));
+    expect(needs.filter((verb) => !verb.example).map(label)).toEqual([]);
+    expect(
+      verbs
+        .filter(
+          (verb) => verb.example && Object.keys(verb.example).length === 0,
+        )
+        .map(label),
+    ).toEqual([]);
+  });
+});
+
+describe("an example teaches batching", () => {
+  it("shows every list-accepting param as an array of at least two distinct values", () => {
+    // Recorded: a model that knew `symbol` was a list still made twenty calls
+    // of one symbol each — the example it had been shown held a single string.
+    const single = verbs.flatMap((verb) =>
+      verb.params
+        .filter((param) => wireType(param).list && verb.example?.[param.name])
+        .filter((param) => {
+          const value = verb.example?.[param.name];
+          return !Array.isArray(value) || new Set(value).size < 2;
+        })
+        .map((param) => `${label(verb)} { ${param.name} }`),
+    );
+    expect(single).toEqual([]);
+  });
+});
+
+describe("every call names a registered verb and params its schema accepts", () => {
+  const calls: readonly (readonly [string, Call])[] = [
+    ...verbs.flatMap((verb) => {
+      const call = exampleCall(verb);
+      return call ? [[`example of ${call.verb}`, call] as const] : [];
+    }),
+    ...storyEmpties.map(
+      (call) => [`story empty → ${call.verb}`, call] as const,
+    ),
+    ["default empty", DEFAULT_EMPTY_RECOVERY.call as Call],
+    ["empty query → catalogue", EMPTY_QUERY_CALLS.catalogue],
+    ["empty query → namespaces", EMPTY_QUERY_CALLS.namespaces],
+    ["build the store", BUILD_STORE_CALL],
+    ["build the store, verbosely", VERBOSE_BUILD_CALL],
+    ["link skills", LINK_SKILLS_CALL],
+  ];
+
+  it("holds for every example, story empty and generic dead end", () => {
+    const offenders = calls.flatMap(([name, call]) => {
+      const problem = findProblem(call);
+      return problem ? [`${name}: ${problem}`] : [];
+    });
+    expect(offenders).toEqual([]);
+    // Guard against a vacuous pass: the stories do declare empties.
+    expect(storyEmpties.length).toBeGreaterThan(0);
+  });
+
+  it("the validator is the verb's tool schema: it knows confirm and detail, and rejects the rest", () => {
+    // A next step or an example NEVER skips the plan: a mutating tool is
+    // plan-first, and the plan it returns says how to proceed.
+    expect(
+      findProblem({ verb: "sources update", params: { confirm: true } }),
+    ).toMatch(/confirm/i);
+    expect(
+      findProblem({ verb: "sources update", params: { skipInvalid: true } }),
+    ).toBeUndefined();
+    expect(
+      findProblem({
+        verb: "block lookup",
+        params: { name: ["Button"], detail: "summary" },
+      }),
+    ).toBeUndefined();
+    expect(
+      findProblem({ verb: "block list", params: { confirm: true } }),
+    ).toMatch(/confirm/i);
+    expect(
+      findProblem({ verb: "standard sample", params: { count: 2 } }),
+    ).toMatch(/count/);
+  });
+
+  it("checks a recovery as it is built, anywhere in this suite", () => {
+    expect(() => renderCall({ verb: "no such verb" }, "cli")).toThrow(
+      /names no registered verb/,
+    );
+    expect(() =>
+      renderCall({ verb: "config unset", params: { field: "tier" } }, "mcp"),
+    ).toThrow(/Unsound call config unset/);
+    expect(() => renderCall({ verb: "graph inspect" }, "cli")).toThrow(/uri/);
+  });
+});

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

@@ -4,12 +4,13 @@ import { join } from "node:path";
 import { describe, expect, it } from "vitest";
 import { executeVerb } from "../../kernel/project/cli/dispatch.js";
 import { bootRuntime } from "../../kernel/runtime/boot.js";
-import { emitSurface } from "../../kernel/spec/emitSurface.js";
+import { renderCall } from "../../kernel/spec/call.js";
+import { emitSurface, toolName } from "../../kernel/spec/emitSurface.js";
+import { exampleCall } from "../../kernel/spec/guidance.js";
 import type { GlobalFlags, VerbSpec } from "../../kernel/spec/types.js";
 import { capabilities } from "../index.js";
 import { capabilitiesSelfVerb } from "./capabilities.verb.js";
-import { buildCapabilitiesData, liveTools, mutatingTools } from "./catalog.js";
-import { TOOL_HINTS } from "./hints.js";
+import { buildCapabilitiesData, liveTools } from "./catalog.js";
 import type { CapabilitiesData } from "./types.js";
 
 const NO_MUT = { dryRun: false, undo: false, yes: false };
@@ -23,27 +24,54 @@ const FLAGS: GlobalFlags = {
 const freshCwd = (): string => mkdtempSync(join(tmpdir(), "pragma-caps-"));
 const tools = liveTools(capabilities);
 const data = buildCapabilitiesData(capabilities);
+/** The tools whose verbs mutate, read straight off the registry. */
+const mutating = new Set(
+  capabilities
+    .flatMap((module) => module.verbs)
+    .filter((verb) => verb.capability.mutates && verb.capability.mcp.expose)
+    .map((verb) => toolName(verb.path)),
+);
 
 describe("capabilities catalog — grammar-derived, drift-guarded (PROTECTED)", () => {
-  it("every live tool has a TOOL_HINTS entry (no missing hint)", () => {
-    const missing = tools.filter((tool) => !(tool in TOOL_HINTS));
-    expect(missing).toEqual([]);
+  // The catalogue has no table of its own to drift: each entry is read off the
+  // tool's verb. That every verb DECLARES its guidance is `callRule.test.ts`.
+  it("every entry is its own verb's guidance: question, category, example", () => {
+    const verbs = new Map(
+      capabilities.flatMap((module) =>
+        module.verbs.map((verb) => [toolName(verb.path), verb] as const),
+      ),
+    );
+    for (const tool of data.tools) {
+      const verb = verbs.get(tool.name) as VerbSpec;
+      expect(tool.use_when, tool.name).toBe(verb.useWhen);
+      const example = exampleCall(verb);
+      expect(tool.example, tool.name).toBe(
+        example ? renderCall(example, "mcp") : undefined,
+      );
+    }
   });
 
-  it("no TOOL_HINTS key is stale (every hint names a live tool)", () => {
-    const live = new Set(tools);
-    const stale = Object.keys(TOOL_HINTS).filter((name) => !live.has(name));
-    expect(stale).toEqual([]);
+  it("a verb declaring no guidance (a third-party story may) degrades to its summary", () => {
+    const {
+      useWhen: _useWhen,
+      example: _example,
+      ...bare
+    } = capabilitiesSelfVerb;
+    const [tool] = buildCapabilitiesData([
+      { name: "capabilities", verbs: [bare as VerbSpec] },
+    ]).tools;
+    expect(tool).toEqual({
+      name: "capabilities",
+      category: "orientation",
+      use_when: capabilitiesSelfVerb.summary,
+    });
   });
 
-  it("hint categories agree with the live surface (write ⟺ mutates)", () => {
-    const mutating = mutatingTools(capabilities);
-    for (const tool of tools) {
-      const isWrite = TOOL_HINTS[tool]?.category === "write";
-      expect(
-        isWrite,
-        `${tool}: hint category "${TOOL_HINTS[tool]?.category}" vs mutates=${mutating.has(tool)}`,
-      ).toBe(mutating.has(tool));
+  it("categories agree with the live surface (write ⟺ mutates)", () => {
+    for (const tool of data.tools) {
+      expect(tool.category === "write", tool.name).toBe(
+        mutating.has(tool.name),
+      );
     }
   });
 
@@ -67,7 +95,7 @@ describe("capabilities catalog — grammar-derived, drift-guarded (PROTECTED)",
     ).toBe(counts.total);
     expect(counts.orientation).toBe(1); // exactly `capabilities`
     expect(counts.diagnostic).toBe(2); // `doctor` + `info`
-    expect(counts.write).toBe(mutatingTools(capabilities).size);
+    expect(counts.write).toBe(mutating.size);
   });
 
   it("the discovery sequence's sample stage lists the live *_sample tools", () => {

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

@@ -31,6 +31,8 @@ const capabilitiesVerb: VerbSpec<Record<string, unknown>, CapabilitiesData> = {
   path: ["capabilities"],
   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.",
+  useWhen: "when unsure which tool answers a question",
+  category: "orientation",
   params: [],
   output: { formatters: capabilitiesFormatters },
   examples: [

package/src/capabilities/capabilities/catalog.ts

@@ -3,21 +3,28 @@
  *
  * `buildCapabilitiesData(modules)` projects the LIVE grammar: it emits the
  * surface, walks `mcpSurface.tools` (the sorted, covenant-conformant set), and
- * annotates each tool from the authored `TOOL_HINTS` table. The tool set, the
+ * annotates each tool from the guidance its OWN verb declares (`useWhen`,
+ * `example` — see `kernel/spec/guidance.ts`). The tool set, the
  * category counts, and the discovery-sample list are all DERIVED — never pinned
  * — so the catalog tracks the surface automatically (the fix for the old shell's
  * hand-maintained list, which drifted to name retired tools).
  *
  * Pure + zod-free: it reads only `emitSurface` (itself fast-path-safe), so the
- * verb's storeless guarantee holds. The conventions + discovery strings are
- * exported so `kernel/project/mcp/instructions.ts` derives the handshake
- * orientation from the SAME source and the two can never diverge.
+ * verb's storeless guarantee holds. The conventions + discovery strings live
+ * here, on the distribution's side — they name its tools and tiers — and reach
+ * the kernel's handshake instructions as data ({@link ORIENTATION}), so the two
+ * can never diverge and the kernel names no tool.
  */
 
 import { BIN_NAME, PROGRAM_DESCRIPTION, VERSION } from "../../constants.js";
-import type { CapabilityModule } from "../../kernel/spec/index.js";
-import { emitSurface } from "../../kernel/spec/index.js";
-import { TOOL_HINTS } from "./hints.js";
+import { renderCall } from "../../kernel/spec/call.js";
+import { exampleCall, verbCategory } from "../../kernel/spec/guidance.js";
+import type {
+  CapabilityModule,
+  McpOrientation,
+  VerbSpec,
+} from "../../kernel/spec/index.js";
+import { emitSurface, toolName } from "../../kernel/spec/index.js";
 import type {
   CapabilitiesData,
   CatalogTool,
@@ -26,24 +33,11 @@ import type {
 } from "./types.js";
 
 /**
- * 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); `mutations` is new in v2, surfacing the
- * plan-first/confirm gate.
- *
- * `model` is the one that has had to be rewritten twice, and both times because
- * it was describing a gate that had moved. It stopped claiming reads were
- * tier/channel-scoped when the hand-written filtering was removed (the
- * hierarchy became graph data, not a query gate) — and "Reads are unscoped —
- * every list shows everything" became false the day the tier scope landed. An
- * agent reading it took a scoped `block_list` for the whole design system,
- * which is the exact misreading the sentence existed to prevent. So it now says
- * what is true of each half separately: the TIER hierarchy gates a read of a
- * tiered noun and names the argument that widens it, while the CHANNEL is still
- * data on the entity and gates nothing.
+ * The four orientation conventions — the single source both the `capabilities`
+ * tool and the MCP handshake read, so the two cannot contradict each other.
+ * `model` says what is true of each half separately: the TIER hierarchy scopes
+ * a read of a tiered noun and names the argument that widens it; the CHANNEL is
+ * data on the entity and scopes nothing.
  */
 export const CONVENTIONS = {
   // `help` is authored as a bare phrase (`--help` renders it as one), so the
@@ -52,31 +46,20 @@ export const CONVENTIONS = {
   // otherwise reads "recipe graph.. A CLI and MCP server…".
   system: `${BIN_NAME} — ${PROGRAM_DESCRIPTION} (a CLI and MCP server over a knowledge graph).`,
   model:
-    'The tier hierarchy (global > apps > apps_lxd) SCOPES every read of a tiered entity: lists answer from the top-level tiers, lookups prefer them. Pass tier: "<name>" for a tier plus its ancestors, or tier: "all" for every tier; each answer states its scope. Channels scope nothing.',
+    'Reads of tiered entities are SCOPED to the top-level tiers (global > apps > apps_lxd): pass tier: "<name>" for that tier plus its ancestors, or tier: "all". Each answer states its scope; channels scope nothing.',
   querying:
-    "All queries run against an RDF triple store. Prefixed IRIs (e.g. prefix:name) identify entities. Use ontology_list to discover the active namespaces.",
+    "The data is an RDF graph; prefixed IRIs (prefix:name) identify entities, and ontology_list names the prefixes that exist.",
   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). */
-const OUTPUT_MODES = ["plain", "json", "llm"] as const;
-
-/** The set of tool names that mutate, read from the emitted surface. */
-function mutatingTools(modules: readonly CapabilityModule[]): Set<string> {
-  const mutating = new Set<string>();
-  for (const { verbs } of Object.values(emitSurface(modules).nouns)) {
-    for (const verb of verbs) {
-      if (verb.mutates && typeof verb.mcp === "string") mutating.add(verb.mcp);
-    }
-  }
-  return mutating;
-}
-
-/** The live sorted tool names the covenant blesses, from the emitted surface. */
-export function liveTools(modules: readonly CapabilityModule[]): string[] {
-  return emitSurface(modules).mcpSurface.tools;
-}
+/**
+ * The words people use are not the noun the tools carry: an agent looking for a
+ * "component" tool finds none. Said exactly twice — here, in the handshake, and
+ * in `block_list`'s own `useWhen` — and not a third time in the catalogue.
+ */
+export const BLOCKS_SENTENCE =
+  "Components, patterns, layouts and subcomponents are all blocks: read every one of them through the block tools (block_list, block_lookup).";
 
 /**
  * Build the discovery sequence, deriving the sample list from the tools that
@@ -100,7 +83,7 @@ export function buildDiscoverySequence(
       stage: 2,
       tool: "sources_status",
       purpose:
-        "See which pack is answering. A fresh install answers reads from the snapshot shipped with the CLI 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.",
+        "See which pack is answering. A fresh install answers reads from the snapshot shipped with the CLI and needs no build; only an `unavailable` status requires sources_update, which is a project that declared its own packs and has not built them.",
     },
     {
       stage: 3,
@@ -111,11 +94,28 @@ export function buildDiscoverySequence(
       stage: 4,
       tool: "domain tools",
       purpose:
-        "Query specific entities — block_list, standard_lookup, etc. Use the use_when hints above to pick the right tool.",
+        "Query specific entities — block_list, standard_lookup, etc. Each tool description opens with the question it answers.",
     },
   ];
 }
 
+/**
+ * What the handshake instructions open with (see
+ * `kernel/project/mcp/instructions.ts`, which adds the generated question →
+ * tool index and states the plan-first rule beside the write tools it lists).
+ */
+export const ORIENTATION: McpOrientation = {
+  conventions: [CONVENTIONS.system, CONVENTIONS.model, BLOCKS_SENTENCE],
+};
+
+/** The output modes v2 renders (dropped "text" → "plain"; condensed retired). */
+const OUTPUT_MODES = ["plain", "json", "llm"] as const;
+
+/** The live sorted tool names the covenant blesses, from the emitted surface. */
+export function liveTools(modules: readonly CapabilityModule[]): string[] {
+  return emitSurface(modules).mcpSurface.tools;
+}
+
 /** Tally the catalog tools by category (all counts DERIVED, never pinned). */
 function countByCategory(tools: readonly CatalogTool[]): ToolCounts {
   const of = (category: CatalogTool["category"]) =>
@@ -140,15 +140,22 @@ export function buildCapabilitiesData(
   modules: readonly CapabilityModule[],
 ): CapabilitiesData {
   const tools = liveTools(modules);
+  const verbs = new Map(
+    modules.flatMap((module) =>
+      module.verbs.map((verb) => [toolName(verb.path), verb] as const),
+    ),
+  );
   const catalogTools: CatalogTool[] = tools.map((name) => {
-    const hint = TOOL_HINTS[name];
-    // A missing hint is a drift bug caught by `capabilities.test.ts`; degrade
-    // to a truthful placeholder rather than throwing inside a tool call.
+    // Every emitted tool IS a verb of these modules, so the lookup cannot miss.
+    const verb = verbs.get(name) as VerbSpec;
+    const example = exampleCall(verb);
+    // Missing guidance is a drift bug caught by `callRule.test.ts`; degrade to
+    // the summary rather than throwing inside a tool call.
     return {
       name,
-      category: hint?.category ?? "read",
-      use_when:
-        hint?.use_when ?? "(no hint authored — see capabilities/hints.ts)",
+      category: verbCategory(verb),
+      use_when: verb.useWhen ?? verb.summary,
+      ...(example ? { example: renderCall(example, "mcp") } : {}),
     };
   });
 
@@ -161,5 +168,3 @@ export function buildCapabilitiesData(
     limits: { output_modes: OUTPUT_MODES, condensed_available: false },
   };
 }
-
-export { mutatingTools };

package/src/capabilities/capabilities/index.ts

@@ -5,9 +5,11 @@
 
 import type { CapabilityModule } from "../../kernel/spec/index.js";
 import { capabilitiesSelfVerb } from "./capabilities.verb.js";
+import { ORIENTATION } from "./catalog.js";
 
 /** The `capabilities` capability module (a single storeless self-verb). */
 export const capabilitiesModule: CapabilityModule = {
   name: "capabilities",
   verbs: [capabilitiesSelfVerb],
+  mcpOrientation: ORIENTATION,
 };

package/src/capabilities/capabilities/types.ts

@@ -1,34 +1,31 @@
 /**
  * Types for the `capabilities` orientation tool.
  *
- * The catalog is DERIVED from the live grammar (`emitSurface`) plus an authored
- * hint table — never a hand-maintained tool list — so it cannot drift from the
- * real surface (the exact failure mode of the old shell's `TOOL_CATALOG`, which
- * still named retired tools). See {@link ToolHint} + `hints.ts` for the one
- * authored input, and `catalog.ts` for the derivation.
+ * The catalog is DERIVED from the live grammar (`emitSurface`) plus the guidance
+ * each verb declares — never a hand-maintained tool list — so it cannot drift
+ * from the real surface (the exact failure mode of the old shell's
+ * `TOOL_CATALOG`, which still named retired tools). See `catalog.ts` for the
+ * derivation.
  */
 
-/** A tool's behavioural category, used for grouping + counts. */
-export type ToolCategory = "read" | "write" | "orientation" | "diagnostic";
+import type { ToolCategory } from "../../kernel/spec/index.js";
 
-/** The one authored fact per tool: its category + a one-line "use when" hint. */
-export interface ToolHint {
-  readonly category: ToolCategory;
-  readonly use_when: string;
+export type { ToolCategory };
+
+/** A single stage in the discovery flow the `capabilities` answer lays out. */
+export interface DiscoveryStage {
+  readonly stage: number;
+  readonly tool: string;
+  readonly purpose: string;
 }
 
-/** One tool as it appears in the catalog — its live name plus its hint. */
+/** One tool as it appears in the catalog — its live name plus its verb's guidance. */
 export interface CatalogTool {
   readonly name: string;
   readonly category: ToolCategory;
   readonly use_when: string;
-}
-
-/** A single stage in the discovery flow an agent follows at session start. */
-export interface DiscoveryStage {
-  readonly stage: number;
-  readonly tool: string;
-  readonly purpose: string;
+  /** One real call, as an MCP tool call; absent only if the verb declares none. */
+  readonly example?: string;
 }
 
 /** Tool counts by category (all DERIVED from the live catalog, never pinned). */

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

@@ -14,9 +14,10 @@
  * it there is what lets these stay pure.
  */
 
-import { BIN_NAME } from "../../constants.js";
 import { defaultStyle, type RenderStyle } from "../../kernel/render/style.js";
-import type { Formatters } from "../../kernel/spec/index.js";
+import { renderNextStep } from "../../kernel/spec/call.js";
+import type { Formatters, Surface } from "../../kernel/spec/index.js";
+import { BUILD_STORE_CALL } from "../shared/calls.js";
 import { renderMarkdownToTerminal } from "./markdownTerminal.js";
 import type { ColophonData, ColophonSection } from "./types.js";
 
@@ -27,7 +28,9 @@ import type { ColophonData, ColophonSection } from "./types.js";
  * Like every empty state it goes to stderr with exit 0 (a calm success), so a
  * script reading stdout still reads nothing.
  */
-const EMPTY_NOTICE = `No colophon declared. A colophon comes from an active pack — build the store with \`${BIN_NAME} sources update\`.`;
+function describeEmpty(surface: Surface): string {
+  return `No colophon declared. A colophon comes from an active pack — build the store. ${renderNextStep(BUILD_STORE_CALL, surface)}`;
+}
 
 /** Render one section (title as H1 + body) as styled terminal Markdown. */
 function plainSection(section: ColophonSection, style: RenderStyle): string {
@@ -56,7 +59,7 @@ export const colophonFormatters: Formatters<ColophonData> = {
     // llm returns before the dispatcher's empty-state routing, so the
     // condensed form carries its own zero-section line (the same shape the
     // other empty states use) rather than handing an agent zero bytes.
-    if (data.sections.length === 0) return `_${EMPTY_NOTICE}_`;
+    if (data.sections.length === 0) return `_${describeEmpty("cli")}_`;
     return data.sections.map(llmSection).join("\n\n");
   },
 
@@ -66,5 +69,6 @@ export const colophonFormatters: Formatters<ColophonData> = {
 
   // Zero sections: the dispatcher routes this to stderr (exit 0) so plain
   // stdout stays empty; llm/json keep their own empty shapes.
-  notice: (data) => (data.sections.length === 0 ? EMPTY_NOTICE : undefined),
+  notice: (data, surface = "cli") =>
+    data.sections.length === 0 ? describeEmpty(surface) : undefined,
 };

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

@@ -17,6 +17,7 @@ const colophonVerb: VerbSpec<Record<string, unknown>, ColophonData> = {
   path: ["colophon"],
   summary: "Narrate how the active domain is made.",
   doc: `Storeless — the colophon each active pack declares for its domain. With no pack telling a story, it prints the one ${BIN_NAME} declares for itself instead; with neither, it says so. Also available as a condensed Markdown narration for agents, or as a structured JSON projection of the sections.`,
+  useWhen: "when asked which packs the data comes from",
   params: [],
   output: { formatters: colophonFormatters },
   examples: [

package/src/capabilities/config/get.verb.ts

@@ -39,6 +39,8 @@ const getVerb: VerbSpec<Record<string, unknown>, ConfigGetData> = {
   path: ["config", "get"],
   summary: "Print one resolved config value.",
   doc: "Reads the effective value of a single field after layering — built-in defaults, the global config, and the nearest project config. Prints the bare value (nothing when the field is unset), so the output substitutes directly into a shell.",
+  useWhen: "when asked for the value of one setting",
+  example: { key: "tier" },
   params: [
     {
       kind: "enum",

package/src/capabilities/config/runField.ts

@@ -12,7 +12,7 @@
 
 import { map, type Task } from "@canonical/task";
 import { writeConfigField } from "../../kernel/config/index.js";
-import { cliRecovery, PragmaError } from "../../kernel/error/index.js";
+import { callRecovery, PragmaError } from "../../kernel/error/index.js";
 import { type ConfigFieldSpec, RESERVED_CLEAR_VALUES } from "./fields.js";
 import type { ConfigFieldResult } from "./types.js";
 
@@ -34,8 +34,8 @@ export function runField(
 
   if (spec.kind === "string" && RESERVED_CLEAR_VALUES.includes(value)) {
     throw PragmaError.invalidInput(spec.field, value, {
-      recovery: cliRecovery(
-        `config unset ${spec.field}`,
+      recovery: callRecovery(
+        { verb: "config unset", params: { key: spec.field } },
         "Clear the field with the unset command.",
       ),
     });

package/src/capabilities/config/set.verb.ts

@@ -29,6 +29,9 @@ const setVerb: VerbSpec<Record<string, unknown>, ConfigFieldResult> = {
   path: ["config", "set"],
   summary: "Set a config field by name.",
   doc: "Write a global config field by name. `key` is one of `tier`, `channel`, or `detail`; clearing a field is `config unset <key>`'s job, and the values that used to double as clear-markers are refused. Written to the global layer only — project configs are authored by hand.",
+  useWhen:
+    "when asked to change a setting, such as making one product's tier the default for every read",
+  example: { key: "tier", value: "apps/lxd" },
   params: [
     {
       kind: "enum",

package/src/capabilities/config/show.verb.ts

@@ -18,6 +18,8 @@ const showVerb: VerbSpec<Record<string, unknown>, ConfigShowData> = {
   path: ["config", "show"],
   summary: "Show the resolved config and per-field provenance.",
   doc: `Merges built-in defaults, the global XDG config, and the nearest ${PROJECT_CONFIG_FILENAME}, marking which layer supplied each value.`,
+  useWhen:
+    "when asked how the tool is configured and which file set each value",
   params: [],
   output: { formatters: configShowFormatters },
   examples: [

package/src/capabilities/config/unset.verb.ts

@@ -23,6 +23,8 @@ const unsetVerb: VerbSpec<Record<string, unknown>, ConfigFieldResult> = {
   path: ["config", "unset"],
   summary: "Clear a config field by name.",
   doc: "Removes a field from the global config so the built-in default (or a project config) applies again. The counterpart of `config set` — setting writes a value, unsetting removes one; no value doubles as a remove-marker.",
+  useWhen: "when asked to put a setting back to its built-in default",
+  example: { key: "tier" },
   params: [
     {
       kind: "enum",

package/src/capabilities/create/constants.ts

@@ -2,8 +2,8 @@
  * The command-path ALLOWLIST of the `create` surface — the one list the
  * surface's mechanical copies derive from: the `CreateKind` union
  * (`types.ts`) and the generator lookup (`pickGenerator.ts`). Prose is NOT
- * derived: the verb summaries in `create.verb.ts` and
- * `capabilities/hints.ts` still name the frameworks by hand.
+ * derived: the verb summaries and `useWhen` sentences in `create.verb.ts`
+ * still name the frameworks by hand.
  *
  * This table is the SINGLE authoring point for which generator packages the
  * distribution ships: it binds each `create` noun to the command PATHS it