@canonical/pragma-cli 0.34.0 → 0.35.0

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

@@ -1,18 +1,62 @@
 /**
  * Global-flag pre-parsing, ahead of Commander.
  *
- * `--format`, `--verbose`, and `--detail` may appear anywhere on the line, so
+ * `--format`, `--verbose`, `--no-headers`, and `--detail` may appear anywhere on the line, so
  * they are scanned and stripped before Commander sees argv — otherwise
  * `enablePositionalOptions()` scoping would reject a flag placed after a verb.
+ *
+ * ANYWHERE STOPS AT `--`. Everything after the option terminator is the user's
+ * data, not this program's flags: `block lookup -- --format` looks up a block
+ * literally named `--format`. Commander honours the terminator on its own, so
+ * a scan here that ignored it would parse — and strip — tokens Commander was
+ * about to hand through verbatim.
+ *
+ * A FLAG'S VALUE IS NEVER ANOTHER FLAG. `--detail --category css` supplies no
+ * detail; it is a valueless `--detail` followed by a separate flag. Reading the
+ * next token unconditionally would consume `--category` as the value and strip
+ * it, so the filter would vanish and the command would answer over the whole
+ * set instead — a wrong answer with no diagnostic.
  * Ported from the v1 `parseGlobalFlags`, with two v2 changes: a new `--detail`
- * flag and the `--format text` value renamed to `plain` (the kernel's
- * {@link OutputFormat}). The dedicated `--llm` flag was folded into
- * `--format llm`, leaving auto-detection as the sole implicit trigger. Both the
- * space (`--format json`) and equals (`--format=json`) forms are recognized.
+ * flag and the `--format text` value replaced by `plain` (the kernel's
+ * {@link OutputFormat}) — `text` is not accepted; the bin rejects it with the
+ * valid list. The dedicated `--llm` flag was folded into `--format llm`,
+ * leaving auto-detection as the sole implicit trigger. Both the space
+ * (`--format json`) and equals (`--format=json`) forms are recognized.
  */
 
 import { DETAIL_LEVELS, type DetailLevel } from "../../../constants.js";
-import type { GlobalFlags } from "../../runtime/types.js";
+import type { GlobalFlags } from "../../runtime/index.js";
+
+/** The end-of-options separator: nothing after it is a flag of this program. */
+const OPTION_TERMINATOR = "--";
+
+/**
+ * The span of argv this program's flags may occupy — everything before the
+ * option terminator, or all of argv when there is none. Exported for the
+ * bin's retired-flag detection: a retired spelling AFTER the terminator is
+ * an operand, not a flag, and must not trigger a migration message.
+ *
+ * @param argv - The user's arguments.
+ * @returns The scannable span; the same array when no terminator is present.
+ */
+export function selectScanSpan(argv: readonly string[]): readonly string[] {
+  const terminator = argv.indexOf(OPTION_TERMINATOR);
+  return terminator === -1 ? argv : argv.slice(0, terminator);
+}
+
+/**
+ * Whether a token can serve as a flag's value.
+ *
+ * A token starting with `-` is the next flag, not this one's value. Shared by
+ * every reader below so the space form cannot swallow a sibling flag at one
+ * call site while guarding against it at another.
+ *
+ * @param token - The token following a flag, if any.
+ * @returns True when the token is a value rather than another flag.
+ */
+function isFlagValue(token: string | undefined): token is string {
+  return token !== undefined && !token.startsWith("-");
+}
 
 /**
  * Read a `--flag`'s value, accepting both `--flag value` and `--flag=value`.
@@ -25,35 +69,74 @@ function readFlagValue(
   argv: readonly string[],
   flag: string,
 ): string | undefined {
+  const span = selectScanSpan(argv);
   const equalsPrefix = `${flag}=`;
-  const equalsArg = argv.find((arg) => arg.startsWith(equalsPrefix));
+  const equalsArg = span.find((arg) => arg.startsWith(equalsPrefix));
   if (equalsArg !== undefined) {
     return equalsArg.slice(equalsPrefix.length);
   }
-  const spaceIndex = argv.indexOf(flag);
-  return spaceIndex === -1 ? undefined : argv[spaceIndex + 1];
+  const spaceIndex = span.indexOf(flag);
+  if (spaceIndex === -1) return undefined;
+  const value = span.at(spaceIndex + 1);
+  return isFlagValue(value) ? value : undefined;
 }
 
 /**
- * Read the raw `--format` value exactly as typed, for validation.
+ * Read a value flag's raw value exactly as typed, for validation.
  *
  * Unlike {@link parseGlobalFlags} this does not normalize — the caller decides
- * how to reject an unknown value. A bare `--format` with no following value is
+ * how to reject an unknown value. A bare flag with no following value is
  * reported as `""` (not `undefined`) so it is rejected rather than silently
- * falling through.
+ * falling through. One reader for every validated global value flag, so a
+ * guard applied to one cannot silently miss its siblings.
  *
  * @param argv - Raw argv (the user's arguments).
- * @returns The raw value, `""` for a valueless `--format`, or `undefined`.
+ * @param flag - The flag including leading dashes (e.g. `--format`).
+ * @returns The raw value, `""` for a valueless flag, or `undefined`.
  */
-export function readRawFormat(argv: readonly string[]): string | undefined {
-  const equalsArg = argv.find((arg) => arg.startsWith("--format="));
-  if (equalsArg !== undefined) return equalsArg.slice("--format=".length);
+function readRawFlag(
+  argv: readonly string[],
+  flag: string,
+): string | undefined {
+  const span = selectScanSpan(argv);
+  const equalsPrefix = `${flag}=`;
+  const equalsArg = span.find((arg) => arg.startsWith(equalsPrefix));
+  if (equalsArg !== undefined) return equalsArg.slice(equalsPrefix.length);
 
-  const spaceIndex = argv.indexOf("--format");
+  const spaceIndex = span.indexOf(flag);
   if (spaceIndex === -1) return undefined;
 
-  const value = argv[spaceIndex + 1];
-  return value !== undefined && !value.startsWith("-") ? value : "";
+  // `""` rather than `undefined`: a valueless flag must be REJECTED by the
+  // caller, not fall through to the default.
+  const value = span.at(spaceIndex + 1);
+  return isFlagValue(value) ? value : "";
+}
+
+/** The raw `--format` value as typed (see {@link readRawFlag}). */
+export function readRawFormat(argv: readonly string[]): string | undefined {
+  return readRawFlag(argv, "--format");
+}
+
+/**
+ * The raw `--detail` value as typed (see {@link readRawFlag}). Validated by
+ * the bin exactly as `--format` is — an unrecognized level used to be
+ * dropped silently, which is the same defect class as a filter that
+ * evaporates: wrong output with no diagnostic.
+ */
+export function readRawDetail(argv: readonly string[]): string | undefined {
+  return readRawFlag(argv, "--detail");
+}
+
+/**
+ * The `--verbose=<x>` token, if present. `--verbose` takes no value — one
+ * flag, one spelling — and the program must not accept-and-ignore a second
+ * one: the bin rejects the token this finds.
+ *
+ * @param argv - Raw argv (the user's arguments).
+ * @returns The offending token, or `undefined`.
+ */
+export function findValuedVerbose(argv: readonly string[]): string | undefined {
+  return selectScanSpan(argv).find((arg) => arg.startsWith("--verbose="));
 }
 
 /**
@@ -108,11 +191,18 @@ export function parseGlobalFlags(
   const formatRequested = rawFormat !== undefined;
   const autoLlm = !formatRequested && !env.isTty && !env.noAutoLlm;
   const detail = readDetail(argv);
+  const span = selectScanSpan(argv);
   return {
     llm: format === "llm" || autoLlm,
     autoLlm,
     format,
-    verbose: argv.includes("--verbose"),
+    verbose: span.includes("--verbose"),
+    // `--no-headers` suppresses the plain-table header row; it is global so
+    // every list-shaped verb honors one spelling.
+    ...(span.includes("--no-headers") ? { noHeaders: true } : {}),
+    // `--quiet` silences success/progress (the report seam, interpreter logs,
+    // onboarding, calm notices) while error rendering stays untouched.
+    ...(span.includes("--quiet") ? { quiet: true } : {}),
     ...(detail !== undefined ? { detail } : {}),
   };
 }
@@ -122,7 +212,8 @@ export function parseGlobalFlags(
  *
  * Since {@link parseGlobalFlags} pre-parses these, they are dropped so they do
  * not collide with Commander's positional scoping, letting the user place them
- * anywhere on the line.
+ * anywhere on the line — anywhere before the option terminator, which this
+ * stops at and hands through whole.
  *
  * @param argv - The user's arguments.
  * @returns A new array with global flags stripped.
@@ -130,20 +221,29 @@ export function parseGlobalFlags(
 export function stripGlobalFlags(argv: readonly string[]): string[] {
   const result: string[] = [];
   for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    if (arg === "--verbose") continue;
-    if (
-      arg?.startsWith("--format=") ||
-      arg?.startsWith("--verbose=") ||
-      arg?.startsWith("--detail=")
-    ) {
+    const arg = argv.at(i);
+    if (arg === undefined) continue;
+
+    // Past the terminator nothing is ours: hand the remainder over untouched,
+    // terminator included, so Commander still sees where options end.
+    if (arg === OPTION_TERMINATOR) {
+      result.push(...argv.slice(i));
+      return result;
+    }
+
+    if (arg === "--verbose" || arg === "--no-headers" || arg === "--quiet") {
+      continue;
+    }
+    if (arg.startsWith("--format=") || arg.startsWith("--detail=")) {
       continue;
     }
     if (arg === "--format" || arg === "--detail") {
-      i += 1; // skip the space-form value too
+      // Skip the value ONLY when the next token is one. A valueless flag before
+      // another flag must leave that flag standing.
+      if (isFlagValue(argv.at(i + 1))) i += 1;
       continue;
     }
-    result.push(arg as string);
+    result.push(arg);
   }
   return result;
 }

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

@@ -32,6 +32,19 @@ export function helpTerm(text: string): string {
   return chalk.cyan(text);
 }
 
+/**
+ * The wordmark's colour.
+ *
+ * `yellow` is a PALETTE slot, not a fixed hue: the 16-colour ANSI palette has no
+ * orange, and this slot is the one terminal themes render as orange — Ubuntu's
+ * among them. Naming the slot rather than a 256-colour or truecolour orange is
+ * what lets the wordmark follow the user's own theme instead of fighting it, and
+ * keeps it legible on light backgrounds where a hardcoded orange would not be.
+ */
+export function helpLogo(text: string): string {
+  return chalk.yellow(text);
+}
+
 /** The `Usage:` line: a dim label followed by the given command shape. */
 export function helpUsage(body: string): string {
   return `${chalk.dim("Usage:")} ${body}`;

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

@@ -10,11 +10,13 @@
  * never heard of still surfaces.
  */
 
-import type { VerbSpec } from "../../spec/types.js";
+import { PROGRAM_LOGO } from "../../../constants.js";
+import type { VerbSpec } from "../../spec/index.js";
 import {
   helpColumns,
   helpDim,
   helpHeading,
+  helpLogo,
   helpTerm,
   helpUsage,
 } from "./helpFormat.js";
@@ -79,6 +81,7 @@ function buildKernelGroups(programName: string): readonly HelpGroup[] {
           summary: `Read and write ${programName} configuration`,
         },
         { noun: "info", summary: "Show version, config, and update status" },
+        { noun: "version", summary: "Print the CLI version" },
         {
           noun: "upgrade",
           summary: `Upgrade the ${programName} CLI to the latest version`,
@@ -92,14 +95,16 @@ function buildKernelGroups(programName: string): readonly HelpGroup[] {
           noun: "capabilities",
           summary: "Discover conventions, tools, and the discovery sequence",
         },
-        {
-          noun: "colophon",
-          summary: `Read how ${programName} and the active domain are made`,
-        },
+        // A colophon is the note at the back of a book: the typeface, the
+        // press, the paper. Nothing depends on it, which is the point — so
+        // this line does not argue for it. Every other summary in this column
+        // promises work done; this one just invites you to look.
+        { noun: "colophon", summary: "Read the credits" },
         { 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.
+        // Curated for PLACEMENT, not for existence: `mcp serve` is an
+        // ordinary verb like every other, and this group is where a reader
+        // looks for it.
         { noun: "mcp", summary: "Start the MCP server over stdio" },
       ],
     },
@@ -133,17 +138,22 @@ function summarizeNoun(noun: string, verbs: readonly VerbSpec[]): string {
  * @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.
+ * @param issuesUrl - Where the preview notice sends feedback; the
+ *   distribution's own, so a fork points at its own tracker.
+ * @param version - The version to stamp on the header. Passed in rather than
+ *   read here so it is the SAME string `--version` prints: `buildProgram`
+ *   resolves `options.version ?? VERSION`, and a host that overrides one must
+ *   not be able to leave the other saying something else.
  * @returns The formatted, colorized help text.
  */
 export function formatRootHelp(
   programName: string,
   description: string,
   verbs: readonly VerbSpec[],
+  version: string,
+  issuesUrl: string,
 ): string {
   const present = nounsFrom(verbs);
-  // `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 kernel = buildKernelGroups(programName);
   const curated = new Set(kernel.flatMap((g) => g.nouns.map((n) => n.noun)));
 
@@ -171,7 +181,24 @@ export function formatRootHelp(
   );
 
   const lines: string[] = [
-    `${helpHeading(programName)} — ${description}`,
+    // The wordmark leads when the distribution declares one. A fork ships its
+    // own art or none, so its front door is never branded with someone else's.
+    ...(PROGRAM_LOGO.length > 0 ? [...PROGRAM_LOGO.map(helpLogo), ""] : []),
+    // `<name> v<version> — <blurb>`, the spelling `info` and `capabilities`
+    // already use, so the front door names the build the same way every other
+    // surface does. Dimmed: it answers "which build am I on" for someone who
+    // is already here, and must not compete with the name.
+    `${helpHeading(programName)} ${helpDim(`v${version}`)} — ${description}`,
+    "",
+    // The preview notice. Dimmed and directly under the header, because it
+    // qualifies what the reader has just been told the tool IS — a version
+    // number alone does not say "expect this to move".
+    //
+    // The URL is the distribution's declared `issuesUrl`, never a literal:
+    // `kernel/copy.test.ts` forbids the kernel naming a distribution, and a
+    // fork inviting feedback to someone else's tracker would be worse than a
+    // missing line. It is passed in for the same reason `version` is.
+    helpDim(`This is a preview version. Issues and suggestions: ${issuesUrl}`),
     "",
     helpUsage(
       `${programName} ${helpTerm("<command>")} ${helpDim("[subcommand] [flags]")}`,
@@ -203,7 +230,9 @@ export function formatRootHelp(
       "--detail <level>",
       "Progressive-disclosure level (summary, standard, detailed)",
     ],
-    ["--verbose", "Diagnostic output on stderr"],
+    ["--no-headers", "Hide the table header row in plain output"],
+    ["--quiet", "Suppress success and progress output (errors still print)"],
+    ["--verbose", "Diagnostic output on stderr (sources update)"],
     ["--help", "Show help (works on any command)"],
     ["--version", "Show the CLI version"],
   ];

package/src/kernel/project/cli/suggest.test.ts

@@ -1,6 +1,11 @@
 import { describe, expect, it } from "vitest";
+import { capabilities } from "../../../capabilities/index.js";
 import { fixtureModule } from "../../../testing/fixtures/fixtureCapability.js";
-import { nounVerbMap, resolveUnknownCommand } from "./suggest.js";
+import {
+  curatedSuggestions,
+  nounVerbMap,
+  resolveUnknownCommand,
+} from "./suggest.js";
 import { suggestNames } from "./suggestNames.js";
 
 const verbs = [...fixtureModule.verbs];
@@ -36,6 +41,33 @@ describe("resolveUnknownCommand", () => {
   });
 });
 
+describe("curatedSuggestions", () => {
+  it("answers the conventional spelling with the commands that own the job", () => {
+    // `status` is nowhere near `info` or `doctor` textually, so edit distance
+    // can never offer them. The table is the answer for a token whose JOB
+    // exists here under other names — and it stays a suggestion: `status` is
+    // not a command, because `info` already is.
+    expect(curatedSuggestions("status")).toEqual(["info", "doctor"]);
+  });
+
+  it("has nothing to say about a plain typo — that is ranking's job", () => {
+    expect(curatedSuggestions("infoo")).toBeUndefined();
+    expect(curatedSuggestions("")).toBeUndefined();
+  });
+
+  it("never names a command the program does not have", () => {
+    // A curated entry that outlived its target would send a confused user at
+    // nothing. Check every suggestion against the LIVE registry, so renaming
+    // `info` reddens here instead of shipping a dead hint.
+    const live = new Set(
+      capabilities.flatMap((m) => m.verbs.map((v) => v.path[0])),
+    );
+    for (const suggestion of curatedSuggestions("status") ?? []) {
+      expect(live.has(suggestion)).toBe(true);
+    }
+  });
+});
+
 describe("suggestNames", () => {
   it("ranks prefix matches ahead of edit-distance matches", () => {
     expect(suggestNames("con", ["config", "connect", "block"])).toEqual([

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

@@ -10,7 +10,31 @@
  * internals leak into the suggester.
  */
 
-import type { VerbSpec } from "../../spec/types.js";
+import type { VerbSpec } from "../../spec/index.js";
+
+/**
+ * Curated suggestions for a token whose JOB exists under other names. Edit
+ * distance cannot rank these — `status` is nowhere near `info` textually —
+ * but a user typing the conventional spelling deserves the commands that own
+ * the job here, not the nearest-looking noun. Consulted before fuzzy ranking;
+ * adding a second spelling as a real command is the one thing this table must
+ * never become.
+ */
+const CURATED_SUGGESTIONS: Readonly<Record<string, readonly string[]>> = {
+  status: ["info", "doctor"],
+};
+
+/**
+ * The curated suggestions for an unknown token, if any.
+ *
+ * @param token - The unresolved command token.
+ * @returns The commands that own the token's job, or `undefined`.
+ */
+export function curatedSuggestions(
+  token: string,
+): readonly string[] | undefined {
+  return CURATED_SUGGESTIONS[token];
+}
 
 /** An unresolved token and the sibling names to rank it against. */
 export interface UnknownCommand {

package/src/kernel/project/cli/verbHelp.test.ts

@@ -60,9 +60,39 @@ const selfVerb: VerbSpec = {
   run: async () => null,
 };
 
+/** A mutating verb with a default-true boolean, for the injected-flag rows. */
+const mutating: VerbSpec = {
+  path: ["thing", "make"],
+  summary: "Make a thing.",
+  params: [
+    {
+      kind: "boolean",
+      name: "withStyles",
+      doc: "Include styles.",
+      default: true,
+    },
+  ],
+  output: { formatters: passthrough },
+  capability: { needsStore: false, mutates: true, mcp: { expose: true } },
+  run: async () => null,
+};
+
 describe("formatVerbHelp", () => {
   const help = formatVerbHelp("pragma", get);
 
+  it("renders every flag the command parses: negations and mutation flags", () => {
+    // Help derives from the same spec facts registration reads, so a page
+    // can never deny a flag that works.
+    const mutatingHelp = formatVerbHelp("pragma", mutating);
+    expect(mutatingHelp).toContain("--with-styles");
+    expect(mutatingHelp).toContain("--no-with-styles");
+    expect(mutatingHelp).toContain("--dry-run");
+    expect(mutatingHelp).toContain("--undo");
+    expect(mutatingHelp).toContain("--yes");
+    // A read verb keeps its Flags block free of mutation rows.
+    expect(help).not.toContain("--dry-run");
+  });
+
   it("renders the usage line with the positional", () => {
     expect(help).toContain("Usage: pragma block get <name> [flags]");
   });

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

@@ -8,8 +8,9 @@
  * `formatVerbHelp`, retargeted at the grammar.
  */
 
-import { kebabCase } from "../../spec/emitSurface.js";
-import type { ParamSpec, VerbSpec } from "../../spec/types.js";
+import type { ParamSpec, VerbSpec } from "../../spec/index.js";
+import { kebabCase } from "../../spec/index.js";
+import { MUTATION_FLAG_DOCS, negationFlagDoc } from "./constants.js";
 import {
   helpColumns,
   helpDim,
@@ -73,13 +74,28 @@ export function formatVerbHelp(programName: string, verb: VerbSpec): string {
     if (cliDoc) lines.push("", cliDoc);
   }
 
-  if (flags.length > 0) {
-    lines.push(
-      "",
-      helpHeading("Flags"),
-      ...helpColumns(flags.map((flag) => [flagDisplay(flag), flag.doc])),
+  // Every flag the command PARSES is rendered, from the same spec facts
+  // registration reads: the declared params, each default-true boolean's
+  // `--no-` negation, and — on a mutating verb — the auto-injected mutation
+  // flags. Help denying a working flag is the drift this derivation removes.
+  const flagRows: (readonly [string, string])[] = flags.flatMap((flag) => {
+    const rows: (readonly [string, string])[] = [
+      [flagDisplay(flag), flag.doc] as const,
+    ];
+    if (flag.kind === "boolean" && flag.default === true) {
+      const kebab = kebabCase(flag.name);
+      rows.push([`--no-${kebab}`, negationFlagDoc(kebab)] as const);
+    }
+    return rows;
+  });
+  if (verb.capability.mutates) {
+    flagRows.push(
+      ...MUTATION_FLAG_DOCS.map(({ flag, doc }) => [flag, doc] as const),
     );
   }
+  if (flagRows.length > 0) {
+    lines.push("", helpHeading("Flags"), ...helpColumns(flagRows));
+  }
 
   if (verb.examples && verb.examples.length > 0) {
     lines.push("", helpHeading("Examples"));

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

@@ -16,9 +16,9 @@
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { MCP_SERVER_NAME, VERSION } from "../../../constants.js";
-import { bootRuntime } from "../../runtime/boot.js";
-import type { GlobalFlags } from "../../runtime/types.js";
-import type { CapabilityModule } from "../../spec/types.js";
+import type { GlobalFlags } from "../../runtime/index.js";
+import { bootRuntime } from "../../runtime/index.js";
+import type { CapabilityModule } from "../../spec/index.js";
 import { buildInstructions } from "./instructions.js";
 import { registerVerb } from "./registerVerb.js";
 
@@ -66,7 +66,10 @@ export async function buildServer(
       }
     }
     // A module's optional resource surface (NOT a tool) — the `{+uri}` template.
-    await module.mcpResources?.register(server, runtime);
+    // The WHOLE module set goes with it: the listing the provider installs is
+    // the union of every module's declared `mcpListable` slices, which the
+    // declaring module cannot see from where it sits.
+    await module.mcpResources?.register(server, runtime, modules);
     // A module's optional native prompt surface (NOT a tool) — `prompts/*`.
     await module.mcpPrompts?.register(server, runtime);
   }

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

@@ -9,8 +9,8 @@
  */
 
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import type { PragmaError } from "../../error/PragmaError.js";
-import { errorEnvelope, successEnvelope } from "../../render/envelope.js";
+import type { PragmaError } from "../../error/index.js";
+import { errorEnvelope, successEnvelope } from "../../render/index.js";
 
 /**
  * Wrap success data as an MCP tool result.

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

@@ -17,8 +17,8 @@ import {
   buildDiscoverySequence,
   CONVENTIONS,
 } from "../../../capabilities/capabilities/catalog.js";
-import { emitSurface } from "../../spec/emitSurface.js";
-import type { CapabilityModule } from "../../spec/types.js";
+import type { CapabilityModule } from "../../spec/index.js";
+import { emitSurface } from "../../spec/index.js";
 
 /** Hard ceiling on the instructions length (asserted by the protected test). */
 export const INSTRUCTIONS_MAX_CHARS = 1500;

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

@@ -17,7 +17,7 @@
  */
 
 import type { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
-import type { PragmaError } from "../../error/PragmaError.js";
+import type { PragmaError } from "../../error/index.js";
 
 /** The SDK error primitives a provider dynamic-imports and hands to {@link mcpErrorFrom}. */
 export interface McpErrorPrimitives {

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

@@ -102,9 +102,12 @@ describe("MCP plan-first is honest (PRA-104)", () => {
 
     expect(planned.ok).toBe(true);
     expect(planned.meta).toEqual({ planOnly: true, confirmRequired: true });
-    expect((planned.data as { plan: string[] }).plan).toContain(
+    // The SHARED filter applies to every mutating tool and not just `create`:
+    // the write is named, and the `ReadFile` this verb performs first is
+    // internal and filtered out, so the plan is one row.
+    expect((planned.data as { plan: string[] }).plan).toEqual([
       `Write file: ${source}.grafted (8 bytes)`,
-    );
+    ]);
     expect(readdirSync(dir)).toEqual(["present.txt"]);
   });
 });

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

@@ -0,0 +1,37 @@
+/**
+ * Prompt entities, read two ways from one graph type.
+ *
+ * A prompt lives in the graph as an entity the distribution's vocabulary
+ * declares, and two surfaces offer it: the native MCP `prompts/list` +
+ * `prompts/get` handlers, and the `prompt list` / `prompt lookup` verbs behind
+ * the covenant tools. The pair is the cohesion principle — the reader here is
+ * the ONE place either surface learns what a prompt is, so the two can never
+ * report a different set of prompts or a different template body for one.
+ *
+ * The barrel carries both halves, and they READ DIFFERENTLY — the distinction
+ * matters to anyone rerouting imports through here, so it is stated rather
+ * than implied.
+ *
+ * `promptProvider` is the MCP module hook. Its `prompts/list` is STORELESS:
+ * it projects the pack index through `listPromptSummaries`, returning `[]`
+ * when no index is reachable and never booting the store. Its `prompts/get`
+ * is store-backed. The provider is imported STATICALLY by the prompt
+ * capability (`capabilities/prompt/index.ts`) — what it defers is the MCP SDK
+ * itself, whose request schemas it reaches through a dynamic import so the SDK
+ * stays off the `--help`/`__complete` fast path.
+ *
+ * `readPrompts` and `readPrompt` are the reads the CLI verbs take, and BOTH
+ * are store-backed: they query through `runSelect` directly, not through the
+ * index projection. A caller that expects a listing here to be as cheap as the
+ * MCP one is mistaken, and a reroute that makes either reachable statically
+ * from the capability graph puts a store boot on the fast path.
+ *
+ * `listPromptSummaries` stays internal. It is the MCP list path's projection,
+ * not a shared foundation under the two exported reads, and a caller choosing
+ * it directly is choosing a partial prompt without the store-backed body that
+ * makes it usable.
+ */
+
+export { promptProvider } from "./provider.js";
+export type { PromptArgument, PromptEntry } from "./source.js";
+export { readPrompt, readPrompts } from "./source.js";

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

@@ -30,11 +30,11 @@
  */
 
 import { readPackIndex } from "../../../completion/entitySource.js";
-import { runSelect } from "../../../packs/sparql/runSelect.js";
+import { runSelect } from "../../../packs/sparql/index.js";
 import type { PackRow } from "../../../packs/types.js";
 import { distributionSource } from "../../../packs/types.js";
+import type { PragmaRuntime } from "../../../runtime/index.js";
 import type { SourcesDecision } from "../../../runtime/resolveSources.js";
-import type { PragmaRuntime } from "../../../runtime/types.js";
 import { VOCABULARY } from "../../../vocabulary.js";
 
 /** The declared prompt terms this module reads the graph with. */