create-ailk 0.14.0 → 0.16.0

package/dist/adopt.js

@@ -0,0 +1,314 @@
+/**
+ * `create-ailk adopt [<target-dir>]` — record, once, what an existing site
+ * is (#7875).
+ *
+ * A site scaffolded before #7426, or not scaffolded by create-ailk at all,
+ * has no `topology` in its `.ailk-site-manifest.json`, so every create-ailk
+ * command that asks `readSiteTopology` treats it as a hub — wrong for a site
+ * trimmed to a spoke by hand. Adopt writes the two fields the keystone added
+ * (D10 of spec 7426), and nothing else:
+ *
+ *   - `topology` is derived from the tree against `SPOKE_REMOVED_ROOTS`
+ *     (D1) — all removed roots absent is a spoke, all present a hub, a mix
+ *     is refused. Never a flag: the tree is the evidence;
+ *   - `patternVersion` is the running create-ailk version, the value a
+ *     scaffold records (D8 — on an adopted site, the version it was adopted
+ *     against);
+ *   - an existing manifest gains the two fields, every other byte kept
+ *     (`planTopologyRecord`, D3); a site with none gets one built by the
+ *     scaffold's own writer from `--template` and the module set
+ *     (`planAdoptedSiteManifest`, D4/D5);
+ *   - a manifest already recording either field is refused (D2): adopt runs
+ *     once. A recorded module a spoke cannot carry is a warning, never a
+ *     refusal (D6) — `add-module` is the admission gate, not adopt.
+ *
+ * It writes the manifest — never a seam file, `architecture.yaml`, anything
+ * under `apps/api`, and never another subcommand (`sync-routes --apply`
+ * included). The one exception is a spoke's `project.yaml` (#7874 D9): on a
+ * site it derives as a spoke, adopt also appends an `env_contract` row for
+ * every env var the site's code reads that has none, so its `pnpm
+ * env:declared` check has a contract to read. A hub's `project.yaml` is never
+ * touched. Every refusal throws before any write.
+ *
+ * Pure module: no `import.meta.url`, so jest can import it directly — the
+ * package-rooted directories are supplied by the CLI, the `add-route.ts`
+ * split. Spec: docs/specs/7875-create-ailk-adopt-spec.md.
+ */
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { readArchitectureHeader } from "./add-module-core.js";
+import { buildScaffoldMarkers } from "./copy.js";
+import { EnvContractError, planEnvRows } from "./lib/declared-env.js";
+import { ENV_CATALOG } from "./lib/env-catalog.js";
+import { normalizeModules } from "./module-architecture.js";
+import { ParseError, RECOGNIZED_MODULES, } from "./parse-args.js";
+import { planAdoptedSiteManifest, planTopologyRecord, } from "./site-manifest.js";
+import { LEGACY_SITE_ROSTER_PATH, SITE_ROSTER_PATH, readSiteRoster, resolveRosterTemplate, } from "./site-roster.js";
+import { SHAPE_STARTERS } from "./template-manifest.js";
+import { MCP_SEAM_PATH, SPOKE_REMOVED_ROOTS, WEB_SEAM_PATH, renderMcpSeam, renderWebSeam, spokeModuleRefusal, } from "./topology.js";
+/** A refusal the CLI exits 2 on, thrown before anything is written. */
+export class AdoptRefusedError extends Error {
+    exitCode = 2;
+    constructor(message) {
+        super(message);
+        this.name = "AdoptRefusedError";
+    }
+}
+/** The generated seam files, by the app directory each lives in, with their renders. */
+const SEAMS = [
+    { app: "apps/web", path: WEB_SEAM_PATH, render: renderWebSeam },
+    { app: "apps/mcp", path: MCP_SEAM_PATH, render: renderMcpSeam },
+];
+function isDirectory(path) {
+    return existsSync(path) && statSync(path).isDirectory();
+}
+/**
+ * D1 — the topology the tree shows: every `SPOKE_REMOVED_ROOTS` entry absent
+ * is a spoke, every one present a hub. Anything else is refused.
+ */
+function deriveTopology(targetDir) {
+    const present = SPOKE_REMOVED_ROOTS.filter((root) => isDirectory(join(targetDir, root)));
+    if (present.length === 0)
+        return "spoke";
+    if (present.length === SPOKE_REMOVED_ROOTS.length)
+        return "hub";
+    const absent = SPOKE_REMOVED_ROOTS.filter((root) => !present.includes(root));
+    throw new AdoptRefusedError(`adopt: ${targetDir} has ${present.join(", ")} but not ${absent.join(", ")}, so it is neither a hub nor a spoke`);
+}
+/** D5 — the module set for a site with no manifest: `--modules`, else the header. */
+function moduleSet(targetDir, flag) {
+    if (flag !== undefined) {
+        try {
+            return normalizeModules(flag.split(","));
+        }
+        catch (err) {
+            throw new AdoptRefusedError(`--modules is not a module list: ${err.message}`);
+        }
+    }
+    const archPath = join(targetDir, "architecture.yaml");
+    if (!existsSync(archPath)) {
+        throw new AdoptRefusedError(`${targetDir} has no architecture.yaml to read its module set from; name it with --modules <a,b>`);
+    }
+    try {
+        return readArchitectureHeader(readFileSync(archPath, "utf8")).modules;
+    }
+    catch (err) {
+        throw new AdoptRefusedError(`${err.message.replace(/\.$/, "")}. Name the module set with --modules <a,b> instead.`);
+    }
+}
+/** The recorded module names this package recognizes; anything else is ignored. */
+function recordedModules(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((m) => RECOGNIZED_MODULES.includes(m));
+}
+/**
+ * Adopt the site at `opts.targetDir`: write the manifest recording its
+ * topology and pattern version. Every refusal throws before the one write.
+ *
+ * @throws AdoptRefusedError (exit 2) on a refusal this command names, and
+ *   the `AddModuleRefusedError` (exit 2) the roster readers and manifest
+ *   writer throw on a manifest they cannot read or extend.
+ */
+export function adoptSite(opts) {
+    const targetDir = resolve(opts.targetDir);
+    if (!isDirectory(targetDir)) {
+        throw new Error(`adopt target is not a directory: ${targetDir}. Point adopt at an existing site.`);
+    }
+    const topology = deriveTopology(targetDir);
+    const markers = buildScaffoldMarkers(basename(targetDir));
+    const patternVersion = markers["CREATE_AILK_VERSION"];
+    if (patternVersion === undefined || patternVersion === "") {
+        // A once-only field: never record an empty version a second run cannot fix.
+        throw new Error("adopt: this create-ailk has no version to record");
+    }
+    const record = { topology, patternVersion };
+    const roster = readSiteRoster(targetDir);
+    let text;
+    let modules;
+    if (roster !== undefined) {
+        if (roster.path === LEGACY_SITE_ROSTER_PATH) {
+            throw new AdoptRefusedError(`${LEGACY_SITE_ROSTER_PATH} is the pre-#6658 roster name; rename it to ${SITE_ROSTER_PATH}, then re-run adopt.`);
+        }
+        for (const key of ["topology", "patternVersion"]) {
+            if (key in roster.doc) {
+                throw new AdoptRefusedError(`${roster.path} already records "${key}", so this site is already adopted. To move it to a new create-ailk version, see the README § Keeping a spoke current.`);
+            }
+        }
+        for (const [flag, value] of [
+            ["--template", opts.template],
+            ["--modules", opts.modules],
+        ]) {
+            if (value !== undefined) {
+                throw new AdoptRefusedError(`${roster.path} already records the site's template and modules; ${flag} would contradict it. Re-run adopt without ${flag}.`);
+            }
+        }
+        text = planTopologyRecord(roster.text, record, roster.path);
+        modules = recordedModules(roster.doc["modules"]);
+    }
+    else {
+        if (opts.template === undefined) {
+            throw new AdoptRefusedError(`${targetDir} has no ${SITE_ROSTER_PATH}; name the template it was built from with --template <name> (one of: ${Object.keys(SHAPE_STARTERS).join(", ")}).`);
+        }
+        try {
+            resolveRosterTemplate(opts.template);
+        }
+        catch (err) {
+            throw new AdoptRefusedError(`--template "${opts.template}" names no declared template: ${err.message}`);
+        }
+        modules = moduleSet(targetDir, opts.modules);
+        text = planAdoptedSiteManifest({
+            targetDir,
+            template: opts.template,
+            modules,
+            ...record,
+            siteTemplatesDir: opts.siteTemplatesDir,
+            templatesDir: opts.templatesDir,
+            markers,
+        });
+    }
+    const warnings = topology === "spoke"
+        ? modules.flatMap((m) => spokeModuleRefusal(m) ?? [])
+        : [];
+    const seams = SEAMS.filter(({ app }) => isDirectory(join(targetDir, app))).map(({ path, render }) => {
+        const abs = join(targetDir, path);
+        if (!existsSync(abs))
+            return { path, state: "absent" };
+        return {
+            path,
+            state: readFileSync(abs, "utf8") === render(topology) ? "present" : "differs",
+        };
+    });
+    // #7874 D9 — a spoke's env_contract rows, planned before any write: a
+    // block adopt cannot read is a refusal, and nothing is written.
+    const yamlPath = join(targetDir, "project.yaml");
+    let env = { state: "hub" };
+    let yamlNext;
+    if (topology === "spoke") {
+        if (!existsSync(yamlPath)) {
+            env = { state: "no-project-yaml" };
+        }
+        else {
+            const yamlText = readFileSync(yamlPath, "utf8");
+            try {
+                const plan = planEnvRows(targetDir, yamlText, {
+                    topology,
+                    catalog: ENV_CATALOG,
+                });
+                if (plan.text === yamlText) {
+                    env = { state: "unchanged" };
+                }
+                else {
+                    env = { state: "written", added: plan.added };
+                    yamlNext = plan.text;
+                }
+            }
+            catch (err) {
+                if (err instanceof EnvContractError) {
+                    throw new AdoptRefusedError(`adopt: ${err.message}`);
+                }
+                throw err;
+            }
+        }
+    }
+    writeFileSync(join(targetDir, SITE_ROSTER_PATH), text);
+    if (yamlNext !== undefined)
+        writeFileSync(yamlPath, yamlNext);
+    return {
+        targetDir,
+        path: SITE_ROSTER_PATH,
+        topology,
+        patternVersion,
+        created: roster === undefined,
+        seams,
+        warnings,
+        env,
+    };
+}
+/** The printed report: the path written, the record, the seams, the warnings. */
+export function formatAdoptReport(result) {
+    const lines = [
+        `[create-ailk] adopt → ${result.targetDir}`,
+        `${result.created ? "Wrote" : "Updated"} ${result.path}`,
+        `  topology: ${result.topology}`,
+        `  patternVersion: ${result.patternVersion}`,
+    ];
+    if (result.seams.length > 0) {
+        lines.push(`Seam files (against the ${result.topology} render):`);
+        const width = Math.max(...result.seams.map((s) => s.path.length));
+        lines.push(...result.seams.map((s) => `  ${s.path.padEnd(width)}  ${s.state}`));
+    }
+    const env = formatAdoptEnv(result.env);
+    if (env !== undefined)
+        lines.push(env);
+    lines.push(...result.warnings.map((w) => `warning: ${w}`));
+    return lines.join("\n") + "\n";
+}
+/** The report's one env_contract line (#7874 D9); none on a hub. */
+function formatAdoptEnv(env) {
+    switch (env.state) {
+        case "written":
+            return `env_contract: ${env.added.length} rows added (${env.added.join(", ")})`;
+        case "unchanged":
+            return "env_contract: every read already declared";
+        case "no-project-yaml":
+            return "env_contract: no project.yaml, nothing written";
+        case "hub":
+            return undefined;
+    }
+}
+export const ADOPT_HELP = `create-ailk adopt — record what an existing site is, once.
+
+Usage:
+  create-ailk adopt [<target-dir>] [--template <name>] [--modules <a,b>]
+
+Arguments:
+  <target-dir>             The existing site. Defaults to the current dir.
+
+Options:
+  --template <name>        The template the site was built from. Required
+                           when the site has no .ailk-site-manifest.json;
+                           refused when it has one.
+  --modules <a,b>          The site's module set, when it has no manifest.
+                           Overrides architecture.yaml's "# Modules:" header.
+  --help, -h               Print this message.
+
+Writes "topology" and "patternVersion" into .ailk-site-manifest.json. On a
+spoke it also appends an env_contract row to project.yaml for every
+environment variable the site's code reads that has none, so pnpm
+env:declared has a contract to check; it never edits or removes a row, and
+it never touches a hub's project.yaml. Nothing else is written. The
+topology is read from the tree: no apps/api and no database/ is a spoke,
+both is a hub, one without the other is refused.
+patternVersion is this create-ailk's version. A site with no manifest gets
+one, built the way a scaffold builds it. A manifest that already records
+either field is refused: adopt runs once. A recorded module a spoke cannot
+carry is a warning, not a refusal.
+`;
+/**
+ * Parse the argv AFTER the `adopt` word. Strict `node:util` parseArgs, like
+ * `parseAddRouteArgs`; the values themselves are validated by `adoptSite`.
+ */
+export function parseAdoptArgs(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        strict: true,
+        allowPositionals: true,
+        options: {
+            template: { type: "string" },
+            modules: { type: "string" },
+            help: { type: "boolean", default: false, short: "h" },
+        },
+    });
+    const [target, ...rest] = parsed.positionals;
+    if (rest.length > 0) {
+        throw new ParseError(`adopt takes at most one target directory, got ${parsed.positionals.length} arguments`);
+    }
+    return {
+        target,
+        template: parsed.values.template,
+        modules: parsed.values.modules,
+        help: parsed.values.help === true,
+    };
+}

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

@@ -7,6 +7,12 @@
  *      addModule(), print the report, exit (2 on a refusal it names)
  *      on an `add-route` subcommand: add one route surface to an existing
  *      site, print the report, exit (2 on a refusal it names) (#6947)
+ *      on an `adopt` subcommand: record an existing site's topology and
+ *      pattern version in its manifest, print the report, exit (2 on a
+ *      refusal it names) (#7875)
+ *      on a `seed-flows` subcommand: send a spoke's declared flows/*.json to
+ *      its hub with the key from AILK_SPOKE_KEY, print one line per flow,
+ *      exit 1 if any failed (2 on a refusal it names, nothing sent) (#7876)
  *      on a `sync-routes` subcommand: parse its own argv, run syncRoutesSync(),
  *      print the report, exit (1 iff routes are missing in check mode)
  *      on a `license set` subcommand: write the key into the scaffold, push it
@@ -40,6 +46,7 @@ import { basename, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ADD_MODULE_HELP, AddModuleRefusedError, formatAddModuleReport, parseAddModuleArgs, } from "./add-module.js";
 import { ADD_ROUTE_HELP, AddRouteRefusedError, addRouteToScaffold, formatAddRouteReport, parseAddRouteArgs, } from "./add-route.js";
+import { ADOPT_HELP, AdoptRefusedError, adoptSite, formatAdoptReport, parseAdoptArgs, } from "./adopt.js";
 import { APPLY_DESIGN_HELP, applyDesign, formatApplyDesignReport, parseApplyDesignArgs, } from "./apply-design.js";
 import { CLAUDE_MD_CHECK_PATH } from "./claude-md.js";
 import { buildScaffoldMarkers } from "./copy.js";
@@ -48,6 +55,7 @@ import { FREE_PREREQUISITES_NOTE, LICENSED_PREREQUISITES_NOTE, isLicensedInstall
 import { LICENSE_SET_HELP, runLicenseSet } from "./license-set.js";
 import { PLUGIN_INSTALL_LINES, helpText, parseCliArgs, parseModules, resolveCliShape, toScaffoldOptions, } from "./parse-args.js";
 import { addModule, formatSurfaceDrift, scaffold, syncArchitectureSync, syncCatalogSync, syncClaudeMdSync, syncRoutesSync, } from "./programmatic.js";
+import { SEED_FLOWS_HELP, SeedFlowsRefusedError, parseSeedFlowsArgs, seedFlows, } from "./seed-flows.js";
 import { CORE_SURFACE_PATHS, SURFACE_ALIASES } from "./surfaces.js";
 import { SYNC_ROUTES_HELP, formatSyncRoutesReport, parseSyncRoutesArgs, } from "./sync-routes.js";
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -161,6 +169,62 @@ async function main() {
         }
         process.exit(0);
     }
+    // `adopt [dir]` (#7875): record an existing site's topology and pattern
+    // version in its manifest, once. Writes that one file and nothing else. A
+    // refusal it names (a half-trimmed tree, a second run, a missing or
+    // contradicting --template / --modules, a legacy roster) exits 2.
+    if (argv[0] === "adopt") {
+        const args = parseAdoptArgs(argv.slice(1));
+        if (args.help) {
+            process.stdout.write(ADOPT_HELP);
+            process.exit(0);
+        }
+        try {
+            const result = adoptSite({
+                targetDir: args.target ?? process.cwd(),
+                templatesDir: resolve(PKG_ROOT, "templates"),
+                siteTemplatesDir: resolve(PKG_ROOT, "site-templates"),
+                template: args.template,
+                modules: args.modules,
+            });
+            process.stdout.write(formatAdoptReport(result));
+        }
+        catch (err) {
+            if (!(err instanceof AdoptRefusedError) &&
+                !(err instanceof AddModuleRefusedError)) {
+                throw err;
+            }
+            process.stderr.write(`[create-ailk] ${err.message}\n`);
+            process.exit(err.exitCode);
+        }
+        process.exit(0);
+    }
+    // `seed-flows [dir]` (#7876): send a spoke's declared flows/*.json to its
+    // hub with the spoke key from AILK_SPOKE_KEY. Exit 1 when any flow failed;
+    // a refusal it names (a hub, a bad file, no key, no valid hub origin)
+    // exits 2 before anything is sent.
+    if (argv[0] === "seed-flows") {
+        const args = parseSeedFlowsArgs(argv.slice(1));
+        if (args.help) {
+            process.stdout.write(SEED_FLOWS_HELP);
+            process.exit(0);
+        }
+        try {
+            const result = await seedFlows({
+                targetDir: args.target ?? process.cwd(),
+                hubUrl: args.hubUrl,
+                dryRun: args.dryRun,
+                onLine: (line) => process.stdout.write(`${line}\n`),
+            });
+            process.exit(result.exitCode);
+        }
+        catch (err) {
+            if (!(err instanceof SeedFlowsRefusedError))
+                throw err;
+            process.stderr.write(`[create-ailk] ${err.message}\n`);
+            process.exit(err.exitCode);
+        }
+    }
     // Subcommand dispatch, ahead of the flag parser: `sync-routes` has its own
     // argv shape (#4986). Check mode exits 1 iff a template route is missing;
     // locally modified routes are reported but do not fail; --apply exits 0.
@@ -203,6 +267,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);
@@ -246,6 +311,10 @@ async function main() {
             "\n" +
             ADD_ROUTE_HELP +
             "\n" +
+            ADOPT_HELP +
+            "\n" +
+            SEED_FLOWS_HELP +
+            "\n" +
             APPLY_DESIGN_HELP +
             "\n" +
             LICENSE_SET_HELP);
@@ -318,7 +387,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, hubSignInOrigin, } = 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 +416,34 @@ 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, ${hubSignInOrigin !== undefined ? "sign-in through the hub" : "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",
+                // #7894 D11 — the hub sign-in mode's client, issued on the hub.
+                ...(hubSignInOrigin !== undefined
+                    ? [
+                        `  AILK_HUB_SIGN_IN_URL=${hubSignInOrigin}   # written to apps/web/.env.local`,
+                        "  AILK_HUB_SESSION_SECRET    # generated into apps/web/.env.local; keep it secret",
+                        "  AILK_HUB_CLIENT_ID         # this spoke's id on the hub; never written here",
+                        "  AILK_HUB_CLIENT_SECRET     # issued by the hub; never written here",
+                        "",
+                        "On the hub, issue the client id and secret with:",
+                        "  pnpm --filter @working-theory/api spokes sign-in-client --id <spoke_id> --redirect-uri <this site's origin>/api/hub-session/callback",
+                    ]
+                    : []),
+            ]
+            : []),
         "",
     ];
     // Prerequisites (#6440 AC4) — every one the scaffold enforces, and nothing
@@ -374,13 +472,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)