@canonical/pragma-cli 0.34.0 → 0.35.0

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"
@@ -45,6 +64,10 @@ describe("defaults — the validated distribution config (pragma.conf.ts)", () =
         name: "@canonical/code-standards",
         source: "git+https://github.com/canonical/web-code-standards.git#main",
       },
+      {
+        name: "@canonical/ds-implementations",
+        source: "git+https://github.com/canonical/pragma.git#main",
+      },
     ]);
   });
 
@@ -55,7 +78,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;

package/src/kernel/copy.test.ts

@@ -28,6 +28,11 @@
  * in a capability source — became content the config declares
  * (`pragma.conf.ts#colophon`), which is what made removing it checkable.
  *
+ * Beside the naming rules, the same scanner enforces the HOUSE VOICE rules for
+ * user-facing copy ({@link COPY_RULES}, authored as data in `copy.ts`) over
+ * both file sets — the kernel set above and `src/capabilities/**` — in the
+ * last describe of this file. See `copy.ts` for what each rule bans and why.
+ *
  * NOTE for a reader of an older revision: this docblock used to say the
  * `examples[].cmd` sweep and the `docs/reference/*.md` regen "have to move
  * together". They must be CONSISTENT, not simultaneous — the whole sweep was
@@ -41,6 +46,7 @@ import { fileURLToPath } from "node:url";
 import { describe, expect, it } from "vitest";
 import conf from "../../pragma.conf.js";
 import { BIN_NAME } from "../constants.js";
+import { COPY_RULES } from "./copy.js";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const root = resolve(here, "..");
@@ -250,13 +256,17 @@ function pushCopy(copy: string[], literal: string): void {
  * `file: literal` for every authored literal matching `pattern`, so a failure
  * names its offenders instead of only counting them.
  *
- * @param pattern - What kernel copy may not contain.
+ * @param pattern - What the copy may not contain.
+ * @param sources - The files to read; the kernel set by default.
  * @returns One entry per offending literal.
- * @note Impure — reads every kernel source.
+ * @note Impure — reads every listed source.
  */
-function findOffenders(pattern: RegExp): string[] {
+function findOffenders(
+  pattern: RegExp,
+  sources: readonly string[] = files,
+): string[] {
   const found: string[] = [];
-  for (const file of files) {
+  for (const file of sources) {
     for (const literal of readCopy(readFileSync(file, "utf-8"))) {
       if (pattern.test(literal)) {
         found.push(`${relative(root, file)}: ${literal}`);
@@ -451,3 +461,23 @@ describe("capability commands (PROTECTED)", () => {
     expect(offenders).toEqual([]);
   });
 });
+
+describe("user-facing copy house style (PROTECTED)", () => {
+  // The voice rules ({@link COPY_RULES}) run over BOTH file sets the naming
+  // rules above read — the kernel set and the capability set — because voice,
+  // unlike the distribution's name, is not content anywhere: a capability's
+  // error is the same product speaking as a kernel diagnostic. `readCopy`
+  // keeps comments, regexes, specifiers and test files out of scope, so a
+  // rule fires only on a string a user can actually be shown.
+  //
+  // One `it` per rule, NAMED by the rule, so a red run states the rule that
+  // fired; the assertion message carries the fix. What a failure prints is the
+  // offender list plus those two strings — everything needed to correct the
+  // copy lives in this repo.
+  const allSources = [...files, ...capabilitySources];
+  for (const { pattern, rule, fix } of COPY_RULES) {
+    it(rule, () => {
+      expect(findOffenders(pattern, allSources), fix).toEqual([]);
+    });
+  }
+});

package/src/kernel/copy.ts

@@ -0,0 +1,54 @@
+/**
+ * The house rules for user-facing copy, as data.
+ *
+ * Every string this CLI prints is one product speaking, and a product with one
+ * voice phrases one meaning one way. These descriptors name the phrasings that
+ * are out of that voice, why, and what to write instead; `copy.test.ts` runs
+ * them over every authored string literal in the tree — the same scanner and
+ * file sets as the naming rules there, so comments, regexes, module specifiers
+ * and test fixtures are never in scope. A failure quotes the offending literal,
+ * the rule, and the fix, and nothing else: everything a maintainer needs to
+ * correct the string lives in this file.
+ *
+ * Rules are DATA rather than assertions so the set can grow (or move into a
+ * shared standards package) without rewriting the guard, and so each rule's
+ * pattern, statement and fix are reviewed together as one unit. Precision is
+ * the set's credibility: a pattern that fires on domain vocabulary gets
+ * disabled in practice, so a carve-out is encoded in the pattern itself — with
+ * its reason — never in an exemption list beside it.
+ */
+
+/** One banned phrasing: what copy may not contain, why, and the rewrite. */
+export interface CopyRule {
+  /** What the copy must not contain. */
+  readonly pattern: RegExp;
+  /** The house rule, stated for a reader of THIS codebase. */
+  readonly rule: string;
+  /** How to fix an offending string. */
+  readonly fix: string;
+}
+
+/** The banned phrasings for user-facing copy. Enforced by `copy.test.ts`. */
+export const COPY_RULES: readonly CopyRule[] = [
+  {
+    pattern: /\b(?:could not|failed to|unable to)\b/i,
+    rule: "User-facing copy says `cannot` — one phrasing for one meaning, so the CLI reads as one voice.",
+    fix: "Rewrite with `cannot` (present tense, no hedging), naming what is wrong rather than what was attempted.",
+  },
+  {
+    // `\w+n't` covers every negated contraction in one arm; the lookbehind
+    // carves out `do/don't`, which is domain vocabulary — the name of the
+    // paired good/bad example a coding standard ships — not conversational
+    // tone. The second arm lists the pronoun contractions, which have no
+    // shared suffix shape.
+    pattern:
+      /\b(?<!do\/)\w+n't\b|\b(?:you|we|they|it|that|there|here|what|let)'(?:re|ve|ll|s|d)\b|\bi'm\b/i,
+    rule: "No contractions in user-facing copy — instructions read as statements, not conversation.",
+    fix: "Spell the words out, or restructure the sentence to drop the second person.",
+  },
+  {
+    pattern: /\b(?:please|sorry|oops)\b/i,
+    rule: "The CLI does not apologise or plead; it states the fact and the action.",
+    fix: "Drop the pleading word and instruct directly: `Report this issue at <url>.`",
+  },
+];

package/src/kernel/error/PragmaError.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "vitest";
+import { ISSUES_URL } from "../../constants.js";
 import { errorEnvelope, successEnvelope } from "../render/envelope.js";
 import { PragmaError } from "./PragmaError.js";
 import { cliRecovery } from "./recovery.js";
@@ -56,7 +57,9 @@ describe("PragmaError factories", () => {
   it("internalError attaches a report hint", () => {
     const error = PragmaError.internalError("boom");
     expect(error.code).toBe("INTERNAL_ERROR");
-    expect(error.recovery).toEqual({ message: "Please report this issue." });
+    expect(error.recovery).toEqual({
+      message: `Report this issue at ${ISSUES_URL}.`,
+    });
   });
 });
 
@@ -66,7 +69,7 @@ describe("serializeError", () => {
     expect(serializeError(error)).toEqual({
       code: "INTERNAL_ERROR",
       message: "Internal error: boom",
-      recovery: { message: "Please report this issue." },
+      recovery: { message: `Report this issue at ${ISSUES_URL}.` },
     });
   });