create-ailk 0.13.0 → 0.15.0

package/component-catalog.md

@@ -15,13 +15,13 @@ The component inventory of `@working-theory/ui` and the shells of `@working-theo
 3. Check the Primitives, Panels and Shells tables too — a low-level control, a collapsible layout container, or a route-level frame lives there, not under Sections or Blocks.
 4. Only then build. If you do build, you are declaring the capability is genuinely absent.
 
-Inventory: **307 component files** across 16 tiers — 55 sections, 99 blocks, 18 chrome, 79 primitives, 6 panels, 6 shells, 5 docs-blog-blocks, 1 docs-blog-chrome, 2 docs-blog-shells, 2 scheduling-sections, 5 scheduling-blocks, 5 signal-collectors-sections, 9 signal-collectors-blocks, 2 commerce-sections, 12 commerce-blocks, 1 commerce-panels. 304 distinct names: `SchedulerEmbed`, `Separator`, `Tabs` exist in more than one tier as genuinely different components, listed once per tier with its own source path.
+Inventory: **311 component files** across 16 tiers — 55 sections, 101 blocks, 18 chrome, 79 primitives, 6 panels, 8 shells, 5 docs-blog-blocks, 1 docs-blog-chrome, 2 docs-blog-shells, 2 scheduling-sections, 5 scheduling-blocks, 5 signal-collectors-sections, 9 signal-collectors-blocks, 2 commerce-sections, 12 commerce-blocks, 1 commerce-panels. 308 distinct names: `SchedulerEmbed`, `Separator`, `Tabs` exist in more than one tier as genuinely different components, listed once per tier with its own source path.
 
-Description coverage: **303/307** components carry a capability description derived from source — 44 from the section registry's hand-authored when-to-use text, 228 from the component's own doc-comment header, 31 from its tier barrel's roster line. **4** have none; they are listed under [Undescribed components](#undescribed-components) rather than given a sentence invented from their name.
+Description coverage: **307/311** components carry a capability description derived from source — 44 from the section registry's hand-authored when-to-use text, 232 from the component's own doc-comment header, 31 from its tier barrel's roster line. **4** have none; they are listed under [Undescribed components](#undescribed-components) rather than given a sentence invented from their name.
 
-Of those, **272** are *strong* — a capability sentence you could match a requirement against — and **31** are *weak*: either one short clause, or a long one that spends itself on wiring (client boundaries, class names, which primitives it composes) instead of on what the thing is for. Weak rows are marked `(weak)` and listed in full under [Weak descriptions](#weak-descriptions). Coverage is 99%, but **findable-without-luck coverage is 89%**.
+Of those, **276** are *strong* — a capability sentence you could match a requirement against — and **31** are *weak*: either one short clause, or a long one that spends itself on wiring (client boundaries, class names, which primitives it composes) instead of on what the thing is for. Weak rows are marked `(weak)` and listed in full under [Weak descriptions](#weak-descriptions). Coverage is 99%, but **findable-without-luck coverage is 89%**.
 
-Per tier, strong out of total: **Sections** 54/55 · **Blocks** 93/99 · **Chrome** 10/18 · **Primitives** 64/79 (4 undescribed) · **Panels** 5/6 · **Shells** 5/6 · **Docs + Blog Blocks** 5/5 · **Docs + Blog Chrome** 1/1 · **Docs + Blog Shells** 0/2 · **Scheduling Sections** 2/2 · **Scheduling Blocks** 5/5 · **Signal-Collectors Sections** 5/5 · **Signal-Collectors Blocks** 8/9 · **Commerce Sections** 2/2 · **Commerce Blocks** 12/12 · **Commerce Panels** 1/1. A tier low on this line is a tier where a capability search is most likely to come up empty on something that exists.
+Per tier, strong out of total: **Sections** 54/55 · **Blocks** 95/101 · **Chrome** 10/18 · **Primitives** 64/79 (4 undescribed) · **Panels** 5/6 · **Shells** 7/8 · **Docs + Blog Blocks** 5/5 · **Docs + Blog Chrome** 1/1 · **Docs + Blog Shells** 0/2 · **Scheduling Sections** 2/2 · **Scheduling Blocks** 5/5 · **Signal-Collectors Sections** 5/5 · **Signal-Collectors Blocks** 8/9 · **Commerce Sections** 2/2 · **Commerce Blocks** 12/12 · **Commerce Panels** 1/1. A tier low on this line is a tier where a capability search is most likely to come up empty on something that exists.
 
 That grade is **mechanical**. It counts what it can measure — how much a description adds beyond the component's own name, how much of it is spent on wiring, whether the extraction came out damaged — and it cannot tell a fluent paragraph about the wrong subject from a useful one. A person reading these tables will find more rows unusable than the weak count admits. Treat it as a floor on the problem, not a measurement of it, and read the source before concluding a capability is absent.
 
@@ -119,7 +119,7 @@ Import: `import { X } from "@working-theory/ui/sections";` (or from the `@workin
 
 ---
 
-## Blocks (99)
+## Blocks (101)
 
 Intermediate composition tiles — the pieces sections are built from. Compose primitives and panels; never import a section.
 
@@ -158,6 +158,7 @@ Import: `import { X } from "@working-theory/ui/blocks";` (or from the `@working-
 | `DescriptionList` | Semantic <dl> of aligned term/definition rows (rows + inline layouts). A semantic <dl> rendering label/value rows from an `items` prop. Each item is a <dt> (muted term) paired with a <dd> (value). The value is a ReactNode, so callers compose richer values (spans, lists, mono text) inside it. | `import { DescriptionList } from "@working-theory/ui/blocks"` |
 | `DetailCard` | The collapsible console / data-panel card: a composable card with a header (title + optional actions + collapse toggle), an optional tab bar, a body slot, and an optional footer. The "deferred SidePanel DetailCard" from, built as a general content card any console / detail view can compose without inventing its own card structure. | `import { DetailCard } from "@working-theory/ui/blocks"` |
 | `DetailHeader` | The entity-bearing sibling of PageHeader: a Breadcrumb wayfinding trail above an EntityHeader identity row, plus a forwarded actions slot. | `import { DetailHeader } from "@working-theory/ui/blocks"` |
+| `DisplayList` | Centred display-size rows of short labels, each optionally a link, with no rules, cards or dividers between them — the bondcap.com "what we offer" list and its report archive grid. | `import { DisplayList } from "@working-theory/ui/blocks"` |
 | `DistributionList` | Per-option answer-share list over the Progress primitive. One question's answer distribution: a title, an "answered" count line, and one row per declared option (a label, a pre-formatted share `display` string, and a `Progress` bar). `display` is pre-formatted by the caller (Rule 10 — this block never formats numbers itself); `share` drives the `Progress` fill, scaled to the primitive's 0–100 range. | `import { DistributionList } from "@working-theory/ui/blocks"` |
 | `EntityHeader` | The single identity-row source: an optional leading avatar, a title/name (Heading), an optional subtitle/meta line (Text), an optional type-badge slot above the title, and an optional trailing actions slot. | `import { EntityHeader } from "@working-theory/ui/blocks"` |
 | `FaqItem` | Q&A pair block for FAQ section families (expanded + accordion). Defaults reproduce the current render except the deliberate item-spacing-asymmetry fix. | `import { FaqItem } from "@working-theory/ui/blocks"` |
@@ -208,6 +209,7 @@ Import: `import { X } from "@working-theory/ui/blocks";` (or from the `@working-
 | `SectionHeader` | Alignment-parameterized section header (eyebrow/subtitle/description/supportLink). The same component serves two ranks (headingLevel="section" \| "subsection") and three alignments (align="start" \| "center" \| "end"). It knows nothing about columns/splits/carousels — it is width-flexible and fills whatever container the section places it in. | `import { SectionHeader } from "@working-theory/ui/blocks"` |
 | `ShareBar` | The reader-facing counterpart to DocsActionBar. Both surfaces share the same SplitButton *affordance + slot* (outline variant, right-justified on the post title row) but fill it with different actions: DocsActionBar carries the AI-ingestion set (Copy page + Open in …), ShareBar carries the social-share set (X · LinkedIn · Bluesky · Copy link). One primitive, two configs. | `import { ShareBar } from "@working-theory/ui/blocks"` |
 | `SinglePriceCard` | 2-column split card for the Pricing 'single-price-with-details' variant. *(weak)* | `import { SinglePriceCard } from "@working-theory/ui/blocks"` |
+| `SlideAdvance` | The deck's slide-advance control. One ghost Button holding a hairline chevron: a down chevron moves to the next slide, an up chevron to the first. A native button, so a click, Enter and Space all fire the same move, and nothing else listens: no wheel, touch, scroll or key handler is added, so native scroll-snap still settles every user scroll (the argument against a scroll-hijacking deck). | `import { SlideAdvance } from "@working-theory/ui/blocks"` |
 | `SocialIcons` | Horizontal row of social icon links. Renders brand icons (via Icon primitive + simple-icons paths) inside accessible Link primitives. Each platform link gets an aria-label. Shared by company-mission, simple-centered, and newsletter-below footer variants, and composed by TeamMemberCard for member social links. *(weak)* | `import { SocialIcons } from "@working-theory/ui/blocks"` |
 | `SortableList` | The one @dnd-kit/sortable reorder block: mouse, touch and keyboard drag behind a six-dot grip, announced, controlled. `@dnd-kit/sortable` wrapped ONCE behind our six-dot grip. The ONLY file in the monorepo that imports `@dnd-kit/*` — enforced by tests/architecture/no-dnd-kit-outside-sortablelist.test.ts (SD-2). | `import { SortableList } from "@working-theory/ui/blocks"` |
 | `StatTicker` | Static, horizontally overflow-scrollable workspace stat strip with an optional trailing CTA; no auto-scroll marquee (ploy-capture recomposition). The Overview stat strip captured off ploy.ai (behavior spec: -2, — `overview-ticker` "-viewport"/"-track"/"-segment"/"-value"/"-cta"). | `import { StatTicker } from "@working-theory/ui/blocks"` |
@@ -365,7 +367,7 @@ Import: `import { X } from "@working-theory/ui/panels";` (or from the `@working-
 
 ---
 
-## Shells (6)
+## Shells (8)
 
 Route-level slot-frames — the outermost layout a page is placed into. They supply geometry and slots (nav / sidebar / main / footer), not content: you inject the real Nav, Footer and sidebar. A different package from every tier above: `@working-theory/templates`.
 
@@ -377,6 +379,8 @@ Import: `import { X } from "@working-theory/templates/shells";` (or from the `@w
 | `AppShell` | Shared authed-app base frame. Layout ownership: AppShell is the SINGLE owner of the authed sidebar frame layout. The `sidebar` prop is CONTENT (e.g. a <SidebarNav>), never a layout component. Do NOT pass SidebarShell or FixedPanel as the sidebar — that nests two incompatible layout systems (a fixed-width shell vs a variable-width panel). | `import { AppShell } from "@working-theory/templates/shells"` |
 | `AuthShell` | The frame the five auth pages (/sign-in, /sign-up, /forgot-password, /reset-password, /verify-email) share: a brand mark top-start, one centered content column, and a slim footer. No nav — an auth page has nothing to navigate to, and the marketing Nav is exactly what this shell exists to replace on those routes. | `import { AuthShell } from "@working-theory/templates/shells"` |
 | `DeckHeroObserver` | Internal client island for MarketingShell's `deckHero` option. | internal — compose from `packages/templates/src/shells/DeckHeroObserver.tsx` |
+| `DeckPresentation` | Internal client island for MarketingShell's `presentation` option. Not exported from the shells barrel (`./index.ts`) — MarketingShell renders it internally under `snap="mandatory"` with `presentation`, beside DeckHeroObserver, whose idiom it follows: a zero-size anchor, no React state, and every write made through the DOM after hydration. | internal — compose from `packages/templates/src/shells/DeckPresentation.tsx` |
+| `DeckSlideAdvance` | Internal client island that puts one working slide-advance button at the foot of every slide of MarketingShell's scroll-snap deck: down to the next slide, and up from the last slide back to the first. | internal — compose from `packages/templates/src/shells/DeckSlideAdvance.tsx` |
 | `MarketingShell` | Public-facing marketing site **slot-frame**. Server Component (RSC default). A shell is a slot-defining frame: it carves out *where chrome goes* (top + bottom) and *where sections go* (the body), owning **geometry only**. Chrome (Nav/Footer) and sections **fill** the slots — nothing is baked into the component. See (first instance). *(weak)* | `import { MarketingShell } from "@working-theory/templates/shells"` |
 | `SignedInShell` | Every AILK signed-in area runs on this frame: the admin app's workspace (AppFrame supplies its switcher, Library and gating as content) and a site's own /account area. | `import { SignedInShell } from "@working-theory/templates/shells"` |
 

package/dist/add-module.d.ts

@@ -4,6 +4,13 @@ import { type ModulePatch } from "./module-architecture.js";
 import { type ModuleName } from "./parse-args.js";
 import type { MarkerMap, WorkspaceVersionMap } from "./substitute.js";
 import { type SyncRoutesResult } from "./sync-routes.js";
+import { type Topology } from "./topology.js";
+/**
+ * The site's topology for add-module (#7426 D13): an unreadable manifest is a
+ * refusal this command names (exit 2), before the first write — the same
+ * posture as its unreadable-roster refusal.
+ */
+export declare function addModuleSiteTopology(targetDir: string): Topology;
 export { AddModuleRefusedError, readArchitectureHeader };
 /**
  * One report row: a bundle file written, patched or skipped, or a seed the

package/dist/add-module.js

@@ -39,6 +39,22 @@ import { ParseError, parseModules } from "./parse-args.js";
 import { SITE_ROSTER_PATH, moduleRosterRows, planRosterAppend, readSiteRoster, siteRosterProblems, } from "./site-roster.js";
 import { MODULE_SURFACES, NAV_CONFIG_PATH, readNavConfigStamp, renderNavConfig, resolveSurfaces, } from "./surfaces.js";
 import { syncRoutes } from "./sync-routes.js";
+import { TopologyError, isSpokeExcluded, readSiteTopology, spokeModuleRefusal, } from "./topology.js";
+/**
+ * The site's topology for add-module (#7426 D13): an unreadable manifest is a
+ * refusal this command names (exit 2), before the first write — the same
+ * posture as its unreadable-roster refusal.
+ */
+export function addModuleSiteTopology(targetDir) {
+    try {
+        return readSiteTopology(targetDir);
+    }
+    catch (err) {
+        if (err instanceof TopologyError)
+            throw new AddModuleRefusedError(err.message);
+        throw err;
+    }
+}
 export { AddModuleRefusedError, readArchitectureHeader };
 /** `package.json` paths a `json` patch may write under the plus-config policy. */
 const PACKAGE_JSON_PATCH_KEYS = new Set([
@@ -86,6 +102,17 @@ export function checkPlusConfigPatches(patches) {
 export async function applyModuleToScaffold(opts) {
     const targetAbs = resolve(opts.targetDir);
     const archPath = join(targetAbs, "architecture.yaml");
+    // #7426 D13 — a spoke stays a spoke: a module it does not admit is refused
+    // before the first write, and an admitted one lands through the spoke
+    // filter. `mcp` follows whether the spoke still carries apps/mcp.
+    const spoke = addModuleSiteTopology(targetAbs) === "spoke"
+        ? { mcp: existsSync(join(targetAbs, "apps", "mcp")) }
+        : undefined;
+    if (spoke !== undefined) {
+        const refusal = spokeModuleRefusal(opts.moduleName);
+        if (refusal !== undefined)
+            throw new AddModuleRefusedError(refusal);
+    }
     const current = readArchitectureHeader(readFileSync(archPath, "utf8"));
     const modules = normalizeModules([...current.modules, opts.moduleName]);
     // Resolved before the first write: a header surface that is unknown, or
@@ -112,6 +139,9 @@ export async function applyModuleToScaffold(opts) {
         markers: opts.markers,
         existingFilePolicy: "skip-existing",
         checkPatches: checkPlusConfigPatches,
+        ...(spoke !== undefined
+            ? { skip: (destination) => isSpokeExcluded(destination, spoke) }
+            : {}),
     });
     const routes = syncRoutes({
         targetDir: targetAbs,
@@ -123,10 +153,12 @@ export async function applyModuleToScaffold(opts) {
     // #6107 D8 — a module that brings `apps/admin` brings its auth hard-fail;
     // the Admin app gets the web app's effective secret, and a secret already
     // held in any Next-loaded env file is never shadowed.
-    writeAuthSecretFile(targetAbs);
+    // A spoke has no sign-in (#7426 D13), so it gets no secret.
+    if (spoke === undefined)
+        writeAuthSecretFile(targetAbs);
     // The same composition `syncArchitectureSync` writes — a pure function of
     // the module set, so an unchanged set rewrites identical bytes.
-    writeFileSync(archPath, deriveArchitecture(modules, surfaces));
+    writeFileSync(archPath, deriveArchitecture(modules, surfaces, spoke !== undefined ? { topology: "spoke", mcp: spoke.mcp } : {}));
     // #7536 D3 — the paid-sections registry follows `apps/web/package.json`,
     // which the bundle's `patches` just edited. Generated and always
     // overwritten, like `architecture.yaml` above.

package/dist/add-route.js

@@ -39,6 +39,7 @@ import { substituteMarkers } from "./substitute.js";
 import { GATEABLE_SURFACES, MODULE_SURFACES, parseSurfaces, resolveSurfaces, } from "./surfaces.js";
 import { syncRoutes } from "./sync-routes.js";
 import { BASE_LAYER_DIR } from "./template-manifest.js";
+import { TopologyError, readSiteTopology } from "./topology.js";
 /** A refusal the CLI exits 2 on, thrown before anything is written. */
 export class AddRouteRefusedError extends Error {
     exitCode = 2;
@@ -64,6 +65,20 @@ export function addRouteToScaffold(opts) {
     if (!existsSync(archPath)) {
         throw new Error(`not a scaffolded repo: no architecture.yaml at ${targetAbs}. Run \`create-ailk <target-dir>\` to scaffold first.`);
     }
+    // #7426 D13 — a spoke stays a spoke. Read before the first write: an
+    // unreadable manifest is a refusal this command names (exit 2).
+    let spoke;
+    try {
+        spoke =
+            readSiteTopology(targetAbs) === "spoke"
+                ? { mcp: existsSync(join(targetAbs, "apps", "mcp")) }
+                : undefined;
+    }
+    catch (err) {
+        if (err instanceof TopologyError)
+            throw new AddRouteRefusedError(err.message);
+        throw err;
+    }
     const route = canonicalRoute(opts.route);
     const owner = Object.entries(MODULE_SURFACES).find(([, surfaces]) => surfaces.includes(route))?.[0];
     let current;
@@ -106,8 +121,9 @@ export function addRouteToScaffold(opts) {
     if (navRow !== undefined)
         report.push(navRow);
     // Last: the declared header is what makes a rerun a no-op, so it is
-    // written only once every other step has landed.
-    writeFileSync(archPath, deriveArchitecture(current.modules, surfaces));
+    // written only once every other step has landed. A spoke's `syncRoutes`
+    // call above already skipped what it lacks (#7426 D13).
+    writeFileSync(archPath, deriveArchitecture(current.modules, surfaces, spoke !== undefined ? { topology: "spoke", mcp: spoke.mcp } : {}));
     return { targetDir: targetAbs, route, surfaces, report, routes };
 }
 /** The canonical id for one route argument, refusing an unknown one. */

package/dist/apply-design.d.ts

@@ -1,3 +1,5 @@
+import { type HomeSeedOutcome } from "./design-home.js";
+import { type UnreadChromeKnob } from "./lib/chrome-readers.js";
 export interface ApplyDesignOptions {
     /** The design: a shipped name, or a directory holding a DESIGN.md. */
     design: string;
@@ -6,7 +8,11 @@ export interface ApplyDesignOptions {
     /** Package-rooted inputs, supplied by the caller (cli.ts from its PKG_ROOT). */
     designsDir: string;
     siteTemplatesDir: string;
+    /** The overlay's `templates/` (#7743 D7) — where a treeless shape's home lives. Default: `templates` beside `siteTemplatesDir`. */
+    templatesDir?: string;
     catalogPath: string;
+    /** #7781 — apply the design even when a reader file of the site ignores a chrome knob it sets; the pairs are reported instead of refused. */
+    allowUnreadChrome?: boolean;
     /** Where a relative design path resolves from. Default process.cwd(). */
     cwd?: string;
     /** Read for AILK_LICENSE_KEY only (D6). Default process.env. */
@@ -21,6 +27,9 @@ export type ApplyDesignChange = {
 } | {
     path: string;
     kind: "layout";
+} | {
+    path: string;
+    kind: "fonts";
 } | {
     path: string;
     kind: "design";
@@ -28,6 +37,11 @@ export type ApplyDesignChange = {
     path: string;
     kind: "preset";
     fields: string[];
+} | {
+    path: string;
+    kind: "home";
+    action: "seeded" | "restored";
+    fields: string[];
 } | {
     path: string;
     kind: "manifest";
@@ -39,15 +53,31 @@ export interface ApplyDesignResult {
     /** In write order (D4); [] when nothing changed. */
     changes: ApplyDesignChange[];
     manifest: "recorded" | "unchanged" | "no-roster" | "legacy-roster";
+    /** #7743 D7 — what the design did to the home page's sections. */
+    home: HomeSeedOutcome;
+    /** #7743 D7 — the design ships a home arc for this site, so a home it leaves alone is reported. */
+    homeArc?: true;
     /** The site-relative roster file, when there is one. */
     rosterPath?: string;
+    /** #7720 D4.2 — the distinct families written to site-fonts.ts, display first; set only when faces are written. */
+    fonts?: string[];
+    /** #7720 D4.2 — faces were written, but the site's layout.tsx does not read lib/site-fonts. */
+    fontsUnwired?: true;
+    /** #7781 — chrome knobs the design set that a reader file of the site does not read; present only when non-empty, which only `allowUnreadChrome` lets through. */
+    unreadChrome?: UnreadChromeKnob[];
+}
+/** #7781 — thrown before any write when the design sets a chrome knob that a reader file of the site does not read. */
+export declare class UnreadChromeError extends Error {
+    readonly unread: readonly UnreadChromeKnob[];
+    constructor(unread: readonly UnreadChromeKnob[]);
 }
 export interface ApplyDesignArgs {
     design: string | undefined;
     target: string | undefined;
+    allowUnreadChrome: boolean;
     help: boolean;
 }
-export declare const APPLY_DESIGN_HELP = "create-ailk apply-design \u2014 make an existing site wear a design.\n\nUsage:\n  create-ailk apply-design <name> [--target <site-dir>]\n  create-ailk apply-design <path> [--target <site-dir>]\n\nArguments:\n  <name|path>              A shipped design (standard, minimalism), or a\n                           directory holding a DESIGN.md. A relative path\n                           resolves from the current directory.\n\nOptions:\n  --target <site-dir>      An already-scaffolded repo (contains\n                           architecture.yaml). Defaults to the current dir.\n  --help, -h               Print this message.\n\nWrites only the look: DESIGN.md (replaced whole by the design's, keeping the\nsite's Source template and Version lines), the theme: block of\ncontent/_site.mdx, the generated apps/web/lib/site-chrome.ts, the look fields\nof sections the site's pages already place, and the design/layout/theme record\nin .ailk-site-manifest.json.\nNever adds, removes or renames a route or page, never touches a content field\nor the brand: block, and leaves every page's structured data unchanged.\n\nA design other than standard needs a Pro or Pro Plus key: the site's own\nailk.key (put one there with create-ailk license set <key>), else\nAILK_LICENSE_KEY. A malformed package, a preset the validator refuses or a\nmissing key is refused before any file is written.\n\nA preset sets the look fields it names and never unsets one: a field it does\nnot name keeps whatever value the page has. Running it again changes nothing.\n";
+export declare const APPLY_DESIGN_HELP = "create-ailk apply-design \u2014 make an existing site wear a design.\n\nUsage:\n  create-ailk apply-design <name> [--target <site-dir>]\n  create-ailk apply-design <path> [--target <site-dir>]\n\nArguments:\n  <name|path>              A shipped design (standard, minimalism), or a\n                           directory holding a DESIGN.md. A relative path\n                           resolves from the current directory.\n\nOptions:\n  --target <site-dir>      An already-scaffolded repo (contains\n                           architecture.yaml). Defaults to the current dir.\n  --allow-unread-chrome    Apply the design even when a file of the site does\n                           not read a chrome setting the design sets (a site\n                           scaffolded before the setting existed). Without it\n                           that is refused; with it each such file is reported.\n  --help, -h               Print this message.\n\nWrites only the look: DESIGN.md (replaced whole by the design's, keeping the\nsite's Source template and Version lines), the theme: block of\ncontent/_site.mdx, the generated apps/web/lib/site-chrome.ts, the generated\napps/web/lib/site-fonts.ts, the look fields of sections the site's pages\nalready place, and the design/layout/theme record in .ailk-site-manifest.json.\nNever adds, removes or renames a route or page, never touches a content field\n(except a placeholder home's sections, below) or the brand: block, and leaves\nevery other page's structured data unchanged.\n\nA design may seed the placeholder home's sections \u2014 its home arc \u2014 while they\nare still a placeholder: the shape's own, or a design's arc of them. It never\nchanges a home whose sections were edited; it reports it and leaves it. A\nseeded home takes the design's looks; look values on the sections it replaced\nare not kept. A design that ships no arc restores the shape's own sections on\na home that still wears another design's untouched arc.\n\nA design other than standard needs a Pro or Pro Plus key: the site's own\nailk.key (put one there with create-ailk license set <key>), else\nAILK_LICENSE_KEY. A malformed package, a preset the validator refuses or a\nmissing key is refused before any file is written.\n\nA preset sets the look fields it names and never unsets one: a field it does\nnot name keeps whatever value the page has. Running it again changes nothing.\n";
 /**
  * Parse the argv AFTER the `apply-design` word (D1). Strict `node:util`
  * parseArgs, like `parseSyncRoutesArgs`: exactly one positional, the design
@@ -57,7 +87,7 @@ export declare function parseApplyDesignArgs(argv: string[]): ApplyDesignArgs;
 /**
  * Apply a design to an existing site (D2–D7). Refuses before any write
  * (C1–C6); otherwise writes only the files whose text changes — page files,
- * `site-chrome.ts`, `DESIGN.md`, `_site.mdx`, then the manifest last.
+ * `site-chrome.ts`, `site-fonts.ts`, `DESIGN.md`, `_site.mdx`, then the manifest last.
  */
 export declare function applyDesign(opts: ApplyDesignOptions): Promise<ApplyDesignResult>;
 /** The changed-file report (D9). */

package/dist/apply-design.js

@@ -7,7 +7,9 @@
  * resolver and theme splicer, #6816's preset validator and applier, #6760's
  * design gate and #6813's manifest writer. Every refusal happens before the
  * first write (D3); every new text is planned in memory, then written in one
- * pass (D4). Routes, content fields, `brand:` and structured data never move.
+ * pass (D4). Routes, content fields, `brand:` and structured data never move —
+ * except a placeholder home's `sections:`, which a design's home arc may
+ * replace (#7743 D7).
  *
  * Reads no module URL of its own — every package directory it reads is passed in
  * — so Jest's CJS transform can import it, unlike `programmatic.ts`.
@@ -16,15 +18,31 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSy
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
 import { planDesignMd } from "./apply-design-md.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 { resolveDesign, spliceThemeBlock } from "./design-scaffold.js";
+import { chromeKnobReaders, unreadChromeKnobs } from "./lib/chrome-readers.js";
 import { LICENSE_KEY_FILE } from "./lib/license-key-files.js";
 import { CONVERSION_HINT_URL, LicenseRequiredError, assertDesignAllowed, deriveLevel, } from "./lib/module-license-gate.js";
 import { LEVEL_LABEL } from "./lib/module-tier.js";
 import { ParseError } from "./parse-args.js";
 import { SITE_CHROME_PATH, renderSiteChrome, resolveSiteChrome, } from "./site-chrome.js";
-import { SITE_ROSTER_PATH, planSiteManifestDesign, readSiteRoster, } from "./site-roster.js";
+import { SITE_FONTS_PATH, renderSiteFonts } from "./site-fonts.js";
+import { SITE_ROSTER_PATH, planHomeRecord, planSiteManifestDesign, readSiteRoster, } from "./site-roster.js";
+/** #7781 — thrown before any write when the design sets a chrome knob that a reader file of the site does not read. */
+export class UnreadChromeError extends Error {
+    unread;
+    constructor(unread) {
+        super(`design chrome would not render: the site's own copy of these files does not read the knob the design sets (update them from the current create-ailk overlay, or pass --allow-unread-chrome to apply anyway):\n${unread
+            .map(({ knob, file }) => `  ${knob} — ${file}`)
+            .join("\n")}`);
+        this.unread = unread;
+        this.name = "UnreadChromeError";
+    }
+}
+/** The site's locale layout — the one reader of the generated site-fonts.ts. */
+const SITE_LAYOUT_PATH = "apps/web/app/[locale]/layout.tsx";
 export const APPLY_DESIGN_HELP = `create-ailk apply-design — make an existing site wear a design.
 
 Usage:
@@ -39,15 +57,27 @@ Arguments:
 Options:
   --target <site-dir>      An already-scaffolded repo (contains
                            architecture.yaml). Defaults to the current dir.
+  --allow-unread-chrome    Apply the design even when a file of the site does
+                           not read a chrome setting the design sets (a site
+                           scaffolded before the setting existed). Without it
+                           that is refused; with it each such file is reported.
   --help, -h               Print this message.
 
 Writes only the look: DESIGN.md (replaced whole by the design's, keeping the
 site's Source template and Version lines), the theme: block of
-content/_site.mdx, the generated apps/web/lib/site-chrome.ts, the look fields
-of sections the site's pages already place, and the design/layout/theme record
-in .ailk-site-manifest.json.
+content/_site.mdx, the generated apps/web/lib/site-chrome.ts, the generated
+apps/web/lib/site-fonts.ts, the look fields of sections the site's pages
+already place, and the design/layout/theme record in .ailk-site-manifest.json.
 Never adds, removes or renames a route or page, never touches a content field
-or the brand: block, and leaves every page's structured data unchanged.
+(except a placeholder home's sections, below) or the brand: block, and leaves
+every other page's structured data unchanged.
+
+A design may seed the placeholder home's sections — its home arc — while they
+are still a placeholder: the shape's own, or a design's arc of them. It never
+changes a home whose sections were edited; it reports it and leaves it. A
+seeded home takes the design's looks; look values on the sections it replaced
+are not kept. A design that ships no arc restores the shape's own sections on
+a home that still wears another design's untouched arc.
 
 A design other than standard needs a Pro or Pro Plus key: the site's own
 ailk.key (put one there with create-ailk license set <key>), else
@@ -69,6 +99,7 @@ export function parseApplyDesignArgs(argv) {
         allowPositionals: true,
         options: {
             target: { type: "string" },
+            "allow-unread-chrome": { type: "boolean", default: false },
             help: { type: "boolean", default: false, short: "h" },
         },
     });
@@ -80,7 +111,12 @@ export function parseApplyDesignArgs(argv) {
     if (design === undefined && !help) {
         throw new ParseError("apply-design needs a design. Usage: create-ailk apply-design <name|path> [--target <site-dir>]");
     }
-    return { design, target: parsed.values.target, help };
+    return {
+        design,
+        target: parsed.values.target,
+        allowUnreadChrome: parsed.values["allow-unread-chrome"] === true,
+        help,
+    };
 }
 /** `abs` relative to `root`, with `/` separators. */
 function siteRelative(root, abs) {
@@ -118,7 +154,7 @@ function readSiteKey(targetAbs, env) {
 /**
  * Apply a design to an existing site (D2–D7). Refuses before any write
  * (C1–C6); otherwise writes only the files whose text changes — page files,
- * `site-chrome.ts`, `DESIGN.md`, `_site.mdx`, then the manifest last.
+ * `site-chrome.ts`, `site-fonts.ts`, `DESIGN.md`, `_site.mdx`, then the manifest last.
  */
 export async function applyDesign(opts) {
     const targetAbs = resolve(opts.targetDir);
@@ -146,13 +182,18 @@ export async function applyDesign(opts) {
     const { pkg } = resolved;
     const hasPresets = Object.keys(pkg.sections).length > 0;
     // C4 — the presets, validated exactly as scaffold() validates them.
+    let lookCatalog;
+    const catalog = () => (lookCatalog ??= readSectionLookCatalog(opts.catalogPath));
     if (hasPresets) {
         validateDesignPresets(pkg.sections, {
-            catalog: readSectionLookCatalog(opts.catalogPath),
+            catalog: catalog(),
             pageTypes: shippedPageTypes(opts.siteTemplatesDir),
             file: join(resolved.dir, "DESIGN.md"),
         });
     }
+    // #7743 D7 — the home seeds (the design's and every shipped design's), validated beside the presets.
+    const designSeeds = designHomeSeeds(resolved, { designsDir: opts.designsDir, catalog });
+    const shippedSeeds = shippedHomeSeeds({ designsDir: opts.designsDir, catalog });
     // C5 — the design gate, fed the site's own key (D6). A Free design reads no key.
     if (!resolved.free) {
         const key = readSiteKey(targetAbs, env);
@@ -170,20 +211,60 @@ export async function applyDesign(opts) {
             throw new LicenseRequiredError(`design "${resolved.display}" is a Pro feature — this site's licence level is ${LEVEL_LABEL[level]}; put a Pro or Pro Plus key in the site with create-ailk license set <key>, or set AILK_LICENSE_KEY → ${CONVERSION_HINT_URL}`);
         }
     }
+    // #7781 — after the licence gate, before any plan: every chrome knob the design sets must be read by
+    // the site's own copy of each overlay file that reads it. The reader map is derived from the overlay.
+    const roster = readSiteRoster(targetAbs);
+    const chrome = resolveSiteChrome(roster?.template.layout, pkg.layout);
+    const templatesDir = opts.templatesDir ?? join(dirname(opts.siteTemplatesDir), "templates");
+    const unreadChrome = unreadChromeKnobs(chrome, chromeKnobReaders(templatesDir), targetAbs);
+    if (unreadChrome.length > 0 && opts.allowUnreadChrome !== true)
+        throw new UnreadChromeError(unreadChrome);
     // C6 / D4 — plan every write in memory.
     const theme = compileDesignTheme(pkg);
     const siteMdxCurrent = readFileSync(siteMdxPath, "utf8");
     const siteMdxNext = spliceThemeBlock(siteMdxCurrent, theme, siteMdxPath);
-    const roster = readSiteRoster(targetAbs);
-    const chrome = resolveSiteChrome(roster?.template.layout, pkg.layout);
     const chromePath = join(targetAbs, SITE_CHROME_PATH);
     const chromeCurrent = existsSync(chromePath) ? readFileSync(chromePath, "utf8") : undefined;
     const chromeNext = renderSiteChrome(chrome);
+    // #7720 D4.2 — a face-less design never adds the file to a site that lacks it.
+    const fonts = compileDesignFonts(pkg);
+    const fontsPath = join(targetAbs, SITE_FONTS_PATH);
+    const fontsCurrent = existsSync(fontsPath) ? readFileSync(fontsPath, "utf8") : undefined;
+    const fontsNext = renderSiteFonts(fonts);
+    const writeFonts = fontsNext !== fontsCurrent && (fontsCurrent !== undefined || fonts !== undefined);
+    const fontFamilies = writeFonts && fonts !== undefined
+        ? [...new Set([fonts.display?.family, fonts.body?.family])].filter((family) => family !== undefined)
+        : undefined;
+    const layoutPath = join(targetAbs, SITE_LAYOUT_PATH);
+    const fontsUnwired = fontFamilies !== undefined &&
+        !(existsSync(layoutPath) && readFileSync(layoutPath, "utf8").includes("lib/site-fonts"));
     const designMdPath = join(targetAbs, "DESIGN.md");
     const designMdCurrent = existsSync(designMdPath) ? readFileSync(designMdPath, "utf8") : undefined;
     const designMdNext = planDesignMd(resolved.dir, targetAbs);
+    // #7743 D7 — the home is planned before the presets, so a seeded home is
+    // written once, carrying both. The one `planDesignHome` call site here.
+    const shape = roster?.template.shape;
+    const target = designSeeds.find((seed) => seed.shape === shape);
+    // The arc this site would take: the shape's seed, or (with no shape to pick one) any seed at all.
+    const homeArc = target !== undefined || (shape === undefined && designSeeds.length > 0);
+    const homePath = join(targetAbs, ...HOME_PAGE_PATH.split("/"));
+    const current = existsSync(homePath) ? readFileSync(homePath, "utf8") : undefined;
+    const homePlan = planDesignHome({
+        current,
+        shape,
+        target,
+        shapeHome: shape === undefined || current === undefined
+            ? ""
+            : readFileSync(shapeHomePath(shape, {
+                siteTemplatesDir: opts.siteTemplatesDir,
+                templatesDir,
+            }), "utf8"),
+        shippedSeeds,
+        catalog: catalog(),
+    });
+    const homeAction = homePlan.outcome === "seeded" || homePlan.outcome === "restored" ? homePlan.outcome : undefined;
     const pageWrites = [];
-    if (hasPresets && roster !== undefined) {
+    if (roster !== undefined && (hasPresets || homeAction !== undefined)) {
         const pageTypes = new Set();
         for (const row of roster.rows) {
             const pageType = row.value["pageType"];
@@ -191,17 +272,28 @@ export async function applyDesign(opts) {
                 pageTypes.add(pageType);
         }
         const contentDir = join(targetAbs, "content");
+        // An authored home kept from a design's arc is reported as kept, so no preset dresses it either (D3, F4).
+        const homeKept = homePlan.outcome === "authored" && homeArc;
         const pages = listMdxFiles(contentDir)
-            .filter((path) => path !== siteMdxPath)
-            .map((path) => ({ path, text: readFileSync(path, "utf8") }));
-        const presetResult = applyDesignPresets(pages, pkg.sections, { pageTypes });
-        for (const page of presetResult.pages) {
+            .filter((path) => path !== siteMdxPath && !(homeKept && path === homePath))
+            .map((path) => ({
+            path,
+            text: path === homePath && homePlan.text !== undefined ? homePlan.text : readFileSync(path, "utf8"),
+        }));
+        const presetResult = hasPresets
+            ? applyDesignPresets(pages, pkg.sections, { pageTypes })
+            : { pages: [], applied: [] };
+        for (const page of pages) {
+            const preset = presetResult.pages.find((p) => p.path === page.path);
+            const home = page.path === homePath ? homeAction : undefined;
+            if (preset === undefined && home === undefined)
+                continue;
             const fields = [
                 ...new Set(presetResult.applied
                     .filter((a) => a.path === page.path)
                     .map((a) => `${a.sectionType}.${a.field}`)),
             ].sort();
-            pageWrites.push({ path: page.path, text: page.text, fields });
+            pageWrites.push({ path: page.path, text: preset?.text ?? page.text, fields, ...(home !== undefined ? { home } : {}) });
         }
     }
     let manifest = "no-roster";
@@ -210,23 +302,37 @@ export async function applyDesign(opts) {
     if (roster !== undefined && rosterAbs !== undefined) {
         if (roster.path === SITE_ROSTER_PATH) {
             manifestNext = planSiteManifestDesign(readFileSync(rosterAbs, "utf8"), { design: resolved.recorded, layout: chrome, theme }, rosterAbs);
+            // #7743 D6 — the `/` row records the home as written, in the same single write.
+            const home = pageWrites.find((page) => page.home !== undefined);
+            if (home !== undefined) {
+                manifestNext =
+                    planHomeRecord(manifestNext ?? readFileSync(rosterAbs, "utf8"), home.text, catalog()) ?? manifestNext;
+            }
             manifest = manifestNext === undefined ? "unchanged" : "recorded";
         }
         else {
             manifest = "legacy-roster";
         }
     }
-    // Write — page files, site-chrome.ts, DESIGN.md, _site.mdx, the manifest last (D4).
+    // Write — page files, site-chrome.ts, site-fonts.ts, DESIGN.md, _site.mdx, the manifest last (D4).
     const changes = [];
     for (const page of pageWrites) {
         writeFileSync(page.path, page.text);
-        changes.push({ path: siteRelative(targetAbs, page.path), kind: "preset", fields: page.fields });
+        const path = siteRelative(targetAbs, page.path);
+        changes.push(page.home !== undefined
+            ? { path, kind: "home", action: page.home, fields: page.fields }
+            : { path, kind: "preset", fields: page.fields });
     }
     if (chromeNext !== chromeCurrent) {
         mkdirSync(dirname(chromePath), { recursive: true });
         writeFileSync(chromePath, chromeNext);
         changes.push({ path: SITE_CHROME_PATH, kind: "layout" });
     }
+    if (writeFonts) {
+        mkdirSync(dirname(fontsPath), { recursive: true });
+        writeFileSync(fontsPath, fontsNext);
+        changes.push({ path: SITE_FONTS_PATH, kind: "fonts" });
+    }
     if (designMdNext !== designMdCurrent) {
         writeFileSync(designMdPath, designMdNext);
         changes.push({ path: "DESIGN.md", kind: "design" });
@@ -245,7 +351,12 @@ export async function applyDesign(opts) {
         display: resolved.display,
         changes,
         manifest,
+        home: homePlan.outcome,
+        ...(homeArc ? { homeArc: true } : {}),
         ...(roster !== undefined ? { rosterPath: roster.path } : {}),
+        ...(fontFamilies !== undefined ? { fonts: fontFamilies } : {}),
+        ...(fontsUnwired ? { fontsUnwired: true } : {}),
+        ...(unreadChrome.length > 0 ? { unreadChrome } : {}),
     };
 }
 /** The changed-file report (D9). */
@@ -257,11 +368,33 @@ export function formatApplyDesignReport(result) {
     else {
         lines.push(`[create-ailk] Applied design "${result.design}" to ${result.targetDir}`);
         for (const change of result.changes) {
-            const suffix = change.kind === "preset" ? ` (${change.fields.join(", ")})` : "";
+            const suffix = change.kind === "preset"
+                ? ` (${change.fields.join(", ")})`
+                : change.kind === "home"
+                    ? ` (${[change.action, change.fields.join(", ")].filter((part) => part !== "").join("; ")})`
+                    : "";
             lines.push(`  ${change.kind.padEnd(8)}  ${change.path}${suffix}`);
         }
         const n = result.changes.length;
-        lines.push(`${n} file${n === 1 ? "" : "s"} changed. Routes, page content and structured data are unchanged.`);
+        const homeWritten = result.changes.some((change) => change.kind === "home");
+        lines.push(`${n} file${n === 1 ? "" : "s"} changed. ${homeWritten
+            ? "Routes are unchanged; the home page's sections were replaced."
+            : "Routes and structured data are unchanged."}`);
+    }
+    if (result.home === "authored" && result.homeArc === true) {
+        lines.push(`home kept: ${HOME_PAGE_PATH} has authored sections — the ${result.design} home arc was not applied`);
+    }
+    else if (result.home === "no-shape" && result.homeArc === true) {
+        lines.push("home not seeded: the site records no shape");
+    }
+    if (result.fonts !== undefined) {
+        lines.push(`fonts: ${result.fonts.join(", ")} load at next build through next/font/google — a family that is not a variable Google font fails there`);
+    }
+    if (result.fontsUnwired === true) {
+        lines.push(`fonts not loaded: ${SITE_LAYOUT_PATH} predates lib/site-fonts — update the layout from the current create-ailk overlay`);
+    }
+    for (const { knob, file } of result.unreadChrome ?? []) {
+        lines.push(`chrome not rendered: ${knob} — ${file} does not read it`);
     }
     if (result.manifest === "legacy-roster") {
         lines.push(`manifest not recorded: ${result.rosterPath} predates the design record`);