@odla-ai/chapter 0.36.0 → 0.37.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