@odla-ai/chapter 0.23.0 → 0.25.0

package/dist/index.d.cts

@@ -21,7 +21,14 @@ interface ChapterCopy {
     join: {
         form: TextFields<"submit" | "submitting" | "submitFailed" | "unexpectedFailure">;
         booking: TextFields<"unavailable" | "loadFailed" | "slotTaken" | "failed" | "loading" | "book" | "booking">;
-        payment: TextFields<"setupFailed" | "preparing" | "pending" | "processing" | "payAndContinue" | "incomplete">;
+        /**
+         * `consent` is the affirmative statement a member agrees to before the card
+         * form appears, rendered beside the checkbox and beneath the policy text.
+         * It is what the member is shown at the moment of consent, so it says they
+         * agree rather than merely restating the policy. Set it to an empty string
+         * to render the checkbox with the policy as its only label.
+         */
+        payment: TextFields<"setupFailed" | "preparing" | "pending" | "processing" | "payAndContinue" | "incomplete" | "consent">;
         done: TextFields<"label" | "calendarInvite" | "memberArea">;
     };
     members: {
@@ -320,10 +327,9 @@ interface ChapterApplication {
      *  writing a row with no consent record. Default `true`. Set `false`
      *  deliberately only when the site renders no consent control. */
     requireDisclaimerAck?: boolean;
-    /** Allowlist of fields that reach the Clerk account's client-readable
-     *  `public_metadata.profile`. Default `[]`, so application details remain
-     *  db-only. Set a curated list (e.g. `["phone", "state", "focus"]`) for
-     *  fields the browser may read. */
+    /** Allowlist of application fields mirrored into the Clerk account's
+     *  backend-only `private_metadata.profile`. Default `[]`. Use this for small
+     *  account/admin signals; the application row and CRM remain canonical. */
     profileFields?: readonly string[];
     /** Extra application fields carried into the one-way CRM projection, on top of
      *  the built-in identity/contact set. Each MUST be declared on your crm person
@@ -521,6 +527,20 @@ interface ChapterIntegrationDescriptor {
         path: string;
         expectedStatus: number;
     }>;
+    /** Runbooks that bear on THIS chapter's role, so tooling can point at the
+     * right procedure without the operator knowing it exists. A chapter declaring
+     * `network.targets` is a leader hub; one declaring none is a follower site,
+     * and the two follow different procedures for the same words ("connect",
+     * "share records"). */
+    runbooks: ChapterRunbookHints;
+}
+/** Which runbooks apply, and why. */
+interface ChapterRunbookHints {
+    role: "leader" | "follower";
+    /** Platform runbook slugs, most relevant first. */
+    slugs: string[];
+    /** One line a human or agent can act on. */
+    guidance: string;
 }
 /**
  * Build the one CLI-consumable integration for a chapter/hub: the crm_*
@@ -856,11 +876,10 @@ declare function clampArray(value: unknown, max: number): unknown;
  *  the boolean an API client sends and the string a plain HTML form posts. */
 declare function hasDisclaimerAck(fields: Record<string, unknown>): boolean;
 /**
- * The applicant profile written to the Clerk account's client-readable
- * `public_metadata.profile`. Projects each configured non-identity field, plus
- * `focus` (clamped), but ONLY those in `application.profileFields`, so a site
- * keeps confidential fields (`message`, `referral`) db-only. Derived from
- * config, so a site's own field names project without this package knowing
+ * The applicant profile written to the Clerk account's backend-only
+ * `private_metadata.profile`. Projects each configured non-identity field, plus
+ * `focus` (clamped), but ONLY those in `application.profileFields`. Derived
+ * from config, so a site's own field names project without this package knowing
  * them. Pure; returns `undefined` when there is nothing to write.
  */
 declare function applicantProfile(chapter: Chapter, fields: Record<string, unknown>): Record<string, unknown> | undefined;
@@ -1076,7 +1095,7 @@ interface ClerkResult {
     ok: boolean;
     status: number;
     existed?: boolean;
-    /** Set when an `existed` heal also refreshed the account's public_metadata. */
+    /** Set when an `existed` heal also refreshed the account's metadata. */
     refreshed?: boolean;
 }
 /** Inputs for a Clerk invitation. */
@@ -1084,8 +1103,9 @@ interface ClerkInviteInput {
     email: string;
     /** Where the accept-invitation link lands (usually the member area). */
     redirectUrl?: string;
-    /** Written to the invitation's `public_metadata`, so the accepted account
-     *  carries your own profile fields. */
+    /** Written to the invitation's `public_metadata`. Clerk application
+     *  invitations cannot carry private metadata, so never put applicant profile
+     *  fields here. Chapter completes that backend-only write after acceptance. */
     publicMetadata?: Record<string, unknown>;
 }
 /** Build the Clerk Backend API invitation request (path + JSON body). Pure, so
@@ -1103,9 +1123,14 @@ interface ClerkUserInput {
     email: string;
     firstName?: string;
     lastName?: string;
-    /** Written to the user's `public_metadata` — the site's own profile fields
-     *  (role, tier, whatever the member area reads). */
+    /** Backend-authored, browser-readable claims such as `role`. */
     publicMetadata?: Record<string, unknown>;
+    /** Backend-only account signals and profile data. */
+    privateMetadata?: Record<string, unknown>;
+    /** Optional metadata merge used only when create returns 422 for an existing
+     * account. This lets migrations remove legacy keys without putting tombstone
+     * values on a newly-created user. Defaults to the create metadata. */
+    repairMetadata?: ClerkMetadataInput;
 }
 /** Build the Clerk Backend API user-create request. The account is created
  *  passwordless (the member signs in via the site's Clerk flow), so join step 3
@@ -1114,21 +1139,41 @@ declare function clerkUserRequest(input: ClerkUserInput): {
     path: string;
     body: Record<string, unknown>;
 };
+/** One merge-PATCH to the metadata fields Clerk exposes on its Backend API. */
+interface ClerkMetadataInput {
+    publicMetadata?: Record<string, unknown>;
+    privateMetadata?: Record<string, unknown>;
+}
+/** Merge metadata into an existing Clerk user. Nested `null` values remove old
+ * keys, which Chapter uses to migrate its former public profile into private
+ * metadata without disturbing the public `role` claim. */
+declare function updateClerkUserMetadata(secretKey: string, userId: string, input: ClerkMetadataInput, fetchImpl?: typeof fetch): Promise<boolean>;
+/** Look a Clerk account up by email and merge its metadata.
+ *
+ * Returns `false` when no matching user can be resolved or Clerk rejects the
+ * lookup or update. Chapter uses this for create-healing and invitation
+ * adoption so a repeated application repairs the private account snapshot.
+ */
+declare function updateClerkUserMetadataByEmail(secretKey: string, email: string, input: ClerkMetadataInput, fetchImpl?: typeof fetch): Promise<boolean>;
 /** Create the applicant's Clerk account server-side. A repeat for an email that
  *  already has an account heals to `{ ok: true, existed: true }` — the account
- *  exists, which is the state apply-time provisioning wanted — and, when
- *  `publicMetadata` was supplied, refreshes it on the existing account so a
- *  re-application repairs a previously missed create (`refreshed: true`). */
+ *  exists, which is the state apply-time provisioning wanted — and refreshes
+ *  supplied public/private metadata on the existing account so a re-application
+ *  repairs a previously missed create (`refreshed: true`). */
 declare function createClerkUser(secretKey: string, input: ClerkUserInput, fetchImpl?: typeof fetch): Promise<ClerkResult>;
 
 /** A Clerk user as chapter's role layer sees it. `role` defaults to the lowest
- *  rung when `public_metadata` carries none; `publicMetadata` is returned raw so a
- *  site with a custom ladder can re-derive it. */
+ *  rung when `public_metadata` carries none. Raw public/private metadata is
+ *  returned only from this backend helper; `profile` and `applicationId` are the
+ *  normalized Chapter-owned private signals. */
 interface ClerkUserRecord {
     id: string;
     email?: string;
     role: string;
     publicMetadata: Record<string, unknown>;
+    privateMetadata: Record<string, unknown>;
+    profile: Record<string, unknown>;
+    applicationId?: string;
 }
 /** Look a Clerk user up by email. `null` when no such user — or when the lookup
  *  fails (a role gate treats an unresolvable user as absent, matching the site's
@@ -1143,8 +1188,9 @@ declare function clerkGetUser(secretKey: string, id: string, fetchImpl?: typeof
  *  until a short page. A page fetch that fails THROWS rather than returning a
  *  partial list, so the caller never mistakes a truncated roster for the whole. */
 declare function clerkListUsers(secretKey: string, fetchImpl?: typeof fetch): Promise<ClerkUserRecord[]>;
-/** Write a user's role: a MERGE-PATCH of only `{ role }` on `public_metadata`, so
- *  it leaves a separately-written `profile` untouched. Returns whether it stuck. */
+/** Write a user's role: a MERGE-PATCH of only `{ role }` on `public_metadata`.
+ *  The backend-only profile lives in `private_metadata`, so the two signals
+ *  cannot overwrite each other. Returns whether the role write stuck. */
 declare function clerkSetRole(secretKey: string, id: string, role: string, fetchImpl?: typeof fetch): Promise<boolean>;
 
 /** Which auth mode a secret is required for: `"client"` (publishable key only) or
@@ -1210,8 +1256,9 @@ interface IntegrationDescriptor {
  * the one public `setting` (the `pk_*` publishable key, served to the SPA), the
  * `secrets` auth mode `"full"` needs in the tenant vault, BOTH sync directions —
  * the inbound `$users` webhook mirror (`provider->odla`) and the outbound
- * role/profile write via `clerk_secret_key` (`odla->provider`, chapter's
- * `clerk.ts`) — and the `provision` split. Data only; it performs none of it.
+ * public role/private profile write via `clerk_secret_key` (`odla->provider`,
+ * chapter's `clerk.ts`) — and the `provision` split. Data only; it performs
+ * none of it.
  */
 declare const clerkIntegration: IntegrationDescriptor;
 
@@ -1470,4 +1517,4 @@ type ApplicationBookingPatch = {
  *  already there (never backward). */
 declare function applicationBookingUpdate(currentStatus: string, startAt: number, htmlLink?: string | null): ApplicationBookingPatch;
 
-export { type AccountModel, type AdminNotificationTrigger, type Applicant, type ApplicationBookingPatch, type ApplicationRecord, type ApplicationSummary, type Attr, type AttrType, type Chapter, type ChapterApplication, type ChapterAuth, type ChapterBrand, type ChapterConfig, type ChapterCopy, type ChapterCopyInput, type ChapterDb, type ChapterEmails, type ChapterIntegrationDescriptor, type ChapterIntegrationOptions, type ChapterMode, type ChapterNetwork, type ChapterNetworkTarget, type ChapterOperations, type ChapterPipeline, type ChapterPolicy, type ChapterPrices, type ChapterScheduling, type ChapterSends, type ClerkInviteInput, type ClerkResult, type ClerkUserInput, type ClerkUserRecord, type CompiledChapterBrandTokens, DEFAULT_CHAPTER_COPY, DEFAULT_SHARE_FIELDS, type DashboardMetricData, type DashboardMetricSeries, type DbOp, type DbRules, type DbSchema, type DeliveryDecision, type EmailGroup, type EmailTemplate, type EmailTemplateRow, type Entity, type ExistingMeeting, type GuardResult, type IntegrationDescriptor, type IntegrationProvision, type IntegrationSecret, type IntegrationSetting, type IntegrationSync, type JoinConfigGroup, type LiveEvent, type MailSender, type MeetingForReconcile, type MeetingRecord, type MeetingReschedulePatch, type MemberApplication, type MemberSession, type NewMeetingRow, type NotifyDeps, type NotifyInput, type NotifyResult, type PaymentsGroup, type ProjectionDeps, type ReconcileDecision, type ResolvedApplication, type ResolvedAuth, type ResolvedNetwork, type ResolvedNetworkTarget, type ResolvedOperations, type ResolvedPipeline, type ResolvedScheduling, type ResolvedSends, type RoleChangeContext, type Rule, SCHEDULING_DEFAULTS, type SchedulingErrors, type SecretMode, type SecretStore, type SessionUser, type SharedBusiness, type SharedPerson, type SharedRecord, type StripeEvent, type StripeResult, type SubmitResult, type WebhookEvent, applicantProfile, applicationBookingUpdate, applicationSummary, backfillCrm, bookingDecision, brandTokens, bucketSeries, buildGroupSeed, canApprove, canBook, canChangeRole, canTransition, canceledPatch, chapterBrandFromTokens, chapterDb, clampArray, clerkGetUser, clerkGetUserByEmail, clerkIntegration, clerkInviteRequest, clerkListUsers, clerkSetRole, clerkUserRequest, createChapterIntegration, createClerkInvitation, createClerkUser, dashboardMetricData, defaultCrm, defineChapter, emailGroupFrom, endForSlot, findApplicationRef, firstPaymentPatch, formatChapterCopy, getVaultSecret, hasDisclaimerAck, introIdempotencyKey, isAdminRole, isAlreadySent, isReconcilable, isSlotAvailable, isValidEmail, joinConfig, meetingCreateRow, meetingRescheduleUpdate, memberApplication, memberSession, networkSourceTag, normalizeSharedRecord, normalizeWebhookEvent, paymentsReady, personInputFromApp, planDelivery, projectApplicant, projectSharedRecord, reconcileMeetings, refundedPatch, render, renderSummary, renderTemplateBody, renewalPatch, resolveApplication, resolveAuth, resolveChapterCopy, resolvePipeline, resolveScheduling, roleFromClaim, sendTemplated, sharedPersonInput, sharedRecordFromCrm, slotWindow, stageIndex, stripeCall, stripeForm, subAnnualCents, submitApplication, subscriptionIdempotencyKey, syncApplicationToCrm, validateScheduling, verifyStripeSignature, webhookMutationId };
+export { type AccountModel, type AdminNotificationTrigger, type Applicant, type ApplicationBookingPatch, type ApplicationRecord, type ApplicationSummary, type Attr, type AttrType, type Chapter, type ChapterApplication, type ChapterAuth, type ChapterBrand, type ChapterConfig, type ChapterCopy, type ChapterCopyInput, type ChapterDb, type ChapterEmails, type ChapterIntegrationDescriptor, type ChapterIntegrationOptions, type ChapterMode, type ChapterNetwork, type ChapterNetworkTarget, type ChapterOperations, type ChapterPipeline, type ChapterPolicy, type ChapterPrices, type ChapterRunbookHints, type ChapterScheduling, type ChapterSends, type ClerkInviteInput, type ClerkMetadataInput, type ClerkResult, type ClerkUserInput, type ClerkUserRecord, type CompiledChapterBrandTokens, DEFAULT_CHAPTER_COPY, DEFAULT_SHARE_FIELDS, type DashboardMetricData, type DashboardMetricSeries, type DbOp, type DbRules, type DbSchema, type DeliveryDecision, type EmailGroup, type EmailTemplate, type EmailTemplateRow, type Entity, type ExistingMeeting, type GuardResult, type IntegrationDescriptor, type IntegrationProvision, type IntegrationSecret, type IntegrationSetting, type IntegrationSync, type JoinConfigGroup, type LiveEvent, type MailSender, type MeetingForReconcile, type MeetingRecord, type MeetingReschedulePatch, type MemberApplication, type MemberSession, type NewMeetingRow, type NotifyDeps, type NotifyInput, type NotifyResult, type PaymentsGroup, type ProjectionDeps, type ReconcileDecision, type ResolvedApplication, type ResolvedAuth, type ResolvedNetwork, type ResolvedNetworkTarget, type ResolvedOperations, type ResolvedPipeline, type ResolvedScheduling, type ResolvedSends, type RoleChangeContext, type Rule, SCHEDULING_DEFAULTS, type SchedulingErrors, type SecretMode, type SecretStore, type SessionUser, type SharedBusiness, type SharedPerson, type SharedRecord, type StripeEvent, type StripeResult, type SubmitResult, type WebhookEvent, applicantProfile, applicationBookingUpdate, applicationSummary, backfillCrm, bookingDecision, brandTokens, bucketSeries, buildGroupSeed, canApprove, canBook, canChangeRole, canTransition, canceledPatch, chapterBrandFromTokens, chapterDb, clampArray, clerkGetUser, clerkGetUserByEmail, clerkIntegration, clerkInviteRequest, clerkListUsers, clerkSetRole, clerkUserRequest, createChapterIntegration, createClerkInvitation, createClerkUser, dashboardMetricData, defaultCrm, defineChapter, emailGroupFrom, endForSlot, findApplicationRef, firstPaymentPatch, formatChapterCopy, getVaultSecret, hasDisclaimerAck, introIdempotencyKey, isAdminRole, isAlreadySent, isReconcilable, isSlotAvailable, isValidEmail, joinConfig, meetingCreateRow, meetingRescheduleUpdate, memberApplication, memberSession, networkSourceTag, normalizeSharedRecord, normalizeWebhookEvent, paymentsReady, personInputFromApp, planDelivery, projectApplicant, projectSharedRecord, reconcileMeetings, refundedPatch, render, renderSummary, renderTemplateBody, renewalPatch, resolveApplication, resolveAuth, resolveChapterCopy, resolvePipeline, resolveScheduling, roleFromClaim, sendTemplated, sharedPersonInput, sharedRecordFromCrm, slotWindow, stageIndex, stripeCall, stripeForm, subAnnualCents, submitApplication, subscriptionIdempotencyKey, syncApplicationToCrm, updateClerkUserMetadata, updateClerkUserMetadataByEmail, validateScheduling, verifyStripeSignature, webhookMutationId };

package/dist/index.d.ts

@@ -21,7 +21,14 @@ interface ChapterCopy {
     join: {
         form: TextFields<"submit" | "submitting" | "submitFailed" | "unexpectedFailure">;
         booking: TextFields<"unavailable" | "loadFailed" | "slotTaken" | "failed" | "loading" | "book" | "booking">;
-        payment: TextFields<"setupFailed" | "preparing" | "pending" | "processing" | "payAndContinue" | "incomplete">;
+        /**
+         * `consent` is the affirmative statement a member agrees to before the card
+         * form appears, rendered beside the checkbox and beneath the policy text.
+         * It is what the member is shown at the moment of consent, so it says they
+         * agree rather than merely restating the policy. Set it to an empty string
+         * to render the checkbox with the policy as its only label.
+         */
+        payment: TextFields<"setupFailed" | "preparing" | "pending" | "processing" | "payAndContinue" | "incomplete" | "consent">;
         done: TextFields<"label" | "calendarInvite" | "memberArea">;
     };
     members: {
@@ -320,10 +327,9 @@ interface ChapterApplication {
      *  writing a row with no consent record. Default `true`. Set `false`
      *  deliberately only when the site renders no consent control. */
     requireDisclaimerAck?: boolean;
-    /** Allowlist of fields that reach the Clerk account's client-readable
-     *  `public_metadata.profile`. Default `[]`, so application details remain
-     *  db-only. Set a curated list (e.g. `["phone", "state", "focus"]`) for
-     *  fields the browser may read. */
+    /** Allowlist of application fields mirrored into the Clerk account's
+     *  backend-only `private_metadata.profile`. Default `[]`. Use this for small
+     *  account/admin signals; the application row and CRM remain canonical. */
     profileFields?: readonly string[];
     /** Extra application fields carried into the one-way CRM projection, on top of
      *  the built-in identity/contact set. Each MUST be declared on your crm person
@@ -521,6 +527,20 @@ interface ChapterIntegrationDescriptor {
         path: string;
         expectedStatus: number;
     }>;
+    /** Runbooks that bear on THIS chapter's role, so tooling can point at the
+     * right procedure without the operator knowing it exists. A chapter declaring
+     * `network.targets` is a leader hub; one declaring none is a follower site,
+     * and the two follow different procedures for the same words ("connect",
+     * "share records"). */
+    runbooks: ChapterRunbookHints;
+}
+/** Which runbooks apply, and why. */
+interface ChapterRunbookHints {
+    role: "leader" | "follower";
+    /** Platform runbook slugs, most relevant first. */
+    slugs: string[];
+    /** One line a human or agent can act on. */
+    guidance: string;
 }
 /**
  * Build the one CLI-consumable integration for a chapter/hub: the crm_*
@@ -856,11 +876,10 @@ declare function clampArray(value: unknown, max: number): unknown;
  *  the boolean an API client sends and the string a plain HTML form posts. */
 declare function hasDisclaimerAck(fields: Record<string, unknown>): boolean;
 /**
- * The applicant profile written to the Clerk account's client-readable
- * `public_metadata.profile`. Projects each configured non-identity field, plus
- * `focus` (clamped), but ONLY those in `application.profileFields`, so a site
- * keeps confidential fields (`message`, `referral`) db-only. Derived from
- * config, so a site's own field names project without this package knowing
+ * The applicant profile written to the Clerk account's backend-only
+ * `private_metadata.profile`. Projects each configured non-identity field, plus
+ * `focus` (clamped), but ONLY those in `application.profileFields`. Derived
+ * from config, so a site's own field names project without this package knowing
  * them. Pure; returns `undefined` when there is nothing to write.
  */
 declare function applicantProfile(chapter: Chapter, fields: Record<string, unknown>): Record<string, unknown> | undefined;
@@ -1076,7 +1095,7 @@ interface ClerkResult {
     ok: boolean;
     status: number;
     existed?: boolean;
-    /** Set when an `existed` heal also refreshed the account's public_metadata. */
+    /** Set when an `existed` heal also refreshed the account's metadata. */
     refreshed?: boolean;
 }
 /** Inputs for a Clerk invitation. */
@@ -1084,8 +1103,9 @@ interface ClerkInviteInput {
     email: string;
     /** Where the accept-invitation link lands (usually the member area). */
     redirectUrl?: string;
-    /** Written to the invitation's `public_metadata`, so the accepted account
-     *  carries your own profile fields. */
+    /** Written to the invitation's `public_metadata`. Clerk application
+     *  invitations cannot carry private metadata, so never put applicant profile
+     *  fields here. Chapter completes that backend-only write after acceptance. */
     publicMetadata?: Record<string, unknown>;
 }
 /** Build the Clerk Backend API invitation request (path + JSON body). Pure, so
@@ -1103,9 +1123,14 @@ interface ClerkUserInput {
     email: string;
     firstName?: string;
     lastName?: string;
-    /** Written to the user's `public_metadata` — the site's own profile fields
-     *  (role, tier, whatever the member area reads). */
+    /** Backend-authored, browser-readable claims such as `role`. */
     publicMetadata?: Record<string, unknown>;
+    /** Backend-only account signals and profile data. */
+    privateMetadata?: Record<string, unknown>;
+    /** Optional metadata merge used only when create returns 422 for an existing
+     * account. This lets migrations remove legacy keys without putting tombstone
+     * values on a newly-created user. Defaults to the create metadata. */
+    repairMetadata?: ClerkMetadataInput;
 }
 /** Build the Clerk Backend API user-create request. The account is created
  *  passwordless (the member signs in via the site's Clerk flow), so join step 3
@@ -1114,21 +1139,41 @@ declare function clerkUserRequest(input: ClerkUserInput): {
     path: string;
     body: Record<string, unknown>;
 };
+/** One merge-PATCH to the metadata fields Clerk exposes on its Backend API. */
+interface ClerkMetadataInput {
+    publicMetadata?: Record<string, unknown>;
+    privateMetadata?: Record<string, unknown>;
+}
+/** Merge metadata into an existing Clerk user. Nested `null` values remove old
+ * keys, which Chapter uses to migrate its former public profile into private
+ * metadata without disturbing the public `role` claim. */
+declare function updateClerkUserMetadata(secretKey: string, userId: string, input: ClerkMetadataInput, fetchImpl?: typeof fetch): Promise<boolean>;
+/** Look a Clerk account up by email and merge its metadata.
+ *
+ * Returns `false` when no matching user can be resolved or Clerk rejects the
+ * lookup or update. Chapter uses this for create-healing and invitation
+ * adoption so a repeated application repairs the private account snapshot.
+ */
+declare function updateClerkUserMetadataByEmail(secretKey: string, email: string, input: ClerkMetadataInput, fetchImpl?: typeof fetch): Promise<boolean>;
 /** Create the applicant's Clerk account server-side. A repeat for an email that
  *  already has an account heals to `{ ok: true, existed: true }` — the account
- *  exists, which is the state apply-time provisioning wanted — and, when
- *  `publicMetadata` was supplied, refreshes it on the existing account so a
- *  re-application repairs a previously missed create (`refreshed: true`). */
+ *  exists, which is the state apply-time provisioning wanted — and refreshes
+ *  supplied public/private metadata on the existing account so a re-application
+ *  repairs a previously missed create (`refreshed: true`). */
 declare function createClerkUser(secretKey: string, input: ClerkUserInput, fetchImpl?: typeof fetch): Promise<ClerkResult>;
 
 /** A Clerk user as chapter's role layer sees it. `role` defaults to the lowest
- *  rung when `public_metadata` carries none; `publicMetadata` is returned raw so a
- *  site with a custom ladder can re-derive it. */
+ *  rung when `public_metadata` carries none. Raw public/private metadata is
+ *  returned only from this backend helper; `profile` and `applicationId` are the
+ *  normalized Chapter-owned private signals. */
 interface ClerkUserRecord {
     id: string;
     email?: string;
     role: string;
     publicMetadata: Record<string, unknown>;
+    privateMetadata: Record<string, unknown>;
+    profile: Record<string, unknown>;
+    applicationId?: string;
 }
 /** Look a Clerk user up by email. `null` when no such user — or when the lookup
  *  fails (a role gate treats an unresolvable user as absent, matching the site's
@@ -1143,8 +1188,9 @@ declare function clerkGetUser(secretKey: string, id: string, fetchImpl?: typeof
  *  until a short page. A page fetch that fails THROWS rather than returning a
  *  partial list, so the caller never mistakes a truncated roster for the whole. */
 declare function clerkListUsers(secretKey: string, fetchImpl?: typeof fetch): Promise<ClerkUserRecord[]>;
-/** Write a user's role: a MERGE-PATCH of only `{ role }` on `public_metadata`, so
- *  it leaves a separately-written `profile` untouched. Returns whether it stuck. */
+/** Write a user's role: a MERGE-PATCH of only `{ role }` on `public_metadata`.
+ *  The backend-only profile lives in `private_metadata`, so the two signals
+ *  cannot overwrite each other. Returns whether the role write stuck. */
 declare function clerkSetRole(secretKey: string, id: string, role: string, fetchImpl?: typeof fetch): Promise<boolean>;
 
 /** Which auth mode a secret is required for: `"client"` (publishable key only) or
@@ -1210,8 +1256,9 @@ interface IntegrationDescriptor {
  * the one public `setting` (the `pk_*` publishable key, served to the SPA), the
  * `secrets` auth mode `"full"` needs in the tenant vault, BOTH sync directions —
  * the inbound `$users` webhook mirror (`provider->odla`) and the outbound
- * role/profile write via `clerk_secret_key` (`odla->provider`, chapter's
- * `clerk.ts`) — and the `provision` split. Data only; it performs none of it.
+ * public role/private profile write via `clerk_secret_key` (`odla->provider`,
+ * chapter's `clerk.ts`) — and the `provision` split. Data only; it performs
+ * none of it.
  */
 declare const clerkIntegration: IntegrationDescriptor;
 
@@ -1470,4 +1517,4 @@ type ApplicationBookingPatch = {
  *  already there (never backward). */
 declare function applicationBookingUpdate(currentStatus: string, startAt: number, htmlLink?: string | null): ApplicationBookingPatch;
 
-export { type AccountModel, type AdminNotificationTrigger, type Applicant, type ApplicationBookingPatch, type ApplicationRecord, type ApplicationSummary, type Attr, type AttrType, type Chapter, type ChapterApplication, type ChapterAuth, type ChapterBrand, type ChapterConfig, type ChapterCopy, type ChapterCopyInput, type ChapterDb, type ChapterEmails, type ChapterIntegrationDescriptor, type ChapterIntegrationOptions, type ChapterMode, type ChapterNetwork, type ChapterNetworkTarget, type ChapterOperations, type ChapterPipeline, type ChapterPolicy, type ChapterPrices, type ChapterScheduling, type ChapterSends, type ClerkInviteInput, type ClerkResult, type ClerkUserInput, type ClerkUserRecord, type CompiledChapterBrandTokens, DEFAULT_CHAPTER_COPY, DEFAULT_SHARE_FIELDS, type DashboardMetricData, type DashboardMetricSeries, type DbOp, type DbRules, type DbSchema, type DeliveryDecision, type EmailGroup, type EmailTemplate, type EmailTemplateRow, type Entity, type ExistingMeeting, type GuardResult, type IntegrationDescriptor, type IntegrationProvision, type IntegrationSecret, type IntegrationSetting, type IntegrationSync, type JoinConfigGroup, type LiveEvent, type MailSender, type MeetingForReconcile, type MeetingRecord, type MeetingReschedulePatch, type MemberApplication, type MemberSession, type NewMeetingRow, type NotifyDeps, type NotifyInput, type NotifyResult, type PaymentsGroup, type ProjectionDeps, type ReconcileDecision, type ResolvedApplication, type ResolvedAuth, type ResolvedNetwork, type ResolvedNetworkTarget, type ResolvedOperations, type ResolvedPipeline, type ResolvedScheduling, type ResolvedSends, type RoleChangeContext, type Rule, SCHEDULING_DEFAULTS, type SchedulingErrors, type SecretMode, type SecretStore, type SessionUser, type SharedBusiness, type SharedPerson, type SharedRecord, type StripeEvent, type StripeResult, type SubmitResult, type WebhookEvent, applicantProfile, applicationBookingUpdate, applicationSummary, backfillCrm, bookingDecision, brandTokens, bucketSeries, buildGroupSeed, canApprove, canBook, canChangeRole, canTransition, canceledPatch, chapterBrandFromTokens, chapterDb, clampArray, clerkGetUser, clerkGetUserByEmail, clerkIntegration, clerkInviteRequest, clerkListUsers, clerkSetRole, clerkUserRequest, createChapterIntegration, createClerkInvitation, createClerkUser, dashboardMetricData, defaultCrm, defineChapter, emailGroupFrom, endForSlot, findApplicationRef, firstPaymentPatch, formatChapterCopy, getVaultSecret, hasDisclaimerAck, introIdempotencyKey, isAdminRole, isAlreadySent, isReconcilable, isSlotAvailable, isValidEmail, joinConfig, meetingCreateRow, meetingRescheduleUpdate, memberApplication, memberSession, networkSourceTag, normalizeSharedRecord, normalizeWebhookEvent, paymentsReady, personInputFromApp, planDelivery, projectApplicant, projectSharedRecord, reconcileMeetings, refundedPatch, render, renderSummary, renderTemplateBody, renewalPatch, resolveApplication, resolveAuth, resolveChapterCopy, resolvePipeline, resolveScheduling, roleFromClaim, sendTemplated, sharedPersonInput, sharedRecordFromCrm, slotWindow, stageIndex, stripeCall, stripeForm, subAnnualCents, submitApplication, subscriptionIdempotencyKey, syncApplicationToCrm, validateScheduling, verifyStripeSignature, webhookMutationId };
+export { type AccountModel, type AdminNotificationTrigger, type Applicant, type ApplicationBookingPatch, type ApplicationRecord, type ApplicationSummary, type Attr, type AttrType, type Chapter, type ChapterApplication, type ChapterAuth, type ChapterBrand, type ChapterConfig, type ChapterCopy, type ChapterCopyInput, type ChapterDb, type ChapterEmails, type ChapterIntegrationDescriptor, type ChapterIntegrationOptions, type ChapterMode, type ChapterNetwork, type ChapterNetworkTarget, type ChapterOperations, type ChapterPipeline, type ChapterPolicy, type ChapterPrices, type ChapterRunbookHints, type ChapterScheduling, type ChapterSends, type ClerkInviteInput, type ClerkMetadataInput, type ClerkResult, type ClerkUserInput, type ClerkUserRecord, type CompiledChapterBrandTokens, DEFAULT_CHAPTER_COPY, DEFAULT_SHARE_FIELDS, type DashboardMetricData, type DashboardMetricSeries, type DbOp, type DbRules, type DbSchema, type DeliveryDecision, type EmailGroup, type EmailTemplate, type EmailTemplateRow, type Entity, type ExistingMeeting, type GuardResult, type IntegrationDescriptor, type IntegrationProvision, type IntegrationSecret, type IntegrationSetting, type IntegrationSync, type JoinConfigGroup, type LiveEvent, type MailSender, type MeetingForReconcile, type MeetingRecord, type MeetingReschedulePatch, type MemberApplication, type MemberSession, type NewMeetingRow, type NotifyDeps, type NotifyInput, type NotifyResult, type PaymentsGroup, type ProjectionDeps, type ReconcileDecision, type ResolvedApplication, type ResolvedAuth, type ResolvedNetwork, type ResolvedNetworkTarget, type ResolvedOperations, type ResolvedPipeline, type ResolvedScheduling, type ResolvedSends, type RoleChangeContext, type Rule, SCHEDULING_DEFAULTS, type SchedulingErrors, type SecretMode, type SecretStore, type SessionUser, type SharedBusiness, type SharedPerson, type SharedRecord, type StripeEvent, type StripeResult, type SubmitResult, type WebhookEvent, applicantProfile, applicationBookingUpdate, applicationSummary, backfillCrm, bookingDecision, brandTokens, bucketSeries, buildGroupSeed, canApprove, canBook, canChangeRole, canTransition, canceledPatch, chapterBrandFromTokens, chapterDb, clampArray, clerkGetUser, clerkGetUserByEmail, clerkIntegration, clerkInviteRequest, clerkListUsers, clerkSetRole, clerkUserRequest, createChapterIntegration, createClerkInvitation, createClerkUser, dashboardMetricData, defaultCrm, defineChapter, emailGroupFrom, endForSlot, findApplicationRef, firstPaymentPatch, formatChapterCopy, getVaultSecret, hasDisclaimerAck, introIdempotencyKey, isAdminRole, isAlreadySent, isReconcilable, isSlotAvailable, isValidEmail, joinConfig, meetingCreateRow, meetingRescheduleUpdate, memberApplication, memberSession, networkSourceTag, normalizeSharedRecord, normalizeWebhookEvent, paymentsReady, personInputFromApp, planDelivery, projectApplicant, projectSharedRecord, reconcileMeetings, refundedPatch, render, renderSummary, renderTemplateBody, renewalPatch, resolveApplication, resolveAuth, resolveChapterCopy, resolvePipeline, resolveScheduling, roleFromClaim, sendTemplated, sharedPersonInput, sharedRecordFromCrm, slotWindow, stageIndex, stripeCall, stripeForm, subAnnualCents, submitApplication, subscriptionIdempotencyKey, syncApplicationToCrm, updateClerkUserMetadata, updateClerkUserMetadataByEmail, validateScheduling, verifyStripeSignature, webhookMutationId };

package/dist/index.js

@@ -44,6 +44,10 @@ var applications = {
     meetingAt: attr("number", { indexed: true, optional: true }),
     meetingLink: attr("string", { optional: true }),
     clerkUserId: attr("string", { indexed: true, optional: true }),
+    // One-time/effect-repair marker. Absent means /api/me should copy the
+    // allowlisted application snapshot into Clerk private_metadata and remove
+    // the former public_metadata copy.
+    clerkPrivateMetadataSyncedAt: attr("number", { optional: true }),
     phone: attr("string", { optional: true }),
     state: attr("string", { optional: true }),
     groupId: attr("string", { indexed: true, optional: true }),
@@ -687,7 +691,8 @@ var DEFAULT_JOIN_COPY = {
     pending: "Confirming your payment\u2026",
     processing: "Processing\u2026",
     payAndContinue: "Pay and continue",
-    incomplete: "The payment did not complete. Please try again."
+    incomplete: "The payment did not complete. Please try again.",
+    consent: "I have read and agree to the pricing and refund policy above."
   },
   done: {
     label: "You're booked",
@@ -949,6 +954,16 @@ function createChapterIntegration(chapter, options = {}) {
   if (group) {
     seeds.push({ id: "group", ns: "groups", key: { attr: "id", value: chapter.id }, attrs: { ...group, createdAt: now } });
   }
+  const isLeader = (chapter.config.network?.targets?.length ?? 0) > 0;
+  const runbooks = isLeader ? {
+    role: "leader",
+    slugs: ["chapter-leader", "chapter-network", "crm"],
+    guidance: `${chapter.name} is a LEADER hub: it holds the CRM and shares records with its chapters. Read it with \`odla-ai runbook get chapter-leader\`.`
+  } : {
+    role: "follower",
+    slugs: ["chapter-follower", "chapter-network"],
+    guidance: `${chapter.name} is a FOLLOWER site: it receives people and records from a leader hub. Read it with \`odla-ai runbook get chapter-follower\`.`
+  };
   return {
     id: "chapter",
     title: `Chapter: ${chapter.name}`,
@@ -959,7 +974,8 @@ function createChapterIntegration(chapter, options = {}) {
     },
     rules: { ...crmDesc.rules, ...chapter.rules },
     seeds,
-    probes: [...crmDesc.probes ?? []]
+    probes: [...crmDesc.probes ?? []],
+    runbooks
   };
 }
 
@@ -1346,7 +1362,7 @@ function billingColumns(app) {
 async function syncApplicationToCrm(deps, opts) {
   const emailKey = str(opts.app.email).toLowerCase();
   if (!emailKey) return null;
-  const crmDeps = { crm: deps.crm, db: deps.db, now: deps.now, newId: deps.newId };
+  const recordDeps = { crm: deps.crm, db: deps.db, now: deps.now, newId: deps.newId };
   const input = personInputFromApp(deps.chapter, opts.app);
   const { crm_record } = await deps.db.query({
     crm_record: { $: { where: { type: "person", primaryEmail: emailKey }, limit: 1 } }
@@ -1356,16 +1372,16 @@ async function syncApplicationToCrm(deps, opts) {
   let recordId;
   if (existing && typeof existing.id === "string") {
     recordId = existing.id;
-    await updateRecord2(crmDeps, { id: recordId, input });
+    await updateRecord2(recordDeps, { id: recordId, input });
   } else {
-    const created = await createRecord2(crmDeps, { type: "person", input, ...stage ? { stage } : {} });
+    const created = await createRecord2(recordDeps, { type: "person", input, ...stage ? { stage } : {} });
     recordId = created.id;
   }
   if (existing && stage && existing.stage !== stage) {
-    await setStage(crmDeps, { id: recordId, to: stage, authorId: "system", mutationId: `crm:stage:${recordId}:${stage}` }).catch(() => void 0);
+    await setStage(recordDeps, { id: recordId, to: stage, authorId: "system", mutationId: `crm:stage:${recordId}:${stage}` }).catch(() => void 0);
   }
   await deps.db.transact([{ t: "update", ns: "crm_record", id: recordId, attrs: billingColumns(opts.app) }]);
-  await linkIdentity(crmDeps, { recordId, email: emailKey, mutationId: `crm:link:${recordId}:${emailKey}` }).catch(() => void 0);
+  await linkIdentity(recordDeps, { recordId, email: emailKey, mutationId: `crm:link:${recordId}:${emailKey}` }).catch(() => void 0);
   return recordId;
 }
 async function backfillCrm(deps) {
@@ -1490,23 +1506,30 @@ function clerkUserRequest(input) {
       skip_password_requirement: true,
       ...input.firstName ? { first_name: input.firstName } : {},
       ...input.lastName ? { last_name: input.lastName } : {},
-      ...input.publicMetadata ? { public_metadata: input.publicMetadata } : {}
+      ...input.publicMetadata !== void 0 ? { public_metadata: input.publicMetadata } : {},
+      ...input.privateMetadata !== void 0 ? { private_metadata: input.privateMetadata } : {}
     }
   };
 }
-async function refreshUserMetadata(secretKey, email, publicMetadata, fetchImpl) {
+async function updateClerkUserMetadata(secretKey, userId, input, fetchImpl = fetch) {
+  const res = await fetchImpl(`https://api.clerk.com/v1/users/${encodeURIComponent(userId)}/metadata`, {
+    method: "PATCH",
+    headers: { authorization: `Bearer ${secretKey}`, "content-type": "application/json" },
+    body: JSON.stringify({
+      ...input.publicMetadata !== void 0 ? { public_metadata: input.publicMetadata } : {},
+      ...input.privateMetadata !== void 0 ? { private_metadata: input.privateMetadata } : {}
+    })
+  });
+  return res.ok;
+}
+async function updateClerkUserMetadataByEmail(secretKey, email, input, fetchImpl = fetch) {
   const auth = { authorization: `Bearer ${secretKey}` };
   const found = await fetchImpl(`https://api.clerk.com/v1/users?email_address=${encodeURIComponent(email)}&limit=1`, { headers: auth });
   if (!found.ok) return false;
   const users = await found.json().catch(() => null);
   const id2 = Array.isArray(users) && typeof users[0]?.id === "string" ? users[0].id : void 0;
   if (!id2) return false;
-  const patched = await fetchImpl(`https://api.clerk.com/v1/users/${id2}/metadata`, {
-    method: "PATCH",
-    headers: { ...auth, "content-type": "application/json" },
-    body: JSON.stringify({ public_metadata: publicMetadata })
-  });
-  return patched.ok;
+  return updateClerkUserMetadata(secretKey, id2, input, fetchImpl);
 }
 async function createClerkUser(secretKey, input, fetchImpl = fetch) {
   const { path, body } = clerkUserRequest(input);
@@ -1517,8 +1540,15 @@ async function createClerkUser(secretKey, input, fetchImpl = fetch) {
   });
   if (res.ok) return { ok: true, status: res.status };
   const healed = heal(res.status);
-  if (!healed.existed || !input.publicMetadata) return healed;
-  const refreshed = await refreshUserMetadata(secretKey, input.email, input.publicMetadata, fetchImpl).catch(() => false);
+  const repair = input.repairMetadata ?? {
+    ...input.publicMetadata !== void 0 ? { publicMetadata: input.publicMetadata } : {},
+    ...input.privateMetadata !== void 0 ? { privateMetadata: input.privateMetadata } : {}
+  };
+  if (!healed.existed || repair.publicMetadata === void 0 && repair.privateMetadata === void 0) return healed;
+  const refreshed = await updateClerkUserMetadataByEmail(secretKey, input.email, {
+    ...repair.publicMetadata !== void 0 ? { publicMetadata: repair.publicMetadata } : {},
+    ...repair.privateMetadata !== void 0 ? { privateMetadata: repair.privateMetadata } : {}
+  }, fetchImpl).catch(() => false);
   return { ...healed, refreshed };
 }
 
@@ -1529,9 +1559,21 @@ var PAGE = 100;
 function toRecord(u) {
   if (typeof u.id !== "string") return null;
   const pm = u.public_metadata ?? {};
+  const privateMetadata = u.private_metadata ?? {};
+  const rawProfile = privateMetadata.profile;
+  const profile = rawProfile && typeof rawProfile === "object" && !Array.isArray(rawProfile) ? rawProfile : {};
+  const applicationId = typeof privateMetadata.applicationId === "string" ? privateMetadata.applicationId : void 0;
   const role = typeof pm.role === "string" && pm.role ? pm.role : DEFAULT_ROLE;
   const email = u.email_addresses?.[0]?.email_address;
-  return { id: u.id, email: typeof email === "string" ? email : void 0, role, publicMetadata: pm };
+  return {
+    id: u.id,
+    email: typeof email === "string" ? email : void 0,
+    role,
+    publicMetadata: pm,
+    privateMetadata,
+    profile,
+    ...applicationId ? { applicationId } : {}
+  };
 }
 async function clerkGet(path, secretKey, fetchImpl) {
   const res = await fetchImpl(`${CLERK_API}${path}`, { headers: { authorization: `Bearer ${secretKey}` } });
@@ -1594,7 +1636,7 @@ var clerkIntegration = {
     },
     {
       key: "clerk_secret_key",
-      description: "Clerk backend key (sk_*) \u2014 powers the odla->Clerk writes (account create, role + profile via public_metadata) and lets odla-db resolve user email/name via the Clerk API.",
+      description: "Clerk backend key (sk_*) \u2014 powers account creation, the public role claim, and backend-only private profile signals; it also lets odla-db resolve user email/name via the Clerk API.",
       pattern: "sk_",
       mode: "full",
       vault: true
@@ -1614,8 +1656,13 @@ var clerkIntegration = {
       engine: "@odla-ai/chapter clerk.ts (Clerk Backend API via vault clerk_secret_key)",
       direction: "odla->provider",
       entity: "clerk user",
-      // Separate merge-PATCHes so a role write never clobbers a profile write.
-      fields: ["public_metadata.role", "public_metadata.profile"],
+      // Separate metadata fields so a public role write cannot expose or
+      // clobber backend-only account/profile signals.
+      fields: [
+        "public_metadata.role",
+        "private_metadata.applicationId",
+        "private_metadata.profile"
+      ],
       onDelete: "n/a (writes only)"
     }
   ],
@@ -1992,6 +2039,8 @@ export {
   submitApplication,
   subscriptionIdempotencyKey,
   syncApplicationToCrm,
+  updateClerkUserMetadata,
+  updateClerkUserMetadataByEmail,
   validateScheduling,
   verifyStripeSignature,
   webhookMutationId