@canonical/pragma-cli 0.38.0 → 0.40.0

package/src/kernel/packs/tierScope.test.ts

@@ -25,7 +25,8 @@ import { executeVerb } from "../project/cli/dispatch.js";
 import type { GlobalFlags, PragmaRuntime } from "../runtime/types.js";
 import type { VerbSpec } from "../spec/types.js";
 import { compilePack } from "./compile.js";
-import type { LookupOutput } from "./resolveEntity.js";
+import { lookupFormatters } from "./renderPack.js";
+import { GLOB_EXPANSION_CAP, type LookupOutput } from "./resolveEntity.js";
 import { buildTierHierarchy, resolveTierScope } from "./tierScope.js";
 import {
   distributionSource,
@@ -334,6 +335,7 @@ describe("a scoped answer says so, in every format", () => {
   it("the page carries the scope as data", async () => {
     expect((await page({})).scope).toEqual({
       tiers: ["global", "apps", "sites"],
+      counts: { global: 2, apps: 1, sites: 1, apps_lxd: 2, "no tier": 1 },
     });
     expect((await page({ tier: "all" })).scope).toBeUndefined();
   });
@@ -346,7 +348,7 @@ describe("a scoped answer says so, in every format", () => {
       withTier(undefined, LLM),
     );
     expect(outcome.stdout).toContain(
-      "## Widget (5, tier scope: global, apps, sites)",
+      "## Widget (5, tier scope: global 2, apps 1, sites 1, no tier 1)",
     );
   });
 
@@ -358,7 +360,8 @@ describe("a scoped answer says so, in every format", () => {
       withTier(undefined, LLM),
     );
     expect(outcome.stdout).toContain(
-      "## Widget (2, more exist, tier scope: global, apps, sites)",
+      // The counts are of the WHOLE answer, not of the two rows in hand.
+      "## Widget (2, more exist, tier scope: global 2, apps 1, sites 1, no tier 1)",
     );
   });
 
@@ -372,7 +375,9 @@ describe("a scoped answer says so, in every format", () => {
       withTier(undefined, PLAIN),
     );
     expect(outcome.stdout).toContain("Button");
-    expect(outcome.stderr).toContain("Tier scope: global, apps, sites.");
+    expect(outcome.stderr).toContain(
+      "Tier scope: global 2, apps 1, sites 1, no tier 1.",
+    );
     expect(outcome.stderr).toContain("`--tier all` for every tier");
   });
 
@@ -384,12 +389,72 @@ describe("a scoped answer says so, in every format", () => {
       withTier(undefined, JSON_FLAGS),
     );
     const envelope = JSON.parse(outcome.stdout as string);
-    expect(envelope.meta.scope).toEqual({ tiers: ["global", "apps", "sites"] });
-    expect(envelope.meta.notice).toContain("Tier scope: global, apps, sites.");
+    expect(envelope.meta.scope).toEqual({
+      tiers: ["global", "apps", "sites"],
+      counts: { global: 2, apps: 1, sites: 1, apps_lxd: 2, "no tier": 1 },
+    });
+    expect(envelope.meta.notice).toContain("Tier scope: global 2, apps 1,");
     // `data` keeps its shape: the bare row array it has always been.
     expect(Array.isArray(envelope.data)).toBe(true);
   });
 
+  it("counts the FILTERED answer, and names the tier a miss lives in", async () => {
+    // The case the breakdown is for: nothing in scope matches, and the answer
+    // still says which tier to pass.
+    const missed = await page({ search: "meter" });
+    expect(missed.rows).toEqual([]);
+    expect(missed.scope?.counts).toEqual({
+      global: 0,
+      apps: 0,
+      sites: 0,
+      apps_lxd: 1,
+    });
+    const outcome = await executeVerb(
+      verbFor(KIT, "list"),
+      { search: "meter" },
+      REAL,
+      withTier(undefined, LLM),
+    );
+    expect(outcome.stdout).toContain("other tiers: apps_lxd 1");
+  });
+
+  it("counts on the first page only, and a failed count never fails the list", async () => {
+    const first = await page({ limit: 2 });
+    expect(first.scope?.counts).toBeDefined();
+    const second = await page({ limit: 2, after: first.nextAfter });
+    expect(second.scope).toEqual({ tiers: ["global", "apps", "sites"] });
+
+    const failing: PragmaRuntime = {
+      ...rt,
+      query: {
+        ...rt.query,
+        sparql: (text: string) =>
+          text.includes("GROUP BY")
+            ? Promise.reject(new Error("count failed"))
+            : rt.query.sparql(text),
+      },
+    };
+    const answer = await page({}, failing);
+    expect(answer.rows).toHaveLength(5);
+    expect(answer.scope).toEqual({ tiers: ["global", "apps", "sites"] });
+  });
+
+  it("counts ROWS per tier: an entity in two tiers counts under each, and its row is returned once", async () => {
+    const { rt: twice } = await buildFixtureRuntime({
+      ttl: `${TTL}\nex:button ex:tier ex:apps .`,
+      prefixes: PREFIXES,
+    });
+    try {
+      const answer = (await verbFor(KIT, "list").run({}, twice)) as PackPage;
+      expect(answer.rows.filter((row) => row.name === "Button")).toHaveLength(
+        1,
+      );
+      expect(answer.scope?.counts).toMatchObject({ global: 2, apps: 2 });
+    } finally {
+      (await twice.store.get()).store.dispose();
+    }
+  });
+
   it("an unscoped read says nothing about a scope", async () => {
     const outcome = await executeVerb(
       verbFor(KIT, "list"),
@@ -425,6 +490,55 @@ describe("a lookup prefers the scope and falls back rather than refusing", () =>
       runtime,
     )) as LookupOutput;
 
+  it("a pattern applies the scope BEFORE the cap", async () => {
+    // Five LXD widgets sort ahead of 55 global ones; none of them takes a slot.
+    const wide = [
+      ...Array.from({ length: 5 }, (_, i) => ["a", i, "apps_lxd"] as const),
+      ...Array.from({ length: 55 }, (_, i) => ["w", i, "global"] as const),
+    ]
+      .map(
+        ([stem, i, tier]) =>
+          `ex:${stem}${i} a ex:Widget ; ex:name "${stem}.${String(i).padStart(2, "0")}" ; ex:tier ex:${tier} .`,
+      )
+      .join("\n");
+    const { rt: crowded } = await buildFixtureRuntime({
+      ttl: `${TTL}\n${wide}`,
+      prefixes: PREFIXES,
+    });
+    try {
+      const out = await lookup("*.*", {}, crowded);
+      // Cut inside the scope: the total is the scope's, the rest is named.
+      expect(out).toMatchObject({ total: 55, elsewhere: 5 });
+      expect(
+        lookupFormatters({ by: "ex:name" }, PREFIXES).notice?.(out, "mcp"),
+      ).toContain(
+        '50 of 55 matches shown, and 5 more in other tiers: pass `tier: "all"`.',
+      );
+      expect(out.results).toHaveLength(GLOB_EXPANSION_CAP);
+      expect(out.results.every((e) => String(e.name).startsWith("w."))).toBe(
+        true,
+      );
+      expect(out.outOfScope).toBeUndefined();
+    } finally {
+      (await crowded.store.get()).store.dispose();
+    }
+  });
+
+  it("a pattern answers a shared name with the in-scope one alone, and an out-of-scope one with a line", async () => {
+    expect((await lookup("Chi*")).results.map((e) => e.uri)).toEqual([
+      "https://example.org/kit#chip",
+    ]);
+    const out = await lookup("Met*");
+    expect(out.results.map((e) => e.name)).toEqual(["Meter"]);
+    expect(out.outOfScope?.at(0)).toMatchObject({ tiers: ["apps_lxd"] });
+    // The same redirect reached by a pattern AND by name is said once.
+    const both = (await verbFor(KIT, "lookup").run(
+      { name: ["Met*", "Meter"] },
+      rt,
+    )) as LookupOutput;
+    expect(both.outOfScope).toHaveLength(1);
+  });
+
   it("answers a shared name with the in-scope one alone", async () => {
     const out = await lookup("Chip");
     expect(out.results.map((entity) => entity.uri)).toEqual([

package/src/kernel/packs/tierScope.ts

@@ -38,7 +38,7 @@
  * next read re-learns the hierarchy from the pack that replaced it.
  */
 
-import { cliRecovery, PragmaError } from "../error/index.js";
+import { callRecovery, PragmaError } from "../error/index.js";
 import type { PragmaRuntime } from "../runtime/index.js";
 import type { StoreSession } from "../runtime/types.js";
 import { formatTerm } from "./sparql/escape.js";
@@ -330,15 +330,13 @@ export function resolveTierScope(
       validOptions,
       recovery:
         perCall === undefined
-          ? cliRecovery(
-              "config unset tier",
+          ? callRecovery(
+              { verb: "config unset", params: { key: "tier" } },
               `The \`tier\` config key names "${asked}", which is not one of this pack's ${hierarchy.tiers.length} tiers. Clear it, or set one that exists.`,
-              { tool: "config_unset", params: { key: "tier" } },
             )
-          : cliRecovery(
-              "tier list",
+          : callRecovery(
+              { verb: "tier list" },
               `Name one of the ${hierarchy.tiers.length} tiers, or "${EVERY_TIER}" for every tier.`,
-              { tool: "tier_list", params: {} },
             ),
     });
   }

package/src/kernel/packs/toolDescription.test.ts

@@ -1,21 +1,31 @@
 /**
- * PROTECTED — the pack `toolDescription` → MCP tool description wiring.
+ * PROTECTED — the pack guidance → MCP tool description wiring.
  *
- * A pack authors `toolDescription` FOR the agent-facing MCP tool description
- * (see kernel/packs/types.ts, "MCP tool description"). The compiler routes it
- * into `VerbSpec.doc`, the MCP projector emits `doc ?? summary` as the tool
- * description, and the CLI projector renders `doc` in verb help WITHOUT the
- * MCP tool-call example (`noun_verb {…}` is MCP-transport syntax).
+ * A story half authors three things for a caller choosing a tool:
+ * `toolDescription` (what the tool returns), `useWhen` (the question it
+ * answers) and `example` (one call's params). The compiler routes them onto
+ * the verb, and ONE generator (`kernel/spec/guidance.ts`) builds the MCP
+ * description from them; verb help renders the same example as a COMMAND.
  *
  * This pins representative text on BOTH surfaces so the routing can't silently
- * regress: the rich description must reach MCP, and the MCP tool-call example
- * must never leak into CLI `--help`.
+ * regress: the question, the prose and the generated example must reach MCP,
+ * and MCP tool-call syntax must never leak into CLI `--help`.
+ *
+ * These cases used to regex-match a hand-typed `Example: tool {…}` suffix in
+ * the authored prose. The suffix is gone — the example is declared as data and
+ * rendered — so they assert the GENERATED description instead, and whether an
+ * example's params are ones the tool accepts is no longer sampled by regex
+ * here: `capabilities/callRule.test.ts` validates every example against its
+ * verb's whole input schema.
  */
 
 import { describe, expect, it } from "vitest";
 import { storyModules } from "../../capabilities/distribution.js";
 import { projectMcp } from "../../testing/helpers/projectMcp.js";
 import { formatVerbHelp } from "../project/cli/verbHelp.js";
+import { renderCall } from "../spec/call.js";
+import { describeTool, exampleCall } from "../spec/guidance.js";
+import { toolName } from "../spec/index.js";
 import type { VerbSpec } from "../spec/types.js";
 
 const standardModule = storyModules.get("standard");
@@ -51,8 +61,10 @@ describe("pack toolDescription wiring (PROTECTED)", () => {
     )?.description;
     await mcp.cleanup();
     expect(desc).toContain("Get one design-token symbol in full");
-    // The authored MCP tool-call example survives on the MCP surface.
-    expect(desc).toContain('Example: token_lookup { name: ["color.text"] }');
+    // The declared example reaches MCP, rendered as a tool call.
+    expect(desc).toContain(
+      'Example: token_lookup { name: ["color.text","color.border"] }.',
+    );
   });
 
   it("routes the definition-level toolDescription to the MCP list tool", async () => {
@@ -62,9 +74,12 @@ describe("pack toolDescription wiring (PROTECTED)", () => {
     )?.description;
     await mcp.cleanup();
     // The rich description reaches MCP (was previously dropped — only `summary`
-    // reached the tool), including the authored call example.
+    // reached the tool), behind the question it answers and before its example.
+    expect(desc).toMatch(/^Use when asked which design tokens exist/);
     expect(desc).toContain("List the design-token SYMBOLS");
-    expect(desc).toContain('Example: token_list { type: "color" }');
+    expect(desc).toContain(
+      'Example: token_list { type: ["color","dimension"] }.',
+    );
   });
 
   it("routes an extra-verb toolDescription to its MCP tool", async () => {
@@ -77,12 +92,16 @@ describe("pack toolDescription wiring (PROTECTED)", () => {
     // fragment rather than by exact string: the wiring is what this pins, and
     // tool descriptions are explicitly not frozen (`registerVerb.ts:324-326`).
     expect(desc).toContain("List all code standard categories");
-    expect(desc).toContain("Example: standard_categories {}");
+    // Callable with no arguments, so there is no example to show.
+    expect(desc).not.toContain("Example:");
   });
 
-  it("CLI --help shows the rich prose but NEVER the MCP tool-call syntax", () => {
+  it("CLI --help shows the prose and the example as a COMMAND, never as a tool call", () => {
     const lookupHelp = formatVerbHelp("pragma", verb(tokenModule, "lookup"));
     expect(lookupHelp).toContain("Get one design-token symbol in full");
+    expect(lookupHelp).toContain("Use when asked everything about one token");
+    // The same declared example, spelled for this surface.
+    expect(lookupHelp).toContain("pragma token lookup color.text");
     // No-leaks: the `token_lookup {…}` MCP call shape must not reach CLI help.
     expect(lookupHelp).not.toContain("token_lookup {");
     expect(lookupHelp).not.toContain("Example:");
@@ -93,71 +112,37 @@ describe("pack toolDescription wiring (PROTECTED)", () => {
   });
 });
 
-describe("a tool-call example names a parameter the tool ACCEPTS (PROTECTED)", () => {
-  // Four `*_lookup` descriptions taught agents `{ names: [...] }` while every
-  // schema required `name`. An agent copying the example — which is what an
-  // example is for — got `-32602 Invalid arguments`, and the description is
-  // the only instruction it has. Prose that contradicts the schema beside it
-  // is worse than no prose: it is a documented wrong answer.
-  it("every `Example: tool { key: … }` uses a declared property", async () => {
-    const mcp = await projectMcp([...storyModules.values()]);
+describe("every story tool's description is GENERATED from its verb (PROTECTED)", () => {
+  // Four `*_lookup` descriptions once taught agents `{ names: [...] }` while
+  // every schema required `name`, and `standard` once shipped no example at
+  // all. Both were failures of hand-typed prose. The description is now built
+  // from what the verb declares, so this asserts the build — for EVERY story
+  // tool, against the one generator — rather than pattern-matching the prose.
+  it("is the question, then the prose, then the verb's own example as a tool call", async () => {
+    const modules = [...storyModules.values()];
+    const mcp = await projectMcp(modules);
     try {
       const tools = await mcp.listTools();
-      const offenders: string[] = [];
-
-      for (const tool of tools) {
-        const example = /Example:\s*\w+\s*\{\s*([A-Za-z_$][\w$]*)\s*:/.exec(
-          tool.description ?? "",
-        );
-        const key = example?.[1];
-        if (key === undefined) continue; // No call example to check.
-        const properties = Object.keys(
-          (tool.inputSchema as { properties?: Record<string, unknown> })
-            ?.properties ?? {},
-        );
-        if (!properties.includes(key)) {
-          offenders.push(
-            `${tool.name}: example says \`${key}\`, schema declares ${properties.join(", ")}`,
+      const verbs = modules.flatMap((module) => module.verbs);
+      expect(tools.length).toBe(verbs.length);
+      for (const storyVerb of verbs) {
+        const name = toolName(storyVerb.path);
+        const desc = tools.find((tool) => tool.name === name)?.description;
+        expect(desc, name).toBe(describeTool(storyVerb));
+        expect(desc, name).toMatch(/^Use /);
+        expect(desc, name).toContain(storyVerb.useWhen);
+        // Spelled with its OWN name and its declared params, so an example
+        // cannot be copied from a sibling tool and left stale. A verb callable
+        // with no arguments declares none, and shows none.
+        const example = exampleCall(storyVerb);
+        if (example) {
+          expect(desc, name).toContain(
+            `Example: ${renderCall(example, "mcp")}.`,
           );
+        } else {
+          expect(desc, name).not.toContain("Example:");
         }
       }
-
-      expect(offenders).toEqual([]);
-      // Guard against a vacuous pass: some tool must actually carry an example.
-      expect(
-        tools.filter((t) => /Example:\s*\w+\s*\{/.test(t.description ?? ""))
-          .length,
-      ).toBeGreaterThan(0);
-    } finally {
-      await mcp.cleanup();
-    }
-  });
-});
-
-describe("every story tool CARRIES a call example (PROTECTED)", () => {
-  // The check above only polices examples that exist. `standard` authored NONE,
-  // and the auto-generated one fires only for a filter declaring `values` —
-  // which the category filter deliberately does not, because the graph is the
-  // vocabulary. So the four `standard_*` tools shipped with no worked call at
-  // all, and the model that could not form one had nothing to copy.
-  //
-  // This asserts the gap cannot reappear on a future story: a compiled story
-  // tool must show an agent one call it can make, spelled with its OWN name so
-  // the example cannot be copied from a sibling tool and left stale.
-  it("names its own tool in an `Example: <tool_name> {…}` fragment", async () => {
-    const mcp = await projectMcp([...storyModules.values()]);
-    try {
-      const tools = await mcp.listTools();
-      expect(tools.length).toBeGreaterThan(0);
-      const missing = tools
-        .filter(
-          (tool) =>
-            !new RegExp(`Example:\\s*${tool.name}\\s*\\{`).test(
-              tool.description ?? "",
-            ),
-        )
-        .map((tool) => tool.name);
-      expect(missing).toEqual([]);
     } finally {
       await mcp.cleanup();
     }

package/src/kernel/packs/types.ts

@@ -93,8 +93,22 @@ export const TIER_PARAM = "tier";
  */
 export const ENTITY_VARIABLE = "uri";
 
+/**
+ * What a cell may say about the values it prints, on a list column, a lookup
+ * field or an expand field alike.
+ */
+export interface PackCellLink {
+  /**
+   * The noun whose entities this cell NAMES: every value it prints is a name
+   * that noun's lookup resolves, so a reader can take the cell to
+   * `<noun> lookup` verbatim. On a list column it also promises a filter of
+   * the same `noun` over that column.
+   */
+  readonly noun?: string;
+}
+
 /** A list column: a SELECT variable to display. */
-export interface PackColumn {
+export interface PackColumn extends PackCellLink {
   /** SELECT variable name (without `?`). */
   readonly field: string;
   /** Column heading (defaults to the field name). */
@@ -102,7 +116,7 @@ export interface PackColumn {
 }
 
 /** A looked-up value: an output name bound to a property of the entity. */
-export interface PackField {
+export interface PackField extends PackCellLink {
   /** Output field name on the looked-up entity. */
   readonly name: string;
   /** Property to read — a prefixed name (`ds:tier`) or absolute IRI. */
@@ -141,7 +155,7 @@ export interface PackSection extends PackField {
 }
 
 /** A field read from each child node of a {@link PackExpand}. */
-export interface PackExpandField {
+export interface PackExpandField extends PackCellLink {
   /** Output field name on the child record. */
   readonly name: string;
   /** Property to read on the child node — prefixed name, IRI, or path. */
@@ -166,6 +180,15 @@ export interface PackExpandField {
    * and filter against it, and a GraphQL document cannot.
    */
   readonly blankWhenSelf?: true;
+  /**
+   * The property reaches SEVERAL values per child, and the cell is all of them:
+   * distinct, sorted, space-separated, one row per child. Without it each value is a
+   * row of its own, repeating every other cell.
+   *
+   * SPARQL lane only. Not combinable with {@link blankWhenSelf}, and not a
+   * name an expand may order by — a set has no order to sort on.
+   */
+  readonly many?: true;
 }
 
 /**
@@ -365,6 +388,23 @@ export interface PackFilter {
    * names neither is refused where it is declared.
    */
   readonly vocabulary?: PackFilterVocabulary;
+  /**
+   * In place of {@link values} or a {@link vocabulary}: a value is a literal
+   * name or IRI of that noun (never a pattern), resolved as `<noun> lookup`
+   * resolves one, and rows are kept by the IRIs it reaches, matched against
+   * {@link entity}.
+   */
+  readonly noun?: string;
+  /**
+   * The projected SELECT variable holding the IRI a {@link noun} filter
+   * constrains. Left out of the rows unless a column displays it.
+   */
+  readonly entity?: string;
+  /**
+   * The path from {@link entity} to the named entity when they are different
+   * nodes (`^ex:madeBy` from a row's maker to its widgets); absent, they are one.
+   */
+  readonly via?: string;
   /** Help text (defaults to a generated description). */
   readonly description?: string;
 }
@@ -393,16 +433,41 @@ export interface PackSearch {
   readonly description?: string;
 }
 
+/** The shape of a verb path (`sources update`): a noun, optionally a verb — never a command line. */
+export const VERB_PATH_PATTERN = /^[a-z][a-z0-9-]*( [a-z][a-z0-9-]*)?$/;
+
+/**
+ * A call as a story writes it: a verb path and the params to make it with.
+ * Structurally the kernel's `Call` (`spec/types.ts`), restated here because this
+ * file is on the distribution config's import graph and may import nothing.
+ */
+export interface PackCall {
+  readonly verb: string;
+  readonly params?: Readonly<Record<string, unknown>>;
+}
+
 /** Opt-in empty-result recovery for a list story. */
 export interface PackEmptyRecovery {
   /** Human-readable cause + fix (e.g. which packages provide the data). */
   readonly message: string;
   /**
-   * The command that fixes the emptiness, WITHOUT the binary name
-   * (`sources update`). The consuming distribution's renderer prepends its own
-   * name, so a story stays portable across distributions.
+   * The call that fixes the emptiness (`{ verb: "sources update" }`). A verb
+   * path, never a binary name: the consuming distribution's renderer spells it
+   * for the surface it prints on, so a story stays portable across both.
    */
-  readonly cli?: string;
+  readonly call?: PackCall;
+}
+
+/**
+ * What a story half tells a caller choosing between tools. Optional in the
+ * grammar, because third-party packs predate it; the distribution's own stories
+ * are held to declaring both (`callRule.test.ts`).
+ */
+export interface PackGuidance {
+  /** The question a person would ask, in their words, as a bare clause ("when asked …"). */
+  readonly useWhen?: string;
+  /** One real call's params (never empty) — the verb is implied, and both spellings derive. */
+  readonly example?: Readonly<Record<string, unknown>>;
 }
 
 /** The list half of a pack (always SPARQL-sourced). */
@@ -424,7 +489,7 @@ export interface PackList {
  * machinery as `list` (e.g. standard's `categories`). May not collide with the
  * compiled `list`/`lookup`/`sample` verbs.
  */
-export interface PackVerb extends PackList {
+export interface PackVerb extends PackList, PackGuidance {
   /** Verb name (kebab-case), e.g. `"categories"`. */
   readonly verb: string;
   /** CLI description for the command. */
@@ -437,7 +502,7 @@ export interface PackVerb extends PackList {
  * The sample capability: `<noun> sample [count]` returns 1–5 randomly selected
  * complete entities (resolved through the lookup path at the HIGHEST level).
  */
-export interface PackSample {
+export interface PackSample extends PackGuidance {
   /** Default sample count when none is requested (1–5; default 2). */
   readonly count?: number;
   /**
@@ -516,7 +581,7 @@ export interface PackScopeWeight {
  * ALWAYS generated SPARQL regardless of source (an implementation detail, not a
  * second declared source).
  */
-export interface PackLookup {
+export interface PackLookup extends PackGuidance {
   /**
    * Field-fetch strategy (default `"sparql"`). `"graphql"` keeps the SPARQL
    * name→URI resolve, then fetches all fields/sections/expands in ONE generated
@@ -604,6 +669,14 @@ export interface PackLookup {
   readonly completion?: PackCompletion;
 }
 
+/**
+ * The lookup another story's noun declares, by noun — how a {@link PackFilter}
+ * naming a `noun` reaches that noun's resolver. A story is compiled alone, so
+ * whoever compiles it supplies this over the stories it knows. It may throw a
+ * CONFIG_ERROR of its own when it knows why a noun has no lookup.
+ */
+export type NounLookups = (noun: string) => PackLookup | undefined;
+
 /** A pack list row / flat lookup base: variable name → string value. */
 export type PackRow = Record<string, string>;
 
@@ -664,8 +737,17 @@ export interface PageTierScope {
    * use (the tier IRI's local name), base first and then shallowest first.
    */
   readonly tiers: readonly string[];
+  /**
+   * Rows of the WHOLE filtered answer per tier, keyed by local name: every
+   * in-scope tier (0 when empty), the out-of-scope tiers holding some, and
+   * {@link UNTIERED_KEY} for rows in no tier. First page only.
+   */
+  readonly counts?: Readonly<Record<string, number>>;
 }
 
+/** The `counts` key for rows whose entity is in no tier (no tier is named so). */
+export const UNTIERED_KEY = "no tier";
+
 /** One filter a list read was narrowed by, as the caller spelled it. */
 export interface PackAppliedFilter {
   /** The parameter name (its CLI flag is `--<param>`). */
@@ -692,7 +774,7 @@ export type PackChildRow = Record<
 export type PackEntity = Record<string, string | readonly PackChildRow[]>;
 
 /** One declarative read story: a noun with its preferred queries. */
-export interface PackDefinition {
+export interface PackDefinition extends PackGuidance {
   /** Command noun (kebab-case), e.g. `"standard"` → `pragma standard list`. */
   readonly noun: string;
   /** CLI description for the list command. */

package/src/kernel/project/cli/buildProgram.ts

@@ -19,6 +19,7 @@ import {
   VERSION,
 } from "../../../constants.js";
 import type { GlobalFlags } from "../../runtime/index.js";
+import { declareVerbs } from "../../spec/call.js";
 import { kebabCase } from "../../spec/index.js";
 import type { CliProjection, ParamSpec, VerbSpec } from "../../spec/types.js";
 import { MUTATION_FLAG_DOCS, negationFlagDoc } from "./constants.js";
@@ -302,6 +303,9 @@ export function buildProgram(
   const version = options.version ?? VERSION;
   const issuesUrl = options.issuesUrl ?? ISSUES_URL;
   const live = verbs.filter((verb) => !verb.hidden);
+  // A recovery or an example names a call; spelling it as a command needs the
+  // named verb's positionals, so the renderer is told which verbs exist.
+  declareVerbs(verbs);
 
   const program = new Command();
   program.name(programName).description(description);