create-ailk 0.13.0 → 0.15.0

package/dist/programmatic.js

@@ -15,33 +15,36 @@
  *   import { scaffoldSync } from './programmatic.js';
  *   const result = scaffoldSync({ targetDir: '/tmp/my-site', projectName: 'my-site' });
  */
-import { existsSync, readdirSync, readFileSync, rmdirSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmdirSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { AddModuleRefusedError, applyModuleToScaffold, } from "./add-module.js";
+import { AddModuleRefusedError, addModuleSiteTopology, applyModuleToScaffold, } from "./add-module.js";
 import { planDesignMd } from "./apply-design-md.js";
 import { renderClaudeMd, syncClaudeMd, } from "./claude-md.js";
 import { CATALOG_TARGET_PATH, writeComponentCatalog, } from "./component-catalog.js";
 import { buildScaffoldMarkers, copyTemplate } from "./copy.js";
 import { deriveArchitecture } from "./derive-architecture.js";
-import { compileDesignTheme } from "./design-compile.js";
+import { compileDesignFonts, compileDesignTheme } from "./design-compile.js";
+import { HOME_PAGE_PATH, designHomeSeeds, planDesignHome, shapeHomePath, shippedHomeSeeds, } from "./design-home.js";
 import { applyDesignPresets, readSectionLookCatalog, shippedPageTypes, validateDesignPresets, } from "./design-presets.js";
-import { installDesignSample, resolveDesign, spliceThemeBlock, } from "./design-scaffold.js";
+import { resolveDesign, spliceThemeBlock, } from "./design-scaffold.js";
 import { writeAuthSecretFile } from "./lib/auth-secret-file.js";
 import { extractModuleBundle, installBundleTree, } from "./lib/extract-module-bundle.js";
 import { fetchTemplate } from "./lib/fetch-template.js";
 import { assertLicenseKeyShape, writeLicenseKeyFiles, } from "./lib/license-key-files.js";
-import { assertDesignAllowed, assertReleased, deriveLevel, resolveModuleSet, resolvePaidModules, } from "./lib/module-license-gate.js";
+import { assertDesignAllowed, assertReleased, deriveDesignLevel, deriveLevel, resolveModuleSet, resolvePaidModules, } from "./lib/module-license-gate.js";
 import { classifyModules } from "./lib/module-tier.js";
 import { normalizeModules } from "./module-architecture.js";
 import { writePaidSections } from "./paid-sections.js";
 import { RECOGNIZED_SHAPES, RESERVED_SHAPES, } from "./parse-args.js";
 import { SITE_CHROME_PATH, renderSiteChrome, resolveSiteChrome, } from "./site-chrome.js";
+import { SITE_FONTS_PATH, renderSiteFonts } from "./site-fonts.js";
 import { planSiteManifest } from "./site-manifest.js";
-import { SITE_ROSTER_PATH, planSiteManifestDesign, readSiteRoster, withMeetPlaceholderSeeds, } from "./site-roster.js";
+import { SITE_ROSTER_PATH, planHomeRecord, planSiteManifestDesign, readSiteRoster, withMeetPlaceholderSeeds, } from "./site-roster.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, SHAPE_STARTERS, TEMPLATE_MANIFESTS, TemplateError, mergeRoster, resolveTemplate, resolveTemplateLineage, rosterDeclares, templateDelivery, templateTreeDir, } from "./template-manifest.js";
+import { TopologyError, applySpokeTransforms, isSpokeExcluded, normalizeHubUrl, readSiteTopology, spokeExclusions, spokeModuleRefusal, spokeModules, writeHubOriginEnv, } from "./topology.js";
 import { validateTarget } from "./validate.js";
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const TEMPLATES_DIR = resolve(PKG_ROOT, "templates");
@@ -149,14 +152,23 @@ export function scaffoldSync(opts) {
     // The declared route surface (#4154). Resolved BEFORE the copy: it decides
     // both which route directories are skipped and what architecture.yaml records.
     const enabledSurfaces = resolveSurfaces(opts.modules ?? ["marketing"], opts.surfaces ?? []);
+    // #7426 D4 — a spoke is this same copy with the spoke's exclusions added:
+    // one registry over the one template tree, never a second tree.
+    const spoke = opts.topology === "spoke" ? { mcp: opts.mcp !== false } : undefined;
     const versions = readVersionMap();
     copyTemplate({
         templatesDir: TEMPLATES_DIR,
         targetDir: targetAbs,
         versions,
-        excludePaths: excludedRoutePaths(enabledSurfaces),
+        excludePaths: [
+            ...excludedRoutePaths(enabledSurfaces),
+            ...(spoke !== undefined ? spokeExclusions(TEMPLATES_DIR, spoke) : []),
+        ],
         markers: buildScaffoldMarkers(projectName),
     });
+    // #7426 D5/D6 — the root files a spoke rewrites, and the spoke seams.
+    if (spoke !== undefined)
+        applySpokeTransforms(targetAbs, spoke);
     // Stamp the copied CLAUDE.md's template regions with their hashes (#6904
     // D2). No later layer writes a root CLAUDE.md, so this is the final file.
     writeFileSync(join(targetAbs, "CLAUDE.md"), renderClaudeMd(readFileSync(join(TEMPLATES_DIR, "CLAUDE.md"), "utf8"), projectName));
@@ -165,7 +177,7 @@ export function scaffoldSync(opts) {
     // closes the dangling `architecture_rules: architecture.yaml` reference in
     // the scaffolded project.yaml. Written AFTER the template copy, at the target
     // root — a deterministic function of the selected module set.
-    writeFileSync(join(targetAbs, "architecture.yaml"), deriveArchitecture(opts.modules ?? ["marketing"], enabledSurfaces));
+    writeFileSync(join(targetAbs, "architecture.yaml"), deriveArchitecture(opts.modules ?? ["marketing"], enabledSurfaces, spoke !== undefined ? { topology: "spoke", mcp: spoke.mcp } : {}));
     // Regenerate the site nav from the same surface set (#4154). The nav is a
     // static list the layout renders into the header AND the footer, so leaving
     // the template's copy in place would link /docs and /blog sitewide in a
@@ -250,6 +262,9 @@ export async function scaffold(opts) {
             ? resolveShapeTemplate(opts.shape)
             : undefined;
     assertReleased("modules", [...(opts.modules ?? []), ...(template?.requires ?? [])]);
+    // #7426 D1-D3/D7 — a spoke's refusals, before anything is fetched or
+    // written: the target directory never exists for a refused spoke.
+    const spoke = resolveSpoke(opts, template);
     // #6813 D8 step 3 — the design this scaffold renders, resolved from its
     // package ONCE, before any fetch or write: the caller's override, else the
     // template's own. Unset for a scaffold naming neither. Replaces the
@@ -267,14 +282,22 @@ export async function scaffold(opts) {
     // (D2): a non-look field or unknown variant throws `DesignPackageError`
     // naming page type, section type and field, and the target is never
     // created. A design with no `sections` block executes no new read (D8).
+    let lookCatalog;
+    const catalog = () => (lookCatalog ??= readSectionLookCatalog(join(PKG_ROOT, "component-catalog.json")));
     if (resolvedDesign !== undefined &&
         Object.keys(resolvedDesign.pkg.sections).length > 0) {
         validateDesignPresets(resolvedDesign.pkg.sections, {
-            catalog: readSectionLookCatalog(join(PKG_ROOT, "component-catalog.json")),
+            catalog: catalog(),
             pageTypes: shippedPageTypes(SITE_TEMPLATES_DIR),
             file: join(resolvedDesign.dir, "DESIGN.md"),
         });
     }
+    // #7743 D5 — the design's home seeds are read and validated beside its
+    // presets: a malformed seed throws `DesignPackageError`, naming the file,
+    // before the target is created.
+    const designSeeds = resolvedDesign !== undefined
+        ? designHomeSeeds(resolvedDesign, { designsDir: DESIGNS_DIR, catalog })
+        : [];
     // #6813 D7 — the resolved design only when the CALLER chose one (`opts.design`);
     // a template's own declared design is never gated (#6778 option (c)).
     const chosenDesign = opts.design !== undefined ? resolvedDesign : undefined;
@@ -298,10 +321,12 @@ export async function scaffold(opts) {
     // list.
     let modules;
     let bundles;
+    // #7426 D7 — the key's default modules a spoke does not admit.
+    let dropped = [];
     // The run's derived level (#6759), for `assertDesignAllowed` below.
     // Undefined on the alias branch and on a `--modules`-keep run (D2/D4 in
     // module-license-gate.ts — the level plays no part in composing either),
-    // so a non-`standard` design on either path derives it separately, below.
+    // so a non-`standard` design on either path derives it separately.
     let level;
     if (opts.template !== undefined) {
         // Alias run — untouched (NFR-4): the union line and its
@@ -350,6 +375,27 @@ export async function scaffold(opts) {
         });
         bundles = chosen.bundles;
         level = chosen.level;
+        // #7426 D7 — a key-derived default set keeps only what a spoke admits;
+        // the run names what it dropped (`droppedModules`).
+        if (spoke !== undefined && opts.modules === undefined) {
+            const admitted = new Set(spokeModules());
+            dropped = chosen.modules.filter((m) => !admitted.has(m));
+            chosen.modules = chosen.modules.filter((m) => admitted.has(m));
+            for (const name of dropped)
+                bundles.delete(name);
+        }
+        // #7010 — a `--modules`-keep run composes no level (NFR-2), so a chosen
+        // non-Free design derives one from the key here, as the addition branch
+        // does; a plain keep run makes no extra network call.
+        if (level === undefined && chosenDesign !== undefined && !chosenDesign.free) {
+            level = await deriveDesignLevel({
+                licenseKey,
+                ...(opts.moduleRegistryUrl !== undefined
+                    ? { registryUrl: opts.moduleRegistryUrl }
+                    : {}),
+                ...(opts.fetchImpl !== undefined ? { fetchImpl: opts.fetchImpl } : {}),
+            });
+        }
         modules =
             template !== undefined
                 ? normalizeModules([...template.requires, ...chosen.modules])
@@ -378,9 +424,9 @@ export async function scaffold(opts) {
     }
     // #6760 D4 — after the level is resolved, before any fetch or write below.
     // Only the caller's chosen design is gated (#6778 option (c)); a template's
-    // own declared design is not. `level ?? "free"` fails closed: a
-    // `--modules`-keep run under-reports its level by design (NFR-2), so a
-    // chosen non-Free design on that path is refused rather than trusted. The
+    // own declared design is not. `level ?? "free"` fails closed: a level left
+    // underived (a plain alias or `--modules`-keep run with no chosen non-Free
+    // design) is never trusted. The
     // refusal names `chosen.display` — the name, or the absolute directory
     // (#6813 D7) — and `chosen.free` decides Free-ness by identity (D2), never
     // by `FREE_DESIGNS.includes(name)` alone (a path is never in that list).
@@ -431,6 +477,7 @@ export async function scaffold(opts) {
     const result = scaffoldSync({
         ...opts,
         modules,
+        ...(spoke !== undefined ? { topology: "spoke", mcp: spoke.mcp } : {}),
         ...(surfaces !== undefined ? { surfaces } : {}),
         // #5612 D1/D2 — the code registry's own `layout` block, known
         // synchronously (unlike a bundle's `ailk-template.json`, only readable
@@ -464,6 +511,14 @@ export async function scaffold(opts) {
     // anything. Starts empty at the base-layer boundary: the `templates/`
     // snapshot (layer 0) is deliberately outside it.
     const ownership = new Map();
+    // #7426 D4 — every layer below lands through the spoke filter: a module
+    // bundle's or the template's destination a spoke does not carry is dropped.
+    const exclusions = spoke !== undefined ? spokeExclusions(TEMPLATES_DIR, spoke) : [];
+    const spokeSkip = spoke !== undefined
+        ? {
+            skip: (destination) => isSpokeExcluded(destination, { mcp: spoke.mcp, exclusions }),
+        }
+        : {};
     // 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
@@ -483,6 +538,7 @@ export async function scaffold(opts) {
             versions,
             markers,
             ownership,
+            ...spokeSkip,
         });
     }
     for (const [moduleName, bytes] of bundles) {
@@ -493,6 +549,7 @@ export async function scaffold(opts) {
             versions,
             markers,
             ownership,
+            ...spokeSkip,
         });
     }
     // The template lands LAST — after `scaffoldSync` and after every module
@@ -528,6 +585,7 @@ export async function scaffold(opts) {
                 versions,
                 markers,
                 ownership,
+                ...spokeSkip,
             })
             : (() => {
                 const sourceRoot = join(SITE_TEMPLATES_DIR, templateTreeDir(template.name));
@@ -543,6 +601,7 @@ export async function scaffold(opts) {
                     versions,
                     markers,
                     ownership,
+                    ...spokeSkip,
                 });
             })();
         installedLayout = installed.layout;
@@ -568,22 +627,6 @@ export async function scaffold(opts) {
             : [];
         writeFileSync(join(result.targetDir, NAV_CONFIG_PATH), renderNavConfig(result.surfaces, { serviceSlugs }));
         pruneUnrosteredSeeds(result.targetDir, mergeRoster(template, template.requires), result.surfaces, ownership);
-        // spec 6892 D4 — the resolved design's own sample (the minimalism design's
-        // nine-slide deck home + its SVGs; no template declares `minimalism`
-        // since #6976, so none installs it today), installed AFTER the template
-        // layer so it wins over the shape's `HomePage/home.mdx`, and ONLY when
-        // the resolved design is the template's OWN declared design: a caller
-        // combination like `--shape organization-product --design minimalism`
-        // installs no sample (its roster carries neither the deck's link targets
-        // nor, in its generated record, the deck's sections).
-        if (resolvedDesign !== undefined &&
-            resolvedDesign.recorded === template.design) {
-            installDesignSample({
-                designDir: resolvedDesign.dir,
-                targetDir: result.targetDir,
-                ownership,
-            });
-        }
     }
     // #6813 D5/D8 steps 9-10 — whenever a design is resolved (the caller's,
     // else the template's): the design's DESIGN.md (#6939); the compiled theme,
@@ -595,6 +638,15 @@ export async function scaffold(opts) {
         // #6939 — the scaffold's DESIGN.md is the design it wears, not the one
         // its template layer shipped; the site's own header lines are kept.
         writeFileSync(join(result.targetDir, "DESIGN.md"), planDesignMd(resolvedDesign.dir, result.targetDir));
+        // #7720 D4.1 — the faces the design sources, beside site-chrome.ts. A
+        // design that sources none renders the overlay's committed default, so
+        // the file is left as the template tree wrote it.
+        const siteFontsPath = join(result.targetDir, SITE_FONTS_PATH);
+        const siteFonts = renderSiteFonts(compileDesignFonts(resolvedDesign.pkg));
+        if (!existsSync(siteFontsPath) || readFileSync(siteFontsPath, "utf8") !== siteFonts) {
+            mkdirSync(dirname(siteFontsPath), { recursive: true });
+            writeFileSync(siteFontsPath, siteFonts);
+        }
         const compiledTheme = compileDesignTheme(resolvedDesign.pkg);
         const siteMdxPath = join(result.targetDir, "content", "_site.mdx");
         if (existsSync(siteMdxPath)) {
@@ -613,6 +665,27 @@ export async function scaffold(opts) {
                     writeFileSync(rosterPath, nextManifest);
             }
         }
+        // #7743 D5 — the design's home arc, seeded over a placeholder home once
+        // every layer has landed, before the presets dress it. A home that is not
+        // the shape's placeholder is never written; `--design standard` (no
+        // seeds) leaves the shape's home byte-identical. The one
+        // `planDesignHome` call site in scaffold().
+        const homePath = join(result.targetDir, ...HOME_PAGE_PATH.split("/"));
+        let homeSeeded = false;
+        if (template !== undefined) {
+            const homePlan = planDesignHome({
+                current: existsSync(homePath) ? readFileSync(homePath, "utf8") : undefined,
+                shape: template.shape,
+                target: designSeeds.find((seed) => seed.shape === template.shape),
+                shapeHome: readFileSync(shapeHomePath(template.shape, { siteTemplatesDir: SITE_TEMPLATES_DIR, templatesDir: TEMPLATES_DIR }), "utf8"),
+                shippedSeeds: shippedHomeSeeds({ designsDir: DESIGNS_DIR, catalog }),
+                catalog: catalog(),
+            });
+            if (homePlan.outcome === "seeded" && homePlan.text !== undefined) {
+                writeFileSync(homePath, homePlan.text);
+                homeSeeded = true;
+            }
+        }
         // #6816 D6 step 10b — the design's section presets, written onto the
         // pages of the page types the roster of record places, once every layer
         // has landed. The one `applyDesignPresets` call site. A scaffold with no
@@ -637,6 +710,14 @@ export async function scaffold(opts) {
                     writeFileSync(page.path, page.text);
             }
         }
+        // #7743 D6 — the manifest's `/` row records the seeded home's sections,
+        // as the presets left them.
+        const rosterPath = join(result.targetDir, SITE_ROSTER_PATH);
+        if (homeSeeded && existsSync(rosterPath)) {
+            const nextManifest = planHomeRecord(readFileSync(rosterPath, "utf8"), readFileSync(homePath, "utf8"), catalog());
+            if (nextManifest !== undefined)
+                writeFileSync(rosterPath, nextManifest);
+        }
     }
     // #6944 — the manifest records what this scaffold IS, once every layer has
     // landed: the effective module set, a row for every route on disk, and the
@@ -652,6 +733,8 @@ export async function scaffold(opts) {
                 roster,
                 modules: result.modules,
                 level,
+                topology: spoke !== undefined ? "spoke" : "hub",
+                patternVersion: markers["CREATE_AILK_VERSION"] ?? "",
                 siteTemplatesDir: SITE_TEMPLATES_DIR,
                 templatesDir: TEMPLATES_DIR,
                 markers,
@@ -663,20 +746,70 @@ export async function scaffold(opts) {
     writePaidSections(result.targetDir);
     // #6107 D2 — after every layer landed, so nothing later overwrites it: a
     // served scaffold needs BETTER_AUTH_SECRET (#6044), and this is its value.
-    writeAuthSecretFile(result.targetDir);
+    // A spoke has no sign-in (#7426 D4), so it gets its hub's origin instead
+    // (D2) — never the spoke key, which the hub issues.
+    if (spoke !== undefined)
+        writeHubOriginEnv(result.targetDir, spoke.hubOrigin);
+    else
+        writeAuthSecretFile(result.targetDir);
     // #6683 D9 — persisted only after every layer landed, and only when the
-    // caller passed `license`: a scaffold without it writes nothing new.
+    // caller passed `license`: a scaffold without it writes nothing new. A
+    // spoke has no apps/api, so it keeps the key in ailk.key alone (#7426 D6).
     if (opts.license !== undefined) {
-        writeLicenseKeyFiles(result.targetDir, opts.license);
+        writeLicenseKeyFiles(result.targetDir, opts.license, {
+            apiEnv: spoke === undefined,
+        });
     }
     // #6754 D4/D5 — the resolved starter, so the CLI names what it built.
+    const withDropped = {
+        ...result,
+        ...(dropped.length > 0 ? { droppedModules: dropped } : {}),
+        ...(spoke !== undefined ? { hubOrigin: spoke.hubOrigin } : {}),
+    };
     if (template !== undefined && resolvedDesign !== undefined) {
         return {
-            ...result,
+            ...withDropped,
             starter: { template: template.name, shape: template.shape, design: resolvedDesign.recorded },
         };
     }
-    return result;
+    return withDropped;
+}
+/**
+ * A spoke's resolved inputs (#7426 D1-D3/D7), or undefined for a hub. Every
+ * refusal is a `TemplateError` thrown before anything is fetched or written.
+ */
+function resolveSpoke(opts, template) {
+    if (opts.topology !== "spoke") {
+        const spokeOnly = [
+            opts.hubUrl !== undefined ? "hubUrl" : undefined,
+            opts.mcp !== undefined ? "mcp" : undefined,
+        ].filter((f) => f !== undefined);
+        if (spokeOnly.length > 0) {
+            throw new TemplateError(`${spokeOnly.join(" and ")} only apply to a spoke — pass topology: "spoke"`);
+        }
+        return undefined;
+    }
+    if (template === undefined) {
+        throw new TemplateError("a spoke needs a starter — pass --shape <shape> or --template <name>: the site manifest is where the topology is recorded");
+    }
+    let hubOrigin;
+    try {
+        hubOrigin = normalizeHubUrl(opts.hubUrl ?? process.env["AILK_API_URL"]);
+    }
+    catch (err) {
+        if (err instanceof TopologyError)
+            throw new TemplateError(err.message);
+        throw err;
+    }
+    for (const name of normalizeModules([...(opts.modules ?? []), ...template.requires])) {
+        const refusal = spokeModuleRefusal(name);
+        if (refusal !== undefined) {
+            throw new TemplateError(template.requires.includes(name) && !(opts.modules ?? []).includes(name)
+                ? `template "${template.name}" requires ${refusal}`
+                : refusal);
+        }
+    }
+    return { mcp: opts.mcp !== false, hubOrigin };
 }
 /**
  * The per-row install of the two SHARED seed layers (#6646 D1, disposition
@@ -798,7 +931,12 @@ export function syncArchitectureSync(opts) {
         throw new Error(`not a scaffolded repo: no architecture.yaml at ${targetAbs}. Run \`create-ailk <target-dir>\` to scaffold first.`);
     }
     const enabledSurfaces = resolveSurfaces(opts.modules, opts.surfaces ?? []);
-    writeFileSync(archPath, deriveArchitecture(opts.modules, enabledSurfaces));
+    // #7426 D13 — a spoke stays a spoke: its topology is read from its
+    // manifest, and `mcp` from whether it still carries apps/mcp.
+    const topology = readSiteTopology(targetAbs);
+    writeFileSync(archPath, deriveArchitecture(opts.modules, enabledSurfaces, topology === "spoke"
+        ? { topology, mcp: existsSync(join(targetAbs, "apps", "mcp")) }
+        : {}));
     return {
         targetDir: targetAbs,
         surfaces: enabledSurfaces,
@@ -916,6 +1054,13 @@ export async function addModule(opts) {
     if (!existsSync(join(targetAbs, "architecture.yaml"))) {
         throw new Error(`not a scaffolded repo: no architecture.yaml at ${targetAbs}. Run \`create-ailk <target-dir>\` to scaffold first.`);
     }
+    // #7426 D13 — a spoke refuses a module it does not admit before any key
+    // read or network call (`applyModuleToScaffold` refuses it again).
+    if (addModuleSiteTopology(targetAbs) === "spoke") {
+        const refusal = spokeModuleRefusal(opts.moduleName);
+        if (refusal !== undefined)
+            throw new AddModuleRefusedError(refusal);
+    }
     const { paid } = classifyModules([opts.moduleName]);
     if (paid.length === 0) {
         throw new AddModuleRefusedError(`"${opts.moduleName}" ships with every scaffold — there is no module bundle to add`);

package/dist/site-chrome.d.ts

@@ -38,6 +38,24 @@ 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";
+/** The `innerPages` knob's vocabulary (#7721). `bare` → every non-home page
+ *  gets the bare header and the one-bar footer. */
+export type SiteChromeInnerPages = "default" | "bare";
+/** The `colorMode` knob's vocabulary (#7742). `light` pins the site to light
+ *  and removes every theme switch; dark then appears only as a deck ground. */
+export type SiteChromeColorMode = "user" | "light";
+/** The `chromeStyle` knob's vocabulary (#7742). `minimal` → the deck's closing
+ *  slide is the wordmark + contact lines + one legal line, and the consent bar
+ *  is a ground-coloured hairline bar that never covers the down cue. */
+export type SiteChromeChromeStyle = "default" | "minimal";
+/**
+ * The `deckGrounds` knob's vocabulary (#7719 D3) — the shared section surface
+ * enum, duplicated from `@working-theory/validation`'s `SectionSurfaceSchema`
+ * because `create-ailk` cannot import it (one runtime dependency, § 1.5);
+ * `site-chrome.test.ts` proves the two lists equal.
+ */
+export declare const DECK_GROUND_VALUES: readonly ["none", "gray-100", "wash", "wash-secondary", "gradient-brand", "gradient-dark", "solid-dark"];
+export type DeckGround = (typeof DECK_GROUND_VALUES)[number];
 /**
  * A template's declared layout block — every field optional. Lives on
  * `TemplateManifest.layout` (the code registry, `template-manifest.ts`) and
@@ -48,6 +66,18 @@ export interface TemplateLayout {
     footer?: SiteChromeFooter;
     announcementBanner?: boolean;
     home?: SiteChromeHome;
+    /** #7719 D3 — the surfaces a deck home cycles, slide by slide, onto slides that author none. */
+    deckGrounds?: readonly DeckGround[];
+    /** #7721 D1 — `bare`: every non-home page wears the bare header and the one-bar footer. */
+    innerPages?: SiteChromeInnerPages;
+    /** #7740 D1 — `true`: the deck home presents slide by slide (a deck home only). */
+    deckPresentation?: boolean;
+    /** #7742 D1 — `light`: the site is pinned to light, with no theme switch. */
+    colorMode?: SiteChromeColorMode;
+    /** #7742 D1 — `minimal`: the minimal closing slide, consent bar and themed 404. */
+    chromeStyle?: SiteChromeChromeStyle;
+    /** #7797 D1 — route paths whose page ends on the closing footer (wordmark, contact lines, legal line). */
+    closingFooterPaths?: readonly string[];
 }
 /** `TemplateLayout` with every field resolved — what `site-chrome.ts` exports. */
 export interface ResolvedSiteChrome {
@@ -55,6 +85,18 @@ export interface ResolvedSiteChrome {
     footer: SiteChromeFooter;
     announcementBanner: boolean;
     home: SiteChromeHome;
+    /** Present only when a list resolves AND `home` is `deck` (#7719 D3) — never an `undefined` key. */
+    deckGrounds?: readonly DeckGround[];
+    /** Present only when it resolves to "bare" — never "default" (#7721 D1). */
+    innerPages?: "bare";
+    /** Present only when it resolves to `true` AND `home` is `deck` (#7740 D1) — never `false`. */
+    deckPresentation?: true;
+    /** Present only when it resolves to "light" — never "user" (#7742 D1). */
+    colorMode?: "light";
+    /** Present only when it resolves to "minimal" — never "default" (#7742 D1). */
+    chromeStyle?: "minimal";
+    /** Present only when a non-empty list resolves — never `[]` (#7797 D1). */
+    closingFooterPaths?: readonly string[];
 }
 /** Defaults (#5612 D1; banner off since #6469). */
 export declare const DEFAULT_SITE_CHROME: ResolvedSiteChrome;