create-ailk 0.2.0 → 0.4.0

package/dist/parse-args.d.ts

@@ -7,16 +7,23 @@
  * composition is downstream work, so the default (`marketing`) reproduces
  * today's fixed-tree scaffold exactly.
  */
-export declare const RECOGNIZED_MODULES: readonly ["marketing", "docs", "multi-tenant", "scheduling"];
+export declare const RECOGNIZED_MODULES: readonly ["marketing", "docs-blog", "multi-tenant", "workspace", "scheduling", "signal-collectors", "commerce"];
 export type ModuleName = (typeof RECOGNIZED_MODULES)[number];
 export interface CliOptions {
     /** Positional target directory (the dir to scaffold into). Optional only
      *  when `help` or `version` is set. */
     target: string | undefined;
+    /**
+     * The site template to install (`--template`), validated against
+     * `RECOGNIZED_TEMPLATES` at parse time. Undefined when the flag is absent —
+     * and a run naming no template scaffolds exactly what it did before the
+     * flag existed (spec 5481 § 3 DD3).
+     */
+    template: string | undefined;
     install: boolean;
     help: boolean;
     version: boolean;
-    /** Selected modules (recognized: marketing, docs, multi-tenant, scheduling).
+    /** Selected modules (recognized: marketing, docs-blog, multi-tenant, scheduling).
      *  Defaults to ['marketing'] when the flag is absent. */
     modules: string[];
     /** Explicitly requested route surfaces (`--surfaces`). Empty when the flag is

package/dist/parse-args.js

@@ -9,6 +9,7 @@
  */
 import { parseArgs } from "node:util";
 import { RECOGNIZED_SURFACES, parseSurfaces } from "./surfaces.js";
+import { RECOGNIZED_TEMPLATES } from "./template-names.js";
 /**
  * The recognized module vocabulary for the `--modules` selector.
  *
@@ -20,9 +21,12 @@ import { RECOGNIZED_SURFACES, parseSurfaces } from "./surfaces.js";
  */
 export const RECOGNIZED_MODULES = [
     "marketing",
-    "docs",
+    "docs-blog",
     "multi-tenant",
+    "workspace",
     "scheduling",
+    "signal-collectors",
+    "commerce",
 ];
 /** The default module selection when `--modules` is absent (reproduces today's scaffold). */
 const DEFAULT_MODULES = ["marketing"];
@@ -49,6 +53,16 @@ Options:
                            Defaults to \`marketing\`, which reproduces today's
                            scaffold. A module is a composable unit across the
                            three tiers (data · API · presentation).
+  --template <name>        The site template to install (recognized:
+                           ${RECOGNIZED_TEMPLATES.join(", ")}).
+                           A template is a page roster plus seed content and
+                           config — never code. Its required modules are ADDED
+                           to whatever \`--modules\` names, so the two compose.
+                           A template needing only free modules installs from
+                           the tree this package ships, with no key and no
+                           network call; one needing a paid module needs
+                           AILK_LICENSE_KEY to cover every module it requires,
+                           and refuses naming whichever it does not.
   --surfaces <csv>         Comma-separated route surfaces to scaffold IN
                            ADDITION to the core set (/, /about, /contact, /faq,
                            /thanks). Recognized: ${RECOGNIZED_SURFACES.join(", ")}.
@@ -100,6 +114,7 @@ export function parseCliArgs(argv) {
             allowPositionals: true,
             options: {
                 modules: { type: "string" },
+                template: { type: "string" },
                 surfaces: { type: "string" },
                 "sync-architecture": { type: "string" },
                 "sync-catalog": { type: "boolean", default: false },
@@ -117,6 +132,7 @@ export function parseCliArgs(argv) {
     const version = parsed.values.version === true;
     const install = parsed.values.install === true;
     const modules = parseModules(parsed.values.modules);
+    const template = parseTemplate(parsed.values.template);
     const surfaces = parseSurfaceList(parsed.values.surfaces);
     const syncArchitecture = parsed.values["sync-architecture"];
     const syncCatalog = parsed.values["sync-catalog"] === true;
@@ -136,6 +152,7 @@ export function parseCliArgs(argv) {
     if (help || version) {
         return {
             target: undefined,
+            template: undefined,
             install,
             help,
             version,
@@ -153,6 +170,7 @@ export function parseCliArgs(argv) {
         }
         return {
             target: parsed.positionals[0],
+            template,
             install,
             help,
             version,
@@ -171,6 +189,7 @@ export function parseCliArgs(argv) {
     }
     return {
         target: parsed.positionals[0],
+        template,
         install,
         help,
         version,
@@ -181,6 +200,32 @@ export function parseCliArgs(argv) {
         syncArchitecture: undefined,
     };
 }
+/**
+ * Validate the `--template` value against the declared template set
+ * (spec 5481 § 3 DD1).
+ *
+ * Validated HERE, in the parser, so an unrecognized template fails at parse
+ * time as a `ParseError` exactly like an unrecognized module or surface does.
+ * Splitting it out to `programmatic.ts` would make `--template` the one flag
+ * in this CLI whose bad value surfaces somewhere else.
+ *
+ * The names come from `template-names.ts` rather than from
+ * `TEMPLATE_MANIFESTS` itself, and that file's doc comment records the
+ * measured reason: importing the registry here closes a runtime cycle
+ * through `lib/module-tier.ts`. `TEMPLATE_MANIFESTS` remains the registry;
+ * the two sets are asserted equal by the suite.
+ *
+ * @throws ParseError on an undeclared template name, naming the declared set.
+ */
+function parseTemplate(raw) {
+    if (raw === undefined)
+        return undefined;
+    const name = raw.trim();
+    if (!RECOGNIZED_TEMPLATES.includes(name)) {
+        throw new ParseError(`unknown template "${raw}". Recognized: ${RECOGNIZED_TEMPLATES.join(", ")}`);
+    }
+    return name;
+}
 /**
  * Parse + validate the `--surfaces` CSV, re-throwing an unrecognized-surface
  * failure as a ParseError so every CLI parse failure reaches the orchestrator's

package/dist/programmatic.d.ts

@@ -29,7 +29,23 @@ export interface ScaffoldOptions {
      */
     preset?: string;
     /**
-     * Selected modules (recognized: marketing, docs, multi-tenant). Defaults to
+     * The site template to install (`--template`), a `TEMPLATE_MANIFESTS` key.
+     *
+     * Consumed ONLY by the async `scaffold()` below. `scaffoldSync` stays
+     * template-oblivious for exactly the reason it stays licensing-oblivious
+     * (spec 5481 § 3 DD3): a call naming no template takes a code path with no
+     * new statement in it, which is a stronger byte-identity guarantee than a
+     * test asserting the output happens to match.
+     *
+     * What a template DOES change is `modules` — `scaffold()` unions the
+     * template's `requires` with whatever `--modules` named and passes THAT
+     * list to `scaffoldSync` (DD2), so the resolved surfaces, the emitted
+     * `architecture.yaml` and the generated nav are all functions of the union.
+     */
+    template?: string;
+    /**
+     * Selected modules (recognized: marketing, docs-blog, multi-tenant,
+     * scheduling). Defaults to
      * ['marketing']. The scaffolder does NOT yet vary the copied template tree by
      * module (per-module template composition is downstream work), so the copied
      * files are today's fixed-tree scaffold — BUT the derived `architecture.yaml`
@@ -69,6 +85,8 @@ export interface ScaffoldOptions {
     licenseKey?: string;
     /** Overrides `AILK_MODULE_REGISTRY_URL` / the built-in module-distribution default. */
     moduleRegistryUrl?: string;
+    /** Overrides `AILK_TEMPLATE_REGISTRY_URL` / the built-in template-distribution default. */
+    templateRegistryUrl?: string;
     /** Injected fetch for tests. Never a live network call in CI or in this repo's evidence runs. */
     fetchImpl?: typeof fetch;
 }
@@ -97,9 +115,17 @@ export declare function scaffoldSync(opts: ScaffoldOptions): ScaffoldResult;
  *      read and no network call (the regression floor). A paid module with
  *      no key, or a licence the module distribution rejects, throws
  *      `LicenseRequiredError` HERE — before anything is written to disk.
- *   3. `scaffoldSync` — unchanged, today's local `templates/` copy.
+ *   3. `scaffoldSync` — unchanged, today's local `templates/` copy, over the
+ *      EFFECTIVE module set (see 0 below).
  *   4. Merge each resolved paid module's fetched bundle into the freshly
  *      scaffolded tree (`extractModuleBundle`).
+ *   5. Install the named site template LAST (#5481; parent record D9), from
+ *      its fetched bundle or — when it requires only free modules — from the
+ *      `site-templates/` tree this package ships.
+ *
+ * And, ahead of all five when `opts.template` is set (0): resolve the
+ * template and union its `requires` with `opts.modules`, so every step above
+ * runs over the EFFECTIVE module set rather than the requested one.
  *
  * `scaffoldSync` itself stays licensing-oblivious on purpose: every existing
  * synchronous caller (this package's own test suite, overwhelmingly) is

package/dist/programmatic.js

@@ -21,15 +21,26 @@ import { fileURLToPath } from "node:url";
 import { CATALOG_TARGET_PATH, writeComponentCatalog, } from "./component-catalog.js";
 import { copyTemplate } from "./copy.js";
 import { deriveArchitecture } from "./derive-architecture.js";
-import { extractModuleBundle } from "./lib/extract-module-bundle.js";
+import { extractModuleBundle, installBundleTree, } from "./lib/extract-module-bundle.js";
+import { fetchTemplate } from "./lib/fetch-template.js";
 import { resolvePaidModules } from "./lib/module-license-gate.js";
 import { classifyModules } from "./lib/module-tier.js";
 import { normalizeModules } from "./module-architecture.js";
 import { NAV_CONFIG_PATH, excludedRoutePaths, renderNavConfig, resolveSurfaces, } from "./surfaces.js";
 import { syncRoutes } from "./sync-routes.js";
+import { resolveTemplate, templateDelivery } from "./template-manifest.js";
 import { validateTarget } from "./validate.js";
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const TEMPLATES_DIR = resolve(PKG_ROOT, "templates");
+/**
+ * Where a Free site template's files are read from on the keyless path — and
+ * why it is BESIDE `templates/` rather than inside it (parent record D14):
+ * `copyTemplate` copies the whole `templates/` tree into EVERY scaffold, so a
+ * per-template subtree there would land in scaffolds that asked for a
+ * different template, or for none. It reaches the published tarball through
+ * `package.json` `files` instead.
+ */
+const SITE_TEMPLATES_DIR = resolve(PKG_ROOT, "site-templates");
 const VERSIONS_FILE = resolve(PKG_ROOT, "versions.json");
 function readVersionMap() {
     if (!existsSync(VERSIONS_FILE)) {
@@ -114,9 +125,17 @@ export function scaffoldSync(opts) {
  *      read and no network call (the regression floor). A paid module with
  *      no key, or a licence the module distribution rejects, throws
  *      `LicenseRequiredError` HERE — before anything is written to disk.
- *   3. `scaffoldSync` — unchanged, today's local `templates/` copy.
+ *   3. `scaffoldSync` — unchanged, today's local `templates/` copy, over the
+ *      EFFECTIVE module set (see 0 below).
  *   4. Merge each resolved paid module's fetched bundle into the freshly
  *      scaffolded tree (`extractModuleBundle`).
+ *   5. Install the named site template LAST (#5481; parent record D9), from
+ *      its fetched bundle or — when it requires only free modules — from the
+ *      `site-templates/` tree this package ships.
+ *
+ * And, ahead of all five when `opts.template` is set (0): resolve the
+ * template and union its `requires` with `opts.modules`, so every step above
+ * runs over the EFFECTIVE module set rather than the requested one.
  *
  * `scaffoldSync` itself stays licensing-oblivious on purpose: every existing
  * synchronous caller (this package's own test suite, overwhelmingly) is
@@ -124,23 +143,106 @@ export function scaffoldSync(opts) {
  * with a paid module in `opts.modules` exercises the gate at all.
  */
 export async function scaffold(opts) {
-    const { paid } = classifyModules(normalizeModules(opts.modules ?? ["marketing"]));
+    // Resolved first, and by the registry rather than re-validated here: the
+    // name already passed `parse-args.ts`, and `resolveTemplate` throws a
+    // `TemplateError` for a programmatic caller that skipped the parser.
+    const template = opts.template !== undefined ? resolveTemplate(opts.template) : undefined;
+    // The effective module set: union(template.requires, parsed --modules),
+    // normalized through `normalizeModules` — the single ordering authority
+    // (parent record D7). Order-independence falls out rather than being
+    // engineered: it returns `RECOGNIZED_MODULES.filter(...)`, declaration-
+    // ordered and deduped, so the same SET in any argument order is the same
+    // list.
+    const modules = normalizeModules([
+        ...(template?.requires ?? []),
+        ...(opts.modules ?? ["marketing"]),
+    ]);
+    const { paid } = classifyModules(modules);
     const bundles = await resolvePaidModules({
         paidModules: paid,
         licenseKey: opts.licenseKey,
+        ...(template !== undefined ? { templateName: template.name } : {}),
         ...(opts.moduleRegistryUrl !== undefined
             ? { registryUrl: opts.moduleRegistryUrl }
             : {}),
         ...(opts.fetchImpl !== undefined ? { fetchImpl: opts.fetchImpl } : {}),
     });
-    const result = scaffoldSync(opts);
+    // The template's OWN bundle, fetched here — before `scaffoldSync` — so the
+    // fourth refusal (the template's bundle unpublished, parent record D17 /
+    // spec 5481 § 3 DD5 row 4) throws with the target still non-existent, like
+    // the three module refusals above it (DD6). It is EXTRACTED last, below.
+    //
+    // The keyless path never reaches this at all: a template requiring only
+    // free modules classifies to an empty paid set, so `resolvePaidModules`
+    // returned at its first branch without reading `process.env` or the
+    // network, and `templateDelivery` sends us past this too (DD7). That is
+    // what makes record D11's no-network guarantee structural rather than
+    // merely likely.
+    const templateBundle = template !== undefined && templateDelivery(template) === "paid"
+        ? await fetchTemplate({
+            templateName: template.name,
+            token: opts.licenseKey ?? process.env["AILK_LICENSE_KEY"] ?? "",
+            ...(opts.templateRegistryUrl !== undefined
+                ? { registryUrl: opts.templateRegistryUrl }
+                : {}),
+            ...(opts.fetchImpl !== undefined ? { fetchImpl: opts.fetchImpl } : {}),
+        })
+        : undefined;
+    // `modules` — the union — is what `scaffoldSync` receives, not `opts`
+    // (spec 5481 § 3 DD2). `resolveSurfaces`, `deriveArchitecture` and
+    // `renderNavConfig` are all computed INSIDE `scaffoldSync` from
+    // `opts.modules`, so a union computed for the licence classification alone
+    // would gate correctly and emit the wrong surfaces, the wrong
+    // `architecture.yaml` and the wrong nav — a silent wrong result, not a
+    // failure.
+    const result = scaffoldSync({ ...opts, modules });
+    // Threaded to extractModuleBundle for `package.json` patch targets'
+    // `workspace:*` substitution (spec 5418 § 3 D2) — the same version map
+    // `scaffoldSync` already reads for `copyTemplate`, re-read here since
+    // `scaffold()` doesn't share `scaffoldSync`'s call frame.
+    const versions = readVersionMap();
     for (const [moduleName, bytes] of bundles) {
         await extractModuleBundle({
             bytes,
             targetDir: result.targetDir,
             moduleName,
+            versions,
         });
     }
+    // The template lands LAST — after `scaffoldSync` and after every module
+    // bundle (parent record D9) — so its content and config files sit on top of
+    // everything derived. It shapes the derived artifacts by DECLARING (its
+    // `requires` are in the union above; its roster rows are what the nav is
+    // generated from), never by landing a code file: the nav is already written
+    // by `scaffoldSync` from `renderNavConfig(enabledSurfaces)`, and record
+    // §5.2 forbids a `.ts` in any `site-templates/` `installMap` destination.
+    //
+    // One install step, two source roots (DD7): an extracted staging dir on the
+    // paid path, `site-templates/<name>/` on disk on the Free one.
+    if (template !== undefined) {
+        if (templateBundle !== undefined) {
+            await extractModuleBundle({
+                bytes: templateBundle,
+                targetDir: result.targetDir,
+                moduleName: template.name,
+                templateRequires: template.requires,
+                versions,
+            });
+        }
+        else {
+            const sourceRoot = join(SITE_TEMPLATES_DIR, template.name);
+            if (!existsSync(sourceRoot)) {
+                throw new Error(`template "${template.name}": ${sourceRoot} is missing — the published package must carry site-templates/ in its "files" list`);
+            }
+            installBundleTree({
+                sourceRoot,
+                targetDir: result.targetDir,
+                name: template.name,
+                templateRequires: template.requires,
+                versions,
+            });
+        }
+    }
     return result;
 }
 // Re-exported so a consumer of the async `scaffold()` above can type its own
@@ -194,10 +296,15 @@ export function syncArchitectureSync(opts) {
  * stats paths and returns strings, and never writes or deletes.
  *
  * Routes only, deliberately. A surface's content directories are informational
- * (`Surface.content`), not drift: `apps/web/content/<locale>/{blog,docs}` must
- * exist in EVERY scaffold — `source.config.ts` resolves those paths at build
- * time whether or not the route is mounted — so sweeping content here would
- * tell every operator to delete directories the build requires.
+ * (`Surface.content`), not drift, so sweeping content here would tell an
+ * operator to delete directories that merely hold their own copy.
+ *
+ * This used to rest on a stronger claim — that `apps/web/content/<locale>/
+ * {blog,docs}` must exist in EVERY scaffold, because `source.config.ts`
+ * resolved those paths at build time whether or not the route mounted. D-46
+ * retired it: `source.config.ts` leaves with the docs + blog module (#5365 D3),
+ * so a Free scaffold defines no Fumadocs collection and carries neither
+ * directory.
  */
 function findUndeclaredSurfacePaths(targetAbs, enabled) {
     return excludedRoutePaths(enabled)

package/dist/surfaces.d.ts

@@ -1,36 +1,3 @@
-/**
- * Route-surface registry — which public routes a scaffolded site carries.
- *
- * A SURFACE is one public route surface of the presentation tier (see
- * architecture.yaml `composition_model`): a hub route plus the detail route and
- * content directories that feed it. The registry is the single source of the
- * surface vocabulary, in the same spirit as `module-architecture.ts` is the
- * single source of the module→architecture-slice mapping — a code registry, not
- * N hand-maintained template trees.
- *
- * Two tiers:
- *
- *   - CORE_SURFACE_PATHS — the routes every AILK site has regardless of what
- *     the business is (`/`, `/about`, `/contact`, `/faq`, `/thanks/{slug}`).
- *     Always scaffolded, never gateable.
- *   - GATEABLE_SURFACES — everything else. A surface is scaffolded ONLY when
- *     the declared architecture carries it; otherwise its route directories are
- *     skipped by `copyTemplate` and the routes are ABSENT from the scaffold,
- *     not present-and-placeholdering (spec #4154 D1).
- *
- * The default (`--modules marketing`) enables NO gateable surface: every one of
- * them is a claim about the business that the scaffolder cannot make. The path
- * from there is the `suggest-site-pages` → `scaffold-page` skill pair that
- * already ships in `templates/.claude/skills/`.
- *
- * Zero runtime dependencies — create-ailk is a published, standalone CLI.
- *
- * Deliberately imports nothing from `parse-args.ts`: that module imports THIS
- * one (for the `--surfaces` vocabulary in its help text), so a back-import
- * would close a cycle. The module vocabulary is re-stated here as the keys of
- * `MODULE_SURFACES`, and `__tests__/surface-gating.test.ts` asserts those keys
- * equal `RECOGNIZED_MODULES` so the two cannot drift.
- */
 /**
  * Route paths (site-relative, for the record written into `architecture.yaml`)
  * that every scaffold carries.
@@ -88,9 +55,18 @@ export declare const RECOGNIZED_SURFACES: readonly string[];
  * Surfaces each recognized module contributes.
  *
  * `marketing` (the default) contributes NONE — a default scaffold is core-only.
- * `docs` mounts the Fumadocs presentation surface; `multi-tenant` brings the
- * flow-stepper surface with its API-backed engine; `scheduling` brings the
- * booking page and the confirmation page the module owns.
+ * `docs-blog` mounts BOTH Fumadocs presentation surfaces: D-46 made docs and
+ * blog one Pro module, so `/blog` is no longer a Free surface that any scaffold
+ * can turn on. `multi-tenant` contributes no surface of its own — it USED to
+ * carry `flows`, but D-48 reassigns that surface to `signal-collectors`
+ * (#5366), which now brings the flow-stepper surface with its API-backed
+ * engine; `scheduling` brings the booking page and the confirmation page the
+ * module owns.
+ *
+ * A surface named here is MODULE-GATED: `resolveSurfaces` refuses it as an
+ * explicit `--surfaces` value unless the module that owns it was selected
+ * (#5365 FR5). Without that, `--surfaces blog` on a keyless scaffold would
+ * declare a surface whose route files the starter no longer contains.
  */
 export declare const MODULE_SURFACES: Record<string, readonly string[]>;
 /** Thrown on an unrecognized surface id. Mirrors parse-args' ParseError shape. */

package/dist/surfaces.js

@@ -164,6 +164,19 @@ export const GATEABLE_SURFACES = [
         routes: [`${ROUTE_ROOT}/partners`],
         content: ["content/<locale>/PartnersList", "content/<locale>/Partner"],
     },
+    {
+        // Module-LESS by construction (#5479 D16): no MODULE_SURFACES value names
+        // it, so a site template may enable it by roster alone. Same for
+        // `privacy` and `terms` below.
+        id: "pricing",
+        routes: [`${ROUTE_ROOT}/pricing`],
+        content: ["content/<locale>/Pricing"],
+    },
+    {
+        id: "privacy",
+        routes: [`${ROUTE_ROOT}/privacy`],
+        content: ["content/<locale>/PrivacyPage"],
+    },
     {
         id: "products",
         routes: [`${ROUTE_ROOT}/products`],
@@ -208,6 +221,11 @@ export const GATEABLE_SURFACES = [
         routes: [`${ROUTE_ROOT}/tech-articles`],
         content: ["content/<locale>/TechArticle"],
     },
+    {
+        id: "terms",
+        routes: [`${ROUTE_ROOT}/terms`],
+        content: ["content/<locale>/TermsPage"],
+    },
     {
         id: "testimonials",
         routes: [`${ROUTE_ROOT}/testimonials`],
@@ -230,15 +248,32 @@ export const RECOGNIZED_SURFACES = GATEABLE_SURFACES.map((s) => s.id);
  * Surfaces each recognized module contributes.
  *
  * `marketing` (the default) contributes NONE — a default scaffold is core-only.
- * `docs` mounts the Fumadocs presentation surface; `multi-tenant` brings the
- * flow-stepper surface with its API-backed engine; `scheduling` brings the
- * booking page and the confirmation page the module owns.
+ * `docs-blog` mounts BOTH Fumadocs presentation surfaces: D-46 made docs and
+ * blog one Pro module, so `/blog` is no longer a Free surface that any scaffold
+ * can turn on. `multi-tenant` contributes no surface of its own — it USED to
+ * carry `flows`, but D-48 reassigns that surface to `signal-collectors`
+ * (#5366), which now brings the flow-stepper surface with its API-backed
+ * engine; `scheduling` brings the booking page and the confirmation page the
+ * module owns.
+ *
+ * A surface named here is MODULE-GATED: `resolveSurfaces` refuses it as an
+ * explicit `--surfaces` value unless the module that owns it was selected
+ * (#5365 FR5). Without that, `--surfaces blog` on a keyless scaffold would
+ * declare a surface whose route files the starter no longer contains.
  */
 export const MODULE_SURFACES = {
     marketing: [],
-    docs: ["docs"],
-    "multi-tenant": ["flows"],
+    "docs-blog": ["docs", "blog"],
+    "multi-tenant": [],
+    // `workspace` contributes zero gateable surfaces (#5371 D4): every route it
+    // owns lives in the `(authed)` segment, never in the public marketing route
+    // tree a template's roster composes — the same reason `multi-tenant` above
+    // carries an empty list. The entry itself is still required: surface-gating's
+    // vocabulary assertion covers exactly the recognized module set.
+    workspace: [],
     scheduling: ["schedule"],
+    "signal-collectors": ["flows"],
+    commerce: [],
 };
 /** Thrown on an unrecognized surface id. Mirrors parse-args' ParseError shape. */
 export class SurfaceError extends Error {
@@ -290,14 +325,33 @@ export function resolveSurfaces(modules = ["marketing"], explicit = []) {
         for (const s of contributed)
             set.add(s);
     }
+    const selected = new Set(modules.map((m) => m.trim().toLowerCase()));
     for (const s of explicit) {
         if (!RECOGNIZED_SURFACES.includes(s)) {
             throw new SurfaceError(`unknown surface "${s}". Recognized: ${RECOGNIZED_SURFACES.join(", ")}`);
         }
+        // A surface a module OWNS cannot be declared without that module (#5365
+        // FR5/D12). The starter no longer carries the route files, so a bare
+        // `--surfaces blog` would declare a surface that serves 404 with no error
+        // anywhere — the silent-wrong-result this refusal closes. Keyed on
+        // MODULE_SURFACES, never on a surface id, so every module inherits it.
+        const owner = moduleOwningSurface(s);
+        if (owner !== undefined && !selected.has(owner)) {
+            throw new SurfaceError(`surface "${s}" is delivered by the "${owner}" module — add it with ` +
+                `--modules ${owner} (a paid module also needs AILK_LICENSE_KEY).`);
+        }
         set.add(s);
     }
     return [...set].sort();
 }
+/** The module that owns a gateable surface, or undefined if no module does. */
+function moduleOwningSurface(surface) {
+    for (const [moduleName, contributed] of Object.entries(MODULE_SURFACES)) {
+        if (contributed.includes(surface))
+            return moduleName;
+    }
+    return undefined;
+}
 /**
  * The template-relative route directories to SKIP when copying the template —
  * every gateable surface not in `enabled`.
@@ -379,6 +433,11 @@ export const ROUTE_SINCE = {
     "launch-service": "0.0.0",
     partners: "0.0.0",
     "partners/[slug]": "0.0.0",
+    // #5479 — three genuinely new route directories, so they attach at today's
+    // fixed-group version rather than the "predates the manifest" 0.0.0 above,
+    // the same rule #5048 ("projects/apply") and #5014 ("(authed)") applied.
+    pricing: "0.22.0",
+    privacy: "0.22.0",
     products: "0.0.0",
     "products/[slug]": "0.0.0",
     projects: "0.0.0",
@@ -398,6 +457,7 @@ export const ROUTE_SINCE = {
     "software/[slug]": "0.0.0",
     "tech-articles": "0.0.0",
     "tech-articles/[slug]": "0.0.0",
+    terms: "0.22.0",
     testimonials: "0.0.0",
     "thanks/[slug]": "0.14.0",
     "use-cases": "0.0.0",
@@ -414,6 +474,12 @@ export const ROUTE_SINCE = {
     // choice #5048's "projects/apply" entry already made for the same reason.
     "(authed)": "0.18.0",
     "(authed)/account": "0.18.0",
+    // #5371 — the workspace module's three settings routes. Genuinely new route
+    // directories, so they attach at today's fixed-group version rather than the
+    // "predates the manifest" 0.0.0 above, the same rule #5479 and #5048 applied.
+    "(authed)/workspace": "0.22.1",
+    "(authed)/workspace/site": "0.22.1",
+    "(authed)/workspace/team": "0.22.1",
     "(authed)/waitlist": "0.18.0",
     "(authed)/waitlist/[experimentId]": "0.18.0",
     "(authed)/waitlist/[experimentId]/signups/[leadId]": "0.18.0",
@@ -460,6 +526,9 @@ export const ROUTE_DEPENDENCIES = {
         `${ROUTE_ROOT}/(authed)/waitlist/components/ForbiddenState.tsx`,
         `${ROUTE_ROOT}/(authed)/waitlist/format.ts`,
     ],
+    "(authed)/workspace": ["apps/web/lib/server-api.ts"],
+    "(authed)/workspace/site": ["apps/web/lib/server-api.ts"],
+    "(authed)/workspace/team": ["apps/web/lib/server-api.ts"],
     "(authed)/waitlist": ["apps/web/lib/server-api.ts"],
 };
 /**
@@ -474,6 +543,9 @@ export const ROUTE_DEPENDENCIES = {
 export const ROUTE_MESSAGE_NAMESPACES = {
     "sign-in": ["signIn"],
     "(authed)/account": ["account"],
+    "(authed)/workspace": ["workspace"],
+    "(authed)/workspace/site": ["workspace"],
+    "(authed)/workspace/team": ["workspace"],
     "(authed)/waitlist": ["waitlistDashboard.gate"],
 };
 /** Template-relative path of the generated site-nav registry. */

package/dist/sync-routes.js

@@ -35,6 +35,18 @@ import { substituteMarkers } from "./substitute.js";
 import { GATEABLE_SURFACES, NON_ROUTE_DIRS, ROUTE_DEPENDENCIES, ROUTE_MESSAGE_NAMESPACES, ROUTE_SINCE, surfaceForRouteDir, } from "./surfaces.js";
 /** Template-relative prefix every `apps/web` route directory sits under. */
 const ROUTE_ROOT = "apps/web/app/[locale]";
+/**
+ * `<surface id>/<entry name>` pairs that live directly under a GATEABLE
+ * surface's top-level directory but belong to a DIFFERENT module (#5366).
+ * `projects/apply` (#5048) is signal-collectors' own owned file
+ * (`ListingApplicationClient.tsx`, D-48) — its module bundle restores it
+ * whenever signal-collectors is selected, independent of the unrelated
+ * "projects" content surface's own selection. See the doc comment on
+ * `syncRoutes`'s `carried` computation.
+ */
+const NESTED_FOREIGN_MODULE_ENTRIES = new Set([
+    "projects/apply",
+]);
 /**
  * The template's route directories, ROUTE_ROOT-relative and sorted.
  *
@@ -120,12 +132,30 @@ export function syncRoutes(opts) {
         throw new Error(`not a scaffolded repo: no architecture.yaml at ${targetAbs}. Run \`create-ailk <target-dir>\` to scaffold first.`);
     }
     // Presence of any of a surface's route dirs means the site carries it.
+    // A surface's directory containing ONLY entries in
+    // `NESTED_FOREIGN_MODULE_ENTRIES` does not count as present (#5366): a
+    // DIFFERENT module can own a companion sub-route nested under an unrelated
+    // content surface's URL segment — `projects/apply` (#5048) is
+    // signal-collectors' own owned file (D-48), and its module bundle restores
+    // it whenever signal-collectors is selected, regardless of whether the
+    // unrelated "projects" CONTENT surface is separately requested. Without
+    // this exclusion, a signal-collectors-only scaffold would falsely read as
+    // "carries projects" the moment its bundle lands that one file.
     const carried = new Set();
     const skippedSurfaces = [];
     for (const surface of GATEABLE_SURFACES) {
         const present = surface.routes.some((r) => {
             const p = join(targetAbs, r);
-            return existsSync(p) && statSync(p).isDirectory();
+            if (!existsSync(p) || !statSync(p).isDirectory())
+                return false;
+            const entries = readdirSync(p);
+            // An ancestor dir left empty by a consumer-side deletion (AC-2's
+            // "ancestor also missing" case) still counts as carried — only a
+            // NON-empty directory whose entries are entirely foreign (the
+            // `projects`/`apply` case above) does not.
+            if (entries.length === 0)
+                return true;
+            return entries.some((name) => !NESTED_FOREIGN_MODULE_ENTRIES.has(`${surface.id}/${name}`));
         });
         if (present)
             carried.add(surface.id);