@canonical/pragma-cli 0.32.0 → 0.34.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,44 +16,56 @@
  * into a static import.
  */
 
+import { BIN_NAME } from "../../constants.js";
+import distribution from "../../kernel/config/defaults.js";
 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 type { ColophonData, ColophonSection } from "./types.js";
 
 /**
  * Assemble the colophon data for the current runtime.
  *
+ * The toolchain section is DECLARED, not authored here: the distribution
+ * config's `colophon` field carries the narrative (and its condensed summary),
+ * and this collector renders whatever it declares under the distribution's own
+ * name — a fork edits its config, never this module. A distribution declaring
+ * no `colophon` gets no toolchain section: the packs' domain colophons stand
+ * alone. The `kind: "pragma"` value is a frozen JSON discriminant (wire
+ * compatibility), not the distribution's name.
+ *
  * @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: the distribution's declared section,
+ *   then each active pack/domain that declares a `colophon`.
  * @note Impure — reads the config layers (never boots the store).
  */
 export async function collectColophon(
   runtime: PragmaRuntime,
 ): Promise<ColophonData> {
-  const sections: ColophonSection[] = [
-    {
+  const sections: ColophonSection[] = [];
+  if (distribution.colophon) {
+    sections.push({
       kind: "pragma",
-      title: "pragma",
-      markdown: PRAGMA_COLOPHON,
-      summary: PRAGMA_COLOPHON_SUMMARY,
+      title: BIN_NAME,
+      markdown: distribution.colophon.markdown,
+      ...(distribution.colophon.summary === undefined
+        ? {}
+        : { summary: distribution.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.)
   }
 
   for (const module of modules) {

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

@@ -78,10 +78,37 @@ describe("colophon render golden — color-free (chalk.level = 0)", () => {
   });
 });
 
-describe("colophon render — color ON", () => {
-  it("plain emits ANSI escapes when chalk color is enabled", () => {
+/** Run `body` with stdout's `isTTY` forced to `value`, then restore it. */
+function withStdoutTty(value: boolean | undefined, body: () => void): void {
+  const stream = process.stdout as { isTTY?: boolean };
+  const saved = stream.isTTY;
+  stream.isTTY = value;
+  try {
+    body();
+  } finally {
+    stream.isTTY = saved;
+  }
+}
+
+describe("colophon render — color ON (attended TTY)", () => {
+  it("plain emits ANSI escapes on a color-capable TTY", () => {
     chalk.level = 1;
-    // biome-ignore lint/suspicious/noControlCharactersInRegex: asserting the literal ESC byte is the point
-    expect(colophonFormatters.plain(FIXTURE)).toMatch(/\x1b\[/);
+    withStdoutTty(true, () => {
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: asserting the literal ESC byte is the point
+      expect(colophonFormatters.plain(FIXTURE)).toMatch(/\x1b\[/);
+    });
+  });
+});
+
+describe("colophon render — piped output is ANSI-free (F1)", () => {
+  it("plain emits ZERO ANSI off a TTY even when chalk reports color (CI/FORCE_COLOR)", () => {
+    // The CI leak: `supports-color` sets a non-zero level off a TTY under
+    // GITHUB_ACTIONS / FORCE_COLOR, so gating on `chalk.level` alone bled ANSI
+    // into `colophon --format plain | tee`. The isTTY gate closes it.
+    chalk.level = 3;
+    withStdoutTty(undefined, () => {
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: asserting NO ESC byte survives
+      expect(colophonFormatters.plain(FIXTURE)).not.toMatch(/\x1b\[/);
+    });
   });
 });

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

@@ -9,23 +9,32 @@
  * (which carries no leading H1) is never double-titled.
  */
 
+import { defaultStyle, type RenderStyle } from "../../kernel/render/style.js";
 import type { Formatters } from "../../kernel/spec/types.js";
 import { renderMarkdownToTerminal } from "./markdownTerminal.js";
 import type { ColophonData, ColophonSection } from "./types.js";
 
 /** Render one section (title as H1 + body) as styled terminal Markdown. */
-function plainSection(section: ColophonSection): string {
-  return renderMarkdownToTerminal(`# ${section.title}\n\n${section.markdown}`);
+function plainSection(section: ColophonSection, style: RenderStyle): string {
+  return renderMarkdownToTerminal(
+    `# ${section.title}\n\n${section.markdown}`,
+    style,
+  );
 }
 
-/** Render one section as condensed Markdown for `--llm` (summary preferred). */
+/** Render one section as condensed Markdown for `--format llm` (summary preferred). */
 function llmSection(section: ColophonSection): string {
   return `## ${section.title}\n\n${section.summary ?? section.markdown}`;
 }
 
 export const colophonFormatters: Formatters<ColophonData> = {
   plain(data) {
-    return data.sections.map(plainSection).join("\n\n");
+    // Resolve the TTY decision ONCE (impure: reads stdout.isTTY + chalk level),
+    // then render every section through the same inert-off-a-TTY styler.
+    const style = defaultStyle();
+    return data.sections
+      .map((section) => plainSection(section, style))
+      .join("\n\n");
   },
 
   llm(data) {

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

@@ -4,7 +4,7 @@
  * 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`/`--llm` precedence, holds CLI-json ≡ MCP
+ * three formatter modes + `--format` precedence, holds CLI-json ≡ MCP
  * parity, and checks the pack-grammar accepts a `colophon` field (rejecting a
  * non-string).
  */
@@ -47,7 +47,7 @@ const FLAGS: GlobalFlags = {
   verbose: false,
 };
 const FLAGS_JSON: GlobalFlags = { ...FLAGS, format: "json" };
-const FLAGS_LLM: GlobalFlags = { ...FLAGS, llm: true };
+const FLAGS_LLM: GlobalFlags = { ...FLAGS, format: "llm", llm: true };
 const NO_MUT = { dryRun: false, undo: false, yes: false };
 
 /** A deterministic two-section fixture for pure formatter assertions. */
@@ -170,7 +170,7 @@ describe("colophon — formatter modes", () => {
     expect((envelope.data as ColophonData).sections[0]?.kind).toBe("pragma");
   });
 
-  it("--llm selects the condensed Markdown form", async () => {
+  it("--format llm selects the condensed Markdown form", async () => {
     const outcome = await executeVerb(
       colophonVerb,
       {},

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

@@ -7,6 +7,7 @@
  * `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 { colophonFormatters } from "./colophon.render.js";
@@ -14,13 +15,19 @@ 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 ${BIN_NAME} and the active domain are made.`,
+  doc: `Storeless — a colophon for the toolchain. Prints the story the distribution declares for itself (its config's \`colophon\`) 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.`,
   params: [],
   output: { formatters: colophonFormatters },
   examples: [
-    { cmd: "pragma colophon", note: "the toolchain + active domain story" },
-    { cmd: "pragma colophon --llm", note: "condensed Markdown for agents" },
+    {
+      cmd: `${BIN_NAME} colophon`,
+      note: "the toolchain + active domain story",
+    },
+    {
+      cmd: `${BIN_NAME} colophon --format llm`,
+      note: "condensed Markdown for agents",
+    },
   ],
   capability: {
     needsStore: false,

package/src/capabilities/colophon/markdownTerminal.ts

@@ -7,11 +7,14 @@
  *
  * Single consumer today (`pragma colophon`); a promotion candidate to
  * `kernel/render/` if another verb ever wants the same helper. Determinism note:
- * styling routes entirely through `chalk`, so a test forcing `chalk.level = 0`
- * gets a stable, color-free snapshot of the structural transforms.
+ * styling routes through the shared {@link RenderStyle} seam (color only on a
+ * color-capable TTY), so piped / redirected / CI output — where `supports-color`
+ * can report a level with no TTY — stays byte-for-byte the color-free structural
+ * transform, and a test can force either mode by passing an explicit style.
  */
 
 import chalk from "chalk";
+import { defaultStyle, type RenderStyle } from "../../kernel/render/style.js";
 
 /** Full ANSI escape sequences (`ESC [ … final-letter`) — colour/cursor codes. */
 // biome-ignore lint/suspicious/noControlCharactersInRegex: deliberate control-char scrub
@@ -33,25 +36,35 @@ function stripControl(line: string): string {
   return line.replace(ANSI_ESCAPE, "").replace(C0_CONTROLS, "");
 }
 
-/** Style inline `**bold**` and `` `code` `` spans within one line. */
-function styleInline(text: string): string {
+/**
+ * Style inline `**bold**` and `` `code` `` spans within one line. The `**` / `` ` ``
+ * markers are ALWAYS consumed; off a TTY the styler is inert, so the markers drop
+ * with no color (byte-identical to the pre-seam `chalk.level = 0` behavior).
+ */
+function styleInline(text: string, style: RenderStyle): string {
   return text
-    .replace(/\*\*([^*]+)\*\*/g, (_match, inner: string) => chalk.bold(inner))
-    .replace(/`([^`]+)`/g, (_match, inner: string) => chalk.cyan(inner));
+    .replace(/\*\*([^*]+)\*\*/g, (_match, inner: string) => style.bold(inner))
+    .replace(/`([^`]+)`/g, (_match, inner: string) => style.cyan(inner));
 }
 
 /**
  * Render a Markdown string to styled terminal text.
  *
  * @param markdown - The authored Markdown body.
- * @returns The chalk-styled terminal string (no trailing newline).
+ * @param style - The TTY styler; defaults to the process style. On a color-capable
+ *   terminal headings/bullets/inline spans are tinted; off a TTY the styler is
+ *   inert, so the output is byte-identical to the color-free structural form.
+ * @returns The styled terminal string (no trailing newline).
  */
-export function renderMarkdownToTerminal(markdown: string): string {
+export function renderMarkdownToTerminal(
+  markdown: string,
+  style: RenderStyle = defaultStyle(),
+): string {
   const lines: string[] = [];
   let inFence = false;
 
   for (const rawLine of markdown.split("\n")) {
-    // Scrub pack-authored terminal control codes BEFORE our own chalk styling
+    // Scrub pack-authored terminal control codes BEFORE our own styling
     // (colophon bodies are domain-as-data — never a channel for raw ANSI).
     const raw = stripControl(rawLine);
     // A fence toggles code mode; the ``` markers themselves are dropped.
@@ -60,25 +73,31 @@ export function renderMarkdownToTerminal(markdown: string): string {
       continue;
     }
     if (inFence) {
-      lines.push(chalk.dim(`  ${raw}`));
+      lines.push(style.dim(`  ${raw}`));
       continue;
     }
 
     const heading = /^(#{1,6})\s+(.+)$/.exec(raw);
     if (heading) {
       const level = heading[1]?.length ?? 1;
-      const text = styleInline(heading[2] ?? "");
-      lines.push(level === 1 ? chalk.bold.underline(text) : chalk.bold(text));
+      const text = styleInline(heading[2] ?? "", style);
+      // H1 earns bold+underline on a TTY; underline is outside the RenderStyle
+      // seam, so reach for chalk only when the styler is enabled.
+      lines.push(
+        level === 1 && style.enabled
+          ? chalk.bold.underline(text)
+          : style.bold(text),
+      );
       continue;
     }
 
     const bullet = /^\s*[-*]\s+(.+)$/.exec(raw);
     if (bullet) {
-      lines.push(`  ${chalk.cyan("•")} ${styleInline(bullet[1] ?? "")}`);
+      lines.push(`  ${style.cyan("•")} ${styleInline(bullet[1] ?? "", style)}`);
       continue;
     }
 
-    lines.push(styleInline(raw));
+    lines.push(styleInline(raw, style));
   }
 
   return lines.join("\n");

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 `--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,57 @@
+/**
+ * `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",
+    ]);
+    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 {
+  PackDeclaration,
+  PragmaConfig,
+} from "../../kernel/config/types.js";
 import type { PragmaRuntime } from "../../kernel/runtime/types.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/fields.ts

@@ -1,28 +1,19 @@
 /**
- * The config field table — one declarative row per writable field drives all
- * three setters (`tier` / `channel` / `detail`), the way the pack grammar
- * compiles read verbs from a table.
- *
- * Covenant-exact emission is the hard gate (surfaceConformance): each verb must
- * `emitVerb` to `{ v:<field>, args:["<positional>"], mutates:true,
- * mcp:"config_<field>" }` — one REQUIRED positional, NO flags, NO needsStore
- * (config setters are storeless; the old store-backed `validateTier` is dropped
- * — PARITY_GAP `config-tier-no-ontology-validation`). The factory produces
- * exactly that shape; the `field.test.ts` deep-equals the golden slice.
+ * 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
+ * shaping for free.
  */
 
-import type { Task } from "@canonical/task";
 import { DETAIL_LEVELS } from "../../constants.js";
 import type { RawConfig } from "../../kernel/config/types.js";
 import { CHANNELS } from "../../kernel/config/types.js";
-import { asVerb } from "../../kernel/spec/asVerb.js";
-import type { ParamSpec, VerbSpec } from "../../kernel/spec/types.js";
-import { configFieldFormatters } from "./field.render.js";
-import type { ConfigFieldResult } from "./types.js";
 
 /** One writable config field and how its single positional is shaped/validated. */
 export interface ConfigFieldSpec {
-  /** The `RawConfig` key written (also the verb label + `config_<field>` tool). */
+  /** The `RawConfig` key written (also the `config set` `<key>` enum member). */
   readonly field: keyof RawConfig & ("tier" | "channel" | "detail");
   /** The positional param NAME — its usage token is `<positional>` (covenant). */
   readonly positional: string;
@@ -30,24 +21,16 @@ export interface ConfigFieldSpec {
   readonly kind: "string" | "enum";
   /** The allowed values for an enum field. */
   readonly values?: readonly string[];
-  /** One-line verb summary. */
-  readonly summary: string;
-  /** Extended help doc. */
-  readonly doc: string;
   /** Reserved values that REMOVE the field instead of setting it. */
   readonly resetSentinel?: readonly string[];
-  /** Verb 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`) — no `--reset` flag exists, because a
- * flag would emit `flags:[...]` and break the covenant (PARITY_GAP
- * `config-field-reset-sentinel`). Query is `config show` — the covenant gives
- * each setter exactly ONE required positional, so a no-arg "print current" mode
- * is impossible here (PARITY_GAP `config-field-query-via-show`).
+ * 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).
  */
 export const CONFIG_FIELDS: readonly ConfigFieldSpec[] = [
   {
@@ -55,98 +38,17 @@ export const CONFIG_FIELDS: readonly ConfigFieldSpec[] = [
     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 tier apps/lxd", note: "scope reads to a tier" },
-      { cmd: "pragma config 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 channel experimental" },
-      { cmd: "pragma config 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 detail detailed" },
-      { cmd: "pragma config detail standard", note: "back to the default" },
-    ],
   },
 ];
-
-/** The single required positional for a field, shaped per its `kind`. */
-function fieldPositional(spec: ConfigFieldSpec): ParamSpec {
-  // Name the positional by its usage token (`<path>`/`<name>`/`<level>`) so the
-  // doc and the token agree (was "The tier value to write." for a `<path>`).
-  const doc = `The ${spec.field} ${spec.positional} to write.`;
-  if (spec.kind === "enum") {
-    return {
-      kind: "enum",
-      name: spec.positional,
-      doc,
-      values: spec.values ?? [],
-      required: true,
-      positional: true,
-    };
-  }
-  return {
-    kind: "string",
-    name: spec.positional,
-    doc,
-    required: true,
-    positional: true,
-  };
-}
-
-/**
- * Build one storeless, mutating config setter from a field spec.
- *
- * `run` lazily imports the write body and presents `Promise<Task<R>>` through
- * the `Task<R>` arm by the honest cast (the same seam `sources update` uses) —
- * a literal `Promise<Task>` union arm would poison async read-verb inference.
- *
- * @param spec - The field-table row.
- * @returns The verb spec for `config <field>`.
- */
-export function fieldVerb(
-  spec: ConfigFieldSpec,
-): VerbSpec<Record<string, unknown>, ConfigFieldResult> {
-  return {
-    path: ["config", spec.field],
-    summary: spec.summary,
-    doc: spec.doc,
-    params: [fieldPositional(spec)],
-    output: { formatters: configFieldFormatters },
-    examples: [...spec.examples],
-    capability: {
-      needsStore: false,
-      mutates: true,
-      mcp: {
-        expose: true,
-        annotations: { readOnlyHint: false, openWorldHint: false },
-      },
-    },
-    run: (params) =>
-      import("./runField.js").then((m) =>
-        m.runField(spec, params),
-      ) as unknown as Task<ConfigFieldResult>,
-  };
-}
-
-/** The three config setters, in covenant order (tier, channel, detail). */
-export const configFieldVerbs: VerbSpec[] =
-  CONFIG_FIELDS.map(fieldVerb).map(asVerb);