@odla-ai/chapter 0.36.0 → 0.38.0

package/README.md

@@ -404,6 +404,112 @@ Simulation is deliberately a UI/test boundary, not acceptance evidence for a
 live Chapter. A follower still has to prove its real application write, Stripe
 webhook, and calendar booking journey before production.
 
+### Authenticated member pages
+
+Enable the standard member catalog explicitly:
+
+```ts
+const chapter = defineChapter({
+  // ...normal chapter config...
+  memberContent: {
+    localAuthoring: true,
+    parent: {
+      sourceId: "built-not-found",
+      // default follower vault key: member_content_control_secret
+    },
+  },
+});
+```
+
+This creates two deliberately separate authoring layers. The Parent delivers
+immutable signed revisions; the Chapter admin edits one local revision. The
+effective catalog merges them without permitting a Parent replay to replace a
+Chapter page. Each page declares a stable id/slug, navigation section/order,
+safe Markdown, and either `all-members` or an explicit set of tier ids. Tier
+sets are not treated as an ordinal ladder.
+
+```ts
+const parentDocument = {
+  schemaVersion: 1,
+  revision: 4,
+  generatedAt: Date.now(),
+  source: { type: "parent", appId: "built-not-found" },
+  target: { chapterId: "example-chapter", environment: "dev" },
+  pages: [{
+    id: "steward-library",
+    slug: "steward-library",
+    title: "Steward library",
+    navigation: { section: "Network", order: 20 },
+    audience: { kind: "tiers", tierIds: ["steward"] },
+    teaserMarkdown: "Advanced material for stewards.",
+    bodyMarkdown: "The **private** operating library.",
+    // Built Not Found delegates only this offer to the Chapter admin.
+    upsell: { owner: "chapter" },
+  }],
+};
+```
+
+An upsell references only a live tier id and bounded copy. Authored content
+cannot set price, Stripe ids, checkout state, HTML, CSS, or arbitrary links.
+The Worker attaches the currently offerable tier name and price. A Parent page
+may own its offer (`owner: "parent"`) or declare `owner: "chapter"`; the local
+document then uses `upsellOverrides` for that exact page. Chapter-authored
+pages always keep Chapter offer authority.
+
+`GET /api/member-content` requires a signed-in member. Chapter resolves the
+member's tier from their local application and removes every unauthorized
+`bodyMarkdown` before serializing JSON. Locked metadata may include a teaser
+and resolved offer. Admins may preview every body through the same projection.
+Client-side hiding is not an authorization boundary.
+
+Render the projection through the stock member area:
+
+```tsx
+<MembersArea api={api} signOut={signOut} memberPages />
+```
+
+Or compose `MemberContentArea` directly and provide a host-owned upgrade URL or
+callback. The package does not pretend a second application is an upgrade:
+
+```tsx
+<MemberContentArea
+  api={api}
+  upsellHref={(tierId) => approvedUpgradeRoute(tierId)}
+/>
+```
+
+The standard Chapter admin keeps the top-level Dashboard/People/Settings
+grammar and adds a **Member content** tab under Settings. It labels inherited
+pages as read-only, shows source/access/offer ownership, and edits the complete
+local JSON contract with revision guards and actionable validation errors.
+Agents may use the same authenticated `/api/admin/member-content` GET/PUT
+contract. Page bodies remain out of CRM; CRM continues to own people and
+lifecycle state.
+
+For central delivery, pair `createMemberContentEnvelope(document)` with
+`deliverMemberContent` from `@odla-ai/chapter/worker`. The dedicated signed
+route rejects wrong source/target/environment, stale or conflicting revisions,
+bad digests, undeclared tiers, and any Parent revision that would invalidate
+existing Chapter-owned content. The CRM edge and signup-control secret are
+never reused.
+
+Agents can run the same contract through the supported CLI. `tiers.json`
+contains a JSON array of the live safe authority projection (`id`, `name`,
+`priceCents`, and `active`) and deliberately excludes provider Price ids:
+
+```bash
+odla-ai chapter member-content validate --file parent.json --tiers tiers.json --json
+odla-ai chapter member-content compose --parent parent.json --chapter chapter.json --tiers tiers.json --json
+odla-ai chapter member-content project --parent parent.json --chapter chapter.json --tiers tiers.json --tier community --json
+odla-ai chapter member-content deliver --file parent.json --tiers tiers.json \
+  --url https://chapter.example --from-env MEMBER_CONTENT_SECRET --json
+```
+
+Use `--stdin` instead of `--from-env` when the signing secret comes from a
+producer process. The value is never accepted as an argument. `project` is the
+server-disclosure proof and omits locked bodies; `compose` is a local operator
+authoring view and contains the supplied content.
+
 ### Hub-authoritative live signup control
 
 When a hub must control the live membership page as well as preview it, use the
@@ -448,6 +554,32 @@ join-config, application tier validation, and checkout already read. Public
 application contract, and theme. Applicant requests therefore use local
 last-known-good state and never depend on the hub being reachable.
 
+#### One field contract for follower forms and CMS management
+
+Chapter owns field identity and storage authority; a hub such as Built Not
+Found owns the editor. Declare the follower's maximum application field set in
+`defineChapter({ application: { required, optional, conditions, maxLen } })`.
+A signed signup-control revision may select, reorder, and change requiredness
+only within that declared set. It cannot invent a field, change its value type,
+or expose an operational application attribute.
+
+`chapterFlowFieldContract(chapter, "join")` and
+`chapterFlowFieldContract(chapter, "formation")` return the same versioned,
+ordered shape: stable field id, label, CRM value type, requiredness, order,
+length cap, enum options, and conditions where the flow supports them.
+`GET /api/join-config` exposes the effective `fieldContract` after active
+signup control is applied. `GET /api/formation/config` exposes the same
+`fieldContract` and retains its legacy `fields` array as a compatibility alias.
+Use that document for a CMS preview or host renderer; submit to the packaged
+route so the server enforces the same effective selection.
+
+Email identity is literal. `normalizeChapterEmail()` trims and lowercases only;
+it never applies Gmail/provider alias rules. Consequently
+`foo+bar@gmail.com` and `foo@gmail.com` are distinct application, admission,
+purchase, and gift-beneficiary identities even if a mailbox provider delivers
+both to the same inbox. Email fields advertise `emailIdentity: "literal"` in
+the flow contract so editors and test fixtures do not collapse them.
+
 Materialization addresses provisioned groups and tiers by their unique public
 `id` attributes, not by assuming those values are odla-db entity ids. A failed
 materialization returns a bounded JSON `materialization_failed` rejection and
@@ -620,7 +752,8 @@ and relations by composing its own config before passing it to Chapter.
 
 `formation: {}` opts into a host-rendered public application:
 
-- `GET /api/formation/config` returns only configured public field metadata.
+- `GET /api/formation/config` returns only configured public field metadata in
+  the same versioned `fieldContract` shape as the join flow.
 - `POST /api/formation/applications` accepts only those fields and creates a
   normal `chapter_application` CRM record.
 - A stable base64url `submissionId` makes ambiguous retries resolve to the same
@@ -1155,7 +1288,8 @@ These bite silently — a smoke test won't catch them:
   against a permissive email shape (400 on `"notanemail"`, so it fails cleanly
   here rather than at the downstream Clerk create) — set
   `application: { validateEmail: false }` to opt out; `isValidEmail` is exported.
-  A valid application is never newly rejected.
+  A valid application is never newly rejected. Identity normalization trims
+  and lowercases but keeps the full local part: plus-addresses remain distinct.
 - **CRM enrichment.** `projectApplicant` writes the base identity/contact person.
   To carry more of the application into the CRM, list `application: { crmFields:
   [...] }`. Each name is **cross-checked against your crm `person` type at