@odla-ai/chapter 0.51.0 → 0.52.0

package/README.md

@@ -185,6 +185,25 @@ 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.
 
+#### Packaged workspaces are styled by Chapter, through `@odla-ai/ui`
+
+Chapter owns the styling of every workspace it ships (Admission, Builder
+Library, People, Settings, and the rest) and does it only through `@odla-ai/ui`
+form components and the `--ui-*` tokens the active theme scope supplies. A
+packaged picker is always the `@odla-ai/ui` `Select`, a native select carrying
+the `select` class, so it takes the host's theme without any host CSS, keeps
+its accessible name through its `Field` label, and keeps native keyboard
+behaviour. A guard test in the package fails if a bare select tag reappears in
+a Chapter UI source.
+
+The boundary runs the other way too. A host must not patch package-owned
+markup with its own CSS: if a packaged control looks browser-default, the theme
+layer is missing (see the banner above) or the package has a bug to report,
+never a selector to override. Any custom picker a host adds beside a packaged
+workspace should be the same `@odla-ai/ui` `Select` (with `Field` for its
+label) rather than a bare element, so host and package controls read as one
+surface.
+
 ## API quick start
 
 ```ts
@@ -932,6 +951,32 @@ removing it changes no customer-facing behavior. The BNF frontend may be down
 while the webhook continues to ingest. Registering a Stripe endpoint and
 enabling production remain separate reviewed operations.
 
+A second delivery of a retained event id is a replay when its digest matches, or
+when its canonical fact (id, type, created, and the allowlisted `data.object`
+fields) equals the retained fact however the delivery envelope changed. A
+canonical replay also resolves an open collision for that event, recording a
+`paymentRecoveryReviews` row with the system as actor, unless the collision
+recorded a different fact. Only a delivery whose fact differs registers a
+collision, and it stays active through rebuilds until an operator decides:
+`POST` with `{ command: "resolve", eventId, mutationId, reason }` records the
+actor and reason, dismisses the colliding delivery so the same one replays
+quietly, and keeps the retained fact as the evidence of record; it refuses
+without a valid `mutationId` and a reason. `POST` with
+`{ command: "recover-event", eventId }` instead trusts an independent read of
+the provider Event and rewrites the retained digest when every fact matches.
+
+`/api/admin/payment-recovery` is the drain on both sides. A chapter lists and
+retries its quarantined Stripe receipts; a hub that owns the read model lists
+every active commercial exception (`count` plus provider ids, no PII) and
+retries one through the same ingest the signed webhook uses after an
+independent provider read, with a review row per retry.
+
+Both Workers raise an error-level operator alert when a receipt enters
+quarantine or a commercial exception becomes active, carrying the current count
+and provider event ids only. Pass `recordError` from `@odla-ai/o11y` as
+`chapterWorker({ chapter, recordError })` to deliver those alerts to o11y; the
+default is one structured `console.error` line per alert.
+
 `POST` with `{ command: "reconcile-chapters" }` is a separate, two-sided opt-in
 comparison. A hub target and the matching follower reader must both set
 `commercialParity: true`; neither record browsing nor Stripe shadow mode grants
@@ -1107,10 +1152,15 @@ name is public configuration, not a credential. If a configured binding is
 missing at runtime, the target fails explicitly instead of falling back to a
 potentially misrouted public fetch.
 
-Vault the same random value as `network_share_secret` in the follower and as
-`network_share_example_chapter` in the leader (or set a different
-`secretName`). No secret is placed in source, browser data, or provisioning
-config. The standard collection drawer discovers the target and calls the
+Pair the edge by vaulting one generated value as `network_share_secret` in the
+follower and as `network_share_example_chapter` in the leader (or the target's
+`secretName`), never printed. The integration descriptor declares both slots,
+so provisioning tooling can hold them against the vault, and until both hold a
+value every leader-side surface reports the edge as `code: "edge_unpaired"`
+with a `hint` naming the CLI pairing command (`chapter edge pair`, which
+writes both slots from one generated value and ships with the next
+`@odla-ai/cli` release). No secret is placed in source, browser data, or
+provisioning 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.
 
@@ -1234,8 +1284,11 @@ Use distinct development tenants and follower origins for the first delivery:
 
 1. Confirm every target `id` exactly equals the follower's `chapter.id`. For
    Cloudflare Workers, confirm its `binding` exists in the leader's development
-   Wrangler environment. Vault one random value as `network_share_secret` in
-   the follower and under the target's resolved `secretName` in the leader.
+   Wrangler environment. Pair the edge: vault one generated value as
+   `network_share_secret` in the follower and under the target's resolved
+   `secretName` in the leader (the CLI's `chapter edge pair` command does both
+   writes from the next `@odla-ai/cli` release on). The leader rollup reports
+   `edge_unpaired` until both slots hold a value.
 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.
@@ -1464,13 +1517,38 @@ These bite silently — a smoke test won't catch them:
   | Template | Fires from | Configurable |
   |---|---|---|
   | `adminNotification` | `POST /api/applications` (submit) — or the Stripe webhook (first payment) | `sends.adminNotification: "submit" \| "payment" \| "never"` (default `"submit"`) |
-  | `prepEmail` | `POST /api/schedule/book` | template `enabled` flag |
+  | `submitConfirmation` | `POST /api/applications` (submit) — a free tier always; a paid tier only when `paymentConfirmation` is disabled, so a paid applicant is confirmed once | template `enabled` flag |
+  | `prepEmail` | `POST /api/schedule/book` — once per application; a reschedule sends no second one | template `enabled` flag |
   | `paymentConfirmation` | Stripe webhook, first successful invoice | template `enabled` flag |
+  | `seatAccepted` | `POST /api/named-seat/accept` — to the seat's purchaser, once per seat, naming the recipient and tier | template `enabled` flag; the seeded default copy applies until the group row carries its own `emailTemplates.seatAccepted` |
 
   ```ts
   defineChapter({ /* … */ sends: { adminNotification: "payment" } });
   ```
 
+  **Template variables.** Every value comes from stored data — the frozen
+  checkout the applicant consented to, the tier catalog, the booked meeting,
+  the request origin — never from a price or a name written into code. An
+  unknown placeholder renders empty, so copy can use any subset.
+
+  | Variable | Templates | Value |
+  |---|---|---|
+  | `firstName`, `lastName`, `email`, `phone`, `state` | all | the application row |
+  | `tier`, `tierName` | `adminNotification`, `submitConfirmation`, `prepEmail` | the frozen checkout quote's tier name, else the catalog name for `applications.tierId` |
+  | `paymentAmount`, `paymentAmountSummary` | `submitConfirmation`, `paymentConfirmation`, `prepEmail` | `$900.00` and ` of $900.00` from the frozen checkout; both blank for a free tier or before checkout |
+  | `submitNextStep` | `submitConfirmation` | "Next, schedule your introduction call." / "Next, complete your membership payment." / "Your membership is approved." |
+  | `paymentNextStep` | `paymentConfirmation` | the post-payment step (schedule, waived, or approved) |
+  | `startAt`, `endAt`, `timezone` | `prepEmail` | the booked call rendered in the group's `scheduling.timezone`, e.g. `Wednesday, October 7, 2026 at 10:00 AM EDT` |
+  | `meetUrl`, `htmlLink` | `prepEmail` | the booked meeting's Google Meet and calendar links (blank when the provider returned none) |
+  | `meetingTime`, `meetingLink` | `prepEmail` | aliases of `startAt` and `meetUrl` (falling back to `htmlLink`) for copy written before those existed |
+  | `adminUrl`, `membersUrl` | `adminNotification`, `submitConfirmation`, `onboardingInvite` | `<origin>/admin/` and `<origin>/members/` from the request that fired the send |
+  | `refundPolicyText`, `commitmentText`, `normsText` | all | the group row's policy copy |
+
+  **From display name.** `emails.fromName` (seeded to the group row, editable
+  in Settings → Email) turns the From header into `{ name, email }` —
+  `Tori Horton <tori@…>` in an inbox — while the address stays the Worker's
+  `EMAIL_FROM`. A group with no name sends the bare address exactly as before.
+
   **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.
@@ -1634,7 +1712,11 @@ These bite silently — a smoke test won't catch them:
   `drainMembershipEffects` recovers pending provider work and cancels unpaid
   seats within one exact configured runtime. It never refunds an unaccepted
   seat: a purchased seat waits for its recipient for the whole paid term, and a
-  refund is a super admin's decision on request. Refunding the recipient's own
+  refund is a super admin's decision on request. When the recipient accepts,
+  the chapter emails the purchaser one `seatAccepted` notice with the
+  recipient's name and tier, deduplicated per seat through the email log; a
+  chapter edits or disables it on its group row, and the default copy applies
+  until then. Refunding the recipient's own
   application (`POST /api/admin/applications/:id/refund`) requires a super
   admin when it carries a gifted seat. On a chapter,
   `GET /api/admin/applications/:id/named-seat` shows a purchaser's seat and
@@ -1680,6 +1762,18 @@ These bite silently — a smoke test won't catch them:
   read the same field instead of hard-coding a founding price. The issued offer
   at checkout remains the only promise.
 
+  On the network owner, `GET /api/admin/membership-policy-versions` (super
+  admin; `?chapterId=` narrows it to one chapter) lists every offering and
+  discount policy version the authority holds, newest first, with the state
+  issuance would give it now (active, scheduled, superseded with the date it
+  was passed over, draft, retired), its effective or qualifying window, the
+  provider mechanism a discount uses, and whatever `source`, `actor` and
+  `recordedAt` the writing host stored on the row. `MembershipPolicyVersions`
+  from `@odla-ai/chapter/ui/admin` renders it read-only beside
+  `NetworkSeatBilling`, so an operator can see why a card shows a list price
+  and a payable price without reading the database; nothing on it edits a
+  version.
+
   On a chapter, a person record with no linked application — someone invited or
   a candidate — is managed by the chapter's own admins the way the network
   owner manages it: the record's Invitation tab sets or revokes the local