@canonical/pragma-cli 0.34.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";
@@ -112,12 +118,14 @@ 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");
@@ -127,12 +135,35 @@ describe("doctor — shape & spread", () => {
     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");
-    expect(byName(data, "MCP commands")?.status).toBe("skip");
-    // No project/global config in the isolated XDG.
-    expect(byName(data, "pragma config")?.status).toBe("fail");
+
+    // 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");
   });
 });
 
@@ -169,10 +200,10 @@ describe("doctor — the pack-refs check", () => {
 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 () => {
@@ -181,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();
   });
 });
@@ -211,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

@@ -14,14 +14,14 @@
 
 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: [

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 { BIN_NAME } from "../../constants.js";
-import type { PragmaRuntime } from "../../kernel/runtime/types.js";
-import { checkConfigFile } from "./checks/checkConfigFile.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()],
     [`${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)],
-    ["MCP commands", checkMcpCommands(rt.cwd)],
-    ["Skills symlinked", checkSkillsSymlinked(rt.cwd)],
+    ["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 \`${BIN_NAME} 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,8 +9,19 @@
  */
 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
@@ -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

@@ -85,7 +85,7 @@ const listVerb = (pack: PackDefinition): VerbSpec =>
 const PACK_LISTS: readonly { pack: PackDefinition; hint: RegExp }[] = [
   { pack: storyFor("modifier"), hint: /pragma sources update/ },
   { pack: storyFor("token"), hint: /pragma sources update/ },
-  { pack: storyFor("standard"), hint: /broaden your filter/ },
+  { pack: storyFor("standard"), hint: /broaden the filter/ },
 ];
 
 const REAL = { dryRun: false, undo: false, yes: false };
@@ -101,21 +101,23 @@ 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 () => {
+  it("dispatch routes the empty message to stderr and exits 0 (end-to-end)", async () => {
     const outcome = await executeVerb(
       listVerb(storyFor("modifier")),
       {},
@@ -123,7 +125,10 @@ describe("pack list empty-state (U5, PROTECTED)", () => {
       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");
   });
 });

package/src/capabilities/graph/examples.exec.test.ts

@@ -0,0 +1,107 @@
+/**
+ * The documented examples, EXECUTED against the shipped pack (PROTECTED).
+ *
+ * The existing documentation suite validates example GRAMMAR — that a `cmd`
+ * parses as a command this CLI declares. Grammar is not truth: the previous
+ * `graph inspect ds:button` examples passed that check for as long as they
+ * existed while 404ing for every user who copied them, and the `graph query`
+ * ASK example passed while quietly answering `false`.
+ *
+ * So these run the examples as WRITTEN, against the embedded graph, and assert
+ * they answer. An example is a promise to a stranger; this is the only check
+ * that reads it as one.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { verbKey } from "../../kernel/packs/uniqueness.js";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import type { InspectResult } from "../../kernel/runtime/readEntity.js";
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import { TEST_FLAGS } from "../../testing/helpers/projectCli.js";
+import { graphModule } from "./index.js";
+
+const verb = (name: string): VerbSpec =>
+  graphModule.verbs.find((v) => verbKey(v.path) === name) as VerbSpec;
+
+/**
+ * The name of a verb's single positional, read from the verb rather than
+ * retyped — the point of this file is that documentation and code agree, so it
+ * should not itself hardcode a name that could drift.
+ */
+const positionalOf = (spec: VerbSpec): string =>
+  spec.params.find((p) => p.positional)?.name ?? "";
+
+/**
+ * The argument an example passes, recovered from the example's own `cmd`.
+ *
+ * Read from the declaration rather than retyped, so editing an example without
+ * editing this file cannot leave the test asserting the old one.
+ */
+function exampleArg(spec: VerbSpec, index: number): string {
+  const cmd = spec.examples?.[index]?.cmd ?? "";
+  const quoted = cmd.match(/"([^"]*)"/);
+  if (quoted?.[1]) return quoted[1];
+  return cmd.trim().split(/\s+/).slice(3).join(" ");
+}
+
+// ONE store for the file. Booting per case tripled this suite's cost against
+// the shipped pack for no extra coverage, and the whole package already flakes
+// under parallel contention — a test that need not add load should not.
+let rt: PragmaRuntime;
+beforeAll(() => {
+  rt = bootRuntime(TEST_FLAGS);
+});
+afterAll(async () => {
+  (await rt.store.get()).store.dispose();
+});
+
+describe("documented examples resolve against the shipped graph (PROTECTED)", () => {
+  it("runs every `graph inspect` example as written", async () => {
+    const inspect = verb("graph inspect");
+    expect(inspect.examples?.length).toBeGreaterThan(0);
+
+    for (const [index] of (inspect.examples ?? []).entries()) {
+      const uri = exampleArg(inspect, index);
+      const result = (await inspect.run(
+        { [positionalOf(inspect)]: uri },
+        rt,
+      )) as InspectResult;
+      // The prefixed and absolute forms are two spellings of one subject.
+      expect(
+        result.uri,
+        `example ${index} (${uri}) did not resolve to the documented entity`,
+      ).toBe("https://ds.canonical.com/global.component.button");
+      expect(result.groups.length).toBeGreaterThan(0);
+    }
+  });
+
+  it("runs the `graph query` ASK example and gets a true answer", async () => {
+    // The old example returned `false` — syntactically fine, semantically a lie
+    // about the graph. Asserting the ANSWER is what catches that.
+    const query = verb("graph query");
+    const ask = (query.examples ?? []).findIndex((e) => e.cmd.includes("ASK"));
+    expect(ask, "no ASK example to execute").toBeGreaterThanOrEqual(0);
+
+    const result = (await query.run(
+      { [positionalOf(query)]: exampleArg(query, ask) },
+      rt,
+    )) as { type: string; result?: boolean };
+
+    expect(result.type).toBe("ask");
+    expect(result.result, "the documented ASK example answers false").toBe(
+      true,
+    );
+  });
+
+  it("runs the `graph query` SELECT example and gets rows", async () => {
+    const query = verb("graph query");
+    const result = (await query.run(
+      { [positionalOf(query)]: exampleArg(query, 0) },
+      rt,
+    )) as { type: string; bindings?: unknown[] };
+
+    expect(result.type).toBe("select");
+    expect(result.bindings?.length ?? 0).toBeGreaterThan(0);
+  });
+});

package/src/capabilities/graph/index.ts

@@ -3,7 +3,7 @@
  * (the raw SPARQL escape hatch, PR6). The covenant blesses both.
  */
 
-import type { CapabilityModule } from "../../kernel/spec/types.js";
+import type { CapabilityModule } from "../../kernel/spec/index.js";
 import { resourceProvider } from "../resources/index.js";
 import { graphInspectVerb } from "./inspect.verb.js";
 import { graphQueryVerb } from "./query.verb.js";