@canonical/pragma-cli 0.34.0 → 0.36.0

package/src/capabilities/capabilities/hints.ts

@@ -58,7 +58,13 @@ export const TOOL_HINTS: Record<string, ToolHint> = {
   },
   colophon: {
     category: "read",
-    use_when: `Understanding how ${BIN_NAME} and the active domain are built — the toolchain + domain colophon, for onboarding or a demo`,
+    use_when:
+      "Understanding how the active domain is built — its declared colophon, for onboarding or a demo",
+  },
+  config_get: {
+    category: "read",
+    use_when:
+      "Reading ONE config field's effective value and the layer it came from — the single-value form of config_show",
   },
   config_show: {
     category: "read",
@@ -99,11 +105,6 @@ export const TOOL_HINTS: Record<string, ToolHint> = {
     use_when:
       "Exploring the full schema of a namespace by name — classes, properties, and hierarchy",
   },
-  ontology_show: {
-    category: "read",
-    use_when:
-      "Deprecated alias of ontology_lookup — exploring a namespace's schema (prefer ontology_lookup)",
-  },
   prompt_list: {
     category: "read",
     use_when: "Browsing the workflow prompt templates the active graph offers",
@@ -115,7 +116,7 @@ export const TOOL_HINTS: Record<string, ToolHint> = {
   },
   skill_list: {
     category: "read",
-    use_when: "Discovering agent skills provided by installed packages",
+    use_when: "Discovering agent skills provided by installed packs",
   },
   skill_lookup: {
     category: "read",
@@ -141,6 +142,25 @@ export const TOOL_HINTS: Record<string, ToolHint> = {
     category: "read",
     use_when: "Discovering which standard categories exist before filtering",
   },
+  concept_list: {
+    category: "read",
+    use_when:
+      "Browsing long-form design-system concepts (foundations, how-to guides, decision guides)",
+  },
+  concept_lookup: {
+    category: "read",
+    use_when: "Reading a concept's full Markdown documentation by name or IRI",
+  },
+  implementation_list: {
+    category: "read",
+    use_when:
+      "Finding which library implements a block, on which platform, and where its source lives",
+  },
+  implementation_libraries: {
+    category: "read",
+    use_when:
+      "Discovering which implementation libraries exist, and how much of the design system each covers",
+  },
   standard_sample: {
     category: "read",
     use_when:
@@ -176,6 +196,11 @@ export const TOOL_HINTS: Record<string, ToolHint> = {
     use_when:
       "Setting any config field by name — tier, channel, or detail (e.g. `config set tier apps/lxd`)",
   },
+  config_unset: {
+    category: "write",
+    use_when:
+      'Clearing a config field so the built-in default applies again — no value means "remove", this tool does',
+  },
   create_component: {
     category: "write",
     use_when: "Scaffolding a new component (React, Svelte, or Lit)",

package/src/capabilities/capabilities/index.ts

@@ -3,7 +3,7 @@
  * that replaces the retired `llm` tool.
  */
 
-import type { CapabilityModule } from "../../kernel/spec/types.js";
+import type { CapabilityModule } from "../../kernel/spec/index.js";
 import { capabilitiesSelfVerb } from "./capabilities.verb.js";
 
 /** The `capabilities` capability module (a single storeless self-verb). */

package/src/capabilities/colophon/collectColophon.ts

@@ -18,42 +18,40 @@
 
 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 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 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.
+ * 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: the distribution's declared 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[] = [];
-  if (distribution.colophon) {
-    sections.push({
-      kind: "pragma",
-      title: BIN_NAME,
-      markdown: distribution.colophon.markdown,
-      ...(distribution.colophon.summary === undefined
-        ? {}
-        : { summary: distribution.colophon.summary }),
-      source: "built-in",
-    });
-  }
-
   const { loadEffectiveModules } = await import(
     "../../kernel/packs/collect.js"
   );
@@ -68,6 +66,7 @@ export async function collectColophon(
     // story never throws — it is dropped and reported by doctor.)
   }
 
+  const sections: ColophonSection[] = [];
   for (const module of modules) {
     if (module.colophon) {
       sections.push({
@@ -79,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,18 @@ 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.
+  notice: (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.notice?.(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.notice?.(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

@@ -9,20 +9,20 @@
 
 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 ${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.`,
+  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: `${BIN_NAME} colophon`,
-      note: "the toolchain + active domain story",
+      note: "the active domain's story",
     },
     {
       cmd: `${BIN_NAME} colophon --format llm`,

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

@@ -37,6 +37,7 @@ describe("config show payload", () => {
       "@canonical/design-system",
       "@canonical/anatomy-dsl",
       "@canonical/code-standards",
+      "@canonical/ds-implementations",
     ]);
     for (const pack of data.config.packs ?? []) {
       expect(

package/src/capabilities/config/collectConfigShow.ts

@@ -7,12 +7,12 @@
  * 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";
+} 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. */

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,23 +21,30 @@ export interface ConfigFieldSpec {
   readonly kind: "string" | "enum";
   /** The allowed values for an enum field. */
   readonly values?: readonly string[];
-  /** Reserved values that REMOVE the field instead of setting it. */
-  readonly resetSentinel?: readonly 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", "-"],
   },
   {
     field: "channel",

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);