create-ailk 0.20.0 → 0.22.0

package/templates/apps/api/src/services/person.ts

@@ -13,6 +13,10 @@
  *     match, never overwriting a link.
  *   - `recordCheckoutPerson` — the webhook's step: the Person of a completed
  *     hub checkout, with its live-mode customer id.
+ *     `resolveCheckoutPerson` is the same step answering that Person too, for
+ *     the checkout's terms grant (#8765 D14); the webhook calls it, and
+ *     `recordCheckoutPerson` stays as its outcome-only form for the #852
+ *     suites that pin that outcome.
  *   - `resolveMemberPersonId` — the member reads' Person (#7877 D8): the one
  *     linked to the caller, else the one whose email is the caller's
  *     verified email, linked on first read by `stampPersonUser`'s rule.
@@ -768,6 +772,13 @@ export type CheckoutPersonOutcome =
   | "person_skipped"
   | "person_failed";
 
+/** `recordCheckoutPerson`'s outcome plus the Person it found or created (#8765 D14). */
+export type CheckoutPersonResult = {
+  outcome: CheckoutPersonOutcome;
+  /** The checkout's Person, or `null` when the step skipped or failed. */
+  person: { workspaceId: string; personId: string } | null;
+};
+
 /**
  * The hub webhook's Person step for a paid `checkout.session.completed` of
  * its OWN site carrying `metadata.flowCheckoutId`.
@@ -786,8 +797,23 @@ export async function recordCheckoutPerson(input: {
   customer: unknown;
   livemode: boolean;
 }): Promise<CheckoutPersonOutcome> {
+  return (await resolveCheckoutPerson(input)).outcome;
+}
+
+/**
+ * `recordCheckoutPerson`, also answering the Person it found or created —
+ * the subject of the checkout's terms grant (#8765 D14), which reads the
+ * flow checkout's Person from here and never creates one itself.
+ */
+export async function resolveCheckoutPerson(input: {
+  flowCheckoutId: string;
+  stripeSessionId: string | null | undefined;
+  customer: unknown;
+  livemode: boolean;
+}): Promise<CheckoutPersonResult> {
+  const skipped = { outcome: "person_skipped", person: null } as const;
   if (typeof input.stripeSessionId !== "string" || input.stripeSessionId === "") {
-    return "person_skipped";
+    return skipped;
   }
   try {
     const checkout = await prisma.flowCheckout.findFirst({
@@ -798,13 +824,13 @@ export async function recordCheckoutPerson(input: {
       },
       select: { leadId: true, workspaceId: true },
     });
-    if (!checkout) return "person_skipped";
+    if (!checkout) return skipped;
 
     const lead = await prisma.lead.findFirst({
       where: { id: checkout.leadId, workspaceId: checkout.workspaceId },
       select: { email: true },
     });
-    if (!lead) return "person_skipped";
+    if (!lead) return skipped;
 
     const customerId =
       input.livemode === true && typeof input.customer === "string"
@@ -815,18 +841,24 @@ export async function recordCheckoutPerson(input: {
       ...(customerId !== undefined && { billingCustomerId: customerId }),
     });
     if (!result.ok) {
-      return result.error.kind === "invalid_email" ? "person_skipped" : "person_failed";
+      return result.error.kind === "invalid_email"
+        ? skipped
+        : { outcome: "person_failed", person: null };
     }
+    const person = {
+      workspaceId: checkout.workspaceId,
+      personId: result.value.personId,
+    };
     switch (result.value.billing) {
       case "written":
-        return "person_written";
+        return { outcome: "person_written", person };
       case "kept":
-        return "person_kept";
+        return { outcome: "person_kept", person };
       default:
-        return "person_unchanged";
+        return { outcome: "person_unchanged", person };
     }
   } catch {
-    return "person_failed";
+    return { outcome: "person_failed", person: null };
   }
 }
 

package/templates/apps/api/src/services/plan-offerings.ts

@@ -0,0 +1,59 @@
+/**
+ * The workspace's offerings as plan keys (#8514 D9) — moved here unchanged
+ * from `routes/workspaces/plan.ts` by #8757 D4, so the magnet PATCH's
+ * save-time offering check and the lead route's submit-time re-check
+ * (`services/magnet-completion.ts`) read the same list `GET …/plan-offerings`
+ * serves.
+ *
+ * The workspace's OWN Service then Product pages: `key` is the page slug's
+ * last segment when it is an offering key (else the page is skipped), the
+ * first page per key wins, at most 200; `name` is the page title. Off the
+ * database content adapter only the default workspace has content
+ * (`workspaceContentAdapter`), so every other workspace reads `[]`.
+ *
+ * Never throws: a failed content read answers `{ failed }` with the error's
+ * class name only, so a caller can tell "none published" from "could not
+ * tell" — a failure is never a pass.
+ *
+ * Base tree (SEC-8757-D): no `oss: false` marker and no `MODULE_SLICES`
+ * entry, because the never-gate lead route reaches it.
+ */
+import {
+  PLAN_OFFERINGS_MAX,
+  planOfferingSchema,
+  type PlanOfferingItem,
+} from "@working-theory/validation";
+
+import { workspaceContentAdapter } from "./public-site-resolver.js";
+
+/** The workspace's Service then Product pages as plan keys (D9). */
+export async function listPlanOfferings(
+  workspaceId: string,
+): Promise<PlanOfferingItem[] | { failed: string }> {
+  try {
+    const adapter = await workspaceContentAdapter(workspaceId);
+    if (!adapter) return [];
+    const [services, products] = await Promise.all([
+      adapter.listPages("Service"),
+      adapter.listPages("Product"),
+    ]);
+    const offerings: PlanOfferingItem[] = [];
+    const seen = new Set<string>();
+    const typed = [
+      ...services.map((page) => ({ page, type: "service" as const })),
+      ...products.map((page) => ({ page, type: "product" as const })),
+    ];
+    for (const { page, type } of typed) {
+      if (offerings.length >= PLAN_OFFERINGS_MAX) break;
+      const key = page.slug.split("/").filter(Boolean).pop() ?? "";
+      const name = page.title.trim().slice(0, 200);
+      if (!planOfferingSchema.safeParse(key).success || name === "" || seen.has(key)) continue;
+      seen.add(key);
+      offerings.push({ key, name, type });
+    }
+    return offerings;
+  } catch (error) {
+    // The error's class name only — never its message, which may name a slug.
+    return { failed: error instanceof Error ? error.name : typeof error };
+  }
+}

package/templates/apps/api/src/services/project-listings.ts

@@ -65,6 +65,7 @@ import {
   LISTING_ENTRY_TYPE_DEFAULT,
   PROJECT_LISTING_CONCURRENT_LIMIT,
   PROJECT_LISTING_NON_TERMINAL_STATUSES,
+  RESERVED_FLOW_SLUGS,
 } from "@working-theory/validation";
 import type {
   FlowAddressValue,
@@ -184,6 +185,10 @@ const SLUG_COLLISION_SCAN_LIMIT = 200;
  * free slug and race to the insert; the loser hits the unique constraint and
  * is reported as `slug_taken`, exactly as it was when the client supplied the
  * slug itself.
+ *
+ * #8661 D4 — a listing's slug becomes its diagnostic flow's slug on approval,
+ * so the standard magnets' reserved slugs are treated as taken: a project
+ * named "Contact" is stored at `contact-2`.
  */
 async function firstFreeSlug(siteId: string, base: string): Promise<string> {
   const rows = await prisma.projectListing.findMany({
@@ -191,7 +196,7 @@ async function firstFreeSlug(siteId: string, base: string): Promise<string> {
     select: { slug: true },
     take: SLUG_COLLISION_SCAN_LIMIT,
   });
-  const taken = new Set(rows.map((r) => r.slug));
+  const taken = new Set<string | null>([...RESERVED_FLOW_SLUGS, ...rows.map((r) => r.slug)]);
   if (!taken.has(base)) return base;
 
   // Bounded by `taken.size + 1` iterations — one of the first `n` candidates

package/templates/apps/api/src/services/public-site-resolver.ts

@@ -246,7 +246,13 @@ export async function resolveCallerSite(
  * `request.log` only; the routes answer both reasons the same way.
  */
 export type CallerWorkspace =
-  | { kind: "resolved"; workspaceId: string; viaSpoke: boolean }
+  | {
+      kind: "resolved";
+      workspaceId: string;
+      viaSpoke: boolean;
+      /** #8771 D3 — set exactly when `viaSpoke` is true: the registered spoke's id. */
+      spokeId?: string;
+    }
   | { kind: "unresolved"; reason: "spoke-refused" | "alias-unresolved" };
 
 /**
@@ -270,6 +276,7 @@ export async function resolveCallerWorkspace(
       kind: "resolved",
       workspaceId: caller.workspaceId,
       viaSpoke: true,
+      spokeId: caller.spokeId,
     };
   }
   // Deferred, like every database import in this file.

package/templates/apps/mcp/__tests__/catalog-drift.test.ts

@@ -276,71 +276,79 @@ describe("MCP catalog ↔ server drift — UNSERVED_MCP_TOOLS subtracts from the
   });
 });
 
-describe("MCP catalog ↔ server agreement after a bounded re-read (#7156 AC-1)", () => {
-  const priorEnabledModules = process.env.AILK_ENABLED_MODULES;
-
-  beforeEach(() => {
-    process.env.AILK_ENABLED_MODULES = PAID_MODULES;
-    jest.useFakeTimers();
-  });
+describe.each([
+  ["hub", []],
+  ["spoke", ["create_project"]],
+] as const)(
+  "MCP catalog ↔ server agreement after a bounded re-read (#7156 AC-1) — %s seam",
+  (_topology, unserved) => {
+    const priorEnabledModules = process.env.AILK_ENABLED_MODULES;
 
-  afterEach(() => {
-    resetMcpCommerceClaim();
-    jest.useRealTimers();
-    if (priorEnabledModules === undefined) {
-      delete process.env.AILK_ENABLED_MODULES;
-    } else {
-      process.env.AILK_ENABLED_MODULES = priorEnabledModules;
-    }
-  });
+    beforeEach(() => {
+      process.env.AILK_ENABLED_MODULES = PAID_MODULES;
+      mockSeam.unserved = unserved;
+      jest.useFakeTimers();
+    });
 
-  it("a new server and listRegisteredTools() match the catalog once the re-read resolves", async () => {
-    __setMcpFeatureGateForTest("refuse");
-    await initMcpCommerceClaim({
-      checkLicense: resolving({
-        tier: "pro",
-        features: ["scheduling", "flows-deliverables", "commerce"],
-      }),
+    afterEach(() => {
+      resetMcpCommerceClaim();
+      mockSeam.unserved = undefined;
+      jest.useRealTimers();
+      if (priorEnabledModules === undefined) {
+        delete process.env.AILK_ENABLED_MODULES;
+      } else {
+        process.env.AILK_ENABLED_MODULES = priorEnabledModules;
+      }
     });
 
-    const bootOptions: McpCatalogOptions = {
-      addons: { commerce: true },
-      features: ["scheduling", "flows-deliverables"],
-      featureGate: "refuse",
-    };
-    const bootNames = Object.keys(registeredToolsOf(createMcpServer())).sort();
-    expect(bootNames).toEqual(
-      servedCatalog(bootOptions)
+    it("a new server and listRegisteredTools() match the catalog once the re-read resolves", async () => {
+      __setMcpFeatureGateForTest("refuse");
+      await initMcpCommerceClaim({
+        checkLicense: resolving({
+          tier: "pro",
+          features: ["scheduling", "flows-deliverables", "commerce"],
+        }),
+      });
+
+      const bootOptions: McpCatalogOptions = {
+        addons: { commerce: true },
+        features: ["scheduling", "flows-deliverables"],
+        featureGate: "refuse",
+      };
+      const bootNames = Object.keys(
+        registeredToolsOf(createMcpServer()),
+      ).sort();
+      // Both counts below are of the served catalog — the full catalog (20 at
+      // boot, 14 after the re-read) minus this seam's UNSERVED_MCP_TOOLS (#8665).
+      expect(bootNames).toEqual(
+        servedCatalog(bootOptions)
+          .map((t) => t.name)
+          .sort(),
+      );
+      expect(bootNames).toHaveLength(20 - UNSERVED_MCP_TOOLS.length);
+
+      startMcpClaimRefresh({ checkLicense: resolving({ features: [] }) });
+      await jest.advanceTimersByTimeAsync(MCP_CLAIM_REFRESH_MS);
+
+      const refreshedOptions: McpCatalogOptions = {
+        addons: { commerce: false },
+        features: [],
+        featureGate: "refuse",
+      };
+      const servedNames = servedCatalog(refreshedOptions)
         .map((t) => t.name)
-        .sort(),
-    );
-    expect(bootNames).toHaveLength(20 - UNSERVED_MCP_TOOLS.length);
-
-    startMcpClaimRefresh({ checkLicense: resolving({ features: [] }) });
-    await jest.advanceTimersByTimeAsync(MCP_CLAIM_REFRESH_MS);
-
-    const refreshedOptions: McpCatalogOptions = {
-      addons: { commerce: false },
-      features: [],
-      featureGate: "refuse",
-    };
-    const catalogNames = getMcpToolCatalog(refreshedOptions)
-      .map((t) => t.name)
-      .sort();
-    expect(catalogNames).toHaveLength(14);
-
-    const servedNames = servedCatalog(refreshedOptions)
-      .map((t) => t.name)
-      .sort();
+        .sort();
+      expect(servedNames).toHaveLength(14 - UNSERVED_MCP_TOOLS.length);
 
-    const serverNames = Object.keys(
-      registeredToolsOf(createMcpServer()),
-    ).sort();
-    expect(serverNames).toEqual(servedNames);
+      const serverNames = Object.keys(
+        registeredToolsOf(createMcpServer()),
+      ).sort();
+      expect(serverNames).toEqual(servedNames);
 
-    const listedNames = listRegisteredTools()
-      .map((t) => t.name)
-      .sort();
-    expect(listedNames).toEqual(servedNames);
-  });
-});
+      const listedNames = listRegisteredTools()
+        .map((t) => t.name)
+        .sort();
+      expect(listedNames).toEqual(servedNames);
+    });
+  },
+);

package/templates/apps/mcp/jest.config.cjs

@@ -1,5 +1,6 @@
 module.exports = {
   preset: 'ts-jest',
+  globalSetup: require.resolve('../../tools/jest/pin-timezone.cjs'),
   testEnvironment: 'node',
   // Workaround: @hono/node-server@1.19.14 (transitive via
   // @modelcontextprotocol/sdk's StreamableHTTPServerTransport) calls

package/templates/apps/web/.env.example

@@ -92,6 +92,20 @@ CONTENT_ADAPTER=mdx
 # origin the browser never sees.
 # NEXT_PUBLIC_AILK_API_URL=http://localhost:3002
 
+# =============================================================================
+# The /contact lead's site marker (server-side only) — #8747
+# =============================================================================
+# This site's slug. The /contact Server Action writes it into every lead as
+# payload.site (with payload.page = "contact"), so a hub serving several sites
+# — or one site routing leads to two workspaces — can tell where a lead came
+# from. Use the site's short name, lowercase letters, digits and hyphens (for
+# example "wendihenry"); apps/mcp's capture_lead reads the same variable. Unset
+# or blank leaves the lead with no site marker — nothing is invented, and a
+# visitor-sent "site" field is dropped. The marker is attribution only: the
+# lead route is public, so never gate access on it. The action sends no
+# siteId; the API names the workspace itself (by AILK_SPOKE_KEY on a hub).
+# AILK_LEAD_SITE=
+
 # =============================================================================
 # Listicle directory (#7521) — switched on by the site's listing key (#7872)
 # =============================================================================

package/templates/apps/web/CLAUDE.md

@@ -110,6 +110,26 @@ function — the page under test throws instead of taking a branch. Declare
 every predicate the pages call, binding the two reset ones to the same
 `jest.fn()` when the case does not need them to disagree.
 
+**Sign-up agreements are refused and written on the server (#8765).**
+`lib/sign-up-agreements.ts` is a Better Auth plugin plus two database hooks
+that `auth.ts` installs. While `isSignUpOpen()`, `POST /api/auth/sign-up/email`
+without every sign-up agreement in its `agreements` body key answers
+`400 AGREEMENTS_REQUIRED` before the email lookup (so the answer never depends
+on whether the address is taken), and `503 AGREEMENTS_UNAVAILABLE` when the
+API's `GET /v1/consent/sign-up` evidence cannot be read (60 s fresh, 10 min
+stale-on-error, one cache entry per enabled locale). An accepted sign-up — or
+an OAuth sign-up whose state carries the card's agreements — writes one
+`sign_up` grant per agreement through the auth client's transaction
+(`prismaAdapter(…, { transaction: true })`), so the `User`, its `Account` and
+the grants commit together or not at all; this hook is the ledger's only
+writer outside `apps/api`'s `services/consent.ts`, and it writes only rows of
+a user it is creating. A user created without agreements (a first social
+sign-in from `/sign-in`) has none, and the account interstitial asks them
+(`(authed)/account/layout.tsx`, which fails closed on any read but a 2xx or an
+older hub's 404). The carried `__Host-ailk-signup-agreements` cookie is
+retired. Policy links on every agreement surface come from
+`lib/consent-policies.ts`'s `consentPoliciesFor(locale)`.
+
 ## Contact page
 
 The contact page (`apps/web/app/[locale]/contact/page.tsx`) renders the
@@ -123,15 +143,123 @@ the site's contact email, never a form that would report a message as sent
 when it reached nobody. A failed status read counts as accepting, so the
 form renders and its submit reports honestly.
 
+The form's fields come from the workspace's **Contact form magnet** (#8661):
+every workspace is seeded one, live at slug `contact`, and the page is rendered
+on every request (`force-dynamic`) and reads it through the public flow read,
+`flows.get("contact")`, shared across requests for 15 seconds per server
+instance (#8731) — so a burst of views is one hub read, and an Admin edit shows
+within 15 seconds. The capture-status read is shared the same way. The API resolves the workspace (the site alias
+keyless, a spoke by its key), so the page names none. `contact-form-magnet.ts`
+maps the config's first step onto the block's fields, terms statement and
+submit label. The order is: a usable magnet (its first step has `name` and
+`email` fields), else the page's `contact-form` section fields when it
+declares any, else the built-in form, which is the seeded config itself. Any
+failed read (absent, draft, a Free build with no flow route, a throw) is the
+fallback, never an error. A magnet-driven post carries a hidden
+`source: "flow:contact"`, so it is an Inbox submission of the Contact form
+with every answer shown; a fallback post is `contact-form` (#8747). The terms statement
+links Terms, Privacy Policy and Working Agreement from a page-built
+`policies` map, and `captureLeadAction` refuses a post without
+`consent=true` whatever its source (#8730 D2 — the hidden `source` picks the
+stamp, never the gate) and keeps only the contact sources
+(`CONTACT_LEAD_SOURCES`: `contact-form`, `conversational-intake`,
+`flow:contact`). An accepted post sends `consent: true` to the API, which
+refuses a contact lead without it (`400 consent_required`, shown as the same
+field error) and records `payload.consent` itself.
+
+The action writes through `src/lib/lead-write.ts` (#8747), the site's lead
+writer: `payload.site` is `AILK_LEAD_SITE` (none when unset) and
+`payload.page` is `contact`, both spread last so no form field overrides them,
+and no `siteId` is sent. Before the write it runs a per-visitor limit
+(`src/lib/rate-limit.ts`, 30 posts per 10 minutes, per instance; skipped when
+no client address is readable), because the hub sees only this site's egress
+address. An API that cannot be reached — a
+thrown submit, a 502 or a 504 — renders the contact email, like the 503
+`lead_capture_not_configured`.
+
+**The account link (#8757 D8, D9).** When the Contact form magnet is set to
+`invite` in Admin, the API's 201 carries `next: { completion: "invite" }` and
+the action answers `{ kind: "success", next: { href, label } }`: the success
+alert gains "Track this in your account" (`contact.trackInAccount`, testid
+`contact-success-next`), built by `lib/account-invite.ts` from
+`SIGN_IN_PROVIDER` — `site` links `/sign-in?next=<locale>/account&email=…`,
+`hub` links `/api/hub-session/sign-in?next=/account&email=…`, `none` (or an
+email `accountEmailHintSchema` refuses) gives no link. Anything else,
+`checkout` included (Phase 1), is exactly `{ kind: "success" }`. The link
+signs no one in: `/sign-in` reads one valid `email` as the card's starting
+value (`AuthCard`'s `defaultEmail`), the spoke's
+`/api/hub-session/sign-in` forwards it as `login_hint`, and the hub's
+authorize route carries a valid hint only onto its no-session `/sign-in`
+redirect, never into a code, cookie or continuation ref (a repeated
+`login_hint` is `400 invalid_request`). `email` and `login_hint` are in the
+telemetry scrub lists (`lib/telemetry-scrub.ts`, `packages/analytics`).
+
+**The same link on the magnet walk and /careers (#8771).** The `/careers/<slug>` job page's action reads the API's `next` the same way (`apply.actions.ts`): `invite` returns the link and `contact.trackInAccount`, anything else — or a throw after the write — exactly `{ kind: "success" }`, so an error never invites a duplicate application. The walk (`/flows/<slug>`, `FlowStepperClient`) tracks the first `mapsTo: "email"` answer it submitted; on a completing response with `next: { completion: "invite" }` it asks the server action `accountInviteLinkAction` (the builder reads the generated topology, so it never runs in the client) and shows the link inside `FlowStepper`'s finished card (its `completedAction` slot), or — for a flow with a `thankYou` block — writes one `sessionStorage` item, `ailk:account-invite`, that `/thanks/<slug>`'s `AccountInviteLink` reads once and removes (the page passes it to `renderPage` as `trailing`, so it sits inside `<main>`). Each link sits in a `data-sentry-block` element (Session Replay records `href`s); no walk URL ever carries the email.
+
+A `contact-form` section in the `column` variant (the minimalism design's
+Contact page) renders one centred heading, one line and the form, and the
+page passes the block `look="column"` (the stacked look, CSS in
+`packages/theme/src/tokens.css`) and `consentGate="on-submit"`: Send stays
+enabled and an unticked submit shows the terms error. Every other look keeps
+Send disabled until the box is ticked.
+
 The chat-style intake is not mounted by default.
 `ConversationalIntakeWrapper.tsx` remains for a site that prefers it: it hosts
 `@working-theory/ui`'s `ConversationalIntake` block (contract in
-`packages/ui/src/blocks/conversational-intake/README.md`), submits through the
-same `captureLeadAction`, and on Skip or a failed submit swaps to
+`packages/ui/src/blocks/conversational-intake/README.md`), asks for the terms
+in its own last turn (#8730 D2), submits through the same
+`captureLeadAction` with `consent=true` only when the accept pill was tapped,
+and on a declined terms turn, Skip or a failed submit swaps to
 `LeadCaptureForm`, prefilled with what was already captured. The canonical
 embedding for it is behind the hero CTA's lightbox gate
 (`packages/ui/src/sections/FormLightbox.tsx`, #4577), not a whole-page mount.
 
+## Spoke checkout
+
+A spoke that carries `commerce` sells through the standard spoke checkout
+(#8748), six files every such spoke shares and `create-ailk update` keeps
+current. A hub, or a spoke without `commerce`, never gets them: the hub's
+checkout is `apps/api`'s.
+
+- **The files.** `app/api/checkout/[offering]/route.ts` (the buy route),
+  `app/api/webhooks/stripe/route.ts`, `app/[locale]/checkout/thank-you/page.tsx`,
+  `app/[locale]/checkout/unavailable/page.tsx`, `lib/checkout.ts` (the
+  standard) and `lib/checkout-config.ts` (the site's data). Every guarantee —
+  live-key admission, the buy guards, the webhook's verification and filters,
+  the duplicate guard — lives in `@working-theory/spoke-checkout` and arrives by
+  a package bump.
+- **One data file.** `lib/checkout-config.ts` is the one file a site edits:
+  the `const SITE` stamp and the `offerings` map, no import and no code.
+  `create-ailk update` never rewrites it. Name an offering's slug after the last
+  segment of the Service or Product page that sells it.
+- **A slug that is not an offering answers 404**, before any guard, limiter,
+  admission or buyer lookup. Every other refusal is a 303 to
+  `/checkout/unavailable`.
+- **Spoke only.** Both routes answer 404 and both pages call `notFound()`
+  unless `lib/topology.generated.ts`'s `TOPOLOGY` is `"spoke"`, so this
+  monorepo's hub-shaped `apps/web` serves none of them.
+- **One sender, two importers.** `lib/checkout.ts`'s private fulfilment is the
+  one `apps/web` file that sends an `Idempotency-Key`: one `leads.submit` per
+  paid session, `payload.site` set to the checkout stamp (never
+  `AILK_LEAD_SITE`), the session id as the key, and a body that must stay
+  byte-identical between attempts, because the hub replays only an identical
+  body. The payload's last key, `termsAccepted`, is the session's `ailk_terms`
+  stamp when the buyer accepted Stripe's terms box, else `null`; the hub writes
+  the buyer's checkout consent grant from it (#8778). The hub leaves that key
+  out of its replay comparison, so a redelivery across the update still
+  replays. Only the two route files may import `lib/checkout.ts` or the package
+  (`tests/architecture/idempotency-key-producers.test.ts`, `architecture.yaml`);
+  a spoke that signs in through its hub adds a third, its rendered billing
+  action, which its own `architecture.yaml` admits. The thank-you page may
+  import the package for `readPaidCheckoutEmail` alone, never
+  `lib/checkout.ts` (#8757 D13): it reads `session_id`, and for a paid
+  session of this site under 24 hours old shows "Open your account" with the
+  buyer's email (`accountInviteHref`), else the same link with no email. Each
+  visitor gets 10 reads per 10 minutes (`src/lib/rate-limit.ts`); the page
+  sends no referrer, renders dynamically and never touches a cookie.
+  `spokeCheckoutConfig` reads only `site` and `offerings` from the site's file,
+  so admission always reads `process.env`.
+
 ## The same-origin relay (`/v1/*`)
 
 A visitor's browser never calls the hub. Lead capture, newsletter signup, callback, scheduling and the commerce invoice call post to this site's own `/v1/...` address, and `app/v1/[...path]/route.ts` hands each request to `lib/relay.ts` (`handleRelay`), which forwards it server-side through `@working-theory/api-client`'s `relayToApi` with the site's own `AILK_SPOKE_KEY` when it has one (#7644). The browser never holds the key, so a hub can refuse unknown callers (#7633) without taking a site's forms down.
@@ -158,4 +286,12 @@ A visitor's browser never calls the hub. Lead capture, newsletter signup, callba
 - Don't reach into `apps/api` or `apps/mcp` from `apps/web`. They're peer apps — talk via HTTP/MCP.
 - Don't commit images to `screenshots/` — only the `.gitkeep` is tracked.
 
-Last updated: 2026-10-05 — doc-sync: added § The same-origin relay (#7644) — verified against `apps/web/lib/relay.ts` and `apps/web/app/v1/[...path]/route.ts`.
+Last updated: 2026-10-16 — § Spoke checkout: the purchase lead's `termsAccepted` key, the stamp of the terms the buyer accepted, from which the hub writes the checkout consent grant (#8778) — verified against `lib/checkout.ts` and `packages/spoke-checkout/src/webhook.ts`.
+
+Prior: 2026-10-16 — § Spoke checkout: the thank-you page reads the paid session's email for "Open your account" (#8757 D13, #8800) — verified against `app/[locale]/checkout/thank-you/page.tsx` and `packages/spoke-checkout/src/paid-email.ts`.
+
+Prior: 2026-10-15 — § The `(auth)` route group: sign-up agreements are refused and written on the server, the carried cookie is retired, and the account interstitial asks a user with no current grant (#8765) — verified against `lib/sign-up-agreements.ts`, `auth.ts`, `lib/consent-policies.ts` and `app/[locale]/(authed)/account/layout.tsx`.
+
+Prior: 2026-10-15 — § Spoke checkout: the standard spoke checkout files, the one data file, the 404 and the fulfilment's one-key rule (#8748) — verified against `app/api/checkout/[offering]/route.ts`, `app/api/webhooks/stripe/route.ts`, `app/[locale]/checkout/*/page.tsx`, `lib/checkout.ts` and `lib/checkout-config.ts`.
+
+Prior: 2026-10-15 — § Contact page: the account link an `invite` magnet adds, and the sign-in email hint (#8757).

package/templates/apps/web/__tests__/__mocks__/next-intl-server.ts

@@ -24,10 +24,14 @@ const catalog = msgs as unknown as Record<string, Record<string, string>>;
 //   getTranslations({ namespace, locale }) — renderPage (post-migration)
 export const getTranslations = async (
   arg: string | { namespace?: string; locale?: string },
-): Promise<(key: string) => string> => {
+): Promise<((key: string) => string) & { has: (key: string) => boolean }> => {
   const ns = typeof arg === "string" ? arg : (arg.namespace ?? "");
   const messages = catalog[ns];
-  return (key: string): string => messages?.[key] ?? `${ns}.${key}`;
+  const t = (key: string): string => messages?.[key] ?? `${ns}.${key}`;
+  // next-intl's `t.has` — an optional catalog key (#8790's prospect line) is
+  // present only when the site added it.
+  t.has = (key: string): boolean => messages?.[key] !== undefined;
+  return t;
 };
 
 export const getRequestConfig = (fn: unknown): unknown => fn;

package/templates/apps/web/app/[locale]/(auth)/__tests__/auth-pages.test.tsx

@@ -141,9 +141,9 @@ describe("the (auth) layout", () => {
     expect(document.querySelector(".ailk-footer")).not.toBeInTheDocument();
   });
 
-  it("renders the brand mark and the slim footer's three links", async () => {
+  it("renders no brand row (the mark is in each card, #8790 D3) and the slim footer's three links", async () => {
     await renderLayout();
-    expect(screen.getByTestId("auth-shell-brand")).toBeInTheDocument();
+    expect(screen.queryByTestId("auth-shell-brand")).not.toBeInTheDocument();
     const footer = screen.getByTestId("auth-shell-footer");
     expect(footer.querySelectorAll("a")).toHaveLength(3);
     expect(
@@ -193,9 +193,10 @@ describe("the moved sign-in card", () => {
     expect(screen.queryByTestId("auth-forgot")).not.toBeInTheDocument();
   });
 
-  it("renders no logo inside the card — the mark is the shell's", async () => {
+  it("renders the site's mark inside the card, not in the shell (#8790 D3)", async () => {
     await renderPage(SignInPage);
-    expect(screen.queryByTestId("auth-card-logo")).not.toBeInTheDocument();
+    expect(screen.getByTestId("auth-card-logo")).toBeInTheDocument();
+    expect(screen.queryByTestId("auth-shell-brand")).not.toBeInTheDocument();
   });
 });
 

package/templates/apps/web/app/[locale]/(auth)/forgot-password/forgot-password-card.tsx

@@ -32,12 +32,14 @@ import {
   type AuthSubmitData,
 } from "@working-theory/ui/blocks";
 import { createAuthClient } from "better-auth/react";
-import type { ReactElement } from "react";
+import type { ReactElement, ReactNode } from "react";
 import { useState } from "react";
 
 const authClient = createAuthClient();
 
 export interface ForgotPasswordCardProps {
+  /** The site's mark, centred in the card at 48px (#8790 D3). */
+  logo?: ReactNode;
   /** Absolute same-origin URL of `/reset-password`, resolved server-side. */
   resetUrl: string;
   /** Href for the card footer's "Back to sign in". */
@@ -53,6 +55,7 @@ export function ForgotPasswordCard({
   signInHref,
   labels,
   errorLabels,
+  logo,
 }: ForgotPasswordCardProps): ReactElement {
   const [sent, setSent] = useState(false);
   const [sentTo, setSentTo] = useState("");
@@ -85,6 +88,7 @@ export function ForgotPasswordCard({
   return (
     <div className="flex flex-col gap-4" data-testid="forgot-password-page">
       <AuthCard
+        {...(logo !== undefined ? { logo } : {})}
         intent={sent ? "sent" : "forgot"}
         signInHref={signInHref}
         labels={labels}

package/templates/apps/web/app/[locale]/(auth)/forgot-password/page.tsx

@@ -40,6 +40,7 @@ import type { ReactElement } from "react";
 import { resetSendConfigured } from "../../../../lib/auth-env";
 
 import { ForgotPasswordCard } from "./forgot-password-card";
+import { siteLogo } from "../../../../lib/site-logo";
 
 interface Props {
   params: Promise<{ locale: string }>;
@@ -100,6 +101,7 @@ export default async function ForgotPasswordPage({
 
   return (
     <ForgotPasswordCard
+      logo={siteLogo()}
       resetUrl={resetUrl}
       signInHref={signInHref}
       labels={labels}