@odla-ai/chapter 0.20.0 → 0.20.1

package/README.md

@@ -154,10 +154,10 @@ export default {
 ```
 
 That is the reusable application shell. The follower's public pages remain
-site-owned: start from the Silver & Salt content rhythm and `@odla-ai/ui`
-marketing components, then change the wordmark, palette, copy, imagery, and
-investment thesis. Do not fork auth, admin routing, CRM, payment, booking, or
-account logic to achieve a different brand.
+site-owned: start from a reference design and `@odla-ai/ui` marketing
+components, then change the wordmark, palette, copy, imagery, and investment
+thesis. Do not fork auth, admin routing, CRM, payment, booking, or account logic
+to achieve a different brand.
 
 ### Leader → follower delivery
 
@@ -190,9 +190,126 @@ config. The standard collection drawer discovers the target and calls the
 admin-gated push route. A follower must declare the receiving CRM type/fields;
 otherwise it rejects the record cleanly instead of dropping fields.
 
+#### Existing follower CRMs must opt into the shared graph
+
+When `crm` is omitted, chapter's default already contains compatible `person`
+and `company` types plus a `works_at` relation. Passing a custom CRM replaces
+that default; chapter does not merge missing types or fields into it. A follower
+that wants both people and businesses must therefore declare compatible types
+itself:
+
+```ts
+import { defineCrm } from "@odla-ai/crm";
+
+const crm = defineCrm({
+  types: {
+    person: {
+      label: "Person",
+      labelPlural: "People",
+      nameField: "name",
+      emailField: "email",
+      fields: {
+        name: { type: "string", label: "Name", required: true },
+        email: { type: "email", label: "Email" },
+        firstName: { type: "string", label: "First name" },
+        lastName: { type: "string", label: "Last name" },
+        phone: { type: "string", label: "Phone" },
+        linkedin: { type: "string", label: "LinkedIn" },
+      },
+    },
+    company: {
+      label: "Business",
+      labelPlural: "Businesses",
+      nameField: "name",
+      fields: {
+        name: { type: "string", label: "Name", required: true },
+        domain: { type: "string", label: "Domain / website", slot: "s1" },
+        industry: { type: "string", label: "Industry" },
+        location: { type: "string", label: "Location" },
+        linkedin: { type: "string", label: "LinkedIn" },
+        notes: { type: "string", label: "Notes" },
+      },
+    },
+  },
+  relations: {
+    works_at: {
+      from: "person",
+      to: "company",
+      label: "works at",
+      reverseLabel: "team",
+    },
+  },
+});
+```
+
+The follower must declare every field its leader may send. Unknown types or
+fields fail the request before any CRM write. Record delivery currently moves
+records, not `crm_link` relation rows; create or curate `works_at` links locally.
+
+#### Custom leader consoles must mount the sharing UI
+
+Automatic “Share with …” actions come from chapter's standard collection
+sections. They are present when the console uses
+`<ChapterAdmin chapter={chapter} />`. Passing an explicit `sections` array
+replaces that catalog, so a custom console must deliberately compose it:
+
+```tsx
+import {
+  ChapterAdmin,
+  defaultAdminSections,
+} from "@odla-ai/chapter/ui/admin";
+
+const sections = [
+  customOverviewSection,
+  ...defaultAdminSections(chapter),
+];
+
+render(
+  <ChapterAdmin chapter={chapter} sections={sections} />,
+  document.getElementById("admin-root"),
+);
+```
+
+If the custom console renders its own record drawer instead, mount
+`NetworkShareActions` inside that drawer:
+
+```tsx
+<NetworkShareActions
+  recordId={record.id}
+  recordType={record.type}
+  getToken={sectionContext.getToken}
+/>
+```
+
+The component discovers compatible targets through
+`GET /api/admin/network/targets`; it never receives follower secrets in browser
+data.
+
+#### Verify delivery in development before production
+
+Use distinct development tenants and follower origins for the first delivery:
+
+1. Vault one random value as `network_share_secret` in the follower and under
+   the target's resolved `secretName` in the leader.
+2. Confirm `GET /api/admin/network/targets` lists the development follower with
+   the expected compatible record types.
+3. Share one test person and one test business from the leader's record drawer.
+   Confirm each appears in the follower with only allowlisted fields.
+4. Share each record again. The second delivery must update the same follower
+   record, not create a duplicate.
+5. Confirm the follower's pipeline, account, and billing state did not change;
+   those remain locally authoritative.
+6. Change one allowlisted leader field and share again to prove later deliveries
+   update the existing record. A target with the wrong secret must return `401`
+   without writing CRM data.
+
+Only after this contract passes against development origins should the leader
+target be changed to a production follower origin and the matching production
+vault values be installed.
+
 Section navigation defaults to `/admin/?tab=people`, not
 `/admin/people`. Query routing deliberately works in both leader-style SPAs and
-Silver & Salt-style static subdirectories. Legacy path links still open, and
+ordinary static subdirectories. Legacy path links still open, and
 `routing="path"` remains available only for hosts with an explicit SPA fallback.
 
 ## Adopting into an existing site

package/package.json

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