@canonical/pragma-cli 0.32.0 → 0.34.0

package/src/kernel/project/cli/rootHelp.ts

@@ -1,12 +1,13 @@
 /**
- * Curated root `--help` for `pragma`.
+ * The curated root `--help` page.
  *
- * The front door is hand-curated, not auto-generated: nouns are grouped into
- * task-oriented sections with real one-line summaries, and each section is
- * reconciled against the *live* nouns (from the registered verbs) so a noun
- * that is not built yet is dropped and an uncatalogued one still surfaces under
- * "Other" rather than vanishing. Ported from the v1 root help, retargeted at
- * the grammar and the v2 noun set (no `llm`/`graphql`/`trace`/`tokens`).
+ * The kernel curates the nouns it ships — and only those. It names no domain:
+ * the nouns it does NOT curate lead the page untitled (the header one line up
+ * already carries the distribution's blurb) and describe themselves through
+ * their own verbs, so the front door follows the content instead of naming it.
+ * Every section is reconciled against the *live* nouns (from the registered
+ * verbs), so a noun that is not built yet is dropped and one the kernel has
+ * never heard of still surfaces.
  */
 
 import type { VerbSpec } from "../../spec/types.js";
@@ -24,88 +25,86 @@ interface NounSummary {
 }
 
 interface HelpGroup {
-  readonly title: string;
+  /**
+   * Absent for the leading uncurated group: its rows sit directly under the
+   * usage line, since repeating the header's blurb as a heading three lines
+   * below it says the same thing twice.
+   */
+  readonly title?: string;
   readonly nouns: readonly NounSummary[];
 }
 
 /**
- * Task-oriented grouping with curated summaries. Order is intentional: what
- * people reach for most (exploring, generating) comes first; agent tooling
- * comes last.
+ * The kernel's own nouns, grouped by task with curated summaries. Order is
+ * intentional: what people reach for most comes first; agent tooling comes last.
+ *
+ * @param programName - The CLI binary name (the distribution's `name`).
+ * @returns The task-oriented groups, in display order.
  */
-const HELP_GROUPS: readonly HelpGroup[] = [
-  {
-    title: "Explore the design system",
-    nouns: [
-      {
-        noun: "block",
-        summary: "Inspect components & patterns and their anatomy",
-      },
-      { noun: "token", summary: "Look up design tokens and their values" },
-      { noun: "modifier", summary: "Inspect modifiers and modifier families" },
-      { noun: "standard", summary: "Browse code standards and categories" },
-      {
-        noun: "ontology",
-        summary: "Explore the loaded ontologies (classes, properties)",
-      },
-      { noun: "tier", summary: "List the design-system tiers" },
-    ],
-  },
-  {
-    title: "Generate code",
-    nouns: [
-      { noun: "create", summary: "Scaffold components, packages, and apps" },
-    ],
-  },
-  {
-    title: "Query & serve the graph",
-    nouns: [
-      {
-        noun: "graph",
-        summary: "Run SPARQL queries or inspect a URI directly",
-      },
-    ],
-  },
-  {
-    title: "Set up & maintain",
-    nouns: [
-      { noun: "doctor", summary: "Check environment health" },
-      {
-        noun: "setup",
-        summary: "Configure MCP, skills, completions, and the LSP",
-      },
-      {
-        noun: "sources",
-        summary: "Build and refresh the local store from packages",
-      },
-      { noun: "config", summary: "Read and write pragma configuration" },
-      { noun: "info", summary: "Show version, config, and update status" },
-      {
-        noun: "upgrade",
-        summary: "Upgrade the pragma CLI to the latest version",
-      },
-    ],
-  },
-  {
-    title: "For AI agents",
-    nouns: [
-      {
-        noun: "capabilities",
-        summary: "Discover conventions, tools, and the discovery sequence",
-      },
-      {
-        noun: "colophon",
-        summary: "Read how pragma and the active domain are made",
-      },
-      {
-        noun: "skill",
-        summary: "Browse agent skills from design-system packages",
-      },
-      { noun: "prompt", summary: "Browse reusable prompt templates" },
-      { noun: "mcp", summary: "Start the MCP server over stdio" },
-    ],
-  },
-];
+function buildKernelGroups(programName: string): readonly HelpGroup[] {
+  return [
+    {
+      title: "Generate code",
+      nouns: [
+        { noun: "create", summary: "Scaffold components, packages, and apps" },
+      ],
+    },
+    {
+      title: "Query & serve the graph",
+      nouns: [
+        {
+          noun: "graph",
+          summary: "Run SPARQL queries or inspect a URI directly",
+        },
+        {
+          noun: "ontology",
+          summary: "Explore the loaded ontologies (classes, properties)",
+        },
+      ],
+    },
+    {
+      title: "Set up & maintain",
+      nouns: [
+        { noun: "doctor", summary: "Check environment health" },
+        {
+          noun: "setup",
+          summary: "Configure MCP, skills, completions, and the LSP",
+        },
+        {
+          noun: "sources",
+          summary: "Build and refresh the local store from packs",
+        },
+        {
+          noun: "config",
+          summary: `Read and write ${programName} configuration`,
+        },
+        { noun: "info", summary: "Show version, config, and update status" },
+        {
+          noun: "upgrade",
+          summary: `Upgrade the ${programName} CLI to the latest version`,
+        },
+      ],
+    },
+    {
+      title: "For AI agents",
+      nouns: [
+        {
+          noun: "capabilities",
+          summary: "Discover conventions, tools, and the discovery sequence",
+        },
+        {
+          noun: "colophon",
+          summary: `Read how ${programName} and the active domain are made`,
+        },
+        { noun: "skill", summary: "Browse agent skills from the active packs" },
+        { noun: "prompt", summary: "Browse reusable prompt templates" },
+        // The one noun with no verb to speak for it (the bin special-cases it),
+        // so its summary is hand-written rather than derived.
+        { noun: "mcp", summary: "Start the MCP server over stdio" },
+      ],
+    },
+  ];
+}
 
 /** All distinct, non-hidden top-level nouns present in the registered verbs. */
 function nounsFrom(verbs: readonly VerbSpec[]): Set<string> {
@@ -117,16 +116,21 @@ function nounsFrom(verbs: readonly VerbSpec[]): Set<string> {
   return nouns;
 }
 
-/** The summary to show for an uncatalogued but live noun. */
-function fallbackSummary(noun: string, verbs: readonly VerbSpec[]): string {
+/**
+ * Summarise an uncurated noun from its first live verb — which is the pack's own
+ * `description` whenever the pack ships a `list` (`compilePack` compiles that
+ * verb first). The terminal period a pack sentence carries is dropped so the
+ * column reads as one voice with the kernel's own fragments.
+ */
+function summarizeNoun(noun: string, verbs: readonly VerbSpec[]): string {
   const first = verbs.find((v) => v.path[0] === noun && !v.hidden);
-  return first?.summary ?? `${noun} commands`;
+  return (first?.summary ?? `${noun} commands`).replace(/\.$/, "");
 }
 
 /**
  * Build the curated root help string.
  *
- * @param programName - The CLI binary name (`pragma`).
+ * @param programName - The CLI binary name (the distribution's `name`).
  * @param description - The program description shown in the header.
  * @param verbs - All registered verbs, used to derive the live noun set.
  * @returns The formatted, colorized help text.
@@ -140,27 +144,23 @@ export function formatRootHelp(
   // `mcp` is served by the bin's special-case, not a projected verb, but is
   // always available — surface it so the front door is complete.
   present.add("mcp");
-  const catalogued = new Set(
-    HELP_GROUPS.flatMap((g) => g.nouns.map((n) => n.noun)),
-  );
+  const kernel = buildKernelGroups(programName);
+  const curated = new Set(kernel.flatMap((g) => g.nouns.map((n) => n.noun)));
 
-  const uncatalogued = [...present].filter((n) => !catalogued.has(n)).sort();
   const groups: HelpGroup[] = [
-    ...HELP_GROUPS.map((g) => ({
+    // Everything the kernel's curated table does not claim — in the shipped
+    // binary the bundled domain packs, in a fork whatever it ships. Untitled
+    // and first, so the domain leads the page without the kernel naming it.
+    {
+      nouns: [...present]
+        .filter((n) => !curated.has(n))
+        .sort()
+        .map((noun) => ({ noun, summary: summarizeNoun(noun, verbs) })),
+    },
+    ...kernel.map((g) => ({
       ...g,
       nouns: g.nouns.filter((n) => present.has(n.noun)),
     })),
-    ...(uncatalogued.length > 0
-      ? [
-          {
-            title: "Other",
-            nouns: uncatalogued.map((noun) => ({
-              noun,
-              summary: fallbackSummary(noun, verbs),
-            })),
-          },
-        ]
-      : []),
   ].filter((g) => g.nouns.length > 0);
 
   // One column width across ALL groups so the noun column aligns section to
@@ -180,7 +180,7 @@ export function formatRootHelp(
   ];
 
   for (const group of groups) {
-    lines.push(helpHeading(group.title));
+    if (group.title) lines.push(helpHeading(group.title));
     lines.push(
       ...helpColumns(
         group.nouns.map((n) => [n.noun, n.summary] as const),
@@ -195,8 +195,10 @@ export function formatRootHelp(
   // never these strings.
   lines.push(helpHeading("Global flags"));
   const flags: [string, string][] = [
-    ["--llm", "Condensed Markdown output for agents"],
-    ["--format <json|plain>", "Select output format"],
+    [
+      "--format <plain|llm|json>",
+      "Select output format (llm = condensed Markdown for agents)",
+    ],
     [
       "--detail <level>",
       "Progressive-disclosure level (summary, standard, detailed)",

package/src/kernel/project/mcp/buildServer.ts

@@ -1,12 +1,17 @@
 /**
  * Build the MCP server from the grammar.
  *
- * Constructs an {@link McpServer} under the stable `pragma` identity (matching
- * the CLI bin, so existing agent wiring resolves it), then registers every
- * exposed verb as a tool and each module's optional `mcpResources` surface (the
- * graph resource browser, wired below via `module.mcpResources?.register`). One
- * runtime is booted for the server's lifetime and shared by every tool; the
- * store stays lazy, booting only when a resource read needs it.
+ * Constructs an {@link McpServer} whose wire identity PROJECTS from the
+ * distribution: `serverInfo.name` is the declared distribution name (the same
+ * projection that names the CLI bin, so existing agent wiring resolves it) and
+ * `serverInfo.version` the package version — a fork's server introduces itself
+ * under the fork's own name with no code change. The covenant records the rule
+ * (`surface.v2.json` `mcpSurface.serverInfo`) and `identity.test.ts` pins it on
+ * the wire from a fork's config. Then registers every exposed verb as a tool
+ * and each module's optional `mcpResources` surface (the graph resource
+ * browser, wired below via `module.mcpResources?.register`). One runtime is
+ * booted for the server's lifetime and shared by every tool; the store stays
+ * lazy, booting only when a resource read needs it.
  */
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

package/src/kernel/project/mcp/instructions.ts

@@ -4,7 +4,8 @@
  *
  * It carries the same content the retired `llm` tool front-loaded: the
  * conventions + the discovery sequence. To guarantee it never diverges from the
- * `capabilities` tool, it derives BOTH from the SAME source — `CONVENTIONS` and
+ * `capabilities` tool, the WHOLE orientation — the opening line included —
+ * derives from the SAME source: `CONVENTIONS` and
  * `buildDiscoverySequence` in `capabilities/capabilities/catalog.ts`. Live
  * numbers (tier/channel/entity counts) are deliberately DROPPED (they would need
  * a store boot at handshake); agents fetch those via `info`/`config show`/
@@ -15,8 +16,8 @@
 import {
   buildDiscoverySequence,
   CONVENTIONS,
-  liveTools,
 } from "../../../capabilities/capabilities/catalog.js";
+import { emitSurface } from "../../spec/emitSurface.js";
 import type { CapabilityModule } from "../../spec/types.js";
 
 /** Hard ceiling on the instructions length (asserted by the protected test). */
@@ -31,18 +32,22 @@ export const INSTRUCTIONS_MAX_CHARS = 1500;
 export function buildInstructions(
   modules: readonly CapabilityModule[],
 ): string {
-  const discovery = buildDiscoverySequence(liveTools(modules));
-  const steps = discovery
+  // Tools AND resource templates come from the one emitted surface: the
+  // `<scheme>:{+uri}` template is declared by the module that serves it and
+  // frozen in the covenant, so quoting it here rather than deriving it would be
+  // a second copy of a string the kernel does not own.
+  const { tools, resources } = emitSurface(modules).mcpSurface;
+  const steps = buildDiscoverySequence(tools)
     .map((stage) => `${stage.stage}. ${stage.tool} — ${stage.purpose}`)
     .join("\n");
+  const templates = resources.map((template) => `\`${template}\``).join(", ");
 
   return [
-    "pragma is a CLI and MCP server over a design-system knowledge graph.",
-    `${CONVENTIONS.system} ${CONVENTIONS.model} ${CONVENTIONS.querying}`,
+    `${CONVENTIONS.system} ${CONVENTIONS.model} ${CONVENTIONS.querying} ${CONVENTIONS.mutations}`,
     "",
     "Discovery sequence:",
     steps,
     "",
-    "Call the `capabilities` tool for the full annotated tool catalog; read `pragma:{+uri}` resources (or `graph_inspect`) for entity detail.",
+    `Call the \`capabilities\` tool for the full annotated tool catalog; read ${templates} resources (or \`graph_inspect\`) for entity detail.`,
   ].join("\n");
 }

package/src/kernel/project/mcp/mcpError.ts

@@ -0,0 +1,52 @@
+/**
+ * Project a {@link PragmaError} into an SDK `McpError` for the NATIVE MCP
+ * surfaces (the `prompts/*` provider, the `pragma:{+uri}` resource browser),
+ * which signal failure by throwing a JSON-RPC error rather than by returning the
+ * `{ ok, error }` tool envelope.
+ *
+ * A native read must not swallow a failure into plain-text "success" content: it
+ * carries the machine `code` AND the structured `recovery` into the JSON-RPC
+ * `data`, so an agent that hits a cold store over `prompts/list` or a resource
+ * read sees the SAME `STORE_UNAVAILABLE` + `sources_update` recovery the tool
+ * envelope carries — never a bare string with the recovery dropped.
+ *
+ * The SDK's `McpError`/`ErrorCode` are PASSED IN by the caller (which already
+ * dynamic-imported them in its `register`), so this module — reachable on the
+ * capabilities import graph — never statically pulls the SDK onto the
+ * `--help`/`__complete` fast path.
+ */
+
+import type { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
+import type { PragmaError } from "../../error/PragmaError.js";
+
+/** The SDK error primitives a provider dynamic-imports and hands to {@link mcpErrorFrom}. */
+export interface McpErrorPrimitives {
+  readonly McpError: typeof McpError;
+  readonly ErrorCode: typeof ErrorCode;
+}
+
+/**
+ * Build an `McpError` from a {@link PragmaError}, mapping the machine code to a
+ * JSON-RPC code and preserving `code`/`recovery`/`suggestions`/`validOptions` in
+ * `data`.
+ *
+ * @param error - The structured pragma error to project.
+ * @param primitives - The SDK `McpError`/`ErrorCode` the caller imported.
+ * @returns An `McpError` carrying the diagnostic + recovery in its `data`.
+ */
+export function mcpErrorFrom(
+  error: PragmaError,
+  { McpError: McpErrorCtor, ErrorCode: ErrorCodeEnum }: McpErrorPrimitives,
+): McpError {
+  // A bad/missing entity or rejected input is the caller's fault (InvalidParams);
+  // an unreachable store or internal fault is the server's (InternalError).
+  const jsonRpcCode =
+    error.code === "ENTITY_NOT_FOUND" || error.code === "INVALID_INPUT"
+      ? ErrorCodeEnum.InvalidParams
+      : ErrorCodeEnum.InternalError;
+  const data: Record<string, unknown> = { code: error.code };
+  if (error.recovery) data.recovery = error.recovery;
+  if (error.suggestions.length > 0) data.suggestions = error.suggestions;
+  if (error.validOptions) data.validOptions = error.validOptions;
+  return new McpErrorCtor(jsonRpcCode, error.message, data);
+}

package/src/kernel/project/mcp/parity.test.ts

@@ -1,7 +1,10 @@
-import { existsSync } from "node:fs";
+import { existsSync, mkdtempSync, readdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { describe, expect, it } from "vitest";
 import {
   fixtureEffectsModule,
+  fixturePreviewModule,
   touchPath,
 } from "../../../testing/fixtures/fixtureCapability.js";
 import { projectMcp } from "../../../testing/helpers/projectMcp.js";
@@ -70,3 +73,38 @@ describe("MCP mutation plan-first / confirm (PROTECTED)", () => {
     expect(existsSync(touchPath(name))).toBe(true);
   });
 });
+
+describe("MCP plan-first is honest (PRA-104)", () => {
+  it("returns the ERROR a confirmed run would hit, not a confident plan", async () => {
+    // The CLI twin of this guard lives in cli/dispatch.test.ts: the same
+    // mutation, the same missing source, exiting nonzero instead of printing a
+    // plan. Both surfaces run one interpreter, so they cannot drift.
+    const dir = mkdtempSync(join(tmpdir(), "pragma-graft-mcp-"));
+    const missing = join(dir, "gone");
+
+    const mcp = await projectMcp([fixturePreviewModule], dir);
+    const planned = await mcp.callTool("probe_graft", { source: missing });
+    await mcp.cleanup();
+
+    expect(planned.ok).toBe(false);
+    expect(JSON.stringify(planned.error)).toContain(missing);
+    expect(existsSync(`${missing}.grafted`)).toBe(false);
+  });
+
+  it("returns a plan, and writes nothing, when the read would succeed", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "pragma-graft-mcp-"));
+    const source = join(dir, "present.txt");
+    writeFileSync(source, "content\n");
+
+    const mcp = await projectMcp([fixturePreviewModule], dir);
+    const planned = await mcp.callTool("probe_graft", { source });
+    await mcp.cleanup();
+
+    expect(planned.ok).toBe(true);
+    expect(planned.meta).toEqual({ planOnly: true, confirmRequired: true });
+    expect((planned.data as { plan: string[] }).plan).toContain(
+      `Write file: ${source}.grafted (8 bytes)`,
+    );
+    expect(readdirSync(dir)).toEqual(["present.txt"]);
+  });
+});

package/src/kernel/project/mcp/prompts/prompts.test.ts

@@ -1,13 +1,18 @@
 import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { GetPromptRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { afterEach, describe, expect, it } from "vitest";
+import { CONVENTIONS } from "../../../../capabilities/capabilities/catalog.js";
 import { capabilities } from "../../../../capabilities/index.js";
 import type { McpHarness } from "../../../../testing/helpers/projectMcp.js";
 import { projectMcp } from "../../../../testing/helpers/projectMcp.js";
+import type { PragmaRuntime } from "../../../runtime/types.js";
+import { emitSurface } from "../../../spec/emitSurface.js";
 import type { CapabilityModule } from "../../../spec/types.js";
 import { buildInstructions, INSTRUCTIONS_MAX_CHARS } from "../instructions.js";
 import { fillTemplate, promptProvider } from "./provider.js";
+import { readPrompts } from "./source.js";
 
 const freshCwd = (): string => mkdtempSync(join(tmpdir(), "pragma-prompts-"));
 
@@ -39,14 +44,33 @@ describe("instructions — handshake orientation (PROTECTED)", () => {
     );
   });
 
-  it("derives its conventions from the shared catalog source", () => {
-    // The system convention string is authored once (capabilities/catalog.ts);
-    // instructions must carry it verbatim so the two can never diverge.
-    expect(buildInstructions(capabilities)).toContain(
-      "design-system knowledge graph",
+  it("opens with the shared catalog's conventions, verbatim and once", () => {
+    // The conventions are authored once (capabilities/catalog.ts); instructions
+    // must OPEN with them, so a second hand-written preamble cannot creep back
+    // in and drift from the `capabilities` tool the same handshake carries.
+    expect(buildInstructions(capabilities).startsWith(CONVENTIONS.system)).toBe(
+      true,
     );
   });
 
+  it("quotes the resource templates the MCP surface actually advertises", () => {
+    // The `pragma:` scheme is covenant-frozen protocol identity
+    // (surface.v2.json). The orientation DERIVES it from the emitted surface
+    // instead of hand-copying it, so the two cannot disagree.
+    const { resources } = emitSurface(capabilities).mcpSurface;
+    expect(resources.length).toBeGreaterThan(0);
+    const text = buildInstructions(capabilities);
+    for (const template of resources) expect(text).toContain(template);
+  });
+
+  it("states the plan-first/confirm convention in the orientation (D2)", () => {
+    // The confirm gate must be surfaced at handshake, not discovered by an agent
+    // tripping it. Same single source as the `capabilities` tool's conventions.
+    const text = buildInstructions(capabilities);
+    expect(text.toLowerCase()).toContain("plan-first");
+    expect(text).toContain("confirm: true");
+  });
+
   it("orients a cold agent to check/build the store before any store read", () => {
     // Store-blind guard: the handshake must point a cold agent at the store
     // pre-check (sources_status → sources_update) BEFORE the sample/query steps,
@@ -83,6 +107,105 @@ describe("MCP handshake — capabilities advertised (PROTECTED)", () => {
   });
 });
 
+/** A runtime whose SPARQL facade always fails with `message`. */
+function createFailingRuntime(message: string): PragmaRuntime {
+  return {
+    query: {
+      sparql: () => Promise.reject(new Error(message)),
+    },
+  } as unknown as PragmaRuntime;
+}
+
+/** Every field at the default layer — the embedded pack answers, so the store IS available. */
+const DEFAULT_ORIGINS = {
+  tier: "default",
+  channel: "default",
+  detail: "default",
+  packs: "default",
+  stories: "default",
+  prefixes: "default",
+} as const;
+
+/**
+ * The same failing facade, wearing the shape `promptProvider.register` needs:
+ * a cwd whose store is AVAILABLE (so `guardStore` passes and the read is what
+ * fails) plus a `loadConfig` the readiness check can resolve.
+ */
+function createFailingProviderRuntime(
+  cwd: string,
+  message: string,
+): PragmaRuntime {
+  return {
+    cwd,
+    loadConfig: async () => ({
+      config: { channel: "normal" as const },
+      origins: DEFAULT_ORIGINS,
+      global: { path: "/nonexistent", exists: false },
+      project: { exists: false },
+    }),
+    query: { sparql: () => Promise.reject(new Error(message)) },
+  } as unknown as PragmaRuntime;
+}
+
+describe("native prompts/get — a failed read reaches the agent as one", () => {
+  it("carries the machine code and recovery, not a bare Error", async () => {
+    // The native surface signals failure by THROWING, so a read that fails must
+    // be projected the way the resource browser projects its own — with `code`
+    // and `recovery` in the JSON-RPC `data`. Otherwise the store diagnosis is
+    // lost between `prompt_lookup` (which envelopes it) and `prompts/get`.
+    const handlers = new Map<unknown, (request: unknown) => Promise<unknown>>();
+    const stubServer = {
+      server: {
+        registerCapabilities: () => {},
+        setRequestHandler: (
+          schema: unknown,
+          handler: (request: unknown) => Promise<unknown>,
+        ) => {
+          handlers.set(schema, handler);
+        },
+      },
+    };
+    await promptProvider.register(
+      stubServer as never,
+      createFailingProviderRuntime(freshCwd(), "Prefix not found: ds"),
+    );
+
+    const get = handlers.get(GetPromptRequestSchema);
+    expect(get).toBeDefined();
+    await expect(
+      get?.({ params: { name: "build-a-block" } }),
+    ).rejects.toMatchObject({
+      data: {
+        code: "STORE_UNAVAILABLE",
+        recovery: { mcp: { tool: "sources_update" } },
+      },
+    });
+  });
+});
+
+describe("readPrompts — a failed read is never an empty graph", () => {
+  it("reports an unbound prefix as a store that cannot answer, not as no prompts", async () => {
+    // A pack whose store does not know the declared prompt namespace cannot
+    // answer, and the actionable form of that is STORE_UNAVAILABLE with the
+    // build command — not a silent zero-prompt listing.
+    await expect(
+      readPrompts(createFailingRuntime("Prefix not found: ds")),
+    ).rejects.toMatchObject({
+      code: "STORE_UNAVAILABLE",
+      recovery: { mcp: { tool: "sources_update" } },
+    });
+  });
+
+  it("propagates a query failure instead of returning no prompts", async () => {
+    // The exact defect a bare `catch {}` here caused: a malformed declaration
+    // becomes a parse error, the parse error becomes `[]`, and the user is told
+    // the distribution ships no prompts. It must surface as a failure.
+    await expect(
+      readPrompts(createFailingRuntime("SPARQL syntax error at line 2")),
+    ).rejects.toThrow(/syntax error/);
+  });
+});
+
 describe("fillTemplate — argument substitution", () => {
   it("replaces {{arg}} placeholders and leaves unknowns intact", () => {
     expect(