@canonical/pragma-cli 0.30.0 → 0.31.0

package/README.md

@@ -22,7 +22,7 @@ See [docs/getting-started.md](docs/getting-started.md) for a full walkthrough.
 
 ## CLI Commands
 
-pragma organizes commands into 17 domains — counting every directory under `src/domains/` except `shared/`, which holds cross-domain infrastructure rather than commands. The 14 day-to-day domains are documented below; the remaining three are specialised: `graphql` (compile TTL ontologies into GraphQL schema artifacts), `refs` (`pragma update-refs`, package reference data), and `trace` (query access tracing). Every command supports three output modes: plain text (default), `--llm` (condensed Markdown), and `--format json` (structured JSON).
+pragma organizes commands into 17 domains — counting every directory under `src/domains/` except `shared/`, which holds cross-domain infrastructure rather than commands. The day-to-day domains are documented below; two are specialised and not covered here: `graphql` (compile TTL ontologies into GraphQL schema artifacts) and `trace` (query access tracing). Every command supports three output modes: plain text (default), `--llm` (condensed Markdown), and `--format json` (structured JSON).
 
 ### Block
 
@@ -36,7 +36,7 @@ pragma organizes commands into 17 domains — counting every directory under `sr
 | Command | Description |
 |---------|-------------|
 | `pragma standard list` | List all code standards |
-| `pragma standard lookup <name>` | Show standard with do/don't examples |
+| `pragma standard lookup <name>` | Show standard details (`--detailed` adds do/don't examples) |
 | `pragma standard categories` | List standard categories with counts |
 
 ### Modifier
@@ -46,13 +46,17 @@ pragma organizes commands into 17 domains — counting every directory under `sr
 | `pragma modifier list` | List all modifier families |
 | `pragma modifier lookup <name>` | Show modifier family with values |
 
-### Token
+### Tokens
 
 | Command | Description |
 |---------|-------------|
-| `pragma token list` | List all design tokens |
-| `pragma token lookup <name>` | Show token with theme values |
-| `pragma token add-config` | Add Terrazzo config for token build |
+| `pragma tokens add-config` | Add Terrazzo config for token build |
+
+> **Note:** The token *read* commands (`token list`, `token lookup`, `token sample`)
+> are currently disabled behind a feature flag
+> (`src/domains/token/featureFlag.ts`) because the published design-system
+> data does not yet contain token instances. They will return once token
+> data ships.
 
 ### Tier
 
@@ -65,7 +69,10 @@ pragma organizes commands into 17 domains — counting every directory under `sr
 | Command | Description |
 |---------|-------------|
 | `pragma ontology list` | List loaded ontology namespaces |
-| `pragma ontology show <prefix>` | Show classes and properties for a namespace |
+| `pragma ontology show <prefix>` | Show the TBox: name, metadata, class hierarchy tree with instance counts and relations |
+| `pragma ontology show <prefix> --properties` | Also show datatype properties (attributes) |
+| `pragma ontology show <prefix> --full-uris` | Show full URIs instead of compact prefixed IRIs |
+| `pragma ontology show <prefix> --class <Class>` | Deep-dive into one class: super chain, direct/inherited properties, reverse references, sample instances, and ready-to-run follow-up queries |
 
 ### Graph
 
@@ -97,15 +104,16 @@ pragma organizes commands into 17 domains — counting every directory under `sr
 
 ### Setup
 
-All setup commands support `--dry-run`, `--yes`, and `--undo`.
+All setup commands support `--dry-run`; `--yes` and `--undo` are supported
+where shown below.
 
 | Command | Description |
 |---------|-------------|
-| `pragma setup all` | Run all setup steps (MCP + completions + skills) |
-| `pragma setup mcp` | Configure pragma MCP server for AI harnesses |
-| `pragma setup completions` | Install shell completions (bash/zsh/fish) |
-| `pragma setup skills` | Symlink agent skills into harness config |
-| `pragma setup lsp` | Configure LSP integration |
+| `pragma setup` | Run all setup steps (completions + LSP + MCP); supports `--yes`, `--undo` |
+| `pragma setup mcp` | Configure pragma MCP server for AI harnesses; supports `--yes`, `--undo` |
+| `pragma setup completions` | Install shell completions (bash/zsh/fish); supports `--undo` |
+| `pragma setup skills` | Symlink agent skills into harness config; supports `--yes` |
+| `pragma setup lsp` | Install the Terrazzo LSP VS Code extension; supports `--undo` |
 
 ### Create
 
@@ -113,8 +121,9 @@ Create commands scaffold new code using summon generators. They support `--undo`
 
 | Command | Description |
 |---------|-------------|
-| `pragma create component <name>` | Scaffold a new design system component |
-| `pragma create package <name>` | Scaffold a new monorepo package |
+| `pragma create component <framework> [path]` | Scaffold a new design system component |
+| `pragma create package` | Scaffold a new monorepo package (`--name`, `--type`, …) |
+| `pragma create application [path]` | Scaffold a complete React application with SSR and routing |
 
 ### Doctor
 
@@ -126,8 +135,19 @@ Create commands scaffold new code using summon generators. They support `--undo`
 
 | Command | Description |
 |---------|-------------|
-| `pragma info` | Show pragma version, store summary, installed packages |
-| `pragma info upgrade` | Check for newer pragma versions on the registry |
+| `pragma info` | Show pragma version, config, update status, and store summary |
+
+### Upgrade
+
+| Command | Description |
+|---------|-------------|
+| `pragma upgrade` | Upgrade the pragma CLI to the latest version (`--dry-run` to check only) |
+
+### Refs
+
+| Command | Description |
+|---------|-------------|
+| `pragma update-refs` | Fetch or clone git-referenced semantic packages into the local cache (needed before `skill list` can discover skills) |
 
 ## Global Flags
 
@@ -144,7 +164,7 @@ Setup and create commands support `--undo` to reverse previous operations. The u
 ```bash
 pragma setup mcp --undo             # Remove MCP configuration
 pragma setup completions --undo     # Remove shell completions
-pragma create component Foo --undo  # Remove scaffolded component files
+pragma create component react src/lib/Foo --undo  # Remove scaffolded component files
 ```
 
 ## MCP Integration
@@ -174,27 +194,27 @@ Or add manually to your `.mcp.json`:
 }
 ```
 
-### MCP Tools (30)
+### MCP Tools (28)
 
 All tools return a consistent envelope: `{ ok: true, data, meta }` for success, `{ ok: true, condensed: true, text, tokens }` for condensed mode, or `{ ok: false, error }` with structured recovery on failure.
 
-#### Read Tools (21)
+#### Read Tools (18)
+
+Lookup tools accept a `names` array, so several entities can be fetched in
+one call (partial results are returned alongside per-name errors).
 
 | Tool | Description |
 |------|-------------|
 | `block_list` | List blocks with optional tier filtering and disclosure levels |
 | `block_lookup` | Look up detailed block info (anatomy, modifiers, tokens, standards) |
-| `block_batch_lookup` | Look up multiple blocks by name in a single call |
+| `block_sample` | Return random complete block instances for shape discovery |
 | `standard_list` | List code standards with optional category/search filtering |
 | `standard_lookup` | Look up standard with do/don't code examples |
-| `standard_batch_lookup` | Look up multiple standards by name in a single call |
 | `standard_categories` | List standard categories with counts |
+| `standard_sample` | Return random complete standard instances for shape discovery |
 | `modifier_list` | List modifier families |
 | `modifier_lookup` | Look up modifier family with values |
-| `modifier_batch_lookup` | Look up multiple modifier families by name in a single call |
-| `token_list` | List design tokens with optional category filtering |
-| `token_lookup` | Look up token with theme-resolved values |
-| `token_batch_lookup` | Look up multiple tokens by name in a single call |
+| `modifier_sample` | Return random complete modifier instances for shape discovery |
 | `tier_list` | List all tiers in the hierarchy |
 | `config_show` | Show current tier and channel configuration |
 | `ontology_list` | List loaded ontology namespaces with class/property counts |
@@ -204,7 +224,10 @@ All tools return a consistent envelope: `{ ok: true, data, meta }` for success,
 | `skill_list` | List discovered agent skills |
 | `skill_lookup` | Get full SKILL.md content for skills by name |
 
-#### Write Tools (5)
+`token_list`, `token_lookup`, and `token_sample` are feature-flagged off
+until token data ships (see the Tokens note above).
+
+#### Write Tools (6)
 
 | Tool | Description |
 |------|-------------|
@@ -213,6 +236,7 @@ All tools return a consistent envelope: `{ ok: true, data, meta }` for success,
 | `tokens_add_config` | Add Terrazzo token build configuration |
 | `create_component` | Scaffold a new design system component |
 | `create_package` | Scaffold a new monorepo package |
+| `create_application` | Scaffold a complete React application |
 
 #### Orientation Tools (2)
 
@@ -282,12 +306,12 @@ Error responses include a `recovery` object that tells agents what tool to call
 
 ### Batch Results
 
-List tools that accept a `names` filter return partial results — valid items in `results`, failures in `errors`:
+Lookup tools accept a `names` array and return partial results — valid items in `results`, failures in `errors`:
 
 ```json
 {
   "results": [{ "name": "Button", ... }],
-  "errors": [{ "name": "Buton", "code": "ENTITY_NOT_FOUND", "message": "..." }]
+  "errors": [{ "query": "Buton", "code": "ENTITY_NOT_FOUND", "message": "...", "suggestions": ["Button"] }]
 }
 ```
 
@@ -358,16 +382,21 @@ format is experimental and may change.
 
 ## Error Handling
 
-Errors follow a three-part structure: message, context (suggestions or valid options), and recovery hint.
+Lookup errors report each failed name with typo suggestions:
 
 ```
-Error: block "Buton" not found.
+**Errors:**
+- Buton: block "Buton" not found.
+  Did you mean: Button?
+```
 
-Did you mean?
-  - Button
-  - ButtonGroup
+Other errors carry a code and, where available, a recovery hint:
 
-Run `pragma block list`
+```
+## Error: EMPTY_RESULTS
+No standards found.
+Filters: category=nope
+Recovery: `pragma standard list`
 ```
 
 With `--format json`, errors are returned as structured JSON with error code, suggestions, and recovery. With `--llm`, errors are rendered as Markdown.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@canonical/pragma-cli",
   "description": "CLI and MCP server for Canonical's design system.",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "type": "module",
   "module": "src/index.ts",
   "types": "src/index.ts",
@@ -60,9 +60,9 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.9",
-    "@canonical/biome-config": "^0.30.0",
-    "@canonical/typescript-config": "^0.30.0",
-    "@canonical/webarchitect": "^0.30.0",
+    "@canonical/biome-config": "^0.31.0",
+    "@canonical/typescript-config": "^0.31.0",
+    "@canonical/webarchitect": "^0.31.0",
     "@types/bun": "^1.3.10",
     "@types/node": "^24.12.0",
     "@types/react": "^19.2.14",
@@ -72,16 +72,18 @@
   },
   "dependencies": {
     "@canonical/anatomy-dsl": "^0.2.2",
-    "@canonical/cli-core": "^0.30.0",
+    "@canonical/cli-core": "^0.31.0",
     "@canonical/code-standards": "^0.1.2",
     "@canonical/design-system": "^0.1.2",
-    "@canonical/harnesses": "^0.30.0",
-    "@canonical/ke": "^0.30.0",
-    "@canonical/ke-graphql": "^0.30.0",
-    "@canonical/summon-component": "^0.30.0",
-    "@canonical/summon-core": "^0.30.0",
-    "@canonical/summon-package": "^0.30.0",
-    "@canonical/task": "^0.30.0",
+    "@canonical/harnesses": "^0.31.0",
+    "@canonical/ke": "^0.31.0",
+    "@canonical/ke-graphql": "^0.31.0",
+    "@canonical/summon": "^0.31.0",
+    "@canonical/summon-application": "^0.31.0",
+    "@canonical/summon-component": "^0.31.0",
+    "@canonical/summon-core": "^0.31.0",
+    "@canonical/summon-package": "^0.31.0",
+    "@canonical/task": "^0.31.0",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
@@ -90,5 +92,5 @@
     "react": "^19.2.4",
     "zod": "^3.25.0"
   },
-  "gitHead": "40fe86ac955473536ac14f074812a9821f5b65c0"
+  "gitHead": "d4a67ebe42e62b8cf3de77f42f537309ca88d672"
 }

package/src/completions/constants.ts

@@ -16,3 +16,10 @@ export const POLL_INTERVAL_MS = 50;
 
 /** Maximum time to wait for a spawned server to become ready. */
 export const SPAWN_TIMEOUT_MS = 5_000;
+
+/**
+ * Maximum time to wait for a query response before giving up. Bounds the
+ * whole client call so a wedged or slow server can never hang the shell's
+ * tab-completion — the query resolves to no candidates instead.
+ */
+export const QUERY_TIMEOUT_MS = 3_000;

package/src/completions/handleQuery.test.ts

@@ -37,6 +37,16 @@ function makeTree(): CompletionTree {
             );
           },
         },
+        {
+          name: "detailed",
+          description: "Show full detail",
+          type: "boolean",
+        },
+        {
+          name: "anatomyOnly",
+          description: "Show anatomy only",
+          type: "boolean",
+        },
       ],
       execute: async () => createExitResult(0),
     },
@@ -90,4 +100,26 @@ describe("handleQuery", () => {
     const result = await handleQuery("block list something", makeTree(), ctx);
     expect(result).toBe("");
   });
+
+  it("strips the leading program name shells forward", async () => {
+    // Every generated shell script forwards the full command line, so the
+    // program name arrives as the first word.
+    const result = await handleQuery("pragma blo", makeTree(), ctx);
+    expect(result).toBe("block");
+  });
+
+  it("lists nouns when only the program name is present", async () => {
+    const result = await handleQuery("pragma", makeTree(), ctx);
+    expect(result).toBe("block\nstandard");
+  });
+
+  it("completes verb flags when the word starts with a dash", async () => {
+    const result = await handleQuery("block get --", makeTree(), ctx);
+    expect(result).toBe("--anatomy-only\n--detailed");
+  });
+
+  it("filters verb flags by the dash-prefixed partial", async () => {
+    const result = await handleQuery("block get --d", makeTree(), ctx);
+    expect(result).toBe("--detailed");
+  });
 });

package/src/completions/handleQuery.ts

@@ -1,5 +1,24 @@
 import type { CommandContext, CompletionTree } from "@canonical/cli-core";
 import { resolveCompletion } from "@canonical/cli-core";
+import { PROGRAM_NAME } from "../constants.js";
+
+/**
+ * Split a raw shell partial into completion words, dropping the leading
+ * program name.
+ *
+ * Every generated shell script forwards the full command line — including the
+ * `pragma` program name as the first word — so without this strip the resolver
+ * mistakes `pragma` for the noun and returns no candidates. An empty partial
+ * (first-Tab, no word yet) resolves to a single empty word so noun completion
+ * still fires.
+ *
+ * @param partial - The raw partial input string from the shell.
+ * @returns The completion words with any leading program name removed.
+ */
+function splitCompletionWords(partial: string): string[] {
+  const words = partial.length === 0 ? [""] : partial.split(" ");
+  return words.at(0) === PROGRAM_NAME ? words.slice(1) : words;
+}
 
 /**
  * Resolve a partial CLI input against a completion tree and return
@@ -22,7 +41,7 @@ export default async function handleQuery(
   tree: CompletionTree,
   ctx: CommandContext,
 ): Promise<string> {
-  const words = partial.length === 0 ? [""] : partial.split(" ");
+  const words = splitCompletionWords(partial);
   const result = resolveCompletion(tree, words);
   if (!result.completer) return "";
   const candidates = await result.completer(result.partial, ctx);

package/src/completions/queryCompletions.test.ts

@@ -26,12 +26,15 @@ vi.mock("./waitForSocket.js", () => ({
 
 describe("queryCompletions", () => {
   let stdoutSpy: ReturnType<typeof vi.spyOn>;
+  const unrefMock = vi.fn();
 
   beforeEach(() => {
     vi.clearAllMocks();
     stdoutSpy = vi
       .spyOn(process.stdout, "write")
       .mockImplementation(() => true);
+    // The spawned server handle is unref'd so the client can exit immediately.
+    spawnMock.mockReturnValue({ unref: unrefMock });
     vi.stubGlobal("Bun", { spawn: spawnMock });
   });
 
@@ -67,6 +70,8 @@ describe("queryCompletions", () => {
 
     expect(unlinkSyncMock).toHaveBeenCalledWith("/tmp/pragma-completions.sock");
     expect(spawnMock).toHaveBeenCalledTimes(1);
+    // The server handle is detached so the client is not held alive by it.
+    expect(unrefMock).toHaveBeenCalledTimes(1);
     expect(waitForSocketMock).toHaveBeenCalled();
     expect(querySocketMock).toHaveBeenCalledTimes(2);
     expect(stdoutSpy).toHaveBeenCalledWith("block\n");

package/src/completions/queryCompletions.ts

@@ -38,12 +38,26 @@ export default async function queryCompletions(partial: string): Promise<void> {
     }
   }
 
-  // No running server — spawn one.
-  const binPath = resolve(import.meta.dirname, "../bin.ts");
-  Bun.spawn(["bun", "run", binPath, "_completions-server"], {
+  // No running server — spawn one. Re-invoke THIS executable so completion
+  // works from the shipped binary as well as from source: when the entry file
+  // exists on disk (source run) spawn `bun run bin.ts`; otherwise (a compiled
+  // standalone binary, where bin.ts is embedded, not a file) spawn the binary
+  // itself. The old code always spawned `bun run <dir>/../bin.ts`, which does
+  // not exist inside a compiled binary, so its server never started and every
+  // completion silently returned nothing.
+  const entryPath = resolve(import.meta.dirname, "../bin.ts");
+  const spawnArgs = existsSync(entryPath)
+    ? [process.execPath, "run", entryPath, "_completions-server"]
+    : [process.execPath, "_completions-server"];
+  const server = Bun.spawn(spawnArgs, {
     stdio: ["ignore", "ignore", "ignore"],
     cwd: process.cwd(),
   });
+  // Detach the server from the client's lifecycle. Without this the child keeps
+  // the client's event loop alive until the server's idle timeout (~10s) fires,
+  // so every tab-completion appears to hang for ~10s and the client tears the
+  // server down on exit — defeating the persistent-server fast path entirely.
+  server.unref();
 
   const ready = await waitForSocket(socketPath, SPAWN_TIMEOUT_MS);
   if (!ready) {

package/src/completions/querySocket.test.ts

@@ -67,4 +67,35 @@ describe("querySocket", () => {
       "connect failed",
     );
   });
+
+  it("times out and closes the socket when the server never replies", async () => {
+    vi.useFakeTimers();
+    const end = vi.fn();
+
+    connectMock.mockImplementation(
+      (options: {
+        socket: {
+          open: (socket: {
+            write: () => void;
+            flush: () => void;
+            end: () => void;
+          }) => void;
+        };
+      }) => {
+        // Open but never send data or close — simulate a wedged server.
+        options.socket.open({ write: () => {}, flush: () => {}, end });
+        return Promise.resolve({});
+      },
+    );
+
+    try {
+      const promise = querySocket("/tmp/pragma.sock", "blo");
+      const assertion = expect(promise).rejects.toThrow(/timed out/);
+      await vi.advanceTimersByTimeAsync(5000);
+      await assertion;
+      expect(end).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
 });

package/src/completions/querySocket.ts

@@ -1,10 +1,14 @@
+import { QUERY_TIMEOUT_MS } from "./constants.js";
+
 /**
  * Connect to a Unix domain socket, send a partial string, and
  * collect the response.
  *
- * Opens a Bun TCP connection to the socket, writes the partial
- * terminated by a newline, and accumulates response chunks until
- * the server closes the connection.
+ * Opens a Bun connection to the socket, writes the partial terminated by a
+ * newline, and accumulates response chunks until the server closes the
+ * connection. The whole exchange is bounded by {@link QUERY_TIMEOUT_MS}: if a
+ * wedged or slow server never replies, the promise rejects rather than hanging
+ * the shell's tab-completion indefinitely.
  *
  * @param socketPath - Absolute path to the Unix domain socket.
  * @param partial - The partial CLI input to send for completion.
@@ -18,10 +22,31 @@ export default function querySocket(
 ): Promise<string> {
   return new Promise<string>((resolve, reject) => {
     const chunks: Buffer[] = [];
+    let settled = false;
+    let openSocket: { end: () => void } | undefined;
+
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      // Close the connection so a hung server does not leak an open socket.
+      openSocket?.end();
+      reject(
+        new Error(`Completion query timed out after ${QUERY_TIMEOUT_MS}ms`),
+      );
+    }, QUERY_TIMEOUT_MS);
+
+    const settle = (run: () => void): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      run();
+    };
+
     Bun.connect({
       unix: socketPath,
       socket: {
         open(socket) {
+          openSocket = socket;
           socket.write(`${partial}\n`);
           socket.flush();
         },
@@ -29,16 +54,18 @@ export default function querySocket(
           chunks.push(Buffer.from(data));
         },
         close() {
-          resolve(
-            Buffer.concat(chunks)
-              .toString("utf-8")
-              .replace(/\r?\n$/, ""),
+          settle(() =>
+            resolve(
+              Buffer.concat(chunks)
+                .toString("utf-8")
+                .replace(/\r?\n$/, ""),
+            ),
           );
         },
         error(_socket, err) {
-          reject(err);
+          settle(() => reject(err));
         },
       },
-    }).catch(reject);
+    }).catch((err) => settle(() => reject(err)));
   });
 }

package/src/config/parseConfigValues.ts

@@ -92,6 +92,7 @@ export default function parseConfigValues(
   const packages = parsePackagesField(parsed.packages);
   const stories = parseStoriesField(parsed.stories, sourcePath);
   const prefixes = parsePrefixesField(parsed.prefixes);
+  const detail = typeof parsed.detail === "string" ? parsed.detail : undefined;
 
   return {
     ...(tier !== undefined ? { tier } : {}),
@@ -101,6 +102,7 @@ export default function parseConfigValues(
     ...(framework !== undefined ? { framework } : {}),
     ...(stories ? { stories } : {}),
     ...(prefixes ? { prefixes } : {}),
+    ...(detail !== undefined ? { detail } : {}),
   };
 }
 

package/src/config/readConfigLayers.test.ts

@@ -44,6 +44,7 @@ describe("readConfigLayers", () => {
       framework: "default",
       stories: "default",
       prefixes: "default",
+      detail: "default",
     });
     expect(layers.global.exists).toBe(false);
     expect(layers.project.exists).toBe(false);
@@ -77,6 +78,7 @@ describe("readConfigLayers", () => {
       framework: "default",
       stories: "default",
       prefixes: "default",
+      detail: "default",
     });
   });
 

package/src/config/readConfigLayers.ts

@@ -68,6 +68,7 @@ export default function readConfigLayers(
   const framework = pick("framework");
   const stories = pick("stories");
   const prefixes = pick("prefixes");
+  const detail = pick("detail");
 
   const config: PragmaConfig = {
     tier: tier.value,
@@ -77,6 +78,7 @@ export default function readConfigLayers(
     ...(framework.value !== undefined ? { framework: framework.value } : {}),
     ...(stories.value ? { stories: stories.value } : {}),
     ...(prefixes.value ? { prefixes: prefixes.value } : {}),
+    ...(detail.value !== undefined ? { detail: detail.value } : {}),
   };
 
   return {
@@ -89,6 +91,7 @@ export default function readConfigLayers(
       framework: framework.origin,
       stories: stories.origin,
       prefixes: prefixes.origin,
+      detail: detail.origin,
     },
     global: { path: globalPath, exists: globalFile.exists },
     project: { path: projectPath, exists: projectFile.exists },

package/src/config/types.ts

@@ -39,6 +39,11 @@ interface PragmaConfig {
    * registered on the store (usable in queries) and used for display.
    */
   prefixes?: Readonly<Record<string, string>> | undefined;
+  /**
+   * Default progressive-disclosure level for disclosure-capable commands
+   * (e.g. `"digest"`, `"detailed"`). An explicit `--detail` flag overrides it.
+   */
+  detail?: string | undefined;
 }
 
 /** Partial update payload for writing config changes. */
@@ -67,6 +72,7 @@ interface ConfigFileValues {
   readonly framework?: Framework;
   readonly stories?: ReadonlyArray<StoryPackDefinition>;
   readonly prefixes?: Readonly<Record<string, string>>;
+  readonly detail?: string;
 }
 
 /** Which config layer supplied an effective field value. */
@@ -81,6 +87,7 @@ interface ConfigOrigins {
   readonly framework: ConfigOrigin;
   readonly stories: ConfigOrigin;
   readonly prefixes: ConfigOrigin;
+  readonly detail: ConfigOrigin;
 }
 
 /** A resolved config file layer. */

package/src/constants.ts

@@ -7,7 +7,9 @@
  */
 
 import pkg from "../package.json" with { type: "json" };
-import { PREFIX_MAP } from "./domains/shared/prefixes.js";
+// DEFAULT_PREFIX_MAP carries the transitional DS prefixes (ds/cs) this map
+// still keys on; remove in P4 when DS prefixes ship from their packages.
+import { DEFAULT_PREFIX_MAP as PREFIX_MAP } from "./domains/shared/prefixes.js";
 
 /** CLI program name used in help text and error messages. */
 const PROGRAM_NAME = "pragma";

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

@@ -11,6 +11,7 @@ import {
 } from "@canonical/cli-core";
 import type { PragmaContext } from "../../shared/context.js";
 import { selectFormatter } from "../../shared/formatters.js";
+import parseSampleCount from "../../shared/parseSampleCount.js";
 import type { BlockDetailed, SampleOutput } from "../../shared/types/index.js";
 import { sampleFormatters } from "../formatters/index.js";
 import { sampleBlocks } from "../operations/index.js";
@@ -38,7 +39,7 @@ export default function sampleCommand(ctx: PragmaContext): CommandDefinition {
       examples: ["pragma block sample", "pragma block sample --count 3"],
     },
     async execute(params) {
-      const count = Number(params.count ?? 2);
+      const count = parseSampleCount(params.count);
       const filters = buildBlockFilters(ctx);
       const result = await sampleBlocks(ctx.store, filters, count);