@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/capabilities/block/pack.ts

@@ -0,0 +1,155 @@
+/**
+ * The bundled `block` pack — the lookup verb only.
+ *
+ * `block lookup` is served over the GraphQL fetch path (ONE generated document
+ * over the `UIBlock` interface covering Component/Pattern/Layout/Subcomponent);
+ * `block list` deliberately stays HAND-WRITTEN (tier-chain inheritance + channel
+ * + `--all-tiers` — see ./blockList.verb). Base level mirrors the old summary
+ * view (name/tier/summary); the default is `detailed`, matching the old CLI
+ * which rendered anatomy and modifiers without a flag. A derived name that maps
+ * onto no schema field is omitted (OPTIONAL parity), so a graph lacking
+ * whenToUse/whenNotToUse degrades gracefully.
+ */
+
+import type { PackDefinition } from "../../kernel/packs/types.js";
+
+/**
+ * The bundled design-system domain colophon — the ontology + graph story,
+ * surfaced by `pragma colophon` after pragma's own. Authored on the flagship
+ * UI-block noun because `block` most embodies the design system; it narrates the
+ * DOMAIN (what the graph models), not the toolchain (pragma's built-in section).
+ */
+const DESIGN_SYSTEM_COLOPHON = `The Canonical design system is a **knowledge graph**, not a component library.
+Every block, token, modifier, standard, and tier is a node in an RDF store,
+described by the \`ds:\` ontology and queried the same way whether you reach it
+over GraphQL or raw SPARQL.
+
+## What the graph models
+
+- **Blocks** — components, patterns, layouts, and subcomponents (the \`ds:UIBlock\`
+  family). A block carries its anatomy, guidelines, and \`when to use\` / \`when
+  not to use\` narrative as graph properties, not prose in a wiki.
+- **Modifiers** — families of variant values (\`ds:hasModifierFamily\` →
+  \`ds:hasModifier\`) a block composes, so a variant is a relationship, not a
+  string.
+- **Tokens** — the themeable design values, resolved per theme.
+- **Standards** — the do / don't coding guidance, categorized and linked to the
+  blocks they govern.
+
+## How it fits together
+
+- **Tiers** are a hierarchy (\`global\` > \`apps\` > \`apps/lxd\`): a lower tier
+  inherits and overrides the blocks of its ancestors, so scoping a query to a
+  tier walks that chain.
+- **Channels** (\`normal\`, \`experimental\`, \`prerelease\`) gate visibility, so an
+  in-progress block never leaks into a stable answer.
+
+## Why RDF
+
+One graph makes every relationship first-class and queryable: \`block lookup\`
+follows edges to modifiers and subcomponents, \`graph query\` runs arbitrary
+SPARQL, and \`ontology show\` reads the schema itself. The store is built once
+by \`sources update\` and addressed by content hash, so the domain you query is
+exactly the domain that was published.`;
+
+export const blockPack: PackDefinition = {
+  noun: "block",
+  description: "Look up design system blocks.",
+  colophon: DESIGN_SYSTEM_COLOPHON,
+  lookup: {
+    source: "graphql",
+    toolDescription:
+      'Get detailed information about one or more design system blocks including anatomy, modifiers, and properties. Use when you need the full spec of specific blocks by name — detail: "summary" trims to the base view. Example: block_lookup { names: ["Button"] }.',
+    by: "ds:name",
+    types: ["ds:Component", "ds:Pattern", "ds:Layout", "ds:Subcomponent"],
+    graphqlType: "UIBlock",
+    fields: [
+      { name: "tier", property: "ds:tier", label: "Tier" },
+      {
+        name: "figmaLink",
+        property: "ds:figmaLink",
+        label: "Figma",
+        level: "detailed",
+      },
+    ],
+    sections: [
+      { name: "summary", property: "ds:summary", label: "Summary" },
+      {
+        name: "whenToUse",
+        property: "ds:whenToUse",
+        label: "When to use",
+        level: "detailed",
+      },
+      {
+        name: "whenNotToUse",
+        property: "ds:whenNotToUse",
+        label: "When not to use",
+        level: "detailed",
+      },
+      {
+        name: "guidelines",
+        property: "ds:guidelines",
+        label: "Guidelines",
+        level: "detailed",
+      },
+      {
+        name: "anatomyDsl",
+        property: "ds:anatomyDsl",
+        label: "Anatomy (DSL)",
+        kind: "code",
+        level: "detailed",
+      },
+      {
+        name: "anatomyClassic",
+        property: "ds:anatomyClassic",
+        label: "Anatomy (classic)",
+        kind: "code",
+        level: "detailed",
+      },
+    ],
+    expand: [
+      {
+        name: "modifierFamilies",
+        heading: "Modifier Families",
+        relation: "ds:hasModifierFamily",
+        level: "detailed",
+        select: [
+          { name: "name", property: "ds:name" },
+          {
+            name: "values",
+            relation: "ds:hasModifier",
+            select: [{ name: "name", property: "ds:name" }],
+          },
+        ],
+      },
+      {
+        name: "properties",
+        heading: "Properties",
+        relation: "ds:hasProperty",
+        kind: "table",
+        level: "detailed",
+        select: [
+          { name: "name", property: "ds:name" },
+          { name: "type", property: "ds:propertyType" },
+          { name: "optional", property: "ds:optional" },
+        ],
+      },
+      {
+        name: "subcomponents",
+        heading: "Subcomponents",
+        relation: "ds:hasSubcomponent",
+        level: "detailed",
+        select: [
+          { name: "name", property: "ds:name" },
+          { name: "uri", property: "ds:name", graphqlField: "uri" },
+        ],
+      },
+    ],
+    disclosure: { levels: ["summary", "detailed"], default: "detailed" },
+    sample: {
+      fixedCount: true,
+      toolDescription:
+        "Return randomly selected complete design-system blocks as exemplars. Use BEFORE writing queries to see actual data shapes, anatomy, and property names.",
+    },
+  },
+};

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

@@ -0,0 +1,180 @@
+/**
+ * Block content-parity (PROTECTED) — on a FIXTURE graph, not the live one.
+ *
+ * The hand-written block lookup is gone; parity is asserted against the fixture
+ * graph directly: Button and Modal resolve through the GraphQL `block lookup`
+ * with the same content a direct SPARQL oracle returns (summary, guidance,
+ * anatomy, tier, modifier families with values, properties, subcomponents). The
+ * fixture DECLARES whenToUse/whenNotToUse (which the live graph superseded with
+ * ds:usage), so those sections are exercised here. The hand-written `block list`
+ * is checked for its tier/channel filtering and --all-tiers.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import type { LookupOutput } from "../../kernel/packs/resolveEntity.js";
+import { verbKey } from "../../kernel/packs/uniqueness.js";
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import {
+  BLOCK_PREFIXES,
+  BLOCK_TTL,
+} from "../../testing/fixtures/blockGraph.js";
+import { buildFixtureRuntime } from "../../testing/helpers/packRuntime.js";
+import type { BlockRow } from "./blockList.verb.js";
+import { blockModule } from "./index.js";
+
+const DS = "https://ds.canonical.com/";
+
+const listVerb = blockModule.verbs.find(
+  (v) => verbKey(v.path) === "block list",
+) as VerbSpec;
+const lookupVerb = blockModule.verbs.find(
+  (v) => verbKey(v.path) === "block lookup",
+) as VerbSpec;
+
+let rt: PragmaRuntime;
+
+beforeAll(async () => {
+  ({ rt } = await buildFixtureRuntime({
+    ttl: BLOCK_TTL,
+    prefixes: BLOCK_PREFIXES,
+    detail: "detailed",
+  }));
+});
+
+afterAll(async () => {
+  (await rt.store.get()).store.dispose();
+});
+
+async function lookup(name: string): Promise<Record<string, unknown>> {
+  const out = (await lookupVerb.run({ name: [name] }, rt)) as LookupOutput;
+  expect(out.errors).toEqual([]);
+  return out.results.at(0) as Record<string, unknown>;
+}
+
+/** Oracle: a single scalar from the graph, queried directly. */
+async function oracle(subject: string, predicate: string): Promise<string> {
+  const result = await rt.query.sparql(
+    `SELECT ?v WHERE { <${subject}> ${predicate} ?v }`,
+  );
+  return result.type === "select" ? (result.bindings[0]?.v ?? "") : "";
+}
+
+describe("block lookup — Button content parity (GraphQL, detailed)", () => {
+  it("resolves the full Button spec with content matching the SPARQL oracle", async () => {
+    const button = await lookup("Button");
+    expect(button.uri).toBe(`${DS}button`);
+    expect(button.name).toBe("Button");
+    expect(button.tier).toBe(`${DS}global`);
+
+    // Guidance + anatomy sections — each cross-checked against the graph.
+    expect(button.summary).toBe(await oracle(`${DS}button`, "ds:summary"));
+    expect(button.whenToUse).toBe(await oracle(`${DS}button`, "ds:whenToUse"));
+    expect(button.whenNotToUse).toBe(
+      await oracle(`${DS}button`, "ds:whenNotToUse"),
+    );
+    expect(button.guidelines).toBe(
+      await oracle(`${DS}button`, "ds:guidelines"),
+    );
+    expect(button.anatomyDsl).toBe(
+      await oracle(`${DS}button`, "ds:anatomyDsl"),
+    );
+    expect(button.figmaLink).toBe(await oracle(`${DS}button`, "ds:figmaLink"));
+  });
+
+  it("resolves the nested modifier families with values (inverse union)", async () => {
+    const button = await lookup("Button");
+    const families = button.modifierFamilies as {
+      name: string;
+      values?: string[];
+    }[];
+    expect(families.map((f) => f.name).sort()).toEqual([
+      "density",
+      "importance",
+    ]);
+    const importance = families.find((f) => f.name === "importance");
+    expect(importance?.values?.sort()).toEqual(["primary", "secondary"]);
+  });
+
+  it("resolves properties and the subtype-scoped subcomponents identity field", async () => {
+    const button = await lookup("Button");
+    expect(button.properties).toEqual([
+      { name: "disabled", type: "boolean", optional: "true" },
+    ]);
+    expect(button.subcomponents).toEqual([
+      { name: "Button Icon", uri: `${DS}button.icon` },
+    ]);
+  });
+
+  it("renders every declared section in the llm output", async () => {
+    const out = (await lookupVerb.run(
+      { name: ["Button"] },
+      rt,
+    )) as LookupOutput;
+    const llm = lookupVerb.output.formatters.llm(out);
+    expect(llm).toContain("## Button");
+    expect(llm).toContain("### When to use");
+    expect(llm).toContain("### Anatomy (DSL)");
+    expect(llm).toContain("### Modifier Families");
+    expect(llm).toContain("primary");
+  });
+});
+
+describe("block lookup — Modal content parity (GraphQL, detailed)", () => {
+  it("resolves the full Modal spec (a different block, same document engine)", async () => {
+    const modal = await lookup("Modal");
+    expect(modal.uri).toBe(`${DS}modal`);
+    expect(modal.name).toBe("Modal");
+    expect(modal.summary).toBe(await oracle(`${DS}modal`, "ds:summary"));
+    expect(modal.whenToUse).toBe(await oracle(`${DS}modal`, "ds:whenToUse"));
+    const families = modal.modifierFamilies as {
+      name: string;
+      values?: string[];
+    }[];
+    expect(families.map((f) => f.name)).toEqual(["size"]);
+    expect(families[0]?.values?.sort()).toEqual(["large", "small"]);
+    expect(modal.properties).toEqual([
+      { name: "open", type: "boolean", optional: "false" },
+    ]);
+    // Modal has no subcomponents — the subtype-scoped selection is simply absent.
+    expect(modal.subcomponents).toEqual([]);
+  });
+});
+
+describe("block lookup — disclosure trims to the base view at summary", () => {
+  it("summary keeps name/tier/summary and drops the detailed sections/expands", async () => {
+    const out = (await lookupVerb.run(
+      { name: ["Button"] },
+      { ...rt, globalFlags: { ...rt.globalFlags, detail: "summary" } },
+    )) as LookupOutput;
+    const button = out.results.at(0) as Record<string, unknown>;
+    expect(button.name).toBe("Button");
+    expect(button.summary).toBeDefined();
+    expect(button.whenToUse).toBeUndefined();
+    expect(button.anatomyDsl).toBeUndefined();
+    expect(button.modifierFamilies).toBeUndefined();
+    expect(button.figmaLink).toBeUndefined();
+  });
+});
+
+describe("block list — hand-written tier/channel filtering", () => {
+  it("lists visible blocks with the summary row shape", async () => {
+    const rows = (await listVerb.run({}, rt)) as BlockRow[];
+    const byName = new Map(rows.map((r) => [r.name, r]));
+    expect([...byName.keys()].sort()).toEqual(["Button", "Modal"]);
+    const button = byName.get("Button");
+    expect(button?.type).toBe("component");
+    expect(button?.tier).toBe("global");
+    expect(button?.uri).toBe(`${DS}button`);
+    // GROUP_CONCAT of the family names (order-independent).
+    expect(button?.modifiers.split(", ").sort()).toEqual([
+      "density",
+      "importance",
+    ]);
+  });
+
+  it("--all-tiers returns the same global blocks (no tier configured)", async () => {
+    const rows = (await listVerb.run({ allTiers: true }, rt)) as BlockRow[];
+    expect(rows.map((r) => r.name).sort()).toEqual(["Button", "Modal"]);
+  });
+});

package/src/capabilities/block/tierChain.ts

@@ -0,0 +1,78 @@
+/**
+ * Tier-chain inheritance + channel visibility for the hand-written `block list`.
+ *
+ * Ported from the v1 filters. Setting a tier activates a parent-chain filter
+ * (`apps/lxd` → visible tiers `global`, `apps`, `apps/lxd`); the channel maps to
+ * the set of visible release levels. Both are generated SPARQL clauses composed
+ * only from validated pack terms — no user input reaches the query text (the
+ * tier value comes from config, the channel from a closed enum).
+ */
+
+import type { Channel } from "../../kernel/config/types.js";
+
+/** The `ds:` prefix — the store injects its PREFIX declaration. */
+const DS = "ds:";
+
+/** Release levels visible per channel setting. */
+export const CHANNEL_RELEASES: Record<Channel, readonly string[]> = {
+  normal: ["stable"],
+  experimental: ["stable", "experimental"],
+  prerelease: ["stable", "experimental", "alpha", "beta"],
+};
+
+/**
+ * The parent chain for a tier path.
+ *
+ * `apps/lxd` → `["global", "apps", "apps/lxd"]`; `undefined` → `[]` (all tiers).
+ */
+export function resolveTierChain(tierPath: string | undefined): string[] {
+  if (tierPath === undefined) return [];
+  const normalized = tierPath.trim().toLowerCase();
+  const chain: string[] = ["global"];
+  const segments = normalized.split("/");
+  for (let i = 0; i < segments.length; i++) {
+    const path = segments.slice(0, i + 1).join("/");
+    if (path !== "global") chain.push(path);
+  }
+  return chain;
+}
+
+/** A tier path's URI local name (slashes → underscores: `apps/lxd` → `apps_lxd`). */
+export function tierPathToLocal(tierPath: string): string {
+  return tierPath.trim().toLowerCase().replace(/\//g, "_");
+}
+
+/**
+ * A SPARQL FILTER clause for tier visibility, or empty when no tier is set.
+ *
+ * @param tierPath - The configured tier path (e.g. `apps/lxd`) or `undefined`.
+ * @param varName - The SPARQL variable to filter (default `tier`).
+ */
+export function buildTierFilter(
+  tierPath: string | undefined,
+  varName = "tier",
+): string {
+  if (tierPath === undefined) return "";
+  const uriList = resolveTierChain(tierPath)
+    .map((t) => `${DS}${tierPathToLocal(t)}`)
+    .join(", ");
+  return `FILTER(?${varName} IN (${uriList}))`;
+}
+
+/**
+ * SPARQL clauses for channel visibility: bind `?release` if present, then filter
+ * to allowed levels OR unbound (unannotated blocks are treated as stable).
+ *
+ * @param channel - The configured channel.
+ * @param varName - The SPARQL variable to bind/filter (default `release`).
+ */
+export function buildChannelFilter(
+  channel: Channel,
+  varName = "release",
+): string {
+  const uriList = CHANNEL_RELEASES[channel].map((r) => `${DS}${r}`).join(", ");
+  return [
+    `OPTIONAL { ?component ${DS}release ?${varName} }`,
+    `FILTER(!BOUND(?${varName}) || ?${varName} IN (${uriList}))`,
+  ].join("\n    ");
+}

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

@@ -0,0 +1,89 @@
+/**
+ * Formatters for `pragma capabilities` — plain, llm, json.
+ *
+ * `plain` is ported from the old shell's `renderCapabilities`; `llm` is the same
+ * information as compact Markdown for agents; `json` is the raw structured map
+ * (what the MCP tool returns through the envelope).
+ */
+
+import type { Formatters } from "../../kernel/spec/types.js";
+import type { CapabilitiesData, ToolCategory } from "./types.js";
+
+/** Category display order for grouped tool listings. */
+const CATEGORY_ORDER: readonly ToolCategory[] = [
+  "read",
+  "write",
+  "orientation",
+  "diagnostic",
+];
+
+export const capabilitiesFormatters: Formatters<CapabilitiesData> = {
+  plain(data) {
+    const lines: string[] = [`pragma v${data.version}`, ""];
+
+    lines.push("Conventions");
+    lines.push(`  ${data.conventions.system}`);
+    lines.push(`  ${data.conventions.model}`);
+    lines.push(`  ${data.conventions.querying}`);
+    lines.push("");
+
+    lines.push("Discovery Sequence");
+    for (const stage of data.discovery_sequence) {
+      lines.push(`  ${stage.stage}. ${stage.tool} — ${stage.purpose}`);
+    }
+    lines.push("");
+
+    for (const category of CATEGORY_ORDER) {
+      const tools = data.tools.filter((tool) => tool.category === category);
+      lines.push(`${category} (${tools.length})`);
+      for (const tool of tools) {
+        lines.push(`  ${tool.name} — ${tool.use_when}`);
+      }
+      lines.push("");
+    }
+
+    const { counts } = data;
+    lines.push(
+      `${counts.total} tools: ${counts.read} read, ${counts.write} write, ${counts.orientation} orientation, ${counts.diagnostic} diagnostic`,
+    );
+    lines.push(
+      `output: ${data.limits.output_modes.join(", ")} | condensed: ${data.limits.condensed_available ? "yes" : "no"}`,
+    );
+    return lines.join("\n");
+  },
+
+  llm(data) {
+    const lines: string[] = [`# pragma v${data.version}`, ""];
+
+    lines.push("## Conventions");
+    lines.push(`- ${data.conventions.system}`);
+    lines.push(`- ${data.conventions.model}`);
+    lines.push(`- ${data.conventions.querying}`);
+    lines.push("");
+
+    lines.push("## Discovery sequence");
+    for (const stage of data.discovery_sequence) {
+      lines.push(`${stage.stage}. \`${stage.tool}\` — ${stage.purpose}`);
+    }
+    lines.push("");
+
+    for (const category of CATEGORY_ORDER) {
+      const tools = data.tools.filter((tool) => tool.category === category);
+      lines.push(`## ${category} (${tools.length})`);
+      for (const tool of tools) {
+        lines.push(`- \`${tool.name}\` — ${tool.use_when}`);
+      }
+      lines.push("");
+    }
+
+    const { counts } = data;
+    lines.push(
+      `${counts.total} tools: ${counts.read} read, ${counts.write} write, ${counts.orientation} orientation, ${counts.diagnostic} diagnostic.`,
+    );
+    return lines.join("\n").trimEnd();
+  },
+
+  json(data) {
+    return JSON.stringify(data);
+  },
+};

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

@@ -0,0 +1,131 @@
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { executeVerb } from "../../kernel/project/cli/dispatch.js";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import { emitSurface } from "../../kernel/spec/emitSurface.js";
+import type { GlobalFlags, VerbSpec } from "../../kernel/spec/types.js";
+import { capabilities } from "../index.js";
+import { capabilitiesSelfVerb } from "./capabilities.verb.js";
+import { buildCapabilitiesData, liveTools, mutatingTools } from "./catalog.js";
+import { TOOL_HINTS } from "./hints.js";
+import type { CapabilitiesData } from "./types.js";
+
+const NO_MUT = { dryRun: false, undo: false, yes: false };
+const FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "plain",
+  verbose: false,
+};
+
+const freshCwd = (): string => mkdtempSync(join(tmpdir(), "pragma-caps-"));
+const tools = liveTools(capabilities);
+const data = buildCapabilitiesData(capabilities);
+
+describe("capabilities catalog — grammar-derived, drift-guarded (PROTECTED)", () => {
+  it("every live tool has a TOOL_HINTS entry (no missing hint)", () => {
+    const missing = tools.filter((tool) => !(tool in TOOL_HINTS));
+    expect(missing).toEqual([]);
+  });
+
+  it("no TOOL_HINTS key is stale (every hint names a live tool)", () => {
+    const live = new Set(tools);
+    const stale = Object.keys(TOOL_HINTS).filter((name) => !live.has(name));
+    expect(stale).toEqual([]);
+  });
+
+  it("hint categories agree with the live surface (write ⟺ mutates)", () => {
+    const mutating = mutatingTools(capabilities);
+    for (const tool of tools) {
+      const isWrite = TOOL_HINTS[tool]?.category === "write";
+      expect(
+        isWrite,
+        `${tool}: hint category "${TOOL_HINTS[tool]?.category}" vs mutates=${mutating.has(tool)}`,
+      ).toBe(mutating.has(tool));
+    }
+  });
+
+  it("the catalog tool set equals the live emitted tool set, in order", () => {
+    expect(data.tools.map((tool) => tool.name)).toEqual(
+      emitSurface(capabilities).mcpSurface.tools,
+    );
+  });
+
+  it("every catalog tool carries a non-empty use_when", () => {
+    for (const tool of data.tools) {
+      expect(tool.use_when.length, tool.name).toBeGreaterThan(0);
+    }
+  });
+
+  it("counts are derived from the live categories (never pinned)", () => {
+    const { counts } = data;
+    expect(counts.total).toBe(data.tools.length);
+    expect(
+      counts.read + counts.write + counts.orientation + counts.diagnostic,
+    ).toBe(counts.total);
+    expect(counts.orientation).toBe(1); // exactly `capabilities`
+    expect(counts.diagnostic).toBe(2); // `doctor` + `info`
+    expect(counts.write).toBe(mutatingTools(capabilities).size);
+  });
+
+  it("the discovery sequence's sample stage lists the live *_sample tools", () => {
+    const samples = tools.filter((tool) => tool.endsWith("_sample"));
+    const sampleStage = data.discovery_sequence.find(
+      (stage) => stage.tool === "*_sample",
+    );
+    expect(sampleStage).toBeDefined();
+    for (const sample of samples) {
+      expect(sampleStage?.purpose).toContain(sample);
+    }
+  });
+
+  it("the discovery sequence pre-checks the store before the sample stage (store-blind guard)", () => {
+    const seq = data.discovery_sequence;
+    const storeCheck = seq.findIndex(
+      (stage) => stage.tool === "sources_status",
+    );
+    const sample = seq.findIndex((stage) => stage.tool === "*_sample");
+    // A cold agent must be told to verify/build the store BEFORE being sent into
+    // a store read, or it walks straight into STORE_UNAVAILABLE.
+    expect(storeCheck).toBeGreaterThanOrEqual(0);
+    expect(storeCheck).toBeLessThan(sample);
+    expect(seq[storeCheck]?.purpose).toContain("sources_update");
+  });
+
+  it("reports the v2 output limits (plain/json/llm, condensed retired)", () => {
+    expect(data.limits.output_modes).toEqual(["plain", "json", "llm"]);
+    expect(data.limits.condensed_available).toBe(false);
+  });
+
+  it("carries the three orientation conventions", () => {
+    expect(data.conventions.system.length).toBeGreaterThan(0);
+    expect(data.conventions.model).toContain("tier");
+    expect(data.conventions.querying).toContain("RDF");
+  });
+});
+
+describe("capabilities verb — storeless (PROTECTED)", () => {
+  it("does not construct the store", async () => {
+    const runtime = bootRuntime(FLAGS, freshCwd());
+    const outcome = await executeVerb(
+      capabilitiesSelfVerb as VerbSpec,
+      {},
+      NO_MUT,
+      runtime,
+    );
+    expect(outcome.exitCode).toBe(0);
+    expect(runtime.store.booted).toBe(false);
+  });
+
+  it("the verb run resolves the same data the catalog builds", async () => {
+    const result = (await capabilitiesSelfVerb.run(
+      {},
+      bootRuntime(FLAGS, freshCwd()),
+    )) as CapabilitiesData;
+    expect(result.tools.map((tool) => tool.name)).toEqual(
+      data.tools.map((tool) => tool.name),
+    );
+  });
+});

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

@@ -0,0 +1,48 @@
+/**
+ * The `capabilities` orientation verb (noun `capabilities`, self-verb).
+ *
+ * Storeless read: it returns the grammar-derived tool catalog + conventions +
+ * discovery sequence an agent reads at session start. It replaces the retired
+ * old-shell `llm` tool — the live-context half of that tool (tier/channel/entity
+ * counts) is deliberately DROPPED here (it would require a store boot at
+ * orientation) and lives in `info` / `config show` / `sources status` instead.
+ *
+ * `run` is a lazy thunk that dynamic-imports the catalog + the capability
+ * registry barrel, so building the command tree never pulls the derivation onto
+ * the `--help`/`__complete` fast path, and the tool never boots the store
+ * (`store.booted` stays false — the storeless-spy invariant).
+ */
+
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import { capabilitiesFormatters } from "./capabilities.render.js";
+import type { CapabilitiesData } from "./types.js";
+
+const capabilitiesVerb: VerbSpec<Record<string, unknown>, CapabilitiesData> = {
+  path: ["capabilities"],
+  summary:
+    "Discover pragma conventions, the annotated tool catalog, and the discovery sequence.",
+  doc: "Storeless orientation for agents. Returns the conventions (KG / tier-channel / SPARQL model), a 3-stage discovery sequence, and every live tool with a behavioural use_when hint and category — all derived from the live grammar, so it never drifts. Call it first at session start.",
+  params: [],
+  output: { formatters: capabilitiesFormatters },
+  examples: [
+    { cmd: "pragma capabilities", note: "the annotated tool catalog" },
+    { cmd: "pragma capabilities --format json", note: "the structured map" },
+  ],
+  capability: {
+    needsStore: false,
+    mutates: false,
+    mcp: {
+      expose: true,
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+  },
+  run: (_params, _runtime) =>
+    Promise.all([import("./catalog.js"), import("../index.js")]).then(
+      ([catalog, registry]) =>
+        catalog.buildCapabilitiesData(registry.capabilities),
+    ),
+};
+
+/** The `capabilities` verb, widened for registry composition. */
+export const capabilitiesSelfVerb = asVerb(capabilitiesVerb);