@odla-ai/chapter 0.20.0 → 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 the Silver & Salt content rhythm 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
 
@@ -190,13 +216,134 @@ config. The standard collection drawer discovers the target and calls the
 admin-gated push route. A follower must declare the receiving CRM type/fields;
 otherwise it rejects the record cleanly instead of dropping fields.
 
+#### Existing follower CRMs must opt into the shared graph
+
+When `crm` is omitted, chapter's default already contains compatible `person`
+and `company` types plus a `works_at` relation. Passing a custom CRM replaces
+that default; chapter does not merge missing types or fields into it. A follower
+that wants both people and businesses must therefore declare compatible types
+itself:
+
+```ts
+import { defineCrm } from "@odla-ai/crm";
+
+const crm = defineCrm({
+  types: {
+    person: {
+      label: "Person",
+      labelPlural: "People",
+      nameField: "name",
+      emailField: "email",
+      fields: {
+        name: { type: "string", label: "Name", required: true },
+        email: { type: "email", label: "Email" },
+        firstName: { type: "string", label: "First name" },
+        lastName: { type: "string", label: "Last name" },
+        phone: { type: "string", label: "Phone" },
+        linkedin: { type: "string", label: "LinkedIn" },
+      },
+    },
+    company: {
+      label: "Business",
+      labelPlural: "Businesses",
+      nameField: "name",
+      fields: {
+        name: { type: "string", label: "Name", required: true },
+        domain: { type: "string", label: "Domain / website", slot: "s1" },
+        industry: { type: "string", label: "Industry" },
+        location: { type: "string", label: "Location" },
+        linkedin: { type: "string", label: "LinkedIn" },
+        notes: { type: "string", label: "Notes" },
+      },
+    },
+  },
+  relations: {
+    works_at: {
+      from: "person",
+      to: "company",
+      label: "works at",
+      reverseLabel: "team",
+    },
+  },
+});
+```
+
+The follower must declare every field its leader may send. Unknown types or
+fields fail the request before any CRM write. Record delivery currently moves
+records, not `crm_link` relation rows; create or curate `works_at` links locally.
+
+#### Custom leader consoles must mount the sharing UI
+
+Automatic “Share with …” actions come from chapter's standard collection
+sections. They are present when the console uses
+`<ChapterAdmin chapter={chapter} />`. Passing an explicit `sections` array
+replaces that catalog, so a custom console must deliberately compose it:
+
+```tsx
+import {
+  ChapterAdmin,
+  defaultAdminSections,
+} from "@odla-ai/chapter/ui/admin";
+
+const sections = [
+  customOverviewSection,
+  ...defaultAdminSections(chapter),
+];
+
+render(
+  <ChapterAdmin chapter={chapter} sections={sections} />,
+  document.getElementById("admin-root"),
+);
+```
+
+If the custom console renders its own record drawer instead, mount
+`NetworkShareActions` inside that drawer:
+
+```tsx
+<NetworkShareActions
+  recordId={record.id}
+  recordType={record.type}
+  getToken={sectionContext.getToken}
+/>
+```
+
+The component discovers compatible targets through
+`GET /api/admin/network/targets`; it never receives follower secrets in browser
+data.
+
+#### Verify delivery in development before production
+
+Use distinct development tenants and follower origins for the first delivery:
+
+1. Vault one random value as `network_share_secret` in the follower and under
+   the target's resolved `secretName` in the leader.
+2. Confirm `GET /api/admin/network/targets` lists the development follower with
+   the expected compatible record types.
+3. Share one test person and one test business from the leader's record drawer.
+   Confirm each appears in the follower with only allowlisted fields.
+4. Share each record again. The second delivery must update the same follower
+   record, not create a duplicate.
+5. Confirm the follower's pipeline, account, and billing state did not change;
+   those remain locally authoritative.
+6. Change one allowlisted leader field and share again to prove later deliveries
+   update the existing record. A target with the wrong secret must return `401`
+   without writing CRM data.
+
+Only after this contract passes against development origins should the leader
+target be changed to a production follower origin and the matching production
+vault values be installed.
+
 Section navigation defaults to `/admin/?tab=people`, not
 `/admin/people`. Query routing deliberately works in both leader-style SPAs and
-Silver & Salt-style static subdirectories. Legacy path links still open, and
+ordinary static subdirectories. Legacy path links still open, and
 `routing="path"` remains available only for hosts with an explicit SPA fallback.
 
 ## 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:
 
@@ -302,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
@@ -317,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.0",
+  "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": {