@12-apps/prisma 1.3.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/prisma",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Prisma host: the multi-file schema folder, the plugin migration seam, and the shared PrismaClient singleton with its audit / append-only extensions",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,7 +12,7 @@
     }
   },
   "scripts": {
-    "build": "node scripts/sync-lifecycle-schema.mjs && node scripts/sync-research-schema.mjs && node scripts/sync-shift-schema.mjs --check && node scripts/sync-jobs-schema.mjs --check && node scripts/sync-entitlements-schema.mjs --check && node scripts/sync-payments-schema.mjs --check && node scripts/sync-report-builder-schema.mjs --check && node scripts/sync-rbac-schema.mjs --check && node scripts/sync-prisma-plugins.mjs --check && prisma generate && tsc",
+    "build": "node scripts/sync-lifecycle-schema.mjs && node scripts/sync-research-schema.mjs && node scripts/sync-shift-schema.mjs --check && node scripts/sync-jobs-schema.mjs --check && node scripts/sync-entitlements-schema.mjs --check && node scripts/sync-payments-schema.mjs --check && node scripts/sync-report-builder-schema.mjs --check && node scripts/sync-rbac-schema.mjs --check && node scripts/sync-onboarding-schema.mjs --check && node scripts/sync-mcp-schema.mjs --check && node scripts/sync-prisma-plugins.mjs --check && prisma generate && tsc",
     "clean": "rm -rf dist node_modules coverage",
     "test": "node ../../scripts/vitest-with-teardown.mjs run",
     "test:watch": "vitest watch",
@@ -20,7 +20,7 @@
     "lint": "pnpm run lint:files .",
     "lint:fix": "bash -c 'eslint \"${@:-.}\" --max-warnings 0 --fix' _",
     "typecheck": "tsc --noEmit",
-    "prisma:generate": "node scripts/sync-lifecycle-schema.mjs && node scripts/sync-research-schema.mjs && node scripts/sync-shift-schema.mjs --check && node scripts/sync-jobs-schema.mjs --check && node scripts/sync-entitlements-schema.mjs --check && node scripts/sync-payments-schema.mjs --check && node scripts/sync-report-builder-schema.mjs --check && node scripts/sync-rbac-schema.mjs --check && node scripts/sync-prisma-plugins.mjs --check && prisma generate",
+    "prisma:generate": "node scripts/sync-lifecycle-schema.mjs && node scripts/sync-research-schema.mjs && node scripts/sync-shift-schema.mjs --check && node scripts/sync-jobs-schema.mjs --check && node scripts/sync-entitlements-schema.mjs --check && node scripts/sync-payments-schema.mjs --check && node scripts/sync-report-builder-schema.mjs --check && node scripts/sync-rbac-schema.mjs --check && node scripts/sync-onboarding-schema.mjs --check && node scripts/sync-mcp-schema.mjs --check && node scripts/sync-prisma-plugins.mjs --check && prisma generate",
     "prisma:migrate": "prisma migrate dev",
     "prisma:push": "prisma db push",
     "prisma:studio": "prisma studio",
@@ -39,7 +39,11 @@
     "prisma:sync-plugins": "node scripts/sync-prisma-plugins.mjs",
     "prisma:sync-plugins:check": "node scripts/sync-prisma-plugins.mjs --check",
     "prisma:sync-rbac": "node scripts/sync-rbac-schema.mjs",
-    "prisma:sync-rbac:check": "node scripts/sync-rbac-schema.mjs --check"
+    "prisma:sync-rbac:check": "node scripts/sync-rbac-schema.mjs --check",
+    "prisma:sync-onboarding": "node scripts/sync-onboarding-schema.mjs",
+    "prisma:sync-onboarding:check": "node scripts/sync-onboarding-schema.mjs --check",
+    "prisma:sync-mcp": "node scripts/sync-mcp-schema.mjs",
+    "prisma:sync-mcp:check": "node scripts/sync-mcp-schema.mjs --check"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.2.17",
@@ -53,9 +57,11 @@
     "@12-apps/entity-lifecycle": "^2.1.0",
     "@12-apps/eslint-config": "^1.20.0",
     "@12-apps/jobs": "^2.0.0",
+    "@12-apps/mcp": "^1.20.0",
+    "@12-apps/onboarding": "^1.20.0",
     "@12-apps/payments-backend": "^2.0.0",
     "@12-apps/product-research": "^2.0.0",
-    "@12-apps/rbac": "^1.19.0",
+    "@12-apps/rbac": "^1.20.0",
     "@12-apps/report-builder": "^3.0.0",
     "@12-apps/shift": "^2.0.0",
     "@12-apps/typescript-config": "^1.20.0",

package/prisma/migrations/20260812150000_add_mcp_oauth_tables/migration.sql

@@ -0,0 +1,152 @@
+-- @12-apps/mcp (12-23): the three tables behind an MCP surface's OAuth 2.1
+-- authorization server, owned by the package and copied into a host's migrations
+-- folder by its plugin-migration sync.
+--
+--   * oauth_clients        — a registered external host (a Claude.ai / ChatGPT
+--                            connector) from RFC 7591 dynamic client
+--                            registration or a static registration. NOT a
+--                            multi-tenant customer table — namespaced to avoid
+--                            that collision; no FK to users (clients are apps).
+--   * oauth_refresh_tokens — a rotating refresh token bound to a user email +
+--                            client, stored HASHED (SHA-256), rotated on use
+--                            with `rotated_from` lineage and a `revoked_at`
+--                            revoke path.
+--   * mcp_connections      — which AI host a user has connected, and how
+--                            recently it was active. Per-USER, because an MCP
+--                            bearer is auth-passthrough and not tenant-scoped.
+--
+-- Authorization codes are deliberately absent: they are STATELESS signed blobs,
+-- so there is no table to create and nothing to sweep.
+--
+-- The columns, defaults, indexes and CHECK are future-pay's
+-- `20260713120000_add_oauth_client_refresh`,
+-- `20260715180000_add_onboarding_state_mcp_connection` (the mcp_connections half
+-- — the onboarding half belongs to @12-apps/onboarding) and
+-- `20260720120000_add_mcp_connection_host` verbatim, minus the FK to `users`:
+-- this package cannot know the name of a host's user table, and a host that has
+-- one keeps its own constraint (future-pay's is ON DELETE CASCADE).
+--
+-- EVERY statement is guarded (`IF NOT EXISTS`, and a conrelid-scoped DO block for
+-- the CHECK, which has no IF NOT EXISTS form). That is what makes adoption by a
+-- host that ALREADY has these tables a no-op instead of a failed deploy — and
+-- what lets the PGlite provisioner replay it into an existing schema.
+--
+-- Guarding every STATEMENT is not the same as guarding every COLUMN, though, and
+-- the difference bites exactly the host this file is written for: `CREATE TABLE IF
+-- NOT EXISTS` skips the whole table, columns included, so a host holding an OLDER
+-- shape of one of these tables silently keeps it. Each table below is therefore
+-- followed by a guarded `ADD COLUMN` for every column that reached future-pay in a
+-- LATER migration than its own CREATE. The full audit: `oauth_refresh_tokens
+-- .user_sub` (`20260713150000_add_oauth_refresh_user_sub`) and `mcp_connections
+-- .host` (`20260720120000_add_mcp_connection_host`). `oauth_clients` needs none —
+-- it arrived complete, CHECK and all, and was never altered afterwards. A column
+-- added to this file later needs the same treatment.
+
+-- Registered OAuth client (host app). Array columns are Postgres TEXT[]:
+-- redirect_uris is the exact-match allowlist for open-redirect prevention;
+-- grant_types / scopes are the DCR metadata.
+CREATE TABLE IF NOT EXISTS "oauth_clients" (
+    "id" TEXT NOT NULL,
+    "client_id" TEXT NOT NULL,
+    "client_secret_hash" TEXT,
+    "redirect_uris" TEXT[] NOT NULL DEFAULT ARRAY[]::TEXT[],
+    "client_name" TEXT,
+    "token_endpoint_auth_method" TEXT NOT NULL DEFAULT 'none',
+    "grant_types" TEXT[] NOT NULL DEFAULT ARRAY[]::TEXT[],
+    "scopes" TEXT[] NOT NULL DEFAULT ARRAY[]::TEXT[],
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "oauth_clients_pkey" PRIMARY KEY ("id")
+);
+
+-- Public identifier a token/authorize request presents; unique across clients.
+CREATE UNIQUE INDEX IF NOT EXISTS "oauth_clients_client_id_key"
+  ON "oauth_clients"("client_id");
+
+-- token_endpoint_auth_method domain guard (String+CHECK house style). Scoped to
+-- conrelid because constraint names are unique only per table.
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint
+    WHERE conname = 'oauth_clients_token_endpoint_auth_method_valid'
+      AND conrelid = 'oauth_clients'::regclass
+  ) THEN
+    ALTER TABLE "oauth_clients"
+      ADD CONSTRAINT "oauth_clients_token_endpoint_auth_method_valid"
+      CHECK ("token_endpoint_auth_method" IN ('none', 'client_secret_basic'));
+  END IF;
+END $$;
+
+-- Rotating refresh token. token_hash is the SHA-256 of the opaque token (never
+-- plaintext); user_email is the bound identity; user_sub is the original OAuth
+-- subject, kept stable across every rotation; client_id is a by-value link to
+-- oauth_clients.client_id; rotated_from carries the prior token's hash for
+-- rotation lineage / replay detection; revoked_at is the explicit revoke path.
+CREATE TABLE IF NOT EXISTS "oauth_refresh_tokens" (
+    "id" TEXT NOT NULL,
+    "token_hash" TEXT NOT NULL,
+    "user_email" TEXT NOT NULL,
+    "user_sub" TEXT NOT NULL,
+    "client_id" TEXT NOT NULL,
+    "scopes" TEXT[] NOT NULL DEFAULT ARRAY[]::TEXT[],
+    "expires_at" TIMESTAMP(3) NOT NULL,
+    "rotated_from" TEXT,
+    "revoked_at" TIMESTAMP(3),
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "oauth_refresh_tokens_pkey" PRIMARY KEY ("id")
+);
+
+-- Lookup-on-presentation: hash the incoming token, find its row. Unique so a
+-- duplicate insert is a DB-level error rather than a silent second live token.
+CREATE UNIQUE INDEX IF NOT EXISTS "oauth_refresh_tokens_token_hash_key"
+  ON "oauth_refresh_tokens"("token_hash");
+
+-- Per-user/per-client enumeration + bulk revoke (the lineage walk's input, and
+-- the disconnect path).
+CREATE INDEX IF NOT EXISTS "oauth_refresh_tokens_user_email_client_id_idx"
+  ON "oauth_refresh_tokens"("user_email", "client_id");
+
+-- `CREATE TABLE IF NOT EXISTS` skips the WHOLE table, so a host that already holds
+-- `oauth_refresh_tokens` in an OLDER SHAPE gets none of the columns declared above
+-- — statement-level guarding is not the same as column-level guarding. That is
+-- precisely how future-pay's own history ran: `user_sub` arrived in a SECOND
+-- migration (FUT-105, `20260713150000_add_oauth_refresh_user_sub`), so a host
+-- frozen before it would adopt this file, skip the CREATE, never get the column,
+-- and then fail on every refresh the package serves. Mirror future-pay's pair
+-- verbatim — guarded add with a backfill default to satisfy NOT NULL, then drop
+-- the default so the column matches the Prisma schema (`String`, no default).
+-- Both statements are no-ops on a fresh host and on a replay.
+ALTER TABLE "oauth_refresh_tokens"
+  ADD COLUMN IF NOT EXISTS "user_sub" TEXT NOT NULL DEFAULT '';
+ALTER TABLE "oauth_refresh_tokens"
+  ALTER COLUMN "user_sub" DROP DEFAULT;
+
+-- A user's live AI connections. `host` is nullable: a connection can exist before
+-- any provider attribution is derivable (a CLI callback with no public domain).
+CREATE TABLE IF NOT EXISTS "mcp_connections" (
+    "id" TEXT NOT NULL,
+    "user_id" TEXT NOT NULL,
+    "oauth_client_id" TEXT NOT NULL,
+    "client_name" TEXT,
+    "host" TEXT,
+    "connected_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "last_active_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "revoked_at" TIMESTAMP(3),
+
+    CONSTRAINT "mcp_connections_pkey" PRIMARY KEY ("id")
+);
+
+-- One connection row per (user, OAuth client) — the upsert key for liveness.
+CREATE UNIQUE INDEX IF NOT EXISTS "mcp_connections_user_id_oauth_client_id_key"
+  ON "mcp_connections"("user_id", "oauth_client_id");
+CREATE INDEX IF NOT EXISTS "mcp_connections_user_id_idx" ON "mcp_connections"("user_id");
+CREATE INDEX IF NOT EXISTS "mcp_connections_last_active_at_idx"
+  ON "mcp_connections"("last_active_at");
+
+-- A host adopting this migration where `mcp_connections` predates the `host`
+-- column (future-pay added it in a later migration) gets it here; a fresh host
+-- already has it from the CREATE above, so the guard makes both cases a no-op.
+ALTER TABLE "mcp_connections" ADD COLUMN IF NOT EXISTS "host" TEXT;

package/prisma/migrations/20260812150000_add_onboarding_states/migration.sql

@@ -0,0 +1,61 @@
+-- @12-apps/onboarding (12-23): the guided-onboarding progress table, owned by
+-- the package and copied into a host's migrations folder by its
+-- plugin-migration sync.
+--
+-- The columns, defaults, indexes and the status CHECK are future-pay's
+-- `20260715180000_add_onboarding_state_mcp_connection` verbatim, minus two
+-- things that are the HOST's vocabulary rather than the package's:
+--
+--   * the FKs to `users` / `clients` — this package cannot know the name of a
+--     host's user or tenant table. A host that has them keeps its own
+--     constraints (future-pay's are ON DELETE CASCADE) and they stay
+--     compatible with everything the package writes;
+--   * the `mcp_connections` half of that migration, which belongs to
+--     @12-apps/mcp and ships in ITS folder.
+--
+-- EVERY statement is guarded (`IF NOT EXISTS`, and a conrelid-scoped DO block
+-- for the CHECK, which has no IF NOT EXISTS form). That is what makes adoption
+-- by a host that ALREADY has the table a no-op instead of a failed deploy —
+-- future-pay applies this and nothing changes, no `prisma migrate resolve`
+-- dance required. It is also what lets the PGlite provisioner replay it into an
+-- existing schema, which is how the harness and the integration suites run.
+
+CREATE TABLE IF NOT EXISTS "onboarding_states" (
+    "id" TEXT NOT NULL,
+    "user_id" TEXT NOT NULL,
+    "client_id" TEXT NOT NULL,
+    "feature_key" TEXT NOT NULL,
+    "status" TEXT NOT NULL DEFAULT 'not_started',
+    "step" TEXT,
+    "data" JSONB NOT NULL DEFAULT '{}',
+    "started_at" TIMESTAMP(3),
+    "completed_at" TIMESTAMP(3),
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "onboarding_states_pkey" PRIMARY KEY ("id")
+);
+
+-- One progress row per (user, tenant, feature) — the upsert key.
+CREATE UNIQUE INDEX IF NOT EXISTS "onboarding_states_user_id_client_id_feature_key_key"
+  ON "onboarding_states"("user_id", "client_id", "feature_key");
+
+-- The "who is mid-integration" reach-out query (per tenant, per feature).
+CREATE INDEX IF NOT EXISTS "onboarding_states_client_id_feature_key_status_idx"
+  ON "onboarding_states"("client_id", "feature_key", "status");
+
+-- DB-enforced status domain: the package's own `OnboardingStatus` union, so the
+-- closed set is the package's contract rather than a host's preference. Scoped
+-- to conrelid because constraint names are unique only per table.
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint
+    WHERE conname = 'onboarding_states_status_valid'
+      AND conrelid = 'onboarding_states'::regclass
+  ) THEN
+    ALTER TABLE "onboarding_states"
+      ADD CONSTRAINT "onboarding_states_status_valid"
+      CHECK ("status" IN ('not_started', 'in_progress', 'completed', 'dismissed'));
+  END IF;
+END $$;

package/prisma/plugin-migrations.json

@@ -26,6 +26,8 @@
     "20260810180000_add_report_working_copy",
     "20260812120000_add_rbac_tables",
     "20260812120000_add_retention_watermarks",
+    "20260812150000_add_mcp_oauth_tables",
+    "20260812150000_add_onboarding_states",
     "20260813120000_add_entity_lifecycle_tables"
   ]
 }

package/prisma/schema/mcp.prisma

@@ -0,0 +1,108 @@
+// ---------------------------------------------------------------------------
+// @12-apps/mcp — CANONICAL Prisma model partial (plug-and-play).
+//
+// The three tables behind an MCP surface's authorization server. A host project
+// does NOT copy these models into its main schema by hand: it uses Prisma's
+// multi-file schema folder and SYNCS this file into it with this package's
+// `prisma:sync` script (a byte-for-byte COPY — never a symlink; see
+// scripts/sync-mcp-schema.mjs for why). The migration ships alongside, in
+// prisma/migrations/, and is copied into the host's migrations folder by the
+// host's plugin-migration sync.
+//
+// Host-agnostic by design (the entity-lifecycle / rbac doctrine): `user_id` is a
+// by-value scalar with NO relation, because this package cannot know the name of
+// the host's user model. The host's own migration may add the FK (future-pay's
+// is ON DELETE CASCADE). Note there is deliberately no `oauth_codes` table:
+// authorization codes are STATELESS signed blobs, so there is nothing to store
+// and nothing to sweep.
+// ---------------------------------------------------------------------------
+
+// A registered external OAuth host — a Claude.ai / ChatGPT connector produced by
+// RFC 7591 dynamic client registration, or a static registration an operator
+// created out of band. This is the OAuth *client application*, NOT a
+// multi-tenant customer: namespaced `OAuth*` to avoid that collision, and with
+// no relation to any user (clients are apps, not people).
+//
+// `clientId` is the public, unique identifier; `clientSecretHash` is null for
+// public PKCE clients (which authenticate via `token_endpoint_auth_method =
+// "none"`) and holds a SHA-256 hash for confidential ones — the plaintext secret
+// is returned exactly once at registration and never persisted. `redirectUris`
+// is the EXACT-MATCH allowlist the authorization endpoint validates against for
+// open-redirect prevention. Array columns are Postgres `TEXT[]`.
+model OAuthClient {
+  id                      String   @id @default(uuid())
+  clientId                String   @unique @map("client_id")
+  clientSecretHash        String?  @map("client_secret_hash")
+  redirectUris            String[] @map("redirect_uris")
+  clientName              String?  @map("client_name")
+  // "none" (public PKCE) | "client_secret_basic" (confidential). String + CHECK
+  // (the house convention), not a Prisma enum; validated at the register route.
+  tokenEndpointAuthMethod String   @default("none") @map("token_endpoint_auth_method")
+  grantTypes              String[] @map("grant_types")
+  scopes                  String[]
+  createdAt               DateTime @default(now()) @map("created_at")
+  updatedAt               DateTime @updatedAt @map("updated_at")
+
+  @@map("oauth_clients")
+}
+
+// A rotating OAuth refresh token bound to a signed-in user + a registered
+// client. Stored HASHED (`tokenHash` = SHA-256 of the opaque token, never
+// plaintext) and rotated on every use. Identity is the user's EMAIL: the AS binds
+// to email and a host's guards resolve their user row by it, so this is a scalar
+// rather than a FK and the token store stays decoupled from the user table.
+// `userSub` is the original OAuth subject, carried so a rotated successor mints
+// an access token with the SAME stable `sub` as the initial one (RFC 6749 §5.1 /
+// OIDC §2) — without it a refreshed token's `sub` would fall back to the email
+// and diverge, breaking identity correlation after the first refresh.
+// `clientId` is a by-value link to `OAuthClient.clientId`. Rotation lineage:
+// `rotatedFrom` holds the prior token's hash so reuse of a rotated token is
+// detectable and revokes the whole lineage; `revokedAt` is the explicit revoke
+// path.
+model OAuthRefreshToken {
+  id          String    @id @default(uuid())
+  tokenHash   String    @unique @map("token_hash")
+  userEmail   String    @map("user_email")
+  userSub     String    @map("user_sub")
+  clientId    String    @map("client_id")
+  scopes      String[]
+  expiresAt   DateTime  @map("expires_at")
+  rotatedFrom String?   @map("rotated_from")
+  revokedAt   DateTime? @map("revoked_at")
+  createdAt   DateTime  @default(now()) @map("created_at")
+
+  // `tokenHash` is already indexed by its `@unique` constraint — the
+  // lookup-on-presentation path — so no separate `@@index([tokenHash])` is added
+  // (it would be redundant). The composite index serves per-user/per-client
+  // enumeration and bulk revoke.
+  @@index([userEmail, clientId])
+  @@map("oauth_refresh_tokens")
+}
+
+// A live AI-assistant (MCP) connection a user has authorized. MCP auth is
+// auth-passthrough / per-user (a token is not tenant-scoped), so this is keyed by
+// the host's user id + the registered OAuth client — NOT by tenant. `clientName`
+// snapshots the client's display name for the UI (a registration can change it).
+// `lastActiveAt` is bumped (throttled, best-effort) on each token grant so a
+// config page can show "connected via Claude · active 2 min ago" and an operator
+// panel can tell an active connection from a stalled one. `host` is the AI
+// provider the connection is attributed to (claude / chatgpt / codex), derived
+// from the client's redirect URIs at grant time and confirmable by a self-report
+// tool; null for a pre-attribution connection. `revokedAt` is the explicit
+// disconnect path — and ending the connection is only half of a disconnect, since
+// a host holding a live refresh token would simply rotate its way back in.
+model McpConnection {
+  id            String    @id @default(uuid())
+  userId        String    @map("user_id")
+  oauthClientId String    @map("oauth_client_id")
+  clientName    String?   @map("client_name")
+  host          String?   @map("host")
+  connectedAt   DateTime  @default(now()) @map("connected_at")
+  lastActiveAt  DateTime  @default(now()) @map("last_active_at")
+  revokedAt     DateTime? @map("revoked_at")
+
+  @@unique([userId, oauthClientId])
+  @@index([userId])
+  @@index([lastActiveAt])
+  @@map("mcp_connections")
+}

package/prisma/schema/onboarding.prisma

@@ -0,0 +1,46 @@
+// ---------------------------------------------------------------------------
+// @12-apps/onboarding — CANONICAL Prisma model partial (plug-and-play).
+//
+// This file is the single source of truth for the guided-onboarding progress
+// table. A host project does NOT copy the model into its main schema by hand:
+// it uses Prisma's multi-file schema folder and SYNCS this file into it with
+// this package's `prisma:sync` script (a byte-for-byte COPY — never a symlink;
+// see scripts/sync-onboarding-schema.mjs for why). The migration ships
+// alongside, in prisma/migrations/, and is copied into the host's migrations
+// folder by the host's plugin-migration sync.
+//
+// Host-agnostic by design (the entity-lifecycle / report-builder doctrine):
+//   - `user_id` and `client_id` are by-value scalars, NOT relations — this
+//     package cannot know the name of the host's user or tenant model. The
+//     host's own migration may add the FK constraints (future-pay has both,
+//     ON DELETE CASCADE).
+//   - `status` is a String with a DB CHECK rather than a Prisma enum (the
+//     house String+CHECK pattern); the four values are the package's own
+//     `OnboardingStatus` union, so the closed set IS the package's contract.
+// ---------------------------------------------------------------------------
+
+// Reusable guided-onboarding progress for ANY feature, one row per
+// (user, tenant, featureKey). `featureKey` namespaces the flow
+// ("ai_integration" | "payments" | ...) so a single table backs every guided
+// setup. `step` is the resume point (which step the user stopped on); `data` is
+// an opaque per-feature JSON payload (e.g. the selected AI host) so features
+// evolve their own state with no schema change. Scoped to the host's DB user id
+// and the tenant. Indexed on (client, feature, status) for the "who is
+// mid-integration" reach-out query.
+model OnboardingState {
+  id          String    @id @default(uuid())
+  userId      String    @map("user_id")
+  clientId    String    @map("client_id")
+  featureKey  String    @map("feature_key")
+  status      String    @default("not_started")
+  step        String?
+  data        Json      @default("{}")
+  startedAt   DateTime? @map("started_at")
+  completedAt DateTime? @map("completed_at")
+  createdAt   DateTime  @default(now()) @map("created_at")
+  updatedAt   DateTime  @updatedAt @map("updated_at")
+
+  @@unique([userId, clientId, featureKey])
+  @@index([clientId, featureKey, status])
+  @@map("onboarding_states")
+}