@canonical/pragma-cli 0.38.0 → 0.40.0

package/src/capabilities/prompt/verbs.ts

@@ -13,7 +13,7 @@
  */
 
 import { BIN_NAME } from "../../constants.js";
-import { cliRecovery, PragmaError } from "../../kernel/error/index.js";
+import { callRecovery, PragmaError } from "../../kernel/error/index.js";
 import { VOCABULARY } from "../../kernel/index.js";
 import type { PragmaRuntime } from "../../kernel/runtime/index.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
@@ -37,6 +37,8 @@ const listVerb: VerbSpec<Record<string, unknown>, PromptListData> = {
   path: ["prompt", "list"],
   summary: "List the workflow prompt templates the design system offers.",
   doc: `Browse the prompt entities the active graph declares (${VOCABULARY.prompt.type} in this distribution) — name, description, and argument names. This distribution's graph carries none today. The same prompts are offered natively over MCP prompts/list; use prompt_lookup for the full template body.`,
+  useWhen:
+    "when asked which ready-made workflow prompts the design system offers",
   params: [],
   output: { formatters: promptListFormatters },
   examples: [{ cmd: `${BIN_NAME} prompt list` }],
@@ -58,6 +60,9 @@ const lookupVerb: VerbSpec<Record<string, unknown>, PromptLookupData> = {
   path: ["prompt", "lookup"],
   summary: "Show one workflow prompt template's body and arguments by name.",
   doc: "Fetch a single prompt entity's full template body (with {{arg}} placeholders) and its declared arguments. A prompt is addressed by its label; prompt_list names the ones the active graph carries.",
+  useWhen:
+    "when asked to read or run one workflow prompt by the name prompt_list gave",
+  example: { name: "build-a-block" },
   params: [
     {
       kind: "string",
@@ -91,9 +96,10 @@ const lookupVerb: VerbSpec<Record<string, unknown>, PromptLookupData> = {
         const available = await m.readPrompts(rt);
         throw PragmaError.notFound("prompt", name, {
           suggestions: available.map((prompt) => prompt.name),
-          recovery: cliRecovery("prompt list", "List available prompts.", {
-            tool: "prompt_list",
-          }),
+          recovery: callRecovery(
+            { verb: "prompt list" },
+            "List available prompts.",
+          ),
         });
       }
       return entry;

package/src/capabilities/resources/provider.ts

@@ -46,12 +46,14 @@ import type {
 } from "../../kernel/runtime/graphpack/types.js";
 import { readEntity } from "../../kernel/runtime/readEntity.js";
 import { resolveSources } from "../../kernel/runtime/resolveSources.js";
+import { renderNextStep } from "../../kernel/spec/call.js";
 import type {
   CapabilityModule,
   McpListable,
   McpListableRef,
   McpResourceProvider,
 } from "../../kernel/spec/types.js";
+import { BUILD_STORE_CALL } from "../shared/calls.js";
 
 /**
  * The weight an unweighted slice carries — "as important as any other".
@@ -181,7 +183,9 @@ function listEntity(
 }
 
 /** The recovery entry a missing/legacy index degrades to (and its read body). */
-const SOURCES_RECOVERY = `No enriched entity index. Run \`${BIN_NAME} sources update\` to build it.`;
+// This surface is MCP-only, so the next step is always spelled as a tool call.
+const describeNoIndex = (): string =>
+  `No enriched entity index: the store needs building. ${renderNextStep(BUILD_STORE_CALL, "mcp")}`;
 
 /** The single entry a server with no usable index advertises. */
 function sourcesEntry(): ListedResource {
@@ -189,7 +193,7 @@ function sourcesEntry(): ListedResource {
     uri: SOURCES_URI,
     name: SOURCES_VARIABLE,
     title: "Store not indexed",
-    description: SOURCES_RECOVERY,
+    description: describeNoIndex(),
     mimeType: RECOVERY_MIME_TYPE,
   };
 }
@@ -491,7 +495,7 @@ export const resourceProvider: McpResourceProvider = {
                 {
                   uri: url.href,
                   mimeType: RECOVERY_MIME_TYPE,
-                  text: SOURCES_RECOVERY,
+                  text: describeNoIndex(),
                 },
               ],
             };

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

@@ -511,7 +511,8 @@ describe("resource read — cold-store failure surfaces isError + recovery (D3)"
     const listed = await harness.listResources();
     expect(listed.map((r) => r.uri)).toEqual(["pragma:sources"]);
     const read = await harness.readResource("pragma:sources");
-    expect(read.text).toMatch(/sources update/);
+    // MCP-only surface: the next step is a tool call, and never confirms.
+    expect(read.text).toContain("Call `sources_update {}`.");
   });
 });
 

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

@@ -455,6 +455,9 @@ const setupAllVerb = setupVerb(
   "all",
   SELF_CAPABILITY,
   {
+    useWhen:
+      "when asked to install or repair the tool's integration: the config file, shell completions, MCP registration, skills and the editor extension",
+    example: { scope: "project" },
     doc: "Shows what each target needs, then applies the ones you keep. Everything is configured in your home directory by default; the scope option moves the run to this project alone, or covers both. Without an attended terminal the plan is printed and nothing is written unless the run is explicitly confirmed.",
     examples: [
       { cmd: `${BIN_NAME} setup` },
@@ -479,6 +482,7 @@ const configVerb = setupVerb(
   "Create your global config file, filled in with the defaults.",
   "config",
   SUB_CAPABILITY,
+  { useWhen: "when asked to create only the global config file" },
 );
 
 const mcpVerb = setupVerb(
@@ -486,6 +490,10 @@ const mcpVerb = setupVerb(
   `Register the ${BIN_NAME} MCP server with the AI harnesses on this machine.`,
   "mcp",
   SUB_CAPABILITY,
+  {
+    useWhen:
+      "when asked to connect only the MCP server to the AI tools on this machine",
+  },
 );
 
 const completionsVerb = setupVerb(
@@ -493,6 +501,7 @@ const completionsVerb = setupVerb(
   "Install TAB completion for the shell you are running.",
   "completions",
   SUB_CAPABILITY,
+  { useWhen: "when asked to install only TAB completion for the shell" },
 );
 
 const skillsVerb = setupVerb(
@@ -500,6 +509,10 @@ const skillsVerb = setupVerb(
   "Link the skills you have installed into every AI harness that reads them.",
   "skills",
   SUB_CAPABILITY,
+  {
+    useWhen:
+      "when asked to make only the installed skills visible to the AI tools on this machine",
+  },
 );
 
 const lspVerb = setupVerb(
@@ -507,6 +520,9 @@ const lspVerb = setupVerb(
   "Install the Terrazzo design-token extension into the VS Code-family editors on this machine (on PATH, under /Applications or ~/Applications, or by its user directory).",
   "lsp",
   SUB_CAPABILITY,
+  {
+    useWhen: "when asked to install only the design-token editor extension",
+  },
 );
 
 /** The `setup` capability module (run-all self-verb + five CLI-only sub-verbs). */

package/src/capabilities/shared/calls.ts

@@ -0,0 +1,20 @@
+/**
+ * The calls more than one capability's dead end points at, so
+ * `callRule.test.ts` can hold each to its verb. "Build the store" is the
+ * kernel's own constant (`kernel/spec/call.ts#BUILD_STORE_CALL`), re-exported
+ * here so capabilities and kernel make the same call.
+ */
+
+import { BUILD_STORE_CALL } from "../../kernel/spec/call.js";
+import type { Call } from "../../kernel/spec/index.js";
+
+export { BUILD_STORE_CALL };
+
+/** Link installed skills into the AI harnesses — CLI-only, so it is always spelled as a command. */
+export const LINK_SKILLS_CALL: Call = { verb: "setup skills" };
+
+/** Re-run the build showing each file as it parses. `--verbose` is a global CLI flag, so only the command carries it. */
+export const VERBOSE_BUILD_CALL: Call = {
+  ...BUILD_STORE_CALL,
+  cliFlags: ["--verbose"],
+};

package/src/capabilities/skill/render.ts

@@ -2,14 +2,16 @@
  * Formatters for `skill list` and `skill lookup`.
  */
 
-import { BIN_NAME } from "../../constants.js";
-import type { Formatters } from "../../kernel/spec/index.js";
+import { renderNextStep } from "../../kernel/spec/call.js";
+import type { Formatters, Surface } from "../../kernel/spec/index.js";
+import { BUILD_STORE_CALL, LINK_SKILLS_CALL } from "../shared/calls.js";
 import type { DiscoveredSkill } from "./discover.js";
 import type { SkillLookup } from "./verbs.js";
 
 /** Empty-state guidance (U5) — where skills come from now that packs ship them. */
-const EMPTY_PLAIN = `No skills found.\nSkills come from design-system packs — add one to your config's packs, run \`${BIN_NAME} sources update\`, then \`${BIN_NAME} setup skills\`.`;
-const EMPTY_LLM = `## Skills (0)\n\nNo skills found. Skills come from design-system packs — add one to the project config's packs, run \`${BIN_NAME} sources update\`, then \`${BIN_NAME} setup skills\`.`;
+function describeEmpty(surface: Surface): string {
+  return `No skills found.\nSkills come from design-system packs — add one to the project config's packs, build the store, then link the skills. ${renderNextStep(BUILD_STORE_CALL, surface)} ${renderNextStep(LINK_SKILLS_CALL, surface)}`;
+}
 
 export const skillListFormatters: Formatters<DiscoveredSkill[]> = {
   // Zero skills: plain stdout stays empty — the guidance is `notice`,
@@ -21,10 +23,11 @@ export const skillListFormatters: Formatters<DiscoveredSkill[]> = {
           `${s.name}${s.frontmatter.prompt ? " (prompt)" : ""}  ${s.description}`,
       )
       .join("\n"),
-  notice: (skills) => (skills.length === 0 ? EMPTY_PLAIN : undefined),
+  notice: (skills, surface = "cli") =>
+    skills.length === 0 ? describeEmpty(surface) : undefined,
   llm: (skills) =>
     skills.length === 0
-      ? EMPTY_LLM
+      ? `## Skills (0)\n\n${describeEmpty("cli")}`
       : [
           `## Skills (${skills.length})`,
           "",

package/src/capabilities/skill/verbs.ts

@@ -9,7 +9,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { BIN_NAME } from "../../constants.js";
-import { cliRecovery, PragmaError } from "../../kernel/error/index.js";
+import { callRecovery, PragmaError } from "../../kernel/error/index.js";
 import { suggestNames } from "../../kernel/project/cli/suggestNames.js";
 import type { PragmaRuntime } from "../../kernel/runtime/index.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
@@ -25,6 +25,7 @@ export interface SkillLookup extends DiscoveredSkill {
 const listVerb: VerbSpec<Record<string, unknown>, DiscoveredSkill[]> = {
   path: ["skill", "list"],
   summary: "List discovered skills (SKILL.md files under the skill roots).",
+  useWhen: "when asked which agent skills (guided workflows) are available",
   params: [],
   output: { formatters: skillListFormatters },
   examples: [{ cmd: `${BIN_NAME} skill list` }],
@@ -43,6 +44,8 @@ const listVerb: VerbSpec<Record<string, unknown>, DiscoveredSkill[]> = {
 const lookupVerb: VerbSpec<Record<string, unknown>, SkillLookup> = {
   path: ["skill", "lookup"],
   summary: "Show a skill's metadata and instructions by name.",
+  useWhen: "when asked to follow one skill",
+  example: { name: "specify-component" },
   params: [
     {
       kind: "string",
@@ -75,9 +78,10 @@ const lookupVerb: VerbSpec<Record<string, unknown>, SkillLookup> = {
           name,
           skills.map((skill) => skill.name),
         ),
-        recovery: cliRecovery("skill list", "List discovered skills.", {
-          tool: "skill_list",
-        }),
+        recovery: callRecovery(
+          { verb: "skill list" },
+          "List discovered skills.",
+        ),
       });
     }
     return { ...match, instructions: readInstructions(match.sourcePath) };

package/src/capabilities/sources/collectStatus.ts

@@ -72,7 +72,7 @@ export async function collectStatus(
     ref: entrySource(entry),
   }));
   const decision = resolveSources(layers, runtime.cwd);
-  const base = { cwd: runtime.cwd, sources };
+  const base = { cwd: runtime.cwd, sources, ignoredPack: null };
 
   switch (decision.kind) {
     case "embedded": {
@@ -84,6 +84,11 @@ export async function collectStatus(
         sourceRef: manifest.sourceRef,
         builtAt: manifest.createdAt,
         entityCount: manifest.entityCount ?? null,
+        // The upgrade row: this project HAS a pack, built by an older CLI, and
+        // the snapshot is answering in its place. Reported straight off the
+        // decision — status never re-derives which pack answers, and it must
+        // not re-derive which one was passed over either.
+        ignoredPack: decision.ignoredPack ?? null,
       };
     }
     case "pack": {

package/src/capabilities/sources/index.ts

@@ -1,15 +1,16 @@
 /**
- * The `sources` capability barrel — `status` (storeless read) and `update`
- * (the resolve/build/point Task).
+ * The `sources` capability barrel — `status` (storeless read), `update` (the
+ * resolve/build/point Task), and `reset` (drop the pointer update wrote).
  */
 
 import { asVerb } from "../../kernel/spec/asVerb.js";
 import type { CapabilityModule } from "../../kernel/spec/index.js";
+import { resetVerb } from "./reset.verb.js";
 import { statusVerb } from "./status.verb.js";
 import { updateVerb } from "./update.verb.js";
 
 /** The `sources` capability module. */
 export const sourcesModule: CapabilityModule = {
   name: "sources",
-  verbs: [asVerb(statusVerb), asVerb(updateVerb)],
+  verbs: [asVerb(statusVerb), asVerb(updateVerb), asVerb(resetVerb)],
 };

package/src/capabilities/sources/reset.render.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import { resetFormatters } from "./reset.render.js";
+
+const REMOVED = {
+  removed: true,
+  contentHash: "0e82d35c66687b8a",
+  answers: "embedded",
+} as const;
+
+describe("sources reset formatters", () => {
+  it("llm states what was removed and what answers now", () => {
+    expect(resetFormatters.llm(REMOVED)).toBe(
+      "# sources reset\n- Removed: 0e82d35c66687b8a\n- Answers: embedded",
+    );
+    expect(
+      resetFormatters.llm({
+        removed: false,
+        contentHash: null,
+        answers: "embedded",
+      }),
+    ).toContain("- Removed: nothing was built");
+  });
+
+  it("plain tells a project with its own packs that reads need an update", () => {
+    const out = resetFormatters.plain({ ...REMOVED, answers: "unavailable" });
+    expect(out).toContain(
+      "Removed this project's pack pointer (was 0e82d35c6668).",
+    );
+    expect(out).toContain(
+      "reads need `pragma sources update` before they can answer",
+    );
+  });
+});

package/src/capabilities/sources/reset.render.ts

@@ -0,0 +1,43 @@
+/**
+ * Formatters for `pragma sources reset` — plain, llm, json.
+ *
+ * Two outcomes, and the difference matters to a reader: a pointer was removed,
+ * or there was none to remove. Neither is an error, so both are rendered as the
+ * calm statement they are — and each says what answers reads NOW, because that
+ * is the question a reset is asked in service of.
+ */
+
+import { BIN_NAME } from "../../constants.js";
+import type { Formatters } from "../../kernel/spec/index.js";
+import type { SourcesResetData } from "./types.js";
+
+/** What answers this project's reads after the reset, as a sentence. */
+function nowAnswering(data: SourcesResetData): string {
+  return data.answers === "embedded"
+    ? `The snapshot shipped with the CLI answers reads; run \`${BIN_NAME} sources update\` to build from your configured packs again.`
+    : `This project declares its own packs, so reads need \`${BIN_NAME} sources update\` before they can answer.`;
+}
+
+export const resetFormatters: Formatters<SourcesResetData> = {
+  plain(data) {
+    if (!data.removed) {
+      return `No pack is built for this project — nothing to reset. ${nowAnswering(data)}`;
+    }
+    return [
+      `Removed this project's pack pointer (was ${(data.contentHash ?? "").slice(0, 12)}).`,
+      nowAnswering(data),
+    ].join("\n");
+  },
+
+  llm(data) {
+    return [
+      `# sources reset`,
+      `- Removed: ${data.removed ? (data.contentHash ?? "") : "nothing was built"}`,
+      `- Answers: ${data.answers}`,
+    ].join("\n");
+  },
+
+  json(data) {
+    return JSON.stringify(data);
+  },
+};

package/src/capabilities/sources/reset.verb.ts

@@ -0,0 +1,59 @@
+/**
+ * The `sources reset` verb — drop this project's built pack.
+ *
+ * A mutation (`mutates: true`) that needs neither the network nor the store:
+ * like `sources update` it must not boot the store first (a project whose pack
+ * it is about to unpoint may not have a bootable one at all), and unlike update
+ * it never leaves the machine. Plan-first comes from the projectors, exactly as
+ * it does for update — `--dry-run` previews on the CLI, and
+ * over MCP a call without `confirm` returns the plan and writes nothing.
+ *
+ * `destructive: true`: it removes state a user built on purpose. It deletes
+ * no graph data and `sources update` brings the pack back from the cache, but
+ * the annotation is what tells an agent's host to ask first, and "your project
+ * stops reading the pack it was reading" deserves the ask.
+ */
+
+import type { Task } from "@canonical/task";
+import { BIN_NAME } from "../../constants.js";
+import type { VerbSpec } from "../../kernel/spec/index.js";
+import { resetFormatters } from "./reset.render.js";
+import type { SourcesResetData } from "./types.js";
+
+/** The `sources reset` verb spec. */
+export const resetVerb: VerbSpec<Record<string, unknown>, SourcesResetData> = {
+  path: ["sources", "reset"],
+  summary: "Remove this project's built pack.",
+  doc: "Deletes the pointer that names the pack this project reads, so reads answer from the snapshot shipped with the CLI again; a project that declares its own packs cannot answer reads until the next `sources update`. The cached pack files are left alone — they are shared with any other project built from the same sources, and a later update reuses them. Reports calmly when nothing is built.",
+  useWhen:
+    "to discard locally built data and return to the data shipped with the tool",
+  params: [],
+  output: { formatters: resetFormatters },
+  examples: [
+    {
+      cmd: `${BIN_NAME} sources reset`,
+      note: "drop the built pack and read the shipped snapshot",
+    },
+    {
+      cmd: `${BIN_NAME} sources reset --dry-run`,
+      note: "show what would be removed",
+    },
+  ],
+  capability: {
+    needsStore: false,
+    mutates: true,
+    needsNetwork: false,
+    destructive: true,
+    mcp: {
+      expose: true,
+      annotations: { readOnlyHint: false, openWorldHint: false },
+    },
+  },
+  // `run` really returns `Promise<Task<R>>` — the body reads config and the
+  // pointer before its effects are known — presented through the `Task<R>` arm
+  // by the same honest cast `sources update` uses (see `VerbSpec.run`).
+  run: (_params, runtime) =>
+    import("./runReset.js").then((module) =>
+      module.buildResetTask(runtime),
+    ) as unknown as Task<SourcesResetData>,
+};

package/src/capabilities/sources/runReset.ts

@@ -0,0 +1,65 @@
+/**
+ * Build the `sources reset` Task — drop this project's built pack.
+ *
+ * The counterpart of `sources update`: update points the project at a pack it
+ * built, reset takes the pointer away, so reads go back to what the config
+ * resolves to on its own (the snapshot shipped with the CLI, or — for a project
+ * that declares its own packs — nothing until it builds them again). It is the
+ * verb a user needs after an upgrade passes over a pack an older CLI built and
+ * they would rather remove it than rebuild it.
+ *
+ * THE POINTER, AND ONLY THE POINTER. The pack cache is content-addressed and
+ * SHARED: another project on this machine may point at the same hash, and the
+ * embedded snapshot is materialized into that same cache under its own hash, so
+ * a per-project verb that deleted pack directories would be deleting bytes it
+ * does not own. The pointer is the whole of a project's store state — one line
+ * naming a hash — so removing it is exactly, and only, "this project no longer
+ * reads a pack of its own". What stays behind is a cache doing its job: a later
+ * `sources update` over the same sources finds the pack complete and reuses it
+ * without a rebuild. (No `--all` for the same reason it has no flags at all:
+ * evicting the shared cache, or the git-ref checkouts beside it, is a different
+ * job from resetting one project, and this verb would be the wrong owner.)
+ *
+ * Nothing built is not a failure: the verb reports that it found nothing and
+ * exits 0, the way `config unset` does for a field that was never set. There is
+ * no state to correct — the project already reads what a reset would leave it
+ * reading.
+ */
+
+import { $, deleteFile, gen, type Task } from "@canonical/task";
+import type { PragmaRuntime } from "../../kernel/runtime/index.js";
+import { activePackPath, readActivePack } from "../../kernel/runtime/paths.js";
+import type { SourcesResetData } from "./types.js";
+
+/**
+ * Build the Task that removes the project's active-pack pointer.
+ *
+ * @param runtime - The per-invocation runtime.
+ * @returns A Task yielding what was removed and what answers reads now.
+ * @note Impure — reads config and the pointer; the Task deletes the pointer.
+ */
+export async function buildResetTask(
+  runtime: PragmaRuntime,
+): Promise<Task<SourcesResetData>> {
+  const layers = await runtime.loadConfig();
+  const priorHash = readActivePack(runtime.cwd);
+  const path = activePackPath(runtime.cwd);
+  const data: SourcesResetData = {
+    removed: priorHash !== undefined,
+    contentHash: priorHash ?? null,
+    answers: layers.origins.packs === "default" ? "embedded" : "unavailable",
+  };
+
+  return gen(function* () {
+    // No pointer, no effect: a Task with nothing in it is what "nothing to do"
+    // looks like, and it keeps `--dry-run` honest (an empty plan, not a delete
+    // of a file that is not there).
+    if (priorHash !== undefined) {
+      // No undo is declared: an undo re-plans from the disk, where the pointer
+      // is already gone. The way back is `sources update`, which reuses the
+      // cached pack.
+      yield* $(deleteFile(path));
+    }
+    return data;
+  });
+}

package/src/capabilities/sources/runUpdate.ts

@@ -31,7 +31,7 @@ import {
   writeFile,
 } from "@canonical/task";
 import { VERSION } from "../../constants.js";
-import { cliRecovery, PragmaError } from "../../kernel/error/index.js";
+import { callRecovery, PragmaError } from "../../kernel/error/index.js";
 // DIRECT LEAF IMPORT, not `graphpack/index.js`. The barrel re-exports
 // `embedded.ts`, which statically imports the ~1.9 MB generated pack — and
 // with per-file `tsc` output ESM evaluates that re-export when this module
@@ -49,10 +49,11 @@ import {
   redactUrl,
   resolvePackage,
 } from "../../kernel/runtime/refs/index.js";
+import { existingGlobalSkillDirs } from "../setup/operations/setupSkills.js";
 // The global scope's EXISTING link directories, from the module that owns the
 // scope covenant — so `sources update` cannot drift away from what
 // `setup skills --global` links, or widen the scope on its own.
-import { existingGlobalSkillDirs } from "../setup/operations/setupSkills.js";
+import { VERBOSE_BUILD_CALL } from "../shared/calls.js";
 import { globalSkillRoots, installedSkillsDir } from "../skill/discover.js";
 import { planHarnessSkillLinks, planSkillInstall } from "./installSkills.js";
 import type { SourcesUpdateData } from "./types.js";
@@ -200,8 +201,8 @@ export async function buildUpdateTask(
         ? "No packs are configured, so there are no sources to build a store from. The embedded pack answers reads until you add a pack."
         : `The ${entries.length} configured pack(s) resolved 0 RDF sources (no definitions/**.ttl or data/**.ttl). Refusing to build an empty store.`,
       {
-        recovery: cliRecovery(
-          "sources update --verbose",
+        recovery: callRecovery(
+          VERBOSE_BUILD_CALL,
           "Add a pack that ships `.ttl` under definitions/ or data/, then re-run.",
         ),
       },
@@ -270,8 +271,8 @@ export async function buildUpdateTask(
       throw PragmaError.configError(
         `None of the ${inputs.length} configured source(s) can be parsed — nothing to build.`,
         {
-          recovery: cliRecovery(
-            "sources update --verbose",
+          recovery: callRecovery(
+            VERBOSE_BUILD_CALL,
             "Fix the reported sources, then re-run.",
           ),
         },
@@ -303,8 +304,8 @@ export async function buildUpdateTask(
     throw PragmaError.configError(
       `The configured sources parsed to 0 RDF triples, so the store would be empty. Refusing to build an empty store.`,
       {
-        recovery: cliRecovery(
-          "sources update --verbose",
+        recovery: callRecovery(
+          VERBOSE_BUILD_CALL,
           "Check that the pack sources actually contain RDF triples, then re-run.",
         ),
       },
@@ -496,9 +497,9 @@ export async function classifySourceBuildError(
     ? `Pack source "${culprit.path}" cannot be parsed`
     : "The configured packs cannot be built into a store";
   return PragmaError.configError(`${where}: ${detail}`, {
-    recovery: cliRecovery(
-      "sources update --verbose",
-      "Re-run with --verbose to see each file as it parses. If a pack ships malformed RDF, report it to that pack's maintainer.",
+    recovery: callRecovery(
+      VERBOSE_BUILD_CALL,
+      "A verbose re-run shows each file as it parses. If a pack ships malformed RDF, report it to that pack's maintainer.",
     ),
   });
 }