@odla-ai/chapter 0.12.0 → 0.14.0

package/dist/index.d.cts

@@ -833,6 +833,100 @@ declare function clerkUserRequest(input: ClerkUserInput): {
  *  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. */
+interface ClerkUserRecord {
+    id: string;
+    email?: string;
+    role: string;
+    publicMetadata: Record<string, unknown>;
+}
+/** 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
+ *  own fallback). Role defaults to provisional when unset. */
+declare function clerkGetUserByEmail(secretKey: string, email: string, fetchImpl?: typeof fetch): Promise<ClerkUserRecord | null>;
+/** Fetch a Clerk user by id, for role-change gating. `null` when missing or on a
+ *  failed lookup. Role defaults to provisional when unset. */
+declare function clerkGetUser(secretKey: string, id: string, fetchImpl?: typeof fetch): Promise<ClerkUserRecord | null>;
+/** List ALL Clerk users with their roles, auto-paginating. A membership community
+ *  outgrows one page, and a fixed `limit=100` would silently drop members from the
+ *  admin roster with no error — so this pages (offset in steps of {@link PAGE})
+ *  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. */
+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
+ *  `"full"` (server-side profile/role reads + writes, needing the vault secret). */
+type SecretMode = "client" | "full";
+/** A configuration value the capability needs (e.g. the publishable key). */
+interface IntegrationSetting {
+    key: string;
+    description: string;
+    /** Safe to ship to the browser? (publishable keys are; secrets are not). */
+    public: boolean;
+    /** Expected value shape, e.g. a "pk_" prefix. */
+    pattern?: string;
+    /** Stored per environment (dev/prod)? */
+    perEnv: boolean;
+    /** Where the value is stored and read from. */
+    source: string;
+}
+/** A secret the capability needs, held in the tenant vault. */
+interface IntegrationSecret {
+    key: string;
+    description: string;
+    pattern?: string;
+    /** Auth mode that requires this secret ("full" pulls user profiles). */
+    mode: SecretMode;
+    /** Stored in the tenant vault (never in graph rows or wrangler vars)? */
+    vault: boolean;
+}
+/** One data-sync contract. A capability may declare several (e.g. an inbound
+ *  webhook mirror AND an outbound write), so {@link IntegrationDescriptor.syncs}
+ *  is a list. The mechanism is declared, not reimplemented here. */
+interface IntegrationSync {
+    engine: string;
+    direction: "provider->odla" | "odla->provider" | "bidirectional";
+    entity: string;
+    fields: string[];
+    webhook?: string;
+    onDelete?: string;
+}
+/** The provisioning split: human, CLI, and doctor-assertable steps. */
+interface IntegrationProvision {
+    /** Steps a human performs (out-of-band, e.g. in the Clerk dashboard). */
+    human: string[];
+    /** Steps the odla CLI automates. */
+    cli: string[];
+    /** Checks `odla doctor` should assert. */
+    doctor: string[];
+}
+/** Documentation-as-data for a provider capability, consumed by the odla CLI,
+ *  `odla doctor`, and the docs. */
+interface IntegrationDescriptor {
+    id: string;
+    title: string;
+    npm: string;
+    settings: IntegrationSetting[];
+    secrets: IntegrationSecret[];
+    /** Every data-sync contract the capability declares, each with its direction. */
+    syncs: IntegrationSync[];
+    provision: IntegrationProvision;
+}
+/**
+ * The concrete {@link IntegrationDescriptor} for the Clerk capability. Declares
+ * 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.
+ */
+declare const clerkIntegration: IntegrationDescriptor;
+
 /** An application row, as far as the session cares about it. */
 interface ApplicationRecord {
     id: string;
@@ -1071,4 +1165,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 ChapterDb, type ChapterEmails, type ChapterIntegrationDescriptor, type ChapterIntegrationOptions, type ChapterMode, type ChapterPipeline, type ChapterPolicy, type ChapterPrices, type ChapterScheduling, type ChapterSends, type ClerkInviteInput, type ClerkResult, type ClerkUserInput, type DbOp, type DbRules, type DbSchema, type DeliveryDecision, type EmailGroup, type EmailTemplate, type EmailTemplateRow, type Entity, type ExistingMeeting, type GuardResult, 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 ResolvedPipeline, type ResolvedScheduling, type ResolvedSends, type RoleChangeContext, type Rule, SCHEDULING_DEFAULTS, type SchedulingErrors, type SecretStore, type SessionUser, type SharedPerson, type StripeEvent, type SubmitResult, type WebhookEvent, applicantProfile, applicationBookingUpdate, applicationSummary, bookingDecision, brandTokens, buildGroupSeed, canApprove, canBook, canChangeRole, canTransition, canceledPatch, chapterDb, clampArray, clerkInviteRequest, clerkUserRequest, createChapterIntegration, createClerkInvitation, createClerkUser, defaultCrm, defineChapter, emailGroupFrom, endForSlot, findApplicationRef, firstPaymentPatch, getVaultSecret, hasDisclaimerAck, introIdempotencyKey, isAdminRole, isAlreadySent, isReconcilable, isSlotAvailable, isValidEmail, joinConfig, meetingCreateRow, meetingRescheduleUpdate, memberApplication, memberSession, normalizeWebhookEvent, paymentsReady, planDelivery, projectApplicant, projectSharedRecord, reconcileMeetings, refundedPatch, render, renderSummary, renderTemplateBody, renewalPatch, resolveApplication, resolveAuth, resolvePipeline, resolveScheduling, roleFromClaim, sendTemplated, sharedPersonInput, slotWindow, stageIndex, stripeForm, submitApplication, subscriptionIdempotencyKey, 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 ChapterDb, type ChapterEmails, type ChapterIntegrationDescriptor, type ChapterIntegrationOptions, type ChapterMode, type ChapterPipeline, type ChapterPolicy, type ChapterPrices, type ChapterScheduling, type ChapterSends, type ClerkInviteInput, type ClerkResult, type ClerkUserInput, type ClerkUserRecord, 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 ResolvedPipeline, type ResolvedScheduling, type ResolvedSends, type RoleChangeContext, type Rule, SCHEDULING_DEFAULTS, type SchedulingErrors, type SecretMode, type SecretStore, type SessionUser, type SharedPerson, type StripeEvent, type SubmitResult, type WebhookEvent, applicantProfile, applicationBookingUpdate, applicationSummary, bookingDecision, brandTokens, buildGroupSeed, canApprove, canBook, canChangeRole, canTransition, canceledPatch, chapterDb, clampArray, clerkGetUser, clerkGetUserByEmail, clerkIntegration, clerkInviteRequest, clerkListUsers, clerkSetRole, clerkUserRequest, createChapterIntegration, createClerkInvitation, createClerkUser, defaultCrm, defineChapter, emailGroupFrom, endForSlot, findApplicationRef, firstPaymentPatch, getVaultSecret, hasDisclaimerAck, introIdempotencyKey, isAdminRole, isAlreadySent, isReconcilable, isSlotAvailable, isValidEmail, joinConfig, meetingCreateRow, meetingRescheduleUpdate, memberApplication, memberSession, normalizeWebhookEvent, paymentsReady, planDelivery, projectApplicant, projectSharedRecord, reconcileMeetings, refundedPatch, render, renderSummary, renderTemplateBody, renewalPatch, resolveApplication, resolveAuth, resolvePipeline, resolveScheduling, roleFromClaim, sendTemplated, sharedPersonInput, slotWindow, stageIndex, stripeForm, submitApplication, subscriptionIdempotencyKey, validateScheduling, verifyStripeSignature, webhookMutationId };

package/dist/index.d.ts

@@ -833,6 +833,100 @@ declare function clerkUserRequest(input: ClerkUserInput): {
  *  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. */
+interface ClerkUserRecord {
+    id: string;
+    email?: string;
+    role: string;
+    publicMetadata: Record<string, unknown>;
+}
+/** 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
+ *  own fallback). Role defaults to provisional when unset. */
+declare function clerkGetUserByEmail(secretKey: string, email: string, fetchImpl?: typeof fetch): Promise<ClerkUserRecord | null>;
+/** Fetch a Clerk user by id, for role-change gating. `null` when missing or on a
+ *  failed lookup. Role defaults to provisional when unset. */
+declare function clerkGetUser(secretKey: string, id: string, fetchImpl?: typeof fetch): Promise<ClerkUserRecord | null>;
+/** List ALL Clerk users with their roles, auto-paginating. A membership community
+ *  outgrows one page, and a fixed `limit=100` would silently drop members from the
+ *  admin roster with no error — so this pages (offset in steps of {@link PAGE})
+ *  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. */
+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
+ *  `"full"` (server-side profile/role reads + writes, needing the vault secret). */
+type SecretMode = "client" | "full";
+/** A configuration value the capability needs (e.g. the publishable key). */
+interface IntegrationSetting {
+    key: string;
+    description: string;
+    /** Safe to ship to the browser? (publishable keys are; secrets are not). */
+    public: boolean;
+    /** Expected value shape, e.g. a "pk_" prefix. */
+    pattern?: string;
+    /** Stored per environment (dev/prod)? */
+    perEnv: boolean;
+    /** Where the value is stored and read from. */
+    source: string;
+}
+/** A secret the capability needs, held in the tenant vault. */
+interface IntegrationSecret {
+    key: string;
+    description: string;
+    pattern?: string;
+    /** Auth mode that requires this secret ("full" pulls user profiles). */
+    mode: SecretMode;
+    /** Stored in the tenant vault (never in graph rows or wrangler vars)? */
+    vault: boolean;
+}
+/** One data-sync contract. A capability may declare several (e.g. an inbound
+ *  webhook mirror AND an outbound write), so {@link IntegrationDescriptor.syncs}
+ *  is a list. The mechanism is declared, not reimplemented here. */
+interface IntegrationSync {
+    engine: string;
+    direction: "provider->odla" | "odla->provider" | "bidirectional";
+    entity: string;
+    fields: string[];
+    webhook?: string;
+    onDelete?: string;
+}
+/** The provisioning split: human, CLI, and doctor-assertable steps. */
+interface IntegrationProvision {
+    /** Steps a human performs (out-of-band, e.g. in the Clerk dashboard). */
+    human: string[];
+    /** Steps the odla CLI automates. */
+    cli: string[];
+    /** Checks `odla doctor` should assert. */
+    doctor: string[];
+}
+/** Documentation-as-data for a provider capability, consumed by the odla CLI,
+ *  `odla doctor`, and the docs. */
+interface IntegrationDescriptor {
+    id: string;
+    title: string;
+    npm: string;
+    settings: IntegrationSetting[];
+    secrets: IntegrationSecret[];
+    /** Every data-sync contract the capability declares, each with its direction. */
+    syncs: IntegrationSync[];
+    provision: IntegrationProvision;
+}
+/**
+ * The concrete {@link IntegrationDescriptor} for the Clerk capability. Declares
+ * 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.
+ */
+declare const clerkIntegration: IntegrationDescriptor;
+
 /** An application row, as far as the session cares about it. */
 interface ApplicationRecord {
     id: string;
@@ -1071,4 +1165,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 ChapterDb, type ChapterEmails, type ChapterIntegrationDescriptor, type ChapterIntegrationOptions, type ChapterMode, type ChapterPipeline, type ChapterPolicy, type ChapterPrices, type ChapterScheduling, type ChapterSends, type ClerkInviteInput, type ClerkResult, type ClerkUserInput, type DbOp, type DbRules, type DbSchema, type DeliveryDecision, type EmailGroup, type EmailTemplate, type EmailTemplateRow, type Entity, type ExistingMeeting, type GuardResult, 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 ResolvedPipeline, type ResolvedScheduling, type ResolvedSends, type RoleChangeContext, type Rule, SCHEDULING_DEFAULTS, type SchedulingErrors, type SecretStore, type SessionUser, type SharedPerson, type StripeEvent, type SubmitResult, type WebhookEvent, applicantProfile, applicationBookingUpdate, applicationSummary, bookingDecision, brandTokens, buildGroupSeed, canApprove, canBook, canChangeRole, canTransition, canceledPatch, chapterDb, clampArray, clerkInviteRequest, clerkUserRequest, createChapterIntegration, createClerkInvitation, createClerkUser, defaultCrm, defineChapter, emailGroupFrom, endForSlot, findApplicationRef, firstPaymentPatch, getVaultSecret, hasDisclaimerAck, introIdempotencyKey, isAdminRole, isAlreadySent, isReconcilable, isSlotAvailable, isValidEmail, joinConfig, meetingCreateRow, meetingRescheduleUpdate, memberApplication, memberSession, normalizeWebhookEvent, paymentsReady, planDelivery, projectApplicant, projectSharedRecord, reconcileMeetings, refundedPatch, render, renderSummary, renderTemplateBody, renewalPatch, resolveApplication, resolveAuth, resolvePipeline, resolveScheduling, roleFromClaim, sendTemplated, sharedPersonInput, slotWindow, stageIndex, stripeForm, submitApplication, subscriptionIdempotencyKey, 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 ChapterDb, type ChapterEmails, type ChapterIntegrationDescriptor, type ChapterIntegrationOptions, type ChapterMode, type ChapterPipeline, type ChapterPolicy, type ChapterPrices, type ChapterScheduling, type ChapterSends, type ClerkInviteInput, type ClerkResult, type ClerkUserInput, type ClerkUserRecord, 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 ResolvedPipeline, type ResolvedScheduling, type ResolvedSends, type RoleChangeContext, type Rule, SCHEDULING_DEFAULTS, type SchedulingErrors, type SecretMode, type SecretStore, type SessionUser, type SharedPerson, type StripeEvent, type SubmitResult, type WebhookEvent, applicantProfile, applicationBookingUpdate, applicationSummary, bookingDecision, brandTokens, buildGroupSeed, canApprove, canBook, canChangeRole, canTransition, canceledPatch, chapterDb, clampArray, clerkGetUser, clerkGetUserByEmail, clerkIntegration, clerkInviteRequest, clerkListUsers, clerkSetRole, clerkUserRequest, createChapterIntegration, createClerkInvitation, createClerkUser, defaultCrm, defineChapter, emailGroupFrom, endForSlot, findApplicationRef, firstPaymentPatch, getVaultSecret, hasDisclaimerAck, introIdempotencyKey, isAdminRole, isAlreadySent, isReconcilable, isSlotAvailable, isValidEmail, joinConfig, meetingCreateRow, meetingRescheduleUpdate, memberApplication, memberSession, normalizeWebhookEvent, paymentsReady, planDelivery, projectApplicant, projectSharedRecord, reconcileMeetings, refundedPatch, render, renderSummary, renderTemplateBody, renewalPatch, resolveApplication, resolveAuth, resolvePipeline, resolveScheduling, roleFromClaim, sendTemplated, sharedPersonInput, slotWindow, stageIndex, stripeForm, submitApplication, subscriptionIdempotencyKey, validateScheduling, verifyStripeSignature, webhookMutationId };

package/dist/index.js

@@ -883,6 +883,119 @@ async function createClerkUser(secretKey, input, fetchImpl = fetch) {
   return { ...healed, refreshed };
 }
 
+// src/clerk-roles.ts
+var CLERK_API = "https://api.clerk.com";
+var DEFAULT_ROLE = "provisional";
+var PAGE = 100;
+function toRecord(u) {
+  if (typeof u.id !== "string") return null;
+  const pm = u.public_metadata ?? {};
+  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 };
+}
+async function clerkGet(path, secretKey, fetchImpl) {
+  const res = await fetchImpl(`${CLERK_API}${path}`, { headers: { authorization: `Bearer ${secretKey}` } });
+  if (!res.ok) throw new Error(`clerk GET ${path} \u2192 ${res.status}`);
+  return res.json();
+}
+async function clerkGetUserByEmail(secretKey, email, fetchImpl = fetch) {
+  const data = await clerkGet(`/v1/users?email_address=${encodeURIComponent(email)}&limit=1`, secretKey, fetchImpl).catch(() => null);
+  const user = Array.isArray(data) ? data[0] : void 0;
+  return user ? toRecord(user) : null;
+}
+async function clerkGetUser(secretKey, id2, fetchImpl = fetch) {
+  const data = await clerkGet(`/v1/users/${encodeURIComponent(id2)}`, secretKey, fetchImpl).catch(() => null);
+  return data ? toRecord(data) : null;
+}
+async function clerkListUsers(secretKey, fetchImpl = fetch) {
+  const out = [];
+  for (let offset = 0; ; offset += PAGE) {
+    const data = await clerkGet(`/v1/users?limit=${PAGE}&offset=${offset}`, secretKey, fetchImpl);
+    const page = Array.isArray(data) ? data : [];
+    for (const u of page) {
+      const record = toRecord(u);
+      if (record) out.push(record);
+    }
+    if (page.length < PAGE) break;
+  }
+  return out;
+}
+async function clerkSetRole(secretKey, id2, role, fetchImpl = fetch) {
+  const res = await fetchImpl(`${CLERK_API}/v1/users/${encodeURIComponent(id2)}/metadata`, {
+    method: "PATCH",
+    headers: { authorization: `Bearer ${secretKey}`, "content-type": "application/json" },
+    body: JSON.stringify({ public_metadata: { role } })
+  });
+  return res.ok;
+}
+
+// src/clerk-integration.ts
+var clerkIntegration = {
+  id: "clerk",
+  title: "Clerk end-user auth",
+  npm: "@odla-ai/chapter",
+  settings: [
+    {
+      key: "publishableKey",
+      description: "Clerk publishable key (pk_*). Public by design; served to the SPA (loads clerk-js from Clerk's CDN via @odla-ai/auth-clerk).",
+      public: true,
+      pattern: "pk_",
+      perEnv: true,
+      source: "apps-registry auth[env].publishableKey (from odla.config.mjs auth.clerk.<env>)"
+    }
+  ],
+  secrets: [
+    {
+      key: "CLERK_WEBHOOK_SECRET",
+      description: "Svix signing secret for Clerk user webhooks \u2014 verifies $users sync events.",
+      pattern: "whsec_",
+      mode: "full",
+      vault: true
+    },
+    {
+      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.",
+      pattern: "sk_",
+      mode: "full",
+      vault: true
+    }
+  ],
+  syncs: [
+    {
+      engine: "@odla-ai/db $users (Clerk webhook -> tenant graph)",
+      direction: "provider->odla",
+      entity: "$users",
+      // Matches the webhook mapper: the mirror carries id + primary email + name + avatar.
+      fields: ["id", "email", "name", "imageUrl"],
+      webhook: "whsec_ (svix-signed)",
+      onDelete: "tombstone (never row-delete)"
+    },
+    {
+      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"],
+      onDelete: "n/a (writes only)"
+    }
+  ],
+  provision: {
+    human: [
+      "Run `npx clerk auth login` \u2014 the one interactive step; the agent then creates + configures the Clerk app with the Clerk CLI (no pk_ to hand-paste).",
+      'For auth mode "full": create the Clerk user-sync webhook and store its whsec_, plus the sk_ as clerk_secret_key, in the tenant vault (Studio, write-only).'
+    ],
+    cli: [
+      "Clerk CLI (`npx clerk apps create/link/config patch`) creates + configures the instance and pulls the pk_.",
+      "odla `provision` records it: setAuth(env, publishableKey) -> apps-registry (issuer/JWKS derived from the key)."
+    ],
+    doctor: [
+      "registry auth[env] present when the app mounts <SignIn>?",
+      'auth mode "full" => whsec_ and clerk_secret_key present in the tenant vault?'
+    ]
+  }
+};
+
 // src/session.ts
 function applicationSummary(app) {
   return {
@@ -1100,7 +1213,12 @@ export {
   canceledPatch,
   chapterDb,
   clampArray,
+  clerkGetUser,
+  clerkGetUserByEmail,
+  clerkIntegration,
   clerkInviteRequest,
+  clerkListUsers,
+  clerkSetRole,
   clerkUserRequest,
   createChapterIntegration,
   createClerkInvitation,