@canonical/pragma-cli 0.33.0 → 0.34.0

package/src/capabilities/prompt/verbs.ts

@@ -12,10 +12,13 @@
  * formatters).
  */
 
+import { BIN_NAME } from "../../constants.js";
 import { PragmaError } from "../../kernel/error/PragmaError.js";
+import { cliRecovery } from "../../kernel/error/recovery.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 { VOCABULARY } from "../../kernel/vocabulary.js";
 import {
   promptListFormatters,
   promptLookupFormatters,
@@ -34,10 +37,10 @@ const READ_CAPABILITY = {
 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.",
+  doc: `Browse the prompt entities the active graph declares (${VOCABULARY.prompt.type} in this distribution) — name, description, and argument names. This distribution's graph carries none today. 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" }],
+  examples: [{ cmd: `${BIN_NAME} prompt list` }],
   capability: READ_CAPABILITY,
   run: (_params: Record<string, unknown>, rt: PragmaRuntime) =>
     import("../../kernel/project/mcp/prompts/source.js").then(async (m) => {
@@ -55,19 +58,31 @@ const listVerb: VerbSpec<Record<string, unknown>, PromptListData> = {
 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.",
+  doc: "Fetch a single prompt entity's full template body (with {{arg}} placeholders) and its declared arguments. A prompt is addressed by its label; prompt_list names the ones the active graph carries.",
   params: [
     {
       kind: "string",
       name: "name",
-      doc: "The prompt name (e.g. build-a-block).",
+      doc: "The prompt name, as `prompt list` reports it.",
       positional: true,
       required: true,
-      complete: { kind: "names", source: { from: "prompts" } },
+      // A prompt is addressed by its `rdfs:label`, which the index carries as
+      // `label`, and the index reader offers no substitute for a prompt that
+      // carries none. Not a total guarantee: `label` is the first of several
+      // label predicates the index accepts, so an entity labelled ONLY by
+      // `skos:prefLabel` would still complete without resolving. That gap is
+      // the index's label preference order, not this ref.
+      complete: {
+        kind: "names",
+        source: { from: "index", type: VOCABULARY.prompt.type, field: "label" },
+      },
     },
   ],
   output: { formatters: promptLookupFormatters },
-  examples: [{ cmd: "pragma prompt lookup build-a-block" }],
+  // No example command: this distribution's graph declares no prompt, so any
+  // name quoted here exits 1 with ENTITY_NOT_FOUND — and this is the GENERATED
+  // reference, published as machine-derived truth.
+  examples: [],
   capability: READ_CAPABILITY,
   run: (params: Record<string, unknown>, rt: PragmaRuntime) =>
     import("../../kernel/project/mcp/prompts/source.js").then(async (m) => {
@@ -77,11 +92,9 @@ const lookupVerb: VerbSpec<Record<string, unknown>, PromptLookupData> = {
         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" },
-          },
+          recovery: cliRecovery("prompt list", "List available prompts.", {
+            tool: "prompt_list",
+          }),
         });
       }
       return entry;

package/src/capabilities/resources/provider.ts

@@ -3,9 +3,11 @@
  *
  * 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).
+ * reads one. They read it for the pack the BOOT DECISION names, so the listing
+ * can never advertise entities whose reads then fail STORE_UNAVAILABLE. 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
@@ -16,12 +18,14 @@
  * the `--help`/`__complete` fast path.
  */
 
+import { BIN_NAME } from "../../constants.js";
 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 { resolveSources } from "../../kernel/runtime/resolveSources.js";
 import type { McpResourceProvider } from "../../kernel/spec/types.js";
 
 /** Max autocomplete suggestions returned for a partial URI. */
@@ -32,13 +36,25 @@ 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. */
+/**
+ * The `pragma:` URI scheme + the single reserved-expansion template variable.
+ *
+ * A LITERAL, and it must stay one until the wire identifiers move together.
+ * `surface/surface.v2.json` freezes `pragma:{+uri}` as protocol identity, and
+ * `buildResourceList` mints `pragma:<prefixed>` for every entry it lists —
+ * three writings of one decision. Deriving only this one made a fork advertise
+ * `recipes:{+uri}` over a list of 653 `pragma:` URIs: every resource the server
+ * offered became unreadable, and the readable form was never advertised.
+ * `resources.test.ts` pins the pair through {@link resourceProvider}'s declared
+ * surface; `identity.test.ts` masks this template out of its leak scan for the
+ * same reason.
+ */
 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>`.";
+  `Content mirrors \`${BIN_NAME} graph inspect <uri>\`.`;
 
 /** Agent-navigability annotations mirrored onto a listed resource. */
 export interface ResourceAnnotations {
@@ -80,8 +96,7 @@ export function buildResourceList(
       {
         uri: "pragma:sources",
         name: "Store not indexed",
-        description:
-          "No enriched entity index. Run `pragma sources update` to build it.",
+        description: `No enriched entity index. Run \`${BIN_NAME} sources update\` to build it.`,
         mimeType: "application/json",
       },
     ];
@@ -197,14 +212,18 @@ export const resourceProvider: McpResourceProvider = {
     const { McpError, ErrorCode } = await import(
       "@modelcontextprotocol/sdk/types.js"
     );
+    // The index of the pack the boot decision names — `undefined` when the
+    // store is unavailable, which `buildResourceList` renders as the recovery
+    // entry rather than a catalogue of unreadable URIs.
+    const activeIndex = async (): Promise<PackIndex | undefined> =>
+      readPackIndex(resolveSources(await runtime.loadConfig(), runtime.cwd));
+
     const template = new ResourceTemplate(URI_TEMPLATE, {
-      list: async () => ({
-        resources: buildResourceList(readPackIndex(runtime.cwd)),
-      }),
+      list: async () => ({ resources: buildResourceList(await activeIndex()) }),
       complete: {
         uri: async (value: string) =>
           rankUriCompletions(
-            readPackIndex(runtime.cwd)?.entities ?? [],
+            (await activeIndex())?.entities ?? [],
             value,
             COMPLETION_LIMIT,
           ),

package/src/capabilities/resources/resources.test.ts

@@ -7,7 +7,7 @@
  * degrades to a `pragma sources update` hint (never a live re-index).
  */
 
-import { mkdtempSync } from "node:fs";
+import { mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { ErrorCode } from "@modelcontextprotocol/sdk/types.js";
@@ -16,13 +16,40 @@ import { readPackIndex } from "../../kernel/completion/entitySource.js";
 import { verbKey } from "../../kernel/packs/uniqueness.js";
 import { bootRuntime } from "../../kernel/runtime/boot.js";
 import type { PackIndex } from "../../kernel/runtime/graphpack/types.js";
-import { writeLock } from "../../kernel/runtime/lock.js";
 import type { InspectResult } from "../../kernel/runtime/readEntity.js";
 import type { VerbSpec } from "../../kernel/spec/types.js";
 import { TEST_FLAGS } from "../../testing/helpers/projectCli.js";
 import { projectMcp } from "../../testing/helpers/projectMcp.js";
 import { graphModule } from "../graph/index.js";
-import { buildResourceList, rankUriCompletions } from "./provider.js";
+import {
+  buildResourceList,
+  rankUriCompletions,
+  resourceProvider,
+} from "./provider.js";
+
+/**
+ * Two entities of the committed embedded pack, chosen for what they PROVE: an
+ * abox individual and the tbox class it instantiates, so the schema-before-
+ * individual ordering has both sides. Named, not counted — the roster moves
+ * whenever the design system does.
+ */
+const BUTTON_NAME = "ds:global.component.button";
+const BUTTON_URI = `pragma:${BUTTON_NAME}`;
+const COMPONENT_URI = "pragma:ds:Component";
+
+/**
+ * Blank out blank-node labels.
+ *
+ * Oxigraph re-mints blank-node identifiers every time it loads a store, so two
+ * independently booted sessions over the SAME pack name the same blank node
+ * differently. Those labels are store-local handles, not content — and this
+ * test's subject is that both surfaces return the same CONTENT for the same
+ * entity. (That the labels are not stable across processes is a real property
+ * of exposing blank nodes through `graph inspect`; the toy pack this suite used
+ * to run against simply had none.)
+ */
+const withoutBlankNodeLabels = (value: InspectResult): unknown =>
+  JSON.parse(JSON.stringify(value).replace(/_:[0-9a-f]+/g, "_:b"));
 
 describe("resource listing (storeless, over the pack index)", () => {
   it("degrades to a recovery entry on a missing or legacy index", () => {
@@ -37,15 +64,13 @@ describe("resource listing (storeless, over the pack index)", () => {
   });
 
   it("lists the enriched (v2) embedded index, schema entries first", () => {
-    const index = readPackIndex(process.cwd());
+    const index = readPackIndex({ kind: "embedded" });
     expect(index?.version).toBe(2);
     const resources = buildResourceList(index);
-    expect(resources.some((r) => r.uri === "pragma:ex:Button")).toBe(true);
+    expect(resources.some((r) => r.uri === BUTTON_URI)).toBe(true);
     // A class (tbox) sorts before an individual (abox).
-    const componentIdx = resources.findIndex(
-      (r) => r.uri === "pragma:ex:Component",
-    );
-    const buttonIdx = resources.findIndex((r) => r.uri === "pragma:ex:Button");
+    const componentIdx = resources.findIndex((r) => r.uri === COMPONENT_URI);
+    const buttonIdx = resources.findIndex((r) => r.uri === BUTTON_URI);
     expect(componentIdx).toBeLessThan(buttonIdx);
   });
 
@@ -92,24 +117,46 @@ describe("resource listing (storeless, over the pack index)", () => {
   });
 
   it("enriches each entry with the _meta taxonomy (pragma/box + priority)", () => {
-    const resources = buildResourceList(readPackIndex(process.cwd()));
-    const component = resources.find((r) => r.uri === "pragma:ex:Component");
-    const button = resources.find((r) => r.uri === "pragma:ex:Button");
+    const resources = buildResourceList(readPackIndex({ kind: "embedded" }));
+    const component = resources.find((r) => r.uri === COMPONENT_URI);
+    const button = resources.find((r) => r.uri === BUTTON_URI);
     // A schema class: tbox, higher priority, carries its instance count.
     expect(component?._meta?.["pragma/box"]).toBe("tbox");
     expect(component?.annotations?.audience).toEqual(["assistant"]);
     expect(component?.annotations?.priority).toBe(0.9);
-    expect(component?._meta?.["pragma/instanceCount"]).toBe(3);
+    expect(component?._meta?.["pragma/instanceCount"]).toBeGreaterThan(0);
     // An individual: abox, lower priority, no instance count.
     expect(button?._meta?.["pragma/box"]).toBe("abox");
     expect(button?.annotations?.priority).toBe(0.3);
     expect(button?._meta?.["pragma/instanceCount"]).toBeUndefined();
   });
 
+  it("mints every URI in the scheme the declared template routes", () => {
+    // Two writings of one decision: the template `register` installs (and the
+    // covenant publishes as `mcpSurface.resources`) and the scheme every listed
+    // URI carries. Nothing compared them, and a half-derivation left a fork
+    // advertising `recipes:{+uri}` over a list of `pragma:` URIs — every
+    // resource offered was unreadable and the readable form was unadvertised.
+    // DERIVED from the declared surface, so this cannot be satisfied by two
+    // literals that agree today.
+    const declared = resourceProvider.surface?.templates?.[0];
+    const scheme = `${declared?.split(":")[0]}:`;
+    const listed = [
+      ...buildResourceList(readPackIndex({ kind: "embedded" })),
+      ...buildResourceList(undefined),
+    ];
+    expect(listed.length).toBeGreaterThan(1);
+    expect(listed.filter((r) => !r.uri.startsWith(scheme))).toEqual([]);
+  });
+
   it("ranks autocomplete over prefixed URI and label", () => {
-    const index = readPackIndex(process.cwd());
-    const hits = rankUriCompletions(index?.entities ?? [], "but", 10);
-    expect(hits).toContain("ex:Button");
+    const index = readPackIndex({ kind: "embedded" });
+    const hits = rankUriCompletions(
+      index?.entities ?? [],
+      "global.component.button",
+      10,
+    );
+    expect(hits).toContain(BUTTON_NAME);
   });
 });
 
@@ -124,7 +171,7 @@ describe("resource surface over the server (embedded pack)", () => {
 
   it("registers the {+uri} template and lists resources (not tools)", async () => {
     const resources = await harness.listResources();
-    expect(resources.some((r) => r.uri === "pragma:ex:Button")).toBe(true);
+    expect(resources.some((r) => r.uri === BUTTON_URI)).toBe(true);
     // Resources are NOT tools — the graph module's tools (inspect + the PR6
     // SPARQL escape hatch) are what appear in the tool surface.
     const tools = await harness.listTools();
@@ -135,12 +182,12 @@ describe("resource surface over the server (embedded pack)", () => {
   });
 
   it("autocompletes a partial URI through the template", async () => {
-    const values = await harness.completeResource("But");
-    expect(values).toContain("ex:Button");
+    const values = await harness.completeResource("global.component.butt");
+    expect(values).toContain(BUTTON_NAME);
   });
 
   it("reads an entity, mirroring `graph inspect` content", async () => {
-    const read = await harness.readResource("pragma:ex:Button");
+    const read = await harness.readResource(BUTTON_URI);
     expect(read.mimeType).toBe("application/json");
     const fromResource = JSON.parse(read.text) as InspectResult;
 
@@ -150,21 +197,25 @@ describe("resource surface over the server (embedded pack)", () => {
       (v) => verbKey(v.path) === "graph inspect",
     ) as VerbSpec;
     const fromCli = (await inspect.run(
-      { uri: "ex:Button" },
+      { uri: BUTTON_NAME },
       rt,
     )) as InspectResult;
     (await rt.store.get()).store.dispose();
 
-    expect(fromResource).toEqual(fromCli);
-    expect(fromResource.uri).toBe("https://pragma.canonical.com/sample#Button");
+    expect(withoutBlankNodeLabels(fromResource)).toEqual(
+      withoutBlankNodeLabels(fromCli),
+    );
+    expect(fromResource.uri).toBe(
+      "https://ds.canonical.com/global.component.button",
+    );
   });
 
   it("rejects a read of an absent entity as InvalidParams carrying ENTITY_NOT_FOUND", async () => {
-    // The warm embedded pack resolves the `ex:` prefix but holds no `Nonexistent`
+    // The warm embedded pack resolves the `ds:` prefix but holds no `Nonexistent`
     // subject, so the read fails ENTITY_NOT_FOUND — the caller's fault, which
     // `mcpErrorFrom` maps to JSON-RPC InvalidParams, NOT the InternalError a cold
     // store (STORE_UNAVAILABLE) earns.
-    const error = await harness.readResource("pragma:ex:Nonexistent").then(
+    const error = await harness.readResource("pragma:ds:Nonexistent").then(
       () => undefined,
       (caught: unknown) => caught,
     );
@@ -181,14 +232,19 @@ describe("resource surface over the server (embedded pack)", () => {
  * D3 — a resource-read failure surfaces as a JSON-RPC error (the read analogue of
  * a tool result's `isError`) carrying the recovery, NOT swallowed into a
  * `text/plain` "success" body that drops the recovery and reads as though the
- * entity itself were malformed. A lock pointing at an evicted pack is the cold
- * store; the read boots the store, so it must refuse with STORE_UNAVAILABLE.
+ * entity itself were malformed. A project that declares its own packs and has
+ * never built them is the cold store — it must NOT be served the distribution's
+ * embedded graph; the read boots the store, so it refuses with
+ * STORE_UNAVAILABLE.
  */
 describe("resource read — cold-store failure surfaces isError + recovery (D3)", () => {
   let harness: Awaited<ReturnType<typeof projectMcp>>;
   beforeAll(async () => {
     const cwd = mkdtempSync(join(tmpdir(), "pragma-resource-cold-"));
-    writeLock(cwd, { version: 1, contentHash: "b".repeat(64), packs: [] });
+    writeFileSync(
+      join(cwd, "pragma.config.ts"),
+      `export default { packs: [{ name: "unbuilt", source: "file:///pragma-never-built" }] };\n`,
+    );
     harness = await projectMcp([graphModule], cwd);
   });
   afterAll(async () => {
@@ -196,7 +252,7 @@ describe("resource read — cold-store failure surfaces isError + recovery (D3)"
   });
 
   it("rejects (does not return text/plain content) with the STORE_UNAVAILABLE recovery", async () => {
-    const error = await harness.readResource("pragma:ex:Button").then(
+    const error = await harness.readResource(BUTTON_URI).then(
       () => undefined,
       (caught: unknown) => caught,
     );

package/src/capabilities/setup/operations/setupGenerator.ts

@@ -28,6 +28,7 @@ import type {
   PromptDefinition,
 } from "@canonical/summon-core";
 import { sequence_, type Task, when } from "@canonical/task";
+import { BIN_NAME } from "../../../constants.js";
 import type { PragmaRuntime } from "../../../kernel/runtime/types.js";
 import { guardMissingBinary } from "../../shared/assertExecOk.js";
 import type {
@@ -125,7 +126,7 @@ const buildMeta = (
 ): GeneratorDefinition["meta"] => ({
   name: title,
   displayName: title,
-  description: "Configure pragma for this project",
+  description: `Configure ${BIN_NAME} for this project`,
   version: rt.version,
 });
 
@@ -135,7 +136,7 @@ const buildCustomizePrompt = (
 ): PromptDefinition => ({
   name: "customize",
   type: "confirm",
-  message: "Customize which files pragma configures?",
+  message: `Customize which files ${BIN_NAME} configures?`,
   default: false,
   when,
 });
@@ -282,7 +283,7 @@ function buildRunAllPlan(
   // reads already happened up front). Composing an unchosen step is harmless:
   // `when(false, …)` discards the (side-effect-free) task it was handed.
   const generator: GeneratorDefinition = {
-    meta: buildMeta(rt, "pragma setup"),
+    meta: buildMeta(rt, `${BIN_NAME} setup`),
     prompts,
     generate: (answers) => {
       const chosen = readSteps(answers);
@@ -342,8 +343,11 @@ export async function buildSetupPlan(
     case "completions": {
       const d = await detectCompletions(rt.cwd);
       return {
-        generator: buildSingleStep(rt, "pragma setup completions", [], () =>
-          composeCompletions(d),
+        generator: buildSingleStep(
+          rt,
+          `${BIN_NAME} setup completions`,
+          [],
+          () => composeCompletions(d),
         ),
         toResult: () => ({
           kind: "completions",
@@ -358,7 +362,7 @@ export async function buildSetupPlan(
     case "lsp": {
       const d = await detectLsp(rt.cwd);
       return {
-        generator: buildSingleStep(rt, "pragma setup lsp", [], () =>
+        generator: buildSingleStep(rt, `${BIN_NAME} setup lsp`, [], () =>
           composeGuardedLsp(rt, d.state),
         ),
         toResult: () => ({ kind: "lsp", state: d.state }),
@@ -375,8 +379,11 @@ export async function buildSetupPlan(
             ]
           : [];
       return {
-        generator: buildSingleStep(rt, "pragma setup mcp", prompts, (answers) =>
-          composeMcp(d, selectChosenGroups(d, answers)),
+        generator: buildSingleStep(
+          rt,
+          `${BIN_NAME} setup mcp`,
+          prompts,
+          (answers) => composeMcp(d, selectChosenGroups(d, answers)),
         ),
         toResult: (answers) => {
           const sel = selectChosenGroups(d, answers);
@@ -393,7 +400,7 @@ export async function buildSetupPlan(
       const d = await detectSkills(rt);
       if (!d.available) throw skillsEmptyError();
       return {
-        generator: buildSingleStep(rt, "pragma setup skills", [], () =>
+        generator: buildSingleStep(rt, `${BIN_NAME} setup skills`, [], () =>
           composeSkills(d),
         ),
         toResult: () => ({ kind: "skills", result: toSkillsResult(d) }),

package/src/capabilities/setup/operations/setupMcp.ts

@@ -63,7 +63,7 @@ export interface McpDetection {
  * @returns The pragma {@link McpServerConfig}.
  */
 export function pragmaMcpEntry(cwd: string): McpServerConfig {
-  return { command: "pragma", args: ["mcp"], cwd };
+  return { command: MCP_SERVER_NAME, args: ["mcp"], cwd };
 }
 
 /**
@@ -228,7 +228,7 @@ export function composeMcp(
           : "→";
     tasks.push(
       info(
-        `[${group.scope}] pragma MCP server ${verb} ${group.path} (${names})`,
+        `[${group.scope}] ${MCP_SERVER_NAME} MCP server ${verb} ${group.path} (${names})`,
       ),
     );
   }

package/src/capabilities/setup/operations/setupSkills.ts

@@ -19,7 +19,7 @@ import {
   symlink,
   type Task,
 } from "@canonical/task";
-import { RECOVERY_CLI_PREFIX } from "../../../constants.js";
+import { BIN_NAME } from "../../../constants.js";
 import { PragmaError } from "../../../kernel/error/PragmaError.js";
 import { cliRecovery } from "../../../kernel/error/recovery.js";
 import type { PragmaRuntime } from "../../../kernel/runtime/types.js";
@@ -198,8 +198,8 @@ export function skillsEmptyError(): PragmaError {
   return PragmaError.emptyResults("skill", {
     message: "No skills found to link.",
     recovery: cliRecovery(
-      `${RECOVERY_CLI_PREFIX}sources update`,
-      "Add a design-system package that ships skills to your config, then run `pragma sources update` to install them.",
+      "sources update",
+      `Add a design-system package that ships skills to your config, then run \`${BIN_NAME} sources update\` to install them.`,
     ),
   });
 }

package/src/capabilities/setup/setup.verb.ts

@@ -21,6 +21,7 @@
 
 import type { GeneratorResult } from "@canonical/summon-core";
 import { $, gen, type Task } from "@canonical/task";
+import { BIN_NAME } from "../../constants.js";
 import type { PragmaRuntime } from "../../kernel/runtime/types.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
 import type {
@@ -207,20 +208,26 @@ const setupAllVerb = setupVerb(
     params: SCOPE_PARAMS,
     doc: "Runs the shell-completions, LSP, MCP, and skills installers as a single wizard: pick the steps, review the recap, then apply. The scope option targets the project band, the user/home band, or both.",
     examples: [
-      { cmd: "pragma setup" },
-      { cmd: "pragma setup --dry-run", note: "preview every step's effects" },
+      { cmd: `${BIN_NAME} setup` },
       {
-        cmd: "pragma setup --global",
+        cmd: `${BIN_NAME} setup --dry-run`,
+        note: "preview every step's effects",
+      },
+      {
+        cmd: `${BIN_NAME} setup --global`,
         note: "configure only the user/home band",
       },
-      { cmd: "pragma setup mcp", note: "just the MCP server registration" },
+      {
+        cmd: `${BIN_NAME} setup mcp`,
+        note: "just the MCP server registration",
+      },
     ],
   },
 );
 
 const mcpVerb = setupVerb(
   ["setup", "mcp"],
-  "Register the pragma MCP server in detected AI harnesses.",
+  `Register the ${BIN_NAME} MCP server in detected AI harnesses.`,
   "mcp",
   SUB_CAPABILITY,
   { params: SCOPE_PARAMS },

package/src/capabilities/setup/shell.ts

@@ -9,6 +9,7 @@
 
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { BIN_NAME } from "../../constants.js";
 
 /** The shells `setup completions` can install for. */
 export type ShellId = "zsh" | "bash" | "fish";
@@ -34,6 +35,31 @@ export function detectShell(): ShellId | null {
 /**
  * The standard install path for a shell's completion script.
  *
+ * The BASENAME is {@link BIN_NAME}, never a literal, because `emitScripts`
+ * derives the script's own `#compdef` / `complete -F` / `complete -c` from that
+ * same name, and for two of the three shells the basename decides whether the
+ * file is ever loaded. Measured against real shells with the distribution
+ * renamed to `widget9`:
+ *
+ * - **fish** autoloads `completions/<cmd>.fish` BY NAME. A correct `widget9`
+ *   script in a file called `pragma.fish` is never loaded — TAB silently falls
+ *   back to filenames. Verified: renaming that one file is the entire
+ *   difference between candidates and no candidates.
+ * - **bash-completion** looks up `completions/<cmd>` by the command name the
+ *   same way. Verified against bash-completion 2.11's `__load_completion`:
+ *   with the file named `widget9`, `complete -p widget9` reports
+ *   `complete -F _widget9 widget9`; with the identical file named `pragma`,
+ *   `_widget9` is never defined and bash falls back to `_minimal`.
+ * - **zsh** does NOT work that way: `compinit` binds by the `#compdef` tag
+ *   inside the file, so `~/.zfunc/_pragma` holding `#compdef widget9` does
+ *   complete `widget9` (verified — `_comps[widget9]` resolves to `_pragma`).
+ *   The basename still matters, for a different reason: it names the function
+ *   zsh autoloads, and two distributions both writing `_pragma` would silently
+ *   overwrite each other's completions.
+ *
+ * Either way `setup completions` and `doctor` report success, so nothing else
+ * would tell the user.
+ *
  * @param shell - The target shell.
  * @returns The absolute path the completion script is written to.
  * @note Impure — reads the home directory.
@@ -42,7 +68,7 @@ export function completionScriptPath(shell: ShellId): string {
   const home = homedir();
   switch (shell) {
     case "zsh":
-      return join(home, ".zfunc", "_pragma");
+      return join(home, ".zfunc", `_${BIN_NAME}`);
     case "bash":
       return join(
         home,
@@ -50,10 +76,10 @@ export function completionScriptPath(shell: ShellId): string {
         "share",
         "bash-completion",
         "completions",
-        "pragma",
+        BIN_NAME,
       );
     case "fish":
-      return join(home, ".config", "fish", "completions", "pragma.fish");
+      return join(home, ".config", "fish", "completions", `${BIN_NAME}.fish`);
   }
 }
 

package/src/capabilities/skill/discover.ts

@@ -13,6 +13,7 @@
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join } from "node:path";
+import { BIN_NAME } from "../../constants.js";
 
 /** Parsed SKILL.md frontmatter. */
 export interface SkillFrontmatter {
@@ -103,26 +104,31 @@ export function parseFrontmatter(content: string): SkillFrontmatter | null {
 }
 
 /**
- * The installed-skills root: `$XDG_DATA_HOME/pragma/skills`. This is where
+ * The installed-skills root: `$XDG_DATA_HOME/<bin>/skills`. This is where
  * `sources update` INSTALLS package-provided skills (U10) — a symlink per skill
  * — and the second discovery root below reads them back. The single source of
  * truth for both, so the install target and the discovery root can never drift.
+ *
+ * Namespaced by {@link BIN_NAME}, like config, state and cache: two
+ * distributions installed side by side owned ONE skills root, so a `recipes`
+ * build served skills a `pragma` build had installed and could not install its
+ * own without colliding.
  */
 export function installedSkillsDir(): string {
   const dataHome =
     process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share");
-  return join(dataHome, "pragma", "skills");
+  return join(dataHome, BIN_NAME, "skills");
 }
 
 /**
  * The conventional roots skills are discovered from, in PRECEDENCE order: the
- * project root (`<cwd>/.pragma/skills`) FIRST so a project-local skill overrides
+ * project root (`<cwd>/.<bin>/skills`) FIRST so a project-local skill overrides
  * an installed skill of the same name (`discoverSkills` dedups first-seen-wins),
- * then installed skills under `$XDG_DATA_HOME/pragma/skills` (where package
+ * then installed skills under `$XDG_DATA_HOME/<bin>/skills` (where package
  * skills land on `sources update`).
  */
 export function skillRoots(cwd: string): string[] {
-  return [join(cwd, ".pragma", "skills"), installedSkillsDir()];
+  return [join(cwd, `.${BIN_NAME}`, "skills"), installedSkillsDir()];
 }
 
 /** Immediate subdirectories of `root` (each a candidate skill folder). */