create-ailk 0.21.0 → 0.23.0

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,10 +143,27 @@ 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.
 
+**Every visible fact on the form comes from the magnet (#8847).** The page
+reads the magnet through `lib/in-page-magnet.ts`, the in-page form shape:
+its field step's `copy.title` is the page's H1 and `<title>` and its
+`copy.body` the line under it (`framedSources` writes both into the first
+`contact-form` section, and into the frontmatter title when that section
+leads), and its `ending` is the success message (`{name}` filled from the
+posted name). The section's own `submitLabel` and `successMessage` apply
+only to its own fields. When the hub cannot be read the seeded
+`contactFormFlowConfig` renders, so a fresh deploy looks the same. Under
+the form one muted line reads "Prefer email?" (`contact.preferEmail`) and
+the `_site.mdx` contact email, absent when the site has none. The default
+Contact form's statement is the two-link "I accept the Terms and Privacy
+Policy." (`CONTACT_FORM_TERMS_STATEMENT`); sign-up keeps the three-link
+`ACCOUNT_TERMS_STATEMENT`.
+
 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 reads it
-on every request (`force-dynamic`) through the public flow read,
-`flows.get("contact")` — the API resolves the workspace (the site alias
+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
@@ -135,11 +172,44 @@ 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 stays `web`. The terms statement
+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` (the intake excepted) and keeps only the sources `web`,
-`conversational-intake` and `flow:contact`.
+`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 apply page's action (`/careers/<slug>/apply` on a site without the walk, #8849) 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
@@ -151,12 +221,298 @@ 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.
 
+## Newsletter, unsubscribe and the footer signup
+
+The workspace's **Newsletter magnet** (#8847) — seeded live at slug
+`newsletter` in every workspace — is the only source of `/newsletter`,
+`/unsubscribe` and the footer signup; none of their copy is in page code,
+content or the message catalog. All three read it through
+`lib/in-page-magnet.ts`'s `readServedMagnet("newsletter")`, shared for 15
+seconds per instance like /contact's read.
+
+- **`/newsletter`** renders on every request. The magnet's step title is the
+  H1 and `<title>`, its body the line under it, and the standard
+  `NewsletterFormInline` (visible Email label, the consent row above the
+  field, the consent field's help line, Subscribe, and the magnet's ending in
+  place of the form) goes into the page's first `contact-form` section. With
+  the hub unreadable the seeded `newsletterFlowConfig` renders; with capture
+  off (`GET /v1/leads/capture`'s `newsletter`) the slot is `ContactFallback`
+  with the `_site.mdx` email. A page with no `contact-form` section keeps its
+  pre-#8847 composition.
+- **The signup.** `subscribeNewsletterAction` refuses a post without
+  `consent=true`, then re-reads the magnet and submits its step through
+  `flows.submitStep` — the step key, the email field and the consent key
+  (`terms.newsletter`) all from the server's read, never the post — so the
+  hub writes the lead, the `newsletter` consent row and the welcome email.
+  Without a flow route (a Free build) it posts `leads.subscribe`, as before.
+  It lives in `lib/newsletter.actions.ts`, not under `app/[locale]/newsletter/`,
+  because the footer imports it and a scaffold with the `newsletter` surface
+  off drops that route directory.
+- **`/unsubscribe`** takes its title, line, button and done message from the
+  magnet's `unsubscribe` block (strings only across the island edge); the
+  already, invalid and unavailable lines stay in the `unsubscribe` catalog.
+- **The footer** fills `Footer`'s `subscribe` slot with the compact form
+  (stacked, `sr-only` label) only when the magnet is served and capture is
+  on; the built-in config never fills it.
+
+## Careers
+
+Three linked pages, each built from the `content/<locale>/JobPosting/*.mdx`
+records (#8849):
+
+- **`/careers`** renders in sections mode, the /alternatives pattern: one
+  generated `items` section first, a card per posting (newest `publishedAt`
+  first), then the seed's declared sections, so the card grid and the
+  `CollectionPage`'s `ItemList` (`ListItem`s with `position` and `url`) agree.
+  The section's `filter` gives a search box and employment-type and location
+  selects; the facets read the postings' first-class `employmentType` and
+  `location` frontmatter, never `schema.mainEntity`. Every posting stays in the
+  server HTML. Every visible string is a `careers` message.
+- **`/careers/<slug>`** keeps its chrome and ends with an Apply button
+  (`job-apply-cta`, `Button` size `big`) to `/careers/<slug>/apply`; its
+  `ApplyAction` targets the same URL. It makes no hub read.
+- **`/careers/<slug>/apply`** is the `signal-collectors` walk where the module
+  is present (§ Magnet pages), else the Free apply page,
+  `careers/[slug]/[action]/page.tsx`: the posting's title over the one-step
+  `LeadCaptureForm` bound to `apply.actions.ts` with the slug as `job`,
+  `noindex, follow` and full-screen. Next.js serves the static `apply`
+  segment first, the `[slug]/[detail]` idiom; every other action 404s. Lead
+  capture is never-gate, so every tier takes an application. Both apply pages
+  read the posting's title through `lib/posting-title.ts`.
+
+## Meeting pages
+
+The scheduling module's booking pages (#8843) read every meeting fact from
+the workspace — no content file, env var or deploy sits between a Meetings or
+Cal.com edit and the page.
+
+- **One builder.** `lib/meetings.tsx` reads `GET /v1/schedule/meetings`
+  through `schedule.meetings()`, re-parses the body with `MeetingListSchema`
+  and shares the result per server instance for 15 seconds (concurrent and
+  failed reads too, the contact page's #8731 shape). Any failure is
+  `{ ok: false }`. It builds the index cards (`meetingCardsSection`: `items`
+  tiles, two columns, `gapAbove: "tight"`, one card per bookable meeting with
+  the hub's title and description and a "Book <n> min" button) and the
+  meeting page's booker (`meetingPageSections`: `scheduler-embed`, provider
+  `cal`, month view). Every visible string is a `schedule` message.
+- **`/meet` and `/private`** both return `MeetingIndex`
+  (`app/[locale]/meet/meeting-index.tsx` — beside the route, because it
+  renders the paid `BookingProfileHeader`, which `architecture.yaml` admits
+  only there): the back link alone (`Nav` `bar="bare"` `bareMark={false}`),
+  the header's avatar and one H1, then the cards of that visibility. One
+  meeting redirects to `/meet/<slug>`; none, or a failed read, shows the
+  site's contact email — never a 404 or a 500. `/private` is
+  `noindex, nofollow`, has no seed and no nav entry: private means unlisted,
+  not access-controlled.
+- **`/meet/<slug>`** is one centred H1 ("Schedule a <title> meeting"),
+  Cal.com's inline embed from the hub's Cal.com link, and "← All meeting
+  types". A Live meeting that cannot be booked, or a failed read for a valid
+  slug, shows the contact email; an unknown slug or a dotted one is a 404. A
+  `BookCall/<slug>.mdx` seed gives only the URL, the JSON-LD inputs and the
+  fallback title — its sections are never rendered here.
+- **Chrome.** `lib/modules.generated.ts`'s `SCHEDULING_PAGES` (written by
+  create-ailk from `apps/web/package.json`, never copied by `update`) and
+  `lib/auth-routes.ts`'s `isBookingPath` make the locale layout drop the
+  marketing shell on `/meet`, `/meet/<slug>` and `/private`; `/meet/confirmed`
+  and a site without the module keep it. The consent banner stays.
+- **The CSP (D12).** `security-headers.config.ts` exports `SCHEDULING_CSP`
+  (Cal.com's app origin in `script-src` and `connect-src`; `frame-src`
+  `'self'` and the same origin) and a frozen `SCHEDULING_SECURITY_HEADERS`.
+  `middleware.ts` applies it instead of `DEFAULT_SECURITY_HEADERS` only when
+  `SCHEDULING_PAGES && isBookingPath(pathname, enabledLocales)`; sign-in,
+  account, checkout, `/meet/confirmed` and every site without the module keep
+  the default policy. `architecture.yaml`'s `cal\.com` rule excludes the
+  config, the middleware and their two tests for this reason.
+
+## Magnet pages
+
+Every multi-step magnet is a page pair (#8840), rendered by one module,
+`app/[locale]/flows/[slug]/magnet-page.tsx`:
+
+- **`/<magnet>`** — the indexable landing, inside the site's Nav and Footer: a
+  centred hero of the flow record's `landing` copy (title, line, muted meta
+  line, button to `/<magnet>/start`; absent keys fall back to step 1's title
+  and the `flow` messages) and the `Assessment` page type's `WebApplication`
+  JSON-LD.
+- **`/<magnet>/start`** — the walk, `noindex, follow`, full-screen with the
+  back arrow alone (`NavBackLink`) above step 1. `lib/magnet-routes.ts`'s
+  `isMagnetWalkPath` is what the locale layout drops the Nav and Footer on:
+  any path ending in `start`, plus `/careers/apply` and
+  `/careers/<posting>/apply`. The cookie consent banner stays.
+- **The ending.** A flow with an `ending` ends on it, never on `thankYou`:
+  `FlowStepperClient` picks the outcome from the walk's answers
+  (`selectFlowEndingOutcome`) — a screen in the finished card with `{name}`
+  filled, or a redirect to a site path — and re-checks every destination
+  against `flowSitePathSchema` before it renders or navigates.
+- **The hub is down.** Both pages read the flow through one `flows.get`,
+  shared per instance for 15 seconds per slug; a refused connection or a 5xx
+  shows `ContactFallback` with the site's contact email (both pages
+  `noindex`), and a 404 is `notFound()`. `/careers/apply` exists apart from
+  its flow, so it passes `renderMagnetStart` a `title`: a 404, a refused
+  connection or a 5xx all render the contact email under that `<h1>`
+  (#9219).
+- **The pairs.** `/flows/<slug>` is the canonical pair. `/careers/apply` and
+  `/careers/<posting>/apply` walk the Job application magnet (the second
+  titles step 1 with the posting and sends its slug as the hidden `job`).
+  Any other pair is written by `create-ailk add-route magnet --path <path>
+  --flow <slug>`: two short pages carrying the `Standard magnet page
+  (#8840)` marker, which `lib/__tests__/structured-data.test.tsx` exempts
+  from its `renderPage` check. A site adds a magnet by binding a pair to a
+  slug, never by copying stepper code.
+- **The recommender's landing (#9071).** A recommending flow with an offer
+  carrying `lookupKey` (an Offerings recommender, such as the standard
+  `recommender` magnet the Admin's Offerings page opens) never renders its
+  results page: the results permalink
+  (`flows/[slug]/results/[payload]/page.tsx`) redirects a completed walk to
+  `/<locale>/pricing?plan=<plan>` while the first fit's lookup key is in the
+  current shown set, else to `/<locale>/pricing` with no badge (no fit, a key
+  no longer shown, any failed read, or no answer within 5 seconds). The
+  shown-set read is `offerings.shown()`, `/pricing`'s own, shared per
+  instance for 15 seconds; `?plan=` carries the key's `{plan}` part, the only
+  value `/pricing` reads. A flow with no such offer, or whose first fit
+  carries none, renders the results page as before, with no read.
+- **The deliverable pages (#8848).** A flow whose served config carries a
+  `deliverable` block (a `file`, `video`, `page` or `external` payload, gated
+  or not) has one route, `/reports/<slug>`, rendered by
+  `app/[locale]/reports/deliverable-page.tsx`; both halves of every other pair
+  redirect a deliverable flow there. Gated: the page is a centred hero of the
+  block's copy with the back arrow to `/reports` and a button to the walk at
+  `/reports/<slug>/start`, and the walk's finished card shows the deliverable
+  after the ending screen — the reader link `/reports/<slug>?g=<grant>` (in a
+  `data-sentry-block` element), an inline player, a site link or a link out;
+  a redirect ending never runs when the response carries one, and a file walk
+  that minted no grant says the link is in the email. Ungated: the reader over
+  the site's own `/reports/<slug>/file` route handler (it reads the hub's
+  `GET /v1/deliverables/open/:slug` with the spoke key and the visitor
+  forward, 30 reads per visitor per 10 minutes — skipped when no client
+  address is readable — the five file headers passed through), a player, a redirect to the site page, or a button out. Every
+  page under `/reports/<slug>` is chrome-free (`isMagnetWalkPath`); `/reports`
+  keeps its chrome. The reader's Share is built from the page URL, never the
+  bytes or `?g=`. A hub read that fails falls back to the slug's `ReportPage`
+  content. With none, #8848 D6 holds for a configured hub: a 5xx or a refused
+  connection shows the contact email (`noindex`). A site with no hub to ask —
+  the read answers 503 `flows_not_configured`, or no API origin
+  (`AILK_API_URL`, `NEXT_PUBLIC_AILK_API_URL`, `NEXT_PUBLIC_API_URL`) is set —
+  reads `not-configured` (set once in `readMagnet`), and the slug 404s, as
+  does its `/start` (#9219). `/downloads` and `/downloads/<slug>` are
+  permanent redirects into `/reports` (signal-collectors files).
+
+## Pricing page
+
+The pricing page (`apps/web/app/[locale]/pricing/page.tsx`) renders the
+workspace's Offerings shown set from Stripe (#8927). Before rendering it
+reads `GET /v1/content/shown-offerings` through `offerings.shown()` from
+`@working-theory/api-client`, renders on every request (`force-dynamic`),
+and shares the read across requests for 15 seconds per server instance, the
+contact page's window and reason: a product switched off disappears within
+15 seconds, with no deploy. The API resolves the workspace (a spoke by its
+key), so the page names none. It renders one of three pages:
+
+- **Unconnected** — the route answers `unconnected`, or the deployment runs
+  in production with none of the API origin variables `getApiBase()` reads:
+  today's MDX page through `renderPage`, byte for byte, `?plan=` matching
+  authored plan keys as #8842 made it.
+- **A current shown set** — `lib/offerings-pricing.ts` maps it to a plans
+  fragment and an add-ons fragment. The first `pricing` section that is not
+  `addons` becomes the Stripe plans, and the first `addons` one the Stripe
+  add-ons, each keeping only its authored section copy (eyebrow, headline,
+  description and layout knobs), never an authored plan or price. Every other
+  `pricing` section is removed; a fragment with no section to replace goes
+  after a leading hero. `?plan=` moves the recommendation only for a
+  `{plan}`-grammar value (`LOOKUP_KEY_PLAN_PATTERN`), so `?plan=Growth` keeps
+  the workspace's own. Copy comes from the `pricingOfferings` namespace.
+- **Anything else** — an expired or empty shown set, `empty`, a non-2xx, an
+  unknown body or a throw: every `pricing` section gives way to one
+  `contact-form` section holding `ContactFallback` with the site's contact
+  email (`readSiteContactEmail()`), in the `contact` namespace's copy. Never
+  an error page, and no `Offer` is published.
+
+Stripe text reaches the page only as React text and JSON-LD only through
+`renderPage`'s serializer; the title and meta stay the MDX page's.
+
+Every Stripe card links `/api/offerings/checkout/<lookup_key>`, which
+`app/api/offerings/checkout/[lookupKey]/route.ts` serves (#9051). Only a
+buyer's page load starts anything: a request that is not a top-level
+navigation (`Sec-Fetch-Mode: navigate`, `Sec-Fetch-Dest: document`), a
+`HEAD`, a prefetch, an RSC fetch or a cross-site load is refused before any
+call. A key `parseLookupKey` refuses, a site without the `commerce` claim, and
+production with no API origin are refused locally too. The route then reads
+the shown set, shared per instance for 15 seconds like the page's own read,
+and goes on only when the site is connected and that set shows the key, so an
+unconnected site never reaches the API's env path. Each visitor address gets 5
+starts per 10 minutes per instance. The route POSTs `/v1/checkout/sessions`
+through `checkout.createSession` with the visitor's `x-forwarded-for`, success
+URL `/purchase/success?session_id={CHECKOUT_SESSION_ID}` and cancel URL
+`/pricing`, both on the origin of `resolveBaseUrl()` and never the request's
+host, and answers a `303` to the `https:` Checkout URL the API returns. Every
+refusal is a `303` to `/pricing` with no body, `Cache-Control: no-store` and
+one `[offerings-checkout] refused reason=<reason>` warning; no response or
+log line carries the key. It sends `OSS_API_INTERNAL_SECRET` as
+`x-internal-auth` only from a site that is not a spoke and only to an
+`https:` or loopback API, so the hub's own `apps/web` must hold the API's
+value when the API sets it. A spoke never holds that secret: it sells only
+when its hub lists the spoke's origin in `AILK_TRUSTED_ORIGINS` and does not
+set `OSS_API_INTERNAL_SECRET`, and otherwise every spoke buy returns to
+`/pricing`.
+
+An existing scaffold adopts the new page by bringing
+`lib/offerings-pricing.ts`, `app/api/offerings/checkout/[lookupKey]/route.ts`
+(it sits under `app/api/`, outside the route registry `sync-routes` copies),
+the `pricingOfferings` namespace and an
+`@working-theory/api-client` release that exports `offerings` with it, and
+needs an API (its own `apps/api`, or a spoke's hub) that serves
+`GET /v1/content/shown-offerings` (#8924): an older API answers that path
+non-2xx, which renders the contact email in place of the authored pricing.
+
+## Spoke checkout
+
+**A spoke sells through the Offerings buy route, and only through it.**
+`app/api/offerings/checkout/[lookupKey]/route.ts` (§ Pricing page) is the one
+selling path on every site: the seller's Stripe account is held once per
+Organization on the hub, and the hub authorizes each buy against the
+workspace's shown set. The spoke's legacy env-key checkout — its own buy route
+(`app/api/checkout/[offering]/route.ts`), its Stripe webhook route
+(`app/api/webhooks/stripe/route.ts`), `lib/checkout.ts` (the fulfilment) and
+the generated checkout e2e workflow — is retired (#9142). `create-ailk
+sync-routes --apply` removes them from an existing spoke when they are still
+the copies create-ailk wrote, and names any it leaves.
+
+What a spoke that carries `commerce` still gets (#8748), kept current by
+`create-ailk update`; a hub, or a spoke without `commerce`, never gets them:
+
+- **The two return pages.** `app/[locale]/checkout/thank-you/page.tsx` and
+  `app/[locale]/checkout/unavailable/page.tsx`. Both call `notFound()` unless
+  `lib/topology.generated.ts`'s `TOPOLOGY` is `"spoke"`, so this monorepo's
+  hub-shaped `apps/web` serves neither.
+- **One data file.** `lib/checkout-config.ts` is the site's stamp,
+  `checkoutConfig.site`, and nothing else: no import and no code.
+  `create-ailk update` never rewrites it.
+- **One package reader.** The thank-you page may import
+  `@working-theory/spoke-checkout` for `readPaidCheckoutEmail` alone
+  (`architecture.yaml`, #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. The read
+  admits the spoke's `STRIPE_SECRET_KEY` from `process.env`; that key never
+  sells.
+- **The billing action (a spoke that signs in through its hub).** create-ailk
+  renders `app/[locale]/(authed)/account/billing/spoke-billing.action.ts`,
+  which builds the package's billing reads from `checkoutConfig.site` and
+  `resolveBaseUrl()`; the spoke's own `architecture.yaml` admits it as the
+  package's other importer.
+- **No `Idempotency-Key`.** No `apps/web` file sends one
+  (`tests/architecture/idempotency-key-producers.test.ts`): the fulfilment that
+  did is retired with the legacy checkout.
+
 ## 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.
@@ -183,4 +539,32 @@ 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-14 — § Contact page: the Contact form magnet read, the fallback order and the `column` look (#8661).
+Last updated: 2026-10-19 — § Magnet pages: `/careers/apply` renders the contact email under its own `<h1>` when its flow is absent or the hub cannot answer; `readMagnet`'s `not-configured` kind 404s an unknown `/reports/<slug>` (and its `/start`) on a site with no hub to ask, while a configured hub that is down keeps #8848 D6's contact email (#9219) — verified against `app/[locale]/flows/[slug]/magnet-page.tsx`, `app/[locale]/careers/apply/page.tsx`, `app/[locale]/reports/deliverable-page.tsx` and `app/[locale]/reports/[slug]/{page,start/page}.tsx`.
+
+Prior: 2026-10-18 — § Spoke checkout: the Offerings buy route is the one selling path, and the legacy env-key buy route, webhook route, `lib/checkout.ts` and checkout e2e workflow are retired (#9142) — verified against `app/api/offerings/checkout/[lookupKey]/route.ts`, `app/[locale]/checkout/*/page.tsx`, `lib/checkout-config.ts` and create-ailk's `spoke-checkout.ts` and `sync-routes.ts`.
+
+Prior: 2026-10-18 — § Magnet pages: the recommender's landing on `/pricing?plan=` (#9071) — verified against `app/[locale]/flows/[slug]/results/[payload]/page.tsx` and its `landing.test.tsx`.
+
+Prior: 2026-10-18 — § Magnet pages: the deliverable pages at `/reports/<slug>`, their ending, the file proxy and the `/downloads` redirects (#8848) — verified against `app/[locale]/reports/{deliverable-page.tsx,[slug]/page.tsx,[slug]/start/page.tsx,[slug]/file/route.ts}`, `app/[locale]/flows/[slug]/{magnet-page,FlowStepperClient}.tsx`, `app/[locale]/downloads/` and `lib/magnet-routes.ts`.
+
+Prior: 2026-10-18 — § Contact page and § Newsletter, unsubscribe and the footer signup: the in-page form shape — every visible fact from the Contact form and Newsletter magnets (#8847) — verified against `lib/in-page-magnet.ts`, `app/[locale]/{contact,newsletter,unsubscribe}/page.tsx`, `lib/newsletter.actions.ts` and `app/[locale]/layout.tsx`.
+
+Prior: 2026-10-18 — § Careers: the searchable /careers, the posting's Apply button and the Free apply page (#8849) — verified against `app/[locale]/careers/{page,[slug]/page,[slug]/[action]/page}.tsx` and `lib/posting-title.ts`; § Pricing page: the Offerings buy route `app/api/offerings/checkout/[lookupKey]/route.ts` starts the hosted Checkout for a shown key and returns every refusal to `/pricing`, and the spoke precondition (#9051) — verified against the route, its suite and `lib/offerings-pricing.ts`.
+
+Prior: 2026-10-18 — § Meeting pages: the booking pages carry the Cal.com CSP (`SCHEDULING_CSP`, applied by `middleware.ts` on booking paths only) and `scheduler-embed` forwards `gapAbove` (#8843 D12, D13) — verified against `security-headers.config.ts`, `middleware.ts` and `packages/ui/src/sections/SchedulerEmbed.tsx`.
+
+Prior: 2026-10-18 — § Meeting pages: the booking pages read the workspace's meetings through one builder, the chrome-free booking branch and its module flag (#8843) — verified against `lib/meetings.tsx`, `app/[locale]/meet/`, `app/[locale]/private/page.tsx`, `lib/auth-routes.ts` and `app/[locale]/layout.tsx`.
+
+Prior: 2026-10-18 — § Magnet pages: the standard magnet page pair, its walk predicate, ending, hub-down fallback and `add-route magnet` (#8840) — verified against `app/[locale]/flows/[slug]/magnet-page.tsx`, `FlowStepperClient.tsx`, `lib/magnet-routes.ts`, `app/[locale]/layout.tsx` and `app/[locale]/careers/{apply,[slug]/apply}/page.tsx`.
+
+Prior: 2026-10-18 — § Pricing page: `/pricing` renders the Offerings shown set, the contact email when there is none to sell, and today's page for an unconnected site (#8927) — verified against `app/[locale]/pricing/page.tsx` and `lib/offerings-pricing.ts`.
+
+Prior: 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}

package/templates/apps/web/app/[locale]/(auth)/layout.tsx

@@ -24,7 +24,6 @@ import { headers } from "next/headers";
 import { getTranslations } from "next-intl/server";
 import type { ReactElement, ReactNode } from "react";
 
-import { siteLogo } from "../../../lib/site-logo";
 
 interface Props {
   children: ReactNode;
@@ -51,19 +50,9 @@ export default async function AuthLayout({
 
   return (
     <AuthShell
-      brand={
-        /*
-         * The mark is clamped to 28px the way `BrandLogo` clamps it inside
-         * Nav: `siteLogo()` emits an <img> with a height ATTRIBUTE and no
-         * width, and an SVG with no intrinsic size then stretches to the
-         * container — it rendered 48 x 350 here before the clamp. The shell
-         * owns the row's geometry; the site owns its mark's size.
-         */
-        <div className="inline-flex h-7 items-center [&>img]:h-full [&>img]:w-auto [&>img]:object-contain">
-          {siteLogo()}
-        </div>
-      }
-      brandHref={localeHref(locale, "/")}
+      // No brand row (#8790 D3): every auth card now carries the site's mark
+      // centred at 48px (`AuthCard`'s `logo` slot), so the shell's top-start
+      // corner is free for a page's own affordance (the sign-in's back link).
       footerLinks={footerLinks}
       languageSwitcher={
         <LocaleSwitcherNav

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

@@ -39,6 +39,7 @@ import type { ReactElement } from "react";
 import { resetSendConfigured } from "../../../../lib/auth-env";
 
 import { ResetPasswordCard } from "./reset-password-card";
+import { siteLogo } from "../../../../lib/site-logo";
 
 interface Props {
   params: Promise<{ locale: string }>;
@@ -122,6 +123,7 @@ export default async function ResetPasswordPage({
 
   return (
     <ResetPasswordCard
+      logo={siteLogo()}
       token={token}
       signInHref={signInHref}
       labels={labels}

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

@@ -23,12 +23,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 ResetPasswordCardProps {
+  /** The site's mark, centred in the card at 48px (#8790 D3). */
+  logo?: ReactNode;
   /** The `?token=` Better Auth redirected back with. May be empty. */
   token: string;
   /** Where a completed reset lands. */
@@ -60,6 +62,7 @@ export function ResetPasswordCard({
   labels,
   errorLabels,
   navigate = defaultNavigate,
+  logo,
 }: ResetPasswordCardProps): ReactElement {
   const [errors, setErrors] = useState<{
     password?: string;
@@ -104,6 +107,7 @@ export function ResetPasswordCard({
   return (
     <div className="flex flex-col gap-4" data-testid="reset-password-page">
       <AuthCard
+        {...(logo !== undefined ? { logo } : {})}
         intent="reset"
         signInHref={signInHref}
         labels={labels}