create-ailk 0.23.0 → 0.25.1

package/README.md

@@ -17,9 +17,13 @@ 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`, `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
@@ -42,24 +46,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
@@ -214,9 +221,9 @@ as-is, they never fail the check, and `--apply` never overwrites them.
 
 `--apply` only creates route directories that are absent, through the same
 copier a fresh scaffold uses (so the copied files are byte-identical to a fresh
-scaffold's). It never rewrites or deletes an existing file, never writes
-outside `apps/web/app/[locale]/`, runs no install, and a second run is a
-no-op. `--apply` exits 0 on success.
+scaffold's). It never rewrites or deletes an existing file, writes nothing
+outside `apps/web/app/[locale]/` except the local modules those routes import
+(below), runs no install, and a second run is a no-op. `--apply` exits 0 on success.
 
 **Scope.** Every core route (`about`, `contact`, `faq`, `thanks/[slug]`,
 `sign-in`) is always checked, and so is the `(authed)` route GROUP —
@@ -232,17 +239,30 @@ gated off at scaffold time is listed as skipped, not missing — its absence is
 deliberate, not drift. Add a surface with `--sync-architecture` and the
 `add-page` skill, not with `sync-routes`.
 
-**The lib-and-messages dependency contract (#5014).** Some routes import
-files OUTSIDE their own route directory — `sign-in/page.tsx` imports
-`apps/web/lib/auth-env.ts` and `lib/site-brand.tsx`; the `(authed)` group's
-`layout.tsx` imports `apps/web/auth.ts`; `(authed)/account/page.tsx` imports
-`lib/account-config.ts`, `lib/server-api.ts`, and two files from its
-`(authed)/waitlist` sibling (`components/ForbiddenState.tsx`, `format.ts`).
-Copying a route's directory alone would leave those imports dangling in an
-older consumer that never had them. `ROUTE_DEPENDENCIES` in `src/surfaces.ts`
-declares them per route; `sync-routes` copies each one `--apply` finds
-missing (never overwriting — the same rule routes themselves follow) and
-reports it in check mode under an `Also required` heading. `ROUTE_MESSAGE_NAMESPACES`
+**The local-module dependency contract (#5014, #9406).** Some routes import
+files OUTSIDE their own route directory — `purchase/success/page.tsx` imports
+`apps/web/src/lib/commerce-claim.ts`; the `(authed)` group's `layout.tsx`
+imports `apps/web/auth.ts`. Copying a route's directory alone would leave those
+imports dangling in an older consumer that never had them. So `sync-routes`
+resolves every relative import (`./`, `../`) of every file the route would
+copy, and of every helper that brings in turn, against the site first and then
+the template. `ROUTE_DEPENDENCIES` in `src/surfaces.ts` is a declared
+supplement, unioned with what the resolver finds. Each imported module has one
+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`.
+- **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.
+- **Refused** — the import resolves to no file in the site or the template,
+  only to a spoke-excluded file, or to a surface the site does not carry: the
+  route is listed under `cannot resolve:` and `--apply` does not write it, nor
+  its sub-routes, nor a route that imports from it. Its ancestor route is still
+  copied without the refused sub-tree.
+
+`ROUTE_MESSAGE_NAMESPACES`
 does the same for the i18n namespaces a route's copy needs
 (`signIn`, `account`, `waitlistDashboard.gate`) — but CHECK-ONLY: a
 consumer's `apps/web/messages/<locale>.json` already exists and may carry
@@ -483,6 +503,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`).
@@ -493,7 +524,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
@@ -502,9 +536,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
@@ -513,7 +548,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.
@@ -544,10 +579,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 };
     });
@@ -351,7 +353,9 @@ export function formatAddModuleReport(result, moduleName) {
     const lines = [
         `[create-ailk] add-module ${moduleName} → ${result.targetDir}`,
     ];
-    if (result.report.length === 0 && result.routes.applied.length === 0) {
+    if (result.report.length === 0 &&
+        result.routes.applied.length === 0 &&
+        result.routes.refused.length === 0) {
         lines.push(`Nothing to add — the site already carries everything ${moduleName} brings.`);
     }
     if (written.length > 0) {
@@ -387,6 +391,9 @@ export function formatAddModuleReport(result, moduleName) {
         lines.push(`Also copied ${routes.appliedDependencies.length} file(s) those routes import:`);
         lines.push(...routes.appliedDependencies.map((dep) => `  ${dep}`));
     }
+    if (routes.refused.length > 0) {
+        lines.push(`Routes not copied (${routes.refused.length}) — an import does not resolve (run create-ailk sync-routes for the paths): ${routes.refused.join(", ")}`);
+    }
     if (routes.missingMessageNamespaces.length > 0) {
         lines.push("Also required — message namespace(s) not found in apps/web/messages/en.json (add manually, not auto-merged):");
         lines.push(...routes.missingMessageNamespaces.map((ns) => `  ${ns}`));

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

@@ -226,13 +226,16 @@ export function formatAddRouteReport(result) {
     const skipped = result.report.filter((row) => row.action === "skipped");
     const routes = result.routes ?? {
         applied: [],
+        refused: [],
         appliedDependencies: [],
         missingMessageNamespaces: [],
     };
     const lines = [
         `[create-ailk] add-route ${result.route} → ${result.targetDir}`,
     ];
-    if (result.report.length === 0 && routes.applied.length === 0) {
+    if (result.report.length === 0 &&
+        routes.applied.length === 0 &&
+        routes.refused.length === 0) {
         lines.push(`Nothing to add — the site already carries the ${result.route} route.`);
     }
     if (routes.applied.length > 0) {
@@ -243,6 +246,9 @@ export function formatAddRouteReport(result) {
         lines.push(`Also copied ${routes.appliedDependencies.length} file(s) those routes import:`);
         lines.push(...routes.appliedDependencies.map((dep) => `  ${dep}`));
     }
+    if (routes.refused.length > 0) {
+        lines.push(`Routes not copied (${routes.refused.length}) — an import does not resolve (run create-ailk sync-routes for the paths): ${routes.refused.join(", ")}`);
+    }
     if (written.length > 0) {
         lines.push(`Written (${written.length}):`);
         lines.push(...written.map((row) => `  ${row.path}`));
@@ -308,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);
@@ -322,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);
@@ -376,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) {
@@ -501,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";
 }
@@ -542,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).