@canonical/pragma-cli 0.32.0 → 0.34.0

package/src/capabilities/emptyRecovery.test.ts

@@ -3,24 +3,34 @@
  *
  * Listing zero rows is a calm SUCCESS, not an error. The run body returns `[]`
  * (no throw), dispatch renders a non-blank message and exits 0, and JSON stays
- * `[]`. A pack's authored `emptyRecovery` becomes that message's HINT — the v2
- * story still points at `pragma sources update` — but as guidance on the
- * success path, never a thrown EMPTY_RESULTS (which maps to exit 1 and would
- * break the uniform `ok:true` list contract).
+ * `[]`. A story's declared `emptyRecovery` becomes that message's HINT — but as
+ * guidance on the success path, never a thrown EMPTY_RESULTS (which maps to
+ * exit 1 and would break the uniform `ok:true` list contract).
+ *
+ * The story declares the command WITHOUT a binary name (`sources update`); the
+ * renderer prepends the CONSUMING distribution's. The hints asserted below are
+ * therefore the JOINED string, which is what a user reads — a story that named
+ * a binary itself would render it twice, and the grammar now refuses one.
  */
 
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { compilePack } from "../kernel/packs/compile.js";
 import type { PackDefinition } from "../kernel/packs/types.js";
+import { distributionSource } from "../kernel/packs/types.js";
 import { verbKey } from "../kernel/packs/uniqueness.js";
 import { executeVerb } from "../kernel/project/cli/dispatch.js";
 import { DEFAULT_PREFIX_MAP } from "../kernel/render/prefixes.js";
 import type { PragmaRuntime } from "../kernel/runtime/types.js";
 import type { VerbSpec } from "../kernel/spec/types.js";
 import { buildFixtureRuntime } from "../testing/helpers/packRuntime.js";
-import { modifierPack } from "./modifier/pack.js";
-import { standardPack } from "./standard/pack.js";
-import { tokenPack } from "./token/pack.js";
+import { declaredStories } from "./distribution.js";
+
+/** A story `pragma.conf.ts` declares — absent means it was renamed or dropped. */
+function storyFor(noun: string): PackDefinition {
+  const story = declaredStories.get(noun);
+  if (!story) throw new Error(`pragma.conf.ts declares no story for "${noun}"`);
+  return story;
+}
 
 const PREFIXES = {
   ds: "https://ds.canonical.com/",
@@ -61,19 +71,21 @@ afterAll(async () => {
 });
 
 const listVerb = (pack: PackDefinition): VerbSpec =>
-  compilePack(pack, `bundled:${pack.noun}`, DEFAULT_PREFIX_MAP).find(
-    (v) => verbKey(v.path) === `${pack.noun} list`,
-  ) as VerbSpec;
+  compilePack(
+    pack,
+    distributionSource("pragma.conf.ts"),
+    DEFAULT_PREFIX_MAP,
+  ).find((v) => verbKey(v.path) === `${pack.noun} list`) as VerbSpec;
 
 /**
- * Every bundled pack list verb, with the hint expected in its empty message:
+ * Every declared story's list verb, with the hint expected in its empty message:
  * an authored `emptyRecovery` surfaces `pragma sources update`; the others fall
  * back to the generic build/broaden hint.
  */
 const PACK_LISTS: readonly { pack: PackDefinition; hint: RegExp }[] = [
-  { pack: modifierPack, hint: /pragma sources update/ },
-  { pack: tokenPack, hint: /pragma sources update/ },
-  { pack: standardPack, hint: /broaden your filter/ },
+  { pack: storyFor("modifier"), hint: /pragma sources update/ },
+  { pack: storyFor("token"), hint: /pragma sources update/ },
+  { pack: storyFor("standard"), hint: /broaden your filter/ },
 ];
 
 const REAL = { dryRun: false, undo: false, yes: false };
@@ -104,7 +116,12 @@ describe("pack list empty-state (U5, PROTECTED)", () => {
   });
 
   it("dispatch prints the empty message on stdout and exits 0 (end-to-end)", async () => {
-    const outcome = await executeVerb(listVerb(modifierPack), {}, REAL, rt);
+    const outcome = await executeVerb(
+      listVerb(storyFor("modifier")),
+      {},
+      REAL,
+      rt,
+    );
     expect(outcome.exitCode).toBe(0);
     expect(outcome.stdout).toContain("No modifier entries found.");
     expect(outcome.stdout).toContain("pragma sources update");

package/src/capabilities/graph/inspect.verb.ts

@@ -8,6 +8,7 @@
  * name or absolute IRI addresses the subject exactly.
  */
 
+import { BIN_NAME } from "../../constants.js";
 import type { InspectResult } from "../../kernel/runtime/readEntity.js";
 import { readEntity } from "../../kernel/runtime/readEntity.js";
 import type { PragmaRuntime } from "../../kernel/runtime/types.js";
@@ -32,8 +33,8 @@ const inspectVerb: VerbSpec<Record<string, unknown>, InspectResult> = {
   ],
   output: { formatters: inspectFormatters },
   examples: [
-    { cmd: "pragma graph inspect ds:button" },
-    { cmd: "pragma graph inspect https://ds.canonical.com/button" },
+    { cmd: `${BIN_NAME} graph inspect ds:button` },
+    { cmd: `${BIN_NAME} graph inspect https://ds.canonical.com/button` },
   ],
   capability: {
     needsStore: true,

package/src/capabilities/graph/query.verb.ts

@@ -9,6 +9,7 @@
  * query surfaces as INVALID_INPUT with a recovery pointer to `ontology list`.
  */
 
+import { BIN_NAME } from "../../constants.js";
 import type { PragmaRuntime } from "../../kernel/runtime/types.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
 import type { VerbSpec } from "../../kernel/spec/types.js";
@@ -35,11 +36,11 @@ const queryVerb: VerbSpec<Record<string, unknown>, QueryResult> = {
   output: { formatters: queryFormatters },
   examples: [
     {
-      cmd: 'pragma graph query "SELECT ?s WHERE { ?s a ds:Component }"',
+      cmd: `${BIN_NAME} graph query "SELECT ?s WHERE { ?s a ds:Component }"`,
       note: "list every component subject",
     },
     {
-      cmd: 'pragma graph query "ASK { ds:button a ds:Component }" --format json',
+      cmd: `${BIN_NAME} graph query "ASK { ds:button a ds:Component }" --format json`,
     },
   ],
   capability: {

package/src/capabilities/graph/runQuery.ts

@@ -11,6 +11,7 @@
 
 import type { QueryResult } from "@canonical/ke";
 import { PragmaError } from "../../kernel/error/PragmaError.js";
+import { cliRecovery } from "../../kernel/error/recovery.js";
 import type { PragmaRuntime } from "../../kernel/runtime/types.js";
 
 /**
@@ -39,11 +40,13 @@ export async function runQuery(
       message: detail
         ? `Invalid SPARQL query: ${detail}`
         : "Invalid SPARQL query.",
-      recovery: {
-        message: "Check your SPARQL syntax and the loaded namespaces.",
-        cli: "pragma ontology list",
-        mcp: { tool: "ontology_list" },
-      },
+      recovery: cliRecovery(
+        "ontology list",
+        "Check your SPARQL syntax and the loaded namespaces.",
+        {
+          tool: "ontology_list",
+        },
+      ),
     });
   }
 }

package/src/capabilities/index.ts

@@ -1,46 +1,42 @@
 /**
- * The capability registry: the literal array of every capability module the
- * projectors consume (D8 — test-only fixtures are never listed here).
+ * The capability registry: every capability module the projectors consume
+ * (D8 — test-only fixtures are never listed here).
  *
- * The order is the authoring order; projectors sort where they need to. PR1
- * ships `info` + `config show` as real verbs and the hidden `meta` verbs
- * (`__complete`, `mcp`). Importing this barrel pulls only spec + formatter
- * modules — every run body is behind a lazy dynamic import — so the
+ * Two sources, in this order: the literal array of AUTHORED modules (in
+ * authoring order; projectors sort where they need to), then every story
+ * `pragma.conf.ts` declares that no authored module already claims. Since
+ * L-OPEN-9 no DATA noun is authored — the authored array is the kernel's own
+ * nouns and nothing else, and every design-system noun appears only in the
+ * config. No noun literal is written here: the second half is derived.
+ *
+ * Importing this barrel pulls only spec + formatter modules — every run body is
+ * behind a lazy dynamic import, and `distribution.ts` is zod-free — so the
  * `--help`/`__complete` fast paths stay free of the config reader and zod.
  */
 
 import type { CapabilityModule } from "../kernel/spec/types.js";
-import { blockModule } from "./block/index.js";
 import { capabilitiesModule } from "./capabilities/index.js";
 import { colophonModule } from "./colophon/index.js";
 import { configModule } from "./config/index.js";
 import { createModule } from "./create/index.js";
+import { storyModules } from "./distribution.js";
 import { doctorModule } from "./doctor/index.js";
 import { graphModule } from "./graph/index.js";
 import { infoModule } from "./info/index.js";
 import { metaModule } from "./meta/index.js";
-import { modifierModule } from "./modifier/index.js";
 import { ontologyModule } from "./ontology/index.js";
 import { promptModule } from "./prompt/index.js";
 import { setupModule } from "./setup/index.js";
 import { skillModule } from "./skill/index.js";
 import { sourcesModule } from "./sources/index.js";
-import { standardModule } from "./standard/index.js";
-import { tierModule } from "./tier/index.js";
-import { tokenModule } from "./token/index.js";
 import { upgradeModule } from "./upgrade/index.js";
 
-/** Every capability module, in authoring order. */
-export const capabilities: readonly CapabilityModule[] = [
+/** The modules with hand-written code, in authoring order. */
+const authored: readonly CapabilityModule[] = [
   infoModule,
   configModule,
   createModule,
   sourcesModule,
-  standardModule,
-  tierModule,
-  modifierModule,
-  tokenModule,
-  blockModule,
   ontologyModule,
   skillModule,
   graphModule,
@@ -52,3 +48,11 @@ export const capabilities: readonly CapabilityModule[] = [
   colophonModule,
   metaModule,
 ];
+
+const claimed = new Set(authored.map((module) => module.name));
+
+/** Every capability module: the authored ones, then the unclaimed declared stories. */
+export const capabilities: readonly CapabilityModule[] = [
+  ...authored,
+  ...[...storyModules.values()].filter((module) => !claimed.has(module.name)),
+];

package/src/capabilities/info/collectInfo.ts

@@ -6,10 +6,12 @@
  * the npm registry — this deliberately REVERSES PR1's networkless-D11 stance for
  * `info` (the reversal IS the enrichment), unconditional because the covenant
  * `info` verb carries no flag, 3s timeout, silent-fail — and (b) a storeless
- * entity total from the pack index (`readPackIndex`, the same reader `sources
- * status` uses). Neither enrichment boots the store, so the storeless-guarantee
- * spy still sees `store.booted === false`. Kept out of the spec module so
- * building the command tree never pulls it onto the `--help` fast path.
+ * entity total, read from the index of whichever pack the boot decision names
+ * (`resolveSources` → `readPackIndex`, the same predicate `sources status` and
+ * `doctor` switch on) so `info` never counts a graph this project's reads
+ * refuse. Neither enrichment boots the store, so the storeless-guarantee spy
+ * still sees `store.booted === false`. Kept out of the spec module so building
+ * the command tree never pulls it onto the `--help` fast path.
  */
 
 import {
@@ -17,6 +19,7 @@ import {
   readPackIndex,
 } from "../../kernel/completion/entitySource.js";
 import { readConfig } from "../../kernel/config/readConfig.js";
+import { resolveSources } from "../../kernel/runtime/resolveSources.js";
 import type { PragmaRuntime } from "../../kernel/runtime/types.js";
 import {
   detectInstallSource,
@@ -50,8 +53,9 @@ export async function collectInfo(runtime: PragmaRuntime): Promise<InfoData> {
       : undefined;
   const updateSkipped = registry === undefined;
 
-  // Entity total: storeless — the same pack-index reader `sources status` uses.
-  const index = readPackIndex(runtime.cwd);
+  // Entity total: storeless, over the pack the boot decision names — so a
+  // configured-but-unbuilt project reports no total rather than the snapshot's.
+  const index = readPackIndex(resolveSources(layers, runtime.cwd));
   const entities = index ? entityTotal(index) : undefined;
 
   return {

package/src/capabilities/info/info.render.ts

@@ -2,6 +2,7 @@
  * Formatters for `pragma info` — plain, llm, json (no ink).
  */
 
+import { BIN_NAME } from "../../constants.js";
 import type { ConfigOrigin } from "../../kernel/config/types.js";
 import type { Formatters } from "../../kernel/spec/types.js";
 import type { InfoData } from "./types.js";
@@ -15,7 +16,7 @@ export const infoFormatters: Formatters<InfoData> = {
   plain(data) {
     const { config } = data;
     const lines = [
-      `pragma v${data.version}`,
+      `${BIN_NAME} v${data.version}`,
       `  Installed via: ${data.installSource}`,
       `  tier: ${config.tier ?? "(none)"}${originMarker(config.origins.tier)}`,
       `  channel: ${config.channel}${originMarker(config.origins.channel)}`,
@@ -45,7 +46,7 @@ export const infoFormatters: Formatters<InfoData> = {
   llm(data) {
     const { config } = data;
     const lines = [
-      `# pragma v${data.version}`,
+      `# ${BIN_NAME} v${data.version}`,
       `- Installed via: ${data.installSource}`,
       `- Tier: ${config.tier ?? "(none)"}${originMarker(config.origins.tier)}`,
       `- Channel: ${config.channel}${originMarker(config.origins.channel)}`,

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

@@ -6,6 +6,7 @@
  * the config reader or zod onto the fast path.
  */
 
+import { BIN_NAME } from "../../constants.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
 import type { CapabilityModule, VerbSpec } from "../../kernel/spec/types.js";
 import { infoFormatters } from "./info.render.js";
@@ -18,9 +19,9 @@ const infoVerb: VerbSpec<Record<string, unknown>, InfoData> = {
   params: [],
   output: { formatters: infoFormatters },
   examples: [
-    { cmd: "pragma info", note: "human-readable summary" },
+    { cmd: `${BIN_NAME} info`, note: "human-readable summary" },
     {
-      cmd: "pragma info --format json",
+      cmd: `${BIN_NAME} info --format json`,
       note: "the full {ok,data,meta} envelope",
     },
   ],

package/src/capabilities/lazy.test.ts

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { dirname, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { describe, expect, it } from "vitest";
 
@@ -45,10 +45,63 @@ describe("lazy dispatch — module-graph probe (PROTECTED)", () => {
     expect(has(graph, "info/info.render.ts")).toBe(true);
     expect(has(graph, "config/show.render.ts")).toBe(true);
 
-    // ...but run bodies and the config reader are only dynamic-imported.
+    // ...but run bodies and the config LAYER stay behind the dynamic boundary:
+    // no reader, no defaults layer, no zod schema. The distribution config
+    // itself IS on the graph — `constants.ts` projects the program's identity
+    // from it, `render/prefixes.ts` its domain namespaces and
+    // `kernel/vocabulary.ts` its domain terms — which is safe only because it
+    // is inert data (pinned below).
     expect(has(graph, "info/collectInfo.ts")).toBe(false);
     expect(has(graph, "config/collectConfigShow.ts")).toBe(false);
     expect(has(graph, "kernel/config/readConfig.ts")).toBe(false);
+    expect(has(graph, "kernel/config/defaults.ts")).toBe(false);
+    expect(has(graph, "kernel/config/schema.ts")).toBe(false);
+    expect(has(graph, "pragma.conf.ts")).toBe(true);
+  });
+
+  it("the distribution config is inert data — it imports nothing that runs", () => {
+    const conf = resolve(here, "../../pragma.conf.ts");
+    const pkgRoot = resolve(here, "../..");
+    // The graph walker follows `from "…"` textually and cannot tell an
+    // `import type` from a value import, so the type-only `config/types.ts`
+    // and `packs/types.ts` show up here even though nothing of either survives
+    // compilation. Assert that NO file on the graph has a value import — not
+    // just the conf. That is the claim in the title, and it is what keeps
+    // `--help`/`__complete`/`--version` free of module-init work when another
+    // lane or a fork edits any of these three (`packs/types.ts` in particular
+    // is the grammar that type-checks the declared stories, and its own
+    // docblock promises it stays zod-free BECAUSE it lands here).
+    const graph = [...staticImportGraph(conf)];
+    for (const file of graph) {
+      expect(readFileSync(file, "utf-8"), file).not.toMatch(
+        /^import (?!type\b)/m,
+      );
+    }
+    // The enumeration is exact, not a subset: a type import from a module that
+    // itself imports something grows this list and fails here.
+    expect(graph.map((f) => relative(pkgRoot, f)).sort()).toEqual([
+      "pragma.conf.ts",
+      "src/kernel/config/types.ts",
+      "src/kernel/packs/types.ts",
+    ]);
+  });
+
+  it("the dispatch path never reaches the embedded n-quads module (PROTECTED)", () => {
+    // `activeStories` reads the pack's carried stories from their OWN generated
+    // module rather than through `graphpack/embedded.ts`, which statically
+    // imports the ~1.9 MB `pack.generated.ts`. Restoring that edge costs a
+    // measured +23 ms on EVERY dispatched command, and the whole test suite
+    // passes with it restored — the split is prose in three docblocks and
+    // nothing else. This is the constraint those docblocks describe.
+    for (const entry of [
+      "../kernel/packs/collect.ts",
+      "../kernel/runtime/graphpack/stories.ts",
+      "../kernel/runtime/resolveSources.ts",
+    ]) {
+      const graph = staticImportGraph(resolve(here, entry));
+      expect(has(graph, "embedded/pack.generated.ts"), entry).toBe(false);
+      expect(has(graph, "graphpack/embedded.ts"), entry).toBe(false);
+    }
   });
 
   it("the help path (buildProgram) imports no zod schema module", () => {
@@ -86,4 +139,42 @@ describe("lazy dispatch — module-graph probe (PROTECTED)", () => {
       }
     }
   });
+
+  it("NO module on that graph statically imports zod (PROTECTED)", () => {
+    // This used to pin an exact set of one — `graphpack/types.ts`, reached via
+    // `resolveSources` → `packIsComplete` → `readManifest` → `manifestSchema
+    // .parse` — as the one genuine zod value import on the storeless graph,
+    // measured at ~3–4 ms of a ~30 ms budget. Its own comment said an exact set
+    // was what would make the day it got fixed impossible to miss. That day is
+    // this commit: the schemas moved to `graphpack/schemas.ts`, imported only by
+    // the two readers already off the fast path, and `readManifest` validates
+    // structurally instead.
+    //
+    // The set is now EMPTY, which is strictly stronger than the pin it replaces:
+    // it no longer tolerates one named module, so a brand-new module value-
+    // importing zod fails here too — the gap the previous form left open.
+    const graph = staticImportGraph(resolve(here, "index.ts"));
+    const pkgRoot = resolve(here, "..", "..");
+    const zodImporters = [...graph]
+      .filter((file) => /from\s*["']zod["']/.test(readFileSync(file, "utf-8")))
+      .map((file) => relative(pkgRoot, file))
+      .sort();
+    expect(zodImporters).toEqual([]);
+  });
+
+  it("the help path (buildProgram) imports zod from nowhere (PROTECTED)", () => {
+    // The named-module check above (`kernel/config/schema.ts`,
+    // `kernel/spec/validate.ts`) could only catch the two modules it names — a
+    // third zod importer reaching the help path would have passed it silently.
+    // Generalized (ruling R4) to the property those names were standing in for.
+    const graph = staticImportGraph(
+      resolve(here, "../kernel/project/cli/buildProgram.ts"),
+    );
+    const pkgRoot = resolve(here, "..", "..");
+    const zodImporters = [...graph]
+      .filter((file) => /from\s*["']zod["']/.test(readFileSync(file, "utf-8")))
+      .map((file) => relative(pkgRoot, file))
+      .sort();
+    expect(zodImporters).toEqual([]);
+  });
 });

package/src/capabilities/ontology/index.ts

@@ -3,10 +3,17 @@
  */
 
 import type { CapabilityModule } from "../../kernel/spec/types.js";
-import { ontologyListVerb, ontologyShowVerb } from "./verbs.js";
+import {
+  ontologyListVerb,
+  ontologyLookupVerb,
+  ontologyShowVerb,
+} from "./verbs.js";
 
-/** The `ontology` capability module (`list`, `show`). */
+/**
+ * The `ontology` capability module (`list`, `lookup`, and the deprecated `show`
+ * alias — AV-228 B1).
+ */
 export const ontologyModule: CapabilityModule = {
   name: "ontology",
-  verbs: [ontologyListVerb, ontologyShowVerb],
+  verbs: [ontologyListVerb, ontologyLookupVerb, ontologyShowVerb],
 };

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

@@ -15,13 +15,23 @@ import {
   BLOCK_PREFIXES,
   BLOCK_TTL,
 } from "../../testing/fixtures/blockGraph.js";
+import { CANONICAL_TTL } from "../../testing/fixtures/graph/canonical.js";
+import {
+  bootFixtureRuntime,
+  type FixtureGraph,
+} from "../../testing/helpers/fixtureGraph.js";
 import { buildFixtureRuntime } from "../../testing/helpers/packRuntime.js";
+import { projectMcp } from "../../testing/helpers/projectMcp.js";
+import { capabilities } from "../index.js";
 import { ontologyModule } from "./index.js";
 import type { OntologyShowData, OntologySummary } from "./queries.js";
 
 const listVerb = ontologyModule.verbs.find(
   (v) => verbKey(v.path) === "ontology list",
 ) as VerbSpec;
+const lookupVerb = ontologyModule.verbs.find(
+  (v) => verbKey(v.path) === "ontology lookup",
+) as VerbSpec;
 const showVerb = ontologyModule.verbs.find(
   (v) => verbKey(v.path) === "ontology show",
 ) as VerbSpec;
@@ -48,9 +58,12 @@ describe("ontology list", () => {
   });
 });
 
-describe("ontology show", () => {
+describe("ontology lookup (primary by-name read)", () => {
   it("renders the class hierarchy with per-class instance counts from the index", async () => {
-    const data = (await showVerb.run({ prefix: "ds" }, rt)) as OntologyShowData;
+    const data = (await lookupVerb.run(
+      { prefix: "ds" },
+      rt,
+    )) as OntologyShowData;
     const component = data.classes.find((c) => c.uri.endsWith("Component"));
     expect(component?.superclass).toBe("https://ds.canonical.com/UIBlock");
     // Two Component individuals (Button, Modal) in the fixture.
@@ -58,8 +71,34 @@ describe("ontology show", () => {
     expect(data.properties).toEqual([]);
   });
 
+  it("--detail detailed folds onto disclosure and includes properties (B5)", async () => {
+    // Ontology honours the canonical `--detail` instead of only its bespoke
+    // `--properties`: standard/detailed add the properties section.
+    const detailed = {
+      ...rt,
+      globalFlags: { ...rt.globalFlags, detail: "detailed" as const },
+    };
+    const data = (await lookupVerb.run(
+      { prefix: "ds" },
+      detailed,
+    )) as OntologyShowData;
+    expect(data.properties.length).toBeGreaterThan(0);
+  });
+
+  it("--detail summary keeps classes only (no properties)", async () => {
+    const summary = {
+      ...rt,
+      globalFlags: { ...rt.globalFlags, detail: "summary" as const },
+    };
+    const data = (await lookupVerb.run(
+      { prefix: "ds" },
+      summary,
+    )) as OntologyShowData;
+    expect(data.properties).toEqual([]);
+  });
+
   it("--class focuses on one class and its properties", async () => {
-    const data = (await showVerb.run(
+    const data = (await lookupVerb.run(
       { prefix: "ds", class: "BlockProperty" },
       rt,
     )) as OntologyShowData;
@@ -77,18 +116,131 @@ describe("ontology show", () => {
   });
 
   it("--full-uris flag rides on the payload for the renderer", async () => {
-    const data = (await showVerb.run(
+    const data = (await lookupVerb.run(
       { prefix: "ds", fullUris: true },
       rt,
     )) as OntologyShowData;
     expect(data.fullUris).toBe(true);
-    const llm = showVerb.output.formatters.llm(data);
+    const llm = lookupVerb.output.formatters.llm(data);
     expect(llm).toContain("https://ds.canonical.com/Component");
   });
 
   it("rejects an unknown prefix with recovery", async () => {
+    await expect(lookupVerb.run({ prefix: "nope" }, rt)).rejects.toThrow(
+      /prefix/i,
+    );
+  });
+});
+
+describe("ontology show — deprecated alias of lookup (AV-228 B1)", () => {
+  it("is marked deprecated in its summary and steers callers to `ontology lookup`", () => {
+    expect(showVerb.summary.toLowerCase()).toContain("deprecated");
+    expect(showVerb.summary).toContain("ontology lookup");
+  });
+
+  it("shares the lookup handler — same payload for the same input", async () => {
+    const viaLookup = (await lookupVerb.run(
+      { prefix: "ds", properties: true },
+      rt,
+    )) as OntologyShowData;
+    const viaShow = (await showVerb.run(
+      { prefix: "ds", properties: true },
+      rt,
+    )) as OntologyShowData;
+    expect(viaShow).toEqual(viaLookup);
+  });
+
+  it("still rejects an unknown prefix (the alias is a full, callable verb)", async () => {
     await expect(showVerb.run({ prefix: "nope" }, rt)).rejects.toThrow(
       /prefix/i,
     );
   });
 });
+
+describe("ontology_show honours detail over MCP (B5)", () => {
+  // The CLI B5 cases above seed `globalFlags.detail` and call `showVerb.run`
+  // directly. Over MCP there are NO global flags — the ONLY detail channel is
+  // the per-tool `detail` param the projector injects from the VerbSpec
+  // disclosure. Under an AMBIENT config `detail: standard`, an `ontology_show`
+  // with no declared disclosure would force the properties section with no
+  // per-call escape (the AV-228 MCP-opt-out asymmetry `block`/`standard` lack);
+  // declaring disclosure lights the param up, so an agent can ask for
+  // classes-only per call and can equally override upward.
+  let fixture: FixtureGraph;
+  let mcp: Awaited<ReturnType<typeof projectMcp>>;
+
+  beforeAll(async () => {
+    // Ambient config detail=standard → origins.detail === "project", so it
+    // outranks the verb's `summary` default inside resolvePackDetail.
+    fixture = await bootFixtureRuntime({
+      ttl: CANONICAL_TTL,
+      config: { detail: "standard" },
+    });
+    mcp = await projectMcp(capabilities, fixture.cwd);
+  });
+
+  afterAll(async () => {
+    await mcp.cleanup();
+    await fixture.dispose();
+  });
+
+  it("injects a detail param onto the ontology_show tool (symmetric with block/standard)", async () => {
+    const tools = await mcp.listTools();
+    const show = tools.find((t) => t.name === "ontology_show");
+    const schema = show?.inputSchema as {
+      properties?: Record<string, unknown>;
+    };
+    expect(schema.properties?.detail).toBeDefined();
+  });
+
+  it("exposes the primary ontology_lookup tool with the same injected detail param (AV-228 B1)", async () => {
+    const tools = await mcp.listTools();
+    const lookup = tools.find((t) => t.name === "ontology_lookup");
+    expect(lookup).toBeDefined();
+    const schema = lookup?.inputSchema as {
+      properties?: Record<string, unknown>;
+    };
+    expect(schema.properties?.detail).toBeDefined();
+  });
+
+  it("ontology_lookup honours a per-call detail=summary despite the ambient standard", async () => {
+    const result = await mcp.callTool("ontology_lookup", {
+      prefix: "ds",
+      detail: "summary",
+    });
+    expect(result.ok).toBe(true);
+    const data = result.data as { classes: unknown[]; properties: unknown[] };
+    expect(data.classes.length).toBeGreaterThan(0);
+    expect(data.properties).toEqual([]);
+  });
+
+  it("honours the ambient detail=standard config when no per-call detail is set", async () => {
+    // Proves the ambient level really is standard, so the summary case below is
+    // a genuine per-call override rather than merely the spec default.
+    const result = await mcp.callTool("ontology_show", { prefix: "ds" });
+    expect(result.ok).toBe(true);
+    const data = result.data as { properties: unknown[] };
+    expect(data.properties.length).toBeGreaterThan(0);
+  });
+
+  it("a per-call detail=summary returns classes-only despite the ambient standard", async () => {
+    const result = await mcp.callTool("ontology_show", {
+      prefix: "ds",
+      detail: "summary",
+    });
+    expect(result.ok).toBe(true);
+    const data = result.data as { classes: unknown[]; properties: unknown[] };
+    expect(data.classes.length).toBeGreaterThan(0);
+    expect(data.properties).toEqual([]);
+  });
+
+  it("an explicit detail=detailed overrides upward to include properties", async () => {
+    const result = await mcp.callTool("ontology_show", {
+      prefix: "ds",
+      detail: "detailed",
+    });
+    expect(result.ok).toBe(true);
+    const data = result.data as { properties: unknown[] };
+    expect(data.properties.length).toBeGreaterThan(0);
+  });
+});