@odla-ai/chapter 0.24.0 → 0.25.0

package/package.json

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

@@ -112,15 +112,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:
@@ -163,8 +174,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
@@ -437,6 +450,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

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;