@odla-ai/chapter 0.22.1 → 0.24.0

package/README.md

@@ -8,7 +8,7 @@ email. The host still builds the public pages, routing, and brand presentation;
 Chapter supplies their application mechanics.
 
 ```sh
-npm i --save-exact @odla-ai/chapter@0.22.0
+npm i --save-exact @odla-ai/chapter@0.24.0
 ```
 
 > **Agentic experiment.** Built and maintained by AI agents from bounded runbooks
@@ -37,6 +37,12 @@ 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 repository also contains a build-tested
+[generic Preact reference host](https://github.com/cory/odla-ai/tree/main/examples/chapter-site).
+It is the executable companion to the greenfield runbook: site-owned global
+navigation, public routes, brand, voice, join fields, and member framing wrap
+Chapter-owned application, admin, CRM, payment, and scheduling behavior.
+
 ## The shape
 
 - **One config, two profiles.** `defineChapter()` validates at import and returns
@@ -50,14 +56,15 @@ secrets out of source and require development proof before production.
   Cloudflare `ExportedHandler`. It serves `/api/health`, `/api/config`,
   `/api/me`, `/api/crm/*`, `/api/network/shared`; configured leaders also get
   `/api/admin/network/{targets,push}`. Chapter mode adds the public
-  member surface (`/api/join-config`, `/api/applications`,
+  member surface (`/api/join-config`, `/api/join/resume`, `/api/applications`,
   `/api/schedule/{slots,book}`, `/api/payments/subscription`,
   `/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
+  Unknown `/api/*` paths terminate as JSON `404` responses rather than falling
+  through to an SPA document. 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.
@@ -111,6 +118,17 @@ secrets out of source and require development proof before production.
   Authored and shipped against Preact. Brand tokens
   (`brandTokens`/`<BrandStyle>`) re-skin all of it from
   `brand` (now light **and** dark, via `brand.palette` + `brand.paletteDark`).
+- **Voice is part of the brand.** `copy` is a recursively partial
+  `ChapterCopy`; `defineChapter()` resolves it into a complete `chapter.copy`
+  contract. Packaged join, member, and admin surfaces read that contract, so a
+  follower can own terminology and tone without forking behavior. Text remains
+  serializable; use render slots when the host needs markup or a different
+  composition.
+- **The host owns global navigation.** Admin defaults to `chrome="embedded"` and
+  three familiar workspaces. Dashboard/Billing and Calendar/Email remain
+  link-backed page tabs; record operations remain record tabs. A host can keep
+  one site header around public, join, member, and admin routes without Chapter
+  introducing another top-level navigation model.
 
 ### Theme tokens and scoped branding
 
@@ -134,6 +152,26 @@ and semantic `brand.tokens` / `brand.tokensDark` for normal configuration.
 escape hatch. Chapter scopes these overrides to `[data-chapter-admin]`, so an
 admin brand cannot recolor the document root or vendor sign-in UI.
 
+`brand.accent` selects a named `data-ui-accent` family supplied by the chosen
+theme. Each `AdminWorkspace` may set its own `accent` for a scoped page-level
+variation. For a fully custom palette, compile the brand book through the pure
+token entry and adapt it structurally:
+
+```ts
+import { compileBrandTokens } from "@odla-ai/brand/tokens";
+import { chapterBrandFromTokens } from "@odla-ai/chapter";
+
+const compiled = compileBrandTokens({ swatches });
+const brand = chapterBrandFromTokens(compiled, {
+  theme: "paper",
+  wordmark: "Example Chapter",
+});
+```
+
+This carries the compiler's complete light map, derived dark map, and invert
+map into Chapter without adding an `@odla-ai/brand` runtime dependency to
+Chapter itself.
+
 ## API quick start
 
 ```ts
@@ -157,8 +195,13 @@ export const chapter = defineChapter({
     },
     fonts: { display: "GT Sectra" },
   },
+  copy: {
+    join: { form: { submit: "Start the conversation" } },
+    admin: { workspaces: { people: "Community" } },
+  },
   prices: { standardCents: 100000, foundingDiscountCents: 10000 },
   emails: { notificationEmail: "hello@example.com" },
+  account: "none",
 });
 ```
 
@@ -198,6 +241,42 @@ 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.
 
+### Join and member composition
+
+`JoinIsland` keeps application mechanics while exposing presentation seams:
+
+```tsx
+<JoinIsland
+  config={joinConfig}
+  renderStepHeader={({ state }) => <FlowHeading step={state.step} />}
+  renderSubmit={({ disabled, submitting }) => (
+    <BrandedSubmit disabled={disabled}>{submitting ? "Sending…" : "Apply"}</BrandedSubmit>
+  )}
+  renderDone={({ booked, membersHref }) => (
+    <Confirmation booked={booked} membersHref={membersHref} />
+  )}
+  payment={{
+    appearance: stripeAppearance,
+    fonts: stripeFonts,
+    renderPriceLines: (lines) => <PriceSummary lines={lines} />,
+  }}
+>
+  <ApplicationFields />
+</JoinIsland>
+```
+
+`initialState` accepts trusted server state. On a browser redirect,
+`JoinIsland` reads the `application` capability from the query string and asks
+`GET /api/join/resume` for the canonical payment, booking, or done state; raw
+`redirect_status` and `reschedule` values never choose a UI step. Supply
+`loadResume` when a host stores the capability elsewhere.
+
+`MembersArea.renderProvisional` receives the loaded application, authenticated
+API function, reload callback, apply URL, and `defaultContent`, so the host can
+wrap or replace the provisional card just as admin workspaces can be composed.
+Nested admin/page/record tabs use fragment anchors by default, not query-string
+state.
+
 ### Leader → follower delivery
 
 The leader declares where records may go and exactly which fields each follower
@@ -503,28 +582,23 @@ These bite silently — a smoke test won't catch them:
   **Re-check this on every chapter upgrade.** Wiring a send changes a site's
   outbound mail with no local diff — release notes call out send changes
   explicitly for that reason.
-- **Account model — the default is `"none"`, and that is deliberate.**
+- **Account model is an explicit chapter-mode decision.**
   `account: "create"` makes the Clerk account server-side (so join can say the
   account is ready), `"invite"` **emails the applicant a Clerk invitation**, and
-  `"none"` (the default) provisions nothing. Both non-default models need
-  `clerk_secret_key` in the tenant vault. The default is side-effect-free on
-  purpose: inviting mails a real person, and a site that never made that choice
-  must not be sending mail. **You must opt in — a site that wants accounts and
-  doesn't set `account` will silently provision none.** (Changed in 0.15.0: the
-  default was `"invite"`, which mailed applicants from a config nobody wrote.)
+  `"none"` provisions nothing. `defineChapter()` rejects a chapter-mode config
+  that omits `account`, so forgetting the decision cannot silently disable or
+  enable account provisioning. Both side-effecting models need
+  `clerk_secret_key` in the tenant vault. Hub mode resolves to inert `"none"`.
 - **What lands on the Clerk account (and its `public_metadata` is
-  client-readable).** Both models write `public_metadata` as
-  `{ applicationId, profile }`. By default `profile` is every configured
-  `application.required`/`optional` field Clerk doesn't already carry natively
-  (so *not* email/firstName/lastName), plus `focus` — **which means free-text or
-  third-party fields like `message` or `referral` are exposed to the browser
-  unless you curate.** Set `application: { profileFields: ["phone", "state",
-  "focus", ...] }` to an allowlist and everything else stays db-only. Array fields
+  client-readable).** Both side-effecting models write `applicationId` and,
+  when explicitly selected fields are present, `profile`. The
+  `application.profileFields` default is `[]`, so application details remain
+  db-only. Set `profileFields: ["phone", "state", "focus"]` to a deliberate
+  browser-readable allowlist. Array fields
   (`focus`) are clamped to `maxArrayLen` (default 100) and non-primitive elements
   dropped, so a client can't post an unbounded array into metadata.
   `applicantProfile(chapter, fields)` is exported to assert the exact shape in a
-  test before deleting a local override. (Default is back-compat today; expected
-  to tighten at 1.0.)
+  test before deleting a local override.
 - **Email + input validation.** The field literally named `email` is checked
   against a permissive email shape (400 on `"notanemail"`, so it fails cleanly
   here rather than at the downstream Clerk create) — set
@@ -549,12 +623,10 @@ These bite silently — a smoke test won't catch them:
   one integration test and a join page that quietly stops posting the flag can't
   go unnoticed.
 
-  **If the disclaimer is a compliance record, set
-  `application: { requireDisclaimerAck: true }`** and a submit with no ack is a
-  400 instead of a row with no consent. It defaults to `false` so an upgrade
-  never starts rejecting traffic; enabling it fails *deterministically* on your
-  first test submit, not intermittently in production. Expect this to default to
-  `true` at 1.0.
+  `requireDisclaimerAck` now defaults to `true`, and a submit with no ack is a
+  400 instead of a row with no consent. Set it to `false` deliberately only when
+  the site renders no consent control. Existing adopters must test this before
+  cutover.
 - **CRM projection points.** chapter projects the person on application submit
   (`projectApplicant`), not on booking or on webhook status change. If you mirror
   pipeline stage into the CRM, keep those routes.
@@ -582,7 +654,8 @@ These bite silently — a smoke test won't catch them:
   invitation mail. Importing the full `@odla-ai/chapter/ui` barrel pulls the admin
   half, so prefer the narrower entry.
 - **Known-good application set** (installs clean, no flags):
-  `@odla-ai/chapter` 0.22.1, `@odla-ai/ui` 0.12.1, `@odla-ai/crm` 0.3.1,
+  `@odla-ai/chapter` 0.24.0, `@odla-ai/brand` 0.2.0,
+  `@odla-ai/ui` 0.12.1, `@odla-ai/crm` 0.3.1,
   `@odla-ai/db` 0.6.7,
   `@odla-ai/calendar` 0.2.0, `@odla-ai/email` 0.3.1,
   `@odla-ai/auth-clerk` 0.4.1, `@odla-ai/o11y` 2.2.2, `jose` 6.2.3, and