@canonical/pragma-cli 0.38.0 → 0.40.0

package/src/capabilities/listLookup.shipped.exec.test.ts

@@ -17,9 +17,12 @@
  * defect class is not standard-specific, since every pair shares this
  * machinery. Three guarantees per noun:
  *
- * - every name `list` publishes resolves through `lookup` (executed through
- *   the real verb bodies, so glob/IRI argument-shape dispatch is exercised
- *   with the very strings an agent would paste);
+ * - every IDENTIFIER `list` publishes resolves through `lookup`, in every form
+ *   a row is printed in — the name, the prefixed IRI the plain and condensed
+ *   formats print, and the absolute IRI JSON carries (executed through the
+ *   real verb bodies, so glob/IRI argument-shape dispatch is exercised with
+ *   the very strings an agent would paste). One case per form, so a failure
+ *   names the spelling that broke;
  * - every published name is in the addressable population (`listEntityNames`
  *   — the ONE pool that feeds miss-suggestions, glob expansion AND `sample`'s
  *   draw), so a suggestion can never offer a name the resolve cannot answer;
@@ -44,6 +47,7 @@ import {
   type PackPage,
 } from "../kernel/packs/types.js";
 import { verbKey } from "../kernel/packs/uniqueness.js";
+import { compactUri, DEFAULT_PREFIX_MAP } from "../kernel/render/index.js";
 import { bootRuntime } from "../kernel/runtime/boot.js";
 import type { PragmaRuntime } from "../kernel/runtime/types.js";
 import type { CapabilityModule, VerbSpec } from "../kernel/spec/types.js";
@@ -96,7 +100,19 @@ function verbOf(
 }
 
 /**
- * Run `<noun> list` and return every name it publishes, verbatim, deduped.
+ * The forms a list row's identifier is printed in, by the format that prints
+ * it. Whatever a reader copies out of a list has to be an address.
+ */
+const FORMS = ["name", "prefixed IRI", "absolute IRI"] as const;
+type Form = (typeof FORMS)[number];
+
+/**
+ * Run `<noun> list` and return every identifier it publishes, per form,
+ * verbatim, deduped.
+ *
+ * The prefixed IRI is compacted against the map the distribution's stories are
+ * compiled with (`distribution.ts`), so it is the string the plain and
+ * condensed renderers print — not a second opinion about how to shorten it.
  *
  * WALKS THE PAGES, and it has to. This file's promise is the round trip over the
  * WHOLE corpus rather than a sample, and that used to come free: every declared
@@ -111,13 +127,15 @@ function verbOf(
  * a large corpus, and an unbounded `while` over a broken cursor would hang the
  * suite instead of failing it.
  */
-async function publishedNames(
+async function publishedIdentifiers(
   rt: PragmaRuntime,
   module: CapabilityModule,
   noun: string,
-): Promise<string[]> {
+): Promise<Record<Form, string[]>> {
   const verb = verbOf(module, noun, "list");
   const names = new Set<string>();
+  const prefixed = new Set<string>();
+  const absolute = new Set<string>();
   let after: string | undefined;
   let pages = 0;
   do {
@@ -128,6 +146,10 @@ async function publishedNames(
     for (const row of page.rows) {
       const name = row.name ?? "";
       if (name !== "") names.add(name);
+      const uri = row.uri ?? "";
+      if (uri === "") continue;
+      absolute.add(uri);
+      prefixed.add(compactUri(uri, DEFAULT_PREFIX_MAP));
     }
     after = page.nextAfter;
     pages += 1;
@@ -137,7 +159,20 @@ async function publishedNames(
       );
     }
   } while (after !== undefined);
-  return [...names];
+  return {
+    name: [...names],
+    "prefixed IRI": [...prefixed],
+    "absolute IRI": [...absolute],
+  };
+}
+
+/** Every NAME `<noun> list` publishes — the form the pool guarantees read. */
+async function publishedNames(
+  rt: PragmaRuntime,
+  module: CapabilityModule,
+  noun: string,
+): Promise<string[]> {
+  return (await publishedIdentifiers(rt, module, noun)).name;
 }
 
 /**
@@ -197,11 +232,11 @@ describe("every list-published name resolves through lookup, whole corpus (PROTE
     expect(NOUNS).toContain("block");
   });
 
-  it.each(NOUNS.map((noun) => [noun] as const))(
-    "%s: every published name round-trips, and its corpus is not silently empty",
-    async (noun) => {
+  it.each(NOUNS.flatMap((noun) => FORMS.map((form) => [noun, form] as const)))(
+    "%s: every published %s round-trips, and its corpus is not silently empty",
+    async (noun, form) => {
       const module = storyModules.get(noun) as CapabilityModule;
-      const names = await publishedNames(rt, module, noun);
+      const names = (await publishedIdentifiers(rt, module, noun))[form];
       if (EMPTY_CORPUS_TODAY.includes(noun)) {
         // Asserted empty, not skipped: this is what expires the allowlist.
         expect(
@@ -210,16 +245,18 @@ describe("every list-published name resolves through lookup, whole corpus (PROTE
             "delete it from EMPTY_CORPUS_TODAY so a later regression to zero rows cannot hide behind the entry",
         ).toEqual([]);
       } else {
+        // Held for every form: each shipped list projects its IRI column, and
+        // an IRI case that passed over zero IRIs would prove nothing.
         expect(
           names.length,
-          `${noun} list published no rows at all from the shipped pack`,
+          `${noun} list published no ${form} at all from the shipped pack`,
         ).toBeGreaterThan(0);
       }
 
       const errors = await lookupErrors(rt, module, noun, names);
       expect(
         errors,
-        `${noun} list published ${errors.length} name(s) its own lookup cannot resolve — ` +
+        `${noun} list published ${errors.length} ${form}(s) its own lookup cannot resolve — ` +
           "the two-step grammar the tool descriptions document is broken for every agent following it",
       ).toEqual([]);
     },
@@ -305,6 +342,78 @@ describe("every list-published name resolves through lookup, whole corpus (PROTE
   );
 });
 
+describe("an IRI's local name is one step from an address (shipped pack)", () => {
+  /** A published block IRI of the `tier.component.name` shape, and its local name. */
+  async function sampleIri(): Promise<{ prefixed: string; local: string }> {
+    const module = storyModules.get("block") as CapabilityModule;
+    const { "prefixed IRI": prefixed } = await publishedIdentifiers(
+      rt,
+      module,
+      "block",
+    );
+    const chosen = prefixed.find((iri) => iri.includes(".component.")) ?? "";
+    expect(chosen).not.toBe("");
+    return { prefixed: chosen, local: chosen.replace(/^[^:]*:/, "") };
+  }
+
+  it("a wildcard over a local name reaches its entity", async () => {
+    const { prefixed, local } = await sampleIri();
+    const module = storyModules.get("block") as CapabilityModule;
+    const output = (await verbOf(module, "block", "lookup").run(
+      { name: [`*.${local.split(".").slice(1).join(".")}`] },
+      rt,
+    )) as { results: { uri: string }[]; errors: unknown[] };
+
+    expect(output.errors).toEqual([]);
+    expect(
+      output.results.map((entity) =>
+        compactUri(entity.uri, DEFAULT_PREFIX_MAP),
+      ),
+    ).toContain(prefixed);
+  }, 60_000);
+
+  it("a bare local name misses, and the miss leads with the prefixed form", async () => {
+    const { prefixed, local } = await sampleIri();
+    const module = storyModules.get("block") as CapabilityModule;
+    const reason = await Promise.resolve(
+      verbOf(module, "block", "lookup").run({ name: [local] }, rt),
+    ).catch((error: unknown) => error);
+
+    expect(reason).toMatchObject({ code: "ENTITY_NOT_FOUND" });
+    expect((reason as { suggestions: string[] }).suggestions.at(0)).toBe(
+      prefixed,
+    );
+  }, 60_000);
+});
+
+describe("every story example answers from the shipped pack", () => {
+  // An example is copied verbatim by the agents it is shown to, so a name the
+  // graph has since renamed is a miss handed out in advance.
+  const examples = [...storyModules.values()].flatMap((module) =>
+    module.verbs
+      .filter((verb) => verb.example !== undefined)
+      .map((verb) => [verbKey(verb.path), verb] as const),
+  );
+
+  it.each(examples)(
+    "%s",
+    async (_label, verb) => {
+      const answer = (await verb.run({ ...verb.example }, rt)) as {
+        rows?: unknown[];
+        results?: unknown[];
+        errors?: unknown[];
+      };
+      expect(answer.errors ?? []).toEqual([]);
+      const named = verb.example?.name;
+      if (Array.isArray(named)) {
+        expect(answer.results?.length).toBeGreaterThanOrEqual(named.length);
+      }
+      if (answer.rows) expect(answer.rows.length).toBeGreaterThan(0);
+    },
+    60_000,
+  );
+});
+
 describe("negative control: the pre-#1047 shape fails these assertions", () => {
   // The exact divergence that shipped: a list that COALESCEs an OPTIONAL
   // display name with an IRI-derived one, over a lookup that requires the

package/src/capabilities/listQuery.shipped.exec.test.ts

@@ -34,6 +34,7 @@ import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { MAX_LISTED_OPTIONS } from "../kernel/error/validOptions.js";
 import { compileStoryModule } from "../kernel/packs/compile.js";
 import { MAX_LIST_WINDOW } from "../kernel/packs/paging.js";
+import { listEntityNames } from "../kernel/packs/resolveEntity.js";
 import {
   distributionSource,
   type PackFilter,
@@ -47,7 +48,7 @@ import type { PragmaRuntime } from "../kernel/runtime/types.js";
 import { kebabCase } from "../kernel/spec/emitSurface.js";
 import type { VerbSpec } from "../kernel/spec/types.js";
 import { TEST_FLAGS } from "../testing/helpers/projectCli.js";
-import { declaredStories } from "./distribution.js";
+import { declaredLookups, declaredStories } from "./distribution.js";
 
 const SOURCE = distributionSource("pragma.conf.ts");
 
@@ -65,7 +66,7 @@ interface Body {
  */
 const BODIES: readonly Body[] = [...declaredStories].flatMap(
   ([noun, story]) => {
-    const module = compileStoryModule(story, SOURCE, {});
+    const module = compileStoryModule(story, SOURCE, {}, declaredLookups);
     const find = (verb: string): VerbSpec => {
       const found = module.verbs.find(
         (v) => verbKey(v.path) === `${noun} ${verb}`,
@@ -119,9 +120,14 @@ async function population(body: Body): Promise<readonly PackRow[]> {
   return (await page(body, { limit: MAX_LIST_WINDOW })).rows;
 }
 
-/** The values a value-free filter's declared vocabulary admits. */
+/**
+ * The values a value-free filter admits: its declared vocabulary, or — for a
+ * filter naming a noun — every name that noun's lookup resolves.
+ */
 async function vocabulary(filter: PackFilter): Promise<readonly string[]> {
   if (filter.values) return filter.values;
+  const named = filter.noun ? declaredLookups(filter.noun) : undefined;
+  if (named) return listEntityNames(rt, named, SOURCE);
   const declared = filter.vocabulary;
   if (!declared) throw new Error(`filter --${filter.param} declares neither`);
   const result = await rt.query.sparql(declared.query);
@@ -275,9 +281,15 @@ describe("the compiled query agrees with the retired row predicate (PROTECTED)",
             [filter.param]: value,
             limit: MAX_LIST_WINDOW,
           });
-          expect(JSON.stringify(answered.rows)).toBe(
-            JSON.stringify(rowPredicate(whole, filter, value)),
-          );
+          const expected = rowPredicate(whole, filter, value);
+          // A `via` filter constrains an entity the cell only PRINTS one name
+          // of, so a name the cell does not print may still answer; whatever
+          // the cell does print must answer exactly.
+          if (filter.via === undefined || expected.length > 0) {
+            expect(JSON.stringify(answered.rows)).toBe(
+              JSON.stringify(expected),
+            );
+          }
         }
       }
     },
@@ -351,13 +363,21 @@ describe("a refusal and a calm empty answer stay distinguishable (PROTECTED)", (
     "%s: a value the vocabulary does not admit is INVALID_INPUT, naming the ones it does",
     async (_label, body) => {
       for (const filter of body.shape.filters ?? []) {
-        const admissible = await vocabulary(filter);
-        await expect(
-          page(body, { [filter.param]: "zzz-definitely-not-a-value" }),
-        ).rejects.toMatchObject({
-          code: "INVALID_INPUT",
-          validOptions: [...admissible].sort(),
+        const refusal = page(body, {
+          [filter.param]: "zzz-definitely-not-a-value",
         });
+        // A noun has too many names to list: its miss says so by name.
+        await expect(refusal).rejects.toMatchObject(
+          filter.noun
+            ? {
+                code: "INVALID_INPUT",
+                message: `No ${filter.noun} is named "zzz-definitely-not-a-value".`,
+              }
+            : {
+                code: "INVALID_INPUT",
+                validOptions: [...(await vocabulary(filter))].sort(),
+              },
+        );
       }
     },
     60_000,
@@ -374,6 +394,8 @@ describe("a refusal and a calm empty answer stay distinguishable (PROTECTED)", (
     for (const body of NARROWABLE) {
       const whole = await population(body);
       for (const filter of body.shape.filters ?? []) {
+        // The cell is no oracle for emptiness under a `via` filter (above).
+        if (filter.via !== undefined) continue;
         for (const value of sweep(await vocabulary(filter))) {
           if (rowPredicate(whole, filter, value).length === 0) {
             unpopulated.push({ body, param: filter.param, value });
@@ -389,11 +411,12 @@ describe("a refusal and a calm empty answer stay distinguishable (PROTECTED)", (
       // And the calm sentence rides the same seam it always did — naming the
       // filter that narrowed to nothing, since a filtered empty answer is a
       // statement about the filter and not about the population.
+      // In the flag's own spelling: a story's `channelOf` param is typed
+      // `--channel-of`, and an answer that named the param would be naming
+      // something no caller can pass. A value with a space in it is quoted.
+      const shown = /\s/.test(value) ? `'${value}'` : value;
       expect(body.verb.output.formatters.notice?.(answered as never)).toContain(
-        // In the flag's own spelling: a story's `channelOf` param is typed
-        // `--channel-of`, and an answer that named the param would be naming
-        // something no caller can pass.
-        `matches \`--${kebabCase(param)} ${value}\`.`,
+        `matches \`--${kebabCase(param)} ${shown}\`.`,
       );
     }
   }, 120_000);

package/src/capabilities/lookupBudget.shipped.exec.test.ts

@@ -0,0 +1,208 @@
+/**
+ * The response-size budget for a LOOKUP and for `graph inspect`, at every
+ * disclosure level, measured over the SHIPPED pack (PROTECTED).
+ *
+ * The list budget beside this file bounds what a browse costs. A read of one
+ * entity had no bound at all, and two recorded answers are why it has one now:
+ * `token_lookup { name: ["color.*"] }` answered with 473 entities and 460 KB,
+ * and `graph_inspect` of one block with 41 KB — neither with any way to be
+ * asked for less, since most lookups declared no `detail`.
+ *
+ * So three things are held here, each over the whole shipped corpus and each
+ * derived from the configuration rather than listed:
+ *
+ * - the LARGEST single entity a lookup answers with, per level — `summary` is
+ *   the cheap level by measurement rather than by name;
+ * - the widest possible pattern (`*`), which the expansion cap has to hold to
+ *   a bounded answer on every noun;
+ * - the largest `graph inspect` of a block, per level.
+ *
+ * WHERE IT IS ENFORCED, and why bytes of the re-serialised JSON: exactly as the
+ * list budget does it, for the reasons given there.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { DETAIL_LEVELS, type DetailLevel } from "../constants.js";
+import { MAX_LIST_WINDOW } from "../kernel/packs/paging.js";
+import {
+  GLOB_EXPANSION_CAP,
+  type LookupOutput,
+} from "../kernel/packs/resolveEntity.js";
+import type { PackPage } from "../kernel/packs/types.js";
+import { verbKey } from "../kernel/packs/uniqueness.js";
+import { bootRuntime } from "../kernel/runtime/boot.js";
+import type { PragmaRuntime } from "../kernel/runtime/types.js";
+import type { CapabilityModule, VerbSpec } from "../kernel/spec/types.js";
+import { TEST_FLAGS } from "../testing/helpers/projectCli.js";
+import { declaredStories, storyModules } from "./distribution.js";
+import { graphModule } from "./graph/index.js";
+
+/**
+ * The ceiling on ONE looked-up entity, in bytes, per level.
+ *
+ * **Derived from measurement, 2026-09-17**, as the largest entity of any noun
+ * at that level: 2,425 bytes at `summary` (a code standard), 25,282 at
+ * `standard` (a concept, whose Markdown body arrives there) and 70,097 at
+ * `detailed` (a block). Each ceiling is the measurement × 1.5, rounded — the
+ * list budget's shape of derivation — so ordinary upstream growth in a pack
+ * does not turn this red on a bump, and a lookup whose `summary` quietly grows
+ * an expand does. Per noun, `summary` measured: token 548 (4,174 at
+ * `detailed`), variable 393 (4,854), tier 101 (3,847), modifier 103 (203),
+ * concept 763 (25,302), block 2,312 (70,097), standard 2,425 (6,622).
+ */
+const ENTITY_BUDGET_BYTES: Readonly<Record<DetailLevel, number>> = {
+  summary: 3_700,
+  standard: 38_000,
+  detailed: 105_000,
+};
+
+/**
+ * The ceiling on the answer to the widest pattern a noun can be handed.
+ *
+ * It moves with {@link GLOB_EXPANSION_CAP} and with how fat a noun's entities
+ * are. Measured 2026-09-17: `block` at 22,592 bytes (`summary`) and 206,809
+ * (`detailed`), × 1.5, rounded. Full table in BUDGETS.md.
+ */
+const GLOB_BUDGET_BYTES: Readonly<Record<"summary" | "detailed", number>> = {
+  summary: 34_000,
+  detailed: 310_000,
+};
+
+/**
+ * The ceiling on ONE `graph inspect` of a block, in bytes, per level.
+ *
+ * **Derived from measurement, 2026-09-17**, over every block the shipped pack
+ * lists: 5,785 bytes at `summary`, 20,551 at `standard`, 72,258 at `detailed`;
+ * × 1.5, rounded. `detailed` is the uncut neighbourhood by design, so its
+ * ceiling records a size rather than enforcing a cut; `summary` and `standard`
+ * are the levels the outbound cap holds (the global Button read 28,713 at
+ * `standard` before it, 18,173 after).
+ */
+const INSPECT_BUDGET_BYTES: Readonly<Record<DetailLevel, number>> = {
+  summary: 8_700,
+  standard: 31_000,
+  detailed: 108_000,
+};
+
+/** Every noun with a lookup, derived from the config. */
+const NOUNS: readonly string[] = [...declaredStories]
+  .filter(([, story]) => story.lookup !== undefined)
+  .map(([noun]) => noun);
+
+let rt: PragmaRuntime;
+beforeAll(async () => {
+  rt = bootRuntime(TEST_FLAGS);
+  await rt.store.get();
+}, 60_000);
+afterAll(async () => {
+  (await rt.store.get()).store.dispose();
+});
+
+/** The runtime one call at `detail` sees — what `--detail`/`detail` seed. */
+const at = (detail: DetailLevel): PragmaRuntime => ({
+  ...rt,
+  globalFlags: { ...rt.globalFlags, detail },
+});
+
+/** Bytes of a value as either machine surface re-serialises it. */
+const bytesOf = (value: unknown): number =>
+  Buffer.byteLength(JSON.stringify(value));
+
+function verbOf(noun: string, verb: string): VerbSpec {
+  const module = storyModules.get(noun) as CapabilityModule;
+  const found = module.verbs.find((v) => verbKey(v.path) === `${noun} ${verb}`);
+  if (!found) throw new Error(`no compiled "${noun} ${verb}" verb`);
+  return found;
+}
+
+/**
+ * The argument that lifts a tiered noun's scope, and nothing for the rest: the
+ * budget is over the whole corpus, not over the default scope's part of it.
+ */
+const everyTier = (noun: string): Record<string, unknown> =>
+  declaredStories.get(noun)?.tierScope ? { tier: "all" } : {};
+
+/** Every entity a noun's lookup can be handed, by IRI (none when it has no list). */
+async function population(noun: string): Promise<string[]> {
+  if (declaredStories.get(noun)?.list === undefined) return [];
+  const page = (await verbOf(noun, "list").run(
+    { limit: MAX_LIST_WINDOW, ...everyTier(noun) },
+    rt,
+  )) as PackPage;
+  return [...new Set(page.rows.map((row) => row.uri ?? ""))].filter(Boolean);
+}
+
+describe("lookup response budget, shipped pack (PROTECTED)", () => {
+  it("derives every lookup from the config", () => {
+    expect(NOUNS).toContain("token");
+    expect(NOUNS.length).toBeGreaterThanOrEqual(7);
+  });
+
+  it.each(
+    NOUNS.flatMap((noun) =>
+      DETAIL_LEVELS.map((level) => [noun, level] as const),
+    ),
+  )(
+    "%s lookup at %s: the largest entity is inside the budget",
+    async (noun, level) => {
+      const names = await population(noun);
+      expect(names.length).toBeGreaterThan(0);
+      const output = (await verbOf(noun, "lookup").run(
+        { name: names, ...everyTier(noun) },
+        at(level),
+      )) as LookupOutput;
+      const largest = Math.max(...output.results.map(bytesOf));
+      expect(output.errors).toEqual([]);
+      expect(largest).toBeLessThanOrEqual(ENTITY_BUDGET_BYTES[level]);
+    },
+    120_000,
+  );
+
+  it.each(
+    NOUNS.flatMap((noun) =>
+      (["summary", "detailed"] as const).map((level) => [noun, level] as const),
+    ),
+  )(
+    "%s lookup '*' at %s: the widest pattern is cut, and inside the budget",
+    async (noun, level) => {
+      const verb = verbOf(noun, "lookup");
+      const output = (await verb.run(
+        { name: ["*"], ...everyTier(noun) },
+        at(level),
+      )) as LookupOutput;
+      const bytes = bytesOf(JSON.parse(verb.output.formatters.json(output)));
+      // Cut exactly when there was more than the cap to cut.
+      const entities = (await population(noun)).length;
+      expect(output.truncated === true).toBe(entities > GLOB_EXPANSION_CAP);
+      expect(output.results.length).toBe(
+        Math.min(entities, GLOB_EXPANSION_CAP),
+      );
+      expect(bytes).toBeLessThanOrEqual(GLOB_BUDGET_BYTES[level]);
+    },
+    120_000,
+  );
+});
+
+describe("graph inspect response budget, shipped pack (PROTECTED)", () => {
+  const inspect = graphModule.verbs.find(
+    (v) => verbKey(v.path) === "graph inspect",
+  ) as VerbSpec;
+
+  it.each(DETAIL_LEVELS.map((level) => [level] as const))(
+    "at %s: the largest block neighbourhood is inside the budget",
+    async (level) => {
+      const blocks = await population("block");
+      expect(blocks.length).toBeGreaterThan(0);
+      let largest = 0;
+      for (const uri of blocks) {
+        const result = await inspect.run({ uri }, at(level));
+        largest = Math.max(
+          largest,
+          bytesOf(JSON.parse(inspect.output.formatters.json(result as never))),
+        );
+      }
+      expect(largest).toBeLessThanOrEqual(INSPECT_BUDGET_BYTES[level]);
+    },
+    120_000,
+  );
+});

package/src/capabilities/meta/mcp.verb.ts

@@ -16,6 +16,8 @@ import type { VerbSpec } from "../../kernel/spec/index.js";
 export const mcpVerb: VerbSpec<Record<string, unknown>, void> = {
   path: ["mcp", "serve"],
   summary: "Start the MCP server over stdio.",
+  useWhen:
+    "when an MCP client needs to launch this server; people rarely run it by hand",
   params: [],
   output: {
     formatters: {

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

@@ -126,6 +126,30 @@ describe("ontology lookup (primary by-name read)", () => {
       /prefix/i,
     );
   });
+
+  // Each refusal ends in the same next call, in both spellings.
+  const LIST_RECOVERY = {
+    cli: "pragma ontology list",
+    mcp: { tool: "ontology_list", params: {} },
+  };
+
+  it("an unbound namespace URI recovers to the namespace list", async () => {
+    await expect(
+      lookupVerb.run({ prefix: "https://nope.example/" }, rt),
+    ).rejects.toMatchObject({
+      code: "INVALID_INPUT",
+      recovery: LIST_RECOVERY,
+    });
+  });
+
+  it("a class the namespace does not define recovers to the namespace list", async () => {
+    await expect(
+      lookupVerb.run({ prefix: "ds", class: "NoSuchClass" }, rt),
+    ).rejects.toMatchObject({
+      code: "ENTITY_NOT_FOUND",
+      recovery: LIST_RECOVERY,
+    });
+  });
 });
 
 describe("ontology_lookup honours detail over MCP (B5)", () => {

package/src/capabilities/ontology/verbs.ts

@@ -22,7 +22,7 @@
  */
 
 import { BIN_NAME } from "../../constants.js";
-import { cliRecovery, PragmaError } from "../../kernel/error/index.js";
+import { callRecovery, PragmaError } from "../../kernel/error/index.js";
 import { resolvePackDetail } from "../../kernel/packs/disclosure.js";
 import type { PragmaRuntime } from "../../kernel/runtime/index.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
@@ -51,12 +51,9 @@ function resolvePrefix(
     if (entry) return { prefix: entry[0], namespace: entry[1] };
     throw PragmaError.invalidInput("namespace", input, {
       validOptions: Object.values(prefixes),
-      recovery: cliRecovery(
-        "ontology list",
+      recovery: callRecovery(
+        { verb: "ontology list" },
         "List loaded ontology namespaces.",
-        {
-          tool: "ontology_list",
-        },
       ),
     });
   }
@@ -64,9 +61,10 @@ function resolvePrefix(
   if (namespace === undefined) {
     throw PragmaError.invalidInput("prefix", input, {
       validOptions: Object.keys(prefixes),
-      recovery: cliRecovery("ontology list", "List loaded ontologies.", {
-        tool: "ontology_list",
-      }),
+      recovery: callRecovery(
+        { verb: "ontology list" },
+        "List loaded ontologies.",
+      ),
     });
   }
   return { prefix: input, namespace };
@@ -75,6 +73,8 @@ function resolvePrefix(
 const listVerb: VerbSpec<Record<string, unknown>, OntologySummary[]> = {
   path: ["ontology", "list"],
   summary: "List loaded ontology namespaces with class and property counts.",
+  useWhen:
+    "when asked which vocabularies (namespaces and their prefixes) the data uses — the first step before writing a raw query",
   params: [],
   output: { formatters: ontologyListFormatters },
   examples: [{ cmd: `${BIN_NAME} ontology list` }],
@@ -192,9 +192,10 @@ async function runByName(
 
   if (classes.length === 0 && properties.length === 0) {
     throw PragmaError.notFound("ontology", String(params.prefix), {
-      recovery: cliRecovery("ontology list", "List loaded ontologies.", {
-        tool: "ontology_list",
-      }),
+      recovery: callRecovery(
+        { verb: "ontology list" },
+        "List loaded ontologies.",
+      ),
     });
   }
 
@@ -215,6 +216,9 @@ export const ontologyListVerb = asVerb(listVerb);
 export const ontologyLookupVerb = asVerb({
   path: ["ontology", "lookup"],
   summary: "Look up a namespace's classes (hierarchy + counts) and properties.",
+  useWhen:
+    "before writing a raw query, to find the real class and property names under one prefix",
+  example: { prefix: "ds" },
   params: BY_NAME_PARAMS,
   output: { formatters: ontologyShowFormatters },
   examples: [