create-ailk 0.24.0 → 0.26.0

package/README.md

@@ -17,12 +17,18 @@ Compose the site from modules with `--modules`. The recognized vocabulary is
 `RECOGNIZED_MODULES` in `src/parse-args.ts` — `marketing`, `docs-blog`,
 `multi-tenant`, `workspace`, `scheduling`, `signal-collectors`, `commerce` —
 and `--modules` TRIMS or ADDS relative to the level your licence key unlocks
-(#6759), never replaces it: with no key the level is Free (`marketing`
-alone); a Pro key switches on `docs-blog`, `scheduling` and
-`signal-collectors` too; Pro Plus adds `multi-tenant`. Naming modules here
+(#6759), never replaces it: Free is `marketing` alone; a Pro key switches
+on `docs-blog`, `workspace` (the `/admin` settings surface, #9696),
+`scheduling` and `signal-collectors` too; Pro Plus adds
+`multi-tenant`. A run with no key is a Free run, and Free is held for now
+(`release-scope.json` marks `levels.free` `deferred`, #6484): the CLI refuses
+it before its first write, naming `https://ailaunchkit.ai/pricing` and the
+two ways to pass a key (`--license <key>` or `AILK_LICENSE_KEY`). The Free
+template and level stay defined; only the keyless path is held. Naming modules here
 keeps exactly those, trimming the level's default; naming only `commerce`
-(a per-site add-on) or `workspace` (included at Pro, opt-in) adds it on top
-of the level's default without trimming. The level is always DERIVED from
+(a per-site add-on) adds it on top of the level's default without trimming,
+and naming only `workspace` is a no-op at Pro and Pro Plus, whose defaults already
+carry it (below Pro it is refused, naming Pro). The level is always DERIVED from
 what the module registry answers for your key — never read from a flag, a
 manifest or a key claim (`src/lib/module-tier.ts` `LEVEL_MODULES`,
 `src/lib/module-license-gate.ts` `deriveLevel`):
@@ -42,24 +48,27 @@ vocabulary is `RECOGNIZED_SHAPES` in `src/parse-args.ts` — `organization-produ
 `organization-service`, `local-business-service`, `person-service` (the README
 already lists `RECOGNIZED_MODULES` the same way); `local-business-product` is
 refused as not available yet. A terminal run with no `--shape` asks; a
-non-interactive one stops. The level comes only from your license key: no key
-is Free, and a key switches on its level's modules (`LEVEL_MODULES`) —
-`--modules` trims or adds relative to that set, as above. A keyed example:
+non-interactive one stops. The level comes only from your license key: a key
+switches on its level's modules (`LEVEL_MODULES`) — `--modules` trims or adds
+relative to that set, as above — and no key is the Free level, which is held
+(above), so the run is refused before the shape prompt. A keyed example:
 
 ```bash
 pnpm create ailk@latest my-site --shape organization-service --license <key>
 ```
 
 `--design minimalism` picks the other look and needs a Pro or Pro Plus key;
-`standard` (the default) needs none. `--template <alias>` scaffolds one of the
+`standard` (the default) needs none of its own (the run itself still needs a
+key while Free is held, above). `--template <alias>` scaffolds one of the
 three named aliases (`marketing-site-free`, `marketing-site`, `saas-product`) —
 each fixes a shape, a design and its own module list — and cannot be combined
-with `--shape` or `--design`.
+with `--shape` or `--design`; `marketing-site-free` with no key is refused the
+same way while Free is held.
 
 ### Add a purchased module to an existing site
 
-A site scaffolded without a paid module (a Free site whose owner then buys
-Pro, say) gets it with `add-module` — alias `upgrade` — run against the site
+A site scaffolded without a paid module (a site scaffolded with `--modules
+marketing` whose owner then adds `docs-blog`, say) gets it with `add-module` — alias `upgrade` — run against the site
 itself, with `AILK_LICENSE_KEY` covering the module:
 
 ```bash
@@ -69,6 +78,13 @@ AILK_LICENSE_KEY=<key> create-ailk add-module docs-blog
 AILK_LICENSE_KEY=<key> create-ailk upgrade docs-blog ./my-site
 ```
 
+A Pro site scaffolded before a Pro key switched on `workspace` (#9696) has no
+`/admin`. This is how it gains the owner's settings surface:
+
+```bash
+AILK_LICENSE_KEY=<key> create-ailk add-module workspace
+```
+
 It fetches the module's bundle through the same licence gate a scaffold uses
 (no key, or a key that does not cover the module, is refused with the same
 message, before anything is written) and merges it **without overwriting
@@ -245,7 +261,7 @@ of three outcomes:
 
 - **Copied** — the site lacks it and the template has it: `--apply` copies it
   (never overwriting) and check mode lists it under `copies:` and `Also
-  required`.
+required`.
 - **Left as-is** — the site has it and its copy differs from the template's:
   it is named under `left as-is (differs from the template)` and never
   written. The route is still copied; run your type-check afterwards.
@@ -496,6 +512,17 @@ from the module distribution's own 401/403 (`src/lib/fetch-module.ts`). The
 gate runs before anything is copied (`scaffold()` in `src/programmatic.ts`), so
 a refused run leaves no partial scaffold behind.
 
+While the Free level is held (`release-scope.json` `levels.free: "deferred"`,
+#6484), a request that names no paid module needs a key as well: with none,
+`resolvePaidModules` and `cli.ts` call `assertKeyedOrFreeReleased`, which
+refuses the run with `level "free" is not available yet. No licence key, so
+this would be a Free scaffold — pass --license <key> or set AILK_LICENSE_KEY
+with a Pro key → https://ailaunchkit.ai/pricing`, before any prompt, fetch or
+write. The key is read on that path but never validated or sent — an all-Free
+request still makes no request — and a keyed run proceeds exactly as before.
+`AILK_RELEASE_SCOPE=ignore` is the test-only bypass (this package's jest
+setup); a published CLI never sets it.
+
 `AILK_MODULE_REGISTRY_URL` is optional: `fetchModule` uses an explicitly passed
 `registryUrl`, then that variable, then `https://api.ailaunchkit.ai/v1/modules`
 (`DEFAULT_AILK_MODULE_REGISTRY_URL`, `src/lib/fetch-module.ts`).
@@ -506,7 +533,10 @@ explicitly passed `registryUrl`, then that variable, then
 either registry fails the fetch before any second request is sent.
 
 ```bash
-# free-only — no key read, no network call
+# all-Free — the key is read (Free is held), never validated or sent; no network call
+AILK_LICENSE_KEY=... pnpm create ailk@latest my-site --shape organization-product --modules marketing
+
+# the same run with no key is refused before its first write (exit 1)
 pnpm create ailk@latest my-site --shape organization-product --modules marketing
 
 # paid — the key is read from the environment
@@ -515,9 +545,10 @@ AILK_LICENSE_KEY=... pnpm create ailk@latest my-site --shape organization-produc
 
 The network invariant (#6759 D6), in full:
 
-- **No key** → no request at all. A request that names no paid module never
-  reaches the key check either: `resolvePaidModules` returns an empty map on
-  its first branch, before touching `process.env` or the network.
+- **No key** → no request at all. A request that names no paid module reads
+  the key (#6484) but never validates or sends it: `resolvePaidModules` runs
+  `assertKeyedOrFreeReleased` — refusing a keyless run while Free is held —
+  and returns an empty map on its first branch, before the network.
 - **A key with no `--modules`** → the level probe (`deriveLevel`): 3-4
   requests, to find out what the key unlocks.
 - **An explicit `--modules` list** → requests only for the paid modules it
@@ -526,7 +557,7 @@ The network invariant (#6759 D6), in full:
 ## What it does
 
 1. Validates the target directory does not exist OR is empty.
-2. Copies the curated template tree (`apps/{web,api,mcp}` + `database/` + `content/` + root config files) from the package's `templates/` directory.
+2. Copies the curated template tree (`apps/{web,api,mcp}` + the thin `database/` — `prisma.config.ts` over the installed `@working-theory/database`, plus the two seeds — + `content/` + root config files) from the package's `templates/` directory.
 3. Substitutes `workspace:*` references in every `package.json` with the matching `@working-theory/*` semver from npm — versions are pinned at npm-publish time.
 4. Substitutes `{{PROJECT_NAME}}`, `{{COMPANY_NAME}}`, `{{COMPANY_DOMAIN}}` markers in `templates/README.md` from the target directory name (and CLI flags / interactive prompts in future versions).
 5. Derives and writes `architecture.yaml` (the site's code-boundary config) from the selected module set — see below.
@@ -557,10 +588,10 @@ declares a slice for every recognized module.
 ## Templates are snapshotted at build time
 
 The `prepublishOnly` script (`scripts/build-templates.mjs`) reads the canonical
-sources from this monorepo (`apps/`, `database/`, `content/`, root config) and
-populates `templates/`. The npm tarball ships the populated templates via the
-`files` field. A free-only scaffold performs no network access at scaffold
-time; only `pnpm install` (run by the user after scaffolding) hits the npm
+sources from this monorepo (`apps/`, the two `database/` seeds, `content/`, root
+config) and populates `templates/`. The npm tarball ships the populated templates via the
+`files` field. An all-Free scaffold (a key plus `--modules marketing`)
+performs no network access at scaffold time; only `pnpm install` (run by the user after scaffolding) hits the npm
 registry. A run naming a paid module fetches that module's bundle — see
 [Paid modules require `AILK_LICENSE_KEY`](#paid-modules-require-ailk_license_key).
 

package/component-catalog.json

@@ -1283,7 +1283,7 @@
       "sourcePath": "packages/ui/src/blocks/ListRow.tsx",
       "importPath": "@working-theory/ui/blocks",
       "exported": true,
-      "description": "The PHONE form of one admin list item. The reference is `apps-paid/admin/design/demos/first-steps/demo.html:475` (`rowDoc`), which lays the row out as: a leading type glyph, a two-line text column with the MUTED META LINE FIRST and the item's name second (every phone screen in the demo agrees), an optional trailing control, and a chevron.",
+      "description": "The PHONE form of one admin list item. The reference is `packages-paid/admin/design/demos/first-steps/demo.html:475` (`rowDoc`), which lays the row out as: a leading type glyph, a two-line text column with the MUTED META LINE FIRST and the item's name second (every phone screen in the demo agrees), an optional trailing control, and a chevron.",
       "descriptionSource": "doc-comment",
       "descriptionGrade": "strong",
       "sectionType": null
@@ -1294,7 +1294,7 @@
       "sourcePath": "packages/ui/src/blocks/ListTable.tsx",
       "importPath": "@working-theory/ui/blocks",
       "exported": true,
-      "description": "The desktop form: a fixed-layout list table that never wraps, with the shared Tags and Live cells. The reference is `apps-paid/admin/design/demos/first-steps/demo.html`'s `.tbl`: `table-layout:fixed` on the table and `white-space:nowrap;overflow:hidden;text-overflow:ellipsis` on every cell. BOTH are load-bearing — `table-fixed` alone lets the cell wrap, `truncate` alone lets the browser widen the column to fit.",
+      "description": "The desktop form: a fixed-layout list table that never wraps, with the shared Tags and Live cells. The reference is `packages-paid/admin/design/demos/first-steps/demo.html`'s `.tbl`: `table-layout:fixed` on the table and `white-space:nowrap;overflow:hidden;text-overflow:ellipsis` on every cell. BOTH are load-bearing — `table-fixed` alone lets the cell wrap, `truncate` alone lets the browser widen the column to fit.",
       "descriptionSource": "barrel",
       "descriptionGrade": "strong",
       "sectionType": null
@@ -1646,7 +1646,7 @@
       "sourcePath": "packages/ui/src/blocks/RowGroup.tsx",
       "importPath": "@working-theory/ui/blocks",
       "exported": true,
-      "description": "The bordered box that groups ListRows with hairline dividers. The reference is `apps-paid/admin/design/demos/first-steps/demo.html`'s `.box` (`background:var(--bg);border:1px solid var(--border); border-radius:6px;overflow:hidden`) with `.row{border-top:…}` and `.row:first-child{border-top:0}` — i.e. hairlines BETWEEN rows, none above the first.",
+      "description": "The bordered box that groups ListRows with hairline dividers. The reference is `packages-paid/admin/design/demos/first-steps/demo.html`'s `.box` (`background:var(--bg);border:1px solid var(--border); border-radius:6px;overflow:hidden`) with `.row{border-top:…}` and `.row:first-child{border-top:0}` — i.e. hairlines BETWEEN rows, none above the first.",
       "descriptionSource": "barrel",
       "descriptionGrade": "strong",
       "sectionType": null

package/component-catalog.md

@@ -177,8 +177,8 @@ Import: `import { X } from "@working-theory/ui/blocks";` (or from the `@working-
 | `LeadCaptureForm` | The one contact form every template renders. Submits ONLY through the `action` prop — a Server Action the page binds — so there is no fetch, no URL and no browser-side JSON here. | `import { LeadCaptureForm } from "@working-theory/ui/blocks"` |
 | `LinkCard` | A whole-tile link card: the entire tile IS the anchor (Claude-docs link-card anatomy). Optional leading icon, a title heading, and an optional description paragraph. Hover fill + chrome are intrinsic to the block — never props. | `import { LinkCard } from "@working-theory/ui/blocks"` |
 | `LinkListItem` | Hub-page spoke list row: prose Link + optional description, enlarged to the 44px touch-target floor. Fix: the enlarged-hit-area pattern (same idiom as ShortcutTrigger, SegmentedControl's touchTargetFloor) — `min-h-(control-height-big)` clamps the anchor's clickable box to 44px while `inline-flex items-center` keeps the visible text at its normal prose size. | `import { LinkListItem } from "@working-theory/ui/blocks"` |
-| `ListRow` | The PHONE form of one admin list item. The reference is `apps-paid/admin/design/demos/first-steps/demo.html:475` (`rowDoc`), which lays the row out as: a leading type glyph, a two-line text column with the MUTED META LINE FIRST and the item's name second (every phone screen in the demo agrees), an optional trailing control, and a chevron. | `import { ListRow } from "@working-theory/ui/blocks"` |
-| `ListTable` | The desktop form: a fixed-layout list table that never wraps, with the shared Tags and Live cells. The reference is `apps-paid/admin/design/demos/first-steps/demo.html`'s `.tbl`: `table-layout:fixed` on the table and `white-space:nowrap;overflow:hidden;text-overflow:ellipsis` on every cell. BOTH are load-bearing — `table-fixed` alone lets the cell wrap, `truncate` alone lets the browser widen the column to fit. | `import { ListTable } from "@working-theory/ui/blocks"` |
+| `ListRow` | The PHONE form of one admin list item. The reference is `packages-paid/admin/design/demos/first-steps/demo.html:475` (`rowDoc`), which lays the row out as: a leading type glyph, a two-line text column with the MUTED META LINE FIRST and the item's name second (every phone screen in the demo agrees), an optional trailing control, and a chevron. | `import { ListRow } from "@working-theory/ui/blocks"` |
+| `ListTable` | The desktop form: a fixed-layout list table that never wraps, with the shared Tags and Live cells. The reference is `packages-paid/admin/design/demos/first-steps/demo.html`'s `.tbl`: `table-layout:fixed` on the table and `white-space:nowrap;overflow:hidden;text-overflow:ellipsis` on every cell. BOTH are load-bearing — `table-fixed` alone lets the cell wrap, `truncate` alone lets the browser widen the column to fit. | `import { ListTable } from "@working-theory/ui/blocks"` |
 | `LocaleSwitcher` | Compact globe + locale dropdown. Extracts the "🌐 English ▾" affordance that lived as an inline node in the chrome Footer story into a reusable block. Composes the `Select` primitive (NOT a raw <select>): a leading globe icon, the current locale label (via SelectValue), and the trigger's built-in chevron. | `import { LocaleSwitcher } from "@working-theory/ui/blocks"` |
 | `LocaleSwitcherNav` | Composes the controlled `LocaleSwitcher` block and owns the navigation side-effect that block deliberately leaves to its consumer: on a locale change it writes the `NEXT_LOCALE` cookie and navigates to the as-needed prefixed path (default locale unprefixed, every other locale `/<code>` + path — mirroring `apps/web/middleware.ts`'s `localePrefix: "as-needed"`). | `import { LocaleSwitcherNav } from "@working-theory/ui/blocks"` |
 | `LogoRow` | The ONE logo-strip implementation; bounded layout/treatment/logoSize plus an opt-in motion-safe marquee; composed by the LogoCloud section and the Hero logoStrip opt-in. | `import { LogoRow } from "@working-theory/ui/blocks"` |
@@ -210,7 +210,7 @@ Import: `import { X } from "@working-theory/ui/blocks";` (or from the `@working-
 | `Prose` | The single typography wrapper both the docs route and blog render their compiled-MDX body inside. It styles every RAW markdown element a compiled document emits — h2–h6, p, ul/ol/li, blockquote, table parts, hr, a, inline code, pre, img, kbd, strong/em — via `@working-theory/theme` semantic tokens and type roles. No raw color or spacing literals; dark mode rides the semantic tokens (no `dark:` variants needed). | `import { Prose } from "@working-theory/ui/blocks"` |
 | `RecommendationCard` | "For you" proactive-recommendation tile: status + title + description + "Why this?" disclosure + context chip + action + dismiss (ploy-capture recomposition). The "For you" proactive-recommendation card captured off ploy.ai's Overview page (behavior spec: -2, — `overview-page` "For you" feed / rebuild-triage row "For you" recommendation card"). | `import { RecommendationCard } from "@working-theory/ui/blocks"` |
 | `ResponsiveSheet` | ONE component, TWO forms, ONE open pair. Renders its `children` as a Radix Dialog at `md` (768px, --breakpoint-md) and up, and as a full-screen Radix Sheet below it — never both at once. | `import { ResponsiveSheet } from "@working-theory/ui/blocks"` |
-| `RowGroup` | The bordered box that groups ListRows with hairline dividers. The reference is `apps-paid/admin/design/demos/first-steps/demo.html`'s `.box` (`background:var(--bg);border:1px solid var(--border); border-radius:6px;overflow:hidden`) with `.row{border-top:…}` and `.row:first-child{border-top:0}` — i.e. hairlines BETWEEN rows, none above the first. | `import { RowGroup } from "@working-theory/ui/blocks"` |
+| `RowGroup` | The bordered box that groups ListRows with hairline dividers. The reference is `packages-paid/admin/design/demos/first-steps/demo.html`'s `.box` (`background:var(--bg);border:1px solid var(--border); border-radius:6px;overflow:hidden`) with `.row{border-top:…}` and `.row:first-child{border-top:0}` — i.e. hairlines BETWEEN rows, none above the first. | `import { RowGroup } from "@working-theory/ui/blocks"` |
 | `SchedulerEmbed` | A declarative third-party booking iframe. Renders a full-width, border-0, lazy-loaded <iframe> at `src` with a graceful loading skeleton (shown until the iframe's own `load` event fires) and a timeout-gated plain-link fallback beneath it — for environments that block third-party frames (ad blockers, a strict CSP `frame-src`) where the iframe may load blank or never load at all. | `import { SchedulerEmbed } from "@working-theory/ui/blocks"` · `packages/ui/src/blocks/SchedulerEmbed.tsx` |
 | `SectionActionRow` | The bottom-anchored, centered action row a section places BENEATH its own content, at the 44×44px target-size floor. It is the block form of the placement established for `stair-steps`: a bounded 1-2 action list rendered after the section body rather than inside the section header. | `import { SectionActionRow } from "@working-theory/ui/blocks"` |
 | `SectionHeader` | Alignment-parameterized section header (eyebrow/subtitle/description/supportLink). The same component serves two ranks (headingLevel="section" \| "subsection") and three alignments (align="start" \| "center" \| "end"). It knows nothing about columns/splits/carousels — it is width-flexible and fills whatever container the section places it in. | `import { SectionHeader } from "@working-theory/ui/blocks"` |

package/dist/add-module.js

@@ -35,7 +35,7 @@ import { writeAuthSecretFile } from "./lib/auth-secret-file.js";
 import { appendEnvRows } from "./lib/declared-env.js";
 import { diffTwoStrings, extractModuleBundle, } from "./lib/extract-module-bundle.js";
 import { normalizeModules } from "./module-architecture.js";
-import { MODULE_FLAGS_PATH, PAID_SECTIONS_PATH, writePaidSections } from "./paid-sections.js";
+import { MODULE_FLAGS_PATH, PAID_MCP_TOOLS_PATH, PAID_SECTIONS_PATH, writePaidSections, } from "./paid-sections.js";
 import { ParseError, parseModules } from "./parse-args.js";
 import { writeSpokeFlowsReadme } from "./seed-flows.js";
 import { SITE_ROSTER_PATH, moduleRosterRows, planRosterAppend, readSiteRoster, siteRosterProblems, } from "./site-roster.js";
@@ -211,7 +211,9 @@ export async function applyModuleToScaffold(opts) {
     // overwritten, like `architecture.yaml` above.
     // #8843 D10 — its module-presence flags follow the same file, and are
     // reported the same way when a module turns one on.
-    const generated = [PAID_SECTIONS_PATH, MODULE_FLAGS_PATH].map((path) => {
+    // #9460 DD6 — the paid MCP tool registry follows `apps/mcp/package.json`
+    // the same way.
+    const generated = [PAID_SECTIONS_PATH, MODULE_FLAGS_PATH, PAID_MCP_TOOLS_PATH].map((path) => {
         const abs = join(targetAbs, path);
         return { path, abs, before: existsSync(abs) ? readFileSync(abs, "utf8") : undefined };
     });

package/dist/add-route.d.ts

@@ -72,6 +72,11 @@ export interface AddMagnetResult {
     flow: string;
     /** The landing's row, then the walk's. */
     report: MagnetReportRow[];
+    /**
+     * The `customizations.yaml` entry mapping both pages, indented to append
+     * under `customizations:` as `--seed-customizations` prints entries.
+     */
+    entry: string;
 }
 /**
  * Write a magnet page pair — `apps/web/app/[locale]/<path>/page.tsx` (the
@@ -83,6 +88,12 @@ export interface AddMagnetResult {
  * that already exists is never overwritten: a second run reports both
  * `skipped`. No `architecture.yaml`, nav or seed changes — the pair is the
  * site's own, with no `ROUTE_SINCE` key or routes-map row (D13).
+ *
+ * Being the site's own, the pair is no template-record row either: `update`
+ * deletes an untouched recorded file the template does not carry. So the
+ * site lint's R5a reads both pages as site-authored, and the result carries
+ * the `customizations.yaml` entry that maps them, a site-kept decision the
+ * report prints ready to paste (#9553).
  */
 export declare function addMagnetToScaffold(opts: AddMagnetOptions): AddMagnetResult;
 /** The report `add-route magnet` prints. */
@@ -98,7 +109,7 @@ export interface AddRouteArgs {
     /** `--flow`, the magnet mode's flow slug — set only with `magnet`. */
     flow?: string;
 }
-export declare const ADD_ROUTE_HELP = "create-ailk add-route \u2014 add a route family to an existing site.\n\nUsage:\n  create-ailk add-route <route> [<target-dir>]\n  create-ailk add-route magnet --path <path> --flow <slug> [<target-dir>]\n\nArguments:\n  <route>                  One route family, named as --surfaces names it,\n                           e.g. pricing.\n  <target-dir>             An already-scaffolded repo (contains\n                           architecture.yaml). Defaults to the current dir.\n\nOptions:\n  --path <path>            magnet only: the site path the landing serves,\n                           one to three kebab-case segments, e.g. /diagnostic.\n  --flow <slug>            magnet only: the flow slug the pages are bound to.\n  --help, -h               Print this message.\n\nCopies the route's pages, writes its seed content, declares it in\narchitecture.yaml and adds its link to the generated nav \u2014 the site a fresh\nscaffold with --surfaces <route> would have been. A file the site already has\nis never overwritten: one whose content differs, a hand-edited nav included,\nis left as-is and listed for manual review with the change the route wanted.\nLike add-module, it also restores any other page route the site carries but\nlacks. A route a module delivers (blog and docs come with docs-blog) is\nrefused; add that module with create-ailk add-module. Running it again changes\nnothing.\n\nadd-route magnet writes a magnet page pair bound to one flow: a landing at\napps/web/app/[locale]/<path>/page.tsx and a full-screen walk at\n<path>/start/page.tsx, each a few lines over the standard magnet pages, so the\ncopy, consent and ending come from the flow's record. It needs the\nsignal-collectors module, and refuses (nothing written) a path the site already\nserves, a one-segment path a LandingPage seed of the same slug owns, a path\nending in start or apply, a reserved first segment (api, v1, flows, account,\nadmin, the sign-in routes, a locale) and a slug the flow API would refuse. A\npage that exists is never overwritten: running it again skips both. It changes\nno architecture.yaml, nav or seed.\n";
+export declare const ADD_ROUTE_HELP = "create-ailk add-route \u2014 add a route family to an existing site.\n\nUsage:\n  create-ailk add-route <route> [<target-dir>]\n  create-ailk add-route magnet --path <path> --flow <slug> [<target-dir>]\n\nArguments:\n  <route>                  One route family, named as --surfaces names it,\n                           e.g. pricing.\n  <target-dir>             An already-scaffolded repo (contains\n                           architecture.yaml). Defaults to the current dir.\n\nOptions:\n  --path <path>            magnet only: the site path the landing serves,\n                           one to three kebab-case segments, e.g. /diagnostic.\n  --flow <slug>            magnet only: the flow slug the pages are bound to.\n  --help, -h               Print this message.\n\nCopies the route's pages, writes its seed content, declares it in\narchitecture.yaml and adds its link to the generated nav \u2014 the site a fresh\nscaffold with --surfaces <route> would have been. A file the site already has\nis never overwritten: one whose content differs, a hand-edited nav included,\nis left as-is and listed for manual review with the change the route wanted.\nLike add-module, it also restores any other page route the site carries but\nlacks. A route a module delivers (blog and docs come with docs-blog) is\nrefused; add that module with create-ailk add-module. Running it again changes\nnothing.\n\nadd-route magnet writes a magnet page pair bound to one flow: a landing at\napps/web/app/[locale]/<path>/page.tsx and a full-screen walk at\n<path>/start/page.tsx, each a few lines over the standard magnet pages, so the\ncopy, consent and ending come from the flow's record. It needs the\nsignal-collectors module, and refuses (nothing written) a path the site already\nserves, a one-segment path a LandingPage seed of the same slug owns, a path\nending in start or apply, a reserved first segment (api, v1, flows, account,\nadmin, the sign-in routes, a locale) and a slug the flow API would refuse. A\npage that exists is never overwritten: running it again skips both. It changes\nno architecture.yaml, nav or seed; it prints the customizations.yaml entry\nthat maps the two pages, for pnpm architecture.\n";
 /**
  * Parse the argv AFTER the `add-route` word. Strict `node:util` parseArgs,
  * like `parseAddModuleArgs`; the route itself is validated by

package/dist/add-route.js

@@ -314,6 +314,11 @@ const RESERVED_FIRST_SEGMENTS = new Set([
 const LOCALE_SHAPED_RE = /^[a-z]{2}(-[a-z]{2})?$/;
 /** Template-relative root every page directory sits under. */
 const WEB_ROUTE_ROOT = "apps/web/app/[locale]";
+/**
+ * The `request` a pair's `customizations.yaml` entry names (#9553): the AILK
+ * issue that made the pair the site's own page (#8840 C1).
+ */
+const MAGNET_REQUEST = "working-theory-labs/ai-launch-kit-internal#8840";
 /** Whether `slug` passes `flowSlugSchema`'s rule. */
 export function isMagnetFlowSlug(slug) {
     return slug.length <= FLOW_SLUG_MAX && FLOW_SLUG_RE.test(slug);
@@ -328,6 +333,12 @@ export function isMagnetFlowSlug(slug) {
  * that already exists is never overwritten: a second run reports both
  * `skipped`. No `architecture.yaml`, nav or seed changes — the pair is the
  * site's own, with no `ROUTE_SINCE` key or routes-map row (D13).
+ *
+ * Being the site's own, the pair is no template-record row either: `update`
+ * deletes an untouched recorded file the template does not carry. So the
+ * site lint's R5a reads both pages as site-authored, and the result carries
+ * the `customizations.yaml` entry that maps them, a site-kept decision the
+ * report prints ready to paste (#9553).
  */
 export function addMagnetToScaffold(opts) {
     const targetAbs = resolve(opts.targetDir);
@@ -382,7 +393,23 @@ export function addMagnetToScaffold(opts) {
         writeFileSync(dest, text);
         report.push({ path, action: "written" });
     }
-    return { targetDir: targetAbs, path: opts.path, flow: opts.flow, report };
+    // Segments join on `--`, which no kebab segment carries, so `/a-b` and
+    // `/a/b` never share an id.
+    const today = new Date().toISOString().slice(0, 10);
+    const entry = [
+        `  - id: ${JSON.stringify(`magnet-${segments.join("--")}`)}`,
+        "    paths:",
+        ...pages.map(([path]) => `      - ${JSON.stringify(path)}`),
+        `    request: ${JSON.stringify(MAGNET_REQUEST)}`,
+        `    decision: ${JSON.stringify(`build-in: site — ailk#8840, ${today}, a magnet pair is the site's own page over AILK's standard renderers`)}`,
+    ].join("\n");
+    return {
+        targetDir: targetAbs,
+        path: opts.path,
+        flow: opts.flow,
+        report,
+        entry,
+    };
 }
 /** `--path`'s segments, refusing a path a pair may not take (SEC-8840-J). */
 function magnetPathSegments(path) {
@@ -507,7 +534,7 @@ export function formatAddMagnetReport(result) {
         lines.push(...skipped.map((row) => `  ${row.path}`));
     }
     if (written.length > 0) {
-        lines.push(`Next: pnpm build, then open ${result.path}. The page's copy comes from the ${result.flow} flow's record.`);
+        lines.push(`Next: append this entry to customizations.yaml unless it is there already (an empty \`customizations: []\` becomes \`customizations:\` first), then pnpm build and open ${result.path}. The page's copy comes from the ${result.flow} flow's record.`, result.entry);
     }
     return lines.join("\n") + "\n";
 }
@@ -548,7 +575,8 @@ serves, a one-segment path a LandingPage seed of the same slug owns, a path
 ending in start or apply, a reserved first segment (api, v1, flows, account,
 admin, the sign-in routes, a locale) and a slug the flow API would refuse. A
 page that exists is never overwritten: running it again skips both. It changes
-no architecture.yaml, nav or seed.
+no architecture.yaml, nav or seed; it prints the customizations.yaml entry
+that maps the two pages, for pnpm architecture.
 `;
 /**
  * Parse the argv AFTER the `add-route` word. Strict `node:util` parseArgs,

package/dist/cli.js

@@ -55,7 +55,7 @@ import { ADOPT_HELP, AdoptRefusedError, adoptSite, formatAdoptReport, parseAdopt
 import { APPLY_DESIGN_HELP, applyDesign, formatApplyDesignReport, parseApplyDesignArgs, } from "./apply-design.js";
 import { CLAUDE_MD_CHECK_PATH } from "./claude-md.js";
 import { buildScaffoldMarkers } from "./copy.js";
-import { assertReleased } from "./lib/module-license-gate.js";
+import { assertKeyedOrFreeReleased, assertReleased } from "./lib/module-license-gate.js";
 import { withNpmTokenUserConfig } from "./lib/npm-auth.js";
 import { FREE_PREREQUISITES_NOTE, LICENSED_PREREQUISITES_NOTE, isLicensedInstall, proCallout, } from "./lib/pro-callout.js";
 import { LICENSE_SET_HELP, runLicenseSet } from "./license-set.js";
@@ -309,6 +309,7 @@ async function main() {
                 targetDir: args.target ?? process.cwd(),
                 templatesDir: resolve(PKG_ROOT, "templates"),
                 version: readPackageVersion(),
+                versions: readVersionMap(),
             });
             process.stdout.write(formatUpdateReport(result));
         }
@@ -328,6 +329,8 @@ async function main() {
     if (parsed.needsShapePrompt && !parsed.help && !parsed.version) {
         assertReleased("designs", [parsed.design]);
         assertReleased("modules", parsed.modules ?? []);
+        // #6484 — and a keyless run, which is the Free level the scope defers.
+        assertKeyedOrFreeReleased(parsed.license);
     }
     const opts = await resolveCliShape(parsed, {
         input: process.stdin,
@@ -433,10 +436,12 @@ async function main() {
     // rejection (caught at top level below). The network invariant (#6759 D6):
     // no key → no request at all; a key with no --modules → the D4 level probe
     // (3-4 requests); an explicit --modules list → requests only for the paid
-    // modules it names, exactly as before this card. `--template
-    // marketing-site-free` still rides the no-key case (record D11): its
-    // `requires` is all-free, so it installs from the shipped
-    // `site-templates/` tree with no key and no request.
+    // modules it names, exactly as before this card. A keyless run — `--template
+    // marketing-site-free` included, whose all-free `requires` once rode the
+    // no-key case (record D11) — is refused by the licence gate inside
+    // scaffold() (#6484, REL-034.1: Free is a deferred level,
+    // `release-scope.json`), after its scope-name refusals and before its first
+    // write, naming the pricing page. With a key, every branch is as before.
     const { targetDir: targetAbs, surfaces, starter, modules: effectiveModules, droppedModules, hubOrigin, hubSignInOrigin, } = await scaffold(toScaffoldOptions(opts));
     const isSpoke = opts.topology === "spoke";
     // The starter scaffold() resolved — from --template, or from --shape (#6754 D4).
@@ -491,7 +496,7 @@ async function main() {
                         "  AILK_HUB_CLIENT_SECRET     # issued by the hub; never written here",
                         "",
                         "On the hub, issue the client id and secret with:",
-                        "  pnpm --filter @working-theory/api spokes sign-in-client --id <spoke_id> --redirect-uri <this site's origin>/api/hub-session/callback",
+                        "  pnpm --filter @working-theory/app-api spokes sign-in-client --id <spoke_id> --redirect-uri <this site's origin>/api/hub-session/callback",
                     ]
                     : []),
             ]
@@ -500,7 +505,7 @@ async function main() {
     ];
     // Prerequisites (#6440 AC4) — every one the scaffold enforces, and nothing
     // it does not. A starter reaches `pnpm dev` AND `pnpm build` on a toolchain
-    // alone: the Prisma client is generated by `database`'s own `postinstall`,
+    // alone: the Prisma client ships prebuilt in `@working-theory/database`,
     // so there is no generator step to remember, and no database or vendor API
     // key gates either command (a free install also says no licence key does;
     // a licensed one, #6480, does not). Saying so is the point — the previous

package/dist/derive-architecture.d.ts

@@ -14,7 +14,7 @@
  * fixed document shape this module produces — no `yaml`/`js-yaml` dependency.
  */
 import { type ForbiddenPattern } from "./module-architecture.js";
-import type { Topology } from "./topology.js";
+import { type Topology } from "./topology.js";
 /** The topology a document is derived for (#7426 D8). */
 export interface DeriveArchitectureOptions {
     /** `"hub"` (the default) or `"spoke"`. */
@@ -51,9 +51,8 @@ export declare const SPOKE_MCP_FORBIDDEN_PATTERNS: readonly ForbiddenPattern[];
  *   modules gets exactly what the modules imply.
  * @param options the topology (#7426 D8). Absent or `"hub"` ⟹ the output is
  *   byte-identical to the two-argument form. `"spoke"` ⟹ only the spoke's own
- *   apps (`web`, and `mcp` unless `mcp: false`), no `namespaces`, no
- *   `database` root, a top-level `topology: spoke` and the hub-facing
- *   composition tiers.
+ *   apps (`web`, and `mcp` unless `mcp: false`), no `database` root, a
+ *   top-level `topology: spoke` and the hub-facing composition tiers.
  * @returns the complete `architecture.yaml` file content (a deterministic
  *   function of the module SET, the surface SET and the topology).
  * @throws Error on an unrecognized module (defensive; parse-args rejects first).

package/dist/derive-architecture.js

@@ -14,9 +14,19 @@
  * fixed document shape this module produces — no `yaml`/`js-yaml` dependency.
  */
 import { ARCHITECTURE_BASE, MODULE_SLICES, normalizeModules, } from "./module-architecture.js";
-import { CORE_SURFACE_PATHS, RECOGNIZED_SURFACES, resolveSurfaces, } from "./surfaces.js";
+import { MODULE_FLAGS_PATH, PAID_MCP_TOOLS_PATH, PAID_SECTIONS_PATH } from "./paid-sections.js";
+import { SITE_CHROME_PATH } from "./site-chrome.js";
+import { SITE_FONTS_PATH } from "./site-fonts.js";
+import { SPOKE_CHECKOUT_CONFIG_PATH, SPOKE_CHECKOUT_TEMPLATE_PATHS, } from "./spoke-checkout.js";
+import { CORE_SURFACE_PATHS, NAV_CONFIG_PATH, RECOGNIZED_SURFACES, resolveSurfaces, } from "./surfaces.js";
+import { SPOKE_SEAM_FILES } from "./topology.js";
 /** The npm scope a site consumes and never forks (#9191). */
 const PACKAGE_SCOPE = "@working-theory/";
+/** Apps whose `package.json` name is not `@working-theory/<dir>`, because the published package took it (#9564, #9570). */
+const SHELL_PACKAGE_NAME = {
+    api: "app-api",
+    admin: "admin-shell",
+};
 /** A spoke's composition tiers (#7426 D8): its data and API are the hub's. */
 const SPOKE_TIERS = {
     data: "none — the hub's database",
@@ -209,18 +219,6 @@ function appToYaml(app) {
     }
     return m;
 }
-function namespacesToYaml(ns) {
-    const members = {};
-    const sortedMembers = Object.entries(ns.members).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
-    for (const [key, mem] of sortedMembers) {
-        members[key] = { path: mem.path, description: mem.description };
-    }
-    return {
-        description: ns.description,
-        members,
-        rules: [...ns.rules],
-    };
-}
 /**
  * Derive the `architecture.yaml` document for a module set.
  *
@@ -231,9 +229,8 @@ function namespacesToYaml(ns) {
  *   modules gets exactly what the modules imply.
  * @param options the topology (#7426 D8). Absent or `"hub"` ⟹ the output is
  *   byte-identical to the two-argument form. `"spoke"` ⟹ only the spoke's own
- *   apps (`web`, and `mcp` unless `mcp: false`), no `namespaces`, no
- *   `database` root, a top-level `topology: spoke` and the hub-facing
- *   composition tiers.
+ *   apps (`web`, and `mcp` unless `mcp: false`), no `database` root, a
+ *   top-level `topology: spoke` and the hub-facing composition tiers.
  * @returns the complete `architecture.yaml` file content (a deterministic
  *   function of the module SET, the surface SET and the topology).
  * @throws Error on an unrecognized module (defensive; parse-args rejects first).
@@ -306,11 +303,10 @@ export function deriveArchitecture(modules = ["marketing"], surfaces, options =
             forbidden_patterns: mergeForbidden([...ARCHITECTURE_BASE.appForbiddenPatterns], [...(a.forbidden_patterns ?? []), ...extra]).map(scoped),
         });
     }
-    // namespaces — present only if a data-tier module contributes one, and
-    // never on a spoke, which has no database/ of its own.
-    const nsSlice = spoke
-        ? undefined
-        : slices.find((s) => s.namespaces)?.namespaces;
+    // No `namespaces` block (#9569): a site's `database/` holds no schema — the
+    // namespace boundaries belong to `@working-theory/database`'s own source and
+    // this monorepo's lint, and a rule naming `database/<ns>` paths a scaffold
+    // lacks is what #6940 refuses.
     // forbidden_patterns — base floor first, then the selected modules' patterns.
     const extraForbidden = [];
     for (const s of slices)
@@ -319,17 +315,57 @@ export function deriveArchitecture(modules = ["marketing"], surfaces, options =
     // The upgradeable-consumer rules (#9191): the workspaces this scaffold
     // creates and the in-scope package names it gives them. The site lint
     // reads this block to refuse a forked, patched or pinned-off package.
-    // Every app the scaffold ships is named `@working-theory/<dir>`.
+    // A hub's `database/` is a plain folder, not a workspace (#9569): the
+    // package is an npm dependency the same-caret rule covers like any other.
     const upgradeableConsumer = {
         package_scope: PACKAGE_SCOPE,
-        workspaces: spoke ? ["apps/*"] : ["apps/*", "database"],
-        scaffold_packages: [
-            ...(spoke ? [] : ["database"]),
-            ...Object.keys(apps),
-        ]
-            .map((dir) => `${PACKAGE_SCOPE}${dir}`)
+        workspaces: ["apps/*"],
+        // Every app the scaffold ships is named `@working-theory/<dir>`, except
+        // the two whose published package took the name: `@working-theory/api` is
+        // what the API app boots from (#9564), so the app is
+        // `@working-theory/app-api`; `@working-theory/admin` is what the Admin
+        // shell boots from (#9570), so the app is `@working-theory/admin-shell`.
+        scaffold_packages: Object.keys(apps)
+            .map((dir) => `${PACKAGE_SCOPE}${SHELL_PACKAGE_NAME[dir] ?? dir}`)
             .sort(),
     };
+    // The customizations manifest (#9223): the files under `apps/` the template
+    // record (`.ailk-template-files.json`) cannot see, so the site lint can tell
+    // a site-authored file from a scaffolded one by membership alone. (a) The
+    // generator outputs, on a hub and a spoke alike — an exempted path that is
+    // absent exempts nothing, and only a create-ailk generator writes each. The
+    // constants are composed here, never at module top level: `spoke-checkout`
+    // imports this module back, and `template-record`'s own list is deliberately
+    // not imported (it reads `spoke-checkout` at top level). (b) Each selected
+    // module's bundle-delivered and patched app files, scoped to the apps this
+    // derivation declares. (c) A commerce spoke's checkout slice, which
+    // `add-module` writes with no record row.
+    const generatorPaths = [
+        NAV_CONFIG_PATH,
+        SITE_CHROME_PATH,
+        SITE_FONTS_PATH,
+        PAID_SECTIONS_PATH,
+        MODULE_FLAGS_PATH,
+        PAID_MCP_TOOLS_PATH,
+        ...SPOKE_SEAM_FILES,
+        SPOKE_CHECKOUT_CONFIG_PATH,
+        SPOKE_BILLING_ACTION_PATH,
+    ];
+    const modulePaths = [];
+    for (const s of slices) {
+        modulePaths.push(...(s.ownedFiles ?? []));
+        modulePaths.push(...Object.values(s.installMap ?? {}));
+        if (s.installRoot)
+            modulePaths.push(`${s.installRoot.replace(/\/$/, "")}/**`);
+        modulePaths.push(...(s.patches ?? []).map((p) => p.target));
+    }
+    const checkoutPaths = spoke && selected.includes("commerce")
+        ? SPOKE_CHECKOUT_TEMPLATE_PATHS.map((p) => (/\.[^/]+$/.test(p) ? p : `${p}/**`))
+        : [];
+    const customizations = {
+        manifest: "customizations.yaml",
+        scaffold_paths: sortedUnion(generatorPaths, [...modulePaths, ...checkoutPaths].filter((p) => p.startsWith("apps/") && inScaffold(p))),
+    };
     const doc = {
         version: ARCHITECTURE_BASE.version,
         ...(spoke ? { topology: "spoke" } : {}),
@@ -344,9 +380,9 @@ export function deriveArchitecture(modules = ["marketing"], surfaces, options =
             available: [...RECOGNIZED_SURFACES],
         },
         apps,
-        ...(nsSlice ? { namespaces: namespacesToYaml(nsSlice) } : {}),
         forbidden_patterns: forbidden.map(forbiddenToYaml),
         upgradeable_consumer: upgradeableConsumer,
+        customizations,
     };
     const header = [
         "# Architecture Boundaries — AI Launch Kit site",

package/dist/lib/design-checks.d.ts

@@ -79,13 +79,18 @@ export interface MeasureApplyDesignDriftOptions {
     workDir: string;
     /** The loopback registry the CLI resolves modules and templates from. */
     registryUrl?: string;
-    /** Written to the site's own `ailk.key`, which `apply-design` gates a non-Free design on. */
+    /**
+     * Scaffolds with `--license <key>` (#9650: a keyless run refuses while Free
+     * is held), which writes the site's own `ailk.key` — what `apply-design`
+     * gates a non-Free design on.
+     */
     licenseKey?: string;
 }
 /**
- * Scaffold a keyless `organization-product` site on `standard`, compose its
- * JSON-LD, run `apply-design <design>` on it, and compose again. A non-zero
- * exit at any step throws naming the step and the child's stderr.
+ * Scaffold an `organization-product` site on `standard` — keyed when
+ * `licenseKey` is given — compose its JSON-LD, run `apply-design <design>` on
+ * it, and compose again. A non-zero exit at any step throws naming the step
+ * and the child's stderr.
  */
 export declare function measureApplyDesignDrift(opts: MeasureApplyDesignDriftOptions): {
     before: ComposedPages;