create-ailk 0.14.0 → 0.15.0

package/component-catalog.json

@@ -5235,8 +5235,7 @@
                 }
               },
               "required": [
-                "title",
-                "description"
+                "title"
               ]
             }
           },
@@ -7378,7 +7377,8 @@
             "type": "string",
             "enum": [
               "default",
-              "sm"
+              "sm",
+              "lg"
             ]
           },
           "surface": {

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,4 +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;
@@ -10,6 +11,8 @@ export interface ApplyDesignOptions {
     /** 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. */
@@ -60,13 +63,21 @@ export interface ApplyDesignResult {
     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 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";
+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

package/dist/apply-design.js

@@ -22,6 +22,7 @@ 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";
@@ -29,6 +30,17 @@ import { ParseError } from "./parse-args.js";
 import { SITE_CHROME_PATH, renderSiteChrome, resolveSiteChrome, } from "./site-chrome.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.
@@ -45,6 +57,10 @@ 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
@@ -83,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" },
         },
     });
@@ -94,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) {
@@ -189,12 +211,18 @@ 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);
@@ -229,7 +257,7 @@ export async function applyDesign(opts) {
             ? ""
             : readFileSync(shapeHomePath(shape, {
                 siteTemplatesDir: opts.siteTemplatesDir,
-                templatesDir: opts.templatesDir ?? join(dirname(opts.siteTemplatesDir), "templates"),
+                templatesDir,
             }), "utf8"),
         shippedSeeds,
         catalog: catalog(),
@@ -328,6 +356,7 @@ export async function applyDesign(opts) {
         ...(roster !== undefined ? { rosterPath: roster.path } : {}),
         ...(fontFamilies !== undefined ? { fonts: fontFamilies } : {}),
         ...(fontsUnwired ? { fontsUnwired: true } : {}),
+        ...(unreadChrome.length > 0 ? { unreadChrome } : {}),
     };
 }
 /** The changed-file report (D9). */
@@ -364,6 +393,9 @@ export function formatApplyDesignReport(result) {
     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`);
     }

package/dist/cli.js

@@ -203,6 +203,7 @@ async function main() {
             siteTemplatesDir: resolve(PKG_ROOT, "site-templates"),
             templatesDir: resolve(PKG_ROOT, "templates"),
             catalogPath: resolve(PKG_ROOT, "component-catalog.json"),
+            allowUnreadChrome: args.allowUnreadChrome,
         });
         process.stdout.write(formatApplyDesignReport(result));
         process.exit(0);
@@ -318,7 +319,8 @@ async function main() {
     // marketing-site-free` still rides the no-key case (record D11): its
     // `requires` is all-free, so it installs from the shipped
     // `site-templates/` tree with no key and no request.
-    const { targetDir: targetAbs, surfaces, starter, modules: effectiveModules, } = await scaffold(toScaffoldOptions(opts));
+    const { targetDir: targetAbs, surfaces, starter, modules: effectiveModules, droppedModules, hubOrigin, } = await scaffold(toScaffoldOptions(opts));
+    const isSpoke = opts.topology === "spoke";
     // The starter scaffold() resolved — from --template, or from --shape (#6754 D4).
     const templateName = starter?.template ?? opts.template;
     if (opts.install) {
@@ -346,6 +348,22 @@ async function main() {
         ...(starter !== undefined
             ? [`Starter: shape ${starter.shape}, design ${starter.design}.`]
             : []),
+        // #7426 — a spoke says so, and names what its hosts must carry (D3).
+        ...(isSpoke
+            ? [
+                `Topology: spoke — no apps/api, no database, no sign-in${opts.mcp === false ? ", no apps/mcp" : "; apps/mcp is a stateless front"}.`,
+                ...(droppedModules !== undefined && droppedModules.length > 0
+                    ? [
+                        `Not carried on a spoke: ${droppedModules.join(", ")} (your licence includes ${droppedModules.length === 1 ? "it" : "them"}; a spoke does not admit ${droppedModules.length === 1 ? "it" : "them"} yet).`,
+                    ]
+                    : []),
+                "",
+                `Every host serving this spoke's ${opts.mcp === false ? "apps/web" : "apps/web and apps/mcp"} must carry:`,
+                `  AILK_API_URL=${hubOrigin ?? "<your hub origin>"}   # written to apps/web/.env.local`,
+                "  AILK_SPOKE_KEY             # issued by the hub; never written here",
+                "  AILK_VISITOR_FORWARD_KEY   # issued by the hub; never written here",
+            ]
+            : []),
         "",
     ];
     // Prerequisites (#6440 AC4) — every one the scaffold enforces, and nothing
@@ -374,13 +392,15 @@ async function main() {
     lines.push("Next steps:");
     lines.push(`  cd ${targetAbs}`);
     if (!opts.install) {
-        lines.push("  pnpm install     # also generates the Prisma client");
+        lines.push(isSpoke ? "  pnpm install" : "  pnpm install     # also generates the Prisma client");
     }
     lines.push("  pnpm dev         # http://localhost:3000");
     lines.push("  pnpm build       # production build, when you are ready to deploy");
     lines.push("");
     lines.push("Open http://localhost:3000 to see the home page.");
-    lines.push("Adding auth, saved flows, checkout or database-backed content later? README.md \u00a7 \"When you need a database\" has the one-command setup.");
+    if (!isSpoke) {
+        lines.push("Adding auth, saved flows, checkout or database-backed content later? README.md \u00a7 \"When you need a database\" has the one-command setup.");
+    }
     lines.push("");
     lines.push("Claude Code: the AI Launch Kit skills come from the ailk plugin. Trust this folder and Claude Code loads it, or run in a session:");
     for (const line of PLUGIN_INSTALL_LINES)

package/dist/derive-architecture.d.ts

@@ -1,3 +1,11 @@
+import type { Topology } from "./topology.js";
+/** The topology a document is derived for (#7426 D8). */
+export interface DeriveArchitectureOptions {
+    /** `"hub"` (the default) or `"spoke"`. */
+    topology?: Topology;
+    /** Spoke only: whether the spoke keeps `apps/mcp` (default true). */
+    mcp?: boolean;
+}
 /**
  * Derive the `architecture.yaml` document for a module set.
  *
@@ -6,8 +14,13 @@
  * @param surfaces the enabled gateable route surfaces. Omitted ⟹ derived from
  *   the module set alone (`resolveSurfaces`), so a caller that passes only
  *   modules gets exactly what the modules imply.
+ * @param options the topology (#7426 D8). Absent or `"hub"` ⟹ the output is
+ *   byte-identical to the two-argument form. `"spoke"` ⟹ only the spoke's own
+ *   apps (`web`, and `mcp` unless `mcp: false`), no `namespaces`, no
+ *   `database` root, a top-level `topology: spoke` and the hub-facing
+ *   composition tiers.
  * @returns the complete `architecture.yaml` file content (a deterministic
- *   function of the module SET and the surface SET).
+ *   function of the module SET, the surface SET and the topology).
  * @throws Error on an unrecognized module (defensive; parse-args rejects first).
  */
-export declare function deriveArchitecture(modules?: string[], surfaces?: string[]): string;
+export declare function deriveArchitecture(modules?: string[], surfaces?: string[], options?: DeriveArchitectureOptions): string;

package/dist/derive-architecture.js

@@ -15,6 +15,12 @@
  */
 import { ARCHITECTURE_BASE, MODULE_SLICES, normalizeModules, } from "./module-architecture.js";
 import { CORE_SURFACE_PATHS, RECOGNIZED_SURFACES, resolveSurfaces, } from "./surfaces.js";
+/** A spoke's composition tiers (#7426 D8): its data and API are the hub's. */
+const SPOKE_TIERS = {
+    data: "none — the hub's database",
+    api: "the hub at AILK_API_URL (apps/mcp is a stateless front)",
+    presentation: "apps/web",
+};
 function isScalar(v) {
     return typeof v === "string" || typeof v === "number";
 }
@@ -150,11 +156,18 @@ function namespacesToYaml(ns) {
  * @param surfaces the enabled gateable route surfaces. Omitted ⟹ derived from
  *   the module set alone (`resolveSurfaces`), so a caller that passes only
  *   modules gets exactly what the modules imply.
+ * @param options the topology (#7426 D8). Absent or `"hub"` ⟹ the output is
+ *   byte-identical to the two-argument form. `"spoke"` ⟹ only the spoke's own
+ *   apps (`web`, and `mcp` unless `mcp: false`), no `namespaces`, no
+ *   `database` root, a top-level `topology: spoke` and the hub-facing
+ *   composition tiers.
  * @returns the complete `architecture.yaml` file content (a deterministic
- *   function of the module SET and the surface SET).
+ *   function of the module SET, the surface SET and the topology).
  * @throws Error on an unrecognized module (defensive; parse-args rejects first).
  */
-export function deriveArchitecture(modules = ["marketing"], surfaces) {
+export function deriveArchitecture(modules = ["marketing"], surfaces, options = {}) {
+    const spoke = options.topology === "spoke";
+    const keepMcp = options.mcp !== false;
     const selected = normalizeModules(modules);
     const slices = selected.map((m) => MODULE_SLICES[m]);
     // The declared route surface (#4154). A scaffold's live-route set is a
@@ -180,12 +193,20 @@ export function deriveArchitecture(modules = ["marketing"], surfaces) {
     };
     for (const s of slices)
         Object.assign(declared, s.apps ?? {});
+    // A spoke carries only its own apps (#7426 D8): web, and mcp unless
+    // `--without-mcp` — never api, never a module's admin.
+    if (spoke) {
+        for (const key of Object.keys(declared)) {
+            if (key !== "web" && !(key === "mcp" && keepMcp))
+                delete declared[key];
+        }
+    }
     // A scaffold carries no `packages/` tree — `@working-theory/*` install from
     // npm — so an entry naming a monorepo folder is dropped rather than shipped
     // as a rule the linter can never apply (#6940). What survives names a path
     // the scaffold has: a declared app, or `database/`.
     const roots = [
-        "database",
+        ...(spoke ? [] : ["database"]),
         ...Object.values(declared).map((a) => a.path),
     ];
     const inScaffold = (p) => {
@@ -209,8 +230,11 @@ export function deriveArchitecture(modules = ["marketing"], surfaces) {
             forbidden_patterns: mergeForbidden([...ARCHITECTURE_BASE.appForbiddenPatterns], a.forbidden_patterns ?? []).map(scoped),
         });
     }
-    // namespaces — present only if a data-tier module contributes one.
-    const nsSlice = slices.find((s) => s.namespaces)?.namespaces;
+    // namespaces — present only if a data-tier module contributes one, and
+    // never on a spoke, which has no database/ of its own.
+    const nsSlice = spoke
+        ? undefined
+        : slices.find((s) => s.namespaces)?.namespaces;
     // forbidden_patterns — base floor first, then the selected modules' patterns.
     const extraForbidden = [];
     for (const s of slices)
@@ -218,8 +242,11 @@ export function deriveArchitecture(modules = ["marketing"], surfaces) {
     const forbidden = mergeForbidden([...ARCHITECTURE_BASE.forbiddenPatterns], extraForbidden).map(scoped);
     const doc = {
         version: ARCHITECTURE_BASE.version,
+        ...(spoke ? { topology: "spoke" } : {}),
         composition_model: {
-            tiers: { ...ARCHITECTURE_BASE.composition_model.tiers },
+            tiers: spoke
+                ? { ...SPOKE_TIERS }
+                : { ...ARCHITECTURE_BASE.composition_model.tiers },
         },
         surfaces: {
             core: [...CORE_SURFACE_PATHS],
@@ -240,6 +267,7 @@ export function deriveArchitecture(modules = ["marketing"], surfaces) {
         "#",
         `# Modules: ${selected.join(", ")}`,
         `# Surfaces: ${enabledSurfaces.length > 0 ? enabledSurfaces.join(", ") : "core only"}`,
+        ...(spoke ? ["# Topology: spoke"] : []),
         "",
     ].join("\n");
     return header + emitDocument(doc);

package/dist/design-package.js

@@ -207,7 +207,7 @@ function parseScalar(raw, lineNo, file) {
  * The one dotted key path whose value may be a block sequence (#7719 D2) —
  * the deck's ordered ground list. Every other `- ` line is refused as before.
  */
-const SEQUENCE_PATHS = new Set(["layout.deckGrounds"]);
+const SEQUENCE_PATHS = new Set(["layout.deckGrounds", "layout.closingFooterPaths"]);
 /**
  * Parse a block sequence of scalars whose `- ` items sit at `pos.i`'s indent
  * (#7719 D2). Each item's text is read by `parseScalar`, with every refusal it
@@ -487,7 +487,7 @@ function validateStringMap(raw, file, field) {
 const LAYOUT_KEYS = ["nav", "footer", "announcementBanner", "home"];
 /** Every key a package's `layout` may carry — #7719 D3 adds the optional `deckGrounds` (a deck home only),
  *  #7721 D1 the optional `innerPages`, #7740 D1 the optional `deckPresentation` (a deck home only),
- *  #7742 D1 the optional `colorMode` and `chromeStyle`. */
+ *  #7742 D1 the optional `colorMode` and `chromeStyle`, #7797 D1 the optional `closingFooterPaths`. */
 const ALLOWED_LAYOUT_KEYS = new Set([
     ...LAYOUT_KEYS,
     "deckGrounds",
@@ -495,6 +495,7 @@ const ALLOWED_LAYOUT_KEYS = new Set([
     "deckPresentation",
     "colorMode",
     "chromeStyle",
+    "closingFooterPaths",
 ]);
 function validateLayout(raw, file) {
     const obj = requireObject(raw, file, "layout");

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export { CATALOG_TARGET_PATH, FREE_MODULES, addModule, LicenseRequiredError, PAI
 export { DEFAULT_AILK_MODULE_REGISTRY_URL, FetchModuleError, fetchModule, type FetchModuleOptions, } from "./lib/fetch-module.js";
 export { extractModuleBundle, type ExistingFilePolicy, type ExtractModuleBundleOptions, type InstallReportRow, } from "./lib/extract-module-bundle.js";
 export { ADD_MODULE_HELP, AddModuleRefusedError, applyModuleToScaffold, formatAddModuleReport, parseAddModuleArgs, type AddModuleReportRow, type AddModuleResult, type ApplyModuleOptions, } from "./add-module.js";
-export { APPLY_DESIGN_HELP, applyDesign, formatApplyDesignReport, parseApplyDesignArgs, type ApplyDesignArgs, type ApplyDesignChange, type ApplyDesignOptions, type ApplyDesignResult, } from "./apply-design.js";
+export { APPLY_DESIGN_HELP, UnreadChromeError, applyDesign, formatApplyDesignReport, parseApplyDesignArgs, type ApplyDesignArgs, type ApplyDesignChange, type ApplyDesignOptions, type ApplyDesignResult, } from "./apply-design.js";
 export type { HomeSeedOutcome } from "./design-home.js";
 export { SITE_ROSTER_PATH, readSiteRoster, siteRosterProblems, } from "./site-roster.js";
 export { SYNC_ROUTES_HELP, formatSyncRoutesReport, listTemplateRouteDirs, parseSyncRoutesArgs, syncRoutes, type RouteReport, type SyncRoutesOptions, type SyncRoutesResult, } from "./sync-routes.js";

package/dist/index.js

@@ -16,7 +16,7 @@ export { extractModuleBundle, } from "./lib/extract-module-bundle.js";
 export { ADD_MODULE_HELP, AddModuleRefusedError, applyModuleToScaffold, formatAddModuleReport, parseAddModuleArgs, } from "./add-module.js";
 // `create-ailk apply-design` (#6819) — make an existing site wear a design,
 // changing only its look. The pure core, beside `add-module`'s.
-export { APPLY_DESIGN_HELP, applyDesign, formatApplyDesignReport, parseApplyDesignArgs, } from "./apply-design.js";
+export { APPLY_DESIGN_HELP, UnreadChromeError, applyDesign, formatApplyDesignReport, parseApplyDesignArgs, } from "./apply-design.js";
 // The site's page roster of record and its install-diff check (#6682).
 export { SITE_ROSTER_PATH, readSiteRoster, siteRosterProblems, } from "./site-roster.js";
 // `create-ailk sync-routes` (#4986) — the template-route drift check + copy.

package/dist/lib/chrome-readers.d.ts

@@ -0,0 +1,21 @@
+import { type ResolvedSiteChrome } from "../site-chrome.js";
+/** One knob a design sets that one of the site's reader files does not read. */
+export interface UnreadChromeKnob {
+    knob: string;
+    /** Overlay-relative path of the reader file, with `/` separators. */
+    file: string;
+}
+/** The pattern that means "this text reads `knob`". */
+export declare function chromeReadPattern(knob: string): RegExp;
+/**
+ * knob → the overlay files that read it, sorted. Scans `<templatesDir>/apps/web`;
+ * fails closed (throws, naming the directory) when it is absent or unreadable,
+ * so a broken overlay can never read as "nothing reads any knob".
+ */
+export declare function chromeKnobReaders(templatesDir: string): Map<string, string[]>;
+/**
+ * The `(knob, file)` pairs where the resolved chrome sets a non-default `knob`,
+ * the shipped overlay's `file` reads it, the site has its own `file`, and the
+ * site's `file` does not read it. A reader file the site lacks is skipped.
+ */
+export declare function unreadChromeKnobs(resolved: ResolvedSiteChrome, readers: ReadonlyMap<string, readonly string[]>, siteDir: string): UnreadChromeKnob[];

package/dist/lib/chrome-readers.js

@@ -0,0 +1,100 @@
+/**
+ * Which generated app files read which chrome knob (#7781, spec
+ * docs/specs/apply-design-unread-chrome-spec.md).
+ *
+ * `apply-design` writes a design's chrome knobs into the site's generated
+ * `apps/web/lib/site-chrome.ts`; other generated files read them. A site
+ * scaffolded before a knob existed has a reader file that ignores it, so the
+ * design is half-applied. These pure functions find that gap:
+ *
+ * - `chromeKnobReaders` derives, from the shipped overlay, the files that read
+ *   each knob — nothing is hard-coded, so a new reader file is picked up.
+ * - `unreadChromeKnobs` compares the site's own copy of each reader file.
+ *
+ * "Reads `knob`" means the file's text matches `(?:siteChrome|chrome)\.<knob>\b`.
+ * A file that reads a knob under another name (a destructured alias) is not
+ * recognised — accepted (spec § Clarifications, detection).
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { DEFAULT_SITE_CHROME, } from "../site-chrome.js";
+/** The overlay tree the generated app files live under. */
+const OVERLAY_WEB_DIR = ["apps", "web"];
+/** What precedes a knob name in a read: `siteChrome.` or `chrome.` — the one definition both the overlay scan and the per-site check use. */
+const READ_HEAD = "(?:siteChrome|chrome)\\.";
+/** The pattern that means "this text reads `knob`". */
+export function chromeReadPattern(knob) {
+    return new RegExp(`${READ_HEAD}${knob.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`);
+}
+/** Every `.ts`/`.tsx` file under `dir` outside a `__tests__` segment, as `/`-joined paths relative to `root`. */
+function listSources(root, dir, out) {
+    for (const entry of readdirSync(join(root, dir), { withFileTypes: true })) {
+        const rel = `${dir}/${entry.name}`;
+        if (entry.isDirectory()) {
+            if (entry.name !== "__tests__")
+                listSources(root, rel, out);
+        }
+        else if (/\.tsx?$/.test(entry.name)) {
+            out.push(rel);
+        }
+    }
+}
+/**
+ * knob → the overlay files that read it, sorted. Scans `<templatesDir>/apps/web`;
+ * fails closed (throws, naming the directory) when it is absent or unreadable,
+ * so a broken overlay can never read as "nothing reads any knob".
+ */
+export function chromeKnobReaders(templatesDir) {
+    const webDir = join(templatesDir, ...OVERLAY_WEB_DIR);
+    const readers = new Map();
+    try {
+        if (!existsSync(webDir))
+            throw new Error("missing");
+        const files = [];
+        listSources(templatesDir, OVERLAY_WEB_DIR.join("/"), files);
+        for (const file of files.sort()) {
+            const text = readFileSync(join(templatesDir, file), "utf8");
+            for (const match of text.matchAll(new RegExp(`${READ_HEAD}([A-Za-z_$][\\w$]*)\\b`, "g"))) {
+                const knob = match[1];
+                const list = readers.get(knob) ?? [];
+                if (!list.includes(file))
+                    list.push(file);
+                readers.set(knob, list);
+            }
+        }
+    }
+    catch {
+        throw new Error(`cannot check chrome knobs: the overlay has no readable apps/web at ${webDir}. Reinstall create-ailk.`);
+    }
+    return readers;
+}
+/** A knob is set when it differs from its default; an optional knob (no default) when present. */
+function isSet(resolved, knob) {
+    const value = resolved[knob];
+    if (value === undefined)
+        return false;
+    if (!(knob in DEFAULT_SITE_CHROME))
+        return true;
+    return (value !== DEFAULT_SITE_CHROME[knob]);
+}
+/**
+ * The `(knob, file)` pairs where the resolved chrome sets a non-default `knob`,
+ * the shipped overlay's `file` reads it, the site has its own `file`, and the
+ * site's `file` does not read it. A reader file the site lacks is skipped.
+ */
+export function unreadChromeKnobs(resolved, readers, siteDir) {
+    const out = [];
+    for (const knob of Object.keys(resolved).sort()) {
+        if (!isSet(resolved, knob))
+            continue;
+        const pattern = chromeReadPattern(knob);
+        for (const file of readers.get(knob) ?? []) {
+            const abs = join(siteDir, file);
+            if (!existsSync(abs))
+                continue;
+            if (!pattern.test(readFileSync(abs, "utf8")))
+                out.push({ knob, file });
+        }
+    }
+    return out;
+}