@canonical/pragma-cli 0.30.0 → 0.31.0

package/src/domains/info/operations/collectEntityCounts.test.ts

@@ -0,0 +1,156 @@
+import type { Store } from "@canonical/ke";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { createTestStore, DS_ALL_TTL } from "#testing";
+import listBlocks from "../../block/operations/list.js";
+import listModifiers from "../../modifier/operations/list.js";
+import { TTL_PREFIXES } from "../../shared/prefixes.js";
+import { standardPack } from "../../shared/stories/pack/bundled/standardPack.js";
+import runSelectQuery from "../../shared/stories/pack/runSelectQuery.js";
+import type { FilterConfig } from "../../shared/types/index.js";
+import listTokens from "../../token/operations/list.js";
+import { collectEntityCounts } from "./collectEntityCounts.js";
+
+/**
+ * The user-facing standard row count: the bundled pack's list query is
+ * what `standard list` serves since the standard cutover, so the info
+ * count must stay in lockstep with it (same WHERE grain the retired
+ * listStandards op used, including the OPTIONAL fan-out).
+ */
+async function countStandardRows(store: Store): Promise<number> {
+  const rows = await runSelectQuery(store, standardPack.list.query, "test");
+  return rows.length;
+}
+
+let store: Store;
+let cleanup: () => void;
+
+beforeAll(async () => {
+  const result = await createTestStore({ ttl: DS_ALL_TTL });
+  store = result.store;
+  cleanup = result.cleanup;
+});
+
+afterAll(() => cleanup());
+
+// The block count is the only filtered count, so its parity must hold under
+// every tier/channel combination the list op supports.
+const configs: Record<string, FilterConfig> = {
+  "no tier, prerelease": { tier: undefined, channel: "prerelease" },
+  "no tier, normal": { tier: undefined, channel: "normal" },
+  "global tier": { tier: "global", channel: "prerelease" },
+  "apps/lxd tier": { tier: "apps/lxd", channel: "normal" },
+};
+
+describe("collectEntityCounts", () => {
+  it.each(
+    Object.entries(configs),
+  )("matches legacy list-op lengths for %s", async (_label, config) => {
+    const counts = await collectEntityCounts(store, config);
+
+    expect(counts.blocks).toBe((await listBlocks(store, config)).length);
+    expect(counts.standards).toBe(await countStandardRows(store));
+    expect(counts.modifierFamilies).toBe((await listModifiers(store)).length);
+    expect(counts.tokens).toBe((await listTokens(store)).length);
+  });
+
+  it("returns positive counts on the full fixture", async () => {
+    const counts = await collectEntityCounts(store, {
+      tier: undefined,
+      channel: "prerelease",
+    });
+
+    expect(counts.blocks).toBeGreaterThan(0);
+    expect(counts.standards).toBeGreaterThan(0);
+    expect(counts.modifierFamilies).toBeGreaterThan(0);
+    expect(counts.tokens).toBeGreaterThan(0);
+  });
+});
+
+// A dedicated fan-out store (kept separate from the shared dsFixtures so its
+// enriched cardinality does not ripple into other suites). Every entity fans
+// its list op to MORE rows than there are distinct subjects, which is exactly
+// where a single-variable `COUNT(DISTINCT ?subject)` would undercount — so
+// these fixtures pin the grain-faithful subquery counts (FIX 4).
+const FAN_OUT_TTL = `
+${TTL_PREFIXES}
+
+# One block asserted as TWO types -> two GROUP BY (?component ?type ?name ?tier)
+# groups, so listBlocks emits two rows for a single subject.
+ds:fanout.multitype a ds:Component, ds:Pattern ;
+  ds:name "MultiType" ;
+  ds:tier ds:global ;
+  ds:release ds:stable .
+
+# A beta-only single-type block -> present under prerelease, filtered under
+# normal, so the block count also tracks channel scoping.
+ds:fanout.solo a ds:Component ;
+  ds:name "Solo" ;
+  ds:tier ds:global ;
+  ds:release ds:beta .
+
+# One modifier family with TWO names -> two GROUP BY (?family ?name) groups.
+ds:fanout.family a ds:ModifierFamily ;
+  ds:name "Alpha", "Beta" .
+
+# One standard in TWO categories -> the OPTIONAL hasCategory fans two rows.
+cs:fanout_cat_a a cs:Category ; cs:slug "cat-a" .
+cs:fanout_cat_b a cs:Category ; cs:slug "cat-b" .
+cs:fanout_std a cs:CodeStandard ;
+  cs:name "fanout/standard" ;
+  cs:description "A standard in two categories." ;
+  cs:hasCategory cs:fanout_cat_a, cs:fanout_cat_b .
+
+# One token with TWO token types -> the OPTIONAL tokenType fans two rows.
+ds:fanout_tt_a a ds:TokenType ; rdfs:label "TypeA" .
+ds:fanout_tt_b a ds:TokenType ; rdfs:label "TypeB" .
+ds:fanout.token a ds:Token ;
+  ds:tokenId "fanout.token" ;
+  ds:tokenType ds:fanout_tt_a, ds:fanout_tt_b .
+`;
+
+describe("collectEntityCounts fan-out parity", () => {
+  let fanStore: Store;
+  let fanCleanup: () => void;
+
+  beforeAll(async () => {
+    const result = await createTestStore({ ttl: FAN_OUT_TTL });
+    fanStore = result.store;
+    fanCleanup = result.cleanup;
+  });
+
+  afterAll(() => fanCleanup());
+
+  const fanConfigs: Record<string, FilterConfig> = {
+    prerelease: { tier: undefined, channel: "prerelease" },
+    normal: { tier: undefined, channel: "normal" },
+  };
+
+  it.each(
+    Object.entries(fanConfigs),
+  )("each count equals its legacy list-op length under %s channel", async (_label, config) => {
+    const counts = await collectEntityCounts(fanStore, config);
+
+    expect(counts.blocks).toBe((await listBlocks(fanStore, config)).length);
+    expect(counts.standards).toBe(await countStandardRows(fanStore));
+    expect(counts.modifierFamilies).toBe(
+      (await listModifiers(fanStore)).length,
+    );
+    expect(counts.tokens).toBe((await listTokens(fanStore)).length);
+  });
+
+  it("actually fans each entity beyond its distinct-subject count", async () => {
+    // These are the cardinalities a naive `COUNT(DISTINCT ?subject)` would
+    // undercount (blocks 3 vs 2 subjects, families 2 vs 1, etc.).
+    const config: FilterConfig = { tier: undefined, channel: "prerelease" };
+    expect((await listBlocks(fanStore, config)).length).toBe(3);
+    expect((await listModifiers(fanStore)).length).toBe(2);
+    expect(await countStandardRows(fanStore)).toBe(2);
+    expect((await listTokens(fanStore)).length).toBe(2);
+
+    // And under normal channel the beta block drops out (2 block rows).
+    expect(
+      (await listBlocks(fanStore, { tier: undefined, channel: "normal" }))
+        .length,
+    ).toBe(2);
+  });
+});

package/src/domains/info/operations/collectEntityCounts.ts

@@ -0,0 +1,123 @@
+import type { Store } from "@canonical/ke";
+import { buildQuery } from "../../shared/buildQuery.js";
+import { buildFilters } from "../../shared/filters/buildFilters.js";
+import { P } from "../../shared/prefixes.js";
+import type { FilterConfig } from "../../shared/types/index.js";
+import type { EntityCounts } from "../types.js";
+
+/**
+ * Run a `COUNT` query and parse its single `?count` binding.
+ *
+ * SPARQL `COUNT` yields a typed literal serialized as a string, so the
+ * value is parsed defensively and falls back to `0` when the query does
+ * not resolve to a select result.
+ *
+ * @param store - The ke store to query.
+ * @param query - A `SELECT (COUNT(...) AS ?count)` query string.
+ * @returns The parsed count, or `0` when unavailable.
+ * @note Queries ke store
+ */
+async function countRows(store: Store, query: string): Promise<number> {
+  const result = await store.query(buildQuery(query));
+  if (result.type !== "select") return 0;
+  const first = result.bindings[0];
+  return first ? Number.parseInt(first.count ?? "0", 10) || 0 : 0;
+}
+
+/**
+ * Count blocks, standards, modifier families, and tokens for the
+ * `pragma llm` orientation summary.
+ *
+ * Each `COUNT` reproduces the row cardinality of the matching leaf list
+ * operation, so the results equal `(await listX(...)).length` exactly:
+ *
+ * - **blocks** count the distinct `(?component, ?type, ?name, ?tier)` groups
+ *   `listBlocks` emits via `GROUP BY ?component ?type ?name ?tier`, so a
+ *   `COUNT(*)` over a `SELECT DISTINCT` of that exact grain (incl.
+ *   `buildFilters` for identical tier/channel scoping). This stays exact even
+ *   for a block asserted as several types or tiers, which would fan a
+ *   single-variable `COUNT(DISTINCT ?component)` short of the grouped rows.
+ * - **modifier families** count the distinct `(?family, ?name)` groups
+ *   `listModifiers` emits via `GROUP BY ?family ?name`, so a `COUNT(*)` over a
+ *   `SELECT DISTINCT` of that grain — exact even for a family with two names.
+ * - **standards** and **tokens** have no `GROUP BY` and an `OPTIONAL` that
+ *   fans rows out, so `COUNT(*)` over the identical `WHERE` matches row for
+ *   row (including the fan-out).
+ *
+ * @note Queries ke store
+ *
+ * @param store - The ke store to query.
+ * @param config - Filter config providing tier and channel settings.
+ * @returns Entity counts matching the four leaf list operations' lengths.
+ */
+async function collectEntityCounts(
+  store: Store,
+  config: FilterConfig,
+): Promise<EntityCounts> {
+  const filterClauses = buildFilters(config);
+
+  const [blocks, standards, modifierFamilies, tokens] = await Promise.all([
+    countRows(
+      store,
+      `
+      SELECT (COUNT(*) AS ?count)
+      WHERE {
+        SELECT DISTINCT ?component ?type ?name ?tier
+        WHERE {
+          VALUES ?type { ${P.ds}Component ${P.ds}Pattern ${P.ds}Layout ${P.ds}Subcomponent }
+          ?component a ?type ;
+                     ${P.ds}name ?name ;
+                     ${P.ds}tier ?tier .
+          ${filterClauses}
+        }
+      }
+    `,
+    ),
+    countRows(
+      store,
+      `
+      SELECT (COUNT(*) AS ?count)
+      WHERE {
+        ?standard a ${P.cs}CodeStandard ;
+                  ${P.cs}name ?name ;
+                  ${P.cs}description ?description .
+        OPTIONAL {
+          ?standard ${P.cs}hasCategory ?cat .
+          ?cat ${P.cs}slug ?categoryName .
+        }
+      }
+    `,
+    ),
+    countRows(
+      store,
+      `
+      SELECT (COUNT(*) AS ?count)
+      WHERE {
+        SELECT DISTINCT ?family ?name
+        WHERE {
+          ?family a ${P.ds}ModifierFamily ;
+                  ${P.ds}name ?name .
+        }
+      }
+    `,
+    ),
+    countRows(
+      store,
+      `
+      SELECT (COUNT(*) AS ?count)
+      WHERE {
+        ?token a ${P.ds}Token ;
+               ${P.ds}tokenId ?tokenId .
+        OPTIONAL {
+          ?token ${P.ds}tokenType ?type .
+          ?type ${P.rdfs}label ?typeName .
+        }
+      }
+    `,
+    ),
+  ]);
+
+  return { blocks, standards, modifierFamilies, tokens };
+}
+
+export { collectEntityCounts };

package/src/domains/info/operations/index.ts

@@ -1,5 +1,6 @@
 /** @module Barrel for info operations. */
 
 export { default as checkRegistryVersion } from "./checkRegistryVersion.js";
+export { collectEntityCounts } from "./collectEntityCounts.js";
 export { default as collectInfo } from "./collectInfo.js";
 export { collectStoreSummary } from "./collectStoreSummary.js";

package/src/domains/info/types.ts

@@ -52,3 +52,16 @@ export interface StoreSummary {
   readonly tripleCount: number;
   readonly graphNames: readonly string[];
 }
+
+/**
+ * Entity counts for the `pragma llm` orientation summary.
+ *
+ * Mirrors the row cardinality of the four leaf list operations
+ * (`listBlocks`, `listStandards`, `listModifiers`, `listTokens`).
+ */
+export interface EntityCounts {
+  readonly blocks: number;
+  readonly standards: number;
+  readonly modifierFamilies: number;
+  readonly tokens: number;
+}

package/src/domains/llm/capabilities.test.ts

@@ -1,9 +1,14 @@
 import { describe, expect, it } from "vitest";
 import { VERSION } from "#constants";
+import { TOKEN_READ_SURFACE_ENABLED } from "../token/featureFlag.js";
 import { buildCapabilitiesCommand } from "./commands/index.js";
 import { TOOL_CATALOG } from "./data/index.js";
 import { buildCapabilitiesData } from "./mcp/index.js";
 
+// token_list, token_lookup, and token_sample are gated behind the token
+// read-surface feature flag.
+const EXPECTED_TOOL_COUNT = TOKEN_READ_SURFACE_ENABLED ? 34 : 31;
+
 describe("buildCapabilitiesData", () => {
   it("returns correct version", () => {
     const data = buildCapabilitiesData();
@@ -29,7 +34,7 @@ describe("buildCapabilitiesData", () => {
   it("includes every tool from TOOL_CATALOG", () => {
     const data = buildCapabilitiesData();
     expect(data.tools).toHaveLength(TOOL_CATALOG.length);
-    expect(data.tools).toHaveLength(30);
+    expect(data.tools).toHaveLength(EXPECTED_TOOL_COUNT);
   });
 
   it("every tool has a non-empty use_when", () => {
@@ -41,7 +46,7 @@ describe("buildCapabilitiesData", () => {
 
   it("counts match tool catalog category lengths", () => {
     const data = buildCapabilitiesData();
-    expect(data.counts.total).toBe(30);
+    expect(data.counts.total).toBe(EXPECTED_TOOL_COUNT);
     expect(data.counts.read).toBe(
       TOOL_CATALOG.filter((t) => t.category === "read").length,
     );
@@ -79,7 +84,22 @@ describe("buildCapabilitiesCommand", () => {
     expect(text).toContain("Discovery Sequence");
     expect(text).toContain("block_list");
     expect(text).toContain("read");
-    expect(text).toContain("30 tools");
+    expect(text).toContain(`${EXPECTED_TOOL_COUNT} tools`);
+  });
+
+  it("emits valid JSON when --format json is requested", async () => {
+    const cmd = buildCapabilitiesCommand();
+    const ctx = {
+      cwd: "/test",
+      globalFlags: { llm: false, format: "json" as const, verbose: false },
+    };
+
+    const result = await cmd.execute({}, ctx);
+    if (result.tag !== "output") throw new Error("Expected output result");
+
+    const text = result.render.plain(result.value) as string;
+    expect(() => JSON.parse(text)).not.toThrow();
+    expect(JSON.parse(text)).toMatchObject({ version: expect.any(String) });
   });
 
   it("does not require a store or runtime", async () => {

package/src/domains/llm/commands/capabilities.ts

@@ -1,4 +1,5 @@
 import {
+  type CommandContext,
   type CommandDefinition,
   type CommandResult,
   createOutputResult,
@@ -10,7 +11,8 @@ import { buildCapabilitiesData } from "../mcp/specs.js";
  * Builds the `pragma capabilities` command definition.
  *
  * Returns a static system map: conventions, tool catalog with behavioral
- * hints, discovery sequence, and output modes. No store needed.
+ * hints, discovery sequence, and output modes. No store needed. Honours
+ * `--format json` by emitting the structured payload so agents can parse it.
  *
  * @returns A command definition for `capabilities`.
  */
@@ -20,9 +22,16 @@ export default function buildCapabilitiesCommand(): CommandDefinition {
     description:
       "Discover conventions, available tools, and discovery sequence",
     parameters: [],
-    execute: async (): Promise<CommandResult> => {
+    execute: async (
+      _params: Record<string, unknown>,
+      ctx: CommandContext,
+    ): Promise<CommandResult> => {
       const data = buildCapabilitiesData();
-      return createOutputResult(data, { plain: renderCapabilities });
+      const asJson = ctx?.globalFlags?.format === "json";
+      return createOutputResult(data, {
+        plain: (value) =>
+          asJson ? JSON.stringify(value, null, 2) : renderCapabilities(value),
+      });
     },
   };
 }

package/src/domains/llm/commands/llm.ts

@@ -31,7 +31,11 @@ export default function buildLlmCommand(ctx: PragmaContext): CommandDefinition {
         decisionTrees: DECISION_TREES,
         commandReference: COMMAND_REFERENCE,
       };
-      return createOutputResult(data, { plain: renderLlmOrientation });
+      const asJson = ctx?.globalFlags?.format === "json";
+      return createOutputResult(data, {
+        plain: (value) =>
+          asJson ? JSON.stringify(value, null, 2) : renderLlmOrientation(value),
+      });
     },
   };
 }

package/src/domains/llm/data/commandReference.ts

@@ -1,3 +1,4 @@
+import { TOKEN_READ_SURFACE_ENABLED } from "../../token/featureFlag.js";
 import type { CommandRefEntry } from "../types.js";
 import { TOOL_CATALOG } from "./toolCatalog.js";
 
@@ -60,17 +61,25 @@ export const COMMAND_REFERENCE: readonly CommandRefEntry[] = [
     tokens: "~80",
     use_when: hintFor("modifier_lookup"),
   },
-  {
-    command: "token sample",
-    tokens: "~300",
-    use_when: hintFor("token_sample"),
-  },
-  { command: "token list", tokens: "~400", use_when: hintFor("token_list") },
-  {
-    command: "token lookup <name-or-iri...> --detailed",
-    tokens: "~150",
-    use_when: hintFor("token_lookup"),
-  },
+  ...(TOKEN_READ_SURFACE_ENABLED
+    ? ([
+        {
+          command: "token sample",
+          tokens: "~300",
+          use_when: hintFor("token_sample"),
+        },
+        {
+          command: "token list",
+          tokens: "~400",
+          use_when: hintFor("token_list"),
+        },
+        {
+          command: "token lookup <name-or-iri...> --detailed",
+          tokens: "~150",
+          use_when: hintFor("token_lookup"),
+        },
+      ] as const)
+    : []),
   { command: "tier list", tokens: "~50", use_when: hintFor("tier_list") },
   {
     command: "ontology list",

package/src/domains/llm/data/decisionTrees.ts

@@ -1,3 +1,4 @@
+import { TOKEN_READ_SURFACE_ENABLED } from "../../token/featureFlag.js";
 import type { DecisionTree } from "../types.js";
 
 /**
@@ -26,16 +27,20 @@ export const DECISION_TREES: readonly DecisionTree[] = [
     no  → standard list --category <cat> [~100]
           → standard lookup <std-iri...> --detailed [~400] Σ500`,
   },
-  {
-    intent: "Find a token",
-    tree: `? Know token IRI or name?
+  ...(TOKEN_READ_SURFACE_ENABLED
+    ? ([
+        {
+          intent: "Find a token",
+          tree: `? Know token IRI or name?
   yes → token lookup <name-or-iri...> --detailed [~150]
   no  → token list --category <cat> [~100]
         → token lookup <name-or-iri...> --detailed [~150] Σ250`,
-  },
+        },
+      ] as const)
+    : []),
   {
     intent: "Explore the design system",
-    tree: `first time → block sample / token sample / modifier sample [~300] → see real shapes
+    tree: `first time → block sample / ${TOKEN_READ_SURFACE_ENABLED ? "token sample / " : ""}modifier sample [~300] → see real shapes
 high-level → ontology list [~80] → ontology show <ns> [~300]
 modifiers  → modifier list [~100] → modifier lookup <name-or-iri...> [~80]
 tiers      → tier list [~50]

package/src/domains/llm/data/toolCatalog.ts

@@ -1,5 +1,7 @@
 /** Tool catalog with behavioral hints for agent orientation. */
 
+import { TOKEN_READ_SURFACE_ENABLED } from "../../token/featureFlag.js";
+
 export interface ToolEntry {
   readonly name: string;
   readonly category: "read" | "write" | "orientation" | "diagnostic";
@@ -49,18 +51,22 @@ export const TOOL_CATALOG: readonly ToolEntry[] = [
     use_when:
       "Need values and usage details for specific modifier families by name",
   },
-  {
-    name: "token_list",
-    category: "read",
-    use_when:
-      "Browsing design tokens, optionally filtered by category (color, spacing, etc.)",
-  },
-  {
-    name: "token_lookup",
-    category: "read",
-    use_when:
-      "Need theme values and resolution details for specific tokens by name or IRI",
-  },
+  ...(TOKEN_READ_SURFACE_ENABLED
+    ? ([
+        {
+          name: "token_list",
+          category: "read",
+          use_when:
+            "Browsing design tokens, optionally filtered by category (color, spacing, etc.)",
+        },
+        {
+          name: "token_lookup",
+          category: "read",
+          use_when:
+            "Need theme values and resolution details for specific tokens by name or IRI",
+        },
+      ] as const)
+    : []),
   {
     name: "tier_list",
     category: "read",
@@ -118,12 +124,16 @@ export const TOOL_CATALOG: readonly ToolEntry[] = [
     use_when:
       "See actual standard data shapes (with dos/donts) before querying — returns random instances each call",
   },
-  {
-    name: "token_sample",
-    category: "read",
-    use_when:
-      "See actual token data shapes (with theme values) before querying — returns random instances each call",
-  },
+  ...(TOKEN_READ_SURFACE_ENABLED
+    ? ([
+        {
+          name: "token_sample",
+          category: "read",
+          use_when:
+            "See actual token data shapes (with theme values) before querying — returns random instances each call",
+        },
+      ] as const)
+    : []),
   {
     name: "modifier_sample",
     category: "read",
@@ -160,6 +170,27 @@ export const TOOL_CATALOG: readonly ToolEntry[] = [
     use_when:
       "Scaffolding a new npm package with proper monorepo configuration",
   },
+  {
+    name: "create_application",
+    category: "write",
+    use_when:
+      "Scaffolding a new React application with SSR, routing, and optional Relay",
+  },
+  {
+    name: "create_domain",
+    category: "write",
+    use_when: "Scaffolding a new domain module inside an existing application",
+  },
+  {
+    name: "create_route",
+    category: "write",
+    use_when: "Scaffolding a new route inside an existing application",
+  },
+  {
+    name: "create_wrapper",
+    category: "write",
+    use_when: "Scaffolding a new wrapper component inside an application",
+  },
 
   // — Orientation —————————————————————————————————————————————————————————————
   {

package/src/domains/llm/formatters/orientation.ts

@@ -1,3 +1,4 @@
+import { TOKEN_READ_SURFACE_ENABLED } from "../../token/featureFlag.js";
 import type { LlmData } from "../types.js";
 
 /**
@@ -22,8 +23,11 @@ export default function renderLlmOrientation(data: LlmData): string {
   lines.push("");
   lines.push("## Context");
   lines.push(`tier: ${tierDisplay} | channel: ${ctx.channel}`);
+  const tokenCount = TOKEN_READ_SURFACE_ENABLED
+    ? `, ${ctx.counts.tokens} tokens`
+    : "";
   lines.push(
-    `data: ${ctx.counts.blocks} blocks, ${ctx.counts.standards} standards, ${ctx.counts.modifierFamilies} modifier families, ${ctx.counts.tokens} tokens`,
+    `data: ${ctx.counts.blocks} blocks, ${ctx.counts.standards} standards, ${ctx.counts.modifierFamilies} modifier families${tokenCount}`,
   );
   lines.push(`namespaces: ${ctx.namespaces.join(", ")}`);
   lines.push("");

package/src/domains/llm/llmCommand.test.ts

@@ -3,6 +3,7 @@ import type { Store } from "@canonical/ke";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { createTestStore, DS_ALL_TTL } from "#testing";
 import type { PragmaContext } from "../shared/context.js";
+import { TOKEN_READ_SURFACE_ENABLED } from "../token/featureFlag.js";
 import { buildLlmCommand } from "./commands/index.js";
 import type { LlmData } from "./types.js";
 
@@ -72,14 +73,21 @@ describe("buildLlmCommand", () => {
     expect(value.context.namespaces.length).toBeGreaterThan(0);
   });
 
-  it("includes all 5 decision trees", async () => {
+  it("includes all decision trees", async () => {
     const ctx = makeCtx();
     const cmd = buildLlmCommand(ctx);
     const { value, text } = await executeOutput(cmd, ctx);
-    expect(value.decisionTrees).toHaveLength(5);
+    // "Find a token" is gated behind the token read-surface feature flag.
+    expect(value.decisionTrees).toHaveLength(
+      TOKEN_READ_SURFACE_ENABLED ? 5 : 4,
+    );
     expect(text).toContain("Build a block");
     expect(text).toContain("Audit standards");
-    expect(text).toContain("Find a token");
+    if (TOKEN_READ_SURFACE_ENABLED) {
+      expect(text).toContain("Find a token");
+    } else {
+      expect(text).not.toContain("Find a token");
+    }
     expect(text).toContain("Explore the design system");
     expect(text).toContain("Configure");
   });

package/src/domains/llm/mcp/specs.ts

@@ -5,6 +5,7 @@
 import { VERSION } from "#constants";
 import { buildFilterConfig } from "../../shared/filters/index.js";
 import type { ToolSpec } from "../../shared/ToolSpec.js";
+import { TOKEN_READ_SURFACE_ENABLED } from "../../token/featureFlag.js";
 import {
   COMMAND_REFERENCE,
   DECISION_TREES,
@@ -43,14 +44,12 @@ function buildCapabilitiesData(): CapabilitiesData {
       {
         stage: 2,
         tool: "*_sample",
-        purpose:
-          "Call block_sample, standard_sample, token_sample, or modifier_sample to see real data shapes before querying. Prevents guessing at property names.",
+        purpose: `Call block_sample, standard_sample,${TOKEN_READ_SURFACE_ENABLED ? " token_sample," : ""} or modifier_sample to see real data shapes before querying. Prevents guessing at property names.`,
       },
       {
         stage: 3,
         tool: "domain tools",
-        purpose:
-          "Query specific entities — block_list, standard_lookup, token_list, etc. Use the use_when hints above to pick the right tool.",
+        purpose: `Query specific entities — block_list, standard_lookup, ${TOKEN_READ_SURFACE_ENABLED ? "token_list, " : ""}etc. Use the use_when hints above to pick the right tool.`,
       },
     ],
     tools: TOOL_CATALOG,