@canonical/pragma-cli 0.33.0 → 0.34.0

package/src/capabilities/create/create.test.ts

@@ -25,14 +25,14 @@ import {
 import { bootRuntime } from "../../kernel/runtime/boot.js";
 import type { GlobalFlags } from "../../kernel/runtime/types.js";
 import type { ParamSpec } from "../../kernel/spec/types.js";
+import { CREATE_GENERATORS } from "./constants.js";
 import {
-  createApplicationVerb,
-  createComponentVerb,
-  createPackageVerb,
+  createVerbs,
   INCLUDE_FLAG_ALIASES,
   isModuleNotFound,
 } from "./create.verb.js";
 import { generatorToParams } from "./generatorToVerbSpec.js";
+import { createModule } from "./index.js";
 
 const FLAGS: GlobalFlags = {
   llm: false,
@@ -53,7 +53,7 @@ async function runIn(
   process.chdir(dir);
   try {
     return await executeVerb(
-      createComponentVerb,
+      createVerbs.component,
       params,
       mutation,
       bootRuntime(FLAGS, dir),
@@ -86,7 +86,11 @@ describe("create — real generation + stamp", () => {
     expect(readFileSync(main, "utf-8").split("\n")[0]).toBe(
       "// Generated by @canonical/summon-component:react v0.1.0",
     );
-  });
+    // Explicit timeout, like the package's other real-run gates: this drives a
+    // full generator run (~2.4s idle), and under a contended CI matrix the 5s
+    // vitest default fails it on load, not on a defect — both build-matrix
+    // legs timed out at 5000ms on a run whose import phase alone took 88s.
+  }, 60_000);
 
   it("--dry-run writes nothing and previews effects (no Prompt lines)", async () => {
     const dir = freshCwd();
@@ -101,6 +105,45 @@ describe("create — real generation + stamp", () => {
     expect(walk(dir)).toEqual([]); // nothing written
   });
 
+  it("--dry-run reports the bytes the real run writes (post-stamp)", async () => {
+    // The mock previewer never called `onEffectStart`, so summon's stamping
+    // transform did not run and every planned byte count under-reported the
+    // written file by the stamp's length. The honest previewer runs it.
+    const params = {
+      framework: "react",
+      componentPath: "src/components/Widget",
+      withStyles: true,
+      withStories: false,
+      withSsrTests: false,
+    };
+    const previewDir = freshCwd();
+    const preview = await runIn(previewDir, params, {
+      dryRun: true,
+      undo: false,
+      yes: false,
+    });
+    expect(preview.exitCode).toBe(0);
+    expect(walk(previewDir)).toEqual([]);
+
+    const planned = new Map<string, number>();
+    for (const line of (preview.stdout ?? "").split("\n")) {
+      const match = /^ {2}- Write file: (.+) \((\d+) bytes\)$/.exec(line);
+      if (match) planned.set(match[1] as string, Number(match[2]));
+    }
+    expect(planned.size).toBeGreaterThan(0);
+
+    const realDir = freshCwd();
+    expect((await runIn(realDir, params)).exitCode).toBe(0);
+    for (const [relative, bytes] of planned) {
+      expect({
+        file: relative,
+        bytes: readFileSync(join(realDir, relative), "utf-8").length,
+      }).toEqual({ file: relative, bytes });
+    }
+    // Same set of files, not just the same counts for the ones checked.
+    expect(walk(realDir).sort()).toEqual([...planned.keys()].sort());
+  });
+
   it("--undo reverses a run", async () => {
     const dir = freshCwd();
     await runIn(dir, {
@@ -123,7 +166,9 @@ describe("create — real generation + stamp", () => {
     );
     expect(outcome.exitCode).toBe(0);
     expect(outcome.stdout).toMatch(/Undid \d+ step/);
-  });
+    // TWO real runs (generate, then undo) — the same load-sensitivity as the
+    // stamp test above, doubled; same explicit ceiling.
+  }, 60_000);
 
   it("rejects an unknown framework with INVALID_INPUT", async () => {
     const dir = freshCwd();
@@ -131,7 +176,7 @@ describe("create — real generation + stamp", () => {
     // framework param to exercise pickGenerator's own guard too.
     const runtime = bootRuntime(FLAGS, dir);
     await expect(
-      createComponentVerb.run({ framework: "vue" }, {
+      createVerbs.component.run({ framework: "vue" }, {
         ...runtime,
         interaction: { isTTY: false, transport: "cli", yes: true },
       } as never),
@@ -217,9 +262,19 @@ describe("lazy-React discipline (PROTECTED)", () => {
       "@canonical/summon-component",
       "@canonical/summon-package",
       "@canonical/summon-application",
+      // The generators pull summon-core, and summon-core is what costs the
+      // fast paths (+43 MB RSS once it loads). Dropping the `type` from one of
+      // the four `import type … from "@canonical/summon-core"` lines in this
+      // directory is a one-word regression nothing else catches.
+      "@canonical/summon-core",
     ];
     for (const file of graph) {
-      const src = readFileSync(file, "utf-8");
+      // Type-only imports are erased before runtime, so they load nothing —
+      // strip them before asking what the file actually pulls in.
+      const src = readFileSync(file, "utf-8").replace(
+        /\bimport\s+type\b[^;]*;/g,
+        "",
+      );
       for (const pkg of forbidden) {
         const esc = pkg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
         expect(
@@ -285,7 +340,7 @@ describe("generator→grammar adapter parity (PROTECTED)", () => {
       (generators as Record<string, { prompts: unknown[] }>)["component/react"]
         .prompts as never,
     );
-    const verb = createComponentVerb.params;
+    const verb = createVerbs.component.params;
 
     // The verb SYNTHESIZES a `framework` enum (the 3 framework generators
     // collapse to one verb): react|svelte|lit, default react — no generator
@@ -328,7 +383,7 @@ describe("generator→grammar adapter parity (PROTECTED)", () => {
         .prompts as never,
     );
     // The package verb's grammar IS generatorToParams(PACKAGE_MIRROR).
-    expect(behavioural(createPackageVerb.params)).toEqual(
+    expect(behavioural(createVerbs.package.params)).toEqual(
       behavioural(applyRunInstallOverride(real)),
     );
 
@@ -336,7 +391,7 @@ describe("generator→grammar adapter parity (PROTECTED)", () => {
     const realRunInstall = real.find((p) => p.name === "runInstall") as
       | Record<string, unknown>
       | undefined;
-    const mirrorRunInstall = createPackageVerb.params.find(
+    const mirrorRunInstall = createVerbs.package.params.find(
       (p) => p.name === "runInstall",
     ) as Record<string, unknown> | undefined;
     expect(realRunInstall?.default).toBe(true);
@@ -375,14 +430,14 @@ describe("generator→grammar adapter parity (PROTECTED)", () => {
     // generator's `ssr`/`router`/`forms`.
     expect(
       behavioural(
-        toGeneratorNames("application", createApplicationVerb.params),
+        toGeneratorNames("application", createVerbs.application.params),
       ),
     ).toEqual(behavioural(applyRunInstallOverride(real)));
 
     // Guard the B8 rename itself: ALL application include-flags ARE on the
     // `--with-X` convention (params `withSsr`/`withRouter`/`withForms`/
     // `withRelay`), not the bare `ssr`/`router`/`forms`/`relay` booleans.
-    const names = createApplicationVerb.params.map((p) => p.name);
+    const names = createVerbs.application.params.map((p) => p.name);
     expect(names).toContain("withSsr");
     expect(names).toContain("withRouter");
     expect(names).toContain("withForms");
@@ -393,7 +448,7 @@ describe("generator→grammar adapter parity (PROTECTED)", () => {
     const realRunInstall = real.find((p) => p.name === "runInstall") as
       | Record<string, unknown>
       | undefined;
-    const mirrorRunInstall = createApplicationVerb.params.find(
+    const mirrorRunInstall = createVerbs.application.params.find(
       (p) => p.name === "runInstall",
     ) as Record<string, unknown> | undefined;
     expect(realRunInstall?.default).toBe(true);
@@ -401,7 +456,7 @@ describe("generator→grammar adapter parity (PROTECTED)", () => {
 
     // appPath is the positional entry point (its default carries across).
     expect(
-      createApplicationVerb.params.find((p) => p.name === "appPath"),
+      createVerbs.application.params.find((p) => p.name === "appPath"),
     ).toMatchObject({ kind: "string", positional: true, default: "my-app" });
   });
 });
@@ -430,3 +485,95 @@ describe("compiled-binary create gate (M4)", () => {
     expect(isModuleNotFound("nope")).toBe(false);
   });
 });
+
+describe("declared generator bindings (PROTECTED)", () => {
+  // CREATE_GENERATORS is the one place the create surface's generator facts are
+  // written down. What is checkable against something outside itself — the live
+  // generator maps and the embedded manifest — is checked here.
+
+  it("every binding resolves to the generator it names", async () => {
+    const { pickGenerator } = await import("./pickGenerator.js");
+    // `meta.name` is the generator's OWN identity, so a swapped `key` or a
+    // framework the map does not carry turns this red — which `toBeDefined()`
+    // on a non-nullable return could not.
+    for (const framework of CREATE_GENERATORS.component.frameworks) {
+      expect(pickGenerator("component", { framework }).meta.name).toBe(
+        `component/${framework}`,
+      );
+    }
+    expect(pickGenerator("package", {}).meta.name).toBe("package");
+    expect(pickGenerator("application", {}).meta.name).toBe(
+      "application/react",
+    );
+  });
+
+  it("exactly the two source-run-only verbs publish the availability caveat", () => {
+    // A LITERAL list, for the same reason `compiledCreate.subprocess.test.ts`
+    // uses one: the caveat is DERIVED from `readsEmbeddedTemplates`, so an
+    // assertion derived from the same bit would agree with itself no matter
+    // which way the bit was flipped. These two are the nouns that test proves
+    // refuse on a real compiled binary, so this is what the reference is held
+    // to — and flipping the bit turns this red, along with the reference
+    // drift-guard, in the same run.
+    const caveated = createModule.verbs
+      .filter((verb) => verb.summary.includes("Source-run only."))
+      .map((verb) => verb.path.at(1));
+    expect(caveated).toEqual(["package", "application"]);
+    for (const verb of createModule.verbs) {
+      const kind = verb.path.at(1);
+      const gated = caveated.includes(kind);
+      // The `doc` is what `tools.md` and the MCP tool description render, so
+      // the explanation has to travel with the marker, and it quotes the
+      // command it is about — a copy-paste between bindings is then visible.
+      expect(verb.doc?.includes("UNSUPPORTED") ?? false, kind).toBe(gated);
+      if (gated) {
+        expect(verb.doc).toContain(`create ${kind}`);
+        // And it still says what the verb MAKES. `doc ?? summary` means a doc
+        // REPLACES the summary on the MCP surface, so a caveat alone left an
+        // agent no statement anywhere of what `create_package` scaffolds.
+        expect(verb.doc).toContain(
+          verb.summary.replace(" Source-run only.", ""),
+        );
+      }
+    }
+  });
+
+  it("the --framework enum offers the declared frameworks and defaults to one of them", () => {
+    const framework = createVerbs.component.params.find(
+      (p) => p.name === "framework",
+    );
+    // A `values: []` enum with a `default` would leave every `--framework`
+    // rejected while `--help` still advertises a default — the hazard this names.
+    // (That every value resolves is the test above.)
+    expect(framework?.kind).toBe("enum");
+    const values = (framework as { values: readonly string[] }).values;
+    expect(values.length).toBeGreaterThan(0);
+    expect(values).toContain(framework?.default);
+  });
+
+  it("embeds only the templates the component loader can key", async () => {
+    const { TEMPLATES } = await import("./templates.embedded.generated.js");
+    const keys = Object.keys(TEMPLATES);
+    // summon-component's `qualifiedKey()` prefixes EVERY lookup with
+    // `component/`, so any other entry ships dead weight the binary can never
+    // read — and a binding embedded without a manifest-reading generator would
+    // put one here. Non-empty first: `.every()` over an empty list is vacuous.
+    expect(keys.length).toBeGreaterThan(0);
+    expect(keys.filter((k) => !k.startsWith("component/"))).toEqual([]);
+  });
+
+  it("create surfaces exactly the three declared nouns", () => {
+    // A LITERAL surface pin, deliberately not derived from CREATE_GENERATORS:
+    // surfacing a noun also needs a hand-written prompt mirror, path param and
+    // examples in create.verb.ts, so the surface is a deliberate SUBSET of what
+    // the declared packages ship (`@canonical/summon-application` also ships
+    // `domain`, `route` and `wrapper`). Pinning OUR three nouns rather than any
+    // third-party package's generator list keeps an upstream release from
+    // turning this red.
+    expect(createModule.verbs.map((v) => v.path[1])).toEqual([
+      "component",
+      "package",
+      "application",
+    ]);
+  });
+});

package/src/capabilities/create/create.verb.ts

@@ -1,11 +1,11 @@
 /**
  * The `create` verbs — `component` / `package` / `application` (path capped at
- * two segments; the three component frameworks collapse to one verb + a
+ * two segments; the declared component frameworks collapse to one verb + a
  * `--framework` enum). Each is a mutating, interactive, storeless verb.
  *
  * LAZY DISPATCH (R9 + lazy-React): the params are STATIC — built by the
  * generator→grammar adapter over static prompt MIRRORS, never the live
- * generators (importing a generator runs a top-level `await loadTemplate`). The
+ * generators (importing a generator pulls summon-core, and with it React). The
  * `run` body lazily `import()`s `pickGenerator` + summon-core, so `buildProgram`
  * / `--help` / `__complete` / reads never load summon-core or the generators —
  * and `create --yes` never loads React (the Ink UI is dynamic-only, and only the
@@ -15,9 +15,11 @@
 
 import type { GeneratorResult, PromptDefinition } from "@canonical/summon-core";
 import type { Task } from "@canonical/task";
+import { BIN_NAME } from "../../constants.js";
 import { PragmaError } from "../../kernel/error/PragmaError.js";
 import type { PragmaRuntime } from "../../kernel/runtime/types.js";
 import type { ParamSpec, VerbSpec } from "../../kernel/spec/types.js";
+import { CREATE_GENERATORS } from "./constants.js";
 import { createFormatters } from "./create.render.js";
 import { generatorToParams } from "./generatorToVerbSpec.js";
 import { assertInsideWorkspace } from "./pathJail.js";
@@ -27,13 +29,14 @@ import type { CreateKind } from "./types.js";
 // Static params (mirrors of the generators' prompts — see the module doc)
 // =============================================================================
 
-/** `--framework` — the three component generators collapsed to one enum. */
+/** `--framework` — the declared component generators collapsed to one enum. */
 const FRAMEWORK_PARAM: ParamSpec = {
   kind: "enum",
   name: "framework",
   doc: "Component framework.",
-  values: ["react", "svelte", "lit"],
-  default: "react",
+  values: CREATE_GENERATORS.component.frameworks,
+  // The FIRST declared framework, so the default is always inside the enum.
+  default: CREATE_GENERATORS.component.frameworks[0],
 };
 
 /**
@@ -234,20 +237,16 @@ const PATH_PARAM: Record<CreateKind, string | undefined> = {
 // The lazy run — the one-line summon↔pragma seam per invocation
 // =============================================================================
 
-/**
- * Build the `create` Task for one invocation: pick the generator, jail its
- * output path, pre-validate flag/arg answers, pick the prompt strategy against
- * the interaction context, wire `runtime.exec`, and return `execute`.
- *
- * @returns A `Promise<Task<GeneratorResult>>` (the union's third arm) the
- *   dispatcher/MCP handler awaits into a Task before interpreting.
- */
 /**
  * The standalone `bun build --compile` binary resolves every bundled module
  * under the virtual `/$bunfs` filesystem — a marker absent from any source or
- * `bun`-run module URL. `create component` is fully embedded and runs from the
- * binary; `create package` / `create application` are NOT (application also
- * copies non-`.ejs` assets), so they are gated to a source run below.
+ * `bun`-run module URL. Only a generator that routes its template reads through
+ * the embedded manifest can run there
+ * (`CREATE_GENERATORS[kind].readsEmbeddedTemplates`);
+ * the others call `template({ source })`, which falls through to
+ * `readFile(source)` and dies with `ENOENT … /$bunfs/…` after `mkdir` has
+ * already run, leaving partially-created files behind.
+ * `compiledCreate.subprocess.test.ts` pins the refusal AND the empty cwd.
  */
 const IS_COMPILED_BINARY = import.meta.url.includes("/$bunfs/");
 
@@ -281,23 +280,22 @@ export function isModuleNotFound(cause: unknown): boolean {
  * `--compile` bundler includes them — they stay behind this lazy boundary, so
  * the fast paths and `create --yes` still load neither summon-core nor React).
  *
- * The manifest is injected BEFORE `pickGenerator` — importing the generator
- * packages runs a top-level `await loadTemplate`, and the component loader
- * consults the manifest when its disk read fails (the compiled binary). It is
- * imported from summon-component's `loadTemplate` submodule so this does not
- * evaluate the generator index first. In a source run the disk read wins and the
- * manifest is inert.
+ * The manifest is injected BEFORE `pickGenerator` — the component loader
+ * consults it when its disk read fails (the compiled binary), and the generators
+ * load their templates on first `generate()`. It is imported from
+ * summon-component's `loadTemplate` submodule so this does not evaluate the
+ * generator index first. In a source run the disk read wins and the manifest is
+ * inert.
  *
- * `create package` / `create application` are not yet embedded for the compiled
- * binary (application also copies non-`.ejs` assets), so they are gated to a
- * source run here. A stale resolution failure is a defensive backstop
- * {@link isModuleNotFound} turns into the same clean gate.
+ * A binding whose generator does not read through that manifest is gated to a
+ * source run here ({@link IS_COMPILED_BINARY}). A stale resolution failure is a
+ * defensive backstop {@link isModuleNotFound} turns into the same clean gate.
  */
 async function loadCreateRuntime(kind: CreateKind) {
-  if (IS_COMPILED_BINARY && kind !== "component") {
+  if (IS_COMPILED_BINARY && !CREATE_GENERATORS[kind].readsEmbeddedTemplates) {
     throw new PragmaError({
       code: "UNSUPPORTED",
-      message: `\`create ${kind}\` is not available in the compiled pragma binary yet — only \`create component\` is embedded. Run it from a source checkout, or use the \`summon\` CLI.`,
+      message: `\`create ${kind}\` is not available in the compiled ${BIN_NAME} binary — ${SOURCE_ONLY_REASON}. Run it from a source checkout, or use the \`summon\` CLI.`,
       recovery: {
         message: `Run \`create ${kind}\` from a source checkout, or use \`summon\`.`,
       },
@@ -331,15 +329,26 @@ async function loadCreateRuntime(kind: CreateKind) {
   }
 }
 
+/**
+ * Build the `create` Task for one invocation: pick the generator, jail its
+ * output path, pre-validate flag/arg answers, pick the prompt strategy against
+ * the interaction context, wire `runtime.exec`, and return `execute`.
+ *
+ * @param kind - The create noun.
+ * @param params - The coerced params for this invocation.
+ * @param rt - The pragma runtime.
+ * @returns A `Promise<Task<GeneratorResult>>` (the union's third arm) the
+ *   dispatcher/MCP handler awaits into a Task before interpreting.
+ */
 async function runCreate(
   kind: CreateKind,
   params: Record<string, unknown>,
   rt: PragmaRuntime,
 ): Promise<Task<GeneratorResult>> {
-  // Lazy: importing these runs the generators' top-level template loads and
-  // pulls summon-core — kept off every non-create path. Now STATIC dynamic
-  // imports so `--compile` bundles them; the generators' `.ejs` are embedded and
-  // injected here. `package`/`application` stay a source-run feature in the binary.
+  // Lazy: importing these pulls summon-core (and with it React) — kept off every
+  // non-create path. Now STATIC dynamic imports so `--compile` bundles them; the
+  // embedded `.ejs` manifest is injected here. A binding that does not read
+  // through it stays a source-run feature in the binary.
   const { pickGenerator, summon } = await loadCreateRuntime(kind);
 
   // Normalize the CLI/MCP `--with-X` include-flags to the generator prompt names
@@ -374,7 +383,13 @@ async function runCreate(
     // `onCancel` (H2): an in-Ink Ctrl-C during execution aborts the run so the
     // interpreter stops writing — raw mode swallows the SIGINT, so the wizard
     // drives the abort. Shared with setup by construction.
-    const session = summon.inkPrompt(generator, { signal, onCancel: abort });
+    // `cwd` also reaches the wizard: its confirm-gate preview reads the same
+    // jail-checked write root the interpreter resolves effect paths against.
+    const session = summon.inkPrompt(generator, {
+      signal,
+      onCancel: abort,
+      cwd: rt.cwd,
+    });
     // Thread the per-call write root: the interpreter resolves the generator's
     // relative output paths against `rt.cwd` — the SAME dir the SEC-2 jail
     // validated above — so the write can never escape the checked directory.
@@ -433,10 +448,51 @@ const CREATE_CAPABILITY = {
   },
 };
 
+/**
+ * Why a binding is source-run only — the ONE authoring of it, shared by the
+ * documentation below and by {@link loadCreateRuntime}'s `UNSUPPORTED` refusal,
+ * so what the reference promises and what the binary does cannot disagree.
+ */
+const SOURCE_ONLY_REASON =
+  "its generator reads templates from disk, which the binary does not carry";
+
+/**
+ * The published caveat for a binding the compiled binary cannot run. DERIVED
+ * from `CREATE_GENERATORS[kind].readsEmbeddedTemplates` — flipping that bit
+ * moves the caveat, `docs/reference/*.md`, and `create.test.ts`'s binding
+ * assertion together.
+ *
+ * It LEADS WITH THE PURPOSE, because `tools.md` and the MCP tool description
+ * both render `doc ?? summary` — so a caveat alone REPLACED the only sentence
+ * saying what the tool makes, and an agent enumerating tools could not learn
+ * that `create_package` scaffolds a package. The tool works from a source
+ * checkout; describing nothing but its refusal made a live tool
+ * undiscoverable. The repeated sentence in `commands.md`'s section is the
+ * cheaper of the two costs.
+ *
+ * It names no CLI flag (`mcp/toolDescriptions.test.ts` forbids one, and an
+ * agent has no flags): the plan-only refusal is stated in the terms BOTH
+ * surfaces share.
+ *
+ * @param kind - The create binding.
+ * @param summary - The verb's own one-liner, which the `doc` replaces on MCP.
+ * @returns The `doc` for a source-run-only binding, or `undefined`.
+ */
+function buildAvailabilityDoc(
+  kind: CreateKind,
+  summary: string,
+): string | undefined {
+  if (CREATE_GENERATORS[kind].readsEmbeddedTemplates) return undefined;
+  return `${summary} From the compiled ${BIN_NAME} binary, \`create ${kind}\` refuses with \`UNSUPPORTED\` and writes nothing. Asking it only to PLAN refuses too — the gate runs while the plan is built — so a successful plan is never evidence it would run. The cause is that ${SOURCE_ONLY_REASON}. Run it from a source checkout, or use the \`summon\` CLI.`;
+}
+
 /**
  * Build a create verb. `run` presents `Promise<Task<R>>` through the `Task<R>`
  * arm by an honest cast at this one site (mirroring `sources update`): a literal
  * `Promise<Task<R>>` arm in the union would poison async read-verb inference.
+ *
+ * A binding the compiled binary cannot run says so in its `summary` (which is
+ * what `--help` and the noun listing show) and explains itself in its `doc`.
  */
 function createVerb(
   kind: CreateKind,
@@ -444,9 +500,11 @@ function createVerb(
   params: ParamSpec[],
   examples: VerbSpec["examples"],
 ): VerbSpec<Record<string, unknown>, GeneratorResult> {
+  const doc = buildAvailabilityDoc(kind, summary);
   return {
     path: ["create", kind],
-    summary,
+    summary: doc ? `${summary} Source-run only.` : summary,
+    ...(doc ? { doc } : {}),
     params,
     output: { formatters: createFormatters },
     examples,
@@ -456,38 +514,51 @@ function createVerb(
   };
 }
 
-export const createComponentVerb = createVerb(
-  "component",
-  "Scaffold a React, Svelte, or Lit component.",
-  componentParams,
-  [
-    {
-      cmd: "pragma create component src/components/Button --framework react",
-      note: "React component with tests, stories, and styles",
-    },
-    {
-      cmd: "pragma create component src/lib/Card --framework svelte --dry-run",
-      note: "preview the files without writing",
-    },
-  ],
-);
-
-export const createPackageVerb = createVerb(
-  "package",
-  "Scaffold a new npm package for the monorepo.",
-  packageParams,
-  [
-    { cmd: "pragma create package --name @canonical/my-lib --type library" },
-    { cmd: "pragma create package --name @canonical/my-tool --run-install" },
-  ],
-);
-
-export const createApplicationVerb = createVerb(
-  "application",
-  "Scaffold a full React application with SSR and routing.",
-  applicationParams,
-  [
-    { cmd: "pragma create application my-app" },
-    { cmd: "pragma create application my-app --with-relay" },
-  ],
-);
+/**
+ * The `create` verbs, one per declared generator binding — so adding a binding
+ * to {@link CREATE_GENERATORS} without surfacing it is a type error rather than
+ * a silent no-op. Key order is authoring order, which `index.ts` preserves into
+ * the command tree, `--help` and the emitted surface.
+ */
+export const createVerbs: Record<
+  CreateKind,
+  VerbSpec<Record<string, unknown>, GeneratorResult>
+> = {
+  component: createVerb(
+    "component",
+    "Scaffold a React, Svelte, or Lit component.",
+    componentParams,
+    [
+      {
+        cmd: `${BIN_NAME} create component src/components/Button --framework react`,
+        note: "React component with tests, stories, and styles",
+      },
+      {
+        cmd: `${BIN_NAME} create component src/lib/Card --framework svelte --dry-run`,
+        note: "preview the files without writing",
+      },
+    ],
+  ),
+  package: createVerb(
+    "package",
+    "Scaffold a new npm package for the monorepo.",
+    packageParams,
+    [
+      {
+        cmd: `${BIN_NAME} create package --name @canonical/my-lib --type library`,
+      },
+      {
+        cmd: `${BIN_NAME} create package --name @canonical/my-tool --run-install`,
+      },
+    ],
+  ),
+  application: createVerb(
+    "application",
+    "Scaffold a full React application with SSR and routing.",
+    applicationParams,
+    [
+      { cmd: `${BIN_NAME} create application my-app` },
+      { cmd: `${BIN_NAME} create application my-app --with-relay` },
+    ],
+  ),
+};

package/src/capabilities/create/index.ts

@@ -8,18 +8,10 @@
 
 import { asVerb } from "../../kernel/spec/asVerb.js";
 import type { CapabilityModule } from "../../kernel/spec/types.js";
-import {
-  createApplicationVerb,
-  createComponentVerb,
-  createPackageVerb,
-} from "./create.verb.js";
+import { createVerbs } from "./create.verb.js";
 
 /** The `create` capability module. */
 export const createModule: CapabilityModule = {
   name: "create",
-  verbs: [
-    asVerb(createComponentVerb),
-    asVerb(createPackageVerb),
-    asVerb(createApplicationVerb),
-  ],
+  verbs: Object.values(createVerbs).map(asVerb),
 };