@canonical/pragma-cli 0.33.0 → 0.35.0

package/src/capabilities/colophon/collectColophon.ts

@@ -1,11 +1,14 @@
 /**
  * Collect the `colophon` payload — the verb's run body (lazily imported).
  *
- * STORELESS: it reads the layered config (memoized) and resolves the EFFECTIVE
- * capability modules exactly as a real command would, so a config story that
- * overrides a bundled pack is reflected here — "active domain" is expressed the
- * way the rest of the CLI expresses it. It never boots the triple store, so the
- * storeless-guarantee spy still sees `store.booted === false`.
+ * STORELESS: it resolves the EFFECTIVE capability modules exactly as a real
+ * command would — through `loadEffectiveModules`, so a story declared by a
+ * PACKAGE the active pack carries surfaces its colophon here too, not only a
+ * config-declared one. It never boots the triple store, so the
+ * storeless-guarantee spy still sees `store.booted === false`. The static
+ * import of the validated distribution config (`config/defaults.js`) is safe
+ * here because this module sits behind the verb's dynamic `import()` — it
+ * never lands on the `--help`/`__complete` fast path.
  *
  * The registry is reached through a RUNTIME dynamic `import("../index.js")`
  * inside this async body — never a static import — so the static
@@ -13,46 +16,57 @@
  * into a static import.
  */
 
-import type { PragmaRuntime } from "../../kernel/runtime/types.js";
-import type { CapabilityModule } from "../../kernel/spec/types.js";
-import { PRAGMA_COLOPHON, PRAGMA_COLOPHON_SUMMARY } from "./pragmaColophon.js";
+import { BIN_NAME } from "../../constants.js";
+import distribution from "../../kernel/config/defaults.js";
+import type { PragmaRuntime } from "../../kernel/runtime/index.js";
+import type { CapabilityModule } from "../../kernel/spec/index.js";
 import type { ColophonData, ColophonSection } from "./types.js";
 
 /**
  * Assemble the colophon data for the current runtime.
  *
+ * THE DOMAIN'S STORY WINS. A colophon answers "what am I working with", and
+ * once a domain is configured the answer is the domain — so the domain
+ * sections are the whole output, and the toolchain's own section does not
+ * ride in front of them. The toolchain section is the answer only when no
+ * domain has one: a fresh install, or a distribution that ships no story.
+ * Reading it the other way round put a paragraph about this program's
+ * architecture above the thing the user actually asked about, every time.
+ *
+ * Neither section is authored here. The toolchain half is the distribution
+ * config's `colophon` field (narrative plus condensed summary), rendered under
+ * the distribution's own name — a fork edits its config, never this module —
+ * and the domain half is each active pack's declared `colophon`. The
+ * `kind: "pragma"` value is a frozen JSON discriminant (wire compatibility),
+ * not the distribution's name.
+ *
+ * With neither declared, the payload is empty and the formatter's empty state
+ * says so, rather than the command printing nothing and leaving the reader to
+ * guess whether that is an answer or a failure.
+ *
  * @param runtime - The per-invocation runtime.
- * @returns The storeless colophon payload: pragma's section, then each active
- *   pack/domain that declares a `colophon`.
+ * @returns The storeless colophon payload: every active pack/domain that
+ *   declares a `colophon`, or the distribution's own section when none does.
  * @note Impure — reads the config layers (never boots the store).
  */
 export async function collectColophon(
   runtime: PragmaRuntime,
 ): Promise<ColophonData> {
-  const sections: ColophonSection[] = [
-    {
-      kind: "pragma",
-      title: "pragma",
-      markdown: PRAGMA_COLOPHON,
-      summary: PRAGMA_COLOPHON_SUMMARY,
-      source: "built-in",
-    },
-  ];
-
-  const { assembleEffectiveModules } = await import(
+  const { loadEffectiveModules } = await import(
     "../../kernel/packs/collect.js"
   );
   const { capabilities } = await import("../index.js");
 
   let modules: readonly CapabilityModule[] = capabilities;
   try {
-    const layers = await runtime.loadConfig();
-    modules = assembleEffectiveModules(capabilities, layers);
+    modules = (await loadEffectiveModules(capabilities, runtime.cwd)).modules;
   } catch {
     // A bad config story is surfaced by the real commands; the colophon degrades
-    // to the static (bundled) modules rather than failing the narrative.
+    // to the static modules rather than failing the narrative. (A bad PACKAGE
+    // story never throws — it is dropped and reported by doctor.)
   }
 
+  const sections: ColophonSection[] = [];
   for (const module of modules) {
     if (module.colophon) {
       sections.push({
@@ -64,5 +78,17 @@ export async function collectColophon(
     }
   }
 
+  if (sections.length === 0 && distribution.colophon) {
+    sections.push({
+      kind: "pragma",
+      title: BIN_NAME,
+      markdown: distribution.colophon.markdown,
+      ...(distribution.colophon.summary === undefined
+        ? {}
+        : { summary: distribution.colophon.summary }),
+      source: "built-in",
+    });
+  }
+
   return { sections };
 }

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

@@ -7,13 +7,28 @@
  * The section title is composed as an H1 (`# <title>`) and fed through the ONE
  * styler, so all heading styling lives in a single place and the authored body
  * (which carries no leading H1) is never double-titled.
+ *
+ * The formatters render whatever sections the collector hands them and decide
+ * nothing about which sections exist — that choice (the domain's story, or the
+ * toolchain's when no domain tells one) belongs to the collector, and keeping
+ * it there is what lets these stay pure.
  */
 
+import { BIN_NAME } from "../../constants.js";
 import { defaultStyle, type RenderStyle } from "../../kernel/render/style.js";
-import type { Formatters } from "../../kernel/spec/types.js";
+import type { Formatters } from "../../kernel/spec/index.js";
 import { renderMarkdownToTerminal } from "./markdownTerminal.js";
 import type { ColophonData, ColophonSection } from "./types.js";
 
+/**
+ * The zero-section empty state: nothing declares a colophon — no active pack,
+ * and no story from the distribution itself. Blank output would read as a
+ * broken command, so say what is missing and name the command that fixes it.
+ * Like every empty state it goes to stderr with exit 0 (a calm success), so a
+ * script reading stdout still reads nothing.
+ */
+const EMPTY_NOTICE = `No colophon declared. A colophon comes from an active pack — build the store with \`${BIN_NAME} sources update\`.`;
+
 /** Render one section (title as H1 + body) as styled terminal Markdown. */
 function plainSection(section: ColophonSection, style: RenderStyle): string {
   return renderMarkdownToTerminal(
@@ -38,10 +53,19 @@ export const colophonFormatters: Formatters<ColophonData> = {
   },
 
   llm(data) {
+    // llm returns before the dispatcher's empty-state routing, so the
+    // condensed form carries its own zero-section line (the same shape the
+    // other empty states use) rather than handing an agent zero bytes.
+    if (data.sections.length === 0) return `_${EMPTY_NOTICE}_`;
     return data.sections.map(llmSection).join("\n\n");
   },
 
   json(data) {
     return JSON.stringify(data);
   },
+
+  // Zero sections: the dispatcher routes this to stderr (exit 0) so plain
+  // stdout stays empty; llm/json keep their own empty shapes.
+  emptyNotice: (data) =>
+    data.sections.length === 0 ? EMPTY_NOTICE : undefined,
 };

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

@@ -2,11 +2,14 @@
  * `pragma colophon` — the storeless, pack-extensible toolchain colophon (PR10).
  *
  * Pins the covenant-exact emitted slice (`{ v:"colophon", mcp:"colophon" }`),
- * proves the collector is storeless and combines pragma's built-in section with
- * the active pack's (the bundled `block` design-system colophon), exercises the
- * three formatter modes + `--format` precedence, holds CLI-json ≡ MCP
- * parity, and checks the pack-grammar accepts a `colophon` field (rejecting a
- * non-string).
+ * proves the collector is storeless and prints the ACTIVE DOMAIN's colophon
+ * (the bundled `block` design-system story) with no toolchain section in front
+ * of it, pins the empty state for a distribution and packs that declare none,
+ * exercises the three formatter modes + `--format` precedence, holds CLI-json
+ * ≡ MCP parity, and checks the pack-grammar accepts a `colophon` field
+ * (rejecting a non-string). The fallback — the toolchain's own section when no
+ * pack tells a story — is pinned where a story-less distribution exists:
+ * `identity.test.ts`'s fork.
  */
 
 import { mkdtempSync, readFileSync, rmSync } from "node:fs";
@@ -116,24 +119,42 @@ describe("colophon — storeless collector (PROTECTED)", () => {
   });
 });
 
-describe("colophon — combined content (pragma + active domain)", () => {
-  it("leads with pragma's built-in section", async () => {
-    const data = await collectColophon(bootRuntime(FLAGS, tmpCwd()));
-    const first = data.sections[0];
-    expect(first?.kind).toBe("pragma");
-    expect(first?.title).toBe("pragma");
-    expect(first?.source).toBe("built-in");
-    expect(first?.markdown.length).toBeGreaterThan(0);
-    expect(first?.summary?.length).toBeGreaterThan(0);
-  });
-
-  it("appends the bundled design-system (block) domain section", async () => {
+describe("colophon — the configured domain's story, and only that", () => {
+  it("prints the bundled design-system (block) domain section", async () => {
     const data = await collectColophon(bootRuntime(FLAGS, tmpCwd()));
     const block = data.sections.find((section) => section.title === "block");
     expect(block?.kind).toBe("pack");
     expect(block?.source).toBe("pack:block");
     expect(block?.markdown).toContain("knowledge graph");
   });
+
+  it("does NOT prepend the toolchain's own section when a domain has one", async () => {
+    // A configured reader asked about the domain. The paragraph about how this
+    // program is built is not an answer to that, and it used to arrive first.
+    const data = await collectColophon(bootRuntime(FLAGS, tmpCwd()));
+    // Guard the vacuous pass: `every` over nothing is true, and "no sections"
+    // is a different outcome than "only domain sections".
+    expect(data.sections.length).toBeGreaterThan(0);
+    expect(data.sections.every((section) => section.kind === "pack")).toBe(
+      true,
+    );
+  });
+
+  it("says so, on stderr, when nothing declares a colophon", () => {
+    // The collector can only reach this with neither a pack story nor a
+    // distribution one; the formatter is where the state is expressible, so
+    // the empty state is pinned here — bare stdout, guidance on stderr.
+    const empty: ColophonData = { sections: [] };
+    expect(colophonFormatters.plain(empty)).toBe("");
+    const notice = colophonFormatters.emptyNotice?.(empty);
+    expect(notice).toContain("No colophon declared");
+    expect(notice).toContain("sources update");
+    // llm returns before the dispatcher's stderr routing, so it says the same
+    // thing in its own body rather than emitting nothing.
+    expect(colophonFormatters.llm(empty)).toContain("No colophon declared");
+    // A populated payload has nothing to be calm about.
+    expect(colophonFormatters.emptyNotice?.(FIXTURE)).toBeUndefined();
+  });
 });
 
 describe("colophon — formatter modes", () => {
@@ -167,7 +188,7 @@ describe("colophon — formatter modes", () => {
     );
     const envelope = JSON.parse(outcome.stdout as string);
     expect(envelope.ok).toBe(true);
-    expect((envelope.data as ColophonData).sections[0]?.kind).toBe("pragma");
+    expect((envelope.data as ColophonData).sections[0]?.kind).toBe("pack");
   });
 
   it("--format llm selects the condensed Markdown form", async () => {
@@ -177,12 +198,12 @@ describe("colophon — formatter modes", () => {
       NO_MUT,
       bootRuntime(FLAGS_LLM, tmpCwd()),
     );
-    expect(outcome.stdout).toContain("## pragma");
+    expect(outcome.stdout).toContain("## block");
   });
 });
 
 describe("colophon — MCP parity", () => {
-  it("projects a read-only `colophon` tool that returns the pragma section", async () => {
+  it("projects a read-only `colophon` tool that returns the domain section", async () => {
     const cwd = tmpCwd();
     const mcp = await projectMcp([colophonModule], cwd);
     const tool = (await mcp.listTools()).find((t) => t.name === "colophon");
@@ -195,7 +216,7 @@ describe("colophon — MCP parity", () => {
       openWorldHint: false,
     });
     expect(envelope.ok).toBe(true);
-    expect((envelope.data as ColophonData).sections[0]?.kind).toBe("pragma");
+    expect((envelope.data as ColophonData).sections[0]?.kind).toBe("pack");
   });
 
   it("CLI --format json ≡ MCP colophon (same envelope)", async () => {

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

@@ -7,21 +7,25 @@
  * `infoVerb` / `doctorVerb` / `capabilitiesVerb`.
  */
 
+import { BIN_NAME } from "../../constants.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
-import type { CapabilityModule, VerbSpec } from "../../kernel/spec/types.js";
+import type { CapabilityModule, VerbSpec } from "../../kernel/spec/index.js";
 import { colophonFormatters } from "./colophon.render.js";
 import type { ColophonData } from "./types.js";
 
 const colophonVerb: VerbSpec<Record<string, unknown>, ColophonData> = {
   path: ["colophon"],
-  summary: "Narrate how pragma and the active domain are made.",
-  doc: "Storeless — a colophon for the toolchain. Prints pragma's own story (the effect monad, one-grammar-many-projections, the render/LLM-output model, storeless modularity, and the domain-as-data pack model) followed by the active pack's domain colophon. Also available as a condensed Markdown narration for agents, or as a structured JSON projection of the sections.",
+  summary: "Narrate how the active domain is made.",
+  doc: `Storeless — the colophon each active pack declares for its domain. With no pack telling a story, it prints the one ${BIN_NAME} declares for itself instead; with neither, it says so. Also available as a condensed Markdown narration for agents, or as a structured JSON projection of the sections.`,
   params: [],
   output: { formatters: colophonFormatters },
   examples: [
-    { cmd: "pragma colophon", note: "the toolchain + active domain story" },
     {
-      cmd: "pragma colophon --format llm",
+      cmd: `${BIN_NAME} colophon`,
+      note: "the active domain's story",
+    },
+    {
+      cmd: `${BIN_NAME} colophon --format llm`,
       note: "condensed Markdown for agents",
     },
   ],

package/src/capabilities/colophon/types.ts

@@ -2,28 +2,37 @@
  * Data shapes for `pragma colophon`.
  *
  * A colophon (the printer's end-note on how a book is made) for the toolchain:
- * one section narrating how pragma itself is built, followed by one section per
- * active pack/domain that declares a `colophon`. Storeless and read-only.
+ * one section narrating how the distribution itself is built — declared in its
+ * config, not authored in code — followed by one section per active pack/domain
+ * that declares a `colophon`. Storeless and read-only.
  */
 
-/** One colophon section — pragma's own, or an active pack's domain story. */
+/** One colophon section — the distribution's own, or an active pack's story. */
 export interface ColophonSection {
-  /** Whether this is pragma's built-in section or an active pack's. */
+  /**
+   * Whether this is the distribution's declared section or an active pack's.
+   * `"pragma"` is a FROZEN JSON-visible discriminant (wire compatibility, like
+   * the `pragma:` resource scheme) — it does not track the distribution's
+   * name; a fork's own section still carries `kind: "pragma"`.
+   */
   readonly kind: "pragma" | "pack";
-  /** Section heading — `"pragma"`, or the pack's noun/name. */
+  /** Section heading — the distribution's name, or the pack's noun/name. */
   readonly title: string;
   /**
    * The authored Markdown BODY (no leading H1 — the renderer supplies the
    * heading from {@link title}, so a section is never double-titled).
    */
   readonly markdown: string;
-  /** Optional condensed body for `--format llm` (pragma supplies one). */
+  /** Optional condensed body for `--format llm` (the declaration's `summary`). */
   readonly summary?: string;
   /** Provenance: `"built-in"`, or `"pack:<name>"`. */
   readonly source?: string;
 }
 
-/** The full `colophon` payload: pragma's section first, then active packs'. */
+/**
+ * The full `colophon` payload: the distribution's declared section first (when
+ * its config declares one), then active packs'.
+ */
 export interface ColophonData {
   readonly sections: readonly ColophonSection[];
 }

package/src/capabilities/config/collectConfigShow.test.ts

@@ -0,0 +1,58 @@
+/**
+ * `config show` payload projection — declared story BODIES never ship.
+ *
+ * MCP returns the JSON formatter's output verbatim, so anything in this payload
+ * is tokens in every `config_show` tool call. The distribution declares five
+ * read stories on its packs, whose bodies are SPARQL; carried through, they take
+ * the payload from ~1.3 KB to ~11 KB — larger than `capabilities`, the discovery
+ * tool, for the least useful content in the surface.
+ */
+
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import type { GlobalFlags } from "../../kernel/runtime/types.js";
+import { collectConfigShow } from "./collectConfigShow.js";
+
+const FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "json",
+  verbose: false,
+};
+
+describe("config show payload", () => {
+  it("names the declared packs but carries no story bodies", async () => {
+    const cwd = mkdtempSync(join(tmpdir(), "pragma-config-show-"));
+    const data = await collectConfigShow(bootRuntime(FLAGS, cwd));
+
+    // The pack declarations themselves are still fully reported…
+    expect(
+      data.config.packs?.map((pack) =>
+        typeof pack === "string" ? pack : pack.name,
+      ),
+    ).toEqual([
+      "@canonical/design-system",
+      "@canonical/anatomy-dsl",
+      "@canonical/code-standards",
+      "@canonical/ds-implementations",
+    ]);
+    for (const pack of data.config.packs ?? []) {
+      expect(
+        typeof pack === "string" ? undefined : pack.stories,
+      ).toBeUndefined();
+    }
+    expect(data.config.stories).toBeUndefined();
+
+    // …and provenance stays honest: the payload still says where they came from.
+    expect(data.origins.packs).toBe("default");
+    expect(data.origins.stories).toBe("default");
+
+    // The sharp end: no query text reaches the agent surface.
+    const payload = JSON.stringify(data);
+    expect(payload).not.toContain("SELECT ?");
+    expect(payload.length).toBeLessThan(3000);
+  });
+});

package/src/capabilities/config/collectConfigShow.ts

@@ -1,15 +1,52 @@
 /**
  * Collect the `config show` payload — the verb's run body (lazily imported).
  *
- * Storeless: read the layered config and pass it through with its provenance.
- * Dynamic-imported by the spec so building the tree never pulls the config
- * reader (or zod) onto the fast path.
+ * Storeless: read the layered config and pass it through with its provenance,
+ * minus the declared story BODIES (see {@link withoutStoryBodies}). Dynamic-
+ * imported by the spec so building the tree never pulls the config reader (or
+ * zod) onto the fast path.
  */
 
-import { readConfig } from "../../kernel/config/readConfig.js";
-import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import type {
+  PackDeclaration,
+  PragmaConfig,
+} from "../../kernel/config/index.js";
+import { readConfig } from "../../kernel/config/index.js";
+import type { PragmaRuntime } from "../../kernel/runtime/index.js";
 import type { ConfigShowData } from "./types.js";
 
+/** A pack declaration with any declared story bodies dropped. */
+function nameAndSourceOnly(pack: PackDeclaration): PackDeclaration {
+  if (typeof pack === "string") return pack;
+  return {
+    name: pack.name,
+    ...(pack.source === undefined ? {} : { source: pack.source }),
+  };
+}
+
+/**
+ * The effective config with declared story BODIES dropped — `packs` entries keep
+ * `{ name, source }`, and the top-level `stories` array is omitted.
+ *
+ * A PROJECTION of the payload, not a hiding of config: `origins` still reports
+ * where `packs` and `stories` came from, the plain and llm renders already print
+ * pack NAMES only, and `pragma capabilities` lists the verbs the stories
+ * produce. It exists because the bodies are SPARQL — the distribution's own five
+ * stories take `config show --format json` from 1.3 KB to 11 KB, and MCP returns
+ * the JSON formatter's output, so every `config_show` tool call would carry
+ * ~2.7k tokens of query text: the largest payload in the surface, for its least
+ * useful content.
+ */
+function withoutStoryBodies(config: PragmaConfig): PragmaConfig {
+  const { stories, ...rest } = config;
+  return {
+    ...rest,
+    ...(config.packs === undefined
+      ? {}
+      : { packs: config.packs.map(nameAndSourceOnly) }),
+  };
+}
+
 /**
  * Assemble the resolved config with provenance for the current runtime.
  *
@@ -22,7 +59,7 @@ export async function collectConfigShow(
 ): Promise<ConfigShowData> {
   const layers = await readConfig(runtime.cwd);
   return {
-    config: layers.config,
+    config: withoutStoryBodies(layers.config),
     origins: layers.origins,
     ...(layers.project.path ? { projectConfigPath: layers.project.path } : {}),
     globalConfigPath: layers.global.path,

package/src/capabilities/config/field.render.ts

@@ -1,12 +1,11 @@
 /**
- * Formatters for a `config <field>` setter — plain, llm, json (no ink).
+ * Formatters for the config writers (`set` and `unset`) — plain, llm, json.
  *
- * One shared formatter across all three setters (the field-table pattern): a
- * set reports the value and the file it landed in; a reset reports the removed
- * field.
+ * One shared formatter (the field-table pattern): a set reports the value and
+ * the file it landed in; an unset reports the removed field.
  */
 
-import type { Formatters } from "../../kernel/spec/types.js";
+import type { Formatters } from "../../kernel/spec/index.js";
 import type { ConfigFieldResult } from "./types.js";
 
 export const configFieldFormatters: Formatters<ConfigFieldResult> = {

package/src/capabilities/config/fields.ts

@@ -2,8 +2,8 @@
  * The config field table — one declarative row per writable field. Since AV-228
  * B3 retired the per-field `config tier`/`channel`/`detail` verbs, this table no
  * longer emits verbs of its own: it is the shared source of truth that drives
- * `config set <key> <value>` (via `runSet` → `runField`), giving `set` its
- * `<key>` enum, per-field reset sentinels, enum validation, and positional
+ * `config set <key> <value>` and `config get`/`config unset` (via `runSet` →
+ * `runField`), giving each its `<key>` enum, enum validation, and positional
  * shaping for free.
  */
 
@@ -21,61 +21,41 @@ export interface ConfigFieldSpec {
   readonly kind: "string" | "enum";
   /** The allowed values for an enum field. */
   readonly values?: readonly string[];
-  /** One-line field summary. */
-  readonly summary: string;
-  /** Extended help doc. */
-  readonly doc: string;
-  /** Reserved values that REMOVE the field instead of setting it. */
-  readonly resetSentinel?: readonly string[];
-  /** Field help examples. */
-  readonly examples: readonly { cmd: string; note?: string }[];
 }
 
 /**
- * The three writable fields. Only `tier` (a free string with a meaningful
- * "no value") carries reset sentinels; `channel`/`detail` reset by setting
- * their default (`normal`/`standard`). The migration path for the retired
- * field-verbs is `config set <field> <value>` (e.g. `config set tier apps/lxd`,
- * `config set tier none` to clear it).
+ * Values `config set` refuses for a FREE-STRING field: clearing a field is a
+ * command (`config unset <key>`), not a magic value — a value spelled `none`
+ * conflated "remove the field" with "set it to the string none". They stay
+ * reserved (rather than becoming writable) so the strings cannot silently
+ * change meaning; the rejection names `unset` as the owner of the job.
+ */
+export const RESERVED_CLEAR_VALUES: readonly string[] = [
+  "none",
+  "default",
+  "-",
+];
+
+/**
+ * The three writable fields. `channel`/`detail` are fixed enums;
+ * `tier` is a free string, cleared with `config unset tier`.
  */
 export const CONFIG_FIELDS: readonly ConfigFieldSpec[] = [
   {
     field: "tier",
     positional: "path",
     kind: "string",
-    resetSentinel: ["none", "default", "-"],
-    summary: "Set the active design-system tier.",
-    doc: "Writes the `tier` field to the global config. Pass `none`, `default`, or `-` to clear it. Written to the global layer only — project configs are authored by hand.",
-    examples: [
-      {
-        cmd: "pragma config set tier apps/lxd",
-        note: "scope reads to a tier",
-      },
-      { cmd: "pragma config set tier none", note: "clear the tier" },
-    ],
   },
   {
     field: "channel",
     positional: "name",
     kind: "enum",
     values: CHANNELS,
-    summary: "Set the release channel controlling component visibility.",
-    doc: "Writes the `channel` field to the global config. Reset by setting the default, `normal`.",
-    examples: [
-      { cmd: "pragma config set channel experimental" },
-      { cmd: "pragma config set channel normal", note: "back to the default" },
-    ],
   },
   {
     field: "detail",
     positional: "level",
     kind: "enum",
     values: DETAIL_LEVELS,
-    summary: "Set the default progressive-disclosure level.",
-    doc: "Writes the `detail` field to the global config. Reset by setting the default, `standard`.",
-    examples: [
-      { cmd: "pragma config set detail detailed" },
-      { cmd: "pragma config set detail standard", note: "back to the default" },
-    ],
   },
 ];

package/src/capabilities/config/get.verb.ts

@@ -0,0 +1,70 @@
+/**
+ * `config get <key>` — read ONE resolved config value, scriptably.
+ *
+ * `config show` dumps everything with provenance; scripting one value out of
+ * it needed `--format json` plus a JSON tool. `get` prints the bare resolved
+ * value on stdout (an unset field prints nothing, exit 0), so shell
+ * substitution works directly; the json form carries the field, the value,
+ * and the layer that supplied it.
+ *
+ * The plain and llm forms are the SAME bare value, which is the one place in
+ * the grammar where those two forms may not differ: `TIER=$(… config get
+ * tier)` pipes stdout, and a pipe auto-selects llm, so a decorated llm line
+ * would put backticks and a provenance clause into the variable the command
+ * exists to fill. Provenance has a home already — `--format json` here, and
+ * `config show` for the whole picture.
+ */
+
+import { BIN_NAME } from "../../constants.js";
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import type { Formatters, VerbSpec } from "../../kernel/spec/index.js";
+import { CONFIG_FIELDS } from "./fields.js";
+import type { ConfigGetData } from "./types.js";
+
+/** The readable field names — the `<key>` enum, in covenant order. */
+const CONFIG_KEYS = CONFIG_FIELDS.map((field) => field.field);
+
+/** The bare value, or nothing at all when the field is unset. */
+const bareValue = (data: ConfigGetData): string =>
+  data.value === undefined ? "" : String(data.value);
+
+const configGetFormatters: Formatters<ConfigGetData> = {
+  // The bare value IS the contract: `TIER=$(pragma config get tier)`.
+  plain: bareValue,
+  llm: bareValue,
+  json: (data) => JSON.stringify(data),
+};
+
+const getVerb: VerbSpec<Record<string, unknown>, ConfigGetData> = {
+  path: ["config", "get"],
+  summary: "Print one resolved config value.",
+  doc: "Reads the effective value of a single field after layering — built-in defaults, the global config, and the nearest project config. Prints the bare value (nothing when the field is unset), so the output substitutes directly into a shell.",
+  params: [
+    {
+      kind: "enum",
+      name: "key",
+      doc: "The config field to read.",
+      values: CONFIG_KEYS,
+      required: true,
+      positional: true,
+    },
+  ],
+  output: { formatters: configGetFormatters },
+  examples: [
+    { cmd: `${BIN_NAME} config get tier` },
+    { cmd: `${BIN_NAME} config get channel --format json` },
+  ],
+  capability: {
+    needsStore: false,
+    mutates: false,
+    mcp: {
+      expose: true,
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+  },
+  run: (params, runtime) =>
+    import("./runGet.js").then((m) => m.runGet(params, runtime)),
+};
+
+/** The `config get` verb. */
+export const configGetVerb = asVerb(getVerb);