@canonical/pragma-cli 0.34.0 → 0.35.0

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

@@ -33,10 +33,9 @@ function moduleWith(overrides: Partial<VerbSpec>): CapabilityModule {
 }
 
 describe("buildCompletionModel — structure", () => {
-  it("collects nouns sorted, injecting the bin-served mcp", () => {
+  it("collects nouns sorted, from the declared verbs alone", () => {
     expect(model.nouns.map((n) => n.noun)).toEqual([
       "block",
-      "mcp",
       "standard",
       "status",
     ]);
@@ -62,17 +61,12 @@ describe("buildCompletionModel — structure", () => {
     expect(status?.verbs).toEqual([]);
   });
 
-  it("injects mcp as a bare self-verb noun with nothing to offer", () => {
-    const mcp = findNoun(model, "mcp");
-    expect(mcp?.selfVerb).toEqual({
-      label: "mcp",
-      mutates: false,
-      flags: [],
-      positionals: [],
-    });
-  });
+  it("offers the mcp noun from its declared verb, with no self-verb", () => {
+    // The noun used to be conjured here because the bin served it without a
+    // spec; nothing is conjured now, so a module that declares no mcp verb
+    // gets no mcp noun.
+    expect(findNoun(model, "mcp")).toBeUndefined();
 
-  it("does not inject mcp when a live mcp noun exists", () => {
     const withMcp = buildCompletionModel([
       moduleWith({ path: ["mcp", "serve"] }),
     ]);
@@ -121,6 +115,38 @@ describe("buildCompletionModel — flags and sources", () => {
     });
   });
 
+  it("marks a spec-declared repeatable string/enum flag repeatable", () => {
+    // `string[]` is not the only accumulating shape: a compiled pack marks
+    // every declared filter `repeatable`, so `--category css --category git`
+    // is the union. Reading the kind alone de-offered the flag after its
+    // first use, which is exactly when repetition becomes offerable.
+    const repeatables = buildCompletionModel([
+      moduleWith({
+        params: [
+          {
+            kind: "enum",
+            name: "category",
+            doc: "Filter by category.",
+            values: ["css", "git"],
+            repeatable: true,
+          },
+          {
+            kind: "string",
+            name: "search",
+            doc: "Free text.",
+            repeatable: true,
+          },
+          { kind: "string", name: "note", doc: "Once only." },
+        ],
+      }),
+    ]);
+    const thing = findNoun(repeatables, "thing")?.selfVerb;
+    const flagOf = (flag: string) => thing?.flags.find((f) => f.flag === flag);
+    expect(flagOf("--category")?.repeatable).toBe(true);
+    expect(flagOf("--search")?.repeatable).toBe(true);
+    expect(flagOf("--note")?.repeatable).toBe(false);
+  });
+
   it("resolves name positionals with required/variadic markers", () => {
     expect(get?.positionals).toEqual([
       {
@@ -270,6 +296,11 @@ describe("buildCompletionModel — flags and sources", () => {
       kind: "values",
       values: ["summary", "standard", "detailed"],
     });
+    // Every flag the global parser accepts is offered — a flag the surface
+    // advertises but completion omits is invisible at the TAB that would
+    // teach it.
+    expect(flags["--no-headers"]).toMatchObject({ takesValue: false });
+    expect(flags["--quiet"]).toMatchObject({ takesValue: false });
     expect(flags["--llm"]).toBeUndefined();
     expect(flags["--version"]?.rootOnly).toBe(true);
     expect(flags["--help"]?.rootOnly).toBeUndefined();
@@ -350,6 +381,22 @@ function expectAgreement(
     .filter((noun) => noun !== "mcp" || surfaceNouns.includes("mcp"));
   expect(modelNouns).toEqual(surfaceNouns);
 
+  // A module-owned mount REPLACES its verbs' completion surface with the
+  // flags/positionals the mounted tree actually registers, so agreement for
+  // those verbs is asserted against the module's declared projection data —
+  // not the covenant-facing surface flags (which record binding param names).
+  const mountedByNoun = new Map<
+    string,
+    Readonly<Record<string, import("../spec/types.js").CompletionChildSpec>>
+  >();
+  for (const module of modules) {
+    if (!module.cliProjection) continue;
+    const children = module.cliProjection.completionChildren();
+    for (const verb of module.verbs) {
+      mountedByNoun.set(verb.path[0], children);
+    }
+  }
+
   for (const noun of surfaceNouns) {
     const nounEntry = findNoun(completionModel, noun);
     expect(nounEntry).toBeDefined();
@@ -362,6 +409,7 @@ function expectAgreement(
     ].sort();
     expect(modelLabels).toEqual(surfaceVerbs.map((v) => v.v).sort());
 
+    const mounted = mountedByNoun.get(noun);
     for (const surfaceVerb of surfaceVerbs) {
       const modelVerb: VerbEntry | undefined =
         nounEntry.selfVerb?.label === surfaceVerb.v
@@ -370,6 +418,26 @@ function expectAgreement(
       expect(modelVerb).toBeDefined();
       if (!modelVerb) continue;
 
+      const mountedSpec = mounted?.[surfaceVerb.v];
+      if (mountedSpec) {
+        expect(modelVerb.flags.map((f) => f.flag)).toEqual(
+          mountedSpec.flags.map((f) => f.flag),
+        );
+        expect(modelVerb.positionals.map((p) => p.name)).toEqual(
+          mountedSpec.positionals.map((p) => p.name),
+        );
+        expect((modelVerb.children ?? []).map((c) => c.label)).toEqual(
+          (mountedSpec.children ?? []).map((c) => c.label),
+        );
+        // A namespace node (children) never mutates for completion: the
+        // mounted tree registers the mutation trio on runnable leaves only.
+        const isNamespace = (mountedSpec.children ?? []).length > 0;
+        expect(modelVerb.mutates).toBe(
+          !isNamespace && surfaceVerb.mutates === true,
+        );
+        continue;
+      }
+
       expect(modelVerb.flags.map((f) => f.flag)).toEqual(
         surfaceVerb.flags ?? [],
       );
@@ -393,6 +461,90 @@ describe("projection agreement with emitSurface (PROTECTED)", () => {
   });
 });
 
+describe("mounted create completion — literal candidate pins (PROTECTED)", () => {
+  // The mounted-tree branch of the agreement describe compares the model to
+  // completionChildren() — the same call the model was BUILT from, so it can
+  // never catch that surface going wrong (a garbage projection satisfies
+  // it). These pins are the INDEPENDENT source: literal candidate sets
+  // through the real resolver, shellDrive noun-tier style — the segment
+  // descent (parse.ts children walk) and a leaf's registered flags.
+
+  it("segment tier: `create component <TAB>` offers exactly the framework segments", async () => {
+    const { runComplete } = await import("./complete.js");
+    expect(
+      await runComplete(["create", "component", ""], capabilities),
+    ).toEqual(["lit", "react", "svelte"]);
+    expect(
+      await runComplete(["create", "application", ""], capabilities),
+    ).toEqual(["react"]);
+  });
+
+  it("namespace flag tier: `create component --<TAB>` offers NO leaf prompt or mutation flags", async () => {
+    const { runComplete } = await import("./complete.js");
+    // Prompt AND mutation flags are registered on the LEAVES; a pre-segment
+    // offer completes orderings Commander rejects (`create component
+    // --use-ts-stories svelte` and `create component --dry-run react` both
+    // exit 2 as unknown options). Until a framework segment is typed, only
+    // the global tier is offered.
+    expect(
+      await runComplete(["create", "component", "--"], capabilities),
+    ).toEqual([
+      "--detail",
+      "--format",
+      "--help",
+      "--no-headers",
+      "--quiet",
+      "--verbose",
+    ]);
+  });
+
+  it("leaf flag tier: `create component react --<TAB>` offers the REGISTERED flags", async () => {
+    const { runComplete } = await import("./complete.js");
+    // The leaf's prompt-derived flags in their registered spelling (--no-
+    // forms for default-true confirms, --component-path for the positional
+    // prompt — addPromptOptions registers EVERY prompt as an option), the
+    // mutation trio, and the root globals — as literals, so dropping the
+    // framework positional's values or a leaf prompt flag goes red instead
+    // of silently green.
+    expect(
+      await runComplete(["create", "component", "react", "--"], capabilities),
+    ).toEqual([
+      "--component-path",
+      "--detail",
+      "--dry-run",
+      "--format",
+      "--help",
+      "--no-headers",
+      "--no-with-ssr-tests",
+      "--no-with-stories",
+      "--no-with-styles",
+      "--quiet",
+      "--undo",
+      "--verbose",
+      "--yes",
+    ]);
+    // Svelte's leaf carries its own extra flag — per-leaf, not unioned.
+    expect(
+      await runComplete(["create", "component", "svelte", "--"], capabilities),
+    ).toEqual([
+      "--component-path",
+      "--detail",
+      "--dry-run",
+      "--format",
+      "--help",
+      "--no-headers",
+      "--no-with-ssr-tests",
+      "--no-with-stories",
+      "--no-with-styles",
+      "--quiet",
+      "--undo",
+      "--use-ts-stories",
+      "--verbose",
+      "--yes",
+    ]);
+  });
+});
+
 /** Regression pin: ParamSpec.complete stays optional on every param kind. */
 it("accepts params without a complete field", () => {
   const params: ParamSpec[] = [

package/src/kernel/completion/model.ts

@@ -25,8 +25,13 @@
  */
 
 import { DETAIL_LEVELS, OUTPUT_FORMATS } from "../../constants.js";
-import { kebabCase, verbLabel } from "../spec/emitSurface.js";
-import type { CapabilityModule, ParamSpec, VerbSpec } from "../spec/types.js";
+import { kebabCase, verbLabel } from "../spec/index.js";
+import type {
+  CapabilityModule,
+  CompletionChildSpec,
+  ParamSpec,
+  VerbSpec,
+} from "../spec/types.js";
 import type {
   CompletionModel,
   CompletionSource,
@@ -85,6 +90,13 @@ const GLOBAL_FLAGS: readonly FlagEntry[] = [
     repeatable: false,
     source: { kind: "values", values: DETAIL_LEVELS },
   },
+  {
+    flag: "--no-headers",
+    takesValue: false,
+    repeatable: false,
+    source: none(),
+  },
+  { flag: "--quiet", takesValue: false, repeatable: false, source: none() },
   { flag: "--help", takesValue: false, repeatable: false, source: none() },
   {
     flag: "--version",
@@ -181,7 +193,12 @@ function toVerbEntry(verb: VerbSpec): VerbEntry {
       flags.push({
         flag: `--${name}`,
         takesValue: param.kind !== "boolean",
-        repeatable: param.kind === "string[]",
+        // Two grammars accumulate, so two shapes are repeatable: a `string[]`
+        // flag (`--tag a --tag b`) and any `string`/`enum` param the spec
+        // marks `repeatable` — the form compiled packs give every declared
+        // filter. Reading only the kind de-offered a filter after its first
+        // use, hiding the repetition the parser had just started honouring.
+        repeatable: param.kind === "string[]" || param.repeatable === true,
         source,
       });
     }
@@ -190,18 +207,73 @@ function toVerbEntry(verb: VerbSpec): VerbEntry {
   return { label, mutates: verb.capability.mutates, flags, positionals };
 }
 
-/** An empty self-verb entry (used for the injected `mcp` noun). */
-function bareSelfVerb(label: string): VerbEntry {
-  return { label, mutates: false, flags: [], positionals: [] };
+/**
+ * Convert one module-declared completion node (a mounted subtree's static
+ * data) into a verb entry, asserting every inlinable token's safety exactly
+ * as spec-derived entries are asserted. `mutates` is the owning verb's
+ * mutability, applied only to the LEAVES (see the namespace note below).
+ */
+function toMountedEntry(
+  spec: CompletionChildSpec,
+  mutates: boolean,
+  where: string,
+): VerbEntry {
+  assertSafeToken(spec.label, `${where} label`);
+  const flags: FlagEntry[] = spec.flags.map((flag) => {
+    const name = flag.flag.replace(/^--?/, "");
+    assertSafeToken(name, `${where} flag "${flag.flag}"`);
+    const source: CompletionSource = flag.values
+      ? { kind: "values", values: flag.values }
+      : none();
+    assertSafeSource(source, `${where} flag "${flag.flag}"`);
+    return {
+      flag: flag.flag,
+      takesValue: flag.takesValue,
+      repeatable: false,
+      source,
+    };
+  });
+  const positionals: PositionalEntry[] = spec.positionals.map((positional) => {
+    const source: CompletionSource = positional.values
+      ? { kind: "values", values: positional.values }
+      : positional.files
+        ? { kind: "files" }
+        : none();
+    assertSafeSource(source, `${where} positional "${positional.name}"`);
+    return {
+      name: positional.name,
+      required: positional.required,
+      variadic: false,
+      source,
+    };
+  });
+  const children =
+    spec.children && spec.children.length > 0
+      ? spec.children.map((child) =>
+          toMountedEntry(child, mutates, `${where}/${child.label}`),
+        )
+      : undefined;
+  return {
+    label: spec.label,
+    // A node with children is a NAMESPACE, not a runnable command:
+    // `registerGeneratorCommands` adds the host mutation trio to runnable
+    // LEAVES only, so a mutating namespace would offer `--dry-run`/`--undo`/
+    // `--yes` BEFORE the framework segment — an ordering the CLI rejects as
+    // an unknown option. The verb's mutability descends to the leaves.
+    mutates: children ? false : mutates,
+    flags,
+    positionals,
+    ...(children ? { children } : {}),
+  };
 }
 
 /**
  * Derive the completion model from the capability modules.
  *
  * Hidden verbs are excluded (matching `emitSurface` and `buildProgram`).
- * The bin-served `mcp` entry is injected so `pragma mc<Tab>` completes it,
- * matching the root help.
- * TODO(spec): drop the injection when `mcp` lands as a real (non-hidden) spec.
+ * Every noun in the model comes from a declared verb — `mcp` used to be
+ * injected here because the bin served it without a spec, and it now declares
+ * `mcp serve` like any other pair.
  *
  * @param modules - The capability modules.
  * @returns The completion model, nouns and verbs sorted.
@@ -225,12 +297,24 @@ export function buildCompletionModel(
   };
 
   for (const module of modules) {
+    // A module-owned mount REPLACES its verbs' completion surface: the flags
+    // the mounted tree actually registers (e.g. a default-on confirm's
+    // `--no-` form), the segment positionals, and the child walk — declared
+    // as static data by the module, converted and safety-asserted here.
+    const mountedChildren = module.cliProjection?.completionChildren();
     for (const verb of module.verbs) {
       if (verb.hidden) continue;
       const noun = verb.path[0];
       assertSafeToken(noun, `noun "${noun}"`);
       const bucket = bucketFor(noun);
-      const entry = toVerbEntry(verb);
+      const mountedSpec = mountedChildren?.[verbLabel(verb.path)];
+      const entry = mountedSpec
+        ? toMountedEntry(
+            mountedSpec,
+            verb.capability.mutates,
+            `mounted "${verb.path.join(" ")}"`,
+          )
+        : toVerbEntry(verb);
       if (verb.path[1] === undefined) {
         bucket.selfVerb = entry;
       } else {
@@ -239,10 +323,6 @@ export function buildCompletionModel(
     }
   }
 
-  if (!byNoun.has("mcp")) {
-    byNoun.set("mcp", { selfVerb: bareSelfVerb("mcp"), verbs: [] });
-  }
-
   const nouns: NounEntry[] = [...byNoun.entries()]
     .map(([noun, bucket]) => ({
       noun,

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

@@ -86,6 +86,8 @@ describe("parseWords — flag names (PROTECTED)", () => {
       "--format",
       "--verbose",
       "--detail",
+      "--no-headers",
+      "--quiet",
       "--help",
       "--version",
     ]);
@@ -107,6 +109,8 @@ describe("parseWords — flag names (PROTECTED)", () => {
       "--format",
       "--verbose",
       "--detail",
+      "--no-headers",
+      "--quiet",
       "--help",
     ]);
   });
@@ -326,11 +330,4 @@ describe("parseWords — self-verb nouns (PROTECTED)", () => {
       reason: "positionals exhausted",
     });
   });
-
-  it("the injected mcp noun completes but offers nothing after", () => {
-    expect(parse(["mcp", ""]).context).toEqual({
-      kind: "nothing",
-      reason: "positionals exhausted",
-    });
-  });
 });

package/src/kernel/completion/parse.ts

@@ -137,6 +137,21 @@ function scanCommandWord(
     return;
   }
 
+  // A verb with segment children (a mounted subtree): the word resolves
+  // against the children BEFORE positional counting — a match descends, so
+  // deeper flags/positionals are the child's own; a non-match is terminal.
+  const resolved = knownVerb(state);
+  if (resolved?.children && resolved.children.length > 0) {
+    const child = resolved.children.find((entry) => entry.label === word);
+    if (child) {
+      state.verb = child;
+      state.positionalsSeen = 0;
+      return;
+    }
+    state.verb = "unknown";
+    return;
+  }
+
   state.positionalsSeen += 1;
 }
 

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

@@ -42,7 +42,6 @@ describe("resolveRequest — structural contexts (PROTECTED)", () => {
     await expect(complete(["blo"])).resolves.toEqual(["block"]);
     await expect(complete([""])).resolves.toEqual([
       "block",
-      "mcp",
       "standard",
       "status",
     ]);

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

@@ -319,7 +319,7 @@ describe("storeless guarantee (PROTECTED)", () => {
 
     // prefixes: `ds` is in the default display map, so it comes back for `d`.
     await expect(
-      runComplete(["ontology", "show", "d"], capabilities, env),
+      runComplete(["ontology", "lookup", "d"], capabilities, env),
     ).resolves.toContain("ds");
 
     // index (derived, no field): the tier lookup is a declared pack lookup
@@ -345,14 +345,14 @@ describe("storeless guarantee (PROTECTED)", () => {
   });
 
   it("the spawned __complete fast path answers without touching any state", () => {
-    // The perf globalSetup guarantees dist/pragma exists.
+    // The perf globalSetup guarantees the emitted `dist/` exists.
     // A FRESH INSTALL, reproduced: nothing is inherited from this process's
     // environment, the cwd holds no config, and $HOME plus all three XDG roots
-    // are empty temps. Anything the binary answers here it answered from
+    // are empty temps. Anything the entry answers here it answered from
     // itself. (The suite before this inherited `...process.env`, so it could
     // not tell a compiled-in answer from an ambient one.)
-    const binary = fileURLToPath(
-      new URL("../../../dist/pragma", import.meta.url),
+    const entry = fileURLToPath(
+      new URL("../../../dist/src/bin.js", import.meta.url),
     );
     const home = mkdtempSync(join(tmpdir(), "pragma-storeless-home-"));
     const xdgConfig = mkdtempSync(join(tmpdir(), "pragma-storeless-cfg-"));
@@ -366,23 +366,27 @@ describe("storeless guarantee (PROTECTED)", () => {
       XDG_CACHE_HOME: xdgCache,
     };
 
-    const nouns = spawnSync(binary, ["__complete", "--", "co"], {
-      encoding: "utf-8",
-      cwd: emptyCwd,
-      env,
-    });
+    const nouns = spawnSync(
+      process.execPath,
+      [entry, "__complete", "--", "co"],
+      {
+        encoding: "utf-8",
+        cwd: emptyCwd,
+        env,
+      },
+    );
     expect(nouns.status).toBe(0);
-    expect(nouns.stdout).toBe("colophon\nconfig\n");
+    expect(nouns.stdout).toBe("colophon\nconcept\nconfig\n");
     expect(nouns.stderr).toBe("");
 
     // The headline guarantee of the embedded pack: a user who has installed
-    // the binary and nothing else gets ENTITY candidates on the first TAB.
-    // Every other pin on the embedded index runs in-process, where a bundler
-    // change that made `pack.index.generated.ts` unreachable FROM THE BINARY
-    // would leave the whole suite green.
+    // the shipped entry and nothing else gets ENTITY candidates on the first TAB.
+    // Every other pin on the embedded index runs in-process, where an emit
+    // change that made `pack.index.generated.ts` unreachable FROM THE SHIPPED
+    // ENTRY would leave the whole suite green.
     const entities = spawnSync(
-      binary,
-      ["__complete", "--", "block", "lookup", "ds:global.component.but"],
+      process.execPath,
+      [entry, "__complete", "--", "block", "lookup", "ds:global.component.but"],
       { encoding: "utf-8", cwd: emptyCwd, env },
     );
     expect(entities.status).toBe(0);
@@ -402,17 +406,21 @@ describe("storeless guarantee (PROTECTED)", () => {
   });
 
   it("the spawned fast path emits zero bytes for zero candidates, exit 0", () => {
-    const binary = fileURLToPath(
-      new URL("../../../dist/pragma", import.meta.url),
+    const entry = fileURLToPath(
+      new URL("../../../dist/src/bin.js", import.meta.url),
     );
-    const result = spawnSync(binary, ["__complete", "--", "bogus", ""], {
-      encoding: "utf-8",
-      env: {
-        ...process.env,
-        XDG_CONFIG_HOME: mkdtempSync(join(tmpdir(), "pragma-zb-cfg-")),
-        XDG_STATE_HOME: mkdtempSync(join(tmpdir(), "pragma-zb-state-")),
+    const result = spawnSync(
+      process.execPath,
+      [entry, "__complete", "--", "bogus", ""],
+      {
+        encoding: "utf-8",
+        env: {
+          ...process.env,
+          XDG_CONFIG_HOME: mkdtempSync(join(tmpdir(), "pragma-zb-cfg-")),
+          XDG_STATE_HOME: mkdtempSync(join(tmpdir(), "pragma-zb-state-")),
+        },
       },
-    });
+    );
     expect(result.status).toBe(0);
     expect(result.stdout).toBe("");
     expect(result.stderr).toBe("");

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