@canonical/pragma-cli 0.34.0 → 0.35.0

package/src/capabilities/upgrade/upgrade.render.ts

@@ -7,15 +7,15 @@
  */
 
 import chalk from "chalk";
-import type { Formatters } from "../../kernel/spec/types.js";
-import { PRAGMA_PACKAGE } from "../shared/registry.js";
+import type { Formatters } from "../../kernel/spec/index.js";
+import { PRAGMA_PACKAGE } from "../shared/index.js";
 import type { UpgradeData } from "./types.js";
 
 export const upgradeFormatters: Formatters<UpgradeData> = {
   plain(data) {
     const lines = [`Installed via: ${data.pm}`];
     if (data.offline) {
-      lines.push("Could not reach the registry — try again later.");
+      lines.push("Cannot reach the registry — try again later.");
       return lines.join("\n");
     }
     if (data.alreadyLatest) {
@@ -40,8 +40,7 @@ export const upgradeFormatters: Formatters<UpgradeData> = {
   },
 
   llm(data) {
-    if (data.offline)
-      return "Upgrade check failed: could not reach the registry.";
+    if (data.offline) return "Upgrade check failed: cannot reach the registry.";
     if (data.alreadyLatest) {
       return `Already at the latest version (${data.current}).`;
     }

package/src/capabilities/upgrade/upgrade.test.ts

@@ -199,10 +199,10 @@ describe("assertExecOk — the exec-exitCode guard", () => {
     }
     const err = asPragmaError(thrown);
     // A denied `npm i -g` is user-fixable, NOT a bug — so it must not tell the
-    // user to "please report this issue" (that is INTERNAL_ERROR's recovery).
+    // user to "report this issue" (that is INTERNAL_ERROR's recovery).
     expect(err.code).toBe("UNSUPPORTED");
     expect(err.recovery?.message).not.toContain("report this issue");
-    expect(err.recovery?.message).toMatch(/permissions or network/i);
+    expect(err.recovery?.message).toMatch(/elevated privileges/i);
     // Surfaces the command + exit code + the captured stderr (trimmed).
     expect(err.message).toContain("npm i -g @canonical/pragma-cli");
     expect(err.message).toContain("code 13");
@@ -276,7 +276,7 @@ describe("upgrade — a failed exec maps to an actionable runtime error (exit 1)
 
   it("a missing-binary spawn (ENOENT) at a guarded site is a named UNSUPPORTED, not INTERNAL_ERROR", async () => {
     // The same wrapper `runUpgrade`/`setupLsp` apply: a spawn ENOENT REJECTS the
-    // exec, which used to collapse to INTERNAL_ERROR ("please report this issue").
+    // exec, which used to collapse to INTERNAL_ERROR ("report this issue").
     // `guardMissingBinary` names it instead.
     const thrown = await runToError(
       failVerbWith((_p, rt) =>

package/src/capabilities/upgrade/upgrade.verb.ts

@@ -16,7 +16,7 @@
 import type { Task } from "@canonical/task";
 import { BIN_NAME } from "../../constants.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
-import type { CapabilityModule, VerbSpec } from "../../kernel/spec/types.js";
+import type { CapabilityModule, VerbSpec } from "../../kernel/spec/index.js";
 import type { UpgradeData } from "./types.js";
 import { upgradeFormatters } from "./upgrade.render.js";
 

package/src/capabilities/version/index.ts

@@ -0,0 +1,12 @@
+/**
+ * The `version` capability barrel — the command form of `--version`.
+ */
+
+import type { CapabilityModule } from "../../kernel/spec/index.js";
+import { versionVerbSpec } from "./version.verb.js";
+
+/** The `version` capability module. */
+export const versionModule: CapabilityModule = {
+  name: "version",
+  verbs: [versionVerbSpec],
+};

package/src/capabilities/version/version.test.ts

@@ -0,0 +1,66 @@
+/**
+ * `pragma version` — the command form of `--version`.
+ *
+ * The verb exists because users type it; the ONLY thing worth pinning is that
+ * it is not a second answer to the same question. The process-boundary cell
+ * compares the two spellings byte for byte through the shipped entry, so a
+ * change to either one that does not change the other reddens here. The rest
+ * pins the covenant slice and the storeless, tool-free shape.
+ */
+
+import { describe, expect, it } from "vitest";
+import { VERSION } from "../../constants.js";
+import { executeVerb } from "../../kernel/project/cli/dispatch.js";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import type { GlobalFlags } from "../../kernel/runtime/types.js";
+import { emitVerb } from "../../kernel/spec/emitSurface.js";
+import { runCli } from "../../testing/helpers/runCli.js";
+import { versionModule } from "./index.js";
+
+const FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "plain",
+  verbose: false,
+};
+const REAL = { dryRun: false, undo: false, yes: false };
+const versionVerb = versionModule.verbs[0];
+
+describe("version — covenant-exact emission (PROTECTED)", () => {
+  it("emits a no-argument self-verb with NO tool", () => {
+    // The version already rides `info` and the MCP handshake's serverInfo, so
+    // a tool here would be a third way to ask one question.
+    expect(emitVerb(versionVerb)).toEqual({ v: "version", mcp: false });
+  });
+});
+
+describe("version — one value, two spellings of the same read", () => {
+  it("prints the version and never boots the store", async () => {
+    const rt = bootRuntime(FLAGS, process.cwd());
+    const outcome = await executeVerb(versionVerb, {}, REAL, rt);
+    expect(outcome.stdout).toBe(`${VERSION}\n`);
+    expect(outcome.exitCode).toBe(0);
+    expect(rt.store.booted).toBe(false);
+  });
+
+  it("json carries the value under a named field, not a bare scalar", async () => {
+    const outcome = await executeVerb(
+      versionVerb,
+      {},
+      REAL,
+      bootRuntime({ ...FLAGS, format: "json" }, process.cwd()),
+    );
+    expect(JSON.parse(outcome.stdout ?? "").data).toEqual({
+      version: VERSION,
+    });
+  });
+
+  it("the verb and the flag print the SAME bytes through the shipped entry", () => {
+    const fromVerb = runCli(["version"]);
+    const fromFlag = runCli(["--version"]);
+    expect(fromVerb.exitCode).toBe(0);
+    expect(fromFlag.exitCode).toBe(0);
+    expect(fromVerb.stdout).toBe(fromFlag.stdout);
+    expect(fromVerb.stdout).toBe(`${VERSION}\n`);
+  });
+});

package/src/capabilities/version/version.verb.ts

@@ -0,0 +1,39 @@
+/**
+ * `pragma version` — the command form of `--version`.
+ *
+ * Users type it reflexively, so it exists and prints exactly the bytes the
+ * flag prints: the bare semver on stdout, storeless, no store or network
+ * touched. Withheld from MCP — the version already rides `info` and the
+ * server handshake's `serverInfo`.
+ */
+
+import { BIN_NAME, VERSION } from "../../constants.js";
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import type { VerbSpec } from "../../kernel/spec/index.js";
+
+const versionVerb: VerbSpec<Record<string, unknown>, string> = {
+  path: ["version"],
+  summary: "Print the CLI version.",
+  doc: "Prints the version `--version` prints — one value, two spellings of the same read.",
+  params: [],
+  output: {
+    formatters: {
+      plain: (version) => version,
+      llm: (version) => version,
+      json: (version) => JSON.stringify({ version }),
+    },
+  },
+  examples: [{ cmd: `${BIN_NAME} version` }],
+  capability: {
+    needsStore: false,
+    mutates: false,
+    mcp: {
+      expose: false,
+      reason: "the version rides `info` and the MCP handshake's serverInfo",
+    },
+  },
+  run: async () => VERSION,
+};
+
+/** The `version` verb. */
+export const versionVerbSpec = asVerb(versionVerb);

package/src/constants.ts

@@ -17,6 +17,7 @@
 
 import pkg from "../package.json" with { type: "json" };
 import identity from "../pragma.conf.js";
+import type { RawConfig } from "./kernel/config/types.js";
 import { DETAIL_LEVELS, type DetailLevel } from "./kernel/config/types.js";
 
 /** CLI binary name — the distribution's `name`. */
@@ -64,12 +65,40 @@ const RECOVERY_CLI_PREFIX = `${identity.name} `;
 /** The output formats the renderer selects between (`llm` = condensed Markdown). */
 const OUTPUT_FORMATS = ["plain", "llm", "json"] as const;
 
-/** A selected output format. `--format text` is normalised to `plain`. */
+/**
+ * A selected output format. The set is CLOSED — no alias normalises into it,
+ * so a `--format` value outside {@link OUTPUT_FORMATS} is rejected at the
+ * entry point rather than quietly becoming `plain`.
+ */
 type OutputFormat = (typeof OUTPUT_FORMATS)[number];
 
 /** Default detail level when neither flag, config, nor spec pins one. */
 const DEFAULT_DETAIL_LEVEL: DetailLevel = "standard";
 
+/**
+ * The wordmark `--help` opens with, as raw ASCII-art lines.
+ *
+ * PROJECTED from the distribution config, exactly like {@link BIN_NAME} and
+ * {@link PROGRAM_DESCRIPTION} — a wordmark spells a name, so it is identity, and
+ * `kernel/copy.test.ts` forbids any kernel string from naming the distribution.
+ * Authoring the art here would have branded a fork's front door with someone
+ * else's logo; declaring it as data means a fork ships its own or none.
+ *
+ * Lines rather than one string because the art contains a backtick and
+ * backslashes: a template literal would need every one of them escaped, which is
+ * how a character gets lost the next time someone edits it.
+ */
+// Read through the DECLARED type, not the literal's inferred one. The
+// distribution config is `satisfies RawConfig`, which narrows to exactly the
+// keys that file writes — so `identity.logo` does not typecheck in a fork that
+// omits the field, which is precisely the fork this feature promises a bare
+// header. The assignment (not a cast) is what `satisfies` already guarantees,
+// and it makes every OPTIONAL field readable here. The other constants keep
+// reading `identity` directly, so their literal types are untouched.
+const declared: RawConfig = identity;
+
+const PROGRAM_LOGO: readonly string[] = declared.logo ?? [];
+
 export type { DetailLevel, OutputFormat };
 export {
   BIN_NAME,
@@ -79,6 +108,7 @@ export {
   MCP_SERVER_NAME,
   OUTPUT_FORMATS,
   PROGRAM_DESCRIPTION,
+  PROGRAM_LOGO,
   PROJECT_CONFIG_FILENAME,
   RECOVERY_CLI_PREFIX,
   VERSION,

package/src/identity.test.ts

@@ -112,15 +112,24 @@ describe("identity projection — a fork changes values, not code (PROTECTED)",
     const { upgradeModule } = await import("./capabilities/upgrade/index.js");
     const { colophonModule } = await import("./capabilities/colophon/index.js");
 
-    const help = formatRootHelp(BIN_NAME, PROGRAM_DESCRIPTION, [
-      dishList,
-      ...configModule.verbs,
-      ...upgradeModule.verbs,
-      ...colophonModule.verbs,
-    ]);
+    const help = formatRootHelp(
+      BIN_NAME,
+      PROGRAM_DESCRIPTION,
+      [
+        dishList,
+        ...configModule.verbs,
+        ...upgradeModule.verbs,
+        ...colophonModule.verbs,
+      ],
+      "9.9.9",
+      "https://recipes.test/issues",
+    );
 
     expect(help).not.toMatch(THIS_DISTRIBUTION);
-    expect(help).toMatch(/^recipes — Explore the recipe graph$/m);
+    // The fork's own name and its own version — the header stamps the build
+    // exactly as `--version` reports it, and neither half names this
+    // distribution.
+    expect(help).toMatch(/^recipes v9\.9\.9 — Explore the recipe graph$/m);
     // The pack noun leads the page untitled, and the blurb is not repeated as
     // a heading three lines under the header that already carries it.
     expect(help).toMatch(/^Usage: recipes .*\n\n {2}dish\b/m);
@@ -151,29 +160,28 @@ describe("identity projection — a fork changes values, not code (PROTECTED)",
     expect(text.startsWith("recipes — Explore the recipe graph (")).toBe(true);
   });
 
-  it("greets a first-time user with the fork's issues URL and config file", async () => {
+  it("hints at a first-time user in the fork's own name", async () => {
     process.env.XDG_CONFIG_HOME = mkdtempSync(join(tmpdir(), "identity-"));
-    const { ensureFirstRun } = await import("./kernel/config/firstRun.js");
+    const { setupHintLines } = await import("./kernel/config/firstRun.js");
     const { globalConfigPath } = await import("./kernel/config/paths.js");
 
-    const lines: string[] = [];
-    await ensureFirstRun((line) => lines.push(line));
-    const greeting = lines.join("\n");
+    const hint = setupHintLines().join("\n");
 
-    // Nothing is masked: the resolved config path is IN the greeting, so the
-    // XDG namespace has to follow the fork's name too or this assertion fails.
-    expect(greeting).not.toMatch(THIS_DISTRIBUTION);
-    expect(greeting).toContain(globalConfigPath());
+    // The hint names the fork's issues URL and its own setup command; the XDG
+    // namespace has to follow the fork's name too or the path assertion fails.
+    expect(hint).not.toMatch(THIS_DISTRIBUTION);
     expect(globalConfigPath()).toContain("/recipes/");
-    expect(greeting).toContain("https://example.invalid/recipes/issues");
-    expect(greeting).toContain("`recipes.config.ts`");
+    expect(hint).toContain("https://example.invalid/recipes/issues");
+    expect(hint).toContain("recipes setup");
   });
 
   it("narrates the colophon the fork declares, titled with the fork's name", async () => {
     // The toolchain colophon is DECLARED content (`pragma.conf.ts#colophon`),
     // not authored code: the collector must render the fork's declaration
-    // under the fork's own name. With no packs declared, the fork's whole
-    // colophon is its own story. `kind: "pragma"` is asserted AS the literal:
+    // under the fork's own name. This is also where the FALLBACK is pinned —
+    // the toolchain's own section prints when no pack tells a domain story,
+    // and a fork with no packs is the distribution that has none.
+    // `kind: "pragma"` is asserted AS the literal:
     // it is the frozen JSON discriminant every distribution serves (wire
     // compatibility, like the resource scheme), deliberately NOT derived.
     process.env.XDG_CONFIG_HOME = mkdtempSync(join(tmpdir(), "identity-"));
@@ -246,11 +254,17 @@ describe("identity projection — a fork changes values, not code (PROTECTED)",
     const { pragmaMcpEntry } = await import(
       "./capabilities/setup/operations/setupMcp.js"
     );
-    expect(pragmaMcpEntry("/work")).toEqual({
+    expect(pragmaMcpEntry("/work", "project")).toEqual({
       command: "recipes",
-      args: ["mcp"],
+      args: ["mcp", "serve"],
       cwd: "/work",
     });
+    // The global band omits `cwd` (a per-user server is not project-pinned)
+    // but still runs the fork's own binary.
+    expect(pragmaMcpEntry("/work", "global")).toEqual({
+      command: "recipes",
+      args: ["mcp", "serve"],
+    });
   });
 
   it("generates a reference that never names this distribution", async () => {
@@ -263,9 +277,10 @@ describe("identity projection — a fork changes values, not code (PROTECTED)",
     // ONE exemption, the same one the MCP orientation case above makes and for
     // the same reason: the `pragma:` resource scheme is covenant-frozen PROTOCOL
     // identity (`surface.v2.json`), inherited by a fork along with the
-    // `pragma/box` and `pragma/instanceCount` `_meta` keys it travels with, and
-    // `tools.md` reports it truthfully. Masked from the emitted surface, not by
-    // a literal, so a leak the kernel authored itself still fails here.
+    // `pragma/box`, `pragma/instanceCount` and `pragma/type` `_meta` keys it
+    // travels with, and `tools.md` reports it truthfully. Masked from the
+    // emitted surface, not by a literal, so a leak the kernel authored itself
+    // still fails here.
     const { emitReference } = await import("./kernel/spec/emitReference.js");
     const { emitSurface } = await import("./kernel/spec/emitSurface.js");
     const { capabilities } = await import("./capabilities/index.js");

package/src/kernel/completion/__snapshots__/emitScripts.test.ts.snap

@@ -65,21 +65,21 @@ _pragma() {
   # flag names
   if [[ "$cur" == -* ]]; then
     case "$noun/$verb" in
-      block/get) COMPREPLY=($(compgen -W "--view --out --with-meta --note --format --verbose --detail --help" -- "$cur")); return ;;
-      block/list) COMPREPLY=($(compgen -W "--tags --format --verbose --detail --help" -- "$cur")); return ;;
-      block/remove) COMPREPLY=($(compgen -W "--dry-run --undo --yes --format --verbose --detail --help" -- "$cur")); return ;;
+      block/get) COMPREPLY=($(compgen -W "--view --out --with-meta --note --format --verbose --detail --no-headers --quiet --help" -- "$cur")); return ;;
+      block/list) COMPREPLY=($(compgen -W "--tags --format --verbose --detail --no-headers --quiet --help" -- "$cur")); return ;;
+      block/remove) COMPREPLY=($(compgen -W "--dry-run --undo --yes --format --verbose --detail --no-headers --quiet --help" -- "$cur")); return ;;
     esac
     if [ -z "$noun" ]; then
-      COMPREPLY=($(compgen -W "--format --verbose --detail --help --version" -- "$cur"))
+      COMPREPLY=($(compgen -W "--format --verbose --detail --no-headers --quiet --help --version" -- "$cur"))
     else
-      COMPREPLY=($(compgen -W "--format --verbose --detail --help" -- "$cur"))
+      COMPREPLY=($(compgen -W "--format --verbose --detail --no-headers --quiet --help" -- "$cur"))
     fi
     return
   fi
 
   # nouns
   if [ -z "$noun" ]; then
-    COMPREPLY=($(compgen -W "block mcp standard status" -- "$cur"))
+    COMPREPLY=($(compgen -W "block standard status" -- "$cur"))
     return
   fi
 
@@ -172,12 +172,14 @@ end
 complete -c pragma -f
 
 # nouns
-complete -c pragma -n "__pragma_at ''" -a "block mcp standard status"
+complete -c pragma -n "__pragma_at ''" -a "block standard status"
 
 # global flags
 complete -c pragma -l format -x -a "plain llm json"
 complete -c pragma -l verbose
 complete -c pragma -l detail -x -a "summary standard detailed"
+complete -c pragma -l no-headers
+complete -c pragma -l quiet
 complete -c pragma -l help
 complete -c pragma -n "__pragma_at ''" -l version
 
@@ -277,21 +279,21 @@ _pragma() {
   # flag names
   if [[ "$cur" == -* ]]; then
     case "$noun/$verb" in
-      block/get) compadd -- --view --out --with-meta --note --format --verbose --detail --help; return 0 ;;
-      block/list) compadd -- --tags --format --verbose --detail --help; return 0 ;;
-      block/remove) compadd -- --dry-run --undo --yes --format --verbose --detail --help; return 0 ;;
+      block/get) compadd -- --view --out --with-meta --note --format --verbose --detail --no-headers --quiet --help; return 0 ;;
+      block/list) compadd -- --tags --format --verbose --detail --no-headers --quiet --help; return 0 ;;
+      block/remove) compadd -- --dry-run --undo --yes --format --verbose --detail --no-headers --quiet --help; return 0 ;;
     esac
     if [[ -z "$noun" ]]; then
-      compadd -- --format --verbose --detail --help --version
+      compadd -- --format --verbose --detail --no-headers --quiet --help --version
     else
-      compadd -- --format --verbose --detail --help
+      compadd -- --format --verbose --detail --no-headers --quiet --help
     fi
     return 0
   fi
 
   # nouns
   if [[ -z "$noun" ]]; then
-    compadd -- block mcp standard status
+    compadd -- block standard status
     return 0
   fi
 

package/src/kernel/completion/complete.test.ts

@@ -16,15 +16,24 @@ describe("runComplete — the __complete pipeline", () => {
   it("resolves against the live capabilities (storeless static matches)", async () => {
     await expect(runComplete(["co"], capabilities)).resolves.toEqual([
       "colophon",
+      "concept",
       "config",
     ]);
     // The live `config` sub-verbs, prefix-filtered and sorted by the resolver.
-    // AV-228 B3 retired the per-field tier/channel/detail verbs, leaving set + show.
+    // AV-228 B3 retired the per-field tier/channel/detail verbs; the family is
+    // now the four jobs — read all, read one, write one, clear one.
     await expect(runComplete(["config", ""], capabilities)).resolves.toEqual([
+      "get",
       "set",
       "show",
+      "unset",
     ]);
     await expect(runComplete(["mc"], capabilities)).resolves.toEqual(["mcp"]);
+    // The server entry completes from its own spec — it used to be injected
+    // into the model because the bin served it without one.
+    await expect(runComplete(["mcp", ""], capabilities)).resolves.toEqual([
+      "serve",
+    ]);
     await expect(runComplete(["--d"], capabilities)).resolves.toEqual([
       "--detail",
     ]);
@@ -38,6 +47,7 @@ describe("runComplete — the __complete pipeline", () => {
   it("strips a leading bin name", async () => {
     await expect(runComplete(["pragma", "co"], capabilities)).resolves.toEqual([
       "colophon",
+      "concept",
       "config",
     ]);
   });
@@ -93,7 +103,7 @@ describe("runComplete — never-throw guard (PROTECTED)", () => {
     await runComplete(["co"], capabilities);
     const lines = write.mock.calls.map((call) => String(call[0]));
     expect(lines.join("")).toMatch(
-      /\[complete\] context=noun partial="co" candidates=2 in \d+(\.\d+)?ms/,
+      /\[complete\] context=noun partial="co" candidates=3 in \d+(\.\d+)?ms/,
     );
   });
 });

package/src/kernel/completion/complete.ts

@@ -30,7 +30,7 @@
  * whole grammar is testable through this one function.
  */
 
-import type { CapabilityModule } from "../spec/types.js";
+import type { CapabilityModule } from "../spec/index.js";
 import { emptyNameSource } from "./entitySource.js";
 import { buildCompletionModel } from "./model.js";
 import { parseWords } from "./parse.js";

package/src/kernel/completion/emitScripts.ts

@@ -28,7 +28,7 @@
  */
 
 import { BIN_NAME } from "../../constants.js";
-import type { CapabilityModule } from "../spec/types.js";
+import type { CapabilityModule } from "../spec/index.js";
 import { assertSafeToken, buildCompletionModel } from "./model.js";
 import { bashScript } from "./templates/bash.js";
 import { fishScript } from "./templates/fish.js";

package/src/kernel/completion/entitySource.test.ts

@@ -313,7 +313,7 @@ describe("the storeless fast path implements the pointer half", () => {
     // and would pass with the config file deleted. The read half refusing is
     // what makes this directory a configured-but-unbuilt project rather than a
     // fresh install. (`doctor` says so too, in the same words: verified against
-    // the compiled binary, where `block list` raises STORE_UNAVAILABLE while
+    // a cold install, where `block list` raises STORE_UNAVAILABLE while
     // this same completion still answers.)
     //
     // If a later change gives the fast path a config-free way to see

package/src/kernel/completion/entitySource.ts

@@ -33,11 +33,13 @@
  * - The embedded fallback is read from `pack.index.generated` — its OWN
  *   generated module (only the index string) — so the storeless `__complete`
  *   path never EVALUATES the n-quads/schema/manifest strings that live in
- *   `pack.generated`. It does not avoid parsing them: `bun build --compile`
- *   emits one script, so the whole embed is parsed at process start on every
- *   invocation (~+25 ms here, measured on `--version` against a toy-embed
- *   binary; BUDGETS.md records it). What the split buys is that a completion
- *   never allocates the 1.87 MB.
+ *   `pack.generated`. Under the compiled binary it did not avoid PARSING them
+ *   either — one emitted script meant the whole embed was parsed at process
+ *   start on every invocation (~+25 ms, measured on `--version`; BUDGETS.md
+ *   records it), and the split bought only that a completion never allocated
+ *   the 1.87 MB. Shipping per-module output changed that: `pack.generated` is
+ *   a separate module the fast path never imports, so it is no longer parsed
+ *   at all there. The split now buys both.
  * - The active pack is resolved through `kernel/runtime/paths` — a LEAF module
  *   (node builtins only) that shares the pointer read with `resolveSources`.
  *   `resolveSources` itself is unreachable from here: it pulls the graphpack
@@ -62,7 +64,7 @@ import { discoverSkills } from "../../capabilities/skill/discover.js";
 // Inlined embedded index — its OWN generated module (only the index string), so
 // the storeless `__complete` path never pulls the n-quads/schema/manifest
 // strings that live in `pack.generated.ts`.
-import { DEFAULT_PREFIX_MAP } from "../render/prefixes.js";
+import { DEFAULT_PREFIX_MAP } from "../render/index.js";
 import { indexJson as EMBEDDED_INDEX_JSON } from "../runtime/graphpack/embedded/pack.index.generated.js";
 import type { PackIndex, PackIndexEntity } from "../runtime/graphpack/types.js";
 import { packDir, readActivePack } from "../runtime/paths.js";
@@ -156,8 +158,19 @@ function loadActiveIndex(cwd: string): PackIndex | undefined {
     : readIndexFile(packDir(contentHash));
 }
 
-/** Whether an entity matches a prefixed type filter (primary type or any type). */
-function matchesType(entity: PackIndexEntity, type: string): boolean {
+/**
+ * Whether an entity matches a prefixed type filter (primary type or any type).
+ *
+ * Exported because the MCP resource listing addresses the index by the SAME
+ * vocabulary a completion source does (`McpListableRef` reuses
+ * `CompletionSourceRef`'s fields), and "which entities is this type?" must be
+ * ONE rule — two would let a type list entities its completion refuses.
+ *
+ * @param entity - The indexed entity to test.
+ * @param type - A prefixed type filter; empty matches every entity.
+ * @returns Whether the entity carries that type.
+ */
+export function matchesType(entity: PackIndexEntity, type: string): boolean {
   if (!type) return true;
   if (entity.type === type) return true;
   return Array.isArray(entity.types) && entity.types.includes(type);