@canonical/pragma-cli 0.33.0 → 0.35.0

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

@@ -1,14 +1,20 @@
 /**
- * `pragma doctor` — the nine environment health checks.
+ * `pragma doctor` — the environment checks plus the banded target rows.
  *
  * Runs against isolated HOME/cwd/XDG so the harness/config/completion checks are
  * deterministic (no harnesses, no config, no rc files). Covers the shape, a
- * representative pass/fail/skip spread, the store check (down via an injected
- * throwing store; up via the canonical fixture), exit 0 despite failures, and
- * the MCP read-only envelope.
+ * representative pass/fail/available/skip spread, the store check (down via an
+ * injected throwing store; up via the canonical fixture), exit 0 despite
+ * failures, and the MCP read-only envelope.
  */
 
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import {
+  chmodSync,
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
@@ -28,7 +34,7 @@ import {
 } from "../../testing/fixtures/graph/canonical.js";
 import { bootFixtureRuntime } from "../../testing/helpers/fixtureGraph.js";
 import { projectMcp } from "../../testing/helpers/projectMcp.js";
-import { checkMcpConfigured } from "./checks/checkMcpConfigured.js";
+import { bandedChecks } from "./checks/targetHealth.js";
 import { doctorModule } from "./index.js";
 import { runChecks } from "./runChecks.js";
 import type { DoctorData } from "./types.js";
@@ -79,10 +85,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 },
@@ -113,37 +118,92 @@ const byName = (data: DoctorData, name: string) =>
   data.checks.find((c) => c.name === name);
 
 describe("doctor — shape & spread", () => {
-  it("returns 9 checks whose tallies sum, each with a valid status", async () => {
+  it("returns the environment checks plus one row per banded target", async () => {
     const data = await runChecks(bootRuntime(FLAGS, tmp("pragma-proj-")));
-    expect(data.checks).toHaveLength(9);
-    expect(data.passed + data.failed + data.skipped).toBe(9);
+    // Four unbanded environment checks, then the target table in both bands:
+    // all five targets are global, mcp and skills are also project.
+    expect(data.checks).toHaveLength(11);
+    expect(data.passed + data.failed + data.available + data.skipped).toBe(11);
     for (const check of data.checks) {
-      expect(["pass", "fail", "skip"]).toContain(check.status);
+      expect(["pass", "fail", "available", "skip"]).toContain(check.status);
     }
     // 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");
+    // 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();
+
+    // The banded rows carry the TARGET IDS verbatim — `mcp`, not "MCP
+    // configured" — because the row name IS the fix command's argument. The
+    // environment checks stay unbanded.
+    const banded = data.checks.filter((c) => c.band !== undefined);
+    expect(banded.map((c) => `${c.band}:${c.name}`)).toEqual([
+      "global:config",
+      "global:completions",
+      "global:lsp",
+      "global:mcp",
+      "global:skills",
+      "project:mcp",
+      "project:skills",
+    ]);
+    // Every row that wants action names the exact command that repairs it,
+    // band included — the bijection, derived rather than authored.
+    for (const check of banded) {
+      if (check.status === "fail" || check.status === "available") {
+        expect(check.remedy).toBeDefined();
+      }
+    }
+    // No harnesses in an empty HOME/cwd, so both mcp rows skip; the project
+    // band is opt-in, so its absence is never a fault.
+    expect(
+      banded.find((c) => c.band === "project" && c.name === "mcp")?.status,
+    ).toBe("skip");
+    // No global config in the isolated XDG — an opt-in that is not set up yet.
+    expect(byName(data, "config")?.status).toBe("available");
+    expect(byName(data, "config")?.remedy).toBe("pragma setup config");
+  });
+});
+
+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");
-    expect(pkgRefs?.items?.length).toBe(3);
-    // 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");
-    expect(byName(data, "MCP commands")?.status).toBe("skip");
-    // No project/global config in the isolated XDG.
-    expect(byName(data, "pragma config")?.status).toBe("fail");
+  });
+
+  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-")));
-    expect(data.checks).toHaveLength(9);
-    const keStore = byName(data, "ke store");
-    expect(keStore?.status).toBe("fail");
-    expect(keStore?.remedy).toBeTruthy();
+    expect(data.checks).toHaveLength(11);
+    const store = byName(data, "store");
+    expect(store?.status).toBe("fail");
+    expect(store?.remedy).toBeTruthy();
   });
 
   it("a booted store passes with an entity total", async () => {
@@ -152,9 +212,9 @@ describe("doctor — the store check", () => {
       config: ALL_VISIBLE_CONFIG,
     });
     const data = await runChecks(fixture.runtime);
-    const keStore = byName(data, "ke store");
-    expect(keStore?.status).toBe("pass");
-    expect(keStore?.detail).toMatch(/entities/);
+    const store = byName(data, "store");
+    expect(store?.status).toBe("pass");
+    expect(store?.detail).toMatch(/entities/);
     await fixture.dispose();
   });
 });
@@ -182,28 +242,86 @@ describe("doctor — dispatch & MCP", () => {
     const envelope = await mcp.callTool("doctor");
     await mcp.cleanup();
     expect(envelope.ok).toBe(true);
-    expect((envelope.data as DoctorData).checks).toHaveLength(9);
+    expect((envelope.data as DoctorData).checks).toHaveLength(11);
   });
 });
 
-describe("doctor — MCP checks band by detected harness scope, not check name", () => {
-  it("bands a configured GLOBAL-scope harness (Windsurf) as global", async () => {
-    // Windsurf is a global-only harness whose MCP config lives in the home band.
-    // The old static map tagged every "MCP configured" result PROJECT; the fix
-    // derives the band from the harness's real scope, so this reports `global`.
+describe("doctor — the banded rows can see the GLOBAL band", () => {
+  it("reports a configured global-band entry as configured, not missing", async () => {
+    // The regression this closes: detection recorded only each harness's
+    // DEFAULT band, so a server registered by `setup mcp --global` was invisible
+    // and doctor reported it not-configured forever. The rows now come from the
+    // same target table `setup` writes through, enumerated in BOTH bands, so the
+    // two surfaces cannot disagree about what they looked at.
     const cwd = tmp("pragma-doctor-proj-");
     mkdirSync(join(cwd, ".windsurf"), { recursive: true }); // ⇒ Windsurf detected
     const home = process.env.HOME ?? "";
     const wsDir = join(home, ".codeium", "windsurf");
     mkdirSync(wsDir, { recursive: true });
+    // Exactly what a global-band `setup mcp` writes: no `cwd`, so the entry is
+    // not pinned to whatever directory the registration ran from.
     writeFileSync(
       join(wsDir, "mcp_config.json"),
-      JSON.stringify({ mcpServers: { pragma: { command: "pragma" } } }),
+      JSON.stringify({
+        mcpServers: { pragma: { command: "pragma", args: ["mcp", "serve"] } },
+      }),
+    );
+    // The row also verifies the command BOOTS, so put a `pragma` on the
+    // isolated PATH — otherwise the row correctly fails for a second reason.
+    const binDir = process.env.PATH as string;
+    writeFileSync(join(binDir, "pragma"), "#!/bin/sh\nexit 0\n");
+    chmodSync(join(binDir, "pragma"), 0o755);
+
+    const rows = await bandedChecks(bootRuntime(FLAGS, cwd), "pragma");
+    const global = rows.find((r) => r.name === "mcp" && r.band === "global");
+    expect(global?.status).toBe("pass");
+    expect(
+      global?.items?.some((i) => i.label.includes("mcp_config.json")),
+    ).toBe(true);
+    // ...and the project band stays an opt-in skip, never a fault.
+    const project = rows.find((r) => r.name === "mcp" && r.band === "project");
+    expect(project?.status).toBe("skip");
+  });
+});
+
+describe("doctor — a blocked skill link path is never reported as current", () => {
+  it("distinguishes a hand-placed real directory from a link that is correct", async () => {
+    // Detection marks both `skipped` — there is nothing to do to either — so
+    // the row counted the blocked path as healthy and said "links current"
+    // where no link exists at all.
+    const cwd = tmp("pragma-doctor-proj-");
+    const skillDir = join(cwd, ".pragma", "skills", "my-skill");
+    mkdirSync(skillDir, { recursive: true });
+    writeFileSync(
+      join(skillDir, "SKILL.md"),
+      "---\nname: my-skill\ndescription: A test skill.\n---\n",
     );
+    // A hand-placed directory sitting exactly where the link would go.
+    mkdirSync(join(cwd, ".agents", "skills", "my-skill"), { recursive: true });
+
+    const rows = await bandedChecks(bootRuntime(FLAGS, cwd), "pragma");
+    const row = rows.find((r) => r.name === "skills" && r.band === "project");
+    expect(row?.status).not.toBe("pass");
+    expect(row?.detail).toContain("real directory");
+    // And the remedy is the one that settles it — rerunning setup skips it.
+    expect(row?.remedy).toMatch(/Move or delete/);
+  });
+});
+
+describe("doctor — an unconfigured opt-in integration is available, not a fault", () => {
+  it("a detected harness with no MCP entry reports available with the setup command", async () => {
+    // Windsurf is detected (project signal) but nothing is configured. A fresh
+    // install lands exactly here, and a fresh install is healthy — so this is
+    // the `available` tier, keeping its actionable setup command, and it must
+    // never inflate the failure count.
+    const cwd = tmp("pragma-doctor-proj-");
+    mkdirSync(join(cwd, ".windsurf"), { recursive: true }); // ⇒ Windsurf detected
 
-    const check = await checkMcpConfigured(cwd);
-    expect(check.status).toBe("pass");
-    expect(check.detail).toContain("Windsurf");
-    expect(check.band).toBe("global"); // NOT the old static "project"
+    const rows = await bandedChecks(bootRuntime(FLAGS, cwd), "pragma");
+    const check = rows.find((r) => r.name === "mcp" && r.band === "global");
+    expect(check?.status).toBe("available");
+    expect(check?.detail).toContain("not configured");
+    // The fix is the target's own invocation, derived from the row's id + band.
+    expect(check?.remedy).toBe("pragma setup mcp");
   });
 });

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

@@ -12,20 +12,24 @@
  * `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 type { CapabilityModule, VerbSpec } from "../../kernel/spec/index.js";
 import { doctorFormatters } from "./doctor.render.js";
 import type { DoctorData } from "./types.js";
 
 const doctorVerb: VerbSpec<Record<string, unknown>, DoctorData> = {
   path: ["doctor"],
-  summary: "Check environment health — Node, config, store, MCP, and skills.",
-  doc: "Runs nine diagnostic checks and reports pass/fail/skip with inline remedies. Storeless by default; the store check boots lazily and never fails the run.",
+  summary: "Check environment health and every setup target, in both bands.",
+  doc: "Reports the environment checks and then one row per setup target in each band, as pass, fail, available (an opt-in integration not yet set up), or skip, with inline remedies. Every banded row is named after the setup target that repairs it. Storeless by default; the store check boots lazily and never fails the run.",
   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

@@ -1,100 +1,99 @@
 /**
- * The `doctor` run body: orchestrate all environment health checks.
+ * The `doctor` run body: the unbanded environment checks plus the banded rows
+ * the setup target table derives.
+ *
+ * Two kinds of finding live in one report and they are not the same kind. The
+ * ENVIRONMENT checks — the Node version, this CLI's own version, pack refs, the
+ * store — diagnose things `setup` cannot install; they carry no band and stay
+ * their own section. The BANDED rows are exactly the setup targets, in both
+ * bands, named with the target ids verbatim and repaired by the target's own
+ * command. Adding a target adds its rows here for free.
  *
  * Checks are started eagerly (they run concurrently) and collected in
  * declaration order for a deterministic report. Each is guarded so a thrown
- * check becomes an attributable `fail` rather than aborting the whole run — the
- * same discipline the old shell used. Lazily imported by `doctor.verb.ts`, so
- * neither the checks nor `@canonical/harnesses` land on the fast path.
+ * check becomes an attributable `fail` rather than aborting the whole run.
+ * Lazily imported by `doctor.verb.ts`, so neither the checks nor
+ * `@canonical/harnesses` land on the fast path.
  */
 
-import type { PragmaRuntime } from "../../kernel/runtime/types.js";
-import { checkConfigFile } from "./checks/checkConfigFile.js";
+import { BIN_NAME } from "../../constants.js";
+import type { PragmaRuntime } from "../../kernel/runtime/index.js";
 import { checkKeStore } from "./checks/checkKeStore.js";
-import { checkMcpCommands } from "./checks/checkMcpCommands.js";
-import { checkMcpConfigured } from "./checks/checkMcpConfigured.js";
 import { checkNodeVersion } from "./checks/checkNodeVersion.js";
 import { checkPackageRefs } from "./checks/checkPackageRefs.js";
 import { checkPragmaVersion } from "./checks/checkPragmaVersion.js";
-import { checkShellCompletions } from "./checks/checkShellCompletions.js";
-import { checkSkillsSymlinked } from "./checks/checkSkillsSymlinked.js";
-import type { CheckResult, DoctorData, ScopeBand } from "./types.js";
-
-/**
- * The band a check statically concerns, by name — for checks whose band is
- * fixed by construction: skills always symlink into the per-repo project dir
- * (`skillsPath` is project-rooted), and completions install into the user/home
- * shell dir. The MCP checks are NOT here: they detect harnesses across BOTH
- * bands, so each derives its own band from what it found (see `deriveBand`) and
- * sets it on its own result — {@link attachBand} preserves that.
- */
-const CHECK_BANDS: Record<string, ScopeBand> = {
-  "Skills symlinked": "project",
-  "Shell completions": "global",
-};
-
-/**
- * Attach a band tag to a check result. A check that already set its own band
- * (the harness-derived MCP checks) keeps it; otherwise the static
- * {@link CHECK_BANDS} map fills one in by name, if defined.
- */
-function attachBand(result: CheckResult): CheckResult {
-  if (result.band !== undefined) return result;
-  const band = CHECK_BANDS[result.name];
-  return band ? { ...result, band } : result;
-}
+import { bandedChecks } from "./checks/targetHealth.js";
+import type { CheckResult, DoctorData } from "./types.js";
 
 /**
- * Each check paired with the display name used if it rejects. The fallback name
- * matches the `name` each check returns on success, so a thrown check reports
- * the same label and stays correlatable. Declaration order fixes the report
- * order.
+ * The unbanded environment checks, each paired with the display name used if it
+ * rejects. The fallback name matches the `name` each check returns on success,
+ * so a thrown check reports the same label and stays correlatable.
  */
-function buildChecks(
+function buildEnvironmentChecks(
   rt: PragmaRuntime,
 ): readonly [string, Promise<CheckResult>][] {
   return [
     ["Node version", checkNodeVersion()],
-    ["pragma version", checkPragmaVersion(rt)],
-    ["pragma config", checkConfigFile(rt)],
-    ["package refs", checkPackageRefs(rt)],
-    ["ke store", checkKeStore(rt)],
-    ["Shell completions", checkShellCompletions(rt.cwd)],
-    ["MCP configured", checkMcpConfigured(rt.cwd)],
-    ["MCP commands", checkMcpCommands(rt.cwd)],
-    ["Skills symlinked", checkSkillsSymlinked(rt.cwd)],
+    [`${BIN_NAME} version`, checkPragmaVersion(rt)],
+    ["pack refs", checkPackageRefs(rt)],
+    ["store", checkKeStore(rt)],
   ];
 }
 
+/** Turn a rejected check into an attributable failure rather than a crash. */
+async function guarded(
+  name: string,
+  promise: Promise<CheckResult>,
+): Promise<CheckResult> {
+  try {
+    return await promise;
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return {
+      name,
+      status: "fail",
+      detail: `Check threw an unexpected error: ${reason}`,
+      remedy: `Re-run \`${BIN_NAME} doctor\`; if it persists, report this as a bug.`,
+    };
+  }
+}
+
 /**
- * Run every environment health check and aggregate the results.
+ * Run every health check and aggregate the results.
  *
  * @param rt - The per-invocation runtime.
- * @returns The `{ checks, passed, failed, skipped }` summary.
+ * @returns The `{ checks, passed, failed, available, skipped }` summary.
  * @note Impure — the checks read the fs, boot the store, and detect harnesses.
  */
 export async function runChecks(rt: PragmaRuntime): Promise<DoctorData> {
-  const checks: CheckResult[] = await Promise.all(
-    buildChecks(rt).map(async ([name, promise]): Promise<CheckResult> => {
-      try {
-        return attachBand(await promise);
-      } catch (error) {
-        const reason = error instanceof Error ? error.message : String(error);
-        return attachBand({
-          name,
-          status: "fail",
-          detail: `Check threw an unexpected error: ${reason}`,
-          remedy:
-            "Re-run `pragma doctor`; if it persists, report this as a bug.",
-        });
-      }
-    }),
-  );
+  // The banded rows come back as a batch (one detection pass over the table),
+  // so they are guarded as a batch: a detection that throws becomes one
+  // attributable failure instead of taking the environment section with it.
+  const [environmentResults, bandedResults] = await Promise.all([
+    Promise.all(
+      buildEnvironmentChecks(rt).map(([name, promise]) =>
+        guarded(name, promise),
+      ),
+    ),
+    bandedChecks(rt, BIN_NAME).catch((error: unknown): CheckResult[] => [
+      {
+        name: "setup targets",
+        status: "fail",
+        detail: `Detection threw an unexpected error: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+        remedy: `Re-run \`${BIN_NAME} doctor\`; if it persists, report this as a bug.`,
+      },
+    ]),
+  ]);
 
+  const checks: CheckResult[] = [...environmentResults, ...bandedResults];
   return {
     checks,
     passed: checks.filter((c) => c.status === "pass").length,
     failed: checks.filter((c) => c.status === "fail").length,
+    available: checks.filter((c) => c.status === "available").length,
     skipped: checks.filter((c) => c.status === "skip").length,
   };
 }

package/src/capabilities/doctor/types.ts

@@ -9,12 +9,23 @@
  */
 export type ScopeBand = "project" | "global";
 
-/** Status of a doctor check or one of its sub-items. */
-export type CheckStatus = "pass" | "fail" | "skip";
+/**
+ * Status of a doctor check or one of its sub-items.
+ *
+ * `available` is the tier between fail and skip that keeps the report honest:
+ * an opt-in integration (MCP registration, skills symlinks, a completion
+ * script) that is detected and installable but that the user has not set up.
+ * Nothing is broken — a fresh install is HEALTHY with several availables — so
+ * reporting these as `fail` would teach users that the failure count is noise.
+ * `fail` stays reserved for a real fault: something set up that no longer
+ * works, or an environment the CLI cannot run correctly in. `skip` remains
+ * "nothing to check here" (no shell detected, no harnesses present).
+ */
+export type CheckStatus = "pass" | "fail" | "available" | "skip";
 
 /**
  * A structured sub-item under a check — e.g. one resolved package under
- * `package refs`, or one unresolvable server under `MCP commands`. Lets the
+ * `pack refs`, or one unresolvable server under `MCP commands`. Lets the
  * formatter render an indented, aligned breakdown instead of cramming
  * everything into a single `detail` string.
  */
@@ -35,7 +46,10 @@ export interface CheckResult {
   readonly detail: string;
   /** Optional structured breakdown, rendered as indented sub-items. */
   readonly items?: readonly CheckItem[];
-  /** Remedial instruction shown inline under a failing check. */
+  /**
+   * Remedial instruction shown inline under the check: for `fail` the fix,
+   * for `available` the setup command that enables the integration.
+   */
   readonly remedy?: string;
   /**
    * Which config band the check concerns, if any: `global` for the user/home
@@ -47,10 +61,12 @@ export interface CheckResult {
   readonly band?: ScopeBand;
 }
 
-/** Aggregated results from all doctor checks. */
+/** Aggregated results from all doctor checks — one count per status tier. */
 export interface DoctorData {
   readonly checks: readonly CheckResult[];
   readonly passed: number;
   readonly failed: number;
+  /** Opt-in integrations detected but not set up — counted apart from failures. */
+  readonly available: number;
   readonly skipped: number;
 }

package/src/capabilities/emptyRecovery.test.ts

@@ -3,24 +3,34 @@
  *
  * Listing zero rows is a calm SUCCESS, not an error. The run body returns `[]`
  * (no throw), dispatch renders a non-blank message and exits 0, and JSON stays
- * `[]`. A pack's authored `emptyRecovery` becomes that message's HINT — the v2
- * story still points at `pragma sources update` — but as guidance on the
- * success path, never a thrown EMPTY_RESULTS (which maps to exit 1 and would
- * break the uniform `ok:true` list contract).
+ * `[]`. A story's declared `emptyRecovery` becomes that message's HINT — but as
+ * guidance on the success path, never a thrown EMPTY_RESULTS (which maps to
+ * exit 1 and would break the uniform `ok:true` list contract).
+ *
+ * The story declares the command WITHOUT a binary name (`sources update`); the
+ * renderer prepends the CONSUMING distribution's. The hints asserted below are
+ * therefore the JOINED string, which is what a user reads — a story that named
+ * a binary itself would render it twice, and the grammar now refuses one.
  */
 
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { compilePack } from "../kernel/packs/compile.js";
 import type { PackDefinition } from "../kernel/packs/types.js";
+import { distributionSource } from "../kernel/packs/types.js";
 import { verbKey } from "../kernel/packs/uniqueness.js";
 import { executeVerb } from "../kernel/project/cli/dispatch.js";
 import { DEFAULT_PREFIX_MAP } from "../kernel/render/prefixes.js";
 import type { PragmaRuntime } from "../kernel/runtime/types.js";
 import type { VerbSpec } from "../kernel/spec/types.js";
 import { buildFixtureRuntime } from "../testing/helpers/packRuntime.js";
-import { modifierPack } from "./modifier/pack.js";
-import { standardPack } from "./standard/pack.js";
-import { tokenPack } from "./token/pack.js";
+import { declaredStories } from "./distribution.js";
+
+/** A story `pragma.conf.ts` declares — absent means it was renamed or dropped. */
+function storyFor(noun: string): PackDefinition {
+  const story = declaredStories.get(noun);
+  if (!story) throw new Error(`pragma.conf.ts declares no story for "${noun}"`);
+  return story;
+}
 
 const PREFIXES = {
   ds: "https://ds.canonical.com/",
@@ -61,19 +71,21 @@ afterAll(async () => {
 });
 
 const listVerb = (pack: PackDefinition): VerbSpec =>
-  compilePack(pack, `bundled:${pack.noun}`, DEFAULT_PREFIX_MAP).find(
-    (v) => verbKey(v.path) === `${pack.noun} list`,
-  ) as VerbSpec;
+  compilePack(
+    pack,
+    distributionSource("pragma.conf.ts"),
+    DEFAULT_PREFIX_MAP,
+  ).find((v) => verbKey(v.path) === `${pack.noun} list`) as VerbSpec;
 
 /**
- * Every bundled pack list verb, with the hint expected in its empty message:
+ * Every declared story's list verb, with the hint expected in its empty message:
  * an authored `emptyRecovery` surfaces `pragma sources update`; the others fall
  * back to the generic build/broaden hint.
  */
 const PACK_LISTS: readonly { pack: PackDefinition; hint: RegExp }[] = [
-  { pack: modifierPack, hint: /pragma sources update/ },
-  { pack: tokenPack, hint: /pragma sources update/ },
-  { pack: standardPack, hint: /broaden your filter/ },
+  { pack: storyFor("modifier"), hint: /pragma sources update/ },
+  { pack: storyFor("token"), hint: /pragma sources update/ },
+  { pack: storyFor("standard"), hint: /broaden the filter/ },
 ];
 
 const REAL = { dryRun: false, undo: false, yes: false };
@@ -89,24 +101,34 @@ describe("pack list empty-state (U5, PROTECTED)", () => {
 
   it.each(
     PACK_LISTS,
-  )("$pack.noun list renders a non-blank message (+ hint) and keeps JSON []", ({
+  )("$pack.noun list declares a non-blank empty notice (+ hint), JSON stays []", ({
     pack,
     hint,
   }) => {
     const { formatters } = listVerb(pack).output;
-    const plain = formatters.plain([]);
-    expect(plain).toContain(`No ${pack.noun} entries found.`);
-    expect(plain).toMatch(hint);
+    // The message + runnable hint live on the empty-state seam — the
+    // dispatcher routes them to stderr, keeping plain stdout pure data.
+    const notice = formatters.emptyNotice?.([]);
+    expect(notice).toContain(`No ${pack.noun} entries found.`);
+    expect(notice).toMatch(hint);
     // JSON is the uniform empty array — unchanged by the message.
     expect(formatters.json([])).toBe("[]");
     // The llm view stays non-blank too (the `(0)` heading plus the message).
     expect(formatters.llm([]).trim().length).toBeGreaterThan(0);
   });
 
-  it("dispatch prints the empty message on stdout and exits 0 (end-to-end)", async () => {
-    const outcome = await executeVerb(listVerb(modifierPack), {}, REAL, rt);
+  it("dispatch routes the empty message to stderr and exits 0 (end-to-end)", async () => {
+    const outcome = await executeVerb(
+      listVerb(storyFor("modifier")),
+      {},
+      REAL,
+      rt,
+    );
     expect(outcome.exitCode).toBe(0);
-    expect(outcome.stdout).toContain("No modifier entries found.");
-    expect(outcome.stdout).toContain("pragma sources update");
+    // stdout carries no prose a pipe would read as a record; the calm notice
+    // and its hint reach the human on stderr.
+    expect(outcome.stdout ?? "").not.toContain("No modifier entries found.");
+    expect(outcome.stderr).toContain("No modifier entries found.");
+    expect(outcome.stderr).toContain("pragma sources update");
   });
 });