@odla-ai/chapter 0.15.1 → 0.17.0

package/README.md

@@ -235,22 +235,37 @@ These bite silently — a smoke test won't catch them:
 - **`--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.
-- **The admin surface is intentionally minimal, and staying that way.** chapter
-  ships `/api/admin/scheduling` (booking rules, with field-keyed validation
-  messages) and `/api/admin/meetings` (the reconciled agenda, with the applicant
-  joined, `?all=1`, `from`/`to`, drift fields, Meet/Calendar links and the group
-  timezone), plus `peopleSection`. **Dashboard, billing, email config/log/test,
-  per-person comms, people list, role changes, approve and refund are out of
-  scope** — they are yours as host routes via the seam. Don't plan around them
-  shipping.
-- **`onboardingInvite` is a template with no built-in caller.** It is seeded into
-  the group's email settings (so you can edit its copy) but chapter never fires
-  it, because the moment it would fire — approval — is a host route (approval is
-  out of scope, above). Send it from your own approve handler via `sendTemplated`;
-  the seed existing does not mean the built-ins send it.
-- **Server-side Clerk is exported, even though the admin *routes* aren't.** A role
-  change is your host route — but you don't hand-roll the Clerk REST calls for it.
-  Beside `createClerkUser`/`createClerkInvitation`/`canChangeRole`, chapter exports
+- **The admin operational surface ships (0.16.0).** `/api/admin/*` is now a full
+  membership-operations API, admin-gated (`verifyUser` + `isAdmin`):
+  - **Roster/identity:** `GET /people` (union of `$users` + applications by email,
+    roles from `clerkListUsers`), `GET /people/access`, `POST /people/role`,
+    `POST /crm/sync` (backfill/reproject).
+  - **Pipeline/meetings:** `GET /dashboard` (flow counts, stage counts + weekly
+    delta, agenda, live revenue), `GET /meetings` (reconciled agenda),
+    `GET/PUT /scheduling`, `POST /meetings/:id/{reschedule,cancel}`,
+    `PATCH /applications/:id`.
+  - **Money:** `GET /billing` (applications ⋈ live Stripe subs; `truncated` flags a
+    >100 page instead of losing rows; `billingReady:false` when no Stripe key is
+    vaulted), `POST /applications/:id/{approve,refund}`.
+  - **Email:** `GET/PUT /group/email`, `GET /email/log`, `POST /email/test`,
+    `GET /people/:id/comms` (sent mail + reconstructed calendar invitations).
+
+  Two behaviours are **config, not code** — the mechanics are chapter's, the
+  decisions are yours (same model as `sends`):
+
+  ```ts
+  defineChapter({ operations: {
+    onApprove: { promoteTo: "member", send: "onboardingInvite" }, // promoteTo defaults to the rung below admin; either can be false
+    refund:    { allowedFrom: ["paid_pending_vetting"], cancelSubscription: true }, // allowedFrom validated against the pipeline
+  }});
+  ```
+
+  The escalation rules (super-admin tier, self-demotion lockout) are **not** seams
+  — `canChangeRole` package-enforces them so a site can't weaken them. `approve`
+  is the caller `onboardingInvite` was missing.
+- **The server-side Clerk primitives are exported too** — for host routes beyond
+  the built-in `/people/role`. Beside
+  `createClerkUser`/`createClerkInvitation`/`canChangeRole`, chapter exports
   the odla→Clerk write half: `clerkGetUserByEmail`, `clerkGetUser`, `clerkListUsers`
   (auto-paginated — never a silent 100-user cap), and `clerkSetRole`. Two
   load-bearing semantics: an absent `public_metadata.role` reads as the lowest rung