@canonical/pragma-cli 0.32.0 → 0.33.0

package/src/capabilities/ontology/verbs.ts

@@ -1,17 +1,36 @@
 /**
- * `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 { PragmaError } from "../../kernel/error/PragmaError.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,
@@ -73,98 +92,178 @@ 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.",
+  },
+];
+
+/** 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 },
+  },
+};
 
-    let classes = await queryClasses(
-      rt,
-      namespace,
-      session.index.instanceCountByType,
+/**
+ * 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: {
+        message: "List loaded ontologies.",
+        cli: "pragma ontology list",
+        mcp: { 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: "pragma ontology lookup ds" },
+      { cmd: "pragma ontology lookup ds --properties" },
+      { cmd: "pragma 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: "pragma ontology lookup ds", note: "prefer `lookup`" },
+      { cmd: "pragma 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 } 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 { writeLock } from "../../kernel/runtime/lock.js";
 import type { GlobalFlags } from "../../kernel/spec/types.js";
 import { CANONICAL_TTL } from "../../testing/fixtures/graph/canonical.js";
 import {
@@ -117,3 +121,60 @@ describe("prompt — storeless native listing (PROTECTED)", () => {
     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 lock pointing at an evicted pack is the cold "configured but unbuilt"
+ * store (the pack is absent from the XDG-isolated cache).
+ */
+describe("prompt — cold-store convergence, tool + native agree (D1/D4)", () => {
+  let cold: McpHarness;
+
+  beforeAll(async () => {
+    const cwd = mkdtempSync(join(tmpdir(), "pragma-prompt-cold-"));
+    writeLock(cwd, { version: 1, contentHash: "b".repeat(64), packs: [] });
+    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/reference.test.ts

@@ -0,0 +1,32 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { emitReference } from "../kernel/spec/emitReference.js";
+import { capabilities } from "./index.js";
+
+/** Read a committed reference page exactly as a consumer (or lychee) would. */
+function readCommitted(relPath: string): string {
+  return readFileSync(
+    fileURLToPath(new URL(`../../docs/reference/${relPath}`, import.meta.url)),
+    "utf-8",
+  );
+}
+
+describe("reference docs drift-guard — emitReference == committed (PROTECTED)", () => {
+  const emitted = emitReference(capabilities);
+
+  it("every generated page is byte-identical to the committed file", () => {
+    for (const [relPath, expected] of emitted) {
+      expect(readCommitted(relPath)).toBe(expected);
+    }
+  });
+
+  it("the committed file set matches the generated key set (no orphans, none missing)", () => {
+    const committed = readdirSync(
+      fileURLToPath(new URL("../../docs/reference/", import.meta.url)),
+    )
+      .filter((name) => name.endsWith(".md"))
+      .sort();
+    expect(committed).toEqual([...emitted.keys()].sort());
+  });
+});

package/src/capabilities/resources/provider.ts

@@ -17,7 +17,9 @@
  */
 
 import { readPackIndex } from "../../kernel/completion/entitySource.js";
+import { asPragmaError } from "../../kernel/error/fromTaskError.js";
 import { PragmaError } from "../../kernel/error/PragmaError.js";
+import { mcpErrorFrom } from "../../kernel/project/mcp/mcpError.js";
 import type { PackIndex } from "../../kernel/runtime/graphpack/types.js";
 import { readEntity } from "../../kernel/runtime/readEntity.js";
 import type { McpResourceProvider } from "../../kernel/spec/types.js";
@@ -88,7 +90,18 @@ export function buildResourceList(
     const boxRank = (e: typeof a) => (e.box === "tbox" ? 0 : 1);
     return boxRank(a) - boxRank(b) || a.name.localeCompare(b.name);
   });
-  return ordered.map((entity) => {
+  // Dedup by resource URI: an OWL-punned subject (a class/property IRI ALSO
+  // asserted as a domain individual) is indexed as TWO entities — a tbox and an
+  // abox facet — that compact to the SAME `pragma:<uri>`. Mapping both would
+  // list one URI twice (A8). The sort above puts the tbox facet first, so
+  // keeping the first occurrence per URI surfaces the schema facet (its higher
+  // priority + instance count) and drops the punned duplicate.
+  const seen = new Set<string>();
+  const resources: ListedResource[] = [];
+  for (const entity of ordered) {
+    const uri = `pragma:${entity.prefixed ?? entity.name}`;
+    if (seen.has(uri)) continue;
+    seen.add(uri);
     const isTbox = entity.box === "tbox";
     // Port of the old shell's `_meta` taxonomy: `pragma/box` + a priority that
     // ranks schema (classes/properties) above individuals, so an agent browsing
@@ -104,8 +117,8 @@ export function buildResourceList(
     if (typeof instanceCount === "number") {
       meta["pragma/instanceCount"] = instanceCount;
     }
-    return {
-      uri: `pragma:${entity.prefixed ?? entity.name}`,
+    resources.push({
+      uri,
       name: entity.label || entity.name,
       ...(entity.description ? { description: entity.description } : {}),
       mimeType: "application/json" as const,
@@ -114,8 +127,9 @@ export function buildResourceList(
         priority: isTbox ? CLASS_PRIORITY : INDIVIDUAL_PRIORITY,
       },
       _meta: meta,
-    };
-  });
+    });
+  }
+  return resources;
 }
 
 /**
@@ -180,6 +194,9 @@ export const resourceProvider: McpResourceProvider = {
     const { ResourceTemplate } = await import(
       "@modelcontextprotocol/sdk/server/mcp.js"
     );
+    const { McpError, ErrorCode } = await import(
+      "@modelcontextprotocol/sdk/types.js"
+    );
     const template = new ResourceTemplate(URI_TEMPLATE, {
       list: async () => ({
         resources: buildResourceList(readPackIndex(runtime.cwd)),
@@ -215,15 +232,12 @@ export const resourceProvider: McpResourceProvider = {
             ],
           };
         } catch (error) {
-          const message =
-            error instanceof PragmaError
-              ? JSON.stringify({ code: error.code, message: error.message })
-              : String(error);
-          return {
-            contents: [
-              { uri: url.href, mimeType: "text/plain", text: message },
-            ],
-          };
+          // Surface the failure as a JSON-RPC error (the resource-read analogue
+          // of a tool result's `isError`), preserving the machine code AND the
+          // recovery in `data` — never swallow it into `text/plain` content an
+          // agent reads as a successful entity (which dropped the recovery and
+          // masked a cold store as though the entity itself were malformed).
+          throw mcpErrorFrom(asPragmaError(error), { McpError, ErrorCode });
         }
       },
     );