@canonical/pragma-cli 0.34.0 → 0.35.0

package/src/bin.ts

@@ -1,9 +1,9 @@
-#!/usr/bin/env bun
+#!/usr/bin/env node
 /**
  * CLI entry point for `pragma` (v2 kernel).
  *
  * The composition root. Ordered early exits keep the hot paths minimal and
- * side-effect-free: `mcp` serves over stdio (D9); `__complete` resolves
+ * side-effect-free: `mcp serve` serves over stdio (D9); `__complete` resolves
  * completions storelessly *before* first-run so the greeting never leaks into a
  * shell buffer; `--version` prints and exits. Otherwise: parse global flags,
  * reject a bad `--format`, run first-run onboarding, then build the Commander
@@ -14,13 +14,39 @@
  */
 
 import type { Command } from "commander";
-import { BIN_NAME, PROGRAM_DESCRIPTION, VERSION } from "./constants.js";
+import {
+  BIN_NAME,
+  DETAIL_LEVELS,
+  ISSUES_URL,
+  PROGRAM_DESCRIPTION,
+  VERSION,
+} from "./constants.js";
+
+/**
+ * The flags a bare invocation answers itself. `--version` returns earlier; the
+ * help form falls through to the front door, which IS its answer — so the
+ * unknown-flag guard must not mistake it for a typo. One spelling per flag:
+ * no `-h`/`-v` shorts exist anywhere on the surface.
+ */
+const ROOT_FLAGS = new Set(["--help", "--version"]);
 
 async function main(): Promise<void> {
   const argv = process.argv.slice(2);
 
-  // 1. MCP server entry (D9) — `pragma mcp` serves over stdio.
-  if (argv[0] === "mcp") {
+  // 1. MCP server entry (D9) — `pragma mcp serve` serves over stdio.
+  //    The exit is NARROW on purpose: argv must be EXACTLY those two tokens.
+  //    The server's startup has to stay minimal and stdio-pure (no first-run
+  //    banner, no config read, nothing on stdout but JSON-RPC), which is what
+  //    this shortcut buys — but the noun itself is ordinary grammar, so
+  //    `pragma mcp`, `pragma mcp --help` and `pragma mcp serve --help` fall
+  //    through to the same help machinery every other noun uses, and root
+  //    help's promise that `--help` works on any command becomes true.
+  //    Matching on a PREFIX would extend that purity budget to malformed argv
+  //    it was never bought for: `mcp serve extra` would serve instead of
+  //    letting Commander reject the excess argument, and `mcp serve --version`
+  //    would serve instead of answering the global flag. Anything suffixed
+  //    falls through to the ordinary grammar, which owns both jobs.
+  if (argv.length === 2 && argv[0] === "mcp" && argv[1] === "serve") {
     const [{ serveMcp }, { capabilities }] = await Promise.all([
       import("./kernel/project/mcp/serve.js"),
       import("./capabilities/index.js"),
@@ -29,7 +55,8 @@ async function main(): Promise<void> {
     return;
   }
 
-  // 2. Completion resolver — storeless, before first-run so no banner leaks.
+  // 2. Completion resolver — storeless, and reached before anything that could
+  //    print, so a completion request is never polluted by a hint.
   //    Protocol: `pragma __complete -- <words…>`; the first `--` is framing
   //    (tolerated absent) and is stripped here so a later bare `--` stays the
   //    user's end-of-options. Candidates go to stdout newline-delimited (zero
@@ -60,72 +87,131 @@ async function main(): Promise<void> {
     return;
   }
 
-  const { parseGlobalFlags, readRawFormat, stripGlobalFlags } = await import(
-    "./kernel/project/cli/globalFlags.js"
-  );
+  const {
+    findValuedVerbose,
+    parseGlobalFlags,
+    readRawDetail,
+    readRawFormat,
+    stripGlobalFlags,
+  } = await import("./kernel/project/cli/globalFlags.js");
   const globalFlags = parseGlobalFlags(argv);
 
   // 3. `--version` is global — print and exit wherever it appears.
-  if (argv.some((arg) => arg === "--version" || arg === "-v")) {
+  if (argv.some((arg) => arg === "--version")) {
     process.stdout.write(`${VERSION}\n`);
     return;
   }
 
-  // 4. Reject an unknown `--format` early (help still prints regardless).
-  const explicitHelp = argv.some((arg) => arg === "--help" || arg === "-h");
-  const rawFormat = readRawFormat(argv);
-  if (
-    !explicitHelp &&
-    rawFormat !== undefined &&
-    !["plain", "llm", "json", "text"].includes(rawFormat)
-  ) {
-    const [
-      { PragmaError },
-      { renderErrorPlain, renderErrorJson },
-      { mapExitCode },
-    ] = await Promise.all([
-      import("./kernel/error/PragmaError.js"),
-      import("./kernel/error/renderError.js"),
-      import("./kernel/project/cli/exitCodes.js"),
-    ]);
-    const error = PragmaError.invalidInput("format", rawFormat, {
-      validOptions: ["plain", "llm", "json"],
-    });
-    const rendered =
-      globalFlags.format === "json"
-        ? renderErrorJson(error)
-        : renderErrorPlain(error);
-    process.stderr.write(`${rendered}\n`);
-    process.exitCode = mapExitCode(error.code);
-    return;
-  }
-
-  // 5. First-run onboarding (stderr-only, failure-tolerant). Skipped on the
-  //    side-effect-free help path — `--help` here; `mcp`, `__complete`, and
-  //    `--version` already returned above — so help never seeds state.
+  // 4. Reject a bad global-flag value early (help still prints regardless):
+  //    an unknown `--format`, an unrecognized `--detail` level (which used to
+  //    be dropped silently — the same defect class as a filter that
+  //    evaporates), and a valued `--verbose=<x>` (the flag takes no value;
+  //    accepting-and-ignoring one would be a silent no-op).
+  const explicitHelp = argv.some((arg) => arg === "--help");
+  const jsonMode = globalFlags.format === "json";
   if (!explicitHelp) {
-    const { ensureFirstRun } = await import("./kernel/config/firstRun.js");
-    await ensureFirstRun();
+    const rawFormat = readRawFormat(argv);
+    if (
+      rawFormat !== undefined &&
+      !["plain", "llm", "json"].includes(rawFormat)
+    ) {
+      await rejectGlobalValue(
+        "format",
+        rawFormat,
+        ["plain", "llm", "json"],
+        jsonMode,
+      );
+      return;
+    }
+    const rawDetail = readRawDetail(argv);
+    if (
+      rawDetail !== undefined &&
+      !(DETAIL_LEVELS as readonly string[]).includes(rawDetail)
+    ) {
+      await rejectGlobalValue(
+        "detail",
+        rawDetail,
+        [...DETAIL_LEVELS],
+        jsonMode,
+      );
+      return;
+    }
+    const valuedVerbose = findValuedVerbose(argv);
+    if (valuedVerbose !== undefined) {
+      const { PragmaError } = await import("./kernel/error/PragmaError.js");
+      await renderStartupError(
+        new PragmaError({
+          code: "INVALID_INPUT",
+          message: `\`--verbose\` takes no value; \`${valuedVerbose}\` is not a flag of this program.`,
+          recovery: { message: "Use `--verbose` on its own." },
+        }),
+        jsonMode,
+      );
+      return;
+    }
   }
 
-  // 6. Build the command tree.
-  const [{ buildProgram }, { capabilities }] = await Promise.all([
-    import("./kernel/project/cli/buildProgram.js"),
-    import("./capabilities/index.js"),
-  ]);
+  // 5. Load the capability registry — the command tree's data. Commander and
+  //    the program builder are NOT loaded yet: the bare-invocation branch
+  //    below answers `--help` and the front door from the registry alone, so
+  //    the help fast path never pays for the parser it will not run.
+  const { capabilities } = await import("./capabilities/index.js");
   const args = stripGlobalFlags(argv);
 
-  // 7. A bare invocation (no command token — argv empty or only global flags)
+  // 6. A bare invocation (no command token — argv empty or only global flags)
   //    prints the curated front door instead of exiting silently. Uses the
   //    static capabilities — the front door never reads config or stories.
   if (!args.some((arg) => !arg.startsWith("-"))) {
+    // `args` is argv with the global flags already stripped, so a token still
+    // starting with `-` here is a flag this program does not have — EXCEPT the
+    // two the front door itself answers, which reach this branch by design.
+    // Commander rejects unknown flags below the root; without this the ROOT
+    // answered a typo with the front door and exit 0, so `pragma --detial
+    // standard` read as success.
+    const unknownFlag = args.find(
+      (arg) => arg.startsWith("-") && !ROOT_FLAGS.has(arg),
+    );
+    if (unknownFlag !== undefined) {
+      const [
+        { PragmaError },
+        { renderErrorPlain, renderErrorJson },
+        { mapExitCode },
+      ] = await Promise.all([
+        import("./kernel/error/PragmaError.js"),
+        import("./kernel/error/renderError.js"),
+        import("./kernel/project/cli/exitCodes.js"),
+      ]);
+      const error = new PragmaError({
+        code: "INVALID_INPUT",
+        message: `Unknown option "${unknownFlag}".`,
+        recovery: {
+          message: "Run with `--help` to see the available options.",
+        },
+      });
+      process.stderr.write(
+        `${
+          globalFlags.format === "json"
+            ? renderErrorJson(error)
+            : renderErrorPlain(error)
+        }\n`,
+      );
+      process.exitCode = mapExitCode(error.code);
+      return;
+    }
+
     const { formatRootHelp } = await import("./kernel/project/cli/rootHelp.js");
     const live = capabilities
       .flatMap((module) => [...module.verbs])
       .filter((verb) => !verb.hidden);
     process.stdout.write(
-      `${formatRootHelp(BIN_NAME, PROGRAM_DESCRIPTION, live)}\n`,
+      `${formatRootHelp(BIN_NAME, PROGRAM_DESCRIPTION, live, VERSION, ISSUES_URL)}\n`,
     );
+    // The front door is a read, so it is where the un-set-up hint belongs: the
+    // machine's state is the presence of the global config, and nothing is
+    // written to discover it.
+    const { setupHintLines } = await import("./kernel/config/firstRun.js");
+    const hint = setupHintLines();
+    if (hint.length > 0) process.stderr.write(`\n${hint.join("\n")}\n`);
     return;
   }
 
@@ -143,10 +229,12 @@ async function main(): Promise<void> {
       );
       const effective = await loadEffectiveModules(capabilities, process.cwd());
       modules = effective.modules;
-      for (const problem of effective.problems) {
-        process.stderr.write(
-          `Ignored story ${problem.source}: ${problem.message}\n`,
-        );
+      if (globalFlags.quiet !== true) {
+        for (const problem of effective.problems) {
+          process.stderr.write(
+            `Ignored story ${problem.source}: ${problem.message}\n`,
+          );
+        }
       }
     } catch (error) {
       await renderStartupError(error, globalFlags.format === "json");
@@ -155,11 +243,31 @@ async function main(): Promise<void> {
   }
   const verbs = modules.flatMap((module) => [...module.verbs]);
 
+  // Module-owned noun mounts (CapabilityModule.cliProjection), keyed by the
+  // module's noun. A module's verbs all share their noun, so the module name
+  // is that noun for every module that declares a mount.
+  const mounts = new Map(
+    modules.flatMap((module) =>
+      module.cliProjection
+        ? [[module.name, module.cliProjection] as const]
+        : [],
+    ),
+  );
+
+  // A mount may defer its registration machinery behind `prepare()` (the
+  // fast paths import the projection hook without ever mounting) — resolve
+  // every deferred import before the tree is built, alongside the program
+  // builder's own deferred load.
+  const [{ buildProgram }] = await Promise.all([
+    import("./kernel/project/cli/buildProgram.js"),
+    ...[...mounts.values()].map((projection) => projection.prepare?.()),
+  ]);
   const program = buildProgram(verbs, {
     globalFlags,
     programName: BIN_NAME,
     description: PROGRAM_DESCRIPTION,
     version: VERSION,
+    mounts,
   });
   // Silence Commander's default stderr writer on EVERY command, not just the
   // root — otherwise a bad subcommand/option prints Commander's raw `error: …`
@@ -169,10 +277,30 @@ async function main(): Promise<void> {
   try {
     await program.parseAsync(args, { from: "user" });
   } catch (error) {
-    await handleProgramError(error, argv, globalFlags.format === "json", verbs);
+    await handleProgramError(error, argv, globalFlags.format, verbs);
   }
 }
 
+/**
+ * Reject an invalid global-flag value before dispatch: one renderer for the
+ * `--format`/`--detail` guards, so every validated global value flag fails
+ * with the same invalid-input shape and its valid list.
+ */
+async function rejectGlobalValue(
+  name: string,
+  value: string,
+  validOptions: readonly string[],
+  jsonMode: boolean,
+): Promise<void> {
+  const { PragmaError } = await import("./kernel/error/PragmaError.js");
+  await renderStartupError(
+    PragmaError.invalidInput(name, value, {
+      validOptions: [...validOptions],
+    }),
+    jsonMode,
+  );
+}
+
 /**
  * Render a startup error (e.g. an invalid config story pack) before the command
  * tree is built, mapping it to stderr + an exit code — the same envelope
@@ -216,7 +344,7 @@ function silenceCommanderErrors(command: Command): void {
 async function handleProgramError(
   error: unknown,
   argv: readonly string[],
-  jsonMode: boolean,
+  format: import("./constants.js").OutputFormat,
   verbs: import("./kernel/spec/types.js").VerbSpec[],
 ): Promise<void> {
   const { CommanderError } = await import("commander");
@@ -224,16 +352,66 @@ async function handleProgramError(
   if (error instanceof CommanderError) {
     if (
       error.code === "commander.helpDisplayed" ||
-      error.code === "commander.version" ||
-      error.code === "commander.help"
+      error.code === "commander.version"
     ) {
       process.exitCode = 0;
       return;
     }
-    if (error.code === "commander.unknownCommand") {
-      const { nounVerbMap, resolveUnknownCommand } = await import(
-        "./kernel/project/cli/suggest.js"
+    if (error.code === "commander.help") {
+      // Respect the help error's OWN exit code: `help({ error: true })` — a
+      // bare namespace with children, help written to stderr — carries 1;
+      // a stdout help carries 0.
+      process.exitCode = error.exitCode;
+      return;
+    }
+
+    // A parse failure whose argv still speaks a retired module grammar gets
+    // that module's designed migration error (the module authors the text;
+    // the kernel only routes). Currently: `create component --framework`
+    // (R1) — scoped to the ONE command that ever had the flag, so
+    // `create package --framework …` keeps its honest unknown-option error
+    // instead of a migration message about a grammar it never spoke — and
+    // scoped to the pre-terminator span: after `--` the spelling is an
+    // operand, not the retired flag, so the real parse error stands.
+    const { selectScanSpan, stripGlobalFlags } = await import(
+      "./kernel/project/cli/globalFlags.js"
+    );
+    const strippedArgs = stripGlobalFlags(argv);
+    const strippedPositionals = strippedArgs.filter(
+      (arg) => !arg.startsWith("-"),
+    );
+    if (
+      strippedPositionals[0] === "create" &&
+      strippedPositionals[1] === "component" &&
+      selectScanSpan(strippedArgs).some(
+        (arg) => arg === "--framework" || arg.startsWith("--framework="),
+      )
+    ) {
+      const [
+        { FRAMEWORK_FLAG_ERROR },
+        { PragmaError },
+        { renderErrorForFormat },
+      ] = await Promise.all([
+        import("./capabilities/create/messages.js"),
+        import("./kernel/error/PragmaError.js"),
+        import("./kernel/error/renderError.js"),
+      ]);
+      // Explicit --format json/llm envelope (the kernel's one gate+renderer
+      // decision); plain keeps the designed raw line.
+      const rendered = renderErrorForFormat(
+        new PragmaError({
+          code: "INVALID_INPUT",
+          message: FRAMEWORK_FLAG_ERROR.replace(/^error:\s*/i, ""),
+        }),
+        format,
       );
+      process.stderr.write(`${rendered ?? FRAMEWORK_FLAG_ERROR}\n`);
+      process.exitCode = 2;
+      return;
+    }
+    if (error.code === "commander.unknownCommand") {
+      const { curatedSuggestions, nounVerbMap, resolveUnknownCommand } =
+        await import("./kernel/project/cli/suggest.js");
       const { stripGlobalFlags } = await import(
         "./kernel/project/cli/globalFlags.js"
       );
@@ -244,24 +422,28 @@ async function handleProgramError(
       if (unknown) {
         // Route through the same PragmaError + renderers as every other error,
         // so the plain path gets the `Error:` prefix and the shared "Did you
-        // mean?" list instead of a second, inline rendering.
+        // mean?" list instead of a second, inline rendering — and an explicit
+        // machine format gets the same envelope every other usage error
+        // emits (the kernel's one gate+renderer decision; plain and json
+        // bytes unchanged by construction).
         const [
           { PragmaError },
-          { renderErrorPlain, renderErrorJson },
+          { renderErrorForFormat, renderErrorPlain },
           { suggestNames },
         ] = await Promise.all([
           import("./kernel/error/PragmaError.js"),
           import("./kernel/error/renderError.js"),
           import("./kernel/project/cli/suggestNames.js"),
         ]);
-        const suggestions = suggestNames(unknown.token, [
-          ...unknown.candidates,
-        ]);
+        const curated = curatedSuggestions(unknown.token);
+        const suggestions = curated
+          ? [...curated]
+          : suggestNames(unknown.token, [...unknown.candidates]);
         const unknownError = PragmaError.unknownVerb(unknown.token, {
           suggestions,
         });
         process.stderr.write(
-          `${jsonMode ? renderErrorJson(unknownError) : renderErrorPlain(unknownError)}\n`,
+          `${renderErrorForFormat(unknownError, format) ?? renderErrorPlain(unknownError)}\n`,
         );
       }
       process.exitCode = 2;
@@ -269,19 +451,22 @@ async function handleProgramError(
     }
 
     // Other usage errors (missing argument, unknown option, bad choice). Under
-    // --format json these route through the same error envelope agents parse.
-    if (jsonMode) {
-      const [{ PragmaError }, { renderErrorJson }] = await Promise.all([
-        import("./kernel/error/PragmaError.js"),
-        import("./kernel/error/renderError.js"),
-      ]);
-      const message = error.message.replace(/^error:\s*/i, "");
-      process.stderr.write(
-        `${renderErrorJson(new PragmaError({ code: "INVALID_INPUT", message }))}\n`,
-      );
-    } else {
-      process.stderr.write(`${error.message}\n`);
-    }
+    // an explicit --format json/llm these route through the same error
+    // envelope agents parse (the kernel's one gate+renderer decision — the
+    // llm half used to split this one taxonomy class: an excess positional
+    // enveloped while an unknown option stayed raw prose).
+    const [{ PragmaError }, { renderErrorForFormat }] = await Promise.all([
+      import("./kernel/error/PragmaError.js"),
+      import("./kernel/error/renderError.js"),
+    ]);
+    const rendered = renderErrorForFormat(
+      new PragmaError({
+        code: "INVALID_INPUT",
+        message: error.message.replace(/^error:\s*/i, ""),
+      }),
+      format,
+    );
+    process.stderr.write(`${rendered ?? error.message}\n`);
     process.exitCode = 2;
     return;
   }
@@ -302,7 +487,7 @@ async function handleProgramError(
           error instanceof Error ? error.message : String(error),
         );
   process.stderr.write(
-    `${jsonMode ? renderErrorJson(pragmaError) : renderErrorPlain(pragmaError)}\n`,
+    `${format === "json" ? renderErrorJson(pragmaError) : renderErrorPlain(pragmaError)}\n`,
   );
   process.exitCode = mapExitCode(pragmaError.code);
 }

package/src/capabilities/block.parity.test.ts

@@ -138,9 +138,12 @@ ds:Component a owl:Class .
     try {
       const rows = (await verb("list").run({}, emptyRt)) as PackRow[];
       expect(rows).toEqual([]);
-      const plain = verb("list").output.formatters.plain(rows);
-      expect(plain).toContain("No blocks in the store.");
-      expect(plain).toContain("pragma sources update");
+      // The same semantics, on the empty-state seam: the calm message + its
+      // runnable hint now reach the user via stderr (`emptyNotice`), keeping
+      // plain stdout pure data.
+      const notice = verb("list").output.formatters.emptyNotice?.(rows);
+      expect(notice).toContain("No blocks in the store.");
+      expect(notice).toContain("pragma sources update");
     } finally {
       (await emptyRt.store.get()).store.dispose();
     }

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

@@ -7,7 +7,7 @@
  */
 
 import { BIN_NAME } from "../../constants.js";
-import type { Formatters } from "../../kernel/spec/types.js";
+import type { Formatters } from "../../kernel/spec/index.js";
 import type { CapabilitiesData, ToolCategory } from "./types.js";
 
 /** Category display order for grouped tool listings. */

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

@@ -23,7 +23,7 @@
 
 import { BIN_NAME } from "../../constants.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
-import type { VerbSpec } from "../../kernel/spec/types.js";
+import type { VerbSpec } from "../../kernel/spec/index.js";
 import { capabilitiesFormatters } from "./capabilities.render.js";
 import type { CapabilitiesData } from "./types.js";
 

package/src/capabilities/capabilities/catalog.ts

@@ -15,8 +15,8 @@
  */
 
 import { BIN_NAME, PROGRAM_DESCRIPTION, VERSION } from "../../constants.js";
-import { emitSurface } from "../../kernel/spec/emitSurface.js";
-import type { CapabilityModule } from "../../kernel/spec/types.js";
+import type { CapabilityModule } from "../../kernel/spec/index.js";
+import { emitSurface } from "../../kernel/spec/index.js";
 import { TOOL_HINTS } from "./hints.js";
 import type {
   CapabilitiesData,
@@ -91,7 +91,7 @@ export function buildDiscoverySequence(
       stage: 2,
       tool: "sources_status",
       purpose:
-        "See which pack is answering. A fresh install answers reads from the snapshot embedded in the binary and needs no build; only an `unavailable` status requires sources_update (confirm: true), which is a project that declared its own packs and has not built them.",
+        "See which pack is answering. A fresh install answers reads from the snapshot shipped with the CLI and needs no build; only an `unavailable` status requires sources_update (confirm: true), which is a project that declared its own packs and has not built them.",
     },
     {
       stage: 3,

package/src/capabilities/capabilities/hints.ts

@@ -58,7 +58,13 @@ export const TOOL_HINTS: Record<string, ToolHint> = {
   },
   colophon: {
     category: "read",
-    use_when: `Understanding how ${BIN_NAME} and the active domain are built — the toolchain + domain colophon, for onboarding or a demo`,
+    use_when:
+      "Understanding how the active domain is built — its declared colophon, for onboarding or a demo",
+  },
+  config_get: {
+    category: "read",
+    use_when:
+      "Reading ONE config field's effective value and the layer it came from — the single-value form of config_show",
   },
   config_show: {
     category: "read",
@@ -99,11 +105,6 @@ export const TOOL_HINTS: Record<string, ToolHint> = {
     use_when:
       "Exploring the full schema of a namespace by name — classes, properties, and hierarchy",
   },
-  ontology_show: {
-    category: "read",
-    use_when:
-      "Deprecated alias of ontology_lookup — exploring a namespace's schema (prefer ontology_lookup)",
-  },
   prompt_list: {
     category: "read",
     use_when: "Browsing the workflow prompt templates the active graph offers",
@@ -115,7 +116,7 @@ export const TOOL_HINTS: Record<string, ToolHint> = {
   },
   skill_list: {
     category: "read",
-    use_when: "Discovering agent skills provided by installed packages",
+    use_when: "Discovering agent skills provided by installed packs",
   },
   skill_lookup: {
     category: "read",
@@ -141,6 +142,25 @@ export const TOOL_HINTS: Record<string, ToolHint> = {
     category: "read",
     use_when: "Discovering which standard categories exist before filtering",
   },
+  concept_list: {
+    category: "read",
+    use_when:
+      "Browsing long-form design-system concepts (foundations, how-to guides, decision guides)",
+  },
+  concept_lookup: {
+    category: "read",
+    use_when: "Reading a concept's full Markdown documentation by name or IRI",
+  },
+  implementation_list: {
+    category: "read",
+    use_when:
+      "Finding which library implements a block, on which platform, and where its source lives",
+  },
+  implementation_libraries: {
+    category: "read",
+    use_when:
+      "Discovering which implementation libraries exist, and how much of the design system each covers",
+  },
   standard_sample: {
     category: "read",
     use_when:
@@ -176,6 +196,11 @@ export const TOOL_HINTS: Record<string, ToolHint> = {
     use_when:
       "Setting any config field by name — tier, channel, or detail (e.g. `config set tier apps/lxd`)",
   },
+  config_unset: {
+    category: "write",
+    use_when:
+      'Clearing a config field so the built-in default applies again — no value means "remove", this tool does',
+  },
   create_component: {
     category: "write",
     use_when: "Scaffolding a new component (React, Svelte, or Lit)",

package/src/capabilities/capabilities/index.ts

@@ -3,7 +3,7 @@
  * that replaces the retired `llm` tool.
  */
 
-import type { CapabilityModule } from "../../kernel/spec/types.js";
+import type { CapabilityModule } from "../../kernel/spec/index.js";
 import { capabilitiesSelfVerb } from "./capabilities.verb.js";
 
 /** The `capabilities` capability module (a single storeless self-verb). */