@canonical/pragma-cli 0.33.0 → 0.34.0

package/src/capabilities/doctor/checks/checkPackageRefs.ts

@@ -1,73 +1,107 @@
 /**
- * Doctor check: report how each configured semantic package resolves.
+ * Doctor check: report which pack answers this project's reads.
  *
- * ADAPTED for v2: the old local>git>bundled loader chain is retired — resolution
- * now flows through `sources update` into `pragma.lock.json` + the cached pack.
- * This check reads the lock (which packages resolved) and the storeless pack
- * index (the entity total), never booting the store. An absent lock with
- * configured packages is the "run `sources update`" case.
+ * It switches on the ONE boot decision ({@link resolveSources}) rather than
+ * re-deriving it from config, so doctor can never call an install healthy that
+ * every read would fail. That is the whole point of the check: a project that
+ * configured its own packs and never built them reports `fail` with the update
+ * remedy — not a pass listing the distribution's packs it is not reading.
+ * Storeless throughout: the pointer, the manifest, and the entity index are
+ * read off disk, never through a store session.
+ *
+ * It also names every read story that pack carries but cannot use. Those are
+ * DROPPED at dispatch rather than thrown (a third-party story must never break
+ * a command), so doctor is where the user finds out — and it goes through the
+ * same `validateStories` the dispatch path uses, so the two can never disagree.
  */
 
+import { BIN_NAME } from "../../../constants.js";
 import {
   entityTotal,
   readPackIndex,
 } from "../../../kernel/completion/entitySource.js";
-import type { PackageEntry } from "../../../kernel/config/types.js";
-import { readLock } from "../../../kernel/runtime/lock.js";
+import { validateStories } from "../../../kernel/packs/collect.js";
+import { embeddedManifest } from "../../../kernel/runtime/graphpack/embedded.js";
+import { readManifest } from "../../../kernel/runtime/graphpack/manifest.js";
+import { activeStories } from "../../../kernel/runtime/graphpack/stories.js";
+import type { SourcesDecision } from "../../../kernel/runtime/resolveSources.js";
+import { resolveSources } from "../../../kernel/runtime/resolveSources.js";
 import type { PragmaRuntime } from "../../../kernel/runtime/types.js";
 import type { CheckItem, CheckResult } from "../types.js";
 
-const entryName = (entry: PackageEntry): string =>
-  typeof entry === "string" ? entry : entry.name;
+/**
+ * The stories the answering pack carries but cannot use, as check items.
+ *
+ * The registry is reached through a RUNTIME dynamic import (as
+ * `collectColophon` does) so the static `capabilities/index → doctorModule →
+ * checkPackageRefs → capabilities/index` cycle can never form.
+ *
+ * @param decision - The boot decision the check already resolved.
+ * @returns One failing item per ignored story, in declaration order.
+ * @note Impure — reads the answering pack's `stories.json`.
+ */
+async function ignoredStoryItems(
+  decision: SourcesDecision,
+): Promise<CheckItem[]> {
+  const { capabilities } = await import("../../index.js");
+  const { problems } = validateStories(activeStories(decision), capabilities);
+  return problems.map((problem) => ({
+    label: problem.source,
+    detail: problem.message,
+    status: "fail" as const,
+  }));
+}
+
+/** ` · N story/ies ignored` for a headline, or nothing when all are usable. */
+function ignoredSuffix(items: readonly CheckItem[]): string {
+  if (items.length === 0) return "";
+  return ` · ${items.length} ${items.length === 1 ? "story" : "stories"} ignored`;
+}
 
 /**
- * Report package resolution status against the lock and the entity total.
+ * Report which pack answers reads, its provenance, and its entity total.
  *
  * @param rt - The per-invocation runtime.
- * @returns A CheckResult with a per-package breakdown.
- * @note Impure — reads config, the lock, and the pack index from disk.
+ * @returns A CheckResult naming the answering pack, or the failure to build one.
+ * @note Impure — reads config, the active-pack pointer, and the pack index.
  */
 export async function checkPackageRefs(
   rt: PragmaRuntime,
 ): Promise<CheckResult> {
-  const entries = (await rt.loadConfig()).config.packages ?? [];
-  const lock = readLock(rt.cwd);
-  const index = readPackIndex(rt.cwd);
-  const totalEntities = index ? entityTotal(index) : 0;
+  const decision = resolveSources(await rt.loadConfig(), rt.cwd);
+  // The display says "packs" (config declarations); the file/function keep
+  // "Package" (npm/git resolution vocabulary).
+  const name = "pack refs";
 
-  if (entries.length === 0) {
+  if (decision.kind === "unavailable") {
     return {
-      name: "package refs",
-      status: "pass",
-      detail: `no packages configured — the embedded pack answers reads (${totalEntities.toLocaleString()} entities)`,
+      name,
+      status: "fail",
+      detail: decision.reason,
+      remedy: `${BIN_NAME} sources update`,
     };
   }
 
-  const items: CheckItem[] = [];
-  let unresolved = 0;
-  for (const entry of entries) {
-    const name = entryName(entry);
-    const packEntry = lock?.packs.find((pack) => pack.name === name);
-    if (packEntry) {
-      items.push({
-        label: name,
-        status: "pass",
-        detail: `resolved ${packEntry.resolved}`,
-      });
-    } else {
-      items.push({ label: name, status: "fail", detail: "not in the lock" });
-      unresolved += 1;
-    }
+  const index = readPackIndex(decision);
+  const entities = (index ? entityTotal(index) : 0).toLocaleString();
+  // The pack DOES answer reads, so the check itself passes; the ignored stories
+  // are failing sub-items under it. (A `warn` status would ripple through the
+  // renderer and the DoctorData counts to buy an icon.)
+  const items = await ignoredStoryItems(decision);
+  const suffix = ignoredSuffix(items);
+  if (decision.kind === "embedded") {
+    return {
+      name,
+      status: "pass",
+      detail: `embedded snapshot @ ${embeddedManifest().sourceRef} — ${entities} entities${suffix} · \`${BIN_NAME} sources update\` to build from the configured packs`,
+      ...(items.length > 0 ? { items } : {}),
+    };
   }
-
-  const ok = lock !== undefined && unresolved === 0;
+  const manifest = readManifest(decision.dir);
   return {
-    name: "package refs",
-    status: ok ? "pass" : "fail",
-    detail: ok
-      ? `${entries.length} package(s) resolved · ${totalEntities.toLocaleString()} entities`
-      : `${unresolved} of ${entries.length} package(s) not resolved`,
-    items,
-    ...(ok ? {} : { remedy: "pragma sources update" }),
+    name,
+    status: "pass",
+    detail: `${manifest?.sourceRef ?? decision.contentHash.slice(0, 12)} — ${entities} entities, built ${manifest?.createdAt ?? "?"}${suffix}`,
+    ...(items.length > 0 ? { items } : {}),
   };
 }

package/src/capabilities/doctor/checks/checkPragmaVersion.ts

@@ -1,9 +1,10 @@
+import { BIN_NAME } from "../../../constants.js";
 import type { PragmaRuntime } from "../../../kernel/runtime/types.js";
 import { detectInstallSource } from "../../shared/packageManager.js";
 import type { CheckResult } from "../types.js";
 
 /**
- * Report the pragma version and how it was installed. Always passes — purely
+ * Report the CLI version and how it was installed. Always passes — purely
  * informational.
  *
  * @param rt - The per-invocation runtime (for `version`).
@@ -15,7 +16,7 @@ export async function checkPragmaVersion(
 ): Promise<CheckResult> {
   const install = detectInstallSource();
   return {
-    name: "pragma version",
+    name: `${BIN_NAME} version`,
     status: "pass",
     detail: `v${rt.version} (installed via ${install.label})`,
   };

package/src/capabilities/doctor/checks/checkShellCompletions.test.ts

@@ -1,19 +1,28 @@
 /**
  * `checkShellCompletions` — the doctor check that verifies completions are
- * installed AND functional.
+ * installed AND up to date AND functional.
  *
  * Runs against an isolated HOME and a controlled `$SHELL` so the three gates —
- * the resolver effect test, the real install-path probe, and the zsh fpath
- * activation gate — are deterministic. The effect test (gate 1) drives the real
+ * the resolver effect test, the install probe, and the zsh fpath activation
+ * gate — are deterministic. The effect test (gate 1) drives the real
  * `runComplete` resolver; the install/fpath gates write real files under the
  * temp HOME rather than mocking the fs.
+ *
+ * Gate 2 compares BYTES, not existence, so the "installed" cases here write the
+ * real `emitScripts(capabilities)[shell]` body. A file that merely exists is
+ * now the failing case, and it has its own test — as does the boundary on the
+ * other side, where a per-project `completion` config must NOT be able to
+ * condemn the one global script.
  */
 
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { completionScriptPath } from "../../setup/shell.js";
+import { emitScripts } from "../../../kernel/completion/emitScripts.js";
+import { capabilities } from "../../index.js";
+import { detectCompletions } from "../../setup/operations/setupCompletions.js";
+import { completionScriptPath, type ShellId } from "../../setup/shell.js";
 import { checkShellCompletions } from "./checkShellCompletions.js";
 
 const roots: string[] = [];
@@ -38,11 +47,16 @@ afterEach(() => {
   roots.length = 0;
 });
 
-/** Write the (empty) completion script to the shell's real install path. */
-function installScript(shell: "zsh" | "bash" | "fish"): void {
+/** Write `body` to the shell's real install path. */
+function writeScript(shell: ShellId, body: string): void {
   const path = completionScriptPath(shell);
   mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, "# stub\n");
+  writeFileSync(path, body);
+}
+
+/** Install the script `setup completions` would write for this shell. */
+function installScript(shell: ShellId): void {
+  writeScript(shell, emitScripts(capabilities)[shell]);
 }
 
 /** Write a `.zshrc` that puts ~/.zfunc on fpath. */
@@ -73,20 +87,56 @@ describe("checkShellCompletions — install probe (gate 2)", () => {
     expect(result.remedy).toBe("pragma setup completions");
   });
 
-  it("passes for bash once the script exists at its real path", async () => {
+  it("passes for bash once the up-to-date script is at its real path", async () => {
     process.env.SHELL = "/usr/bin/bash";
     installScript("bash");
     const result = await checkShellCompletions(tmp());
     expect(result.status).toBe("pass");
-    expect(result.detail).toMatch(/bash installed and resolving/);
+    expect(result.detail).toMatch(/bash up to date and resolving/);
   });
 
-  it("passes for fish once the script exists at its real path", async () => {
+  it("passes for fish once the up-to-date script is at its real path", async () => {
     process.env.SHELL = "/usr/bin/fish";
     installScript("fish");
     const result = await checkShellCompletions(tmp());
     expect(result.status).toBe("pass");
   });
+
+  it("fails when the installed script is out of date", async () => {
+    // Reproduced against the compiled binary before this was fixed: overwrite
+    // the installed script with junk and `doctor` still reported
+    // "✓ Shell completions: bash installed and resolving (19 nouns)", while
+    // `setup completions` in the same breath said "Updating bash completions".
+    // Every user upgrading across a grammar change lands here: the old script
+    // offers the old nouns and misses the new ones, and doctor is the one
+    // command whose job is to say so.
+    process.env.SHELL = "/usr/bin/bash";
+    writeScript("bash", "# STALE JUNK\n");
+    const result = await checkShellCompletions(tmp());
+    expect(result.status).toBe("fail");
+    expect(result.detail).toMatch(/out of date/);
+    expect(result.remedy).toBe("pragma setup completions");
+  });
+
+  it("does NOT condemn the global script for one project's `completion` config", async () => {
+    // The script is ONE file per user; `completion` config is layered per
+    // project. Comparing the global file against only THIS directory's body
+    // made `doctor`'s verdict flip with `cd`: reproduced against the real
+    // check, a project declaring `minChars: 5` passed in its own directory and
+    // failed in every other, and running the offered remedy there moved the
+    // failure back rather than closing it. The first assertion is the
+    // discriminator — this project really does ask for a different body — so
+    // deleting the config write below turns the test red.
+    process.env.SHELL = "/usr/bin/bash";
+    installScript("bash");
+    const cwd = tmp();
+    writeFileSync(
+      join(cwd, "pragma.config.ts"),
+      "export default { completion: { minChars: 5 } };\n",
+    );
+    expect((await detectCompletions(cwd)).state).toBe("stale");
+    expect((await checkShellCompletions(cwd)).status).toBe("pass");
+  });
 });
 
 describe("checkShellCompletions — zsh fpath activation (gate 3)", () => {
@@ -106,6 +156,6 @@ describe("checkShellCompletions — zsh fpath activation (gate 3)", () => {
     wireZfunc();
     const result = await checkShellCompletions(tmp());
     expect(result.status).toBe("pass");
-    expect(result.detail).toMatch(/zsh installed and resolving/);
+    expect(result.detail).toMatch(/zsh up to date and resolving/);
   });
 });

package/src/capabilities/doctor/checks/checkShellCompletions.ts

@@ -1,20 +1,48 @@
-import { existsSync, readFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { BIN_NAME } from "../../../constants.js";
 import {
+  emitScripts,
   indexCompletionEnv,
   runComplete,
 } from "../../../kernel/completion/index.js";
 import { capabilities } from "../../index.js";
-import {
-  activationHint,
-  completionScriptPath,
-  detectShell,
-} from "../../setup/shell.js";
+import { detectCompletions } from "../../setup/operations/setupCompletions.js";
+import { activationHint, type ShellId } from "../../setup/shell.js";
 import type { CheckResult } from "../types.js";
 
 const NAME = "Shell completions";
 
+/** The one remedy for an absent or out-of-date script. */
+const INSTALL_REMEDY = `${BIN_NAME} setup completions`;
+
+/**
+ * Whether the installed script is the config-free emit — the body
+ * `setup completions` writes when no `completion` config tunes it.
+ *
+ * The completion script is ONE file per user, but the `completion` config it is
+ * rendered from is layered per project. So `detectCompletions(cwd)`'s `stale`
+ * means only "not what THIS directory would write", and on its own it would let
+ * any project that tunes `minChars` call a globally-correct script out of date
+ * from every other directory — a `doctor` verdict that flips with `cd`, and a
+ * remedy that just moves the failure to the project you came from. A script
+ * that matches neither this project's body nor the untuned one is the one that
+ * is genuinely stale.
+ *
+ * @param path - The install path.
+ * @param shell - The detected shell.
+ * @returns Whether the file there is byte-identical to the untuned emit.
+ * @note Impure — reads the install path. An unreadable file counts as `false`.
+ */
+function isUntunedScript(path: string, shell: ShellId): boolean {
+  try {
+    return readFileSync(path, "utf-8") === emitScripts(capabilities)[shell];
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Whether the user's `.zshrc` puts `~/.zfunc` on `$fpath` — the activation step
  * `setup completions` cannot perform for the user. zsh loads nothing from
@@ -53,23 +81,28 @@ async function completeProbe(cwd: string): Promise<number> {
 }
 
 /**
- * Check that shell completions are installed AND functional.
+ * Check that shell completions are installed AND up to date AND functional.
  *
  * Three gates, in order:
  * 1. The resolver answers (`completeProbe` drives `runComplete` end to end) —
  *    the effect every installed script depends on. A failure here is a real
  *    regression, so it fails even when nothing is installed.
- * 2. The script file exists at the shell's real install path (`shell.ts`) —
- *    NOT a `"pragma"` substring in an RC file, which `setup completions` never
- *    writes.
+ * 2. The installed script is present AND is a script `setup completions` would
+ *    write. Bytes, not existence: a file that merely exists proves nothing — a
+ *    user upgrading across a grammar change keeps the old script, loses the
+ *    moved nouns from TAB, and used to be told everything was fine. The path
+ *    and this project's body come from `detectCompletions`, the ONE owner of
+ *    that decision; {@link isUntunedScript} is what keeps a per-project
+ *    `completion` config from condemning a global file (see its docblock).
  * 3. For zsh, `~/.zfunc` is on `$fpath` — the activation step setup can only
  *    hint. Installed-but-unwired reports a distinct remedy.
  *
- * @param cwd - The project directory (for the resolver's entity seam).
- * @returns A CheckResult: pass (installed + wired + answering), fail (with the
+ * @param cwd - The project directory (the resolver's entity seam, and the
+ *   `completion` config gate 2 renders this project's body from).
+ * @returns A CheckResult: pass (up to date + wired + answering), fail (with the
  *   attributable remedy), or skip (shell undetected).
- * @note Impure — reads `$SHELL`, the install path, `.zshrc`, and drives the
- *   storeless resolver.
+ * @note Impure — reads `$SHELL`, the install path, the config layers, `.zshrc`,
+ *   and drives the storeless resolver.
  */
 export async function checkShellCompletions(cwd: string): Promise<CheckResult> {
   // 1. Effect test: the resolver the scripts delegate to must actually answer.
@@ -82,34 +115,41 @@ export async function checkShellCompletions(cwd: string): Promise<CheckResult> {
       name: NAME,
       status: "fail",
       detail: `completion resolver failed: ${reason}`,
-      remedy: "Report this as a bug — `pragma __complete` should never throw.",
+      remedy: `Report this as a bug — \`${BIN_NAME} __complete\` should never throw.`,
     };
   }
   if (candidates === 0) {
     return {
       name: NAME,
       status: "fail",
-      detail: "completion resolver returned no candidates for `pragma <TAB>`",
+      detail: `completion resolver returned no candidates for \`${BIN_NAME} <TAB>\``,
       remedy: "Report this as a bug — the noun context is always non-empty.",
     };
   }
 
-  // 2. The script file exists at the shell's real install path.
-  const shell = detectShell();
-  if (!shell) {
+  // 2. The installed script is a script `setup completions` would write.
+  const { shell, path, state } = await detectCompletions(cwd);
+  if (shell === null || path === null) {
     return {
       name: NAME,
       status: "skip",
       detail: "resolver OK; shell not detected ($SHELL unset)",
     };
   }
-  const path = completionScriptPath(shell);
-  if (!existsSync(path)) {
+  if (state === "absent") {
     return {
       name: NAME,
       status: "fail",
       detail: `resolver OK; ${shell} script not installed`,
-      remedy: "pragma setup completions",
+      remedy: INSTALL_REMEDY,
+    };
+  }
+  if (state === "stale" && !isUntunedScript(path, shell)) {
+    return {
+      name: NAME,
+      status: "fail",
+      detail: `resolver OK; ${shell} script at ${path} is out of date`,
+      remedy: INSTALL_REMEDY,
     };
   }
 
@@ -126,6 +166,6 @@ export async function checkShellCompletions(cwd: string): Promise<CheckResult> {
   return {
     name: NAME,
     status: "pass",
-    detail: `${shell} installed and resolving (${candidates} nouns)`,
+    detail: `${shell} up to date and resolving (${candidates} nouns)`,
   };
 }

package/src/capabilities/doctor/checks/checkSkillsSymlinked.ts

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import type { DetectedHarness } from "@canonical/harnesses";
 import { detectHarnesses } from "@canonical/harnesses";
 import { runTask } from "@canonical/task/node";
+import { BIN_NAME } from "../../../constants.js";
 import type { CheckResult } from "../types.js";
 
 /**
@@ -21,7 +22,7 @@ export async function checkSkillsSymlinked(cwd: string): Promise<CheckResult> {
       name: "Skills symlinked",
       status: "fail",
       detail: "harness detection failed",
-      remedy: "pragma setup skills",
+      remedy: `${BIN_NAME} setup skills`,
     };
   }
 
@@ -55,6 +56,6 @@ export async function checkSkillsSymlinked(cwd: string): Promise<CheckResult> {
     name: "Skills symlinked",
     status: "fail",
     detail: `missing for ${missing.join(", ")}`,
-    remedy: "pragma setup skills",
+    remedy: `${BIN_NAME} setup skills`,
   };
 }

package/src/capabilities/doctor/doctor.render.test.ts

@@ -24,7 +24,7 @@ const BANDED_DATA: DoctorData = {
     {
       name: "Shell completions",
       status: "pass",
-      detail: "zsh installed and resolving",
+      detail: "zsh up to date and resolving",
       band: "global",
     },
     {
@@ -51,12 +51,12 @@ const COLOR_DATA: DoctorData = {
   checks: [
     { name: "Node version", status: "pass", detail: "v24" },
     {
-      name: "package refs",
+      name: "pack refs",
       status: "fail",
-      detail: "3 configured, 0 locked",
+      detail: "packs are configured but the store has not been built",
       items: [
-        { label: "core", status: "fail", detail: "unlocked" },
-        { label: "ui", status: "fail", detail: "unlocked" },
+        { label: "core", status: "fail", detail: "not built" },
+        { label: "ui", status: "fail", detail: "not built" },
       ],
       remedy: "pragma sources update",
     },
@@ -151,7 +151,7 @@ describe("doctor render — piped output is ANSI-free (F1)", () => {
       // The structural, color-free content still renders (glyphs, names, remedy).
       expect(out).toContain("pragma doctor");
       expect(out).toContain("✓  Node version");
-      expect(out).toContain("✗  package refs");
+      expect(out).toContain("✗  pack refs");
       expect(out).toContain("○  Skills symlinked");
       expect(out).toContain("↳ fix: pragma sources update");
       expect(out).toContain("  1 passed · 1 failed · 1 skipped");

package/src/capabilities/doctor/doctor.render.ts

@@ -11,6 +11,7 @@
  */
 
 import chalk from "chalk";
+import { BIN_NAME } from "../../constants.js";
 import { defaultStyle, type RenderStyle } from "../../kernel/render/style.js";
 import type { Formatters } from "../../kernel/spec/types.js";
 import { BAND_LABELS } from "../shared/bands.js";
@@ -134,7 +135,7 @@ export const doctorFormatters: Formatters<DoctorData> = {
   plain(data) {
     const style = doctorStyle();
     const nameWidth = Math.max(...data.checks.map((c) => c.name.length), 0);
-    const lines: string[] = [style.bold("pragma doctor"), ""];
+    const lines: string[] = [style.bold(`${BIN_NAME} doctor`), ""];
     const { environment, machine, project } = partitionByBand(data.checks);
     const section = (heading: string, checks: CheckResult[]): void => {
       if (checks.length === 0) return;

package/src/capabilities/doctor/doctor.test.ts

@@ -79,10 +79,9 @@ const defaultLayers: ConfigLayers = {
     tier: "default",
     channel: "default",
     detail: "default",
-    packages: "default",
+    packs: "default",
     stories: "default",
     prefixes: "default",
-    prompts: "default",
   },
   global: { path: "", exists: false },
   project: { exists: false },
@@ -122,12 +121,12 @@ describe("doctor — shape & spread", () => {
     }
     // Deterministic under the isolated env.
     expect(byName(data, "Node version")?.status).toBe("pass");
-    // The 3 default-config packages are configured but not locked here → an
-    // attributable fail listing them, with the sources-update remedy.
-    const pkgRefs = byName(data, "package refs");
-    expect(pkgRefs?.status).toBe("fail");
-    expect(pkgRefs?.remedy).toBe("pragma sources update");
-    expect(pkgRefs?.items?.length).toBe(3);
+    // Nothing built, but the packs are the distribution's own — so the embedded
+    // snapshot answers reads and the check passes, naming what it is reading.
+    const pkgRefs = byName(data, "pack refs");
+    expect(pkgRefs?.status).toBe("pass");
+    expect(pkgRefs?.detail).toContain("embedded snapshot @ ");
+    expect(pkgRefs?.remedy).toBeUndefined();
     // No harnesses in an empty HOME/cwd — attributable fail + skips.
     expect(byName(data, "MCP configured")?.status).toBe("fail");
     expect(byName(data, "Skills symlinked")?.status).toBe("skip");
@@ -137,6 +136,36 @@ describe("doctor — shape & spread", () => {
   });
 });
 
+describe("doctor — the pack-refs check", () => {
+  it("a project with its OWN packs and nothing built is an attributable fail", async () => {
+    // The install that must never read healthy: `origins.packs` is "project",
+    // so the embedded snapshot is a DIFFERENT graph and every read throws
+    // STORE_UNAVAILABLE. Doctor has to say so and name the fix, rather than
+    // pass by listing packs it is not actually reading from.
+    const cwd = tmp("pragma-unbuilt-");
+    writeFileSync(
+      join(cwd, "pragma.config.ts"),
+      'export default { packs: [{ name: "unbuilt", source: "file:///pragma-never-built" }] };\n',
+    );
+    const data = await runChecks(bootRuntime(FLAGS, cwd));
+    const pkgRefs = byName(data, "pack refs");
+    expect(pkgRefs?.status).toBe("fail");
+    expect(pkgRefs?.detail).toContain("the store has not been built");
+    expect(pkgRefs?.remedy).toBe("pragma sources update");
+  });
+
+  it("a project pointed at its own built pack passes, naming that pack", async () => {
+    const fixture = await bootFixtureRuntime({ ttl: CANONICAL_TTL });
+    const data = await runChecks(fixture.runtime);
+    const pkgRefs = byName(data, "pack refs");
+    expect(pkgRefs?.status).toBe("pass");
+    // The fixture pack's own provenance label, not the embedded snapshot's.
+    expect(pkgRefs?.detail).toContain("fixture");
+    expect(pkgRefs?.detail).not.toContain("embedded snapshot");
+    await fixture.dispose();
+  });
+});
+
 describe("doctor — the store check", () => {
   it("a store that fails to boot is an attributable fail, not a crash", async () => {
     const data = await runChecks(throwingStoreRuntime(tmp("pragma-proj-")));

package/src/capabilities/doctor/doctor.verb.ts

@@ -12,6 +12,7 @@
  * `doctor-exit-zero-with-failures`.
  */
 
+import { BIN_NAME } from "../../constants.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
 import type { CapabilityModule, VerbSpec } from "../../kernel/spec/types.js";
 import { doctorFormatters } from "./doctor.render.js";
@@ -24,8 +25,11 @@ const doctorVerb: VerbSpec<Record<string, unknown>, DoctorData> = {
   params: [],
   output: { formatters: doctorFormatters },
   examples: [
-    { cmd: "pragma doctor" },
-    { cmd: "pragma doctor --format json", note: "machine-readable checks" },
+    { cmd: `${BIN_NAME} doctor` },
+    {
+      cmd: `${BIN_NAME} doctor --format json`,
+      note: "machine-readable checks",
+    },
   ],
   capability: {
     needsStore: false,

package/src/capabilities/doctor/runChecks.ts

@@ -8,6 +8,7 @@
  * neither the checks nor `@canonical/harnesses` land on the fast path.
  */
 
+import { BIN_NAME } from "../../constants.js";
 import type { PragmaRuntime } from "../../kernel/runtime/types.js";
 import { checkConfigFile } from "./checks/checkConfigFile.js";
 import { checkKeStore } from "./checks/checkKeStore.js";
@@ -55,9 +56,9 @@ function buildChecks(
 ): readonly [string, Promise<CheckResult>][] {
   return [
     ["Node version", checkNodeVersion()],
-    ["pragma version", checkPragmaVersion(rt)],
-    ["pragma config", checkConfigFile(rt)],
-    ["package refs", checkPackageRefs(rt)],
+    [`${BIN_NAME} version`, checkPragmaVersion(rt)],
+    [`${BIN_NAME} config`, checkConfigFile(rt)],
+    ["pack refs", checkPackageRefs(rt)],
     ["ke store", checkKeStore(rt)],
     ["Shell completions", checkShellCompletions(rt.cwd)],
     ["MCP configured", checkMcpConfigured(rt.cwd)],
@@ -84,8 +85,7 @@ export async function runChecks(rt: PragmaRuntime): Promise<DoctorData> {
           name,
           status: "fail",
           detail: `Check threw an unexpected error: ${reason}`,
-          remedy:
-            "Re-run `pragma doctor`; if it persists, report this as a bug.",
+          remedy: `Re-run \`${BIN_NAME} doctor\`; if it persists, report this as a bug.`,
         });
       }
     }),