@canonical/pragma-cli 0.33.0 → 0.35.0

package/src/capabilities/surface.test.ts

@@ -1,11 +1,15 @@
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
+import { buildOptionInfo } from "@canonical/summon-core/projection";
 import { describe, expect, it } from "vitest";
+import { MCP_SERVER_NAME, VERSION } from "../constants.js";
 import { emitSurface } from "../kernel/spec/emitSurface.js";
 import {
   assertConforms,
   type Covenant,
 } from "../kernel/spec/surfaceConformance.js";
+import { projectMcp } from "../testing/helpers/projectMcp.js";
+import { CREATE_SURFACE } from "./create/createSurface.generated.js";
 import { capabilities } from "./index.js";
 
 /** The committed covenant, read from disk exactly as a consumer would. */
@@ -23,34 +27,52 @@ describe("surface conformance — capabilities ⊆ covenant (PROTECTED)", () =>
     expect(() => assertConforms(emitted, golden)).not.toThrow();
   });
 
-  it("emits config show + the one-command config set, in covenant order (field-verbs retired, B3)", () => {
+  it("emits the four config verbs — show, get, set, unset — in covenant order", () => {
     // AV-228 B3 retired the per-field `tier`/`channel`/`detail` setters; the
-    // config noun is now just the `show` reader and the `set <key> <value>` writer.
+    // config noun is the `show` dump, the `get <key>` single read, the
+    // `set <key> <value>` writer, and the `unset <key>` clearer. Reading one
+    // value and clearing one field are commands of their own — neither hides
+    // inside `show --format json` nor inside a reserved `set` value.
     expect(emitted.nouns.config?.verbs).toEqual([
       { v: "show", mcp: "config_show" },
+      { v: "get", args: ["<key>"], mcp: "config_get" },
       {
         v: "set",
         args: ["<key>", "<value>"],
         mutates: true,
         mcp: "config_set",
       },
+      {
+        v: "unset",
+        args: ["<key>"],
+        mutates: true,
+        mcp: "config_unset",
+      },
     ]);
     // info stays a data-only enrichment — its emitted verb is unchanged.
     expect(emitted.nouns.info?.verbs).toEqual([{ v: "info", mcp: "info" }]);
-    // Hidden meta verbs (__complete, mcp) are excluded from the surface.
-    expect(emitted.nouns.mcp).toBeUndefined();
+    // `version` is the command form of `--version`: one value, two spellings
+    // of the same read, and no tool — the version already rides `info`.
+    expect(emitted.nouns.version?.verbs).toEqual([
+      { v: "version", mcp: false },
+    ]);
+    // The server entry is a real noun/verb pair, emitted like any other and
+    // carrying no tool — it serves a protocol, it is not an agent tool.
+    expect(emitted.nouns.mcp?.verbs).toEqual([{ v: "serve", mcp: false }]);
+    // The completion resolver stays hidden — it is a protocol between the
+    // shell script and the bin, not a command anyone types.
     expect(emitted.nouns.__complete).toBeUndefined();
   });
 
-  it("emits the read nouns/verbs the packs add (block list hand-written, sample only where declared)", () => {
+  it("emits the read nouns/verbs the packs add (sample only where declared)", () => {
     expect(emitted.nouns.standard?.verbs.map((v) => v.v)).toEqual([
       "list",
       "categories",
       "lookup",
       "sample",
     ]);
-    // PR7 completes the surface: tier gains a bespoke single-name lookup;
-    // block/modifier/token gain no-argument samples (fixedCount).
+    // PR7 completed the surface; block/modifier/token carry no-argument
+    // samples (fixedCount), tier declares no sample.
     expect(emitted.nouns.tier?.verbs.map((v) => v.v)).toEqual([
       "list",
       "lookup",
@@ -60,16 +82,18 @@ describe("surface conformance — capabilities ⊆ covenant (PROTECTED)", () =>
       "lookup",
       "sample",
     ]);
+    // `token` is purely declarative since L-OPEN-9 removed `add-config`: the
+    // three read verbs its story compiles, and no mutation.
     expect(emitted.nouns.token?.verbs.map((v) => v.v)).toEqual([
       "list",
       "lookup",
       "sample",
-      "add-config",
     ]);
+    // block list is the story's compiled, unfiltered list (L-OPEN-9): no
+    // flags — the `--all-tiers` escape died with the hand-written filtering.
     expect(emitted.nouns.block?.verbs).toEqual([
       {
         v: "list",
-        flags: ["--all-tiers"],
         needsStore: true,
         mcp: "block_list",
       },
@@ -81,11 +105,11 @@ describe("surface conformance — capabilities ⊆ covenant (PROTECTED)", () =>
       },
       { v: "sample", needsStore: true, mcp: "block_sample" },
     ]);
-    // The bespoke tier lookup emits the SINGLE-name positional the covenant
-    // freezes (a pack lookup would emit the variadic `<name...>`).
+    // The tier lookup is the story's compiled lookup (L-OPEN-9), so it emits
+    // the variadic `<name...>` positional every pack lookup emits.
     expect(emitted.nouns.tier?.verbs).toContainEqual({
       v: "lookup",
-      args: ["<name>"],
+      args: ["<name...>"],
       needsStore: true,
       mcp: "tier_lookup",
     });
@@ -101,15 +125,8 @@ describe("surface conformance — capabilities ⊆ covenant (PROTECTED)", () =>
         needsStore: true,
         mcp: "ontology_lookup",
       },
-      // `show` is the deprecated alias of `lookup` (AV-228 B1) — same shape,
-      // both blessed in the covenant.
-      {
-        v: "show",
-        args: ["<prefix>"],
-        flags: ["--properties", "--full-uris", "--class"],
-        needsStore: true,
-        mcp: "ontology_show",
-      },
+      // One job, one spelling: `lookup` is the by-name read, and nothing
+      // else answers to it.
     ]);
     // skill discovery is storeless (filesystem) — no needsStore.
     expect(emitted.nouns.skill?.verbs).toEqual([
@@ -133,6 +150,92 @@ describe("surface conformance — capabilities ⊆ covenant (PROTECTED)", () =>
     ]);
   });
 
+  it("emits the L-CIS create noun — projected grammar, deep-equal to the covenant", () => {
+    // The create surface DERIVES from the generators' prompts (L-CIS): the
+    // framework tree segment is a required positional enum, component's flags
+    // are the framework union (incl. the svelte-only --use-ts-stories), and
+    // every flag AND positional token is the REGISTERED spelling (L-CIS-2) —
+    // a default-true confirm registers ONLY its `--no-<kebab>` form, and the
+    // args carry the kebab positional the usage line prints, so the covenant
+    // names `--no-with-styles` and `[component-path]`, never a
+    // `--with-styles` the CLI rejects or a `[componentPath]` its help never
+    // prints. Pin the three entries verbatim so a prompt edit that moves the
+    // covenant is SEEN.
+    expect(emitted.nouns.create?.verbs).toEqual([
+      {
+        v: "component",
+        args: ["<framework>", "[component-path]"],
+        flags: [
+          "--no-with-styles",
+          "--no-with-stories",
+          "--no-with-ssr-tests",
+          "--use-ts-stories",
+        ],
+        mutates: true,
+        mcp: "create_component",
+      },
+      {
+        v: "package",
+        flags: [
+          "--name",
+          "--type",
+          "--description",
+          "--with-react",
+          "--with-storybook",
+          "--with-cli",
+          "--with-pr-template",
+          "--no-run-install",
+        ],
+        mutates: true,
+        mcp: "create_package",
+      },
+      {
+        v: "application",
+        args: ["[app-path]"],
+        // ssr/router are GONE: always-on facts, not prompts — the pair had no
+        // reachable explicit form (only `--no-` spellings the generator's own
+        // guard rejected), so the projection no longer carries them.
+        flags: ["--no-forms", "--intl", "--relay", "--no-run-install"],
+        mutates: true,
+        mcp: "create_application",
+      },
+    ]);
+  });
+
+  it("every create covenant flag token is buildOptionInfo's primary registered long form (L-CIS-2)", () => {
+    // The derivation tie: the covenant's create tokens must be EXACTLY the
+    // long forms the single flag-shape authority yields for the projected
+    // prompts — the same expression both binaries register from — so the
+    // covenant can never again teach a spelling the CLI rejects (the
+    // round-15 F2 defect: kebab-cased param names blessed `--with-styles`
+    // and rejected the real `--no-with-styles`).
+    const registered = new Map<string, string>();
+    for (const surface of Object.values(CREATE_SURFACE)) {
+      for (const prompt of surface.prompts) {
+        if (prompt.positional === true) continue;
+        registered.set(
+          prompt.name,
+          buildOptionInfo(prompt).flags.split(" ")[0] as string,
+        );
+      }
+    }
+    for (const verb of emitted.nouns.create?.verbs ?? []) {
+      expect(verb.flags?.length ?? 0).toBeGreaterThan(0);
+      for (const token of verb.flags ?? []) {
+        expect([...registered.values()]).toContain(token);
+      }
+    }
+    // …and every non-positional projected prompt is named by some entry.
+    const covenantTokens = new Set(
+      (emitted.nouns.create?.verbs ?? []).flatMap((verb) => verb.flags ?? []),
+    );
+    for (const [name, token] of registered) {
+      expect(covenantTokens.has(token), `${name} → ${token} missing`).toBe(
+        true,
+      );
+    }
+  });
+
   it("emits the PR6 effect/diagnostic self-verbs (doctor, upgrade)", () => {
     // doctor is a storeless read self-verb — no args, no flags, no needsStore.
     expect(emitted.nouns.doctor?.verbs).toEqual([
@@ -163,20 +266,36 @@ describe("surface conformance — capabilities ⊆ covenant (PROTECTED)", () =>
         mutates: true,
         mcp: "setup",
       },
+      {
+        v: "config",
+        flags: ["--scope", "--global", "--local"],
+        mutates: true,
+        mcp: false,
+      },
+      {
+        v: "completions",
+        flags: ["--scope", "--global", "--local"],
+        mutates: true,
+        mcp: false,
+      },
+      {
+        v: "lsp",
+        flags: ["--scope", "--global", "--local"],
+        mutates: true,
+        mcp: false,
+      },
       {
         v: "mcp",
         flags: ["--scope", "--global", "--local"],
         mutates: true,
         mcp: false,
       },
-      { v: "completions", mutates: true, mcp: false },
       {
         v: "skills",
         flags: ["--scope", "--global", "--local"],
         mutates: true,
         mcp: false,
       },
-      { v: "lsp", mutates: true, mcp: false },
     ]);
   });
 
@@ -196,6 +315,8 @@ describe("surface conformance — capabilities ⊆ covenant (PROTECTED)", () =>
       "standard_sample",
       "tier_list",
       "config_show",
+      "config_get",
+      "config_unset",
       "colophon",
     ]) {
       expect(tools).toContain(tool);
@@ -209,14 +330,14 @@ describe("surface COMPLETE — emitted == covenant (PROTECTED)", () => {
   // The CLOSING direction: assertConforms already proves emitted ⊆ covenant;
   // this proves covenant ⊆ emitted, so together the tool sets are EQUAL — the
   // surface-complete milestone. After PR7, every covenant tool is realized.
-  it("emits every covenant tool (all 38) — set equality with the covenant", () => {
+  it("emits every covenant tool (all 42) — set equality with the covenant", () => {
     const emittedTools = new Set(emitted.mcpSurface.tools);
     const missing = golden.mcpSurface.tools.filter((t) => !emittedTools.has(t));
     expect(missing).toEqual([]);
     expect([...emitted.mcpSurface.tools].sort()).toEqual(
       [...golden.mcpSurface.tools].sort(),
     );
-    expect(emitted.mcpSurface.tools).toHaveLength(38);
+    expect(emitted.mcpSurface.tools).toHaveLength(42);
   });
 
   // The covenant edit: the non-tool MCP surface is frozen too.
@@ -230,4 +351,23 @@ describe("surface COMPLETE — emitted == covenant (PROTECTED)", () => {
       golden.mcpSurface.instructions,
     );
   });
+
+  // The L-PR6 covenant edit (PRA-107 ruling): the wire-identity RULE. The
+  // covenant states serverInfo as placeholders — a PROJECTION, deliberately not
+  // live values, so a release does not churn the covenant — and the live
+  // handshake is asserted to follow it: the server introduces itself with the
+  // distribution's declared name and the package version. The fork half of the
+  // same rule (a renamed distribution introduces itself under ITS name) is
+  // pinned in identity.test.ts, where the conf is mocked.
+  it("states the serverInfo projection rule and serves it on the wire", async () => {
+    expect(golden.mcpSurface.serverInfo).toEqual({
+      name: "<the declared distribution name>",
+      version: "<the package version>",
+    });
+
+    const mcp = await projectMcp([]);
+    const wire = mcp.serverInfo();
+    await mcp.cleanup();
+    expect(wire).toEqual({ name: MCP_SERVER_NAME, version: VERSION });
+  });
 });

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

@@ -0,0 +1,144 @@
+/**
+ * Tier-noun semantic parity (PROTECTED) — the `tier` story `pragma.conf.ts`
+ * declares, over a tier/block fixture graph (the standard-noun pattern).
+ *
+ * The hand-written `tier lookup` is gone (L-OPEN-9): both verbs compile from
+ * the declared story, so parity is asserted directly against the graph — every
+ * tier is reachable through list/lookup with the same names, addressable by
+ * name AND by prefixed IRI (the candidates completion now offers, D9-A), the
+ * `blocks` expand resolves the INVERSE path `^ds:tier` (the members scoped
+ * directly to the tier), a memberless tier still resolves, and a miss carries
+ * "did you mean?" suggestions like every declared lookup.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { compilePack } from "../kernel/packs/compile.js";
+import type { LookupOutput } from "../kernel/packs/resolveEntity.js";
+import type { PackRow } from "../kernel/packs/types.js";
+import { verbKey } from "../kernel/packs/uniqueness.js";
+import { DEFAULT_PREFIX_MAP } from "../kernel/render/prefixes.js";
+import type { PragmaRuntime } from "../kernel/runtime/types.js";
+import type { VerbSpec } from "../kernel/spec/types.js";
+import { buildFixtureRuntime } from "../testing/helpers/packRuntime.js";
+import { declaredStories } from "./distribution.js";
+
+const tierPack = declaredStories.get("tier");
+if (!tierPack) {
+  throw new Error('pragma.conf.ts declares no story for "tier"');
+}
+
+const DS = "https://ds.canonical.com/";
+const PREFIXES = {
+  ds: DS,
+  owl: "http://www.w3.org/2002/07/owl#",
+  rdfs: "http://www.w3.org/2000/01/rdf-schema#",
+  xsd: "http://www.w3.org/2001/XMLSchema#",
+};
+
+const TTL = `
+@prefix ds: <${DS}> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+ds:Tier a owl:Class .
+ds:Component a owl:Class .
+ds:name a owl:DatatypeProperty ; rdfs:range xsd:string .
+ds:tier a owl:ObjectProperty ; rdfs:range ds:Tier .
+
+ds:global a ds:Tier ; ds:name "global" .
+ds:apps a ds:Tier ; ds:name "apps" .
+ds:apps_lxd a ds:Tier ; ds:name "apps/lxd" .
+
+ds:button a ds:Component ; ds:name "Button" ; ds:tier ds:global .
+ds:modal a ds:Component ; ds:name "Modal" ; ds:tier ds:global .
+ds:lxdPanel a ds:Component ; ds:name "LXD Panel" ; ds:tier ds:apps_lxd .
+`;
+
+const verbs = () => compilePack(tierPack, "pragma.conf.ts", DEFAULT_PREFIX_MAP);
+const verb = (label: string) =>
+  verbs().find((v) => verbKey(v.path) === `tier ${label}`) as VerbSpec;
+
+let rt: PragmaRuntime;
+beforeAll(async () => {
+  ({ rt } = await buildFixtureRuntime({ ttl: TTL, prefixes: PREFIXES }));
+});
+afterAll(async () => {
+  (await rt.store.get()).store.dispose();
+});
+
+async function lookup(name: string): Promise<Record<string, unknown>> {
+  const out = (await verb("lookup").run({ name: [name] }, rt)) as LookupOutput;
+  expect(out.errors).toEqual([]);
+  return out.results.at(0) as Record<string, unknown>;
+}
+
+/** The `blocks` expand's child names, sorted (the sub-SELECT is unordered). */
+function blockNames(entity: Record<string, unknown>): string[] {
+  return (entity.blocks as { name: string }[]).map((b) => b.name).sort();
+}
+
+describe("tier list parity", () => {
+  it("lists every tier, name-ordered, with the uniform row shape", async () => {
+    const rows = (await verb("list").run({}, rt)) as PackRow[];
+    expect(rows.map((r) => r.name)).toEqual(["apps", "apps/lxd", "global"]);
+    for (const row of rows) {
+      expect(row.uri).toBeTruthy();
+    }
+  });
+});
+
+describe("tier lookup parity — the declared story's compiled lookup", () => {
+  it("resolves a tier by name and expands the blocks scoped directly to it", async () => {
+    const tier = await lookup("apps/lxd");
+    expect(tier.uri).toBe(`${DS}apps_lxd`);
+    expect(tier.name).toBe("apps/lxd");
+    // The `blocks` expand walks the INVERSE `^ds:tier` path (contract:
+    // `PackExpand.relation` admits property paths), so only the DIRECT
+    // members appear — no chain inheritance.
+    expect(blockNames(tier)).toEqual(["LXD Panel"]);
+    const global = await lookup("global");
+    expect(blockNames(global)).toEqual(["Button", "Modal"]);
+  });
+
+  it("a memberless tier still resolves, with an empty blocks expand", async () => {
+    const apps = await lookup("apps");
+    expect(apps.name).toBe("apps");
+    expect(apps.blocks).toEqual([]);
+    // The empty expand renders as an OMITTED section (the generic renderers'
+    // behavior for every declared noun), not a placeholder line.
+    const out = (await verb("lookup").run({ name: ["apps"] }, rt)) as never;
+    expect(verb("lookup").output.formatters.llm(out)).not.toContain("Blocks");
+  });
+
+  it("resolves the same tier by prefixed IRI — the candidates completion offers (D9-A)", async () => {
+    // Completion for the declared lookup serves index entity NAMES (prefixed
+    // IRIs); a candidate is only honest if the lookup resolves it.
+    const byIri = await lookup("ds:apps_lxd");
+    expect(byIri.name).toBe("apps/lxd");
+    expect(byIri.uri).toBe(`${DS}apps_lxd`);
+  });
+
+  it("resolves a variadic batch in one call", async () => {
+    const out = (await verb("lookup").run(
+      { name: ["global", "apps"] },
+      rt,
+    )) as LookupOutput;
+    expect(out.results.map((r) => r.name)).toEqual(["global", "apps"]);
+  });
+
+  it("a miss fails ENTITY_NOT_FOUND with a near-miss suggestion (B6 parity kept)", async () => {
+    // The bespoke lookup earned "did you mean?" in B6; the declared path keeps
+    // it — suggestions come from the same name list every declared lookup uses.
+    let caught: unknown;
+    try {
+      await verb("lookup").run({ name: ["apps/lxdd"] }, rt);
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toMatchObject({ code: "ENTITY_NOT_FOUND" });
+    expect((caught as { suggestions: string[] }).suggestions).toContain(
+      "apps/lxd",
+    );
+  });
+});

package/src/capabilities/upgrade/runUpgrade.ts

@@ -21,13 +21,15 @@
  */
 
 import { $, exec, gen, info, type Task, warn } from "@canonical/task";
-import type { PragmaRuntime } from "../../kernel/runtime/types.js";
-import { assertExecOk, guardMissingBinary } from "../shared/assertExecOk.js";
+import type { PragmaRuntime } from "../../kernel/runtime/index.js";
 import {
+  assertExecOk,
+  checkRegistryVersion,
   detectInstallSource,
+  guardMissingBinary,
+  PRAGMA_PACKAGE,
   pmUpdateCommand,
-} from "../shared/packageManager.js";
-import { checkRegistryVersion, PRAGMA_PACKAGE } from "../shared/registry.js";
+} from "../shared/index.js";
 import type { UpgradeData } from "./types.js";
 
 /**
@@ -61,9 +63,7 @@ export async function runUpgrade(
       executed: false,
     };
     return gen(function* () {
-      yield* $(
-        warn("Could not reach the registry — skipped the update check."),
-      );
+      yield* $(warn("Cannot reach the registry — skipped the update check."));
       return data;
     });
   }
@@ -97,7 +97,7 @@ export async function runUpgrade(
   const bin = parts[0] ?? "npm";
   const args = parts.slice(1);
   // Guard the spawn: an absent package manager (`bin` not on PATH) REJECTS the
-  // exec with ENOENT, which would collapse to INTERNAL_ERROR ("please report
+  // exec with ENOENT, which would collapse to INTERNAL_ERROR ("report
   // this issue"). Surface it as a named "`<pm>` not found on PATH" instead.
   return guardMissingBinary(
     bin,

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

@@ -7,15 +7,15 @@
  */
 
 import chalk from "chalk";
-import type { Formatters } from "../../kernel/spec/types.js";
-import { PRAGMA_PACKAGE } from "../shared/registry.js";
+import type { Formatters } from "../../kernel/spec/index.js";
+import { PRAGMA_PACKAGE } from "../shared/index.js";
 import type { UpgradeData } from "./types.js";
 
 export const upgradeFormatters: Formatters<UpgradeData> = {
   plain(data) {
     const lines = [`Installed via: ${data.pm}`];
     if (data.offline) {
-      lines.push("Could not reach the registry — try again later.");
+      lines.push("Cannot reach the registry — try again later.");
       return lines.join("\n");
     }
     if (data.alreadyLatest) {
@@ -40,8 +40,7 @@ export const upgradeFormatters: Formatters<UpgradeData> = {
   },
 
   llm(data) {
-    if (data.offline)
-      return "Upgrade check failed: could not reach the registry.";
+    if (data.offline) return "Upgrade check failed: cannot reach the registry.";
     if (data.alreadyLatest) {
       return `Already at the latest version (${data.current}).`;
     }

package/src/capabilities/upgrade/upgrade.test.ts

@@ -199,10 +199,10 @@ describe("assertExecOk — the exec-exitCode guard", () => {
     }
     const err = asPragmaError(thrown);
     // A denied `npm i -g` is user-fixable, NOT a bug — so it must not tell the
-    // user to "please report this issue" (that is INTERNAL_ERROR's recovery).
+    // user to "report this issue" (that is INTERNAL_ERROR's recovery).
     expect(err.code).toBe("UNSUPPORTED");
     expect(err.recovery?.message).not.toContain("report this issue");
-    expect(err.recovery?.message).toMatch(/permissions or network/i);
+    expect(err.recovery?.message).toMatch(/elevated privileges/i);
     // Surfaces the command + exit code + the captured stderr (trimmed).
     expect(err.message).toContain("npm i -g @canonical/pragma-cli");
     expect(err.message).toContain("code 13");
@@ -276,7 +276,7 @@ describe("upgrade — a failed exec maps to an actionable runtime error (exit 1)
 
   it("a missing-binary spawn (ENOENT) at a guarded site is a named UNSUPPORTED, not INTERNAL_ERROR", async () => {
     // The same wrapper `runUpgrade`/`setupLsp` apply: a spawn ENOENT REJECTS the
-    // exec, which used to collapse to INTERNAL_ERROR ("please report this issue").
+    // exec, which used to collapse to INTERNAL_ERROR ("report this issue").
     // `guardMissingBinary` names it instead.
     const thrown = await runToError(
       failVerbWith((_p, rt) =>

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

@@ -14,20 +14,24 @@
  */
 
 import type { Task } from "@canonical/task";
+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 type { UpgradeData } from "./types.js";
 import { upgradeFormatters } from "./upgrade.render.js";
 
 const upgradeVerb: VerbSpec<Record<string, unknown>, UpgradeData> = {
   path: ["upgrade"],
-  summary: "Upgrade the pragma CLI to the latest version.",
+  summary: `Upgrade the ${BIN_NAME} CLI to the latest version.`,
   doc: "Checks the registry for the active channel's latest release and runs your package manager's global-update command. Preview the update before applying it.",
   params: [],
   output: { formatters: upgradeFormatters },
   examples: [
-    { cmd: "pragma upgrade" },
-    { cmd: "pragma upgrade --dry-run", note: "show the delta and the command" },
+    { cmd: `${BIN_NAME} upgrade` },
+    {
+      cmd: `${BIN_NAME} upgrade --dry-run`,
+      note: "show the delta and the command",
+    },
   ],
   capability: {
     needsStore: false,

package/src/capabilities/version/index.ts

@@ -0,0 +1,12 @@
+/**
+ * The `version` capability barrel — the command form of `--version`.
+ */
+
+import type { CapabilityModule } from "../../kernel/spec/index.js";
+import { versionVerbSpec } from "./version.verb.js";
+
+/** The `version` capability module. */
+export const versionModule: CapabilityModule = {
+  name: "version",
+  verbs: [versionVerbSpec],
+};

package/src/capabilities/version/version.test.ts

@@ -0,0 +1,66 @@
+/**
+ * `pragma version` — the command form of `--version`.
+ *
+ * The verb exists because users type it; the ONLY thing worth pinning is that
+ * it is not a second answer to the same question. The process-boundary cell
+ * compares the two spellings byte for byte through the shipped entry, so a
+ * change to either one that does not change the other reddens here. The rest
+ * pins the covenant slice and the storeless, tool-free shape.
+ */
+
+import { describe, expect, it } from "vitest";
+import { VERSION } from "../../constants.js";
+import { executeVerb } from "../../kernel/project/cli/dispatch.js";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import type { GlobalFlags } from "../../kernel/runtime/types.js";
+import { emitVerb } from "../../kernel/spec/emitSurface.js";
+import { runCli } from "../../testing/helpers/runCli.js";
+import { versionModule } from "./index.js";
+
+const FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "plain",
+  verbose: false,
+};
+const REAL = { dryRun: false, undo: false, yes: false };
+const versionVerb = versionModule.verbs[0];
+
+describe("version — covenant-exact emission (PROTECTED)", () => {
+  it("emits a no-argument self-verb with NO tool", () => {
+    // The version already rides `info` and the MCP handshake's serverInfo, so
+    // a tool here would be a third way to ask one question.
+    expect(emitVerb(versionVerb)).toEqual({ v: "version", mcp: false });
+  });
+});
+
+describe("version — one value, two spellings of the same read", () => {
+  it("prints the version and never boots the store", async () => {
+    const rt = bootRuntime(FLAGS, process.cwd());
+    const outcome = await executeVerb(versionVerb, {}, REAL, rt);
+    expect(outcome.stdout).toBe(`${VERSION}\n`);
+    expect(outcome.exitCode).toBe(0);
+    expect(rt.store.booted).toBe(false);
+  });
+
+  it("json carries the value under a named field, not a bare scalar", async () => {
+    const outcome = await executeVerb(
+      versionVerb,
+      {},
+      REAL,
+      bootRuntime({ ...FLAGS, format: "json" }, process.cwd()),
+    );
+    expect(JSON.parse(outcome.stdout ?? "").data).toEqual({
+      version: VERSION,
+    });
+  });
+
+  it("the verb and the flag print the SAME bytes through the shipped entry", () => {
+    const fromVerb = runCli(["version"]);
+    const fromFlag = runCli(["--version"]);
+    expect(fromVerb.exitCode).toBe(0);
+    expect(fromFlag.exitCode).toBe(0);
+    expect(fromVerb.stdout).toBe(fromFlag.stdout);
+    expect(fromVerb.stdout).toBe(`${VERSION}\n`);
+  });
+});