create-ailk 0.15.0 → 0.17.0

package/dist/topology.js

@@ -16,13 +16,17 @@
  *   - the two generated seam files (D5) — the only place hub and spoke code
  *     differ, rendered here for either topology;
  *   - the root-file transforms (D6), the hard floors (D9), the module
- *     admission (D7), the manifest reader (D10) and the hub origin (D2).
+ *     admission (D7), the manifest reader (D10) and the hub origin (D2);
+ *   - the sign-in-through-the-hub mode (`signIn: "hub"`, #7894): its seeds,
+ *     its renders of the web and `(authed)` gate seams, its env and floors.
  *
- * Spec: docs/specs/7426-spoke-topology-option-spec.md.
+ * Specs: docs/specs/7426-spoke-topology-option-spec.md,
+ * docs/specs/7894-the-hub-signs-in-its-spec.md (D1, D8, D9, D11).
  *
  * Pure module: no `import.meta.url`, so jest imports it directly. The
  * package's own `templates/` dir is supplied by the caller.
  */
+import { randomBytes } from "node:crypto";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { ENV_LOCAL_IGNORE_LINES } from "./lib/auth-secret-file.js";
@@ -44,10 +48,17 @@ export class TopologyError extends Error {
 export const SPOKE_REMOVED_ROOTS = ["apps/api", "database"];
 /** The root `--without-mcp` removes. */
 export const SPOKE_MCP_ROOT = "apps/mcp";
+/** Commerce's apps/web files that reach the hub's own checkout (spoke-intake Rule 3, #7838). */
+export const SPOKE_HUB_CHECKOUT_SEEDS = [
+    "apps/web/app/[locale]/flows/[slug]/checkout.actions.ts",
+    "apps/web/app/[locale]/flows/[slug]/results",
+    "apps/web/app/[locale]/dev/purchase",
+];
 /**
- * The sign-in and database files a spoke does not carry — files and
- * directories, scaffold-relative. Every other file that imports one of them
- * goes with it (`spokeExclusions`).
+ * The files a spoke does not carry — files and directories, scaffold-relative:
+ * the sign-in and database seeds, then the commerce files that call the hub's
+ * own checkout (`SPOKE_HUB_CHECKOUT_SEEDS`; a spoke keeps its own, #7838).
+ * Every other file that imports one of them goes with it (`spokeExclusions`).
  */
 export const SPOKE_REMOVAL_SEEDS = [
     "apps/web/auth.ts",
@@ -59,13 +70,63 @@ export const SPOKE_REMOVAL_SEEDS = [
     "apps/mcp/src/lib/prisma.ts",
     "apps/mcp/src/lib/public-workspace.ts",
     "apps/mcp/src/lib/license-key-store.ts",
+    ...SPOKE_HUB_CHECKOUT_SEEDS,
+];
+/**
+ * Module paths a spoke drops even when it carries the module (#7876 D8,
+ * clarified 2026-10-09). `signal-collectors`' report reader links a
+ * grant-gated report's bytes on the hub from `NEXT_PUBLIC_AILK_API_URL`,
+ * which a spoke refuses (#7874: its hub origin is server-only), and a
+ * deliverable is hub-side anyway — so a spoke carries neither the
+ * `/reports` routes nor the report seeds that would have no route.
+ */
+export const SPOKE_EXCLUDED_MODULE_PATHS = [
+    "apps/web/app/[locale]/reports",
+    "content/en/ReportPage",
+    "content/en/ReportsList",
+];
+/**
+ * The `(authed)` seeds of the sign-in-through-the-hub mode (#7894 D9): the
+ * whole `(authed)` group goes in the default mode; in the hub mode its account
+ * area, layout and gate seam stay, and only these go — the operator surfaces,
+ * the Better Auth gate and the suites that mock `auth.ts` by path.
+ */
+export const HUB_MODE_AUTHED_SEEDS = [
+    "apps/web/app/[locale]/(authed)/__tests__",
+    "apps/web/app/[locale]/(authed)/account/__tests__",
+    "apps/web/app/[locale]/(authed)/admin",
+    "apps/web/app/[locale]/(authed)/appointments",
+    "apps/web/app/[locale]/(authed)/edit",
+    "apps/web/app/[locale]/(authed)/leads",
+    "apps/web/app/[locale]/(authed)/waitlist",
+    "apps/web/app/[locale]/(authed)/sign-in-gate.tsx",
 ];
-/** The two generated seam files (D5). A seam is rewritten, never removed. */
+/** The default mode's one `(authed)` seed, which the hub mode replaces. */
+const AUTHED_SEED = "apps/web/app/[locale]/(authed)";
+/** The generated seam files (D5; #7874 D12). A seam is rewritten, never removed. */
 export const WEB_SEAM_PATH = "apps/web/lib/topology.generated.ts";
 export const MCP_SEAM_PATH = "apps/mcp/src/lib/topology.generated.ts";
+/** The browser API origin seam (#7874 D12): a spoke's render reads no env. */
+export const API_ORIGIN_SEAM_PATH = "apps/web/lib/api-origin.generated.ts";
+/**
+ * The `(authed)` layout's signed-out gate (#7894 D8). Under the `(authed)`
+ * seed, so a default-mode spoke drops it with its group and never renders it.
+ */
+export const AUTHED_GATE_SEAM_PATH = "apps/web/app/[locale]/(authed)/signed-out-gate.generated.tsx";
 export const SPOKE_SEAM_FILES = [
     WEB_SEAM_PATH,
     MCP_SEAM_PATH,
+    API_ORIGIN_SEAM_PATH,
+    AUTHED_GATE_SEAM_PATH,
+];
+/**
+ * Template files only a spoke carries (#7874 D11): the declared-env check.
+ * `scaffoldSync` excludes them from a hub's copy (`copyTemplate`'s
+ * `excludePaths` matches an exact file path).
+ */
+export const SPOKE_ONLY_FILES = [
+    "tools/declared-env.ts",
+    "tools/check-declared-env.ts",
 ];
 /**
  * The closure's allow-list: a file `spokeExclusions` removes must sit under
@@ -74,6 +135,12 @@ export const SPOKE_SEAM_FILES = [
  * file — and `spokeExclusions` throws naming it rather than cut it silently.
  */
 export const SPOKE_REMOVABLE_PREFIXES = SPOKE_REMOVAL_SEEDS;
+/** The seeds for a sign-in mode, before the mcp filter. */
+function modeSeeds(signIn) {
+    return signIn === "hub"
+        ? SPOKE_REMOVAL_SEEDS.flatMap((seed) => seed === AUTHED_SEED ? [...HUB_MODE_AUTHED_SEEDS] : [seed])
+        : [...SPOKE_REMOVAL_SEEDS];
+}
 function toPosix(path) {
     return path.split("\\").join("/").replace(/^\.\//, "");
 }
@@ -88,15 +155,24 @@ export function spokeRemovedRoots(opts) {
         ? [...SPOKE_REMOVED_ROOTS]
         : [...SPOKE_REMOVED_ROOTS, SPOKE_MCP_ROOT];
 }
-/** The seeds that apply — an mcp seed is moot when `apps/mcp` itself goes. */
+/**
+ * The seeds that apply — an mcp seed is moot when `apps/mcp` itself goes; in
+ * the hub sign-in mode the `(authed)` seed is replaced by eight (#7894 D9).
+ */
 function spokeSeeds(opts) {
-    return SPOKE_REMOVAL_SEEDS.filter((seed) => opts.mcp || !underPrefix(seed, SPOKE_MCP_ROOT));
+    return modeSeeds(opts.signIn).filter((seed) => opts.mcp || !underPrefix(seed, SPOKE_MCP_ROOT));
 }
-/** Whether a closure member is one the registry allows a spoke to drop. */
-export function isRemovableClosureMember(path) {
+/**
+ * Whether a closure member is one the registry allows a spoke to drop: under
+ * a seed of THAT sign-in mode, or a test. In the hub mode a surviving account
+ * file that imports `auth.ts` is therefore not removable, and
+ * `spokeExclusions` throws naming it (#7894 D9).
+ */
+export function isRemovableClosureMember(path, opts = {}) {
     const p = toPosix(path);
+    const prefixes = opts.signIn === "hub" ? modeSeeds("hub") : SPOKE_REMOVABLE_PREFIXES;
     return (p.split("/").includes("__tests__") ||
-        SPOKE_REMOVABLE_PREFIXES.some((prefix) => underPrefix(p, prefix)));
+        prefixes.some((prefix) => underPrefix(p, prefix)));
 }
 /**
  * Every path a spoke does not carry, computed over the built `templates/`
@@ -146,7 +222,7 @@ export function spokeExclusions(templatesDir, opts) {
             break;
     }
     const outside = [...closed]
-        .filter((file) => !isRemovableClosureMember(file))
+        .filter((file) => !isRemovableClosureMember(file, opts))
         .sort();
     if (outside.length > 0) {
         throw new TopologyError(`a spoke cannot drop ${outside.join(", ")}: ${outside.length === 1 ? "it imports" : "each imports"} a sign-in or database file, and ${outside.length === 1 ? "it is" : "they are"} not a sign-in path or a test. Move the import behind the generated seam (${WEB_SEAM_PATH} / ${MCP_SEAM_PATH}) rather than widening SPOKE_REMOVABLE_PREFIXES.`);
@@ -170,15 +246,30 @@ export function isSpokeExcluded(path, opts) {
         ...spokeRemovedRoots(opts),
         ...spokeSeeds(opts),
     ];
-    return prefixes.some((prefix) => underPrefix(p, prefix));
+    return [...prefixes, ...SPOKE_EXCLUDED_MODULE_PATHS].some((prefix) => underPrefix(p, prefix));
+}
+/** A module flow file a hub installs under `database/` (#7876 D10). */
+const DATABASE_FLOW_FILE = /^database\/flows\/([^/]+)\.flow\.json$/;
+/**
+ * Where a module bundle's `installMap` destination lands on a spoke (#7876
+ * D10): `database/flows/<name>.flow.json` becomes `flows/<name>.json` — a
+ * declared flow `create-ailk seed-flows` sends to the hub — and every other
+ * destination is returned unchanged. Applied before the spoke filter, so a
+ * remapped flow survives it while the rest of `database/` is dropped. A hub
+ * install passes no remap.
+ */
+export function spokeDestination(destination) {
+    const match = DATABASE_FLOW_FILE.exec(toPosix(destination));
+    return match ? `flows/${match[1]}.json` : destination;
 }
 // ── D5 — the generated seam files ───────────────────────────────────────────
 const WEB_SEAM_HEADER = `// topology.generated.ts — how this site reads a session and registers its stores.
 //
 // GENERATED by create-ailk for this site's topology (#7426). Do not edit:
-// every scaffold rewrites it. A hub reads the session through Better Auth;
-// a spoke (\`--topology spoke\`) has no sign-in and no database of its own,
-// so its render reads no session and imports nothing.`;
+// every scaffold rewrites it. A hub reads the session through Better Auth.
+// A spoke (\`--topology spoke\`) has no database of its own: by default it
+// has no sign-in, so its render reads no session and imports nothing; with
+// \`--hub-sign-in\` (#7894) it reads the sealed hub-session cookie.`;
 const MCP_SEAM_HEADER = `// topology.generated.ts — how this MCP server resolves its workspace store.
 //
 // GENERATED by create-ailk for this site's topology (#7426). Do not edit:
@@ -186,20 +277,39 @@ const MCP_SEAM_HEADER = `// topology.generated.ts — how this MCP server resolv
 // database; a spoke (\`--topology spoke\`) has none, so its content tools
 // read the spoke's own MDX and its writes go to the hub at AILK_API_URL.`;
 const SITE_SESSION_TYPE = `export type SiteSession = {
-  user: { name?: string | null; email: string };
+  user: {
+    name?: string | null;
+    email: string;
+    emailVerified: boolean;
+    createdAt?: Date | string | null;
+  };
 } | null;`;
-/** `apps/web/lib/topology.generated.ts` for `topology` (D5). */
-export function renderWebSeam(topology) {
+/** The sign-in exports every web seam render carries (#7894 D8). */
+function signInExports(values) {
+    const literal = (value) => value === null ? "null" : JSON.stringify(value);
+    return `export const SIGN_IN_ENABLED: boolean = ${values.enabled};
+export const SIGN_IN_PROVIDER: "site" | "hub" | "none" = ${JSON.stringify(values.provider)};
+export const SIGN_IN_PATH: string | null = ${literal(values.signInPath)};
+export const SIGN_UP_PATH: string | null = ${literal(values.signUpPath)};
+export const SIGN_OUT_ENDPOINT: string | null = ${literal(values.signOutEndpoint)};`;
+}
+/**
+ * `apps/web/lib/topology.generated.ts` for `topology` (D5) and, on a spoke,
+ * its sign-in mode (#7894 D8). The hub render loads `auth.ts` only when a
+ * session is read, so a module that imports this seam for a constant never
+ * loads Better Auth.
+ */
+export function renderWebSeam(topology, signIn = "off") {
     if (topology === "hub") {
         return `${WEB_SEAM_HEADER}
-import { auth } from "../auth";
 
 export const TOPOLOGY: "hub" | "spoke" = "hub";
-export const SIGN_IN_ENABLED: boolean = true;
+${signInExports({ enabled: true, provider: "site", signInPath: "/sign-in", signUpPath: "/sign-up", signOutEndpoint: null })}
 
 ${SITE_SESSION_TYPE}
 
 export async function readSession(headers: Headers): Promise<SiteSession> {
+  const { auth } = await import("../auth");
   return auth.api.getSession({ headers });
 }
 
@@ -207,12 +317,30 @@ export async function registerSiteStores(): Promise<void> {
   const { registerLicenseKeyStore } = await import("./license-key-store");
   await registerLicenseKeyStore();
 }
+`;
+    }
+    if (signIn === "hub") {
+        return `${WEB_SEAM_HEADER}
+import { readHubSession } from "./hub-session/session";
+
+export const TOPOLOGY: "hub" | "spoke" = "spoke";
+${signInExports({ enabled: true, provider: "hub", signInPath: "/account", signUpPath: null, signOutEndpoint: "/api/hub-session/sign-out" })}
+
+${SITE_SESSION_TYPE}
+
+export function readSession(headers: Headers): Promise<SiteSession> {
+  return readHubSession(headers);
+}
+
+export function registerSiteStores(): Promise<void> {
+  return Promise.resolve();
+}
 `;
     }
     return `${WEB_SEAM_HEADER}
 
 export const TOPOLOGY: "hub" | "spoke" = "spoke";
-export const SIGN_IN_ENABLED: boolean = false;
+${signInExports({ enabled: false, provider: "none", signInPath: null, signUpPath: null, signOutEndpoint: null })}
 
 ${SITE_SESSION_TYPE}
 
@@ -226,6 +354,135 @@ export function registerSiteStores(): Promise<void> {
 }
 `;
 }
+const AUTHED_GATE_SEAM_HEADER = `// signed-out-gate.generated.tsx — what the (authed) group shows a signed-out visitor.
+//
+// GENERATED by create-ailk for this site's topology and sign-in mode (#7894).
+// Do not edit: every scaffold rewrites it. A hub renders its own sign-in —
+// the operator gate, or the account area's member gate; a spoke that signs in
+// through its hub (\`--hub-sign-in\`) renders the hub-session gate.`;
+/**
+ * The packages the gate seam imports. Interpolated, not written inline, for
+ * the reason `CONTENT_ADAPTERS_PACKAGE` below is.
+ */
+const UI_PACKAGE = "@working-theory/ui";
+const WEB_I18N_PACKAGE = "@working-theory/web-i18n";
+const NEXT_INTL_SERVER = "next-intl/server";
+const REACT_PACKAGE = "react";
+const AUTHED_GATE_PROPS = `export interface SignedOutGateProps {
+  locale: string;
+  /** The incoming request's headers (\`x-pathname\` names the requested page). */
+  requestHeaders: Headers;
+}`;
+/**
+ * `apps/web/app/[locale]/(authed)/signed-out-gate.generated.tsx` (#7894 D8).
+ * The hub render is the `(authed)` layout's no-session branch, moved; the
+ * `signIn: "hub"` render imports only the hub-session gate. A default-mode
+ * spoke carries no `(authed)` group, so it has no render.
+ * @throws TopologyError for a spoke in the default mode.
+ */
+export function renderAuthedGateSeam(topology, signIn = "off") {
+    if (topology === "hub") {
+        return `${AUTHED_GATE_SEAM_HEADER}
+import { localeHref } from "${UI_PACKAGE}";
+import { Button, Heading, Link, Text } from "${UI_PACKAGE}/primitives";
+import type { AuthPanelProvider } from "${UI_PACKAGE}/sections";
+import { readLocales } from "${WEB_I18N_PACKAGE}";
+import { getTranslations } from "${NEXT_INTL_SERVER}";
+import type { ReactElement } from "${REACT_PACKAGE}";
+
+import { resolveSignInCardText } from "../(auth)/sign-in/sign-in-text";
+import { getActiveProviderIds } from "../../../lib/auth-env";
+import { isAccountPath } from "../../../lib/auth-routes";
+
+import { SignInGate } from "./sign-in-gate";
+
+const SUPPORTED_PROVIDERS: readonly AuthPanelProvider[] = ["google", "github"];
+
+${AUTHED_GATE_PROPS}
+
+export async function SignedOutGate({
+  locale,
+  requestHeaders,
+}: SignedOutGateProps): Promise<ReactElement> {
+  // No \`x-pathname\`, no locale read: a render outside the middleware keeps
+  // the operator gate without touching the locale config.
+  const pathname = requestHeaders.get("x-pathname");
+  const isAccount =
+    pathname !== null && isAccountPath(pathname, readLocales());
+  const t = await getTranslations({
+    locale,
+    namespace: isAccount ? "account.gate" : "waitlistDashboard.gate",
+  });
+  const active = getActiveProviderIds();
+  const emailLink = active.includes("magic-link")
+    ? { text: await resolveSignInCardText(locale) }
+    : undefined;
+  const providers = active.filter((id): id is AuthPanelProvider =>
+    (SUPPORTED_PROVIDERS as readonly string[]).includes(id),
+  );
+  const signInPath = localeHref(locale, "/sign-in");
+
+  if (isAccount && providers.length === 0 && !emailLink) {
+    return (
+      <div
+        className="flex min-h-screen flex-col items-center justify-center gap-4 py-section text-center"
+        data-testid="account-sign-in-gate"
+      >
+        <Heading level={1} visual={4}>
+          {t("emptyHeadline")}
+        </Heading>
+        <Text variant="body-sm" tone="muted" className="max-w-xs">
+          {t("emptyDescription")}
+        </Text>
+        {/* With no sign-in method on, /sign-in has nothing for a member
+            either, so the one action goes back to the site. Outline
+            action, 44px on a phone and 36px from md up. */}
+        <Button asChild variant="secondary" className="max-md:min-h-11">
+          <Link
+            href={localeHref(locale, "/")}
+            variant="bare"
+            data-testid="account-sign-in-gate-home"
+          >
+            {t("homeLink")}
+          </Link>
+        </Button>
+      </div>
+    );
+  }
+
+  return (
+    <SignInGate
+      labels={{
+        emptyHeadline: t("emptyHeadline"),
+        emptyDescription: t("emptyDescription"),
+        signInLinkLabel: t("signInLink"),
+      }}
+      signInPath={signInPath}
+      providers={providers}
+      {...(emailLink ? { emailLink } : {})}
+    />
+  );
+}
+`;
+    }
+    if (signIn !== "hub") {
+        throw new TopologyError(`${AUTHED_GATE_SEAM_PATH}: a spoke without --hub-sign-in carries no (authed) group, so it has no gate to render`);
+    }
+    return `${AUTHED_GATE_SEAM_HEADER}
+import type { ReactElement } from "${REACT_PACKAGE}";
+
+import { HubSignInGate } from "../../../lib/hub-session/sign-in-gate";
+
+${AUTHED_GATE_PROPS}
+
+export function SignedOutGate({
+  locale,
+  requestHeaders,
+}: SignedOutGateProps): Promise<ReactElement> {
+  return HubSignInGate({ locale, requestHeaders });
+}
+`;
+}
 /**
  * The package the spoke mcp seam takes its one type from. Interpolated, not
  * written inline: an inline specifier in this template would read as an
@@ -280,6 +537,30 @@ export function registerLicenseKeyStore(): Promise<void> {
 }
 `;
 }
+const API_ORIGIN_SEAM_HEADER = `// api-origin.generated.ts — the browser-facing API origin this site's server reads.
+//
+// GENERATED by create-ailk for this site's topology (#7874). Do not edit:
+// every scaffold rewrites it. A hub reads NEXT_PUBLIC_AILK_API_URL as a
+// fallback API origin; a spoke (\`--topology spoke\`) has no browser-facing
+// API origin — its hub origin is server-only (AILK_API_URL) — so its render
+// reads no environment variable.`;
+/** `apps/web/lib/api-origin.generated.ts` for `topology` (#7874 D12). */
+export function renderApiOriginSeam(topology) {
+    if (topology === "hub") {
+        return `${API_ORIGIN_SEAM_HEADER}
+
+export function browserApiOrigin(): string | undefined {
+  return process.env.NEXT_PUBLIC_AILK_API_URL;
+}
+`;
+    }
+    return `${API_ORIGIN_SEAM_HEADER}
+
+export function browserApiOrigin(): string | undefined {
+  return undefined;
+}
+`;
+}
 // ── D6 — the root-file transforms ───────────────────────────────────────────
 /**
  * `text` with every line `drop` matches removed, then the dangling comma a
@@ -315,6 +596,66 @@ export function transformRootPackageJson(text) {
     const scriptLine = /^\s*"db:[^"]*"\s*:/;
     return dropLines(text, (line) => scriptLine.test(line), "package.json", true);
 }
+/** The spoke's declared-env script (#7874 D11) — named apart from the monorepo's `env:check`. */
+export const ENV_DECLARED_SCRIPT = "env:declared";
+const ENV_DECLARED_COMMAND = "tsx tools/check-declared-env.ts";
+/**
+ * The spoke's root `package.json` with the declared-env check (#7874 D11):
+ * an `env:declared` script after `claude-md:check`, and `preflight` running
+ * it right after `claude-md:check`. Applied after `transformRootPackageJson`.
+ * @throws TopologyError when either anchor is missing.
+ */
+export function addEnvCheckScripts(text) {
+    const lines = text.split("\n");
+    const anchor = lines.findIndex((line) => /^\s*"claude-md:check"\s*:/.test(line));
+    if (anchor === -1) {
+        throw new TopologyError(`package.json: no "claude-md:check" script to add ${ENV_DECLARED_SCRIPT} after`);
+    }
+    const preflightAt = lines.findIndex((line) => /^\s*"preflight"\s*:/.test(line));
+    const step = "pnpm claude-md:check && ";
+    if (preflightAt === -1 || !(lines[preflightAt] ?? "").includes(step)) {
+        throw new TopologyError(`package.json: no "preflight" script running "${step.trim()}" to add ${ENV_DECLARED_SCRIPT} to`);
+    }
+    lines[preflightAt] = (lines[preflightAt] ?? "").replace(step, `${step}pnpm ${ENV_DECLARED_SCRIPT} && `);
+    const indent = /^\s*/.exec(lines[anchor] ?? "")?.[0] ?? "";
+    lines.splice(anchor + 1, 0, `${indent}${JSON.stringify(ENV_DECLARED_SCRIPT)}: ${JSON.stringify(ENV_DECLARED_COMMAND)},`);
+    const next = lines.join("\n");
+    try {
+        JSON.parse(next);
+    }
+    catch (err) {
+        throw new TopologyError(`package.json: adding ${ENV_DECLARED_SCRIPT} left it unparseable: ${err.message}`);
+    }
+    return next;
+}
+/**
+ * The spoke's `.github/workflows/ci.yml` (#7874 D11): a `pnpm env:declared`
+ * step after `pnpm claude-md:check`, and no `pnpm db:generate` step — a
+ * spoke has no `database/` and no `db:*` script, so that step would fail
+ * first (#7962). The comment block directly above the dropped step goes with
+ * it.
+ * @throws TopologyError when either anchor is missing.
+ */
+export function transformCiWorkflow(text) {
+    const lines = text.split("\n");
+    const dbAt = lines.findIndex((line) => /^\s*- run: pnpm db:generate\s*$/.test(line));
+    if (dbAt === -1) {
+        throw new TopologyError(`.github/workflows/ci.yml: no "- run: pnpm db:generate" step to remove`);
+    }
+    let start = dbAt;
+    while (start > 0 && /^\s*#/.test(lines[start - 1] ?? ""))
+        start--;
+    // Drop the blank line that separated the removed block from the step above.
+    const dropBlank = start > 0 && (lines[start - 1] ?? "").trim() === "" ? 1 : 0;
+    lines.splice(start - dropBlank, dbAt - start + 1 + dropBlank);
+    const anchor = lines.findIndex((line) => /^\s*- run: pnpm claude-md:check\s*$/.test(line));
+    if (anchor === -1) {
+        throw new TopologyError(`.github/workflows/ci.yml: no "- run: pnpm claude-md:check" step to add ${ENV_DECLARED_SCRIPT} after`);
+    }
+    const indent = /^\s*/.exec(lines[anchor] ?? "")?.[0] ?? "";
+    lines.splice(anchor + 1, 0, "", `${indent}# A process.env read with no project.yaml env_contract row — the same check \`pnpm preflight\` runs locally.`, `${indent}- run: pnpm ${ENV_DECLARED_SCRIPT}`);
+    return lines.join("\n");
+}
 /** The root `tsconfig.json` without a reference under a removed root. */
 export function transformRootTsconfig(text, opts) {
     const roots = spokeRemovedRoots(opts);
@@ -339,7 +680,8 @@ export function transformAppPackageJson(text, label, required) {
 /**
  * Apply every D6 root-file transform to the spoke at `targetDir` (after the
  * base copy, before any module or template layer), and write the spoke
- * render of each seam it carries (D5).
+ * render of each seam it carries (D5). Also the declared-env check's root
+ * script and CI step (#7874 D11), and the browser API origin seam (D12).
  * @throws TopologyError naming the file whose anchor is missing.
  */
 export function applySpokeTransforms(targetDir, opts) {
@@ -354,14 +696,21 @@ export function applySpokeTransforms(targetDir, opts) {
             writeFileSync(path, next);
     };
     edit("pnpm-workspace.yaml", transformWorkspaceYaml);
-    edit("package.json", transformRootPackageJson);
+    edit("package.json", (text) => addEnvCheckScripts(transformRootPackageJson(text)));
+    edit(".github/workflows/ci.yml", transformCiWorkflow);
     edit("tsconfig.json", (text) => transformRootTsconfig(text, opts));
     edit("apps/web/package.json", (text) => transformAppPackageJson(text, "apps/web/package.json", true));
     if (opts.mcp) {
         edit("apps/mcp/package.json", (text) => transformAppPackageJson(text, "apps/mcp/package.json", false));
     }
     edit("project.yaml", (text) => transformProjectYaml(text, opts));
-    writeFileSync(join(targetDir, WEB_SEAM_PATH), renderWebSeam("spoke"));
+    writeFileSync(join(targetDir, WEB_SEAM_PATH), renderWebSeam("spoke", opts.signIn));
+    // #7894 D8 — the gate seam lives in the `(authed)` group only the hub
+    // sign-in mode keeps.
+    if (opts.signIn === "hub") {
+        writeFileSync(join(targetDir, AUTHED_GATE_SEAM_PATH), renderAuthedGateSeam("spoke", "hub"));
+    }
+    writeFileSync(join(targetDir, API_ORIGIN_SEAM_PATH), renderApiOriginSeam("spoke"));
     if (opts.mcp) {
         writeFileSync(join(targetDir, MCP_SEAM_PATH), renderMcpSeam("spoke"));
     }
@@ -383,16 +732,24 @@ const NEXT_ENV_FILES = [
  * the hub issues those.
  */
 export function writeHubOriginEnv(targetDir, origin) {
+    writeWebEnv(targetDir, HUB_ORIGIN_ENV_VAR, () => origin);
+}
+/**
+ * `<name>=<value()>` into the spoke's `apps/web/.env.local`, unless any env
+ * file Next loads for `apps/web` already assigns `name` (`value` is then never
+ * called); and `.env.local` gitignored either way.
+ */
+function writeWebEnv(targetDir, name, value) {
     const webDir = join(targetDir, "apps", "web");
-    const assigned = new RegExp(`^\\s*(?:export\\s+)?${HUB_ORIGIN_ENV_VAR}\\s*=\\s*\\S`, "m");
-    const already = NEXT_ENV_FILES.some((name) => {
-        const path = join(webDir, name);
+    const assigned = new RegExp(`^\\s*(?:export\\s+)?${name}\\s*=\\s*\\S`, "m");
+    const already = NEXT_ENV_FILES.some((file) => {
+        const path = join(webDir, file);
         return existsSync(path) && assigned.test(readFileSync(path, "utf8"));
     });
     if (!already) {
         const file = join(webDir, ".env.local");
         const existing = existsSync(file) ? readFileSync(file, "utf8") : "";
-        writeOwnerOnly(file, appendLine(existing, `${HUB_ORIGIN_ENV_VAR}=${origin}`));
+        writeOwnerOnly(file, appendLine(existing, `${name}=${value()}`));
     }
     const ignorePath = join(targetDir, ".gitignore");
     const ignore = existsSync(ignorePath) ? readFileSync(ignorePath, "utf8") : "";
@@ -402,6 +759,21 @@ export function writeHubOriginEnv(targetDir, origin) {
     if (!covered)
         writeFileSync(ignorePath, appendLine(ignore, ".env.local"));
 }
+/** The env var naming the hub's web origin a hub-mode spoke signs in at (#7894 D11). */
+export const HUB_SIGN_IN_URL_ENV_VAR = "AILK_HUB_SIGN_IN_URL";
+/** The env var holding a hub-mode spoke's own cookie key material (#7894 D7, D11). */
+export const HUB_SESSION_SECRET_ENV_VAR = "AILK_HUB_SESSION_SECRET";
+/**
+ * Write a hub-mode spoke's sign-in env (#7894 D11) to `apps/web/.env.local`,
+ * under `writeHubOriginEnv`'s never-clobber rule: the hub's web origin, and a
+ * fresh session secret (32 random bytes, 43 base64url characters). Never the
+ * client id or client secret — the hub issues those (`spokes sign-in-client`)
+ * — and never `BETTER_AUTH_SECRET` or a database URL.
+ */
+export function writeHubSignInEnv(targetDir, origin) {
+    writeWebEnv(targetDir, HUB_SIGN_IN_URL_ENV_VAR, () => origin);
+    writeWebEnv(targetDir, HUB_SESSION_SECRET_ENV_VAR, () => randomBytes(32).toString("base64url"));
+}
 // ── D9 — the spoke's hard floors ────────────────────────────────────────────
 /** The `hard_floors:` block a spoke's `project.yaml` carries (D9). */
 export function renderSpokeHardFloors(opts) {
@@ -410,19 +782,29 @@ export function renderSpokeHardFloors(opts) {
         "  # Surfaces that always require human review on merge, regardless of",
         "  # automation level. This site is a SPOKE (create-ailk --topology spoke):",
         "  # it has no apps/api, no database and no sign-in of its own. Pricing, the",
-        "  # Stripe webhook route and the sign-in paths are floored so their arrival",
-        "  # here is a human merge.",
+        "  # Stripe webhook route, the checkout route, its price map and its e2e",
+        "  # workflow, and the sign-in paths are floored so their arrival here is a",
+        "  # human merge.",
         "  - kind: pricing",
         "  - kind: stripe_live_mode",
         "  - paths:",
         '      - "apps/web/app/api/webhooks/stripe/**"',
         "    reason: Stripe webhook route — payment state requires human review",
         "  - paths:",
+        '      - "apps/web/app/api/checkout/**"',
+        '      - "apps/web/lib/checkout-config.ts"',
+        '      - ".github/workflows/checkout-e2e.yml"',
+        "    reason: Spoke checkout — the buy route, the price map and the checkout e2e workflow require human review",
+        "  - paths:",
         '      - "apps/web/auth.ts"',
         '      - "apps/web/app/api/auth/**"',
         '      - "apps/web/app/[locale]/(auth)/**"',
         '      - "apps/web/app/[locale]/(authed)/**"',
-        "    reason: sign-in paths — absent on a spoke; their return requires human review",
+        '      - "apps/web/lib/hub-session/**"',
+        '      - "apps/web/app/api/hub-session/**"',
+        opts.signIn === "hub"
+            ? "    reason: sign-in paths — this spoke signs in through its hub; every change requires human review"
+            : "    reason: sign-in paths — absent on a spoke; their return requires human review",
     ];
     if (opts.mcp) {
         lines.push("  - paths:", '      - "apps/mcp/src/tools/**"', "    reason: MCP tool surface — signatures require human review");
@@ -447,12 +829,9 @@ export function transformProjectYaml(text, opts) {
 }
 // ── D7 — the module admission ───────────────────────────────────────────────
 /** Why a module is not admitted on a spoke, and where its admission lives. */
-const SPOKE_REFUSAL_REASONS = {
-    scheduling: "its spoke admission lands with #7872",
-    commerce: "its spoke admission lands with #7838",
+export const SPOKE_REFUSAL_REASONS = {
     "multi-tenant": "it needs a database or the Admin app",
     workspace: "it needs a database or the Admin app",
-    "signal-collectors": "it needs a database or the Admin app",
 };
 /** The modules a spoke may carry — every slice declaring `spoke: true`. */
 export function spokeModules() {
@@ -493,6 +872,26 @@ export function readSiteTopology(targetDir) {
     }
     throw new TopologyError(`${SITE_MANIFEST_PATH} records an unknown topology ${JSON.stringify(value)} (expected ${TOPOLOGIES.join(" or ")})`);
 }
+/**
+ * The spoke options `<targetDir>` records (#7894 D1), for the later commands
+ * (`sync-routes`, `add-module`): `undefined` on a hub; on a spoke, `mcp` from
+ * whether it still carries `apps/mcp` and `signIn` from the manifest's
+ * `signIn` key — absent reads as `"off"`, every spoke before #7894.
+ * @throws TopologyError on an unreadable manifest or an unknown value.
+ */
+export function readSpokeShape(targetDir) {
+    if (readSiteTopology(targetDir) !== "spoke")
+        return undefined;
+    const doc = JSON.parse(readFileSync(join(targetDir, SITE_MANIFEST_PATH), "utf8"));
+    const value = doc["signIn"];
+    if (value !== undefined && value !== "hub") {
+        throw new TopologyError(`${SITE_MANIFEST_PATH} records an unknown sign-in mode ${JSON.stringify(value)} (expected "hub", or no key)`);
+    }
+    return {
+        mcp: existsSync(join(targetDir, SPOKE_MCP_ROOT)),
+        signIn: value === "hub" ? "hub" : "off",
+    };
+}
 // ── D2 — the hub origin ─────────────────────────────────────────────────────
 /**
  * Hosts a spoke may reach over plain `http:` — the set
@@ -512,22 +911,34 @@ export function normalizeHubUrl(raw) {
     if (raw === undefined || raw.trim() === "") {
         throw new TopologyError(`a spoke needs its hub's origin, and none was given. ${inputs} (e.g. https://hub.example.com).`);
     }
+    return normalizeOrigin(raw, "the hub origin", inputs);
+}
+/**
+ * The hub's WEB origin a hub-mode spoke signs in at (`--hub-sign-in`, #7894
+ * D1) — `normalizeHubUrl`'s rules, each refusal naming the flag.
+ * @throws TopologyError when `raw` is not such an origin.
+ */
+export function normalizeHubSignInUrl(raw) {
+    return normalizeOrigin(raw, "the --hub-sign-in origin", "Pass --hub-sign-in <origin>");
+}
+/** `raw` normalized to an https (or loopback http) origin; refusals name `what` and `inputs`. */
+function normalizeOrigin(raw, what, inputs) {
     let url;
     try {
         url = new URL(raw.trim());
     }
     catch {
-        throw new TopologyError(`the hub origin is not a URL. ${inputs} to an origin such as https://hub.example.com.`);
+        throw new TopologyError(`${what} is not a URL. ${inputs} to an origin such as https://hub.example.com.`);
     }
     const loopback = LOOPBACK_HOSTS.includes(url.hostname);
     if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) {
-        throw new TopologyError(`the hub origin must be https: (http: only on ${LOOPBACK_HOSTS.join(" or ")}), got ${url.protocol}//${url.host}. ${inputs}.`);
+        throw new TopologyError(`${what} must be https: (http: only on ${LOOPBACK_HOSTS.join(" or ")}), got ${url.protocol}//${url.host}. ${inputs}.`);
     }
     if (url.pathname !== "/" || url.search !== "" || url.hash !== "") {
-        throw new TopologyError(`the hub origin must be an origin only — no path, query or fragment. ${inputs} to ${url.origin}.`);
+        throw new TopologyError(`${what} must be an origin only — no path, query or fragment. ${inputs} to ${url.origin}.`);
     }
     if (url.username !== "" || url.password !== "") {
-        throw new TopologyError(`the hub origin must not carry credentials. ${inputs} to ${url.protocol}//${url.host}.`);
+        throw new TopologyError(`${what} must not carry credentials. ${inputs} to ${url.protocol}//${url.host}.`);
     }
     return url.origin;
 }