@odla-ai/chapter 0.20.1 → 0.20.2

package/README.md

@@ -1,13 +1,14 @@
 # @odla-ai/chapter
 
-A foundation for **membership sites**. One `defineChapter({...})` config stands up
-a full public member site — join/apply → Stripe membership → Google booking →
-member area — plus an admin console and a CRM, or an **admin-only hub**, on
+A foundation for **membership sites**. One `defineChapter({...})` config resolves
+the shared application engine — join/apply → Stripe membership → Google booking
+→ member area — plus an admin console and CRM, or an **admin-only hub**, on
 odla-db + Clerk + [@odla-ai/crm](https://odla.ai/docs/packages/crm) + calendar +
-email.
+email. The host still builds the public pages, routing, and brand presentation;
+Chapter supplies their application mechanics.
 
 ```sh
-npm i @odla-ai/chapter
+npm i --save-exact @odla-ai/chapter@0.20.2
 ```
 
 > **Agentic experiment.** Built and maintained by AI agents from bounded runbooks
@@ -17,12 +18,32 @@ npm i @odla-ai/chapter
 > and leader → follower record delivery ship. APIs may still tighten before 1.0;
 > pin the package and run schema/route contract tests in every site.
 
+## Agent runbooks
+
+The API examples below are not a website-build plan. An LLM or coding agent must
+choose and read one of these version-matched runbooks from the installed npm
+package before changing a site:
+
+- **Empty repo or a genuinely new product:** read
+  [`runbooks/greenfield.md`](./runbooks/greenfield.md) completely. It covers the
+  brand brief, public information architecture, Chapter configuration,
+  member/admin surfaces, Cloudflare/ODLA setup, and visual + journey acceptance.
+- **Existing or deployed site:** read
+  [`runbooks/adopt-existing.md`](./runbooks/adopt-existing.md) completely. It
+  preserves the existing product, URLs, visual identity, data, auth, jobs, and
+  rollback boundary while Chapter becomes the primary implementation.
+
+Do not combine the two flows. A provisioned canary is not a completed adoption,
+and a greenfield build does not need migration machinery. Both runbooks keep
+secrets out of source and require development proof before production.
+
 ## The shape
 
 - **One config, two profiles.** `defineChapter()` validates at import and returns
-  a resolved engine. `mode: "chapter"` is the full public member site; `mode:
-  "hub"` is admin-only and CRM-focused. The mode gates the member/join/payment
-  route surface; everything else (auth, CRM, chrome, provisioning) is shared.
+  a resolved engine. `mode: "chapter"` enables the complete public-member
+  application profile; `mode: "hub"` is admin-only and CRM-focused. The mode
+  gates the member/join/payment route surface; everything else (auth, CRM,
+  chrome, provisioning) is shared.
   `chapter.brand` and `chapter.network` are resolved from this same config, so
   the browser UI does not need a second identity or follower registry.
 - **The worker is the package.** `chapterWorker({ chapter })` is the whole
@@ -31,11 +52,15 @@ npm i @odla-ai/chapter
   `/api/admin/network/{targets,push}`. Chapter mode adds the public
   member surface (`/api/join-config`, `/api/applications`,
   `/api/schedule/{slots,book}`, `/api/payments/subscription`,
-  `/api/webhooks/stripe`) and the admin operational routes (`/api/admin/*`), then
-  falls back to static assets. Your `src/worker.ts` is ~3 lines. Observability is
-  a host concern — wrap it with `withObservability` from `@odla-ai/o11y`.
-  Everything brand-specific (prices, policy copy, email templates, scheduling
-  rules) is read at runtime from a single odla-db `groups` row, never hardcoded.
+  `/api/webhooks/stripe`). The `/api/admin/*` handlers are registered in both
+  modes; expose only the sections compatible with the selected profile and its
+  provisioned namespaces. The Worker then falls back to static assets. Your
+  `src/worker.ts` is ~3 lines. Observability is a host concern — wrap it with
+  `withObservability` from `@odla-ai/o11y`.
+  Operational values that owners may change (prices, policy copy, email
+  templates, scheduling rules) are read at runtime from a single odla-db
+  `groups` row. Brand identity and build-time tokens remain in the checked-in
+  Chapter config.
 - **A route seam, not a black box.** `chapterWorker({ chapter, routes })` runs
   your handlers *before* the built-ins (add routes, or override/alias a path),
   each receiving the same context the built-ins get. The worker entry also exports
@@ -46,13 +71,15 @@ npm i @odla-ai/chapter
   *or* an odla-db `admins` allowlist, plus a read-only `superAdmins` tier —
   selected by `auth.source`, defaulting per mode. Escalation guards
   (`canChangeRole`) are package-enforced.
-- **Correctness is packaged, not per-site.** Exactly-once email
-  (`sendTemplated`/`isAlreadySent`), a non-prod delivery fail-safe
-  (`planDelivery`), status-never-backwards (`canTransition`), Stripe webhook
-  integrity (`verifyStripeSignature`) with the webhook as the authoritative writer
-  of paid/refunded, one-subscription-per-application idempotency, meetings-as-
-  canonical booking (a rebooking *reschedules* the event, preserving the Meet
-  link), Google-edit adoption (`reconcileMeetings`), and a one-way CRM projection.
+- **Correctness is packaged, not per-site.** Replay-deduplicated email
+  (`sendTemplated`/`isAlreadySent`; concurrent sends still need a serialized
+  outbox/provider idempotency for a true exactly-once guarantee), a non-prod
+  delivery fail-safe (`planDelivery`), status-never-backwards (`canTransition`),
+  Stripe webhook integrity (`verifyStripeSignature`) with the webhook as the
+  authoritative writer of paid/refunded, one-subscription-per-application
+  idempotency, meetings-as-canonical booking (a rebooking *reschedules* the
+  event, preserving the Meet link), Google-edit adoption (`reconcileMeetings`),
+  and a one-way CRM projection.
 - **Provisioning is declarative.** `createChapterIntegration(chapter)` composes
   the crm namespaces + the chapter namespaces (`applications`, `groups`,
   `meetings`, `emailLog`, plus the auth tables) + a guarded group-row seed. Drop
@@ -103,7 +130,7 @@ console instead of failing silently. To brand it, pass `brand.palette` /
 override the shared visual grammar in both modes. When the `chapter` prop is
 present, `ChapterAdmin` installs those brand tokens itself.
 
-## Quick start
+## API quick start
 
 ```ts
 // src/chapter.config.mjs
@@ -153,11 +180,10 @@ export default {
 };
 ```
 
-That is the reusable application shell. The follower's public pages remain
-site-owned: start from a reference design and `@odla-ai/ui` marketing
-components, then change the wordmark, palette, copy, imagery, and investment
-thesis. Do not fork auth, admin routing, CRM, payment, booking, or account logic
-to achieve a different brand.
+That is the reusable application shell. Public pages remain site-owned: start
+from the approved product and brand brief plus `@odla-ai/ui` marketing
+components. Do not copy a reference site's identity or fork auth, admin routing,
+CRM, payment, booking, or account logic to achieve a different brand.
 
 ### Leader → follower delivery
 
@@ -314,6 +340,10 @@ ordinary static subdirectories. Legacy path links still open, and
 
 ## Adopting into an existing site
 
+For the complete ordered conversion and cutover procedure, use
+[`runbooks/adopt-existing.md`](./runbooks/adopt-existing.md). The notes below
+are the package-specific behavior reference, not a complete adoption plan.
+
 A real conversion (the site this was extracted from) went from a 2,094-line
 worker to 6 lines and deleted ~2,500 lines. The order that worked:
 
@@ -419,13 +449,15 @@ These bite silently — a smoke test won't catch them:
 
 ### Install + scope notes
 
-- **Your first admin is seeded in odla Studio, by hand — and the email must be
-  lowercased.** Neither `admins` nor `superAdmins` is ever written by a worker
-  route or a provisioning seed; that is deliberate, so nothing running in the app
-  (or injected into a page) can grant admin. The gate looks the email up
-  lowercased, so a row saved as `Ada@Example.com` matches nothing and the account
-  silently isn't an admin — with no error to tell you. Save it lowercase, then
-  confirm by signing in, not by looking at the row.
+- **Bootstrap the first admin according to the selected auth source.** Chapter
+  mode defaults to Clerk claims: set the first operator's Clerk
+  `public_metadata.role` to `admin`. If that operator also needs the
+  read-only cross-site tier, add their lowercase email to `superAdmins` in odla
+  Studio. Hub mode defaults to table auth: add the first operator's lowercase
+  email to `admins` in Studio. Neither allowlist is ever written by a worker
+  route or provisioning seed; that is deliberate, so the running app cannot
+  grant itself admin. Confirm the result by signing in, not merely by inspecting
+  the row.
 - **`@odla-ai/auth-clerk` is not a chapter peer.** It is deliberately absent from
   this package's manifest, because only one entry imports it: the worker verifies
   JWTs with `jose` via `ctx.verifyUser`, and `@odla-ai/chapter/ui/member` is
@@ -434,11 +466,18 @@ These bite silently — a smoke test won't catch them:
   `@odla-ai/auth-clerk/invitations` when you want to send your own branded
   invitation mail. Importing the full `@odla-ai/chapter/ui` barrel pulls the admin
   half, so prefer the narrower entry.
-- **Known-good version set** (installs clean, no flags): `@odla-ai/chapter` 0.20.0,
-  `@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, CLI 0.17.1, plus `jose` and
-  react (or `preact` + `preact/compat`). chapter is the package that pulls the
-  others together, so this is the line to check when an install complains.
+- **Known-good application set** (installs clean, no flags):
+  `@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, and `react-dom` 19.2.7.
+- **Known-good React host toolchain:** `@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,
+  and Wrangler 4.107.0. The greenfield runbook standardizes on this exact React
+  matrix; a Preact host needs its own tested compatibility set.
 - **`--legacy-peer-deps` is a diagnostic, not a setting.** It suppresses exactly
   the peer conflict that tells you a pair is unsupported. If you need it, find out
   why first.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odla-ai/chapter",
-  "version": "0.20.1",
+  "version": "0.20.2",
   "description": "A leader/follower foundation for branded membership sites: shared CRM, admin, auth, payments, booking, and explicit record delivery from one defineChapter config.",
   "license": "MIT",
   "homepage": "https://odla.ai/docs/packages/chapter",
@@ -40,7 +40,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "runbooks"
   ],
   "sideEffects": false,
   "engines": {

package/runbooks/adopt-existing.md

@@ -0,0 +1,505 @@
+# Adoption runbook: convert an existing site to Chapter
+
+Audience: an LLM or coding agent converting an existing or deployed website,
+Worker, database, auth flow, or operating membership product.
+
+Read this file completely before changing the application. Also read the
+installed package `README.md`, `package.json` exports, and `dist/*.d.ts`. The
+existing product stays live until measured Chapter parity and cutover are
+approved.
+
+If the repository is empty and no operating state exists, use
+[`greenfield.md`](./greenfield.md).
+
+## Completion means conversion, not installation
+
+The following are canary evidence only:
+
+- installing `@odla-ai/chapter`;
+- writing `defineChapter()` or rendering `ChapterAdmin`;
+- provisioning an ODLA tenant;
+- serving a login screen or one Chapter API route;
+- deploying a parallel Worker with copied sample data.
+
+Adoption is complete only when the real product routes and journeys use Chapter
+as the primary implementation, live data is reconciled and continuously
+handled, production reads and writes have crossed explicit gates, and both
+runtime and data rollback remain proven.
+
+## Non-negotiable boundaries
+
+1. Never mutate, reset, delete, detach, or repoint current production resources
+   during development adoption. Preserve Workers, Pages projects, domains,
+   databases, R2/KV, queues, Workflows, cron, webhooks, Clerk, Stripe, email,
+   Google calendars, source repositories, and immutable history.
+2. Never print or commit secrets. Dev and production use separate credentials
+   and explicitly targeted Worker environments.
+3. Preserve existing public URLs, content, SEO, header/navigation, responsive
+   layout, theme behavior, accessibility, and branded assets unless the human
+   approves a product change. Framework replacement is not redesign authority.
+4. Preserve data semantics before deleting code. Chapter schema, routes, sends,
+   auth, account, payment, and scheduling defaults are hypotheses until parity
+   tests prove them.
+5. Runtime rollback and data rollback are different. Restoring an old Worker
+   cannot recover writes accepted after Chapter became authoritative.
+6. No silent fallback. A Chapter-primary failure is explicit and measured; a
+   legacy fallback, if approved, is named, time-bounded, and visible.
+7. Keep ODLA rules default-deny and every admin/provider mutation
+   server-mediated.
+
+## Phase 0 — Freeze the operating baseline
+
+Create or extend root `MIGRATION.md`; never replace its history. Record state
+`inventoried` only after the human approves the baseline.
+
+### Inventory the product
+
+- every public, member, admin, API, webhook, health, asset, feed, and 404 route;
+- current production/dev origins, Worker/Pages names and version ids, routes,
+  DNS, compatibility settings, build automation, and rollback versions;
+- D1/SQL/ODLA/KV/R2/files and every reader/writer;
+- queues, Workflow definitions, cron, provider webhooks, retry/outbox behavior;
+- Clerk app/instances, JWT claims, roles/allowlists, redirects, and first-admin
+  process;
+- Stripe products/prices/webhooks/idempotency, Google calendars, Email Service;
+- current schema/rules, row counts, earliest/latest timestamps, natural keys,
+  relations, projections, and owner-edited fields;
+- public/private content boundaries and every raw HTML/Markdown/inline-JSON
+  render sink;
+- telemetry, freshness/error alerts, deploy commands, and CI auto-deploys.
+
+### Freeze visual and behavior evidence
+
+Capture representative production screenshots and measured layouts at 390,
+768, 1280, and 1440 pixels in every supported theme. Record:
+
+- header height, wordmark/nav alignment, responsive breakpoints, page geometry;
+- form fields/labels/errors, Clerk containment, tables/cards/rails, loading,
+  empty, error, unauthorized, and 404 states;
+- full public route/link inventory, titles, descriptions, canonical URLs,
+  structured data, robots/sitemap/feed behavior;
+- join, payment, booking, member, admin, CRM, email, and refund journeys.
+
+Do not rely on visual memory. These fixtures are acceptance authority until a
+human explicitly approves a redesign.
+
+### Define migration budgets
+
+Record accepted count/hash differences, maximum sync lag/newest-data age, route
+and status parity, latency/error budget, visual tolerances, identity merge
+policy, deterministic synthetic user/application ids, and an observation
+window. Record both rollback plans before any Chapter write.
+
+Maintain a migration matrix:
+
+| Track | Legacy authority | Chapter/ODLA dev target | Current reads | Current writes | Evidence/freshness | Rollback | State |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| runtime/bindings | | | | | | | |
+| membership data/CRM | | | | | | | |
+| jobs/webhooks/outboxes | | | | | | | |
+| Clerk/auth | | | | | | | |
+| Stripe/payments | | | | | | | |
+| calendar/booking | | | | | | | |
+| email | | | | | | | |
+| public/member/admin UI | | | | | | | |
+| o11y/alerts | | | | | | | |
+
+Allowed states: `not-started`, `canary`, `parallel`, `verified`,
+`primary-dev`, `primary-prod`, `retired`, or `n/a` with a reason.
+
+## Phase 1 — Model Chapter without deleting anything
+
+Install the version-matched agent guidance and inspect the automation boundary:
+
+```sh
+npx @odla-ai/cli@0.17.1 setup
+npx @odla-ai/cli@0.17.1 capabilities --json
+```
+
+Pin the exact known-good package matrix from the installed Chapter README.
+For this runbook, first require
+`npm view @odla-ai/chapter@0.20.2 version` to succeed. Install every runtime,
+toolchain, CLI, and security package with the exact versions in that README;
+never use `latest`, a range, or `--legacy-peer-deps`.
+
+Write `src/chapter.config.mjs` from the inventory. Make every behavior decision
+explicit:
+
+- `mode`, `services`, complete light/dark brand tokens;
+- price/currency/interval and owner-approved policy copy;
+- email addresses/templates/debug redirect and send trigger;
+- scheduling/timezone and pipeline stages/bookable/approvable subsets;
+- exact application fields, caps, disclaimer requirement, Clerk-visible
+  `profileFields`, and CRM-projected `crmFields`;
+- claim/table auth, ladder/super-admin tier;
+- account side effect (`none`, `create`, or emailed `invite`);
+- approve/refund policy and any network targets/field allowlists.
+
+### Schema/rule parity gate
+
+Before deleting old schema/rules/provisioning:
+
+1. freeze the legacy schema and rules as reviewed test fixtures;
+2. normalize only approved representational differences;
+3. compare `createChapterIntegration(chapter)` namespaces, attrs, links, rules,
+   and seeds to the fixtures;
+4. fail on missing fields, widened rules, cardinality changes, renamed natural
+   keys, new client-readable data, or unapproved seed differences;
+5. record every intentional delta and migration mapping in `MIGRATION.md`.
+
+`createChapterIntegration()` inserts the group seed only when absent. Existing
+runtime owner edits do not update from later config changes. Compare the current
+group row field by field, classify ownership, and write an explicit migration
+for approved differences.
+
+### Behavior-delta gate
+
+At minimum audit:
+
+- services default (`db`, `calendar`, `o11y`);
+- per-field and request-body caps;
+- account default `none` and outbound effects of `create`/`invite`;
+- stock `JoinIsland` generates a fresh `submissionId` on each invocation, so an
+  ambiguous retry after a lost response is not idempotent even though a
+  concurrent click is disabled;
+- Clerk-client-readable `public_metadata.profile`;
+- application-to-CRM projection fields;
+- required disclaimer acknowledgement and `disclaimerAckAt`;
+- initial/bookable/approvable stages and never-backwards transitions;
+- when each lifecycle email fires;
+- Chapter recognizes only the literal `prod` environment as live mail; the
+  CLI-valid alias `production` follows the non-production fail-safe;
+- approve promotion/email and refund/subscription behavior;
+- Chapter route names and member/admin routing;
+- Chapter's insert-only group seed and runtime-edited fields;
+- payment readiness versus actual webhook readiness;
+- calendar's HTTP-200 `schedulingReady: false` degradation.
+
+The stock `applications` namespace is fixed. Its configurable form strings are
+limited to `firstName`, `lastName`, `email`, `referral`, `referralName`,
+`whoYouAre`, `linkedin`, `message`, `phone`, and `state`; `focus` and
+`disclaimerAck` are special. An unknown configured field can pass config
+validation and then fail at the database. Preserve a host schema/submit route
+for every legacy field that cannot be mapped without loss.
+
+The current `prices.currency` and `prices.interval` values do not control
+storage, join config, formatting, or the Stripe subscription. Treat the live
+Stripe Price as authoritative and make provider-side amount/currency/interval
+equality a cutover gate.
+
+Keep one test per accepted behavior decision so a package upgrade cannot change
+the site silently.
+
+### Make the dev descriptor executable
+
+Before Phase 2, create or adapt `odla.config.mjs`. A repository with no ODLA
+config may use the installed exact CLI's `init` command as a starting point,
+but the reviewed result must declare:
+
+- the existing product's one app id/name and only `envs: ["dev"]`;
+- explicit `chapter.services`;
+- `integrations: [createChapterIntegration(chapter)]` plus any compatible,
+  non-overlapping host integrations;
+- the intended dev Clerk publishable key, calendar ids, o11y service, local
+  credential paths, and a null/off-route dev link.
+
+Do not provision both a legacy inline schema and the Chapter integration for the
+same namespaces. After the schema/rule parity gate passes, freeze the legacy
+descriptor as a test fixture and make the reviewed Chapter integration the
+active dev descriptor. Production configuration remains absent.
+
+Create an off-route dev Worker entry using
+`chapterWorker({ chapter, routes: legacyRoutes })`, wrapped with o11y, and an
+explicit `wrangler ... --env dev` target. Keeping all legacy handlers as host
+routes at this point changes no route ownership; it only makes the canary and
+Chapter data surface executable.
+
+### Add a fail-closed migration readiness route
+
+The built-in `/api/health` is only `{ "ok": true }`; it does not touch the
+database. Add an admin-only host route or executable command that returns `503`
+until all of these match the acceptance manifest:
+
+- literal tenant/app/env and Chapter/package release;
+- expected schema/rules digest and required group/config rows;
+- reconciled counts, natural-key collisions, relation integrity, and newest
+  source timestamp within the freshness budget;
+- zero unhandled quarantines and bounded/zero pending outbox work;
+- healthy continuous sync and the Chapter-primary-to-legacy rollback mirror.
+
+Return only redacted counts/digests. This gate is allowed to fail during initial
+canary work; it must be mechanically green before switching either reads or
+writes, and after every rollback recovery.
+
+## Phase 2 — Create an isolated dev canary
+
+Run:
+
+```sh
+npx odla-ai doctor
+npx odla-ai provision --dry-run
+```
+
+The dev topology must be distinct from production:
+
+- `envs: ["dev"]`, tenant `<app-id>--dev`;
+- explicit dev Worker name and `wrangler ... --env dev`;
+- no production route, DNS, database binding, queue, Workflow, cron, webhook,
+  Git writer, Stripe live resource, email recipient, or Google write authority;
+- `debugEmail` enabled and Stripe test mode only;
+- dev Clerk `pk_test_...` from the intended workspace/application;
+- o11y wrapped around the real canary handler with safe low-cardinality labels.
+
+Show the dry-run target, schema/rules, services, link, and secret recipients.
+After the human approves the device code:
+
+```sh
+npx odla-ai provision --email <existing-odla-account> --write-dev-vars --push-secrets
+npm run build
+npx wrangler deploy --env dev
+npx odla-ai smoke --env dev
+```
+
+If credential transfer alone must be retried, use the non-rotating
+`npx odla-ai secrets push --env dev`; do not reprovision or rotate by default.
+Verify the deployed Chapter health marker, a database-backed read, and an
+unauthenticated private-route rejection. Record the URL and Cloudflare version
+id. A canary advances matrix rows only to `canary`; the migration-readiness
+route is expected to remain `503` until Phase 3 evidence passes.
+
+## Phase 3 — Adopt data with replay and reconciliation
+
+Skip historical backfill only when the human-approved inventory proves the
+site has no operating data. Otherwise:
+
+1. Write a checked-in mapping for every legacy table/collection/file and
+   relation: natural key, target namespace, attrs, omissions/nulls, edge
+   direction, ownership, tombstone/deletion behavior, and provenance.
+2. Freeze a source snapshot or bounded high-water mark. Record counts,
+   earliest/latest timestamps, and a digest/immutable id.
+3. Backfill in bounded deterministic chunks using stable mutation ids.
+   Persist checkpoints and a rejection ledger; each input is written, skipped
+   with reason, or failed/retryable.
+4. Replay from an earlier checkpoint and prove no duplicate applications,
+   people, companies, meetings, email log entries, relations, or side effects.
+5. Generate a redacted reconciliation report: counts, required attrs, duplicate
+   natural keys, dangling relations, identity collisions, status/price/role
+   differences, and newest timestamps.
+6. Preserve human-owned fields. Automated projection omits fields it does not
+   own rather than reading and writing stale copies.
+
+### Continuous operation
+
+Choose one durable event boundary for production-shaped changes. New legacy
+applications, payments, role changes, meetings, CRM edits, and emails must reach
+the dev Chapter projection through a measured outbox/queue/replay process.
+Record oldest pending age, attempts, quarantine, and source-to-target lag.
+
+Backfill alone is not conversion. Advance to `continuously-synced` only after
+normal schedules/webhooks are observed and failures replay from durable state.
+
+### Shadow reads
+
+For list/detail/search/admin dashboard/member status/join config, read both
+legacy and Chapter in dev while still serving the legacy response. Compare
+normalized status, ids, ordering, counts, fields, relations, price/policy, and
+freshness. Log bounded diffs, never private row bodies.
+
+At separate human checkpoints:
+
+1. switch dev reads to Chapter and make failures explicit;
+2. switch accepted dev writes to Chapter;
+3. durably mirror Chapter-primary writes back to the legacy rollback authority;
+4. simulate ODLA unavailable and rollback-mirror unavailable.
+
+Every authenticated/admin mutator must use this authority contract or be
+disabled. A separate Chapter demo route does not satisfy primary-dev.
+
+## Phase 4 — Adopt the Worker and routes in safe order
+
+Do not replace schema, worker, routes, and UI in one unreviewable change.
+
+1. Re-assert that the active dev descriptor is the reviewed
+   `createChapterIntegration(chapter)` from Phase 1 and that the legacy
+   provisioner remains only as a parity fixture.
+2. Start from the off-route `chapterWorker({ chapter, routes })` canary. Host
+   routes run before built-ins and receive Chapter's existing context
+   (`verifyUser`, `makeDb`, `roleFor`, `isAdmin`); do not verify JWTs twice.
+3. Initially keep every bespoke endpoint as a host route. Alias legacy URLs to
+   Chapter behavior instead of breaking clients.
+4. Compare built-in and legacy behavior route by route; only then remove a host
+   route that Chapter fully owns.
+5. Keep static fallback and API handling explicit so unknown APIs cannot fall
+   through to a successful SPA document.
+
+Test public/private method policies, body limits, idempotency, auth 401 vs 403,
+safe redirects, webhook signatures/replay, scheduling conflict,
+replay-deduplicated and concurrent email sends, and unavailable-provider
+degradation. Chapter's email log prevents a later replay after success; it does
+not serialize two concurrent sends, so preserve a stricter existing outbox or
+provider-idempotency contract.
+
+## Phase 5 — Adopt UI without losing the product
+
+### Preserve first
+
+Render the Chapter component beside the current implementation in a dev-only
+fixture. Compare markup/behavior and the Phase 0 screenshots before deletion.
+
+- Import `@odla-ai/ui/themes/salt/app.css` before host CSS.
+- Map the legacy design tokens into `brand.palette` and `paletteDark`; do not
+  carry an unbounded parallel theme system.
+- Public pages remain site-owned. Preserve their content hierarchy, imagery,
+  URLs, SEO, and responsive geometry.
+- Replace join orchestration with `JoinIsland`, member behavior with
+  `MembersArea`, and admin with `<ChapterAdmin chapter={chapter}/>` only after
+  field/auth/action parity.
+- The host still supplies member CSS and the Clerk wrapper around
+  `MembersArea`; Chapter does not ship a whole public stylesheet.
+- Scope host form styles. Bare `input`, `button`, `select`, `textarea`, `label`,
+  or global box-model rules must not corrupt Clerk/vendor DOM.
+
+### Required visual acceptance
+
+At 390, 768, 1280, and 1440 pixels in every theme, compare:
+
+- identical product header/navigation position between public/member/admin;
+- wordmark, text baseline, theme control, active state, and hover/focus;
+- join fields/errors, payment and slot picker, Clerk sign-in containment;
+- member cards/actions and every admin section/table/drawer;
+- no clipped labels, card text escape, accidental document scroll, or
+  horizontal overflow;
+- loading, empty, error, unauthorized, 404, and reduced-motion states.
+
+The human approves deployed screenshots/browser behavior. Passing CSS tests is
+not visual parity.
+
+## Phase 6 — Provider and authorization parity
+
+### Clerk
+
+Use the same Clerk application/workspace. Chapter claim mode requires session
+claims for both email and role; hub table mode uses lowercase `admins` rows.
+Prove existing allowed/forbidden users, role ladder, super-admin behavior,
+malformed/expired sessions, sign-out, and return targets.
+
+If the legacy verifier enforces JWT `aud` or `azp`, keep that host verifier in
+front of Chapter. This Chapter release verifies issuer but does not expose or
+enforce the CLI-provisioned Clerk audience. Add wrong-audience and
+wrong-authorized-party fixtures; do not cut over auth until the legacy contract
+still rejects them.
+
+When Chapter needs server-side account/role operations, set the named
+app-readable `clerk_secret_key` through:
+
+```sh
+npx odla-ai secrets set clerk_secret_key --env dev --stdin
+```
+
+Do not substitute `secrets set-clerk-key`; it writes the platform-reserved
+`$clerk_secret`, which Chapter cannot read under the named key. The generic
+command does not validate Clerk instance prefixes: independently confirm dev
+uses `sk_test_`. Never put `sk_live_` in dev.
+
+### Stripe
+
+Use test resources and an isolated dev webhook. Store `stripe_secret_key` and
+`stripe_webhook_secret` write-only; reconcile group `stripePublishableKey` and
+`stripePriceId`. Read that exact Stripe Price from Stripe and prove its first
+charge, recurring amount, currency, and interval match the rendered and
+approved contract. `paymentsReady: true` proves neither that equality nor
+webhook readiness; Chapter's built-in money formatter is USD/dollar-specific in
+this release. Preserve a host UI/route for non-USD or mismatched pricing. Test
+successful payment, duplicate webhook, failure, refund, and subscription
+cancellation before switching the UI.
+
+### Calendar and email
+
+Complete dev Google booking consent, reconnecting any grant from the retired
+read-only mirror, then prove actual slots, booking, rebooking, cancellation,
+and invitation behavior. `schedulingReady: false` with HTTP 200 is a failed
+readiness gate, not a pass.
+
+Use a verified dev sender plus `debugEmail`; prove every lifecycle template,
+recipient redirect, replay deduplication, concurrent-send behavior, and the
+selected account invitation effect. Never let dev send to imported members.
+
+## Phase 7 — Full deployed-dev journey
+
+Check in an executable acceptance manifest with:
+
+- actual dev URLs and Worker version ids;
+- deterministic synthetic member/application ids;
+- expected routes/statuses, schema/counts/freshness, and Chapter backend marker;
+- expected migration-readiness inputs and a `200` only when each is green;
+- expected account, payment, booking, email, CRM, and admin outcomes;
+- expected o11y service/release and safe trace;
+- replay and failure-injection outcomes;
+- visual viewport/theme fixtures.
+
+Run the real journey:
+
+1. browse every public route/deep link and verify SEO/404/method behavior;
+2. submit the configured join form, including consent;
+3. execute Stripe test payment and authoritative webhook;
+4. book/rebook the intro call and receive the debug-routed email;
+5. sign in as provisional/member/admin and use the real member/admin pages;
+6. perform every admin mutation family and verify Chapter-primary audit plus
+   legacy rollback mirror;
+7. replay the event and prove no duplicate row, charge, booking, account, or
+   email;
+8. inject ODLA/provider/mirror failure, observe explicit failure/retry, recover;
+9. verify freshness/continuous-sync budget and visual parity;
+10. require the fail-closed migration-readiness gate to return `200`;
+11. follow safe o11y evidence across the real Worker.
+
+`doctor`, unit tests, build, CLI smoke, a login page, and a human-looking admin
+screen are necessary but not sufficient.
+
+## Phase 8 — Production parallel run and cutover
+
+Do not add production until the human approves the full dev report and both
+rollback plans.
+
+1. Add only the literal `prod` environment using the production instance of the
+   same Clerk app, Stripe live resources, approved email sender, calendars,
+   links, and distinct secret targets. Do not use the CLI-valid alias
+   `production`: Chapter would suppress or debug-redirect lifecycle mail.
+2. Run production build/tests/security scan, `doctor`, and
+   `provision --dry-run`; inspect CI/Workers Builds so merging cannot
+   auto-deploy the legacy production target unexpectedly.
+3. After explicit approval, provision with `--yes` and deploy a production
+   Chapter candidate off-route. Record its version id.
+4. Repeat historical backfill, reconciliation, continuous sync, shadow reads,
+   provider checks, and a production-safe synthetic journey against production
+   source data. Dev data is not a production backfill.
+5. At one checkpoint, require the fail-closed readiness gate to return `200`,
+   then switch production reads. Verify freshness, auth, visual behavior, and
+   explicit failure handling while legacy writes continue.
+6. At a second checkpoint, record a write high-water mark, require readiness
+   again, and make Chapter authoritative for writes. Keep the durable legacy
+   rollback mirror and continuously reconcile it.
+7. Abort when write loss, unbounded lag, unexplained diff, auth failure,
+   freshness breach, or accepted error budget is crossed.
+
+### Runtime rollback
+
+Restore the recorded known-good Worker version plus routes, bindings, triggers,
+and domains. Verify representative routes and health. Keep Chapter resources
+and telemetry for investigation; do not delete them.
+
+### Data rollback
+
+Pause/drain new Chapter-primary work; enumerate accepted writes since the
+checkpoint; reverse-project missing writes with stable idempotency keys;
+reconcile queues, counts, timestamps, identities, status, meetings, charges,
+and email; only then report legacy reads healthy. Never reset either store.
+
+Keep both rollback capabilities through the approved observation window
+(normally at least 72 hours). Retire each legacy reader, writer, binding,
+webhook, job, and secret only in a separate human-approved change with a fresh
+journey afterward.
+
+Close `MIGRATION.md` only when every applicable track is `primary-prod` or
+`retired`, the observation window passes, and the human confirms the existing
+product—not merely a Chapter canary—has been converted.

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.