@canonical/pragma-cli 0.34.0 → 0.36.0

package/src/kernel/completion/shellDrive.test.ts

@@ -50,9 +50,11 @@ import { emitScripts } from "./emitScripts.js";
  *   scripts; the live bash script offers the live grammar's structure with
  *   zero process exec; it hands `__complete` a literal argv and offers back
  *   what it answers; it honours the `minChars` gate. The bash describes are
- *   deliberately NOT gated on a `hasShell` probe — the package pins
- *   `os: ["linux"]`, so a machine with no usable bash should fail this file
- *   loudly rather than skip it and report nothing.
+ *   deliberately NOT gated on a `hasShell` probe — CI runs linux with a modern
+ *   bash, so a machine with no usable bash should fail this file loudly
+ *   rather than skip it and report nothing. (The package no longer pins
+ *   `os: ["linux"]`; run on a bash-3.2 macOS box this fails loudly, which is
+ *   the intended signal — see `templates/bash.ts` on the mapfile floor.)
  * - **By execution only where the shell is installed:** the same guarantees
  *   for zsh and fish. Those describes `skipIf` the shell is absent, which
  *   includes this development box and, today, CI — so on those machines they
@@ -319,7 +321,7 @@ const STRUCTURE = [
     at: "pragma co",
     words: ["pragma", "co"],
     cword: 1,
-    offers: ["colophon", "config"],
+    offers: ["colophon", "concept", "config"],
   },
   {
     at: "pragma block <TAB>",
@@ -331,7 +333,7 @@ const STRUCTURE = [
     at: "pragma setup <TAB>",
     words: ["pragma", "setup", ""],
     cword: 2,
-    offers: ["completions", "lsp", "mcp", "skills"],
+    offers: ["completions", "config", "lsp", "mcp", "skills"],
   },
   {
     at: "pragma create <TAB>",
@@ -349,7 +351,14 @@ const STRUCTURE = [
     at: "pragma block lookup --<TAB>",
     words: ["pragma", "block", "lookup", "--"],
     cword: 3,
-    offers: ["--detail", "--format", "--help", "--verbose"],
+    offers: [
+      "--detail",
+      "--format",
+      "--help",
+      "--no-headers",
+      "--quiet",
+      "--verbose",
+    ],
   },
 ] as const;
 
@@ -362,10 +371,12 @@ const NOUNS = [
   "block",
   "capabilities",
   "colophon",
+  "concept",
   "config",
   "create",
   "doctor",
   "graph",
+  "implementation",
   "info",
   "mcp",
   "modifier",
@@ -378,6 +389,7 @@ const NOUNS = [
   "tier",
   "token",
   "upgrade",
+  "version",
 ] as const;
 
 describe("generated bash — the live grammar's script", () => {
@@ -524,11 +536,11 @@ describe.skipIf(!hasShell("fish"))(
     });
 
     it.each([
-      { line: "pragma co", offers: ["colophon", "config"] },
+      { line: "pragma co", offers: ["colophon", "concept", "config"] },
       { line: "pragma block ", offers: ["list", "lookup", "sample"] },
       {
         line: "pragma setup ",
-        offers: ["completions", "lsp", "mcp", "skills"],
+        offers: ["completions", "config", "lsp", "mcp", "skills"],
       },
       {
         line: "pragma create ",
@@ -572,7 +584,14 @@ describe.skipIf(!hasShell("fish"))(
       const { reply, calls } = driveFish(live.fish, "pragma block lookup --");
       expect(calls).toEqual([]);
       expect(reply.sort()).toEqual(
-        ["--detail", "--format", "--help", "--verbose"].sort(),
+        [
+          "--detail",
+          "--format",
+          "--help",
+          "--no-headers",
+          "--quiet",
+          "--verbose",
+        ].sort(),
       );
     });
 

package/src/kernel/completion/templates/bash.ts

@@ -1,7 +1,12 @@
 // biome-ignore-all lint/suspicious/noTemplateCurlyInString: bash parameter expansions, not JS templates
 /**
- * The bash completion script (static tier). Requires bash >= 4 (mapfile);
- * the package pins os:["linux"], where that floor holds.
+ * The bash completion script (static tier). Requires bash >= 4 for `mapfile`.
+ * That floor is NOT guaranteed by the platform any more: the package dropped
+ * its `os: ["linux"]` pin when it stopped shipping a linux-x64 executable, and
+ * macOS still ships bash 3.2, which has no `mapfile`. `setup completions`
+ * writes this script wherever it is asked to; on such a machine the user's
+ * remedy is a newer bash (zsh and fish are unaffected and are the platform
+ * defaults there).
  *
  * Structure — nouns, verbs, flag names, enum values — is inlined into
  * generator-validated LITERAL `compgen -W` tables (never a variable, never

package/src/kernel/completion/templates/index.ts

@@ -0,0 +1,23 @@
+/**
+ * The static shell-completion templates — one emitter per shell, all fed by
+ * the same completion model.
+ *
+ * The three exports are the domain: each takes the model and returns the text
+ * of a script `setup completions` writes to disk. They are grouped because
+ * they are interchangeable answers to one question — which shell is this — and
+ * because they must stay in step: a fact the model carries has to be
+ * expressible in all three, so a change to one is a change to all three.
+ *
+ * What the barrel does NOT expose is the rendering layer underneath
+ * (`shared.ts`): the per-verb views, the token allowlist re-assertion, the
+ * name/flag list derivations. Those exist so the scripts cannot disagree about
+ * structure, and they are safe only in the emit context they were built for —
+ * every token they return has been re-checked against the safety allowlist on
+ * its way into script text. Offering them across the domain boundary would
+ * offer a way to compose that text without that check, which is the one thing
+ * this domain exists to make impossible.
+ */
+
+export { bashScript } from "./bash.js";
+export { fishScript } from "./fish.js";
+export { zshScript } from "./zsh.js";

package/src/kernel/completion/types.ts

@@ -77,6 +77,13 @@ export interface VerbEntry {
   readonly flags: readonly FlagEntry[];
   /** The verb's positionals, in declared order. */
   readonly positionals: readonly PositionalEntry[];
+  /**
+   * Segment pseudo-verbs beneath this verb (a module-mounted subtree, from
+   * `CapabilityModule.cliProjection.completionChildren`), each with its own
+   * flags/positionals/children. The parse walk descends into a matching
+   * child before flag/positional resolution.
+   */
+  readonly children?: readonly VerbEntry[];
 }
 
 /** One noun with its self-verb (if any) and sub-verbs. */

package/src/kernel/config/defaults.test.ts

@@ -15,6 +15,13 @@ describe("defaults — the validated distribution config (pragma.conf.ts)", () =
     // `collectColophon` reads exactly this object. Pin the shape and the two
     // stable fragments — the story's own subject and the maker line the old
     // one-line `colophon` string carried (folded in when the field went live).
+    //
+    // DOMAIN FIRST: this section is deliberately a one-liner that hands off to
+    // `docs/architecture.md`. `pragma colophon` renders it ABOVE the active
+    // pack's domain colophon, and a reader reaching for the colophon wants the
+    // design system, not the toolchain that serves it. The length pin is the
+    // ruling: architecture prose belongs in the docs, not in front of the
+    // domain every reader came for.
     expect(defaults.colophon?.markdown).toContain("domain-based toolchain");
     expect(defaults.colophon?.markdown).toContain(
       "Made by the Canonical Webteam — https://canonical.com.",
@@ -23,9 +30,21 @@ describe("defaults — the validated distribution config (pragma.conf.ts)", () =
     // Bodies, not documents: the renderer supplies the H1 from the name.
     expect(defaults.colophon?.markdown.startsWith("#")).toBe(false);
     expect(defaults.colophon?.summary?.startsWith("#")).toBe(false);
+    // The handoff, and the brevity that makes it honest (see the note above).
+    // It is a URL, not a repo path: `docs/` is outside the package's `files`
+    // allowlist and is not copied into `dist`, so a path would name a file no
+    // installed user has. A bare `docs/architecture.md` must fail here.
+    expect(defaults.colophon?.markdown).toContain(
+      "https://github.com/canonical/pragma/blob/main/packages/cli/pragma/docs/architecture.md",
+    );
+    expect(defaults.colophon?.summary).toContain(
+      "https://github.com/canonical/pragma/blob/main/packages/cli/pragma/docs/architecture.md",
+    );
+    expect(defaults.colophon?.markdown.length).toBeLessThan(400);
+    expect(defaults.colophon?.summary?.length).toBeLessThan(400);
   });
 
-  it("ships the three canonical default packs (git+https sources)", () => {
+  it("ships the four canonical default packs (git+https sources)", () => {
     expect(
       defaults.packs?.map((pack) =>
         typeof pack === "string"
@@ -43,7 +62,12 @@ describe("defaults — the validated distribution config (pragma.conf.ts)", () =
       },
       {
         name: "@canonical/code-standards",
-        source: "git+https://github.com/canonical/web-code-standards.git#main",
+        source:
+          "git+https://github.com/canonical/web-code-standards.git#v0.1.5",
+      },
+      {
+        name: "@canonical/ds-implementations",
+        source: "git+https://github.com/canonical/pragma.git#main",
       },
     ]);
   });
@@ -55,7 +79,7 @@ describe("defaults — the validated distribution config (pragma.conf.ts)", () =
     const storyCounts = defaults.packs?.map((pack) =>
       typeof pack === "string" ? 0 : (pack.stories?.length ?? 0),
     );
-    expect(storyCounts).toEqual([4, 0, 1]);
+    expect(storyCounts).toEqual([5, 0, 1, 1]);
   });
 
   it("declares no removed field — the validator would refuse to load one", () => {

package/src/kernel/config/defaults.ts

@@ -2,9 +2,10 @@
  * Built-in configuration defaults — the validated distribution config.
  *
  * The lowest config layer is the distribution's own `pragma.conf.ts` (package
- * root), STATICALLY imported so `bun build --compile` inlines it (no fs read —
- * `evaluateProjectConfig` stats/imports from disk, impossible inside the
- * compiled binary) and validated through the same `parseRawConfig` as every
+ * root), STATICALLY imported so it travels with the emitted modules (no fs read
+ * — `evaluateProjectConfig` stats/imports from disk, which is right for a
+ * consumer's config and wrong for the distribution's own) and validated through
+ * the same `parseRawConfig` as every
  * other layer. Statically imported by `readConfig` (itself dynamic-imported,
  * off the `--help`/`__complete` fast path) and by its own test, so the eager
  * validation and the zod import here add nothing to the storeless surfaces —

package/src/kernel/config/evaluateProjectConfig.ts

@@ -16,11 +16,19 @@
  *
  * LIMITATION (accepted, per the review fold): a *transitively*-imported file
  * (e.g. `./pkgs.ts`) edited without touching the entry's mtime is not detected
- * across processes. The fix that would catch it — `bun build --bundle` the config
- * and key on the bundle hash — is unavailable: Bun's bundler cannot run inside
- * the `bun build --compile` binary (no source filesystem at `/$bunfs/root`), and
- * bundling on every load would also blow the warm-load budget. Touch the entry
- * (or bump VERSION) to force a rebuild.
+ * across processes. The fix that would catch it — bundling the config and keying
+ * on the bundle hash — would blow the warm-load budget on every load. Touch the
+ * entry (or bump VERSION) to force a rebuild.
+ *
+ * THE CONFIG IS THE CONSUMER'S OWN TYPESCRIPT, and this is the one place the
+ * distribution executes code it did not author. `pragma` ships on a `node`
+ * shebang, so that import is served by node's type STRIPPING — which erases
+ * annotations and refuses syntax that would need real emit (`enum`, `namespace`,
+ * parameter properties). Those are rejected with `ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`,
+ * which {@link evaluateProjectConfig} names specifically rather than letting it
+ * arrive as an anonymous load failure. The `engines` floor (node >= 22.18) is what
+ * makes stripping default-on — and the range excludes 23.0-23.5, which satisfy
+ * a bare `>=22.18` but predate the 23.x line's own default-on release (23.6).
  */
 
 import { createHash } from "node:crypto";
@@ -34,7 +42,7 @@ import {
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { PROJECT_CONFIG_FILENAME, VERSION } from "../../constants.js";
-import { PragmaError } from "../error/PragmaError.js";
+import { PragmaError } from "../error/index.js";
 import { configCacheDir } from "./paths.js";
 import { parseRawConfig } from "./schema.js";
 import type { RawConfig } from "./types.js";
@@ -94,7 +102,7 @@ export async function evaluateProjectConfig(path: string): Promise<RawConfig> {
   const url = `${pathToFileURL(path).href}?v=${key}`;
   // Evaluating real TypeScript can throw for reasons `parseRawConfig` never sees:
   // a syntax error, a bad import, or a top-level throw in the config module. Left
-  // unwrapped, that raw throw collapses to INTERNAL_ERROR ("please report this
+  // unwrapped, that raw throw collapses to INTERNAL_ERROR ("report this
   // issue") on EVERY command that reads config. Name it: a CONFIG_ERROR that
   // identifies the offending file and the underlying reason.
   let module: { default?: unknown };
@@ -103,8 +111,23 @@ export async function evaluateProjectConfig(path: string): Promise<RawConfig> {
   } catch (error) {
     if (error instanceof PragmaError) throw error;
     const reason = error instanceof Error ? error.message : String(error);
+    // Node strips types rather than compiling them, so a config using syntax that
+    // needs real emit fails here with a message naming neither the constraint nor
+    // the fix. Say both — this is a supported config that simply must be written
+    // in erasable TypeScript, and the author has no other way to learn that.
+    const { code } = (error ?? {}) as { code?: unknown };
+    if (code === "ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX") {
+      throw PragmaError.configError(
+        `Your ${PROJECT_CONFIG_FILENAME} uses TypeScript syntax that cannot be erased: ${reason}`,
+        {
+          recovery: {
+            message: `Rewrite it in erasable TypeScript — types, interfaces and \`satisfies\` are fine; \`enum\`, \`namespace\` and constructor parameter properties are not. A plain object literal with a \`default\` export always works.`,
+          },
+        },
+      );
+    }
     throw PragmaError.configError(
-      `Could not load project config ${path}: ${reason}`,
+      `Cannot load project config ${path}: ${reason}`,
       {
         recovery: {
           message: `Fix the error in your ${PROJECT_CONFIG_FILENAME} (it must evaluate to a default export), then try again.`,

package/src/kernel/config/firstRun.test.ts

@@ -1,60 +1,66 @@
-import { existsSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+/**
+ * The setup hint — the read-only replacement for first-run seeding.
+ *
+ * Onboarding used to WRITE: a pipeline step ran before dispatch on every
+ * non-help invocation and created the global config, so `skill list` — a read —
+ * mutated the machine before the user had consented to anything. Seeding is now
+ * the `config` setup target, created inside a consented run. What is left is a
+ * stateless hint, and the property that matters most about it is the one these
+ * tests pin: reading it writes nothing.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
-import { ensureFirstRun, firstRunTask } from "./firstRun.js";
+import { setupHintLines } from "./firstRun.js";
 import { globalConfigPath } from "./paths.js";
 
 const originalConfigHome = process.env.XDG_CONFIG_HOME;
 
-function freshConfigHome(): void {
-  process.env.XDG_CONFIG_HOME = mkdtempSync(join(tmpdir(), "pragma-first-"));
+function freshConfigHome(): string {
+  const dir = mkdtempSync(join(tmpdir(), "pragma-first-"));
+  process.env.XDG_CONFIG_HOME = dir;
+  return dir;
 }
 
 afterEach(() => {
   process.env.XDG_CONFIG_HOME = originalConfigHome;
 });
 
-describe("first run", () => {
-  it("greets on stderr and seeds the global config", async () => {
+describe("the setup hint", () => {
+  it("names the pre-release and the command that configures the machine", () => {
     freshConfigHome();
-    const path = globalConfigPath();
-    const lines: string[] = [];
-
-    await ensureFirstRun((line) => lines.push(line));
-
-    expect(existsSync(path)).toBe(true);
-    expect(readFileSync(path, "utf-8")).toBe("{}\n");
-    expect(lines[0]).toContain("Hello!");
-    expect(lines.some((line) => line.includes(path))).toBe(true);
-    // Snapshot the note with the volatile path masked.
-    expect(
-      lines.map((line) => line.replace(path, "<CONFIG>")),
-    ).toMatchSnapshot();
+    const lines = setupHintLines();
+    expect(lines.some((line) => line.includes("pre-release"))).toBe(true);
+    expect(lines.some((line) => line.includes("pragma setup"))).toBe(true);
   });
 
-  it("is idempotent — no greeting when the config already exists", async () => {
-    freshConfigHome();
-    await ensureFirstRun(() => {});
+  it("writes NOTHING — presence of the config is the state, not a marker", () => {
+    // A marker file would itself be a pre-consent write, which is the exact
+    // defect being removed. The probe must leave the config home untouched.
+    const dir = freshConfigHome();
+    expect(existsSync(globalConfigPath())).toBe(false);
 
-    const second: string[] = [];
-    await ensureFirstRun((line) => second.push(line));
-    expect(second).toEqual([]);
+    setupHintLines();
+    setupHintLines();
 
-    const task = firstRunTask();
-    expect(task).toBeDefined();
+    expect(readdirSync(dir)).toEqual([]);
+    expect(existsSync(globalConfigPath())).toBe(false);
   });
 
-  it("tolerates a creation failure with a single warning", async () => {
+  it("goes quiet once the config exists", () => {
     freshConfigHome();
-    // Make the pragma config directory path a file so mkdir fails.
-    writeFileSync(join(process.env.XDG_CONFIG_HOME as string, "pragma"), "x");
-    const lines: string[] = [];
-
-    await expect(
-      ensureFirstRun((line) => lines.push(line)),
-    ).resolves.toBeUndefined();
-    expect(lines).toHaveLength(1);
-    expect(lines[0]).toContain("Warning: could not create");
+    const path = globalConfigPath();
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, "{}\n");
+
+    expect(setupHintLines()).toEqual([]);
   });
 });

package/src/kernel/config/firstRun.ts

@@ -1,98 +1,34 @@
 /**
- * First-run onboarding — welcome note + global config creation.
+ * The setup hint — the read-only replacement for first-run seeding.
  *
- * On the first invocation (detected by the absence of the global config file),
- * greet on STDERR and seed `$XDG_CONFIG_HOME/pragma/config.json` with `{}` so
- * every field keeps its built-in default and `config show` reports honest
- * provenance. Modeled as a {@link Task} so the effects stay declarative and
- * testable. The banner goes to stderr — stdout belongs to command output
- * (`--format json`, MCP stdio) and must never be corrupted. Ported from the v1
- * first-run pipeline; runs before dispatch and tolerates every failure.
- */
-
-import { dirname } from "node:path";
-import {
-  $,
-  exists,
-  gen,
-  info,
-  mkdir,
-  type Task,
-  writeFile,
-} from "@canonical/task";
-import { runTask } from "@canonical/task/node";
-import {
-  BIN_NAME,
-  ISSUES_URL,
-  PROJECT_CONFIG_FILENAME,
-} from "../../constants.js";
-import { globalConfigPath } from "./paths.js";
-
-/** Seed content: an empty object, so nothing is pinned the user did not choose. */
-const SEED_CONFIG = "{}\n";
-
-/** Build the welcome note; the resolved path is shown so it is copyable. */
-function welcomeLines(path: string): string[] {
-  return [
-    `Hello! Thanks for taking the time to try the pre-release ${BIN_NAME} CLI.`,
-    `Please file issues and feedback at ${ISSUES_URL}.`,
-    `${BIN_NAME} stores its configuration in ${path} (just created with defaults).`,
-    `A \`${PROJECT_CONFIG_FILENAME}\` in this directory or above it overrides it per project.`,
-    "",
-  ];
-}
-
-/**
- * The first-run task: create the global config, announcing it on first run.
+ * Onboarding used to WRITE. A pipeline step ran before dispatch on every
+ * non-help invocation and created `$XDG_CONFIG_HOME/<bin>/config.json`, so
+ * `skill list` — a read — mutated the machine before the user had consented to
+ * anything, and a banner interleaved itself into the output of runs that were
+ * mutating something else entirely. The config layers already treat the missing
+ * file as "every field at its built-in default", so the write bought nothing.
  *
- * @returns Task yielding whether the config was created and its path.
- * @note Impure — checks/creates the global config file, emits log effects.
+ * Seeding is now a setup target, created inside a consented run. What is left
+ * here is a STATELESS hint: shown when the global config file is absent, on
+ * read-only surfaces only. There is no marker file — a marker is itself a
+ * pre-consent write, which is the exact defect being removed — because the
+ * presence of the config IS the state.
  */
-export function firstRunTask(): Task<{ created: boolean; path: string }> {
-  return gen(function* () {
-    const path = globalConfigPath();
-
-    if (yield* $(exists(path))) {
-      return { created: false, path };
-    }
-
-    // Create first, then greet: if creation fails the effects throw before any
-    // line is emitted, so onboarding degrades to the single stderr warning
-    // rather than a "just created" banner alongside a failure.
-    yield* $(mkdir(dirname(path), true));
-    yield* $(writeFile(path, SEED_CONFIG));
 
-    for (const line of welcomeLines(path)) {
-      yield* $(info(line));
-    }
-
-    return { created: true, path };
-  });
-}
+import { existsSync } from "node:fs";
+import { BIN_NAME, ISSUES_URL } from "../../constants.js";
+import { globalConfigPath } from "./paths.js";
 
 /**
- * Run the first-run task, tolerating every failure.
- *
- * Onboarding must never break an invocation: a read-only home or a race with a
- * concurrent first run degrades to a single stderr warning and the invocation
- * proceeds (the config layers treat a missing global file as defaults anyway).
+ * The hint lines for a machine that has not been set up, or none when it has.
  *
- * @param write - Stderr sink, injectable for tests.
- * @note Impure — filesystem effects + stderr.
+ * @returns The lines to print, or an empty array.
+ * @note Impure — probes the global config path.
  */
-export async function ensureFirstRun(
-  write: (line: string) => void = (line) => process.stderr.write(`${line}\n`),
-): Promise<void> {
-  try {
-    await runTask(firstRunTask(), {
-      // Route log effects to stderr without the interpreter's [INFO] prefix —
-      // this is a greeting, not diagnostics.
-      onLog: (_level, message) => write(message),
-    });
-  } catch (error) {
-    const reason = error instanceof Error ? error.message : String(error);
-    write(
-      `Warning: could not create the global ${BIN_NAME} config — ${reason}`,
-    );
-  }
+export function setupHintLines(): string[] {
+  if (existsSync(globalConfigPath())) return [];
+  return [
+    `${BIN_NAME} is pre-release — report issues at ${ISSUES_URL}.`,
+    `Run \`${BIN_NAME} setup\` to configure this machine.`,
+  ];
 }

package/src/kernel/config/index.ts

@@ -9,7 +9,7 @@
 
 export { evaluateProjectConfig } from "./evaluateProjectConfig.js";
 export { findProjectConfig } from "./findProjectConfig.js";
-export { ensureFirstRun, firstRunTask } from "./firstRun.js";
+export { setupHintLines } from "./firstRun.js";
 export type { GlobalConfigRead } from "./globalConfig.js";
 export { readGlobalConfig } from "./globalConfig.js";
 export {

package/src/kernel/config/readConfig.test.ts

@@ -59,7 +59,7 @@ describe("readConfig — layering + provenance", () => {
     expect(config.tier).toBe("core");
     expect(config.channel).toBe("experimental");
     expect(config.detail).toBe("detailed");
-    expect(config.packs).toHaveLength(3); // from defaults
+    expect(config.packs).toHaveLength(4); // from defaults
 
     expect(origins).toMatchObject({
       tier: "project",
@@ -101,12 +101,15 @@ describe("readConfig — layering + provenance", () => {
     freshXdg();
     writeGlobal('{"help":"Global help"}');
     const dir = projectWith(
-      'export default { name: "acme", colophon: { markdown: "By Acme." }, issuesUrl: "https://acme.test/issues", tier: "core" };',
+      'export default { name: "acme", logo: ["ACME"], colophon: { markdown: "By Acme." }, issuesUrl: "https://acme.test/issues", tier: "core" };',
     );
 
     const { config, origins } = await readConfig(dir);
 
     expect(config).not.toHaveProperty("name");
+    // `logo` is identity too: accepted by the shared schema, silent in a layer.
+    expect(config).not.toHaveProperty("logo");
+    expect(origins).not.toHaveProperty("logo");
     expect(config).not.toHaveProperty("help");
     expect(config).not.toHaveProperty("colophon");
     expect(config).not.toHaveProperty("issuesUrl");
@@ -461,7 +464,7 @@ describe("evaluateProjectConfig — mtime+VERSION cache", () => {
     freshXdg();
     // A malformed project config: references an undefined symbol → the module
     // throws at evaluation. Left unwrapped this collapsed to INTERNAL_ERROR
-    // ("please report this issue") on EVERY command that reads config.
+    // ("report this issue") on EVERY command that reads config.
     const dir = projectWith("export default { tier: definitelyNotDefined };");
     const path = join(dir, "pragma.config.ts");
 

package/src/kernel/config/readConfig.ts

@@ -51,7 +51,7 @@ export async function readConfig(
     return { value: defaultValues[field], origin: "default" };
   };
 
-  // `name`/`help`/`colophon`/`issuesUrl` are DELIBERATELY not picked: identity
+  // `name`/`help`/`logo`/`colophon`/`issuesUrl` are DELIBERATELY not picked: identity
   // is read from `pragma.conf.ts` statically (`src/constants.ts`), so merging a
   // layer's value here would report a provenance nothing honours.
   const tier = pick("tier");

package/src/kernel/config/schema.ts

@@ -16,7 +16,7 @@
  */
 
 import { z } from "zod";
-import { PragmaError } from "../error/PragmaError.js";
+import { PragmaError } from "../error/index.js";
 import { CHANNELS, DETAIL_LEVELS, type RawConfig } from "./types.js";
 
 const packDeclarationSchema = z.union([
@@ -61,6 +61,8 @@ function declaredCompletion(value: unknown): Record<string, unknown> | null {
 export const rawConfigSchema = z.object({
   name: z.string().min(1).optional(),
   help: z.string().min(1).optional(),
+  // Identity, like `name`/`help`: the wordmark root `--help` opens with.
+  logo: z.array(z.string()).optional(),
   // Declared toolchain content: the `colophon` verb renders whatever the
   // distribution declares here (markdown body + optional condensed summary).
   colophon: z

package/src/kernel/config/types.ts

@@ -109,7 +109,7 @@ export interface PragmaConfig {
  * wins during the merge.
  *
  * WIDER than {@link PragmaConfig}: the DISTRIBUTION layer (`pragma.conf.ts`)
- * is `satisfies RawConfig` and declares the four identity fields, which are
+ * is `satisfies RawConfig` and declares the five identity fields, which are
  * read statically and never merged. A global or project layer declaring one is
  * accepted by the validator and has no effect — `docs/reference/config.md`
  * says so, and `readConfig.test.ts` pins it.
@@ -117,6 +117,8 @@ export interface PragmaConfig {
 export interface RawConfig {
   readonly name?: string;
   readonly help?: string;
+  /** ASCII-art wordmark lines shown atop root `--help` (identity, like `name`). */
+  readonly logo?: readonly string[];
   readonly colophon?: ColophonDeclaration;
   readonly issuesUrl?: string;
   readonly tier?: string;