create-ailk 0.15.0 → 0.16.0

package/dist/spoke-checkout.js

@@ -0,0 +1,359 @@
+/**
+ * The spoke checkout slice (#7838) — what a spoke carrying `commerce` gets in
+ * `apps/web`: the buy route and the Stripe webhook route (the only two files
+ * allowed to import the checkout package, #7873), the site's own
+ * `lib/checkout-config.ts`, and the thank-you and unavailable return pages.
+ *
+ * Every guarantee lives in `@working-theory/spoke-checkout` and arrives by a
+ * package bump; these files are thin and, apart from the config's one stamp
+ * line, byte-identical across spokes at one create-ailk version (roadmap D3,
+ * AC-SPOKE-02). A hub never gets them: its checkout is `apps/api`'s.
+ *
+ * Spec: docs/specs/7838-spoke-web-checkout-slice-spec.md (D3–D7, D9).
+ *
+ * Pure module: no `import.meta.url`, so jest imports it directly. Every
+ * package specifier in a rendered file is interpolated from a constant, so the
+ * monorepo's own architecture lint never reads a rendered line as an import
+ * create-ailk makes (the `CONTENT_ADAPTERS_PACKAGE` idiom in topology.ts).
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { SPOKE_CHECKOUT_ROUTE_FILES } from "./derive-architecture.js";
+import { ENV_CATALOG } from "./lib/env-catalog.js";
+import { diffTwoStrings, } from "./lib/extract-module-bundle.js";
+import { substituteWorkspaceVersions, } from "./substitute.js";
+import { TopologyError } from "./topology.js";
+/** The checkout package a spoke's two route files import. */
+export const SPOKE_CHECKOUT_PACKAGE = "@working-theory/spoke-checkout";
+const API_CLIENT_PACKAGE = "@working-theory/api-client";
+const UI_SECTIONS_PACKAGE = "@working-theory/ui/sections";
+const VALIDATION_PACKAGE = "@working-theory/validation";
+/** The site's checkout data — written once, the site's from then on. */
+export const SPOKE_CHECKOUT_CONFIG_PATH = "apps/web/lib/checkout-config.ts";
+/** The two return pages: Stripe's success URL and every refused buy's target. */
+export const SPOKE_CHECKOUT_PAGE_FILES = Object.freeze([
+    "apps/web/app/[locale]/checkout/thank-you/page.tsx",
+    "apps/web/app/[locale]/checkout/unavailable/page.tsx",
+]);
+/** The variables a commerce spoke depends on (D9). The package reads three of them. */
+export const SPOKE_CHECKOUT_ENV_CATALOG = Object.freeze({
+    STRIPE_SECRET_KEY: {
+        description: `Read by ${SPOKE_CHECKOUT_PACKAGE}: a test key (sk_test_ or rk_test_), or a restricted live key the operator sets with STRIPE_MODE=live.`,
+        secret: true,
+    },
+    STRIPE_WEBHOOK_SECRET: {
+        description: `Read by ${SPOKE_CHECKOUT_PACKAGE}: the signing secret of this site's Stripe webhook endpoint.`,
+        secret: true,
+    },
+    STRIPE_MODE: {
+        description: `Read by ${SPOKE_CHECKOUT_PACKAGE}: test (the default) or live. Live is the operator's switch, per site.`,
+        secret: false,
+    },
+    AILK_SPOKE_KEY: {
+        description: "The hub-issued key this site sends as x-ailk-spoke-key; the checkout fulfilment refuses to run without it. Never committed.",
+        secret: true,
+    },
+});
+/** The names a commerce spoke declares although only the package reads them (D9). */
+export const SPOKE_CHECKOUT_DECLARED_ENV = Object.freeze([
+    "STRIPE_SECRET_KEY",
+    "STRIPE_WEBHOOK_SECRET",
+    "STRIPE_MODE",
+]);
+/**
+ * The catalog (and declared names) a spoke's `appendEnvRows` call passes: a
+ * commerce spoke adds the checkout's four rows (D9). `ENV_CATALOG` itself is
+ * unchanged — its test fails on an entry the monorepo's apps never read.
+ */
+export function spokeEnvRowOptions(commerce) {
+    return commerce
+        ? {
+            catalog: { ...ENV_CATALOG, ...SPOKE_CHECKOUT_ENV_CATALOG },
+            declare: SPOKE_CHECKOUT_DECLARED_ENV,
+        }
+        : { catalog: ENV_CATALOG };
+}
+/** `metadata.site` / an offering slug — the package's own pattern. */
+const SITE_PATTERN = /^[a-z0-9][a-z0-9-]{0,39}$/;
+/** A stamp a renderer may interpolate: the package's pattern, never `default` (D6). */
+function isValidSite(site) {
+    return SITE_PATTERN.test(site) && site !== "default";
+}
+function assertSite(site) {
+    if (!isValidSite(site)) {
+        throw new TopologyError(`spoke checkout: site stamp ${JSON.stringify(site)} must match ^[a-z0-9][a-z0-9-]{0,39}$ and must not be "default"`);
+    }
+}
+/**
+ * The site stamp for a project name (D6): lower-cased, every run outside
+ * `a-z0-9` collapsed to `-`, trimmed, cut to 40. A name that leaves nothing
+ * usable — or `default`, which is also an unset hub's own stamp — gets
+ * `site-` and the first 8 hex characters of its SHA-256. Never `AILK_SITE_ID`.
+ */
+export function spokeCheckoutSite(projectName) {
+    const slug = projectName
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40)
+        .replace(/-+$/, "");
+    if (isValidSite(slug))
+        return slug;
+    const digest = createHash("sha256").update(projectName).digest("hex");
+    return `site-${digest.slice(0, 8)}`;
+}
+/** One route file (D4): three lines of wiring, every guarantee in the package. */
+function renderRoute(opts) {
+    return [
+        `// ${opts.title} — GENERATED by create-ailk (#7838). Do not edit: every`,
+        "// guarantee lives in the spoke-checkout package and arrives by a package",
+        "// bump. This site's data is lib/checkout-config.ts.",
+        `import { createSpokeCheckout } from "${SPOKE_CHECKOUT_PACKAGE}";`,
+        "",
+        `import { checkoutConfig } from "../../../../lib/checkout-config";`,
+        "",
+        `export const runtime = "nodejs";`,
+        `export const dynamic = "force-dynamic";`,
+        "",
+        `// platform-decisions-waiver: api-versioning — ${opts.waiver} (spec 7838 §7)`,
+        opts.exportLine,
+        "",
+    ].join("\n");
+}
+const BUY_ROUTE = renderRoute({
+    title: "The buy route",
+    waiver: "a browser buy link that redirects to Stripe Checkout, not a versioned API contract",
+    exportLine: "export const { GET, POST } = createSpokeCheckout(checkoutConfig).buy;",
+});
+const WEBHOOK_ROUTE = renderRoute({
+    title: "The Stripe webhook route",
+    waiver: "the endpoint URL registered in Stripe, not a versioned API contract",
+    exportLine: "export const { POST } = createSpokeCheckout(checkoutConfig).webhook;",
+});
+/** The site's checkout data (D5). Only the `const SITE` line varies by site. */
+function renderConfig(site) {
+    return [
+        "// checkout-config.ts — this spoke's checkout, as data (#7838).",
+        "//",
+        "// Written once by create-ailk and yours from then on: create-ailk never",
+        "// rewrites it. The buy route and the Stripe webhook route build their",
+        "// handlers from it. Those two are the only files allowed to import the",
+        "// checkout package (architecture.yaml), so this file never imports it,",
+        "// stripe-client or the stripe SDK. Keep it to data and the fulfil callback.",
+        "//",
+        "// site       Stamped on every Checkout Session as metadata.site. This site's",
+        "//            webhook acts only on its own stamp, and the hub ignores any stamp",
+        "//            that is not its own, so the stamp must be unique on the Stripe",
+        '//            account this site shares. Never "default". Change it only before',
+        "//            any price exists: every lookup key starts with it.",
+        "// offerings  slug -> Stripe lookup_key. The buy link is /api/checkout/<slug>.",
+        "//            scaffold-commerce replaces the placeholder below.",
+        "// fulfil     Runs for each paid session, at least once. It posts one lead to",
+        "//            the hub with the session id as its Idempotency-Key, so a repeat",
+        "//            writes nothing new. The hub dedupes only an identical body: change",
+        "//            the payload's shape only when no webhook is failing.",
+        `import { leads } from "${API_CLIENT_PACKAGE}";`,
+        "",
+        `import { resolveBaseUrl } from "../src/lib/routes";`,
+        "",
+        `const SITE = "${site}";`,
+        "",
+        "/** What this site's fulfil callback reads from a completed checkout. */",
+        "interface CompletedCheckout {",
+        "  idempotencyKey: string;",
+        "  sessionId: string;",
+        "  offering: string;",
+        '  kind: "fixed" | "quoted";',
+        '  mode: "test" | "live";',
+        "  amountTotal: number | null;",
+        "  currency: string | null;",
+        "  email: string | null;",
+        "  customerId: string | null;",
+        "}",
+        "",
+        "export const checkoutConfig = {",
+        "  site: SITE,",
+        "  siteBaseUrl: resolveBaseUrl(),",
+        "  offerings: {",
+        "    // A placeholder until scaffold-commerce creates this site's prices.",
+        '    example: { kind: "fixed", lookupKey: `${SITE}_example`, cancelPath: "/" },',
+        "  },",
+        "  async fulfil(checkout: CompletedCheckout): Promise<void> {",
+        "    if (checkout.email === null) return;",
+        "    // No spoke key: the hub cannot place the lead in this site's workspace.",
+        "    // Fail, so Stripe retries and the dashboard shows a failed webhook.",
+        "    if (!process.env.AILK_SPOKE_KEY)",
+        '      throw new Error("AILK_SPOKE_KEY is not set");',
+        "    const result = await leads.submit(",
+        "      {",
+        "        siteId: SITE,",
+        '        source: "web",',
+        "        email: checkout.email,",
+        "        payload: {",
+        "          site: SITE,",
+        '          page: "checkout",',
+        "          offering: checkout.offering,",
+        "          checkoutKind: checkout.kind,",
+        "          mode: checkout.mode,",
+        "          amountTotal: checkout.amountTotal,",
+        "          currency: checkout.currency,",
+        "          stripeCustomerId: checkout.customerId,",
+        "          checkoutSession: checkout.sessionId,",
+        "        },",
+        "      },",
+        '      { headers: { "Idempotency-Key": checkout.idempotencyKey } },',
+        "    );",
+        "    // A replay under the same key answers 201 with the first lead; any",
+        "    // failure (422 idempotency_key_reused included) makes Stripe retry.",
+        "    if (!result.ok) throw new Error(`hub lead write answered ${result.status}`);",
+        "  },",
+        "};",
+        "",
+    ].join("\n");
+}
+/** One return page (D7): a server component that reads nothing but its copy. */
+function renderPage(opts) {
+    return [
+        `// ${opts.title} — GENERATED by create-ailk (#7838).`,
+        ...opts.about.map((line) => `// ${line}`),
+        `import { SectionRenderer } from "${UI_SECTIONS_PACKAGE}";`,
+        `import type { PageSection } from "${VALIDATION_PACKAGE}";`,
+        `import type { Metadata } from "next";`,
+        `import { getTranslations } from "next-intl/server";`,
+        `import type { ReactElement } from "react";`,
+        "",
+        "interface Props {",
+        "  params: Promise<{ locale: string }>;",
+        "}",
+        "",
+        "export async function generateMetadata({ params }: Props): Promise<Metadata> {",
+        "  const { locale } = await params;",
+        `  const t = await getTranslations({ locale, namespace: "${opts.namespace}" });`,
+        `  return { title: t("title"), robots: { index: false, follow: false } };`,
+        "}",
+        "",
+        "export default async function Page({ params }: Props): Promise<ReactElement> {",
+        "  const { locale } = await params;",
+        `  const t = await getTranslations({ locale, namespace: "${opts.namespace}" });`,
+        "  const sections: PageSection[] = [",
+        ...opts.sections.map((line) => `    ${line}`),
+        "  ];",
+        "  return (",
+        '    <main id="main">',
+        "      <SectionRenderer sections={sections} locale={locale} leadingSectionOwnsTitle />",
+        "    </main>",
+        "  );",
+        "}",
+        "",
+    ].join("\n");
+}
+const THANK_YOU_PAGE = renderPage({
+    title: "The checkout thank-you page",
+    about: [
+        "Stripe returns a buyer here after paying. It reads no search parameter and",
+        "calls neither Stripe nor the hub: the webhook is what fulfils the order.",
+    ],
+    namespace: "checkoutThankYou",
+    sections: [
+        "{",
+        '  id: "checkout-thank-you",',
+        '  type: "content-block",',
+        '  data: { headline: t("title"), body: t("body") },',
+        "},",
+    ],
+});
+const UNAVAILABLE_PAGE = renderPage({
+    title: "The checkout unavailable page",
+    about: [
+        "Every refused buy lands here. It never says why: a reason is a probe's",
+        "answer, and the buyer needs only that nothing was charged.",
+    ],
+    namespace: "checkoutUnavailable",
+    sections: [
+        "{",
+        '  id: "checkout-unavailable",',
+        '  type: "content-block",',
+        '  data: { headline: t("title"), body: t("body") },',
+        "},",
+        "{",
+        '  id: "checkout-unavailable-cta",',
+        '  type: "cta",',
+        "  data: {",
+        '    headline: t("ctaHeadline"),',
+        '    primaryCta: { label: t("ctaLabel"), href: "/contact" },',
+        "  },",
+        "},",
+    ],
+});
+/**
+ * The slice for `site`, in order: the two route files, the config, the two
+ * pages (D3). Throws `TopologyError` for an invalid stamp (SEC-7838-10).
+ */
+export function renderSpokeCheckoutFiles(site) {
+    assertSite(site);
+    const [buyPath, webhookPath] = SPOKE_CHECKOUT_ROUTE_FILES;
+    const [thankYouPath, unavailablePath] = SPOKE_CHECKOUT_PAGE_FILES;
+    return [
+        [buyPath, BUY_ROUTE],
+        [webhookPath, WEBHOOK_ROUTE],
+        [SPOKE_CHECKOUT_CONFIG_PATH, renderConfig(site)],
+        [thankYouPath, THANK_YOU_PAGE],
+        [unavailablePath, UNAVAILABLE_PAGE],
+    ];
+}
+const WEB_PACKAGE_JSON = "apps/web/package.json";
+/** `deps` with `name: version` added in sorted position, every other key kept in place. */
+function withDependency(deps, name, version) {
+    const out = {};
+    let placed = false;
+    for (const [key, value] of Object.entries(deps)) {
+        // Code-unit order, as package managers sort — never the host's locale.
+        if (!placed && key > name) {
+            out[name] = version;
+            placed = true;
+        }
+        out[key] = value;
+    }
+    if (!placed)
+        out[name] = version;
+    return out;
+}
+/**
+ * Write the slice into `targetDir` (D3). A file that already exists is left
+ * byte-for-byte and reported `skipped` — the config is the site's once
+ * written. Adds the package to `apps/web/package.json` only when absent.
+ * Every refusal (an invalid stamp, a version map without the package, a
+ * missing or malformed `apps/web/package.json`) throws before the first write.
+ */
+export function writeSpokeCheckoutSlice(targetDir, opts) {
+    const files = renderSpokeCheckoutFiles(opts.site);
+    const range = JSON.parse(substituteWorkspaceVersions(`{"${SPOKE_CHECKOUT_PACKAGE}": "workspace:*"}`, opts.versions));
+    const version = range[SPOKE_CHECKOUT_PACKAGE];
+    const pkgPath = join(targetDir, WEB_PACKAGE_JSON);
+    const before = readFileSync(pkgPath, "utf8");
+    const pkg = JSON.parse(before);
+    const rows = [];
+    for (const [path, text] of files) {
+        const abs = join(targetDir, path);
+        if (existsSync(abs)) {
+            rows.push({ path, action: "skipped", wanted: text });
+            continue;
+        }
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, text);
+        rows.push({ path, action: "written" });
+    }
+    const deps = pkg.dependencies ?? {};
+    if (!Object.prototype.hasOwnProperty.call(deps, SPOKE_CHECKOUT_PACKAGE)) {
+        pkg.dependencies = withDependency(deps, SPOKE_CHECKOUT_PACKAGE, version);
+        const after = `${JSON.stringify(pkg, null, 2)}${before.endsWith("\n") ? "\n" : ""}`;
+        writeFileSync(pkgPath, after);
+        rows.push({
+            path: WEB_PACKAGE_JSON,
+            action: "patched",
+            change: diffTwoStrings(WEB_PACKAGE_JSON, before, after, true),
+        });
+    }
+    return rows;
+}

package/dist/surfaces.js

@@ -626,6 +626,10 @@ export const ROUTE_SINCE = {
     "(authed)/account/inbox/[kind]/[id]": "0.30.0",
     "(authed)/account/settings": "0.30.0",
     "(authed)/account/support": "0.30.0",
+    // #7920 — the member file read a message's file action opens. Genuinely
+    // new, so it attaches at today's fixed-group version, the same rule #7430
+    // applied above.
+    "(authed)/account/inbox/message/[id]/file": "0.37.0",
     // The leads inbox (#5678). The ROUTE ships in every scaffold, Free
     // included — lead capture is a never-gate surface, so reading a lead back
     // is one too. Whether it shows a ROW is a separate question with two
@@ -756,6 +760,9 @@ export const ROUTE_DEPENDENCIES = {
         `${ROUTE_ROOT}/(authed)/account/error-row.tsx`,
         `${ROUTE_ROOT}/(authed)/account/retry-button.tsx`,
     ],
+    // #7920 — the member file read re-serves the hub's bytes with the
+    // credential `forwardedCookieInit` returns.
+    "(authed)/account/inbox/message/[id]/file": ["apps/web/lib/server-api.ts"],
     "(authed)/account/settings": [
         "apps/web/lib/account-config.ts",
         "apps/web/lib/auth-env.ts",

package/dist/sync-routes.js

@@ -31,9 +31,11 @@ import { tmpdir } from "node:os";
 import { basename, dirname, join, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
 import { copyTemplate } from "./copy.js";
+import { appendEnvRows } from "./lib/declared-env.js";
+import { ENV_CATALOG } from "./lib/env-catalog.js";
 import { substituteMarkers } from "./substitute.js";
 import { GATEABLE_SURFACES, NON_ROUTE_DIRS, ROUTE_DEPENDENCIES, ROUTE_MESSAGE_NAMESPACES, ROUTE_SINCE, surfaceForRouteDir, } from "./surfaces.js";
-import { isSpokeExcluded, readSiteTopology } from "./topology.js";
+import { SPOKE_SEAM_FILES, isSpokeExcluded, readSpokeShape, } from "./topology.js";
 /** Template-relative prefix every `apps/web` route directory sits under. */
 const ROUTE_ROOT = "apps/web/app/[locale]";
 /**
@@ -99,9 +101,9 @@ function reportFor(route) {
  * byte-for-byte in, the target's copy. Non-recursive: nested directories are
  * route dirs of their own, or `__tests__`.
  */
-function isModified(expectedDir, targetDir) {
+function isModified(expectedDir, targetDir, skip = () => false) {
     for (const entry of readdirSync(expectedDir, { withFileTypes: true })) {
-        if (!entry.isFile())
+        if (!entry.isFile() || skip(entry.name))
             continue;
         const targetFile = join(targetDir, entry.name);
         if (!existsSync(targetFile))
@@ -167,10 +169,17 @@ export function syncRoutes(opts) {
     // #7426 D13 — on a spoke, a route dir the spoke does not carry (the
     // `(auth)` and `(authed)` groups) is out of scope: neither reported nor
     // copied. This is the one filter point for add-module, add-route and the
-    // sync-routes subcommand alike; a hub's scope is unchanged.
-    const spoke = readSiteTopology(targetAbs) === "spoke"
-        ? { mcp: existsSync(join(targetAbs, "apps", "mcp")) }
-        : undefined;
+    // sync-routes subcommand alike; a hub's scope is unchanged. The spoke's
+    // sign-in mode rides along (#7894 D1): a hub sign-in spoke keeps its
+    // `(authed)` account area in scope and its operator surfaces out.
+    const spoke = readSpokeShape(targetAbs);
+    // A spoke's own render of a seam, and a file it does not carry, are not
+    // "modified" (#7894 D8): the template holds the hub's.
+    const spokeSkip = (route) => (name) => {
+        const path = `${ROUTE_ROOT}/${route}/${name}`;
+        return (spoke !== undefined &&
+            (SPOKE_SEAM_FILES.includes(path) || isSpokeExcluded(path, spoke)));
+    };
     const inScope = listTemplateRouteDirs(opts.templatesDir)
         .map(reportFor)
         // "authed" (#5014): the `(authed)` route group ships unconditionally in
@@ -202,7 +211,7 @@ export function syncRoutes(opts) {
             if (!existsSync(targetRoute)) {
                 missing.push(report);
             }
-            else if (isModified(join(scratch, report.route), targetRoute)) {
+            else if (isModified(join(scratch, report.route), targetRoute, spokeSkip(report.route))) {
                 modified.push(report);
             }
         }
@@ -250,6 +259,12 @@ export function syncRoutes(opts) {
             copyDependencyFile(join(opts.templatesDir, dep), dst, markers);
             appliedDependencies.push(dep);
         }
+        // #7874 D9 — a spoke declares what the copied routes read, as the last
+        // write. A malformed env_contract block throws EnvContractError naming
+        // its line; the files copied above stay.
+        if (spoke !== undefined) {
+            appendEnvRows(targetAbs, { topology: "spoke", catalog: ENV_CATALOG });
+        }
     }
     return {
         targetDir: targetAbs,

package/dist/topology.d.ts

@@ -10,16 +10,48 @@ export declare class TopologyError extends Error {
 export declare const SPOKE_REMOVED_ROOTS: readonly string[];
 /** The root `--without-mcp` removes. */
 export declare const SPOKE_MCP_ROOT = "apps/mcp";
+/** Commerce's apps/web files that reach the hub's own checkout (spoke-intake Rule 3, #7838). */
+export declare const SPOKE_HUB_CHECKOUT_SEEDS: readonly string[];
 /**
- * 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 declare const SPOKE_REMOVAL_SEEDS: readonly string[];
-/** The two generated seam files (D5). A seam is rewritten, never removed. */
+/**
+ * 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 declare const SPOKE_EXCLUDED_MODULE_PATHS: readonly string[];
+/**
+ * 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 declare const HUB_MODE_AUTHED_SEEDS: readonly string[];
+/** The generated seam files (D5; #7874 D12). A seam is rewritten, never removed. */
 export declare const WEB_SEAM_PATH = "apps/web/lib/topology.generated.ts";
 export declare 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 declare 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 declare const AUTHED_GATE_SEAM_PATH = "apps/web/app/[locale]/(authed)/signed-out-gate.generated.tsx";
 export declare const SPOKE_SEAM_FILES: readonly string[];
+/**
+ * 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 declare const SPOKE_ONLY_FILES: readonly string[];
 /**
  * The closure's allow-list: a file `spokeExclusions` removes must sit under
  * one of these prefixes, or under a `__tests__/` directory. A member outside
@@ -27,14 +59,26 @@ export declare const SPOKE_SEAM_FILES: readonly string[];
  * file — and `spokeExclusions` throws naming it rather than cut it silently.
  */
 export declare const SPOKE_REMOVABLE_PREFIXES: readonly string[];
+/**
+ * A spoke's sign-in modes (#7894 D1): `off` — the default, no sign-in — and
+ * `hub`, signing a visitor in through the hub (`--hub-sign-in <origin>`).
+ */
+export type SignInMode = "off" | "hub";
 export interface SpokeShapeOptions {
     /** Whether the spoke keeps `apps/mcp` (the default; `--without-mcp` drops it). */
     mcp: boolean;
+    /** The sign-in mode (#7894 D1). Absent means `"off"`, so every existing caller is the default mode. */
+    signIn?: SignInMode;
 }
 /** The removed roots for these options. */
 export declare function spokeRemovedRoots(opts: SpokeShapeOptions): string[];
-/** Whether a closure member is one the registry allows a spoke to drop. */
-export declare function isRemovableClosureMember(path: string): boolean;
+/**
+ * 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 declare function isRemovableClosureMember(path: string, opts?: Pick<SpokeShapeOptions, "signIn">): boolean;
 /**
  * Every path a spoke does not carry, computed over the built `templates/`
  * tree: the removed roots, the seeds that apply, and every source file under
@@ -69,14 +113,56 @@ export interface IsSpokeExcludedOptions extends SpokeShapeOptions {
  * generator contract). Scaffold-relative, `/`- or `\`-separated.
  */
 export declare function isSpokeExcluded(path: string, opts: IsSpokeExcludedOptions): boolean;
-/** `apps/web/lib/topology.generated.ts` for `topology` (D5). */
-export declare function renderWebSeam(topology: Topology): string;
+/**
+ * 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 declare function spokeDestination(destination: string): string;
+/**
+ * `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 declare function renderWebSeam(topology: Topology, signIn?: SignInMode): string;
+/**
+ * `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 declare function renderAuthedGateSeam(topology: Topology, signIn?: SignInMode): string;
 /** `apps/mcp/src/lib/topology.generated.ts` for `topology` (D5). */
 export declare function renderMcpSeam(topology: Topology): string;
+/** `apps/web/lib/api-origin.generated.ts` for `topology` (#7874 D12). */
+export declare function renderApiOriginSeam(topology: Topology): string;
 /** `pnpm-workspace.yaml` without its `database` package entry. */
 export declare function transformWorkspaceYaml(text: string): string;
 /** The root `package.json` without its `db:*` scripts. */
 export declare function transformRootPackageJson(text: string): string;
+/** The spoke's declared-env script (#7874 D11) — named apart from the monorepo's `env:check`. */
+export declare const ENV_DECLARED_SCRIPT = "env:declared";
+/**
+ * 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 declare function addEnvCheckScripts(text: string): string;
+/**
+ * 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 declare function transformCiWorkflow(text: string): string;
 /** The root `tsconfig.json` without a reference under a removed root. */
 export declare function transformRootTsconfig(text: string, opts: SpokeShapeOptions): string;
 /**
@@ -87,7 +173,8 @@ export declare function transformAppPackageJson(text: string, label: string, req
 /**
  * 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 declare function applySpokeTransforms(targetDir: string, opts: SpokeShapeOptions): void;
@@ -101,10 +188,24 @@ export declare const HUB_ORIGIN_ENV_VAR = "AILK_API_URL";
  * the hub issues those.
  */
 export declare function writeHubOriginEnv(targetDir: string, origin: string): void;
+/** The env var naming the hub's web origin a hub-mode spoke signs in at (#7894 D11). */
+export declare 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 declare 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 declare function writeHubSignInEnv(targetDir: string, origin: string): void;
 /** The `hard_floors:` block a spoke's `project.yaml` carries (D9). */
 export declare function renderSpokeHardFloors(opts: SpokeShapeOptions): string;
 /** `project.yaml` with its `hard_floors:` block replaced by the spoke's (D9). */
 export declare function transformProjectYaml(text: string, opts: SpokeShapeOptions): string;
+/** Why a module is not admitted on a spoke, and where its admission lives. */
+export declare const SPOKE_REFUSAL_REASONS: Partial<Record<ModuleName, string>>;
 /** The modules a spoke may carry — every slice declaring `spoke: true`. */
 export declare function spokeModules(): ModuleName[];
 /** The refusal for a module a spoke cannot carry, or undefined when admitted. */
@@ -115,6 +216,14 @@ export declare function spokeModuleRefusal(name: ModuleName): string | undefined
  * @throws TopologyError on an unreadable manifest or an unknown value.
  */
 export declare function readSiteTopology(targetDir: string): Topology;
+/**
+ * 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 declare function readSpokeShape(targetDir: string): SpokeShapeOptions | undefined;
 /**
  * Hosts a spoke may reach over plain `http:` — the set
  * `packages/api-client/src/http.ts` sends the spoke key under. Named here
@@ -129,3 +238,9 @@ export declare const LOOPBACK_HOSTS: readonly string[];
  *   is not such an origin. Never echoes a query or fragment.
  */
 export declare function normalizeHubUrl(raw: string | undefined): string;
+/**
+ * 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 declare function normalizeHubSignInUrl(raw: string): string;