create-ailk 0.8.0 → 0.9.0

package/dist/programmatic.d.ts

@@ -16,11 +16,12 @@
  *   const result = scaffoldSync({ targetDir: '/tmp/my-site', projectName: 'my-site' });
  */
 import { type AddModuleResult } from "./add-module.js";
+import { type SyncClaudeMdResult } from "./claude-md.js";
 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";
-import { type StarterDesign, type StarterShape } from "./template-manifest.js";
+import { type StarterShape } from "./template-manifest.js";
 export interface ScaffoldOptions {
     /** Absolute or relative path to the target directory. Must not exist or be empty. */
     targetDir: string;
@@ -118,15 +119,23 @@ export interface ScaffoldOptions {
      */
     layout?: TemplateLayout;
     /**
-     * The design whose layout knobs fill what `layout` leaves unset (#6638,
-     * `DESIGN_LAYOUTS`). `scaffold()` sets it from the resolved template's
+     * A design name or a directory holding a DESIGN.md (#6638; widened to a
+     * path #6813 D1/D3). `scaffold()` sets it from the resolved template's
      * `design`; a caller may name one to OVERRIDE the template's — the
      * shape × design pairing `verify-scaffold.mjs --design` renders (#6638
      * DD-4), and the CLI's `--design` beside `--shape` (#6754). Unset (every
      * existing `scaffoldSync` caller) resolves exactly as before. Gated
-     * (#6760): a design outside `FREE_DESIGNS` needs a Pro or Pro Plus level.
+     * (#6760): a non-Free design needs a Pro or Pro Plus level.
      */
-    design?: StarterDesign;
+    design?: string;
+    /**
+     * INTERNAL — the resolved design's own layout knobs (#6813 D2/D4/D8),
+     * populated by `scaffold()` from `resolveDesign(...).pkg.layout` before
+     * calling `scaffoldSync`. Never set by a CLI/MCP caller. Replaces the
+     * design-NAME lookup `scaffoldSync` used to do internally through the
+     * code registry that has since been deleted (#6638's per-name table).
+     */
+    designLayout?: TemplateLayout;
 }
 export interface ScaffoldResult {
     /** Resolved absolute path to the scaffolded directory. */
@@ -138,11 +147,13 @@ export interface ScaffoldResult {
     /**
      * The starter this scaffold resolved (#6754 D5) — set whenever a template
      * was resolved, from `template` or from `shape`; absent for the bare overlay.
+     * `design` is the applied design's recorded name (#6813 D6): the shipped
+     * registry name, or the package's own `name` for an unrecognized one.
      */
     starter?: {
         template: string;
         shape: StarterShape;
-        design: StarterDesign;
+        design: string;
     };
     /**
      * The effective module set this scaffold installed (#6759 D6) — what
@@ -258,6 +269,19 @@ export interface SyncCatalogResult {
 export declare function syncCatalogSync(opts: {
     targetDir: string;
 }): SyncCatalogResult;
+/**
+ * Rewrite the template-owned sections of an already-scaffolded repo's root
+ * `CLAUDE.md` to the template this create-ailk ships (#6904 D3). The logic
+ * lives in `claude-md.ts` (a module jest imports directly); this wrapper
+ * only supplies the package's `templates/CLAUDE.md` — the `syncRoutesSync`
+ * split. `templateText` stands in for the shipped template in tests.
+ */
+export declare function syncClaudeMdSync(opts: {
+    targetDir: string;
+    templateText?: string;
+}): SyncClaudeMdResult;
+/** Re-exported beside the other sync results so consumers see one surface. */
+export type { SyncClaudeMdResult } from "./claude-md.js";
 export interface SyncRoutesSyncOptions {
     /** The already-scaffolded repo to sync (absolute or relative). */
     targetDir: string;

package/dist/programmatic.js

@@ -19,20 +19,28 @@ import { existsSync, readdirSync, readFileSync, rmdirSync, rmSync, statSync, wri
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { AddModuleRefusedError, 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 { applyDesignPresets, readSectionLookCatalog, shippedPageTypes, validateDesignPresets, } from "./design-presets.js";
+import { installDesignSample, 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 { FREE_DESIGNS, assertDesignAllowed, deriveLevel, resolveModuleSet, resolvePaidModules, } from "./lib/module-license-gate.js";
+import { assertDesignAllowed, deriveLevel, resolveModuleSet, resolvePaidModules, } from "./lib/module-license-gate.js";
 import { classifyModules } from "./lib/module-tier.js";
 import { normalizeModules } from "./module-architecture.js";
 import { RECOGNIZED_SHAPES, RESERVED_SHAPES, } from "./parse-args.js";
 import { SITE_CHROME_PATH, renderSiteChrome, resolveSiteChrome, } from "./site-chrome.js";
+import { planSiteManifest } from "./site-manifest.js";
+import { SITE_ROSTER_PATH, 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, STARTER_DESIGNS, TEMPLATE_MANIFESTS, TemplateError, mergeRoster, resolveTemplate, resolveTemplateLineage, rosterDeclares, templateDelivery, templateTreeDir, } from "./template-manifest.js";
+import { BASE_LAYER_DIR, SHAPE_STARTERS, TEMPLATE_MANIFESTS, TemplateError, mergeRoster, resolveTemplate, resolveTemplateLineage, rosterDeclares, templateDelivery, templateTreeDir, } 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");
@@ -45,6 +53,8 @@ const TEMPLATES_DIR = resolve(PKG_ROOT, "templates");
  * `package.json` `files` instead.
  */
 const SITE_TEMPLATES_DIR = resolve(PKG_ROOT, "site-templates");
+/** Where shipped design packages live (#6813 D2) — `resolveDesign`'s `designsDir`. */
+const DESIGNS_DIR = join(SITE_TEMPLATES_DIR, "designs");
 const VERSIONS_FILE = resolve(PKG_ROOT, "versions.json");
 function readVersionMap() {
     if (!existsSync(VERSIONS_FILE)) {
@@ -76,6 +86,24 @@ function countFiles(dir) {
     }
     return count;
 }
+/** Every `.mdx` file under `dir`, recursively, sorted (#6816 D6). */
+function listMdxFiles(dir) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    const stack = [dir];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        for (const entry of readdirSync(current, { withFileTypes: true })) {
+            const abs = join(current, entry.name);
+            if (entry.isDirectory())
+                stack.push(abs);
+            else if (entry.name.endsWith(".mdx"))
+                out.push(abs);
+        }
+    }
+    return out.sort();
+}
 /**
  * The template a `shape` scaffolds (#6754 D5, extended #6757 D6 row 1): the
  * one FREE-delivery manifest of that shape — a declared `--template` alias
@@ -128,6 +156,9 @@ export function scaffoldSync(opts) {
         excludePaths: excludedRoutePaths(enabledSurfaces),
         markers: buildScaffoldMarkers(projectName),
     });
+    // 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));
     // Derive + write the module-set-driven architecture.yaml (spec #3787). This
     // is the single source of the scaffolded site's code-boundary config and
     // closes the dangling `architecture_rules: architecture.yaml` reference in
@@ -144,7 +175,7 @@ export function scaffoldSync(opts) {
     // 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, opts.design)));
+    writeFileSync(join(targetAbs, SITE_CHROME_PATH), renderSiteChrome(resolveSiteChrome(opts.layout, opts.designLayout)));
     // 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)
@@ -209,12 +240,32 @@ export async function scaffold(opts) {
         : opts.shape !== undefined
             ? resolveShapeTemplate(opts.shape)
             : undefined;
-    // #6638 — the design this scaffold renders: the caller's override, else the
-    // template's own. Unset for a scaffold naming neither.
-    const design = opts.design ?? template?.design;
-    if (design !== undefined && !STARTER_DESIGNS.includes(design)) {
-        throw new TemplateError(`unknown design "${design}". Declared: ${STARTER_DESIGNS.join(", ")}`);
+    // #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
+    // `STARTER_DESIGNS.includes` name check: an unrecognized name or a missing
+    // directory throws `TemplateError` here; a malformed package throws
+    // `DesignPackageError` (never caught), each naming the field.
+    const designRef = opts.design ?? template?.design;
+    const resolvedDesign = designRef !== undefined
+        ? resolveDesign(designRef, { designsDir: DESIGNS_DIR })
+        : undefined;
+    // #6816 D6 step 3b — a design's section presets are validated here, before
+    // any fetch or write, against the look groups the shipped catalog carries
+    // (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).
+    if (resolvedDesign !== undefined &&
+        Object.keys(resolvedDesign.pkg.sections).length > 0) {
+        validateDesignPresets(resolvedDesign.pkg.sections, {
+            catalog: readSectionLookCatalog(join(PKG_ROOT, "component-catalog.json")),
+            pageTypes: shippedPageTypes(SITE_TEMPLATES_DIR),
+            file: join(resolvedDesign.dir, "DESIGN.md"),
+        });
     }
+    // #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;
     // #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. The registry is the
@@ -260,11 +311,11 @@ export async function scaffold(opts) {
         // #6760 — `resolveModuleSet` never runs on this branch (NFR-4), so no
         // level was derived above. Derive one — from the registry's per-module
         // answers, never a key claim (D2) — only when the caller CHOSE a
-        // non-`standard` design alongside the template (`opts.design`). An
+        // non-Free design alongside the template (`opts.design`, #6813 D7). An
         // alias's own declared design is never gated (#6778 option (c)), so a
         // plain `--template minimalism-site` run makes no extra network call and
         // is never refused on its design.
-        if (opts.design !== undefined && !FREE_DESIGNS.includes(opts.design)) {
+        if (chosenDesign !== undefined && !chosenDesign.free) {
             ({ level } = await deriveLevel({
                 licenseKey,
                 ...(opts.moduleRegistryUrl !== undefined
@@ -317,8 +368,11 @@ export async function scaffold(opts) {
     // 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-`standard` design on that path is refused rather than trusted.
-    assertDesignAllowed(opts.design, level ?? "free");
+    // chosen non-Free design on that path is refused rather than 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).
+    assertDesignAllowed(chosenDesign?.display, level ?? "free", chosenDesign?.free);
     // 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
@@ -372,7 +426,9 @@ export async function scaffold(opts) {
         // design's knobs (#6638), and a `standard` one to the same defaults
         // `scaffoldSync` already writes for a templateless scaffold.
         ...(template?.layout !== undefined ? { layout: template.layout } : {}),
-        ...(design !== undefined ? { design } : {}),
+        // #6813 D8 step 6 — the resolved design's OWN layout (never its name):
+        // `resolveSiteChrome` reads a layout object now, not a `StarterDesign`.
+        ...(resolvedDesign !== undefined ? { designLayout: resolvedDesign.pkg.layout } : {}),
     });
     // Threaded to extractModuleBundle for `package.json` patch targets'
     // `workspace:*` substitution (spec 5418 § 3 D2) — the same version map
@@ -437,6 +493,11 @@ 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.
+    // #6813 D6 — captured for the site-manifest record below, which needs the
+    // chrome ACTUALLY written (`installedLayout ?? template.layout`), readable
+    // only after this block (the bundle's own `layout`, when it declares one,
+    // is unreachable before install).
+    let installedLayout;
     if (template !== undefined) {
         // #5612 D1/D2 — the INSTALLED template's own `ailk-template.json` layout
         // (validated by `readAilkTemplateManifest`), if it declares one. Read
@@ -472,21 +533,131 @@ export async function scaffold(opts) {
                     ownership,
                 });
             })();
+        installedLayout = installed.layout;
         if (installed.layout !== undefined) {
-            writeFileSync(join(result.targetDir, SITE_CHROME_PATH), renderSiteChrome(resolveSiteChrome(installed.layout, design)));
+            writeFileSync(join(result.targetDir, SITE_CHROME_PATH), renderSiteChrome(resolveSiteChrome(installed.layout, resolvedDesign?.pkg.layout)));
         }
+        // #6878 D6 — re-render the nav with the SERVICE slugs the installed tree
+        // just landed (`content/en/Service/*.mdx`, absent on a product shape),
+        // now that `content/en/Service` exists to read. `scaffoldSync`'s own
+        // one-argument render above already wrote a nav for `result.surfaces`
+        // BEFORE the template tree existed — byte-identical to this one on a
+        // product shape (no Service directory to read), and this is what makes a
+        // service shape's flyout show its own Services column instead of an
+        // empty offering column. Unconditional (every templated scaffold gets
+        // this second render, not only one that resolved a `layout`), and BEFORE
+        // `pruneUnrosteredSeeds` below: the read reflects every seed the install
+        // step actually wrote, not what a later prune leaves behind.
+        const serviceContentDir = join(result.targetDir, "content", "en", "Service");
+        const serviceSlugs = existsSync(serviceContentDir)
+            ? readdirSync(serviceContentDir)
+                .filter((f) => f.endsWith(".mdx"))
+                .map((f) => f.slice(0, -".mdx".length))
+            : [];
+        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 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,
+    // spliced into the scaffold's `content/_site.mdx` LAST; then the site manifest records the APPLIED
+    // design, only when a template installed one (`saas-product` ships none).
+    // A scaffold naming neither a design nor a template (the bare overlay)
+    // executes no new statement.
+    if (resolvedDesign !== undefined) {
+        // #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));
+        const compiledTheme = compileDesignTheme(resolvedDesign.pkg);
+        const siteMdxPath = join(result.targetDir, "content", "_site.mdx");
+        if (existsSync(siteMdxPath)) {
+            const current = readFileSync(siteMdxPath, "utf8");
+            const spliced = spliceThemeBlock(current, compiledTheme, siteMdxPath);
+            if (spliced !== current)
+                writeFileSync(siteMdxPath, spliced);
+        }
+        if (template !== undefined) {
+            const rosterPath = join(result.targetDir, SITE_ROSTER_PATH);
+            if (existsSync(rosterPath)) {
+                const rosterText = readFileSync(rosterPath, "utf8");
+                const chromeWritten = resolveSiteChrome(installedLayout ?? template.layout, resolvedDesign.pkg.layout);
+                const nextManifest = planSiteManifestDesign(rosterText, { design: resolvedDesign.recorded, layout: chromeWritten, theme: compiledTheme }, rosterPath);
+                if (nextManifest !== undefined)
+                    writeFileSync(rosterPath, nextManifest);
+            }
+        }
+        // #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
+        // roster (the bare overlay, `saas-product`) validated its presets at
+        // step 3b and applies none: nothing "the shape placed" to resolve against.
+        if (template !== undefined &&
+            Object.keys(resolvedDesign.pkg.sections).length > 0) {
+            const roster = readSiteRoster(result.targetDir);
+            if (roster !== undefined) {
+                const pageTypes = new Set();
+                for (const row of roster.rows) {
+                    const pageType = row.value["pageType"];
+                    if (typeof pageType === "string")
+                        pageTypes.add(pageType);
+                }
+                const contentDir = join(result.targetDir, "content");
+                const pages = listMdxFiles(contentDir)
+                    .filter((path) => path !== join(contentDir, "_site.mdx"))
+                    .map((path) => ({ path, text: readFileSync(path, "utf8") }));
+                const presetResult = applyDesignPresets(pages, resolvedDesign.pkg.sections, { pageTypes });
+                for (const page of presetResult.pages)
+                    writeFileSync(page.path, page.text);
+            }
+        }
+    }
+    // #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
+    // level only when the key path above derived one — `resolveModuleSet`, or
+    // `deriveLevel` for a chosen non-Free design. `level` stays undefined on a
+    // plain alias or `--modules`-keep run, and is never inferred from `modules`.
+    // A scaffold with no manifest (the bare overlay, `saas-product`) writes none.
+    if (template !== undefined) {
+        const roster = readSiteRoster(result.targetDir);
+        if (roster !== undefined) {
+            writeFileSync(join(result.targetDir, roster.path), planSiteManifest({
+                targetDir: result.targetDir,
+                roster,
+                modules: result.modules,
+                level,
+                siteTemplatesDir: SITE_TEMPLATES_DIR,
+                templatesDir: TEMPLATES_DIR,
+                markers,
+            }));
+        }
+    }
+    // #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);
     // #6683 D9 — persisted only after every layer landed, and only when the
     // caller passed `license`: a scaffold without it writes nothing new.
     if (opts.license !== undefined) {
         writeLicenseKeyFiles(result.targetDir, opts.license);
     }
     // #6754 D4/D5 — the resolved starter, so the CLI names what it built.
-    if (template !== undefined && design !== undefined) {
+    if (template !== undefined && resolvedDesign !== undefined) {
         return {
             ...result,
-            starter: { template: template.name, shape: template.shape, design },
+            starter: { template: template.name, shape: template.shape, design: resolvedDesign.recorded },
         };
     }
     return result;
@@ -506,12 +677,17 @@ export async function scaffold(opts) {
  * the content directory of a surface this scaffold ENABLES is kept too, so
  * an explicit `--surfaces pricing` on a template that does not roster
  * `/pricing` gets its route and its seed together.
+ *
+ * The Free `/meet` placeholder seeds count as declared wherever the roster
+ * claims their route, the `scheduling` module's rows included (#6942): an
+ * unconfigured scheduling site's /meet pages hand off to them.
  */
 function pruneUnrosteredSeeds(targetDir, roster, surfaces, ownership) {
     // `installBundleTree`'s ownership label for the base layer: it installs
     // with `templateRequires: []`, so it records as a template. The overlay
     // (the `templates/` snapshot) records no owner at all.
     const shared = new Set([undefined, `template "${BASE_LAYER_DIR}"`]);
+    const declared = withMeetPlaceholderSeeds(roster);
     const enabledDirs = GATEABLE_SURFACES.filter((surface) => surfaces.includes(surface.id)).flatMap((surface) => surface.content.map((dir) => `${dir.replace("<locale>", "en")}/`));
     const root = join(targetDir, "content", "en");
     if (!existsSync(root))
@@ -531,7 +707,7 @@ function pruneUnrosteredSeeds(targetDir, roster, surfaces, ownership) {
                 continue;
             const path = relative(targetDir, abs).split(sep).join("/");
             if (shared.has(ownership.get(path)) &&
-                !rosterDeclares(roster, path) &&
+                !rosterDeclares(declared, path) &&
                 !enabledDirs.some((prefix) => path.startsWith(prefix))) {
                 rmSync(abs);
                 if (readdirSync(dir).length === 0)
@@ -664,6 +840,19 @@ export function syncCatalogSync(opts) {
         catalogPath: writeComponentCatalog(targetAbs),
     };
 }
+/**
+ * Rewrite the template-owned sections of an already-scaffolded repo's root
+ * `CLAUDE.md` to the template this create-ailk ships (#6904 D3). The logic
+ * lives in `claude-md.ts` (a module jest imports directly); this wrapper
+ * only supplies the package's `templates/CLAUDE.md` — the `syncRoutesSync`
+ * split. `templateText` stands in for the shipped template in tests.
+ */
+export function syncClaudeMdSync(opts) {
+    return syncClaudeMd({
+        targetDir: opts.targetDir,
+        templateText: opts.templateText ?? readFileSync(join(TEMPLATES_DIR, "CLAUDE.md"), "utf8"),
+    });
+}
 /**
  * Compare an already-scaffolded repo's route tree with the template this
  * create-ailk ships and, with `apply`, copy in the route dirs it is missing

package/dist/site-chrome.d.ts

@@ -21,11 +21,14 @@
  * block, gets these defaults written, byte-identical to the monorepo's own
  * committed `apps/web/lib/site-chrome.ts`.
  *
- * A template's DESIGN supplies layout knobs too (#6638): `DESIGN_LAYOUTS` in
- * `template-manifest.ts`, read by `resolveSiteChrome`'s optional `design`
- * argument between an explicit `layout` and these defaults.
+ * A design supplies layout knobs too (#6638, widened #6813 D4): its OWN
+ * `layout` (a `DesignPackage`'s, read by `design-scaffold.ts`'s
+ * `resolveDesign`), passed as `resolveSiteChrome`'s optional `designLayout`
+ * argument between an explicit `layout` and these defaults. This module
+ * imports nothing from `template-manifest.ts` (the cycle that import used to
+ * close): an unrecognized design NAME now fails in `resolveDesign`, before
+ * this function ever sees one.
  */
-import { type StarterDesign } from "./template-manifest.js";
 /** 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";
@@ -75,12 +78,19 @@ export declare class TemplateLayoutError extends Error {
  */
 export declare function validateTemplateLayout(value: unknown, subject: string): TemplateLayout;
 /**
- * Fill every field a `TemplateLayout` leaves unset — from `design`'s
- * `DESIGN_LAYOUTS` entry when one is named (#6638), then from
- * `DEFAULT_SITE_CHROME`. The explicit `layout` wins field by field, so a
- * template can wear a design and still override one knob of it.
+ * Fill every field a `TemplateLayout` leaves unset — from `designLayout`
+ * (a design package's own resolved `layout`, #6638/#6813 D4) when one is
+ * given, then from `DEFAULT_SITE_CHROME`. The explicit `layout` wins field by
+ * field, so a template can wear a design and still override one knob of it.
+ *
+ * `designLayout` is typed `TemplateLayout`, but a `.mjs` caller
+ * (`build-template-manifest.mjs`) cannot be compile-time checked the way a
+ * `.ts` caller can, so the type alone cannot stop a caller passing a design
+ * NAME (a string) rather than its resolved layout: a runtime guard throws a
+ * `TypeError` naming what was given, rather than silently resolving to the
+ * defaults.
  */
-export declare function resolveSiteChrome(layout?: TemplateLayout, design?: StarterDesign): ResolvedSiteChrome;
+export declare function resolveSiteChrome(layout?: TemplateLayout, designLayout?: TemplateLayout): ResolvedSiteChrome;
 /**
  * Render `apps/web/lib/site-chrome.ts` for a resolved layout — the same
  * GENERATED-header idiom `renderNavConfig` uses. `layout.tsx` imports

package/dist/site-chrome.js

@@ -21,11 +21,14 @@
  * block, gets these defaults written, byte-identical to the monorepo's own
  * committed `apps/web/lib/site-chrome.ts`.
  *
- * A template's DESIGN supplies layout knobs too (#6638): `DESIGN_LAYOUTS` in
- * `template-manifest.ts`, read by `resolveSiteChrome`'s optional `design`
- * argument between an explicit `layout` and these defaults.
+ * A design supplies layout knobs too (#6638, widened #6813 D4): its OWN
+ * `layout` (a `DesignPackage`'s, read by `design-scaffold.ts`'s
+ * `resolveDesign`), passed as `resolveSiteChrome`'s optional `designLayout`
+ * argument between an explicit `layout` and these defaults. This module
+ * imports nothing from `template-manifest.ts` (the cycle that import used to
+ * close): an unrecognized design NAME now fails in `resolveDesign`, before
+ * this function ever sees one.
  */
-import { DESIGN_LAYOUTS, TemplateError, } from "./template-manifest.js";
 /** Defaults (#5612 D1; banner off since #6469). */
 export const DEFAULT_SITE_CHROME = {
     nav: "full",
@@ -92,17 +95,24 @@ export function validateTemplateLayout(value, subject) {
     return result;
 }
 /**
- * Fill every field a `TemplateLayout` leaves unset — from `design`'s
- * `DESIGN_LAYOUTS` entry when one is named (#6638), then from
- * `DEFAULT_SITE_CHROME`. The explicit `layout` wins field by field, so a
- * template can wear a design and still override one knob of it.
+ * Fill every field a `TemplateLayout` leaves unset — from `designLayout`
+ * (a design package's own resolved `layout`, #6638/#6813 D4) when one is
+ * given, then from `DEFAULT_SITE_CHROME`. The explicit `layout` wins field by
+ * field, so a template can wear a design and still override one knob of it.
+ *
+ * `designLayout` is typed `TemplateLayout`, but a `.mjs` caller
+ * (`build-template-manifest.mjs`) cannot be compile-time checked the way a
+ * `.ts` caller can, so the type alone cannot stop a caller passing a design
+ * NAME (a string) rather than its resolved layout: a runtime guard throws a
+ * `TypeError` naming what was given, rather than silently resolving to the
+ * defaults.
  */
-export function resolveSiteChrome(layout, design) {
-    const fromDesign = design !== undefined ? DESIGN_LAYOUTS[design] : {};
-    // A JS caller (or a cast) can reach here with an undeclared design.
-    if (fromDesign === undefined) {
-        throw new TemplateError(`unknown design "${design}". Declared: ${Object.keys(DESIGN_LAYOUTS).join(", ")}`);
+export function resolveSiteChrome(layout, designLayout) {
+    if (designLayout !== undefined &&
+        (typeof designLayout !== "object" || designLayout === null || Array.isArray(designLayout))) {
+        throw new TypeError(`resolveSiteChrome: designLayout must be a layout object, got ${JSON.stringify(designLayout)}`);
     }
+    const fromDesign = designLayout ?? {};
     return {
         nav: layout?.nav ?? fromDesign.nav ?? DEFAULT_SITE_CHROME.nav,
         footer: layout?.footer ?? fromDesign.footer ?? DEFAULT_SITE_CHROME.footer,

package/dist/site-manifest.d.ts

@@ -0,0 +1,25 @@
+import type { Level } from "./lib/module-tier.js";
+import type { ModuleName } from "./parse-args.js";
+import { type SiteRoster } from "./site-roster.js";
+import type { MarkerMap } from "./substitute.js";
+export interface PlanSiteManifestOptions {
+    targetDir: string;
+    /** The installed manifest, read after every layer landed. */
+    roster: SiteRoster;
+    /** The effective module set the scaffold installed. */
+    modules: readonly ModuleName[];
+    /** The level the key path derived, or undefined when it derived none. */
+    level: Level | undefined;
+    siteTemplatesDir: string;
+    templatesDir: string;
+    markers: MarkerMap;
+}
+/**
+ * The manifest's next text: `modules` (and `level`, when derived) after
+ * `requires`, and a row for every route present on disk.
+ *
+ * @throws AddModuleRefusedError when the file already records `modules` or
+ *   `level`, or its layout is not the generator's (`rows` last, `requires`
+ *   at the top level) — guessing would silently mis-record the site.
+ */
+export declare function planSiteManifest(opts: PlanSiteManifestOptions): string;