@canonical/pragma-cli 0.38.0 → 0.42.0

package/src/kernel/spec/call.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  quoteArgument,
+  quoteCall,
+  renderCall,
+  renderNextStep,
+} from "./call.js";
+
+describe("a call is spelled for the surface it is printed on", () => {
+  const call = { verb: "token lookup", params: { name: ["color.text"] } };
+
+  it("ends a dead end with a command on the CLI and a tool call over MCP", () => {
+    expect(renderNextStep(call, "cli")).toBe(
+      "Run `pragma token lookup color.text`.",
+    );
+    expect(renderNextStep(call, "mcp")).toBe(
+      'Call `token_lookup { name: ["color.text"] }`.',
+    );
+  });
+
+  it("a next step to a mutating tool never confirms: the tool is plan-first, and its plan says how to proceed", () => {
+    const update = { verb: "sources update" };
+    expect(renderNextStep(update, "mcp")).toBe("Call `sources_update {}`.");
+    expect(renderNextStep(update, "cli")).toBe("Run `pragma sources update`.");
+    expect(renderCall(update, "mcp")).toBe("sources_update {}");
+  });
+
+  it("a verb withheld from MCP is spelled as the command it is, on both surfaces", () => {
+    expect(renderNextStep({ verb: "setup skills" }, "mcp")).toBe(
+      "Run `pragma setup skills`.",
+    );
+  });
+
+  it("carries global CLI flags on the command only", () => {
+    const verbose = { verb: "sources update", cliFlags: ["--verbose"] };
+    expect(renderCall(verbose, "cli")).toBe("pragma sources update --verbose");
+    expect(renderCall(verbose, "mcp")).toBe("sources_update {}");
+  });
+
+  it("spells flags the way the CLI parses them", () => {
+    // A default-true boolean is negated; a default-false one is simply absent.
+    expect(
+      renderCall(
+        {
+          verb: "create package",
+          params: { name: "x", runInstall: false, withCli: false },
+        },
+        "cli",
+      ),
+    ).toBe("pragma create package --name x --no-run-install");
+    // `undefined` is not an argument, on either surface.
+    const sparse = {
+      verb: "ontology lookup",
+      params: { prefix: "ds", class: undefined },
+    };
+    expect(renderCall(sparse, "mcp")).toBe('ontology_lookup { prefix: "ds" }');
+    expect(renderCall(sparse, "cli")).toBe("pragma ontology lookup ds");
+  });
+
+  it("fences a flag-like positional, and quotes a call containing a backtick safely", () => {
+    expect(
+      quoteCall({ verb: "graph inspect", params: { uri: "-x" } }, "cli"),
+    ).toBe("`pragma graph inspect -- -x`");
+    expect(
+      quoteCall(
+        { verb: "graph query", params: { sparql: 'ASK { ?s ?p "`" }' } },
+        "mcp",
+      ),
+    ).toMatch(/^`` graph_query .* ``$/);
+    expect(quoteArgument("channelOf", "x", "cli")).toBe("`--channel-of x`");
+    // Shell-quoted like any other word, so the printed flag can be pasted.
+    expect(quoteArgument("search", "two words; rm", "cli")).toBe(
+      "`--search 'two words; rm'`",
+    );
+    expect(quoteArgument("channelOf", "x", "mcp")).toBe('`channelOf: "x"`');
+  });
+
+  it("outside the suite's checking, renders an undeclared verb's params as flags rather than throwing", async () => {
+    // A shipped process never enables checking, and this runs inside error
+    // rendering — a second failure there helps no one. A fresh module instance
+    // is the unchecked, undeclared state a shipped process starts in.
+    vi.resetModules();
+    const fresh = await import("./call.js");
+    expect(
+      fresh.renderCall(
+        { verb: "widget list", params: { kind: "input" } },
+        "cli",
+      ),
+    ).toBe("pragma widget list --kind input");
+    expect(fresh.callTool({ verb: "widget list" })).toEqual({
+      tool: "widget_list",
+      params: {},
+    });
+  });
+});

package/src/kernel/spec/call.ts

@@ -0,0 +1,186 @@
+/**
+ * A call: one verb plus the params to make it with — the single type behind
+ * every example and every recovery.
+ *
+ * An author names the call ONCE and both spellings derive from it:
+ * `token_lookup { name: ["color.text"] }` for an agent on MCP,
+ * `pragma token lookup color.text` for a person at a terminal. A hand-typed
+ * pair can disagree, and a hand-typed string cannot be checked against the
+ * verb it names, where a call can (`capabilities/callRule.test.ts`).
+ *
+ * The CLI spelling needs facts the call does not carry — which params are
+ * positional, which booleans default to true, whether the verb mutates. They
+ * live on the verb, so the projectors declare their verbs here as they boot
+ * ({@link declareVerbs}). A call naming a verb nobody declared renders every
+ * param as a flag rather than throwing: this runs inside error rendering,
+ * where a second failure helps no one.
+ *
+ * NOT derivable here: a noun whose CLI is mounted by its own projection
+ * (`create`, whose commands carry a generator segment the verb's params do
+ * not). Its calls spell correctly as tool calls only.
+ *
+ * Zod-free: it is reachable from the `--help` path.
+ */
+
+import { RECOVERY_CLI_PREFIX } from "../../constants.js";
+import { kebabCase, toolName } from "./emitSurface.js";
+import type { Call, Surface, VerbSpec } from "./types.js";
+
+const declared = new Map<string, VerbSpec>();
+let findProblem:
+  | ((call: Call, verb: VerbSpec | undefined) => string | undefined)
+  | undefined;
+
+/**
+ * Declare the verbs a call may name. Additive, so a fixture's verbs join the
+ * distribution's rather than replacing them.
+ *
+ * @note Impure — fills the module-level index {@link renderCall} reads. A call
+ *   is rendered deep inside error construction and formatters, which hold no
+ *   registry to pass in.
+ */
+export function declareVerbs(verbs: readonly VerbSpec[]): void {
+  for (const verb of verbs) declared.set(verb.path.join(" "), verb);
+}
+
+/**
+ * Make every rendered call prove itself. The test setup installs the ONE
+ * validator — the verb's real MCP input schema — so a recovery built on any
+ * line a test runs is checked exactly as the conformance test checks examples.
+ * It is handed the DECLARED verb the call names, so a fixture that declares its
+ * verbs is held to them too.
+ *
+ * @note Impure — sets module-level state; never installed in a shipped process.
+ */
+export function checkCallsWith(
+  validator: (call: Call, verb: VerbSpec | undefined) => string | undefined,
+): void {
+  findProblem = validator;
+}
+
+/** The tool name a call addresses (`"sources update"` → `sources_update`). */
+function callToolName(call: Call): string {
+  return toolName(call.verb.split(" ") as [string, string?]);
+}
+
+/**
+ * Build (or rebuild) the store from the configured packs — the one call the
+ * kernel itself points at, from every unavailable store and every empty list.
+ * Named once, here, because the kernel owns the verb's name.
+ */
+export const BUILD_STORE_CALL: Call = { verb: "sources update" };
+
+/** The MCP tool a recovery names, or nothing when its verb is withheld from MCP. */
+export function callTool(
+  call: Call,
+): { tool: string; params: Record<string, unknown> } | undefined {
+  if (declared.get(call.verb)?.capability.mcp.expose === false) {
+    return undefined;
+  }
+  return { tool: callToolName(call), params: { ...call.params } };
+}
+
+/** Quote a CLI word unless the shell would read it bare. */
+function quoteWord(value: unknown): string {
+  const word = String(value);
+  return /^[\w.:/@=,+-]+$/.test(word)
+    ? word
+    : `'${word.replaceAll("'", "'\\''")}'`;
+}
+
+/** The CLI spelling: global flags, then flags, then positionals in the verb's order. */
+function renderCliCall(call: Call): string {
+  const params = call.params ?? {};
+  const specs = declared.get(call.verb)?.params ?? [];
+  const positional = specs.filter((p) => p.positional).map((p) => p.name);
+  const flags: string[] = [];
+  for (const [name, value] of Object.entries(params)) {
+    if (positional.includes(name) || value === undefined) continue;
+    const flag = `--${kebabCase(name)}`;
+    if (typeof value === "boolean") {
+      const spec = specs.find((p) => p.name === name);
+      const defaultsTrue = spec?.kind === "boolean" && spec.default === true;
+      if (value) flags.push(flag);
+      else if (defaultsTrue) flags.push(`--no-${kebabCase(name)}`);
+      continue;
+    }
+    // A list-valued flag is repeated, one value each.
+    for (const item of [value].flat()) flags.push(`${flag} ${quoteWord(item)}`);
+  }
+  const words = positional
+    .filter((name) => params[name] !== undefined)
+    .flatMap((name) => [params[name]].flat().map(quoteWord));
+  // A positional that looks like a flag needs the end-of-options marker.
+  const guard = words.some((word) => word.startsWith("-")) ? ["--"] : [];
+  return [
+    `${RECOVERY_CLI_PREFIX}${call.verb}`,
+    ...(call.cliFlags ?? []),
+    ...flags,
+    ...guard,
+    ...words,
+  ].join(" ");
+}
+
+/** The MCP spelling: the tool name and its argument bag. */
+function renderMcpCall(call: Call): string {
+  const body = Object.entries(call.params ?? {})
+    .filter(([, value]) => value !== undefined)
+    .map(([name, value]) => `${name}: ${JSON.stringify(value)}`)
+    .join(", ");
+  return `${callToolName(call)} ${body ? `{ ${body} }` : "{}"}`;
+}
+
+/**
+ * Spell a call for the surface it is about to be printed on.
+ *
+ * @param call - The verb and params to make.
+ * @param surface - `"cli"` for a command line, `"mcp"` for a tool call.
+ * @returns `pragma token lookup color.text`, or `token_lookup { name: ["color.text"] }`.
+ * @throws Error when a validator is installed (tests only) and rejects the call.
+ */
+export function renderCall(call: Call, surface: Surface): string {
+  const problem = findProblem?.(call, declared.get(call.verb));
+  if (problem) throw new Error(`Unsound call ${call.verb}: ${problem}`);
+  return spellingFor(call, surface) === "mcp"
+    ? renderMcpCall(call)
+    : renderCliCall(call);
+}
+
+/**
+ * A verb withheld from MCP has no tool to name, so even over MCP it is spelled
+ * as the command it is — something an agent can hand to its user.
+ */
+function spellingFor(call: Call, surface: Surface): Surface {
+  return declared.get(call.verb)?.capability.mcp.expose === false
+    ? "cli"
+    : surface;
+}
+
+/**
+ * One argument, quoted as code, in the surface's own spelling: `--tier all` on
+ * the CLI, `tier: "all"` over MCP. For the sentences that name an argument to
+ * change rather than a whole call to make. The CLI value is shell-quoted like
+ * any other word, so what is printed can be pasted.
+ */
+export function quoteArgument(
+  name: string,
+  value: string | number,
+  surface: Surface,
+): string {
+  return surface === "mcp"
+    ? `\`${name}: ${JSON.stringify(value)}\``
+    : `\`--${kebabCase(name)} ${quoteWord(value)}\``;
+}
+
+/** A call quoted as code; one containing a backtick takes the doubled fence. */
+export function quoteCall(call: Call, surface: Surface): string {
+  const text = renderCall(call, surface);
+  return text.includes("`") ? `\`\` ${text} \`\`` : `\`${text}\``;
+}
+
+/** The sentence that ends a dead end: the exact next call, for this surface. */
+export function renderNextStep(call: Call, surface: Surface): string {
+  return spellingFor(call, surface) === "mcp"
+    ? `Call ${quoteCall(call, surface)}.`
+    : `Run ${quoteCall(call, surface)}.`;
+}

package/src/kernel/spec/emitReference.ts

@@ -24,6 +24,7 @@ import {
   toolName,
   verbLabel,
 } from "./emitSurface.js";
+import { describeTool, useWhenSentence } from "./guidance.js";
 import type {
   CapabilityModule,
   Example,
@@ -31,6 +32,7 @@ import type {
   ReferenceCliSyntax,
   VerbSpec,
 } from "./types.js";
+import { formatWireType, wireType } from "./wireType.js";
 
 /** The reference doc set: relative path under `docs/reference/` → file content. */
 export type ReferenceDocs = ReadonlyMap<string, string>;
@@ -122,19 +124,11 @@ function formatFlagValue(param: ParamSpec): string {
 }
 
 /**
- * The tool-schema type label a param projects to (mirrors `buildZodSchema`).
- * Enum values are comma-joined (never pipe-joined) so the label is safe inside
- * a Markdown table cell without escaping.
+ * The tool-schema type label a param projects to: the SAME {@link wireType}
+ * `buildZodSchema` validates against, printed — never a mirror of it.
  */
 function formatParamType(param: ParamSpec): string {
-  switch (param.kind) {
-    case "enum":
-      return `enum(${param.values.join(", ")})`;
-    case "string[]":
-      return "string[]";
-    default:
-      return param.kind;
-  }
+  return formatWireType(wireType(param));
 }
 
 /** Render a default value for prose (strings verbatim, everything else stringified). */
@@ -260,6 +254,7 @@ function renderCommandSection(
     `### ${formatInvocation(verb)}`,
     verb.summary,
     verb.doc ?? "",
+    useWhenSentence(verb) ?? "",
     `\`\`\`\n${syntax ? `${BIN_NAME} ${syntax.usage}` : formatUsage(verb)}\n\`\`\``,
     formatArgsTable(verb.params, syntax?.positionalTokens),
     formatFlagsTable(verb.params, syntax?.flagTokens),
@@ -410,7 +405,8 @@ function formatToolAnnotations(verb: VerbSpec): string {
 function renderToolSection(verb: VerbSpec): string {
   const blocks = [
     `### ${toolName(verb.path)}`,
-    verb.doc ?? verb.summary,
+    // The description an agent is actually served, from the one generator.
+    describeTool(verb),
     formatToolAnnotations(verb),
     "**Input**",
     formatToolParams(verb),
@@ -451,7 +447,7 @@ function renderNonToolSurface(modules: readonly CapabilityModule[]): string {
     );
   }
   bullets.push(
-    "- **Instructions**: the server always sends handshake instructions describing the conventions and the discovery sequence.",
+    "- **Instructions**: the server always sends handshake instructions: the conventions, and a generated index of tools by the question each answers, fitted to 2,000 characters.",
   );
   return `## Non-tool surface\n\n${bullets.join("\n")}`;
 }

package/src/kernel/spec/emitSurface.ts

@@ -16,6 +16,14 @@ export function kebabCase(name: string): string {
   return name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
 }
 
+/**
+ * The ceiling on the whole MCP tool catalogue (name + description + input
+ * schema per tool, ~4 characters a token). ONE constant: the emitted surface
+ * states it, the covenant freezes it, and the eval case enforces it. Set from
+ * measurement plus about a tenth — `BUDGETS.md` records each raise.
+ */
+export const CONDENSED_SDL_TOKEN_BUDGET = 9600;
+
 /** The MCP tool name for a verb path (`["config","show"]` -> `config_show`). */
 export function toolName(path: readonly [string, string?]): string {
   const [noun, verb] = path;
@@ -147,7 +155,7 @@ export const FIXED_SURFACE = {
     projectConfigLoad: "<10ms",
     warmStoreVerb: "<300ms",
     mcpP95Warm: "<100ms",
-    condensedSDL: "<=8000 tokens",
+    condensedSDL: `<=${CONDENSED_SDL_TOKEN_BUDGET} tokens`,
   },
 } as const;
 

package/src/kernel/spec/guidance.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+import { capabilities } from "../../capabilities/index.js";
+import { describeTool, useWhenSentence, verbCategory } from "./guidance.js";
+import type { VerbSpec } from "./types.js";
+
+const find = (path: string): VerbSpec =>
+  capabilities
+    .flatMap((module) => module.verbs)
+    .find((verb) => verb.path.join(" ") === path) as VerbSpec;
+
+describe("the one generator of tool guidance", () => {
+  it("leads with the question, adds authored prose, ends with the example", () => {
+    const lookup = find("token lookup");
+    const description = describeTool(lookup);
+    expect(description.startsWith(`Use ${lookup.useWhen}.`)).toBe(true);
+    expect(description).toContain(lookup.doc);
+    expect(
+      description.endsWith(
+        'Example: token_lookup { name: ["color.text","color.border"] }.',
+      ),
+    ).toBe(true);
+  });
+
+  it("does not repeat the one-line summary after the question, and shows no example for a verb callable bare", () => {
+    const list = find("skill list");
+    expect(list.doc).toBeUndefined();
+    expect(describeTool(list)).toBe(useWhenSentence(list));
+  });
+
+  it("falls back to doc or summary for a verb declaring no question (a third-party story may)", () => {
+    const { useWhen: _useWhen, doc: _doc, ...bare } = find("skill list");
+    expect(describeTool(bare as VerbSpec)).toBe(bare.summary);
+    expect(useWhenSentence(bare as VerbSpec)).toBeUndefined();
+  });
+
+  it("does not add a second example to a description that still hand-types one", () => {
+    const legacy = {
+      ...find("token lookup"),
+      doc: 'Get a token. Example: token_lookup { name: ["x"] }.',
+    } as VerbSpec;
+    expect(describeTool(legacy).match(/Example:/g)).toHaveLength(1);
+  });
+
+  it("derives write from mutates, and reads the rest off the verb", () => {
+    expect(verbCategory(find("sources update"))).toBe("write");
+    expect(verbCategory(find("doctor"))).toBe("diagnostic");
+    expect(verbCategory(find("block list"))).toBe("read");
+  });
+});

package/src/kernel/spec/guidance.ts

@@ -0,0 +1,68 @@
+/**
+ * The ONE generator of tool guidance.
+ *
+ * A verb declares the question it answers (`useWhen`) and one real call
+ * (`example`) once. Everything a caller reads when choosing a tool is built
+ * here from those two and the summary: the MCP tool description, the
+ * `capabilities` catalogue entry, the verb's help and the reference. A sentence
+ * that lives in one place cannot be true in the catalogue and missing from the
+ * description, which is how an agent that never called `capabilities` came to
+ * choose between fifty tools without it.
+ *
+ * It names no tool: what the distribution says about its own tools arrives as
+ * data (a verb's fields, a module's `mcpOrientation`).
+ *
+ * Zod-free: the catalogue and help read it on the fast path.
+ */
+
+import { renderCall } from "./call.js";
+import type { Call, ToolCategory, VerbSpec } from "./types.js";
+
+/** A verb's category: `write` ⟺ it mutates, else what it declares, else `read`. */
+export function verbCategory(verb: VerbSpec): ToolCategory {
+  return verb.capability.mutates ? "write" : (verb.category ?? "read");
+}
+
+/**
+ * A verb's declared example as a call. A verb with no required param may
+ * declare none — called bare, its only call is its own name — and then none
+ * is rendered.
+ */
+export function exampleCall(verb: VerbSpec): Call | undefined {
+  return verb.example
+    ? { verb: verb.path.join(" "), params: verb.example }
+    : undefined;
+}
+
+/**
+ * `useWhen` as a sentence. It is stored as the bare clause ("when asked which
+ * components use a token") because the catalogue's field is already named
+ * `use_when`; prose adds the lead.
+ */
+export function useWhenSentence(verb: VerbSpec): string | undefined {
+  return verb.useWhen ? `Use ${verb.useWhen}.` : undefined;
+}
+
+/**
+ * The agent-facing MCP tool description: the question first — it is what a
+ * caller scanning fifty descriptions matches its task against — then what the
+ * tool returns when a richer `doc` is authored, then one call to copy. The
+ * one-line summary is the fallback for a verb declaring no question, never a
+ * second sentence after one: it says the same thing less usefully.
+ *
+ * @param verb - The verb to describe.
+ * @returns The description.
+ */
+export function describeTool(verb: VerbSpec): string {
+  const question = useWhenSentence(verb);
+  const example = exampleCall(verb);
+  const rendered = example && `Example: ${renderCall(example, "mcp")}.`;
+  return [
+    question,
+    verb.doc ?? (question ? undefined : verb.summary),
+    // A third-party description may still end in its own hand-typed example.
+    rendered && !verb.doc?.includes("Example:") ? rendered : undefined,
+  ]
+    .filter(Boolean)
+    .join(" ");
+}

package/src/kernel/spec/index.ts

@@ -23,14 +23,18 @@ export {
 export type { Covenant } from "./surfaceConformance.js";
 export { assertConforms, deepEqual } from "./surfaceConformance.js";
 export type {
+  Call,
   Capability,
   CapabilityModule,
   DisclosureSpec,
   Example,
   Formatters,
   McpAnnotations,
+  McpOrientation,
   McpResourceProvider,
   ParamComplete,
   ParamSpec,
+  Surface,
+  ToolCategory,
   VerbSpec,
 } from "./types.js";

package/src/kernel/spec/surfaceConformance.test.ts

@@ -84,8 +84,8 @@ describe("surface conformance (PROTECTED)", () => {
     );
   });
 
-  it("freezes exactly 49 designed MCP tools including info, the config family, colophon", () => {
-    expect(golden.mcpSurface.tools).toHaveLength(49);
+  it("freezes exactly 51 designed MCP tools including info, the config family, colophon", () => {
+    expect(golden.mcpSurface.tools).toHaveLength(51);
     expect(golden.mcpSurface.tools).toContain("info");
     expect(golden.mcpSurface.tools).toContain("config_show");
     expect(golden.mcpSurface.tools).toContain("config_get");

package/src/kernel/spec/types.ts

@@ -12,7 +12,28 @@
  */
 
 import type { Effect, Task } from "@canonical/task";
-import type { PragmaRuntime } from "../runtime/types.js";
+import type { InteractionRuntime, PragmaRuntime } from "../runtime/types.js";
+
+/** Where text is about to be printed — the projector driving the run. */
+export type Surface = InteractionRuntime["transport"];
+
+/**
+ * A verb path (`"sources update"`) and the params to call it with — the one
+ * type behind every example and every recovery (`call.ts` spells it).
+ */
+export interface Call {
+  readonly verb: string;
+  readonly params?: Readonly<Record<string, unknown>>;
+  /**
+   * GLOBAL CLI flags the command should carry (`--verbose`). They are not
+   * params of the verb and have no MCP counterpart, so only the CLI spelling
+   * renders them.
+   */
+  readonly cliFlags?: readonly string[];
+}
+
+/** A tool's behavioural category, used for grouping + counts. */
+export type ToolCategory = "read" | "write" | "orientation" | "diagnostic";
 
 /** MCP tool annotations mirrored onto exposed verbs. */
 export type McpAnnotations = {
@@ -115,8 +136,8 @@ export type ParamSpec =
        * A repeatable flag ACCUMULATES: `--category css --category git` is
        * the union, never last-wins (repetition is the sanctioned multi-value
        * form, and silently dropping all but the last value is data loss).
-       * CLI-side only: the MCP arg schema keeps its scalar shape, and the
-       * run body accepts one value or many.
+       * Over MCP the same param is an ARRAY that also takes one bare value
+       * (`spec/wireType.ts`); the run body accepts one value or many.
        */
       repeatable?: true;
     }
@@ -173,8 +194,9 @@ export type ParamSpec =
  *   mutes it (success-path guidance).
  * - `--format json` AND the MCP tool result: it rides the envelope as
  *   `meta.notice` (`project/cli/dispatch.ts#renderData`,
- *   `project/mcp/registerVerb.ts#emptyMeta` — the same key from the same seam,
- *   so the two MACHINE surfaces stay byte-equal). `data` keeps its uniform empty
+ *   `project/mcp/registerVerb.ts#noticeMeta` — the same key from the same
+ *   seam; the sentence differs only in how a next step inside it is spelled
+ *   for its surface). `data` keeps its uniform empty
  *   shape; `[]` stays `[]`. Without it an agent could not tell an unbuilt store,
  *   a mistyped filter and a genuinely empty result apart — all three were
  *   `{"ok":true,"data":[],"meta":{}}`.
@@ -191,7 +213,12 @@ export interface Formatters<T> {
   ) => string;
   readonly llm: (d: T) => string;
   readonly json: (d: T) => string;
-  readonly notice?: (d: T) => string | undefined;
+  /**
+   * `surface` says where the sentence is about to be printed, so a notice that
+   * ends in a next call spells it as a tool call on MCP and a command on the
+   * CLI (the default).
+   */
+  readonly notice?: (d: T, surface?: Surface) => string | undefined;
   /**
    * The MACHINE half of the notice seam: facts about the read that belong in
    * the envelope's `meta` as DATA, merged there by both projectors under the
@@ -200,7 +227,7 @@ export interface Formatters<T> {
    * `notice` is a sentence, and a sentence is the right shape for a human
    * reading stderr and the wrong shape for an agent deciding what to do next.
    * The standing case is the tier scope: `meta.scope` names the tiers a list
-   * answered from, so a caller that wants the rest can widen the read without
+   * answered from and counts the whole filtered answer per tier, so a caller that wants the rest can widen the read without
    * parsing prose for tier names. Both machine surfaces read this ONE seam, the
    * way they already read one `notice`, so CLI-JSON and MCP stay byte-equal.
    *
@@ -248,6 +275,24 @@ export interface VerbSpec<P = Record<string, unknown>, R = unknown> {
   readonly path: readonly [noun: string, verb?: string];
   readonly summary: string;
   readonly doc?: string;
+  /**
+   * The question a person would ask that this verb answers, in THEIR words, as
+   * a bare clause ("when asked which components use a token" — prose adds the
+   * "Use" lead, the catalogue's `use_when` field needs none). With {@link example} it is
+   * the one source of guidance: `guidance.ts` builds the MCP tool description,
+   * the `capabilities` catalogue and verb help from it, so none is typed twice.
+   * Optional in the type because a third-party story may omit it; every verb
+   * this distribution registers is held to it by `callRule.test.ts`.
+   */
+  readonly useWhen?: string;
+  /**
+   * One real call's params — the verb is this one, and both spellings derive.
+   * Required of a verb with a required param; a verb callable with no arguments
+   * declares none, because `tool {}` teaches nothing.
+   */
+  readonly example?: Readonly<Record<string, unknown>>;
+  /** The catalogue group, where it is not the default: a mutating verb is a `write`, any other a `read`. */
+  readonly category?: "orientation" | "diagnostic";
   readonly params: readonly ParamSpec[];
   readonly output: {
     schema?: unknown;
@@ -505,6 +550,16 @@ export interface CliProjection {
   ) => ReferenceCliSyntax | undefined;
 }
 
+/**
+ * What a distribution tells an agent at the MCP handshake, as DATA: the words
+ * that name its own tiers and nouns. The kernel adds the generated question →
+ * tool index and holds the whole to a hard length ceiling.
+ */
+export interface McpOrientation {
+  /** The sentences the instructions open with, in order. */
+  readonly conventions: readonly string[];
+}
+
 /** A capability module: a named bundle of verbs with optional boot/resources/prompts hooks. */
 export interface CapabilityModule {
   readonly name: string;
@@ -527,6 +582,8 @@ export interface CapabilityModule {
    */
   readonly story?: true;
   readonly boot?: (rt: PragmaRuntime) => void;
+  /** The handshake orientation (a module hook; one module declares it). */
+  readonly mcpOrientation?: McpOrientation;
   /** An optional MCP resource surface (NOT a VerbSpec field — a module hook). */
   readonly mcpResources?: McpResourceProvider;
   /**