@odla-ai/chapter 0.21.0 → 0.22.0

package/README.md

@@ -8,7 +8,7 @@ email. The host still builds the public pages, routing, and brand presentation;
 Chapter supplies their application mechanics.
 
 ```sh
-npm i --save-exact @odla-ai/chapter@0.21.0
+npm i --save-exact @odla-ai/chapter@0.22.0
 ```
 
 > **Agentic experiment.** Built and maintained by AI agents from bounded runbooks
@@ -365,10 +365,76 @@ The default chapter console deliberately has only three top-level workspaces:
   Connections, Access, and Sharing record tabs when those capabilities apply.
 - **Settings** — Calendar and Email page tabs.
 
-Use `chrome="editorial"` (the default), `chrome="none"` when the host supplies
-its own site header, or `renderHeader` for a fully custom header. The deprecated
-`chrome="topbar"` and `sections` APIs remain available for migration, but do
-not add operational detail back to the global site navigation.
+The default `chrome="embedded"` assumes the host supplies the site header.
+Use `chrome="standalone"` for Chapter's packaged masthead or `renderHeader` for
+a custom header rendered inside the Chapter theme boundary. `editorial`,
+`none`, `topbar`, and `sections` remain compatibility APIs. Do not add
+operational detail back to the global site navigation.
+
+Only the active workspace, page tab, and record tab mount their content.
+Inactive operational panels therefore do not fetch, subscribe, or run effects.
+Their native anchors remain in the document, so every level is still
+reloadable and participates in browser back/forward navigation.
+
+#### Preserve an existing People structure
+
+The responsive state and data loading belong to `@odla-ai/crm`; the branded
+summary, master rail, record heading, and specialized panels can remain
+host-owned:
+
+```tsx
+const people = collectionSection({
+  crm: chapter.crm,
+  type: "person",
+  lifecycle: true,
+  renderSummary: ({ query }) => (
+    <PeopleSummary total={query.page?.total ?? 0} />
+  ),
+  renderMaster: ({ defaultMaster }) => (
+    <PeopleRail>{defaultMaster}</PeopleRail>
+  ),
+  renderDetailHeader: ({ detail }) => (
+    <RecordHeading record={detail.record} />
+  ),
+  extendRecordTabs: (tabs, context) => replaceRecordPanels(tabs, context),
+});
+```
+
+`renderMaster` receives the loaded query, selection helpers, native record-link
+builder, and `defaultMaster`, so a host may wrap the standard list or replace
+its presentation without taking over fetching. `extendRecordTabs` supports
+per-record `visible` and `disabled` predicates. Hidden panels do not mount.
+
+For `lifecycle: true`, Chapter routes stage transitions through the
+application-authoritative approve/refund/manual-transition endpoints and
+requires that adapter. A custom operational collection can pass
+`lifecycleAdapter`; generic CRM collections continue to use the CRM mutation.
+
+#### Adapt existing authentication routes
+
+An existing site does not need to rename its config or current-user endpoints:
+
+```tsx
+<ChapterAdmin
+  chapter={chapter}
+  auth={{
+    configPath: "/api/auth/config",
+    mapConfig: (body) => ({
+      publishableKey: typeof body.publishableKey === "string"
+        ? body.publishableKey
+        : null,
+    }),
+    mapCurrentUser: (body) => ({
+      ...body,
+      authorized: body.role === "admin" || body.superAdmin === true,
+    }),
+  }}
+/>
+```
+
+`loadConfig` and `loadCurrentUser` may replace fetching entirely. The normalized
+current-user object is also available to workspace renderers for presentation
+decisions; server authorization remains authoritative.
 
 When upgrading a flat console:
 
@@ -377,11 +443,14 @@ When upgrading a flat console:
 2. Remove top-level Billing, Email, Calendar, or collection links that duplicate
    the standard nested tabs.
 3. Replace `sections` with `workspaces`, or omit it to accept the defaults.
-4. Remove host-owned record drawers and compose extra operations with
-   `collectionSection` or CRM `extendRecordTabs`.
-5. Change generated links to `adminRouteHref`; keep legacy query/path URLs only
+4. Move host-owned summaries, master rails, and record headings into
+   `collectionSection` render slots; compose specialized operations with
+   `extendRecordTabs`.
+5. Connect application-backed stage changes through `lifecycleAdapter`; never
+   replace an operational transition with a raw CRM stage write.
+6. Change generated links to `adminRouteHref`; keep legacy query/path URLs only
    as inbound compatibility links.
-6. Verify refresh, back/forward navigation, keyboard tab behavior, mobile
+7. Verify refresh, back/forward navigation, keyboard tab behavior, mobile
    list/detail switching, and brand containment before deleting old routes.
 
 ## Adopting into an existing site
@@ -513,7 +582,7 @@ These bite silently — a smoke test won't catch them:
   invitation mail. Importing the full `@odla-ai/chapter/ui` barrel pulls the admin
   half, so prefer the narrower entry.
 - **Known-good application set** (installs clean, no flags):
-  `@odla-ai/chapter` 0.21.0, `@odla-ai/ui` 0.11.0, `@odla-ai/crm` 0.2.0,
+  `@odla-ai/chapter` 0.22.0, `@odla-ai/ui` 0.12.0, `@odla-ai/crm` 0.3.0,
   `@odla-ai/db` 0.6.6,
   `@odla-ai/calendar` 0.2.0, `@odla-ai/email` 0.3.1,
   `@odla-ai/auth-clerk` 0.4.0, `@odla-ai/o11y` 2.2.2, `jose` 6.2.3, React