@odla-ai/chapter 0.24.0 → 0.25.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odla-ai/chapter",
-  "version": "0.24.0",
+  "version": "0.25.1",
   "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",

package/runbooks/adopt-existing.md

@@ -68,6 +68,16 @@ Create or extend root `MIGRATION.md`; never replace its history. Record state
   render sink;
 - telemetry, freshness/error alerts, deploy commands, and CI auto-deploys.
 
+For every route, record the method/path, current consumer, owning implementation
+(`legacy`, Chapter, or an explicit host adapter), request and response schemas,
+status/error/auth/cache behavior, and its evidence. Source evidence names the
+checked-in path plus commit; deployment evidence names the origin plus immutable
+Worker/deployment version. A response observed on an unversioned deployment
+describes only that deployed build at that moment. It does not establish route
+ownership or the contract of the branch being changed. Treat old branches, git
+history, and unrelated deployments as leads to verify, never as the migration
+specification.
+
 ### Freeze visual and behavior evidence
 
 Capture representative production screenshots and measured layouts at 390,
@@ -112,15 +122,26 @@ Allowed states: `not-started`, `canary`, `parallel`, `verified`,
 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
+npm install \
+  @odla-ai/chapter @odla-ai/brand @odla-ai/ui \
+  @odla-ai/crm @odla-ai/db \
+  @odla-ai/calendar @odla-ai/email \
+  @odla-ai/auth-clerk @odla-ai/o11y \
+  jose preact
+npm install --save-dev \
+  @odla-ai/cli @odla-ai/security \
+  @cloudflare/workers-types \
+  typescript vite vitest wrangler
+npx odla-ai setup
+npm ls @odla-ai/chapter @odla-ai/crm @odla-ai/ui @odla-ai/cli
+npx odla-ai 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.24.0 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`.
+Use normal dependency declarations while ODLA is under active development.
+Review and commit `package.json` plus `package-lock.json`, use `npm ci` after
+the intentional dependency update, record resolved versions in PM, and rerun
+the frozen acceptance and Chapter conformance suites. Do not use
+`--legacy-peer-deps` or preserve an incompatible peer.
 
 Write `src/chapter.config.mjs` from the inventory. Make every behavior decision
 explicit:
@@ -139,13 +160,20 @@ explicit:
 
 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
+1. freeze the legacy schema and rules from an exact reviewed source path and
+   commit, with a recorded content digest;
+2. make that baseline independent: use the untouched legacy source or a literal
+   fixture that does not import Chapter, the active descriptor/schema alias, or
+   another generated candidate; do not modify baseline and candidate in the
+   same approval;
+3. normalize only approved representational differences;
+4. compare `createChapterIntegration(chapter)` namespaces, attrs, links, rules,
+   and seeds to the independent baseline;
+5. run a negative control by removing or changing a known field/rule on one side
+   and prove the parity test fails before trusting a green result;
+6. 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`.
+7. 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
@@ -163,8 +191,10 @@ At minimum audit:
 - 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;
-- `profileFields` now defaults to `[]`; enumerate every field that may remain
-  Clerk-client-readable rather than relying on implicit projection;
+- `profileFields` now defaults to `[]`; enumerate the small account/admin
+  signals that may be mirrored into backend-only Clerk private metadata rather
+  than relying on implicit projection. Keep the application row and CRM
+  canonical;
 - application-to-CRM projection fields;
 - `requireDisclaimerAck` now defaults to `true`; set `false` explicitly only
   when the existing product has no consent control, and preserve
@@ -330,10 +360,25 @@ Do not replace schema, worker, routes, and UI in one unreviewable change.
    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
+   Chapter behavior only when the route-contract matrix proves method, auth,
+   request body, response status, JSON keys/types/nesting, units, null/omission
+   semantics, and relevant headers are compatible. Matching business values
+   alone is not response-shape parity.
+4. When contracts differ, keep the legacy route until its consumer adopts the
+   packaged Chapter component end to end, or add an explicit adapter with
+   contract tests. Do not simply repoint the existing browser code.
+5. In Chapter 0.25, `/api/join-config` is Chapter-owned and returns the
+   group-scoped join configuration, raw cent values, policy copy, and readiness;
+   it is not a promise to reproduce a legacy route's prebuilt Stripe line items
+   or publishable key. `JoinIsland` delegates payment to `PaymentStep`, which
+   obtains `clientSecret`, `publishableKey`, and `lineItems` from
+   `POST /api/payments/subscription` after application submission and refund
+   acknowledgement. Verify this installed-version contract before retiring a
+   legacy join route.
+6. Compare built-in and legacy behavior route by route; only then remove a host
+   route that Chapter fully owns and whose consumers use the verified Chapter
+   contract or adapter.
+7. 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,
@@ -437,6 +482,22 @@ Do not substitute `secrets set-clerk-key`; it writes the platform-reserved
 command does not validate Clerk instance prefixes: independently confirm dev
 uses `sk_test_`. Never put `sk_live_` in dev.
 
+Chapter now reserves `public_metadata` for the small authorization role and
+stores its `applicationId`/allowlisted profile snapshot in backend-only
+`private_metadata`. After deploying the schema update, run the authenticated
+admin repair endpoint in bounded batches:
+
+```text
+POST /api/admin/clerk/private-profiles/sync?offset=0&limit=50
+```
+
+Continue with each returned `nextOffset` until it is `null`. Prove that the
+public `role` and unrelated host metadata survive, the former public
+`applicationId`/`profile` keys are absent, the private snapshot matches the
+latest application, and `clerkPrivateMetadataSyncedAt` plus `clerkUserId` are
+recorded locally. The application row and CRM remain canonical; this is an
+account/admin signal mirror, not a third editable profile database.
+
 ### Stripe
 
 Use test resources and an isolated dev webhook. Store `stripe_secret_key` and
@@ -464,9 +525,12 @@ selected account invitation effect. Never let dev send to imported members.
 
 Check in an executable acceptance manifest with:
 
-- actual dev URLs and Worker version ids;
+- actual dev URLs and immutable Worker version ids, paired with the source
+  commit they are expected to run;
 - deterministic synthetic member/application ids;
-- expected routes/statuses, schema/counts/freshness, and Chapter backend marker;
+- expected route owners and full request/response contracts—not only paths,
+  statuses, or equal values—plus 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;
@@ -492,6 +556,14 @@ Run the real journey:
 `doctor`, unit tests, build, CLI smoke, a login page, and a human-looking admin
 screen are necessary but not sufficient.
 
+Before filing a route bug from deployed evidence, prove that the probed
+deployment runs the intended commit/version. Repeat the request against the
+direct candidate origin and the public domain with a unique non-secret query
+value, capture `Age`, `Cache-Control`, `CF-Cache-Status`, `ETag`, and the Worker
+version marker, and re-test after the documented edge/config propagation
+window. A cached pre-deploy or pre-credential `404` is not evidence that the
+current route is absent.
+
 ## Phase 8 — Production parallel run and cutover
 
 Do not add production until the human approves the full dev report and both

package/runbooks/greenfield.md

@@ -41,8 +41,9 @@ consumer, not a visual identity to rename.
 
 ## 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.
+1. Use normal dependency declarations while ODLA is under active development.
+   Commit the lockfile, use `npm ci` for repeatable installs, and rerun
+   conformance after updates. Never use `--legacy-peer-deps`.
 2. Build and prove `dev` before adding `prod`. Production provisioning, secret
    transfer, deploy, DNS, billing activation, and real outbound email are human
    checkpoints.
@@ -113,38 +114,31 @@ renamed reference site.
 
 `@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:
+Initialize npm, install Chapter and the Preact host with normal dependency
+declarations, then install the CLI's 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 Preact
-host matrix. Do not copy these commands into a pre-release branch where
-`@odla-ai/chapter@0.24.0` is not yet on npm.
-
-```sh
-npm view @odla-ai/chapter@0.24.0 version
-npm install --save-exact \
-  @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 preact@10.29.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 \
-  typescript@6.0.3 \
-  vite@8.1.4 vitest@4.1.10 wrangler@4.107.0
+npm install \
+  @odla-ai/chapter @odla-ai/brand @odla-ai/ui \
+  @odla-ai/crm @odla-ai/db \
+  @odla-ai/calendar @odla-ai/email \
+  @odla-ai/auth-clerk @odla-ai/o11y \
+  jose preact
+npm install --save-dev \
+  @odla-ai/cli @odla-ai/security \
+  @cloudflare/workers-types \
+  typescript vite vitest wrangler
+npx odla-ai setup
+npm ls @odla-ai/chapter @odla-ai/crm @odla-ai/ui @odla-ai/cli
 npx odla-ai capabilities --json
 ```
 
-The parent `README.md` repeats this version matrix. This runbook standardizes on
-Preact. Install auth-clerk explicitly when adopting the admin entry; it is an
-optional Chapter peer because worker-only and member-only consumers do not need
-it.
+Commit `package-lock.json`, use `npm ci` after the initial dependency change,
+and rerun conformance whenever the lockfile resolves new ODLA versions. Do not
+bypass peer-dependency validation. Install auth-clerk explicitly when adopting
+the admin entry; it is an optional Chapter peer because worker-only and
+member-only consumers do not need it.
 
 Required host scripts:
 
@@ -341,8 +335,11 @@ both require a named app-readable vault secret `clerk_secret_key`. Keep
 defaults to `true`, and `application.profileFields` defaults to `[]`. Keep all
 three decisions explicit in the checked-in config and snapshot their resolved
 values. A site with no consent control must deliberately set
-`requireDisclaimerAck: false`; an application field reaches client-readable
-Clerk metadata only when it is deliberately listed in `profileFields`.
+`requireDisclaimerAck: false`; an application field reaches backend-only Clerk
+private metadata only when it is deliberately listed in `profileFields`. Keep
+that mirror small and use the application row/CRM as the canonical profile.
+With `account: "invite"`, prove the first signed-in `/api/me` request completes
+the private profile write and records `clerkPrivateMetadataSyncedAt`.
 
 `copy` is a recursive partial of `ChapterCopy`. `defineChapter()` resolves it
 to a complete `chapter.copy`, which is the voice source for packaged join,
@@ -704,7 +701,10 @@ 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;
+3. Clerk account/invite behavior selected by config; prove `role` is the only
+   Chapter-owned public metadata and the allowlisted account snapshot appears
+   in private metadata. For an invite, the first authenticated `/api/me`
+   completes that write exactly once;
 4. provisional and member area;
 5. admin sign-in, people/CRM, application approval, meeting, billing, email;
 6. replay/idempotency and one safe error;