@canonical/pragma-cli 0.33.0 → 0.34.0

package/src/capabilities/create/pickGenerator.ts

@@ -1,38 +1,46 @@
-/**
- * Select the summon generator for a `create` invocation.
- *
- * This module statically imports the summon generator packages' `generators`
- * maps — and importing them runs a top-level `await loadTemplate` that reads
- * every template file from disk. So this module MUST stay behind `create`'s
- * lazy `import()` (R9): the fast paths (`buildProgram` / `__complete` / `--help`
- * / reads) never load it, and `create --yes` never loads React either (the
- * generators pull summon-core, whose Ink UI is dynamic-only).
- */
-
 import { generators as applicationGenerators } from "@canonical/summon-application";
 import { generators as componentGenerators } from "@canonical/summon-component";
 import type { GeneratorDefinition } from "@canonical/summon-core";
 import { generators as packageGenerators } from "@canonical/summon-package";
 import { PragmaError } from "../../kernel/error/PragmaError.js";
+import { CREATE_GENERATORS } from "./constants.js";
 import type { CreateKind } from "./types.js";
 
-/** The component frameworks that collapse to one `create component` verb. */
-export const FRAMEWORKS = ["react", "svelte", "lit"] as const;
+type GeneratorMap = Record<string, GeneratorDefinition | undefined>;
 
 /**
- * The generators' `generate` is invariant in its (specific) answer type, so the
- * strongly-typed maps are erased to the base definition via `unknown`. This is
- * runtime-safe: `execute` calls `generate(answers)` with the resolved answers,
- * which carry the fields the specific generator reads.
+ * The declared packages' generator maps, bound by noun. The STATIC imports above
+ * are load-bearing: `bun build --compile` bundles only statically analysable
+ * specifiers, so `import(CREATE_GENERATORS[kind].name)` would leave the
+ * generators out of the binary (measured: `Cannot find module
+ * '@canonical/summon-component' from '/$bunfs/root/…'`). The declaration decides
+ * WHICH generator runs; it cannot decide which module is linked.
+ *
+ * The maps' `generate` is invariant in its (specific) answer type, so they are
+ * erased to the base definition via `unknown` — runtime-safe because `execute`
+ * calls `generate(answers)` with the resolved answers, which carry the fields
+ * the specific generator reads.
  */
-type GeneratorMap = Record<string, GeneratorDefinition | undefined>;
-const componentMap = componentGenerators as unknown as GeneratorMap;
-const packageMap = packageGenerators as unknown as GeneratorMap;
-const applicationMap = applicationGenerators as unknown as GeneratorMap;
+const GENERATOR_MAPS: Record<CreateKind, GeneratorMap> = {
+  component: componentGenerators as unknown as GeneratorMap,
+  package: packageGenerators as unknown as GeneratorMap,
+  application: applicationGenerators as unknown as GeneratorMap,
+};
 
 /**
  * Pick the generator for a `create <kind>` run.
  *
+ * The module this lives in statically imports the summon generator packages'
+ * `generators` maps — and importing them pulls summon-core. So it MUST stay
+ * behind `create`'s lazy `import()` (R9): the fast paths (`buildProgram` /
+ * `__complete` / `--help` / reads) never load it, and `create --yes` never loads
+ * React either (summon-core's Ink UI is dynamic-only).
+ *
+ * `component` is branched on literally: it is the only noun with a framework
+ * axis (which is why the verb synthesises a `--framework` enum), and narrowing
+ * on `kind` here lets `CREATE_GENERATORS[kind].key` type-check over the
+ * remaining nouns without `in`-narrowing gymnastics.
+ *
  * @param kind - The create noun.
  * @param params - The coerced params (used for `--framework` on `component`).
  * @returns The selected generator definition.
@@ -43,19 +51,17 @@ export function pickGenerator(
   params: Readonly<Record<string, unknown>>,
 ): GeneratorDefinition {
   if (kind === "component") {
-    const framework = String(params.framework ?? "react");
-    const generator = componentMap[`component/${framework}`];
+    const { frameworks } = CREATE_GENERATORS.component;
+    const framework = String(params.framework ?? frameworks[0]);
+    const generator = GENERATOR_MAPS.component[`component/${framework}`];
     if (!generator) {
       throw PragmaError.invalidInput("framework", framework, {
-        validOptions: [...FRAMEWORKS],
+        validOptions: [...frameworks],
       });
     }
     return generator;
   }
-  const generator =
-    kind === "package"
-      ? packageMap.package
-      : applicationMap["application/react"];
+  const generator = GENERATOR_MAPS[kind][CREATE_GENERATORS[kind].key];
   if (!generator) {
     throw PragmaError.internalError(`missing ${kind} generator`);
   }

package/src/capabilities/create/templates.embedded.generated.ts

@@ -1,24 +1,10 @@
 // AUTO-GENERATED by scripts/build.ts — do not edit by hand.
-// Regenerate: `bun run scripts/build.ts`. Inlines the summon generators' .ejs
-// templates as strings so `pragma create` works from the standalone --compile
-// binary (the .ejs files are absent from the binary's virtual filesystem).
+// Regenerate: `bun run scripts/build.ts`. Inlines the .ejs templates of the
+// generators that read through this manifest (`create component`) as strings, so
+// `pragma create component` works from the standalone --compile binary (the .ejs
+// files are absent from the binary's virtual filesystem).
 /** Directory-qualified template path → file contents. */
 export const TEMPLATES: Record<string, string> = {
-  "application/.storybook/main.ts.ejs": "import { createConfig } from \"@canonical/storybook-config\";\n\nexport default createConfig(\"react\", {\n  staticDirs: [\"../src/assets\", \"../public\"],\n<% if (relay) { -%>\n  // Wraps stories that declare `parameters.relay` in a relay-test-utils mock\n  // environment, so components using Relay hooks render without a server.\n  extraAddons: [\"@canonical/storybook-addon-relay\"],\n<% } -%>\n});\n",
-  "application/README.md.ejs": "# <%= name %>\n\nA React application with server-side rendering and routing, generated by\n`@canonical/summon`. It is built on Canonical's shared design system, router, and\nSSR packages, and ships SSR on two runtimes (Bun and Node), file-based routing, a\ncomponent library wired to design tokens, and Storybook.\n\n## Quick start\n\n```bash\nbun install\nbun run dev:bun      # SSR dev server with HMR, on http://localhost:5174\n```\n\nEdit anything under `src/` and the page hot-reloads. To check the production\nbuild before shipping, run `bun run preview:bun` instead.\n\n## Running the app\n\nThe server scripts form a **2×3 matrix** — two modes (development and preview)\nacross three targets (a client-only SPA, SSR on Bun, SSR on Node/Express):\n\n|                  | `dev` — transform, HMR | `preview` — compiled, production-faithful |\n| ---------------- | ---------------------- | ----------------------------------------- |\n| **SPA** (no SSR) | `bun run dev`          | `bun run preview`                         |\n| **SSR · Bun**    | `bun run dev:bun`      | `bun run preview:bun`                     |\n| **SSR · Node**   | `bun run dev:express`  | `bun run preview:express`                 |\n\nThe naming is systematic: the bare name is the **SPA**, the `:bun` / `:express`\nsuffix selects the **SSR runtime**, and the `dev` / `preview` prefix selects the\n**mode**. Reach for `dev:*` while building — it is the fast inner loop, with HMR\nand no build step — and for `preview:*` when verifying that the production bundle\nbehaves before a deploy: `preview:*` builds the client and runs a compiled\nrenderer over the built assets, the same artifact that deploys.\n\n```bash\nbun run storybook    # component workshop\n```\n<% if (relay) { -%>\n\nRelay's compiler artifacts are committed, not rebuilt on the fly:\n\n```bash\nbun run relay          # regenerate src/relay/__generated__ after schema/query edits\nbun run relay:watch    # the same, re-running on change — pair with dev:*\n```\n<% } -%>\n\n## Adding routes\n\n`summon` scaffolds the building blocks of the app so new features follow the\nestablished structure rather than diverging from it.\n\n```bash\nsummon domain billing            # a new feature domain (routes + pages)\nsummon route billing/invoices    # a route within a domain\nsummon wrapper sidebar           # a layout wrapper\n```\n\n## Testing\n\n```bash\nbun run test          # unit + component tests (Vitest, jsdom)\nbun run test:coverage # the same, with a coverage report\nbun run test:e2e      # boots all six matrix servers and asserts each serves\n```\n\n`test:e2e` is an end-to-end test *of the build*: it runs each of the six server\nscripts — including the production builds that `preview:*` performs — and asserts\nthat every server returns a rendered document and serves its client assets with\nthe correct content type.\n\n## Project structure\n\n```\nsrc/\n├── client/         Client entry (hydration)\n├── server/         Server entry, compiled renderer, dev servers, sitemap\n├── domains/        Feature domains (each owns its routes and pages)\n├── lib/            Shared components\n<% if (relay) { -%>\n├── relay/          Relay environment factory, executable mock schema,\n│                   and generated artifacts (__generated__/)\n<% } -%>\n├── styles/         Application CSS\n├── assets/         Assets imported in code (bundled and hashed by Vite)\n└── routes.tsx      Root route map\npublic/             Files served verbatim at a fixed URL (favicon, robots.txt)\ntest/e2e/           The 2×3 server-matrix end-to-end suite\n```\n\nDomains are the unit of feature organisation: each owns its routes and pages, so\nadding a feature is adding a domain rather than threading changes through shared\nfiles. This app ships both `src/assets/` (assets imported in code) and `public/`\n(files served by fixed URL); either may be removed if the app uses only one.\n<% if (relay) { -%>\n\n## Data layer (Relay)\n\nThe `catalog` domain demonstrates the app's [Relay](https://relay.dev) data\nlayer: `ProductList` fetches a page of products with `useLazyLoadQuery`, and\neach `ProductCard` reads its own colocated `useFragment` — the component owns\nits field selection, the parent query just spreads it.\n\n**By default the app needs no backend.** `createEnvironment`\n(`src/relay/environment.ts`) resolves every GraphQL operation in-process\nagainst an executable mock schema (`src/relay/schema.ts`, built from the SDL\nin `src/relay/schema.graphql`) backed by a small deterministic catalog. Set\n`VITE_GRAPHQL_URL` (or pass `graphqlUrl` to `createEnvironment`) to switch the\nenvironment to posting operations to a real GraphQL endpoint instead — no code\nchanges needed.\n\n**Generated artifacts are committed.** The Vite plugin runs with\n`codegen: false`, so `src/relay/__generated__/` is not rebuilt on the fly:\nafter editing a `graphql` tag or the schema, run `bun run relay` (or keep\n`bun run relay:watch` running) to regenerate the artifacts, and commit them.\n\n**SSR ships no data yet.** `useLazyLoadQuery` fetches (and suspends) while\nrendering, and the server cannot serialize the fetched store for the client\nyet, so the catalog page wraps its query subtree in `ClientOnly`\n(`src/lib/ClientOnly/`): the server streams the fallback and the browser\nfetches after hydration.\n\n<% if (standalone) { -%>\n**Patched dependencies.** `patches/` carries three package patches applied via\n`patchedDependencies` in `package.json` (a bun feature — with another package\nmanager, apply the equivalent mechanism): `react-relay@21.0.1` needs a\ncjs-module-lexer export hint so named imports survive Node SSR,\n`relay-runtime@21.0.1` needs real runtime bindings for type-only names its\ncompiler artifacts import as values (`ConcreteRequest`, `ReaderFragment`,\n`FragmentRefs`), and `relay-runtime-network@0.1.0` ships a broken `imports`\nmap. The last patch is temporary until the fixed upstream release lands\n([advl/lit-relay#32](https://github.com/advl/lit-relay/pull/32)); drop it and\nits `patchedDependencies` entry once a fixed version is published.\n<% } else { -%>\n**Patched dependencies.** This app was scaffolded inside a bun workspace, so\ndependency patching is owned by the workspace root — bun resolves\n`patchedDependencies` paths from the root, which is why the scaffold emitted\nno app-local `patches/` directory or `patchedDependencies` block. The root's\n`patches/` must carry the `react-relay@21.0.1`, `relay-runtime@21.0.1` and\n`relay-runtime-network@0.1.0` patches (named imports under Node SSR, runtime\nbindings for type-only artifact imports, and a broken `imports` map,\nrespectively).\n<% } -%>\n\n**Not yet on npm.** `@canonical/storybook-addon-relay` and the fixed\n`relay-runtime-network` release have not been published yet, so a fresh\ninstall of this app will not fully resolve until they land on npm.\n<% } -%>\n",
-  "application/biome.json.ejs": "{\n  \"extends\": [\"@canonical/biome-config\"],\n  \"files\": {\n    \"includes\": [\"src\", \"*.json\", \"vite.config.ts\"<% if (relay) { %>, \"!src/relay/__generated__\"<% } %>]\n  }\n}\n",
-  "application/index.html.ejs": "<!doctype html>\n<html lang=\"en\">\n  <head>\n    <meta charset=\"UTF-8\" />\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" />\n    <meta name=\"description\" content=\"<%= name %> — a React application built with the Canonical design system, router, and SSR packages.\" />\n    <link rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"https://assets.ubuntu.com/v1/be7e4cc6-COF-favicon-32x32.png\">\n    <title><%= name %></title>\n  </head>\n  <body>\n    <div id=\"root\"></div>\n    <script type=\"module\" src=\"/src/client/entry.tsx\"></script>\n  </body>\n</html>\n",
-  "application/package.json.ejs": "{\n  \"name\": \"<%= name %>\",\n  \"private\": true,\n  \"version\": \"0.0.0\",\n  \"type\": \"module\",\n  \"license\": \"GPL-3.0-only\",\n  \"imports\": {\n    \"#lib/*\": \"./src/lib/*\",\n    \"#domains/*\": \"./src/domains/*\",\n<% if (relay) { -%>\n    \"#relay/*\": \"./src/relay/*\",\n<% } -%>\n    \"#styles/*\": \"./src/styles/*\"\n  },\n  \"scripts\": {\n    \"dev\": \"vite\",\n    \"dev:express\": \"node --import tsx src/server/server.express.ts\",\n    \"dev:bun\": \"bun src/server/server.bun.ts\",\n    \"preview\": \"bun run build:client && vite preview --outDir dist/client\",\n    \"preview:bun\": \"bun run build:client && bun run build:server && bun src/server/preview.bun.ts\",\n    \"preview:express\": \"bun run build:client && bun run build:server && node --import tsx src/server/preview.express.ts\",\n    \"build\": \"bun run build:client\",\n    \"build:all\": \"bun run build:client && bun run build:storybook\",\n    \"build:client\": \"vite build --ssrManifest --outDir dist/client\",\n    \"build:server\": \"vite build --mode server\",\n    \"build:storybook\": \"storybook build\",\n    \"check\": \"bun run check:biome && bun run check:ts\",\n    \"check:fix\": \"bun run check:biome:fix && bun run check:ts\",\n    \"check:biome\": \"biome check\",\n    \"check:biome:fix\": \"biome check --write\",\n    \"check:ts\": \"tsc --noEmit\",\n<% if (relay) { -%>\n    \"relay\": \"relay-compiler\",\n    \"relay:watch\": \"relay-compiler --watch\",\n<% } -%>\n    \"test\": \"vitest run\",\n    \"test:watch\": \"vitest\",\n    \"test:coverage\": \"vitest run --coverage\",\n    \"test:e2e\": \"vitest run --config vitest.e2e.config.ts\",\n    \"storybook\": \"storybook dev -p 6010 --no-open --host 0.0.0.0\"\n  },\n  \"dependencies\": {\n    \"@canonical/react-ds-global\": \"<%= pragmaVersion %>\",\n<% if (forms) { -%>\n    \"@canonical/react-ds-global-form\": \"<%= pragmaVersion %>\",\n<% } -%>\n    \"@canonical/react-head\": \"<%= pragmaVersion %>\",\n    \"@canonical/react-hooks\": \"<%= pragmaVersion %>\",\n    \"@canonical/react-ssr\": \"<%= pragmaVersion %>\",\n    \"@canonical/router-core\": \"<%= pragmaVersion %>\",\n    \"@canonical/router-react\": \"<%= pragmaVersion %>\",\n<% if (relay) { -%>\n    \"@canonical/storybook-addon-relay\": \"<%= pragmaVersion %>\",\n<% } -%>\n    \"@canonical/storybook-config\": \"<%= pragmaVersion %>\",\n    \"@canonical/styles\": \"<%= pragmaVersion %>\",\n    \"express\": \"^5.2.1\",\n<% if (relay) { -%>\n    \"graphql\": \"^16.11.0\",\n<% } -%>\n    \"react\": \"^19.2.4\",\n    \"react-dom\": \"^19.2.4\"<% if (relay) { %>,\n    \"react-relay\": \"^21.0.1\",\n    \"relay-runtime\": \"^21.0.1\",\n    \"relay-runtime-network\": \"^0.1.0\"<% } %>\n  },\n  \"devDependencies\": {\n    \"@biomejs/biome\": \"2.4.9\",\n    \"@canonical/biome-config\": \"<%= pragmaVersion %>\",\n    \"@canonical/typescript-config-react\": \"<%= pragmaVersion %>\",\n    \"@storybook/react-vite\": \"^10.3.1\",\n    \"@testing-library/jest-dom\": \"^6.9.1\",\n    \"@testing-library/react\": \"^16.3.2\",\n    \"@types/express\": \"^5.0.6\",\n    \"@types/node\": \"^24.12.0\",\n    \"@types/react\": \"^19.2.14\",\n    \"@types/react-dom\": \"^19.2.3\",\n<% if (relay) { -%>\n    \"@types/react-relay\": \"^18.2.1\",\n    \"@types/relay-runtime\": \"^20.1.1\",\n    \"@types/relay-test-utils\": \"^19.0.0\",\n<% } -%>\n    \"@vitejs/plugin-react\": \"^6.0.0\",\n    \"@vitest/coverage-v8\": \"^4.0.18\",\n    \"browserslist\": \"^4.28.1\",\n    \"bun-types\": \"^1.3.9\",\n    \"jsdom\": \"^28.1.0\",\n    \"lightningcss\": \"^1.32.0\",\n<% if (relay) { -%>\n    \"relay-compiler\": \"^21.0.1\",\n    \"relay-test-utils\": \"^21.0.1\",\n<% } -%>\n    \"storybook\": \"^10.3.1\",\n    \"tsx\": \"^4.19.0\",\n    \"typescript\": \"^5.9.3\",\n    \"vite\": \"^8.0.1\",\n<% if (relay) { -%>\n    \"vite-plugin-relay-lite\": \"^0.12.0\",\n<% } -%>\n    \"vitest\": \"^4.0.18\"\n  }<% if (relay && standalone) { %>,\n  \"patchedDependencies\": {\n    \"react-relay@21.0.1\": \"patches/react-relay@21.0.1.patch\",\n    \"relay-runtime@21.0.1\": \"patches/relay-runtime@21.0.1.patch\",\n    \"relay-runtime-network@0.1.0\": \"patches/relay-runtime-network@0.1.0.patch\"\n  }<% } %>\n}\n",
-  "application/src/client/entry.tsx.ejs": "import { HeadProvider } from \"@canonical/react-head\";\nimport { createBrowserRouter } from \"@canonical/router-core\";\nimport { Outlet, RouterProvider } from \"@canonical/router-react\";\nimport { hydrateRoot } from \"react-dom/client\";\n<% if (relay) { -%>\nimport { RelayEnvironmentProvider } from \"react-relay\";\nimport { createEnvironment } from \"#relay/environment.js\";\n<% } -%>\nimport { appRoutes, middleware, notFoundRoute } from \"../routes.js\";\nimport \"#styles/index.css\";\n\nconst router = createBrowserRouter(appRoutes, {\n  middleware: [...middleware],\n  notFound: notFoundRoute,\n});\n<% if (relay) { -%>\n\n// One Relay environment (network + normalized store) for the whole browser\n// session — module scope, so client-side navigations share the cache.\nconst relayEnvironment = createEnvironment();\n<% } -%>\n\nconst root = document.getElementById(\"root\");\nif (!root) {\n  throw new Error('Root element \"#root\" not found');\n}\n\n<% if (relay) { -%>\nhydrateRoot(\n  root,\n  <HeadProvider>\n    <RelayEnvironmentProvider environment={relayEnvironment}>\n      <RouterProvider router={router}>\n        <Outlet fallback={<p>Loading…</p>} />\n      </RouterProvider>\n    </RelayEnvironmentProvider>\n  </HeadProvider>,\n);\n<% } else { -%>\nhydrateRoot(\n  root,\n  <HeadProvider>\n    <RouterProvider router={router}>\n      <Outlet fallback={<p>Loading…</p>} />\n    </RouterProvider>\n  </HeadProvider>,\n);\n<% } -%>\n",
-  "application/src/lib/Navigation/Navigation.tsx.ejs": "import { Link } from \"@canonical/router-react\";\nimport type { ReactElement } from \"react\";\nimport ThemeSelector from \"../ThemeSelector/index.js\";\n\nexport default function Navigation(): ReactElement {\n  return (\n    <nav aria-label=\"Main\">\n      <Link to=\"home\">Home</Link>\n      <Link params={{ slug: \"router-core\" }} to=\"guide\">\n        Guide\n      </Link>\n<% if (relay) { -%>\n      <Link to=\"catalog\">Catalog</Link>\n<% } -%>\n<% if (forms) { -%>\n      <Link to=\"contact\">Contact</Link>\n<% } -%>\n      <Link search={{ auth: \"1\" }} to=\"account\">\n        Demo sign-in\n      </Link>\n      <ThemeSelector />\n    </nav>\n  );\n}\n",
-  "application/src/lib/index.ts.ejs": "<% if (relay) { -%>\nexport { default as ClientOnly } from \"./ClientOnly/index.js\";\n<% } -%>\nexport { ExampleComponent } from \"./ExampleComponent/index.js\";\nexport { default as LazyComponent } from \"./LazyComponent/index.js\";\nexport { default as Navigation } from \"./Navigation/index.js\";\nexport { default as ThemeSelector } from \"./ThemeSelector/index.js\";\n",
-  "application/src/routes.tsx.ejs": "import {\n  type AnyRoute,\n  group,\n  type NavigationContext,\n  type RouteMiddleware,\n  type RouteParamValues,\n  redirect,\n  route,\n  wrapper,\n} from \"@canonical/router-core\";\nimport type { ReactElement, ReactNode } from \"react\";\nimport accountRoutes from \"#domains/account/routes.js\";\n<% if (relay) { -%>\nimport catalogRoutes from \"#domains/catalog/routes.js\";\n<% } -%>\n<% if (forms) { -%>\nimport contactRoutes from \"#domains/contact/routes.js\";\n<% } -%>\nimport marketingRoutes from \"#domains/marketing/routes.js\";\nimport Navigation from \"#lib/Navigation/index.js\";\n\nconst protectedPaths = new Set([\"/account\"]);\n\nfunction hasDemoAuth(search: unknown): boolean {\n  const authValue = (search as Record<string, unknown>)?.auth;\n\n  return authValue === \"1\";\n}\n\nexport function getAuthRedirectHref(input: string | URL): string | null {\n  // Absolute URLs are used as-is; relative paths resolve against a dummy base.\n  const url =\n    input instanceof URL ? input : new URL(input, \"https://router.local\");\n\n  if (\n    !protectedPaths.has(url.pathname) ||\n    hasDemoAuth({ auth: url.searchParams.get(\"auth\") })\n  ) {\n    return null;\n  }\n\n  return `/login?from=${encodeURIComponent(url.pathname)}`;\n}\n\nexport function withAuth(loginPath: string): RouteMiddleware {\n  return ((currentRoute: AnyRoute) => {\n    if (!protectedPaths.has(currentRoute.url)) {\n      return currentRoute;\n    }\n\n    const currentPrefetch = currentRoute.prefetch;\n\n    return {\n      ...currentRoute,\n      prefetch: (\n        params: unknown,\n        search: unknown,\n        context: NavigationContext,\n      ) => {\n        if (!hasDemoAuth(search)) {\n          const from = currentRoute.render(\n            (params ?? {}) as RouteParamValues | Record<string, never>,\n          );\n\n          redirect(`${loginPath}?from=${encodeURIComponent(from)}`, 302);\n        }\n\n        if (currentPrefetch) {\n          return currentPrefetch(params, search, context);\n        }\n      },\n    };\n  }) as RouteMiddleware;\n}\n\nconst publicLayout = wrapper<ReactElement>({\n  id: \"public-layout\",\n  component: ({ children }: { children: ReactNode }) => (\n    <div className=\"subgrid app-shell\">\n      <header className=\"subgrid shell-header\">\n        <Navigation />\n      </header>\n      <main className=\"subgrid\">{children}</main>\n    </div>\n  ),\n});\n\nconst notFoundRoute = route({\n  url: \"/not-found\",\n  content: () => (\n    <section>\n      <h1>Page not found</h1>\n      <p>The page you are looking for does not exist.</p>\n    </section>\n  ),\n});\n\nconst [guide, home] = group(publicLayout, [\n  marketingRoutes.guide,\n  marketingRoutes.home,\n] as const);\n\nconst [account, login] = group(publicLayout, [\n  accountRoutes.account,\n  accountRoutes.login,\n] as const);\n\n<% if (forms) { -%>\nconst [contact] = group(publicLayout, [contactRoutes.contact] as const);\n\n<% } -%>\n<% if (relay) { -%>\nconst [catalog] = group(publicLayout, [catalogRoutes.catalog] as const);\n\n<% } -%>\nconst appRoutes = {\n  guide,\n  home,\n  account,\n  login,\n<% if (forms) { -%>\n  contact,\n<% } -%>\n<% if (relay) { -%>\n  catalog,\n<% } -%>\n} as const;\n\nexport type AppRoutes = typeof appRoutes;\n\ndeclare module \"@canonical/router-react\" {\n  interface RouterRegister {\n    routes: AppRoutes;\n  }\n}\n\nexport const middleware = [withAuth(\"/login\")] as const;\n\nexport { appRoutes, notFoundRoute };\n",
-  "application/src/server/entry.tsx.ejs": "import { HeadProvider } from \"@canonical/react-head\";\nimport type { ServerEntrypointProps } from \"@canonical/react-ssr/renderer\";\nimport { createStaticRouter } from \"@canonical/router-core\";\nimport { Outlet, RouterProvider } from \"@canonical/router-react\";\n<% if (relay) { -%>\nimport { RelayEnvironmentProvider } from \"react-relay\";\nimport { createEnvironment } from \"#relay/environment.js\";\n<% } -%>\nimport { appRoutes, middleware, notFoundRoute } from \"../routes.js\";\nimport \"#styles/app.css\";\n\ninterface InitialData extends Record<string, unknown> {\n  readonly url?: string;\n  /** Colour-scheme preference resolved from the request cookie, if any. */\n  readonly theme?: \"light\" | \"dark\";\n}\n\nexport default function EntryServer(props: ServerEntrypointProps<InitialData>) {\n  const initialData = props.initialData ?? {};\n  const url = initialData.url ?? \"/\";\n  const router = createStaticRouter(appRoutes, url, {\n    middleware: [...middleware],\n    notFound: notFoundRoute,\n  });\n<% if (relay) { -%>\n\n  // A fresh Relay environment per server render, so no store state leaks\n  // between requests. Nothing fetches through it yet: components that issue\n  // queries are wrapped in `ClientOnly` (see CatalogPage) until data\n  // serialization/hydration is supported; the provider is here so any\n  // component touching Relay context renders without branching on runtime.\n  const relayEnvironment = createEnvironment();\n<% } -%>\n\n  // Paint the cookie-resolved theme on <html> for a flash-free first render —\n  // the same element `usePreferredTheme` toggles on the client, and one React\n  // does not hydrate (only `#root` is), so there is no mismatch to reconcile.\n<% if (relay) { -%>\n  return (\n    <html lang={props.lang} className={initialData.theme}>\n      <head>\n        {props.otherHeadElements}\n        {props.scriptElements}\n        {props.linkElements}\n      </head>\n      <body>\n        <div id=\"root\">\n          <HeadProvider>\n            <RelayEnvironmentProvider environment={relayEnvironment}>\n              <RouterProvider router={router}>\n                <Outlet fallback={<p>Loading…</p>} />\n              </RouterProvider>\n            </RelayEnvironmentProvider>\n          </HeadProvider>\n        </div>\n      </body>\n    </html>\n  );\n<% } else { -%>\n  return (\n    <html lang={props.lang} className={initialData.theme}>\n      <head>\n        {props.otherHeadElements}\n        {props.scriptElements}\n        {props.linkElements}\n      </head>\n      <body>\n        <div id=\"root\">\n          <HeadProvider>\n            <RouterProvider router={router}>\n              <Outlet fallback={<p>Loading…</p>} />\n            </RouterProvider>\n          </HeadProvider>\n        </div>\n      </body>\n    </html>\n  );\n<% } -%>\n}\n\nexport type { InitialData };\n",
-  "application/src/sitemap/getSitemapItems.ts.ejs": "import type { SitemapItem } from \"@canonical/react-ssr/renderer\";\n\n/**\n * Returns sitemap entries for all known routes.\n *\n * Update this list as you add domains and routes. For dynamic content\n * (blog posts, product pages), fetch entries from your data source.\n *\n * @example\n * const posts = await fetchPosts();\n * return [\n *   ...staticEntries,\n *   ...posts.map((post) => ({\n *     loc: `/blog/${post.slug}`,\n *     lastmod: post.updatedAt,\n *     changefreq: \"weekly\" as const,\n *     priority: 0.7,\n *   })),\n * ];\n */\nexport default async function getSitemapItems(): Promise<SitemapItem[]> {\n  return [\n    { loc: \"/\", changefreq: \"weekly\", priority: 1.0 },\n    { loc: \"/guides/router-core\", changefreq: \"monthly\", priority: 0.8 },\n<% if (relay) { -%>\n    { loc: \"/catalog\", changefreq: \"weekly\", priority: 0.7 },\n<% } -%>\n<% if (forms) { -%>\n    { loc: \"/contact\", changefreq: \"monthly\", priority: 0.7 },\n<% } -%>\n    { loc: \"/account\", changefreq: \"monthly\", priority: 0.5 },\n    { loc: \"/login\", changefreq: \"yearly\", priority: 0.3 },\n  ];\n}\n",
-  "application/src/styles/index.css.ejs": "@import url(\"@canonical/styles\");\n<% if (forms) { -%>\n@import url(\"@canonical/react-ds-global-form/dist/esm/index.css\");\n<% } -%>\n@import url(\"./app.css\");\n",
-  "application/tsconfig.json.ejs": "{\n  \"extends\": \"@canonical/typescript-config-react\",\n  \"compilerOptions\": {\n    \"baseUrl\": \"src\",\n    \"skipLibCheck\": true,\n    \"types\": [\n      \"bun-types\",\n      \"node\",\n      \"react\",\n      \"react-dom\",\n      \"vitest/globals\",\n      \"@testing-library/jest-dom\"\n    ],\n    \"noEmit\": true,\n    \"paths\": {\n      \"#lib/*\": [\"./lib/*\"],\n      \"#domains/*\": [\"./domains/*\"],\n<% if (relay) { -%>\n      \"#relay/*\": [\"./relay/*\"],\n<% } -%>\n      \"#styles/*\": [\"./styles/*\"]\n    }\n  },\n  \"include\": [\n    \"src/**/*.ts\",\n    \"src/**/*.tsx\",\n    \".storybook/*.ts\",\n    \".storybook/*.tsx\",\n    \"vite.config.ts\",\n    \"vitest.setup.ts\",\n    \"vitest.config.ts\",\n    \"vitest.e2e.config.ts\",\n    \"test/**/*.ts\"\n  ]\n}\n",
-  "application/vite.config.ts.ejs": "import react from \"@vitejs/plugin-react\";\nimport browserslist from \"browserslist\";\nimport { browserslistToTargets } from \"lightningcss\";\nimport { defineConfig } from \"vite\";\n<% if (relay) { -%>\nimport relay from \"vite-plugin-relay-lite\";\n<% } -%>\n\n// Path aliases (#lib, #domains, #styles) are declared as Node subpath imports\n// in package.json \"imports\" and resolved natively by Vite — no resolver plugin.\nconst PORT = Number(process.env.PORT) || undefined;\n\n// `build:server` runs `vite build --mode server` to compile the two server\n// renderers in a single pass. Each is a separate, individually-instantiated\n// Lego brick, so they are named Rollup inputs — the build emits\n// `dist/server/renderer.js` (the JSX app) + `dist/server/sitemap.js` (the XML\n// sitemap), which the preview servers import directly. Every other command\n// (`dev`, `build:client`, `preview`) uses the default mode and the SPA client\n// build (`--ssrManifest --outDir dist/client`).\nexport default defineConfig(({ mode }) => ({\n<% if (relay) { -%>\n  // Relay's `graphql\\`...\\`` tags must be rewritten into imports of the\n  // compiler-generated artifacts. `@vitejs/plugin-react` v6 is OXC-based (no\n  // Babel), so the classic `babel-plugin-relay` route would need the\n  // `@rolldown/plugin-babel` escape hatch; `vite-plugin-relay-lite` does the\n  // same rewrite with its own parser and no Babel, and works on Vite 8 /\n  // rolldown despite its peer range stopping at Vite 7 (bun installs it with\n  // only a peer-version warning). Footgun: its tag scanner matches the word\n  // \"graphql\" followed by a backtick even inside comments, so never\n  // backtick-quote a graphql file name in a comment. `codegen: false` because\n  // artifacts are committed and regenerated explicitly via the `relay` /\n  // `relay:watch` scripts.\n  plugins: [relay({ codegen: false }), react()],\n<% } else { -%>\n  plugins: [react()],\n<% } -%>\n  // Honour the PORT env var for `dev` (SPA) and `preview` so all server scripts\n  // — including the SSR ones, which already read PORT — respond to it uniformly.\n  server: { port: PORT },\n  preview: { port: PORT },\n  // CSS delivery is the app's job, not the libraries': @canonical/* packages\n  // deliberately ship modern, uncompiled per-component CSS and take no stance\n  // on browser support. Lightning CSS (already bundled with Vite 8) compiles\n  // that CSS down to this app's declared browser floor — the browserslist\n  // query in .browserslistrc, which is the one knob to turn when support\n  // requirements change. Not everything can be downleveled: math functions\n  // like `mod()` (used by the typography baseline grid) have no polyfillable\n  // form, so that feature's effective Chromium ≥ 125 floor is unchanged.\n  css: {\n    transformer: \"lightningcss\",\n    lightningcss: { targets: browserslistToTargets(browserslist()) },\n  },\n  build: {\n    // Minify CSS with Lightning CSS too (instead of the esbuild default), so\n    // a single tool owns both downleveling and minification — in the client\n    // build and the server build alike.\n    cssMinify: \"lightningcss\",\n    ...(mode === \"server\"\n      ? {\n          ssr: true,\n          outDir: \"dist/server\",\n          rollupOptions: {\n            input: {\n              renderer: \"src/server/renderer.tsx\",\n              sitemap: \"src/sitemap/renderer.ts\",\n            },\n          },\n        }\n      : undefined),\n  },\n  ssr: {\n    // Bundle @canonical/* for SSR rather than externalising them, for two\n    // reasons: (1) some packages declare only a \"module\" entry (no\n    // \"main\"/\"exports\"), which Vite's SSR (Node-style) resolver ignores —\n    // externalising them fails with ERR_RESOLVE_PACKAGE_ENTRY_FAIL; (2) their\n    // built output imports CSS as a side effect (e.g. `import \"./x.css\"`),\n    // which Node cannot load (ERR_UNKNOWN_FILE_EXTENSION) but Vite's SSR\n    // transform no-ops. The regex covers the whole scope so any current or\n    // future @canonical dependency is handled.\n<% if (relay) { -%>\n    //\n    // The Relay packages (react-relay, relay-runtime, relay-runtime-network,\n    // graphql) stay externalised like react itself. Three packaging defects\n    // made that possible and are fixed via `patchedDependencies` (app-local\n    // patches/ for a standalone app; the workspace root's patches/ when the\n    // app lives inside a bun workspace): react-relay's CJS exports are member\n    // expressions cjs-module-lexer cannot detect (breaking named imports\n    // under Node SSR and Vite's dev module runner), relay-runtime lacks\n    // runtime bindings for type-only names its compiler artifacts import as\n    // values (ConcreteRequest, ReaderFragment, FragmentRefs), and\n    // relay-runtime-network@0.1.0 ships an `imports` map pointing at its\n    // unpublished src/ directory.\n<% } -%>\n    noExternal: [/^@canonical\\//],\n  },\n}));\n",
-  "application/vitest.setup.ts.ejs": "import * as matchers from \"@testing-library/jest-dom/matchers\";\nimport { cleanup } from \"@testing-library/react\";\n<% if (relay) { -%>\nimport { afterEach, expect, vi } from \"vitest\";\n<% } else { -%>\nimport { afterEach, expect } from \"vitest\";\n<% } -%>\n\nexpect.extend(matchers as unknown as Parameters<typeof expect.extend>[0]);\n<% if (relay) { -%>\n\n// relay-test-utils' `createMockEnvironment` wraps environment methods in\n// `jest.fn` mocks whenever NODE_ENV === \"test\", reaching for a global `jest`\n// object. Vitest sets NODE_ENV=test but exposes `vi` instead, so alias it —\n// `vi.fn` is API-compatible with the `jest.fn` surface relay-test-utils uses\n// (`.mock`, `.mockClear`).\n(globalThis as { jest?: typeof vi }).jest = vi;\n<% } -%>\n\nafterEach(() => {\n  cleanup();\n});\n",
   "component/lit/component.ts.ejs": "import { html, LitElement } from \"lit\";\nimport { customElement } from \"lit/decorators.js\";\n<% if (withStyles) { -%>\nimport styles from \"./styles.css\";\n<% } -%>\nimport type { <%= name %>Props } from \"./types.js\";\n\nconst componentCssClassName = \"ds <%= kebabName %>\";\n\n/**\n * <%= name %> web component.\n *\n * @implements ds:global.component.<%= kebabName %>\n */\n@customElement(\"ds-<%= kebabName %>\")\nexport default class <%= name %> extends LitElement implements <%= name %>Props {\n<% if (withStyles) { -%>\n  static styles = styles;\n\n<% } -%>\n  render() {\n    return html`\n      <div class=\"${componentCssClassName}\">\n        <slot></slot>\n      </div>\n    `;\n  }\n}\n",
   "component/lit/index.ts.ejs": "export { default as <%= name %> } from \"./<%= name %>.js\";\nexport type { <%= name %>Props } from \"./types.js\";\n",
   "component/lit/stories.ts.ejs": "import type { Meta, StoryObj } from \"@storybook/web-components-vite\";\nimport { html } from \"lit\";\n\nimport \"./<%= name %>.js\";\nimport type <%= name %> from \"./<%= name %>.js\";\n\nconst meta = {\n  title: \"Web Components/<%= name %>\",\n  tags: [\"autodocs\"],\n} satisfies Meta<<%= name %>>;\n\nexport default meta;\ntype Story = StoryObj<<%= name %>>;\n\nexport const Default: Story = {\n  render: () => html`<ds-<%= kebabName %>>Hello, <%= name %>!</ds-<%= kebabName %>>`,\n};\n",
@@ -39,15 +25,4 @@ export const TEMPLATES: Record<string, string> = {
   "component/svelte/stories.ts.ejs": "import type { Meta, StoryObj } from \"@storybook/svelte\";\nimport <%= name %> from \"./<%= name %>.svelte\";\n\nconst meta: Meta<typeof <%= name %>> = {\n\ttitle: \"Components/<%= name %>\",\n\tcomponent: <%= name %>,\n\ttags: [\"autodocs\"],\n};\n\nexport default meta;\ntype Story = StoryObj<typeof <%= name %>>;\n\nexport const Default: Story = {};\n\nexport const WithCustomClass: Story = {\n\targs: {\n\t\tclass: \"custom-class\",\n\t},\n};\n",
   "component/svelte/test.ts.ejs": "import type { Locator } from \"@vitest/browser/context\";\nimport { createRawSnippet } from \"svelte\";\nimport type { ComponentProps } from \"svelte\";\nimport { describe, expect, it } from \"vitest\";\nimport { render } from \"vitest-browser-svelte\";\nimport type { RenderResult } from \"vitest-browser-svelte\";\nimport Component from \"./<%= name %>.svelte\";\n\ndescribe(\"<%= name %> component\", () => {\n\tconst baseProps = {\n\t\tchildren: createRawSnippet(() => ({\n\t\t\trender: () => `<span><%= name %></span>`,\n\t\t})),\n\t} satisfies ComponentProps<typeof Component>;\n\n\tit(\"renders\", async () => {\n\t\tconst page = render(Component, { ...baseProps });\n\t\tawait expect.element(componentLocator(page)).toBeInTheDocument();\n\t\tawait expect.element(page.getByText(\"<%= name %>\")).toBeVisible();\n\t});\n\n\tdescribe(\"attributes\", () => {\n\t\tit.each([\n\t\t\t[\"id\", \"test-id\"],\n\t\t\t[\"aria-label\", \"test-aria-label\"],\n\t\t])(\"applies %s\", async (attribute, expected) => {\n\t\t\tconst page = render(Component, { ...baseProps, [attribute]: expected });\n\t\t\tawait expect\n\t\t\t\t.element(componentLocator(page))\n\t\t\t\t.toHaveAttribute(attribute, expected);\n\t\t});\n\n\t\tit(\"applies classes\", async () => {\n\t\t\tconst page = render(Component, { ...baseProps, class: \"test-class\" });\n\t\t\tawait expect.element(componentLocator(page)).toHaveClass(\"test-class\");\n<% if (withStyles) { _%>\n\t\t\tawait expect.element(componentLocator(page)).toHaveClass(\"ds\");\n\t\t\tawait expect\n\t\t\t\t.element(componentLocator(page))\n\t\t\t\t.toHaveClass(\"<%= kebabName %>\");<% } %>\n\t\t});\n\n\t\tit(\"applies style\", async () => {\n\t\t\tconst page = render(Component, {\n\t\t\t\t...baseProps,\n\t\t\t\tstyle: \"color: orange;\",\n\t\t\t});\n\t\t\tawait expect\n\t\t\t\t.element(componentLocator(page))\n\t\t\t\t.toHaveStyle({ color: \"orange\" });\n\t\t});\n\t});\n});\n\n// Note: Prefer role/semantics-oriented ways of selecting elements (e.g., by role, label, etc.) not only for component roots but for all elements to enhance accessibility and maintainability.\n// To select the component's root element, use one of the available [Locators](https://vitest.dev/guide/browser/locators.html).\nfunction componentLocator(page: RenderResult<typeof Component>): Locator {\n\t// 1. SEMANTIC ROLES (PREFERRED) - These the most closely resemble how assistive technologies interact with your component\n\t// return page.getByRole(\"link\", { name: \"Learn more\" });\n\n\t// 2. LABELS - To test the association between labels and form controls\n\t// return page.getByLabel(\"Email address\");\n\n\t// 3. PLACEHOLDER TEXT - Useful for input fields with placeholders\n\t// return page.getByPlaceholder(\"Enter your email\");\n\n\t// 4. TEXT CONTENT - Good for testing the presence of unique texts and selecting non-interactive elements\n\t// return page.getByText(\"<%= name %>\");\n\n\t// 5. ALT TEXT - For images and visual elements\n\t// return page.getByAltText(\"Company logo\");\n\n\t// 6. TITLE ATTRIBUTE - For elements with title tooltips\n\t// return page.getByTitle(\"Close dialog\");\n\n\t// 7. TEST IDS (LAST RESORT) - When semantic options aren't available\n\t// return page.getByTestId(\"<%= kebabName %>\");\n}\n",
   "component/svelte/types.ts.ejs": "import type { Snippet } from \"svelte\";\nimport type { SvelteHTMLElements } from \"svelte/elements\";\n\n/*\n\tFor components that render specific HTML elements with extended prop sets,\n\tmake sure to change `\"div\"` to the appropriate HTML element type.\n*/\ntype BaseProps = SvelteHTMLElements[\"div\"];\n\nexport interface <%= name %>Props extends BaseProps {\n\t/** Content to render inside the component */\n\tchildren?: Snippet;\n\t// Define additional props specific to <%= name %> here\n}\n\n/*\n\t...or consider using appropriate interfaces directly exported from `svelte/elements`.\n\n\tFor example:\n\t- `HTMLButtonAttributes` (provides `disabled`, `type`, etc.)\n\t- `HTMLAnchorAttributes` (provides `href`, `target`, etc.)\n\t- `HTMLInputAttributes` (provides `type`, `checked`, `value`, etc.)\n\t- `HTMLFormAttributes` (provides `action`, `method`, etc.)\n\n\t```typescript\n\timport type { HTMLButtonAttributes } from \"svelte/elements\";\n\n\texport interface MyButtonProps extends HTMLButtonAttributes {\n\t\t// Your custom props here\n\t}\n\t```\n\n\tSee Svelte documentation on typing wrapper components:\n\thttps://svelte.dev/docs/svelte/typescript#Typing-wrapper-components\n*/\n",
-  "package/PULL_REQUEST_TEMPLATE.md.ejs": "## Summary\n\n[What this PR does and why]\n\n## QA\n\n- [Add QA steps]\n\n### Checklist\n\n- [ ] PR title follows [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format\n- [ ] Code follows the [code standards](https://github.com/canonical/web-code-standards)\n- [ ] `check`, `test` pass locally\n",
-  "package/README.md.ejs": "# <%= name %>\n\n<%= description || 'TODO: Add description' %>\n\n## Installation\n\n```bash\nbun add <%= name %>\n```\n\n## Usage\n\n```typescript\nimport { } from \"<%= name %>\";\n```\n\n## Development\n\n```bash\n# Run checks\nbun run check\n\n# Run tests\nbun run test\n```\n\n## License\n\n<%= license %>\n",
-  "package/biome.json.ejs": "{\n  \"extends\": [\"@canonical/biome-config\"],\n  \"files\": {\n    \"includes\": [\"src\", \"*.json\"]\n  }\n}\n",
-  "package/cli.ts.ejs": "#!/usr/bin/env bun\n/**\n * <%= name %> CLI\n *\n * <%= description || 'TODO: Add description' %>\n */\n\nconsole.log(\"Hello from <%= shortName %>!\");\n",
-  "package/index.css.ejs": "/**\n * <%= name %>\n *\n * <%= description || 'TODO: Add description' %>\n */\n",
-  "package/index.ts.ejs": "/**\n * <%= name %>\n *\n * <%= description || 'TODO: Add description' %>\n */\n\nexport {};\n",
-  "package/package.json.ejs": "{\n  \"name\": \"<%= name %>\",\n  \"description\": \"<%= description %>\",\n  \"version\": \"<%= version %>\",\n  \"type\": \"module\",\n<% if (type === 'tool-ts') { -%>\n  \"module\": \"src/index.ts\",\n  \"types\": \"src/index.ts\",\n<% } else if (type === 'css') { -%>\n  \"module\": \"src/index.css\",\n<% } else { -%>\n  \"module\": \"dist/esm/index.js\",\n  \"types\": \"dist/types/index.d.ts\",\n<% } -%>\n<% if (withCli && type !== 'css') { -%>\n  \"bin\": {\n    \"<%= shortName %>\": \"src/cli.ts\"\n  },\n<% } -%>\n  \"files\": [\n<% if (type === 'tool-ts' || type === 'css') { -%>\n    \"src\"\n<% } else { -%>\n    \"dist\"\n<% } -%>\n  ],\n  \"author\": {\n    \"email\": \"webteam@canonical.com\",\n    \"name\": \"Canonical Webteam\"\n  },\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"https://github.com/canonical/pragma\"\n  },\n  \"license\": \"<%= license %>\",\n  \"bugs\": {\n    \"url\": \"https://github.com/canonical/pragma/issues\"\n  },\n  \"homepage\": \"https://github.com/canonical/pragma#readme\",\n  \"scripts\": {\n<% if (type === 'tool-ts' || type === 'css') { -%>\n    \"build\": \"echo 'No build needed'\",\n<% } else { -%>\n    \"build\": \"tsc -p tsconfig.build.json\",\n<% } -%>\n<% if (withStorybook) { -%>\n    \"build:all\": \"bun run build && bun run build:storybook\",\n    \"build:storybook\": \"storybook build\",\n<% } else { -%>\n    \"build:all\": \"bun run build\",\n<% } -%>\n<% if (type === 'css') { -%>\n    \"check\": \"bun run check:biome && bun run check:webarchitect\",\n    \"check:fix\": \"bun run check:biome:fix\",\n<% } else { -%>\n    \"check\": \"bun run check:biome && bun run check:ts && bun run check:webarchitect\",\n    \"check:fix\": \"bun run check:biome:fix && bun run check:ts\",\n<% } -%>\n    \"check:biome\": \"biome check\",\n    \"check:biome:fix\": \"biome check --write\",\n<% if (type !== 'css') { -%>\n    \"check:ts\": \"tsc --noEmit\",\n<% } -%>\n    \"check:webarchitect\": \"webarchitect <%= ruleset %>\",\n<% if (withStorybook) { -%>\n    \"storybook\": \"storybook dev -p 6006 --no-open --host 0.0.0.0\",\n<% } -%>\n<% if (type === 'css') { -%>\n    \"test\": \"echo 'No tests for CSS package'\"\n<% } else { -%>\n    \"test\": \"vitest run\"\n<% } -%>\n  },\n<% if (type !== 'css') { -%>\n  \"devDependencies\": {\n    \"@biomejs/biome\": \"2.4.6\",\n    \"@canonical/biome-config\": \"^<%= monorepoVersion || '0.1.0' %>\",\n<% if (withReact) { -%>\n    \"@canonical/typescript-config-react\": \"^<%= monorepoVersion || '0.1.0' %>\",\n<% } else { -%>\n    \"@canonical/typescript-config\": \"^<%= monorepoVersion || '0.1.0' %>\",\n<% } -%>\n<% if (withStorybook) { -%>\n    \"@chromatic-com/storybook\": \"^5.0.0\",\n<% } -%>\n<% if (withReact) { -%>\n    \"@types/react\": \"^19.0.0\",\n    \"@types/react-dom\": \"^19.0.0\",\n<% } -%>\n    \"bun-types\": \"^1.0.0\",\n<% if (withStorybook) { -%>\n    \"storybook\": \"^10.1.11\",\n<% } -%>\n    \"typescript\": \"^5.9.3\",\n    \"vitest\": \"^3.2.4\"\n  },\n  \"dependencies\": {\n<% if (withStorybook) { -%>\n    \"@canonical/storybook-config\": \"^<%= monorepoVersion || '0.1.0' %>\",\n<% } -%>\n<% if (withReact) { -%>\n    \"react\": \"^19.0.0\",\n    \"react-dom\": \"^19.0.0\"\n<% } -%>\n  }\n<% } else { -%>\n  \"devDependencies\": {\n    \"@biomejs/biome\": \"2.4.6\",\n    \"@canonical/biome-config\": \"^<%= monorepoVersion || '0.1.0' %>\"\n  }\n<% } -%>\n}\n",
-  "package/storybook-main.ts.ejs": "import { createConfig } from \"@canonical/storybook-config\";\n\nexport default createConfig(\"react\", {\n  staticDirs: [\"../src/assets\", \"../public\"],\n});\n",
-  "package/storybook-preview.ts.ejs": "import { withThemeByClassName } from \"@storybook/addon-themes\";\nimport type { Preview, ReactRenderer } from \"@storybook/react-vite\";\n\nimport \"index.css\";\nimport \"@canonical/styles-debug/baseline-grid\";\n\nconst preview: Preview = {\n  tags: [\"autodocs\"],\n  decorators: [\n    withThemeByClassName<ReactRenderer>({\n      themes: {\n        light: \"is-light\",\n        dark: \"dark\",\n        paper: \"is-paper\",\n      },\n      defaultTheme: \"light\",\n    }),\n  ],\n  parameters: {\n    docs: {\n      codePanel: true,\n    },\n  },\n};\n\nexport default preview;\n",
-  "package/tsconfig-react.json.ejs": "{\n  \"extends\": \"@canonical/typescript-config-react\",\n  \"compilerOptions\": {\n    \"baseUrl\": \"src\",\n    \"types\": [\"bun-types\"]\n  },\n  \"include\": [\"src/**/*.ts\", \"src/**/*.tsx\"]\n}\n",
-  "package/tsconfig.json.ejs": "{\n  \"extends\": \"@canonical/typescript-config\",\n  \"compilerOptions\": {\n    \"baseUrl\": \"src\",\n    \"types\": [\"bun-types\"]\n  },\n  \"include\": [\"src/**/*.ts\"]\n}\n",
 };

package/src/capabilities/create/types.ts

@@ -1,8 +1,12 @@
+import type { CREATE_GENERATORS } from "./constants.js";
+
 /**
- * Create-capability types with NO summon-core / generator import, so a module
- * that only needs `CreateKind` (e.g. `create.verb`) does not drag
- * `pickGenerator` — and its heavy generator imports — into the static graph.
+ * The `create` nouns — one per declared generator binding (path capped at two
+ * segments). Derived from {@link CREATE_GENERATORS} so the union cannot drift
+ * from the bindings.
+ *
+ * Deliberately free of any summon-core / generator import, so a module that only
+ * needs this type (e.g. `create.verb`) does not drag `pickGenerator` — and its
+ * heavy generator imports — into the static graph.
  */
-
-/** The three `create` nouns (path capped at two segments). */
-export type CreateKind = "component" | "package" | "application";
+export type CreateKind = keyof typeof CREATE_GENERATORS;

package/src/capabilities/{standard/parity.test.ts → distribution.parity.test.ts}

@@ -1,6 +1,6 @@
 /**
- * Standard-noun semantic parity (PROTECTED) — the bundled `standard` pack over a
- * code-standards fixture graph.
+ * Standard-noun semantic parity (PROTECTED) — the `standard` story
+ * `pragma.conf.ts` declares, over a code-standards fixture graph.
  *
  * The hand-written standard domain is gone, so parity is asserted directly
  * against the graph: every standard is reachable through list/lookup/categories/
@@ -10,16 +10,22 @@
  */
 
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import { compilePack } from "../../kernel/packs/compile.js";
-import type { LookupOutput } from "../../kernel/packs/resolveEntity.js";
-import { parsePackDefinition } from "../../kernel/packs/schema.js";
-import type { PackRow } from "../../kernel/packs/types.js";
-import { verbKey } from "../../kernel/packs/uniqueness.js";
-import { DEFAULT_PREFIX_MAP } from "../../kernel/render/prefixes.js";
-import type { PragmaRuntime } from "../../kernel/runtime/types.js";
-import type { VerbSpec } from "../../kernel/spec/types.js";
-import { buildFixtureRuntime } from "../../testing/helpers/packRuntime.js";
-import { standardPack } from "./pack.js";
+import { compilePack } from "../kernel/packs/compile.js";
+import type { LookupOutput } from "../kernel/packs/resolveEntity.js";
+import { parsePackDefinition } from "../kernel/packs/schema.js";
+import type { PackRow } from "../kernel/packs/types.js";
+import { distributionSource } from "../kernel/packs/types.js";
+import { verbKey } from "../kernel/packs/uniqueness.js";
+import { DEFAULT_PREFIX_MAP } from "../kernel/render/prefixes.js";
+import type { PragmaRuntime } from "../kernel/runtime/types.js";
+import type { VerbSpec } from "../kernel/spec/types.js";
+import { buildFixtureRuntime } from "../testing/helpers/packRuntime.js";
+import { declaredStories } from "./distribution.js";
+
+const standardPack = declaredStories.get("standard");
+if (!standardPack) {
+  throw new Error('pragma.conf.ts declares no story for "standard"');
+}
 
 const CS = "http://pragma.canonical.com/codestandards#";
 const PREFIXES = {
@@ -72,7 +78,11 @@ cs:code.function.purity a cs:CodeStandard ;
 `;
 
 const verbs = () =>
-  compilePack(standardPack, "bundled:standard", DEFAULT_PREFIX_MAP);
+  compilePack(
+    standardPack,
+    distributionSource("pragma.conf.ts"),
+    DEFAULT_PREFIX_MAP,
+  );
 const verb = (label: string) =>
   verbs().find((v) => verbKey(v.path) === `standard ${label}`) as VerbSpec;
 
@@ -98,7 +108,7 @@ async function lookupAt(
   return out.results.at(0) as Record<string, unknown>;
 }
 
-describe("standard pack definition (PROTECTED)", () => {
+describe("standard story definition (PROTECTED)", () => {
   it("round-trips as declarative JSON and validates", () => {
     expect(
       parsePackDefinition(JSON.parse(JSON.stringify(standardPack)), "t"),

package/src/capabilities/distribution.test.ts

@@ -0,0 +1,120 @@
+/**
+ * The distribution's own declared read stories (PROTECTED).
+ *
+ * `pragma.conf.ts` is hand-authored data that the TypeScript compiler checks
+ * against `PackDefinition`; `kernel/packs/schema.ts` is an independently written
+ * zod grammar that every config- and package-declared story must pass. Nothing
+ * forced the two to agree until the distribution started coming through the same
+ * door — and the first thing that comparison found was `sample.fixedCount`,
+ * documented and used by three of these five stories yet missing from the
+ * `.strict()` sample schema, which made any third-party story declaring it die
+ * with a fatal CONFIG_ERROR. Round-tripping ALL five is what keeps that shut.
+ */
+
+import { describe, expect, it } from "vitest";
+import { compilePack } from "../kernel/packs/compile.js";
+import { parsePackDefinition } from "../kernel/packs/schema.js";
+import { DEFAULT_PREFIX_MAP } from "../kernel/render/prefixes.js";
+import type { VerbSpec } from "../kernel/spec/types.js";
+import { VOCABULARY } from "../kernel/vocabulary.js";
+import { declaredStories, storyModules } from "./distribution.js";
+import { capabilities } from "./index.js";
+
+/** A verb's DECLARED shape — everything but the closures a compile mints fresh. */
+function declaredShape(verb: VerbSpec): Record<string, unknown> {
+  return {
+    path: verb.path.join(" "),
+    summary: verb.summary,
+    doc: verb.doc,
+    params: verb.params,
+    capability: verb.capability,
+    examples: verb.examples,
+  };
+}
+
+describe("the distribution's declared stories (PROTECTED)", () => {
+  it("declares exactly the five domain nouns", () => {
+    // Every domain noun is now nothing BUT its story (L-OPEN-9), so a renamed
+    // or dropped noun deletes a whole command rather than shrinking one — it
+    // must fail HERE.
+    expect([...declaredStories.keys()].sort()).toEqual([
+      "block",
+      "modifier",
+      "standard",
+      "tier",
+      "token",
+    ]);
+  });
+
+  it.each([
+    ...declaredStories.keys(),
+  ])("the %s story validates against the pack grammar, unchanged", (noun) => {
+    const story = declaredStories.get(noun);
+    expect(
+      parsePackDefinition(JSON.parse(JSON.stringify(story)), "pragma.conf.ts"),
+    ).toEqual(story);
+  });
+
+  it("every declared noun reaches the registry as an overridable module", () => {
+    for (const noun of declaredStories.keys()) {
+      const module = capabilities.find((entry) => entry.name === noun);
+      expect(module, `no capability module for "${noun}"`).toBeDefined();
+      // `story: true` is what lets a project's own story REPLACE it at
+      // dispatch; without it the noun would be treated as authored CLI.
+      expect(module?.story).toBe(true);
+      expect(module?.verbs.length).toBeGreaterThan(0);
+    }
+  });
+
+  it("ZERO hand-written data commands: a registered noun IS its compiled story", () => {
+    // The machine form of L-OPEN-9's end state — "a fork defines its entire
+    // read surface in pragma.conf.ts". Prose can go stale; this cannot. Every
+    // declared noun's REGISTERED module (what the CLI, the MCP server and the
+    // generated reference all project) must be verb-for-verb what recompiling
+    // its story alone produces. Re-introducing a composite — an authored module
+    // that prepends or appends a hand-written verb beside the story, which is
+    // exactly how `block`, `token` and `tier` used to be built — fails here,
+    // whatever the docblocks say.
+    for (const [noun, story] of declaredStories) {
+      const registered = capabilities.find((entry) => entry.name === noun);
+      const compiled = compilePack(story, "pragma.conf.ts", DEFAULT_PREFIX_MAP);
+      // Two halves, because a spec carries closures a fresh compile cannot
+      // reproduce by identity. (1) SHAPE: recompiling the story alone must
+      // yield the same verbs, declared the same way — an extra verb or an extra
+      // flag beside the story fails here.
+      expect(
+        registered?.verbs.map(declaredShape),
+        `"${noun}" registers verbs its story does not declare`,
+      ).toEqual(compiled.map(declaredShape));
+      // (2) IDENTITY: each registered verb must BE the compiled story's verb
+      // object, not a look-alike. A composite module — the `[...story.verbs,
+      // handWrittenVerb]` shape `block`, `token` and `tier` used to be built
+      // with — constructs new objects, so it cannot pass this even if its
+      // shapes happen to match.
+      const fromStory = storyModules.get(noun)?.verbs ?? [];
+      expect(registered?.verbs.length).toBe(fromStory.length);
+      registered?.verbs.forEach((verb, index) => {
+        expect(verb, `"${noun}" verb ${index} is not the story's`).toBe(
+          fromStory[index],
+        );
+      });
+    }
+  });
+
+  it("the tier story is internally coherent, and coherent with the vocabulary", () => {
+    // Both tier verbs are declared data now (L-OPEN-9), so the noun can no
+    // longer disagree with ITSELF in code — but the list query spells its
+    // class and property literally (`pragma.conf.ts` is inert data and imports
+    // nothing) while the lookup declares them as fields, and the vocabulary
+    // declares the addressing property once more for the index builder. This
+    // holds all three to one class and one property, so a candidate that
+    // completes still resolves and the index projects the names the lookup
+    // matches.
+    const story = declaredStories.get("tier");
+    const query = story?.list?.query ?? "";
+    expect(story?.lookup?.type).toBe("ds:Tier");
+    expect(query).toContain(`a ${story?.lookup?.type}`);
+    expect(story?.lookup?.by).toBe(VOCABULARY.altName);
+    expect(query).toContain(`${VOCABULARY.altName} ?name`);
+  });
+});

package/src/capabilities/distribution.ts

@@ -0,0 +1,59 @@
+/**
+ * The distribution's own read stories, compiled at module load.
+ *
+ * `pragma.conf.ts` declares them on the packs that supply them; this is the ONE
+ * place those declarations become capabilities. They come through the SAME door
+ * a third-party story does — {@link compilePack} — so the mechanism the CLI
+ * offers forks is the mechanism the CLI itself runs on.
+ *
+ * They are compiled STATICALLY rather than merged at dispatch on purpose: the
+ * `--help` / `__complete` fast paths read the static capability set, and
+ * `surface/surface.v2.json` freezes the emitted surface, so a noun that only
+ * arrived at dispatch would vanish from help and completion on a fresh install.
+ * That is affordable because this module is zod-free and pure — `pragma.conf.ts`
+ * is inert data and `compilePack` builds specs without touching the store.
+ *
+ * Config- and package-declared stories still OVERRIDE these at dispatch; the
+ * `story` marker on each module is what tells `assembleEffectiveModules` which
+ * modules may be replaced.
+ */
+
+import conf from "../../pragma.conf.js";
+import { compilePack } from "../kernel/packs/compile.js";
+import {
+  distributionSource,
+  type PackDefinition,
+} from "../kernel/packs/types.js";
+import { DEFAULT_PREFIX_MAP } from "../kernel/render/prefixes.js";
+import type { CapabilityModule } from "../kernel/spec/types.js";
+
+/** The read stories `pragma.conf.ts` declares on its packs, by noun. */
+export const declaredStories: ReadonlyMap<string, PackDefinition> = new Map(
+  conf.packs
+    .flatMap((pack) => pack.stories ?? [])
+    .map((story): readonly [string, PackDefinition] => [story.noun, story]),
+);
+
+/**
+ * Those stories compiled to capability modules, by noun.
+ *
+ * `capabilities/index.ts` appends every module no authored one claims — and
+ * since L-OPEN-9 that is every one of them: no data noun is authored, so a
+ * declared story IS the whole noun. `distribution.test.ts` holds that shut by
+ * asserting each registered module's verbs deep-equal its compiled story's.
+ */
+export const storyModules: ReadonlyMap<string, CapabilityModule> = new Map(
+  [...declaredStories].map(([noun, story]) => [
+    noun,
+    {
+      name: noun,
+      story: true,
+      verbs: compilePack(
+        story,
+        distributionSource("pragma.conf.ts"),
+        DEFAULT_PREFIX_MAP,
+      ),
+      colophon: story.colophon,
+    },
+  ]),
+);

package/src/capabilities/doctor/checks/checkConfigFile.ts

@@ -1,3 +1,4 @@
+import { BIN_NAME } from "../../../constants.js";
 import { readConfig } from "../../../kernel/config/readConfig.js";
 import type { PragmaRuntime } from "../../../kernel/runtime/types.js";
 import type { CheckResult } from "../types.js";
@@ -5,7 +6,7 @@ import type { CheckResult } from "../types.js";
 /**
  * Check which config layer is active for the working directory.
  *
- * Passes when a project `pragma.config.ts` is found up the tree, or — pragma is
+ * Passes when a project config is found up the tree, or — the CLI is
  * global-first — when only the global XDG config exists. Fails only when
  * neither layer is configured.
  *
@@ -18,7 +19,7 @@ export async function checkConfigFile(rt: PragmaRuntime): Promise<CheckResult> {
 
   if (layers.project.exists) {
     return {
-      name: "pragma config",
+      name: `${BIN_NAME} config`,
       status: "pass",
       detail: `project config active (${layers.project.path})`,
     };
@@ -26,16 +27,16 @@ export async function checkConfigFile(rt: PragmaRuntime): Promise<CheckResult> {
 
   if (layers.global.exists) {
     return {
-      name: "pragma config",
+      name: `${BIN_NAME} config`,
       status: "pass",
       detail: `no project config — global config active (${layers.global.path})`,
     };
   }
 
   return {
-    name: "pragma config",
+    name: `${BIN_NAME} config`,
     status: "fail",
     detail: "not found",
-    remedy: "pragma config set tier <path>",
+    remedy: `${BIN_NAME} config set tier <path>`,
   };
 }

package/src/capabilities/doctor/checks/checkKeStore.ts

@@ -1,3 +1,4 @@
+import { BIN_NAME } from "../../../constants.js";
 import { entityTotal } from "../../../kernel/completion/entitySource.js";
 import type { PragmaRuntime } from "../../../kernel/runtime/types.js";
 import type { CheckResult } from "../types.js";
@@ -32,8 +33,7 @@ export async function checkKeStore(rt: PragmaRuntime): Promise<CheckResult> {
       name: "ke store",
       status: "fail",
       detail: "failed to boot",
-      remedy:
-        "Ensure design-system packages are installed and run `pragma sources update`.",
+      remedy: `Ensure design-system packs are configured and run \`${BIN_NAME} sources update\`.`,
     };
   }
 }

package/src/capabilities/doctor/checks/checkMcpConfigured.ts

@@ -1,11 +1,12 @@
 import type { DetectedHarness } from "@canonical/harnesses";
 import { detectHarnesses, readMcpConfig } from "@canonical/harnesses";
 import { runTask } from "@canonical/task/node";
+import { BIN_NAME, MCP_SERVER_NAME } from "../../../constants.js";
 import type { CheckResult } from "../types.js";
 import { deriveBand } from "./deriveBand.js";
 
 /**
- * Check that at least one AI harness has pragma configured as an MCP server. The
+ * Check that at least one AI harness has this CLI configured as an MCP server. The
  * result's band is derived from the harnesses actually found (Windsurf ⇒ global,
  * Cursor ⇒ project), not the check name — so a global-scope harness is not
  * mislabeled PROJECT.
@@ -23,7 +24,7 @@ export async function checkMcpConfigured(cwd: string): Promise<CheckResult> {
       name: "MCP configured",
       status: "fail",
       detail: "harness detection failed",
-      remedy: "pragma setup mcp",
+      remedy: `${BIN_NAME} setup mcp`,
     };
   }
 
@@ -32,7 +33,7 @@ export async function checkMcpConfigured(cwd: string): Promise<CheckResult> {
       name: "MCP configured",
       status: "fail",
       detail: "no AI harnesses detected",
-      remedy: "pragma setup mcp",
+      remedy: `${BIN_NAME} setup mcp`,
     };
   }
 
@@ -41,7 +42,7 @@ export async function checkMcpConfigured(cwd: string): Promise<CheckResult> {
     if (!d.configExists) continue;
     try {
       const servers = await runTask(readMcpConfig(d.harness, cwd));
-      if ("pragma" in servers) configured.push(d);
+      if (MCP_SERVER_NAME in servers) configured.push(d);
     } catch {
       // Config unreadable — skip.
     }
@@ -60,8 +61,8 @@ export async function checkMcpConfigured(cwd: string): Promise<CheckResult> {
   return {
     name: "MCP configured",
     status: "fail",
-    detail: `detected ${names} but pragma not configured`,
-    remedy: "pragma setup mcp",
+    detail: `detected ${names} but ${MCP_SERVER_NAME} not configured`,
+    remedy: `${BIN_NAME} setup mcp`,
     band: deriveBand(detected),
   };
 }