@taodigital/database 0.0.0-stage → 1.2.0

package/prisma/schema.prisma

@@ -0,0 +1,2901 @@
+// ============================================================================
+//  THE DATA MODEL — "the sealed boxes"
+//  Tenant -> Workspace -> Project -> (Zeta Core, Screens, Test Suites...)
+//
+//  Every record carries tenantId. Tenant isolation is ALSO enforced at the
+//  database layer via Row-Level Security (see migrations/0001_tenant_isolation).
+//  Never rely on application code alone to keep tenants apart.
+// ============================================================================
+
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+  directUrl = env("MIGRATION_DATABASE_URL")
+}
+
+// ---- Access layer -----------------------------------------------------------
+
+model Tenant {
+  id          String    @id @default(cuid())
+  name        String
+  slug        String    @unique @default("")
+  // "POOL" = shared infra with row-level filtering. "SILO" = dedicated (Phase 5).
+  isolation   String
+  region      String
+  createdAt   DateTime  @default(now())
+  workspaces  Workspace[]
+  projects    Project[]
+  memberships Membership[]
+  tokenBudget TokenBudget?
+  notifications           Notification[]
+  notificationPreferences NotificationPreference[]
+  invitations             Invitation[]
+  customRoles             CustomRole[]
+  auditLogs               AuditLog[]
+  ssoConfig               SsoConfig?
+  slackConnection         SlackConnection?
+  teamsConnection         TeamsConnection?
+  siloConfig              TenantSiloConfig?
+  plan                    TenantPlan?
+  accessReviews           AccessReview[]
+  workspaceAgentPrompts  WorkspaceAgentPrompt[]
+}
+
+model Workspace {
+  id          String    @id @default(cuid())
+  tenantId    String
+  name        String
+  slug        String
+  settings    Json?     // domain config: { vertical, requirementTypes, testTechniques }
+  requireMfa  Boolean   @default(false)
+  createdAt   DateTime  @default(now())
+  tenant      Tenant    @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+  projects    Project[]
+
+  @@unique([tenantId, slug])
+  @@index([tenantId])
+}
+
+model User {
+  id               String       @id @default(cuid())
+  email            String       @unique
+  name             String?
+  avatarUrl        String?
+  passwordHash     String?
+  mfaEnabled       Boolean      @default(false)
+  mfaSecret_enc    String?      // AES-256-GCM encrypted TOTP secret
+  mfaVerifiedAt    DateTime?    // when user completed first TOTP verification
+  lastLoginAt      DateTime?    // updated on every successful login
+  failedLoginCount Int          @default(0)   // consecutive failures since last success; reset on login
+  lastFailedLoginAt DateTime?   // timestamp of most recent failed attempt
+  createdAt        DateTime     @default(now())
+  memberships      Membership[]
+  mfaRecoveryCodes MfaRecoveryCode[]
+  notifications           Notification[]
+  notificationPreferences NotificationPreference[]
+  auditLogs               AuditLog[]
+  stepValidations         StepValidation[]
+  createdAgentTokens      AgentToken[]
+  comments                Comment[]
+  userContext             UserContext?
+  learningJourney         LearningJourney?
+}
+
+// Which user has which ROLE inside which tenant.
+model Membership {
+  id        String @id @default(cuid())
+  userId    String
+  tenantId  String
+  // OWNER | ADMIN | QA_LEAD | TESTER | DEVELOPER | VIEWER
+  role      String
+  // ACTIVE | SUSPENDED — set to SUSPENDED by SCIM deprovisioning (soft
+  // suspend, role preserved for reactivation) or an admin. Enforced in
+  // resolveContext() on every authenticated request, not just at login.
+  status    String @default("ACTIVE")
+  user      User   @relation(fields: [userId], references: [id])
+  tenant    Tenant @relation(fields: [tenantId], references: [id])
+
+  @@unique([userId, tenantId])
+  @@index([tenantId])
+  @@index([userId])
+}
+
+// Custom roles created by the tenant
+model CustomRole {
+  id          String   @id @default(cuid())
+  tenantId    String
+  name        String
+  description String?
+  permissions Json     @default("[]") // e.g. ["project:read", "project:write", "settings:manage"]
+  createdAt   DateTime @default(now())
+  updatedAt   DateTime @default(now())
+  tenant      Tenant   @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+  
+  @@unique([tenantId, name])
+}
+
+// Pending invites to a tenant
+model Invitation {
+  id          String    @id @default(cuid())
+  tenantId    String
+  email       String
+  role        String
+  tokenHash   String    @unique
+  invitedBy   String?
+  status      String    @default("PENDING")
+  expiresAt   DateTime
+  createdAt   DateTime  @default(now())
+  acceptedAt  DateTime?
+  tenant      Tenant    @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+  
+  @@unique([tenantId, email])
+  @@index([tenantId, status])
+}
+
+// ---- A Project = one app being tested --------------------------------------
+
+model Project {
+  id         String   @id @default(cuid())
+  tenantId   String
+  name         String
+  slug         String   @default("")
+  appUrl       String?
+  figmaUrl     String?
+  appType      String?
+  crawlConfig  Json?    // { username?, password_enc?, totpSecret_enc? }
+  ciFailureThreshold   Int?
+  slaThreshold         Int?
+  visualDiffThreshold  Float?
+  // Set to true when the project's knowledge outgrows direct loading and
+  // needs vector search (RAG). Default false = direct loading (the simple way).
+  description String?
+  status      String     @default("ACTIVE")
+  oversized   Boolean    @default(false)
+  restricted  Boolean    @default(false)
+  vsaEnabled  Boolean    @default(false)
+  workspaceId String?
+  // Context Intelligence (P1-P8)
+  projectKind              String  @default("WEB")
+  contextSources           Json    @default("{}")
+  contextScore             Int     @default(0)
+  contextPhase             String  @default("PENDING_CONTEXT")
+  contextSourceRequirements Json   @default("{}")
+  approvalGateSummary      Json?
+  createdAt   DateTime   @default(now())
+  updatedAt   DateTime   @updatedAt
+  tenant      Tenant     @relation(fields: [tenantId], references: [id])
+  workspace   Workspace? @relation(fields: [workspaceId], references: [id], onDelete: SetNull)
+
+  screens          Screen[]
+  screenGroups     ScreenGroup[]
+  flows            Flow[]
+  skillFiles       SkillFile[]
+  artifacts        ProjectArtifact[]
+  testSuites       TestSuite[]
+  scriptBundles    ScriptBundle[]
+  connectors       Connector[]
+  oauthConnections OAuthConnection[]
+  agentTokens      AgentToken[]
+  webhooks         Webhook[]
+  auditLogs        AuditLog[]
+  changeLogs       ChangeLog[]
+  platformJobs     PlatformJob[]
+  sessions         UserSession[]
+  testRuns         TestRun[]
+  appFields           AppField[]
+  nativeAppBuilds     NativeAppBuild[]
+  projectEnvironments ProjectEnvironment[]
+  projectMembers      ProjectMember[]
+  requirements        Requirement[]
+  extensionCaptures   ExtensionCapture[]
+  extensionErrors     ExtensionError[]
+  screenTransitions   ScreenTransition[]
+  crawlEvidence       CrawlEvidence[]
+  actionRecipes       ActionRecipe[]
+  apiEndpointObservations ApiEndpointObservation[]
+  testDataSets        TestDataSet[]
+  a11yViolations      ScreenA11yViolation[]
+  // Framework Modernization — Phase 2
+  githubRepoConnections GitHubRepoConnection[]
+  coverageSnapshots     CoverageSnapshot[]
+  idePushTokens         IdePushToken[]
+  skillFileConfigs      SkillFileConfig[]
+  discoveredLinks       DiscoveredLink[]
+  virtualScreens        VirtualScreen[]
+  contextEnhancements   ContextEnhancement[]
+  contextSourceApprovals ContextSourceApproval[]
+  crawlDiffs            CrawlDiff[]
+  bugSignals            BugSignal[]
+  requirementCoverages  RequirementCoverage[]
+  figmaComponents       FigmaComponent[]
+  extractedElements     ExtractedElement[]
+
+  @@unique([tenantId, slug])
+  @@index([tenantId])
+  @@index([workspaceId])
+}
+
+// ---- THE Zeta Core (a normal, structured, versioned knowledge store) -------
+
+model ScreenGroup {
+  id          String   @id @default(cuid())
+  tenantId    String
+  projectId   String
+  name        String
+  slug        String
+  description String?
+  color       String   @default("#6FD0E8")
+  icon        String   @default("◈")
+  order       Int      @default(0)
+  crawlJobId  String?
+  createdAt   DateTime @default(now())
+  updatedAt   DateTime @updatedAt
+  project     Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+  screens     Screen[]
+
+  @@index([tenantId, projectId])
+}
+
+model Screen {
+  id          String   @id @default(cuid())
+  tenantId    String
+  projectId   String
+  name        String
+  url         String?
+  version     Int      @default(1)
+  groupId     String?
+  group       ScreenGroup? @relation(fields: [groupId], references: [id])
+  // How closely the live screen matches its Figma design (Phase 2). 0-100.
+  figmaMatch  Int?
+  // Accessibility score 0-100 (Phase 3).
+  a11yScore   Int?
+  lastSeenAt      DateTime @default(now())
+  // Lifecycle fields — track screen presence across crawl runs
+  status          String   @default("ACTIVE") // ACTIVE | PENDING_REMOVAL
+  lastCrawlJobId  String?  // ID of the last PlatformJob that discovered this screen
+  removedAt       DateTime?
+  removalReason   String?  // e.g. "Not found in crawl #N (was present in crawl #N-1)"
+  // How this screen was first discovered — set once at creation, never changed on
+  // re-crawl. Powers orphan-page detection: a screen with zero inbound KAG edges
+  // (Element.transitionsToScreenId) is only a meaningful "orphan" if it wasn't the
+  // crawl's own entry point.
+  // ENTRY_POINT | LINK_FOLLOW | SEED_URL | SKYVERN_AI | SITEMAP
+  discoveryMethod String   @default("LINK_FOLLOW")
+  project         Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+  elements    Element[]
+  screenshots Screenshot[]
+  baselines   VisualBaseline[]
+  testCases   TestCase[]
+
+  // Knowledge Graph (KAG): Elements on OTHER screens that transition to this screen
+  transitionedFrom Element[] @relation("ElementTransitions")
+
+  // Phase 2: element hash for stale-test detection
+  elementHash          String?
+  elementHashChangedAt DateTime?
+
+  // Phase 3: perceptual screenshot diffs
+  screenDiffs          ScreenDiff[]
+
+  // Phase 5: structured probe observations
+  probeObservations    ProbeObservation[]
+  screenTransitionsFrom ScreenTransition[] @relation("ScreenTransitionFrom")
+  screenTransitionsTo   ScreenTransition[] @relation("ScreenTransitionTo")
+  crawlEvidence         CrawlEvidence[]
+  apiEndpointObservations ApiEndpointObservation[]
+
+  // Navigation graph: discovered link edges from/to this screen
+  discoveredLinksFrom  DiscoveredLink[] @relation("DiscoveredLinkFromScreen")
+  discoveredLinksTo    DiscoveredLink[] @relation("DiscoveredLinkToScreen")
+
+  domSnapshotPath      String?
+  domSnapshotCloudUrl  String?
+  // True when crawler detected this screen requires authentication but session was lost.
+  // DOM/elements captured for this screen may reflect an auth wall, not real content.
+  requiresAuth         Boolean  @default(false)
+
+  // Navigation graph metadata
+  depth                Int?     // BFS depth from entry point (0 = entry point)
+  parentUrl            String?  // URL of the screen that linked to this one first
+
+  // Role profiles that can access this screen — populated by multi-role crawl runs.
+  roleAccess           String[] @default([])
+
+  // Markdown extraction (crawl4AI-style text output). "readability" = clean
+  // article content (nav/ads/chrome stripped); "full-page" = whole-page
+  // fallback for app UI screens Readability finds no article in.
+  markdownPath         String?
+  markdownContent      String?
+  markdownMethod       String?
+  markdownWordCount    Int?
+  // AI-generated one-sentence summary of what this screen does/contains
+  aiSummary            String?
+
+  // Phase 4.4: axe-core accessibility violations
+  a11yViolations       ScreenA11yViolation[]
+  virtualScreens       VirtualScreen[]
+  figmaNodeId          String?
+  figmaComponents      FigmaComponent[]
+  crawlDiffsAsFrom     CrawlDiff[] @relation("CrawlDiffFromScreen")
+  crawlDiffsAsTo       CrawlDiff[] @relation("CrawlDiffToScreen")
+
+  @@index([tenantId, projectId])
+  @@index([tenantId, projectId, status])
+  @@index([tenantId, projectId, elementHashChangedAt])
+  @@index([status])
+}
+
+// Phase 4.4: Per-screen axe-core accessibility violations (WCAG 2.x)
+model ScreenA11yViolation {
+  id          String   @id @default(cuid())
+  tenantId    String
+  projectId   String
+  screenId    String
+  runId       String?
+  impact      String   // critical | serious | moderate | minor
+  rule        String   // axe rule ID e.g. "color-contrast"
+  description String
+  nodeHtml    String?  // offending DOM snippet (truncated to 500 chars)
+  wcagTags    Json     @default("[]")  // ["wcag2a", "wcag21aa"] etc
+  createdAt   DateTime @default(now())
+  project     Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+  screen      Screen   @relation(fields: [screenId], references: [id], onDelete: Cascade)
+
+  @@index([tenantId, projectId])
+  @@index([screenId])
+}
+
+// Rich workflow graph edge discovered during crawl/probe/replay.
+model ScreenTransition {
+  id           String   @id @default(cuid())
+  tenantId     String
+  projectId    String
+  fromScreenId String
+  toScreenId   String?
+  action       Json
+  confidence   Float    @default(0.5)
+  jobId        String?
+  createdAt    DateTime @default(now())
+  project      Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+  fromScreen   Screen   @relation("ScreenTransitionFrom", fields: [fromScreenId], references: [id], onDelete: Cascade)
+  toScreen     Screen?  @relation("ScreenTransitionTo", fields: [toScreenId], references: [id], onDelete: SetNull)
+
+  @@index([tenantId, projectId])
+  @@index([tenantId, projectId, jobId])
+  @@index([fromScreenId])
+  @@index([toScreenId])
+}
+
+// Durable evidence envelope emitted by the crawler for auditability and replay.
+model CrawlEvidence {
+  id        String   @id @default(cuid())
+  tenantId  String
+  projectId String
+  screenId  String?
+  jobId     String?
+  type      String
+  payload   Json
+  createdAt DateTime @default(now())
+  project   Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+  screen    Screen?  @relation(fields: [screenId], references: [id], onDelete: Cascade)
+
+  @@index([tenantId, projectId])
+  @@index([tenantId, projectId, jobId])
+  @@index([screenId])
+  @@index([type])
+}
+
+// Replay-first self-healing action recipe. Successful AI/manual actions become
+// deterministic recipes before future crawls spend more model tokens.
+model ActionRecipe {
+  id          String    @id @default(cuid())
+  tenantId    String
+  projectId   String
+  domain      String
+  purpose     String
+  fingerprint String
+  steps       Json
+  successRate Float     @default(0)
+  lastUsedAt  DateTime?
+  createdAt   DateTime  @default(now())
+  updatedAt   DateTime  @updatedAt
+  project     Project   @relation(fields: [projectId], references: [id], onDelete: Cascade)
+
+  @@unique([tenantId, projectId, purpose, fingerprint])
+  @@index([tenantId, projectId])
+  @@index([tenantId, projectId, domain])
+}
+
+// Represents a dynamic state (modal, panel, popup) within a base Screen, captured after an interaction
+model VirtualScreen {
+  id              String   @id @default(cuid())
+  tenantId        String
+  projectId       String
+  parentScreenId  String
+  stateId         String   // simHash of DOM after action
+  triggerAction   String   // e.g. "click Import Tests"
+  overlayType     String   // 'modal' | 'panel' | 'tooltip' | 'dropdown'
+  screenshotUrl   String?
+  domSnapshotUrl  String?
+  createdAt       DateTime @default(now())
+
+  project         Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+  parentScreen    Screen   @relation(fields: [parentScreenId], references: [id], onDelete: Cascade)
+
+  @@unique([tenantId, projectId, parentScreenId, stateId])
+  @@index([tenantId, projectId])
+  @@index([parentScreenId])
+}
+
+// Network/API calls observed while rendering a screen. This connects UI screens
+// to REST/GraphQL endpoints for API test generation and backend-state mapping.
+model ApiEndpointObservation {
+  id            String   @id @default(cuid())
+  tenantId      String
+  projectId     String
+  screenId      String?
+  method        String
+  urlPattern    String
+  statusCode    Int?
+  requestKind   String?
+  responseShape Json?
+  createdAt     DateTime @default(now())
+  project       Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+  screen        Screen?  @relation(fields: [screenId], references: [id], onDelete: Cascade)
+
+  @@index([tenantId, projectId])
+  @@index([tenantId, projectId, method])
+  @@index([screenId])
+}
+
+model Element {
+  id           String  @id @default(cuid())
+  tenantId     String
+  projectId    String
+  // Nullable because extension-captured elements (context-menu/devtools/picker)
+  // don't correspond to a crawled Screen — only crawl-discovered elements set this.
+  screenId     String?
+  // A stable, human-readable description, e.g. "Primary login submit button".
+  meaning      String?
+  // The kind of thing it is: BUTTON | INPUT | LINK | MENU | CHECKBOX | ...
+  role         String?
+  // What data this field expects, e.g. "valid_email", "us_phone", "date_ddmmyyyy".
+  expectedData String?
+  // Free-form notes learned over time, e.g. "rejects non-company.com domains".
+  notes        String?
+  text              String?  // Inner text or placeholder
+  isInteractive     Boolean? // True if it's an a/button/input, false if it's just layout
+
+  // Phase 1: enriched element metadata
+  boundingRect      Json?    // {x, y, width, height, top, left, right, bottom}
+  ariaState         Json?    // {expanded, checked, pressed, selected, invalid, required}
+  parentLandmark    String?  // "main" | "nav" | "aside" | "header" | "footer" | "modal"
+  viewport          String   @default("DESKTOP")
+
+  // Extension-capture fields (context-menu/devtools/picker sources — no crawled Screen).
+  selector      String?
+  pageUrl       String?
+  screenshotUrl String?
+  source        String  @default("crawl") // "crawl" | "context-menu" | "devtools" | "picker"
+  metadata      Json?
+
+  // Knowledge Graph (KAG) Edge: If clicking this element leads to another screen.
+  transitionsToScreenId String?
+  transitionsToScreen   Screen? @relation("ElementTransitions", fields: [transitionsToScreenId], references: [id])
+
+  screen       Screen? @relation(fields: [screenId], references: [id])
+  fingerprint  ElementFingerprint?
+
+  @@unique([tenantId, projectId, selector, pageUrl], name: "Element_ext_upsert_key")
+  @@index([tenantId, projectId])
+  @@index([tenantId, screenId])
+  @@index([tenantId, screenId, parentLandmark])
+  @@index([tenantId, screenId, viewport])
+}
+
+model Flow {
+  id         String  @id @default(cuid())
+  tenantId   String
+  projectId  String
+  name       String
+  // Ordered list of screen ids that make up this user journey (JSON).
+  steps      Json
+  project    Project @relation(fields: [projectId], references: [id], onDelete: Cascade)
+
+  @@index([tenantId, projectId])
+}
+
+model Screenshot {
+  id          String   @id @default(cuid())
+  tenantId    String
+  projectId   String
+  screenId    String
+  // DESKTOP | MOBILE | TABLET
+  viewport    String   @default("DESKTOP")
+  storagePath String
+  cloudUrl    String?
+  version     Int      @default(1)
+  capturedAt  DateTime @default(now())
+  // FM-4: device pixel ratio captured at crawl time; null = unknown (pre-migration)
+  dpr         Float?
+  screen      Screen   @relation(fields: [screenId], references: [id])
+  stepEvidence StepEvidence[]
+
+  @@index([tenantId, projectId])
+  @@index([tenantId, screenId])
+  @@index([screenId, version(sort: Desc)])
+}
+
+// A reusable, per-project instruction package the AI loads before a task.
+//
+// TAXONOMY KINDS (Application Intelligence):
+//   PLATFORM  — tech stack: React 18, JWT auth, REST API, mobile-responsive
+//   FUNCTION  — domain: "e-commerce checkout", "healthcare patient portal"
+//   DESIGN    — visual system: color tokens, typography, spacing, dark/light mode
+//   THEME     — cross-cutting conventions: "errors = toast top-right", "spinner on submit"
+//   COMPONENT — reusable UI patterns: "DataTable paginates at 25 rows, sortable cols"
+//   ELEMENT   — specific element behavior: "email validates on blur, error inline"
+//
+// LEGACY KINDS (task-specific):
+//   TEST_CASE | TEST_DATA | TEST_SCRIPT | CRAWL | SCREEN_UNDERSTANDING
+//
+// RETRIEVAL TIERS:
+//   PLATFORM + FUNCTION + DESIGN + THEME  → always injected (global, project-wide)
+//   COMPONENT + ELEMENT                   → injected selectively (filtered by screenIds/tags)
+model SkillFile {
+  id         String   @id @default(cuid())
+  tenantId   String
+  projectId  String
+
+  // Taxonomy kind (see above)
+  kind       String
+
+  // PROJECT = per-project (default)
+  // WORKSPACE = shared template across all projects in this tenant
+  scope      String   @default("PROJECT")
+
+  // 1-3 line plain-English description — shown in UI and used for keyword search
+  summary    String?
+
+  // Searchable tags for selective retrieval: ["login-form", "email-validation"]
+  tags       Json     @default("[]")
+
+  // For COMPONENT/ELEMENT: which screenIds this knowledge covers ([] = all screens)
+  screenIds  Json     @default("[]")
+
+  // The full markdown instruction content — grows with human edits over time
+  content    String
+
+  // Machine-readable extraction alongside markdown. Generators should prefer
+  // this when present; markdown remains the human review surface.
+  structuredData Json     @default("{}")
+  provenance     Json     @default("[]")
+  confidence     Float?
+
+  // UNKNOWN | PASS | WARN | FAIL
+  validationStatus  String  @default("UNKNOWN")
+  validationSummary String?
+
+  // CURRENT | STALE | APPROVED_STALE
+  staleStatus String  @default("CURRENT")
+  staleReason String?
+
+  generatorVersion String?
+
+  version        Int      @default(1)
+  approvedBy     String?
+  // PENDING | APPROVED | NEEDS_REVIEW
+  approvalStatus String   @default("PENDING")
+
+  // Diff / review fields — populated when AI regenerates content
+  priorContent        String?
+  priorVersion        Int?
+  priorGeneratedAt    DateTime?
+  changesSummary      String?
+
+  // AUTO (AI-generated) | MANUAL (human-written) | SEEDED (platform template)
+  source     String   @default("AUTO")
+
+  updatedAt  DateTime @default(now())
+  project    Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+
+  // Token Tracking
+  lastGenPromptTokens     Int?
+  lastGenCompletionTokens Int?
+  lastGenCostUsd          Float?
+  lastGenModel            String?
+  lastGenAt               DateTime?
+
+  @@unique([projectId, kind, scope])
+  @@index([tenantId, projectId])
+  @@index([tenantId, kind])
+}
+
+// ---- Per-project skill file kind configuration ----------------------------
+// Platform admins can enable/disable generation for specific kinds,
+// require manual approval, or set auto-gen schedules per project.
+
+model SkillFileConfig {
+  id                  String   @id @default(cuid())
+  projectId           String
+  tenantId            String
+  kind                String   // matches TAXONOMY_KINDS value
+  enabled             Boolean  @default(true)
+  requireApproval     Boolean  @default(false)
+  autoGenIntervalMins Int?     // null = no scheduled auto-gen
+  generationStrategy  String   @default("AUTO")  // AUTO | MANUAL | SEEDED
+  validationThresholds Json?   // { minConfidence?: number, maxStaleAgeDays?: number }
+  adminNotes          String?  @db.Text
+  createdAt           DateTime @default(now())
+  updatedAt           DateTime @updatedAt
+
+  project             Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+
+  @@unique([projectId, kind])
+  @@index([tenantId, projectId])
+}
+
+// ---- User-uploaded knowledge artifacts ------------------------------------
+
+model ProjectArtifact {
+  id           String   @id @default(cuid())
+  tenantId     String
+  projectId    String
+  name         String            // display name (user-editable)
+  originalName String            // filename as uploaded
+  mimeType     String
+  size         Int               // bytes of original file
+  content      String   @db.Text // converted markdown content
+  storageKey   String?           // object key in tenant S3/R2 (original file); null = not stored in cloud
+  // When tenant S3 is configured, extracted markdown is stored there too.
+  // Resolver: if contentKey is set, read from S3; otherwise use content field directly.
+  contentKey   String?
+  kind         String   @default("DOCUMENT") // DOCUMENT | SPREADSHEET | TEST_CASES | SPEC | OTHER
+  uploadedBy   String
+  uploadedAt   DateTime @default(now())
+  summary          String?
+  keywords         String[]  @default([])
+  docType          String?
+  chunkCount       Int      @default(1)
+  cachedScenarios  Json?    // Cached extractScenarios result — array of ScenarioSummary objects
+  // Import lifecycle tracking
+  importStatus     String?  // null | 'IMPORTED' | 'FAILED'
+  importedAt       DateTime?
+  importedTestCount Int?
+  importedSuiteId  String?  // suite the test cases were imported into; null if suite deleted
+  // Version chain — versionNum increments on re-upload; previousVersionId links to prior artifact
+  versionNum       Int      @default(1)
+  previousVersionId String?
+  contentHash      String?  // sha256 of original upload bytes; partial unique (projectId, contentHash) index in migration SQL
+  previousVersion   ProjectArtifact?  @relation("ArtifactVersionChain", fields: [previousVersionId], references: [id], onDelete: SetNull)
+  nextVersions      ProjectArtifact[] @relation("ArtifactVersionChain")
+  project          Project    @relation(fields: [projectId], references: [id], onDelete: Cascade)
+  testCases        TestCase[]
+
+  @@index([tenantId, projectId])
+}
+
+// ---- Test artifacts --------------------------------------------------------
+
+enum SuiteCategory {
+  REGRESSION
+  SMOKE
+  SANITY
+  API
+  SECURITY
+  INTEGRATION
+  E2E
+  CUSTOM
+}
+
+model TestSuite {
+  id        String     @id @default(cuid())
+  tenantId  String
+  projectId String
+  name      String
+  createdAt DateTime   @default(now())
+  project   Project    @relation(fields: [projectId], references: [id], onDelete: Cascade)
+  testCases TestCase[]
+  category  SuiteCategory?
+
+  // Hierarchy — child suites are created per Section column on import
+  // Unique (tenantId, projectId, COALESCE(parentId,''), name) expression index lives in migration SQL.
+  parentId  String?
+  parent    TestSuite?  @relation("SuiteHierarchy", fields: [parentId], references: [id], onDelete: Cascade)
+  children  TestSuite[] @relation("SuiteHierarchy")
+
+  ownerUserId      String?
+
+  // Token Tracking
+  genTotalTokens   Int?
+  genTotalCostUsd  Float?
+  genModel         String?
+  genAt            DateTime?
+  genScreenCount   Int?
+  coverageReport   Json?
+
+  @@index([tenantId, projectId])
+  @@index([parentId])
+}
+
+model TestCase {
+  id             String     @id @default(cuid())
+  tenantId       String
+  projectId      String
+  suiteId        String
+  screenId       String?
+  // Human-readable stable reference, e.g. "TC-LOGIN-014"
+  ref            String?
+  title          String
+  // POSITIVE | NEGATIVE | EDGE | ACCESSIBILITY | SECURITY
+  kind           String
+  // CRITICAL | HIGH | MEDIUM | LOW
+  priority       String     @default("HIGH")
+  preconditions  String?
+  steps          Json
+  expectedResult String?
+  // The rendered Gherkin .feature text for this case
+  gherkin        String?
+  // PENDING_REVIEW | APPROVED | RETIRED  (human-in-the-loop)
+  status         String     @default("PENDING_REVIEW")
+  approvedBy     String?   // userId of reviewer who approved
+  approvedAt     DateTime? // when APPROVED status was set
+  // AI_GENERATED | HUMAN_WRITTEN | IMPORTED
+  source         String     @default("AI_GENERATED")
+  // Which real element ids this test is grounded in (proves "no invention").
+  groundedOn     Json
+  // Searchable tags e.g. ["@smoke", "@auth", "@regression"]
+  tags           Json       @default("[]")
+  // Links to external requirements/Figma/JIRA
+  caseRefs       Json       @default("[]")
+  // Viewport scopes for this test case. Empty = applies to all.
+  // Values: ["DESKTOP", "MOBILE_PORTRAIT", "TABLET"]
+  viewports      Json       @default("[]")
+  // Which runner viewport this test case is valid for. ALL = any runner.
+  // ALL | DESKTOP_ONLY | MOBILE_ONLY | TABLET_ONLY
+  viewportConstraint  String  @default("ALL")
+  screen         Screen?    @relation(fields: [screenId], references: [id])
+  suite          TestSuite  @relation(fields: [suiteId], references: [id])
+  testData        TestData[]
+  scripts         TestScript[]
+  humanReviews    HumanReviewItem[]
+  results         TestResult[]
+  testCaseRuns    TestCaseRun[]
+  stepEvidence    StepEvidence[]
+  stepValidations StepValidation[]
+
+  techniqueOfRecord  String?
+  traceTo            String?
+  // Additional requirement IDs this test also covers (many-to-many traceability).
+  // traceTo stays the primary link; this array holds secondary reqIds.
+  traceToExtra       Json      @default("[]")
+  testDataInline     Json?
+  dataNote           String?   // LLM-generated guidance for the data-agent: field constraints, personas, boundary values
+  scriptNote         String?   // LLM-generated guidance for the script-agent: preconditions, dynamic extractions, parallelism
+  structuredSteps    Json?     // [{action, target?, data?}] — machine-readable step format for accurate data extraction
+
+  // Traceability — which artifact this test case was imported from
+  artifactId     String?
+  artifact       ProjectArtifact? @relation(fields: [artifactId], references: [id], onDelete: SetNull)
+
+  // Scenario traceability
+  scenarioId     String?
+  scenario       Scenario? @relation(fields: [scenarioId], references: [id], onDelete: SetNull)
+  // Suspect link — flagged when upstream requirement changes after this test was generated
+  suspect        Boolean   @default(false)
+  suspectReason  String?
+
+  // Flakiness tracking — rolling stats over the last N TestCaseRun outcomes,
+  // recomputed by AppBrain.recordFlakinessOutcome() after each run. See
+  // docs/13-TEST-FLAKINESS-DETECTION.md "Future Work".
+  // 0.0-1.0 fraction of FAILED+FLAKY outcomes in the rolling window.
+  flakyScore        Float     @default(0)
+  // Current losing streak (consecutive FAILED/FLAKY runs), reset on a PASS.
+  consecutiveFlakes Int       @default(0)
+  lastFlakyAt       DateTime?
+  // Auto- or human-quarantined tests are blocked from running (POST .../run
+  // returns 409) unless the caller explicitly passes force:true. Never
+  // auto-cleared — requires an explicit PATCH .../quarantine to lift.
+  quarantined       Boolean   @default(false)
+  quarantinedAt     DateTime?
+  quarantineReason  String?
+
+  // Token Tracking
+  genPromptTokens     Int?
+  genCompletionTokens Int?
+  genCostUsd          Float?
+  genModel            String?
+
+  // Data-driven execution — linked data set (Phase 4.3)
+  dataSetId           String?
+  dataSet             TestDataSet? @relation(fields: [dataSetId], references: [id], onDelete: SetNull)
+
+  // Framework Modernization — script coverage mapping (Phase 2)
+  coverageMapping     CoverageMapping?
+  // Where a generated script should land in the connected repo (Phase 3)
+  repoTargetPath      String?
+
+  // S3 content key pointers (DB→S3 pattern; doc 18).
+  // When set, the corresponding DB field is a stub and actual content is in tenant S3.
+  stepsKey        String?   // pointer for steps Json
+  gherkinKey      String?   // pointer for gherkin String
+
+  // SHA-256 of normalized(title+steps+expectedResult+preconditions) — used for content-hash dedup.
+  // Replaces title-only dedup so AI-paraphrased duplicates are caught cross-pass.
+  contentHash     String?
+  // SHA-256 of sorted(groundedOn element IDs) + kind — structural dedup: same DOM flow + kind = same test.
+  groundingHash   String?
+
+  // Extracted Playwright locator expressions — computed from Screen.elements (crawl path)
+  // or from on-demand page extraction (import path). Stored as PlaywrightLocator[] JSON.
+  // Shape: [{key, expression, elementType, confidence, source, description}]
+  locatorsJson    Json?
+  // ISO timestamp of last locator extraction (used to show staleness in UI)
+  locatorsExtractedAt DateTime?
+  // Per-step screenshot/evidence trail from CAPTURE_STEPS jobs.
+  captureStepScreenshots Json?
+
+  versions        TestCaseVersion[]
+  sourceEnhancementId   String?
+  sourceEnhancement     ContextEnhancement? @relation("TestCaseSourceEnhancement", fields: [sourceEnhancementId], references: [id], onDelete: SetNull)
+  contextQualityScore   Int?
+  crawlDiffId           String?
+  crawlDiff             CrawlDiff? @relation("TestCaseCrawlDiff", fields: [crawlDiffId], references: [id], onDelete: SetNull)
+  bugSignalRefs         BugSignal[] @relation("BugSignalAffectedTestCases")
+
+  createdAt       DateTime @default(now())
+  updatedAt       DateTime @updatedAt
+
+  @@index([tenantId, projectId])
+  @@index([tenantId, suiteId])
+  @@index([suiteId, contentHash])
+  @@index([suiteId, groundingHash])
+  @@index([screenId])
+  @@index([priority])
+  @@index([source])
+  @@index([artifactId])
+  @@index([scenarioId])
+  @@index([traceTo])
+  @@index([tenantId, projectId, suspect])
+  @@index([tenantId, projectId, quarantined])
+  @@index([dataSetId])
+  @@index([status, projectId])
+  @@index([sourceEnhancementId])
+  @@index([crawlDiffId])
+}
+
+// Immutable snapshot of a TestCase taken before each save (edit/review).
+// versionNum increments per testCase starting at 1. The snapshot field holds
+// the full TestCase row at time of capture for complete restore fidelity.
+model TestCaseVersion {
+  id             String   @id @default(cuid())
+  testCaseId     String
+  testCase       TestCase @relation(fields: [testCaseId], references: [id], onDelete: Cascade)
+  versionNum     Int
+  title          String
+  steps          Json?
+  preconditions  String?
+  expectedResult String?
+  kind           String?
+  priority       String?
+  snapshot       Json     // full TestCase fields at time of snapshot
+  createdAt      DateTime @default(now())
+  createdBy      String?  // userId
+  tenantId       String
+
+  @@unique([testCaseId, versionNum])
+  @@index([tenantId, testCaseId])
+}
+
+model TestData {
+  id         String   @id @default(cuid())
+  tenantId   String
+  projectId  String
+  testCaseId String
+  // VALID | INVALID | EDGE | SYNTHETIC
+  kind       String
+  // SYNTHETIC | FALLBACK | PRODUCTION | STAGING | SANDBOX | DUMMY | IMPORTED
+  source     String   @default("SYNTHETIC")
+  payload    Json
+  // When set, this row is a historical version superseded by a later regeneration
+  supersededAt DateTime?
+  testCase   TestCase @relation(fields: [testCaseId], references: [id])
+
+  @@index([tenantId, projectId])
+  @@index([tenantId, testCaseId])
+  @@index([tenantId, source])
+  @@index([tenantId, testCaseId, supersededAt])
+}
+
+model TestScript {
+  id         String   @id @default(cuid())
+  tenantId   String
+  projectId  String
+  testCaseId String
+  // The runnable, exportable code (e.g. Playwright).
+  language   String   @default("playwright-ts")
+  code       String   @db.Text
+  filePath   String?          // relative path in the repo, e.g. src/MySuite/locators/MyClass.locators.ts
+  // When tenant S3 is configured, code is stored there and this holds the object key.
+  // Resolver: if codeKey is set, read from S3; otherwise use code field directly.
+  codeKey    String?
+  // PENDING | PASS | FAIL | SKIPPED
+  validationStatus String  @default("PENDING")
+  validationErrors String? @db.Text
+  // Whether this script was pushed to a GitHub PR
+  pushedToPR      Boolean  @default(false)
+  pushedPRId      String?  // GitHubPR.id
+  scriptContextSnapshot Json?
+  testCase   TestCase @relation(fields: [testCaseId], references: [id])
+
+  @@unique([testCaseId, language])
+  @@index([tenantId, projectId])
+  @@index([tenantId, testCaseId])
+}
+
+model ScriptBundle {
+  id        String   @id @default(cuid())
+  tenantId  String
+  projectId String
+  // SUITE | PACK
+  scopeType String
+  // TestSuite.id for suites, pack id such as regression/smoke/sanity for packs.
+  scopeId   String
+  language  String   @default("playwright-ts")
+  files     Json
+  basePage  String?
+  caseCount Int      @default(0)
+  project   Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([tenantId, projectId, scopeType, scopeId, language])
+  @@index([tenantId, projectId])
+  @@index([tenantId, projectId, scopeType, scopeId])
+}
+
+// Stores script alignment verification results — score, aligned flag, and issues
+// from the AI verifier. Uses a proper dedicated table instead of abusing TestScript.
+model AlignmentResult {
+  id         String   @id @default(cuid())
+  tenantId   String
+  projectId  String
+  testCaseId String
+  language   String
+  score      Int      @default(0)
+  aligned    Boolean  @default(false)
+  issues     Json     @default("[]")
+  // Deterministic step coverage (matched steps ÷ total steps), independent of the LLM score.
+  stepCoveragePct Float?
+  // { totalSteps, coveredSteps, coveragePct, assertionCoverage, perStep: [...] }
+  stepCoverage    Json?
+  verifiedAt DateTime @default(now())
+  createdAt  DateTime @default(now())
+  updatedAt  DateTime @updatedAt
+
+  @@unique([testCaseId, language])
+  @@index([tenantId, projectId])
+  @@index([tenantId, testCaseId])
+}
+
+// Snapshot table — captures old TestScript code before each regeneration.
+// The TestScript table always holds the latest version; history lives here.
+model TestScriptVersion {
+  id         String   @id @default(cuid())
+  tenantId   String
+  testCaseId String
+  language   String
+  code       String   @db.Text
+  versionNum Int
+  createdAt  DateTime @default(now())
+
+  @@index([testCaseId, language])
+  @@index([tenantId, testCaseId])
+}
+
+// Snapshot table — captures SkillFile content (especially TEST_PLAN) before each update.
+model SkillFileVersion {
+  id          String   @id @default(cuid())
+  tenantId    String
+  projectId   String
+  skillFileId String
+  kind        String
+  content     String   @db.Text
+  versionNum  Int
+  createdAt   DateTime @default(now())
+
+  @@index([skillFileId, versionNum])
+  @@index([tenantId, projectId, kind])
+}
+
+// ---- Workspace / Tenant Settings -------------------------------------------
+
+// Workspace-level configuration per tenant — LLM provider, notifications, etc.
+// Sensitive fields (API keys) use the _enc suffix, encrypted with AES-256-GCM.
+model TenantSetting {
+  id                 String   @id @default(cuid())
+  tenantId           String
+  // "LLM" | "NOTIFICATIONS" | "BRANDING"
+  category           String
+  // JSON blob; sensitive fields end with _enc (same pattern as Connector)
+  config             Json     @default("{}")
+  dataRetentionDays  Int      @default(365)
+  updatedAt          DateTime @default(now())
+
+  @@unique([tenantId, category])
+  @@index([tenantId])
+}
+
+// Per-tenant override of a platform feature-flag default. Absence of a row for
+// a given (tenantId, key) means "use the default" (see FEATURE_FLAG_DEFAULTS
+// in @detiq/core) — this table only ever stores explicit overrides, not every
+// flag's state for every tenant.
+model TenantFeatureFlag {
+  id        String   @id @default(cuid())
+  tenantId  String
+  key       String
+  enabled   Boolean
+  updatedAt DateTime @default(now())
+
+  @@unique([tenantId, key])
+  @@index([tenantId])
+}
+
+model PlatformJob {
+  id         String    @id @default(cuid())
+  tenantId   String
+  projectId  String
+  type       String    @default("CRAWL") // CRAWL | GENERATE_TESTS | VISUAL_REGRESSION
+  name       String?   // EventName_YYYY-MM-DD_timestamp for tracking
+  // QUEUED | RUNNING | DONE | FAILED
+  status     String    @default("QUEUED")
+  config     Json
+  result     Json?
+  error      String?
+  failureType String?  // FailureType enum: TRANSIENT | INFRASTRUCTURE | LOGICAL | FATAL
+  progress   Int       @default(0)
+  queuedAt   DateTime  @default(now())
+  startedAt  DateTime?
+  finishedAt DateTime?
+  // Identifies which worker process claimed this job (host:pid) — diagnostics +
+  // lets the stale-job sweep tell a legitimately long-running job apart from
+  // one whose worker died without updating status.
+  workerId    String?
+  // Bumped on every progress update while RUNNING. The stale-job sweep compares
+  // this (not startedAt) against its timeout, so a slow-but-alive job doesn't
+  // get requeued and double-processed by another worker.
+  heartbeatAt DateTime?
+  project    Project   @relation(fields: [projectId], references: [id], onDelete: Cascade)
+
+  // Token Tracking
+  totalPromptTokens     Int?
+  totalCompletionTokens Int?
+  totalCacheReadTokens  Int?
+  totalEstimatedCostUsd Float?
+  llmCallCount          Int      @default(0)
+
+  // Gap 30: Dead-letter queue / automatic retry
+  retryCount    Int       @default(0)
+  nextRetryAt   DateTime?
+  dlq           Boolean   @default(false)
+  dlqReason     String?
+
+  // Worker lease / fencing (GAP-03)
+  leaseExpiresAt  DateTime?
+  fencingToken    String?
+
+  // Durable checkpoint for CRAWL (GAP-04)
+  checkpoint      Json?
+  checkpointAt    DateTime?
+
+  // Parent-child relationship (GAP-06)
+  parentJobId     String?
+  rootJobId       String?
+  parent          PlatformJob?  @relation("JobParent", fields: [parentJobId], references: [id])
+  children        PlatformJob[] @relation("JobParent")
+
+  // Current execution step as indexed column (GAP-09)
+  currentStep     String?
+
+  // Re-queue timestamp for accurate queue-wait time on retries (GAP-10/22)
+  requeuedAt      DateTime?
+
+  // DLQ lifecycle (GAP-13)
+  dlqAt           DateTime?
+  dlqRedriveCount Int       @default(0)
+
+  // User attribution (GAP-16)
+  submittedBy     String?
+
+  // Inline (API-in-process) vs Worker mode (GAP-21)
+  inline          Boolean   @default(false)
+
+  // Priority — higher = sooner (GAP-23)
+  priority        Int       @default(0)
+
+  // Attempts relation
+  attempts        JobAttempt[]
+
+  @@index([tenantId, projectId])
+  @@index([tenantId, projectId, queuedAt])
+  @@index([status])
+  @@index([status, queuedAt])
+  @@index([status, workerId])
+  @@index([status, dlq, nextRetryAt])
+  @@index([status, nextRetryAt])
+  @@index([parentJobId])
+  @@index([tenantId, status])
+  @@index([priority, queuedAt])
+}
+
+model JobAttempt {
+  id            String      @id @default(cuid())
+  jobId         String
+  tenantId      String
+  attemptNumber Int
+  workerId      String?
+  fencingToken  String?
+  startedAt     DateTime    @default(now())
+  finishedAt    DateTime?
+  status        String      // RUNNING | DONE | FAILED | CANCELLED
+  error         String?
+  progress      Int         @default(0)
+  job           PlatformJob @relation(fields: [jobId], references: [id], onDelete: Cascade)
+
+  @@index([jobId])
+  @@index([tenantId])
+  @@index([jobId, attemptNumber])
+}
+
+// ---- Self-Healing Element Fingerprints -------------------------------------
+
+model ElementFingerprint {
+  id           String    @id @default(cuid())
+  tenantId     String
+  projectId    String
+  elementId    String    @unique
+  // Multiple selectors ranked by stability: [{type, value, confidence}]
+  selectors    Json
+  lastHealedAt DateTime?
+  healCount    Int       @default(0)
+  element      Element   @relation(fields: [elementId], references: [id])
+
+  @@index([tenantId, projectId])
+}
+
+// ---- Session Recording (Record-and-Replay + Production Capture) ------------
+
+model UserSession {
+  id               String    @id @default(cuid())
+  tenantId         String
+  projectId        String
+  // RECORDED | PRODUCTION
+  source           String
+  startUrl         String
+  // Array of {type, target, value, timestamp, viewport}
+  events           Json
+  duration         Int?
+  // PENDING | PROCESSING | CONVERTED | FAILED
+  status           String    @default("PENDING")
+  convertedSuiteId String?
+  recordedAt       DateTime  @default(now())
+  project          Project   @relation(fields: [projectId], references: [id], onDelete: Cascade)
+
+  @@index([tenantId, projectId])
+  @@index([status])
+}
+
+// ---- Visual Regression Testing ---------------------------------------------
+
+model VisualBaseline {
+  id          String      @id @default(cuid())
+  tenantId    String
+  projectId   String
+  screenId    String
+  viewport    String      @default("DESKTOP")
+  browser     String      @default("chromium")
+  storagePath String
+  cloudUrl    String?
+  approvedBy  String?
+  createdAt   DateTime    @default(now())
+  gitBranch   String      @default("main")
+  gitCommit   String?
+  // Masking zones — regions excluded from visual diff comparison.
+  // Array of {x, y, width, height, label} rectangles (user-drawn exclusions for dynamic content).
+  ignoredRegions  Json  @default("[]")
+  // Snapshot of element bounding boxes at baseline creation time for layout drift detection.
+  // Array of {meaning, role, boundingRect} objects.
+  elementSnapshot Json?
+  screen      Screen      @relation(fields: [screenId], references: [id])
+  diffs       VisualDiff[]
+
+  @@index([tenantId, projectId])
+  @@unique([screenId, viewport, gitBranch, browser])
+}
+
+model VisualDiff {
+  id                String         @id @default(cuid())
+  tenantId          String
+  baselineId        String
+  newScreenshotPath String
+  newScreenshotCloudUrl String?
+  diffImageCloudUrl     String?
+  // 0-100; 0 = identical
+  diffScore         Float
+  // NONE | MINOR | SIGNIFICANT | CRITICAL
+  changeType        String
+  // [{description, location, severity}]
+  changes           Json?
+  // APPROVE | REVIEW | FLAG | BLOCK
+  recommendation    String?
+  bugReportDraft    Json?
+  // AI-generated one-sentence summary of what changed (or "No meaningful changes detected")
+  aiSummary         String?
+  // PENDING | APPROVED | FLAGGED | BLOCKED
+  status            String         @default("PENDING")
+  reviewedBy        String?
+  bugSignalVisualDiffId String?
+  bugSignalRef          BugSignal? @relation("BugSignalVisualDiffs", fields: [bugSignalVisualDiffId], references: [id], onDelete: SetNull)
+  createdAt         DateTime       @default(now())
+  baseline          VisualBaseline @relation(fields: [baselineId], references: [id])
+
+  @@index([tenantId, baselineId])
+  @@index([status])
+}
+
+// ---- Human + AI Hybrid Review Queue ----------------------------------------
+
+model HumanReviewItem {
+  id         String    @id @default(cuid())
+  tenantId   String
+  projectId  String
+  testCaseId String
+  reason     String
+  confidence Float
+  context    Json?
+  // PENDING | IN_REVIEW | APPROVED | REJECTED
+  status     String    @default("PENDING")
+  assignedTo String?
+  resolution String?
+  reviewedAt DateTime?
+  createdAt  DateTime  @default(now())
+  testCase   TestCase  @relation(fields: [testCaseId], references: [id])
+
+  @@index([tenantId, projectId])
+  @@index([status])
+}
+
+// ---- Per-step visual evidence — persisted AI+human element matching -----------
+// One row per (testCaseId, stepIndex). Populated on first evidence fetch and
+// can be corrected by a QA reviewer (source -> 'human_verified').
+// When the parent Screen is re-crawled and elementHash changes, source is set
+// to 'stale' so reviewers know to re-verify.
+
+model StepEvidence {
+  id           String      @id @default(cuid())
+  tenantId     String
+  testCaseId   String
+  stepIndex    Int         // 0-based index matching TestCase.steps array
+  stepText     String      // snapshot of step text when evidence was computed
+
+  // The screenshot that best captures the screen state for this step.
+  // Null = use the Screen's latest screenshot (default).
+  screenshotId String?
+  screenshot   Screenshot? @relation(fields: [screenshotId], references: [id], onDelete: SetNull)
+
+  // JSON array of Element.id strings that are relevant to this step
+  elementIds   Json        @default("[]")
+
+  // Highest confidence score among matched elements (0.0-1.0)
+  confidence   Float       @default(0)
+
+  // 'ai_heuristic' | 'ai_semantic' | 'human_verified' | 'stale'
+  source       String      @default("ai_heuristic")
+
+  testCase     TestCase    @relation(fields: [testCaseId], references: [id], onDelete: Cascade)
+  createdAt    DateTime    @default(now())
+  updatedAt    DateTime    @updatedAt
+
+  @@unique([testCaseId, stepIndex])
+  @@index([tenantId, testCaseId])
+}
+
+// ---- Manual QA step validation — human-in-the-loop per-step annotation -------
+// Inspired by TestRail step results. A QA reviewer marks each step
+// PASS / FAIL / SKIP / BLOCKED and optionally uploads screenshot evidence.
+
+model StepValidation {
+  id            String   @id @default(cuid())
+  tenantId      String
+  testCaseId    String
+  stepIndex     Int      // 0-based index matching TestCase.steps array
+  // PASS | FAIL | SKIP | BLOCKED
+  result        String
+  comment       String?
+  // URL of an uploaded screenshot or other attachment (S3 cloudUrl)
+  attachmentUrl String?
+  // Optional: ties this validation to a specific TestCaseRun
+  testCaseRunId String?
+  testCaseRun   TestCaseRun? @relation(fields: [testCaseRunId], references: [id], onDelete: SetNull)
+  reviewerId    String?
+  reviewer      User?    @relation(fields: [reviewerId], references: [id], onDelete: SetNull)
+  createdAt     DateTime @default(now())
+  testCase      TestCase @relation(fields: [testCaseId], references: [id], onDelete: Cascade)
+
+  @@index([tenantId, testCaseId])
+  @@index([testCaseId, stepIndex])
+}
+
+// ---- Per-Test-Case Execution Runs ------------------------------------------
+
+model TestCaseRun {
+  id             String    @id @default(cuid())
+  testCaseId     String
+  tenantId       String
+  // PENDING | RUNNING | PASSED | FAILED | ERROR | FLAKY (maxRuns>1, outcomes diverged)
+  status         String    @default("PENDING")
+  // Array<ExecutionStep> generated by test-script-agent
+  executionPlan  Json?
+  // Array<StepResult> from executor
+  stepResults    Json?
+  totalDuration  Int?
+  // 0-indexed step number that failed
+  errorStep      Int?
+  errorMessage   String?
+  screenshotPath String?
+  viewport       String    @default("DESKTOP")
+  // chromium | firefox | webkit — engine used for this run (executeTestPlan already
+  // supports all 3; this just records/selects which one)
+  browser        String    @default("chromium")
+  createdAt      DateTime  @default(now())
+  completedAt    DateTime?
+  testCase       TestCase  @relation(fields: [testCaseId], references: [id], onDelete: Cascade)
+  stepValidations StepValidation[]
+
+  @@index([tenantId, testCaseId])
+  @@index([tenantId, status, createdAt])
+}
+
+// ---- Test Run Tracking -----------------------------------------------------
+
+model TestRun {
+  id          String       @id @default(cuid())
+  tenantId    String
+  projectId   String
+  suiteId     String?
+  // MANUAL | SCHEDULED | GIT_PUSH | POST_CRAWL | GITHUB_ACTION
+  trigger     String       @default("MANUAL")
+  // RUNNING | COMPLETED | FAILED | CANCELLED
+  status      String       @default("RUNNING")
+  // {browser, viewport, baseUrl, env, browsers?: string[], shards?: number}
+  config      Json?
+  // {total, passed, failed, skipped, duration}
+  summary     Json?
+  // Parallel shard config — null means single-shard (legacy) run
+  totalShards Int?
+  // CI/CD integration fields
+  githubRepo  String?
+  githubSha   String?
+  githubRef   String?
+  triggeredBy String?
+  startedAt   DateTime     @default(now())
+  finishedAt  DateTime?
+  project     Project      @relation(fields: [projectId], references: [id], onDelete: Cascade)
+  results     TestResult[]
+  shards      TestRunShard[]
+
+  @@index([tenantId, projectId])
+  @@index([status])
+}
+
+// One row per parallel shard within a TestRun.
+// Each shard runs a subset of test cases, optionally on a different browser.
+model TestRunShard {
+  id         String    @id @default(cuid())
+  runId      String
+  tenantId   String
+  shardIndex Int       // 0-based index within the run
+  browser    String    @default("chromium") // chromium | firefox | webkit
+  // PENDING | RUNNING | COMPLETED | FAILED
+  status     String    @default("PENDING")
+  // {total, passed, failed, skipped, duration}
+  summary    Json?
+  startedAt  DateTime?
+  finishedAt DateTime?
+  run        TestRun   @relation(fields: [runId], references: [id], onDelete: Cascade)
+
+  @@unique([runId, shardIndex, browser])
+  @@index([runId])
+  @@index([tenantId])
+}
+
+model TestResult {
+  id                String    @id @default(cuid())
+  tenantId          String
+  runId             String
+  testCaseId        String
+  // PASSED | FAILED | SKIPPED | ERROR
+  status            String
+  duration          Int?
+  error             String?
+  screenshotPath    String?
+  logs              Json?
+  healedAt          DateTime?
+  // AI-generated root cause summary (Phase 4.1)
+  failureAnalysis   String?
+  failureAnalysisAt DateTime?
+  // Data-driven execution — which row produced this result (Phase 4.3)
+  dataRowId         String?
+  dataRowIndex      Int?
+  bugSignalId       String?
+  bugSignalRef      BugSignal? @relation("BugSignalTestResults", fields: [bugSignalId], references: [id], onDelete: SetNull)
+  run               TestRun   @relation(fields: [runId], references: [id])
+  testCase          TestCase  @relation(fields: [testCaseId], references: [id])
+
+  @@index([tenantId, runId])
+  @@index([tenantId, runId, status])
+  @@index([testCaseId])
+}
+
+// ---- Connectors, audit, change tracking ------------------------------------
+
+model Connector {
+  id        String   @id @default(cuid())
+  tenantId  String
+  projectId String
+  // GITHUB | JIRA | FIGMA | CONFLUENCE | PAGERDUTY | SERVICENOW | SALESFORCE
+  kind      String
+  // A reference/handle to where credentials live in the secrets manager.
+  // NEVER store raw secrets in the database.
+  secretRef String
+  config    Json?
+  createdAt DateTime @default(now())
+  project   Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+
+  @@index([tenantId, projectId])
+}
+
+// OAuth 2.0 connections — replaces manual token entry in Connector.
+// All token fields use the _enc suffix and are AES-256-GCM encrypted at rest.
+// Never return raw token values in API responses.
+model OAuthConnection {
+  id        String   @id @default(cuid())
+  tenantId  String
+  projectId String
+
+  // GITHUB | JIRA | FIGMA
+  provider  String
+
+  // Encrypted access token (AES-256-GCM, base64).
+  // Null for GitHub App (uses IAT generated on-the-fly from private key).
+  accessToken_enc       String?
+  // Encrypted refresh token. Null for GitHub App.
+  // Jira: rotating — always store new one issued on refresh.
+  refreshToken_enc      String?
+  // When the access token expires. Null = does not expire (rare).
+  tokenExpiresAt        DateTime?
+  // When the refresh token expires (Jira ~180 days unused; GitHub 6 months).
+  refreshTokenExpiresAt DateTime?
+
+  // CONNECTED | NEEDS_REAUTH | DISCONNECTED
+  // Only set to NEEDS_REAUTH on definitive auth errors (400/401 with invalid_grant).
+  // Proactive refresh failures use backoff, not status change.
+  status    String   @default("CONNECTED")
+
+  // Human-readable identity — who/what authorized this connection.
+  // e.g. "Acme Corp (org)" for GitHub App, "user@company.atlassian.net" for Jira.
+  connectedAs String?
+
+  // GitHub App: numeric installation ID (needed to generate IAT)
+  installationId String?
+
+  // Jira Cloud: cloudId from /oauth/token/accessible-resources
+  // Required to construct API base URL: api.atlassian.com/ex/jira/{cloudId}/...
+  cloudId   String?
+
+  // Granted OAuth scopes (space-separated string or JSON array as string)
+  scopes    String?
+
+  // Encrypted PAT — fallback for Jira Data Center / on-prem (no 3LO available)
+  pat_enc   String?
+  // Jira Data Center base URL (e.g. https://jira.internal.company.com)
+  dcBaseUrl String?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+  project   Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+
+  // One active connection per provider per project
+  @@unique([projectId, provider])
+  @@index([tenantId, projectId])
+  @@index([tenantId, provider])
+  @@index([status])
+}
+
+// A real, revocable login session — the row's id IS the JWT's `jti` claim.
+// checked on every request (see resolveContext in packages/api). Deliberately
+// distinct from UserSession (that model is unrelated: recorded browser test
+// sessions for replay/conversion, nothing to do with authentication).
+// Admin-impersonation tokens get one too (minted via mintSessionToken, same
+// as a real login) so "Stop Impersonating" can actually revoke it server-side
+// instead of only clearing the admin's local browser storage — the 30-minute
+// natural expiry alone isn't enough for a privileged-access session that's
+// meant to be endable on demand. Not created for the transient "root" token
+// issued when a login can't yet pick a single tenant (that token alone can't
+// reach any tenant-scoped route, so there is nothing meaningful to revoke).
+model AuthSession {
+  id         String    @id  // JWT jti claim — set from crypto.randomUUID() in mintSessionToken()
+  userId     String
+  tenantId   String
+  userAgent  String?
+  ipAddress  String?
+  createdAt  DateTime  @default(now())
+  lastSeenAt DateTime  @default(now())
+  revokedAt  DateTime?
+
+  @@index([userId])
+  @@index([tenantId])
+}
+
+// One-time backup codes for TOTP MFA recovery (each usable exactly once)
+model MfaRecoveryCode {
+  id        String    @id @default(cuid())
+  userId    String
+  codeHash  String    // bcrypt hash of the plain recovery code
+  usedAt    DateTime?
+  createdAt DateTime  @default(now())
+  user      User      @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@index([userId])
+}
+
+// SSO configuration per tenant (SAML 2.0 or OIDC)
+model SsoConfig {
+  id                String   @id @default(cuid())
+  tenantId          String   @unique
+  provider          String   // "SAML" | "OIDC"
+  // SAML fields
+  entryPoint        String?  // IdP SSO URL
+  issuer            String?  // IdP entity ID / OIDC issuer URL
+  cert              String?  // IdP signing certificate (PEM)
+  // OIDC fields
+  clientId          String?
+  clientSecret_enc  String?  // AES-256-GCM encrypted
+  // Common
+  defaultRole       String   @default("TESTER")
+  emailDomains      String[]                 // permitted email domains for JIT provisioning; empty = allow all
+  jitProvisioning   Boolean  @default(false) // auto-create users on first SSO login
+  enabled           Boolean  @default(false)
+  // When true, password login is rejected for members of this tenant who
+  // have an active membership here — they must use SSO. Defaults to false
+  // (opt-in) so configuring SSO doesn't silently lock out existing password
+  // users. See docs/100-GAPS-RBAC-SECURITY-ENTERPRISE.md §1 #42 (SSO-02).
+  ssoRequired       Boolean  @default(false)
+  // SCIM 2.0 bearer token for this tenant, stored as a SHA-256 hash (same
+  // pattern as AgentToken.tokenHash) — never the plaintext, which is shown
+  // once at generation time. Nullable: SCIM is off until an admin generates
+  // one. Previously this field didn't exist at all, so per-tenant SCIM could
+  // never work — see docs/100-GAPS-RBAC-SECURITY-ENTERPRISE.md §3 NEW-1.
+  scimTokenHash     String?  @unique
+  createdAt         DateTime @default(now())
+  updatedAt         DateTime @updatedAt
+  tenant            Tenant   @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+}
+
+// Audit trail for compliance (SOC 2 / EU AI Act) — Phase 3 expands this.
+model AuditLog {
+  id        String   @id @default(cuid())
+  tenantId  String
+  projectId String?
+  actorId   String?
+  action    String
+  detail    Json?
+  ipAddress String?
+  createdAt DateTime @default(now())
+  project   Project? @relation(fields: [projectId], references: [id], onDelete: SetNull)
+  user      User?    @relation(fields: [actorId], references: [id])
+  tenant    Tenant   @relation(fields: [tenantId], references: [id])
+
+  @@index([tenantId, createdAt])
+  @@index([tenantId, action])
+}
+
+model AccessReview {
+  id           String   @id @default(cuid())
+  tenantId     String
+  reviewedBy   String
+  memberCount  Int
+  removedCount Int      @default(0)
+  completedAt  DateTime @default(now())
+  tenant       Tenant   @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+
+  @@index([tenantId])
+}
+
+// Local agent pairing token — hashed, never stored plain.
+model AgentToken {
+  id              String    @id @default(cuid())
+  tenantId        String
+  projectId       String?
+  name            String
+  tokenHash       String    @unique
+  lastSeenAt      DateTime?
+  revokedAt       DateTime?
+  createdAt       DateTime  @default(now())
+  expiresAt       DateTime?
+  createdByUserId String?
+  project         Project?  @relation(fields: [projectId], references: [id], onDelete: SetNull)
+  createdByUser   User?     @relation(fields: [createdByUserId], references: [id])
+
+  @@index([tenantId, projectId])
+}
+
+// Outbound webhook — ZeTa posts events to this URL on crawl/test changes.
+model Webhook {
+  id        String   @id @default(cuid())
+  tenantId  String
+  projectId String
+  url       String
+  // HMAC secret, AES-256-GCM encrypted at application layer.
+  secret_enc String
+  // JSON array of event names, e.g. ["crawl.done","test.generated"]
+  events    Json     @default("[]")
+  active    Boolean  @default(true)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+  project   Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+  deliveries WebhookDelivery[]
+
+  @@index([tenantId, projectId])
+}
+
+// One row per delivery attempt (dispatch retries on failure, so a single
+// logical event can produce several rows sharing the same event/payload with
+// increasing `attempt`). Storing the payload lets a failed delivery be
+// manually redelivered later with the exact original body.
+model WebhookDelivery {
+  id         String   @id @default(cuid())
+  webhookId  String
+  tenantId   String
+  event      String
+  payload    Json
+  attempt    Int      @default(1)
+  status     String   // SUCCESS | FAILED
+  httpStatus Int?
+  error      String?
+  createdAt  DateTime @default(now())
+  webhook    Webhook  @relation(fields: [webhookId], references: [id], onDelete: Cascade)
+
+  @@index([webhookId, createdAt])
+  @@index([webhookId, status])
+}
+
+// Phase 3: Perceptual screenshot diff — crawl-to-crawl visual change detection
+model ScreenDiff {
+  id            String   @id @default(cuid())
+  tenantId      String
+  projectId     String
+  screenId      String
+  fromVersion   Int
+  toVersion     Int
+  // (hammingDistance / 64) * 100, rounded to 1 decimal. 0–100.
+  pHashDistance Float
+  // "IDENTICAL" | "MINOR" | "MODERATE" | "SIGNIFICANT"
+  changeLevel   String
+  createdAt     DateTime @default(now())
+  screen        Screen   @relation(fields: [screenId], references: [id])
+
+  @@unique([screenId, fromVersion, toVersion])
+  @@index([tenantId, projectId])
+  @@index([tenantId, screenId])
+}
+
+// Phase 5: Structured probe observations — typed facts from interactive probe
+model ProbeObservation {
+  id              String   @id @default(cuid())
+  tenantId        String
+  projectId       String
+  screenId        String
+  elementMeaning  String
+  // VALIDATION_ERROR | MODAL | SUCCESS_TOAST | CONDITIONAL_REVEAL | LOADING_STATE
+  observationType String
+  observedText    String
+  // "empty_submit" | "invalid_format" | "button_click:{label}" | "select_change:{label}:{value}"
+  triggeredBy     String
+  observedAt      DateTime @default(now())
+  screen          Screen   @relation(fields: [screenId], references: [id])
+
+  @@index([tenantId, projectId])
+  @@index([tenantId, screenId])
+  @@index([tenantId, screenId, observationType])
+}
+
+// Records what changed between crawls (Differential Engine — Phase 6).
+model ChangeLog {
+  id        String   @id @default(cuid())
+  tenantId  String
+  projectId String
+  // ADDED | REMOVED | MODIFIED
+  changeType String
+  summary    String
+  detail     Json?
+  createdAt  DateTime @default(now())
+  project    Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+
+  @@index([tenantId, projectId])
+}
+
+// Full-text search index — one row per heading-delimited section of a skill file or artifact.
+// The `tsv` tsvector column is GENERATED ALWAYS AS in Postgres (see migration 0014).
+// Prisma does not manage tsv — it is invisible to Prisma and updated automatically by Postgres.
+model KnowledgeChunk {
+  id         String   @id @default(cuid())
+  tenantId   String
+  projectId  String?  // null = global / research docs available to all projects
+  sourceType String   // SKILL_FILE | ARTIFACT | SCREEN
+  sourceId   String   // ID of the parent SkillFile or ProjectArtifact
+  imagePath  String?  // Base64 or local path for vision-grounded chunks
+  heading    String
+  content    String
+  // tsv is a GENERATED ALWAYS AS STORED tsvector column managed entirely by Postgres.
+  // Declared Unsupported so Prisma never tries to write it (and never drops it).
+  tsv        Unsupported("tsvector")?
+  updatedAt  DateTime @updatedAt
+
+  @@index([tenantId, projectId])
+  @@index([sourceId])
+}
+
+// ---- Token Optimisation & Ledger -------------------------------------------
+
+model LLMCallLog {
+  id               String   @id @default(cuid())
+  tenantId         String
+  projectId        String?
+
+  // What triggered this call
+  jobId            String?  // FK to PlatformJob (if inside a job)
+  agentType        String   // 'test_case' | 'skill_file' | 'flow' | 'nlp' | 'script' | 'data' | 'visual'
+  label            String   // 'pass1_functional' | 'skill_file_TECH_STACK' | 'flow_journey'
+  entityId         String?  // TestCase.id or SkillFile.id this call produced/contributed to
+  entityType       String?  // 'test_case' | 'skill_file' | 'script' | 'test_data'
+
+  // Provider
+  provider         String
+  model            String
+
+  // Token counts
+  promptTokens     Int
+  completionTokens Int
+  cacheReadTokens  Int      @default(0)
+  cacheWriteTokens Int      @default(0)
+  totalTokens      Int
+
+  // Cost
+  estimatedCostUsd Float    @default(0)
+
+  // Response quality
+  outputTokens     Int?     // alias completionTokens
+  latencyMs        Int?
+
+  taskType         String?
+  calledAt         DateTime @default(now())
+
+  @@index([tenantId, projectId])
+  @@index([tenantId, jobId])
+  @@index([tenantId, agentType])
+  @@index([entityId])
+  @@index([calledAt])
+}
+
+model TokenBudget {
+  id                  String   @id @default(cuid())
+  tenantId            String   @unique
+  monthlyTokenCap     Int?
+  monthlyUsdCap       Float?
+  alertAtPercent      Int      @default(80)
+  currentMonthTokens  Int      @default(0)
+  currentMonthUsd     Float    @default(0)
+  lastResetAt         DateTime @default(now())
+  updatedAt           DateTime @updatedAt
+  tenant              Tenant   @relation(fields: [tenantId], references: [id])
+}
+
+model Notification {
+  id         String   @id @default(cuid())
+  tenantId   String
+  userId     String
+  type       String
+  title      String
+  body       String
+  metadata   Json?
+  read       Boolean  @default(false)
+  createdAt  DateTime @default(now())
+  tenant     Tenant   @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+  user       User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+  @@index([tenantId, userId, read])
+  @@index([tenantId, createdAt])
+}
+
+model NotificationPreference {
+  id        String   @id @default(cuid())
+  tenantId  String
+  userId    String
+  eventType String
+  inApp     Boolean  @default(true)
+  email     Boolean  @default(true)
+  tenant    Tenant   @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+  user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+  @@unique([userId, tenantId, eventType])
+  @@index([tenantId, userId])
+}
+
+// ─── Platform System Configuration ───────────────────────────────────────────
+// Key-value store for platform-wide settings managed via admin panel.
+// Replaces env vars for runtime-changeable config (SMTP, LLM, OAuth app creds).
+// Sensitive values are AES-256-GCM encrypted before storage.
+// Env vars remain as fallback if no DB row exists.
+
+model SystemConfig {
+  key              String   @id
+  value            String
+  category         String
+  sensitive        Boolean  @default(false)
+  updatedAt        DateTime @updatedAt
+  updatedByAdminId String?
+
+  @@index([category])
+}
+
+// ---- App Fields (form field schema per project) ----------------------------
+
+model AppField {
+  id            String   @id @default(cuid())
+  tenantId      String
+  projectId     String
+  fieldKey      String
+  label         String
+  elementRole   String
+  dataBearing   Boolean  @default(true)
+  dataType      String
+  required      Boolean  @default(false)
+  minLength     Int?
+  maxLength     Int?
+  minValue      Float?
+  maxValue      Float?
+  precision     Int?
+  regex         String?
+  enumValues    Json?
+  piiClass      String   @default("unknown")
+  exampleValue  String?
+  relationGroup String?
+  notes         String?
+  status        String   @default("unconfirmed")
+  createdAt     DateTime @default(now())
+  updatedAt     DateTime @updatedAt
+  project       Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+
+  @@unique([tenantId, projectId, fieldKey])
+  @@index([tenantId, projectId])
+}
+
+// ---- Workspace Connectors (third-party service credentials per tenant) ------
+
+model WorkspaceConnector {
+  id        String   @id @default(cuid())
+  tenantId  String
+  kind      String
+  secretRef String   @default("local-aes256")
+  config    Json?
+  testOk    Boolean  @default(false)
+  testedAt  DateTime?
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([tenantId, kind])
+  @@index([tenantId])
+}
+
+// ---- Shared Run Tokens (shareable signed links to test run results) ---------
+
+model SharedRunToken {
+  id        String   @id
+  tenantId  String
+  runId     String
+  token     String   @unique
+  expiresAt DateTime
+  createdAt DateTime @default(now())
+
+  @@index([tenantId])
+  @@index([token])
+}
+
+// ---- Native App Builds -----------------------------------------------------
+
+model NativeAppBuild {
+  id          String   @id @default(cuid())
+  tenantId    String
+  projectId   String
+  platform    String
+  fileFormat  String
+  fileName    String?
+  s3Path      String
+  packageName String?
+  version     String?
+  uploadedAt  DateTime @default(now())
+  project     Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+
+  @@index([tenantId, projectId])
+}
+
+// ---- Performance Snapshots -------------------------------------------------
+
+model PerformanceSnapshot {
+  id              String   @id @default(cuid())
+  tenantId        String
+  screenId        String
+  crawlJobId      String
+  lcp             Float?
+  fcp             Float?
+  cls             Float?
+  ttfb            Float?
+  viewport        String   @default("DESKTOP")
+  lighthousePerf  Float?
+  lighthouseA11y  Float?
+  lighthouseSEO   Float?
+  lighthouseBP    Float?
+  capturedAt      DateTime @default(now())
+
+  @@index([tenantId, screenId])
+  @@index([tenantId, crawlJobId])
+}
+
+// ---- Project Environments --------------------------------------------------
+
+model ProjectEnvironment {
+  id              String   @id @default(cuid())
+  tenantId        String
+  projectId       String
+  name            String
+  baseUrl         String
+  credentials_enc String?
+  isDefault       Boolean  @default(false)
+  createdAt       DateTime @default(now())
+  updatedAt       DateTime @updatedAt
+  project         Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+
+  @@index([tenantId, projectId])
+}
+
+// ---- Project Members -------------------------------------------------------
+
+model ProjectMember {
+  id        String @id @default(cuid())
+  tenantId  String
+  projectId String
+  userId    String
+  project   Project @relation(fields: [projectId], references: [id], onDelete: Cascade)
+
+  @@unique([projectId, userId])
+  @@index([tenantId, userId])
+}
+
+// ---- Comments --------------------------------------------------------------
+
+model Comment {
+  id         String   @id @default(cuid())
+  tenantId   String
+  parentType String
+  parentId   String
+  userId     String?
+  user       User?    @relation(fields: [userId], references: [id], onDelete: SetNull)
+  body       String
+  createdAt  DateTime @default(now())
+  updatedAt  DateTime @updatedAt
+
+  @@index([tenantId, parentType, parentId])
+}
+
+// ---- Requirements ----------------------------------------------------------
+
+model Requirement {
+  id                  String   @id @default(cuid())
+  tenantId            String
+  projectId           String
+  reqId               String
+  title               String
+  actor               String?
+  type                String   @default("functional")
+  priority            String   @default("HIGH")
+  acceptanceCriteria  Json     @default("[]")
+  businessRules       Json     @default("[]")
+  relatedScreenHints  Json     @default("[]")
+  sourceSection       String?
+  derived             Boolean  @default(false)
+  status              String   @default("pending")
+  source              String   @default("AI_GENERATED")
+  // External tracker metadata (Jira): { url, issueType, status, epic, labels, components, links, subtasks }
+  externalMeta        Json?
+  // Append-only history of content changes. Each entry: { version, changedAt, changedFields, snapshot }
+  changeLog           Json     @default("[]")
+  createdAt           DateTime @default(now())
+  updatedAt           DateTime @updatedAt
+  project             Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+  scenarios           Scenario[]
+
+  @@unique([tenantId, projectId, reqId])
+  @@index([tenantId, projectId])
+  @@index([tenantId, projectId, priority])
+  @@index([tenantId, projectId, status])
+  @@index([tenantId, projectId, sourceSection])
+}
+
+// ---- Scenarios --------------------------------------------------------------
+
+model Scenario {
+  id            String   @id @default(cuid())
+  tenantId      String
+  projectId     String
+  requirementId String
+  title         String
+  description   String?
+  gherkin       String   @db.Text
+  status        String   @default("draft")   // draft | approved | rejected
+  version       Int      @default(1)
+  source        String   @default("AI_GENERATED")
+  createdAt     DateTime @default(now())
+  updatedAt     DateTime @updatedAt
+
+  requirement   Requirement @relation(fields: [requirementId], references: [id], onDelete: Cascade)
+  testCases     TestCase[]
+
+  @@index([tenantId, projectId])
+  @@index([requirementId])
+}
+
+// ---- Extension Captures ----------------------------------------------------
+
+model ExtensionCapture {
+  id           String   @id @default(cuid())
+  tenantId     String
+  projectId    String
+  kind         String
+  s3Url        String?
+  entryCount   Int      @default(0)
+  capturedAt   DateTime @default(now())
+  createdAt    DateTime @default(now())
+  metadata     Json?
+  project      Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+  interactions ExtensionInteraction[]
+
+  @@index([tenantId, projectId])
+  @@index([tenantId, projectId, kind])
+  @@index([tenantId, projectId, capturedAt])
+}
+
+model ExtensionInteraction {
+  id        String  @id @default(cuid())
+  tenantId  String
+  captureId String
+  type      String
+  selector  String?
+  xpath     String?
+  tagName   String?
+  value     String?
+  url       String?
+  timestamp BigInt?
+  metadata  Json?
+  capture   ExtensionCapture @relation(fields: [captureId], references: [id], onDelete: Cascade)
+
+  @@index([tenantId, captureId])
+  @@index([captureId])
+}
+
+model ExtensionError {
+  id           String   @id @default(cuid())
+  tenantId     String
+  projectId    String
+  pageUrl      String?
+  kind         String
+  level        String   @default("error")
+  text         String
+  url          String?
+  lineNumber   Int?
+  columnNumber Int?
+  stackTrace   Json?
+  source       String?
+  capturedAt   DateTime @default(now())
+  createdAt    DateTime @default(now())
+  project      Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+
+  @@index([tenantId, projectId])
+  @@index([tenantId, projectId, pageUrl])
+  @@index([tenantId, projectId, kind])
+  @@index([tenantId, projectId, level])
+  @@index([tenantId, projectId, capturedAt])
+}
+
+// ---- Billing / Plan Enforcement --------------------------------------------
+
+model TenantPlanConfig {
+  tier                 String   @id
+  maxProjects          Int
+  maxMembers           Int
+  maxSessions          Int
+  maxCrawlsPerMonth    Int
+  maxRunsPerMonth      Int
+  maxShards            Int
+  maxTokensPerMonth    Int
+  createdAt            DateTime @default(now())
+  updatedAt            DateTime @updatedAt
+}
+
+model TenantPlan {
+  tenantId             String   @id
+  tier                 String   @default("TRIAL")  // TRIAL | STARTER | GROWTH | ENTERPRISE
+  stripeCustomerId     String?
+  stripeSubscriptionId String?
+  trialEndsAt          DateTime?
+  maxProjects          Int
+  maxMembers           Int
+  maxSessions          Int
+  maxCrawlsPerMonth    Int
+  maxRunsPerMonth      Int
+  maxShards            Int
+  maxTokensPerMonth    Int
+  currentCrawls        Int      @default(0)
+  currentRuns          Int      @default(0)
+  lastResetAt          DateTime @default(now())
+  updatedAt            DateTime @updatedAt
+  tenant               Tenant   @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+}
+
+// ---- Platform Admin --------------------------------------------------------
+
+model AdminUser {
+  id                String                 @id @default(cuid())
+  email             String                 @unique
+  passwordHash      String
+  name              String?
+  role              String                 @default("SUPER_ADMIN") // SUPER_ADMIN | SUPPORT
+  mfaEnabled        Boolean                @default(false)
+  mfaSecret_enc     String?
+  mfaVerifiedAt     DateTime?
+  lastLoginAt       DateTime?              // updated on every successful login (F-009)
+  failedLoginCount  Int                    @default(0)  // consecutive failures since last success; reset on login (F-010)
+  lastFailedLoginAt DateTime?              // timestamp of most recent failed attempt (F-010)
+  createdAt         DateTime               @default(now())
+  updatedAt         DateTime               @default(now())
+  mfaRecoveryCodes  AdminMfaRecoveryCode[]
+  mfaChallenges     AdminMfaChallenge[]
+  authSessions      AdminAuthSession[]
+}
+
+model AdminAuthSession {
+  id         String    @id  // JWT jti claim — set from crypto.randomUUID() in mintSessionToken()
+  adminId    String
+  userAgent  String?
+  ipAddress  String?
+  createdAt  DateTime  @default(now())
+  lastSeenAt DateTime  @default(now())
+  revokedAt  DateTime?
+  admin      AdminUser @relation(fields: [adminId], references: [id], onDelete: Cascade)
+
+  @@index([adminId])
+  @@index([lastSeenAt])
+}
+
+model AdminMfaRecoveryCode {
+  id        String    @id @default(cuid())
+  adminId   String
+  codeHash  String
+  usedAt    DateTime?
+  createdAt DateTime  @default(now())
+  admin     AdminUser @relation(fields: [adminId], references: [id], onDelete: Cascade)
+
+  @@index([adminId])
+}
+
+model AdminMfaChallenge {
+  id        String    @id
+  adminId   String
+  purpose   String
+  expiresAt DateTime
+  usedAt    DateTime?
+  createdAt DateTime  @default(now())
+  admin     AdminUser @relation(fields: [adminId], references: [id], onDelete: Cascade)
+
+  @@index([adminId, purpose, usedAt])
+  @@index([expiresAt])
+}
+
+// ---- DB-driven built-in role permissions -----------------------------------
+// Stores the permission sets for the 6 built-in roles (OWNER, ADMIN, etc.).
+// Seeded on first deploy; editable by platform super-admins at runtime.
+// The middleware reads from here (with a 60s in-memory cache) instead of
+// the hardcoded ROLE_PERMISSIONS map in @detiq/core.
+model RoleConfig {
+  roleName    String   @id              // 'OWNER' | 'ADMIN' | 'QA_LEAD' | 'TESTER' | 'DEVELOPER' | 'VIEWER'
+  rank        Int      @unique          // 0=VIEWER … 5=OWNER — used for privilege-escalation checks
+  permissions String[]                  // array of Permission strings
+  updatedAt   DateTime @updatedAt
+
+  @@map("role_configs")
+}
+
+// ---- Slack Integration (OAuth Bot token per workspace) ----------------------
+
+model SlackConnection {
+  id              String   @id @default(cuid())
+  tenantId        String   @unique
+  teamId          String
+  teamName        String
+  channelId       String
+  channelName     String
+  accessToken_enc String   // AES-256-GCM encrypted Bot token
+  installedBy     String   // userId of the member who ran /slack/install
+  createdAt       DateTime @default(now())
+  updatedAt       DateTime @updatedAt
+  tenant          Tenant   @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+}
+
+// ---- Microsoft Teams Integration (Power Automate webhook) ------------------
+
+model TeamsConnection {
+  id           String   @id @default(cuid())
+  tenantId     String   @unique
+  webhookUrl   String   // Power Automate incoming webhook URL
+  channelName  String?
+  installedBy  String
+  createdAt    DateTime @default(now())
+  updatedAt    DateTime @updatedAt
+  tenant       Tenant   @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+}
+
+// ---- SILO Isolation Config (Phase 3.2) -------------------------------------
+
+model TenantSiloConfig {
+  tenantId             String   @id
+  connectionString_enc String
+  encryptionKeyRef     String   @default("default")
+  provisionedAt        DateTime @default(now())
+  tenant               Tenant   @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+}
+
+// ---- Data-Driven Test Execution (Phase 4.3) ---------------------------------
+
+model TestDataSet {
+  id             String        @id @default(cuid())
+  tenantId       String
+  projectId      String
+  name           String
+  // SYNTHETIC | PRODUCTION | STAGING | SANDBOX | DUMMY | IMPORTED
+  classification String        @default("SYNTHETIC")
+  // Free-form environment label e.g. "Production", "UAT", "QA-01"
+  environment    String?
+  rows           TestDataRow[]
+  testCases      TestCase[]
+  createdAt      DateTime      @default(now())
+  project        Project       @relation(fields: [projectId], references: [id], onDelete: Cascade)
+
+  @@index([tenantId, projectId])
+  @@index([tenantId, classification])
+}
+
+model TestDataRow {
+  id        String      @id @default(cuid())
+  tenantId  String
+  dataSetId String
+  rowIndex  Int
+  data      Json        // { fieldName: value } — e.g. { "username": "alice", "password": "pass1" }
+  dataSet   TestDataSet @relation(fields: [dataSetId], references: [id], onDelete: Cascade)
+
+  @@unique([dataSetId, rowIndex])
+  @@index([tenantId])
+}
+
+// ---- Framework Modernization — Phase 2: GitHub Repo Integration -------------
+
+// One row per connected GitHub automation repo per project.
+model GitHubRepoConnection {
+  id              String   @id @default(cuid())
+  tenantId        String
+  projectId       String
+  createdBy       String                   // userId who connected the repo
+  // "owner/repo"
+  repoFullName    String
+  defaultBranch   String   @default("main")
+  // AES-256-GCM: "<iv>:<authTag>:<ciphertext>"
+  tokenEnc        String
+  // ACTIVE | NEEDS_REAUTH | ERROR | DISCONNECTED
+  status          String   @default("ACTIVE")
+  // PAT | GITHUB_APP | FINE_GRAINED_PAT
+  authMethod      String   @default("PAT")
+  // Detected from config files: playwright-ts | cypress-ts | pytest | junit | etc.
+  detectedFramework String?
+  configFilePath  String?  // e.g. "playwright.config.ts"
+  testGlob        String?  // e.g. "**/*.spec.ts"
+  // Regex to extract test IDs from test titles
+  testIdPattern   String   @default("TC-[A-Z]+-\\d+")
+  // JSON: extracted style conventions for aligned script generation (Phase 3)
+  styleProfile    Json?
+  // Compressed JSON tree from last scan (stored as base64 gzip)
+  treeSnapshot    String?  @db.Text
+  // IDLE | SCANNING | DONE | FAILED
+  scanStatus      String   @default("IDLE")
+  scanError       String?
+  testFileCount   Int      @default(0)
+  extractedIdCount Int     @default(0)
+  lastScannedAt   DateTime?
+  lastSyncAt      DateTime?
+  // JSON array of PageObjectSummary — populated during repo scan
+  pageObjectInventory Json?
+  // GitHub App installation ID (for GitHub App auth)
+  installationId  Int?
+  createdAt       DateTime @default(now())
+  updatedAt       DateTime @updatedAt
+
+  project         Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+  repoTestFiles   RepoTestFile[]
+  coverageMappings CoverageMapping[]
+  gitHubPRs       GitHubPR[]
+
+  @@index([tenantId, projectId])
+  @@index([tenantId, status])
+}
+
+// One row per test file discovered in the connected repo.
+model RepoTestFile {
+  id               String   @id @default(cuid())
+  tenantId         String
+  projectId        String
+  repoConnectionId String
+  // Repo-root-relative path, forward slashes, no leading slash
+  filePath         String
+  framework        String   // playwright-ts | cypress-ts | pytest | etc.
+  // string[] of extracted test IDs / names
+  extractedIds     Json     @default("[]")
+  // First 2000 chars — used for style extraction
+  rawSample        String?  @db.Text
+  lastScannedAt    DateTime @default(now())
+
+  repoConnection   GitHubRepoConnection @relation(fields: [repoConnectionId], references: [id], onDelete: Cascade)
+
+  @@unique([repoConnectionId, filePath])
+  @@index([tenantId, projectId])
+  @@index([repoConnectionId])
+}
+
+// One row per TestCase — tracks mapping to a repo script file.
+model CoverageMapping {
+  id               String   @id @default(cuid())
+  tenantId         String
+  projectId        String
+  testCaseId       String   @unique
+  repoConnectionId String
+  // MAPPED | UNMAPPED | AMBIGUOUS
+  status           String   @default("UNMAPPED")
+  matchedFilePath  String?  // relative path in repo
+  scriptTestName   String?  // matched test name inside the file
+  lineNumber       Int?
+  // 0.0–1.0
+  confidence         Float?
+  requirementScore   Float?   // cross-encoder quality score: how well TC covers its linked requirement (0.0–1.0)
+  suggestedReqId     String?  // for UNMAPPED TCs: best-match requirement ID from cross-encoder
+  suggestedReqScore  Float?   // cross-encoder confidence for the suggestion (0.0–1.0)
+  // EXACT | NORMALIZED | FUZZY | AI | MANUAL
+  matchMethod      String?
+  manualOverride   Boolean  @default(false)
+  confirmedBy      String?  // userId
+  confirmedAt      DateTime?
+  createdAt        DateTime @default(now())
+  updatedAt        DateTime @updatedAt
+
+  testCase         TestCase @relation(fields: [testCaseId], references: [id], onDelete: Cascade)
+  repoConnection   GitHubRepoConnection @relation(fields: [repoConnectionId], references: [id], onDelete: Cascade)
+
+  @@index([tenantId, projectId])
+  @@index([repoConnectionId])
+  @@index([status, projectId])
+}
+
+// Time-series snapshot of coverage % for the dashboard trend chart.
+model CoverageSnapshot {
+  id              String   @id @default(cuid())
+  tenantId        String
+  projectId       String
+  totalCases      Int
+  mappedCases     Int
+  unmappedCases   Int
+  ambiguousCases  Int
+  coveragePercent Float
+  snapshotAt      DateTime @default(now())
+
+  project         Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+
+  @@index([tenantId, projectId, snapshotAt])
+}
+
+// Tracks GitHub PRs created by ZeTa (one per automated push batch).
+model GitHubPR {
+  id               String   @id @default(cuid())
+  tenantId         String
+  projectId        String
+  repoConnectionId String
+  prNumber         Int
+  prUrl            String
+  branch           String
+  headSha          String
+  // OPEN | MERGED | CLOSED
+  status           String   @default("OPEN")
+  // Which crawl job triggered this PR (optional)
+  crawlJobId       String?
+  // How many scripts are in this PR
+  scriptCount      Int      @default(0)
+  // ZeTa-generated PR body text
+  prBody           String?  @db.Text
+  createdAt        DateTime @default(now())
+  updatedAt        DateTime @updatedAt
+
+  repoConnection   GitHubRepoConnection @relation(fields: [repoConnectionId], references: [id], onDelete: Cascade)
+
+  @@index([tenantId, projectId])
+  @@index([repoConnectionId])
+  @@index([tenantId, status])
+}
+
+// ---- IDE Push Tokens (one-time, 60-second OTP for VS Code / JetBrains) ------
+// The web app mints a token, puts only its hash in DB, and hands the plain token
+// to the IDE extension via the vscode:// URI. The extension exchanges it here
+// (GET /ide-push/:token) which validates, marks as used (single-use), and returns
+// the script payload — without the long-lived AgentToken ever touching a URI.
+model IdePushToken {
+  id         String    @id @default(cuid())
+  tenantId   String
+  projectId  String
+  suiteId    String?
+  packId     String?   // for pack-based pushes (regression/smoke/sanity)
+  scriptIds  String?   // JSON array of TestScript IDs for direct selection
+  language   String    @default("playwright-ts")
+  tokenHash  String    @unique
+  expiresAt  DateTime
+  usedAt     DateTime?
+  createdAt  DateTime  @default(now())
+  project    Project   @relation(fields: [projectId], references: [id], onDelete: Cascade)
+
+  @@index([tenantId, projectId])
+  @@index([tokenHash])
+  @@index([expiresAt])
+}
+
+// ---- LLM pricing table (replaces hardcoded PRICING constant in token-pricing.ts) ---------
+// Platform admin can update prices via UI without a code deploy.
+// modelKey format: "provider/model" e.g. "anthropic/claude-sonnet-4-6".
+model LlmPricing {
+  id               String   @id @default(cuid())
+  modelKey         String   @unique
+  inputPer1M       Float
+  outputPer1M      Float
+  cacheReadPer1M   Float    @default(0)
+  cacheWritePer1M  Float    @default(0)
+  effectiveDate    DateTime @default(now())
+  createdAt        DateTime @default(now())
+  updatedAt        DateTime @updatedAt
+
+  @@index([modelKey])
+}
+
+// ---- Database-seeded agent prompts (replaces hardcoded GLOBAL_RULES) ---------
+// Loaded by packages/core/src/agent-prompts.ts with 60s in-process cache.
+// agentKey: e.g. "test-case-global-rules", passKey: optional per-pass override key.
+model AgentPrompt {
+  id        String   @id @default(cuid())
+  name      String
+  agentKey  String
+  passKey   String?
+  body      String   @db.Text
+  version   Int      @default(1)
+  isActive  Boolean  @default(true)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([agentKey, passKey, isActive])
+  @@index([agentKey, isActive])
+}
+
+// Per-tenant override of platform-wide AgentPrompt.
+// Resolution order: WorkspaceAgentPrompt (tenant) → AgentPrompt (platform) → hardcoded fallback.
+model WorkspaceAgentPrompt {
+  id        String   @id @default(cuid())
+  tenantId  String
+  agentKey  String
+  passKey   String?
+  name      String
+  body      String   @db.Text
+  isActive  Boolean  @default(true)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+  updatedBy String?
+
+  tenant    Tenant   @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+
+  @@unique([tenantId, agentKey, passKey])
+  @@index([tenantId, agentKey, isActive])
+}
+
+// ---- Admin Config Change History -----------------------------------------
+// Immutable audit trail for every SystemConfig upsert and delete.
+// Sensitive field values stored as MASK ("••••••••") — never raw.
+
+model SystemConfigHistory {
+  id         String   @id @default(cuid())
+  configKey  String   // e.g. "smtp.password"
+  category   String
+  fieldKey   String
+  oldValue   String?  // null on first-ever create; MASK for sensitive
+  newValue   String?  // null on delete; MASK for sensitive
+  action     String   // "upsert" | "delete"
+  sensitive  Boolean  @default(false)
+  adminId    String?
+  adminEmail String?
+  changedAt  DateTime @default(now())
+
+  @@index([configKey, changedAt(sort: Desc)])
+  @@index([category,  changedAt(sort: Desc)])
+  @@index([adminId])
+}
+
+// ---- Platform Prompt Change History --------------------------------------
+// Captures every body edit to AgentPrompt platform records (version++ trigger).
+
+model AgentPromptHistory {
+  id            String   @id @default(cuid())
+  agentPromptId String
+  agentKey      String
+  passKey       String?
+  oldBody       String   @db.Text
+  newBody       String   @db.Text
+  version       Int
+  adminId       String?
+  adminEmail    String?
+  changedAt     DateTime @default(now())
+
+  @@index([agentPromptId, changedAt(sort: Desc)])
+  @@index([agentKey,      changedAt(sort: Desc)])
+}
+
+// ---- Tenant Prompt Override History --------------------------------------
+// Tracks every upsert/delete of WorkspaceAgentPrompt per tenant.
+
+model WorkspaceAgentPromptHistory {
+  id                     String   @id @default(cuid())
+  workspaceAgentPromptId String?  // null when record was deleted
+  tenantId               String
+  agentKey               String
+  passKey                String?
+  oldBody                String?  @db.Text  // null = first creation
+  newBody                String?  @db.Text  // null = deletion
+  action                 String   // "upsert" | "delete"
+  updatedBy              String?
+  changedAt              DateTime @default(now())
+
+  @@index([tenantId, agentKey, changedAt(sort: Desc)])
+  @@index([workspaceAgentPromptId, changedAt(sort: Desc)])
+}
+
+// ==========================================
+// Learning / Onboarding Models
+// ==========================================
+
+model UserContext {
+  id              String    @id @default(cuid())
+  userId          String    @unique
+  dailyTasks      String[]  @default([])
+  roles           String[]  @default([])
+  responsibilities String[] @default([])
+  toolsUsed       String[]  @default([])
+  lastExtractedAt DateTime?
+  user            User      @relation(fields: [userId], references: [id], onDelete: Cascade)
+}
+
+model LearningJourney {
+  id       String         @id @default(cuid())
+  userId   String         @unique
+  tenantId String
+  level    Int            @default(1)
+  status   String         @default("ACTIVE")
+  tasks    LearningTask[]
+  user     User           @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@index([tenantId])
+}
+
+model LearningTask {
+  id                String           @id @default(cuid())
+  journeyId         String
+  title             String
+  description       String           @db.Text
+  requiredArtifacts String[]         @default([])
+  status            String           @default("ASSIGNED")
+  createdAt         DateTime         @default(now())
+  submissions       TaskSubmission[]
+  journey           LearningJourney  @relation(fields: [journeyId], references: [id], onDelete: Cascade)
+
+  @@index([journeyId])
+}
+
+model TaskSubmission {
+  id          String       @id @default(cuid())
+  taskId      String
+  textContent String?      @db.Text
+  contentUrl  String?
+  submittedAt DateTime     @default(now())
+  task        LearningTask @relation(fields: [taskId], references: [id], onDelete: Cascade)
+
+  @@index([taskId])
+}
+
+// Navigation Knowledge Graph: hyperlink edges discovered between screens during crawl.
+// linkType: NAV_LINK | CONTENT_LINK | FORM_ACTION | BUTTON_LINK | DATA_LINK
+// source:   DOM | AI | INTERACTIVE | SITEMAP
+model DiscoveredLink {
+  id           String   @id @default(cuid())
+  tenantId     String
+  projectId    String
+  fromScreenId String
+  toScreenId   String?
+  href         String
+  text         String?
+  landmark     String?  // nav | header | footer | main | sidebar | aside
+  linkType     String   @default("NAV_LINK")
+  source       String   @default("DOM")
+  confidence   Float    @default(1.0)
+  jobId        String?
+  createdAt    DateTime @default(now())
+  project      Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+  fromScreen   Screen   @relation("DiscoveredLinkFromScreen", fields: [fromScreenId], references: [id], onDelete: Cascade)
+  toScreen     Screen?  @relation("DiscoveredLinkToScreen", fields: [toScreenId], references: [id], onDelete: SetNull)
+
+  @@unique([fromScreenId, href])
+  @@index([tenantId, projectId])
+  @@index([tenantId, projectId, jobId])
+  @@index([toScreenId])
+  @@index([href])
+}
+
+// ---- API Test Run Persistence (GAP-003) ------------------------------------
+// Persists newman / agent API test run results beyond the 5-min in-memory TTL.
+
+model ApiTestRunHistory {
+  id          String    @id @default(cuid())
+  tenantId    String
+  projectId   String
+  status      String    // queued | running | passed | failed | error
+  summary     Json?
+  source      String?   // newman | agent
+  createdAt   DateTime  @default(now())
+  completedAt DateTime?
+  requests    ApiTestRunRequest[]
+
+  @@index([tenantId, projectId])
+  @@index([tenantId, createdAt])
+}
+
+model ApiTestRunRequest {
+  id           String            @id @default(cuid())
+  runHistoryId String
+  run          ApiTestRunHistory @relation(fields: [runHistoryId], references: [id], onDelete: Cascade)
+  requestName  String
+  status       String            // pending | running | passed | failed | skipped | error
+  statusCode   Int?
+  durationMs   Int?
+  assertions   Json?
+  requestUrl   String?
+  error        String?
+
+  @@index([runHistoryId])
+}
+
+// ---- Custom Assertion Builder (GAP-009) ------------------------------------
+// Stores per-test-case custom assertions for the assertion builder UI.
+
+model TestCaseAssertion {
+  id            String   @id @default(cuid())
+  testCaseId    String
+  field         String
+  operator      String   // eq | ne | contains | gt | lt | gte | lte | schema | regex | exists
+  expectedValue String?
+  createdAt     DateTime @default(now())
+
+  @@index([testCaseId])
+}
+
+// ---- CSV/JSON Data-Driven Testing — Skill File Link (GAP-017) -------------
+// Links a test case to a TEST_DATA skill file for multi-row iteration via
+// Newman --iteration-data (CSV/JSON). Separate from TestDataSet (DB rows)
+// to support file-based data sources without DB import.
+
+model TestCaseDataLink {
+  id          String   @id @default(cuid())
+  testCaseId  String   @unique
+  skillFileId String   // ID of the TEST_DATA skill file
+  dataFormat  String   @default("json")  // json | csv
+  iterateAll  Boolean  @default(true)
+  createdAt   DateTime @default(now())
+
+  @@index([testCaseId])
+}
+
+// ---- Context Intelligence Models (P1-P7) ------------------------------------
+
+model ContextEnhancement {
+  id             String   @id @default(cuid())
+  tenantId       String
+  projectId      String
+  sourceType     String
+  sourceRef      String?
+  crawlJobId     String?
+  status         String   @default("PENDING")
+  proposedChanges Json    @default("[]")
+  appliedAt      DateTime?
+  appliedBy      String?
+  rejectedAt     DateTime?
+  rejectedBy     String?
+  approvalRequestedAt    DateTime?
+  approvalRequestedBy    String?
+  assignedReviewerId     String?
+  project        Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+  extractedElements      ExtractedElement[]
+  enrichedTestCases      TestCase[] @relation("TestCaseSourceEnhancement")
+  createdAt      DateTime @default(now())
+  updatedAt      DateTime @updatedAt
+
+  @@index([tenantId, projectId])
+  @@index([tenantId, projectId, status])
+  @@index([tenantId, projectId, sourceType])
+  @@index([sourceRef])
+}
+
+model ExtractedElement {
+  id                  String   @id @default(cuid())
+  tenantId            String
+  projectId           String
+  sourceEnhancementId String
+  figmaComponentId    String?
+  name                String?
+  role                String?
+  selector            String?
+  confidence          Float    @default(0.5)
+  boundingBox         Json?
+  extractedFrom       String
+  project             Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+  sourceEnhancement   ContextEnhancement @relation(fields: [sourceEnhancementId], references: [id], onDelete: Cascade)
+  figmaComponent      FigmaComponent?    @relation(fields: [figmaComponentId], references: [id], onDelete: SetNull)
+  createdAt           DateTime @default(now())
+
+  @@index([tenantId, projectId])
+  @@index([sourceEnhancementId])
+}
+
+model ContextSourceApproval {
+  id             String   @id @default(cuid())
+  tenantId       String
+  projectId      String
+  sourceType     String
+  approvedBy     String?
+  approvedAt     DateTime?
+  jobId          String?
+  diffCount      Int      @default(0)
+  diffApprovedCount Int   @default(0)
+  project        Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+  createdAt      DateTime @default(now())
+  updatedAt      DateTime @updatedAt
+
+  @@index([tenantId, projectId])
+  @@index([tenantId, projectId, sourceType])
+}
+
+model FigmaComponent {
+  id                  String   @id @default(cuid())
+  tenantId            String
+  projectId           String
+  screenId            String?
+  figmaNodeId         String
+  name                String
+  componentType       String   @default("COMPONENT")
+  description         String?
+  interactions        Json?
+  destinationScreenId String?
+  suggestedLocator    String?
+  suggestedTestId     String?
+  boundingBox         Json?
+  project             Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+  screen              Screen?  @relation(fields: [screenId], references: [id], onDelete: SetNull)
+  extractedElements   ExtractedElement[]
+  createdAt           DateTime @default(now())
+  updatedAt           DateTime @updatedAt
+
+  @@index([tenantId, projectId])
+  @@index([screenId])
+  @@index([figmaNodeId])
+  @@unique([projectId, figmaNodeId])
+}
+
+model CrawlDiff {
+  id                  String   @id @default(cuid())
+  tenantId            String
+  projectId           String
+  fromJobId           String?
+  toJobId             String
+  fromScreenId        String?
+  toScreenId          String?
+  diffType            String
+  severity            String   @default("MINOR")
+  description         String?
+  beforeSnapshot      Json?
+  afterSnapshot       Json?
+  affectedTestCaseIds Json     @default("[]")
+  status              String   @default("PENDING")
+  reviewedBy          String?
+  reviewedAt          DateTime?
+  project             Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+  fromScreen          Screen?  @relation("CrawlDiffFromScreen", fields: [fromScreenId], references: [id], onDelete: SetNull)
+  toScreen            Screen?  @relation("CrawlDiffToScreen", fields: [toScreenId], references: [id], onDelete: SetNull)
+  staleTestCases      TestCase[] @relation("TestCaseCrawlDiff")
+  createdAt           DateTime @default(now())
+  updatedAt           DateTime @updatedAt
+
+  @@index([tenantId, projectId])
+  @@index([tenantId, projectId, status])
+  @@index([toJobId])
+  @@index([fromJobId])
+  @@index([severity, status])
+}
+
+model BugSignal {
+  id                  String   @id @default(cuid())
+  tenantId            String
+  projectId           String
+  signalType          String
+  severity            String   @default("MEDIUM")
+  title               String
+  description         String?
+  sourceRef           Json     @default("{}")
+  affectedTestCaseIds Json     @default("[]")
+  affectedRequirementIds Json  @default("[]")
+  status              String   @default("OPEN")
+  resolution          String?
+  assignedTo          String?
+  project             Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+  testResults         TestResult[] @relation("BugSignalTestResults")
+  visualDiffs         VisualDiff[] @relation("BugSignalVisualDiffs")
+  relatedTestCases    TestCase[] @relation("BugSignalAffectedTestCases")
+  createdAt           DateTime @default(now())
+  updatedAt           DateTime @updatedAt
+
+  @@index([tenantId, projectId])
+  @@index([tenantId, projectId, status])
+  @@index([tenantId, projectId, signalType])
+  @@index([tenantId, projectId, severity])
+  @@index([assignedTo])
+}
+
+model RequirementCoverage {
+  id                  String   @id @default(cuid())
+  tenantId            String
+  projectId           String
+  requirementId       String
+  testCaseIds         Json     @default("[]")
+  coverageScore       Float    @default(0)
+  uncoveredAcIds      Json     @default("[]")
+  computedAt          DateTime @default(now())
+  project             Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
+
+  @@unique([projectId, requirementId])
+  @@index([tenantId, projectId])
+  @@index([tenantId, projectId, coverageScore])
+}