@canonical/pragma-cli 0.27.1-experimental.0 → 0.30.0

package/src/domains/llm/index.ts

@@ -1,8 +1,9 @@
 /**
  * @module LLM domain barrel.
  *
- * Provides the `pragma llm` command for LLM orientation context generation.
+ * Provides the `pragma capabilities` and `pragma llm` commands
+ * for LLM orientation context generation.
  */
 
-export { buildLlmCommand } from "./commands/index.js";
+export { buildCapabilitiesCommand, buildLlmCommand } from "./commands/index.js";
 export { specs as mcpSpecs } from "./mcp/index.js";

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

@@ -1,2 +1,2 @@
 /** @module LLM domain MCP barrel — capabilities, llm. */
-export { default as specs } from "./specs.js";
+export { buildCapabilitiesData, default as specs } from "./specs.js";

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

@@ -2,74 +2,80 @@
  * MCP tool specs for llm domain — capabilities, llm.
  */
 
+import { VERSION } from "#constants";
 import { buildFilterConfig } from "../../shared/filters/index.js";
 import type { ToolSpec } from "../../shared/ToolSpec.js";
-import { COMMAND_REFERENCE, DECISION_TREES } from "../data/index.js";
+import {
+  COMMAND_REFERENCE,
+  DECISION_TREES,
+  TOOL_CATALOG,
+} from "../data/index.js";
 import { collectContext } from "../operations/index.js";
-import type { LlmData } from "../types.js";
+import type { CapabilitiesData, LlmData } from "../types.js";
 
-/** All registered tool names, categorized for the capabilities response. */
-const toolNames = {
-  read: [
-    "block_list",
-    "block_lookup",
-    "standard_list",
-    "standard_lookup",
-    "standard_categories",
-    "modifier_list",
-    "modifier_lookup",
-    "token_list",
-    "token_lookup",
-    "tier_list",
-    "config_show",
-    "ontology_list",
-    "ontology_show",
-    "graph_query",
-    "graph_inspect",
-    "skill_list",
-  ],
-  write: [
-    "config_tier",
-    "config_channel",
-    "tokens_add_config",
-    "create_component",
-    "create_package",
-  ],
-  orientation: ["llm", "capabilities"],
-  diagnostic: ["doctor", "info"],
-};
-const allToolNames = [
-  ...toolNames.read,
-  ...toolNames.write,
-  ...toolNames.orientation,
-  ...toolNames.diagnostic,
-];
+/** Build the static capabilities response. */
+function buildCapabilitiesData(): CapabilitiesData {
+  const counts = {
+    total: TOOL_CATALOG.length,
+    read: TOOL_CATALOG.filter((t) => t.category === "read").length,
+    write: TOOL_CATALOG.filter((t) => t.category === "write").length,
+    orientation: TOOL_CATALOG.filter((t) => t.category === "orientation")
+      .length,
+    diagnostic: TOOL_CATALOG.filter((t) => t.category === "diagnostic").length,
+  };
+
+  return {
+    version: VERSION,
+    conventions: {
+      system:
+        "Pragma is a CLI and MCP server for querying a design system knowledge graph — blocks, tokens, modifiers, standards, and ontologies.",
+      model:
+        "Data is scoped by tier (hierarchical, e.g. global > apps > apps/lxd) and channel (normal, experimental, prerelease). Set these via config_tier and config_channel.",
+      querying:
+        "All queries run against an RDF triple store. Prefixed IRIs (e.g. ds:global.component.button) identify entities. Use ontology_list to discover namespaces.",
+    },
+    discovery_sequence: [
+      {
+        stage: 1,
+        tool: "capabilities",
+        purpose: "Understand conventions, available tools, and how to navigate",
+      },
+      {
+        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.",
+      },
+      {
+        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.",
+      },
+    ],
+    tools: TOOL_CATALOG,
+    counts,
+    limits: {
+      output_modes: ["text", "json", "llm"],
+      condensed_available: true,
+    },
+  };
+}
 
 const specs: readonly ToolSpec[] = [
   {
     name: "capabilities",
     description:
-      "List all available pragma MCP tools with counts by category. Call this first to discover what pragma can do. (~100 tokens)",
+      "Discover pragma conventions, available tools with behavioral hints, and discovery sequence. Call this first at session start.",
     readOnly: true,
     async execute() {
-      return {
-        data: {
-          tools: allToolNames,
-          counts: {
-            total: allToolNames.length,
-            read: toolNames.read.length,
-            write: toolNames.write.length,
-            orientation: toolNames.orientation.length,
-            diagnostic: toolNames.diagnostic.length,
-          },
-        },
-      };
+      return { data: buildCapabilitiesData() };
     },
   },
   {
     name: "llm",
     description:
-      "Get LLM orientation for the pragma design system CLI. Returns context, decision trees for common intents, and command reference with token costs. Call this first when starting a design system task.",
+      "Get live LLM orientation — context snapshot (tier, channel, entity counts), decision trees for common intents, and command reference with token costs. Call after capabilities when starting design system work.",
     readOnly: true,
     async execute(rt) {
       const filters = buildFilterConfig(rt);
@@ -84,4 +90,5 @@ const specs: readonly ToolSpec[] = [
   },
 ];
 
+export { buildCapabilitiesData };
 export default specs;

package/src/domains/llm/types.ts

@@ -1,3 +1,42 @@
+import type { ToolEntry } from "./data/toolCatalog.js";
+
+// — Capabilities ——————————————————————————————————————————————————————————————
+
+/** Structured system map returned by `pragma capabilities`. */
+export interface CapabilitiesData {
+  readonly version: string;
+  readonly conventions: {
+    readonly system: string;
+    readonly model: string;
+    readonly querying: string;
+  };
+  readonly discovery_sequence: readonly DiscoveryStage[];
+  readonly tools: readonly ToolEntry[];
+  readonly counts: ToolCounts;
+  readonly limits: {
+    readonly output_modes: readonly string[];
+    readonly condensed_available: boolean;
+  };
+}
+
+/** A single stage in the discovery flow. */
+export interface DiscoveryStage {
+  readonly stage: number;
+  readonly tool: string;
+  readonly purpose: string;
+}
+
+/** Tool counts by category. */
+export interface ToolCounts {
+  readonly total: number;
+  readonly read: number;
+  readonly write: number;
+  readonly orientation: number;
+  readonly diagnostic: number;
+}
+
+// — LLM orientation ———————————————————————————————————————————————————————————
+
 /** Dynamic context snapshot: tier, channel, entity counts, and namespaces. */
 export interface LlmContext {
   readonly tier: string | undefined;
@@ -22,6 +61,7 @@ export interface DecisionTree {
 export interface CommandRefEntry {
   readonly command: string;
   readonly tokens: string;
+  readonly use_when: string;
 }
 
 /** Complete payload rendered by `pragma llm`: context, trees, and reference. */

package/src/domains/modifier/commands/index.ts

@@ -1,4 +1,5 @@
-/** @module Re-exports modifier command builders (`lookup`, `list`). */
+/** @module Re-exports modifier command builders (`list`, `lookup`, `sample`). */
 
 export { default as listCommand } from "./list.js";
 export { default as lookupCommand } from "./lookup.js";
+export { default as sampleCommand } from "./sample.js";

package/src/domains/modifier/commands/list.ts

@@ -1,42 +1,9 @@
-/**
- * Wires the `pragma modifier list` CLI command.
- *
- * Lists all modifier families with their allowed values. Throws a
- * structured recovery error when no families are found.
- */
-
-import {
-  type CommandDefinition,
-  createOutputResult,
-} from "@canonical/cli-core";
-import { createListView } from "#tui";
+import type { CommandDefinition } from "@canonical/cli-core";
 import type { PragmaContext } from "../../shared/context.js";
-import { selectFormatter } from "../../shared/formatters.js";
-import { listFormatters } from "../formatters/index.js";
-import { modifierConfig } from "../modifierConfig.js";
-import { resolveModifierList } from "../orchestration/index.js";
+import { compileReadCommand } from "../../shared/stories/index.js";
+import { modifierListStory } from "../stories.js";
 
+/** Wire the `pragma modifier list` CLI command from the modifier list story. */
 export default function listCommand(ctx: PragmaContext): CommandDefinition {
-  return {
-    path: ["modifier", "list"],
-    description: "List all modifier families",
-    parameters: [],
-    meta: {
-      examples: ["pragma modifier list", "pragma modifier list --llm"],
-    },
-    async execute() {
-      const resolution = await resolveModifierList(ctx);
-
-      return createOutputResult([...resolution.items], {
-        plain: selectFormatter(ctx, listFormatters),
-        ink: (data) =>
-          createListView({
-            heading: "Modifiers",
-            domain: "modifier",
-            items: data,
-            columns: modifierConfig.listColumns,
-          }),
-      });
-    },
-  };
+  return compileReadCommand(ctx, modifierListStory);
 }

package/src/domains/modifier/commands/lookup.ts

@@ -1,85 +1,14 @@
-/**
- * Wires the `pragma modifier lookup <name...>` CLI command.
- *
- * Retrieves a single modifier family by name and renders its values.
- */
-
-import {
-  type CommandDefinition,
-  createOutputResult,
-} from "@canonical/cli-core";
-import { createLookupView } from "#tui";
+import type { CommandDefinition } from "@canonical/cli-core";
 import type { PragmaContext } from "../../shared/context.js";
-import type { LookupResult } from "../../shared/contracts.js";
-import { renderLookupResults } from "../../shared/formatters.js";
-import {
-  createInkLookupOptions,
-  lookupFormatters,
-} from "../formatters/index.js";
-import type { lookupModifier } from "../operations/index.js";
-import { resolveModifierLookup } from "../orchestration/index.js";
-
-interface ModifierLookupOutput {
-  readonly result: LookupResult<Awaited<ReturnType<typeof lookupModifier>>>;
-}
+import { compileLookupCommand } from "../../shared/stories/index.js";
+import { modifierLookupStory } from "../stories.js";
 
+/**
+ * Wire the `pragma modifier lookup <name...>` CLI command from the
+ * modifier lookup story.
+ */
 export default function buildLookupCommand(
   ctx: PragmaContext,
 ): CommandDefinition {
-  return {
-    path: ["modifier", "lookup"],
-    description: "Look up a modifier family and its values",
-    parameters: [
-      {
-        name: "names",
-        description: "Modifier family names or IRIs",
-        type: "multiselect",
-        positional: true,
-        required: true,
-      },
-    ],
-    meta: {
-      examples: [
-        "pragma modifier lookup importance",
-        "pragma modifier lookup importance density",
-        "pragma modifier lookup importance --llm",
-      ],
-    },
-    async execute(params: Record<string, unknown>) {
-      const names = normalizeNames(params.names, params.name);
-      const contract = await resolveModifierLookup(ctx.store, names);
-
-      return createOutputResult<ModifierLookupOutput>(
-        { result: contract.result },
-        {
-          plain: ({ result }) =>
-            renderLookupResults({
-              ctx,
-              result,
-              formatters: lookupFormatters,
-              mapResult: (family) => family,
-            }),
-          ink: ({ result }) =>
-            createLookupView({
-              results: result.results,
-              errors: result.errors,
-              domain: "modifier",
-              options: createInkLookupOptions(),
-            }),
-        },
-      );
-    },
-  };
-}
-
-function normalizeNames(names: unknown, legacyName?: unknown): string[] {
-  if (Array.isArray(names)) {
-    return names.filter(
-      (name): name is string => typeof name === "string" && name.length > 0,
-    );
-  }
-  if (typeof legacyName === "string" && legacyName.length > 0) {
-    return [legacyName];
-  }
-  return [];
+  return compileLookupCommand(ctx, modifierLookupStory);
 }

package/src/domains/modifier/commands/sample.ts

@@ -0,0 +1,53 @@
+/**
+ * Wires the `pragma modifier sample` CLI command.
+ *
+ * Returns 1–5 complete modifier family instances as exemplars so agents
+ * can learn the data shape before writing queries.
+ */
+
+import {
+  type CommandDefinition,
+  createOutputResult,
+} from "@canonical/cli-core";
+import type { PragmaContext } from "../../shared/context.js";
+import { selectFormatter } from "../../shared/formatters.js";
+import type { ModifierFamily, SampleOutput } from "../../shared/types/index.js";
+import { sampleFormatters } from "../formatters/index.js";
+import { sampleModifiers } from "../operations/index.js";
+
+const NEXT_STEPS = [
+  "Use modifier_lookup to inspect specific modifier families by name.",
+  "Use modifier_list to see all available modifier families.",
+];
+
+export default function sampleCommand(ctx: PragmaContext): CommandDefinition {
+  return {
+    path: ["modifier", "sample"],
+    description:
+      "Return randomly selected complete modifier family instances as exemplars for shape discovery",
+    parameters: [
+      {
+        name: "count",
+        type: "string",
+        description: "Number of samples to return (1–5, default 2)",
+        required: false,
+      },
+    ],
+    meta: {
+      examples: ["pragma modifier sample", "pragma modifier sample --count 3"],
+    },
+    async execute(params) {
+      const count = Number(params.count ?? 2);
+      const result = await sampleModifiers(ctx.store, count);
+
+      const output: SampleOutput<ModifierFamily> = {
+        ...result,
+        nextSteps: NEXT_STEPS,
+      };
+
+      return createOutputResult(output, {
+        plain: selectFormatter(ctx, sampleFormatters),
+      });
+    },
+  };
+}

package/src/domains/modifier/formatters/index.ts

@@ -1,7 +1,8 @@
-/** @module Re-exports modifier formatters (`lookupFormatters`, `listFormatters`). */
+/** @module Re-exports modifier formatters (`listFormatters`, `lookupFormatters`, `sampleFormatters`). */
 
 export { default as listFormatters } from "./list.js";
 export {
   createInkLookupOptions,
   default as lookupFormatters,
 } from "./lookup.js";
+export { default as sampleFormatters } from "./sample.js";

package/src/domains/modifier/formatters/sample.ts

@@ -0,0 +1,15 @@
+/**
+ * Sample formatter for the modifier domain.
+ *
+ * Delegates to the shared factory, rendering each item via the
+ * existing modifier lookup formatter.
+ */
+
+import createSampleFormatters from "../../shared/sampleFormatters.js";
+import type { ModifierFamily } from "../../shared/types/index.js";
+import lookupFormatters from "./lookup.js";
+
+export default createSampleFormatters<ModifierFamily>(
+  "modifiers",
+  (family, mode) => lookupFormatters[mode](family),
+);

package/src/domains/modifier/index.ts

@@ -7,15 +7,19 @@
 
 import type { CommandDefinition } from "@canonical/cli-core";
 import type { PragmaContext } from "../shared/context.js";
-import { listCommand, lookupCommand } from "./commands/index.js";
+import { listCommand, lookupCommand, sampleCommand } from "./commands/index.js";
 
 export function commands(ctx: PragmaContext): CommandDefinition[] {
-  return [listCommand(ctx), lookupCommand(ctx)];
+  return [listCommand(ctx), lookupCommand(ctx), sampleCommand(ctx)];
 }
 
 export { specs as mcpSpecs } from "./mcp/index.js";
 export { modifierConfig } from "./modifierConfig.js";
-export { listModifiers, lookupModifier } from "./operations/index.js";
+export {
+  listModifiers,
+  lookupModifier,
+  sampleModifiers,
+} from "./operations/index.js";
 export {
   modifierEmptyError,
   resolveModifierList,

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

@@ -1,60 +1,35 @@
 /**
- * MCP tool specs for the modifier domain.
+ * MCP tool specs for the modifier domain — modifier_list, modifier_lookup,
+ * modifier_sample.
  *
- * Declarative definitions — no MCP imports. The adapter layer
- * converts these into registered MCP tools via `registerFromSpec()`.
+ * The list and lookup tools are compiled from the modifier read stories in
+ * `../stories.ts`; only the sample tool is spec'd by hand. The adapter
+ * layer converts these into registered MCP tools via `registerFromSpec()`.
  */
 
-import type { ToolSpec } from "../../shared/ToolSpec.js";
-import {
-  listFormatters as modifierListFmt,
-  lookupFormatters as modifierLookupFmt,
-} from "../formatters/index.js";
 import {
-  resolveModifierList,
-  resolveModifierLookup,
-} from "../orchestration/index.js";
+  compileLookupTool,
+  compileReadTool,
+  condense,
+} from "../../shared/stories/index.js";
+import type { ToolSpec } from "../../shared/ToolSpec.js";
+import { sampleFormatters as modifierSampleFmt } from "../formatters/index.js";
+import { sampleModifiers } from "../operations/index.js";
+import { modifierListStory, modifierLookupStory } from "../stories.js";
 
 const specs: readonly ToolSpec[] = [
+  compileReadTool(modifierListStory),
+  compileLookupTool(modifierLookupStory),
   {
-    name: "modifier_list",
-    description: "List all modifier families with their values.",
+    name: "modifier_sample",
+    description:
+      "Return 1–5 randomly selected complete modifier family instances as exemplars. Use BEFORE writing queries to see actual data shapes, property names, and value formats. Each call returns different instances.",
     params: {
-      condensed: {
-        type: "boolean",
-        description: "Token-optimized output",
+      count: {
+        type: "string",
+        description: "Number of samples (1–5, default 2)",
         optional: true,
       },
-    },
-    readOnly: true,
-    async execute(rt, { condensed }) {
-      const resolution = await resolveModifierList(rt);
-
-      if (condensed) {
-        const text = modifierListFmt.llm([...resolution.items]);
-        return {
-          condensed: true,
-          text,
-          tokens: `~${Math.ceil(text.length / 4)}`,
-        };
-      }
-
-      return {
-        data: resolution.items,
-        meta: { count: resolution.items.length },
-      };
-    },
-  },
-
-  {
-    name: "modifier_lookup",
-    description: "Get one or more modifier families and their values.",
-    params: {
-      names: {
-        type: "string[]",
-        description: "Modifier family names or IRIs to look up",
-        optional: false,
-      },
       condensed: {
         type: "boolean",
         description: "Token-optimized output",
@@ -62,34 +37,27 @@ const specs: readonly ToolSpec[] = [
       },
     },
     readOnly: true,
-    async execute(rt, { names, condensed }) {
-      const contract = await resolveModifierLookup(rt.store, names as string[]);
-      const result = contract.result;
+    async execute(rt, { count, condensed }) {
+      const n = Number(count ?? 2);
+      const result = await sampleModifiers(rt.store, n);
+      const nextSteps = [
+        `These are ${result.samples.length} of ${result.totalCount} total modifier families.`,
+        "Use modifier_lookup to inspect specific modifier families by name.",
+        "Use modifier_list to see all available modifier families.",
+      ];
 
       if (condensed) {
-        const textParts = result.results.map((family) =>
-          modifierLookupFmt.llm(family),
-        );
-
-        if (result.errors.length > 0) {
-          textParts.push(
-            [
-              "### Errors",
-              ...result.errors.map(
-                (error) => `- ${error.query}: ${error.message}`,
-              ),
-            ].join("\n"),
-          );
-        }
-
-        return {
-          condensed: true,
-          text: textParts.join("\n\n"),
-          tokens: `~${Math.ceil(textParts.join("\n\n").length / 4)}`,
-        };
+        return condense(modifierSampleFmt.llm({ ...result, nextSteps }));
       }
 
-      return { data: result, meta: { count: result.results.length } };
+      return {
+        data: {
+          samples: result.samples,
+          totalCount: result.totalCount,
+          nextSteps,
+        },
+        meta: { count: result.samples.length },
+      };
     },
   },
 ] as const;

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

@@ -1,4 +1,5 @@
-/** @module Re-exports modifier operations (`lookupModifier`, `listModifiers`). */
+/** @module Re-exports modifier operations (`listModifiers`, `lookupModifier`, `sampleModifiers`). */
 
 export { default as listModifiers } from "./list.js";
 export { default as lookupModifier } from "./lookup.js";
+export { default as sampleModifiers } from "./sample.js";

package/src/domains/modifier/operations/lookup.ts

@@ -13,6 +13,11 @@ import { escapeSparqlValue } from "@canonical/ke";
 import { PragmaError } from "#error";
 import { buildQuery } from "../../shared/buildQuery.js";
 import { P } from "../../shared/prefixes.js";
+import {
+  detectCrossDomain,
+  listDomainNames,
+  suggestNames,
+} from "../../shared/suggestions/index.js";
 import type { ModifierFamily } from "../../shared/types/index.js";
 
 export default async function lookupModifier(
@@ -39,12 +44,16 @@ export default async function lookupModifier(
   );
 
   if (result.type !== "select" || result.bindings.length === 0) {
+    const candidates = await listDomainNames(store, "modifier");
+    const crossDomain = await detectCrossDomain(name, "modifier", store);
     throw PragmaError.notFound("modifier", name, {
+      suggestions: suggestNames(name, candidates),
       recovery: {
         message: "List available modifiers.",
         cli: "pragma modifier list",
         mcp: { tool: "modifier_list" },
       },
+      crossDomain: crossDomain ?? undefined,
     });
   }
 

package/src/domains/modifier/operations/sample.ts

@@ -0,0 +1,32 @@
+/**
+ * Returns a small number of complete modifier family instances as exemplars.
+ *
+ * Composes the existing list and lookup operations to avoid duplicating
+ * any SPARQL logic. Agents use this to learn the data shape before querying.
+ *
+ * @param store - ke store to query
+ * @param count - number of samples (clamped 1–5, default 2)
+ * @returns sample result with detailed modifier families and total count
+ * @note Queries ke store
+ */
+
+import type { Store } from "@canonical/ke";
+import pickRandom from "../../shared/pickRandom.js";
+import type { ModifierFamily, SampleResult } from "../../shared/types/index.js";
+import listModifiers from "./list.js";
+import lookupModifier from "./lookup.js";
+
+export default async function sampleModifiers(
+  store: Store,
+  count = 2,
+): Promise<SampleResult<ModifierFamily>> {
+  const clamped = Math.max(1, Math.min(5, count));
+  const all = await listModifiers(store);
+  const selected = pickRandom(all, clamped);
+
+  const samples = await Promise.all(
+    selected.map((m) => lookupModifier(store, m.name)),
+  );
+
+  return { samples, totalCount: all.length };
+}