create-ailk 0.3.0 → 0.5.0

package/dist/parse-args.d.ts

@@ -7,12 +7,19 @@
  * composition is downstream work, so the default (`marketing`) reproduces
  * today's fixed-tree scaffold exactly.
  */
-export declare const RECOGNIZED_MODULES: readonly ["marketing", "docs-blog", "multi-tenant", "scheduling", "signal-collectors", "commerce"];
+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;

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.
  *
@@ -22,6 +23,7 @@ export const RECOGNIZED_MODULES = [
     "marketing",
     "docs-blog",
     "multi-tenant",
+    "workspace",
     "scheduling",
     "signal-collectors",
     "commerce",
@@ -51,9 +53,23 @@ 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(", ")}.
+                           ADDITION to the core set (/, /about, /contact, /faq).
+                           /thanks/{slug} ships with every scaffold too, but it
+                           is not a surface you select here — it is a per-form
+                           confirmation page, authored when the form that needs
+                           it exists (there is no /thanks hub). Recognized:
+                           ${RECOGNIZED_SURFACES.join(", ")}.
                            Surfaces the declared architecture does not carry are
                            NOT scaffolded — their routes are absent, so a fresh
                            site never serves a stock page with placeholder
@@ -102,6 +118,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 },
@@ -119,6 +136,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;
@@ -138,6 +156,7 @@ export function parseCliArgs(argv) {
     if (help || version) {
         return {
             target: undefined,
+            template: undefined,
             install,
             help,
             version,
@@ -155,6 +174,7 @@ export function parseCliArgs(argv) {
         }
         return {
             target: parsed.positionals[0],
+            template,
             install,
             help,
             version,
@@ -173,6 +193,7 @@ export function parseCliArgs(argv) {
     }
     return {
         target: parsed.positionals[0],
+        template,
         install,
         help,
         version,
@@ -183,6 +204,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

@@ -17,6 +17,7 @@
  */
 import { CATALOG_TARGET_PATH } from "./component-catalog.js";
 import { type ModuleName } from "./parse-args.js";
+import { type TemplateLayout } from "./site-chrome.js";
 import { type SyncRoutesResult } from "./sync-routes.js";
 export interface ScaffoldOptions {
     /** Absolute or relative path to the target directory. Must not exist or be empty. */
@@ -28,6 +29,21 @@ export interface ScaffoldOptions {
      * Ignored at runtime until named presets are implemented.
      */
     preset?: string;
+    /**
+     * 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
@@ -70,8 +86,19 @@ 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;
+    /**
+     * Resolved template layout knobs (#5612 D1/D2) — INTERNAL: populated by
+     * `scaffold()` from the resolved template's `layout` block (the code
+     * registry's `TemplateManifest.layout`) before calling `scaffoldSync`. Never
+     * set by a CLI/MCP caller directly. `scaffoldSync` fills every unset field
+     * with `DEFAULT_SITE_CHROME`, so a call naming no `layout` (every existing
+     * caller) writes the same defaults `site-chrome.ts` always has.
+     */
+    layout?: TemplateLayout;
 }
 export interface ScaffoldResult {
     /** Resolved absolute path to the scaffolded directory. */
@@ -98,9 +125,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,27 @@ 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 { SITE_CHROME_PATH, renderSiteChrome, resolveSiteChrome, } from "./site-chrome.js";
+import { GATEABLE_SURFACES, MODULE_SURFACES, NAV_CONFIG_PATH, excludedRoutePaths, renderNavConfig, resolveSurfaces, } from "./surfaces.js";
 import { syncRoutes } from "./sync-routes.js";
+import { BASE_LAYER_DIR, mergeRoster, resolveTemplate, resolveTemplateLineage, 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)) {
@@ -84,6 +96,10 @@ export function scaffoldSync(opts) {
             PROJECT_NAME: projectName,
             COMPANY_NAME: "Your Company",
             COMPANY_DOMAIN: "example.com",
+            // The social-profile handle the Free chrome's footer links carry
+            // (`https://x.com/{{COMPANY_HANDLE}}`, #5469 D5) — a placeholder the
+            // site owner replaces, never the kit vendor's own handle.
+            COMPANY_HANDLE: "yourcompany",
         },
     });
     // Derive + write the module-set-driven architecture.yaml (spec #3787). This
@@ -97,6 +113,12 @@ export function scaffoldSync(opts) {
     // the template's copy in place would link /docs and /blog sitewide in a
     // scaffold that carries neither route.
     writeFileSync(join(targetAbs, NAV_CONFIG_PATH), renderNavConfig(enabledSurfaces));
+    // Site-level chrome knobs (#5612 D2) — beside nav-config.ts, same GENERATED
+    // idiom. `opts.layout` is set only by `scaffold()`, from the resolved
+    // template's `layout` block; a bare `scaffoldSync` call (every existing
+    // synchronous caller) writes DEFAULT_SITE_CHROME, byte-identical to the
+    // monorepo's own committed apps/web/lib/site-chrome.ts.
+    writeFileSync(join(targetAbs, SITE_CHROME_PATH), renderSiteChrome(resolveSiteChrome(opts.layout)));
     // Opt-in only (#4636). Every write above this line is unconditional, so a
     // scaffold with `withCatalog` unset touches exactly the files it did before.
     if (opts.withCatalog === true)
@@ -114,9 +136,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,31 +154,212 @@ 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;
+    // #5618 D2 — the `extends` chain is resolved in the client registry before
+    // any fetch: an unknown parent or a cycle is refused here, with the target
+    // still non-existent, like the four refusals below.
+    if (template !== undefined)
+        resolveTemplateLineage(template.name);
+    // 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.
+    //
+    // The template's roster ENABLES its surfaces (#5469 D10, the #5554 finding).
+    // A template's module-less rows (`/pricing`, `/privacy`, `/terms`) name
+    // `GATEABLE_SURFACES` entries no module contributes, and until this line
+    // `mergeRoster` was dead on this path: the content landed, the route
+    // directories were skipped, and the three pages 404ed. The merged roster's
+    // routes select their surface entries — matched on each surface's own
+    // `routes[]`, never on a new field — and that set rides `opts.surfaces`
+    // into `scaffoldSync`'s existing `resolveSurfaces` call, so the copied
+    // tree, the emitted `architecture.yaml` and the generated nav all follow.
+    // A scaffold naming no template takes no new statement (parent § D16): the
+    // roster-derived set is only ever computed when `template` is set.
+    const surfaces = template !== undefined
+        ? [...new Set([...(opts.surfaces ?? []), ...rosterSurfaces(template)])].sort()
+        : opts.surfaces;
+    const result = scaffoldSync({
+        ...opts,
+        modules,
+        ...(surfaces !== undefined ? { surfaces } : {}),
+        // #5612 D1/D2 — the code registry's own `layout` block, known
+        // synchronously (unlike a bundle's `ailk-template.json`, only readable
+        // after install below). A template declaring none resolves to the same
+        // defaults `scaffoldSync` already writes for a templateless scaffold.
+        ...(template?.layout !== undefined ? { layout: template.layout } : {}),
+    });
     // 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();
+    // #5618 D4 — the file-grain ownership registry for THIS scaffold: which
+    // layer wrote which destination. Call-scoped (a fresh Map per scaffold(),
+    // never module-level), threaded through every layer install below in the
+    // composition order base → modules → template. A module writing a path the
+    // base or an earlier module owns is refused before its first write unless
+    // it is a declared patch; the template, the customer's copy, may overwrite
+    // anything. Starts empty at the base-layer boundary: the `templates/`
+    // snapshot (layer 0) is deliberately outside it.
+    const ownership = new Map();
+    // The BASE LAYER lands first (#5618 D1) — the seed files every template
+    // reaches by `extends` (today the three module-less base pages), read off
+    // the `site-templates/_base/` tree this package ships, through the same
+    // `installBundleTree` the keyless Free path uses below. Inside the
+    // `template !== undefined` guard, so a scaffold naming no template
+    // executes no new statement — the keyless regression floor holds
+    // structurally, exactly as spec 5462 D16 argues for `rosterSurfaces` above.
+    // Never fetched: it ships in the npm tarball, so the Free path keeps making
+    // zero requests. Every module bundle and then the template land ON TOP of
+    // it, later layers winning file by file.
+    if (template !== undefined) {
+        installBundleTree({
+            sourceRoot: join(SITE_TEMPLATES_DIR, BASE_LAYER_DIR),
+            targetDir: result.targetDir,
+            name: BASE_LAYER_DIR,
+            templateRequires: [],
+            versions,
+            ownership,
+        });
+    }
     for (const [moduleName, bytes] of bundles) {
         await extractModuleBundle({
             bytes,
             targetDir: result.targetDir,
             moduleName,
             versions,
+            ownership,
         });
     }
+    // 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) {
+        // #5612 D1/D2 — the INSTALLED template's own `ailk-template.json` layout
+        // (validated by `readAilkTemplateManifest`), if it declares one. Read
+        // only now: it lives in the bundle/tree, unreachable before install. When
+        // declared, it is authoritative over the code registry's `template.layout`
+        // already baked into `result`'s site-chrome.ts above — overwritten below.
+        // Absent (every shipped template today), the registry-resolved write from
+        // `scaffoldSync` stands untouched.
+        const installed = templateBundle !== undefined
+            ? await extractModuleBundle({
+                bytes: templateBundle,
+                targetDir: result.targetDir,
+                moduleName: template.name,
+                templateRequires: template.requires,
+                templateExtends: template.extends,
+                versions,
+                ownership,
+            })
+            : (() => {
+                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`);
+                }
+                return installBundleTree({
+                    sourceRoot,
+                    targetDir: result.targetDir,
+                    name: template.name,
+                    templateRequires: template.requires,
+                    templateExtends: template.extends,
+                    versions,
+                    ownership,
+                });
+            })();
+        if (installed.layout !== undefined) {
+            writeFileSync(join(result.targetDir, SITE_CHROME_PATH), renderSiteChrome(resolveSiteChrome(installed.layout)));
+        }
+    }
     return result;
 }
+/**
+ * The MODULE-LESS gateable-surface ids a template's merged roster names
+ * (#5469 D10): every `GATEABLE_SURFACES` entry no module contributes
+ * (`MODULE_SURFACES`) one of whose `routes[]` directories is the route
+ * directory of a merged roster row. Module-owned surfaces are left to the
+ * module set — a module's own rows (docs-blog's `/blog`) already enable
+ * theirs through `resolveSurfaces`, and the Free `/blog` teaser row must NOT
+ * enable the docs-blog `blog` surface: keyless there is no `blog/` route
+ * directory to copy, and the teaser renders through `[slug]` (D3).
+ *
+ * Merged over the template's OWN `requires`, not the scaffold's full module
+ * set: a module-less surface can only ever come from the template's base
+ * rows, and merging the Free template with an ADDED docs-blog would make
+ * `mergeRoster` refuse `/blog` (the teaser and the module's listing both
+ * claim it — parent § D8). That composition is legal at the route level
+ * precisely because the module's `blog/` directory takes precedence over
+ * the `[slug]` teaser, so it is resolved there, never in the registry.
+ *
+ * Route → directory: a roster route is site-relative (`/pricing`,
+ * `/flows/[slug]/start`); a surface owns template-relative route directories
+ * (`apps/web/app/[locale]/pricing`). A row matches a surface when its first
+ * path segment is the surface's top-level route directory.
+ */
+function rosterSurfaces(template) {
+    const routeRoot = "apps/web/app/[locale]";
+    const moduleOwned = new Set(Object.values(MODULE_SURFACES).flat());
+    const topSegments = new Set(mergeRoster(template, template.requires)
+        .map((row) => row.route.split("/").filter(Boolean)[0])
+        .filter((segment) => segment !== undefined));
+    return GATEABLE_SURFACES.filter((surface) => !moduleOwned.has(surface.id) &&
+        surface.routes.some((dir) => topSegments.has(dir.slice(routeRoot.length + 1)))).map((surface) => surface.id);
+}
 // Re-exported so a consumer of the async `scaffold()` above can type its own
 // wrapper (e.g. the MCP scaffold-site tool) without reaching into `lib/`.
 export { LicenseRequiredError, } from "./lib/module-license-gate.js";

package/dist/site-chrome.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Template layout knobs (#5612) — the resolved chrome facts a scaffold's
+ * `apps/web/app/[locale]/layout.tsx` reads to mount Nav/Footer/Banner/
+ * MarketingShell: `nav` (full nav links vs. brand-mark-only), `footer`
+ * (columns vs. the existing centered variant), `announcementBanner` (mount
+ * the home-only announcement Banner or not) and `home` (the default
+ * document-scroll home vs. the scroll-snap deck, #5270/#5426).
+ *
+ * A site template is content + an `installMap`, never a route/layout/`.ts`
+ * file (spec 5462 D9/D16) — these are SITE-LEVEL facts a template DECLARES
+ * (on `TemplateManifest.layout` in the code registry, or on a bundle's
+ * `ailk-template.json` `layout` field), never a file it ships. This module is
+ * the single place that declares the vocabulary, fills defaults, validates an
+ * untrusted (bundle-sourced) value, and renders the generated
+ * `apps/web/lib/site-chrome.ts` every scaffold gets — beside `nav-config.ts`,
+ * the same GENERATED-header idiom (`surfaces.ts` `renderNavConfig`).
+ *
+ * Every field is optional and DEFAULTS to today's render (`full` / `columns`
+ * / `true` / `default`) — a scaffold naming no template, or a template naming
+ * no `layout` block, gets these defaults written, byte-identical to the
+ * monorepo's own committed `apps/web/lib/site-chrome.ts`.
+ */
+/** The `nav` knob's vocabulary. `mark-only` → the layout passes Nav an empty
+ *  `navItems` (brand mark + the existing actions/theme/locale controls only). */
+export type SiteChromeNav = "full" | "mark-only";
+/** The `footer` knob's vocabulary. `centered` → `Footer layout="centered"`
+ *  (the existing third variant: nav row + social row + FooterBottomBar). */
+export type SiteChromeFooter = "columns" | "centered";
+/** The `home` knob's vocabulary. `deck` → the locale-root route mounts
+ *  MarketingShell with `snap="mandatory"` + `deckHero` (spec 5426 D7). */
+export type SiteChromeHome = "default" | "deck";
+/**
+ * A template's declared layout block — every field optional. Lives on
+ * `TemplateManifest.layout` (the code registry, `template-manifest.ts`) and
+ * on a template bundle's `ailk-template.json` `layout` field, same shape.
+ */
+export interface TemplateLayout {
+    nav?: SiteChromeNav;
+    footer?: SiteChromeFooter;
+    announcementBanner?: boolean;
+    home?: SiteChromeHome;
+}
+/** `TemplateLayout` with every field resolved — what `site-chrome.ts` exports. */
+export interface ResolvedSiteChrome {
+    nav: SiteChromeNav;
+    footer: SiteChromeFooter;
+    announcementBanner: boolean;
+    home: SiteChromeHome;
+}
+/** Byte-identical-to-today defaults (#5612 D1). */
+export declare const DEFAULT_SITE_CHROME: ResolvedSiteChrome;
+/** Template-relative path of the generated site-chrome registry — beside `NAV_CONFIG_PATH`. */
+export declare const SITE_CHROME_PATH = "apps/web/lib/site-chrome.ts";
+/** Thrown by `validateTemplateLayout` on an unrecognized value, naming the field. */
+export declare class TemplateLayoutError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validate an UNTRUSTED `layout` value (a bundle's `ailk-template.json`
+ * `layout` field — arbitrary JSON, never compile-time checked the way the
+ * code registry's `TemplateManifest.layout` is) against the vocabulary above.
+ * Refuses on the first unrecognized field value, naming the field and the
+ * value (#5612 D1). `undefined`/`null` is valid (no block declared); a
+ * non-object value, or a recognized field holding the wrong TYPE, is refused
+ * the same way as an unrecognized enum value — both are "not a value this
+ * field accepts".
+ *
+ * @param subject Caller-supplied context for the error message (e.g. `template "foo"`).
+ */
+export declare function validateTemplateLayout(value: unknown, subject: string): TemplateLayout;
+/** Fill every field a `TemplateLayout` leaves unset with `DEFAULT_SITE_CHROME`'s value. */
+export declare function resolveSiteChrome(layout?: TemplateLayout): ResolvedSiteChrome;
+/**
+ * Render `apps/web/lib/site-chrome.ts` for a resolved layout — the same
+ * GENERATED-header idiom `renderNavConfig` uses. `layout.tsx` imports
+ * `siteChrome` to decide Nav's `navItems`, Footer's `layout` prop, whether
+ * the announcement Banner mounts, and whether the locale-root route passes
+ * `snap="mandatory"` + `deckHero` to MarketingShell.
+ */
+export declare function renderSiteChrome(resolved: ResolvedSiteChrome): string;