create-ailk 0.1.0 → 0.2.0

package/templates/.claude/skills/scaffold-commerce/templates/subscription-route.template.ts

@@ -0,0 +1,446 @@
+/**
+ * Subscription routes — instantiated by `scaffold-commerce`'s
+ * surface-selection branch (SKILL.md § Step 10h, FEAT-023 U5) into the
+ * consumer's own `apps/api`. Lands at, e.g.,
+ * `apps/api/src/routes/commerce/subscriptions.ts`. TWO handlers with
+ * DELIBERATELY OPPOSITE auth postures — do not register them in the same
+ * scope:
+ *
+ *   1. `subscribeHandler` — a PUBLIC, unauthenticated "subscribe" action.
+ *      Mirrors `checkout-route.template.ts` exactly (this surface reuses
+ *      `createCheckoutSession()`, pinned `mode: "subscription"` — spec §3
+ *      design decision: no parallel subscription client module).
+ *   2. `subscriptionRoutes` — an ADMIN + TENANT-GUARDED Fastify plugin
+ *      exposing the subscription-status READ. Mirrors
+ *      `invoice-route.template.ts`'s `requireSiteAdmin` +
+ *      `requireSingleTenantScope` guards verbatim (spec §5.3 escalation
+ *      boundary: "retrieve-on-view is the v1 default, mirroring U4" — no
+ *      subscription webhook is scaffolded at v1).
+ *
+ * Registration (BOTH required, in DIFFERENT scopes):
+ *
+ *     // 1. subscribeHandler — public, rate-limited (mirrors checkout):
+ *     await fastify.register(async (subscribeScope) => {
+ *       subscribeScope.register(rateLimitMiddleware); // apps/api/src/middleware/rate-limit.ts
+ *       subscribeScope.post("/api/subscriptions/subscribe", subscribeHandler);
+ *     });
+ *
+ *     // 2. subscriptionRoutes — tenant-guarded admin read (mirrors invoices):
+ *     await tenantScope.register(subscriptionRoutes);
+ *
+ * ── Auth posture — split by handler, on purpose ─────────────────────────────
+ * `subscribeHandler` is a storefront "subscribe" action — the recurring-price
+ * analog of `checkout-route.template.ts`'s one-time "buy" action. It is
+ * intentionally UNAUTHENTICATED and does exactly ONE thing: create a NEW
+ * Stripe Checkout Session (`mode: "subscription"`, pinned — never
+ * caller-overridable) for ONE OF THE RECURRING PRICES this surface was
+ * scaffolded to sell (`ALLOWED_LOOKUP_KEYS`, enforced server-side before any
+ * Stripe call). It has NO list/read of existing subscriptions, no
+ * update/cancel — see `subscriptionRoutes` below for that, and see the
+ * "point management at the U6 portal" design decision (spec §3): this surface
+ * never builds self-service cancel/change, it only shows state + a portal
+ * link (`packages/ui`'s `SubscriptionStatus`).
+ *
+ * `subscriptionRoutes` READS an existing subscription's status — a
+ * MANAGEMENT-shaped action, so it is authenticated + site-admin + tenant
+ * guarded, the OPPOSITE of `subscribeHandler`'s public posture. Do not copy
+ * `subscribeHandler`'s public registration for it.
+ *
+ * ── Entitlement is NOT authorization (repeats the AILK#3744 lesson) ─────────
+ * `assertCommerceEntitled()`/`hasFeature("commerce")` answers "does this
+ * DEPLOYMENT have commerce?", never "is this caller allowed to do this?" — it
+ * is a SCAFFOLD-TIME check (this file is not emitted without
+ * `feature:commerce`); there is deliberately no runtime entitlement call
+ * here, and none is claimed for either handler.
+ *
+ * ── v1 tenancy limitation (mirrors invoice-route.template.ts verbatim) ──────
+ * `loadStripeSurfaceConfig()` resolves ONE deployment-wide
+ * `STRIPE_SECRET_KEY` and v1 has NO per-organization Stripe customer
+ * namespace (see `docs/research/commerce-template-audit/subscriptions.md`).
+ * A subscription therefore carries no org attribution, so on a multi-tenant
+ * deployment there is no honest way to decide whether a caller-supplied
+ * `subscriptionId` belongs to the caller's org. `requireSingleTenantScope`
+ * admits ONLY the deployment's own operator org (the fixed single-tenant
+ * sentinel `DEFAULT_ORG_ID`) and REFUSES every tenant org's admin outright —
+ * subscription-status reading is an OPERATOR surface at v1, not a per-tenant
+ * self-service one. Lifting the refusal needs a per-org Stripe Connect /
+ * customer-namespace model (tracked follow-up, not silently claimed fixed).
+ *
+ * TEST-MODE ONLY (v1), and the live-key guard has no remaining gap.
+ * `assertSandboxKey` (`packages/stripe-client/src/client.ts`) is an ALLOW-LIST
+ * as of AILK#3734: it accepts only `sk_test_`, `pk_test_` and `rk_test_` and
+ * refuses everything else, so a restricted live key and any future live prefix
+ * are refused by construction. It is a shared file outside this template's
+ * scope; both handlers below inherit that coverage via
+ * `loadStripeSurfaceConfig()` + `getStripeClient()`, never a second/divergent
+ * prefix check.
+ */
+import { DEFAULT_ORG_ID } from "@working-theory/database/tenancy";
+import type {
+  FastifyPluginAsync,
+  FastifyReply,
+  FastifyRequest,
+} from "fastify";
+import { z } from "zod";
+
+import {
+  createCheckoutSession,
+  retrieveSubscriptionStatus,
+  StripeConfigError,
+  UnknownProductCodeError,
+} from "@working-theory/stripe-client";
+
+import { prisma } from "../../lib/prisma.js";
+import { loadStripeSurfaceConfig } from "./stripe-config.js";
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 1. subscribeHandler — PUBLIC "subscribe" action (mirrors checkout-route)
+// ═══════════════════════════════════════════════════════════════════════════
+
+// ── Purchasable-plan allowlist — SCAFFOLD-TIME EDIT ───────────────────────────
+//
+// The ONLY recurring lookup_keys this surface is allowed to sell. Without
+// this allowlist the route resolves a caller-supplied `lookupKey` against
+// the merchant's ENTIRE Stripe account — the exact one-time-checkout hole
+// closed in PR #3733, applied here for the subscription surface. Step 10h
+// replaces the placeholder below with the recurring lookup_key(s) the
+// consumer selected. Until it does, EVERY subscribe request 404s.
+const ALLOWED_LOOKUP_KEYS: ReadonlySet<string> = new Set<string>([
+  "REPLACE_WITH_YOUR_RECURRING_STRIPE_LOOKUP_KEY",
+]);
+
+const LOOKUP_KEY_REGEX = /^[A-Za-z0-9._-]{1,200}$/;
+const REDIRECT_MAX_LENGTH = 2048;
+
+const SubscribeRequestSchema = z.object({
+  lookupKey: z
+    .string()
+    .regex(LOOKUP_KEY_REGEX, "lookupKey must match /^[A-Za-z0-9._-]{1,200}$/"),
+  successUrl: z
+    .string()
+    .min(1, "successUrl is required")
+    .max(REDIRECT_MAX_LENGTH, "successUrl is too long"),
+  cancelUrl: z
+    .string()
+    .min(1, "cancelUrl is required")
+    .max(REDIRECT_MAX_LENGTH, "cancelUrl is too long"),
+});
+
+/** Site's own origin — the ONLY origin a checkout redirect may resolve to (mirrors checkout-route.template.ts). */
+function loadSiteOrigin(): URL {
+  const raw = process.env.FRONTEND_URL;
+  if (!raw) {
+    throw new Error(
+      "FRONTEND_URL is missing. It is the site origin checkout redirects are locked to.",
+    );
+  }
+  try {
+    return new URL(raw);
+  } catch {
+    throw new Error("FRONTEND_URL is not a valid absolute URL.");
+  }
+}
+
+/** Resolves a caller-supplied redirect against the site's own origin, or null (mirrors checkout-route.template.ts). */
+function toSameOriginRedirect(raw: string, siteOrigin: URL): string | null {
+  let resolved: URL;
+  try {
+    resolved = new URL(raw, siteOrigin);
+  } catch {
+    return null;
+  }
+  if (resolved.protocol !== "https:" && resolved.protocol !== "http:") {
+    return null;
+  }
+  if (resolved.origin !== siteOrigin.origin) {
+    return null;
+  }
+  return resolved.toString();
+}
+
+/**
+ * POST handler — creates a test-mode SUBSCRIPTION (`mode: "subscription"`,
+ * pinned) Checkout Session for `lookupKey` and returns `{ sessionId, url }`.
+ * The caller (the scaffolded `PricingTable` section's `onSubscribe`)
+ * redirects the browser to `url` on success.
+ *
+ * @public-by-design — a storefront "subscribe" action, intentionally
+ * UNAUTHENTICATED (the recurring-price analog of checkout's public "buy"; see
+ * the file-header "Auth posture" note). It creates ONE allowlisted
+ * subscription Checkout Session and reads/mutates nothing else. Its ADMIN
+ * sibling `subscriptionRoutes` below is identity + tenant guarded — the marker
+ * exempts ONLY this handler (route-template-auth-gate, #3751), never the file.
+ */
+export async function subscribeHandler(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  let siteOrigin: URL;
+  try {
+    if (!process.env.STRIPE_SECRET_KEY || !process.env.STRIPE_PUBLISHABLE_KEY) {
+      throw new Error(
+        "STRIPE_SECRET_KEY / STRIPE_PUBLISHABLE_KEY are missing. Run scaffold-commerce (direct payments path) first.",
+      );
+    }
+    siteOrigin = loadSiteOrigin();
+    loadStripeSurfaceConfig();
+  } catch (err) {
+    if (err instanceof StripeConfigError) {
+      request.log.error(
+        { method: request.method, path: request.url, message: err.message },
+        "[subscriptions] subscribe: LIVE Stripe key REFUSED — live-mode-forbidden",
+      );
+      return reply.status(500).send({ error: "live-mode-forbidden" });
+    }
+    request.log.error(
+      {
+        method: request.method,
+        path: request.url,
+        message: err instanceof Error ? err.message : "unknown",
+      },
+      "[subscriptions] subscribe: config error",
+    );
+    return reply.status(500).send({ error: "config-error" });
+  }
+
+  const parsed = SubscribeRequestSchema.safeParse(request.body);
+  if (!parsed.success) {
+    return reply.status(400).send({
+      error: "validation-error",
+      details: parsed.error.issues,
+    });
+  }
+
+  const { lookupKey, successUrl, cancelUrl } = parsed.data;
+
+  if (!ALLOWED_LOOKUP_KEYS.has(lookupKey)) {
+    request.log.warn(
+      { method: request.method, path: request.url, status: 404 },
+      "[subscriptions] subscribe: lookupKey is not in this surface's allowlist; refused",
+    );
+    return reply.status(404).send({ error: "unknown-product-code" });
+  }
+
+  const safeSuccessUrl = toSameOriginRedirect(successUrl, siteOrigin);
+  const safeCancelUrl = toSameOriginRedirect(cancelUrl, siteOrigin);
+  if (safeSuccessUrl === null || safeCancelUrl === null) {
+    request.log.warn(
+      { method: request.method, path: request.url, status: 400 },
+      "[subscriptions] subscribe: redirect URL is not same-origin; refused",
+    );
+    return reply.status(400).send({ error: "invalid-redirect-url" });
+  }
+
+  try {
+    // Pinned mode: "subscription" — this endpoint can never open a one-time
+    // checkout session, regardless of caller input (spec §3 design decision).
+    const { sessionId, url } = await createCheckoutSession({
+      productCode: lookupKey,
+      successUrl: safeSuccessUrl,
+      cancelUrl: safeCancelUrl,
+      mode: "subscription",
+    });
+
+    request.log.info(
+      {
+        method: request.method,
+        path: request.url,
+        sessionIdPrefix: sessionId.substring(0, 8),
+        status: 201,
+      },
+      "[subscriptions] subscribe: session created",
+    );
+
+    return reply.status(201).send({ sessionId, url });
+  } catch (err) {
+    if (err instanceof UnknownProductCodeError) {
+      return reply.status(404).send({ error: "unknown-product-code" });
+    }
+    if (err instanceof StripeConfigError) {
+      request.log.error(
+        {
+          method: request.method,
+          path: request.url,
+          errName: err.name,
+          message: err.message,
+        },
+        "[subscriptions] subscribe: config error",
+      );
+      return reply.status(500).send({ error: "config-error" });
+    }
+    request.log.error(
+      {
+        method: request.method,
+        path: request.url,
+        errName: err instanceof Error ? err.name : "unknown",
+      },
+      "[subscriptions] subscribe: stripe error; checkout-unavailable",
+    );
+    return reply.status(502).send({ error: "checkout-unavailable" });
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 2. subscriptionRoutes — ADMIN + TENANT-GUARDED status read (mirrors
+//    invoice-route.template.ts's guards verbatim)
+// ═══════════════════════════════════════════════════════════════════════════
+
+function unauthorized(reply: FastifyReply): void {
+  reply.status(401).send({
+    ok: false,
+    error: { code: "unauthorized", message: "Authentication required." },
+  });
+}
+
+function forbidden(reply: FastifyReply): void {
+  reply.status(403).send({
+    ok: false,
+    error: { code: "forbidden", message: "Admin access required." },
+  });
+}
+
+/** Identical for EVERY request — leaks no information about which subscriptions exist (no enumeration oracle). */
+function tenancyUnsupported(reply: FastifyReply): void {
+  reply.status(403).send({
+    ok: false,
+    error: {
+      code: "tenancy_unsupported",
+      message:
+        "Subscription-status reading is unavailable on a multi-tenant deployment: v1 has no per-organization Stripe customer namespace, so a subscription cannot be attributed to an organization.",
+    },
+  });
+}
+
+function invalidBody(reply: FastifyReply): void {
+  reply.status(400).send({
+    ok: false,
+    error: { code: "invalid_body", message: "Invalid request." },
+  });
+}
+
+function serverError(reply: FastifyReply): void {
+  // Never echo the raw Stripe/internal error — it may embed request params.
+  reply.status(500).send({
+    ok: false,
+    error: { code: "internal_error", message: "Something went wrong." },
+  });
+}
+
+/**
+ * The site-admin role set. `User.role` is a per-deployment String
+ * ("user" | "admin" | "owner") — DISTINCT from the org-membership `Role` enum
+ * the multi-tenant module uses. Named rather than compared inline so the next
+ * role change is one greppable edit per template; mirrored from
+ * `payment-link-route.template.ts:135` because these are copied-not-imported
+ * scaffold sources with nowhere to share a constant (AILK#3765).
+ */
+const SITE_ADMIN_ROLES: ReadonlySet<string> = new Set(["admin", "owner"]);
+
+/**
+ * Gate 1 — requires an authenticated, site-admin caller. `request.userId` is
+ * populated by `authPreHandlerPlugin` (see the Registration note above); this
+ * re-checks it defensively. Sends the 401/403 itself and returns `null` on
+ * denial; the caller's handler must `return` immediately when this returns
+ * `null`.
+ */
+async function requireSiteAdmin(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<string | null> {
+  const userId = request.userId;
+  if (!userId) {
+    unauthorized(reply);
+    return null;
+  }
+
+  let role: string | undefined;
+  try {
+    const user = await prisma.user.findUnique({
+      where: { id: userId },
+      select: { role: true },
+    });
+    role = user?.role;
+  } catch (err) {
+    // FAIL CLOSED. Never `catch {}` into the happy path.
+    //
+    // Unwrapped, a rejection here escapes to Fastify's default error handler,
+    // which serializes `error.message` back to the caller — contradicting this
+    // file's own no-raw-echo contract. It always denied; it denied while
+    // leaking.
+    request.log.error(
+      {
+        method: request.method,
+        path: request.url,
+        message: err instanceof Error ? err.message : "unknown",
+      },
+      "[subscriptions] role resolution failed; DENYING",
+    );
+    serverError(reply);
+    return null;
+  }
+
+  // A missing user row (deleted account, stale session) has no role -> denied.
+  if (!role || !SITE_ADMIN_ROLES.has(role)) {
+    forbidden(reply);
+    return null;
+  }
+
+  return userId;
+}
+
+/**
+ * Gate 2 — the tenancy guard. v1 resolves ONE deployment-wide
+ * `STRIPE_SECRET_KEY` and has no per-org Stripe customer namespace, so a
+ * subscription carries no organization attribution — this guard admits ONLY
+ * the deployment's own operator org (the fixed single-tenant sentinel
+ * `DEFAULT_ORG_ID`) and refuses everyone else, before any Stripe call.
+ * Mirrors `invoice-route.template.ts`'s `requireSingleTenantScope` verbatim.
+ */
+async function requireSingleTenantScope(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<boolean> {
+  const tenant = request.tenant;
+  if (!tenant) {
+    forbidden(reply);
+    return false;
+  }
+
+  if (tenant.organizationId !== DEFAULT_ORG_ID) {
+    tenancyUnsupported(reply);
+    return false;
+  }
+
+  return true;
+}
+
+const statusQuerySchema = z.object({
+  subscriptionId: z.string().min(1).max(255),
+});
+
+/**
+ * `subscriptionRoutes` — a single GET endpoint: retrieve-on-view by the
+ * subscription's own Stripe id (spec §5.3 escalation boundary — no
+ * subscription webhook is scaffolded at v1; mirrors
+ * `invoice-route.template.ts`'s `?invoiceId=` shape).
+ */
+export const subscriptionRoutes: FastifyPluginAsync = async (fastify) => {
+  // GET /v1/commerce/subscriptions?subscriptionId=sub_...
+  fastify.get("/v1/commerce/subscriptions", async (request, reply) => {
+    if (!(await requireSiteAdmin(request, reply))) return;
+    if (!(await requireSingleTenantScope(request, reply))) return;
+
+    const query = statusQuerySchema.safeParse(request.query);
+    if (!query.success) return invalidBody(reply);
+
+    try {
+      loadStripeSurfaceConfig();
+      const status = await retrieveSubscriptionStatus({
+        subscriptionId: query.data.subscriptionId,
+      });
+      return reply.send({ ok: true, data: status });
+    } catch {
+      return serverError(reply);
+    }
+  });
+};

package/templates/.claude/skills/suggest-site-pages/references/categories.md

@@ -2,8 +2,8 @@
 
 The 10 business categories `suggest-site-pages` knows about, with the
 ordered page list and primary schema.org type for each page. Schemas
-are drawn from the 45 types `@working-theory/schema` builds; nothing in this
-file should reference a type the package can't generate.
+are drawn from the 60 page types `@working-theory/schema` builds; nothing in
+this file should reference a type the package can't generate.
 
 ## How to read this file
 
@@ -275,7 +275,7 @@ operates as an entity.
 
 Every `Schema.orgType` referenced above is a member of the
 `SchemaOrgType` union exported by `@working-theory/schema` and has a builder
-function. The v1 catalog uses 21 of the 45 supported types:
+function. The v1 catalog uses 21 of the 60 supported types:
 
 `HomePage`, `AboutPage`, `ContactPage`, `PrivacyPage`, `TermsPage`,
 `Organization`, `Person`, `ServicesList`, `Service`, `ProductsList`,
@@ -283,5 +283,5 @@ function. The v1 catalog uses 21 of the 45 supported types:
 `EventsList`, `CoursesList`, `Course`, `BlogList`, `BlogPosting`,
 `CaseStudiesList`.
 
-The remaining 24 types are available to `scaffold-page` and `add-schema`
+The remaining 39 types are available to `scaffold-page` and `add-schema`
 for per-page use but don't drive category recommendations.

package/templates/.env.example

@@ -50,8 +50,67 @@ CONTENT_BACKEND=mdx
 # BETTER_AUTH_URL=http://localhost:3000
 # BETTER_AUTH_SECRET=
 
+# ── Single-tenant operator pin (multi-tenant module, apps/api) ───────────────
+# On a single-tenant deployment (the default Workspace exists and is the ONLY
+# Workspace) the FIRST authenticated user to resolve a tenant context is
+# bound as the sole owner (TOFU — trust on first use); every subsequent
+# caller is denied. AILK_OPERATOR_EMAIL is OPTIONAL and pins that binding to
+# one email address instead of "whoever logs in first" — set it when you
+# want to guarantee only a specific operator account can ever become owner.
+# Case-insensitive, trimmed. Leave unset for pure TOFU.
+# AILK_OPERATOR_EMAIL=
+#
+# Belt-and-suspenders: the owner-pin denies any non-operator account at
+# tenant resolution regardless, but for a single-tenant deployment you should
+# also disable open sign-up / configure an OAuth allowlist on your identity
+# provider (or Better Auth's `disableSignUp` option, if you wire it in) so a
+# random account can't even authenticate in the first place.
+
 # ── Email provider (Resend default) ──────────────────────────────────────────
 # RESEND_API_KEY=
+#
+# Lead capture's owner-notification email — read by lead-routing.ts. Both
+# must be set for the operator notification to send; either unset skips it.
+# AILK_LEAD_NOTIFICATION_TO=
+# AILK_LEAD_NOTIFICATION_FROM=
+#
+# Abandon-email's lead-facing sender (#3962). Optional — falls back to
+# AILK_LEAD_NOTIFICATION_FROM when unset. Only needed for flows whose config
+# declares an `abandonEmail` block with `mode:'enabled'`; `mode:'dark'` never
+# sends and needs no sender.
+# AILK_ABANDON_EMAIL_FROM=
+#
+# Deliverable-delivery's lead-facing sender (#3961). Optional — falls back to
+# AILK_LEAD_NOTIFICATION_FROM when unset. Only needed for flows whose config
+# declares a `deliverables` block; unset means the grant still mints but the
+# email send is skipped (log-and-skip, never a lost grant).
+# AILK_DELIVERABLE_EMAIL_FROM=
+#
+# Waitlist follow-up sequence's lead-facing sender (#4732). Optional — falls
+# back to AILK_LEAD_NOTIFICATION_FROM when unset. Only needed for flows whose
+# config declares a `followUps` block.
+# AILK_FOLLOWUP_EMAIL_FROM=
+#
+# The Resend Contacts audience the #4732 follow-up sweep checks before
+# sending — a lead found unsubscribed in this audience is suppressed.
+# Optional: unset degrades to "cannot verify — proceed" (never to "block all
+# sends"), since nothing in this repo syncs leads into a Resend audience by
+# default.
+# RESEND_AUDIENCE_ID=
+#
+# The public base URL this API is reachable at — used ONLY to build the
+# deliverable-delivery download link (#3961 D5):
+# `${AILK_PUBLIC_API_URL}/v1/deliverables/:grantId`. Unset means a relative
+# link (base ""), which is not usable from an email client — set this in any
+# deployment that uses the `deliverables` block.
+# AILK_PUBLIC_API_URL=
+#
+# The apps/api origin @working-theory/api-client calls from
+# apps-paid/marketing-web's SERVER (RSC + Server Actions) for the pricing
+# recommender's /v1/flows/* routes (#4884). Unset means /pricing makes no
+# request and serves the manifest content page. Format: https://<host> (no
+# trailing slash). Server-only — never NEXT_PUBLIC_.
+# AILK_API_URL=
 
 # ── Analytics ────────────────────────────────────────────────────────────────
 # All providers off by default. Set the env var(s) for any provider(s) you want.
@@ -188,8 +247,9 @@ CONTENT_BACKEND=mdx
 # Allowlist format: comma-separated user IDs (exact-match strings; no regex,
 # no wildcard). Empty entries between commas are trimmed.
 # Run `pnpm --filter @working-theory/database db:seed:test` to seed three test users
-# (test-e2e-user / test-e2e-admin / test-e2e-owner — distinguished by the
-# Better Auth `role` field). The seed script itself refuses to run unless
+# (user_00000000-0000-7000-8000-0000000000e1 / …e2 / …e3 — reserved-range
+# prefixed ids per ADR-0031, distinguished by the Better Auth `role` field).
+# The seed script itself refuses to run unless
 # AILK_TEST_AUTH_ENABLED === "true".
 #
 # AILK_TEST_AUTH_ENABLED=
@@ -203,3 +263,67 @@ CONTENT_BACKEND=mdx
 # LEAD_CAPTURE_FILE_DISABLED=false
 # Set to "true" to include the submitter's IP in metadata (default: off for privacy).
 # LEAD_CAPTURE_INCLUDE_IP=false
+
+# ── Instant AEO score service (#4666) ─────────────────────────────────────────
+# Total crawl wall-clock budget (ms) for POST /v1/aeo/score. Must leave
+# cold-start headroom inside the deployment's function timeout (assumed
+# >= 10s) and stay below the handler's 25s request guard — a value above
+# 15000 is rejected on each request (logged once per request, falls back
+# to the default below; there is no persistent startup phase to check
+# this once in a serverless deployment).
+# AEO_SCORE_BUDGET_MS=6000
+
+# ── Scheduling (the `booker` section, #4416) ──────────────────────────────────
+# Server-side only — read inside apps/api, never exposed to the browser.
+# Unset is a supported state: the booker degrades to the provider's own
+# booking page. Full notes in apps/api/.env.example.
+# CAL_API_KEY=cal_live_xxx
+# CAL_API_BASE_URL=https://api.cal.com
+# SCHEDULING_PUBLIC_BASE_URL=https://cal.com
+# SCHEDULING_PROVIDER=cal
+#
+# Which event the /schedule page books, as "<owner>/<event-slug>" (the path of
+# the provider's own public booking page). Read server-side by apps/web; unset
+# means the /schedule route 404s, exactly as if the scheduling module were not
+# installed. Deliberately NOT a NEXT_PUBLIC_ variable — the whole scheduling
+# config surface is server-read.
+# SCHEDULING_CAL_LINK=owner/event-slug
+
+# ── Recommender mode — the purchase hand-off (REL-013, #4762 / #4879) ────────
+# A `recommending` flow's email + checkout moment spans two deployments:
+# apps/api serves POST /v1/flows/:slug/save + /checkout and the Stripe
+# webhook; apps/web runs the Server Action that calls them
+# (app/[locale]/flows/[slug]/checkout.actions.ts). Who sets what, and what
+# happens unset, is tabulated in docs/runbooks/site-configuration.md
+# § Recommender mode. apps/api's three reads are declared above:
+# DATABASE_URL (required — /save + /checkout answer 503 flows_not_configured
+# without it), STRIPE_SECRET_KEY (sk_test_ only — the checkout route refuses
+# any other prefix before its first side effect) and STRIPE_WEBHOOK_SECRET
+# (whsec_ — the completed/expired stamp on the FlowCheckout buyer row).
+#
+# The public origin of THIS site (apps/web). The Stripe success/cancel return
+# URLs are built from it (resolveBaseUrl(), apps/web/src/lib/routes.ts) as
+# `${NEXT_PUBLIC_BASE_URL}/<locale>/flows/<slug>/results/<payload>?checkout=…`;
+# it also drives the llms.txt / sitemap.xml / robots.txt canonical URLs. Unset
+# falls back to https://ailk.example.com — a placeholder host a paying buyer
+# would be returned to after payment. Set on every apps/web deployment that
+# serves a recommending flow. Scheme + host only, no trailing slash.
+# NEXT_PUBLIC_BASE_URL=https://www.example.com
+#
+# apps/api's origin as seen from apps/web's SERVER process — the api-client's
+# base URL (getApiBase(), packages/api-client/src/http.ts) for every flow
+# Server Action call (flows.get / submitStep / save / checkout). AILK_API_URL
+# wins; NEXT_PUBLIC_API_URL is the fallback; both unset resolves to
+# http://localhost:3001 (local dev only — off-localhost every save / checkout
+# call fails as `network`). Distinct from NEXT_PUBLIC_AILK_API_URL
+# (apps/web/.env.example), which BROWSER-side blocks post to directly. Set on
+# every apps/web deployment whose API is not on localhost.
+# AILK_API_URL=http://localhost:3001
+#
+# NEXT_PUBLIC_ENABLED_LOCALES — do NOT set by hand. Baked at build time by
+# apps/web/next.config.mjs from project.yaml `product.locales` (falls back to
+# "en" when project.yaml is absent) and read by middleware.ts, the sitemap
+# route and the flow Server Actions / clients to validate the locale segment
+# of every URL they build. Declared here so the read is not an undocumented
+# dependency; a value set in the platform env is overridden by the build.
+# NEXT_PUBLIC_ENABLED_LOCALES=en

package/templates/CLAUDE.md

@@ -14,7 +14,7 @@ docs/             Project notes (ADRs, architecture, planning)
 ```
 
 You consume `@working-theory/*` packages from npm. Source for those packages is at
-<https://github.com/tailwind-ai/ai-launch-kit>; you don't have it locally.
+<https://github.com/working-theory-labs/ai-launch-kit>; you don't have it locally.
 Treat each `@working-theory/*` package as a third-party dependency — read its README
 or its types, don't go looking for the source.
 
@@ -108,9 +108,15 @@ checking what `@working-theory/schema` exports.
 These are non-negotiable in this repo. Don't ask, don't try to route
 around them.
 
-- **No live Stripe keys in code.** `sk_live_*` and `pk_live_*` belong in
-  the deployment platform's secrets store, never in `.env`, source files,
-  or commit messages. Use Stripe sandbox keys for everything in source.
+- **No live Stripe keys in code.** The runtime guard is an ALLOW-LIST, not
+  a list of banned prefixes: it accepts only recognized test-mode keys
+  (`sk_test_`, `pk_test_`, `rk_test_`) and refuses everything else. Every
+  live key is therefore refused — a restricted key (`rk_live_`) and any
+  prefix Stripe introduces later included — because it is absent from the
+  allow-list, not because someone remembered to ban it. Live keys belong
+  in the deployment platform's secrets store, never in `.env`, source
+  files, or commit messages. Use Stripe sandbox keys for everything in
+  source.
 - **No secrets in commits.** API keys, license keys, database URLs — all
   go through `.env.local` (gitignored) for local dev and the deployment
   platform's secrets store for prod.
@@ -127,7 +133,7 @@ when:
 
 - An architecture invariant would have to bend.
 - A change to a shared `@working-theory/*` package would be needed (file an issue
-  upstream at <https://github.com/tailwind-ai/ai-launch-kit>; don't fork).
+  upstream at <https://github.com/working-theory-labs/ai-launch-kit>; don't fork).
 - You're about to delete or move >5 files at once.
 - The acceptance criteria contradict each other or the existing code.
 

package/templates/README.md

@@ -105,6 +105,6 @@ If you need to override a section component, swap its registration in the sectio
 
 Your project — `{{PROJECT_NAME}}`, owned by {{COMPANY_NAME}} ({{COMPANY_DOMAIN}}) — is yours. Pick whatever license suits you.
 
-The AI Launch Kit framework upstream is **Apache 2.0** — see <https://github.com/tailwind-ai/ai-launch-kit/blob/main/LICENSE>. Contributions are welcome at the upstream repo; start with the [contributing guide](https://github.com/tailwind-ai/ai-launch-kit/blob/main/CONTRIBUTING.md).
+The AI Launch Kit framework upstream is **Apache 2.0** — see <https://github.com/working-theory-labs/ai-launch-kit/blob/main/LICENSE>. Contributions are welcome at the upstream repo; start with the [contributing guide](https://github.com/working-theory-labs/ai-launch-kit/blob/main/CONTRIBUTING.md).
 
 For the full handbook, examples, and Pro features: <https://ailaunchkit.ai>.