@odla-ai/chapter 0.25.0 → 0.25.2

package/runbooks/adopt-existing.md

@@ -49,8 +49,24 @@ runtime and data rollback remain proven.
 
 ## Phase 0 — Freeze the operating baseline
 
-Create or extend root `MIGRATION.md`; never replace its history. Record state
-`inventoried` only after the human approves the baseline.
+Use odla PM as the migration's durable coordination state; do not create a
+parallel migration diary. If the odla app already exists, begin by listing
+doing tasks, open bugs, open goals, and recent decisions for the `appId` from
+`odla.config.mjs`. Read the active task, its linked goal, and their comments
+before inspecting code.
+
+If the app is not registered yet, choose the intended stable `appId`, keep
+Phase 0/early provisioning evidence in focused commits and checkpoint
+handoffs, and rerun the inventory when a fresh agent resumes. Old branches,
+git history, unrelated deployments, and earlier experiments are only leads to
+verify. Immediately after the first provision registers the app, create PM
+goals/tasks/decisions and backfill the approved baseline evidence; PM is
+authoritative from then on.
+
+Use one conformance goal per acceptance outcome, parallel tasks for independent
+tracks, decisions for product/data/identity/route/rollback choices, and bugs
+for defects. Comments carry the source commit, immutable deployment version,
+verification command/result, and rollback checkpoint. Never put secrets in PM.
 
 ### Inventory the product
 
@@ -68,6 +84,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,
@@ -150,13 +176,21 @@ 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 as a PM decision, and
+   attach the comparator evidence to the linked conformance goal/task.
 
 `createChapterIntegration()` inserts the group seed only when absent. Existing
 runtime owner edits do not update from later config changes. Compare the current
@@ -343,10 +377,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,
@@ -388,10 +437,15 @@ fixture. Compare markup/behavior and the Phase 0 screenshots before deletion.
   `renderHeader` when the header belongs inside the Chapter scope. Chapter mode
   defaults to Dashboard, People, and Settings; move former global Billing,
   Calendar, Email, and per-record operations into nested tabs.
-- Preserve a distinctive People summary, rail, and record heading with
-  `collectionSection`'s `renderSummary`, `renderMaster`, and
-  `renderDetailHeader` slots. Replace specialized record tabs rather than
-  flattening them into global navigation.
+- Preserve distinctive People summary content, list presentation, record
+  heading, and specialized panels with `collectionSection`'s `renderSummary`,
+  `renderMaster`, `renderDetailHeader`, and record-tab slots. These slots
+  customize content; they do not fix pane geometry.
+- Operational usability is not pixel parity with a cramped legacy admin. At
+  desktop widths, the unselected People collection must use the full workspace
+  width; after a record opens it becomes master/detail. This is the
+  `collapseClosedDetail` default. Set it to `false` only when the empty detail
+  pane contains intentional, useful content approved by the human.
 - Application-backed pipeline changes must use a lifecycle adapter that invokes
   the authoritative application endpoints. Prove approve/refund/manual
   transition side effects; a raw CRM `setStage` is not parity.
@@ -416,6 +470,9 @@ At 390, 768, 1280, and 1440 pixels in every theme, compare:
 - wordmark, text baseline, theme control, active state, and hover/focus;
 - join fields/errors, payment and slot picker, Clerk sign-in containment;
 - member cards/actions and every admin section/table/drawer;
+- at 1280 and 1440, every unselected collection table uses the full content
+  width: no empty detail pane and no wide table squeezed into a narrow rail;
+  after selection, both master and detail remain usable;
 - no clipped labels, card text escape, accidental document scroll, or
   horizontal overflow;
 - loading, empty, error, unauthorized, 404, and reduced-motion states.
@@ -427,16 +484,21 @@ not visual parity.
 
 ### Clerk
 
-Use the same Clerk application/workspace. Chapter claim mode requires session
-claims for both email and role; hub table mode uses lowercase `admins` rows.
-Prove existing allowed/forbidden users, role ladder, super-admin behavior,
-malformed/expired sessions, sign-out, and return targets.
-
-If the legacy verifier enforces JWT `aud` or `azp`, keep that host verifier in
-front of Chapter. This Chapter release verifies issuer but does not expose or
-enforce the CLI-provisioned Clerk audience. Add wrong-audience and
-wrong-authorized-party fixtures; do not cut over auth until the legacy contract
-still rejects them.
+For the one website being converted, retain that website's existing Clerk
+application/workspace unless the human approves an identity migration. A
+leader and follower are different websites and use different Clerk
+applications, publishable keys, issuers, roles, and local session tokens. A
+Clerk JWT never authenticates a cross-site delivery.
+
+Chapter claim mode requires session claims for both email and role; hub table
+mode uses lowercase `admins` rows. Prove signed-out, allowed, forbidden,
+provisional, member, admin, super-admin, malformed, expired, wrong-issuer,
+sign-out, and return-target behavior. If the site's verifier intentionally
+enforces JWT `aud` or `azp`, retain that check with a host verifier until
+Chapter exposes the same policy and add wrong-audience/wrong-authorized-party
+fixtures. If it never enforced those claims, mark those two cases `n/a` only
+after the full matrix is recorded; do not call their absence an auth success or
+use it to skip the remaining authorization tests.
 
 When Chapter needs server-side account/role operations, set the named
 app-readable `clerk_secret_key` through:
@@ -493,9 +555,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;
@@ -521,6 +586,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
@@ -565,6 +638,7 @@ Keep both rollback capabilities through the approved observation window
 webhook, job, and secret only in a separate human-approved change with a fresh
 journey afterward.
 
-Close `MIGRATION.md` only when every applicable track is `primary-prod` or
-`retired`, the observation window passes, and the human confirms the existing
-product—not merely a Chapter canary—has been converted.
+Mark the migration goals met and tasks done only when every applicable track is
+`primary-prod` or `retired`, the observation window passes, evidence is attached
+in PM, and the human confirms the existing product—not merely a Chapter
+canary—has been converted.

package/runbooks/greenfield.md

@@ -67,9 +67,19 @@ consumer, not a visual identity to rename.
 
 ## Phase 0 — Resolve the product and brand brief
 
-Write `PRODUCT.md` before code. Record decisions rather than inventing business
-facts. Ask the human only for missing choices that change money, identity,
-outbound communication, authorization, or the public brand.
+Record decisions rather than inventing business facts. Ask the human only for
+missing choices that change money, identity, outbound communication,
+authorization, or the public brand. Do not create a parallel product or
+migration diary.
+
+PM requires a registered, co-owned odla app. Before Phase 3 registration, use a
+focused branch/commit and checkpoint handoff for the approved brief and rerun
+the Phase 0 checks when a fresh agent resumes. Immediately after provision
+registers the app, create PM conformance goals and track tasks, record these
+product/brand/identity decisions, and backfill the earlier evidence. PM is
+authoritative from then on; start every later session by listing doing tasks,
+open bugs/goals, and recent decisions for the `appId` in
+`odla.config.mjs`. Never put secrets in PM.
 
 | Decision | Required answer |
 | --- | --- |
@@ -158,7 +168,6 @@ Recommended minimum tree:
 
 ```text
 .
-├── PRODUCT.md
 ├── package.json
 ├── index.html
 ├── vite.config.mjs
@@ -344,9 +353,8 @@ 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,
 member, and admin surfaces. Put plain text in `copy`; use render slots for
-markup or a different composition. Include the voice constraints from
-`PRODUCT.md` in a contract test, such as banned punctuation or required
-terminology.
+markup or a different composition. Include the approved voice constraints in a
+contract test, such as banned punctuation or required terminology.
 
 In this release, `prices.currency` and `prices.interval` record intent but do
 not control the group row, public join config, or Stripe charge. The Stripe
@@ -376,6 +384,32 @@ Snapshot these resolved values in `chapter-contract.test.ts`:
   schema/rules/seeds/probes, using the fixed clock because the integration seed
   carries the timestamp.
 
+### When this site is a leader or follower
+
+Model the network as website nodes joined by directed delivery edges. Every
+website keeps its own `appId`, ODLA tenant/key, CRM config, Clerk application,
+issuer, roles, and users. A leader edge is one `network.targets[]` record with
+the follower id/name/origin, optional vault secret name, and a per-record-type
+field allowlist. The follower declares compatible CRM types and fields; it does
+not need the leader's Clerk configuration.
+
+The leader browser authenticates only to the leader. Its Worker authorizes the
+local admin, reads the edge's share secret from the leader vault, and sends a
+versioned `{ version, type, hubRecordId, input }` payload to the follower. The
+follower validates that share secret and its local CRM config, then writes with
+its own `ODLA_API_KEY`. Never send either website's Clerk JWT or ODLA key across
+the edge. Pipeline, account, billing, and roles remain authoritative locally.
+
+Conformance must prove:
+
+- the target metadata returned to the browser contains no secret;
+- only allowlisted fields leave the leader;
+- unknown follower types/fields fail before a write;
+- wrong share secret returns `401` and writes nothing;
+- retry updates the provenance-matched follower record instead of duplicating;
+- neither Clerk token nor either `ODLA_API_KEY` appears in the cross-site
+  request or client bundle.
+
 ## Phase 3 — Provisioning and Worker shell
 
 ```js
@@ -448,6 +482,10 @@ separate browser-owned booking-consent checkpoint for availability plus
 create/reschedule/cancel access. A grant created for the retired read-only
 mirror must be reconnected. No OAuth code or token passes through the agent.
 
+The app now exists. Initialize PM, backfill the approved Phase 0–2 decisions
+and evidence, create linked tasks/goals for the remaining tracks, and read that
+state before continuing.
+
 ## Phase 4 — Build the four application surfaces
 
 Import the public site's application theme once. For the admin application,
@@ -564,6 +602,13 @@ anchors; record details are record-tab anchors. Do not promote those tabs into
 the global site header. Use `chrome="standalone"` only for an admin-only product
 that has no host shell.
 
+The People collection uses the full workspace width until a record is selected,
+then becomes master/detail. Keep the default
+`collectionSection({ collapseClosedDetail: true })`; set it to `false` only
+when an intentional empty-detail panel contains useful approved content. At
+1280 and 1440 pixels, verify a wide collection table is not squeezed into a
+narrow rail beside an empty pane.
+
 The router must serve and reload `/`, every public page, `/join`, `/members/`,
 and `/admin/` without accidentally sending API paths to the SPA. Chapter
 terminates unknown `/api/*` paths as JSON 404s before the static asset fallback.
@@ -571,8 +616,10 @@ terminates unknown `/api/*` paths as JSON 404s before the static asset fallback.
 ## Phase 5 — Configure Clerk and bootstrap authority
 
 At this step, read Clerk's current agent-facing CLI documentation. Use one
-Clerk application with development and production instances; do not create a
-second application for production.
+Clerk application with development and production instances **for this
+website**; do not create a second application merely for this site's production
+environment. A leader and a follower are separate websites and use separate
+Clerk applications, issuers, users, and roles.
 
 For default chapter claim auth, the session token must include both: