create-ailk 0.18.0 → 0.19.1

package/dist/surfaces.js

@@ -503,6 +503,31 @@ export function excludedContentPaths(enabled) {
     }
     return out.sort();
 }
+/**
+ * True when `path` (scaffold-relative, `/`-separated) lies inside one of the
+ * content directories `excludedContentPaths(enabled)` names, with `<locale>`
+ * matching any one path segment (#8427 D4).
+ *
+ * This is `excludedContentPaths`' first non-export reader — its own comment
+ * already named exactly this class ("orphan content makes `/sitemap.xml`
+ * advertise URLs that 404"). It is wired into the `skip` predicate
+ * `extractModuleBundle` already takes (`programmatic.ts`, `add-module.ts`),
+ * and into `layerInstalledSeeds`'s installed-seed count (`site-roster.ts`),
+ * so a module bundle never writes — and a roster check never counts — a
+ * seed under a gateable surface the scaffold does not enable.
+ */
+export function isUnservedSurfaceContent(path, enabled) {
+    const segments = path.split("/");
+    for (const contentPath of excludedContentPaths([...enabled])) {
+        const prefixSegments = contentPath.split("/");
+        if (prefixSegments.length > segments.length)
+            continue;
+        const matches = prefixSegments.every((segment, i) => segment === "<locale>" || segment === segments[i]);
+        if (matches)
+            return true;
+    }
+    return false;
+}
 /**
  * Route manifest (#4986): every template route directory, keyed relative to
  * ROUTE_ROOT (`apps/web/app/[locale]`), → the `@working-theory/*` fixed-group
@@ -630,6 +655,23 @@ export const ROUTE_SINCE = {
     // 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",
+    // #8232 — User settings' two pages, General and Billing (the old
+    // `(authed)/account/settings` now redirects to General). Genuinely new, so
+    // they attach at today's fixed-group version, the same rule #7430 applied.
+    "(authed)/account/general": "0.38.0",
+    "(authed)/account/billing": "0.38.0",
+    // #8339 — User settings' two new tabs, Security and Notifications
+    // (General and Billing now render through the shared account-settings
+    // composition). Genuinely new, so they attach at today's fixed-group
+    // version, the same rule #7430/#8232 applied.
+    "(authed)/account/security": "0.38.0",
+    "(authed)/account/notifications": "0.38.0",
+    // #8234 — the member Artifacts pages and a version's file route. Genuinely
+    // new, so they attach at today's fixed-group version, the same rule #7430
+    // applied.
+    "(authed)/account/artifacts": "0.38.0",
+    "(authed)/account/artifacts/[pieceId]": "0.38.0",
+    "(authed)/account/artifacts/[pieceId]/versions/[version]/file": "0.38.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
@@ -759,24 +801,144 @@ export const ROUTE_DEPENDENCIES = {
         `${ROUTE_ROOT}/(authed)/account/account-data.ts`,
         `${ROUTE_ROOT}/(authed)/account/error-row.tsx`,
         `${ROUTE_ROOT}/(authed)/account/retry-button.tsx`,
+        // #8233 C9 — the New menu's files beside account-config.ts: new-popups.tsx
+        // binds the config's actions to the popups, which import the menu and its
+        // server actions. (account-config.ts itself imports none of them — a
+        // spoke without sign-in drops the `(authed)` group and keeps the config.)
+        `${ROUTE_ROOT}/(authed)/account/new-menu.tsx`,
+        `${ROUTE_ROOT}/(authed)/account/new-actions.ts`,
+        `${ROUTE_ROOT}/(authed)/account/new-popups.tsx`,
+        `${ROUTE_ROOT}/(authed)/account/components/schedule-service.tsx`,
+        `${ROUTE_ROOT}/(authed)/account/components/request-quote.tsx`,
+        `${ROUTE_ROOT}/(authed)/account/components/send-message.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"],
+    // #8232 D13 — the settings route is a redirect now; what it still imports
+    // from outside itself is `theme-modes.ts`'s theme reader and the brand file
+    // that reader imports.
     "(authed)/account/settings": [
+        "apps/web/lib/site-brand.tsx",
+        "apps/web/lib/site-theme.ts",
+    ],
+    // #8232 D13 — General and Billing import files in their parent's directory
+    // too. Each listed parent file is new in #8232 or unchanged by it, so a
+    // scaffold that already has one keeps a copy that still compiles; the
+    // settings components General changed moved into `general/` instead (C3).
+    // `profile-actions.ts` imports `lib/hub-session/reseal.ts` by its own path,
+    // since a scaffold's existing `lib/hub-session/index.ts` is never updated.
+    //
+    // #8339 D11 — `settings/color-mode.tsx` drops: General's own color-mode
+    // control is now the shared `AccountSettings` composition's
+    // (@working-theory/templates/account). `sign-in-method.ts` stays: General no
+    // longer renders the Sign-in section itself (moved to Security), but it
+    // still imports `sign-in-method.ts` transitively through
+    // `profile-source.ts`'s `via` derivation.
+    "(authed)/account/general": [
         "apps/web/lib/account-config.ts",
         "apps/web/lib/auth-env.ts",
         "apps/web/lib/server-api.ts",
         "apps/web/lib/site-brand.tsx",
         "apps/web/lib/site-theme.ts",
+        "apps/web/lib/hub-session/reseal.ts",
         `${ROUTE_ROOT}/(authed)/account/account-data.ts`,
-        `${ROUTE_ROOT}/(authed)/account/support-actions.ts`,
+        `${ROUTE_ROOT}/(authed)/account/settings-frame.tsx`,
+        `${ROUTE_ROOT}/(authed)/account/sign-in-method.ts`,
+        `${ROUTE_ROOT}/(authed)/account/profile-actions.ts`,
+        `${ROUTE_ROOT}/(authed)/account/settings/theme-modes.ts`,
+        // #8233 C9 — the New menu's files beside account-config.ts: new-popups.tsx
+        // binds the config's actions to the popups, which import the menu and its
+        // server actions. (account-config.ts itself imports none of them — a
+        // spoke without sign-in drops the `(authed)` group and keeps the config.)
+        `${ROUTE_ROOT}/(authed)/account/new-menu.tsx`,
+        `${ROUTE_ROOT}/(authed)/account/new-actions.ts`,
+        `${ROUTE_ROOT}/(authed)/account/new-popups.tsx`,
+        `${ROUTE_ROOT}/(authed)/account/components/schedule-service.tsx`,
+        `${ROUTE_ROOT}/(authed)/account/components/request-quote.tsx`,
+        `${ROUTE_ROOT}/(authed)/account/components/send-message.tsx`,
+    ],
+    // #8339 D11 — Security holds the former Sign-in section, moved verbatim
+    // from General: `sign-in-method.ts` and what it imports. #8431 D8 — the
+    // tab's failed-read row (`error-row.tsx` and its `retry-button.tsx`); its
+    // own `security-source.ts` and `security-panel.tsx` live in the route dir
+    // and copy with it.
+    "(authed)/account/security": [
+        "apps/web/lib/account-config.ts",
+        "apps/web/lib/auth-env.ts",
+        "apps/web/lib/server-api.ts",
+        "apps/web/lib/hub-session/config.ts",
+        `${ROUTE_ROOT}/(authed)/account/account-data.ts`,
+        `${ROUTE_ROOT}/(authed)/account/error-row.tsx`,
+        `${ROUTE_ROOT}/(authed)/account/retry-button.tsx`,
+        `${ROUTE_ROOT}/(authed)/account/settings-frame.tsx`,
+        `${ROUTE_ROOT}/(authed)/account/sign-in-method.ts`,
+    ],
+    // #8339 D11 — Notifications holds the former Privacy section's
+    // cookie-settings link, moved verbatim from General.
+    "(authed)/account/notifications": [
+        "apps/web/lib/account-config.ts",
+        "apps/web/lib/server-api.ts",
+        `${ROUTE_ROOT}/(authed)/account/account-data.ts`,
+        `${ROUTE_ROOT}/(authed)/account/settings-frame.tsx`,
+    ],
+    "(authed)/account/billing": [
+        "apps/web/lib/account-config.ts",
+        "apps/web/lib/server-api.ts",
+        `${ROUTE_ROOT}/(authed)/account/account-data.ts`,
+        `${ROUTE_ROOT}/(authed)/account/actions.ts`,
+        `${ROUTE_ROOT}/(authed)/account/error-row.tsx`,
+        `${ROUTE_ROOT}/(authed)/account/retry-button.tsx`,
+        `${ROUTE_ROOT}/(authed)/account/settings-frame.tsx`,
+        `${ROUTE_ROOT}/(authed)/account/billing-source.ts`,
+        // #8233 C9 — the New menu's files beside account-config.ts: new-popups.tsx
+        // binds the config's actions to the popups, which import the menu and its
+        // server actions. (account-config.ts itself imports none of them — a
+        // spoke without sign-in drops the `(authed)` group and keeps the config.)
+        `${ROUTE_ROOT}/(authed)/account/new-menu.tsx`,
+        `${ROUTE_ROOT}/(authed)/account/new-actions.ts`,
+        `${ROUTE_ROOT}/(authed)/account/new-popups.tsx`,
+        `${ROUTE_ROOT}/(authed)/account/components/schedule-service.tsx`,
+        `${ROUTE_ROOT}/(authed)/account/components/request-quote.tsx`,
+        `${ROUTE_ROOT}/(authed)/account/components/send-message.tsx`,
+    ],
+    // #8234 — the Artifacts pages import files in their parent's directory, as
+    // #7430's children do; the artifact page also imports its own parent's
+    // `artifact-data.ts` and `artifact-actions.ts`, which an older synced
+    // `artifacts/` might lack. The file route re-serves the hub's bytes with
+    // the credential `forwardedCookieInit` returns.
+    "(authed)/account/artifacts": [
+        "apps/web/lib/account-config.ts",
+        "apps/web/lib/server-api.ts",
+        `${ROUTE_ROOT}/(authed)/account/account-data.ts`,
+        `${ROUTE_ROOT}/(authed)/account/error-row.tsx`,
+        `${ROUTE_ROOT}/(authed)/account/retry-button.tsx`,
+    ],
+    "(authed)/account/artifacts/[pieceId]": [
+        "apps/web/lib/account-config.ts",
+        "apps/web/lib/server-api.ts",
+        `${ROUTE_ROOT}/(authed)/account/account-data.ts`,
+        `${ROUTE_ROOT}/(authed)/account/error-row.tsx`,
+        `${ROUTE_ROOT}/(authed)/account/retry-button.tsx`,
+        `${ROUTE_ROOT}/(authed)/account/artifacts/artifact-data.ts`,
+        `${ROUTE_ROOT}/(authed)/account/artifacts/artifact-actions.ts`,
     ],
+    "(authed)/account/artifacts/[pieceId]/versions/[version]/file": ["apps/web/lib/server-api.ts"],
     "(authed)/account/support": [
         "apps/web/lib/account-config.ts",
         "apps/web/lib/server-api.ts",
         `${ROUTE_ROOT}/(authed)/account/account-data.ts`,
         `${ROUTE_ROOT}/(authed)/account/support-actions.ts`,
+        // #8233 C9 — the New menu's files beside account-config.ts: new-popups.tsx
+        // binds the config's actions to the popups, which import the menu and its
+        // server actions. (account-config.ts itself imports none of them — a
+        // spoke without sign-in drops the `(authed)` group and keeps the config.)
+        `${ROUTE_ROOT}/(authed)/account/new-menu.tsx`,
+        `${ROUTE_ROOT}/(authed)/account/new-actions.ts`,
+        `${ROUTE_ROOT}/(authed)/account/new-popups.tsx`,
+        `${ROUTE_ROOT}/(authed)/account/components/schedule-service.tsx`,
+        `${ROUTE_ROOT}/(authed)/account/components/request-quote.tsx`,
+        `${ROUTE_ROOT}/(authed)/account/components/send-message.tsx`,
     ],
     "(authed)/admin": [
         "apps/web/lib/server-api.ts",
@@ -832,6 +994,13 @@ export const ROUTE_MESSAGE_NAMESPACES = {
     "(authed)/account/inbox/[kind]/[id]": ["account"],
     "(authed)/account/settings": ["account"],
     "(authed)/account/support": ["account"],
+    "(authed)/account/general": ["account"],
+    "(authed)/account/security": ["account"],
+    "(authed)/account/notifications": ["account"],
+    "(authed)/account/billing": ["account"],
+    // #8234 — the two Artifacts pages; the file route renders no string.
+    "(authed)/account/artifacts": ["account"],
+    "(authed)/account/artifacts/[pieceId]": ["account"],
     "(authed)/admin": ["admin"],
     "(authed)/leads": ["leadsInbox"],
     // #5977 — every string on both editor routes comes from the `edit`

package/dist/template-manifest.d.ts

@@ -14,7 +14,7 @@
  * package already twice records that a fixed template FILE is the drift a
  * registry removes.
  */
-import type { CategorySlug } from "@working-theory/schema/categories";
+import type { CategorySlug } from "./category-profile.js";
 import { type PageRosterRow } from "./module-architecture.js";
 import type { ModuleName } from "./parse-args.js";
 import type { TemplateLayout } from "./site-chrome.js";
@@ -66,8 +66,9 @@ export interface TemplateManifest {
      * The business categories this template is FOR — one or more LEAF slugs from
      * the site-category registry (`@working-theory/schema/categories`, #5830),
      * shared with content's frontmatter `categories`. Required, and typed against
-     * `CategorySlug`, for the same reason `requires` is typed against
-     * `ModuleName`: an unrecognized name fails type-check rather than a runtime
+     * `CategorySlug` — create-ailk's drift-tested copy of the registry's leaves
+     * (`category-profile.ts`, #8412) — for the same reason `requires` is typed
+     * against `ModuleName`: an unrecognized name fails type-check rather than a runtime
      * validation, and every template must be findable under at least one
      * category on the hub's "Browse by business" band.
      *

package/dist/topology.d.ts

@@ -134,9 +134,14 @@ export declare const SPOKE_UNSERVED_MCP_TOOLS: readonly 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.
+ * loads Better Auth. `opts.spokeBilling` (#8217 D7) makes `loadSpokeBilling`
+ * reach the spoke billing action — only on a spoke that signs in through its
+ * hub, the one render whose account area can call it.
+ * @throws TopologyError for `spokeBilling` on a hub or a default-mode spoke.
  */
-export declare function renderWebSeam(topology: Topology, signIn?: SignInMode): string;
+export declare function renderWebSeam(topology: Topology, signIn?: SignInMode, opts?: {
+    spokeBilling?: boolean;
+}): 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

package/dist/topology.js

@@ -271,7 +271,11 @@ const WEB_SEAM_HEADER = `// topology.generated.ts — how this site reads a sess
 // 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.
 // UNSERVED_MCP_TOOLS names the MCP tools /.well-known/mcp.json leaves out
-// on this topology (#8070).`;
+// on this topology (#8070).
+// loadSpokeBilling reaches the spoke billing action only on a spoke that
+// signs in through its hub and carries commerce (#8217); elsewhere, null.
+// readOwnAccounts lists the signed-in person's own sign-in accounts through
+// Better Auth on a hub (#8431); a spoke has none here, so it answers null.`;
 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:
@@ -301,6 +305,26 @@ const SITE_SESSION_TYPE = `export type SiteSession = {
     createdAt?: Date | string | null;
   };
 } | null;`;
+/**
+ * `readOwnAccounts` (#8431 D2a): the session's own sign-in accounts, which
+ * the account Security tab reads to say whether the person has a password.
+ * The hub render loads `auth.ts` only when it is called; a spoke has no local
+ * accounts, so its renders answer `null` and import nothing.
+ */
+function ownAccountsReader(topology) {
+    if (topology === "hub") {
+        return `export async function readOwnAccounts(
+  headers: Headers,
+): Promise<ReadonlyArray<{ providerId: string }> | null> {
+  const { auth } = await import("../auth");
+  return auth.api.listUserAccounts({ headers });
+}`;
+    }
+    return `export function readOwnAccounts(headers: Headers): Promise<ReadonlyArray<{ providerId: string }> | null> {
+  void headers;
+  return Promise.resolve(null);
+}`;
+}
 /** The sign-in exports every web seam render carries (#7894 D8). */
 function signInExports(values) {
     const literal = (value) => value === null ? "null" : JSON.stringify(value);
@@ -310,13 +334,62 @@ 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)};`;
 }
+/** The spoke billing action (#8217 D6), relative to the web seam. */
+const SPOKE_BILLING_ACTION_IMPORT = "../app/[locale]/(authed)/account/billing/spoke-billing.action";
+/** The billing types every web seam render carries (#8217 D7). */
+const SPOKE_BILLING_TYPES = `export type SpokeCard = { brand: string; last4: string; expMonth: number; expYear: number };
+
+export type SpokeBillingRead =
+  | {
+      kind: "subscription";
+      status: "trialing" | "active" | "past_due" | "canceled";
+      planName: string | null;
+      paymentMethod: SpokeCard | null;
+      unreadable: boolean;
+    }
+  | { kind: "none"; unreadable: boolean }
+  | { kind: "failed" };
+
+export type SpokeBilling = {
+  read(): Promise<SpokeBillingRead>;
+  portalUrl(): Promise<string | null>;
+};`;
+/**
+ * `loadSpokeBilling` (#8217 D7): the billing render imports the action, by a
+ * dynamic import, so a module that reads this seam for a constant never
+ * loads the checkout package; every other render resolves `null`.
+ */
+function spokeBillingLoader(spokeBilling) {
+    if (!spokeBilling) {
+        return `${SPOKE_BILLING_TYPES}
+
+export function loadSpokeBilling(): Promise<SpokeBilling | null> {
+  return Promise.resolve(null);
+}`;
+    }
+    return `${SPOKE_BILLING_TYPES}
+
+export async function loadSpokeBilling(): Promise<SpokeBilling | null> {
+  const { readSpokeBilling, spokeBillingPortalUrl } = await import(
+    "${SPOKE_BILLING_ACTION_IMPORT}"
+  );
+  return { read: readSpokeBilling, portalUrl: spokeBillingPortalUrl };
+}`;
+}
 /**
  * `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.
+ * loads Better Auth. `opts.spokeBilling` (#8217 D7) makes `loadSpokeBilling`
+ * reach the spoke billing action — only on a spoke that signs in through its
+ * hub, the one render whose account area can call it.
+ * @throws TopologyError for `spokeBilling` on a hub or a default-mode spoke.
  */
-export function renderWebSeam(topology, signIn = "off") {
+export function renderWebSeam(topology, signIn = "off", opts = {}) {
+    const spokeBilling = opts.spokeBilling === true;
+    if (spokeBilling && (topology !== "spoke" || signIn !== "hub")) {
+        throw new TopologyError("the spoke billing loader renders only on a spoke that signs in through its hub (--hub-sign-in)");
+    }
     if (topology === "hub") {
         return `${WEB_SEAM_HEADER}
 
@@ -331,10 +404,14 @@ export async function readSession(headers: Headers): Promise<SiteSession> {
   return auth.api.getSession({ headers });
 }
 
+${ownAccountsReader("hub")}
+
 export async function registerSiteStores(): Promise<void> {
   const { registerLicenseKeyStore } = await import("./license-key-store");
   await registerLicenseKeyStore();
 }
+
+${spokeBillingLoader(false)}
 `;
     }
     if (signIn === "hub") {
@@ -351,9 +428,13 @@ export function readSession(headers: Headers): Promise<SiteSession> {
   return readHubSession(headers);
 }
 
+${ownAccountsReader("spoke")}
+
 export function registerSiteStores(): Promise<void> {
   return Promise.resolve();
 }
+
+${spokeBillingLoader(spokeBilling)}
 `;
     }
     return `${WEB_SEAM_HEADER}
@@ -369,9 +450,13 @@ export function readSession(headers: Headers): Promise<SiteSession> {
   return Promise.resolve(null);
 }
 
+${ownAccountsReader("spoke")}
+
 export function registerSiteStores(): Promise<void> {
   return Promise.resolve();
 }
+
+${spokeBillingLoader(false)}
 `;
 }
 const AUTHED_GATE_SEAM_HEADER = `// signed-out-gate.generated.tsx — what the (authed) group shows a signed-out visitor.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ailk",
-  "version": "0.18.0",
+  "version": "0.19.1",
   "description": "Scaffolder for AI Launch Kit — `pnpm create ailk@latest <dir>` produces a starter repo consuming @working-theory/* from npm (per ADR 0007).",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,7 +18,8 @@
     "component-catalog.json",
     "component-catalog.md",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "NOTICE"
   ],
   "publishConfig": {
     "access": "public"
@@ -27,8 +28,8 @@
     "tar": "^7.5.21"
   },
   "devDependencies": {
-    "@working-theory/templates": "0.38.0",
-    "@working-theory/schema": "0.38.0"
+    "@working-theory/schema": "0.40.0",
+    "@working-theory/templates": "0.40.0"
   },
   "repository": {
     "type": "git",

package/templates/.env.example

@@ -9,9 +9,9 @@ AILK_PUBLIC_DOMAIN=ailaunchkit.ai
 # STEALTH defaults to "true" for new installs so a freshly-deployed instance
 # isn't indexed by crawlers or unfurled by Slack/Twitter/LinkedIn before the
 # operator is ready. Three layers gate on this single flag:
-#   1. apps-paid/marketing-web/public/robots.txt (always-blocking static file)
-#   2. X-Robots-Tag: noindex, nofollow, noarchive HTTP header (next.config.ts)
-#   3. <meta name="robots" content="noindex,nofollow"> tag (app/layout.tsx)
+#   1. robots.txt answers "Disallow: /" for every crawler (apps/web/app/robots.txt/route.ts)
+#   2. X-Robots-Tag: noindex, nofollow, noarchive HTTP header (apps/web/next.config.mjs)
+#   3. <meta name="robots" content="noindex,nofollow"> tag (apps/web/app/[locale]/layout.tsx)
 # At launch, set STEALTH=false on the hosting platform's env vars and redeploy.
 # See README.md § "Going live" for the full flip checklist.
 STEALTH=true

package/templates/.github/workflows/ci.yml

@@ -54,4 +54,9 @@ jobs:
 
       - run: pnpm test
 
+      # apps/web's `next build` with the docs module outgrows Node's default
+      # ~2 GB heap and aborts with "JavaScript heap out of memory" (#8069).
+      # The hosted runner has ~7 GB; give the build room.
       - run: pnpm build
+        env:
+          NODE_OPTIONS: --max-old-space-size=6144

package/templates/apps/api/.env.example

@@ -32,8 +32,14 @@ DATABASE_URL="postgresql://user:password@localhost:5432/customer_template"
 # Stripe (Optional)
 # =============================================================================
 # Consumed by apps/api/src/lib/stripe.ts via @working-theory/stripe-client wrapper.
-# Use sandbox keys only — live-mode keys are rejected at runtime.
+# Use sandbox keys only — live-mode keys are rejected at runtime, unless
+# STRIPE_MODE=live below admits a restricted live key (#8450).
 STRIPE_SECRET_KEY=sk_test_xxx
+# test (the default when unset) or live. `live` is admitted only beside a
+# restricted live key, on a production build — VERCEL_ENV=production, or,
+# off Vercel, NODE_ENV=production, so a staging host must not set the latter.
+# Every other live key stays refused at boot and on every route.
+STRIPE_MODE=test
 STRIPE_WEBHOOK_SECRET=whsec_xxx
 
 # =============================================================================
@@ -46,6 +52,16 @@ STRIPE_WEBHOOK_SECRET=whsec_xxx
 # Generate with: openssl rand -hex 32
 # OSS_API_INTERNAL_SECRET=your-shared-secret-here
 
+# =============================================================================
+# Consent — the signed unsubscribe link (#8438)
+# =============================================================================
+# Keys the HMAC on the unsubscribe token an email's link carries
+# (POST /v1/consent/unsubscribe). Optional: unset, no link can be minted and the
+# route answers 503 link_secret_not_configured. When set it must be at least
+# 32 bytes — a shorter value logs an error at boot and is treated as unset.
+# Generate with: openssl rand -hex 32
+# AILK_CONSENT_LINK_SECRET=
+
 # =============================================================================
 # Scheduling — the `booker` section's provider (#4416)
 # =============================================================================