@canonical/pragma-cli 0.34.0 → 0.36.0

package/src/kernel/packs/types.ts

@@ -150,10 +150,56 @@ export interface PackFilter {
    * string matched case-insensitively against the variable).
    */
   readonly values?: readonly string[];
+  /**
+   * How a provided value is compared to the row's cell.
+   *
+   * `"exact"` (the default) compares the whole cell. `"set"` reads the cell as
+   * a SPACE-SEPARATED set and matches when ANY member equals the provided
+   * value — the shape a `GROUP_CONCAT` produces, for a dimension where one row
+   * legitimately belongs to several values at once. The standing case is a
+   * hierarchy: a standard filed under `testing-unit` is, by the definition of
+   * the hierarchy, also a `testing` standard, and a filter that compared only
+   * the leaf answered `--category testing` with 1 of 8 — a silently wrong
+   * answer, exit 0.
+   */
+  readonly match?: "exact" | "set";
+  /**
+   * Where the dimension's VOCABULARY lives in the graph, for a filter with no
+   * declared {@link values}.
+   *
+   * A value-free filter rejects a value the data does not carry. The question is
+   * what "the data" means. The rows a list just returned are the wrong answer:
+   * they are a POPULATION, and a value can be real while no row carries it — a
+   * category the graph declares with zero standards filed under it, a
+   * `ds:ConceptType` no concept uses yet. Validating against rows turns those
+   * into `INVALID_INPUT`, when the honest answer is a calm empty list.
+   *
+   * So the vocabulary is read from the graph directly, from the same terms the
+   * surface that ENUMERATES it reads (`standard categories` reads `cs:Category`
+   * / `cs:slug`; so does the `category` filter's vocabulary query). The ruling
+   * this honours is "the graph is the vocabulary, don't hard-code the slugs" —
+   * rows were never the graph, just the part of it that answered.
+   *
+   * Without it a value-free filter falls back to the observed rows, which is the
+   * only evidence available; that is a NARROWER vocabulary than the truth, and a
+   * story whose dimension has an authoritative source should declare it.
+   */
+  readonly vocabulary?: PackFilterVocabulary;
   /** Help text (defaults to a generated description). */
   readonly description?: string;
 }
 
+/** The authoritative value set for a value-free {@link PackFilter}. */
+export interface PackFilterVocabulary {
+  /** SPARQL SELECT producing one row per admissible value. */
+  readonly query: string;
+  /**
+   * SELECT variable carrying the value (without `?`). Defaults to the filter's
+   * own {@link PackFilter.variable}.
+   */
+  readonly variable?: string;
+}
+
 /**
  * Free-text search over list rows: a `--search` string keeping a row when ANY
  * named SELECT variable contains the term (case-insensitive substring). Applied
@@ -239,6 +285,49 @@ export interface PackCompletion {
   readonly minChars?: number;
 }
 
+/**
+ * How much an entity's containing SCOPE is worth when a name reaches several
+ * entities at once — the ranking factor {@link PackLookup.scopeWeight} declares.
+ *
+ * DERIVED, never enumerated. The scope's own name is a path (`Global`,
+ * `Apps/Launchpad`), so its DEPTH is a fact the graph already states, and a
+ * scope nobody has heard of yet inherits its place the day it appears. An
+ * enumerated ranking would have to be edited for each new one, and the one
+ * nobody edited would silently rank first.
+ *
+ * The weight falls by {@link falloff} per level below the top, so the top level
+ * is worth 1 and each nesting step costs the same again; floored at 0, so a very
+ * deep scope can never turn negative and invert the type factor it multiplies.
+ *
+ * {@link asserted} is the retirement path for the DERIVATION, not for this
+ * declaration: an asserted value wins over the derived one
+ * (`COALESCE(?asserted, ?derived)`), so the day the ontology states the ranking
+ * itself, the depth heuristic stops mattering and `falloff` becomes inert.
+ *
+ * The declaration itself must stay. Every read of {@link asserted} is reached
+ * through this object, so deleting it does not fall back to the ontology's rank
+ * — it removes scope ranking from the query altogether and silently returns the
+ * lookup to `STR(?uri)` order, which is the defect this exists to fix. What
+ * retires is the derivation, and what remains is `via` plus `asserted`.
+ */
+export interface PackScopeWeight {
+  /** The entity → scope edge (e.g. `ds:tier`). */
+  readonly via: string;
+  /**
+   * The scope property holding its path-shaped name (e.g. `ds:name`), whose
+   * `/`-separated depth derives the weight.
+   *
+   * It must be the NAME, not the IRI: the live tiers spell the same scope
+   * `ds:apps_launchpad` and `"Apps/Launchpad"`, and only the name carries the
+   * separator that makes the hierarchy legible.
+   */
+  readonly by: string;
+  /** Score cost per level below the top, 0–1 (e.g. 0.2 → 1, 0.8, 0.6, …). */
+  readonly falloff: number;
+  /** An asserted weight on the scope, which WINS over the derived one. */
+  readonly asserted?: string;
+}
+
 /**
  * The lookup half of a pack. The query is generated from `by` and `type`/`types`
  * — user-supplied names are escaped by the generator, never interpolated by the
@@ -256,6 +345,29 @@ export interface PackLookup {
   readonly source?: "sparql" | "graphql";
   /** Property whose value names the entity — prefixed name or IRI. */
   readonly by: string;
+  /**
+   * What names an entity that carries no {@link by} value. Absent (the default)
+   * means NOTHING does: the `by` triple is required, and an entity without one
+   * is not addressable by name and never drawn by `sample`.
+   *
+   * `"iri"` opts the family into an IRI-DERIVED name — the local name after the
+   * last `#`/`/`, with dot-separated hierarchy segments published as slashes
+   * (`cs:react.component.props` → `react/component/props`).
+   *
+   * DECLARE IT ONLY WHEN THE STORY'S `list` PUBLISHES THE SAME DERIVED NAME.
+   * The option exists to keep the two halves of the two-step grammar over ONE
+   * population: `standard list` synthesizes a name for the ~87% of code
+   * standards carrying no `cs:name`, so `standard lookup` must answer to it.
+   * Turning it on where the list does NOT publish such a name is the mirror
+   * defect — `token list` requires `ds:tokenId`, so a `ds:Token` without one
+   * would become addressable and sampleable under a name the list never
+   * published.
+   *
+   * Requires a class constraint ({@link type}/{@link types}): the derived name
+   * is only as trustworthy as the class that vouches for the entity, and
+   * without one there is nothing to bound the scan with either.
+   */
+  readonly nameFallback?: "iri";
   /** Optional single class constraint — prefixed name or IRI. */
   readonly type?: string;
   /** CLI description for the lookup command (defaults to a generated one). */
@@ -267,6 +379,30 @@ export interface PackLookup {
    * VALUES constraint on the name resolve. Mutually exclusive with `type`.
    */
   readonly types?: readonly string[];
+  /**
+   * Relative importance per addressed type, prefixed type → 0–1 (unlisted types
+   * default to 1). Editorial judgement about which of a noun's classes matters
+   * most, declared as DATA rather than frozen into the kernel — it feeds the MCP
+   * listing's `annotations.priority`, breaks ties in URI-completion ranking, AND
+   * is one factor of the score a name resolve ORDERS BY, so a `ds:Subcomponent`
+   * at 0.6 sinks below every component at equal match.
+   *
+   * A separate map rather than an entry shape on `types` so `types` keeps its
+   * flat `readonly string[]` form and the addition is non-breaking. A key naming
+   * a type the lookup does not address is REJECTED, not ignored: a silent no-op
+   * is how a weight that never applied survives review.
+   */
+  readonly weights?: Readonly<Record<string, number>>;
+  /**
+   * The OTHER factor of that score: how much an entity's containing scope is
+   * worth, derived from how DEEP that scope sits in its own hierarchy.
+   *
+   * {@link weights} answers "which KIND of thing did they mean"; this answers
+   * "whose?". They multiply rather than tiebreak, because neither subsumes the
+   * other: a whole component in a narrow scope still beats a mere part of a
+   * block in the widest one.
+   */
+  readonly scopeWeight?: PackScopeWeight;
   /**
    * GraphQL type or interface the generated document's inline fragment targets
    * (`source: "graphql"` only). Defaults to the local name of `type`; required

package/src/kernel/packs/uniqueness.ts

@@ -8,7 +8,7 @@
  * conflict, reported with both sources.
  */
 
-import type { VerbSpec } from "../spec/types.js";
+import type { VerbSpec } from "../spec/index.js";
 
 /** The `(noun, verb)` key for a verb path (`["standard","list"]` → `standard list`). */
 export function verbKey(path: readonly [string, string?]): string {

package/src/kernel/project/cli/buildProgram.test.ts

@@ -3,6 +3,7 @@ import { afterAll, describe, expect, it, vi } from "vitest";
 import { VERSION } from "../../../constants.js";
 import { fixtureModule } from "../../../testing/fixtures/fixtureCapability.js";
 import { projectCli } from "../../../testing/helpers/projectCli.js";
+import type { GlobalFlags } from "../../runtime/index.js";
 import type { CapabilityModule, VerbSpec } from "../../spec/types.js";
 import { formatRootHelp } from "./rootHelp.js";
 
@@ -105,6 +106,121 @@ describe("buildProgram — default-true boolean negation (B9)", () => {
   });
 });
 
+describe("buildProgram — one spelling per flag", () => {
+  it("registers no short option anywhere in the tree", () => {
+    const program = projectCli([fixtureModule]);
+    const walk = (cmd: import("commander").Command): void => {
+      expect(cmd.options.some((o) => o.short !== undefined)).toBe(false);
+      for (const child of cmd.commands) walk(child);
+    };
+    walk(program);
+  });
+
+  it("still answers --help while -v/-h reject as unknown options", async () => {
+    const spyErr = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation(() => true);
+    const spyOut = vi
+      .spyOn(process.stdout, "write")
+      .mockImplementation(() => true);
+    await expect(
+      projectCli([fixtureModule]).parseAsync(["widget", "--help"], {
+        from: "user",
+      }),
+    ).rejects.toMatchObject({ code: "commander.helpDisplayed" });
+    await expect(
+      projectCli([fixtureModule]).parseAsync(["widget", "list", "-h"], {
+        from: "user",
+      }),
+    ).rejects.toMatchObject({ code: "commander.unknownOption" });
+    await expect(
+      projectCli([fixtureModule]).parseAsync(["widget", "list", "-v"], {
+        from: "user",
+      }),
+    ).rejects.toMatchObject({ code: "commander.unknownOption" });
+    spyErr.mockRestore();
+    spyOut.mockRestore();
+  });
+});
+
+describe("buildProgram — repeatable filter flags", () => {
+  /** A verb with a repeatable enum filter and a repeatable string filter. */
+  const filterVerb: VerbSpec = {
+    path: ["thing", "list"],
+    summary: "thing list summary",
+    params: [
+      {
+        kind: "enum",
+        name: "category",
+        doc: "Filter by category.",
+        values: ["css", "git"],
+        repeatable: true,
+      },
+      { kind: "string", name: "tag", doc: "Filter by tag.", repeatable: true },
+    ],
+    output: {
+      formatters: {
+        plain: (d) => JSON.stringify(d),
+        llm: (d) => JSON.stringify(d),
+        json: (d) => JSON.stringify(d),
+      },
+    },
+    capability: { needsStore: false, mutates: false, mcp: { expose: true } },
+    run: async (params) => params,
+  };
+
+  /** Parse argv and capture the option bag the action receives. */
+  async function optsFor(argv: string[]): Promise<Record<string, unknown>> {
+    let seen: Record<string, unknown> = {};
+    const program = projectCli([
+      {
+        name: "thing",
+        verbs: [
+          {
+            ...filterVerb,
+            run: async (params) => {
+              seen = params;
+              return null;
+            },
+          },
+        ],
+      },
+    ]);
+    await program.parseAsync(["thing", "list", ...argv], { from: "user" });
+    return seen;
+  }
+
+  it("accumulates a repeated filter into the union, never last-wins", async () => {
+    const params = await optsFor([
+      "--category",
+      "css",
+      "--category",
+      "git",
+      "--tag",
+      "a",
+      "--tag",
+      "b",
+    ]);
+    expect(params.category).toEqual(["css", "git"]);
+    expect(params.tag).toEqual(["a", "b"]);
+  });
+
+  it("keeps a single occurrence a one-element array and validates enum values", async () => {
+    const params = await optsFor(["--category", "css"]);
+    expect(params.category).toEqual(["css"]);
+    const program = projectCli([{ name: "thing", verbs: [filterVerb] }]);
+    const spy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation(() => true);
+    await expect(
+      program.parseAsync(["thing", "list", "--category", "bogus"], {
+        from: "user",
+      }),
+    ).rejects.toMatchObject({ code: "commander.invalidArgument" });
+    spy.mockRestore();
+  });
+});
+
 describe("buildProgram — early exits", () => {
   it("throws commander.version for --version, writing the version", async () => {
     const program = projectCli([fixtureModule]);
@@ -371,12 +487,88 @@ describe("buildProgram — sub-verb-only noun invoked bare (U2)", () => {
   });
 });
 
+/** The global flags of a human at a terminal: plain output, nothing inferred. */
+const HUMAN_FLAGS: GlobalFlags = {
+  llm: false,
+  format: "plain",
+  verbose: false,
+};
+
+/** A run whose stdout is captured: `llm`, inferred or asked for. */
+const CAPTURED_FLAGS: GlobalFlags = {
+  llm: true,
+  autoLlm: true,
+  format: "plain",
+  verbose: false,
+};
+
+/** The first line of the wordmark art — present iff the wordmark printed. */
+const WORDMARK_LINE = "(___,";
+
+const rootHelpFor = (flags: GlobalFlags): string =>
+  formatRootHelp(
+    "pragma",
+    "pragma test",
+    [
+      makeVerb(["info"]),
+      makeVerb(["config", "show"]),
+      makeVerb(["block", "list"]),
+    ],
+    "1.2.3",
+    "https://example.test/issues",
+    flags,
+  );
+
+describe("formatRootHelp — the wordmark is gated on the AUDIENCE", () => {
+  // Asserted on the ART, never on styling: `golden.ts` strips ANSI and this
+  // suite pins `chalk.level = 0`, so a colour-only change would be invisible
+  // here — and chalk emits no escapes off a TTY anyway, so it would save an
+  // agent nothing. The lines have to go.
+  it("prints the art for a human reading plain output", () => {
+    expect(rootHelpFor(HUMAN_FLAGS)).toContain(WORDMARK_LINE);
+  });
+
+  it("drops the art — every line of it — when stdout is captured", () => {
+    const help = rootHelpFor(CAPTURED_FLAGS);
+    expect(help).not.toContain(WORDMARK_LINE);
+    // No leading blank line either: the header IS the first line.
+    expect(help.startsWith("pragma v1.2.3 — pragma test")).toBe(true);
+    // Only the art goes; the page itself is untouched.
+    expect(help).toContain("Usage: pragma <command> [subcommand] [flags]");
+    expect(help).toContain("Global flags");
+  });
+
+  it("drops the art for `--format json` too", () => {
+    expect(
+      rootHelpFor({ llm: false, format: "json", verbose: false }),
+    ).not.toContain(WORDMARK_LINE);
+  });
+
+  it("keeps the art for an EXPLICIT `--format plain` down a pipe", () => {
+    // Explicit beats inference: asking for the human shape gets the human page,
+    // captured or not. (`parseGlobalFlags` leaves `llm` false whenever
+    // `--format` was requested.)
+    expect(
+      rootHelpFor({
+        llm: false,
+        autoLlm: false,
+        format: "plain",
+        verbose: false,
+      }),
+    ).toContain(WORDMARK_LINE);
+  });
+
+  it("differs ONLY by the wordmark block", () => {
+    const human = rootHelpFor(HUMAN_FLAGS).split("\n");
+    const captured = rootHelpFor(CAPTURED_FLAGS).split("\n");
+    // 10 art lines + the blank that separates them from the header.
+    expect(human.length - captured.length).toBe(11);
+    expect(human.slice(11)).toEqual(captured);
+  });
+});
+
 describe("formatRootHelp — grouping", () => {
-  const help = formatRootHelp("pragma", "pragma test", [
-    makeVerb(["info"]),
-    makeVerb(["config", "show"]),
-    makeVerb(["block", "list"]),
-  ]);
+  const help = rootHelpFor(HUMAN_FLAGS);
 
   it("leads with the uncurated nouns, untitled, under the usage line", () => {
     // `block` is not in the kernel's curated table, so it leads the page with
@@ -389,11 +581,13 @@ describe("formatRootHelp — grouping", () => {
     expect(help.match(/pragma test/g)).toHaveLength(1);
   });
 
-  it("lists the live nouns and always-available mcp", () => {
+  it("lists the live nouns, and only those", () => {
     expect(help).toContain("block");
     expect(help).toContain("config");
     expect(help).toContain("info");
-    expect(help).toContain("mcp");
+    // `mcp` is curated for PLACEMENT, not conjured into existence: a registry
+    // without an mcp verb has no mcp row.
+    expect(help).not.toContain("mcp");
   });
 
   it("drops nouns that are not present", () => {
@@ -410,7 +604,20 @@ describe("formatRootHelp — grouping", () => {
 
   it("renders the unified root page (restyle golden)", () => {
     expect(help).toMatchInlineSnapshot(`
-      "pragma — pragma test
+      "              _
+                  /' \`\\
+                /'     )
+              /' (___,/'____     ____     ____     ,__________     ____
+            /'        )'    )--/'    )  /'    )   /'    )     )  /'    )
+          /'        /'       /'    /' /'    /'  /'    /'    /' /'    /'
+      (,/'        /'        (___,/(__(___,/(__/'    /'    /(__(___,/(__
+                                        /'
+                                /     /'
+                               (___,/'
+
+      pragma v1.2.3 — pragma test
+
+      This is a preview version. Issues and suggestions: https://example.test/issues
 
       Usage: pragma <command> [subcommand] [flags]
 
@@ -420,13 +627,12 @@ describe("formatRootHelp — grouping", () => {
         config  Read and write pragma configuration
         info    Show version, config, and update status
 
-      For AI agents
-        mcp     Start the MCP server over stdio
-
       Global flags
         --format <plain|llm|json>  Select output format (llm = condensed Markdown for agents)
         --detail <level>           Progressive-disclosure level (summary, standard, detailed)
-        --verbose                  Diagnostic output on stderr
+        --no-headers               Hide the table header row in plain output
+        --quiet                    Suppress success and progress output (errors still print)
+        --verbose                  Diagnostic output on stderr (sources update)
         --help                     Show help (works on any command)
         --version                  Show the CLI version
 

package/src/kernel/project/cli/buildProgram.ts

@@ -11,11 +11,17 @@
  * the v1 cli-core `registerAll`, retargeted at the grammar.
  */
 
-import { Command, Option } from "commander";
-import { BIN_NAME, PROGRAM_DESCRIPTION, VERSION } from "../../../constants.js";
-import type { GlobalFlags } from "../../runtime/types.js";
-import { kebabCase } from "../../spec/emitSurface.js";
-import type { ParamSpec, VerbSpec } from "../../spec/types.js";
+import { Command, InvalidArgumentError, Option } from "commander";
+import {
+  BIN_NAME,
+  ISSUES_URL,
+  PROGRAM_DESCRIPTION,
+  VERSION,
+} from "../../../constants.js";
+import type { GlobalFlags } from "../../runtime/index.js";
+import { kebabCase } from "../../spec/index.js";
+import type { CliProjection, ParamSpec, VerbSpec } from "../../spec/types.js";
+import { MUTATION_FLAG_DOCS, negationFlagDoc } from "./constants.js";
 import { dispatch } from "./dispatch.js";
 import { formatRootHelp } from "./rootHelp.js";
 import { formatNounHelp, formatVerbHelp } from "./verbHelp.js";
@@ -30,6 +36,15 @@ export interface BuildProgramOptions {
   readonly description?: string;
   /** Version string for `--version`. */
   readonly version?: string;
+  /** Where root help's preview notice sends feedback. */
+  readonly issuesUrl?: string;
+  /**
+   * Module-owned noun mounts (see `CapabilityModule.cliProjection`), keyed by
+   * noun. A mounted noun's parent command is created here exactly once and
+   * handed to the module's `mount` — the module owns everything beneath it;
+   * its verbs stay the binding-level grammar for help/surface/completion.
+   */
+  readonly mounts?: ReadonlyMap<string, CliProjection>;
 }
 
 /** The positional usage token for a param (`<name>` / `[name]`, variadic `...`). */
@@ -61,7 +76,30 @@ function registerParams(command: Command, verb: VerbSpec): void {
   for (const param of verb.params) {
     if (param.positional) continue;
     const spec = flagSpec(param);
-    if (param.kind === "enum") {
+    if (
+      (param.kind === "enum" || param.kind === "string") &&
+      param.repeatable === true
+    ) {
+      // A repeatable flag ACCUMULATES — Commander's default keeps only the
+      // last occurrence, which silently drops data. The collector validates
+      // an enum's values itself, since a custom parser replaces the parser
+      // `.choices()` would install.
+      command.addOption(
+        new Option(spec, param.doc).argParser(
+          (value: string, previous: string[] | undefined) => {
+            if (
+              param.kind === "enum" &&
+              !(param.values as readonly string[]).includes(value)
+            ) {
+              throw new InvalidArgumentError(
+                `Allowed choices are ${param.values.join(", ")}.`,
+              );
+            }
+            return [...(previous ?? []), value];
+          },
+        ),
+      );
+    } else if (param.kind === "enum") {
       const option = new Option(spec, param.doc).choices([...param.values]);
       if (param.default !== undefined) option.default(param.default);
       command.addOption(option);
@@ -70,23 +108,28 @@ function registerParams(command: Command, verb: VerbSpec): void {
     } else {
       command.option(spec, param.doc);
     }
-    // B9: a default-`true` boolean is otherwise undisableable — the grammar has
-    // no negation form, so `create`'s sibling booleans (--ssr/--with-styles/…)
-    // could never be turned off. Register a paired `--no-<flag>` so they can:
+    // B9: a default-`true` boolean is otherwise undisableable — the grammar
+    // has no negation form, so a kernel-registered default-true boolean could
+    // never be turned off. Register a paired `--no-<flag>` so it can:
     // Commander keeps the `true` default and lets `--no-<flag>` set it false
-    // (verified: an unset default-false boolean is left alone). This is a CLI
-    // PARSE convenience, never a ParamSpec — `emitSurface`/MCP/the covenant are
-    // untouched — so the frozen flag list stands and negation stays additive.
+    // (verified: an unset default-false boolean is left alone). For verbs
+    // registered HERE this is a CLI PARSE convenience, never a ParamSpec —
+    // `emitSurface`/MCP/the covenant keep the positive kebab token and
+    // negation stays additive. A MOUNTED noun (`create`) never reaches this
+    // loop: its leaves register through the projection's `buildOptionInfo`,
+    // where a default-true confirm registers ONLY the `--no-` form — so its
+    // covenant/reference tokens come from the module's registered-syntax
+    // seam, not this convention (L-CIS-2).
     if (param.kind === "boolean" && param.default === true) {
       const flag = kebabCase(param.name);
-      command.option(`--no-${flag}`, `Disable --${flag} (on by default).`);
+      command.option(`--no-${flag}`, negationFlagDoc(flag));
     }
   }
 
   if (verb.capability.mutates) {
-    command.option("--dry-run", "Preview effects without applying them");
-    command.option("--undo", "Reverse a previous run of this command");
-    command.option("--yes", "Apply without an interactive confirmation");
+    for (const { flag, doc } of MUTATION_FLAG_DOCS) {
+      command.option(flag, doc);
+    }
   }
 }
 
@@ -241,15 +284,28 @@ export function buildProgram(
   const programName = options.programName ?? BIN_NAME;
   const description = options.description ?? PROGRAM_DESCRIPTION;
   const version = options.version ?? VERSION;
+  const issuesUrl = options.issuesUrl ?? ISSUES_URL;
   const live = verbs.filter((verb) => !verb.hidden);
 
   const program = new Command();
   program.name(programName).description(description);
-  program.version(version, "-v, --version");
+  // One spelling per flag: no shorts. `--version` drops `-v` (which reads as
+  // *verbose* everywhere else), and the help option is `--help` alone —
+  // subcommands created from here on inherit it (Commander copies the help
+  // option into children at creation), including a mounted subtree's.
+  program.version(version, "--version");
+  program.helpOption("--help", "Show help (works on any command)");
   program.enablePositionalOptions();
   program.exitOverride();
   useDesignedHelp(program, () =>
-    formatRootHelp(programName, description, live),
+    formatRootHelp(
+      programName,
+      description,
+      live,
+      version,
+      issuesUrl,
+      options.globalFlags,
+    ),
   );
 
   const groups = new Map<string, VerbSpec[]>();
@@ -264,6 +320,16 @@ export function buildProgram(
     const selfVerbs = bucket.filter((v) => v.path.length === 1);
     const subVerbs = bucket.filter((v) => v.path.length > 1);
 
+    // A module-owned mount replaces the generic per-verb attachment for its
+    // noun: create the parent once, hand it over, move on.
+    const mounted = options.mounts?.get(noun);
+    if (mounted) {
+      const parent = program.command(noun);
+      parent.enablePositionalOptions();
+      mounted.mount(parent, { globalFlags: options.globalFlags, programName });
+      continue;
+    }
+
     // Pure self-verb noun(s) — attach each leaf directly to the root, as before.
     if (subVerbs.length === 0) {
       for (const verb of selfVerbs) {

package/src/kernel/project/cli/constants.ts

@@ -0,0 +1,34 @@
+/**
+ * CLI projector constants — the flag/doc pairs that must read identically
+ * wherever they surface.
+ *
+ * The mutation flags are auto-injected onto every mutating verb by
+ * `registerParams` (and by the mounted create subtree's own registration),
+ * and `formatVerbHelp` renders them in the Flags block; a default-true
+ * boolean's `--no-` negation is likewise both registered and rendered. Help
+ * and registration deriving from the SAME rows here is what keeps a page
+ * from denying a flag that parses — the defect this file exists to prevent.
+ */
+
+/** One auto-injected flag: the token and the doc both surfaces print. */
+export interface FlagDoc {
+  readonly flag: string;
+  readonly doc: string;
+}
+
+/** The three mutation flags every mutating verb accepts, in display order. */
+export const MUTATION_FLAG_DOCS: readonly FlagDoc[] = [
+  { flag: "--dry-run", doc: "Preview effects without applying them" },
+  { flag: "--undo", doc: "Reverse a previous run of this command" },
+  { flag: "--yes", doc: "Apply without an interactive confirmation" },
+];
+
+/**
+ * The doc for the `--no-<flag>` negation a default-true boolean registers.
+ *
+ * @param kebab - The positive flag's kebab token (no dashes).
+ * @returns The doc string registration and help share.
+ */
+export function negationFlagDoc(kebab: string): string {
+  return `Disable --${kebab} (on by default).`;
+}