create-ailk 0.14.0 → 0.16.0

package/dist/parse-args.js

@@ -59,6 +59,14 @@ const SHAPE_DESCRIPTIONS = {
     "person-service": "a person selling their own service",
 };
 const SHAPE_LIST = RECOGNIZED_SHAPES.join(", ");
+/**
+ * The `--topology` vocabulary (#7426 D1) — orthogonal to `--shape`: any shape
+ * can be scaffolded as either. Declared here rather than imported from
+ * `topology.ts` for the reason `RECOGNIZED_MODULES` is: that module reads
+ * `MODULE_SLICES`, and importing it here closes a runtime cycle through
+ * `lib/module-tier.ts`. `spoke-topology.test.ts` pins the two lists equal.
+ */
+export const RECOGNIZED_TOPOLOGIES = ["hub", "spoke"];
 export class ParseError extends Error {
     constructor(message) {
         super(message);
@@ -158,6 +166,24 @@ Options:
   --license <key>          Your licence key: fetch paid modules with it and
                            write it into the scaffold (apps/api/.env and a
                            gitignored ailk.key, both owner-only).
+  --topology <hub|spoke>   hub (the default) scaffolds the whole site: web,
+                           API, MCP and database. spoke scaffolds a web-only
+                           site that sends its forms, flows and listings to a
+                           hub — no apps/api, no database, no sign-in, and
+                           apps/mcp kept as a stateless front. Composes with
+                           any --shape or --template. A spoke carries
+                           marketing and docs-blog.
+  --hub-url <origin>       A spoke's hub, e.g. https://hub.example.com (https:,
+                           or http: on localhost). Defaults to AILK_API_URL;
+                           a spoke with neither is refused. Written to
+                           apps/web/.env.local — the spoke key never is.
+  --without-mcp            A spoke without apps/mcp.
+  --hub-sign-in <origin>   A spoke whose /account signs visitors in through
+                           its hub's own sign-in page (the hub's web origin,
+                           https: or http: on localhost). No database: the
+                           session is a sealed cookie. Writes the origin and
+                           a session secret to apps/web/.env.local — never the
+                           client secret, which the hub issues.
   --install                After scaffolding, run \`pnpm install\` in the
                            target directory. Off by default.
   --help, -h               Print this message.
@@ -194,6 +220,10 @@ export function parseCliArgs(argv, env = { interactive: false }) {
                 shape: { type: "string" },
                 design: { type: "string" },
                 license: { type: "string" },
+                topology: { type: "string" },
+                "hub-url": { type: "string" },
+                "without-mcp": { type: "boolean", default: false },
+                "hub-sign-in": { type: "string" },
                 surfaces: { type: "string" },
                 "sync-architecture": { type: "string" },
                 "sync-catalog": { type: "boolean", default: false },
@@ -224,6 +254,11 @@ export function parseCliArgs(argv, env = { interactive: false }) {
     const syncClaudeMd = parsed.values["sync-claude-md"] === true;
     const withCatalog = parsed.values["with-catalog"] === true;
     const license = parseLicense(parsed.values.license);
+    const rawTopology = parsed.values.topology;
+    const topology = parseTopology(rawTopology);
+    const hubUrl = parsed.values["hub-url"];
+    const withoutMcp = parsed.values["without-mcp"] === true;
+    const hubSignIn = parsed.values["hub-sign-in"];
     // The sync modes each exit after rewriting their one file, so asking for
     // more than one in one invocation has no coherent meaning.
     const syncFlags = [
@@ -234,6 +269,22 @@ export function parseCliArgs(argv, env = { interactive: false }) {
     if (syncFlags.length > 1) {
         throw new ParseError(`${syncFlags.join(" and ")} cannot be combined; run them one at a time`);
     }
+    // #7426 D1 — a sync reads the topology from the site's manifest; naming one
+    // here has no coherent meaning.
+    if (rawTopology !== undefined && syncFlags.length > 0) {
+        throw new ParseError(`--topology cannot be combined with ${syncFlags[0]}: a sync reads the site's topology from its .ailk-site-manifest.json`);
+    }
+    // #7426 D2/D3 — the spoke-only flags.
+    if (topology !== "spoke") {
+        const spokeOnly = [
+            hubUrl !== undefined ? "--hub-url" : undefined,
+            withoutMcp ? "--without-mcp" : undefined,
+            hubSignIn !== undefined ? "--hub-sign-in" : undefined,
+        ].filter((f) => f !== undefined);
+        if (spokeOnly.length > 0) {
+            throw new ParseError(`${spokeOnly.join(" and ")} only apply${spokeOnly.length === 1 ? "s" : ""} to a spoke. Pass --topology spoke, or drop ${spokeOnly.length === 1 ? "it" : "them"}.`);
+        }
+    }
     // Validate the sync-architecture value now, through the SAME parseModules
     // path `--modules` uses, so an unknown module throws ParseError at parse time
     // (cli.ts re-parses the raw value to the module list in sync mode).
@@ -255,6 +306,7 @@ export function parseCliArgs(argv, env = { interactive: false }) {
             syncClaudeMd: false,
             withCatalog: false,
             syncArchitecture: undefined,
+            topology: "hub",
         };
     }
     // Sync modes: the target dir is optional (positional if given, else cwd).
@@ -275,6 +327,7 @@ export function parseCliArgs(argv, env = { interactive: false }) {
             syncClaudeMd,
             withCatalog,
             syncArchitecture,
+            topology: "hub",
         };
     }
     if (parsed.positionals.length === 0) {
@@ -292,6 +345,13 @@ export function parseCliArgs(argv, env = { interactive: false }) {
                 : "--design";
         throw new ParseError(`--template cannot be combined with ${flags}: a template already fixes its shape and design. Pass --template alone, or --shape with an optional --design.`);
     }
+    // #7426 D2 — a spoke needs its hub's origin. Presence only, here: the value
+    // is validated and normalized by `scaffold()` (`topology.ts`
+    // `normalizeHubUrl`), still before the target directory exists.
+    if (topology === "spoke" &&
+        (hubUrl ?? process.env["AILK_API_URL"] ?? "").trim() === "") {
+        throw new ParseError("a spoke needs its hub's origin, and none was given. Pass --hub-url <origin>, or set AILK_API_URL (e.g. https://hub.example.com).");
+    }
     // R1 — no silent default: with neither a template nor a shape, ask on a
     // terminal and refuse without one.
     const needsShapePrompt = template === undefined && shape === undefined;
@@ -314,8 +374,26 @@ export function parseCliArgs(argv, env = { interactive: false }) {
         withCatalog,
         syncArchitecture: undefined,
         ...(license !== undefined ? { license } : {}),
+        topology,
+        ...(topology === "spoke"
+            ? {
+                ...(hubUrl !== undefined ? { hubUrl } : {}),
+                mcp: !withoutMcp,
+                ...(hubSignIn !== undefined ? { hubSignIn } : {}),
+            }
+            : {}),
     };
 }
+/** Validate `--topology` (#7426 D1): `hub` when absent, trimmed and lowercased. */
+function parseTopology(raw) {
+    if (raw === undefined)
+        return "hub";
+    const name = raw.trim().toLowerCase();
+    if (!RECOGNIZED_TOPOLOGIES.includes(name)) {
+        throw new ParseError(`unknown topology "${raw}". Recognized: ${RECOGNIZED_TOPOLOGIES.join(", ")}`);
+    }
+    return name;
+}
 /**
  * Validate `--shape` (#6754 D2 step 2): trimmed and lowercased. A reserved
  * shape is refusal R2; any other unrecognized value names the recognized set.
@@ -467,6 +545,17 @@ export function toScaffoldOptions(opts) {
         ...(opts.shape !== undefined ? { shape: opts.shape } : {}),
         ...(opts.design !== undefined ? { design: opts.design } : {}),
         ...(opts.license !== undefined ? { license: opts.license } : {}),
+        // #7426 — a hub run hands `scaffold()` the object it did before.
+        ...(opts.topology === "spoke"
+            ? {
+                topology: "spoke",
+                ...(opts.hubUrl !== undefined ? { hubUrl: opts.hubUrl } : {}),
+                mcp: opts.mcp !== false,
+                ...(opts.hubSignIn !== undefined
+                    ? { hubSignInUrl: opts.hubSignIn }
+                    : {}),
+            }
+            : {}),
     };
 }
 /**

package/dist/programmatic.d.ts

@@ -22,6 +22,7 @@ import { type ModuleName } from "./parse-args.js";
 import { type TemplateLayout } from "./site-chrome.js";
 import { type SyncRoutesResult } from "./sync-routes.js";
 import { type StarterShape } from "./template-manifest.js";
+import { type Topology } from "./topology.js";
 export interface ScaffoldOptions {
     /** Absolute or relative path to the target directory. Must not exist or be empty. */
     targetDir: string;
@@ -136,6 +137,24 @@ export interface ScaffoldOptions {
      * code registry that has since been deleted (#6638's per-name table).
      */
     designLayout?: TemplateLayout;
+    /**
+     * The scaffold's topology (`--topology`, #7426 D1). `"hub"` — the default
+     * — is the whole site. `"spoke"` is the same scaffold with nodes removed
+     * (`topology.ts`): no `apps/api`, no `database/`, no sign-in, `apps/mcp`
+     * a stateless front unless `mcp: false`. A spoke needs a `template` or a
+     * `shape` (the manifest records the topology) and a hub origin.
+     */
+    topology?: Topology;
+    /** A spoke's hub origin (`--hub-url`), else `AILK_API_URL` (#7426 D2). */
+    hubUrl?: string;
+    /** Spoke only: `false` drops `apps/mcp` (`--without-mcp`, #7426 D3). Default true. */
+    mcp?: boolean;
+    /**
+     * Spoke only: the hub's web origin this spoke signs visitors in at
+     * (`--hub-sign-in`, #7894 D1). Set, the spoke is scaffolded in the hub
+     * sign-in mode (`SpokeShapeOptions.signIn: "hub"`).
+     */
+    hubSignInUrl?: string;
 }
 export interface ScaffoldResult {
     /** Resolved absolute path to the scaffolded directory. */
@@ -161,6 +180,15 @@ export interface ScaffoldResult {
      * a keyed run with no `--modules` carries the key's derived level here.
      */
     modules: ModuleName[];
+    /**
+     * A spoke only (#7426 D7): modules the key's default set carried that a
+     * spoke does not admit, dropped from this scaffold. Absent when none were.
+     */
+    droppedModules?: ModuleName[];
+    /** A spoke only (#7426 D2): the normalized hub origin written to apps/web/.env.local. */
+    hubOrigin?: string;
+    /** A hub sign-in spoke only (#7894 D11): the hub web origin written to apps/web/.env.local. */
+    hubSignInOrigin?: string;
 }
 /**
  * Scaffold an AI Launch Kit starter project into targetDir (synchronous).

package/dist/programmatic.js

@@ -18,7 +18,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmdirSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { AddModuleRefusedError, applyModuleToScaffold, } from "./add-module.js";
+import { AddModuleRefusedError, addModuleSiteTopology, applyModuleToScaffold, } from "./add-module.js";
 import { planDesignMd } from "./apply-design-md.js";
 import { renderClaudeMd, syncClaudeMd, } from "./claude-md.js";
 import { CATALOG_TARGET_PATH, writeComponentCatalog, } from "./component-catalog.js";
@@ -29,21 +29,26 @@ import { HOME_PAGE_PATH, designHomeSeeds, planDesignHome, shapeHomePath, shipped
 import { applyDesignPresets, readSectionLookCatalog, shippedPageTypes, validateDesignPresets, } from "./design-presets.js";
 import { resolveDesign, spliceThemeBlock, } from "./design-scaffold.js";
 import { writeAuthSecretFile } from "./lib/auth-secret-file.js";
+import { appendEnvRows } from "./lib/declared-env.js";
+import { ENV_CATALOG } from "./lib/env-catalog.js";
 import { extractModuleBundle, installBundleTree, } from "./lib/extract-module-bundle.js";
 import { fetchTemplate } from "./lib/fetch-template.js";
 import { assertLicenseKeyShape, writeLicenseKeyFiles, } from "./lib/license-key-files.js";
 import { assertDesignAllowed, assertReleased, deriveDesignLevel, deriveLevel, resolveModuleSet, resolvePaidModules, } from "./lib/module-license-gate.js";
-import { classifyModules } from "./lib/module-tier.js";
+import { classifyModules, isAddition } from "./lib/module-tier.js";
 import { normalizeModules } from "./module-architecture.js";
 import { writePaidSections } from "./paid-sections.js";
 import { RECOGNIZED_SHAPES, RESERVED_SHAPES, } from "./parse-args.js";
+import { writeSpokeFlowsReadme } from "./seed-flows.js";
 import { SITE_CHROME_PATH, renderSiteChrome, resolveSiteChrome, } from "./site-chrome.js";
 import { SITE_FONTS_PATH, renderSiteFonts } from "./site-fonts.js";
 import { planSiteManifest } from "./site-manifest.js";
 import { SITE_ROSTER_PATH, planHomeRecord, planSiteManifestDesign, readSiteRoster, withMeetPlaceholderSeeds, } from "./site-roster.js";
+import { spokeCheckoutSite, spokeEnvRowOptions, writeSpokeCheckoutSlice, } from "./spoke-checkout.js";
 import { GATEABLE_SURFACES, MODULE_SURFACES, NAV_CONFIG_PATH, excludedRoutePaths, renderNavConfig, resolveSurfaces, } from "./surfaces.js";
 import { syncRoutes } from "./sync-routes.js";
 import { BASE_LAYER_DIR, SHAPE_STARTERS, TEMPLATE_MANIFESTS, TemplateError, mergeRoster, resolveTemplate, resolveTemplateLineage, rosterDeclares, templateDelivery, templateTreeDir, } from "./template-manifest.js";
+import { SPOKE_ONLY_FILES, TopologyError, applySpokeTransforms, isSpokeExcluded, normalizeHubSignInUrl, normalizeHubUrl, readSiteTopology, spokeExclusions, spokeDestination, spokeModuleRefusal, spokeModules, writeHubOriginEnv, writeHubSignInEnv, } from "./topology.js";
 import { validateTarget } from "./validate.js";
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const TEMPLATES_DIR = resolve(PKG_ROOT, "templates");
@@ -151,14 +156,31 @@ export function scaffoldSync(opts) {
     // The declared route surface (#4154). Resolved BEFORE the copy: it decides
     // both which route directories are skipped and what architecture.yaml records.
     const enabledSurfaces = resolveSurfaces(opts.modules ?? ["marketing"], opts.surfaces ?? []);
+    // #7426 D4 — a spoke is this same copy with the spoke's exclusions added:
+    // one registry over the one template tree, never a second tree.
+    const spoke = opts.topology === "spoke"
+        ? {
+            mcp: opts.mcp !== false,
+            ...(opts.hubSignInUrl !== undefined ? { signIn: "hub" } : {}),
+        }
+        : undefined;
     const versions = readVersionMap();
     copyTemplate({
         templatesDir: TEMPLATES_DIR,
         targetDir: targetAbs,
         versions,
-        excludePaths: excludedRoutePaths(enabledSurfaces),
+        excludePaths: [
+            ...excludedRoutePaths(enabledSurfaces),
+            // #7874 D11 — the declared-env check is a spoke's alone.
+            ...(spoke !== undefined
+                ? spokeExclusions(TEMPLATES_DIR, spoke)
+                : SPOKE_ONLY_FILES),
+        ],
         markers: buildScaffoldMarkers(projectName),
     });
+    // #7426 D5/D6 — the root files a spoke rewrites, and the spoke seams.
+    if (spoke !== undefined)
+        applySpokeTransforms(targetAbs, spoke);
     // Stamp the copied CLAUDE.md's template regions with their hashes (#6904
     // D2). No later layer writes a root CLAUDE.md, so this is the final file.
     writeFileSync(join(targetAbs, "CLAUDE.md"), renderClaudeMd(readFileSync(join(TEMPLATES_DIR, "CLAUDE.md"), "utf8"), projectName));
@@ -167,7 +189,7 @@ export function scaffoldSync(opts) {
     // closes the dangling `architecture_rules: architecture.yaml` reference in
     // the scaffolded project.yaml. Written AFTER the template copy, at the target
     // root — a deterministic function of the selected module set.
-    writeFileSync(join(targetAbs, "architecture.yaml"), deriveArchitecture(opts.modules ?? ["marketing"], enabledSurfaces));
+    writeFileSync(join(targetAbs, "architecture.yaml"), deriveArchitecture(opts.modules ?? ["marketing"], enabledSurfaces, spoke !== undefined ? { topology: "spoke", mcp: spoke.mcp } : {}));
     // Regenerate the site nav from the same surface set (#4154). The nav is a
     // static list the layout renders into the header AND the footer, so leaving
     // the template's copy in place would link /docs and /blog sitewide in a
@@ -187,6 +209,11 @@ export function scaffoldSync(opts) {
     // scaffold with `withCatalog` unset touches exactly the files it did before.
     if (opts.withCatalog === true)
         writeComponentCatalog(targetAbs);
+    // #7874 D9 — a spoke's env_contract rows, as its last write, so every file
+    // above is in the scan. A hub's project.yaml is never touched.
+    if (spoke !== undefined) {
+        appendEnvRows(targetAbs, { topology: "spoke", catalog: ENV_CATALOG });
+    }
     const filesCreated = countFiles(targetAbs);
     return {
         targetDir: targetAbs,
@@ -252,6 +279,9 @@ export async function scaffold(opts) {
             ? resolveShapeTemplate(opts.shape)
             : undefined;
     assertReleased("modules", [...(opts.modules ?? []), ...(template?.requires ?? [])]);
+    // #7426 D1-D3/D7 — a spoke's refusals, before anything is fetched or
+    // written: the target directory never exists for a refused spoke.
+    const spoke = resolveSpoke(opts, template);
     // #6813 D8 step 3 — the design this scaffold renders, resolved from its
     // package ONCE, before any fetch or write: the caller's override, else the
     // template's own. Unset for a scaffold naming neither. Replaces the
@@ -308,6 +338,8 @@ export async function scaffold(opts) {
     // list.
     let modules;
     let bundles;
+    // #7426 D7 — the key's default modules a spoke does not admit.
+    let dropped = [];
     // The run's derived level (#6759), for `assertDesignAllowed` below.
     // Undefined on the alias branch and on a `--modules`-keep run (D2/D4 in
     // module-license-gate.ts — the level plays no part in composing either),
@@ -360,6 +392,19 @@ export async function scaffold(opts) {
         });
         bundles = chosen.bundles;
         level = chosen.level;
+        // #7426 D7 — a key-derived default set keeps only what a spoke admits;
+        // the run names what it dropped (`droppedModules`). Naming only
+        // additions (`--modules commerce`) keeps the level default too, so it is
+        // filtered the same way (#7838 D12); a named keep set is never touched.
+        if (spoke !== undefined &&
+            (opts.modules === undefined ||
+                opts.modules.every(isAddition))) {
+            const admitted = new Set(spokeModules());
+            dropped = chosen.modules.filter((m) => !admitted.has(m));
+            chosen.modules = chosen.modules.filter((m) => admitted.has(m));
+            for (const name of dropped)
+                bundles.delete(name);
+        }
         // #7010 — a `--modules`-keep run composes no level (NFR-2), so a chosen
         // non-Free design derives one from the key here, as the addition branch
         // does; a plain keep run makes no extra network call.
@@ -453,6 +498,7 @@ export async function scaffold(opts) {
     const result = scaffoldSync({
         ...opts,
         modules,
+        ...(spoke !== undefined ? { topology: "spoke", mcp: spoke.mcp } : {}),
         ...(surfaces !== undefined ? { surfaces } : {}),
         // #5612 D1/D2 — the code registry's own `layout` block, known
         // synchronously (unlike a bundle's `ailk-template.json`, only readable
@@ -476,7 +522,8 @@ export async function scaffold(opts) {
     // it a `{{MARKER}}` authored in a base-layer or site-template file would
     // survive into the scaffold verbatim — the state before this card, and the
     // reason a template file could not carry the version stamp.
-    const markers = buildScaffoldMarkers(opts.projectName ?? basename(result.targetDir));
+    const projectName = opts.projectName ?? basename(result.targetDir);
+    const markers = buildScaffoldMarkers(projectName);
     // #5618 D4 — the file-grain ownership registry for THIS scaffold: which
     // layer wrote which destination. Call-scoped (a fresh Map per scaffold(),
     // never module-level), threaded through every layer install below in the
@@ -486,6 +533,16 @@ export async function scaffold(opts) {
     // anything. Starts empty at the base-layer boundary: the `templates/`
     // snapshot (layer 0) is deliberately outside it.
     const ownership = new Map();
+    // #7426 D4 — every layer below lands through the spoke filter: a module
+    // bundle's or the template's destination a spoke does not carry is dropped.
+    // #7876 D10 — and a module flow file lands in `flows/` as declared data.
+    const exclusions = spoke !== undefined ? spokeExclusions(TEMPLATES_DIR, spoke) : [];
+    const spokeSkip = spoke !== undefined
+        ? {
+            skip: (destination) => isSpokeExcluded(destination, { ...spoke, exclusions }),
+            remapDestination: spokeDestination,
+        }
+        : {};
     // The BASE LAYER lands first (#5618 D1) — the seed files every template
     // reaches by `extends` (today the three module-less base pages), read off
     // the `site-templates/_base/` tree this package ships, through the same
@@ -505,6 +562,7 @@ export async function scaffold(opts) {
             versions,
             markers,
             ownership,
+            ...spokeSkip,
         });
     }
     for (const [moduleName, bytes] of bundles) {
@@ -515,6 +573,7 @@ export async function scaffold(opts) {
             versions,
             markers,
             ownership,
+            ...spokeSkip,
         });
     }
     // The template lands LAST — after `scaffoldSync` and after every module
@@ -550,6 +609,7 @@ export async function scaffold(opts) {
                 versions,
                 markers,
                 ownership,
+                ...spokeSkip,
             })
             : (() => {
                 const sourceRoot = join(SITE_TEMPLATES_DIR, templateTreeDir(template.name));
@@ -565,6 +625,7 @@ export async function scaffold(opts) {
                     versions,
                     markers,
                     ownership,
+                    ...spokeSkip,
                 });
             })();
         installedLayout = installed.layout;
@@ -682,6 +743,17 @@ export async function scaffold(opts) {
                 writeFileSync(rosterPath, nextManifest);
         }
     }
+    // #7838 D8 — a commerce spoke's own checkout: two routes, its config and
+    // two return pages, once every layer has landed (so the spoke filter has
+    // already dropped the hub-checkout files) and before the manifest, whose
+    // code-route rows then record /checkout/thank-you and /checkout/unavailable.
+    const spokeCommerce = spoke !== undefined && result.modules.includes("commerce");
+    if (spokeCommerce) {
+        writeSpokeCheckoutSlice(result.targetDir, {
+            site: spokeCheckoutSite(projectName),
+            versions,
+        });
+    }
     // #6944 — the manifest records what this scaffold IS, once every layer has
     // landed: the effective module set, a row for every route on disk, and the
     // level only when the key path above derived one — `resolveModuleSet`, or
@@ -696,6 +768,9 @@ export async function scaffold(opts) {
                 roster,
                 modules: result.modules,
                 level,
+                topology: spoke !== undefined ? "spoke" : "hub",
+                ...(spoke?.signIn === "hub" ? { signIn: "hub" } : {}),
+                patternVersion: markers["CREATE_AILK_VERSION"] ?? "",
                 siteTemplatesDir: SITE_TEMPLATES_DIR,
                 templatesDir: TEMPLATES_DIR,
                 markers,
@@ -705,22 +780,105 @@ export async function scaffold(opts) {
     // #7536 D3 — the registry follows `apps/web/package.json`, which a module
     // bundle's `patches` (and the template layer) just finished editing.
     writePaidSections(result.targetDir);
+    // #7874 D9 — a spoke's rows again, now the module bundles and the template
+    // layer are in the scan; it appends only what those layers added. A
+    // commerce spoke also declares what the checkout package reads (#7838 D9).
+    if (spoke !== undefined) {
+        appendEnvRows(result.targetDir, {
+            topology: "spoke",
+            ...spokeEnvRowOptions(spokeCommerce),
+        });
+    }
     // #6107 D2 — after every layer landed, so nothing later overwrites it: a
     // served scaffold needs BETTER_AUTH_SECRET (#6044), and this is its value.
-    writeAuthSecretFile(result.targetDir);
+    // A spoke has no sign-in (#7426 D4), so it gets its hub's origin instead
+    // (D2) — never the spoke key, which the hub issues.
+    // #7894 D11 — a spoke signing in through its hub also gets the hub's web
+    // origin and its own session secret; never the client secret.
+    if (spoke !== undefined)
+        writeHubOriginEnv(result.targetDir, spoke.hubOrigin);
+    else
+        writeAuthSecretFile(result.targetDir);
+    if (spoke?.hubSignInOrigin !== undefined) {
+        writeHubSignInEnv(result.targetDir, spoke.hubSignInOrigin);
+    }
+    // #7876 D9 — a spoke carrying the flow stepper says what its `flows/` is
+    // and how its rollout seeds it. A hub, and a spoke without flows, get none.
+    if (spoke !== undefined && modules.includes("signal-collectors")) {
+        writeSpokeFlowsReadme(result.targetDir);
+    }
     // #6683 D9 — persisted only after every layer landed, and only when the
-    // caller passed `license`: a scaffold without it writes nothing new.
+    // caller passed `license`: a scaffold without it writes nothing new. A
+    // spoke has no apps/api, so it keeps the key in ailk.key alone (#7426 D6).
     if (opts.license !== undefined) {
-        writeLicenseKeyFiles(result.targetDir, opts.license);
+        writeLicenseKeyFiles(result.targetDir, opts.license, {
+            apiEnv: spoke === undefined,
+        });
     }
     // #6754 D4/D5 — the resolved starter, so the CLI names what it built.
+    const withDropped = {
+        ...result,
+        ...(dropped.length > 0 ? { droppedModules: dropped } : {}),
+        ...(spoke !== undefined ? { hubOrigin: spoke.hubOrigin } : {}),
+        ...(spoke?.hubSignInOrigin !== undefined
+            ? { hubSignInOrigin: spoke.hubSignInOrigin }
+            : {}),
+    };
     if (template !== undefined && resolvedDesign !== undefined) {
         return {
-            ...result,
+            ...withDropped,
             starter: { template: template.name, shape: template.shape, design: resolvedDesign.recorded },
         };
     }
-    return result;
+    return withDropped;
+}
+/**
+ * A spoke's resolved inputs (#7426 D1-D3/D7), or undefined for a hub. Every
+ * refusal is a `TemplateError` thrown before anything is fetched or written.
+ */
+function resolveSpoke(opts, template) {
+    if (opts.topology !== "spoke") {
+        const spokeOnly = [
+            opts.hubUrl !== undefined ? "hubUrl" : undefined,
+            opts.mcp !== undefined ? "mcp" : undefined,
+            opts.hubSignInUrl !== undefined ? "hubSignInUrl" : undefined,
+        ].filter((f) => f !== undefined);
+        if (spokeOnly.length > 0) {
+            throw new TemplateError(`${spokeOnly.join(" and ")} only apply to a spoke — pass topology: "spoke"`);
+        }
+        return undefined;
+    }
+    if (template === undefined) {
+        throw new TemplateError("a spoke needs a starter — pass --shape <shape> or --template <name>: the site manifest is where the topology is recorded");
+    }
+    let hubOrigin;
+    let hubSignInOrigin;
+    try {
+        hubOrigin = normalizeHubUrl(opts.hubUrl ?? process.env["AILK_API_URL"]);
+        if (opts.hubSignInUrl !== undefined) {
+            hubSignInOrigin = normalizeHubSignInUrl(opts.hubSignInUrl);
+        }
+    }
+    catch (err) {
+        if (err instanceof TopologyError)
+            throw new TemplateError(err.message);
+        throw err;
+    }
+    for (const name of normalizeModules([...(opts.modules ?? []), ...template.requires])) {
+        const refusal = spokeModuleRefusal(name);
+        if (refusal !== undefined) {
+            throw new TemplateError(template.requires.includes(name) && !(opts.modules ?? []).includes(name)
+                ? `template "${template.name}" requires ${refusal}`
+                : refusal);
+        }
+    }
+    return {
+        mcp: opts.mcp !== false,
+        hubOrigin,
+        ...(hubSignInOrigin !== undefined
+            ? { signIn: "hub", hubSignInOrigin }
+            : {}),
+    };
 }
 /**
  * The per-row install of the two SHARED seed layers (#6646 D1, disposition
@@ -842,7 +1000,12 @@ export function syncArchitectureSync(opts) {
         throw new Error(`not a scaffolded repo: no architecture.yaml at ${targetAbs}. Run \`create-ailk <target-dir>\` to scaffold first.`);
     }
     const enabledSurfaces = resolveSurfaces(opts.modules, opts.surfaces ?? []);
-    writeFileSync(archPath, deriveArchitecture(opts.modules, enabledSurfaces));
+    // #7426 D13 — a spoke stays a spoke: its topology is read from its
+    // manifest, and `mcp` from whether it still carries apps/mcp.
+    const topology = readSiteTopology(targetAbs);
+    writeFileSync(archPath, deriveArchitecture(opts.modules, enabledSurfaces, topology === "spoke"
+        ? { topology, mcp: existsSync(join(targetAbs, "apps", "mcp")) }
+        : {}));
     return {
         targetDir: targetAbs,
         surfaces: enabledSurfaces,
@@ -960,6 +1123,13 @@ export async function addModule(opts) {
     if (!existsSync(join(targetAbs, "architecture.yaml"))) {
         throw new Error(`not a scaffolded repo: no architecture.yaml at ${targetAbs}. Run \`create-ailk <target-dir>\` to scaffold first.`);
     }
+    // #7426 D13 — a spoke refuses a module it does not admit before any key
+    // read or network call (`applyModuleToScaffold` refuses it again).
+    if (addModuleSiteTopology(targetAbs) === "spoke") {
+        const refusal = spokeModuleRefusal(opts.moduleName);
+        if (refusal !== undefined)
+            throw new AddModuleRefusedError(refusal);
+    }
     const { paid } = classifyModules([opts.moduleName]);
     if (paid.length === 0) {
         throw new AddModuleRefusedError(`"${opts.moduleName}" ships with every scaffold — there is no module bundle to add`);

package/dist/seed-flows.d.ts

@@ -0,0 +1,65 @@
+/** The environment variable the spoke key is read from — and nowhere else. */
+export declare const SPOKE_KEY_ENV_VAR = "AILK_SPOKE_KEY";
+/** A refusal the CLI exits 2 on, thrown before any request is sent. */
+export declare class SeedFlowsRefusedError extends Error {
+    readonly exitCode = 2;
+    constructor(message: string);
+}
+export interface SeedFlowsOptions {
+    /** The spoke site. */
+    targetDir: string;
+    /** `--hub-url`. */
+    hubUrl?: string | undefined;
+    /** `--dry-run` — read and check the files, send nothing, read no key. */
+    dryRun?: boolean;
+    /** Injectable for tests; defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /** Injectable for tests; defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Each report line as it happens; defaults to nothing. */
+    onLine?: (line: string) => void;
+}
+/** Where the hub origin came from. */
+export type HubSource = "--hub-url" | "AILK_API_URL" | "apps/web/.env.local";
+export type SeedFlowOutcome = {
+    slug: string;
+    ok: true;
+    result: string;
+    status: string;
+} | {
+    slug: string;
+    ok: false;
+    failure: string;
+} | {
+    slug: string;
+    ok: "dry-run";
+};
+export interface SeedFlowsResult {
+    /** The hub origin, when one resolved (a dry run may have none). */
+    hub?: {
+        origin: string;
+        source: HubSource;
+    };
+    /** Set when there were no declared flows to send. */
+    empty?: string;
+    flows: SeedFlowOutcome[];
+    /** 0 every flow answered 200 (or a dry run); 1 any failed. */
+    exitCode: 0 | 1;
+}
+/** The whole report, one line per row — what `seedFlows` printed as it went. */
+export declare function formatSeedFlowsReport(result: SeedFlowsResult): string;
+export declare function seedFlows(opts: SeedFlowsOptions): Promise<SeedFlowsResult>;
+export declare const SPOKE_FLOWS_README = "# flows/\n\nEach file here is one **declared flow**: `flows/<slug>.json` holds one flow\nconfig, exactly as the hub stores it. This repo owns these configs \u2014 the hub\nruns them for this site.\n\n## What a spoke may declare\n\nA spoke key may seed only what this site's own flow pages show:\n`slug`, `defaultLocale`, `steps`, `thankYou` and `flags`. Anything the\nhub acts on outside these pages \u2014 emails, deliverables, pricing, registers,\nlistings \u2014 is refused (`field_not_seedable`). A flow that needs one of those\nis authored in the hub's Admin instead.\n\nThe file name must be the config's `slug` plus `.json`.\n\n## Seeding them into the hub\n\nRun this as part of each rollout, from the site's root, with the spoke key\nyour hub issued set as `AILK_SPOKE_KEY` in the environment (a shell or CI\nsecret \u2014 never a file in this repo):\n\n    npx create-ailk seed-flows .\n\nThe hub origin comes from `--hub-url`, else `AILK_API_URL`, else the\n`AILK_API_URL=` line of `apps/web/.env.local`. The key is read from the\nenvironment only. Each flow answers `created`, `updated` or `unchanged`,\nso running it again is safe. `--dry-run` checks the files and sends nothing.\n\nThe hub's operator must first turn seeding on (`AILK_SPOKE_FLOW_SEED=true`\non the hub). Until it is on and this command has run, links to these flows\n(`/flows/<slug>`) reach no flow.\n\n## Who owns what\n\nThe next seed that differs overwrites the hub's copy of a flow's config, so\nedit flows here, not in the Admin. A flow's status (live or draft) is the\nhub's: switching a seeded flow to draft in the Admin keeps it draft through\nevery later seed. Removing a file here does not delete the hub's flow. If\nthe Admin adds a block only it can author (an email, a deliverable, an\noffer), the hub refuses the next seed of that flow (`slug_owned`) rather\nthan delete the block.\n";
+/**
+ * Write `SPOKE_FLOWS_README` to `<targetDir>/flows/README.md` unless that
+ * file exists. Returns whether it wrote.
+ */
+export declare function writeSpokeFlowsReadme(targetDir: string): boolean;
+export interface SeedFlowsArgs {
+    target: string | undefined;
+    hubUrl: string | undefined;
+    dryRun: boolean;
+    help: boolean;
+}
+export declare const SEED_FLOWS_HELP = "create-ailk seed-flows \u2014 send a spoke's declared flows to its hub.\n\nUsage:\n  AILK_SPOKE_KEY=<key> create-ailk seed-flows [<dir>] [--hub-url <origin>] [--dry-run]\n\nArguments:\n  <dir>                The spoke site. Defaults to the current dir.\n\nOptions:\n  --hub-url <origin>   The hub's origin. Else AILK_API_URL, else the\n                       AILK_API_URL= line of apps/web/.env.local. https:\n                       only (http: on localhost or 127.0.0.1).\n  --dry-run            Check every flows/*.json and print what would be sent.\n                       Sends nothing and reads no key.\n  -h, --help           Show this help.\n\nEach flows/<slug>.json is sent to PUT <hub>/v1/flows/<slug>/definition with\nthe spoke key, which is read from AILK_SPOKE_KEY only. The hub must have\nAILK_SPOKE_FLOW_SEED=true. Exit 0 when every flow was accepted, 1 when any\nfailed, 2 on a refusal (nothing is sent).\n";
+export declare function parseSeedFlowsArgs(argv: string[]): SeedFlowsArgs;