create-ailk 0.4.0 → 0.5.0

package/dist/parse-args.js

@@ -64,8 +64,12 @@ Options:
                            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

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. */
@@ -89,6 +90,15 @@ export interface ScaffoldOptions {
     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. */

package/dist/programmatic.js

@@ -26,9 +26,10 @@ 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 { resolveTemplate, templateDelivery } from "./template-manifest.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");
@@ -95,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
@@ -108,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)
@@ -147,6 +158,11 @@ export async function scaffold(opts) {
     // 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
@@ -195,18 +211,72 @@ export async function scaffold(opts) {
     // 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 });
+    //
+    // 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
@@ -220,31 +290,76 @@ export async function scaffold(opts) {
     // 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({
+        // #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,
-            });
-        }
-        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,
-            });
+                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;

package/dist/site-chrome.js

@@ -0,0 +1,135 @@
+/**
+ * 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`.
+ */
+/** Byte-identical-to-today defaults (#5612 D1). */
+export const DEFAULT_SITE_CHROME = {
+    nav: "full",
+    footer: "columns",
+    announcementBanner: true,
+    home: "default",
+};
+/** Template-relative path of the generated site-chrome registry — beside `NAV_CONFIG_PATH`. */
+export const SITE_CHROME_PATH = "apps/web/lib/site-chrome.ts";
+/** Thrown by `validateTemplateLayout` on an unrecognized value, naming the field. */
+export class TemplateLayoutError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TemplateLayoutError";
+    }
+}
+const NAV_VALUES = ["full", "mark-only"];
+const FOOTER_VALUES = ["columns", "centered"];
+const HOME_VALUES = ["default", "deck"];
+/**
+ * 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 function validateTemplateLayout(value, subject) {
+    if (value === undefined || value === null)
+        return {};
+    if (typeof value !== "object" || Array.isArray(value)) {
+        throw new TemplateLayoutError(`${subject}: "layout" must be an object, got ${JSON.stringify(value)}`);
+    }
+    const raw = value;
+    const result = {};
+    if ("nav" in raw && raw.nav !== undefined) {
+        if (!NAV_VALUES.includes(raw.nav)) {
+            throw new TemplateLayoutError(`${subject}: layout.nav must be one of ${NAV_VALUES.join(", ")} — got ${JSON.stringify(raw.nav)}`);
+        }
+        result.nav = raw.nav;
+    }
+    if ("footer" in raw && raw.footer !== undefined) {
+        if (!FOOTER_VALUES.includes(raw.footer)) {
+            throw new TemplateLayoutError(`${subject}: layout.footer must be one of ${FOOTER_VALUES.join(", ")} — got ${JSON.stringify(raw.footer)}`);
+        }
+        result.footer = raw.footer;
+    }
+    if ("announcementBanner" in raw && raw.announcementBanner !== undefined) {
+        if (typeof raw.announcementBanner !== "boolean") {
+            throw new TemplateLayoutError(`${subject}: layout.announcementBanner must be a boolean — got ${JSON.stringify(raw.announcementBanner)}`);
+        }
+        result.announcementBanner = raw.announcementBanner;
+    }
+    if ("home" in raw && raw.home !== undefined) {
+        if (!HOME_VALUES.includes(raw.home)) {
+            throw new TemplateLayoutError(`${subject}: layout.home must be one of ${HOME_VALUES.join(", ")} — got ${JSON.stringify(raw.home)}`);
+        }
+        result.home = raw.home;
+    }
+    return result;
+}
+/** Fill every field a `TemplateLayout` leaves unset with `DEFAULT_SITE_CHROME`'s value. */
+export function resolveSiteChrome(layout) {
+    return {
+        nav: layout?.nav ?? DEFAULT_SITE_CHROME.nav,
+        footer: layout?.footer ?? DEFAULT_SITE_CHROME.footer,
+        announcementBanner: layout?.announcementBanner ?? DEFAULT_SITE_CHROME.announcementBanner,
+        home: layout?.home ?? DEFAULT_SITE_CHROME.home,
+    };
+}
+/**
+ * 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 function renderSiteChrome(resolved) {
+    return `// site-chrome.ts — resolved template layout knobs.
+//
+// GENERATED by create-ailk from the declared template's \`layout\` block
+// (#5612). A scaffold with no template, or a template with no \`layout\`
+// block, gets these defaults — byte-identical to every scaffold before this
+// file existed. \`apps/web/app/[locale]/layout.tsx\` reads this to decide:
+//   - nav: "mark-only" → Nav renders the brand mark + right-hand controls
+//     only (no nav links).
+//   - footer: "centered" → Footer renders its existing centered variant.
+//   - announcementBanner: false → the home-only announcement Banner is not
+//     mounted (the cookie-consent Banner is unaffected — it is not an
+//     announcement).
+//   - home: "deck" → the locale-root route mounts MarketingShell with
+//     snap="mandatory" + deckHero (spec 5426 D7); every other route is
+//     unaffected.
+
+export interface SiteChrome {
+  nav: "full" | "mark-only";
+  footer: "columns" | "centered";
+  announcementBanner: boolean;
+  home: "default" | "deck";
+}
+
+export const siteChrome: SiteChrome = {
+  nav: ${JSON.stringify(resolved.nav)},
+  footer: ${JSON.stringify(resolved.footer)},
+  announcementBanner: ${JSON.stringify(resolved.announcementBanner)},
+  home: ${JSON.stringify(resolved.home)},
+};
+`;
+}

package/dist/surfaces.d.ts

@@ -51,6 +51,12 @@ export interface Surface {
 export declare const GATEABLE_SURFACES: readonly Surface[];
 /** The recognized `--surfaces` vocabulary, sorted. */
 export declare const RECOGNIZED_SURFACES: readonly string[];
+/**
+ * Retired surface ids, kept for ONE release (#5563). Removal rides the same
+ * trigger as the `/schedule` legacyRoutes entries in routes-map.ts — see the
+ * comment on that row. Resolving through an alias prints a deprecation notice.
+ */
+export declare const SURFACE_ALIASES: Readonly<Record<string, string>>;
 /**
  * Surfaces each recognized module contributes.
  *
@@ -176,12 +182,21 @@ export declare const NAV_CONFIG_PATH = "apps/web/lib/nav-config.ts";
  * exists: two dead links, sitewide, by default. So the nav follows the declared
  * surface set for the same reason the route tree does.
  *
- * Only surfaces carrying a `navLabelKey` are linked, because a nav entry needs
- * a translated label and the template's `nav` namespace ships keys for exactly
- * `home`, `docs`, and `blog`. Emitting an entry whose `labelKey` has no
- * translation would trade a dead link for a missing-message error.
+ * The base items are the Free marketing-site chrome (#5469 D5, the approved
+ * chrome diff recorded on that card):
+ * a Product flyout (How it works · Features · FAQ), then How it works, Pricing
+ * and About. Every one of those pages is in EVERY scaffold — the four core
+ * routes plus the `[slug]` route over the overlay's LandingPage MDX — except
+ * Pricing, which is a gateable surface: its item is emitted only when the
+ * `pricing` surface is enabled (a template roster enables it, #5469 D10), so
+ * the nav still never links a page the scaffold does not carry.
+ *
+ * Only gateable surfaces carrying a `navLabelKey` are linked after the base
+ * items, because a nav entry needs a translated label. Emitting an entry whose
+ * `labelKey` has no translation would trade a dead link for a missing-message
+ * error.
  *
- * Deterministic: entries follow GATEABLE_SURFACES order (alphabetical by id),
- * after the always-present home entry.
+ * Deterministic: gateable entries follow GATEABLE_SURFACES order (alphabetical
+ * by id), after the fixed base items.
  */
 export declare function renderNavConfig(enabled: string[]): string;