@canonical/pragma-cli 0.31.0 → 0.33.0

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

@@ -0,0 +1,87 @@
+/**
+ * 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,
+  PromptListData,
+  PromptLookupData,
+} from "./types.js";
+
+/** Render an argument list as `name (required)` / `name` tokens. */
+function argTokens(args: readonly PromptArgument[]): string {
+  if (args.length === 0) return "(none)";
+  return args
+    .map((arg) => (arg.required ? `${arg.name} (required)` : arg.name))
+    .join(", ");
+}
+
+export const promptListFormatters: Formatters<PromptListData> = {
+  plain(data) {
+    if (data.prompts.length === 0) return "No prompts in the store.";
+    const lines = ["Prompts"];
+    for (const prompt of data.prompts) {
+      lines.push(`  ${prompt.name} — ${prompt.description ?? ""}`.trimEnd());
+      lines.push(`    args: ${argTokens(prompt.arguments)}`);
+    }
+    return lines.join("\n");
+  },
+  llm(data) {
+    if (data.prompts.length === 0) return "_No prompts in the store._";
+    // 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(),
+      );
+      lines.push(`  - args: ${argTokens(prompt.arguments)}`);
+    }
+    return lines.join("\n");
+  },
+  json(data) {
+    return JSON.stringify(data);
+  },
+};
+
+export const promptLookupFormatters: Formatters<PromptLookupData> = {
+  plain(data) {
+    // 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(
+      `  ${style.cyan("args")}: ${argTokens(data.arguments)}`,
+      "",
+      data.body,
+    );
+    return lines.join("\n");
+  },
+  llm(data) {
+    // 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");
+      for (const arg of data.arguments) {
+        lines.push(
+          `- \`${arg.name}\`${arg.required ? " (required)" : ""}${arg.description ? ` — ${arg.description}` : ""}`,
+        );
+      }
+    }
+    lines.push("", "### Template", data.body);
+    return lines.join("\n");
+  },
+  json(data) {
+    return JSON.stringify(data);
+  },
+};

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

@@ -0,0 +1,180 @@
+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 {
+  bootFixtureRuntime,
+  type FixtureGraph,
+} from "../../testing/helpers/fixtureGraph.js";
+import type { McpHarness } from "../../testing/helpers/projectMcp.js";
+import { projectMcp } from "../../testing/helpers/projectMcp.js";
+import { capabilities } from "../index.js";
+
+const FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "plain",
+  verbose: false,
+};
+
+/** The 5 authored prompt names (rdfs:label), sorted. */
+const EXPECTED = [
+  "audit-standards",
+  "build-a-block",
+  "configure",
+  "explore-design-system",
+  "scaffold-component",
+];
+
+let fixture: FixtureGraph;
+let mcp: McpHarness;
+
+beforeAll(async () => {
+  fixture = await bootFixtureRuntime({ ttl: CANONICAL_TTL });
+  mcp = await projectMcp(capabilities, fixture.cwd);
+});
+
+afterAll(async () => {
+  await mcp.cleanup();
+  await fixture.dispose();
+});
+
+describe("prompt content noun — prompt_list / prompt_lookup (PROTECTED)", () => {
+  it("prompt_list resolves the authored ds:Prompt entities", async () => {
+    const result = await mcp.callTool("prompt_list");
+    const data = result.data as {
+      prompts: { name: string; arguments: unknown[] }[];
+    };
+    expect(data.prompts.map((p) => p.name).sort()).toEqual(EXPECTED);
+  });
+
+  it("prompt_lookup returns the body + arguments of one prompt", async () => {
+    const result = await mcp.callTool("prompt_lookup", {
+      name: "build-a-block",
+    });
+    const data = result.data as {
+      name: string;
+      body: string;
+      arguments: { name: string; required?: boolean }[];
+    };
+    expect(data.name).toBe("build-a-block");
+    expect(data.body).toContain("{{blockName}}");
+    expect(data.arguments.map((a) => a.name)).toContain("blockName");
+  });
+
+  it("prompt_lookup on a required-arg prompt reports the requirement", async () => {
+    const result = await mcp.callTool("prompt_lookup", {
+      name: "scaffold-component",
+    });
+    const data = result.data as {
+      arguments: { name: string; required?: boolean }[];
+    };
+    const componentName = data.arguments.find(
+      (a) => a.name === "componentName",
+    );
+    expect(componentName?.required).toBe(true);
+  });
+
+  it("prompt_lookup on an unknown name errors with suggestions", async () => {
+    const result = await mcp.callTool("prompt_lookup", { name: "nope" });
+    expect(result.ok).toBe(false);
+    const error = result.error as { code: string };
+    expect(error.code).toBe("ENTITY_NOT_FOUND");
+  });
+});
+
+describe("prompt — native MCP prompts surface (PROTECTED)", () => {
+  it("prompts/list is non-empty, each with a description", async () => {
+    const prompts = await mcp.listPrompts();
+    expect(prompts.map((p) => p.name).sort()).toEqual(EXPECTED);
+    for (const prompt of prompts) {
+      expect(prompt.description, prompt.name).toBeTruthy();
+    }
+  });
+
+  it("prompts/get returns the body store-backed, with arguments filled", async () => {
+    const result = await mcp.getPrompt("build-a-block", {
+      blockName: "Button",
+    });
+    const first = result.messages[0] as {
+      content: { type: string; text: string };
+    };
+    expect(first.content.text).toContain("Button");
+    expect(first.content.text).not.toContain("{{blockName}}");
+  });
+
+  it("prompts/get on an unknown name throws", async () => {
+    await expect(mcp.getPrompt("nope")).rejects.toThrow();
+  });
+});
+
+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);
+    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 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/prompt/types.ts

@@ -0,0 +1,30 @@
+/**
+ * Data shapes for the `prompt` content noun (`prompt_list`/`prompt_lookup`).
+ *
+ * Both project the SAME `ds:Prompt` entities the native MCP `prompts/*` surface
+ * reads (via the shared `kernel/project/mcp/prompts/source.ts`), so the tool and
+ * the native prompt can never disagree. `list` returns summaries (no body);
+ * `lookup` returns the full entry (body + arguments).
+ */
+
+import type {
+  PromptArgument,
+  PromptEntry,
+} from "../../kernel/project/mcp/prompts/source.js";
+
+/** One prompt in a `prompt_list` result — summary only (no template body). */
+export interface PromptListing {
+  readonly name: string;
+  readonly description?: string;
+  readonly arguments: readonly PromptArgument[];
+}
+
+/** The `prompt_list` payload. */
+export interface PromptListData {
+  readonly prompts: readonly PromptListing[];
+}
+
+/** The `prompt_lookup` payload — the full materialized prompt. */
+export type PromptLookupData = PromptEntry;
+
+export type { PromptArgument, PromptEntry };

package/src/capabilities/prompt/verbs.ts

@@ -0,0 +1,93 @@
+/**
+ * `prompt list` and `prompt lookup <name>` — the covenant `prompt` content noun.
+ *
+ * Bespoke (not compilePack): the covenant freezes `prompt_lookup` with a SINGLE
+ * `<name>` positional, whereas a pack lookup always emits the variadic
+ * `<name...>`. Both are `needsStore` (per covenant) and read the SAME
+ * `ds:Prompt` source the native `prompts/*` provider uses, so the tool surface
+ * and the native prompt surface are ONE data source, two projections.
+ *
+ * Run bodies dynamic-import the store-backed source, keeping the store code off
+ * the `--help`/`__complete` fast path (the module barrel loads only specs +
+ * formatters).
+ */
+
+import { PragmaError } from "../../kernel/error/PragmaError.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 {
+  promptListFormatters,
+  promptLookupFormatters,
+} from "./prompt.render.js";
+import type { PromptListData, PromptLookupData } from "./types.js";
+
+const READ_CAPABILITY = {
+  needsStore: true,
+  mutates: false,
+  mcp: {
+    expose: true as const,
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
+};
+
+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.",
+  params: [],
+  output: { formatters: promptListFormatters },
+  examples: [{ cmd: "pragma prompt list" }],
+  capability: READ_CAPABILITY,
+  run: (_params: Record<string, unknown>, rt: PragmaRuntime) =>
+    import("../../kernel/project/mcp/prompts/source.js").then(async (m) => {
+      const prompts = await m.readPrompts(rt);
+      return {
+        prompts: prompts.map((prompt) => ({
+          name: prompt.name,
+          ...(prompt.description ? { description: prompt.description } : {}),
+          arguments: prompt.arguments,
+        })),
+      };
+    }),
+};
+
+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.",
+  params: [
+    {
+      kind: "string",
+      name: "name",
+      doc: "The prompt name (e.g. build-a-block).",
+      positional: true,
+      required: true,
+      complete: { kind: "names", source: { from: "prompts" } },
+    },
+  ],
+  output: { formatters: promptLookupFormatters },
+  examples: [{ cmd: "pragma prompt lookup build-a-block" }],
+  capability: READ_CAPABILITY,
+  run: (params: Record<string, unknown>, rt: PragmaRuntime) =>
+    import("../../kernel/project/mcp/prompts/source.js").then(async (m) => {
+      const name = String(params.name);
+      const entry = await m.readPrompt(rt, name);
+      if (!entry) {
+        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" },
+          },
+        });
+      }
+      return entry;
+    }),
+};
+
+/** The `prompt` content verbs (`list`, `lookup`). */
+export const promptListVerb = asVerb(listVerb);
+export const promptLookupVerb = asVerb(lookupVerb);

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/index.ts

@@ -0,0 +1,15 @@
+/**
+ * The MCP resource browser barrel.
+ *
+ * The `graph-entity` resource surface is a MODULE hook (not a tool), attached to
+ * the `graph` capability — `graph inspect` (CLI) and the resource read (MCP)
+ * share one entity reader. Exposed here so `graph/index` can hang it off its
+ * module and the resources suite can exercise list/complete/read directly.
+ */
+
+export {
+  buildResourceList,
+  type ListedResource,
+  rankUriCompletions,
+  resourceProvider,
+} from "./provider.js";

package/src/capabilities/resources/provider.ts

@@ -0,0 +1,245 @@
+/**
+ * The MCP resource browser — a `pragma:{+uri}` template over the pack index.
+ *
+ * Listing and autocomplete are STORELESS: they read the enriched `index.json`
+ * (readPackIndex) off disk, so the resource surface costs nothing until an agent
+ * reads one. A read is STORE-BACKED through the SHARED {@link readEntity} — the
+ * same reader `graph inspect` uses — so a resource read and a `graph inspect` of
+ * the same URI return identical content (the mirror contract).
+ *
+ * Degradation (Risk4): on a missing or legacy (pre-v2) index the listing returns
+ * a single "run `pragma sources update`" hint — never a live re-index of the
+ * store on the resource path.
+ *
+ * The MCP SDK's `ResourceTemplate` is dynamic-imported inside `register` so this
+ * module — reachable on the capabilities import graph — never pulls the SDK onto
+ * the `--help`/`__complete` fast path.
+ */
+
+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";
+
+/** Max autocomplete suggestions returned for a partial URI. */
+const COMPLETION_LIMIT = 50;
+
+/** MCP annotation priority for a schema (TBox) entry — surfaced above individuals. */
+const CLASS_PRIORITY = 0.9;
+/** MCP annotation priority for an individual (ABox) entry. */
+const INDIVIDUAL_PRIORITY = 0.3;
+
+/** The `pragma:` URI scheme + the single reserved-expansion template variable. */
+const URI_TEMPLATE = "pragma:{+uri}";
+
+const TEMPLATE_DESCRIPTION =
+  "Knowledge-graph entities from the local pack. Read any entry by its prefixed " +
+  "URI (e.g. pragma:ds:button); autocomplete matches URI or label substrings. " +
+  "Content mirrors `pragma graph inspect <uri>`.";
+
+/** Agent-navigability annotations mirrored onto a listed resource. */
+export interface ResourceAnnotations {
+  /** MCP audience roles (the SDK's literal union) — always the assistant here. */
+  readonly audience: ("user" | "assistant")[];
+  readonly priority: number;
+}
+
+/** The audience every listed resource carries (assistant-facing). */
+const ASSISTANT_AUDIENCE: ("user" | "assistant")[] = ["assistant"];
+
+/** One resource entry in the listing. */
+export interface ListedResource {
+  readonly uri: string;
+  readonly name: string;
+  readonly description?: string;
+  readonly mimeType: "application/json";
+  /** Audience + priority (schema surfaced above individuals). */
+  readonly annotations?: ResourceAnnotations;
+  /** Taxonomy metadata: `pragma/box` (tbox|abox) + optional instance count. */
+  readonly _meta?: Record<string, unknown>;
+}
+
+/**
+ * Build the resource listing from the storeless pack index.
+ *
+ * @param index - The active pack index, or `undefined` when none is reachable.
+ * @returns One resource per indexed entity, schema (TBox) first; a single
+ *   recovery entry when the index is missing or pre-v2 (no enrichment).
+ */
+export function buildResourceList(
+  index: PackIndex | undefined,
+): ListedResource[] {
+  // readPackIndex returns raw JSON.parse output (no zod), so guard structurally:
+  // a malformed index missing `version` must degrade to the recovery hint, not
+  // fall through to `[...index.entities]` (a TypeError inside the MCP handler).
+  if (!index || index.version !== 2 || !Array.isArray(index.entities)) {
+    return [
+      {
+        uri: "pragma:sources",
+        name: "Store not indexed",
+        description:
+          "No enriched entity index. Run `pragma sources update` to build it.",
+        mimeType: "application/json",
+      },
+    ];
+  }
+  const ordered = [...index.entities].sort((a, b) => {
+    const boxRank = (e: typeof a) => (e.box === "tbox" ? 0 : 1);
+    return boxRank(a) - boxRank(b) || a.name.localeCompare(b.name);
+  });
+  // 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
+    // the resource list sees the schema first. `pragma/instanceCount` is the
+    // per-type count carried in the index for a TBox class entry.
+    // `instanceCountByType` is keyed by the full type IRI; a TBox class entry's
+    // own IRI is that key, so it carries the count of its individuals.
+    const instanceCount =
+      isTbox && entity.uri ? index.instanceCountByType[entity.uri] : undefined;
+    const meta: Record<string, unknown> = {
+      "pragma/box": entity.box ?? "abox",
+    };
+    if (typeof instanceCount === "number") {
+      meta["pragma/instanceCount"] = instanceCount;
+    }
+    resources.push({
+      uri,
+      name: entity.label || entity.name,
+      ...(entity.description ? { description: entity.description } : {}),
+      mimeType: "application/json" as const,
+      annotations: {
+        audience: ASSISTANT_AUDIENCE,
+        priority: isTbox ? CLASS_PRIORITY : INDIVIDUAL_PRIORITY,
+      },
+      _meta: meta,
+    });
+  }
+  return resources;
+}
+
+/**
+ * Rank URI autocomplete candidates against a partial query (case-insensitive over
+ * both the prefixed URI and the label; exact > prefix > substring), capped.
+ */
+export function rankUriCompletions(
+  entities: readonly PackIndex["entities"][number][],
+  query: string,
+  limit: number,
+): string[] {
+  const needle = query.toLowerCase();
+  const score = (field: string): number =>
+    field === needle
+      ? 3
+      : field.startsWith(needle)
+        ? 2
+        : field.includes(needle)
+          ? 1
+          : 0;
+  const scored: { prefixed: string; score: number }[] = [];
+  for (const entity of entities) {
+    const prefixed = entity.prefixed ?? entity.name;
+    const uriScore = score(prefixed.toLowerCase());
+    const labelScore = entity.label ? score(entity.label.toLowerCase()) : 0;
+    const best = Math.max(uriScore, labelScore);
+    if (best > 0) scored.push({ prefixed, score: best });
+  }
+  scored.sort((a, b) =>
+    b.score !== a.score
+      ? b.score - a.score
+      : a.prefixed.localeCompare(b.prefixed),
+  );
+  const seen = new Set<string>();
+  const ranked: string[] = [];
+  for (const { prefixed } of scored) {
+    if (seen.has(prefixed)) continue;
+    seen.add(prefixed);
+    ranked.push(prefixed);
+    if (ranked.length >= limit) break;
+  }
+  return ranked;
+}
+
+/** Read the single `uri` template variable, tolerating array expansion. */
+function readUriVariable(value: string | string[] | undefined): string {
+  const uri = Array.isArray(value) ? value.at(0) : value;
+  if (uri === undefined) {
+    throw PragmaError.invalidInput("uri", String(value), {
+      recovery: { message: "Provide a prefixed or full entity URI." },
+    });
+  }
+  return uri;
+}
+
+/** The graph-entity resource provider (registered by buildServer). */
+export const resourceProvider: McpResourceProvider = {
+  // The single authoring point for the template id — the surface emitter reads
+  // this so `mcpSurface.resources` cannot drift from what `register` installs.
+  surface: { templates: [URI_TEMPLATE] },
+  async register(server, runtime) {
+    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)),
+      }),
+      complete: {
+        uri: async (value: string) =>
+          rankUriCompletions(
+            readPackIndex(runtime.cwd)?.entities ?? [],
+            value,
+            COMPLETION_LIMIT,
+          ),
+      },
+    });
+
+    server.registerResource(
+      "graph-entity",
+      template,
+      { description: TEMPLATE_DESCRIPTION, mimeType: "application/json" },
+      async (
+        url: URL,
+        variables: Record<string, string | string[] | undefined>,
+      ) => {
+        try {
+          const uri = readUriVariable(variables.uri);
+          const entity = await readEntity(runtime, uri);
+          return {
+            contents: [
+              {
+                uri: url.href,
+                mimeType: "application/json",
+                text: JSON.stringify(entity, null, 2),
+              },
+            ],
+          };
+        } catch (error) {
+          // 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 });
+        }
+      },
+    );
+  },
+};