@canonical/pragma-cli 0.32.0 → 0.34.0

package/src/capabilities/ontology/verbs.ts

@@ -1,17 +1,38 @@
 /**
- * `ontology list` and `ontology show <prefix>` — schema (TBox) inspection.
+ * `ontology list` and `ontology lookup <prefix>` — schema (TBox) inspection.
  *
- * `list` groups loaded namespaces by prefix with class/property counts; `show`
+ * `list` groups loaded namespaces by prefix with class/property counts; `lookup`
  * renders a namespace's class hierarchy (with per-class instance counts read
- * from the pack index) and, with `--properties` or a `--class` focus, its
- * properties. `--full-uris` shows absolute IRIs; `--class <name>` narrows to one
- * class and the properties whose domain is that class.
+ * from the pack index) and, with `--properties`, a `--class` focus, or a
+ * `--detail` of `standard`+, its properties. `--full-uris` shows absolute IRIs;
+ * `--class <name>` narrows to one class and the properties whose domain is that
+ * class.
+ *
+ * `ontology show` is the DEPRECATED alias of `ontology lookup` (AV-228 B1): the
+ * verb was renamed to `lookup` for consistency with block/standard/tier/etc.
+ * (the ratified by-name read name), and `show` is kept callable — both share the
+ * same params, disclosure, and handler, and both stay blessed in the covenant.
+ *
+ * Disclosure (B5): rather than reinvent its own scheme, the by-name read declares
+ * the canonical disclosure ladder and honours the `--detail`/config `detail` the
+ * rest of the CLI reads AND the injected `detail` tool param the MCP projector
+ * derives from that declaration — a two-behaviour fold where `summary` is
+ * classes-only and `standard`/`detailed` add the properties section. The frozen
+ * `--properties` flag stays as an explicit override (it forces the section at
+ * any level), so the covenant is untouched.
  */
 
+import { BIN_NAME } from "../../constants.js";
 import { PragmaError } from "../../kernel/error/PragmaError.js";
+import { cliRecovery } from "../../kernel/error/recovery.js";
+import { resolvePackDetail } from "../../kernel/packs/disclosure.js";
 import type { PragmaRuntime } from "../../kernel/runtime/types.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
-import type { VerbSpec } from "../../kernel/spec/types.js";
+import type {
+  DisclosureSpec,
+  ParamSpec,
+  VerbSpec,
+} from "../../kernel/spec/types.js";
 import {
   listNamespaces,
   localName,
@@ -32,22 +53,22 @@ function resolvePrefix(
     if (entry) return { prefix: entry[0], namespace: entry[1] };
     throw PragmaError.invalidInput("namespace", input, {
       validOptions: Object.values(prefixes),
-      recovery: {
-        message: "List loaded ontology namespaces.",
-        cli: "pragma ontology list",
-        mcp: { tool: "ontology_list" },
-      },
+      recovery: cliRecovery(
+        "ontology list",
+        "List loaded ontology namespaces.",
+        {
+          tool: "ontology_list",
+        },
+      ),
     });
   }
   const namespace = prefixes[input];
   if (namespace === undefined) {
     throw PragmaError.invalidInput("prefix", input, {
       validOptions: Object.keys(prefixes),
-      recovery: {
-        message: "List loaded ontologies.",
-        cli: "pragma ontology list",
-        mcp: { tool: "ontology_list" },
-      },
+      recovery: cliRecovery("ontology list", "List loaded ontologies.", {
+        tool: "ontology_list",
+      }),
     });
   }
   return { prefix: input, namespace };
@@ -58,7 +79,7 @@ const listVerb: VerbSpec<Record<string, unknown>, OntologySummary[]> = {
   summary: "List loaded ontology namespaces with class and property counts.",
   params: [],
   output: { formatters: ontologyListFormatters },
-  examples: [{ cmd: "pragma ontology list" }],
+  examples: [{ cmd: `${BIN_NAME} ontology list` }],
   capability: {
     needsStore: true,
     mutates: false,
@@ -73,98 +94,176 @@ const listVerb: VerbSpec<Record<string, unknown>, OntologySummary[]> = {
   },
 };
 
-const showVerb: VerbSpec<Record<string, unknown>, OntologyShowData> = {
-  path: ["ontology", "show"],
-  summary: "Show a namespace's classes (hierarchy + counts) and properties.",
-  params: [
-    {
-      kind: "string",
-      name: "prefix",
-      doc: "The namespace prefix (ds) or full URI.",
-      positional: true,
-      required: true,
-      complete: { kind: "names", source: { from: "prefixes" } },
-    },
-    {
-      kind: "boolean",
-      name: "properties",
-      doc: "Include the properties section.",
-    },
-    {
-      kind: "boolean",
-      name: "fullUris",
-      doc: "Show full IRIs instead of prefixed.",
-    },
-    {
-      kind: "string",
-      name: "class",
-      doc: "Focus on one class and its properties.",
-    },
-  ],
-  output: { formatters: ontologyShowFormatters },
-  examples: [
-    { cmd: "pragma ontology show ds" },
-    { cmd: "pragma ontology show ds --properties" },
-    { cmd: "pragma ontology show ds --class Component" },
-  ],
-  capability: {
-    needsStore: true,
-    mutates: false,
-    mcp: {
-      expose: true,
-      annotations: { readOnlyHint: true, openWorldHint: false },
-    },
+/**
+ * The canonical disclosure the by-name read folds onto (B5). Declared on both
+ * the primary {@link ontologyLookupVerb} and its deprecated {@link
+ * ontologyShowVerb} alias — so the MCP projector injects the `detail` enum tool
+ * param and its per-call `withDetail` seeding light up (symmetric with
+ * `block`/`standard`, which an inline resolve left dark over MCP) — AND read by
+ * `run` to resolve the effective level, so the advertised param and the fetched
+ * level share ONE source. The levels are the full canonical ladder; the fold is
+ * two-behaviour (`summary` = classes only, `standard`/`detailed` add properties).
+ */
+const BY_NAME_DISCLOSURE: DisclosureSpec = {
+  levels: ["summary", "standard", "detailed"],
+  default: "summary",
+};
+
+/** The params shared by `ontology lookup` and its deprecated `ontology show` alias. */
+const BY_NAME_PARAMS: ParamSpec[] = [
+  {
+    kind: "string",
+    name: "prefix",
+    doc: "The namespace prefix (ds) or full URI.",
+    positional: true,
+    required: true,
+    complete: { kind: "names", source: { from: "prefixes" } },
   },
-  run: async (params: Record<string, unknown>, rt: PragmaRuntime) => {
-    const session = await rt.store.get();
-    const { prefix, namespace } = resolvePrefix(
-      String(params.prefix),
-      session.prefixes,
-    );
-    const focus = typeof params.class === "string" ? params.class : undefined;
-    const wantProperties = params.properties === true || focus !== undefined;
+  {
+    kind: "boolean",
+    name: "properties",
+    doc: "Include the properties section (also implied by --detail standard or higher).",
+  },
+  {
+    kind: "boolean",
+    name: "fullUris",
+    doc: "Show full IRIs instead of prefixed.",
+  },
+  {
+    kind: "string",
+    name: "class",
+    doc: "Focus on one class and its properties.",
+  },
+];
 
-    let classes = await queryClasses(
-      rt,
-      namespace,
-      session.index.instanceCountByType,
+/** The by-name read capability — a storeless-free, read-only MCP tool. */
+const BY_NAME_CAPABILITY = {
+  needsStore: true,
+  mutates: false,
+  mcp: {
+    expose: true as const,
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
+};
+
+/**
+ * The by-name read handler shared by `ontology lookup` and `ontology show`.
+ *
+ * @param params - The coerced param bag (`prefix`, `properties`, `fullUris`, `class`).
+ * @param rt - The runtime (store + disclosure precedence).
+ * @returns The namespace's classes (and, per disclosure, properties) payload.
+ */
+async function runByName(
+  params: Record<string, unknown>,
+  rt: PragmaRuntime,
+): Promise<OntologyShowData> {
+  const session = await rt.store.get();
+  const { prefix, namespace } = resolvePrefix(
+    String(params.prefix),
+    session.prefixes,
+  );
+  const focus = typeof params.class === "string" ? params.class : undefined;
+  // Fold ontology's bespoke disclosure onto the canonical `--detail` (B5),
+  // resolving through the SAME {@link BY_NAME_DISCLOSURE} the verb declares (so
+  // the MCP `detail` param and its withDetail seeding resolve identically, not
+  // just the CLI `--detail` flag) and the SAME precedence packs use (flag >
+  // explicit config > default). The frozen `--properties` flag and a `--class`
+  // focus still force the section, so honouring the level is covenant-safe.
+  const level = await resolvePackDetail(rt, BY_NAME_DISCLOSURE);
+  const wantProperties =
+    params.properties === true || focus !== undefined || level !== "summary";
+
+  let classes = await queryClasses(
+    rt,
+    namespace,
+    session.index.instanceCountByType,
+  );
+  let properties = wantProperties ? await queryProperties(rt, namespace) : [];
+
+  if (focus !== undefined) {
+    const needle = focus.toLowerCase();
+    classes = classes.filter(
+      (c) =>
+        localName(c.uri).toLowerCase() === needle ||
+        c.label.toLowerCase() === needle,
+    );
+    const focusUris = new Set(classes.map((c) => c.uri));
+    properties = properties.filter(
+      (p) => p.domain !== undefined && focusUris.has(p.domain),
     );
-    let properties = wantProperties ? await queryProperties(rt, namespace) : [];
+  }
 
-    if (focus !== undefined) {
-      const needle = focus.toLowerCase();
-      classes = classes.filter(
-        (c) =>
-          localName(c.uri).toLowerCase() === needle ||
-          c.label.toLowerCase() === needle,
-      );
-      const focusUris = new Set(classes.map((c) => c.uri));
-      properties = properties.filter(
-        (p) => p.domain !== undefined && focusUris.has(p.domain),
-      );
-    }
+  if (classes.length === 0 && properties.length === 0) {
+    throw PragmaError.notFound("ontology", String(params.prefix), {
+      recovery: cliRecovery("ontology list", "List loaded ontologies.", {
+        tool: "ontology_list",
+      }),
+    });
+  }
 
-    if (classes.length === 0 && properties.length === 0) {
-      throw PragmaError.notFound("ontology", String(params.prefix), {
-        recovery: {
-          message: "List loaded ontologies.",
-          cli: "pragma ontology list",
-          mcp: { tool: "ontology_list" },
-        },
-      });
-    }
+  return {
+    prefix,
+    namespace,
+    classes,
+    properties,
+    fullUris: params.fullUris === true,
+    ...(focus !== undefined ? { focus } : {}),
+  };
+}
 
-    return {
-      prefix,
-      namespace,
-      classes,
-      properties,
-      fullUris: params.fullUris === true,
-      ...(focus !== undefined ? { focus } : {}),
-    };
-  },
-};
+/**
+ * Build one by-name read verb (`lookup` primary or `show` deprecated alias) —
+ * both share {@link BY_NAME_PARAMS}, {@link BY_NAME_DISCLOSURE}, the formatters,
+ * and {@link runByName}; only the path label, summary, doc, and examples differ.
+ */
+function byNameVerb(
+  verb: "lookup" | "show",
+  summary: string,
+  examples: VerbSpec["examples"],
+  doc?: string,
+): VerbSpec<Record<string, unknown>, OntologyShowData> {
+  return {
+    path: ["ontology", verb],
+    summary,
+    ...(doc !== undefined ? { doc } : {}),
+    params: BY_NAME_PARAMS,
+    output: { formatters: ontologyShowFormatters },
+    examples,
+    disclosure: BY_NAME_DISCLOSURE,
+    capability: BY_NAME_CAPABILITY,
+    run: runByName,
+  };
+}
 
-/** The `ontology` verbs (`list`, `show`). */
+/** The `ontology` verbs (`list`, `lookup`, and the deprecated `show` alias). */
 export const ontologyListVerb = asVerb(listVerb);
-export const ontologyShowVerb = asVerb(showVerb);
+
+/** `ontology lookup <prefix>` — the primary by-name schema read. */
+export const ontologyLookupVerb = asVerb(
+  byNameVerb(
+    "lookup",
+    "Look up a namespace's classes (hierarchy + counts) and properties.",
+    [
+      { cmd: `${BIN_NAME} ontology lookup ds` },
+      { cmd: `${BIN_NAME} ontology lookup ds --properties` },
+      { cmd: `${BIN_NAME} ontology lookup ds --class Component` },
+    ],
+  ),
+);
+
+/**
+ * `ontology show <prefix>` — DEPRECATED alias of {@link ontologyLookupVerb}
+ * (AV-228 B1). Kept callable and blessed in the covenant; shares the same
+ * handler, so it behaves identically. New callers should use `ontology lookup`.
+ */
+export const ontologyShowVerb = asVerb(
+  byNameVerb(
+    "show",
+    "(deprecated: use `ontology lookup`) Show a namespace's classes (hierarchy + counts) and properties.",
+    [
+      { cmd: `${BIN_NAME} ontology lookup ds`, note: "prefer `lookup`" },
+      { cmd: `${BIN_NAME} ontology show ds`, note: "deprecated alias" },
+    ],
+    "Deprecated alias of `ontology lookup` — retained for compatibility. Prefer `ontology lookup <prefix>`.",
+  ),
+);

package/src/capabilities/prompt/prompt.render.test.ts

@@ -0,0 +1,94 @@
+import chalk from "chalk";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  promptListFormatters,
+  promptLookupFormatters,
+} from "./prompt.render.js";
+import type { PromptListData, PromptLookupData } from "./types.js";
+
+/** Run `body` with stdout's `isTTY` forced to `value`, then restore it. */
+function withStdoutTty(value: boolean | undefined, body: () => void): void {
+  const stream = process.stdout as { isTTY?: boolean };
+  const saved = stream.isTTY;
+  stream.isTTY = value;
+  try {
+    body();
+  } finally {
+    stream.isTTY = saved;
+  }
+}
+
+const LOOKUP: PromptLookupData = {
+  name: "build-a-block",
+  description: "Scaffold a block",
+  arguments: [
+    { name: "blockName", required: true, description: "The block name" },
+    { name: "tier", required: false },
+  ],
+  body: "Create {{blockName}} in {{tier}}.",
+};
+
+const LIST: PromptListData = {
+  prompts: [
+    { name: "build-a-block", description: "Scaffold a block", arguments: [] },
+  ],
+};
+
+describe("promptLookupFormatters", () => {
+  it("underlines the plain name with an ═ rule (B7)", () => {
+    const lines = promptLookupFormatters.plain(LOOKUP).split("\n");
+    expect(lines.at(0)).toBe("build-a-block");
+    expect(lines.at(1)).toBe("═".repeat(24));
+    expect(lines.at(2)).toBe("");
+    expect(lines).toContain("  args: blockName (required), tier");
+  });
+
+  it("heads the llm entity at H2 with H3 sub-sections (B2)", () => {
+    const lines = promptLookupFormatters.llm(LOOKUP).split("\n");
+    expect(lines.at(0)).toBe("## build-a-block");
+    expect(lines).toContain("### Arguments");
+    expect(lines).toContain("### Template");
+    // The old H1 title / H2 sub-sections are gone.
+    expect(lines).not.toContain("# build-a-block");
+    expect(lines).not.toContain("## Arguments");
+    expect(lines).not.toContain("## Template");
+  });
+});
+
+describe("promptListFormatters", () => {
+  it("heads the llm list at H2, never H1 (B2)", () => {
+    const out = promptListFormatters.llm(LIST);
+    expect(out.startsWith("## Prompts")).toBe(true);
+    expect(out).not.toMatch(/^# Prompts/m);
+  });
+});
+
+describe("promptLookupFormatters — shared style seam (B7)", () => {
+  const prevLevel = chalk.level;
+  afterEach(() => {
+    chalk.level = prevLevel;
+  });
+
+  it("styles the plain title on a color-capable TTY", () => {
+    chalk.level = 1;
+    withStdoutTty(true, () => {
+      // The title/rule/label now route through the same style seam block and
+      // skill lookups use — previously a prompt title stayed unstyled on a TTY.
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: asserting the ESC byte is the point
+      expect(promptLookupFormatters.plain(LOOKUP)).toMatch(/\x1b\[/);
+    });
+  });
+
+  it("keeps piped plain output byte-stable off a TTY", () => {
+    chalk.level = 3;
+    withStdoutTty(undefined, () => {
+      const out = promptLookupFormatters.plain(LOOKUP);
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: asserting NO ESC byte survives
+      expect(out).not.toMatch(/\x1b\[/);
+      const lines = out.split("\n");
+      expect(lines.at(0)).toBe("build-a-block");
+      expect(lines.at(1)).toBe("═".repeat(24));
+      expect(lines).toContain("  args: blockName (required), tier");
+    });
+  });
+});

package/src/capabilities/prompt/prompt.render.ts

@@ -2,6 +2,7 @@
  * Formatters for the `prompt` content noun — plain, llm, json.
  */
 
+import { defaultStyle } from "../../kernel/render/style.js";
 import type { Formatters } from "../../kernel/spec/types.js";
 import type {
   PromptArgument,
@@ -29,7 +30,8 @@ export const promptListFormatters: Formatters<PromptListData> = {
   },
   llm(data) {
     if (data.prompts.length === 0) return "_No prompts in the store._";
-    const lines = ["# Prompts"];
+    // H2 for a content read — consistent with the shared list renderer (B2).
+    const lines = ["## Prompts"];
     for (const prompt of data.prompts) {
       lines.push(
         `- \`${prompt.name}\` — ${prompt.description ?? ""}`.trimEnd(),
@@ -45,23 +47,38 @@ export const promptListFormatters: Formatters<PromptListData> = {
 
 export const promptLookupFormatters: Formatters<PromptLookupData> = {
   plain(data) {
-    const lines = [data.name];
+    // Full delegation to `renderLookupPlain` is infeasible: the description line
+    // carries no field label and the template body is appended raw, whereas the
+    // shared renderer only emits `label: value` fields + indented sections. So
+    // route the TITLE + rule + field label through the SAME style seam it uses
+    // (bold title, dim rule, cyan label) — closing the TTY drift where a prompt
+    // title stayed unstyled — and keep the bespoke body inline. Off a TTY the
+    // styler is inert, so piped output stays byte-stable (B7).
+    const style = defaultStyle();
+    const rule = "═".repeat(Math.max(data.name.length, 24));
+    const lines = [style.bold(data.name), style.dim(rule), ""];
     if (data.description) lines.push(`  ${data.description}`);
-    lines.push(`  args: ${argTokens(data.arguments)}`, "", data.body);
+    lines.push(
+      `  ${style.cyan("args")}: ${argTokens(data.arguments)}`,
+      "",
+      data.body,
+    );
     return lines.join("\n");
   },
   llm(data) {
-    const lines = [`# ${data.name}`];
+    // H2 entity title with H3 sub-sections — the hierarchy the shared
+    // `renderLookupLlm` uses (`## title` / `### section`) (B2).
+    const lines = [`## ${data.name}`];
     if (data.description) lines.push(data.description);
     if (data.arguments.length > 0) {
-      lines.push("", "## Arguments");
+      lines.push("", "### Arguments");
       for (const arg of data.arguments) {
         lines.push(
           `- \`${arg.name}\`${arg.required ? " (required)" : ""}${arg.description ? ` — ${arg.description}` : ""}`,
         );
       }
     }
-    lines.push("", "## Template", data.body);
+    lines.push("", "### Template", data.body);
     return lines.join("\n");
   },
   json(data) {

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

@@ -1,6 +1,10 @@
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { listPromptSummaries } from "../../kernel/project/mcp/prompts/source.js";
 import { bootRuntime } from "../../kernel/runtime/boot.js";
+import { resolveSources } from "../../kernel/runtime/resolveSources.js";
 import type { GlobalFlags } from "../../kernel/spec/types.js";
 import { CANONICAL_TTL } from "../../testing/fixtures/graph/canonical.js";
 import {
@@ -112,8 +116,71 @@ describe("prompt — native MCP prompts surface (PROTECTED)", () => {
 describe("prompt — storeless native listing (PROTECTED)", () => {
   it("listing the prompts does NOT boot the store", async () => {
     const runtime = bootRuntime(FLAGS, fixture.cwd);
-    const summaries = listPromptSummaries(runtime);
+    const summaries = listPromptSummaries(
+      resolveSources(await runtime.loadConfig(), runtime.cwd),
+    );
     expect(summaries.map((s) => s.name).sort()).toEqual(EXPECTED);
     expect(runtime.store.booted).toBe(false);
   });
 });
+
+/**
+ * D1/D4 — cold-store convergence. The `prompt_list` tool is store-backed
+ * (`needsStore`), so a cold store throws STORE_UNAVAILABLE through its pre-check;
+ * native `prompts/list`/`prompts/get` must present the SAME diagnostic rather
+ * than silently listing a stale index (D1) or reporting a bogus "not found"
+ * (D4). A project that declares its own packs and has never built them is the
+ * cold "configured but unbuilt" store — the row of the boot decision table
+ * that must never be served the distribution's embedded graph.
+ */
+describe("prompt — cold-store convergence, tool + native agree (D1/D4)", () => {
+  let cold: McpHarness;
+
+  beforeAll(async () => {
+    const cwd = mkdtempSync(join(tmpdir(), "pragma-prompt-cold-"));
+    writeFileSync(
+      join(cwd, "pragma.config.ts"),
+      `export default { packs: [{ name: "unbuilt", source: "file:///pragma-never-built" }] };\n`,
+    );
+    cold = await projectMcp(capabilities, cwd);
+  });
+  afterAll(async () => {
+    await cold.cleanup();
+  });
+
+  it("prompt_list (tool) and prompts/list (native) BOTH surface STORE_UNAVAILABLE", async () => {
+    const tool = await cold.callTool("prompt_list");
+    expect(tool.ok).toBe(false);
+    expect((tool.error as { code: string }).code).toBe("STORE_UNAVAILABLE");
+    // The native list no longer diverges into a silent [] / stale index listing.
+    await expect(cold.listPrompts()).rejects.toThrow(/store unavailable/i);
+  });
+
+  it("both surfaces carry the same `sources_update` recovery cold", async () => {
+    const tool = await cold.callTool("prompt_list");
+    const toolRecovery = (
+      tool.error as { recovery?: { mcp?: { tool?: string } } }
+    ).recovery;
+    expect(toolRecovery?.mcp?.tool).toBe("sources_update");
+
+    // Native carries the recovery in the JSON-RPC error `data` — never dropped.
+    const nativeErr = await cold.listPrompts().then(
+      () => undefined,
+      (error: unknown) => error,
+    );
+    const data = (
+      nativeErr as { data?: { recovery?: { mcp?: { tool?: string } } } }
+    ).data;
+    expect(data?.recovery?.mcp?.tool).toBe("sources_update");
+  });
+
+  it("native prompts/get reports STORE_UNAVAILABLE cold, not a bogus 'not found' (D4)", async () => {
+    const error = await cold.getPrompt("build-a-block").then(
+      () => undefined,
+      (caught: unknown) => caught as Error,
+    );
+    expect(error?.message).toMatch(/store unavailable/i);
+    // The genuine-miss message must NOT mask the cold store.
+    expect(error?.message).not.toMatch(/not found/i);
+  });
+});

package/src/capabilities/prompt/verbs.ts

@@ -12,10 +12,13 @@
  * formatters).
  */
 
+import { BIN_NAME } from "../../constants.js";
 import { PragmaError } from "../../kernel/error/PragmaError.js";
+import { cliRecovery } from "../../kernel/error/recovery.js";
 import type { PragmaRuntime } from "../../kernel/runtime/types.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
 import type { VerbSpec } from "../../kernel/spec/types.js";
+import { VOCABULARY } from "../../kernel/vocabulary.js";
 import {
   promptListFormatters,
   promptLookupFormatters,
@@ -34,10 +37,10 @@ const READ_CAPABILITY = {
 const listVerb: VerbSpec<Record<string, unknown>, PromptListData> = {
   path: ["prompt", "list"],
   summary: "List the workflow prompt templates the design system offers.",
-  doc: "Browse the ds:Prompt entities in the active graph — name, description, and argument names. The same prompts are offered natively over MCP prompts/list; use prompt_lookup for the full template body.",
+  doc: `Browse the prompt entities the active graph declares (${VOCABULARY.prompt.type} in this distribution) — name, description, and argument names. This distribution's graph carries none today. The same prompts are offered natively over MCP prompts/list; use prompt_lookup for the full template body.`,
   params: [],
   output: { formatters: promptListFormatters },
-  examples: [{ cmd: "pragma prompt list" }],
+  examples: [{ cmd: `${BIN_NAME} prompt list` }],
   capability: READ_CAPABILITY,
   run: (_params: Record<string, unknown>, rt: PragmaRuntime) =>
     import("../../kernel/project/mcp/prompts/source.js").then(async (m) => {
@@ -55,19 +58,31 @@ const listVerb: VerbSpec<Record<string, unknown>, PromptListData> = {
 const lookupVerb: VerbSpec<Record<string, unknown>, PromptLookupData> = {
   path: ["prompt", "lookup"],
   summary: "Show one workflow prompt template's body and arguments by name.",
-  doc: "Fetch a single ds:Prompt entity's full template body (with {{arg}} placeholders) and its declared arguments.",
+  doc: "Fetch a single prompt entity's full template body (with {{arg}} placeholders) and its declared arguments. A prompt is addressed by its label; prompt_list names the ones the active graph carries.",
   params: [
     {
       kind: "string",
       name: "name",
-      doc: "The prompt name (e.g. build-a-block).",
+      doc: "The prompt name, as `prompt list` reports it.",
       positional: true,
       required: true,
-      complete: { kind: "names", source: { from: "prompts" } },
+      // A prompt is addressed by its `rdfs:label`, which the index carries as
+      // `label`, and the index reader offers no substitute for a prompt that
+      // carries none. Not a total guarantee: `label` is the first of several
+      // label predicates the index accepts, so an entity labelled ONLY by
+      // `skos:prefLabel` would still complete without resolving. That gap is
+      // the index's label preference order, not this ref.
+      complete: {
+        kind: "names",
+        source: { from: "index", type: VOCABULARY.prompt.type, field: "label" },
+      },
     },
   ],
   output: { formatters: promptLookupFormatters },
-  examples: [{ cmd: "pragma prompt lookup build-a-block" }],
+  // No example command: this distribution's graph declares no prompt, so any
+  // name quoted here exits 1 with ENTITY_NOT_FOUND — and this is the GENERATED
+  // reference, published as machine-derived truth.
+  examples: [],
   capability: READ_CAPABILITY,
   run: (params: Record<string, unknown>, rt: PragmaRuntime) =>
     import("../../kernel/project/mcp/prompts/source.js").then(async (m) => {
@@ -77,11 +92,9 @@ const lookupVerb: VerbSpec<Record<string, unknown>, PromptLookupData> = {
         const available = await m.readPrompts(rt);
         throw PragmaError.notFound("prompt", name, {
           suggestions: available.map((prompt) => prompt.name),
-          recovery: {
-            message: "List available prompts.",
-            cli: "pragma prompt list",
-            mcp: { tool: "prompt_list" },
-          },
+          recovery: cliRecovery("prompt list", "List available prompts.", {
+            tool: "prompt_list",
+          }),
         });
       }
       return entry;