@canonical/pragma-cli 0.38.0 → 0.42.0

package/src/capabilities/create/shippedCreate.subprocess.test.ts

@@ -17,8 +17,8 @@
  * existed to turn that crash into a clean refusal.
  *
  * There is no virtual filesystem now. Every generator's templates are real
- * files under its own package, so all three nouns run from the shipped entry and
- * all three are asserted here. THE REFUSAL CASES ARE GONE ON PURPOSE: a test
+ * files under its own package, so all four nouns run from the shipped entry and
+ * all four are asserted here. THE REFUSAL CASES ARE GONE ON PURPOSE: a test
  * asserting `create package` refuses would now be asserting a defect.
  *
  * The svelte + lit cases stay load-bearing: `types.ts.ejs` / `index.ts.ejs` /
@@ -28,7 +28,13 @@
  */
 
 import { execFileSync, spawnSync } from "node:child_process";
-import { mkdtempSync, readdirSync, readFileSync } from "node:fs";
+import {
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -70,7 +76,12 @@ function snapshot(dir: string): Map<string, string> {
  * No case installs dependencies (`runInstall` defaults false), so every tree is
  * generator output alone and byte-comparable.
  */
-const CASES: ReadonlyArray<{ label: string; args: readonly string[] }> = [
+const CASES: ReadonlyArray<{
+  label: string;
+  args: readonly string[];
+  /** Files that must already exist in the cwd (`page` adds to a domain). */
+  seed?: Readonly<Record<string, string>>;
+}> = [
   ...(["react", "svelte", "lit"] as const).map((framework) => ({
     label: `component ${framework}`,
     // The framework is a PATH SEGMENT, not a flag — `create` mirrors summon's
@@ -88,6 +99,11 @@ const CASES: ReadonlyArray<{ label: string; args: readonly string[] }> = [
     // `application/react`, and the tree mirrors summon's.
     args: ["create", "application", "react", "probeapp", "--yes"],
   },
+  {
+    label: "page",
+    args: ["create", "page", "probe/detail", "--yes"],
+    seed: { "src/domains/probe/routes.ts": "export default {};\n" },
+  },
 ];
 
 /** Run one create invocation in its own cwd and snapshot what it wrote. */
@@ -95,19 +111,24 @@ function create(
   command: string,
   prefix: readonly string[],
   args: readonly string[],
+  seed: Readonly<Record<string, string>> = {},
 ): Map<string, string> {
   const dir = freshCwd();
+  for (const [file, content] of Object.entries(seed)) {
+    mkdirSync(dirname(join(dir, file)), { recursive: true });
+    writeFileSync(join(dir, file), content);
+  }
   execFileSync(command, [...prefix, ...args], { cwd: dir, stdio: "pipe" });
   return snapshot(dir);
 }
 
 describe("shipped pragma create (PROTECTED)", () => {
-  for (const { label, args } of CASES) {
+  for (const { label, args, seed } of CASES) {
     it(`${label}: shipped entry ≡ source run, byte-for-byte`, () => {
       // (1) The shipped entry, exactly as a consumer's `pragma` runs it.
-      const shipped = create(process.execPath, [shippedEntry], args);
+      const shipped = create(process.execPath, [shippedEntry], args, seed);
       // (2) A source run — the reference output.
-      const source = create("bun", [sourceEntry], args);
+      const source = create("bun", [sourceEntry], args, seed);
 
       // Wrote something. Before the distribution stopped shipping a compiled
       // binary, `package` and `application` wrote NOTHING here — they refused.

package/src/capabilities/distribution.test.ts

@@ -63,7 +63,7 @@ describe("the distribution's declared stories (PROTECTED)", () => {
     },
   );
 
-  it('every declared filter names "values" or a "vocabulary"', () => {
+  it('every declared filter names "values", a "vocabulary" or a "noun"', () => {
     // The rule the round-trip above already enforces, said OUT LOUD. It was
     // only implied there — a story satisfies the whole grammar or it does not,
     // and a reader looking for this particular property found no assertion
@@ -87,6 +87,7 @@ describe("the distribution's declared stories (PROTECTED)", () => {
       "implementation list --library",
       "implementation list --platform",
       "standard list --category",
+      "token consumers --block",
       "token consumers --key",
       "token consumers --state",
       "token consumers --symbol",
@@ -105,8 +106,10 @@ describe("the distribution's declared stories (PROTECTED)", () => {
     ]);
     for (const [label, filter] of filters) {
       expect(
-        filter.values !== undefined || filter.vocabulary !== undefined,
-        `${label} declares neither "values" nor a "vocabulary"`,
+        filter.values !== undefined ||
+          filter.vocabulary !== undefined ||
+          filter.noun !== undefined,
+        `${label} declares no "values", "vocabulary" or "noun"`,
       ).toBe(true);
       // And never both — a declared set IS the vocabulary.
       expect(

package/src/capabilities/distribution.ts

@@ -22,6 +22,7 @@ import conf from "../../pragma.conf.js";
 import { compileStoryModule } from "../kernel/packs/compile.js";
 import {
   distributionSource,
+  type NounLookups,
   type PackDefinition,
 } from "../kernel/packs/types.js";
 import { DEFAULT_PREFIX_MAP } from "../kernel/render/index.js";
@@ -34,6 +35,10 @@ export const declaredStories: ReadonlyMap<string, PackDefinition> = new Map(
     .map((story): readonly [string, PackDefinition] => [story.noun, story]),
 );
 
+/** The lookup each declared noun resolves names through, for a filter naming it. */
+export const declaredLookups: NounLookups = (noun) =>
+  declaredStories.get(noun)?.lookup;
+
 /**
  * Those stories compiled to capability modules, by noun.
  *
@@ -49,6 +54,7 @@ export const storyModules: ReadonlyMap<string, CapabilityModule> = new Map(
       story,
       distributionSource("pragma.conf.ts"),
       DEFAULT_PREFIX_MAP,
+      declaredLookups,
     ),
   ]),
 );

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

@@ -28,7 +28,10 @@ import {
 import { activeStories } from "../../../kernel/runtime/graphpack/stories.js";
 import type { PragmaRuntime } from "../../../kernel/runtime/index.js";
 import type { SourcesDecision } from "../../../kernel/runtime/resolveSources.js";
-import { resolveSources } from "../../../kernel/runtime/resolveSources.js";
+import {
+  describeIgnoredPack,
+  resolveSources,
+} from "../../../kernel/runtime/resolveSources.js";
 import type { CheckItem, CheckResult } from "../types.js";
 
 /**
@@ -148,6 +151,15 @@ export async function checkPackageRefs(
   const composition = `${packs.length} ${packs.length === 1 ? "pack" : "packs"}, ${entities} entities${suffix}`;
 
   if (decision.kind === "embedded") {
+    // A pack this project built, passed over because an older CLI built it. The
+    // check still PASSES — the snapshot is answering and its answers are the
+    // current ones — so the account of the pack goes in the detail, next to the
+    // account of what IS answering, and the remedy stays unset: there is
+    // nothing to fix, only two ways to change it, and the sentence names both.
+    const ignored =
+      decision.ignoredPack === undefined
+        ? ""
+        : ` · ${describeIgnoredPack(decision.ignoredPack)}`;
     return {
       name,
       status: "pass",
@@ -157,7 +169,7 @@ export async function checkPackageRefs(
       // neither. "shipped with the CLI" rather than "embedded snapshot" — the
       // reader needs to know where these packs came from, not what the build
       // calls the artefact.
-      detail: `shipped with the CLI — ${composition} · run \`${BIN_NAME} sources update\` to build from your own configured packs instead`,
+      detail: `shipped with the CLI — ${composition} · run \`${BIN_NAME} sources update\` to build from your own configured packs instead${ignored}`,
       ...(items.length > 0 ? { items } : {}),
     };
   }

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

@@ -16,12 +16,13 @@ import {
   writeFileSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import type { ConfigLayers } from "../../kernel/config/types.js";
 import { executeVerb } from "../../kernel/project/cli/dispatch.js";
 import { bootRuntime } from "../../kernel/runtime/boot.js";
 import { createQueryFacade } from "../../kernel/runtime/facade.js";
+import { activePackPath, packDir } from "../../kernel/runtime/paths.js";
 import type {
   GlobalFlags,
   LazyStore,
@@ -212,6 +213,42 @@ describe("doctor — the pack-refs check", () => {
     }
   });
 
+  it("still passes when a pack an older CLI built is passed over — and names it", async () => {
+    // The upgrade state. The check PASSES: the snapshot is answering and its
+    // answers are the current ones, so there is nothing to fix — only a pack to
+    // account for, and two ways to change it. Hence a detail, not a remedy.
+    const cwd = tmp("pragma-proj-");
+    const hash = "b".repeat(64);
+    const dir = packDir(hash);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "data.nq"), "<urn:s> <urn:p> <urn:o> .\n");
+    writeFileSync(join(dir, "schema.json"), "{}");
+    writeFileSync(join(dir, "index.json"), "{}");
+    writeFileSync(join(dir, "stories.json"), "[]");
+    writeFileSync(
+      join(dir, "manifest.json"),
+      JSON.stringify({
+        name: "pragma",
+        version: "0.1.0",
+        sourceRef: "t",
+        contentHash: hash,
+        prefixes: {},
+        createdAt: "2026-09-10T21:49:00.411Z",
+      }),
+    );
+    mkdirSync(dirname(activePackPath(cwd)), { recursive: true });
+    writeFileSync(activePackPath(cwd), hash);
+
+    const pkgRefs = await checkPackageRefs(bootRuntime(FLAGS, cwd));
+    expect(pkgRefs.status).toBe("pass");
+    expect(pkgRefs.detail).toContain("shipped with the CLI");
+    expect(pkgRefs.detail).toContain(
+      "a pack built by pragma 0.1.0 on 2026-09-10 is ignored",
+    );
+    expect(pkgRefs.detail).toContain("pragma sources reset");
+    expect(pkgRefs.remedy).toBeUndefined();
+  });
+
   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

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

@@ -27,6 +27,8 @@ const doctorVerb: VerbSpec<Record<string, unknown>, DoctorData> = {
   // (`toolDescriptions.test.ts`), so the inventory's widening is described as
   // "the verbose global flag" rather than by its spelling.
   doc: "Reports the environment checks first, then one row per setup target — once for your home directory, once for this project. Each row is pass, fail, available (an optional integration you have not set up yet), or skip (nothing to do here, and the row says why), with the next step printed inline. Every row is named after the setup target that repairs it, except `harnesses`: a listing, per scope, of the AI harnesses found on this machine and whether this CLI's MCP server is registered in each — the ones actually found, or every harness it knows about under the verbose global flag. Needs no store; the store check boots lazily and never fails the run.",
+  useWhen: "when something is not working, to find out what",
+  category: "diagnostic",
   params: [],
   output: { formatters: doctorFormatters },
   examples: [

package/src/capabilities/emptyRecovery.test.ts

@@ -174,6 +174,11 @@ describe("pack list empty-state (U5, PROTECTED)", () => {
       const notice = formatters.notice?.(empty);
       expect(notice).toContain(`No ${pack.noun} entries found.`);
       expect(notice).toMatch(hint);
+      // Over MCP the same hint ends in a TOOL CALL: an agent cannot run a
+      // command, and `meta.notice` is the only place it reads this.
+      const overMcp = formatters.notice?.(empty, "mcp");
+      expect(overMcp).toMatch(/Call `[a-z]+_[a-z]+ \{.*\}`\./);
+      expect(overMcp).not.toMatch(hint);
       // JSON is the uniform empty array — unchanged by the message.
       expect(formatters.json(empty)).toBe("[]");
       // The llm view stays non-blank too (the `(0)` heading plus the message).

package/src/capabilities/graph/connect.verb.ts

@@ -103,6 +103,8 @@ const connectVerb: VerbSpec<Record<string, unknown>, ConnectResult> = {
   path: ["graph", "connect"],
   summary: "Show the shortest relation paths between two entities.",
   doc: "Finds every shortest path of RELATION edges between two entities, and says which kind of nothing it found when there is no path. An edge counts as a relation only where it does not fan out into a roster — membership of a class, a tier or a family is answered by that noun's list verb, not by a path — so most pairs are correctly reported as unconnected. Address each endpoint by prefixed name (ds:global.component.button) or absolute IRI. Every answer states the hop limit, the fan-in threshold, and the packs searched.",
+  useWhen: "when asked whether and how two things are related",
+  example: { a: "ds:global.component.button", b: "dt:color.text" },
   params: [
     {
       kind: "string",

package/src/capabilities/graph/inspect.render.ts

@@ -11,6 +11,7 @@ import { toTurtle } from "../../kernel/render/turtle.js";
 import type {
   InboundGroup,
   InspectResult,
+  PredicateGroup,
   ReadTerm,
 } from "../../kernel/runtime/readEntity.js";
 import type { Formatters } from "../../kernel/spec/index.js";
@@ -39,6 +40,13 @@ function inboundHeading(group: InboundGroup): string {
   return `${short(group.predicate)} (${suffix})`;
 }
 
+/** `predicate (24 objects, showing 10)` — a cut group says what it was cut from. */
+function outboundHeading(group: PredicateGroup): string {
+  return group.truncated
+    ? `${short(group.predicate)} (${group.count} objects, showing ${group.objects.length})`
+    : short(group.predicate);
+}
+
 export const inspectFormatters: Formatters<InspectResult> = {
   plain(data) {
     const title = data.label
@@ -46,7 +54,7 @@ export const inspectFormatters: Formatters<InspectResult> = {
       : (data.prefixed ?? data.uri);
     const lines = [title, "═".repeat(Math.max(title.length, 24)), ""];
     for (const group of data.groups) {
-      lines.push(`  ${short(group.predicate)}:`);
+      lines.push(`  ${outboundHeading(group)}:`);
       for (const object of group.objects) lines.push(`    ${named(object)}`);
     }
     for (const [via, rows] of Object.entries(data.nested)) {

package/src/capabilities/graph/inspect.test.ts

@@ -333,3 +333,76 @@ describe("bounds and losslessness the review surfaced", () => {
     });
   });
 });
+
+describe("an outbound predicate is cut below `detailed`, and says so", () => {
+  // One subject asserting a wide predicate both ways: 14 named objects, and 12
+  // blank ones that inline as records.
+  const indexes = Array.from({ length: 14 }, (_, index) => index);
+  const WIDE_TTL = [
+    "@prefix ds: <https://ds.canonical.com/> .",
+    `ds:wide ds:name "Wide" ;`,
+    `  ds:uses ${indexes.map((index) => `ds:part.${index}`).join(", ")} ;`,
+    `  ds:binds ${indexes
+      .slice(0, 12)
+      .map((index) => `[ ds:rank ${index} ]`)
+      .join(", ")} .`,
+  ].join("\n");
+
+  const readAt = async (
+    detail: "summary" | "standard" | "detailed",
+  ): Promise<InspectResult> => {
+    const fixture = await buildFixtureRuntime({
+      ttl: WIDE_TTL,
+      prefixes: BLOCK_PREFIXES,
+      detail,
+    });
+    try {
+      return (await inspectVerb.run(
+        { uri: "ds:wide" },
+        fixture.rt,
+      )) as InspectResult;
+    } finally {
+      (await fixture.rt.store.get()).store.dispose();
+    }
+  };
+  const group = (result: InspectResult, local: string) =>
+    result.groups.find((g) => g.predicate.value === `${DS}${local}`);
+
+  it("lists the head and states the true count at standard", async () => {
+    const result = await readAt("standard");
+    expect(group(result, "uses")).toMatchObject({ truncated: true, count: 14 });
+    expect(group(result, "uses")?.objects).toHaveLength(10);
+    // The inlined records follow the objects that survived the cut.
+    expect(group(result, "binds")?.count).toBe(12);
+    expect(result.nested["ds:binds"]).toHaveLength(10);
+    // A predicate under the cap carries neither marker.
+    expect(group(result, "name")).not.toHaveProperty("truncated");
+    expect(group(result, "name")).not.toHaveProperty("count");
+  });
+
+  it("keeps a few at summary rather than none", async () => {
+    expect(group(await readAt("summary"), "uses")?.objects).toHaveLength(3);
+  });
+
+  it("cuts nothing at detailed", async () => {
+    const result = await readAt("detailed");
+    expect(group(result, "uses")?.objects).toHaveLength(14);
+    expect(group(result, "uses")).not.toHaveProperty("truncated");
+    expect(result.nested["ds:binds"]).toHaveLength(12);
+  });
+
+  it("prints the count in the plain and the Turtle forms", async () => {
+    const result = await readAt("standard");
+    const formatters = inspectVerb.output.formatters;
+    expect(formatters.plain(result)).toContain(
+      "ds:uses (14 objects, showing 10):",
+    );
+    const turtle = formatters.llm(result);
+    expect(turtle).toContain(
+      "  # ds:uses — 14 objects, showing 10\n  ds:uses ",
+    );
+    expect(turtle).toContain(
+      "  # ds:binds — 12 objects, showing 10\n  ds:binds\n",
+    );
+  });
+});

package/src/capabilities/graph/inspect.verb.ts

@@ -25,6 +25,8 @@ const inspectVerb: VerbSpec<Record<string, unknown>, InspectResult> = {
   summary:
     "Show every triple where a URI is the subject, grouped by predicate.",
   doc: "Inspect one entity: all predicate/object pairs asserted on the subject. Address it by prefixed name (ds:global.component.button) or absolute IRI.",
+  useWhen: "when asked for everything recorded about one identifier",
+  example: { uri: "ds:global.component.button" },
   params: [
     {
       kind: "string",

package/src/capabilities/graph/query.render.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { queryFormatters } from "./query.render.js";
+
+const EMPTY = { type: "select", bindings: [] } as never;
+
+describe("graph query — zero rows names the next call", () => {
+  it("says the query ran, and points at the catalogue and the namespaces as commands on the CLI", () => {
+    const notice = queryFormatters.notice?.(EMPTY) as string;
+    expect(notice).toContain("the query ran and matched nothing");
+    expect(notice).toContain("`pragma capabilities`");
+    expect(notice).toContain("`pragma ontology list`");
+    // The condensed form is one stream, so it carries the same sentence.
+    expect(queryFormatters.llm(EMPTY)).toBe(notice);
+  });
+
+  it("spells them as tool calls over MCP, and names no domain tool", () => {
+    const notice = queryFormatters.notice?.(EMPTY, "mcp") as string;
+    expect(notice).toContain("`capabilities {}`");
+    expect(notice).toContain("`ontology_list {}`");
+    expect(notice).not.toContain("pragma ");
+    // Which tool answers the question is the catalogue's to say, not this
+    // renderer's: the only tools it may name are the two it points at.
+    const named = [...notice.matchAll(/`([a-z_]+) \{/g)].map((m) => m[1]);
+    expect(named.sort()).toEqual(["capabilities", "ontology_list"]);
+  });
+
+  it("says nothing when there are rows", () => {
+    expect(
+      queryFormatters.notice?.({
+        type: "select",
+        bindings: [{ s: "ds:x" }],
+      } as never),
+    ).toBeUndefined();
+  });
+});

package/src/capabilities/graph/query.render.ts

@@ -9,11 +9,12 @@
  * - json: the serialized {@link QueryResult}.
  */
 
-import type { Formatters } from "../../kernel/spec/index.js";
+import { quoteCall } from "../../kernel/spec/call.js";
+import type { Call, Formatters, Surface } from "../../kernel/spec/index.js";
 
 // Inline `import("…")` type (no `from`) — keeps the ke types off the static
 // import graph the lazy-dispatch probe walks (see query.verb.ts).
-type QueryResult = import("@canonical/ke").QueryResult;
+type QueryAnswer = import("./runQuery.js").QueryAnswer;
 
 /**
  * Render CONSTRUCT triples as readable `subject\tpredicate\tobject` lines,
@@ -35,13 +36,46 @@ function formatTriples(
     .join("\n");
 }
 
-export const queryFormatters: Formatters<QueryResult> = {
+/**
+ * Where an empty SELECT points. Deliberately no domain tool: which one answers
+ * the caller's question is the catalogue's to say, so the pointer is to the
+ * catalogue — and to the namespaces that exist, since an invented prefix parses
+ * and matches nothing.
+ */
+export const EMPTY_QUERY_CALLS = {
+  catalogue: { verb: "capabilities" },
+  namespaces: { verb: "ontology list" },
+} as const satisfies Record<string, Call>;
+
+/**
+ * What zero rows says for itself. "No results." read as a failed tool to an
+ * agent with nowhere to go next. The query RAN; when its own text declares a
+ * prefix this graph does not have, that is the reason and it is said exactly.
+ */
+function describeEmptySelect(result: QueryAnswer, surface: Surface): string {
+  const { catalogue, namespaces } = EMPTY_QUERY_CALLS;
+  const invented = (result.unknownPrefixes ?? [])
+    .map(
+      ({ prefix, iri }) =>
+        `Prefix \`${prefix}:\` <${iri}> is not a namespace of this graph, so nothing under it can match.`,
+    )
+    .join(" ");
+  return [
+    "No results: the query ran and matched nothing.",
+    invented,
+    `The namespaces that exist are listed by ${quoteCall(namespaces, surface)} (an invented prefix matches nothing). A domain tool may answer this without SPARQL: ${quoteCall(catalogue, surface)} lists the tools by the question each answers.`,
+  ]
+    .filter(Boolean)
+    .join(" ");
+}
+
+export const queryFormatters: Formatters<QueryAnswer> = {
   // Zero rows/triples: plain stdout stays empty — the notice is
   // `notice`, routed to stderr (exit 0) by the dispatcher so a pipe
   // reads no prose. ASK always has a result and never goes empty.
-  notice(result) {
+  notice(result, surface = "cli") {
     if (result.type === "select" && result.bindings.length === 0) {
-      return "No results.";
+      return describeEmptySelect(result, surface);
     }
     if (result.type === "construct" && result.triples.length === 0) {
       return "No triples.";
@@ -65,7 +99,9 @@ export const queryFormatters: Formatters<QueryResult> = {
 
   llm(result) {
     if (result.type === "select") {
-      if (result.bindings.length === 0) return "_No results._";
+      if (result.bindings.length === 0) {
+        return describeEmptySelect(result, "cli");
+      }
       const cols = Object.keys(result.bindings[0] ?? {});
       const header = `| ${cols.join(" | ")} |`;
       const divider = `| ${cols.map(() => "---").join(" | ")} |`;
@@ -84,6 +120,8 @@ export const queryFormatters: Formatters<QueryResult> = {
   },
 
   json(result) {
-    return JSON.stringify(result);
+    // The payload is the engine's own shape; the prefix finding is the notice's.
+    const { unknownPrefixes: _unknownPrefixes, ...data } = result;
+    return JSON.stringify(data);
   },
 };

package/src/capabilities/graph/query.shipped.exec.test.ts

@@ -64,3 +64,47 @@ describe("a name pragma printed can be pasted back (PROTECTED)", () => {
     expect(prefixed).toEqual(absolute);
   });
 });
+
+describe("an invented namespace is named, not answered with silence", () => {
+  // The recorded failure: nine queries against a namespace that does not
+  // exist, nine "No results", and a guess. A declared PREFIX always parses, so
+  // only a check against the store's own prefix map can say why nothing matched.
+  const INVENTED =
+    "PREFIX tok: <https://example.invalid/tokens#> SELECT ?c WHERE { ?c tok:uses ?t }";
+
+  it("says exactly which prefix is not a namespace of this graph, on both surfaces", async () => {
+    const result = await queryVerb.run({ sparql: INVENTED }, rt);
+    const { notice, json } = queryVerb.output.formatters;
+    const cli = notice?.(result, "cli") as string;
+    expect(cli).toContain(
+      "Prefix `tok:` <https://example.invalid/tokens#> is not a namespace of this graph",
+    );
+    expect(cli).toContain("`pragma ontology list`");
+    expect(notice?.(result, "mcp")).toContain("`ontology_list {}`");
+    // The finding explains the emptiness; the payload stays the engine's shape.
+    const payload = JSON.parse(json(result));
+    expect(payload).toMatchObject({ type: "select", bindings: [] });
+    expect(payload).not.toHaveProperty("unknownPrefixes");
+  });
+
+  it("says nothing about prefixes when the query declares only real ones, or has rows", async () => {
+    const real = await queryVerb.run(
+      {
+        sparql:
+          "PREFIX ds: <https://ds.canonical.com/> SELECT ?s WHERE { ?s a ds:NoSuchClass }",
+      },
+      rt,
+    );
+    const notice = queryVerb.output.formatters.notice?.(real, "cli") as string;
+    expect(notice).toContain("the query ran and matched nothing");
+    expect(notice).not.toContain("is not a namespace");
+    const hit = await queryVerb.run(
+      {
+        sparql: `${INVENTED.replace("WHERE { ?c tok:uses ?t }", "WHERE { ?c ?p ?t } LIMIT 1")}`,
+      },
+      rt,
+    );
+    expect(queryVerb.output.formatters.notice?.(hit, "cli")).toBeUndefined();
+    expect(hit).not.toHaveProperty("unknownPrefixes");
+  });
+});

package/src/capabilities/graph/query.verb.ts

@@ -24,6 +24,8 @@ const queryVerb: VerbSpec<Record<string, unknown>, QueryResult> = {
   path: ["graph", "query"],
   summary: "Run a raw SPARQL query against the loaded graph.",
   doc: "Executes an arbitrary SPARQL query (SELECT / ASK / CONSTRUCT) against the store. Prefixes are applied automatically from the pack's namespace map; list the ontology namespaces to discover the available prefixes.",
+  useWhen: "only when no other tool answers: SPARQL joins or counts",
+  example: { sparql: "SELECT ?s WHERE { ?s a ds:Component } LIMIT 5" },
   params: [
     {
       kind: "string",

package/src/capabilities/graph/queryText.test.ts

@@ -10,7 +10,11 @@
  */
 
 import { describe, expect, it } from "vitest";
-import { expandPrefixedNames, trimQueryError } from "./queryText.js";
+import {
+  expandPrefixedNames,
+  findUnknownPrefixes,
+  trimQueryError,
+} from "./queryText.js";
 
 const PREFIXES = {
   ds: "https://ds.canonical.com/",
@@ -119,3 +123,53 @@ describe("trimQueryError — the caller's own position", () => {
     );
   });
 });
+
+describe("findUnknownPrefixes — only a prefix that can explain the emptiness", () => {
+  const KNOWN = { ds: "https://ds.canonical.com/" };
+  const BAD = "https://example.invalid/t#";
+
+  it("reports a declared, used prefix whose IRI is no namespace of the graph", () => {
+    expect(
+      findUnknownPrefixes(
+        `PREFIX tok: <${BAD}> PREFIX ds: <https://ds.canonical.com/> SELECT ?c WHERE { ?c tok:uses ds:x }`,
+        KNOWN,
+      ),
+    ).toEqual([{ prefix: "tok", iri: BAD }]);
+  });
+
+  it("ignores a PREFIX in a comment or inside a string literal", () => {
+    expect(
+      findUnknownPrefixes(
+        `# PREFIX tok: <${BAD}>\nSELECT ?s WHERE { ?s ds:label "PREFIX tok: <${BAD}> tok:x" }`,
+        KNOWN,
+      ),
+    ).toEqual([]);
+  });
+
+  it("ignores a declared prefix the body never uses", () => {
+    expect(
+      findUnknownPrefixes(
+        `PREFIX tok: <${BAD}> SELECT ?s WHERE { ?s a ds:Component }`,
+        KNOWN,
+      ),
+    ).toEqual([]);
+  });
+
+  it("does not judge a relative IRI, which BASE resolves", () => {
+    expect(
+      findUnknownPrefixes(
+        "BASE <https://ds.canonical.com/> PREFIX rel: <tokens/> SELECT ?s WHERE { ?s rel:p ?o }",
+        KNOWN,
+      ),
+    ).toEqual([]);
+  });
+
+  it("reports the default prefix too, when the body uses it", () => {
+    expect(
+      findUnknownPrefixes(
+        `PREFIX : <${BAD}> SELECT ?s WHERE { ?s :p ?o }`,
+        KNOWN,
+      ),
+    ).toEqual([{ prefix: "", iri: BAD }]);
+  });
+});