@odla-ai/chapter 0.20.0 → 0.20.2

package/runbooks/greenfield.md

@@ -0,0 +1,652 @@
+# Greenfield runbook: build a Chapter website
+
+Audience: an LLM or coding agent starting from an empty repository.
+
+Read this file completely before creating files or running provisioning. This
+runbook ships with the installed `@odla-ai/chapter` version; its `README.md`,
+`package.json` exports, and `dist/*.d.ts` are the version-matched API authority.
+Do not substitute remembered APIs or a reference site's private source.
+
+If a site, Worker, database, login, scheduled job, or production route already
+exists, stop and use [`adopt-existing.md`](./adopt-existing.md). A redesign in a
+new directory is not a safe adoption.
+
+## What Chapter supplies—and what the host must build
+
+Chapter supplies:
+
+- the validated `defineChapter()` engine and generated schema/rules/seed;
+- the Cloudflare Worker API through `chapterWorker()`;
+- the join, payment, booking, member, admin, CRM, and network behavior;
+- member-facing React components and the complete Clerk-gated admin console;
+- the provisioning descriptor consumed by `@odla-ai/cli`.
+
+Chapter does **not** generate a website. The host still owns:
+
+- `package.json`, Vite/React or Vite/Preact, HTML entries, routing, and CSS;
+- public pages, navigation, copy, imagery, SEO, legal text, and the join form;
+- the member auth wrapper that gives `MembersArea` an authenticated `api`;
+- Wrangler configuration, observability wrapping, provider setup, and tests.
+
+Do not reimplement Chapter's worker routes, auth checks, admin shell, CRM,
+payment, booking, account, or lifecycle logic just to achieve a different
+brand. Public presentation is site-owned; application mechanics are
+package-owned.
+
+## Non-negotiable boundaries
+
+1. Pin every ODLA package to an exact tested version. Never use `latest`, `^`,
+   `~`, or `--legacy-peer-deps` in a committed Chapter site.
+2. Build and prove `dev` before adding `prod`. Production provisioning, secret
+   transfer, deploy, DNS, billing activation, and real outbound email are human
+   checkpoints.
+3. Never print, paste into chat, or commit a secret. Never read back
+   `.dev.vars`, `.odla/credentials.local.json`, or `.odla/dev-token.json`.
+   A Clerk `pk_test_...` publishable key is public; Clerk/Stripe secret keys,
+   webhook secrets, ODLA credentials, and network share secrets are not.
+4. Keep database rules default-deny. The Worker uses the admin credential;
+   browser code never receives `ODLA_API_KEY`.
+5. `createChapterIntegration()` seeds the `groups` row only when absent.
+   Provisioning again does not overwrite owner-edited runtime copy, prices,
+   templates, scheduling, or Stripe fields. Compare config to the live row
+   deliberately after the first seed.
+6. `@odla-ai/cli smoke` proves platform/schema reachability, not the Chapter
+   application journey. The route, auth, payment, calendar, email, and visual
+   checks below are still required.
+7. The only live environment name in this runbook is the literal `prod`.
+   Although the CLI also recognizes `production` as live, Chapter's email
+   fail-safe currently recognizes only `prod`; using `production` suppresses or
+   debug-redirects lifecycle mail.
+
+## Phase 0 — Resolve the product and brand brief
+
+Write `PRODUCT.md` before code. Record decisions rather than inventing business
+facts. Ask the human only for missing choices that change money, identity,
+outbound communication, authorization, or the public brand.
+
+| Decision | Required answer |
+| --- | --- |
+| Profile | `chapter` for a public membership site; `hub` for an admin-only CRM hub |
+| Identity | lowercase app id, public name, approved domains, owner |
+| Audience | who the site serves, why it exists, primary action |
+| Public IA | required pages and exact navigation labels |
+| Brand | wordmark, short badge, voice, approved logo/images, light and dark palettes, typography |
+| Membership | price, currency, interval, refund policy, disclaimer/consent |
+| Application | exact fields, required/optional status, caps, confidential vs Clerk-visible vs CRM-projected |
+| Account side effect | `none`, server-side `create`, or emailed Clerk `invite` |
+| Lifecycle | pipeline, booking eligibility, approval effect, refund rule, email trigger |
+| Operations | notification/reply/debug addresses, scheduling timezone/hours |
+| Providers | intended ODLA account, Clerk app/workspace, Stripe test account, Google calendar, verified email sender |
+
+### Brand procedure
+
+1. Inventory approved logos, marks, photography, illustrations, fonts, and
+   usage rights. Do not redraw a logo, scrape a reference site's assets, or
+   generate claims/testimonials.
+2. If no direction exists, present three clearly different one-screen visual
+   directions and pause for selection. Do not blend unapproved directions.
+3. Convert the selected direction into semantic tokens:
+   `brand.palette` for light mode and `brand.paletteDark` for dark mode. Define
+   background, surface tiers, text tiers, border tiers, accent/soft/strong,
+   on-accent, good, warning, and danger—not merely one accent. Use the actual
+   `--ui-*` token names from the installed UI theme.
+4. Use one wordmark, one product header, and one navigation model across public,
+   join, member, and admin surfaces. Do not repeat a page/product label in a
+   secondary strip when the active navigation already establishes context.
+5. Build public information architecture before decoration. A Chapter site
+   normally needs: home/value proposition, thesis or program, process,
+   membership, join/apply, member sign-in/area, admin, privacy, and terms.
+6. Validate at 390, 768, 1280, and 1440 CSS pixels in light and dark mode.
+   Require visible focus, readable contrast, no clipped labels, no horizontal
+   document overflow, and contained Clerk cards/forms.
+
+The public site must look like the approved organization, not an ODLA demo or a
+renamed reference site.
+
+## Phase 1 — Scaffold the host
+
+`@odla-ai/chapter` has no scaffolding binary. The agent creates the host files.
+
+Initialize npm, install the exact CLI named by this release, and install its
+agent guidance:
+
+```sh
+npm init -y
+npx @odla-ai/cli@0.17.1 setup
+```
+
+Verify every release target exists, then install the exact known-good React
+host matrix. Do not copy these commands into a pre-release branch where
+`@odla-ai/chapter@0.20.2` is not yet on npm.
+
+```sh
+npm view @odla-ai/chapter@0.20.2 version
+npm install --save-exact \
+  @odla-ai/chapter@0.20.2 @odla-ai/ui@0.10.0 \
+  @odla-ai/crm@0.1.4 @odla-ai/db@0.6.6 \
+  @odla-ai/calendar@0.2.0 @odla-ai/email@0.3.1 \
+  @odla-ai/auth-clerk@0.4.0 @odla-ai/o11y@2.2.2 \
+  jose@6.2.3 react@19.2.7 react-dom@19.2.7
+npm install --save-dev --save-exact \
+  @odla-ai/cli@0.17.1 @odla-ai/security@0.3.1 \
+  @cloudflare/workers-types@4.20260702.1 \
+  @types/react@19.2.17 @types/react-dom@19.2.3 \
+  @vitejs/plugin-react@6.0.3 typescript@6.0.3 \
+  vite@8.1.4 vitest@4.1.10 wrangler@4.107.0
+npx odla-ai capabilities --json
+```
+
+The parent `README.md` repeats this version matrix. This runbook standardizes on
+React; a Preact host needs its own exact, tested compatibility matrix. Install
+auth-clerk explicitly: it is deliberately not a Chapter peer because
+worker-only and member-only consumers do not need it.
+
+Required host scripts:
+
+```json
+{
+  "scripts": {
+    "build": "vite build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "dev": "npm run build && wrangler dev --env dev",
+    "deploy:dev": "npm run build && wrangler deploy --env dev"
+  }
+}
+```
+
+Recommended minimum tree:
+
+```text
+.
+├── PRODUCT.md
+├── package.json
+├── index.html
+├── vite.config.mjs
+├── wrangler.jsonc
+├── odla.config.mjs
+├── src/
+│   ├── chapter.config.mjs
+│   ├── worker.ts
+│   └── app/
+│       ├── main.tsx
+│       ├── public.tsx
+│       ├── join.tsx
+│       ├── members.tsx
+│       ├── admin.tsx
+│       └── app.css
+└── test/
+    ├── chapter-contract.test.ts
+    ├── routes.test.ts
+    └── render.test.tsx
+```
+
+Gitignore at least:
+
+```gitignore
+node_modules/
+dist/
+.dev.vars
+.odla/
+```
+
+## Phase 2 — Write the single Chapter decision record
+
+Do not accept safety-sensitive defaults silently. A chapter-mode starting point:
+
+```js
+// src/chapter.config.mjs
+import { defineChapter } from "@odla-ai/chapter";
+
+export const chapter = defineChapter({
+  id: "example-chapter",
+  name: "Example Chapter",
+  url: "https://example.org",
+  mode: "chapter",
+  services: ["db", "calendar", "o11y"],
+  brand: {
+    badge: "EX",
+    wordmark: "Example Chapter",
+    tagline: "Approved public positioning goes here.",
+    palette: {
+      "--ui-bg": "#f6f2e9",
+      "--ui-surface": "#fffdf8",
+      "--ui-surface-2": "#eee7dc",
+      "--ui-text": "#24342b",
+      "--ui-text-muted": "#66736b",
+      "--ui-text-faint": "#8a958e",
+      "--ui-border": "#d8d2c5",
+      "--ui-border-strong": "#b8ae9d",
+      "--ui-accent": "#b85c38",
+      "--ui-accent-strong": "#8c3f24",
+      "--ui-accent-soft": "rgba(184, 92, 56, 0.12)",
+      "--ui-on-accent": "#ffffff",
+      "--ui-good": "#4e765c",
+      "--ui-warn": "#9a732b",
+      "--ui-danger": "#a9443b",
+    },
+    paletteDark: {
+      "--ui-bg": "#15211b",
+      "--ui-surface": "#1d2b24",
+      "--ui-surface-2": "#27372e",
+      "--ui-text": "#f3eee4",
+      "--ui-text-muted": "#aab6ad",
+      "--ui-text-faint": "#7d8d83",
+      "--ui-border": "#3c4a42",
+      "--ui-border-strong": "#58675e",
+      "--ui-accent": "#ef8a63",
+      "--ui-accent-strong": "#ffad88",
+      "--ui-accent-soft": "rgba(239, 138, 99, 0.16)",
+      "--ui-on-accent": "#15211b",
+      "--ui-good": "#83b58f",
+      "--ui-warn": "#d5ad5d",
+      "--ui-danger": "#e58278",
+    },
+  },
+  prices: {
+    standardCents: 100000,
+    foundingDiscountCents: 10000,
+    currency: "usd",
+    interval: "year",
+  },
+  policy: {
+    disclaimerText: "Replace with approved consent language.",
+    refundPolicyText: "Replace with the approved refund policy.",
+    trustCopy: "Replace with approved trust and privacy copy.",
+  },
+  emails: {
+    notificationEmail: "owner@example.org",
+    replyTo: "hello@example.org",
+    debugEmail: "dev-mail@example.org",
+  },
+  scheduling: {
+    slotMinutes: 45,
+    days: [1, 2, 3, 4, 5],
+    startHour: 9,
+    endHour: 17,
+    timezone: "America/Los_Angeles",
+    minNoticeHours: 24,
+    windowDays: 14,
+  },
+  pipeline: {
+    stages: [
+      "submitted",
+      "paid_pending_vetting",
+      "call_scheduled",
+      "interviewed",
+      "approved",
+      "declined",
+      "refunded",
+    ],
+    initial: "submitted",
+    bookableFrom: ["submitted", "paid_pending_vetting"],
+    approvableFrom: ["interviewed"],
+  },
+  application: {
+    required: ["firstName", "lastName", "email", "whoYouAre", "message"],
+    optional: ["linkedin", "phone", "state"],
+    defaultMaxLen: 2000,
+    maxLen: { firstName: 100, lastName: 100, email: 320, state: 100 },
+    bodyCap: 32768,
+    requireDisclaimerAck: true,
+    profileFields: ["phone", "state"],
+    crmFields: ["phone", "state", "linkedin", "whoYouAre", "message"],
+    maxArrayLen: 25,
+    validateEmail: true,
+  },
+  auth: {
+    source: "claim",
+    claim: "role",
+    ladder: ["provisional", "member", "admin"],
+    superAdmins: true,
+  },
+  account: "none",
+  sends: { adminNotification: "submit" },
+  operations: {
+    onApprove: { promoteTo: "member", send: "onboardingInvite" },
+    refund: { allowedFrom: ["paid_pending_vetting"], cancelSubscription: true },
+  },
+});
+```
+
+Replace every example value before provisioning. `account: "invite"` sends a
+real Clerk invitation; `account: "create"` creates an account server-side;
+both require a named app-readable vault secret `clerk_secret_key`. Keep
+`account: "none"` until that side effect is explicitly approved and tested.
+
+In this release, `prices.currency` and `prices.interval` record intent but do
+not control the group row, public join config, or Stripe charge. The Stripe
+Price id is authoritative. Phase 6 requires a provider-side amount, currency,
+and recurring-interval equality check before payment is exposed.
+
+The built-in application schema is fixed. With stock `/api/applications`, form
+string names are limited to `firstName`, `lastName`, `email`, `referral`,
+`referralName`, `whoYouAre`, `linkedin`, `message`, `phone`, and `state`;
+`focus` and `disclaimerAck` are special fields. Every rendered string input must
+appear in `application.required` or `optional`, and every required field must be
+rendered. `JoinIsland` currently keeps only one `FormData` value per name, so it
+cannot submit an array-valued `focus` control without a tested adapter.
+
+Do not put an arbitrary name in `required` or `optional`: config validation does
+not reject it, but the provisioned schema cannot store it. If the approved
+product requires another field, stop and either upgrade Chapter to a release
+with that field or keep a reviewed host-owned schema/submit route; do not claim
+the stock join surface supports it.
+
+Snapshot these resolved values in `chapter-contract.test.ts`:
+
+- `chapter.services`, `auth`, `pipeline`, `application`, and `operations`;
+- namespace names and default-deny rules;
+- `chapter.groupSeed()` exactly;
+- `createChapterIntegration(chapter, { now: 1_700_000_000_000 })`
+  schema/rules/seeds/probes, using the fixed clock because the integration seed
+  carries the timestamp.
+
+## Phase 3 — Provisioning and Worker shell
+
+```js
+// odla.config.mjs
+import { createChapterIntegration } from "@odla-ai/chapter";
+import { chapter } from "./src/chapter.config.mjs";
+
+export default {
+  platformUrl: "https://odla.ai",
+  dbEndpoint: "https://db.odla.ai",
+  app: { id: chapter.id, name: chapter.name },
+  envs: ["dev"],
+  services: chapter.services,
+  integrations: [createChapterIntegration(chapter)],
+  calendar: {
+    google: {
+      availabilityCalendars: { dev: ["primary"] },
+      bookingCalendar: { dev: "primary" },
+    },
+  },
+  o11y: { service: chapter.id },
+  auth: { clerk: { dev: "REPLACE_WITH_APPROVED_PK_TEST_KEY" } },
+  links: { dev: null },
+  local: {
+    tokenFile: ".odla/dev-token.json",
+    credentialsFile: ".odla/credentials.local.json",
+    devVarsFile: ".dev.vars",
+  },
+};
+```
+
+```ts
+// src/worker.ts
+import { chapterWorker } from "@odla-ai/chapter/worker";
+import { withObservability } from "@odla-ai/o11y";
+import { chapter } from "./chapter.config.mjs";
+
+export default withObservability(chapterWorker({ chapter }));
+```
+
+Use current Cloudflare agent documentation for syntax, but preserve this
+application contract in `wrangler.jsonc`:
+
+- `main` is `src/worker.ts`;
+- `nodejs_compat` is enabled for observability;
+- static assets bind as `ASSETS` from `dist`, never the repository root;
+- dev Worker name and `ODLA_TENANT=<chapter.id>--dev` are explicit;
+- dev vars identify `ODLA_ENDPOINT`, `ODLA_PLATFORM`, `ODLA_APP_ID`,
+  `ODLA_ENV=dev`, and a verified `EMAIL_FROM`;
+- the dev `ASSETS` and optional `send_email` bindings are declared inside
+  `env.dev` because Wrangler environments do not inherit bindings;
+- no production binding, route, schedule, or credential enters the dev target.
+
+Run:
+
+```sh
+npx odla-ai doctor
+npx odla-ai provision --dry-run
+```
+
+Show the resolved tenant, services, schema/rules, auth, links, and Worker target
+to the human. Then start the email-bound device handshake:
+
+```sh
+npx odla-ai provision --email <existing-odla-account> --write-dev-vars
+```
+
+The human reviews the exact device code in ODLA Studio. Google Calendar adds a
+separate browser-owned booking-consent checkpoint for availability plus
+create/reschedule/cancel access. A grant created for the retired read-only
+mirror must be reconnected. No OAuth code or token passes through the agent.
+
+## Phase 4 — Build the four application surfaces
+
+Import the application theme once, before host CSS:
+
+```ts
+import "@odla-ai/ui/themes/salt/app.css";
+import "./app.css";
+```
+
+`BrandStyle` adds brand token overrides; it does not provide the theme layer or
+member layout CSS. The host must style `join-form`, fields, payment, slots,
+cards, member rows, responsive navigation, and public content.
+
+### Public pages
+
+Build the approved route inventory, not a generic landing page. Use semantic
+ODLA UI components/classes and the same header/footer across routes. Public
+routes must render without waiting for Clerk. Include deliberate loading,
+empty, error, 404, and reduced-motion states.
+
+### Join
+
+Fetch `GET /api/join-config`; do not hardcode live price/policy/readiness. Render
+`<JoinIsland config={config}>` with labeled inputs matching the configured field
+names and a required `disclaimerAck` checkbox when configured. Test:
+
+- invalid/missing required values;
+- over-cap values and malformed email;
+- missing and accepted disclaimer acknowledgement;
+- concurrent double-click suppression and an ambiguous lost-response retry;
+- `paymentsReady: false` and `true`;
+- `schedulingReady: false`, slot conflict, booking, and completion.
+
+`JoinIsland` disables its button while one request is pending, but creates a new
+`submissionId` for every submit invocation. A retry after the server committed
+but the response was lost can therefore create another application. If that is
+unacceptable, stop and fix/upgrade the package or use a reviewed host adapter
+that keeps one stable id across logical retries. Do not label the stock behavior
+fully idempotent.
+
+### Members
+
+Use `@odla-ai/auth-clerk` to render signed-out/sign-in and signed-in states. In
+the signed-in child, build one `api(path, init)` function that calls
+`useClerkAuth().getToken()`, adds `Authorization: Bearer <token>`, checks the
+HTTP status, and returns JSON. Pass that function, `signOut`, and
+`applyHref="/join"` to `<MembersArea>`; its package default is `/join.html`.
+Do not put a Clerk secret key or ODLA admin key in browser code.
+
+### Admin
+
+```tsx
+import { ChapterAdmin } from "@odla-ai/chapter/ui/admin";
+import { chapter } from "../chapter.config.mjs";
+
+export function AdminPage() {
+  return <ChapterAdmin chapter={chapter} basePath="/admin" />;
+}
+```
+
+Keep default query routing (`/admin/?tab=people`) unless the host has a tested
+SPA fallback for every admin subpath. Pass custom sections only when the
+product truly needs additional host-owned operations.
+
+The router must serve and reload `/`, every public page, `/join`, `/members/`,
+and `/admin/` without accidentally sending API paths to the SPA.
+
+## Phase 5 — Configure Clerk and bootstrap authority
+
+At this step, read Clerk's current agent-facing CLI documentation. Use one
+Clerk application with development and production instances; do not create a
+second application for production.
+
+For default chapter claim auth, the session token must include both:
+
+```json
+{
+  "email": "{{user.primary_email_address}}",
+  "role": "{{user.public_metadata.role}}"
+}
+```
+
+Put only the development publishable key in `auth.clerk.dev`. Set the owner's
+Clerk `public_metadata.role` to `"admin"`. If that owner may grant/change admin
+roles, add their lowercase email to `superAdmins` in ODLA Studio.
+
+For `mode: "hub"` with table auth, add the first admin's lowercase email to the
+`admins` namespace instead. A mixed-case row silently fails to match.
+
+If account creation/invitation or role writes are enabled, transfer the
+app-readable named secret—not the platform-reserved Clerk sync secret:
+
+```sh
+npx odla-ai secrets set clerk_secret_key --env dev --stdin
+```
+
+Supply the value through stdin or a named environment variable without echoing
+it. `secrets set-clerk-key` writes the reserved `$clerk_secret`; Chapter cannot
+read that key as `clerk_secret_key`. The generic named-secret command does not
+validate Clerk instance prefixes: independently confirm the dev source begins
+with `sk_test_`. Never put `sk_live_` in dev; production requires `sk_live_`,
+the literal `prod` environment, and explicit production approval.
+
+Test signed out, provisional, member, admin, super-admin, malformed bearer,
+expired session, forbidden account, sign out, and safe return routing on the
+deployed dev origin.
+
+## Phase 6 — Configure Stripe, calendar, and email
+
+### Stripe test mode
+
+1. Create the approved recurring test product/price.
+2. Point a Stripe test webhook to
+   `https://<dev-origin>/api/webhooks/stripe`.
+3. Store `stripe_secret_key` and `stripe_webhook_secret` as named dev vault
+   secrets through write-only `odla-ai secrets set ... --stdin`.
+4. In the guarded `groups` row, set `stripePublishableKey` and `stripePriceId`.
+5. Read that exact Stripe Price from Stripe and compare its first charge,
+   recurring amount, currency, and interval with the approved public contract.
+6. Send and verify a Stripe test event before opening the payment UI.
+
+`paymentsReady` checks the publishable key, price id, and Stripe secret key; it
+does not prove the webhook secret works or that the Price matches Chapter's
+displayed cents. The built-in formatter is USD/dollar-specific in this release;
+non-USD or unmatched pricing needs a host UI/route and cannot use the stock
+payment presentation. Never accept money until the provider equality check and
+webhook test prove authoritative paid/refunded state and idempotent replay.
+
+### Google Calendar
+
+Complete the human Google booking consent from provisioning, then:
+
+```sh
+npx odla-ai calendar calendars --env dev --json
+npx odla-ai calendar status --env dev --json
+```
+
+Refine the checked-in calendar ids and re-provision. Verify
+`GET /api/schedule/slots` returns `schedulingReady: true` and real bounded test
+slots. It returns HTTP 200 with `schedulingReady: false` when unavailable, so a
+generic HTTP smoke check is insufficient. Book and rebook one synthetic
+applicant and confirm the Google invitation/Meet behavior.
+
+### Email
+
+Configure Cloudflare's Email Service binding and an onboarded `EMAIL_FROM`.
+Keep `debugEmail` in every non-production Chapter. Send a test lifecycle email,
+prove it is redirected to the debug address, and confirm the bounded
+`emailLog`. If `account: "invite"` is selected, separately prove a test
+applicant receives a Clerk invitation. Chapter deduplicates a replay after the
+success log exists; it does not serialize two concurrent sends. If true
+exactly-once delivery is required, add a serialized outbox or provider
+idempotency and test the concurrent case.
+
+## Phase 7 — Local and deployed development acceptance
+
+Before the first deploy:
+
+```sh
+npm test
+npm run typecheck
+npm run build
+npx odla-security scan . --profile odla --out .odla/security/latest --fail-on high --fail-on-candidates critical
+npx wrangler dev --env dev
+```
+
+Required local contracts:
+
+- config/integration snapshots described above;
+- full join form, members gate, admin theme, and public routes render;
+- `/api/health`, `/api/config`, `/api/join-config`, static fallback, and 404;
+- valid/invalid application plus `disclaimerAckAt`;
+- signed-out/member/admin authorization matrix;
+- CRM routes and default-deny behavior;
+- no secret-shaped value in source or client bundle.
+
+Review every security candidate; a clean deterministic scan is not proof the
+application is safe. Run the optional hosted ODLA security pass only after the
+human reviews its current disclosure plan and explicitly approves the required
+redacted-source acknowledgement.
+
+Deploy only the dev Worker:
+
+```sh
+npm run deploy:dev
+```
+
+Record the actual URL and Cloudflare version id. Put the exact URL in
+`links.dev`, re-run the provision dry run, then deliberately transfer Worker
+secrets:
+
+```sh
+npx odla-ai provision --email <existing-odla-account> --write-dev-vars --push-secrets
+npx odla-ai smoke --env dev
+```
+
+Run a real deployed journey:
+
+1. public home and every navigation/deep link;
+2. join-config readiness, application submit, test payment, booking;
+3. Clerk account/invite behavior selected by config;
+4. provisional and member area;
+5. admin sign-in, people/CRM, application approval, meeting, billing, email;
+6. replay/idempotency and one safe error;
+7. o11y trace with no secret, email, token, or request body;
+8. visual review at the four target widths in light/dark mode.
+
+The human reviews the actual browser result. Source inspection is not visual
+acceptance.
+
+## Phase 8 — Production checkpoint
+
+Production is a separate operation. Only after dev acceptance:
+
+1. add `prod` to `envs`, `auth.clerk.prod`,
+   `calendar.google.availabilityCalendars.prod`,
+   `calendar.google.bookingCalendar.prod`, `links.prod`, and reviewed top-level
+   Wrangler prod vars/bindings;
+2. use the production instance of the same Clerk app and Stripe live-mode
+   resources;
+3. run `doctor`, production build/tests, the installed ODLA security preflight,
+   and `provision --dry-run`;
+4. show the complete production plan, secrets, routes, email, billing, and
+   rollback to the human;
+5. after explicit approval, provision with `--yes`, transfer each prod secret
+   through write-only flows, deploy the off-route candidate, and run
+   `smoke --env prod`;
+6. repeat the entire Chapter journey with production-safe synthetic data before
+   attaching DNS or accepting real money/mail;
+7. record the previous Worker version and route configuration as runtime
+   rollback. Preserve database rows during rollback; do not reset data.
+
+The build is complete only when the checked-in decisions, deployed dev journey,
+provider readiness, responsive visual review, and production rollback evidence
+all exist. A working homepage or passing ODLA smoke alone is not a Chapter
+website.