From 5fa48613aeff3f618b0f86d6ecbd818170ab30bf Mon Sep 17 00:00:00 2001
From: chasprowebdev <chasgarciaprowebdev@gmail.com>
Date: Thu, 23 Apr 2026 11:40:10 -0400
Subject: [PATCH 01/40] fix(app): move 'Statement of Applicability' from
 Questionnaire to Documents

---
 .../components/CompanyOverviewCards.tsx       |  34 ++++
 .../documents/components/SOAOverviewCard.tsx  |  49 +++++
 .../components/ApplicableSwatch.tsx           |   0
 .../components/CreateSOADocument.test.tsx     |   2 +-
 .../components/CreateSOADocument.tsx          |   4 +-
 .../components/EditableSOAFields.tsx          |   2 +-
 .../components/SOADocumentInfo.tsx            |   0
 .../components/SOAFrameworkTable.tsx          |   2 +-
 .../components/SOAFrameworkTabs.tsx           |   2 +-
 .../components/SOAMobileRow.tsx               |   0
 .../components/SOAPendingApprovalAlert.tsx    |   0
 .../components/SOATable.tsx                   |   0
 .../components/SOATableRow.tsx                |   0
 .../StatementOfApplicabilitySection.tsx       |  86 +++++++++
 .../components/SubmitApprovalDialog.tsx       |   0
 .../components/index.ts                       |   1 +
 .../components/soa-field-types.ts             |   0
 .../hooks/useSOAAutoFill.ts                   |   0
 .../hooks/useSOADocument.ts                   |   0
 .../statement-of-applicability/page.tsx       | 181 ++++++++++++++++++
 .../statement-of-applicability}/types.ts      |   0
 .../components/QuestionnaireTabs.tsx          |  92 ---------
 .../app/(app)/[orgId]/questionnaire/page.tsx  | 144 +-------------
 .../(app)/[orgId]/questionnaire/soa/page.tsx  |   5 +-
 24 files changed, 361 insertions(+), 243 deletions(-)
 create mode 100644 apps/app/src/app/(app)/[orgId]/documents/components/SOAOverviewCard.tsx
 rename apps/app/src/app/(app)/[orgId]/{questionnaire/soa => documents/statement-of-applicability}/components/ApplicableSwatch.tsx (100%)
 rename apps/app/src/app/(app)/[orgId]/{questionnaire/soa => documents/statement-of-applicability}/components/CreateSOADocument.test.tsx (98%)
 rename apps/app/src/app/(app)/[orgId]/{questionnaire/soa => documents/statement-of-applicability}/components/CreateSOADocument.tsx (93%)
 rename apps/app/src/app/(app)/[orgId]/{questionnaire/soa => documents/statement-of-applicability}/components/EditableSOAFields.tsx (99%)
 rename apps/app/src/app/(app)/[orgId]/{questionnaire/soa => documents/statement-of-applicability}/components/SOADocumentInfo.tsx (100%)
 rename apps/app/src/app/(app)/[orgId]/{questionnaire/soa => documents/statement-of-applicability}/components/SOAFrameworkTable.tsx (99%)
 rename apps/app/src/app/(app)/[orgId]/{questionnaire/soa => documents/statement-of-applicability}/components/SOAFrameworkTabs.tsx (99%)
 rename apps/app/src/app/(app)/[orgId]/{questionnaire/soa => documents/statement-of-applicability}/components/SOAMobileRow.tsx (100%)
 rename apps/app/src/app/(app)/[orgId]/{questionnaire/soa => documents/statement-of-applicability}/components/SOAPendingApprovalAlert.tsx (100%)
 rename apps/app/src/app/(app)/[orgId]/{questionnaire/soa => documents/statement-of-applicability}/components/SOATable.tsx (100%)
 rename apps/app/src/app/(app)/[orgId]/{questionnaire/soa => documents/statement-of-applicability}/components/SOATableRow.tsx (100%)
 create mode 100644 apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/StatementOfApplicabilitySection.tsx
 rename apps/app/src/app/(app)/[orgId]/{questionnaire/soa => documents/statement-of-applicability}/components/SubmitApprovalDialog.tsx (100%)
 create mode 100644 apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/index.ts
 rename apps/app/src/app/(app)/[orgId]/{questionnaire/soa => documents/statement-of-applicability}/components/soa-field-types.ts (100%)
 rename apps/app/src/app/(app)/[orgId]/{questionnaire/soa => documents/statement-of-applicability}/hooks/useSOAAutoFill.ts (100%)
 rename apps/app/src/app/(app)/[orgId]/{questionnaire => documents/statement-of-applicability}/hooks/useSOADocument.ts (100%)
 create mode 100644 apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/page.tsx
 rename apps/app/src/app/(app)/[orgId]/{questionnaire/soa => documents/statement-of-applicability}/types.ts (100%)

diff --git a/apps/app/src/app/(app)/[orgId]/documents/components/CompanyOverviewCards.tsx b/apps/app/src/app/(app)/[orgId]/documents/components/CompanyOverviewCards.tsx
index ee969a9448..f0fce75b14 100644
--- a/apps/app/src/app/(app)/[orgId]/documents/components/CompanyOverviewCards.tsx
+++ b/apps/app/src/app/(app)/[orgId]/documents/components/CompanyOverviewCards.tsx
@@ -18,10 +18,24 @@ import Link from 'next/link';
 import { useMemo } from 'react';
 import useSWR from 'swr';
 import { evidenceFormDefinitionList, meetingSubTypeValues } from '../forms';
+import { SOAOverviewCard } from './SOAOverviewCard';
 
 type FormStatuses = Record<string, { lastSubmittedAt: string | null }>;
+type FrameworkListResponse = {
+  data: Array<{
+    id: string;
+    frameworkId: string;
+    framework: {
+      id: string;
+      name: string;
+      description: string | null;
+      visible: boolean;
+    };
+  }>;
+};
 
 const SIX_MONTHS_MS = 6 * 30 * 24 * 60 * 60 * 1000;
+const ISO27001_NAMES = ['ISO 27001', 'iso27001', 'ISO27001'];
 
 const MEETING_SUB_TYPES = meetingSubTypeValues;
 const MEETING_ALL_TYPES = new Set<string>([...MEETING_SUB_TYPES, 'meeting']);
@@ -106,6 +120,16 @@ export function CompanyOverviewCards({ organizationId }: { organizationId: strin
   );
 
   const { data: findingsResponse } = useOrganizationFindings();
+  const { data: frameworksResponse } = useSWR<FrameworkListResponse>(
+    '/v1/frameworks',
+    async (endpoint: string) => {
+      const response = await api.get<FrameworkListResponse>(endpoint);
+      if (response.error || !response.data) {
+        throw new Error(response.error ?? 'Failed to load frameworks');
+      }
+      return response.data;
+    },
+  );
 
   const activeIssueCounts = useMemo(() => {
     const counts: Record<string, number> = {};
@@ -141,8 +165,18 @@ export function CompanyOverviewCards({ organizationId }: { organizationId: strin
     return map;
   }, [visibleForms]);
 
+  const hasISO27001Framework = useMemo(() => {
+    const frameworks = frameworksResponse?.data ?? [];
+    return frameworks.some(
+      (frameworkInstance) =>
+        !!frameworkInstance.framework?.name &&
+        ISO27001_NAMES.includes(frameworkInstance.framework.name),
+    );
+  }, [frameworksResponse]);
+
   return (
     <Stack gap="6">
+      {hasISO27001Framework && <SOAOverviewCard organizationId={organizationId} />}
       {Array.from(categories.entries()).map(([category, forms]) => (
         <div key={category} className="space-y-3">
           <div className="flex items-center gap-2">
diff --git a/apps/app/src/app/(app)/[orgId]/documents/components/SOAOverviewCard.tsx b/apps/app/src/app/(app)/[orgId]/documents/components/SOAOverviewCard.tsx
new file mode 100644
index 0000000000..b4d2018e42
--- /dev/null
+++ b/apps/app/src/app/(app)/[orgId]/documents/components/SOAOverviewCard.tsx
@@ -0,0 +1,49 @@
+import {
+  Badge,
+  Card,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  Text,
+} from '@trycompai/design-system';
+import Link from 'next/link';
+
+const STATEMENT_OF_APPLICABILITY_FORM = {
+  type: 'statement-of-applicability',
+  title: 'Statement of Applicability',
+  description:
+    "Auto-complete Statement of Applicability for ISO 27001. Generate answers based on your organization's policies and documentation.",
+} as const;
+
+interface SOAOverviewCardProps {
+  organizationId: string;
+}
+
+export function SOAOverviewCard({
+  organizationId,
+}: SOAOverviewCardProps) {
+  const form = STATEMENT_OF_APPLICABILITY_FORM;
+
+  return (
+    <div className="space-y-3">
+      <div className="flex items-center gap-2">
+        <Text size="lg" weight="semibold">
+          {form.title}
+        </Text>
+        <Badge variant="secondary">1</Badge>
+      </div>
+      <div className="grid gap-4 lg:grid-cols-2">
+        <Link href={`/${organizationId}/documents/${form.type}`}>
+          <Card>
+            <CardHeader>
+              <CardTitle>{form.title}</CardTitle>
+              <div className="line-clamp-1">
+                <CardDescription>{form.description}</CardDescription>
+              </div>
+            </CardHeader>
+          </Card>
+        </Link>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/ApplicableSwatch.tsx b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/ApplicableSwatch.tsx
similarity index 100%
rename from apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/ApplicableSwatch.tsx
rename to apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/ApplicableSwatch.tsx
diff --git a/apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/CreateSOADocument.test.tsx b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/CreateSOADocument.test.tsx
similarity index 98%
rename from apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/CreateSOADocument.test.tsx
rename to apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/CreateSOADocument.test.tsx
index 5260abbd6c..2c8756fc52 100644
--- a/apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/CreateSOADocument.test.tsx
+++ b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/CreateSOADocument.test.tsx
@@ -18,7 +18,7 @@ vi.mock('@/hooks/use-permissions', () => ({
 
 // Mock createSOADocument
 const mockCreateSOADocument = vi.fn();
-vi.mock('../../hooks/useSOADocument', () => ({
+vi.mock('../hooks/useSOADocument', () => ({
   createSOADocument: (...args: any[]) => mockCreateSOADocument(...args),
 }));
 
diff --git a/apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/CreateSOADocument.tsx b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/CreateSOADocument.tsx
similarity index 93%
rename from apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/CreateSOADocument.tsx
rename to apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/CreateSOADocument.tsx
index 3bb979c5ea..bac6054593 100644
--- a/apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/CreateSOADocument.tsx
+++ b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/CreateSOADocument.tsx
@@ -7,7 +7,7 @@ import { Plus, Loader2 } from 'lucide-react';
 import { useRouter } from 'next/navigation';
 import { useState } from 'react';
 import { toast } from 'sonner';
-import { createSOADocument } from '../../hooks/useSOADocument';
+import { createSOADocument } from '../hooks/useSOADocument';
 
 interface CreateSOADocumentProps {
   frameworkId: string;
@@ -31,7 +31,7 @@ export function CreateSOADocument({
     try {
       const result = await createSOADocument({ frameworkId, organizationId });
       toast.success('SOA document created successfully');
-      router.push(`/${organizationId}/questionnaire/soa/${result.id}`);
+      router.push(`/${organizationId}/documents/statement-of-applicability/${result.id}`);
     } catch (error) {
       toast.error(
         error instanceof Error ? error.message : 'An error occurred while creating the SOA document',
diff --git a/apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/EditableSOAFields.tsx b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/EditableSOAFields.tsx
similarity index 99%
rename from apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/EditableSOAFields.tsx
rename to apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/EditableSOAFields.tsx
index 7a081d6291..aa2dc5d144 100644
--- a/apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/EditableSOAFields.tsx
+++ b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/EditableSOAFields.tsx
@@ -20,7 +20,7 @@ import {
 } from '@trycompai/ui/dialog';
 import { X, Loader2, Edit2 } from 'lucide-react';
 import { toast } from 'sonner';
-import { useSOADocument } from '../../hooks/useSOADocument';
+import { useSOADocument } from '../hooks/useSOADocument';
 import { ApplicableReadOnlyDisplay, ApplicableSwatchRow } from './ApplicableSwatch';
 import type { SOAFieldSavePayload } from './soa-field-types';
 
diff --git a/apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/SOADocumentInfo.tsx b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOADocumentInfo.tsx
similarity index 100%
rename from apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/SOADocumentInfo.tsx
rename to apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOADocumentInfo.tsx
diff --git a/apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/SOAFrameworkTable.tsx b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOAFrameworkTable.tsx
similarity index 99%
rename from apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/SOAFrameworkTable.tsx
rename to apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOAFrameworkTable.tsx
index fbfd9f0fdb..0c10696b59 100644
--- a/apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/SOAFrameworkTable.tsx
+++ b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOAFrameworkTable.tsx
@@ -4,7 +4,7 @@ import { Card } from '@trycompai/ui';
 import { useState, useMemo, useEffect } from 'react';
 import { toast } from 'sonner';
 import { useSOAAutoFill } from '../hooks/useSOAAutoFill';
-import { useSOADocument } from '../../hooks/useSOADocument';
+import { useSOADocument } from '../hooks/useSOADocument';
 import type { Member, User } from '@db';
 import { SOADocumentInfo } from './SOADocumentInfo';
 import { SOAPendingApprovalAlert } from './SOAPendingApprovalAlert';
diff --git a/apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/SOAFrameworkTabs.tsx b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOAFrameworkTabs.tsx
similarity index 99%
rename from apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/SOAFrameworkTabs.tsx
rename to apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOAFrameworkTabs.tsx
index 2cdf8814c6..bb9071a839 100644
--- a/apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/SOAFrameworkTabs.tsx
+++ b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOAFrameworkTabs.tsx
@@ -5,7 +5,7 @@ import { useState, useTransition } from 'react';
 import { toast } from 'sonner';
 import { Loader2, ShieldCheck } from 'lucide-react';
 import { SOAFrameworkTable } from './SOAFrameworkTable';
-import { ensureSOASetup } from '../../hooks/useSOADocument';
+import { ensureSOASetup } from '../hooks/useSOADocument';
 import type { FrameworkWithSOAData } from '../types';
 
 interface SOAFrameworkTabsProps {
diff --git a/apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/SOAMobileRow.tsx b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOAMobileRow.tsx
similarity index 100%
rename from apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/SOAMobileRow.tsx
rename to apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOAMobileRow.tsx
diff --git a/apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/SOAPendingApprovalAlert.tsx b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOAPendingApprovalAlert.tsx
similarity index 100%
rename from apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/SOAPendingApprovalAlert.tsx
rename to apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOAPendingApprovalAlert.tsx
diff --git a/apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/SOATable.tsx b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOATable.tsx
similarity index 100%
rename from apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/SOATable.tsx
rename to apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOATable.tsx
diff --git a/apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/SOATableRow.tsx b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOATableRow.tsx
similarity index 100%
rename from apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/SOATableRow.tsx
rename to apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOATableRow.tsx
diff --git a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/StatementOfApplicabilitySection.tsx b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/StatementOfApplicabilitySection.tsx
new file mode 100644
index 0000000000..6f61619587
--- /dev/null
+++ b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/StatementOfApplicabilitySection.tsx
@@ -0,0 +1,86 @@
+import { PageHeader, Text } from '@trycompai/design-system';
+import { SOAFrameworkTable } from './SOAFrameworkTable';
+
+type SOAFrameworkTableProps = Parameters<typeof SOAFrameworkTable>[0];
+
+export interface SOAData {
+  framework: SOAFrameworkTableProps['framework'];
+  configuration: SOAFrameworkTableProps['configuration'];
+  document: SOAFrameworkTableProps['document'];
+  isFullyRemote: boolean;
+  canApprove: boolean;
+  approver: SOAFrameworkTableProps['approver'];
+  isPendingApproval: boolean;
+  canCurrentUserApprove: boolean;
+  currentMemberId: string | null;
+  ownerAdminMembers: SOAFrameworkTableProps['ownerAdminMembers'];
+}
+
+interface StatementOfApplicabilitySectionProps {
+  organizationId: string;
+  soaData?: SOAData | null;
+  soaError?: string | null;
+}
+
+function SectionHeader() {
+  return (
+    <>
+      <PageHeader title="Statement of Applicability" />
+      <div className="line-clamp-1">
+        <Text variant="muted">
+          Auto-complete Statement of Applicability for ISO 27001. Generate answers based on your
+          organization's policies and documentation.
+        </Text>
+      </div>
+    </>
+  );
+}
+
+export function StatementOfApplicabilitySection({
+  organizationId,
+  soaData,
+  soaError,
+}: StatementOfApplicabilitySectionProps) {
+  if (soaError) {
+    return (
+      <div className="flex flex-col gap-8">
+        <SectionHeader />
+        <div className="flex items-center justify-center rounded-lg border py-12">
+          <Text variant="muted">{soaError}</Text>
+        </div>
+      </div>
+    );
+  }
+
+  if (soaData) {
+    return (
+      <div className="flex flex-col gap-8">
+        <SectionHeader />
+        <SOAFrameworkTable
+          framework={soaData.framework}
+          configuration={soaData.configuration}
+          document={soaData.document}
+          organizationId={organizationId}
+          isFullyRemote={soaData.isFullyRemote}
+          canApprove={soaData.canApprove}
+          approver={soaData.approver as Parameters<typeof SOAFrameworkTable>[0]['approver']}
+          isPendingApproval={soaData.isPendingApproval}
+          canCurrentUserApprove={soaData.canCurrentUserApprove}
+          currentMemberId={soaData.currentMemberId}
+          ownerAdminMembers={
+            soaData.ownerAdminMembers as Parameters<typeof SOAFrameworkTable>[0]['ownerAdminMembers']
+          }
+        />
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex flex-col gap-8">
+      <SectionHeader />
+      <div className="flex items-center justify-center py-12">
+        <div className="h-6 w-6 animate-spin rounded-full border-2 border-muted-foreground border-t-transparent" />
+      </div>
+    </div>
+  );
+}
diff --git a/apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/SubmitApprovalDialog.tsx b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SubmitApprovalDialog.tsx
similarity index 100%
rename from apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/SubmitApprovalDialog.tsx
rename to apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SubmitApprovalDialog.tsx
diff --git a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/index.ts b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/index.ts
new file mode 100644
index 0000000000..56e5d52b1e
--- /dev/null
+++ b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/index.ts
@@ -0,0 +1 @@
+export { StatementOfApplicabilitySection, type SOAData } from './StatementOfApplicabilitySection';
diff --git a/apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/soa-field-types.ts b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/soa-field-types.ts
similarity index 100%
rename from apps/app/src/app/(app)/[orgId]/questionnaire/soa/components/soa-field-types.ts
rename to apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/soa-field-types.ts
diff --git a/apps/app/src/app/(app)/[orgId]/questionnaire/soa/hooks/useSOAAutoFill.ts b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/hooks/useSOAAutoFill.ts
similarity index 100%
rename from apps/app/src/app/(app)/[orgId]/questionnaire/soa/hooks/useSOAAutoFill.ts
rename to apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/hooks/useSOAAutoFill.ts
diff --git a/apps/app/src/app/(app)/[orgId]/questionnaire/hooks/useSOADocument.ts b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/hooks/useSOADocument.ts
similarity index 100%
rename from apps/app/src/app/(app)/[orgId]/questionnaire/hooks/useSOADocument.ts
rename to apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/hooks/useSOADocument.ts
diff --git a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/page.tsx b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/page.tsx
new file mode 100644
index 0000000000..c098e0034b
--- /dev/null
+++ b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/page.tsx
@@ -0,0 +1,181 @@
+import { getFeatureFlags } from '@/app/posthog';
+import { serverApi } from '@/lib/api-server';
+import { auth } from '@/utils/auth';
+import { Breadcrumb, PageLayout } from '@trycompai/design-system';
+import { headers } from 'next/headers';
+import Link from 'next/link';
+import { notFound } from 'next/navigation';
+import { StatementOfApplicabilitySection, type SOAData } from './components';
+
+const ISO27001_NAMES = ['ISO 27001', 'iso27001', 'ISO27001'];
+
+interface FrameworkApiResponse {
+  data: Array<{
+    id: string;
+    frameworkId: string;
+    framework: {
+      id: string;
+      name: string;
+      description: string | null;
+      visible: boolean;
+    };
+  }>;
+}
+
+interface PeopleApiResponse {
+  data: Array<{
+    id: string;
+    role: string;
+    userId: string;
+    deactivated: boolean;
+    user: {
+      id: string;
+      name: string | null;
+      email: string;
+      image: string | null;
+    };
+  }>;
+}
+
+interface ContextApiResponse {
+  data: Array<{
+    id: string;
+    question: string;
+    answer: string | null;
+    tags: string[];
+    createdAt: string;
+    updatedAt: string;
+  }>;
+}
+
+export default async function StatementOfApplicabilityPage({
+  params,
+}: {
+  params: Promise<{ orgId: string }>;
+}) {
+  const { orgId } = await params;
+
+  const session = await auth.api.getSession({
+    headers: await headers(),
+  });
+
+  if (!session?.user?.id || !session?.session?.activeOrganizationId) {
+    return notFound();
+  }
+
+  const flags = await getFeatureFlags(session.user.id);
+  const isFeatureEnabled = flags['ai-vendor-questionnaire'] === true;
+
+  if (!isFeatureEnabled) {
+    return notFound();
+  }
+
+  const organizationId = session.session.activeOrganizationId;
+
+  const [frameworksResult, peopleResult, contextResult] = await Promise.all([
+    serverApi.get<FrameworkApiResponse>('/v1/frameworks'),
+    serverApi.get<PeopleApiResponse>('/v1/people'),
+    serverApi.get<ContextApiResponse>('/v1/context'),
+  ]);
+
+  const frameworks = frameworksResult.data?.data ?? [];
+  const isoFrameworkInstance = frameworks.find(
+    (fi) => fi.framework?.name && ISO27001_NAMES.includes(fi.framework.name),
+  );
+
+  const people = peopleResult.data?.data ?? [];
+  const contextEntries = contextResult.data?.data ?? [];
+
+  let soaData: SOAData | null = null;
+  let soaError: string | null = null;
+
+  if (isoFrameworkInstance) {
+    try {
+      const { frameworkId, framework } = isoFrameworkInstance;
+
+      const setupResult = await serverApi.post<{
+        success: boolean;
+        error?: string;
+        configuration: Record<string, unknown> | null;
+        document: Record<string, unknown> | null;
+      }>('/v1/soa/ensure-setup', { frameworkId, organizationId });
+
+      const configuration = setupResult.data?.configuration;
+      const document = setupResult.data?.document;
+
+      if (configuration && document) {
+        let approver = null;
+        const approverId = document.approverId as string | undefined;
+        if (approverId) {
+          approver = people.find((p) => p.id === approverId) ?? null;
+        }
+
+        const currentMember =
+          people.find((p) => p.userId === session.user.id && !p.deactivated) ?? null;
+
+        const canApprove = currentMember
+          ? currentMember.role.includes('owner') || currentMember.role.includes('admin')
+          : false;
+
+        const isPendingApproval = document.status === 'needs_review';
+        const canCurrentUserApprove = isPendingApproval && approverId === currentMember?.id;
+
+        const ownerAdminMembers = people
+          .filter(
+            (p) =>
+              !p.deactivated && (p.role.includes('owner') || p.role.includes('admin')),
+          )
+          .sort((a, b) => (a.user?.name ?? '').localeCompare(b.user?.name ?? ''));
+
+        let isFullyRemote = false;
+        const teamWorkContext = contextEntries.find((c) =>
+          c.question?.toLowerCase().includes('how does your team work'),
+        );
+        if (teamWorkContext?.answer) {
+          const answerLower = teamWorkContext.answer.toLowerCase();
+          isFullyRemote =
+            answerLower.includes('fully remote') || answerLower.includes('fully-remote');
+        }
+
+        soaData = {
+          framework,
+          configuration,
+          document,
+          isFullyRemote,
+          canApprove,
+          approver: approver ? { ...approver, user: approver.user } : null,
+          isPendingApproval,
+          canCurrentUserApprove,
+          currentMemberId: currentMember?.id || null,
+          ownerAdminMembers,
+        } as SOAData;
+      }
+    } catch (error) {
+      console.error('Failed to setup SOA:', error);
+      soaError = 'Failed to setup SOA. Please try again later.';
+    }
+  } else {
+    soaError =
+      'ISO 27001 framework not found. Please add ISO 27001 framework to your organization to get started.';
+  }
+
+  return (
+    <PageLayout>
+      <Breadcrumb
+        items={[
+          {
+            label: 'Documents',
+            href: `/${orgId}/documents`,
+            props: { render: <Link href={`/${orgId}/documents`} /> },
+          },
+          { label: 'Statement of Applicability', isCurrent: true },
+        ]}
+      />
+      <StatementOfApplicabilitySection
+        organizationId={organizationId}
+        soaData={soaData}
+        soaError={soaError}
+      />
+    </PageLayout>
+  );
+}
diff --git a/apps/app/src/app/(app)/[orgId]/questionnaire/soa/types.ts b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/types.ts
similarity index 100%
rename from apps/app/src/app/(app)/[orgId]/questionnaire/soa/types.ts
rename to apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/types.ts
diff --git a/apps/app/src/app/(app)/[orgId]/questionnaire/components/QuestionnaireTabs.tsx b/apps/app/src/app/(app)/[orgId]/questionnaire/components/QuestionnaireTabs.tsx
index 48af923c83..189512d6b1 100644
--- a/apps/app/src/app/(app)/[orgId]/questionnaire/components/QuestionnaireTabs.tsx
+++ b/apps/app/src/app/(app)/[orgId]/questionnaire/components/QuestionnaireTabs.tsx
@@ -8,14 +8,12 @@ import {
   TabsContent,
   TabsList,
   TabsTrigger,
-  Text,
 } from '@trycompai/design-system';
 import { AdditionalDocumentsSection } from '../knowledge-base/additional-documents/components';
 import { KnowledgeBaseHeader } from '../knowledge-base/components/KnowledgeBaseHeader';
 import { ContextSection } from '../knowledge-base/context/components';
 import { ManualAnswersSection } from '../knowledge-base/manual-answers/components';
 import { PublishedPoliciesSection } from '../knowledge-base/published-policies/components';
-import { SOAFrameworkTable } from '../soa/components/SOAFrameworkTable';
 import { QuestionnaireOverview } from '../start_page/components';
 import type {
   ContextEntry,
@@ -25,31 +23,11 @@ import type {
   QuestionnaireListItem,
 } from './types';
 
-// Use type inference from SOAFrameworkTable props
-type SOAFrameworkTableProps = Parameters<typeof SOAFrameworkTable>[0];
-
-interface SOAData {
-  framework: SOAFrameworkTableProps['framework'];
-  configuration: SOAFrameworkTableProps['configuration'];
-  document: SOAFrameworkTableProps['document'];
-  isFullyRemote: boolean;
-  canApprove: boolean;
-  approver: SOAFrameworkTableProps['approver'];
-  isPendingApproval: boolean;
-  canCurrentUserApprove: boolean;
-  currentMemberId: string | null;
-  ownerAdminMembers: SOAFrameworkTableProps['ownerAdminMembers'];
-}
-
 interface QuestionnaireTabsProps {
   organizationId: string;
   // Questionnaires tab
   questionnaires: QuestionnaireListItem[];
   hasPublishedPolicies: boolean;
-  // SOA tab (conditional)
-  showSOATab: boolean;
-  soaData?: SOAData | null;
-  soaError?: string | null;
   // Knowledge Base tab
   policies: PublishedPolicy[];
   contextEntries: ContextEntry[];
@@ -61,9 +39,6 @@ export function QuestionnaireTabs({
   organizationId,
   questionnaires,
   hasPublishedPolicies,
-  showSOATab,
-  soaData,
-  soaError,
   policies,
   contextEntries,
   manualAnswers,
@@ -116,7 +91,6 @@ export function QuestionnaireTabs({
             tabs={
               <TabsList variant="underline">
                 <TabsTrigger value="questionnaires">Security Questionnaire</TabsTrigger>
-                {showSOATab && <TabsTrigger value="soa">Statement of Applicability</TabsTrigger>}
                 <TabsTrigger value="knowledge-base">Knowledge Base</TabsTrigger>
               </TabsList>
             }
@@ -128,72 +102,6 @@ export function QuestionnaireTabs({
           <QuestionnaireOverview questionnaires={questionnaires} />
         </TabsContent>
 
-        {/* SOA Tab (conditional) */}
-        {showSOATab && (
-          <TabsContent value="soa">
-            {soaError ? (
-              <div className="flex flex-col gap-8">
-                <div className="flex flex-col gap-2">
-                  <h2 className="text-lg font-semibold text-foreground lg:text-xl">
-                    Statement of Applicability
-                  </h2>
-                  <Text variant="muted" size="sm">
-                    Auto-complete Statement of Applicability for ISO 27001. Generate answers based
-                    on your organization's policies and documentation.
-                  </Text>
-                </div>
-                <div className="flex items-center justify-center rounded-lg border py-12">
-                  <Text variant="muted">{soaError}</Text>
-                </div>
-              </div>
-            ) : soaData ? (
-              <div className="flex flex-col gap-8">
-                <div className="flex flex-col gap-2">
-                  <h2 className="text-lg font-semibold text-foreground lg:text-xl">
-                    Statement of Applicability
-                  </h2>
-                  <Text variant="muted" size="sm">
-                    Auto-complete Statement of Applicability for ISO 27001. Generate answers based
-                    on your organization's policies and documentation.
-                  </Text>
-                </div>
-                <SOAFrameworkTable
-                  framework={soaData.framework}
-                  configuration={soaData.configuration}
-                  document={soaData.document}
-                  organizationId={organizationId}
-                  isFullyRemote={soaData.isFullyRemote}
-                  canApprove={soaData.canApprove}
-                  approver={soaData.approver as Parameters<typeof SOAFrameworkTable>[0]['approver']}
-                  isPendingApproval={soaData.isPendingApproval}
-                  canCurrentUserApprove={soaData.canCurrentUserApprove}
-                  currentMemberId={soaData.currentMemberId}
-                  ownerAdminMembers={
-                    soaData.ownerAdminMembers as Parameters<
-                      typeof SOAFrameworkTable
-                    >[0]['ownerAdminMembers']
-                  }
-                />
-              </div>
-            ) : (
-              <div className="flex flex-col gap-8">
-                <div className="flex flex-col gap-2">
-                  <h2 className="text-lg font-semibold text-foreground lg:text-xl">
-                    Statement of Applicability
-                  </h2>
-                  <Text variant="muted" size="sm">
-                    Auto-complete Statement of Applicability for ISO 27001. Generate answers based
-                    on your organization's policies and documentation.
-                  </Text>
-                </div>
-                <div className="flex items-center justify-center py-12">
-                  <div className="h-6 w-6 animate-spin rounded-full border-2 border-muted-foreground border-t-transparent" />
-                </div>
-              </div>
-            )}
-          </TabsContent>
-        )}
-
         {/* Knowledge Base Tab */}
         <TabsContent value="knowledge-base">
           <KnowledgeBaseHeader organizationId={organizationId} />
diff --git a/apps/app/src/app/(app)/[orgId]/questionnaire/page.tsx b/apps/app/src/app/(app)/[orgId]/questionnaire/page.tsx
index 5fd0b08b2c..59c00c84dd 100644
--- a/apps/app/src/app/(app)/[orgId]/questionnaire/page.tsx
+++ b/apps/app/src/app/(app)/[orgId]/questionnaire/page.tsx
@@ -5,8 +5,6 @@ import { headers } from 'next/headers';
 import { notFound } from 'next/navigation';
 import { QuestionnaireTabs } from './components/QuestionnaireTabs';
 
-const ISO27001_NAMES = ['ISO 27001', 'iso27001', 'ISO27001'];
-
 interface PolicyApiResponse {
   data: Array<{
     id: string;
@@ -40,34 +38,6 @@ interface QuestionnaireApiResponse {
   }>;
 }
 
-interface FrameworkApiResponse {
-  data: Array<{
-    id: string;
-    frameworkId: string;
-    framework: {
-      id: string;
-      name: string;
-      description: string | null;
-      visible: boolean;
-    };
-  }>;
-}
-
-interface PeopleApiResponse {
-  data: Array<{
-    id: string;
-    role: string;
-    userId: string;
-    deactivated: boolean;
-    user: {
-      id: string;
-      name: string | null;
-      email: string;
-      image: string | null;
-    };
-  }>;
-}
-
 interface ContextApiResponse {
   data: Array<{
     id: string;
@@ -101,13 +71,7 @@ interface KBDocumentApiResponse {
   updatedAt: string;
 }
 
-export default async function SecurityQuestionnairePage({
-  params,
-}: {
-  params: Promise<{ orgId: string }>;
-}) {
-  const { orgId } = await params;
-
+export default async function SecurityQuestionnairePage() {
   const session = await auth.api.getSession({
     headers: await headers(),
   });
@@ -129,16 +93,12 @@ export default async function SecurityQuestionnairePage({
   const [
     policiesResult,
     questionnairesResult,
-    frameworksResult,
-    peopleResult,
     contextResult,
     manualAnswersResult,
     kbDocumentsResult,
   ] = await Promise.all([
     serverApi.get<PolicyApiResponse>('/v1/policies'),
     serverApi.get<QuestionnaireApiResponse>('/v1/questionnaire'),
-    serverApi.get<FrameworkApiResponse>('/v1/frameworks'),
-    serverApi.get<PeopleApiResponse>('/v1/people'),
     serverApi.get<ContextApiResponse>('/v1/context'),
     serverApi.get<ManualAnswerApiResponse[]>('/v1/knowledge-base/manual-answers'),
     serverApi.get<KBDocumentApiResponse[]>('/v1/knowledge-base/documents'),
@@ -154,18 +114,6 @@ export default async function SecurityQuestionnairePage({
   // Questionnaires list
   const questionnaires = questionnairesResult.data?.data ?? [];
 
-  // Check ISO 27001 framework
-  const frameworks = frameworksResult.data?.data ?? [];
-  const isoFrameworkInstance = frameworks.find((fi) => {
-    return fi.framework?.name && ISO27001_NAMES.includes(fi.framework.name);
-  });
-
-  const hasISO27001 = !!isoFrameworkInstance;
-  const showSOATab = hasISO27001;
-
-  // People data
-  const people = peopleResult.data?.data ?? [];
-
   // Context data
   const contextEntries = contextResult.data?.data ?? [];
 
@@ -177,101 +125,11 @@ export default async function SecurityQuestionnairePage({
     ? kbDocumentsResult.data
     : [];
 
-  // Build SOA data if needed
-  let soaData = null;
-  let soaError: string | null = null;
-
-  if (showSOATab && isoFrameworkInstance) {
-    try {
-      const { frameworkId, framework } = isoFrameworkInstance;
-
-      const setupResult = await serverApi.post<{
-        success: boolean;
-        error?: string;
-        configuration: Record<string, unknown> | null;
-        document: Record<string, unknown> | null;
-      }>('/v1/soa/ensure-setup', { frameworkId, organizationId });
-
-      const configuration = setupResult.data?.configuration;
-      const document = setupResult.data?.document;
-
-      if (configuration && document) {
-        // Find approver from people list
-        let approver = null;
-        const approverId = document.approverId as string | undefined;
-        if (approverId) {
-          approver =
-            people.find((p) => p.id === approverId) ?? null;
-        }
-
-        // Find current member
-        const currentMember =
-          people.find(
-            (p) => p.userId === session.user.id && !p.deactivated,
-          ) ?? null;
-
-        const canApprove = currentMember
-          ? currentMember.role.includes('owner') ||
-            currentMember.role.includes('admin')
-          : false;
-
-        const isPendingApproval = document.status === 'needs_review';
-        const canCurrentUserApprove =
-          isPendingApproval && approverId === currentMember?.id;
-
-        // Filter owner/admin members
-        const ownerAdminMembers = people
-          .filter(
-            (p) =>
-              !p.deactivated &&
-              (p.role.includes('owner') || p.role.includes('admin')),
-          )
-          .sort((a, b) =>
-            (a.user?.name ?? '').localeCompare(b.user?.name ?? ''),
-          );
-
-        // Check if fully remote from context
-        let isFullyRemote = false;
-        const teamWorkContext = contextEntries.find((c) =>
-          c.question?.toLowerCase().includes('how does your team work'),
-        );
-        if (teamWorkContext?.answer) {
-          const answerLower = teamWorkContext.answer.toLowerCase();
-          isFullyRemote =
-            answerLower.includes('fully remote') ||
-            answerLower.includes('fully-remote');
-        }
-
-        soaData = {
-          framework,
-          configuration,
-          document,
-          isFullyRemote,
-          canApprove,
-          approver: approver ? { ...approver, user: approver.user } : null,
-          isPendingApproval,
-          canCurrentUserApprove,
-          currentMemberId: currentMember?.id || null,
-          ownerAdminMembers,
-        };
-      }
-    } catch (error) {
-      console.error('Failed to setup SOA:', error);
-      soaError = 'Failed to setup SOA. Please try again later.';
-    }
-  } else if (showSOATab && !isoFrameworkInstance) {
-    soaError =
-      'ISO 27001 framework not found. Please add ISO 27001 framework to your organization to get started.';
-  }
-
   return (
     <QuestionnaireTabs
       organizationId={organizationId}
       questionnaires={questionnaires}
       hasPublishedPolicies={hasPublishedPolicies}
-      showSOATab={showSOATab}
-      soaData={soaData as Parameters<typeof QuestionnaireTabs>[0]['soaData']}
-      soaError={soaError}
       policies={publishedPolicies}
       contextEntries={contextEntries}
       manualAnswers={manualAnswers}
diff --git a/apps/app/src/app/(app)/[orgId]/questionnaire/soa/page.tsx b/apps/app/src/app/(app)/[orgId]/questionnaire/soa/page.tsx
index f161193001..97478811ce 100644
--- a/apps/app/src/app/(app)/[orgId]/questionnaire/soa/page.tsx
+++ b/apps/app/src/app/(app)/[orgId]/questionnaire/soa/page.tsx
@@ -4,8 +4,9 @@ interface SOAPageProps {
   params: Promise<{ orgId: string }>;
 }
 
-// Redirect to main questionnaire page - SOA is now a tab
+// Redirect to the Statement of Applicability page under Documents.
+// SOA was previously a tab on the Questionnaires page; it now lives under Documents.
 export default async function SOAPage({ params }: SOAPageProps) {
   const { orgId } = await params;
-  redirect(`/${orgId}/questionnaire`);
+  redirect(`/${orgId}/documents/statement-of-applicability`);
 }

From d8a9a8d88b58c9afc41b7cd13323ddf080ff5c61 Mon Sep 17 00:00:00 2001
From: chasprowebdev <chasgarciaprowebdev@gmail.com>
Date: Thu, 23 Apr 2026 13:27:44 -0400
Subject: [PATCH 02/40] fix(app): update approval status after approving of
 'Statement of Applicability'

---
 .../components/SOAFrameworkTable.tsx               | 14 ++++++--------
 1 file changed, 6 insertions(+), 8 deletions(-)

diff --git a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOAFrameworkTable.tsx b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOAFrameworkTable.tsx
index 0c10696b59..02dfae7b31 100644
--- a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOAFrameworkTable.tsx
+++ b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOAFrameworkTable.tsx
@@ -105,17 +105,17 @@ export function SOAFrameworkTable({
     );
   });
 
-  // Update answersMap when document changes
+  // Update answersMap when the live document changes
   useEffect(() => {
     setAnswersMap(
       new Map(
-        (document?.answers || []).map((answer: { questionId: string; answer: string | null; answerVersion: number }) => [
+        (resolvedDocument?.answers || []).map((answer: { questionId: string; answer: string | null; answerVersion: number }) => [
           answer.questionId,
           { answer: answer.answer, answerVersion: answer.answerVersion },
         ])
       )
     );
-  }, [document?.answers]);
+  }, [resolvedDocument?.answers]);
 
   const handleAnswerUpdate = (questionId: string, payload: SOAFieldSavePayload) => {
     setAnswersMap((prev) => {
@@ -190,10 +190,8 @@ export function SOAFrameworkTable({
     );
   }
 
-  // The document comes from the Prisma SOADocument type which has all necessary fields.
-  // We cast to the SOADocumentInfo's expected type for the info panel.
-  const docForInfo = document as unknown as SOADocumentInfoDocument;
-  const approverId = (document as Record<string, unknown>).approverId as string | null | undefined;
+  // Use the resolved SWR document so approval status updates instantly without page refresh.
+  const docForInfo = resolvedDocument as unknown as SOADocumentInfoDocument;
 
   const handleAutoFill = async () => {
     if (!document) return;
@@ -278,7 +276,7 @@ export function SOAFrameworkTable({
         isFullyRemote={isFullyRemote}
         isExpanded={isExpanded}
         onToggleExpand={() => setIsExpanded(!isExpanded)}
-        documentId={document.id}
+        documentId={resolvedDocument?.id ?? document.id}
         isPendingApproval={derivedIsPendingApproval}
         organizationId={organizationId}
         onAnswerUpdate={handleAnswerUpdate}

From 4d6e85486d9b9ef5339397e6a9d74ebcdc973df1 Mon Sep 17 00:00:00 2001
From: chasprowebdev <chasgarciaprowebdev@gmail.com>
Date: Thu, 23 Apr 2026 14:18:56 -0400
Subject: [PATCH 03/40] fix(app): show approval status on Statement of
 Applicability card in documents

---
 .../components/CompanyOverviewCards.tsx       | 13 ++-
 .../documents/components/SOAOverviewCard.tsx  | 89 +++++++++++++++++++
 2 files changed, 99 insertions(+), 3 deletions(-)

diff --git a/apps/app/src/app/(app)/[orgId]/documents/components/CompanyOverviewCards.tsx b/apps/app/src/app/(app)/[orgId]/documents/components/CompanyOverviewCards.tsx
index f0fce75b14..2cb3ec7bf1 100644
--- a/apps/app/src/app/(app)/[orgId]/documents/components/CompanyOverviewCards.tsx
+++ b/apps/app/src/app/(app)/[orgId]/documents/components/CompanyOverviewCards.tsx
@@ -165,18 +165,25 @@ export function CompanyOverviewCards({ organizationId }: { organizationId: strin
     return map;
   }, [visibleForms]);
 
-  const hasISO27001Framework = useMemo(() => {
+  const iso27001Framework = useMemo(() => {
     const frameworks = frameworksResponse?.data ?? [];
-    return frameworks.some(
+    return frameworks.find(
       (frameworkInstance) =>
         !!frameworkInstance.framework?.name &&
         ISO27001_NAMES.includes(frameworkInstance.framework.name),
     );
   }, [frameworksResponse]);
+  const hasISO27001Framework = !!iso27001Framework;
+  const iso27001FrameworkId = iso27001Framework?.frameworkId ?? null;
 
   return (
     <Stack gap="6">
-      {hasISO27001Framework && <SOAOverviewCard organizationId={organizationId} />}
+      {hasISO27001Framework && iso27001FrameworkId && (
+        <SOAOverviewCard
+          organizationId={organizationId}
+          iso27001FrameworkId={iso27001FrameworkId}
+        />
+      )}
       {Array.from(categories.entries()).map(([category, forms]) => (
         <div key={category} className="space-y-3">
           <div className="flex items-center gap-2">
diff --git a/apps/app/src/app/(app)/[orgId]/documents/components/SOAOverviewCard.tsx b/apps/app/src/app/(app)/[orgId]/documents/components/SOAOverviewCard.tsx
index b4d2018e42..a9d2666a4a 100644
--- a/apps/app/src/app/(app)/[orgId]/documents/components/SOAOverviewCard.tsx
+++ b/apps/app/src/app/(app)/[orgId]/documents/components/SOAOverviewCard.tsx
@@ -1,12 +1,16 @@
 import {
   Badge,
   Card,
+  CardContent,
   CardDescription,
   CardHeader,
   CardTitle,
   Text,
 } from '@trycompai/design-system';
+import { api } from '@/lib/api-client';
 import Link from 'next/link';
+import { useMemo } from 'react';
+import useSWR from 'swr';
 
 const STATEMENT_OF_APPLICABILITY_FORM = {
   type: 'statement-of-applicability',
@@ -17,12 +21,94 @@ const STATEMENT_OF_APPLICABILITY_FORM = {
 
 interface SOAOverviewCardProps {
   organizationId: string;
+  iso27001FrameworkId: string;
+}
+
+type SOASetupResponse = {
+  success: boolean;
+  configuration: Record<string, unknown> | null;
+  document: {
+    status?: string | null;
+    approvedAt?: string | Date | null;
+    approverId?: string | null;
+    declinedAt?: string | Date | null;
+  } | null;
+};
+
+type SOAApprovalStatus = 'Approved' | 'Declined' | 'Pending' | 'Not approved';
+
+function SOAApprovalStatusBadge({ status }: { status: SOAApprovalStatus }) {
+  const statusConfig: Record<
+    SOAApprovalStatus,
+    { label: SOAApprovalStatus; className: string }
+  > = {
+    Approved: {
+      label: 'Approved',
+      className:
+        'bg-green-100 text-green-800 dark:bg-green-950/30 dark:text-green-400',
+    },
+    Pending: {
+      label: 'Pending',
+      className:
+        'bg-amber-100 text-amber-800 dark:bg-amber-950/30 dark:text-amber-400',
+    },
+    Declined: {
+      label: 'Declined',
+      className: 'bg-red-100 text-red-800 dark:bg-red-950/30 dark:text-red-400',
+    },
+    'Not approved': {
+      label: 'Not approved',
+      className:
+        'bg-slate-100 text-slate-800 dark:bg-slate-950/30 dark:text-slate-400',
+    },
+  };
+
+  const { label, className } = statusConfig[status];
+  return (
+    <span
+      className={`inline-flex items-center rounded-sm px-1.5 py-1 text-[10px] font-semibold uppercase tracking-wider leading-none ${className}`}
+    >
+      {label}
+    </span>
+  );
 }
 
 export function SOAOverviewCard({
   organizationId,
+  iso27001FrameworkId,
 }: SOAOverviewCardProps) {
   const form = STATEMENT_OF_APPLICABILITY_FORM;
+  const { data: soaSetupResponse } = useSWR<SOASetupResponse>(
+    ['/v1/soa/ensure-setup', organizationId, iso27001FrameworkId],
+    async ([endpoint, orgId, frameworkId]: readonly [string, string, string]) => {
+      const response = await api.post<SOASetupResponse>(endpoint, {
+        organizationId: orgId,
+        frameworkId,
+      });
+      if (response.error || !response.data) {
+        throw new Error(response.error ?? 'Failed to load SOA status');
+      }
+      return response.data;
+    },
+    {
+      revalidateOnFocus: true,
+    },
+  );
+
+  const document = soaSetupResponse?.document;
+  const approvalStatus = useMemo<SOAApprovalStatus>(() => {
+    if (!document) return 'Not approved';
+    if (document.approvedAt) return 'Approved';
+    if (document.declinedAt) return 'Declined';
+    if (
+      document.status === 'needs_review' ||
+      document.status === 'pending_approval' ||
+      !!document.approverId
+    ) {
+      return 'Pending';
+    }
+    return 'Not approved';
+  }, [document]);
 
   return (
     <div className="space-y-3">
@@ -41,6 +127,9 @@ export function SOAOverviewCard({
                 <CardDescription>{form.description}</CardDescription>
               </div>
             </CardHeader>
+            <CardContent>
+              <SOAApprovalStatusBadge status={approvalStatus} />
+            </CardContent>
           </Card>
         </Link>
       </div>

From 10c67f7bf49169082240cf7c415beb9d23068d4b Mon Sep 17 00:00:00 2001
From: chasprowebdev <chasgarciaprowebdev@gmail.com>
Date: Thu, 23 Apr 2026 15:43:26 -0400
Subject: [PATCH 04/40] fix(api): include soa to documents score

---
 .../frameworks/frameworks-scores.helper.ts    | 55 ++++++++++++++++---
 1 file changed, 48 insertions(+), 7 deletions(-)

diff --git a/apps/api/src/frameworks/frameworks-scores.helper.ts b/apps/api/src/frameworks/frameworks-scores.helper.ts
index b629742787..456f8c5f28 100644
--- a/apps/api/src/frameworks/frameworks-scores.helper.ts
+++ b/apps/api/src/frameworks/frameworks-scores.helper.ts
@@ -5,6 +5,7 @@ import {
   toExternalEvidenceFormType,
 } from '@trycompai/company';
 import { db } from '@db';
+import { ISO27001_FRAMEWORK_NAMES } from '../soa/utils/constants';
 import { filterComplianceMembers } from '../utils/compliance-filters';
 
 const SIX_MONTHS_MS = 6 * 30 * 24 * 60 * 60 * 1000;
@@ -185,11 +186,24 @@ export async function getOverviewScores(organizationId: string) {
 }
 
 async function computeDocumentsScore(organizationId: string) {
-  const groupedStatuses = await db.evidenceSubmission.groupBy({
-    by: ['formType'],
-    where: { organizationId },
-    _max: { submittedAt: true },
-  });
+  const [groupedStatuses, isoFrameworkInstances] = await Promise.all([
+    db.evidenceSubmission.groupBy({
+      by: ['formType'],
+      where: { organizationId },
+      _max: { submittedAt: true },
+    }),
+    db.frameworkInstance.findMany({
+      where: {
+        organizationId,
+        framework: {
+          name: {
+            in: ISO27001_FRAMEWORK_NAMES,
+          },
+        },
+      },
+      select: { frameworkId: true },
+    }),
+  ]);
 
   const statuses: Record<string, { lastSubmittedAt: string | null }> = {};
   for (const form of evidenceFormDefinitionList) {
@@ -204,8 +218,7 @@ async function computeDocumentsScore(organizationId: string) {
   const includedForms = evidenceFormDefinitionList.filter(
     (f) => !f.hidden && !f.optional,
   );
-  const totalDocuments = includedForms.length;
-  const outstandingDocuments = includedForms.reduce((count, form) => {
+  const nonSOAOutstandingDocuments = includedForms.reduce((count, form) => {
     if (form.type === 'meeting') {
       const allMeetingsOutstanding = meetingSubTypeValues.every((subType) => {
         const lastSubmitted = statuses[subType]?.lastSubmittedAt;
@@ -223,6 +236,34 @@ async function computeDocumentsScore(organizationId: string) {
     return isOutstanding ? count + 1 : count;
   }, 0);
 
+  const isoFrameworkIds = isoFrameworkInstances
+    .map((instance) => instance.frameworkId)
+    .filter((id): id is string => !!id);
+  const hasSOADocumentRequirement = isoFrameworkIds.length > 0;
+
+  let soaCompleted = false;
+  if (hasSOADocumentRequirement) {
+    const latestSOADocument = await db.sOADocument.findFirst({
+      where: {
+        organizationId,
+        isLatest: true,
+        frameworkId: { in: isoFrameworkIds },
+      },
+      select: {
+        approvedAt: true,
+      },
+      orderBy: {
+        updatedAt: 'desc',
+      },
+    });
+    soaCompleted = !!latestSOADocument?.approvedAt;
+  }
+
+  const soaTotalDocuments = hasSOADocumentRequirement ? 1 : 0;
+  const soaOutstandingDocuments = hasSOADocumentRequirement && !soaCompleted ? 1 : 0;
+  const totalDocuments = includedForms.length + soaTotalDocuments;
+  const outstandingDocuments = nonSOAOutstandingDocuments + soaOutstandingDocuments;
+
   return {
     totalDocuments,
     completedDocuments: totalDocuments - outstandingDocuments,

From 7364c58c7cdc9801061a4df6f2ca95d6a346254d Mon Sep 17 00:00:00 2001
From: chasprowebdev <chasgarciaprowebdev@gmail.com>
Date: Thu, 23 Apr 2026 16:50:43 -0400
Subject: [PATCH 05/40] fix(api): create endpoint to export soa into pdf

---
 .../src/soa/dto/export-soa-document.dto.ts    |  13 ++
 apps/api/src/soa/soa.controller.ts            |  26 ++++
 apps/api/src/soa/soa.service.ts               |  60 +++++++
 apps/api/src/soa/utils/export-generator.ts    | 146 ++++++++++++++++++
 4 files changed, 245 insertions(+)
 create mode 100644 apps/api/src/soa/dto/export-soa-document.dto.ts
 create mode 100644 apps/api/src/soa/utils/export-generator.ts

diff --git a/apps/api/src/soa/dto/export-soa-document.dto.ts b/apps/api/src/soa/dto/export-soa-document.dto.ts
new file mode 100644
index 0000000000..84c62cbade
--- /dev/null
+++ b/apps/api/src/soa/dto/export-soa-document.dto.ts
@@ -0,0 +1,13 @@
+import { IsIn, IsString } from 'class-validator';
+
+export class ExportSOADocumentDto {
+  @IsString()
+  documentId!: string;
+
+  @IsString()
+  organizationId!: string;
+
+  @IsIn(['pdf'])
+  format!: 'pdf';
+}
+
diff --git a/apps/api/src/soa/soa.controller.ts b/apps/api/src/soa/soa.controller.ts
index 64d1bed7ca..451c93476e 100644
--- a/apps/api/src/soa/soa.controller.ts
+++ b/apps/api/src/soa/soa.controller.ts
@@ -25,6 +25,7 @@ import { EnsureSOASetupDto } from './dto/ensure-soa-setup.dto';
 import { ApproveSOADocumentDto } from './dto/approve-soa-document.dto';
 import { DeclineSOADocumentDto } from './dto/decline-soa-document.dto';
 import { SubmitSOAForApprovalDto } from './dto/submit-soa-for-approval.dto';
+import { ExportSOADocumentDto } from './dto/export-soa-document.dto';
 import { syncOrganizationEmbeddings } from '@/vector-store/lib';
 import { OrganizationId } from '@/auth/auth-context.decorator';
 import { AuthContext } from '@/auth/auth-context.decorator';
@@ -395,4 +396,29 @@ export class SOAController {
   ) {
     return this.soaService.submitForApproval(dto);
   }
+
+  @Post('export')
+  @RequirePermission('audit', 'read')
+  @ApiOperation({ summary: 'Export a SOA document' })
+  @ApiConsumes('application/json')
+  @ApiProduces('application/pdf')
+  @ApiOkResponse({
+    description: 'Export SOA document to PDF',
+  })
+  async exportDocument(
+    @Body() dto: ExportSOADocumentDto,
+    @Res({ passthrough: true }) res: Response,
+    @OrganizationId() organizationId: string,
+  ): Promise<void> {
+    dto.organizationId = organizationId;
+    const result = await this.soaService.exportDocument(dto);
+
+    res.setHeader('Content-Type', result.mimeType);
+    res.setHeader(
+      'Content-Disposition',
+      `attachment; filename="${result.filename}"`,
+    );
+
+    res.send(result.fileBuffer);
+  }
 }
diff --git a/apps/api/src/soa/soa.service.ts b/apps/api/src/soa/soa.service.ts
index aa085444ac..ca5ac33c21 100644
--- a/apps/api/src/soa/soa.service.ts
+++ b/apps/api/src/soa/soa.service.ts
@@ -13,9 +13,14 @@ import { EnsureSOASetupDto } from './dto/ensure-soa-setup.dto';
 import { ApproveSOADocumentDto } from './dto/approve-soa-document.dto';
 import { DeclineSOADocumentDto } from './dto/decline-soa-document.dto';
 import { SubmitSOAForApprovalDto } from './dto/submit-soa-for-approval.dto';
+import { ExportSOADocumentDto } from './dto/export-soa-document.dto';
 import type { SimilarContentResult } from '@/vector-store/lib';
 import { loadISOConfig } from './utils/transform-iso-config';
 import { ISO27001_FRAMEWORK_NAMES } from './utils/constants';
+import {
+  generateSOAExportFile,
+  type SOAExportQuestion,
+} from './utils/export-generator';
 import {
   batchSearchSOAQuestions,
   generateSOAAnswerWithRAG,
@@ -437,6 +442,61 @@ export class SOAService {
     return { success: true, data: updatedDocument };
   }
 
+  async exportDocument(dto: ExportSOADocumentDto): Promise<{
+    fileBuffer: Buffer;
+    mimeType: string;
+    filename: string;
+  }> {
+    const document = await db.sOADocument.findFirst({
+      where: {
+        id: dto.documentId,
+        organizationId: dto.organizationId,
+      },
+      include: {
+        configuration: true,
+        framework: {
+          select: { name: true },
+        },
+        answers: {
+          where: { isLatestAnswer: true },
+          select: {
+            questionId: true,
+            answer: true,
+          },
+        },
+      },
+    });
+
+    if (!document) {
+      throw new NotFoundException('SOA document not found');
+    }
+
+    const questions =
+      (document.configuration.questions as unknown as SOAQuestion[]) ?? [];
+    const answersByQuestionId = new Map(
+      document.answers.map((answer) => [answer.questionId, answer.answer]),
+    );
+
+    const exportQuestions: SOAExportQuestion[] = questions.map((question) => ({
+      id: question.id,
+      text: question.text,
+      columnMapping: {
+        title: question.columnMapping?.title ?? null,
+        control_objective: question.columnMapping?.control_objective ?? null,
+        isApplicable: question.columnMapping?.isApplicable ?? null,
+        justification: question.columnMapping?.justification ?? null,
+      },
+      answer: answersByQuestionId.get(question.id) ?? null,
+    }));
+
+    return generateSOAExportFile(
+      exportQuestions,
+      document.framework.name || 'ISO 27001',
+      document.version,
+      dto.format,
+    );
+  }
+
   // Auto-fill related methods (delegating to utilities)
 
   async checkIfFullyRemote(organizationId: string): Promise<boolean> {
diff --git a/apps/api/src/soa/utils/export-generator.ts b/apps/api/src/soa/utils/export-generator.ts
new file mode 100644
index 0000000000..d75b45721e
--- /dev/null
+++ b/apps/api/src/soa/utils/export-generator.ts
@@ -0,0 +1,146 @@
+import { jsPDF } from 'jspdf';
+
+export type SOAExportFormat = 'pdf';
+
+export interface SOAExportQuestion {
+  id: string;
+  text: string;
+  columnMapping: {
+    title: string | null;
+    control_objective: string | null;
+    isApplicable: boolean | null;
+    justification: string | null;
+  };
+  answer: string | null;
+}
+
+export interface SOAExportResult {
+  fileBuffer: Buffer;
+  mimeType: string;
+  filename: string;
+}
+
+export function generateSOAExportFile(
+  questions: SOAExportQuestion[],
+  frameworkName: string,
+  version: number,
+  format: SOAExportFormat = 'pdf',
+): SOAExportResult {
+  if (format !== 'pdf') {
+    throw new Error(`Unsupported SOA export format: ${format}`);
+  }
+
+  return {
+    fileBuffer: generateSOAPDF(questions, frameworkName, version),
+    mimeType: 'application/pdf',
+    filename: `statement-of-applicability-${sanitizeFrameworkName(frameworkName)}-v${version}.pdf`,
+  };
+}
+
+function generateSOAPDF(
+  questions: SOAExportQuestion[],
+  frameworkName: string,
+  version: number,
+): Buffer {
+  const pdf = new jsPDF();
+  const pageWidth = pdf.internal.pageSize.getWidth();
+  const pageHeight = pdf.internal.pageSize.getHeight();
+  const margin = 20;
+  const contentWidth = pageWidth - margin * 2;
+  const lineHeight = 7;
+  let y = margin;
+
+  const ensureSpace = (requiredHeight: number) => {
+    if (y + requiredHeight > pageHeight - margin) {
+      pdf.addPage();
+      y = margin;
+    }
+  };
+
+  pdf.setFont('helvetica', 'bold');
+  pdf.setFontSize(16);
+  pdf.text('Statement of Applicability', margin, y);
+  y += lineHeight * 1.8;
+
+  pdf.setFont('helvetica', 'normal');
+  pdf.setFontSize(10);
+  pdf.text(`Framework: ${frameworkName}`, margin, y);
+  y += lineHeight;
+  pdf.text(`Version: v${version}`, margin, y);
+  y += lineHeight;
+  pdf.text(`Exported: ${new Date().toLocaleDateString()}`, margin, y);
+  y += lineHeight * 2;
+
+  pdf.setFontSize(11);
+  for (let i = 0; i < questions.length; i++) {
+    const question = questions[i];
+    const mapped = question.columnMapping ?? {
+      title: null,
+      control_objective: null,
+      isApplicable: null,
+      justification: null,
+    };
+
+    const isApplicableLabel =
+      mapped.isApplicable === true
+        ? 'Yes'
+        : mapped.isApplicable === false
+          ? 'No'
+          : 'N/A';
+
+    const justification =
+      typeof mapped.justification === 'string' && mapped.justification.trim()
+        ? mapped.justification
+        : question.answer || 'No justification provided';
+
+    const title = `${i + 1}. ${mapped.title || question.text || 'Untitled Control'}`;
+    const objective = mapped.control_objective
+      ? `Objective: ${mapped.control_objective}`
+      : null;
+    const applicability = `Applicable: ${isApplicableLabel}`;
+    const justificationText = `Justification: ${justification}`;
+
+    const titleLines = pdf.splitTextToSize(title, contentWidth);
+    const objectiveLines = objective
+      ? pdf.splitTextToSize(objective, contentWidth)
+      : [];
+    const applicabilityLines = pdf.splitTextToSize(applicability, contentWidth);
+    const justificationLines = pdf.splitTextToSize(
+      justificationText,
+      contentWidth,
+    );
+    const blockHeight =
+      (titleLines.length +
+        objectiveLines.length +
+        applicabilityLines.length +
+        justificationLines.length) *
+        lineHeight +
+      lineHeight * 1.5;
+
+    ensureSpace(blockHeight);
+
+    pdf.setFont('helvetica', 'bold');
+    pdf.text(titleLines, margin, y);
+    y += titleLines.length * lineHeight;
+
+    pdf.setFont('helvetica', 'normal');
+    if (objectiveLines.length > 0) {
+      pdf.text(objectiveLines, margin, y);
+      y += objectiveLines.length * lineHeight;
+    }
+    pdf.text(applicabilityLines, margin, y);
+    y += applicabilityLines.length * lineHeight;
+    pdf.text(justificationLines, margin, y);
+    y += justificationLines.length * lineHeight + lineHeight * 0.5;
+  }
+
+  return Buffer.from(pdf.output('arraybuffer'));
+}
+
+function sanitizeFrameworkName(frameworkName: string): string {
+  return (frameworkName || 'soa')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/(^-|-$)/g, '');
+}
+

From e6731b2bed8b50b8e50b4fffdecf61eaafe9e9bd Mon Sep 17 00:00:00 2001
From: chasprowebdev <chasgarciaprowebdev@gmail.com>
Date: Thu, 23 Apr 2026 16:54:39 -0400
Subject: [PATCH 06/40] fix(app): export Statement of Applicability as pdf

---
 .../StatementOfApplicabilitySection.tsx       | 66 +++++++++++++++++--
 .../hooks/useSOADocument.ts                   | 66 ++++++++++++++++++-
 2 files changed, 125 insertions(+), 7 deletions(-)

diff --git a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/StatementOfApplicabilitySection.tsx b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/StatementOfApplicabilitySection.tsx
index 6f61619587..7c496e4090 100644
--- a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/StatementOfApplicabilitySection.tsx
+++ b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/StatementOfApplicabilitySection.tsx
@@ -1,4 +1,8 @@
-import { PageHeader, Text } from '@trycompai/design-system';
+'use client';
+
+import { Button, PageHeader, Text } from '@trycompai/design-system';
+import { Download } from '@trycompai/design-system/icons';
+import { useSOADocument } from '../hooks/useSOADocument';
 import { SOAFrameworkTable } from './SOAFrameworkTable';
 
 type SOAFrameworkTableProps = Parameters<typeof SOAFrameworkTable>[0];
@@ -22,10 +26,31 @@ interface StatementOfApplicabilitySectionProps {
   soaError?: string | null;
 }
 
-function SectionHeader() {
+function SectionHeader({
+  onExport,
+  isExporting,
+  canExport,
+}: {
+  onExport: () => void;
+  isExporting: boolean;
+  canExport: boolean;
+}) {
   return (
     <>
-      <PageHeader title="Statement of Applicability" />
+      <PageHeader
+        title="Statement of Applicability"
+        actions={
+          <Button
+            type="button"
+            variant="secondary"
+            iconLeft={<Download size={16} />}
+            onClick={onExport}
+            disabled={!canExport || isExporting}
+          >
+            {isExporting ? 'Exporting...' : 'Export PDF'}
+          </Button>
+        }
+      />
       <div className="line-clamp-1">
         <Text variant="muted">
           Auto-complete Statement of Applicability for ISO 27001. Generate answers based on your
@@ -41,10 +66,27 @@ export function StatementOfApplicabilitySection({
   soaData,
   soaError,
 }: StatementOfApplicabilitySectionProps) {
+  const soaDocumentId =
+    ((soaData?.document as { id?: string | null } | null | undefined)?.id ??
+      null);
+  const { handleExport, isExporting } = useSOADocument({
+    documentId: soaDocumentId,
+    organizationId,
+    fallbackData:
+      (soaData?.document as Parameters<typeof useSOADocument>[0]['fallbackData']) ??
+      null,
+  });
+
   if (soaError) {
     return (
       <div className="flex flex-col gap-8">
-        <SectionHeader />
+        <SectionHeader
+          onExport={() => {
+            void handleExport('pdf');
+          }}
+          isExporting={isExporting}
+          canExport={false}
+        />
         <div className="flex items-center justify-center rounded-lg border py-12">
           <Text variant="muted">{soaError}</Text>
         </div>
@@ -55,7 +97,13 @@ export function StatementOfApplicabilitySection({
   if (soaData) {
     return (
       <div className="flex flex-col gap-8">
-        <SectionHeader />
+        <SectionHeader
+          onExport={() => {
+            void handleExport('pdf');
+          }}
+          isExporting={isExporting}
+          canExport={!!soaDocumentId}
+        />
         <SOAFrameworkTable
           framework={soaData.framework}
           configuration={soaData.configuration}
@@ -77,7 +125,13 @@ export function StatementOfApplicabilitySection({
 
   return (
     <div className="flex flex-col gap-8">
-      <SectionHeader />
+      <SectionHeader
+        onExport={() => {
+          void handleExport('pdf');
+        }}
+        isExporting={isExporting}
+        canExport={false}
+      />
       <div className="flex items-center justify-center py-12">
         <div className="h-6 w-6 animate-spin rounded-full border-2 border-muted-foreground border-t-transparent" />
       </div>
diff --git a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/hooks/useSOADocument.ts b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/hooks/useSOADocument.ts
index 790d5ecc6d..f74d261fd2 100644
--- a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/hooks/useSOADocument.ts
+++ b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/hooks/useSOADocument.ts
@@ -1,8 +1,10 @@
 'use client';
 
 import useSWR from 'swr';
-import { useEffect, useRef } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { api } from '@/lib/api-client';
+import { env } from '@/env.mjs';
+import { toast } from 'sonner';
 
 interface SOADocumentData {
   id: string;
@@ -28,6 +30,7 @@ function buildKey(documentId: string | null) {
 }
 
 export function useSOADocument({ documentId, organizationId, fallbackData }: UseSOADocumentOptions) {
+  const [isExporting, setIsExporting] = useState(false);
   const { data, error, isLoading, mutate } = useSWR<SOADocumentData | null>(
     buildKey(documentId),
     null,
@@ -123,15 +126,76 @@ export function useSOADocument({ documentId, organizationId, fallbackData }: Use
     return true;
   };
 
+  const handleExport = async (format: 'pdf' = 'pdf'): Promise<void> => {
+    if (!documentId) {
+      toast.error('No SOA document to export');
+      return;
+    }
+
+    setIsExporting(true);
+    try {
+      const response = await fetch(
+        `${env.NEXT_PUBLIC_API_URL || 'http://localhost:3333'}/v1/soa/export`,
+        {
+          method: 'POST',
+          credentials: 'include',
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify({
+            documentId,
+            organizationId,
+            format,
+          }),
+        },
+      );
+
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        throw new Error(errorData.message || 'Failed to export SOA document');
+      }
+
+      const contentDisposition = response.headers.get('Content-Disposition');
+      let filename = `statement-of-applicability.${format}`;
+      if (contentDisposition) {
+        const match = contentDisposition.match(/filename="(.+)"/);
+        if (match) {
+          filename = match[1];
+        }
+      }
+
+      const blob = await response.blob();
+      const url = window.URL.createObjectURL(blob);
+      const link = document.createElement('a');
+      link.href = url;
+      link.download = filename;
+      document.body.appendChild(link);
+      link.click();
+      document.body.removeChild(link);
+      window.URL.revokeObjectURL(url);
+
+      toast.success(`Exported as ${filename}`);
+    } catch (error) {
+      console.error('SOA export error:', error);
+      toast.error(
+        error instanceof Error ? error.message : 'Failed to export SOA document',
+      );
+    } finally {
+      setIsExporting(false);
+    }
+  };
+
   return {
     document: data ?? null,
     error,
     isLoading,
+    isExporting,
     mutate,
     saveAnswer,
     approve,
     decline,
     submitForApproval,
+    handleExport,
   };
 }
 

From 1d3f903915a5bc6932020065d768fa32d5e2ee66 Mon Sep 17 00:00:00 2001
From: chasprowebdev <chasgarciaprowebdev@gmail.com>
Date: Thu, 23 Apr 2026 21:49:26 -0400
Subject: [PATCH 07/40] fix(api): add metrics to SOA pdf document

---
 apps/api/src/soa/soa.service.ts            | 26 ++++++++++++
 apps/api/src/soa/utils/export-generator.ts | 49 +++++++++++++++++++++-
 2 files changed, 74 insertions(+), 1 deletion(-)

diff --git a/apps/api/src/soa/soa.service.ts b/apps/api/src/soa/soa.service.ts
index ca5ac33c21..8749449a92 100644
--- a/apps/api/src/soa/soa.service.ts
+++ b/apps/api/src/soa/soa.service.ts
@@ -19,6 +19,7 @@ import { loadISOConfig } from './utils/transform-iso-config';
 import { ISO27001_FRAMEWORK_NAMES } from './utils/constants';
 import {
   generateSOAExportFile,
+  type SOAExportMetadata,
   type SOAExportQuestion,
 } from './utils/export-generator';
 import {
@@ -457,6 +458,16 @@ export class SOAService {
         framework: {
           select: { name: true },
         },
+        approver: {
+          select: {
+            user: {
+              select: {
+                name: true,
+                email: true,
+              },
+            },
+          },
+        },
         answers: {
           where: { isLatestAnswer: true },
           select: {
@@ -481,6 +492,7 @@ export class SOAService {
       id: question.id,
       text: question.text,
       columnMapping: {
+        closure: question.columnMapping?.closure ?? null,
         title: question.columnMapping?.title ?? null,
         control_objective: question.columnMapping?.control_objective ?? null,
         isApplicable: question.columnMapping?.isApplicable ?? null,
@@ -489,10 +501,24 @@ export class SOAService {
       answer: answersByQuestionId.get(question.id) ?? null,
     }));
 
+    const exportMetadata: SOAExportMetadata = {
+      preparedBy: (document.preparedBy as string | null) ?? null,
+      answeredQuestions: document.answeredQuestions,
+      totalQuestions: document.totalQuestions,
+      approvedAt: document.approvedAt ?? null,
+      declinedAt: (document as { declinedAt?: Date | null }).declinedAt ?? null,
+      status: document.status,
+      approverName:
+        document.approver?.user?.name ||
+        document.approver?.user?.email ||
+        null,
+    };
+
     return generateSOAExportFile(
       exportQuestions,
       document.framework.name || 'ISO 27001',
       document.version,
+      exportMetadata,
       dto.format,
     );
   }
diff --git a/apps/api/src/soa/utils/export-generator.ts b/apps/api/src/soa/utils/export-generator.ts
index d75b45721e..f53f6c0bed 100644
--- a/apps/api/src/soa/utils/export-generator.ts
+++ b/apps/api/src/soa/utils/export-generator.ts
@@ -6,6 +6,7 @@ export interface SOAExportQuestion {
   id: string;
   text: string;
   columnMapping: {
+    closure?: string | null;
     title: string | null;
     control_objective: string | null;
     isApplicable: boolean | null;
@@ -14,6 +15,16 @@ export interface SOAExportQuestion {
   answer: string | null;
 }
 
+export interface SOAExportMetadata {
+  preparedBy: string | null;
+  answeredQuestions: number;
+  totalQuestions: number;
+  approvedAt?: Date | string | null;
+  declinedAt?: Date | string | null;
+  status?: string | null;
+  approverName?: string | null;
+}
+
 export interface SOAExportResult {
   fileBuffer: Buffer;
   mimeType: string;
@@ -24,6 +35,7 @@ export function generateSOAExportFile(
   questions: SOAExportQuestion[],
   frameworkName: string,
   version: number,
+  metadata: SOAExportMetadata,
   format: SOAExportFormat = 'pdf',
 ): SOAExportResult {
   if (format !== 'pdf') {
@@ -31,7 +43,7 @@ export function generateSOAExportFile(
   }
 
   return {
-    fileBuffer: generateSOAPDF(questions, frameworkName, version),
+    fileBuffer: generateSOAPDF(questions, frameworkName, version, metadata),
     mimeType: 'application/pdf',
     filename: `statement-of-applicability-${sanitizeFrameworkName(frameworkName)}-v${version}.pdf`,
   };
@@ -41,6 +53,7 @@ function generateSOAPDF(
   questions: SOAExportQuestion[],
   frameworkName: string,
   version: number,
+  metadata: SOAExportMetadata,
 ): Buffer {
   const pdf = new jsPDF();
   const pageWidth = pdf.internal.pageSize.getWidth();
@@ -68,6 +81,29 @@ function generateSOAPDF(
   y += lineHeight;
   pdf.text(`Version: v${version}`, margin, y);
   y += lineHeight;
+  const progressPercentage =
+    metadata.totalQuestions > 0
+      ? Math.round((metadata.answeredQuestions / metadata.totalQuestions) * 100)
+      : 0;
+  pdf.text(
+    `Progress: ${metadata.answeredQuestions} / ${metadata.totalQuestions} (${progressPercentage}%)`,
+    margin,
+    y,
+  );
+  y += lineHeight;
+  pdf.text(`Prepared by: ${metadata.preparedBy || 'Comp AI'}`, margin, y);
+  y += lineHeight;
+  const approvalStatusText = metadata.approvedAt
+    ? `Approved on ${new Date(metadata.approvedAt).toLocaleDateString()}`
+    : metadata.status === 'needs_review' && metadata.declinedAt
+      ? `Declined on ${new Date(metadata.declinedAt).toLocaleDateString()}`
+      : metadata.approverName
+        ? 'Pending approval'
+        : 'Not approved';
+  pdf.text(`Approval status: ${approvalStatusText}`, margin, y);
+  y += lineHeight;
+  pdf.text(`Approved by: ${metadata.approverName || 'N/A'}`, margin, y);
+  y += lineHeight;
   pdf.text(`Exported: ${new Date().toLocaleDateString()}`, margin, y);
   y += lineHeight * 2;
 
@@ -94,6 +130,9 @@ function generateSOAPDF(
         : question.answer || 'No justification provided';
 
     const title = `${i + 1}. ${mapped.title || question.text || 'Untitled Control'}`;
+    const closure = mapped.closure
+      ? `Closure: ${mapped.closure}`
+      : null;
     const objective = mapped.control_objective
       ? `Objective: ${mapped.control_objective}`
       : null;
@@ -101,6 +140,9 @@ function generateSOAPDF(
     const justificationText = `Justification: ${justification}`;
 
     const titleLines = pdf.splitTextToSize(title, contentWidth);
+    const closureLines = closure
+      ? pdf.splitTextToSize(closure, contentWidth)
+      : [];
     const objectiveLines = objective
       ? pdf.splitTextToSize(objective, contentWidth)
       : [];
@@ -111,6 +153,7 @@ function generateSOAPDF(
     );
     const blockHeight =
       (titleLines.length +
+        closureLines.length +
         objectiveLines.length +
         applicabilityLines.length +
         justificationLines.length) *
@@ -124,6 +167,10 @@ function generateSOAPDF(
     y += titleLines.length * lineHeight;
 
     pdf.setFont('helvetica', 'normal');
+    if (closureLines.length > 0) {
+      pdf.text(closureLines, margin, y);
+      y += closureLines.length * lineHeight;
+    }
     if (objectiveLines.length > 0) {
       pdf.text(objectiveLines, margin, y);
       y += objectiveLines.length * lineHeight;

From fd5ba8b72596babf5d55c485296559fe2bc69a54 Mon Sep 17 00:00:00 2001
From: chasprowebdev <chasgarciaprowebdev@gmail.com>
Date: Thu, 23 Apr 2026 21:58:57 -0400
Subject: [PATCH 08/40] fix(app): add organizationId to frameworks SWR cache

---
 .../[orgId]/documents/components/CompanyOverviewCards.tsx     | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/app/src/app/(app)/[orgId]/documents/components/CompanyOverviewCards.tsx b/apps/app/src/app/(app)/[orgId]/documents/components/CompanyOverviewCards.tsx
index 2cb3ec7bf1..72f909980f 100644
--- a/apps/app/src/app/(app)/[orgId]/documents/components/CompanyOverviewCards.tsx
+++ b/apps/app/src/app/(app)/[orgId]/documents/components/CompanyOverviewCards.tsx
@@ -121,8 +121,8 @@ export function CompanyOverviewCards({ organizationId }: { organizationId: strin
 
   const { data: findingsResponse } = useOrganizationFindings();
   const { data: frameworksResponse } = useSWR<FrameworkListResponse>(
-    '/v1/frameworks',
-    async (endpoint: string) => {
+    ['/v1/frameworks', organizationId] as const,
+    async ([endpoint]: readonly [string, string]) => {
       const response = await api.get<FrameworkListResponse>(endpoint);
       if (response.error || !response.data) {
         throw new Error(response.error ?? 'Failed to load frameworks');

From 49c16732b2748e15a93d2354f2cb172980a9914d Mon Sep 17 00:00:00 2001
From: chasprowebdev <chasgarciaprowebdev@gmail.com>
Date: Thu, 23 Apr 2026 22:04:26 -0400
Subject: [PATCH 09/40] fix(app): remove use of hasISO27001Framework on
 CompanyOverviewCards

---
 .../[orgId]/documents/components/CompanyOverviewCards.tsx      | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/apps/app/src/app/(app)/[orgId]/documents/components/CompanyOverviewCards.tsx b/apps/app/src/app/(app)/[orgId]/documents/components/CompanyOverviewCards.tsx
index 72f909980f..b617918b73 100644
--- a/apps/app/src/app/(app)/[orgId]/documents/components/CompanyOverviewCards.tsx
+++ b/apps/app/src/app/(app)/[orgId]/documents/components/CompanyOverviewCards.tsx
@@ -173,12 +173,11 @@ export function CompanyOverviewCards({ organizationId }: { organizationId: strin
         ISO27001_NAMES.includes(frameworkInstance.framework.name),
     );
   }, [frameworksResponse]);
-  const hasISO27001Framework = !!iso27001Framework;
   const iso27001FrameworkId = iso27001Framework?.frameworkId ?? null;
 
   return (
     <Stack gap="6">
-      {hasISO27001Framework && iso27001FrameworkId && (
+      {iso27001FrameworkId && (
         <SOAOverviewCard
           organizationId={organizationId}
           iso27001FrameworkId={iso27001FrameworkId}

From 993e89b01f7a96ff3fa133ea2e7e6619d6e1e019 Mon Sep 17 00:00:00 2001
From: chasprowebdev <chasgarciaprowebdev@gmail.com>
Date: Thu, 23 Apr 2026 22:05:09 -0400
Subject: [PATCH 10/40] fix(app): remove use of ai-vendor-questionnaire FF for
 SOA page

---
 .../[orgId]/documents/statement-of-applicability/page.tsx | 8 --------
 1 file changed, 8 deletions(-)

diff --git a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/page.tsx b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/page.tsx
index c098e0034b..002cdc4b8d 100644
--- a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/page.tsx
+++ b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/page.tsx
@@ -1,4 +1,3 @@
-import { getFeatureFlags } from '@/app/posthog';
 import { serverApi } from '@/lib/api-server';
 import { auth } from '@/utils/auth';
 import { Breadcrumb, PageLayout } from '@trycompai/design-system';
@@ -63,13 +62,6 @@ export default async function StatementOfApplicabilityPage({
     return notFound();
   }
 
-  const flags = await getFeatureFlags(session.user.id);
-  const isFeatureEnabled = flags['ai-vendor-questionnaire'] === true;
-
-  if (!isFeatureEnabled) {
-    return notFound();
-  }
-
   const organizationId = session.session.activeOrganizationId;
 
   const [frameworksResult, peopleResult, contextResult] = await Promise.all([

From 589f28516c5c296e3f6f0b5844b5de02c77a5562 Mon Sep 17 00:00:00 2001
From: chasprowebdev <chasgarciaprowebdev@gmail.com>
Date: Thu, 23 Apr 2026 23:24:57 -0400
Subject: [PATCH 11/40] fix(api): fix pagination overflow for long question
 blocks in soa pdf

---
 apps/api/src/soa/utils/export-generator.ts | 47 +++++++++-------------
 1 file changed, 19 insertions(+), 28 deletions(-)

diff --git a/apps/api/src/soa/utils/export-generator.ts b/apps/api/src/soa/utils/export-generator.ts
index f53f6c0bed..fdeacb22af 100644
--- a/apps/api/src/soa/utils/export-generator.ts
+++ b/apps/api/src/soa/utils/export-generator.ts
@@ -69,6 +69,18 @@ function generateSOAPDF(
       y = margin;
     }
   };
+  const writeLines = (
+    lines: string[],
+    fontStyle: 'normal' | 'bold' = 'normal',
+  ) => {
+    if (lines.length === 0) return;
+    pdf.setFont('helvetica', fontStyle);
+    for (const line of lines) {
+      ensureSpace(lineHeight);
+      pdf.text(line, margin, y);
+      y += lineHeight;
+    }
+  };
 
   pdf.setFont('helvetica', 'bold');
   pdf.setFontSize(16);
@@ -151,34 +163,13 @@ function generateSOAPDF(
       justificationText,
       contentWidth,
     );
-    const blockHeight =
-      (titleLines.length +
-        closureLines.length +
-        objectiveLines.length +
-        applicabilityLines.length +
-        justificationLines.length) *
-        lineHeight +
-      lineHeight * 1.5;
-
-    ensureSpace(blockHeight);
-
-    pdf.setFont('helvetica', 'bold');
-    pdf.text(titleLines, margin, y);
-    y += titleLines.length * lineHeight;
-
-    pdf.setFont('helvetica', 'normal');
-    if (closureLines.length > 0) {
-      pdf.text(closureLines, margin, y);
-      y += closureLines.length * lineHeight;
-    }
-    if (objectiveLines.length > 0) {
-      pdf.text(objectiveLines, margin, y);
-      y += objectiveLines.length * lineHeight;
-    }
-    pdf.text(applicabilityLines, margin, y);
-    y += applicabilityLines.length * lineHeight;
-    pdf.text(justificationLines, margin, y);
-    y += justificationLines.length * lineHeight + lineHeight * 0.5;
+    writeLines(titleLines, 'bold');
+    writeLines(closureLines);
+    writeLines(objectiveLines);
+    writeLines(applicabilityLines);
+    writeLines(justificationLines);
+    ensureSpace(lineHeight * 0.5);
+    y += lineHeight * 0.5;
   }
 
   return Buffer.from(pdf.output('arraybuffer'));

From ada6b5e4515092087c58288fd6049ef0caac5b00 Mon Sep 17 00:00:00 2001
From: chasprowebdev <chasgarciaprowebdev@gmail.com>
Date: Fri, 24 Apr 2026 10:48:35 -0400
Subject: [PATCH 12/40] fix(api): correct SOA export classification for
 declined cases

---
 apps/api/src/soa/utils/export-generator.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/api/src/soa/utils/export-generator.ts b/apps/api/src/soa/utils/export-generator.ts
index fdeacb22af..02ae96088e 100644
--- a/apps/api/src/soa/utils/export-generator.ts
+++ b/apps/api/src/soa/utils/export-generator.ts
@@ -107,7 +107,7 @@ function generateSOAPDF(
   y += lineHeight;
   const approvalStatusText = metadata.approvedAt
     ? `Approved on ${new Date(metadata.approvedAt).toLocaleDateString()}`
-    : metadata.status === 'needs_review' && metadata.declinedAt
+    : metadata.status === 'declined' && metadata.declinedAt
       ? `Declined on ${new Date(metadata.declinedAt).toLocaleDateString()}`
       : metadata.approverName
         ? 'Pending approval'

From 760c3048e171cee420201ad537217aed7e24411c Mon Sep 17 00:00:00 2001
From: chasprowebdev <chasgarciaprowebdev@gmail.com>
Date: Fri, 24 Apr 2026 10:51:26 -0400
Subject: [PATCH 13/40] fix(app): use exact role checks instead of substring
 matching

---
 .../documents/statement-of-applicability/page.tsx   | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/page.tsx b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/page.tsx
index 002cdc4b8d..0e003a34e1 100644
--- a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/page.tsx
+++ b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/page.tsx
@@ -1,4 +1,5 @@
 import { serverApi } from '@/lib/api-server';
+import { parseRolesString } from '@/lib/permissions';
 import { auth } from '@/utils/auth';
 import { Breadcrumb, PageLayout } from '@trycompai/design-system';
 import { headers } from 'next/headers';
@@ -105,9 +106,10 @@ export default async function StatementOfApplicabilityPage({
         const currentMember =
           people.find((p) => p.userId === session.user.id && !p.deactivated) ?? null;
 
-        const canApprove = currentMember
-          ? currentMember.role.includes('owner') || currentMember.role.includes('admin')
-          : false;
+        const currentMemberRoles = parseRolesString(currentMember?.role);
+        const canApprove = currentMemberRoles.some(
+          (role) => role === 'owner' || role === 'admin',
+        );
 
         const isPendingApproval = document.status === 'needs_review';
         const canCurrentUserApprove = isPendingApproval && approverId === currentMember?.id;
@@ -115,7 +117,10 @@ export default async function StatementOfApplicabilityPage({
         const ownerAdminMembers = people
           .filter(
             (p) =>
-              !p.deactivated && (p.role.includes('owner') || p.role.includes('admin')),
+              !p.deactivated &&
+              parseRolesString(p.role).some(
+                (role) => role === 'owner' || role === 'admin',
+              ),
           )
           .sort((a, b) => (a.user?.name ?? '').localeCompare(b.user?.name ?? ''));
 

From 24f97917b9be58f1b5d218415012b654507dd913 Mon Sep 17 00:00:00 2001
From: chasprowebdev <chasgarciaprowebdev@gmail.com>
Date: Fri, 24 Apr 2026 10:54:36 -0400
Subject: [PATCH 14/40] fix(api): add coverage for SOA export endpoint

---
 apps/api/src/soa/soa.controller.spec.ts |  47 ++++++++++
 apps/api/src/soa/soa.service.spec.ts    | 111 ++++++++++++++++++++++++
 2 files changed, 158 insertions(+)

diff --git a/apps/api/src/soa/soa.controller.spec.ts b/apps/api/src/soa/soa.controller.spec.ts
index f2dd111cef..83fa7db005 100644
--- a/apps/api/src/soa/soa.controller.spec.ts
+++ b/apps/api/src/soa/soa.controller.spec.ts
@@ -1,5 +1,6 @@
 import { Test, TestingModule } from '@nestjs/testing';
 import { BadRequestException } from '@nestjs/common';
+import type { Response } from 'express';
 import { HybridAuthGuard } from '../auth/hybrid-auth.guard';
 import { PermissionGuard } from '../auth/permission.guard';
 import type { AuthContext } from '../auth/types';
@@ -9,6 +10,15 @@ import { SOAService } from './soa.service';
 jest.mock('../auth/auth.server', () => ({
   auth: { api: { getSession: jest.fn() } },
 }));
+jest.mock('../auth/hybrid-auth.guard', () => ({
+  HybridAuthGuard: class MockHybridAuthGuard {},
+}));
+jest.mock('../auth/permission.guard', () => ({
+  PermissionGuard: class MockPermissionGuard {},
+}));
+jest.mock('./soa.service', () => ({
+  SOAService: class MockSOAService {},
+}));
 
 jest.mock('@trycompai/auth', () => ({
   statement: {},
@@ -37,6 +47,7 @@ describe('SOAController', () => {
     approveDocument: jest.fn(),
     declineDocument: jest.fn(),
     submitForApproval: jest.fn(),
+    exportDocument: jest.fn(),
   };
 
   const mockGuard = { canActivate: jest.fn().mockReturnValue(true) };
@@ -210,4 +221,40 @@ describe('SOAController', () => {
       expect(result).toEqual(submitted);
     });
   });
+
+  describe('exportDocument', () => {
+    const dto = {
+      documentId: 'doc_1',
+      format: 'pdf',
+    };
+
+    it('should call soaService.exportDocument, set headers, and send file buffer', async () => {
+      const fileBuffer = Buffer.from('pdf-data');
+      mockSOAService.exportDocument.mockResolvedValue({
+        fileBuffer,
+        mimeType: 'application/pdf',
+        filename: 'soa-export.pdf',
+      });
+      const res = {
+        setHeader: jest.fn(),
+        send: jest.fn(),
+      } as unknown as Response;
+
+      await controller.exportDocument(dto as never, res, 'org_123');
+
+      expect(soaService.exportDocument).toHaveBeenCalledWith({
+        ...dto,
+        organizationId: 'org_123',
+      });
+      expect(res.setHeader).toHaveBeenCalledWith(
+        'Content-Type',
+        'application/pdf',
+      );
+      expect(res.setHeader).toHaveBeenCalledWith(
+        'Content-Disposition',
+        'attachment; filename="soa-export.pdf"',
+      );
+      expect(res.send).toHaveBeenCalledWith(fileBuffer);
+    });
+  });
 });
diff --git a/apps/api/src/soa/soa.service.spec.ts b/apps/api/src/soa/soa.service.spec.ts
index 8c87ad045f..c9e5e7afbe 100644
--- a/apps/api/src/soa/soa.service.spec.ts
+++ b/apps/api/src/soa/soa.service.spec.ts
@@ -6,6 +6,7 @@ import {
 } from '@nestjs/common';
 import { db } from '@db';
 import { SOAService } from './soa.service';
+import { generateSOAExportFile } from './utils/export-generator';
 
 jest.mock('@db', () => ({
   db: {
@@ -51,8 +52,12 @@ jest.mock('./utils/soa-storage', () => ({
   updateDocumentAnsweredCount: jest.fn(),
   checkIfFullyRemote: jest.fn(),
 }));
+jest.mock('./utils/export-generator', () => ({
+  generateSOAExportFile: jest.fn(),
+}));
 
 const mockDb = jest.mocked(db);
+const mockGenerateSOAExportFile = jest.mocked(generateSOAExportFile);
 
 describe('SOAService', () => {
   let service: SOAService;
@@ -298,4 +303,110 @@ describe('SOAService', () => {
       expect(result.success).toBe(true);
     });
   });
+
+  describe('exportDocument', () => {
+    const dto = {
+      documentId: 'doc-1',
+      organizationId: 'org-1',
+      format: 'pdf' as const,
+    };
+
+    it('throws NotFoundException when document not found', async () => {
+      (mockDb.sOADocument.findFirst as jest.Mock).mockResolvedValue(null);
+
+      await expect(service.exportDocument(dto)).rejects.toThrow(NotFoundException);
+    });
+
+    it('maps document data and delegates to generateSOAExportFile', async () => {
+      const generated = {
+        fileBuffer: Buffer.from('pdf'),
+        mimeType: 'application/pdf',
+        filename: 'statement-of-applicability-iso-27001-v2.pdf',
+      };
+      mockGenerateSOAExportFile.mockReturnValue(generated);
+      (mockDb.sOADocument.findFirst as jest.Mock).mockResolvedValue({
+        id: 'doc-1',
+        organizationId: 'org-1',
+        preparedBy: 'Compliance Lead',
+        answeredQuestions: 3,
+        totalQuestions: 5,
+        approvedAt: null,
+        declinedAt: new Date('2026-04-20T00:00:00.000Z'),
+        status: 'declined',
+        version: 2,
+        framework: { name: 'ISO 27001' },
+        configuration: {
+          questions: [
+            {
+              id: 'q-1',
+              text: 'Control 1',
+              columnMapping: {
+                closure: 'A.5',
+                title: 'Control title',
+                control_objective: 'Objective',
+                isApplicable: true,
+                justification: 'Mapped justification',
+              },
+            },
+            {
+              id: 'q-2',
+              text: 'Control 2',
+              columnMapping: {},
+            },
+          ],
+        },
+        approver: {
+          user: {
+            name: 'Approver Name',
+            email: 'approver@example.com',
+          },
+        },
+        answers: [{ questionId: 'q-2', answer: 'Fallback answer' }],
+      });
+
+      const result = await service.exportDocument(dto);
+
+      expect(mockGenerateSOAExportFile).toHaveBeenCalledWith(
+        [
+          {
+            id: 'q-1',
+            text: 'Control 1',
+            columnMapping: {
+              closure: 'A.5',
+              title: 'Control title',
+              control_objective: 'Objective',
+              isApplicable: true,
+              justification: 'Mapped justification',
+            },
+            answer: null,
+          },
+          {
+            id: 'q-2',
+            text: 'Control 2',
+            columnMapping: {
+              closure: null,
+              title: null,
+              control_objective: null,
+              isApplicable: null,
+              justification: null,
+            },
+            answer: 'Fallback answer',
+          },
+        ],
+        'ISO 27001',
+        2,
+        {
+          preparedBy: 'Compliance Lead',
+          answeredQuestions: 3,
+          totalQuestions: 5,
+          approvedAt: null,
+          declinedAt: new Date('2026-04-20T00:00:00.000Z'),
+          status: 'declined',
+          approverName: 'Approver Name',
+        },
+        'pdf',
+      );
+      expect(result).toEqual(generated);
+    });
+  });
 });

From a5e898876c990a0f947ee53150d2a165f08c8491 Mon Sep 17 00:00:00 2001
From: chasprowebdev <chasgarciaprowebdev@gmail.com>
Date: Fri, 24 Apr 2026 11:47:12 -0400
Subject: [PATCH 15/40] fix(framework-editor): add SOA document to ISO 27001
 framework

---
 .../(pages)/controls/document-type-options.ts    |  5 +++++
 .../(pages)/documents/DocumentControlsCell.tsx   | 16 ++++++++++++++--
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/apps/framework-editor/app/(pages)/controls/document-type-options.ts b/apps/framework-editor/app/(pages)/controls/document-type-options.ts
index 332eb364b6..32b81c582c 100644
--- a/apps/framework-editor/app/(pages)/controls/document-type-options.ts
+++ b/apps/framework-editor/app/(pages)/controls/document-type-options.ts
@@ -10,6 +10,11 @@ export const DOCUMENT_TYPE_OPTIONS: MultiSelectOption[] = [
   { value: 'rbac_matrix', label: 'RBAC Matrix', category: 'Security' },
   { value: 'infrastructure_inventory', label: 'Infrastructure Inventory', category: 'Security' },
   { value: 'network_diagram', label: 'Network Diagram', category: 'Security' },
+  {
+    value: 'statement_of_applicability',
+    label: 'Statement of Applicability',
+    category: 'SOA',
+  },
   { value: 'tabletop_exercise', label: 'Incident Response Tabletop Exercise', category: 'Security' },
   { value: 'whistleblower_report', label: 'Whistleblower Report', category: 'People' },
   { value: 'employee_performance_evaluation', label: 'Employee Performance Evaluation', category: 'People' },
diff --git a/apps/framework-editor/app/(pages)/documents/DocumentControlsCell.tsx b/apps/framework-editor/app/(pages)/documents/DocumentControlsCell.tsx
index e52c35ee11..38b5209445 100644
--- a/apps/framework-editor/app/(pages)/documents/DocumentControlsCell.tsx
+++ b/apps/framework-editor/app/(pages)/documents/DocumentControlsCell.tsx
@@ -24,6 +24,7 @@ export function DocumentControlsCell({
   onControlLinked,
   onControlUnlinked,
 }: DocumentControlsCellProps) {
+  const isSOADocument = documentType === 'statement_of_applicability';
   const [isExpanded, setIsExpanded] = useState(false);
   const [isSearching, setIsSearching] = useState(false);
   const [search, setSearch] = useState('');
@@ -67,6 +68,11 @@ export function DocumentControlsCell({
 
   const handleLink = useCallback(
     async (control: { id: string; name: string }) => {
+      if (isSOADocument) {
+        toast.info('Linking controls is disabled for Statement of Applicability');
+        return;
+      }
+
       try {
         const current = await apiClient<ControlTemplate>(`/control-template/${control.id}`);
         const currentTypes: string[] = Array.isArray(current.documentTypes)
@@ -86,7 +92,7 @@ export function DocumentControlsCell({
       setSearch('');
       setIsSearching(false);
     },
-    [documentType, onControlLinked],
+    [documentType, isSOADocument, onControlLinked],
   );
 
   const handleUnlink = useCallback(
@@ -211,12 +217,18 @@ export function DocumentControlsCell({
           <button
             type="button"
             onClick={() => setIsSearching(true)}
-            className="border-border hover:bg-muted flex w-full items-center justify-center gap-1 rounded-xs border px-3 py-1.5 text-sm"
+            disabled={isSOADocument}
+            className="border-border hover:bg-muted disabled:text-muted-foreground disabled:bg-muted/40 disabled:cursor-not-allowed flex w-full items-center justify-center gap-1 rounded-xs border px-3 py-1.5 text-sm"
           >
             <Plus className="h-3 w-3" />
             Add Control
           </button>
         )}
+        {isSOADocument && (
+          <p className="text-muted-foreground mt-2 text-xs">
+            Linking controls is disabled for Statement of Applicability.
+          </p>
+        )}
       </div>
     </div>
   );

From 2f12556fddfdaa68e2eb489b3bf88087572b1c1a Mon Sep 17 00:00:00 2001
From: chasprowebdev <chasgarciaprowebdev@gmail.com>
Date: Fri, 24 Apr 2026 12:52:51 -0400
Subject: [PATCH 16/40] fix(app): handle serverApi.post errors to prevent
 infinite loading on SOA page

---
 .../documents/statement-of-applicability/page.tsx  | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/page.tsx b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/page.tsx
index 0e003a34e1..e41b658023 100644
--- a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/page.tsx
+++ b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/page.tsx
@@ -93,10 +93,15 @@ export default async function StatementOfApplicabilityPage({
         document: Record<string, unknown> | null;
       }>('/v1/soa/ensure-setup', { frameworkId, organizationId });
 
-      const configuration = setupResult.data?.configuration;
-      const document = setupResult.data?.document;
+      const setupData = setupResult.data;
+      if (!setupData?.success) {
+        soaError = setupData?.error || 'Failed to setup SOA. Please try again later.';
+      }
+
+      const configuration = setupData?.configuration;
+      const document = setupData?.document;
 
-      if (configuration && document) {
+      if (!soaError && configuration && document) {
         let approver = null;
         const approverId = document.approverId as string | undefined;
         if (approverId) {
@@ -146,6 +151,9 @@ export default async function StatementOfApplicabilityPage({
           currentMemberId: currentMember?.id || null,
           ownerAdminMembers,
         } as SOAData;
+      } else if (!soaError) {
+        soaError =
+          'SOA setup did not return required configuration data. Please try again later.';
       }
     } catch (error) {
       console.error('Failed to setup SOA:', error);

From 38642badc3b477f4e98a2ca01956b25806a9d3b1 Mon Sep 17 00:00:00 2001
From: chasprowebdev <chasgarciaprowebdev@gmail.com>
Date: Fri, 24 Apr 2026 12:55:19 -0400
Subject: [PATCH 17/40] fix(api): correct SOA completion logic based on
 approvedAt for SOA

---
 apps/api/src/frameworks/frameworks-scores.helper.ts | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/apps/api/src/frameworks/frameworks-scores.helper.ts b/apps/api/src/frameworks/frameworks-scores.helper.ts
index c76aeb522d..ea843a86d5 100644
--- a/apps/api/src/frameworks/frameworks-scores.helper.ts
+++ b/apps/api/src/frameworks/frameworks-scores.helper.ts
@@ -251,12 +251,15 @@ async function computeDocumentsScore(organizationId: string) {
       },
       select: {
         approvedAt: true,
+        status: true,
       },
       orderBy: {
         updatedAt: 'desc',
       },
     });
-    soaCompleted = !!latestSOADocument?.approvedAt;
+    soaCompleted =
+      latestSOADocument?.status === 'completed' &&
+      !!latestSOADocument.approvedAt;
   }
 
   const soaTotalDocuments = hasSOADocumentRequirement ? 1 : 0;

From 140db39d9d7864fc0c6276b8462972fd44d32d8d Mon Sep 17 00:00:00 2001
From: chasprowebdev <chasgarciaprowebdev@gmail.com>
Date: Fri, 24 Apr 2026 13:03:08 -0400
Subject: [PATCH 18/40] fix(app): avoid defaulting to 'Not approved' before SOA
 status loads

---
 .../documents/components/SOAOverviewCard.tsx  | 25 ++++++++++++++++---
 1 file changed, 22 insertions(+), 3 deletions(-)

diff --git a/apps/app/src/app/(app)/[orgId]/documents/components/SOAOverviewCard.tsx b/apps/app/src/app/(app)/[orgId]/documents/components/SOAOverviewCard.tsx
index a9d2666a4a..110b8b1ee6 100644
--- a/apps/app/src/app/(app)/[orgId]/documents/components/SOAOverviewCard.tsx
+++ b/apps/app/src/app/(app)/[orgId]/documents/components/SOAOverviewCard.tsx
@@ -35,13 +35,29 @@ type SOASetupResponse = {
   } | null;
 };
 
-type SOAApprovalStatus = 'Approved' | 'Declined' | 'Pending' | 'Not approved';
+type SOAApprovalStatus =
+  | 'Approved'
+  | 'Declined'
+  | 'Pending'
+  | 'Not approved'
+  | 'Loading'
+  | 'Unavailable';
 
 function SOAApprovalStatusBadge({ status }: { status: SOAApprovalStatus }) {
   const statusConfig: Record<
     SOAApprovalStatus,
     { label: SOAApprovalStatus; className: string }
   > = {
+    Loading: {
+      label: 'Loading',
+      className:
+        'bg-slate-100 text-slate-700 dark:bg-slate-950/30 dark:text-slate-300',
+    },
+    Unavailable: {
+      label: 'Unavailable',
+      className:
+        'bg-slate-100 text-slate-700 dark:bg-slate-950/30 dark:text-slate-300',
+    },
     Approved: {
       label: 'Approved',
       className:
@@ -78,7 +94,8 @@ export function SOAOverviewCard({
   iso27001FrameworkId,
 }: SOAOverviewCardProps) {
   const form = STATEMENT_OF_APPLICABILITY_FORM;
-  const { data: soaSetupResponse } = useSWR<SOASetupResponse>(
+  const { data: soaSetupResponse, error: soaSetupError, isLoading: isLoadingSOASetup } =
+    useSWR<SOASetupResponse>(
     ['/v1/soa/ensure-setup', organizationId, iso27001FrameworkId],
     async ([endpoint, orgId, frameworkId]: readonly [string, string, string]) => {
       const response = await api.post<SOASetupResponse>(endpoint, {
@@ -97,6 +114,8 @@ export function SOAOverviewCard({
 
   const document = soaSetupResponse?.document;
   const approvalStatus = useMemo<SOAApprovalStatus>(() => {
+    if (isLoadingSOASetup) return 'Loading';
+    if (soaSetupError || !soaSetupResponse?.success) return 'Unavailable';
     if (!document) return 'Not approved';
     if (document.approvedAt) return 'Approved';
     if (document.declinedAt) return 'Declined';
@@ -108,7 +127,7 @@ export function SOAOverviewCard({
       return 'Pending';
     }
     return 'Not approved';
-  }, [document]);
+  }, [document, isLoadingSOASetup, soaSetupError, soaSetupResponse?.success]);
 
   return (
     <div className="space-y-3">

From 46b9575c4798bb9cada8b609954e0add20e1ba1e Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Fri, 24 Apr 2026 13:38:35 -0400
Subject: [PATCH 19/40] feat: allow selecting which policies to download when
 clicking download all

* feat(policies): allow filtering download-all by policyIds

* feat(policies): parse policyIds query param on download-all endpoint

* fix(policies): use typed mockAuthContext in controller spec

* feat(policies): add policy download picker sheet

* feat(policies): open download picker sheet from Download All button

* chore(policies): import icons from design-system re-export

* fix(policies): reset picker selection on reopen and accept array policyIds

Addresses cubic review on PR #2672:
- PolicyDownloadSheet: reset selection to current policy IDs whenever the
  sheet opens or the policies prop changes, so reopens and upstream data
  refreshes don't leave stale or deleted IDs selected.
- Controller: accept repeated-key array form (?policyIds=a&policyIds=b)
  in addition to comma-separated, and flatten both into a single deduped
  string[].

---------

Co-authored-by: Mariano <marfuen98@gmail.com>
---
 .../src/policies/policies.controller.spec.ts  | 102 +++++++++
 apps/api/src/policies/policies.controller.ts  |  25 ++-
 apps/api/src/policies/policies.service.ts     |   8 +-
 apps/app/package.json                         |   1 +
 .../components/PolicyDownloadSheet.test.tsx   | 206 ++++++++++++++++++
 .../all/components/PolicyDownloadSheet.tsx    | 179 +++++++++++++++
 .../all/components/PolicyPageActions.test.tsx |  16 ++
 .../all/components/PolicyPageActions.tsx      |  42 +---
 bun.lock                                      |   3 +
 9 files changed, 548 insertions(+), 34 deletions(-)
 create mode 100644 apps/app/src/app/(app)/[orgId]/policies/all/components/PolicyDownloadSheet.test.tsx
 create mode 100644 apps/app/src/app/(app)/[orgId]/policies/all/components/PolicyDownloadSheet.tsx

diff --git a/apps/api/src/policies/policies.controller.spec.ts b/apps/api/src/policies/policies.controller.spec.ts
index 767fbcba3d..17fb8d2258 100644
--- a/apps/api/src/policies/policies.controller.spec.ts
+++ b/apps/api/src/policies/policies.controller.spec.ts
@@ -53,6 +53,10 @@ jest.mock('@db', () => ({
     draft: 'draft',
     published: 'published',
   },
+  FindingType: {
+    soc2: 'soc2',
+    iso27001: 'iso27001',
+  },
 }));
 
 jest.mock('@trigger.dev/sdk', () => ({
@@ -188,10 +192,12 @@ describe('PoliciesController', () => {
       const result = await controller.downloadAllPolicies(
         orgId,
         mockAuthContext,
+        undefined,
       );
 
       expect(policiesService.downloadAllPoliciesPdf).toHaveBeenCalledWith(
         orgId,
+        undefined,
       );
       expect(result).toEqual({
         url: 'https://s3.example.com/bundle.pdf',
@@ -199,6 +205,102 @@ describe('PoliciesController', () => {
         authenticatedUser: { id: 'usr_123', email: 'test@example.com' },
       });
     });
+
+    it('parses comma-separated policyIds and passes an array to the service', async () => {
+      const mockResult = { downloadUrl: 'https://s3/signed', name: 'all-policies', policyCount: 2 };
+      mockPoliciesService.downloadAllPoliciesPdf.mockResolvedValue(mockResult);
+
+      await controller.downloadAllPolicies(
+        orgId,
+        mockAuthContext,
+        'p1, p2 ,p3',
+      );
+
+      expect(policiesService.downloadAllPoliciesPdf).toHaveBeenCalledWith(
+        orgId,
+        ['p1', 'p2', 'p3'],
+      );
+    });
+
+    it('dedupes policyIds and strips empty entries', async () => {
+      const mockResult = { downloadUrl: 'https://s3/signed', name: 'all-policies', policyCount: 1 };
+      mockPoliciesService.downloadAllPoliciesPdf.mockResolvedValue(mockResult);
+
+      await controller.downloadAllPolicies(
+        orgId,
+        mockAuthContext,
+        'p1,,p1,p2,',
+      );
+
+      expect(policiesService.downloadAllPoliciesPdf).toHaveBeenCalledWith(
+        orgId,
+        ['p1', 'p2'],
+      );
+    });
+
+    it('passes undefined when policyIds query is missing', async () => {
+      const mockResult = { downloadUrl: 'https://s3/signed', name: 'all-policies', policyCount: 10 };
+      mockPoliciesService.downloadAllPoliciesPdf.mockResolvedValue(mockResult);
+
+      await controller.downloadAllPolicies(
+        orgId,
+        mockAuthContext,
+        undefined,
+      );
+
+      expect(policiesService.downloadAllPoliciesPdf).toHaveBeenCalledWith(
+        orgId,
+        undefined,
+      );
+    });
+
+    it('passes undefined when policyIds query is an empty string', async () => {
+      const mockResult = { downloadUrl: 'https://s3/signed', name: 'all-policies', policyCount: 10 };
+      mockPoliciesService.downloadAllPoliciesPdf.mockResolvedValue(mockResult);
+
+      await controller.downloadAllPolicies(
+        orgId,
+        mockAuthContext,
+        '',
+      );
+
+      expect(policiesService.downloadAllPoliciesPdf).toHaveBeenCalledWith(
+        orgId,
+        undefined,
+      );
+    });
+
+    it('handles repeated-key array form (policyIds=a&policyIds=b)', async () => {
+      const mockResult = { downloadUrl: 'https://s3/signed', name: 'all-policies', policyCount: 2 };
+      mockPoliciesService.downloadAllPoliciesPdf.mockResolvedValue(mockResult);
+
+      await controller.downloadAllPolicies(
+        orgId,
+        mockAuthContext,
+        ['p1', 'p2'],
+      );
+
+      expect(policiesService.downloadAllPoliciesPdf).toHaveBeenCalledWith(
+        orgId,
+        ['p1', 'p2'],
+      );
+    });
+
+    it('handles mixed array form where each value itself contains commas', async () => {
+      const mockResult = { downloadUrl: 'https://s3/signed', name: 'all-policies', policyCount: 3 };
+      mockPoliciesService.downloadAllPoliciesPdf.mockResolvedValue(mockResult);
+
+      await controller.downloadAllPolicies(
+        orgId,
+        mockAuthContext,
+        ['p1,p2', 'p3'],
+      );
+
+      expect(policiesService.downloadAllPoliciesPdf).toHaveBeenCalledWith(
+        orgId,
+        ['p1', 'p2', 'p3'],
+      );
+    });
   });
 
   describe('getPolicy', () => {
diff --git a/apps/api/src/policies/policies.controller.ts b/apps/api/src/policies/policies.controller.ts
index 3f65834bf7..52af8da998 100644
--- a/apps/api/src/policies/policies.controller.ts
+++ b/apps/api/src/policies/policies.controller.ts
@@ -72,6 +72,22 @@ import {
 } from './schemas/version-responses';
 import { PolicyResponseDto } from './dto/policy-responses.dto';
 
+function parsePolicyIdsParam(
+  raw: string | string[] | undefined,
+): string[] | undefined {
+  if (!raw) return undefined;
+  const values = Array.isArray(raw) ? raw : [raw];
+  const ids = Array.from(
+    new Set(
+      values
+        .flatMap((value) => value.split(','))
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0),
+    ),
+  );
+  return ids.length > 0 ? ids : undefined;
+}
+
 @ApiTags('Policies')
 @ApiExtraModels(PolicyResponseDto)
 @Controller({ path: 'policies', version: '1' })
@@ -154,9 +170,14 @@ export class PoliciesController {
   async downloadAllPolicies(
     @OrganizationId() organizationId: string,
     @AuthContext() authContext: AuthContextType,
+    @Query('policyIds') policyIdsParam?: string | string[],
   ) {
-    const result =
-      await this.policiesService.downloadAllPoliciesPdf(organizationId);
+    const policyIds = parsePolicyIdsParam(policyIdsParam);
+
+    const result = await this.policiesService.downloadAllPoliciesPdf(
+      organizationId,
+      policyIds,
+    );
 
     return {
       ...result,
diff --git a/apps/api/src/policies/policies.service.ts b/apps/api/src/policies/policies.service.ts
index 225342add5..08c0228830 100644
--- a/apps/api/src/policies/policies.service.ts
+++ b/apps/api/src/policies/policies.service.ts
@@ -1268,7 +1268,10 @@ export class PoliciesService {
   /**
    * Download all published policies as a single PDF bundle (no watermark)
    */
-  async downloadAllPoliciesPdf(organizationId: string) {
+  async downloadAllPoliciesPdf(
+    organizationId: string,
+    policyIds?: string[],
+  ) {
     // Get organization info
     const organization = await db.organization.findUnique({
       where: { id: organizationId },
@@ -1285,6 +1288,9 @@ export class PoliciesService {
         organizationId,
         isArchived: false,
         archivedAt: null,
+        ...(policyIds && policyIds.length > 0
+          ? { id: { in: policyIds } }
+          : {}),
       },
       select: {
         id: true,
diff --git a/apps/app/package.json b/apps/app/package.json
index cfe571db22..671b522e2a 100644
--- a/apps/app/package.json
+++ b/apps/app/package.json
@@ -150,6 +150,7 @@
         "@testing-library/dom": "^10.4.0",
         "@testing-library/jest-dom": "^6.6.3",
         "@testing-library/react": "^16.3.0",
+        "@testing-library/user-event": "^14.6.1",
         "@trigger.dev/build": "4.4.3",
         "@types/d3": "^7.4.3",
         "@types/jspdf": "^2.0.0",
diff --git a/apps/app/src/app/(app)/[orgId]/policies/all/components/PolicyDownloadSheet.test.tsx b/apps/app/src/app/(app)/[orgId]/policies/all/components/PolicyDownloadSheet.test.tsx
new file mode 100644
index 0000000000..71fe48411e
--- /dev/null
+++ b/apps/app/src/app/(app)/[orgId]/policies/all/components/PolicyDownloadSheet.test.tsx
@@ -0,0 +1,206 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import type { Policy } from '@db';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('@/lib/api-client', () => ({
+  api: { get: vi.fn() },
+}));
+
+vi.mock('sonner', () => ({
+  toast: { error: vi.fn(), success: vi.fn() },
+}));
+
+import { api } from '@/lib/api-client';
+import { toast } from 'sonner';
+import { PolicyDownloadSheet } from './PolicyDownloadSheet';
+
+const policies: Array<Pick<Policy, 'id' | 'name' | 'status'>> = [
+  { id: 'p1', name: 'Security Policy', status: 'published' },
+  { id: 'p2', name: 'Privacy Policy', status: 'needs_review' },
+  { id: 'p3', name: 'Draft Policy', status: 'draft' },
+];
+
+const renderSheet = (
+  overrides: Partial<React.ComponentProps<typeof PolicyDownloadSheet>> = {},
+) =>
+  render(
+    <PolicyDownloadSheet
+      open={true}
+      onOpenChange={vi.fn()}
+      policies={policies}
+      {...overrides}
+    />,
+  );
+
+describe('PolicyDownloadSheet', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('renders one checkbox per policy and all are checked by default', () => {
+    renderSheet();
+
+    expect(screen.getByLabelText(/security policy/i)).toBeChecked();
+    expect(screen.getByLabelText(/privacy policy/i)).toBeChecked();
+    expect(screen.getByLabelText(/draft policy/i)).toBeChecked();
+  });
+
+  it('shows a status badge for each policy', () => {
+    renderSheet();
+    expect(screen.getByText(/published/i)).toBeInTheDocument();
+    expect(screen.getByText(/needs review/i)).toBeInTheDocument();
+    // "Draft" badge text (distinct from "Draft Policy" name) — use exact match
+    expect(screen.getByText(/^draft$/i)).toBeInTheDocument();
+  });
+
+  it('shows "Download 3 policies" by default and enables the button', () => {
+    renderSheet();
+    const btn = screen.getByRole('button', { name: /download 3 policies/i });
+    expect(btn).toBeEnabled();
+  });
+
+  it('updates the count when a policy is unchecked', async () => {
+    const user = userEvent.setup();
+    renderSheet();
+
+    await user.click(screen.getByLabelText(/draft policy/i));
+
+    expect(
+      screen.getByRole('button', { name: /download 2 policies/i }),
+    ).toBeEnabled();
+  });
+
+  it('disables the download button when zero are selected', async () => {
+    const user = userEvent.setup();
+    renderSheet();
+
+    await user.click(screen.getByLabelText(/select all/i));
+
+    expect(screen.getByRole('button', { name: /download/i })).toBeDisabled();
+  });
+
+  it('select all toggles every policy', async () => {
+    const user = userEvent.setup();
+    renderSheet();
+
+    await user.click(screen.getByLabelText(/select all/i));
+    expect(screen.getByLabelText(/security policy/i)).not.toBeChecked();
+
+    await user.click(screen.getByLabelText(/select all/i));
+    expect(screen.getByLabelText(/security policy/i)).toBeChecked();
+  });
+
+  it('calls the API with selected policyIds and triggers download', async () => {
+    const user = userEvent.setup();
+    vi.mocked(api.get).mockResolvedValue({
+      data: {
+        downloadUrl: 'https://s3/signed.pdf',
+        name: 'all-policies',
+        policyCount: 2,
+      },
+      status: 200,
+    });
+
+    const onOpenChange = vi.fn();
+    renderSheet({ onOpenChange });
+
+    await user.click(screen.getByLabelText(/draft policy/i));
+    await user.click(
+      screen.getByRole('button', { name: /download 2 policies/i }),
+    );
+
+    expect(api.get).toHaveBeenCalledWith(
+      '/v1/policies/download-all?policyIds=p1%2Cp2',
+    );
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+  });
+
+  it('re-selects all current policies when reopened, dropping stale IDs', async () => {
+    const user = userEvent.setup();
+    const onOpenChange = vi.fn();
+
+    const { rerender } = render(
+      <PolicyDownloadSheet
+        open={true}
+        onOpenChange={onOpenChange}
+        policies={policies}
+      />,
+    );
+
+    // Deselect one policy while open
+    await user.click(screen.getByLabelText(/draft policy/i));
+    expect(
+      screen.getByRole('button', { name: /download 2 policies/i }),
+    ).toBeEnabled();
+
+    // Close and reopen — selection should reset to all
+    rerender(
+      <PolicyDownloadSheet
+        open={false}
+        onOpenChange={onOpenChange}
+        policies={policies}
+      />,
+    );
+    rerender(
+      <PolicyDownloadSheet
+        open={true}
+        onOpenChange={onOpenChange}
+        policies={policies}
+      />,
+    );
+
+    expect(screen.getByLabelText(/draft policy/i)).toBeChecked();
+    expect(
+      screen.getByRole('button', { name: /download 3 policies/i }),
+    ).toBeEnabled();
+  });
+
+  it('updates selection when the policies prop changes while open', () => {
+    const { rerender } = render(
+      <PolicyDownloadSheet
+        open={true}
+        onOpenChange={vi.fn()}
+        policies={policies}
+      />,
+    );
+
+    const newPolicies: typeof policies = [
+      { id: 'p1', name: 'Security Policy', status: 'published' },
+      { id: 'p4', name: 'New Policy', status: 'draft' },
+    ];
+
+    rerender(
+      <PolicyDownloadSheet
+        open={true}
+        onOpenChange={vi.fn()}
+        policies={newPolicies}
+      />,
+    );
+
+    // New policy is checked by default; stale IDs are dropped
+    expect(screen.getByLabelText(/new policy/i)).toBeChecked();
+    expect(screen.queryByLabelText(/privacy policy/i)).not.toBeInTheDocument();
+    expect(
+      screen.getByRole('button', { name: /download 2 policies/i }),
+    ).toBeEnabled();
+  });
+
+  it('shows a toast and keeps the sheet open on API error', async () => {
+    const user = userEvent.setup();
+    vi.mocked(api.get).mockResolvedValue({
+      error: 'boom',
+      status: 500,
+    });
+
+    const onOpenChange = vi.fn();
+    renderSheet({ onOpenChange });
+
+    await user.click(
+      screen.getByRole('button', { name: /download 3 policies/i }),
+    );
+
+    expect(toast.error).toHaveBeenCalled();
+    expect(onOpenChange).not.toHaveBeenCalledWith(false);
+  });
+});
diff --git a/apps/app/src/app/(app)/[orgId]/policies/all/components/PolicyDownloadSheet.tsx b/apps/app/src/app/(app)/[orgId]/policies/all/components/PolicyDownloadSheet.tsx
new file mode 100644
index 0000000000..92f9e50215
--- /dev/null
+++ b/apps/app/src/app/(app)/[orgId]/policies/all/components/PolicyDownloadSheet.tsx
@@ -0,0 +1,179 @@
+'use client';
+
+import { api } from '@/lib/api-client';
+import type { Policy, PolicyStatus } from '@db';
+import {
+  Badge,
+  Button,
+  Checkbox,
+  ScrollArea,
+  Sheet,
+  SheetBody,
+  SheetContent,
+  SheetFooter,
+  SheetHeader,
+  SheetTitle,
+  Stack,
+  Text,
+} from '@trycompai/design-system';
+import { useEffect, useMemo, useState } from 'react';
+import { toast } from 'sonner';
+
+interface PolicyDownloadSheetProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  policies: Pick<Policy, 'id' | 'name' | 'status'>[];
+}
+
+type BadgeVariant = 'default' | 'secondary' | 'outline';
+
+const STATUS_LABEL: Record<PolicyStatus, string> = {
+  published: 'Published',
+  needs_review: 'Needs review',
+  draft: 'Draft',
+};
+
+const STATUS_VARIANT: Record<PolicyStatus, BadgeVariant> = {
+  published: 'default',
+  needs_review: 'secondary',
+  draft: 'outline',
+};
+
+export function PolicyDownloadSheet({
+  open,
+  onOpenChange,
+  policies,
+}: PolicyDownloadSheetProps) {
+  const allIds = useMemo(() => policies.map((p) => p.id), [policies]);
+  const [selected, setSelected] = useState<Set<string>>(() => new Set(allIds));
+  const [isDownloading, setIsDownloading] = useState(false);
+
+  // Reset selection to all current policies whenever the sheet opens or the
+  // underlying policy list changes, so reopens and prop refreshes don't leave
+  // stale or deleted IDs in the selection.
+  useEffect(() => {
+    if (!open) return;
+    setSelected(new Set(allIds));
+  }, [open, allIds]);
+
+  const handleToggle = (id: string) => {
+    setSelected((prev) => {
+      const next = new Set(prev);
+      if (next.has(id)) next.delete(id);
+      else next.add(id);
+      return next;
+    });
+  };
+
+  const allChecked = selected.size === allIds.length && allIds.length > 0;
+  const someChecked = selected.size > 0 && !allChecked;
+
+  const handleToggleAll = () => {
+    setSelected((prev) =>
+      prev.size === allIds.length ? new Set() : new Set(allIds),
+    );
+  };
+
+  const handleDownload = async () => {
+    if (selected.size === 0) return;
+    setIsDownloading(true);
+    try {
+      const ids = Array.from(selected).join(',');
+      const url = `/v1/policies/download-all?policyIds=${encodeURIComponent(ids)}`;
+      const res = await api.get<{
+        downloadUrl: string;
+        name: string;
+        policyCount: number;
+      }>(url);
+
+      if (res.error || !res.data?.downloadUrl) {
+        toast.error('Failed to generate PDF. Please try again.');
+        return;
+      }
+
+      const link = document.createElement('a');
+      link.href = res.data.downloadUrl;
+      link.download = `${res.data.name ?? 'policies'}.pdf`;
+      document.body.appendChild(link);
+      link.click();
+      document.body.removeChild(link);
+      onOpenChange(false);
+    } catch {
+      toast.error('Failed to download policies.');
+    } finally {
+      setIsDownloading(false);
+    }
+  };
+
+  const count = selected.size;
+  const buttonLabel =
+    count === 0
+      ? 'Download'
+      : `Download ${count} ${count === 1 ? 'policy' : 'policies'}`;
+
+  return (
+    <Sheet open={open} onOpenChange={onOpenChange}>
+      <SheetContent>
+        <SheetHeader>
+          <SheetTitle>Download policies</SheetTitle>
+        </SheetHeader>
+        <SheetBody>
+          <Stack gap="md">
+            <div className="flex items-center gap-2">
+              <Checkbox
+                checked={allChecked}
+                indeterminate={someChecked}
+                onCheckedChange={handleToggleAll}
+                aria-label="Select all"
+              />
+              <Text>
+                Select all ({selected.size} of {allIds.length} selected)
+              </Text>
+            </div>
+            <ScrollArea>
+              <Stack gap="xs">
+                {policies.map((policy) => {
+                  const statusKey = policy.status ?? 'draft';
+                  return (
+                    <div
+                      key={policy.id}
+                      className="flex items-center gap-2 py-1"
+                    >
+                      <Checkbox
+                        checked={selected.has(policy.id)}
+                        onCheckedChange={() => handleToggle(policy.id)}
+                        aria-label={policy.name ?? 'Policy'}
+                      />
+                      <div className="flex flex-1 items-center gap-2">
+                        <Text>{policy.name}</Text>
+                        <Badge variant={STATUS_VARIANT[statusKey] ?? 'outline'}>
+                          {STATUS_LABEL[statusKey] ?? statusKey}
+                        </Badge>
+                      </div>
+                    </div>
+                  );
+                })}
+              </Stack>
+            </ScrollArea>
+          </Stack>
+        </SheetBody>
+        <SheetFooter>
+          <Button
+            variant="outline"
+            onClick={() => onOpenChange(false)}
+            disabled={isDownloading}
+          >
+            Cancel
+          </Button>
+          <Button
+            onClick={handleDownload}
+            loading={isDownloading}
+            disabled={count === 0}
+          >
+            {buttonLabel}
+          </Button>
+        </SheetFooter>
+      </SheetContent>
+    </Sheet>
+  );
+}
diff --git a/apps/app/src/app/(app)/[orgId]/policies/all/components/PolicyPageActions.test.tsx b/apps/app/src/app/(app)/[orgId]/policies/all/components/PolicyPageActions.test.tsx
index 3846332b4a..2e7c36656b 100644
--- a/apps/app/src/app/(app)/[orgId]/policies/all/components/PolicyPageActions.test.tsx
+++ b/apps/app/src/app/(app)/[orgId]/policies/all/components/PolicyPageActions.test.tsx
@@ -1,4 +1,5 @@
 import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import {
   setMockPermissions,
@@ -20,6 +21,12 @@ vi.mock('@/components/sheets/create-policy-sheet', () => ({
   CreatePolicySheet: () => <div data-testid="create-policy-sheet" />,
 }));
 
+// Mock PolicyDownloadSheet — only renders when open
+vi.mock('./PolicyDownloadSheet', () => ({
+  PolicyDownloadSheet: ({ open }: { open: boolean }) =>
+    open ? <div data-testid="policy-download-sheet" /> : null,
+}));
+
 // Mock api client
 vi.mock('@/lib/api-client', () => ({
   api: { get: vi.fn() },
@@ -72,6 +79,15 @@ describe('PolicyPageActions', () => {
         screen.getByRole('button', { name: /download all/i }),
       ).toBeInTheDocument();
     });
+
+    it('opens the download sheet when Download All is clicked', async () => {
+      const user = userEvent.setup();
+      render(<PolicyPageActions policies={basePolicies} />);
+
+      await user.click(screen.getByRole('button', { name: /download all/i }));
+
+      expect(screen.getByTestId('policy-download-sheet')).toBeInTheDocument();
+    });
   });
 
   describe('auditor permissions (no policy:create)', () => {
diff --git a/apps/app/src/app/(app)/[orgId]/policies/all/components/PolicyPageActions.tsx b/apps/app/src/app/(app)/[orgId]/policies/all/components/PolicyPageActions.tsx
index d3b64c3299..2d75c61993 100644
--- a/apps/app/src/app/(app)/[orgId]/policies/all/components/PolicyPageActions.tsx
+++ b/apps/app/src/app/(app)/[orgId]/policies/all/components/PolicyPageActions.tsx
@@ -1,14 +1,13 @@
 'use client';
 
 import { CreatePolicySheet } from '@/components/sheets/create-policy-sheet';
-import { api } from '@/lib/api-client';
-import { Add, Download } from '@carbon/icons-react';
+import { usePermissions } from '@/hooks/use-permissions';
+import { Add, Download } from '@trycompai/design-system/icons';
 import type { Policy } from '@db';
 import { Button, HStack } from '@trycompai/design-system';
 import { usePathname, useRouter, useSearchParams } from 'next/navigation';
 import { useState } from 'react';
-import { toast } from 'sonner';
-import { usePermissions } from '@/hooks/use-permissions';
+import { PolicyDownloadSheet } from './PolicyDownloadSheet';
 
 interface PolicyPageActionsProps {
   policies: Policy[];
@@ -18,33 +17,10 @@ export function PolicyPageActions({ policies }: PolicyPageActionsProps) {
   const router = useRouter();
   const pathname = usePathname();
   const searchParams = useSearchParams();
-  const [isDownloadingAll, setIsDownloadingAll] = useState(false);
+  const [isDownloadSheetOpen, setIsDownloadSheetOpen] = useState(false);
   const { hasPermission } = usePermissions();
 
-  const handleDownloadAll = async () => {
-    setIsDownloadingAll(true);
-    try {
-      const res = await api.get<{ downloadUrl: string; name: string; policyCount: number }>(
-        '/v1/policies/download-all',
-      );
-
-      if (res.error || !res.data?.downloadUrl) {
-        toast.error('Failed to generate PDF. Please try again.');
-        return;
-      }
-
-      const link = document.createElement('a');
-      link.href = res.data.downloadUrl;
-      link.download = `${res.data.name ?? 'all-policies'}.pdf`;
-      document.body.appendChild(link);
-      link.click();
-      document.body.removeChild(link);
-    } catch {
-      toast.error('Failed to download policies.');
-    } finally {
-      setIsDownloadingAll(false);
-    }
-  };
+  const handleOpenDownloadSheet = () => setIsDownloadSheetOpen(true);
 
   const handleCreatePolicy = () => {
     const params = new URLSearchParams(searchParams.toString());
@@ -59,8 +35,7 @@ export function PolicyPageActions({ policies }: PolicyPageActionsProps) {
           <Button
             variant="outline"
             iconLeft={<Download />}
-            loading={isDownloadingAll}
-            onClick={handleDownloadAll}
+            onClick={handleOpenDownloadSheet}
           >
             Download All
           </Button>
@@ -72,6 +47,11 @@ export function PolicyPageActions({ policies }: PolicyPageActionsProps) {
         )}
       </HStack>
       <CreatePolicySheet />
+      <PolicyDownloadSheet
+        open={isDownloadSheetOpen}
+        onOpenChange={setIsDownloadSheetOpen}
+        policies={policies}
+      />
     </>
   );
 }
diff --git a/bun.lock b/bun.lock
index 0a775b615e..ad5b423ad8 100644
--- a/bun.lock
+++ b/bun.lock
@@ -364,6 +364,7 @@
         "@testing-library/dom": "^10.4.0",
         "@testing-library/jest-dom": "^6.6.3",
         "@testing-library/react": "^16.3.0",
+        "@testing-library/user-event": "^14.6.1",
         "@trigger.dev/build": "4.4.3",
         "@types/d3": "^7.4.3",
         "@types/jspdf": "^2.0.0",
@@ -2483,6 +2484,8 @@
 
     "@testing-library/react": ["@testing-library/react@16.3.1", "", { "dependencies": { "@babel/runtime": "^7.12.5" }, "peerDependencies": { "@testing-library/dom": "^10.0.0", "@types/react": "^18.0.0 || ^19.0.0", "@types/react-dom": "^18.0.0 || ^19.0.0", "react": "^18.0.0 || ^19.0.0", "react-dom": "^18.0.0 || ^19.0.0" }, "optionalPeers": ["@types/react", "@types/react-dom"] }, "sha512-gr4KtAWqIOQoucWYD/f6ki+j5chXfcPc74Col/6poTyqTmn7zRmodWahWRCp8tYd+GMqBonw6hstNzqjbs6gjw=="],
 
+    "@testing-library/user-event": ["@testing-library/user-event@14.6.1", "", { "peerDependencies": { "@testing-library/dom": ">=7.21.4" } }, "sha512-vq7fv0rnt+QTXgPxr5Hjc210p6YKq2kmdziLgnsZGgLJ9e6VAShx1pACLuRjd/AS/sr7phAR58OIIpf0LlmQNw=="],
+
     "@thallesp/nestjs-better-auth": ["@thallesp/nestjs-better-auth@2.4.0", "", { "peerDependencies": { "@nestjs/common": "^11.1.6", "@nestjs/core": "^11.1.6", "@nestjs/graphql": "^13.1.0", "@nestjs/websockets": "^11.1.6", "better-auth": ">=1.3.8 <2.0.0", "express": "^5.1.0", "graphql": "^16.11.0", "typescript": "^5.9.2" }, "optionalPeers": ["@nestjs/graphql", "@nestjs/websockets", "graphql"] }, "sha512-JSmtXEoYFDTMWyLr6mlXiqlDwurGnlnN52Hwe80AHYuiy7dfNJMIz9X5PfvFjSXs5tcklXoyrgTcm6OYDfQIpw=="],
 
     "@tiptap/core": ["@tiptap/core@3.22.3", "", { "peerDependencies": { "@tiptap/pm": "^3.22.3" } }, "sha512-Dv9MKK5BDWCF0N2l6/Pxv3JNCce2kwuWf2cKMBc2bEetx0Pn6o7zlFmSxMvYK4UtG1Tw9Yg/ZHi6QOFWK0Zm9Q=="],

From 1296eeb109f00aecbbf816a2cf636871801d784e Mon Sep 17 00:00:00 2001
From: chasprowebdev <chasgarciaprowebdev@gmail.com>
Date: Fri, 24 Apr 2026 13:45:39 -0400
Subject: [PATCH 20/40] fix(db): add declined fields to SOADocument

---
 .../migration.sql                                           | 6 ++++++
 packages/db/prisma/schema/soa.prisma                        | 4 +++-
 2 files changed, 9 insertions(+), 1 deletion(-)
 create mode 100644 packages/db/prisma/migrations/20260424134500_add_soa_declined_status_and_timestamp/migration.sql

diff --git a/packages/db/prisma/migrations/20260424134500_add_soa_declined_status_and_timestamp/migration.sql b/packages/db/prisma/migrations/20260424134500_add_soa_declined_status_and_timestamp/migration.sql
new file mode 100644
index 0000000000..72b7b8d639
--- /dev/null
+++ b/packages/db/prisma/migrations/20260424134500_add_soa_declined_status_and_timestamp/migration.sql
@@ -0,0 +1,6 @@
+-- AlterEnum: Add declined status for SOA document workflow
+ALTER TYPE "SOADocumentStatus" ADD VALUE 'declined';
+
+-- AlterTable: Track when SOA document was declined
+ALTER TABLE "SOADocument"
+ADD COLUMN "declinedAt" TIMESTAMP(3);
diff --git a/packages/db/prisma/schema/soa.prisma b/packages/db/prisma/schema/soa.prisma
index d3f28d386f..34ab556847 100644
--- a/packages/db/prisma/schema/soa.prisma
+++ b/packages/db/prisma/schema/soa.prisma
@@ -53,7 +53,7 @@ model SOADocument {
   isLatest Boolean @default(true) // Whether this is the latest version
 
   // Document status
-  status SOADocumentStatus @default(draft) // draft, in_progress, completed
+  status SOADocumentStatus @default(draft) // draft, in_progress, needs_review, declined, completed
 
   // Document metadata
   totalQuestions    Int @default(0) // Total number of questions in this document
@@ -64,6 +64,7 @@ model SOADocument {
   approverId String? // Member ID who will approve this document (set when submitted for approval)
   approver   Member? @relation("SOADocumentApprover", fields: [approverId], references: [id], onDelete: SetNull, onUpdate: Cascade)
   approvedAt DateTime? // When document was approved
+  declinedAt DateTime? // When document was declined
 
   // Dates
   completedAt DateTime? // When document was completed
@@ -124,6 +125,7 @@ enum SOADocumentStatus {
   draft // Document is being created/edited
   in_progress // Document is being generated
   needs_review // Document is submitted for approval
+  declined // Document was declined by approver
   completed // Document is complete and approved
 }
 

From 83a5619777e61efffef88d28115bf25cd2dbe670 Mon Sep 17 00:00:00 2001
From: chasprowebdev <chasgarciaprowebdev@gmail.com>
Date: Fri, 24 Apr 2026 14:23:12 -0400
Subject: [PATCH 21/40] fix(db): remove declined from SOADocumentStatus

---
 .../migration.sql                                              | 3 ---
 packages/db/prisma/schema/soa.prisma                           | 3 +--
 2 files changed, 1 insertion(+), 5 deletions(-)

diff --git a/packages/db/prisma/migrations/20260424134500_add_soa_declined_status_and_timestamp/migration.sql b/packages/db/prisma/migrations/20260424134500_add_soa_declined_status_and_timestamp/migration.sql
index 72b7b8d639..d449df524c 100644
--- a/packages/db/prisma/migrations/20260424134500_add_soa_declined_status_and_timestamp/migration.sql
+++ b/packages/db/prisma/migrations/20260424134500_add_soa_declined_status_and_timestamp/migration.sql
@@ -1,6 +1,3 @@
--- AlterEnum: Add declined status for SOA document workflow
-ALTER TYPE "SOADocumentStatus" ADD VALUE 'declined';
-
 -- AlterTable: Track when SOA document was declined
 ALTER TABLE "SOADocument"
 ADD COLUMN "declinedAt" TIMESTAMP(3);
diff --git a/packages/db/prisma/schema/soa.prisma b/packages/db/prisma/schema/soa.prisma
index 34ab556847..562418a743 100644
--- a/packages/db/prisma/schema/soa.prisma
+++ b/packages/db/prisma/schema/soa.prisma
@@ -53,7 +53,7 @@ model SOADocument {
   isLatest Boolean @default(true) // Whether this is the latest version
 
   // Document status
-  status SOADocumentStatus @default(draft) // draft, in_progress, needs_review, declined, completed
+  status SOADocumentStatus @default(draft) // draft, in_progress, needs_review, completed
 
   // Document metadata
   totalQuestions    Int @default(0) // Total number of questions in this document
@@ -125,7 +125,6 @@ enum SOADocumentStatus {
   draft // Document is being created/edited
   in_progress // Document is being generated
   needs_review // Document is submitted for approval
-  declined // Document was declined by approver
   completed // Document is complete and approved
 }
 

From dafde6f2400d6a7529ec3ea8bf525532cb48a76f Mon Sep 17 00:00:00 2001
From: chasprowebdev <chasgarciaprowebdev@gmail.com>
Date: Fri, 24 Apr 2026 14:37:03 -0400
Subject: [PATCH 22/40] fix(api): update declineAt during SOA Document status
 changes

---
 apps/api/src/soa/soa.service.spec.ts  | 108 ++++++++++++++++++++++++++
 apps/api/src/soa/soa.service.ts       |   4 +
 apps/api/src/soa/utils/soa-storage.ts |   2 +
 3 files changed, 114 insertions(+)

diff --git a/apps/api/src/soa/soa.service.spec.ts b/apps/api/src/soa/soa.service.spec.ts
index c9e5e7afbe..91b35aabb8 100644
--- a/apps/api/src/soa/soa.service.spec.ts
+++ b/apps/api/src/soa/soa.service.spec.ts
@@ -212,6 +212,105 @@ describe('SOAService', () => {
       });
       const result = await service.approveDocument(dto, userId);
       expect(result.success).toBe(true);
+      expect(mockDb.sOADocument.update).toHaveBeenCalledWith({
+        where: { id: dto.documentId },
+        data: expect.objectContaining({
+          status: 'completed',
+          declinedAt: null,
+        }),
+      });
+    });
+  });
+
+  describe('declineDocument', () => {
+    const dto = {
+      documentId: 'doc-1',
+      organizationId: 'org-1',
+      reason: 'Needs changes',
+    };
+    const userId = 'user-1';
+    const ownerMember = { id: 'mem-1', role: 'owner' };
+
+    it('throws NotFoundException when member not found', async () => {
+      (mockDb.member.findFirst as jest.Mock).mockResolvedValue(null);
+
+      await expect(service.declineDocument(dto, userId)).rejects.toThrow(
+        NotFoundException,
+      );
+    });
+
+    it('throws ForbiddenException when user is not owner/admin', async () => {
+      (mockDb.member.findFirst as jest.Mock).mockResolvedValue({
+        id: 'mem-1',
+        role: 'employee',
+      });
+
+      await expect(service.declineDocument(dto, userId)).rejects.toThrow(
+        ForbiddenException,
+      );
+    });
+
+    it('throws NotFoundException when document not found', async () => {
+      (mockDb.member.findFirst as jest.Mock).mockResolvedValue(ownerMember);
+      (mockDb.sOADocument.findFirst as jest.Mock).mockResolvedValue(null);
+
+      await expect(service.declineDocument(dto, userId)).rejects.toThrow(
+        NotFoundException,
+      );
+    });
+
+    it('throws ForbiddenException when not pending approval for this user', async () => {
+      (mockDb.member.findFirst as jest.Mock).mockResolvedValue(ownerMember);
+      (mockDb.sOADocument.findFirst as jest.Mock).mockResolvedValue({
+        id: 'doc-1',
+        approverId: 'other-member',
+        status: 'needs_review',
+      });
+
+      await expect(service.declineDocument(dto, userId)).rejects.toThrow(
+        ForbiddenException,
+      );
+    });
+
+    it('throws BadRequestException when not in needs_review status', async () => {
+      (mockDb.member.findFirst as jest.Mock).mockResolvedValue(ownerMember);
+      (mockDb.sOADocument.findFirst as jest.Mock).mockResolvedValue({
+        id: 'doc-1',
+        approverId: 'mem-1',
+        status: 'draft',
+      });
+
+      await expect(service.declineDocument(dto, userId)).rejects.toThrow(
+        BadRequestException,
+      );
+    });
+
+    it('declines document and sets declinedAt', async () => {
+      (mockDb.member.findFirst as jest.Mock).mockResolvedValue(ownerMember);
+      (mockDb.sOADocument.findFirst as jest.Mock).mockResolvedValue({
+        id: 'doc-1',
+        approverId: 'mem-1',
+        status: 'needs_review',
+      });
+      (mockDb.sOADocument.update as jest.Mock).mockResolvedValue({
+        id: 'doc-1',
+        status: 'completed',
+      });
+
+      const result = await service.declineDocument(dto, userId);
+
+      expect(result.success).toBe(true);
+      expect(mockDb.sOADocument.update).toHaveBeenCalledWith({
+        where: { id: dto.documentId },
+        data: expect.objectContaining({
+          approverId: null,
+          approvedAt: null,
+          status: 'completed',
+        }),
+      });
+      expect((mockDb.sOADocument.update as jest.Mock).mock.calls[0][0].data.declinedAt).toBeInstanceOf(
+        Date,
+      );
     });
   });
 
@@ -301,6 +400,15 @@ describe('SOAService', () => {
       });
       const result = await service.submitForApproval(dto);
       expect(result.success).toBe(true);
+      expect(mockDb.sOADocument.update).toHaveBeenCalledWith({
+        where: { id: dto.documentId },
+        data: expect.objectContaining({
+          approverId: dto.approverId,
+          status: 'needs_review',
+          approvedAt: null,
+          declinedAt: null,
+        }),
+      });
     });
   });
 
diff --git a/apps/api/src/soa/soa.service.ts b/apps/api/src/soa/soa.service.ts
index 8749449a92..ef43aea18b 100644
--- a/apps/api/src/soa/soa.service.ts
+++ b/apps/api/src/soa/soa.service.ts
@@ -346,6 +346,7 @@ export class SOAService {
       data: {
         status: 'completed',
         approvedAt: new Date(),
+        declinedAt: null,
       },
     });
 
@@ -380,6 +381,7 @@ export class SOAService {
         approverId: null,
         approvedAt: null,
         status: 'completed',
+        declinedAt: new Date(),
       },
     });
 
@@ -436,6 +438,8 @@ export class SOAService {
       where: { id: dto.documentId },
       data: {
         approverId: dto.approverId,
+        approvedAt: null,
+        declinedAt: null,
         status: 'needs_review',
       },
     });
diff --git a/apps/api/src/soa/utils/soa-storage.ts b/apps/api/src/soa/utils/soa-storage.ts
index f36fa621d9..e1e64309c7 100644
--- a/apps/api/src/soa/utils/soa-storage.ts
+++ b/apps/api/src/soa/utils/soa-storage.ts
@@ -131,6 +131,7 @@ export async function updateDocumentAfterAutoFill(
       completedAt: answeredCount === totalQuestions ? new Date() : null,
       approverId: null,
       approvedAt: null,
+      declinedAt: null,
     },
   });
 }
@@ -174,6 +175,7 @@ export async function updateDocumentAnsweredCount(
       // Clear approval when answers are edited
       approverId: null,
       approvedAt: null,
+      declinedAt: null,
     },
   });
 }

From 59567c4ce6a1abd7f4765730a834270cfe0fa070 Mon Sep 17 00:00:00 2001
From: chasprowebdev <chasgarciaprowebdev@gmail.com>
Date: Fri, 24 Apr 2026 14:52:40 -0400
Subject: [PATCH 23/40] fix(app): update approval status text on soa

---
 .../statement-of-applicability/components/SOADocumentInfo.tsx   | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOADocumentInfo.tsx b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOADocumentInfo.tsx
index 0dbe4dd839..1f83cddc5f 100644
--- a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOADocumentInfo.tsx
+++ b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOADocumentInfo.tsx
@@ -42,7 +42,7 @@ export function SOADocumentInfo({
 
   const approvalStatusText = document.approvedAt
     ? `Approved on ${new Date(document.approvedAt).toLocaleDateString()}`
-    : document.status === 'needs_review' && document.declinedAt
+    : document.declinedAt
       ? `Declined on ${new Date(document.declinedAt).toLocaleDateString()}`
       : approver
         ? 'Pending approval'

From 4813da66b12400c40975362fe27903c506749bcd Mon Sep 17 00:00:00 2001
From: chasprowebdev <chasgarciaprowebdev@gmail.com>
Date: Fri, 24 Apr 2026 14:53:02 -0400
Subject: [PATCH 24/40] fix(api): update approval status text on soa pdf

---
 apps/api/src/soa/utils/export-generator.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/api/src/soa/utils/export-generator.ts b/apps/api/src/soa/utils/export-generator.ts
index 02ae96088e..df2859e5ac 100644
--- a/apps/api/src/soa/utils/export-generator.ts
+++ b/apps/api/src/soa/utils/export-generator.ts
@@ -107,7 +107,7 @@ function generateSOAPDF(
   y += lineHeight;
   const approvalStatusText = metadata.approvedAt
     ? `Approved on ${new Date(metadata.approvedAt).toLocaleDateString()}`
-    : metadata.status === 'declined' && metadata.declinedAt
+    : metadata.declinedAt
       ? `Declined on ${new Date(metadata.declinedAt).toLocaleDateString()}`
       : metadata.approverName
         ? 'Pending approval'

From af47b4e75d104233f588e6fdead8c10763538cdf Mon Sep 17 00:00:00 2001
From: chasprowebdev <chasgarciaprowebdev@gmail.com>
Date: Fri, 24 Apr 2026 15:10:08 -0400
Subject: [PATCH 25/40] fix(app): update SOA Document Info based on status
 changes

---
 .../components/SOAFrameworkTable.tsx          | 69 ++++++++++++++++++-
 .../hooks/useSOAAutoFill.ts                   |  7 +-
 2 files changed, 71 insertions(+), 5 deletions(-)

diff --git a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOAFrameworkTable.tsx b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOAFrameworkTable.tsx
index 02dfae7b31..e2b591498a 100644
--- a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOAFrameworkTable.tsx
+++ b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOAFrameworkTable.tsx
@@ -118,6 +118,12 @@ export function SOAFrameworkTable({
   }, [resolvedDocument?.answers]);
 
   const handleAnswerUpdate = (questionId: string, payload: SOAFieldSavePayload) => {
+    const previousIsApplicable =
+      answersMap.get(questionId)?.savedIsApplicable ??
+      processedResults.get(questionId)?.isApplicable ??
+      questions.find((q) => q.id === questionId)?.columnMapping.isApplicable ??
+      null;
+
     setAnswersMap((prev) => {
       const newMap = new Map(prev);
       const existing = newMap.get(questionId);
@@ -128,6 +134,40 @@ export function SOAFrameworkTable({
       });
       return newMap;
     });
+
+    void mutateSOADocument((current) => {
+      if (!current) return current;
+
+      const totalQuestions = current.totalQuestions as number | undefined;
+      const currentAnsweredQuestions = current.answeredQuestions as number | undefined;
+
+      if (
+        typeof totalQuestions !== 'number' ||
+        typeof currentAnsweredQuestions !== 'number'
+      ) {
+        return current;
+      }
+
+      const nextIsApplicable = payload.isApplicable ?? null;
+      let answeredQuestions = currentAnsweredQuestions;
+
+      if (previousIsApplicable === null && nextIsApplicable !== null) {
+        answeredQuestions += 1;
+      } else if (previousIsApplicable !== null && nextIsApplicable === null) {
+        answeredQuestions -= 1;
+      }
+
+      answeredQuestions = Math.max(0, Math.min(totalQuestions, answeredQuestions));
+
+      return {
+        ...current,
+        answeredQuestions,
+        status: answeredQuestions === totalQuestions ? 'completed' : 'in_progress',
+        approverId: null,
+        approvedAt: null,
+        declinedAt: null,
+      };
+    }, false);
   };
 
   const [isSubmitApprovalDialogOpen, setIsSubmitApprovalDialogOpen] = useState(false);
@@ -151,9 +191,32 @@ export function SOAFrameworkTable({
     questions: questionsForHook,
     documentId: document?.id || '',
     organizationId,
-    onUpdate: () => {
-      // Revalidate SWR cache instead of full page reload
-      void mutateSOADocument();
+    onUpdate: ({ total, answered } = {}) => {
+      // Keep SOA info card in sync immediately after auto-fill completion.
+      void mutateSOADocument((current) => {
+        if (!current) return current;
+        const totalQuestions =
+          typeof total === 'number' ? total : (current.totalQuestions as number | undefined);
+        const answeredQuestions =
+          typeof answered === 'number'
+            ? answered
+            : (current.answeredQuestions as number | undefined);
+
+        if (typeof totalQuestions !== 'number' || typeof answeredQuestions !== 'number') {
+          return current;
+        }
+
+        return {
+          ...current,
+          totalQuestions,
+          answeredQuestions,
+          status:
+            answeredQuestions === totalQuestions ? 'completed' : 'in_progress',
+          approverId: null,
+          approvedAt: null,
+          declinedAt: null,
+        };
+      }, false);
     },
   });
 
diff --git a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/hooks/useSOAAutoFill.ts b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/hooks/useSOAAutoFill.ts
index 4359b844a7..63efa69619 100644
--- a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/hooks/useSOAAutoFill.ts
+++ b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/hooks/useSOAAutoFill.ts
@@ -17,7 +17,7 @@ interface UseSOAAutoFillProps {
   }>;
   documentId: string;
   organizationId: string;
-  onUpdate: () => void;
+  onUpdate: (payload?: { total?: number; answered?: number }) => void;
 }
 
 export function useSOAAutoFill({ questions, documentId, organizationId, onUpdate }: UseSOAAutoFillProps) {
@@ -115,7 +115,10 @@ export function useSOAAutoFill({ questions, documentId, organizationId, onUpdate
                 // All questions completed
                 toast.success(`Auto-filled ${data.answered} questions`);
                 setIsAutoFilling(false);
-                onUpdate();
+                onUpdate({
+                  total: typeof data.total === 'number' ? data.total : undefined,
+                  answered: typeof data.answered === 'number' ? data.answered : undefined,
+                });
               } else if (data.type === 'error') {
                 toast.error(data.error || 'Failed to auto-fill SOA');
                 setIsAutoFilling(false);

From 08971f944f918cec00208749c63fba7beab2b4d4 Mon Sep 17 00:00:00 2001
From: chasprowebdev <chasgarciaprowebdev@gmail.com>
Date: Fri, 24 Apr 2026 15:25:32 -0400
Subject: [PATCH 26/40] fix(app): correct approvalStatusText handling of
 declinedAt

---
 .../statement-of-applicability/components/SOADocumentInfo.tsx   | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOADocumentInfo.tsx b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOADocumentInfo.tsx
index 1f83cddc5f..0dbe4dd839 100644
--- a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOADocumentInfo.tsx
+++ b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOADocumentInfo.tsx
@@ -42,7 +42,7 @@ export function SOADocumentInfo({
 
   const approvalStatusText = document.approvedAt
     ? `Approved on ${new Date(document.approvedAt).toLocaleDateString()}`
-    : document.declinedAt
+    : document.status === 'needs_review' && document.declinedAt
       ? `Declined on ${new Date(document.declinedAt).toLocaleDateString()}`
       : approver
         ? 'Pending approval'

From 8c3780071afa6584ad31dedb3b91d2817c62d15f Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Fri, 24 Apr 2026 15:29:01 -0400
Subject: [PATCH 27/40] chore(policies): add search + status grouping to
 download picker (#2676)

Co-authored-by: Mariano <marfuen98@gmail.com>
---
 .../components/PolicyDownloadSheet.test.tsx   |  80 ++++++++-
 .../all/components/PolicyDownloadSheet.tsx    | 169 +++++++++++++-----
 2 files changed, 201 insertions(+), 48 deletions(-)

diff --git a/apps/app/src/app/(app)/[orgId]/policies/all/components/PolicyDownloadSheet.test.tsx b/apps/app/src/app/(app)/[orgId]/policies/all/components/PolicyDownloadSheet.test.tsx
index 71fe48411e..9d6f34b099 100644
--- a/apps/app/src/app/(app)/[orgId]/policies/all/components/PolicyDownloadSheet.test.tsx
+++ b/apps/app/src/app/(app)/[orgId]/policies/all/components/PolicyDownloadSheet.test.tsx
@@ -46,12 +46,86 @@ describe('PolicyDownloadSheet', () => {
     expect(screen.getByLabelText(/draft policy/i)).toBeChecked();
   });
 
-  it('shows a status badge for each policy', () => {
+  it('shows a status section header for each policy group', () => {
     renderSheet();
+    // Status labels now appear as section headers with counts, e.g. "Published (1)"
     expect(screen.getByText(/published/i)).toBeInTheDocument();
     expect(screen.getByText(/needs review/i)).toBeInTheDocument();
-    // "Draft" badge text (distinct from "Draft Policy" name) — use exact match
-    expect(screen.getByText(/^draft$/i)).toBeInTheDocument();
+    // "Draft (1)" section header — distinct from the "Draft Policy" policy name
+    expect(screen.getByText(/^draft \(1\)$/i)).toBeInTheDocument();
+  });
+
+  it('groups policies by status with section headers and counts', () => {
+    renderSheet();
+    expect(screen.getByText(/^published \(1\)$/i)).toBeInTheDocument();
+    expect(screen.getByText(/^needs review \(1\)$/i)).toBeInTheDocument();
+    expect(screen.getByText(/^draft \(1\)$/i)).toBeInTheDocument();
+  });
+
+  it('hides inline per-row status badge (status is implied by section)', () => {
+    renderSheet();
+    // The old layout rendered a standalone "Published" badge next to each row.
+    // Section headers now use "Published (1)" wording, so an exact match should
+    // return nothing.
+    const badges = screen.queryAllByText(/^published$/i);
+    expect(badges).toHaveLength(0);
+  });
+
+  it('filters rows live as the user types in the search input', async () => {
+    const user = userEvent.setup();
+    renderSheet();
+
+    const search = screen.getByRole('searchbox', { name: /search policies/i });
+    await user.type(search, 'priva');
+
+    expect(screen.getByLabelText(/privacy policy/i)).toBeInTheDocument();
+    expect(screen.queryByLabelText(/security policy/i)).not.toBeInTheDocument();
+    expect(screen.queryByLabelText(/draft policy/i)).not.toBeInTheDocument();
+  });
+
+  it('shows an empty state when search matches nothing', async () => {
+    const user = userEvent.setup();
+    renderSheet();
+
+    const search = screen.getByRole('searchbox', { name: /search policies/i });
+    await user.type(search, 'zzzzzz');
+
+    expect(screen.getByText(/no policies match/i)).toBeInTheDocument();
+  });
+
+  it('preserves selection state for policies hidden by search', async () => {
+    const user = userEvent.setup();
+    renderSheet();
+
+    // Start: all 3 selected. Deselect Draft Policy.
+    await user.click(screen.getByLabelText(/draft policy/i));
+    expect(
+      screen.getByRole('button', { name: /download 2 policies/i }),
+    ).toBeEnabled();
+
+    // Search to hide Draft Policy entirely
+    const search = screen.getByRole('searchbox', { name: /search policies/i });
+    await user.type(search, 'priva');
+
+    // Download button still says 2 — hidden-but-selected are still counted
+    expect(
+      screen.getByRole('button', { name: /download 2 policies/i }),
+    ).toBeEnabled();
+  });
+
+  it('per-group select-all toggles only that group', async () => {
+    const user = userEvent.setup();
+    renderSheet();
+
+    // Published group: currently 1 selected (p1). Click its group toggle to clear.
+    const publishedGroupToggle = screen.getByRole('checkbox', {
+      name: /toggle published group/i,
+    });
+    await user.click(publishedGroupToggle);
+
+    expect(screen.getByLabelText(/security policy/i)).not.toBeChecked();
+    expect(screen.getByLabelText(/privacy policy/i)).toBeChecked();
+    expect(screen.getByLabelText(/draft policy/i)).toBeChecked();
   });
 
   it('shows "Download 3 policies" by default and enables the button', () => {
diff --git a/apps/app/src/app/(app)/[orgId]/policies/all/components/PolicyDownloadSheet.tsx b/apps/app/src/app/(app)/[orgId]/policies/all/components/PolicyDownloadSheet.tsx
index 92f9e50215..d6a379daee 100644
--- a/apps/app/src/app/(app)/[orgId]/policies/all/components/PolicyDownloadSheet.tsx
+++ b/apps/app/src/app/(app)/[orgId]/policies/all/components/PolicyDownloadSheet.tsx
@@ -3,10 +3,9 @@
 import { api } from '@/lib/api-client';
 import type { Policy, PolicyStatus } from '@db';
 import {
-  Badge,
   Button,
   Checkbox,
-  ScrollArea,
+  Input,
   Sheet,
   SheetBody,
   SheetContent,
@@ -25,20 +24,15 @@ interface PolicyDownloadSheetProps {
   policies: Pick<Policy, 'id' | 'name' | 'status'>[];
 }
 
-type BadgeVariant = 'default' | 'secondary' | 'outline';
+type PolicyRow = Pick<Policy, 'id' | 'name' | 'status'>;
 
+const STATUS_ORDER: PolicyStatus[] = ['published', 'needs_review', 'draft'];
 const STATUS_LABEL: Record<PolicyStatus, string> = {
   published: 'Published',
   needs_review: 'Needs review',
   draft: 'Draft',
 };
 
-const STATUS_VARIANT: Record<PolicyStatus, BadgeVariant> = {
-  published: 'default',
-  needs_review: 'secondary',
-  draft: 'outline',
-};
-
 export function PolicyDownloadSheet({
   open,
   onOpenChange,
@@ -47,15 +41,50 @@ export function PolicyDownloadSheet({
   const allIds = useMemo(() => policies.map((p) => p.id), [policies]);
   const [selected, setSelected] = useState<Set<string>>(() => new Set(allIds));
   const [isDownloading, setIsDownloading] = useState(false);
+  const [query, setQuery] = useState('');
 
-  // Reset selection to all current policies whenever the sheet opens or the
-  // underlying policy list changes, so reopens and prop refreshes don't leave
-  // stale or deleted IDs in the selection.
+  // Reset selection + search whenever the sheet opens or the underlying policy
+  // list changes, so reopens and prop refreshes don't leave stale or deleted
+  // IDs in the selection.
   useEffect(() => {
     if (!open) return;
     setSelected(new Set(allIds));
+    setQuery('');
   }, [open, allIds]);
 
+  const normalizedQuery = query.trim().toLowerCase();
+  const filteredPolicies = useMemo(() => {
+    if (!normalizedQuery) return policies;
+    return policies.filter((p) =>
+      (p.name ?? '').toLowerCase().includes(normalizedQuery),
+    );
+  }, [policies, normalizedQuery]);
+
+  const groups = useMemo(() => {
+    const byStatus = new Map<PolicyStatus, PolicyRow[]>();
+    for (const p of filteredPolicies) {
+      const status = (p.status ?? 'draft') as PolicyStatus;
+      const list = byStatus.get(status) ?? [];
+      list.push(p);
+      byStatus.set(status, list);
+    }
+    return STATUS_ORDER.filter((s) => (byStatus.get(s)?.length ?? 0) > 0).map(
+      (s) => ({ status: s, items: byStatus.get(s) ?? [] }),
+    );
+  }, [filteredPolicies]);
+
+  const visibleIds = useMemo(
+    () => filteredPolicies.map((p) => p.id),
+    [filteredPolicies],
+  );
+  const visibleSelectedCount = visibleIds.filter((id) =>
+    selected.has(id),
+  ).length;
+  const allVisibleChecked =
+    visibleIds.length > 0 && visibleSelectedCount === visibleIds.length;
+  const someVisibleChecked =
+    visibleSelectedCount > 0 && visibleSelectedCount < visibleIds.length;
+
   const handleToggle = (id: string) => {
     setSelected((prev) => {
       const next = new Set(prev);
@@ -65,13 +94,29 @@ export function PolicyDownloadSheet({
     });
   };
 
-  const allChecked = selected.size === allIds.length && allIds.length > 0;
-  const someChecked = selected.size > 0 && !allChecked;
+  const handleToggleVisible = () => {
+    setSelected((prev) => {
+      const next = new Set(prev);
+      if (allVisibleChecked) {
+        for (const id of visibleIds) next.delete(id);
+      } else {
+        for (const id of visibleIds) next.add(id);
+      }
+      return next;
+    });
+  };
 
-  const handleToggleAll = () => {
-    setSelected((prev) =>
-      prev.size === allIds.length ? new Set() : new Set(allIds),
-    );
+  const handleToggleGroup = (groupIds: string[]) => {
+    const allChecked = groupIds.every((id) => selected.has(id));
+    setSelected((prev) => {
+      const next = new Set(prev);
+      if (allChecked) {
+        for (const id of groupIds) next.delete(id);
+      } else {
+        for (const id of groupIds) next.add(id);
+      }
+      return next;
+    });
   };
 
   const handleDownload = async () => {
@@ -111,6 +156,12 @@ export function PolicyDownloadSheet({
       ? 'Download'
       : `Download ${count} ${count === 1 ? 'policy' : 'policies'}`;
 
+  const hasAnyResults = filteredPolicies.length > 0;
+  const totalDiffersFromVisible = count !== visibleSelectedCount;
+  const selectAllSuffix = totalDiffersFromVisible
+    ? `, ${count} total selected`
+    : '';
+
   return (
     <Sheet open={open} onOpenChange={onOpenChange}>
       <SheetContent>
@@ -119,42 +170,70 @@ export function PolicyDownloadSheet({
         </SheetHeader>
         <SheetBody>
           <Stack gap="md">
-            <div className="flex items-center gap-2">
+            <Input
+              type="search"
+              placeholder="Search policies…"
+              value={query}
+              onChange={(e) => setQuery(e.target.value)}
+              aria-label="Search policies"
+            />
+
+            <div className="flex items-center gap-2 border-b pb-3">
               <Checkbox
-                checked={allChecked}
-                indeterminate={someChecked}
-                onCheckedChange={handleToggleAll}
+                checked={allVisibleChecked}
+                indeterminate={someVisibleChecked}
+                onCheckedChange={handleToggleVisible}
                 aria-label="Select all"
+                disabled={!hasAnyResults}
               />
               <Text>
-                Select all ({selected.size} of {allIds.length} selected)
+                Select all ({visibleSelectedCount} of {visibleIds.length} shown
+                {selectAllSuffix})
               </Text>
             </div>
-            <ScrollArea>
-              <Stack gap="xs">
-                {policies.map((policy) => {
-                  const statusKey = policy.status ?? 'draft';
-                  return (
-                    <div
-                      key={policy.id}
-                      className="flex items-center gap-2 py-1"
-                    >
+
+            {!hasAnyResults && <Text>No policies match "{query}".</Text>}
+
+            {hasAnyResults &&
+              groups.map((group) => {
+                const groupIds = group.items.map((p) => p.id);
+                const groupChecked =
+                  groupIds.length > 0 &&
+                  groupIds.every((id) => selected.has(id));
+                const groupSome =
+                  !groupChecked && groupIds.some((id) => selected.has(id));
+
+                return (
+                  <div key={group.status} className="flex flex-col">
+                    <div className="flex items-center gap-2 py-1">
                       <Checkbox
-                        checked={selected.has(policy.id)}
-                        onCheckedChange={() => handleToggle(policy.id)}
-                        aria-label={policy.name ?? 'Policy'}
+                        checked={groupChecked}
+                        indeterminate={groupSome}
+                        onCheckedChange={() => handleToggleGroup(groupIds)}
+                        aria-label={`Toggle ${STATUS_LABEL[group.status]} group`}
                       />
-                      <div className="flex flex-1 items-center gap-2">
-                        <Text>{policy.name}</Text>
-                        <Badge variant={STATUS_VARIANT[statusKey] ?? 'outline'}>
-                          {STATUS_LABEL[statusKey] ?? statusKey}
-                        </Badge>
-                      </div>
+                      <span className="text-muted-foreground text-xs font-medium uppercase tracking-wide">
+                        {STATUS_LABEL[group.status]} ({group.items.length})
+                      </span>
+                    </div>
+                    <div className="flex flex-col">
+                      {group.items.map((policy) => (
+                        <div
+                          key={policy.id}
+                          className="hover:bg-muted/40 flex h-10 items-center gap-2 rounded-sm px-2"
+                        >
+                          <Checkbox
+                            checked={selected.has(policy.id)}
+                            onCheckedChange={() => handleToggle(policy.id)}
+                            aria-label={policy.name ?? 'Policy'}
+                          />
+                          <Text>{policy.name}</Text>
+                        </div>
+                      ))}
                     </div>
-                  );
-                })}
-              </Stack>
-            </ScrollArea>
+                  </div>
+                );
+              })}
           </Stack>
         </SheetBody>
         <SheetFooter>

From f817d4465da29ab7f868b5271e45b632feb070f2 Mon Sep 17 00:00:00 2001
From: chasprowebdev <chasgarciaprowebdev@gmail.com>
Date: Fri, 24 Apr 2026 15:56:48 -0400
Subject: [PATCH 28/40] fix(app): correct SOA document info during the status
 changes

---
 .../documents/components/SOAOverviewCard.tsx  |  1 -
 .../components/SOADocumentInfo.tsx            | 11 ++++++----
 .../components/SOAFrameworkTable.tsx          |  6 ++++--
 .../hooks/useSOADocument.ts                   | 20 +++++++++----------
 4 files changed, 20 insertions(+), 18 deletions(-)

diff --git a/apps/app/src/app/(app)/[orgId]/documents/components/SOAOverviewCard.tsx b/apps/app/src/app/(app)/[orgId]/documents/components/SOAOverviewCard.tsx
index 110b8b1ee6..62aa664646 100644
--- a/apps/app/src/app/(app)/[orgId]/documents/components/SOAOverviewCard.tsx
+++ b/apps/app/src/app/(app)/[orgId]/documents/components/SOAOverviewCard.tsx
@@ -121,7 +121,6 @@ export function SOAOverviewCard({
     if (document.declinedAt) return 'Declined';
     if (
       document.status === 'needs_review' ||
-      document.status === 'pending_approval' ||
       !!document.approverId
     ) {
       return 'Pending';
diff --git a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOADocumentInfo.tsx b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOADocumentInfo.tsx
index 0dbe4dd839..35ca9848c2 100644
--- a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOADocumentInfo.tsx
+++ b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOADocumentInfo.tsx
@@ -42,9 +42,9 @@ export function SOADocumentInfo({
 
   const approvalStatusText = document.approvedAt
     ? `Approved on ${new Date(document.approvedAt).toLocaleDateString()}`
-    : document.status === 'needs_review' && document.declinedAt
+    : document.declinedAt
       ? `Declined on ${new Date(document.declinedAt).toLocaleDateString()}`
-      : approver
+      : document.status === 'needs_review'
         ? 'Pending approval'
         : 'Not approved';
 
@@ -93,13 +93,16 @@ export function SOADocumentInfo({
               <InfoItem label="Approved by" value={approver.user.name || approver.user.email || 'Unknown'} />
             </>
           )}
-          {approver && !document.approvedAt && document.status !== 'needs_review' && (
+          {approver &&
+            !document.approvedAt &&
+            !document.declinedAt &&
+            document.status === 'needs_review' && (
             <>
               <div className="hidden xl:block h-8 w-px bg-border" />
               <InfoItem label="Pending approval by" value={approver.user.name || approver.user.email || 'Unknown'} />
             </>
           )}
-          {document.status === 'needs_review' && document.declinedAt && (
+          {document.declinedAt && (
             <>
               <div className="hidden xl:block h-8 w-px bg-border" />
               <InfoItem
diff --git a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOAFrameworkTable.tsx b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOAFrameworkTable.tsx
index e2b591498a..675cd0bef6 100644
--- a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOAFrameworkTable.tsx
+++ b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOAFrameworkTable.tsx
@@ -84,12 +84,14 @@ export function SOAFrameworkTable({
 
   // Derive state from SWR-cached document (updates after mutations)
   const resolvedDocument = swrDocument ?? document;
-  const derivedIsPendingApproval = resolvedDocument?.status === 'pending_approval' || isPendingApproval;
+  const derivedIsPendingApproval = resolvedDocument
+    ? resolvedDocument.status === 'needs_review'
+    : isPendingApproval;
   const derivedApproverId = (resolvedDocument?.approverId ?? document?.approverId) as string | null | undefined;
   // Resolve the approver member from the list using the derived approverId
   const derivedApprover = derivedApproverId
     ? ownerAdminMembers.find((m) => m.id === derivedApproverId) ?? approver
-    : approver;
+    : null;
   const derivedCanCurrentUserApprove = derivedIsPendingApproval && derivedApproverId === currentMemberId;
 
   const columns = configuration.columns as SOAColumn[];
diff --git a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/hooks/useSOADocument.ts b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/hooks/useSOADocument.ts
index f74d261fd2..91fa1d7e63 100644
--- a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/hooks/useSOADocument.ts
+++ b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/hooks/useSOADocument.ts
@@ -70,14 +70,13 @@ export function useSOADocument({ documentId, organizationId, fallbackData }: Use
     if (response.error) throw new Error(response.error);
     if (!response.data?.success) throw new Error('Failed to save answer');
 
-    await mutate();
     return true;
   };
 
   const approve = async (): Promise<boolean> => {
     if (!documentId) throw new Error('No document ID');
 
-    const response = await api.post<{ success: boolean; data?: unknown }>(
+    const response = await api.post<{ success: boolean; data?: SOADocumentData }>(
       '/v1/soa/approve',
       { organizationId, documentId },
     );
@@ -85,8 +84,8 @@ export function useSOADocument({ documentId, organizationId, fallbackData }: Use
     if (response.error) throw new Error(response.error || 'Failed to approve SOA document');
     if (!response.data?.success) throw new Error('Failed to approve SOA document');
 
-    if (data) {
-      await mutate({ ...data, status: 'approved', approvedAt: new Date().toISOString() }, false);
+    if (response.data?.data) {
+      await mutate(response.data.data, false);
     }
     return true;
   };
@@ -94,7 +93,7 @@ export function useSOADocument({ documentId, organizationId, fallbackData }: Use
   const decline = async (): Promise<boolean> => {
     if (!documentId) throw new Error('No document ID');
 
-    const response = await api.post<{ success: boolean; data?: unknown }>(
+    const response = await api.post<{ success: boolean; data?: SOADocumentData }>(
       '/v1/soa/decline',
       { organizationId, documentId },
     );
@@ -102,8 +101,8 @@ export function useSOADocument({ documentId, organizationId, fallbackData }: Use
     if (response.error) throw new Error(response.error || 'Failed to decline SOA document');
     if (!response.data?.success) throw new Error('Failed to decline SOA document');
 
-    if (data) {
-      await mutate({ ...data, status: 'needs_review', declinedAt: new Date().toISOString() }, false);
+    if (response.data?.data) {
+      await mutate(response.data.data, false);
     }
     return true;
   };
@@ -111,7 +110,7 @@ export function useSOADocument({ documentId, organizationId, fallbackData }: Use
   const submitForApproval = async (approverId: string): Promise<boolean> => {
     if (!documentId) throw new Error('No document ID');
 
-    const response = await api.post<{ success: boolean; data?: unknown }>(
+    const response = await api.post<{ success: boolean; data?: SOADocumentData }>(
       '/v1/soa/submit-for-approval',
       { organizationId, documentId, approverId },
     );
@@ -119,9 +118,8 @@ export function useSOADocument({ documentId, organizationId, fallbackData }: Use
     if (response.error) throw new Error(response.error || 'Failed to submit for approval');
     if (!response.data?.success) throw new Error('Failed to submit for approval');
 
-    // Optimistically update cached document status
-    if (data) {
-      await mutate({ ...data, status: 'pending_approval', approverId }, false);
+    if (response.data?.data) {
+      await mutate(response.data.data, false);
     }
     return true;
   };

From 7705eca723b1208ef95650cebdc2e103f3e6cb2d Mon Sep 17 00:00:00 2001
From: chasprowebdev <chasgarciaprowebdev@gmail.com>
Date: Fri, 24 Apr 2026 15:57:27 -0400
Subject: [PATCH 29/40] fix(api): update the soa pdf content

---
 apps/api/src/soa/utils/export-generator.ts | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/apps/api/src/soa/utils/export-generator.ts b/apps/api/src/soa/utils/export-generator.ts
index df2859e5ac..f1fc30fc8f 100644
--- a/apps/api/src/soa/utils/export-generator.ts
+++ b/apps/api/src/soa/utils/export-generator.ts
@@ -109,12 +109,19 @@ function generateSOAPDF(
     ? `Approved on ${new Date(metadata.approvedAt).toLocaleDateString()}`
     : metadata.declinedAt
       ? `Declined on ${new Date(metadata.declinedAt).toLocaleDateString()}`
-      : metadata.approverName
+      : metadata.status === 'needs_review'
         ? 'Pending approval'
         : 'Not approved';
+  const approvalActorLabel = metadata.approvedAt
+    ? 'Approved by'
+    : metadata.declinedAt
+      ? 'Declined by'
+      : metadata.status === 'needs_review'
+        ? 'Pending approval by'
+        : 'Approver';
   pdf.text(`Approval status: ${approvalStatusText}`, margin, y);
   y += lineHeight;
-  pdf.text(`Approved by: ${metadata.approverName || 'N/A'}`, margin, y);
+  pdf.text(`${approvalActorLabel}: ${metadata.approverName || 'N/A'}`, margin, y);
   y += lineHeight;
   pdf.text(`Exported: ${new Date().toLocaleDateString()}`, margin, y);
   y += lineHeight * 2;

From 959d5717cf190e7cad2a5ab6c239f5823e9bedd2 Mon Sep 17 00:00:00 2001
From: chasprowebdev <chasgarciaprowebdev@gmail.com>
Date: Fri, 24 Apr 2026 16:26:19 -0400
Subject: [PATCH 30/40] fix(app): handle /v1/frameworks fetch errors before
 showing not found message on SOA

---
 .../documents/statement-of-applicability/page.tsx  | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/page.tsx b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/page.tsx
index e41b658023..a9a9ed12a8 100644
--- a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/page.tsx
+++ b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/page.tsx
@@ -71,6 +71,13 @@ export default async function StatementOfApplicabilityPage({
     serverApi.get<ContextApiResponse>('/v1/context'),
   ]);
 
+  let soaData: SOAData | null = null;
+  let soaError: string | null = null;
+
+  if (frameworksResult.error) {
+    soaError = 'Failed to load frameworks. Please try again later.';
+  }
+
   const frameworks = frameworksResult.data?.data ?? [];
   const isoFrameworkInstance = frameworks.find(
     (fi) => fi.framework?.name && ISO27001_NAMES.includes(fi.framework.name),
@@ -79,10 +86,7 @@ export default async function StatementOfApplicabilityPage({
   const people = peopleResult.data?.data ?? [];
   const contextEntries = contextResult.data?.data ?? [];
 
-  let soaData: SOAData | null = null;
-  let soaError: string | null = null;
-
-  if (isoFrameworkInstance) {
+  if (!soaError && isoFrameworkInstance) {
     try {
       const { frameworkId, framework } = isoFrameworkInstance;
 
@@ -159,7 +163,7 @@ export default async function StatementOfApplicabilityPage({
       console.error('Failed to setup SOA:', error);
       soaError = 'Failed to setup SOA. Please try again later.';
     }
-  } else {
+  } else if (!soaError) {
     soaError =
       'ISO 27001 framework not found. Please add ISO 27001 framework to your organization to get started.';
   }

From b9a580f70c84ca7500cc654574876366596c620b Mon Sep 17 00:00:00 2001
From: chasprowebdev <chasgarciaprowebdev@gmail.com>
Date: Fri, 24 Apr 2026 16:28:39 -0400
Subject: [PATCH 31/40] fix(app): guard answers sync effect from clearing
 answersMap on partial data in SOA page

---
 .../components/SOAFrameworkTable.tsx                         | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOAFrameworkTable.tsx b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOAFrameworkTable.tsx
index 675cd0bef6..21866e0fa7 100644
--- a/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOAFrameworkTable.tsx
+++ b/apps/app/src/app/(app)/[orgId]/documents/statement-of-applicability/components/SOAFrameworkTable.tsx
@@ -109,9 +109,12 @@ export function SOAFrameworkTable({
 
   // Update answersMap when the live document changes
   useEffect(() => {
+    if (!Array.isArray(resolvedDocument?.answers)) {
+      return;
+    }
     setAnswersMap(
       new Map(
-        (resolvedDocument?.answers || []).map((answer: { questionId: string; answer: string | null; answerVersion: number }) => [
+        resolvedDocument.answers.map((answer: { questionId: string; answer: string | null; answerVersion: number }) => [
           answer.questionId,
           { answer: answer.answer, answerVersion: answer.answerVersion },
         ])

From 32b210ee57f4b8eb0c900a961e53a1d7dc9e600e Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Sat, 25 Apr 2026 12:37:57 -0400
Subject: [PATCH 32/40] feat: add ability to set frequency on automations
 running
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(api): add isDueToday scheduler helper

* test(api): use .spec.ts suffix and fix misleading test title

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* refactor(api): harden isDueToday exhaustive check and document UTC contract

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(db): add per-automation scheduleFrequency and lastRunAt

* refactor(api): remove stale schedule field from browserbase DTOs and update service

The BrowserAutomation.schedule column was dropped in the previous commit.
TypeScript did not catch the dangling DTO entries or updateBrowserAutomation
param because object spread does not trigger excess-property checks, but
Prisma would throw "Unknown argument" at runtime if a caller supplied the
field.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(api): respect integrationScheduleFrequency in integration orchestrator

* fix(api): retry integration task on transient execution error

Previously, integrationLastRunAt was written whenever the check loop
completed, even if one or more checks returned status='error' (meaning
the check could not execute). On weekly+ schedules this would push the
retry out a full period. Distinguish 'error' (infra issue, retry) from
'failed' (legitimate finding, ran successfully).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(api): respect scheduleFrequency in browser automation orchestrator

* docs(api): clarify browser orchestrator retry comment

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(api): accept scheduleFrequency in automation and task PATCH endpoints

* feat(app): add SchedulePicker component

* feat(app): add schedule picker to browser automation config

* feat(app): add schedule edit dialog for evidence automations

* feat(app): add integration schedule picker on task detail

* feat(app): show schedule summary on automation cards

* fix(app,api): repair test fixtures and guard missing schedule frequency

Updates test fixtures for Task schema additions (integrationScheduleFrequency,
integrationLastRunAt, previousStatus, archivedAt, lastCompletedAt),
adds TaskFrequency to the @db mock in browserbase.controller.spec so
the new @IsEnum(TaskFrequency) DTO decorator resolves at module load,
and fixes an undefined-index access in AutomationOverview when the
scheduleFrequency field is missing on stale client types.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* style(api): apply prettier to SALE-49 files

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix: address cubic review findings on schedule UI and DTOs

- TaskIntegrationChecks: compute "Next run" from scheduleFrequency +
  lastRunAt rather than hardcoding daily 6 AM UTC (was misleading for
  non-daily schedules).
- Task response DTOs (swagger.dto.ts + task-responses.dto.ts): expose
  integrationScheduleFrequency and integrationLastRunAt so API
  consumers see them in generated documentation.
- ScheduleSummary: render locale-agnostic YYYY-MM-DD and anchor "now"
  to UTC midnight to prevent server/client hydration mismatches.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(app): daily period is 1 day in TaskIntegrationChecks next-run calc

daily: 0 caused the "next run" display to always skip to tomorrow even
when the task was due today. Align with ScheduleSummary's PERIOD_DAYS map.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(api): include integrationScheduleFrequency in createTask response

The TaskResponseDto now declares integrationScheduleFrequency as a
required field; the createTask service method must populate it from
the persisted row to satisfy the contract.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(app): inline schedule picker on automation overview, render label not enum

Replaces EditScheduleDialog with an inline SchedulePicker on the
automation Settings tab — fewer clicks, no Dialog focus-trap quirks
when interacting with the DS Select. Also forces SelectValue to
render the human label (e.g. "Daily") rather than falling back to
the raw enum string when re-opened.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(app): metrics schedule + next-run reflect frequency in user's TZ

- MetricsSection now takes scheduleFrequency + lastRunAt and re-derives
  the Schedule and Next Run labels per change.
- "Every day at 9:00 AM UTC" → "Every day at 4:00 AM EST" (or whatever
  the user's locale resolves), and the same TZ is shown on Next Run for
  consistency.
- Both labels are computed client-only to avoid SSR/CSR drift across
  timezones; placeholder em-dash during SSR.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(app): use @trycompai/ui Select in SchedulePicker

The DS Select uses base-ui internals whose portaled popover fights with
the Radix-based Dialog focus trap (closes immediately on click in
BrowserAutomationConfigDialog). @trycompai/ui Select is Radix-based
like the Dialog, so the two co-operate. Same API shape so callers
don't change. Test mock updated accordingly.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(app): show next-run as next tick (not now + period) when never run

For null lastRunAt the orchestrator's isDueToday short-circuits to true,
so the automation runs on the very next 09:00 UTC tick. The previous
math added a full period to "now", over-projecting a never-run weekly
automation a full week into the future.

Apply the same fix to ScheduleSummary on automation cards.

Also tighten the MetricsSection test's UTC-absence assertion to use a
word-boundary regex so it can't pass on a label that legitimately
contains "UTC".

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Mariano <marfuen98@gmail.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../browserbase.controller.spec.ts            |  16 +-
 .../browserbase/browserbase.service.spec.ts   |  89 ++-
 .../src/browserbase/browserbase.service.ts    |  32 +-
 .../src/browserbase/dto/browserbase.dto.ts    |  27 +-
 .../tasks/automations/automations.service.ts  |   7 +-
 .../automations/dto/update-automation.dto.ts  |  13 +-
 apps/api/src/tasks/dto/swagger.dto.ts         |  28 +
 apps/api/src/tasks/dto/task-responses.dto.ts  |  14 +
 apps/api/src/tasks/schemas/task.schemas.ts    |   1 +
 apps/api/src/tasks/tasks.controller.ts        |  11 +
 apps/api/src/tasks/tasks.service.ts           |  12 +-
 .../run-browser-automation.ts                 |  18 +
 .../run-browser-automations-schedule.spec.ts  | 118 ++++
 .../run-browser-automations-schedule.ts       |  62 +-
 .../run-integration-checks-schedule.spec.ts   | 117 ++++
 .../run-integration-checks-schedule.ts        |  42 +-
 .../run-task-integration-checks.ts            |  17 +
 .../src/trigger/shared/is-due-today.spec.ts   | 141 +++++
 apps/api/src/trigger/shared/is-due-today.ts   |  51 ++
 .../hooks/use-task-automation.ts              |  13 +-
 .../components/AutomationOverview.tsx         |  44 +-
 .../components/MetricsSection.test.tsx        | 152 +++--
 .../overview/components/MetricsSection.tsx    | 147 +++--
 .../tasks/[taskId]/components/SingleTask.tsx  |  16 +
 .../[taskId]/components/TaskAutomations.tsx   |   5 +
 .../components/TaskIntegrationChecks.tsx      |  73 ++-
 .../browser-automations/AutomationItem.tsx    |   9 +
 .../BrowserAutomationConfigDialog.tsx         |  42 +-
 .../[orgId]/tasks/[taskId]/hooks/types.ts     |   4 +
 .../[orgId]/tasks/[taskId]/hooks/use-task.ts  |   3 +-
 .../[taskId]/hooks/useBrowserAutomations.ts   |   3 +
 .../ModernSingleStatusTaskList.test.tsx       |  34 +-
 .../tasks/components/TaskList.test.tsx        |   5 +
 .../src/components/schedule-picker.test.tsx   |  91 +++
 apps/app/src/components/schedule-picker.tsx   |  49 ++
 .../src/components/schedule-summary.test.tsx  |  22 +
 apps/app/src/components/schedule-summary.tsx  |  60 ++
 .../migration.sql                             |  18 +
 packages/db/prisma/schema/auth.prisma         |  28 +-
 packages/db/prisma/schema/automation.prisma   |  12 +-
 .../prisma/schema/browserbase-context.prisma  | 121 ++--
 packages/db/prisma/schema/control.prisma      |  14 +-
 packages/db/prisma/schema/device.prisma       |  14 +-
 .../prisma/schema/dynamic-integration.prisma  | 150 ++---
 .../db/prisma/schema/framework-editor.prisma  |   4 +-
 .../db/prisma/schema/framework-version.prisma |  20 +-
 .../prisma/schema/integration-platform.prisma | 544 +++++++++---------
 .../prisma/schema/integration-sync-log.prisma |   6 +-
 .../prisma/schema/notification-policy.prisma  |   8 +-
 .../prisma/schema/organization-billing.prisma |   2 +-
 packages/db/prisma/schema/organization.prisma |  38 +-
 packages/db/prisma/schema/policy.prisma       |   6 +-
 .../prisma/schema/remediation-action.prisma   |  48 +-
 .../db/prisma/schema/remediation-batch.prisma |  32 +-
 .../security-penetration-test-run.prisma      |  10 +-
 packages/db/prisma/schema/soa.prisma          |   4 +-
 packages/db/prisma/schema/task-item.prisma    |  28 +-
 packages/db/prisma/schema/task.prisma         |  22 +-
 packages/db/prisma/schema/timeline.prisma     | 110 ++--
 59 files changed, 2048 insertions(+), 779 deletions(-)
 create mode 100644 apps/api/src/trigger/browser-automation/run-browser-automations-schedule.spec.ts
 create mode 100644 apps/api/src/trigger/integration-platform/run-integration-checks-schedule.spec.ts
 create mode 100644 apps/api/src/trigger/shared/is-due-today.spec.ts
 create mode 100644 apps/api/src/trigger/shared/is-due-today.ts
 create mode 100644 apps/app/src/components/schedule-picker.test.tsx
 create mode 100644 apps/app/src/components/schedule-picker.tsx
 create mode 100644 apps/app/src/components/schedule-summary.test.tsx
 create mode 100644 apps/app/src/components/schedule-summary.tsx
 create mode 100644 packages/db/prisma/migrations/20260424164600_custom_task_schedules/migration.sql

diff --git a/apps/api/src/browserbase/browserbase.controller.spec.ts b/apps/api/src/browserbase/browserbase.controller.spec.ts
index 1713edeffa..6e8cbe75e0 100644
--- a/apps/api/src/browserbase/browserbase.controller.spec.ts
+++ b/apps/api/src/browserbase/browserbase.controller.spec.ts
@@ -10,6 +10,13 @@ jest.mock('@db', () => ({
       }
     },
   },
+  TaskFrequency: {
+    daily: 'daily',
+    weekly: 'weekly',
+    monthly: 'monthly',
+    quarterly: 'quarterly',
+    yearly: 'yearly',
+  },
 }));
 
 jest.mock('../auth/auth.server', () => ({
@@ -35,7 +42,9 @@ import { PermissionGuard } from '../auth/permission.guard';
 
 describe('BrowserbaseController.redirectToScreenshot', () => {
   let controller: BrowserbaseController;
-  let service: jest.Mocked<Pick<BrowserbaseService, 'getScreenshotRedirectUrl'>>;
+  let service: jest.Mocked<
+    Pick<BrowserbaseService, 'getScreenshotRedirectUrl'>
+  >;
 
   beforeEach(async () => {
     service = {
@@ -73,7 +82,10 @@ describe('BrowserbaseController.redirectToScreenshot', () => {
       organizationId: 'org_1',
       download: false,
     });
-    expect(res.redirect).toHaveBeenCalledWith(302, 'https://s3.example.com/fresh-signed');
+    expect(res.redirect).toHaveBeenCalledWith(
+      302,
+      'https://s3.example.com/fresh-signed',
+    );
   });
 
   it('passes download=true to the service when the query param is "true"', async () => {
diff --git a/apps/api/src/browserbase/browserbase.service.spec.ts b/apps/api/src/browserbase/browserbase.service.spec.ts
index 5a06feaf39..7f8cdba32f 100644
--- a/apps/api/src/browserbase/browserbase.service.spec.ts
+++ b/apps/api/src/browserbase/browserbase.service.spec.ts
@@ -8,6 +8,17 @@ jest.mock('@db', () => ({
     browserAutomationRun: {
       findUnique: jest.fn(),
     },
+    browserAutomation: {
+      create: jest.fn(),
+      update: jest.fn(),
+    },
+  },
+  TaskFrequency: {
+    daily: 'daily',
+    weekly: 'weekly',
+    monthly: 'monthly',
+    quarterly: 'quarterly',
+    yearly: 'yearly',
   },
 }));
 
@@ -17,7 +28,7 @@ jest.mock('@/app/s3', () => ({
   BUCKET_NAME: 'test-bucket',
 }));
 
-import { db } from '@db';
+import { db, TaskFrequency } from '@db';
 import { getSignedUrl } from '@/app/s3';
 
 describe('BrowserbaseService.getScreenshotRedirectUrl', () => {
@@ -126,3 +137,79 @@ describe('BrowserbaseService.getScreenshotRedirectUrl', () => {
     );
   });
 });
+
+describe('BrowserbaseService schedule frequency passthrough', () => {
+  let service: BrowserbaseService;
+
+  beforeEach(async () => {
+    jest.clearAllMocks();
+    const moduleRef = await Test.createTestingModule({
+      providers: [BrowserbaseService],
+    }).compile();
+    service = moduleRef.get(BrowserbaseService);
+  });
+
+  it('forwards scheduleFrequency when creating a browser automation', async () => {
+    (db.browserAutomation.create as jest.Mock).mockResolvedValue({
+      id: 'bau_1',
+    });
+
+    await service.createBrowserAutomation({
+      taskId: 'tsk_1',
+      name: 'name',
+      targetUrl: 'https://example.com',
+      instruction: 'click',
+      scheduleFrequency: TaskFrequency.weekly,
+    });
+
+    expect(db.browserAutomation.create).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ scheduleFrequency: 'weekly' }),
+      }),
+    );
+  });
+
+  it('omits scheduleFrequency when creating without the field', async () => {
+    (db.browserAutomation.create as jest.Mock).mockResolvedValue({
+      id: 'bau_1',
+    });
+
+    await service.createBrowserAutomation({
+      taskId: 'tsk_1',
+      name: 'name',
+      targetUrl: 'https://example.com',
+      instruction: 'click',
+    });
+
+    const call = (db.browserAutomation.create as jest.Mock).mock.calls[0][0];
+    expect(call.data).not.toHaveProperty('scheduleFrequency');
+  });
+
+  it('forwards scheduleFrequency when updating a browser automation', async () => {
+    (db.browserAutomation.update as jest.Mock).mockResolvedValue({
+      id: 'bau_1',
+    });
+
+    await service.updateBrowserAutomation('bau_1', {
+      scheduleFrequency: TaskFrequency.monthly,
+    });
+
+    expect(db.browserAutomation.update).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { id: 'bau_1' },
+        data: expect.objectContaining({ scheduleFrequency: 'monthly' }),
+      }),
+    );
+  });
+
+  it('omits scheduleFrequency when updating without the field', async () => {
+    (db.browserAutomation.update as jest.Mock).mockResolvedValue({
+      id: 'bau_1',
+    });
+
+    await service.updateBrowserAutomation('bau_1', { name: 'renamed' });
+
+    const call = (db.browserAutomation.update as jest.Mock).mock.calls[0][0];
+    expect(call.data).not.toHaveProperty('scheduleFrequency');
+  });
+});
diff --git a/apps/api/src/browserbase/browserbase.service.ts b/apps/api/src/browserbase/browserbase.service.ts
index 8e388fbc13..da81adadea 100644
--- a/apps/api/src/browserbase/browserbase.service.ts
+++ b/apps/api/src/browserbase/browserbase.service.ts
@@ -3,9 +3,13 @@ import Browserbase from '@browserbasehq/sdk';
 // Lazy-imported in createStagehand() to avoid Node v25 crash
 // (SlowBuffer.prototype was removed — @browserbasehq/stagehand bundles buffer-equal-constant-time which uses it)
 type Stagehand = import('@browserbasehq/stagehand').Stagehand;
-import { db } from '@db';
+import { db, TaskFrequency } from '@db';
 import { z } from 'zod';
-import { GetObjectCommand, PutObjectCommand, S3Client } from '@aws-sdk/client-s3';
+import {
+  GetObjectCommand,
+  PutObjectCommand,
+  S3Client,
+} from '@aws-sdk/client-s3';
 import { BUCKET_NAME, getSignedUrl, s3Client } from '@/app/s3';
 import { renderOverlay } from './screenshot-overlay';
 import { isNoPageError, toRunErrorMessage } from './run-error-formatter';
@@ -353,7 +357,7 @@ export class BrowserbaseService {
     targetUrl: string;
     instruction: string;
     evaluationCriteria?: string;
-    schedule?: string;
+    scheduleFrequency?: TaskFrequency;
   }) {
     return db.browserAutomation.create({
       data: {
@@ -363,8 +367,10 @@ export class BrowserbaseService {
         targetUrl: data.targetUrl,
         instruction: data.instruction,
         evaluationCriteria: normalizeCriteria(data.evaluationCriteria),
-        schedule: data.schedule,
         isEnabled: true, // Enable by default so scheduled runs work
+        ...(data.scheduleFrequency !== undefined
+          ? { scheduleFrequency: data.scheduleFrequency }
+          : {}),
       },
     });
   }
@@ -402,11 +408,11 @@ export class BrowserbaseService {
       targetUrl?: string;
       instruction?: string;
       evaluationCriteria?: string;
-      schedule?: string;
       isEnabled?: boolean;
+      scheduleFrequency?: TaskFrequency;
     },
   ) {
-    const { evaluationCriteria, ...rest } = data;
+    const { evaluationCriteria, scheduleFrequency, ...rest } = data;
     return db.browserAutomation.update({
       where: { id: automationId },
       data: {
@@ -414,6 +420,7 @@ export class BrowserbaseService {
         ...(evaluationCriteria !== undefined
           ? { evaluationCriteria: normalizeCriteria(evaluationCriteria) }
           : {}),
+        ...(scheduleFrequency !== undefined ? { scheduleFrequency } : {}),
       },
     });
   }
@@ -848,10 +855,15 @@ export class BrowserbaseService {
           capturedAt: new Date(),
         });
       } catch (overlayErr) {
-        this.logger.warn('Screenshot overlay render failed; uploading raw image', {
-          error:
-            overlayErr instanceof Error ? overlayErr.message : String(overlayErr),
-        });
+        this.logger.warn(
+          'Screenshot overlay render failed; uploading raw image',
+          {
+            error:
+              overlayErr instanceof Error
+                ? overlayErr.message
+                : String(overlayErr),
+          },
+        );
       }
 
       // Optional evaluation: if the automation was configured with
diff --git a/apps/api/src/browserbase/dto/browserbase.dto.ts b/apps/api/src/browserbase/dto/browserbase.dto.ts
index 00b637cf20..2a7334a782 100644
--- a/apps/api/src/browserbase/dto/browserbase.dto.ts
+++ b/apps/api/src/browserbase/dto/browserbase.dto.ts
@@ -1,11 +1,13 @@
 import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 import {
+  IsEnum,
   IsNotEmpty,
   IsOptional,
   IsString,
   IsBoolean,
   IsUrl,
 } from 'class-validator';
+import { TaskFrequency } from '@db';
 import { IsSafeUrl } from '../validators/url-safety.validator';
 
 // ===== Session DTOs =====
@@ -90,10 +92,13 @@ export class CreateBrowserAutomationDto {
   @IsOptional()
   evaluationCriteria?: string;
 
-  @ApiPropertyOptional({ description: 'Cron schedule expression' })
-  @IsString()
+  @ApiPropertyOptional({
+    enum: TaskFrequency,
+    description: 'Automation schedule cadence',
+  })
+  @IsEnum(TaskFrequency)
   @IsOptional()
-  schedule?: string;
+  scheduleFrequency?: TaskFrequency;
 }
 
 export class UpdateBrowserAutomationDto {
@@ -127,15 +132,18 @@ export class UpdateBrowserAutomationDto {
   @IsOptional()
   evaluationCriteria?: string;
 
-  @ApiPropertyOptional({ description: 'Cron schedule expression' })
-  @IsString()
-  @IsOptional()
-  schedule?: string;
-
   @ApiPropertyOptional({ description: 'Whether automation is enabled' })
   @IsBoolean()
   @IsOptional()
   isEnabled?: boolean;
+
+  @ApiPropertyOptional({
+    enum: TaskFrequency,
+    description: 'Automation schedule cadence',
+  })
+  @IsEnum(TaskFrequency)
+  @IsOptional()
+  scheduleFrequency?: TaskFrequency;
 }
 
 // ===== Response DTOs =====
@@ -186,9 +194,6 @@ export class BrowserAutomationResponseDto {
   @ApiProperty()
   isEnabled: boolean;
 
-  @ApiPropertyOptional()
-  schedule?: string;
-
   @ApiProperty()
   createdAt: Date;
 
diff --git a/apps/api/src/tasks/automations/automations.service.ts b/apps/api/src/tasks/automations/automations.service.ts
index 3afedd380f..86a6fd8ee9 100644
--- a/apps/api/src/tasks/automations/automations.service.ts
+++ b/apps/api/src/tasks/automations/automations.service.ts
@@ -87,12 +87,17 @@ export class AutomationsService {
       throw new NotFoundException('Automation not found');
     }
 
+    const { scheduleFrequency, ...rest } = updateAutomationDto;
+
     // Update the automation
     const automation = await db.evidenceAutomation.update({
       where: {
         id: automationId,
       },
-      data: updateAutomationDto,
+      data: {
+        ...rest,
+        ...(scheduleFrequency !== undefined ? { scheduleFrequency } : {}),
+      },
     });
 
     return {
diff --git a/apps/api/src/tasks/automations/dto/update-automation.dto.ts b/apps/api/src/tasks/automations/dto/update-automation.dto.ts
index 6c5e87ef47..96ce844067 100644
--- a/apps/api/src/tasks/automations/dto/update-automation.dto.ts
+++ b/apps/api/src/tasks/automations/dto/update-automation.dto.ts
@@ -1,5 +1,6 @@
-import { ApiProperty } from '@nestjs/swagger';
-import { IsString, IsOptional, IsBoolean } from 'class-validator';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { IsString, IsOptional, IsBoolean, IsEnum } from 'class-validator';
+import { TaskFrequency } from '@db';
 
 export class UpdateAutomationDto {
   @ApiProperty({
@@ -35,4 +36,12 @@ export class UpdateAutomationDto {
   @IsString()
   @IsOptional()
   evaluationCriteria?: string;
+
+  @ApiPropertyOptional({
+    enum: TaskFrequency,
+    description: 'Automation schedule cadence',
+  })
+  @IsEnum(TaskFrequency)
+  @IsOptional()
+  scheduleFrequency?: TaskFrequency;
 }
diff --git a/apps/api/src/tasks/dto/swagger.dto.ts b/apps/api/src/tasks/dto/swagger.dto.ts
index 19c73df0a5..76b21023ea 100644
--- a/apps/api/src/tasks/dto/swagger.dto.ts
+++ b/apps/api/src/tasks/dto/swagger.dto.ts
@@ -29,6 +29,14 @@ export class CreateTaskDto {
   })
   frequency?: string;
 
+  @ApiProperty({
+    description:
+      'Cadence for running the integration check attached to this task',
+    enum: ['daily', 'weekly', 'monthly', 'quarterly', 'yearly'],
+    required: false,
+  })
+  integrationScheduleFrequency?: string;
+
   @ApiProperty({
     description: 'Department assignment',
     enum: ['none', 'admin', 'gov', 'hr', 'it', 'itsm', 'qms'],
@@ -80,6 +88,14 @@ export class UpdateTaskDto {
   })
   frequency?: string;
 
+  @ApiProperty({
+    description:
+      'Cadence for running the integration check attached to this task',
+    enum: ['daily', 'weekly', 'monthly', 'quarterly', 'yearly'],
+    required: false,
+  })
+  integrationScheduleFrequency?: string;
+
   @ApiProperty({
     description: 'Department assignment',
     enum: ['none', 'admin', 'gov', 'hr', 'it', 'itsm', 'qms'],
@@ -172,6 +188,18 @@ export class TaskResponseDto {
   })
   frequency: string | null;
 
+  @ApiProperty({
+    description: 'Cadence for running the integration check attached to this task',
+    enum: ['daily', 'weekly', 'monthly', 'quarterly', 'yearly'],
+  })
+  integrationScheduleFrequency: string;
+
+  @ApiProperty({
+    description: 'Last successful integration check run timestamp',
+    nullable: true,
+  })
+  integrationLastRunAt: Date | null;
+
   @ApiProperty({
     description: 'Department assignment',
     enum: ['none', 'admin', 'gov', 'hr', 'it', 'itsm', 'qms'],
diff --git a/apps/api/src/tasks/dto/task-responses.dto.ts b/apps/api/src/tasks/dto/task-responses.dto.ts
index 3870fe3075..d80661ccf5 100644
--- a/apps/api/src/tasks/dto/task-responses.dto.ts
+++ b/apps/api/src/tasks/dto/task-responses.dto.ts
@@ -85,4 +85,18 @@ export class TaskResponseDto {
     required: false,
   })
   taskTemplateId?: string | null;
+
+  @ApiProperty({
+    description: 'Cadence for running the integration check attached to this task',
+    enum: ['daily', 'weekly', 'monthly', 'quarterly', 'yearly'],
+    example: 'daily',
+  })
+  integrationScheduleFrequency: string;
+
+  @ApiProperty({
+    description: 'Last successful integration check run timestamp',
+    nullable: true,
+    required: false,
+  })
+  integrationLastRunAt?: Date | null;
 }
diff --git a/apps/api/src/tasks/schemas/task.schemas.ts b/apps/api/src/tasks/schemas/task.schemas.ts
index 5380d90987..907a29ef45 100644
--- a/apps/api/src/tasks/schemas/task.schemas.ts
+++ b/apps/api/src/tasks/schemas/task.schemas.ts
@@ -30,6 +30,7 @@ export const CreateTaskSchema = z.object({
   description: z.string().min(1, 'Description is required'),
   status: TaskStatusSchema.optional().default('todo'),
   frequency: TaskFrequencySchema.optional(),
+  integrationScheduleFrequency: TaskFrequencySchema.optional(),
   department: DepartmentsSchema.optional().default('none'),
   order: z.number().int().min(0).optional().default(0),
   assigneeId: z.string().optional(),
diff --git a/apps/api/src/tasks/tasks.controller.ts b/apps/api/src/tasks/tasks.controller.ts
index 47984b0a99..61a4ae8e3b 100644
--- a/apps/api/src/tasks/tasks.controller.ts
+++ b/apps/api/src/tasks/tasks.controller.ts
@@ -712,6 +712,13 @@ export class TasksController {
           enum: ['daily', 'weekly', 'monthly', 'quarterly', 'yearly'],
           example: 'monthly',
         },
+        integrationScheduleFrequency: {
+          type: 'string',
+          enum: ['daily', 'weekly', 'monthly', 'quarterly', 'yearly'],
+          example: 'daily',
+          description:
+            'Cadence for running the integration check attached to this task',
+        },
         department: {
           type: 'string',
           enum: ['none', 'admin', 'gov', 'hr', 'it', 'itsm', 'qms'],
@@ -754,6 +761,7 @@ export class TasksController {
       assigneeId?: string | null;
       approverId?: string | null;
       frequency?: string;
+      integrationScheduleFrequency?: string;
       department?: string;
       reviewDate?: string;
     },
@@ -789,6 +797,9 @@ export class TasksController {
         assigneeId: body.assigneeId,
         approverId: body.approverId,
         frequency: body.frequency as TaskFrequency | undefined,
+        integrationScheduleFrequency: body.integrationScheduleFrequency as
+          | TaskFrequency
+          | undefined,
         department: body.department,
         reviewDate: parsedReviewDate,
       },
diff --git a/apps/api/src/tasks/tasks.service.ts b/apps/api/src/tasks/tasks.service.ts
index cc4fda1350..5a3e57d00c 100644
--- a/apps/api/src/tasks/tasks.service.ts
+++ b/apps/api/src/tasks/tasks.service.ts
@@ -532,8 +532,8 @@ export class TasksService {
         organizationId,
         timelinesService: this.timelinesService,
       }).catch((err) => {
-      this.logger.warn('timeline auto-complete check failed', err);
-    });
+        this.logger.warn('timeline auto-complete check failed', err);
+      });
 
       return { deletedCount: result.count };
     } catch (error) {
@@ -558,6 +558,7 @@ export class TasksService {
       assigneeId?: string | null;
       approverId?: string | null;
       frequency?: TaskFrequency;
+      integrationScheduleFrequency?: TaskFrequency;
       department?: string;
       reviewDate?: Date | null;
     },
@@ -592,6 +593,7 @@ export class TasksService {
         assigneeId?: string | null;
         approverId?: string | null;
         frequency?: TaskFrequency;
+        integrationScheduleFrequency?: TaskFrequency;
         department?: string;
         reviewDate?: Date | null;
       } = {};
@@ -651,6 +653,10 @@ export class TasksService {
           updateData.frequency,
         );
       }
+      if (updateData.integrationScheduleFrequency !== undefined) {
+        dataToUpdate.integrationScheduleFrequency =
+          updateData.integrationScheduleFrequency;
+      }
       if (updateData.department !== undefined) {
         dataToUpdate.department = updateData.department;
       }
@@ -879,6 +885,8 @@ export class TasksService {
         createdAt: task.createdAt,
         updatedAt: task.updatedAt,
         taskTemplateId: task.taskTemplateId,
+        integrationScheduleFrequency: task.integrationScheduleFrequency,
+        integrationLastRunAt: task.integrationLastRunAt,
       };
     } catch (error) {
       console.error('Error creating task:', error);
diff --git a/apps/api/src/trigger/browser-automation/run-browser-automation.ts b/apps/api/src/trigger/browser-automation/run-browser-automation.ts
index 5b9bb5a8c6..26b54945a2 100644
--- a/apps/api/src/trigger/browser-automation/run-browser-automation.ts
+++ b/apps/api/src/trigger/browser-automation/run-browser-automation.ts
@@ -292,6 +292,7 @@ export const runBrowserAutomation = task({
         runId: result.runId,
         error: result.error,
         needsReauth: result.needsReauth,
+        evaluationStatus: result.evaluationStatus,
       });
 
       // Mark task as failed if auth issue
@@ -325,6 +326,23 @@ export const runBrowserAutomation = task({
       }
     }
 
+    // Record a successful run on the automation so the orchestrator's
+    // schedule filter (`isDueToday`) can skip it on the next tick. "Executed"
+    // here means the automation actually ran — including runs whose evaluation
+    // legitimately returned `fail`. We skip the write when the automation
+    // genuinely couldn't execute (e.g. `needsReauth` / missing browser context
+    // / other transient infra errors) so the next orchestrator tick retries
+    // instead of waiting a full schedule period.
+    const executed =
+      result.success === true || result.evaluationStatus === 'fail';
+
+    if (executed) {
+      await db.browserAutomation.update({
+        where: { id: automationId },
+        data: { lastRunAt: new Date() },
+      });
+    }
+
     return {
       success: result.success,
       runId: result.runId,
diff --git a/apps/api/src/trigger/browser-automation/run-browser-automations-schedule.spec.ts b/apps/api/src/trigger/browser-automation/run-browser-automations-schedule.spec.ts
new file mode 100644
index 0000000000..2ae7fb5a7d
--- /dev/null
+++ b/apps/api/src/trigger/browser-automation/run-browser-automations-schedule.spec.ts
@@ -0,0 +1,118 @@
+import { TaskFrequency } from '@trycompai/db';
+import { filterDueAutomations } from './run-browser-automations-schedule';
+
+// Mock @db at the module boundary so importing the orchestrator does not try
+// to connect to Postgres. We never call the scheduled `run` function itself
+// (it's wrapped in `schedules.task({...})` and not independently invokable),
+// we only exercise the pure helper it uses.
+jest.mock('@db', () => ({
+  db: {
+    browserAutomation: { findMany: jest.fn(), update: jest.fn() },
+  },
+  TaskFrequency: {
+    daily: 'daily',
+    weekly: 'weekly',
+    monthly: 'monthly',
+    quarterly: 'quarterly',
+    yearly: 'yearly',
+  },
+}));
+
+jest.mock('@trigger.dev/sdk', () => ({
+  logger: { info: jest.fn(), warn: jest.fn(), error: jest.fn() },
+  schedules: {
+    task: (config: unknown) => config,
+  },
+}));
+
+jest.mock('./run-browser-automation', () => ({
+  runBrowserAutomation: { batchTrigger: jest.fn() },
+}));
+
+const atUtc = (iso: string) => new Date(`${iso}T00:00:00.000Z`);
+
+describe('filterDueAutomations (browser automation orchestrator)', () => {
+  const now = atUtc('2026-04-24');
+
+  it('returns only automations whose schedule says they are due', () => {
+    const candidateAutomations = [
+      // Daily → always due
+      {
+        id: 'ba_daily',
+        name: 'Daily login check',
+        taskId: 'tsk_a',
+        scheduleFrequency: TaskFrequency.daily,
+        lastRunAt: atUtc('2026-04-23'),
+      },
+      // Weekly, ran 3 days ago → NOT due
+      {
+        id: 'ba_weekly_recent',
+        name: 'Recent weekly',
+        taskId: 'tsk_b',
+        scheduleFrequency: TaskFrequency.weekly,
+        lastRunAt: atUtc('2026-04-21'),
+      },
+      // Weekly, ran 10 days ago → due
+      {
+        id: 'ba_weekly_stale',
+        name: 'Stale weekly',
+        taskId: 'tsk_c',
+        scheduleFrequency: TaskFrequency.weekly,
+        lastRunAt: atUtc('2026-04-14'),
+      },
+    ];
+
+    const due = filterDueAutomations({
+      automations: candidateAutomations,
+      now,
+    });
+
+    expect(due.map((a) => a.id)).toEqual(['ba_daily', 'ba_weekly_stale']);
+  });
+
+  it('treats a null lastRunAt as due (first run)', () => {
+    const candidateAutomations = [
+      {
+        id: 'ba_never_run',
+        name: 'Never run',
+        taskId: 'tsk_a',
+        scheduleFrequency: TaskFrequency.weekly,
+        lastRunAt: null as Date | null,
+      },
+    ];
+
+    const due = filterDueAutomations({
+      automations: candidateAutomations,
+      now,
+    });
+
+    expect(due).toHaveLength(1);
+    expect(due[0]?.id).toBe('ba_never_run');
+  });
+
+  it('returns an empty array when nothing is due', () => {
+    const candidateAutomations = [
+      {
+        id: 'ba_monthly_recent',
+        name: 'Recent monthly',
+        taskId: 'tsk_a',
+        scheduleFrequency: TaskFrequency.monthly,
+        lastRunAt: atUtc('2026-04-10'),
+      },
+      {
+        id: 'ba_quarterly_recent',
+        name: 'Recent quarterly',
+        taskId: 'tsk_b',
+        scheduleFrequency: TaskFrequency.quarterly,
+        lastRunAt: atUtc('2026-03-01'),
+      },
+    ];
+
+    const due = filterDueAutomations({
+      automations: candidateAutomations,
+      now,
+    });
+
+    expect(due).toEqual([]);
+  });
+});
diff --git a/apps/api/src/trigger/browser-automation/run-browser-automations-schedule.ts b/apps/api/src/trigger/browser-automation/run-browser-automations-schedule.ts
index 429a6260ab..dedd4b5660 100644
--- a/apps/api/src/trigger/browser-automation/run-browser-automations-schedule.ts
+++ b/apps/api/src/trigger/browser-automation/run-browser-automations-schedule.ts
@@ -1,6 +1,29 @@
-import { db } from '@db';
+import { db, TaskFrequency } from '@db';
 import { logger, schedules } from '@trigger.dev/sdk';
 import { runBrowserAutomation } from './run-browser-automation';
+import { isDueToday } from '../shared/is-due-today';
+
+/**
+ * Pure helper extracted for unit testing. Filters a list of candidate
+ * automations down to those whose schedule says they are due at `now`.
+ *
+ * Kept in-memory (Shape A from the plan) because the single source of truth
+ * for schedule math is `isDueToday`; duplicating it in SQL would create drift.
+ */
+export function filterDueAutomations<
+  T extends {
+    scheduleFrequency: TaskFrequency;
+    lastRunAt: Date | null;
+  },
+>({ automations, now }: { automations: T[]; now: Date }): T[] {
+  return automations.filter((a) =>
+    isDueToday({
+      scheduleFrequency: a.scheduleFrequency,
+      lastRunAt: a.lastRunAt,
+      now,
+    }),
+  );
+}
 
 /**
  * Daily scheduled task (orchestrator) that finds all enabled browser automations
@@ -16,10 +39,17 @@ export const browserAutomationsSchedule = schedules.task({
       lastRun: payload.lastTimestamp,
     });
 
+    const now = new Date();
+
     // Find all enabled browser automations
-    const automations = await db.browserAutomation.findMany({
+    const candidateAutomations = await db.browserAutomation.findMany({
       where: { isEnabled: true },
-      include: {
+      select: {
+        id: true,
+        name: true,
+        taskId: true,
+        scheduleFrequency: true,
+        lastRunAt: true,
         task: {
           select: {
             id: true,
@@ -30,12 +60,34 @@ export const browserAutomationsSchedule = schedules.task({
       },
     });
 
-    if (automations.length === 0) {
+    if (candidateAutomations.length === 0) {
       logger.info('No enabled browser automations found');
       return { success: true, automationsTriggered: 0 };
     }
 
-    logger.info(`Found ${automations.length} enabled browser automations`);
+    logger.info(
+      `Found ${candidateAutomations.length} enabled browser automations`,
+    );
+
+    // Filter by the automation's schedule. `lastRunAt` is only written when
+    // the automation actually executed (including legitimate 'fail' verdicts)
+    // inside `runBrowserAutomation`, so infra-level failures naturally retry
+    // on the next orchestrator tick (the "crude retry" behavior).
+    const automations = filterDueAutomations({
+      automations: candidateAutomations,
+      now,
+    });
+
+    if (automations.length < candidateAutomations.length) {
+      logger.info(
+        `Skipped ${candidateAutomations.length - automations.length} automation(s) not due yet`,
+      );
+    }
+
+    if (automations.length === 0) {
+      logger.info('No browser automations due today');
+      return { success: true, automationsTriggered: 0 };
+    }
 
     // Build payloads for batch triggering
     const triggerPayloads = automations.map((automation) => ({
diff --git a/apps/api/src/trigger/integration-platform/run-integration-checks-schedule.spec.ts b/apps/api/src/trigger/integration-platform/run-integration-checks-schedule.spec.ts
new file mode 100644
index 0000000000..9343a609c9
--- /dev/null
+++ b/apps/api/src/trigger/integration-platform/run-integration-checks-schedule.spec.ts
@@ -0,0 +1,117 @@
+import { TaskFrequency } from '@trycompai/db';
+import { filterDueTasks } from './run-integration-checks-schedule';
+
+// Mock @db at the module boundary so importing the orchestrator does not try
+// to connect to Postgres. We never call the scheduled `run` function itself
+// (it's wrapped in `schedules.task({...})` and not independently invokable),
+// we only exercise the pure helper it uses.
+jest.mock('@db', () => ({
+  db: {
+    integrationConnection: { findMany: jest.fn() },
+    task: { findMany: jest.fn(), update: jest.fn() },
+  },
+  TaskFrequency: {
+    daily: 'daily',
+    weekly: 'weekly',
+    monthly: 'monthly',
+    quarterly: 'quarterly',
+    yearly: 'yearly',
+  },
+}));
+
+jest.mock('@trycompai/integration-platform', () => ({
+  getManifest: jest.fn(),
+}));
+
+jest.mock('@trigger.dev/sdk', () => ({
+  logger: { info: jest.fn(), warn: jest.fn(), error: jest.fn() },
+  schedules: {
+    task: (config: unknown) => config,
+  },
+}));
+
+jest.mock('./run-task-integration-checks', () => ({
+  runTaskIntegrationChecks: { batchTrigger: jest.fn() },
+}));
+
+const atUtc = (iso: string) => new Date(`${iso}T00:00:00.000Z`);
+
+describe('filterDueTasks (integration orchestrator)', () => {
+  const now = atUtc('2026-04-24');
+
+  it('returns only tasks whose schedule says they are due', () => {
+    const candidateTasks = [
+      // Daily → always due
+      {
+        id: 'tsk_daily',
+        title: 'Daily check',
+        taskTemplateId: 'tpl_a',
+        integrationScheduleFrequency: TaskFrequency.daily,
+        integrationLastRunAt: atUtc('2026-04-23'),
+      },
+      // Weekly, ran 2 days ago → NOT due
+      {
+        id: 'tsk_weekly_recent',
+        title: 'Recent weekly',
+        taskTemplateId: 'tpl_b',
+        integrationScheduleFrequency: TaskFrequency.weekly,
+        integrationLastRunAt: atUtc('2026-04-22'),
+      },
+      // Weekly, ran 10 days ago → due
+      {
+        id: 'tsk_weekly_stale',
+        title: 'Stale weekly',
+        taskTemplateId: 'tpl_c',
+        integrationScheduleFrequency: TaskFrequency.weekly,
+        integrationLastRunAt: atUtc('2026-04-14'),
+      },
+    ];
+
+    const dueTasks = filterDueTasks({ tasks: candidateTasks, now });
+
+    expect(dueTasks.map((t) => t.id)).toEqual([
+      'tsk_daily',
+      'tsk_weekly_stale',
+    ]);
+  });
+
+  it('treats a null integrationLastRunAt as due (first run)', () => {
+    const candidateTasks = [
+      {
+        id: 'tsk_never_run',
+        title: 'Never run',
+        taskTemplateId: 'tpl_a',
+        integrationScheduleFrequency: TaskFrequency.yearly,
+        integrationLastRunAt: null as Date | null,
+      },
+    ];
+
+    const dueTasks = filterDueTasks({ tasks: candidateTasks, now });
+
+    expect(dueTasks).toHaveLength(1);
+    expect(dueTasks[0]?.id).toBe('tsk_never_run');
+  });
+
+  it('returns an empty array when nothing is due', () => {
+    const candidateTasks = [
+      {
+        id: 'tsk_monthly_recent',
+        title: 'Recent monthly',
+        taskTemplateId: 'tpl_a',
+        integrationScheduleFrequency: TaskFrequency.monthly,
+        integrationLastRunAt: atUtc('2026-04-10'),
+      },
+      {
+        id: 'tsk_quarterly_recent',
+        title: 'Recent quarterly',
+        taskTemplateId: 'tpl_b',
+        integrationScheduleFrequency: TaskFrequency.quarterly,
+        integrationLastRunAt: atUtc('2026-03-01'),
+      },
+    ];
+
+    const dueTasks = filterDueTasks({ tasks: candidateTasks, now });
+
+    expect(dueTasks).toEqual([]);
+  });
+});
diff --git a/apps/api/src/trigger/integration-platform/run-integration-checks-schedule.ts b/apps/api/src/trigger/integration-platform/run-integration-checks-schedule.ts
index 0a80d22fa6..600e03ef94 100644
--- a/apps/api/src/trigger/integration-platform/run-integration-checks-schedule.ts
+++ b/apps/api/src/trigger/integration-platform/run-integration-checks-schedule.ts
@@ -1,8 +1,31 @@
 import { getManifest } from '@trycompai/integration-platform';
-import { db } from '@db';
+import { db, TaskFrequency } from '@db';
 import { logger, schedules } from '@trigger.dev/sdk';
 import { runTaskIntegrationChecks } from './run-task-integration-checks';
 import { parseDisabledTaskChecks } from '../../integration-platform/utils/disabled-task-checks';
+import { isDueToday } from '../shared/is-due-today';
+
+/**
+ * Pure helper extracted for unit testing. Filters a list of candidate tasks
+ * down to those whose schedule says they are due at `now`.
+ *
+ * Kept in-memory (Shape A from the plan) because the single source of truth
+ * for schedule math is `isDueToday`; duplicating it in SQL would create drift.
+ */
+export function filterDueTasks<
+  T extends {
+    integrationScheduleFrequency: TaskFrequency;
+    integrationLastRunAt: Date | null;
+  },
+>({ tasks, now }: { tasks: T[]; now: Date }): T[] {
+  return tasks.filter((t) =>
+    isDueToday({
+      scheduleFrequency: t.integrationScheduleFrequency,
+      lastRunAt: t.integrationLastRunAt,
+      now,
+    }),
+  );
+}
 
 /**
  * Daily scheduled task (orchestrator) that finds all tasks with integration checks
@@ -18,6 +41,8 @@ export const integrationChecksSchedule = schedules.task({
       lastRun: payload.lastTimestamp,
     });
 
+    const now = new Date();
+
     // Get all active integration connections
     const activeConnections = await db.integrationConnection.findMany({
       where: { status: 'active' },
@@ -63,7 +88,7 @@ export const integrationChecksSchedule = schedules.task({
       }
 
       // Find tasks in this org that match these templates
-      const tasks = await db.task.findMany({
+      const candidateTasks = await db.task.findMany({
         where: {
           organizationId: connection.organizationId,
           taskTemplateId: { in: taskTemplateIds as string[] },
@@ -72,9 +97,22 @@ export const integrationChecksSchedule = schedules.task({
           id: true,
           title: true,
           taskTemplateId: true,
+          integrationScheduleFrequency: true,
+          integrationLastRunAt: true,
         },
       });
 
+      // Filter by the task's integration schedule. `lastRunAt` is only written
+      // on success inside `runTaskIntegrationChecks`, so failures naturally
+      // retry on the next orchestrator tick (the "crude retry" behavior).
+      const tasks = filterDueTasks({ tasks: candidateTasks, now });
+
+      if (tasks.length < candidateTasks.length) {
+        logger.info(
+          `Skipped ${candidateTasks.length - tasks.length} task(s) not due yet for connection ${connection.id}`,
+        );
+      }
+
       // Per-task disabled checks are stored on the connection's metadata so
       // users can disconnect individual checks from individual tasks without
       // tearing down the whole integration. Resolve once per connection.
diff --git a/apps/api/src/trigger/integration-platform/run-task-integration-checks.ts b/apps/api/src/trigger/integration-platform/run-task-integration-checks.ts
index 57aef35305..e2c4b404a5 100644
--- a/apps/api/src/trigger/integration-platform/run-task-integration-checks.ts
+++ b/apps/api/src/trigger/integration-platform/run-task-integration-checks.ts
@@ -319,6 +319,7 @@ export const runTaskIntegrationChecks = task({
     let totalFindings = 0;
     let totalPassing = 0;
     let hasFailedChecks = false;
+    let hasExecutionErrors = false;
 
     // Run only the checks that apply to this task
     try {
@@ -347,6 +348,9 @@ export const runTaskIntegrationChecks = task({
         if (checkResult.status === 'failed' || checkResult.status === 'error') {
           hasFailedChecks = true;
         }
+        if (checkResult.status === 'error') {
+          hasExecutionErrors = true;
+        }
 
         // Store check run
         const checkRun = await db.integrationCheckRun.create({
@@ -415,6 +419,19 @@ export const runTaskIntegrationChecks = task({
         data: { lastSyncAt: new Date() },
       });
 
+      // Record a successful run on the task so the orchestrator's schedule
+      // filter (`isDueToday`) can skip it on the next tick. "Successful" here
+      // means every check executed — including checks that legitimately found
+      // violations (`status: 'failed'`). We skip the write only when a check
+      // couldn't execute (`status: 'error'`, e.g. transient provider error),
+      // so the next orchestrator tick retries instead of waiting a full period.
+      if (!hasExecutionErrors) {
+        await db.task.update({
+          where: { id: taskId },
+          data: { integrationLastRunAt: new Date() },
+        });
+      }
+
       // Update task status based on check results
       // If any findings or check failures, mark as failed
       // If all checks pass with no findings, mark as done (only if not already done)
diff --git a/apps/api/src/trigger/shared/is-due-today.spec.ts b/apps/api/src/trigger/shared/is-due-today.spec.ts
new file mode 100644
index 0000000000..3920031e2c
--- /dev/null
+++ b/apps/api/src/trigger/shared/is-due-today.spec.ts
@@ -0,0 +1,141 @@
+import { TaskFrequency } from '@trycompai/db';
+import { isDueToday } from './is-due-today';
+
+const atUtc = (iso: string) => new Date(`${iso}T00:00:00.000Z`);
+
+describe('isDueToday', () => {
+  const now = atUtc('2026-04-24');
+
+  describe('daily', () => {
+    it('returns true when lastRunAt is null', () => {
+      expect(
+        isDueToday({
+          scheduleFrequency: TaskFrequency.daily,
+          lastRunAt: null,
+          now,
+        }),
+      ).toBe(true);
+    });
+    it('returns true even when it ran today', () => {
+      expect(
+        isDueToday({
+          scheduleFrequency: TaskFrequency.daily,
+          lastRunAt: atUtc('2026-04-24'),
+          now,
+        }),
+      ).toBe(true);
+    });
+  });
+
+  describe('weekly', () => {
+    it('returns true when lastRunAt is null', () => {
+      expect(
+        isDueToday({
+          scheduleFrequency: TaskFrequency.weekly,
+          lastRunAt: null,
+          now,
+        }),
+      ).toBe(true);
+    });
+    it('returns false when lastRunAt is 6 days ago', () => {
+      expect(
+        isDueToday({
+          scheduleFrequency: TaskFrequency.weekly,
+          lastRunAt: atUtc('2026-04-18'),
+          now,
+        }),
+      ).toBe(false);
+    });
+    it('returns true when lastRunAt is exactly 7 days ago', () => {
+      expect(
+        isDueToday({
+          scheduleFrequency: TaskFrequency.weekly,
+          lastRunAt: atUtc('2026-04-17'),
+          now,
+        }),
+      ).toBe(true);
+    });
+    it('returns true when lastRunAt is 14 days ago', () => {
+      expect(
+        isDueToday({
+          scheduleFrequency: TaskFrequency.weekly,
+          lastRunAt: atUtc('2026-04-10'),
+          now,
+        }),
+      ).toBe(true);
+    });
+  });
+
+  describe('monthly', () => {
+    it('returns true when lastRunAt crossed a calendar-month boundary', () => {
+      // 2026-03-26 → 2026-04-24: different calendar month → due
+      expect(
+        isDueToday({
+          scheduleFrequency: TaskFrequency.monthly,
+          lastRunAt: atUtc('2026-03-26'),
+          now,
+        }),
+      ).toBe(true);
+    });
+    it('returns false when lastRunAt is same calendar month', () => {
+      expect(
+        isDueToday({
+          scheduleFrequency: TaskFrequency.monthly,
+          lastRunAt: atUtc('2026-04-01'),
+          now,
+        }),
+      ).toBe(false);
+    });
+    it('returns true when lastRunAt is null', () => {
+      expect(
+        isDueToday({
+          scheduleFrequency: TaskFrequency.monthly,
+          lastRunAt: null,
+          now,
+        }),
+      ).toBe(true);
+    });
+  });
+
+  describe('quarterly', () => {
+    it('returns false when lastRunAt is 2 months ago', () => {
+      expect(
+        isDueToday({
+          scheduleFrequency: TaskFrequency.quarterly,
+          lastRunAt: atUtc('2026-02-24'),
+          now,
+        }),
+      ).toBe(false);
+    });
+    it('returns true when lastRunAt is 3 months ago', () => {
+      expect(
+        isDueToday({
+          scheduleFrequency: TaskFrequency.quarterly,
+          lastRunAt: atUtc('2026-01-24'),
+          now,
+        }),
+      ).toBe(true);
+    });
+  });
+
+  describe('yearly', () => {
+    it('returns false when lastRunAt is 11 months ago', () => {
+      expect(
+        isDueToday({
+          scheduleFrequency: TaskFrequency.yearly,
+          lastRunAt: atUtc('2025-05-24'),
+          now,
+        }),
+      ).toBe(false);
+    });
+    it('returns true when lastRunAt is 12 months ago', () => {
+      expect(
+        isDueToday({
+          scheduleFrequency: TaskFrequency.yearly,
+          lastRunAt: atUtc('2025-04-24'),
+          now,
+        }),
+      ).toBe(true);
+    });
+  });
+});
diff --git a/apps/api/src/trigger/shared/is-due-today.ts b/apps/api/src/trigger/shared/is-due-today.ts
new file mode 100644
index 0000000000..c38008311d
--- /dev/null
+++ b/apps/api/src/trigger/shared/is-due-today.ts
@@ -0,0 +1,51 @@
+import { TaskFrequency } from '@trycompai/db';
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+function calendarMonthsBetween(earlier: Date, later: Date): number {
+  const years = later.getUTCFullYear() - earlier.getUTCFullYear();
+  const months = later.getUTCMonth() - earlier.getUTCMonth();
+  return years * 12 + months;
+}
+
+/**
+ * Returns whether an automation with the given schedule is due to run at `now`.
+ *
+ * `now` and `lastRunAt` are treated as UTC instants — weekly math uses fixed
+ * 86_400_000-ms days, monthly/quarterly/yearly use UTC calendar buckets. Callers
+ * should pass real `Date` values (any instant works); do NOT pass "midnight in
+ * local time" expecting DST-aware behavior.
+ *
+ * `null` lastRunAt always returns `true` (first run).
+ */
+export function isDueToday({
+  scheduleFrequency,
+  lastRunAt,
+  now,
+}: {
+  scheduleFrequency: TaskFrequency;
+  lastRunAt: Date | null;
+  now: Date;
+}): boolean {
+  if (scheduleFrequency === TaskFrequency.daily) return true;
+  if (lastRunAt === null) return true;
+
+  switch (scheduleFrequency) {
+    case TaskFrequency.weekly: {
+      const days = Math.floor(
+        (now.getTime() - lastRunAt.getTime()) / MS_PER_DAY,
+      );
+      return days >= 7;
+    }
+    case TaskFrequency.monthly:
+      return calendarMonthsBetween(lastRunAt, now) >= 1;
+    case TaskFrequency.quarterly:
+      return calendarMonthsBetween(lastRunAt, now) >= 3;
+    case TaskFrequency.yearly:
+      return calendarMonthsBetween(lastRunAt, now) >= 12;
+    default: {
+      const _exhaustive: never = scheduleFrequency;
+      throw new Error(`Unhandled TaskFrequency: ${String(_exhaustive)}`);
+    }
+  }
+}
diff --git a/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/automation/[automationId]/hooks/use-task-automation.ts b/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/automation/[automationId]/hooks/use-task-automation.ts
index bf4bf7b43e..45bb3d6958 100644
--- a/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/automation/[automationId]/hooks/use-task-automation.ts
+++ b/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/automation/[automationId]/hooks/use-task-automation.ts
@@ -1,4 +1,5 @@
 import { api } from '@/lib/api-client';
+import type { TaskFrequency } from '@db';
 import { useParams } from 'next/navigation';
 import useSWR from 'swr';
 
@@ -13,15 +14,21 @@ interface TaskAutomationData {
   updatedAt: string;
   evaluationCriteria?: string;
   isEnabled: boolean;
+  scheduleFrequency?: TaskFrequency;
+  lastRunAt?: string | null;
 }
 
+type UpdateAutomationPayload = Partial<
+  Pick<TaskAutomationData, 'name' | 'description' | 'scheduleFrequency'>
+>;
+
 interface UseTaskAutomationReturn {
   automation: TaskAutomationData | undefined;
   isLoading: boolean;
   isError: boolean;
   error: Error | undefined;
   mutate: () => Promise<unknown>;
-  updateAutomation: (body: Partial<Pick<TaskAutomationData, 'name' | 'description'>>) => Promise<void>;
+  updateAutomation: (body: UpdateAutomationPayload) => Promise<void>;
   deleteAutomation: () => Promise<void>;
 }
 
@@ -71,9 +78,7 @@ export function useTaskAutomation(overrideAutomationId?: string): UseTaskAutomat
     },
   );
 
-  const updateAutomation = async (
-    body: Partial<Pick<TaskAutomationData, 'name' | 'description'>>,
-  ) => {
+  const updateAutomation = async (body: UpdateAutomationPayload) => {
     const realId = data?.id || automationId;
     const response = await api.patch(
       `/v1/tasks/${taskId}/automations/${realId}`,
diff --git a/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/automations/[automationId]/overview/components/AutomationOverview.tsx b/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/automations/[automationId]/overview/components/AutomationOverview.tsx
index 7802a16024..329135a712 100644
--- a/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/automations/[automationId]/overview/components/AutomationOverview.tsx
+++ b/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/automations/[automationId]/overview/components/AutomationOverview.tsx
@@ -3,7 +3,13 @@
 import { RecentAuditLogs } from '@/components/RecentAuditLogs';
 import { useAuditLogs } from '@/hooks/use-audit-logs';
 import { Button } from '@trycompai/ui/button';
-import type { EvidenceAutomation, EvidenceAutomationRun, EvidenceAutomationVersion, Task } from '@db';
+import type {
+  EvidenceAutomation,
+  EvidenceAutomationRun,
+  EvidenceAutomationVersion,
+  Task,
+  TaskFrequency,
+} from '@db';
 import {
   Breadcrumb,
   Button as DSButton,
@@ -28,6 +34,7 @@ import {
   toggleAutomationEnabled,
 } from '../../../../automation/[automationId]/actions/task-automation-actions';
 import { DeleteAutomationDialog } from '../../../../automation/[automationId]/components/AutomationSettingsDialogs';
+import { SchedulePicker } from '@/components/schedule-picker';
 import { useTaskAutomation } from '../../../../automation/[automationId]/hooks/use-task-automation';
 import { AutomationRunsCard } from '../../../../components/AutomationRunsCard';
 import { useAutomationRuns } from '../hooks/use-automation-runs';
@@ -57,6 +64,7 @@ export function AutomationOverview({
   }>();
 
   const [deleteDialogOpen, setDeleteDialogOpen] = useState(false);
+  const [isUpdatingSchedule, setIsUpdatingSchedule] = useState(false);
   const [isTogglingEnabled, setIsTogglingEnabled] = useState(false);
   const [isEditingName, setIsEditingName] = useState(false);
   const [nameValue, setNameValue] = useState('');
@@ -136,6 +144,19 @@ export function AutomationOverview({
     }
   };
 
+  const handleScheduleChange = async (value: TaskFrequency) => {
+    setIsUpdatingSchedule(true);
+    try {
+      await updateAutomation({ scheduleFrequency: value });
+      toast.success('Schedule updated');
+      await mutateAutomation();
+    } catch {
+      toast.error('Failed to update schedule');
+    } finally {
+      setIsUpdatingSchedule(false);
+    }
+  };
+
   const handleTestVersion = async () => {
     if (!selectedVersion) return;
     setIsTestingVersion(true);
@@ -272,6 +293,8 @@ export function AutomationOverview({
       <MetricsSection
         initialVersions={initialVersions}
         initialRuns={runs}
+        scheduleFrequency={automation.scheduleFrequency ?? 'daily'}
+        lastRunAt={automation.lastRunAt ?? null}
       />
 
       <Tabs defaultValue="history">
@@ -372,6 +395,24 @@ export function AutomationOverview({
 
                 <div className="border-t" />
 
+                <HStack justify="between" align="center">
+                  <Stack gap="none">
+                    <Text size="sm" weight="medium">Schedule</Text>
+                    <Text size="xs" variant="muted">
+                      How often this automation runs
+                    </Text>
+                  </Stack>
+                  <div className="w-40">
+                    <SchedulePicker
+                      value={automation.scheduleFrequency ?? 'daily'}
+                      onChange={handleScheduleChange}
+                      disabled={isUpdatingSchedule}
+                    />
+                  </div>
+                </HStack>
+
+                <div className="border-t" />
+
                 <HStack justify="between" align="center">
                   <Stack gap="none">
                     <Text size="sm" weight="medium">Delete Automation</Text>
@@ -400,6 +441,7 @@ export function AutomationOverview({
         onOpenChange={setDeleteDialogOpen}
         onSuccess={mutateAutomation}
       />
+
     </PageLayout>
   );
 }
diff --git a/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/automations/[automationId]/overview/components/MetricsSection.test.tsx b/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/automations/[automationId]/overview/components/MetricsSection.test.tsx
index 805db6a275..578927f1b3 100644
--- a/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/automations/[automationId]/overview/components/MetricsSection.test.tsx
+++ b/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/automations/[automationId]/overview/components/MetricsSection.test.tsx
@@ -2,7 +2,7 @@ import { render, screen } from '@testing-library/react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { MetricsSection } from './MetricsSection';
 
-describe('MetricsSection (CS-97)', () => {
+describe('MetricsSection (SALE-49)', () => {
   beforeEach(() => {
     // shouldAdvanceTime lets React effects flush on their normal tick
     // while still letting us pin `new Date()` with vi.setSystemTime.
@@ -13,88 +13,114 @@ describe('MetricsSection (CS-97)', () => {
     vi.useRealTimers();
   });
 
-  it('labels the schedule as 9:00 AM UTC (no ambiguous local time)', () => {
-    vi.setSystemTime(new Date('2026-04-16T07:00:00Z'));
-    render(<MetricsSection initialVersions={[]} initialRuns={[]} />);
-    expect(screen.getByText('Every day at 9:00 AM UTC')).toBeInTheDocument();
-  });
-
-  it('uses an SSR-safe placeholder for the next run (defers date formatting to post-mount)', () => {
-    // Verify the initial JSX does NOT synchronously format a Date — that's
-    // the property that keeps SSR and hydration outputs identical. We
-    // simulate "server-side" rendering with renderToString and assert the
-    // Next Run cell specifically contains the em-dash placeholder rather
-    // than a formatted weekday/time. We scope the assertion to the Next Run
-    // card because Success Rate also renders `—` when there are no runs.
+  it('uses an SSR-safe placeholder for schedule + next run (defers date formatting to post-mount)', () => {
     const { renderToString } = require('react-dom/server') as typeof import('react-dom/server');
     vi.setSystemTime(new Date('2026-04-16T07:00:00Z'));
     const html = renderToString(
-      <MetricsSection initialVersions={[]} initialRuns={[]} />,
+      <MetricsSection
+        initialVersions={[]}
+        initialRuns={[]}
+        scheduleFrequency="daily"
+        lastRunAt={null}
+      />,
     );
 
-    // No weekday should appear anywhere in SSR output.
+    // No weekday and no UTC literal in SSR output — defers locale-dependent
+    // formatting to the client-only effect.
     expect(html).not.toMatch(/Mon|Tue|Wed|Thu|Fri|Sat|Sun/);
+    expect(html).not.toMatch(/UTC/);
 
-    // Locate the Next Run cell and assert its value paragraph contains `—`.
-    // Matches: <p ...>Next Run</p><p class="...">—</p>
-    const nextRunCellMatch = html.match(
-      /Next Run[^<]*<\/p>\s*<p[^>]*>([^<]*)<\/p>/,
-    );
-    expect(nextRunCellMatch).not.toBeNull();
-    expect(nextRunCellMatch?.[1]).toBe('—');
+    // Both Schedule and Next Run cells should show the em-dash placeholder.
+    const scheduleCell = html.match(/Schedule[^<]*<\/p>\s*<p[^>]*>([^<]*)<\/p>/);
+    const nextRunCell = html.match(/Next Run[^<]*<\/p>\s*<p[^>]*>([^<]*)<\/p>/);
+    expect(scheduleCell?.[1]).toBe('—');
+    expect(nextRunCell?.[1]).toBe('—');
   });
 
-  it('fills in the next-run label after mount with a concrete weekday, time, and timezone', async () => {
+  it('labels the daily schedule with the user\'s timezone (not UTC)', async () => {
     vi.setSystemTime(new Date('2026-04-16T07:00:00Z'));
-    render(<MetricsSection initialVersions={[]} initialRuns={[]} />);
+    render(
+      <MetricsSection
+        initialVersions={[]}
+        initialRuns={[]}
+        scheduleFrequency="daily"
+        lastRunAt={null}
+      />,
+    );
 
-    // Old hardcoded literals must never appear.
-    expect(screen.queryByText('Every Day 9:00 AM')).not.toBeInTheDocument();
-    expect(screen.queryByText('Tomorrow 9:00 AM')).not.toBeInTheDocument();
+    // After mount: "Every day at <time> <TZ>". Time is locale-formatted, so
+    // we assert the recurring prefix and a timezone abbreviation; we don't
+    // pin the literal time because it depends on the test runner's TZ.
+    const label = await screen.findByText(/^Every day at \d{1,2}:\d{2}\s(AM|PM)\s\S+/);
+    expect(label).toBeInTheDocument();
+    expect(label.textContent).not.toMatch(/\bUTC\b/);
+  });
 
-    // After mount the effect runs and the real label shows up. It must
-    // include an explicit timezone so it's not confused with the UTC
-    // Schedule card next to it — e.g. "Thu 9:00 AM UTC" or "Thu, 12:00 PM EST".
-    // Node/browser locales may insert a comma after the weekday; allow both.
-    const nextRunLabels = await screen.findAllByText(
-      /^(Mon|Tue|Wed|Thu|Fri|Sat|Sun),?\s\d{1,2}:\d{2}\s(AM|PM)\s.+/,
+  it('updates the schedule label when the frequency changes', async () => {
+    vi.setSystemTime(new Date('2026-04-16T07:00:00Z'));
+    const { rerender } = render(
+      <MetricsSection
+        initialVersions={[]}
+        initialRuns={[]}
+        scheduleFrequency="daily"
+        lastRunAt={null}
+      />,
     );
-    expect(nextRunLabels.length).toBeGreaterThan(0);
+    expect(await screen.findByText(/^Every day at /)).toBeInTheDocument();
+
+    rerender(
+      <MetricsSection
+        initialVersions={[]}
+        initialRuns={[]}
+        scheduleFrequency="weekly"
+        lastRunAt={null}
+      />,
+    );
+    expect(await screen.findByText(/^Every week at /)).toBeInTheDocument();
+    expect(screen.queryByText(/^Every day at /)).not.toBeInTheDocument();
   });
 
-  it('picks today (UTC) when the current time is before 09:00 UTC', async () => {
-    // 2026-04-16 07:00 UTC → next run is 2026-04-16 09:00 UTC (same day).
+  it('renders concrete weekday + date + timezone for next run after mount', async () => {
     vi.setSystemTime(new Date('2026-04-16T07:00:00Z'));
-    render(<MetricsSection initialVersions={[]} initialRuns={[]} />);
+    render(
+      <MetricsSection
+        initialVersions={[]}
+        initialRuns={[]}
+        scheduleFrequency="daily"
+        lastRunAt={null}
+      />,
+    );
 
-    const expected = new Date('2026-04-16T09:00:00Z').toLocaleString(
-      undefined,
-      {
-        weekday: 'short',
-        hour: 'numeric',
-        minute: '2-digit',
-        hour12: true,
-        timeZoneName: 'short',
-      },
+    // Format: "Thu, Apr 16, 9:00 AM <TZ>" — must include a timezone short name
+    // so the user isn't left guessing the offset.
+    const nextRunLabels = await screen.findAllByText(
+      /^(Mon|Tue|Wed|Thu|Fri|Sat|Sun),?\s\w+\s\d{1,2},?\s\d{1,2}:\d{2}\s(AM|PM)\s\S+/,
     );
-    expect(await screen.findByText(expected)).toBeInTheDocument();
+    expect(nextRunLabels.length).toBeGreaterThan(0);
   });
 
-  it('picks the next day (UTC) when the current time is past 09:00 UTC', async () => {
-    // 2026-04-16 10:00 UTC → today's run already happened, next is 2026-04-17 09:00 UTC.
-    vi.setSystemTime(new Date('2026-04-16T10:00:00Z'));
-    render(<MetricsSection initialVersions={[]} initialRuns={[]} />);
-
-    const expected = new Date('2026-04-17T09:00:00Z').toLocaleString(
-      undefined,
-      {
-        weekday: 'short',
-        hour: 'numeric',
-        minute: '2-digit',
-        hour12: true,
-        timeZoneName: 'short',
-      },
+  it('pushes the next run forward by 7 days when frequency is weekly with a recent lastRunAt', async () => {
+    // 2026-04-16 07:00 UTC. lastRunAt was today. Weekly → next run ~7 days later.
+    vi.setSystemTime(new Date('2026-04-16T07:00:00Z'));
+    render(
+      <MetricsSection
+        initialVersions={[]}
+        initialRuns={[]}
+        scheduleFrequency="weekly"
+        lastRunAt={new Date('2026-04-16T09:00:00Z')}
+      />,
     );
-    expect(await screen.findByText(expected)).toBeInTheDocument();
+
+    // 2026-04-23 (Thursday)
+    const expectedDate = new Date('2026-04-23T09:00:00Z').toLocaleString(undefined, {
+      weekday: 'short',
+      month: 'short',
+      day: 'numeric',
+      hour: 'numeric',
+      minute: '2-digit',
+      hour12: true,
+      timeZoneName: 'short',
+    });
+    expect(await screen.findByText(expectedDate)).toBeInTheDocument();
   });
 });
diff --git a/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/automations/[automationId]/overview/components/MetricsSection.tsx b/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/automations/[automationId]/overview/components/MetricsSection.tsx
index 2d85e4871d..442bb73945 100644
--- a/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/automations/[automationId]/overview/components/MetricsSection.tsx
+++ b/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/automations/[automationId]/overview/components/MetricsSection.tsx
@@ -1,16 +1,70 @@
 'use client';
 
-import type { EvidenceAutomationRun, EvidenceAutomationVersion } from '@db';
+import type { EvidenceAutomationRun, EvidenceAutomationVersion, TaskFrequency } from '@db';
 import { useEffect, useMemo, useState } from 'react';
 
 interface MetricsSectionProps {
   initialVersions: EvidenceAutomationVersion[];
   initialRuns: EvidenceAutomationRun[];
+  scheduleFrequency: TaskFrequency;
+  lastRunAt: Date | string | null;
+}
+
+const FREQUENCY_DESCRIPTIONS: Record<TaskFrequency, string> = {
+  daily: 'Every day',
+  weekly: 'Every week',
+  monthly: 'Every month',
+  quarterly: 'Every quarter',
+  yearly: 'Every year',
+};
+
+const PERIOD_DAYS: Record<TaskFrequency, number> = {
+  daily: 1,
+  weekly: 7,
+  monthly: 30,
+  quarterly: 91,
+  yearly: 365,
+};
+
+// The orchestrator fires daily at 09:00 UTC and decides per-automation whether
+// the schedule says to run today (see apps/api/src/trigger/shared/is-due-today.ts).
+// We approximate the next qualifying tick by adding the frequency's period to
+// `lastRunAt` (or `now` if never run) and snapping to the next 09:00 UTC.
+const ORCHESTRATOR_HOUR_UTC = 9;
+
+function computeNextRunUtc(
+  scheduleFrequency: TaskFrequency,
+  lastRunAt: Date | null,
+  now: Date,
+): Date {
+  // Never-run automations: the orchestrator's `isDueToday` short-circuits to
+  // true on a null lastRunAt, so the next run is the next 09:00 UTC tick. Do
+  // NOT add the period — that would push the displayed next-run a full week/
+  // month into the future and contradict the actual scheduler behavior.
+  if (lastRunAt !== null) {
+    const candidate = new Date(lastRunAt.getTime());
+    candidate.setUTCDate(candidate.getUTCDate() + PERIOD_DAYS[scheduleFrequency]);
+    candidate.setUTCHours(ORCHESTRATOR_HOUR_UTC, 0, 0, 0);
+    if (candidate.getTime() > now.getTime()) {
+      return candidate;
+    }
+  }
+  // Either never run, or the period-aligned candidate is already in the past;
+  // both fall through to "next 09:00 UTC tick from now".
+  const next = new Date(
+    Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate(), ORCHESTRATOR_HOUR_UTC),
+  );
+  if (next.getTime() <= now.getTime()) {
+    next.setUTCDate(next.getUTCDate() + 1);
+  }
+  return next;
 }
 
 export function MetricsSection({
   initialVersions,
   initialRuns,
+  scheduleFrequency,
+  lastRunAt,
 }: MetricsSectionProps) {
   const thisWeekRuns = useMemo(() => {
     const now = new Date();
@@ -26,50 +80,57 @@ export function MetricsSection({
     (run) => run.status === 'completed' && run.success && run.evaluationStatus !== 'fail',
   ).length;
   const successRate = totalRuns > 0 ? Math.round((successfulRuns / totalRuns) * 100) : 0;
-  const successRateColor = successRate >= 90 ? 'text-primary' : successRate >= 60 ? 'text-warning' : 'text-destructive';
+  const successRateColor =
+    successRate >= 90 ? 'text-primary' : successRate >= 60 ? 'text-warning' : 'text-destructive';
   const latestRun = initialRuns[0];
 
-  // Automations run daily at 09:00 UTC (see
-  // comp-private/apps/enterprise-api/src/trigger/automation/run-automations-schedule.ts).
-  // Render the schedule explicitly in UTC and the next run in the user's
-  // local timezone so the label matches when it actually fires.
-  //
-  // The next-run label is computed on the client only (useState + useEffect
-  // instead of useMemo) to avoid a hydration mismatch: Node.js renders in
-  // the server's timezone + locale (typically UTC) while the browser renders
-  // in the user's, and `new Date()` can also tick across 09:00 UTC between
-  // the two renders and produce a different weekday. We render `—` during
-  // SSR and fill it in once mounted.
+  // Render schedule + next-run labels client-side only to avoid a hydration
+  // mismatch (Node renders in the server's locale + timezone, the browser in
+  // the user's). We show "—" during SSR and fill in after mount.
+  const [scheduleLabel, setScheduleLabel] = useState<string | null>(null);
   const [nextRunLabel, setNextRunLabel] = useState<string | null>(null);
+  const [lastRunLabel, setLastRunLabel] = useState<string | null>(null);
 
   useEffect(() => {
     const now = new Date();
-    const next = new Date(
-      Date.UTC(
-        now.getUTCFullYear(),
-        now.getUTCMonth(),
-        now.getUTCDate(),
-        9,
-        0,
-        0,
-        0,
-      ),
-    );
-    if (next.getTime() <= now.getTime()) {
-      next.setUTCDate(next.getUTCDate() + 1);
-    }
-    // Include timeZoneName so the label is unambiguous alongside the UTC
-    // Schedule card — otherwise "Fri 12:00 PM" could be mistaken for UTC.
+    const last = lastRunAt ? new Date(lastRunAt) : null;
+    const next = computeNextRunUtc(scheduleFrequency, last, now);
+
+    // Format the recurring time in the user's timezone (e.g., "Every day at
+    // 4:00 AM EST"). Pulling time-of-day from the next-run instant guarantees
+    // the schedule and next-run labels agree about clock time.
+    const timeOfDay = next.toLocaleTimeString(undefined, {
+      hour: 'numeric',
+      minute: '2-digit',
+      hour12: true,
+      timeZoneName: 'short',
+    });
+    setScheduleLabel(`${FREQUENCY_DESCRIPTIONS[scheduleFrequency]} at ${timeOfDay}`);
+
     setNextRunLabel(
       next.toLocaleString(undefined, {
         weekday: 'short',
+        month: 'short',
+        day: 'numeric',
         hour: 'numeric',
         minute: '2-digit',
         hour12: true,
         timeZoneName: 'short',
       }),
     );
-  }, []);
+
+    if (latestRun) {
+      setLastRunLabel(
+        new Date(latestRun.createdAt).toLocaleTimeString(undefined, {
+          hour: 'numeric',
+          minute: '2-digit',
+          hour12: true,
+        }),
+      );
+    } else {
+      setLastRunLabel(null);
+    }
+  }, [scheduleFrequency, lastRunAt, latestRun]);
 
   return (
     <div className="grid grid-cols-2 md:grid-cols-4 divide-x border-y py-4">
@@ -83,7 +144,7 @@ export function MetricsSection({
 
       <div className="px-4">
         <p className="text-xs text-muted-foreground mb-1">Schedule</p>
-        <p className="text-sm font-medium">Every day at 9:00 AM UTC</p>
+        <p className="text-sm font-medium">{scheduleLabel ?? '—'}</p>
       </div>
 
       <div className="px-4">
@@ -95,19 +156,17 @@ export function MetricsSection({
         <p className="text-xs text-muted-foreground mb-1">Last Run</p>
         {latestRun ? (
           <>
-            <p className="text-sm font-medium">
-              {new Date(latestRun.createdAt).toLocaleTimeString(undefined, {
-                hour: 'numeric',
-                minute: '2-digit',
-                hour12: true,
-              })}
-            </p>
-            <p className={`text-xs font-medium ${
-              latestRun.status === 'completed' && latestRun.evaluationStatus !== 'fail'
-                ? 'text-primary'
-                : 'text-destructive'
-            }`}>
-              {latestRun.status === 'completed' && latestRun.evaluationStatus !== 'fail' ? 'Complete' : 'Failed'}
+            <p className="text-sm font-medium">{lastRunLabel ?? '—'}</p>
+            <p
+              className={`text-xs font-medium ${
+                latestRun.status === 'completed' && latestRun.evaluationStatus !== 'fail'
+                  ? 'text-primary'
+                  : 'text-destructive'
+              }`}
+            >
+              {latestRun.status === 'completed' && latestRun.evaluationStatus !== 'fail'
+                ? 'Complete'
+                : 'Failed'}
             </p>
           </>
         ) : (
diff --git a/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/components/SingleTask.tsx b/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/components/SingleTask.tsx
index 6085775f24..76a0e39b3f 100644
--- a/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/components/SingleTask.tsx
+++ b/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/components/SingleTask.tsx
@@ -24,6 +24,7 @@ import {
   type Control,
   type Member,
   type Task,
+  type TaskFrequency,
   type TaskStatus,
   type User,
 } from '@db';
@@ -163,6 +164,16 @@ export function SingleTask({
     }
   };
 
+  const handleUpdateIntegrationSchedule = async (value: TaskFrequency) => {
+    try {
+      await updateTask({ integrationScheduleFrequency: value });
+      toast.success('Schedule updated');
+      mutateActivity();
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : 'Failed to update schedule');
+    }
+  };
+
   const handleUpdateTask = async (
     updates: Partial<Pick<Task, 'status' | 'assigneeId' | 'approverId' | 'frequency' | 'department' | 'reviewDate'>>,
   ) => {
@@ -344,6 +355,11 @@ export function SingleTask({
                 taskId={task.id}
                 onTaskUpdated={() => mutateTask()}
                 isManualTask={task.automationStatus === 'MANUAL'}
+                scheduleFrequency={task.integrationScheduleFrequency ?? undefined}
+                lastRunAt={task.integrationLastRunAt ?? null}
+                onScheduleChange={
+                  canUpdateTask ? handleUpdateIntegrationSchedule : undefined
+                }
               />
               <TaskAutomations
                 automations={automations || []}
diff --git a/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/components/TaskAutomations.tsx b/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/components/TaskAutomations.tsx
index dca7ecb076..ddc5f57ae8 100644
--- a/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/components/TaskAutomations.tsx
+++ b/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/components/TaskAutomations.tsx
@@ -14,6 +14,7 @@ import { useParams, useRouter } from 'next/navigation';
 import { useState } from 'react';
 import { toast } from 'sonner';
 import { Button, HStack, Section, Stack, Text } from '@trycompai/design-system';
+import { ScheduleSummary } from '@/components/schedule-summary';
 import { useTaskAutomations } from '../hooks/use-task-automations';
 
 type AutomationWithLatestRun = EvidenceAutomation & {
@@ -89,6 +90,10 @@ export const TaskAutomations = ({ automations, isManualTask = false }: TaskAutom
                     ? `Last ran ${lastRan} • v${latestVersionRun.version}`
                     : 'No published runs yet'}
                 </Text>
+                <ScheduleSummary
+                  scheduleFrequency={automation.scheduleFrequency}
+                  lastRunAt={automation.lastRunAt}
+                />
               </Stack>
 
               {latestVersionRun && (
diff --git a/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/components/TaskIntegrationChecks.tsx b/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/components/TaskIntegrationChecks.tsx
index 73b7572673..43b3d41d52 100644
--- a/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/components/TaskIntegrationChecks.tsx
+++ b/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/components/TaskIntegrationChecks.tsx
@@ -2,7 +2,9 @@
 
 import { ConnectIntegrationDialog } from '@/components/integrations/ConnectIntegrationDialog';
 import { ManageIntegrationDialog } from '@/components/integrations/ManageIntegrationDialog';
+import { SchedulePicker } from '@/components/schedule-picker';
 import { downloadAutomationPDF } from '@/lib/evidence-download';
+import type { TaskFrequency } from '@db';
 import type { TaskIntegrationCheck, StoredCheckRun } from '../hooks/useIntegrationChecks';
 import { useIntegrationChecks } from '../hooks/useIntegrationChecks';
 import { cn } from '@/lib/utils';
@@ -50,12 +52,21 @@ interface TaskIntegrationChecksProps {
   onTaskUpdated?: () => void;
   /** When true, disables creating new automations (shows existing ones read-only) */
   isManualTask?: boolean;
+  /** Current schedule for integration checks on this task. When provided with
+   * `onScheduleChange`, renders a schedule picker in the card header. */
+  scheduleFrequency?: TaskFrequency;
+  /** Last successful run timestamp, used to compute the "next run" display. */
+  lastRunAt?: Date | string | null;
+  onScheduleChange?: (value: TaskFrequency) => void | Promise<void>;
 }
 
 export function TaskIntegrationChecks({
   taskId,
   onTaskUpdated,
   isManualTask = false,
+  scheduleFrequency,
+  lastRunAt,
+  onScheduleChange,
 }: TaskIntegrationChecksProps) {
   const params = useParams();
   const searchParams = useSearchParams();
@@ -260,26 +271,43 @@ export function TaskIntegrationChecks({
   const failedRuns = storedRuns.filter((r) => r.status === 'failed' || r.failedCount > 0).length;
   const successRate = totalRuns > 0 ? Math.round((successfulRuns / totalRuns) * 100) : 0;
 
-  // Calculate next scheduled run (daily at 6 AM UTC)
+  // Calculate next scheduled run. Orchestrator fires daily at 6 AM UTC; the
+  // actual task only runs on a tick when `isDueToday(scheduleFrequency,
+  // lastRunAt)` returns true (server-side). We approximate the next qualifying
+  // 6 AM UTC tick here — exact enough for a UI hint, not authoritative.
   const getNextScheduledRun = () => {
     const now = new Date();
-    let nextRun = setMinutes(setHours(new Date(), 6), 0); // 6:00 AM UTC today
-
-    // If we're past 6 AM UTC today, schedule for tomorrow
+    const PERIOD_DAYS: Record<TaskFrequency, number> = {
+      daily: 1,
+      weekly: 7,
+      monthly: 30,
+      quarterly: 91,
+      yearly: 365,
+    };
+    const last = lastRunAt ? new Date(lastRunAt) : null;
+    const periodDays = PERIOD_DAYS[scheduleFrequency ?? 'daily'];
+    const earliestDueFromLast = last
+      ? addDays(last, periodDays)
+      : now;
+    // Snap to next 6 AM UTC at or after the earliest-due date
+    let nextRun = setMinutes(setHours(earliestDueFromLast, 6), 0);
     if (isBefore(nextRun, now)) {
-      nextRun = addDays(nextRun, 1);
+      nextRun = setMinutes(setHours(addDays(now, 1), 6), 0);
     }
-
     return nextRun;
   };
 
   const nextRun = connectedChecks.length > 0 ? getNextScheduledRun() : null;
+  const hasConfiguredChecks =
+    connectedChecks.length > 0 || disabledForTaskChecks.length > 0;
+  const showSchedulePicker =
+    hasConfiguredChecks && !!scheduleFrequency && !!onScheduleChange;
 
   return (
     <div className="rounded-lg border border-border bg-card overflow-hidden">
       {/* Card Header */}
       <div className="px-5 py-4 border-b border-border">
-        <div className="flex items-center justify-between">
+        <div className="flex items-center justify-between gap-4">
           <div className="flex items-center gap-2.5">
             <div className="p-1.5 rounded-md bg-muted">
               <PlugZap className="h-4 w-4 text-primary" />
@@ -291,16 +319,31 @@ export function TaskIntegrationChecks({
               </p>
             </div>
           </div>
-          {connectedChecks.length > 0 && nextRun && (
-            <div className="text-right">
-              <div className="text-[10px] text-muted-foreground uppercase tracking-wide">
-                Next run
+          <div className="flex items-center gap-4">
+            {showSchedulePicker && scheduleFrequency && onScheduleChange && (
+              <div className="flex items-center gap-2">
+                <span className="text-xs text-muted-foreground uppercase tracking-wide">
+                  Schedule
+                </span>
+                <SchedulePicker
+                  value={scheduleFrequency}
+                  onChange={(value) => {
+                    void onScheduleChange(value);
+                  }}
+                />
               </div>
-              <div className="text-sm font-medium text-foreground">
-                {formatDistanceToNow(nextRun, { addSuffix: true })}
+            )}
+            {connectedChecks.length > 0 && nextRun && (
+              <div className="text-right">
+                <div className="text-[10px] text-muted-foreground uppercase tracking-wide">
+                  Next run
+                </div>
+                <div className="text-sm font-medium text-foreground">
+                  {formatDistanceToNow(nextRun, { addSuffix: true })}
+                </div>
               </div>
-            </div>
-          )}
+            )}
+          </div>
         </div>
       </div>
 
diff --git a/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/components/browser-automations/AutomationItem.tsx b/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/components/browser-automations/AutomationItem.tsx
index 951851db10..1bc4b61eb4 100644
--- a/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/components/browser-automations/AutomationItem.tsx
+++ b/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/components/browser-automations/AutomationItem.tsx
@@ -13,6 +13,7 @@ import {
 } from 'lucide-react';
 import { formatDistanceToNow } from 'date-fns';
 import { useState } from 'react';
+import { ScheduleSummary } from '@/components/schedule-summary';
 import type { BrowserAutomation, BrowserAutomationRun } from '../../hooks/types';
 import { RunHistory } from './RunHistory';
 
@@ -86,6 +87,14 @@ export function AutomationItem({
           ) : (
             <p className="text-xs text-muted-foreground mt-0.5">Never run</p>
           )}
+          {automation.scheduleFrequency && (
+            <div className="mt-0.5">
+              <ScheduleSummary
+                scheduleFrequency={automation.scheduleFrequency}
+                lastRunAt={automation.lastRunAt ?? null}
+              />
+            </div>
+          )}
         </div>
 
         <div className="flex items-center gap-1.5">
diff --git a/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/components/browser-automations/BrowserAutomationConfigDialog.tsx b/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/components/browser-automations/BrowserAutomationConfigDialog.tsx
index 07dc6ee42e..29c0bb65fe 100644
--- a/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/components/browser-automations/BrowserAutomationConfigDialog.tsx
+++ b/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/components/browser-automations/BrowserAutomationConfigDialog.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { SchedulePicker } from '@/components/schedule-picker';
 import { Button } from '@trycompai/ui/button';
 import {
   Dialog,
@@ -15,7 +16,7 @@ import { Textarea } from '@trycompai/ui/textarea';
 import { zodResolver } from '@hookform/resolvers/zod';
 import { Loader2 } from 'lucide-react';
 import { useEffect } from 'react';
-import { useForm } from 'react-hook-form';
+import { Controller, useForm } from 'react-hook-form';
 import { z } from 'zod';
 import type { BrowserAutomation } from '../../hooks/types';
 
@@ -24,6 +25,7 @@ const automationConfigSchema = z.object({
   targetUrl: z.string().trim().url({ message: 'Starting URL must be a valid URL' }),
   instruction: z.string().trim().min(1, { message: 'Instruction is required' }),
   evaluationCriteria: z.string().trim().optional(),
+  scheduleFrequency: z.enum(['daily', 'weekly', 'monthly', 'quarterly', 'yearly']),
 });
 
 type AutomationConfigFormData = z.infer<typeof automationConfigSchema>;
@@ -33,7 +35,7 @@ interface BrowserAutomationConfigDialogProps {
   mode: 'create' | 'edit';
   initialValues?: Pick<
     BrowserAutomation,
-    'id' | 'name' | 'targetUrl' | 'instruction' | 'evaluationCriteria'
+    'id' | 'name' | 'targetUrl' | 'instruction' | 'evaluationCriteria' | 'scheduleFrequency'
   >;
   isSaving: boolean;
   onClose: () => void;
@@ -51,6 +53,7 @@ export function BrowserAutomationConfigDialog({
   onUpdate,
 }: BrowserAutomationConfigDialogProps) {
   const {
+    control,
     register,
     handleSubmit,
     reset,
@@ -62,6 +65,7 @@ export function BrowserAutomationConfigDialog({
       targetUrl: '',
       instruction: '',
       evaluationCriteria: '',
+      scheduleFrequency: 'daily',
     },
   });
 
@@ -74,15 +78,28 @@ export function BrowserAutomationConfigDialog({
         targetUrl: initialValues.targetUrl ?? '',
         instruction: initialValues.instruction ?? '',
         evaluationCriteria: initialValues.evaluationCriteria ?? '',
+        scheduleFrequency: initialValues.scheduleFrequency ?? 'daily',
       });
       return;
     }
 
-    reset({ name: '', targetUrl: '', instruction: '', evaluationCriteria: '' });
+    reset({
+      name: '',
+      targetUrl: '',
+      instruction: '',
+      evaluationCriteria: '',
+      scheduleFrequency: 'daily',
+    });
   }, [isOpen, mode, initialValues, reset]);
 
   const handleClose = () => {
-    reset({ name: '', targetUrl: '', instruction: '', evaluationCriteria: '' });
+    reset({
+      name: '',
+      targetUrl: '',
+      instruction: '',
+      evaluationCriteria: '',
+      scheduleFrequency: 'daily',
+    });
     onClose();
   };
 
@@ -180,6 +197,23 @@ export function BrowserAutomationConfigDialog({
             </p>
           </div>
 
+          <div className="flex flex-col gap-2">
+            <Label htmlFor="automation-schedule-frequency">Schedule</Label>
+            <Controller
+              control={control}
+              name="scheduleFrequency"
+              render={({ field }) => (
+                <SchedulePicker value={field.value} onChange={field.onChange} />
+              )}
+            />
+            {errors.scheduleFrequency?.message && (
+              <p className="text-sm text-destructive">{errors.scheduleFrequency.message}</p>
+            )}
+            <p className="text-xs text-muted-foreground">
+              How often this automation should run automatically.
+            </p>
+          </div>
+
           <DialogFooter>
             <Button type="button" variant="outline" onClick={handleClose} disabled={isSaving}>
               Cancel
diff --git a/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/hooks/types.ts b/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/hooks/types.ts
index bde9703734..7675f22086 100644
--- a/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/hooks/types.ts
+++ b/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/hooks/types.ts
@@ -1,3 +1,5 @@
+import type { TaskFrequency } from '@db';
+
 export interface BrowserAutomationRun {
   id: string;
   status: string;
@@ -18,6 +20,8 @@ export interface BrowserAutomation {
   evaluationCriteria?: string | null;
   isEnabled: boolean;
   schedule?: string;
+  scheduleFrequency?: TaskFrequency;
+  lastRunAt?: string | null;
   createdAt: string;
   runs?: BrowserAutomationRun[];
 }
diff --git a/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/hooks/use-task.ts b/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/hooks/use-task.ts
index fa8f3d363f..982f76e65e 100644
--- a/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/hooks/use-task.ts
+++ b/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/hooks/use-task.ts
@@ -1,5 +1,5 @@
 import { apiClient } from '@/lib/api-client';
-import type { Control, Task, TaskStatus } from '@db';
+import type { Control, Task, TaskFrequency, TaskStatus } from '@db';
 import { useParams } from 'next/navigation';
 import useSWR from 'swr';
 
@@ -17,6 +17,7 @@ interface UpdateTaskPayload {
   reviewDate?: string | null;
   title?: string;
   description?: string;
+  integrationScheduleFrequency?: TaskFrequency;
 }
 
 interface UseTaskReturn {
diff --git a/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/hooks/useBrowserAutomations.ts b/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/hooks/useBrowserAutomations.ts
index ab73c86ab1..a089fcfb97 100644
--- a/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/hooks/useBrowserAutomations.ts
+++ b/apps/app/src/app/(app)/[orgId]/tasks/[taskId]/hooks/useBrowserAutomations.ts
@@ -1,6 +1,7 @@
 'use client';
 
 import { apiClient } from '@/lib/api-client';
+import type { TaskFrequency } from '@db';
 import { useCallback, useState } from 'react';
 import { toast } from 'sonner';
 import type { BrowserAutomation } from './types';
@@ -13,6 +14,8 @@ interface AutomationConfigInput {
   name: string;
   targetUrl: string;
   instruction: string;
+  evaluationCriteria?: string;
+  scheduleFrequency?: TaskFrequency;
 }
 
 export function useBrowserAutomations({ taskId }: UseBrowserAutomationsOptions) {
diff --git a/apps/app/src/app/(app)/[orgId]/tasks/components/ModernSingleStatusTaskList.test.tsx b/apps/app/src/app/(app)/[orgId]/tasks/components/ModernSingleStatusTaskList.test.tsx
index 0500aeb1d3..037bf8306b 100644
--- a/apps/app/src/app/(app)/[orgId]/tasks/components/ModernSingleStatusTaskList.test.tsx
+++ b/apps/app/src/app/(app)/[orgId]/tasks/components/ModernSingleStatusTaskList.test.tsx
@@ -122,10 +122,25 @@ const mockTasks = [
     id: 'task-1',
     title: 'Test Task 1',
     description: 'A test task',
-    status: 'todo',
+    status: 'todo' as const,
+    previousStatus: null,
+    automationStatus: 'AUTOMATED' as const,
+    frequency: null,
+    integrationScheduleFrequency: 'daily' as const,
+    integrationLastRunAt: null,
+    department: null,
     assigneeId: null,
     createdAt: new Date(),
     updatedAt: new Date(),
+    archivedAt: null,
+    lastCompletedAt: null,
+    reviewDate: null,
+    order: 0,
+    taskTemplateId: null,
+    approvalStatus: null,
+    approverId: null,
+    approvedAt: null,
+    approvalComment: null,
     organizationId: 'org_1',
     controls: [],
   },
@@ -133,10 +148,25 @@ const mockTasks = [
     id: 'task-2',
     title: 'Test Task 2',
     description: 'Another test task',
-    status: 'todo',
+    status: 'todo' as const,
+    previousStatus: null,
+    automationStatus: 'AUTOMATED' as const,
+    frequency: null,
+    integrationScheduleFrequency: 'daily' as const,
+    integrationLastRunAt: null,
+    department: null,
     assigneeId: null,
     createdAt: new Date(),
     updatedAt: new Date(),
+    archivedAt: null,
+    lastCompletedAt: null,
+    reviewDate: null,
+    order: 0,
+    taskTemplateId: null,
+    approvalStatus: null,
+    approverId: null,
+    approvedAt: null,
+    approvalComment: null,
     organizationId: 'org_1',
     controls: [],
   },
diff --git a/apps/app/src/app/(app)/[orgId]/tasks/components/TaskList.test.tsx b/apps/app/src/app/(app)/[orgId]/tasks/components/TaskList.test.tsx
index e061d10903..459f1714c7 100644
--- a/apps/app/src/app/(app)/[orgId]/tasks/components/TaskList.test.tsx
+++ b/apps/app/src/app/(app)/[orgId]/tasks/components/TaskList.test.tsx
@@ -132,12 +132,17 @@ import { TaskList } from './TaskList';
 const baseMockTask = {
   description: 'Test',
   status: 'todo' as const,
+  previousStatus: null,
   frequency: null,
+  integrationScheduleFrequency: 'daily' as const,
+  integrationLastRunAt: null,
   department: null,
   assigneeId: null,
   organizationId: 'org_123',
   createdAt: new Date(),
   updatedAt: new Date(),
+  archivedAt: null,
+  lastCompletedAt: null,
   order: 0,
   taskTemplateId: null,
   reviewDate: null,
diff --git a/apps/app/src/components/schedule-picker.test.tsx b/apps/app/src/components/schedule-picker.test.tsx
new file mode 100644
index 0000000000..b77b7127b7
--- /dev/null
+++ b/apps/app/src/components/schedule-picker.test.tsx
@@ -0,0 +1,91 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import { createContext, useContext, type ReactNode } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+interface SelectContextValue {
+  value: string;
+  onValueChange: (next: string) => void;
+  disabled?: boolean;
+}
+
+const MockSelectContext = createContext<SelectContextValue | null>(null);
+
+function useMockSelect(): SelectContextValue {
+  const ctx = useContext(MockSelectContext);
+  if (!ctx) {
+    throw new Error('Select components must be used within Select');
+  }
+  return ctx;
+}
+
+vi.mock('@trycompai/ui/select', () => ({
+  Select: ({
+    value,
+    onValueChange,
+    disabled,
+    children,
+  }: {
+    value: string;
+    onValueChange: (next: string) => void;
+    disabled?: boolean;
+    children: ReactNode;
+  }) => (
+    <MockSelectContext.Provider value={{ value, onValueChange, disabled }}>
+      <div>{children}</div>
+    </MockSelectContext.Provider>
+  ),
+  SelectTrigger: ({ children }: { children: ReactNode }) => {
+    const { disabled } = useMockSelect();
+    return (
+      <button type="button" role="combobox" disabled={disabled}>
+        {children}
+      </button>
+    );
+  },
+  SelectContent: ({ children }: { children: ReactNode }) => <div>{children}</div>,
+  SelectValue: ({
+    placeholder,
+    children,
+  }: {
+    placeholder?: string;
+    children?: ReactNode;
+  }) => {
+    const { value } = useMockSelect();
+    // Mirror the real Radix behavior: render `children` (the label) when
+    // `value` is set, otherwise the placeholder.
+    return <span>{value ? (children ?? value) : placeholder}</span>;
+  },
+  SelectItem: ({ value, children }: { value: string; children: ReactNode }) => {
+    const { onValueChange } = useMockSelect();
+    return (
+      <div role="option" onClick={() => onValueChange(value)}>
+        {children}
+      </div>
+    );
+  },
+}));
+
+// Import AFTER mock is declared so the component uses the mocked Select.
+import { SchedulePicker } from './schedule-picker';
+
+describe('SchedulePicker', () => {
+  it('renders the current value as a capitalized label', () => {
+    render(<SchedulePicker value="weekly" onChange={() => {}} />);
+    // The trigger displays the human label (via SelectValue children),
+    // not the raw enum.
+    expect(screen.getByRole('combobox')).toHaveTextContent('Weekly');
+  });
+
+  it('calls onChange when a new option is picked', () => {
+    const onChange = vi.fn();
+    render(<SchedulePicker value="daily" onChange={onChange} />);
+    fireEvent.click(screen.getByRole('combobox'));
+    fireEvent.click(screen.getByText('Monthly'));
+    expect(onChange).toHaveBeenCalledWith('monthly');
+  });
+
+  it('is disabled when disabled prop is true', () => {
+    render(<SchedulePicker value="daily" onChange={() => {}} disabled />);
+    expect(screen.getByRole('combobox')).toBeDisabled();
+  });
+});
diff --git a/apps/app/src/components/schedule-picker.tsx b/apps/app/src/components/schedule-picker.tsx
new file mode 100644
index 0000000000..a7c404d9f1
--- /dev/null
+++ b/apps/app/src/components/schedule-picker.tsx
@@ -0,0 +1,49 @@
+'use client';
+
+import { TaskFrequency } from '@db';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@trycompai/ui/select';
+
+const LABELS: Record<TaskFrequency, string> = {
+  daily: 'Daily',
+  weekly: 'Weekly',
+  monthly: 'Monthly',
+  quarterly: 'Quarterly',
+  yearly: 'Yearly',
+};
+
+const FREQUENCIES = Object.keys(LABELS) as TaskFrequency[];
+
+export function SchedulePicker({
+  value,
+  onChange,
+  disabled,
+}: {
+  value: TaskFrequency;
+  onChange: (value: TaskFrequency) => void;
+  disabled?: boolean;
+}) {
+  return (
+    <Select
+      value={value}
+      onValueChange={(next) => onChange(next as TaskFrequency)}
+      disabled={disabled}
+    >
+      <SelectTrigger>
+        <SelectValue placeholder="Select a frequency">{LABELS[value]}</SelectValue>
+      </SelectTrigger>
+      <SelectContent>
+        {FREQUENCIES.map((freq) => (
+          <SelectItem key={freq} value={freq}>
+            {LABELS[freq]}
+          </SelectItem>
+        ))}
+      </SelectContent>
+    </Select>
+  );
+}
diff --git a/apps/app/src/components/schedule-summary.test.tsx b/apps/app/src/components/schedule-summary.test.tsx
new file mode 100644
index 0000000000..88906fa592
--- /dev/null
+++ b/apps/app/src/components/schedule-summary.test.tsx
@@ -0,0 +1,22 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { ScheduleSummary } from './schedule-summary';
+
+describe('ScheduleSummary', () => {
+  it('renders frequency label', () => {
+    render(<ScheduleSummary scheduleFrequency="weekly" lastRunAt={null} />);
+    expect(screen.getByText(/Weekly/)).toBeInTheDocument();
+  });
+
+  it('renders a deterministic YYYY-MM-DD next-run date', () => {
+    render(
+      <ScheduleSummary
+        scheduleFrequency="weekly"
+        lastRunAt={new Date('2026-04-17T00:00:00.000Z').toISOString()}
+      />,
+    );
+    // lastRunAt 2026-04-17 + 7 days = 2026-04-24. Tests render the literal
+    // locale-agnostic YYYY-MM-DD, not a toLocaleDateString() output.
+    expect(screen.getByText(/next: 2026-04-24/)).toBeInTheDocument();
+  });
+});
diff --git a/apps/app/src/components/schedule-summary.tsx b/apps/app/src/components/schedule-summary.tsx
new file mode 100644
index 0000000000..725dca0b36
--- /dev/null
+++ b/apps/app/src/components/schedule-summary.tsx
@@ -0,0 +1,60 @@
+'use client';
+
+import { TaskFrequency } from '@db';
+
+const LABELS: Record<TaskFrequency, string> = {
+  daily: 'Daily',
+  weekly: 'Weekly',
+  monthly: 'Monthly',
+  quarterly: 'Quarterly',
+  yearly: 'Yearly',
+};
+
+const PERIOD_DAYS: Record<TaskFrequency, number> = {
+  daily: 1,
+  weekly: 7,
+  monthly: 30,
+  quarterly: 91,
+  yearly: 365,
+};
+
+// Approximate next-run (months ≈ 30 days). The server's isDueToday helper is the
+// real authority; this is only a UX hint shown on automation cards.
+//
+// When `lastRunAt` is null the orchestrator picks the automation up on its
+// next tick, so we show "now" rather than now + period (which would over-
+// project a full period into the future).
+function computeNextRun(frequency: TaskFrequency, lastRunAt: Date | null, now: Date): Date {
+  if (lastRunAt === null) return now;
+  return new Date(lastRunAt.getTime() + PERIOD_DAYS[frequency] * 24 * 60 * 60 * 1000);
+}
+
+// Locale-agnostic YYYY-MM-DD so the rendered string is byte-identical on
+// server vs. client, avoiding React hydration mismatches that
+// `toLocaleDateString()` would introduce under different user locales.
+function formatYmdUtc(d: Date): string {
+  const y = d.getUTCFullYear();
+  const m = String(d.getUTCMonth() + 1).padStart(2, '0');
+  const day = String(d.getUTCDate()).padStart(2, '0');
+  return `${y}-${m}-${day}`;
+}
+
+export function ScheduleSummary({
+  scheduleFrequency,
+  lastRunAt,
+}: {
+  scheduleFrequency: TaskFrequency;
+  lastRunAt: string | Date | null;
+}) {
+  const last = lastRunAt ? new Date(lastRunAt) : null;
+  // Anchor "now" to UTC midnight so a render that spans a day boundary
+  // doesn't produce a different next-run date between server and client.
+  const nowUtc = new Date();
+  nowUtc.setUTCHours(0, 0, 0, 0);
+  const next = computeNextRun(scheduleFrequency, last, nowUtc);
+  return (
+    <span className="text-xs text-muted-foreground">
+      Runs {LABELS[scheduleFrequency]} · next: {formatYmdUtc(next)}
+    </span>
+  );
+}
diff --git a/packages/db/prisma/migrations/20260424164600_custom_task_schedules/migration.sql b/packages/db/prisma/migrations/20260424164600_custom_task_schedules/migration.sql
new file mode 100644
index 0000000000..f8cde3c627
--- /dev/null
+++ b/packages/db/prisma/migrations/20260424164600_custom_task_schedules/migration.sql
@@ -0,0 +1,18 @@
+/*
+  Warnings:
+
+  - You are about to drop the column `schedule` on the `BrowserAutomation` table. All the data in the column will be lost.
+
+*/
+-- AlterTable
+ALTER TABLE "BrowserAutomation" DROP COLUMN "schedule",
+ADD COLUMN     "lastRunAt" TIMESTAMP(3),
+ADD COLUMN     "scheduleFrequency" "TaskFrequency" NOT NULL DEFAULT 'daily';
+
+-- AlterTable
+ALTER TABLE "EvidenceAutomation" ADD COLUMN     "lastRunAt" TIMESTAMP(3),
+ADD COLUMN     "scheduleFrequency" "TaskFrequency" NOT NULL DEFAULT 'daily';
+
+-- AlterTable
+ALTER TABLE "Task" ADD COLUMN     "integrationLastRunAt" TIMESTAMP(3),
+ADD COLUMN     "integrationScheduleFrequency" "TaskFrequency" NOT NULL DEFAULT 'daily';
diff --git a/packages/db/prisma/schema/auth.prisma b/packages/db/prisma/schema/auth.prisma
index 05502d9017..e823f31472 100644
--- a/packages/db/prisma/schema/auth.prisma
+++ b/packages/db/prisma/schema/auth.prisma
@@ -15,20 +15,20 @@ model User {
   banExpires                     DateTime?
   isPlatformAdmin                Boolean   @default(false)
 
-  accounts                  Account[]
-  auditLog                  AuditLog[]
-  integrationResults        IntegrationResult[]
-  invitations               Invitation[]
-  members                   Member[]
-  sessions                  Session[]
-  fleetPolicyResults        FleetPolicyResult[]
-  evidenceSubmissions       EvidenceSubmission[] @relation("EvidenceSubmitter")
-  evidenceReviews           EvidenceSubmission[] @relation("EvidenceReviewer")
-  adminFindings             Finding[]            @relation("AdminFindingCreator")
-  timelinePhaseCompletions  TimelinePhase[]
-  lockedTimelineInstances   TimelineInstance[]   @relation("TimelineInstanceLockedBy")
-  unlockedTimelineInstances TimelineInstance[]   @relation("TimelineInstanceUnlockedBy")
-  publishedFrameworkVersions FrameworkVersion[]  @relation("FrameworkVersionPublisher")
+  accounts                   Account[]
+  auditLog                   AuditLog[]
+  integrationResults         IntegrationResult[]
+  invitations                Invitation[]
+  members                    Member[]
+  sessions                   Session[]
+  fleetPolicyResults         FleetPolicyResult[]
+  evidenceSubmissions        EvidenceSubmission[] @relation("EvidenceSubmitter")
+  evidenceReviews            EvidenceSubmission[] @relation("EvidenceReviewer")
+  adminFindings              Finding[]            @relation("AdminFindingCreator")
+  timelinePhaseCompletions   TimelinePhase[]
+  lockedTimelineInstances    TimelineInstance[]   @relation("TimelineInstanceLockedBy")
+  unlockedTimelineInstances  TimelineInstance[]   @relation("TimelineInstanceUnlockedBy")
+  publishedFrameworkVersions FrameworkVersion[]   @relation("FrameworkVersionPublisher")
 
   @@unique([email])
 }
diff --git a/packages/db/prisma/schema/automation.prisma b/packages/db/prisma/schema/automation.prisma
index f9c0501779..8f14424f6d 100644
--- a/packages/db/prisma/schema/automation.prisma
+++ b/packages/db/prisma/schema/automation.prisma
@@ -1,9 +1,11 @@
 model EvidenceAutomation {
-  id          String   @id @default(dbgenerated("generate_prefixed_cuid('aut'::text)"))
-  name        String
-  description String?
-  createdAt   DateTime @default(now())
-  isEnabled   Boolean  @default(false)
+  id                String        @id @default(dbgenerated("generate_prefixed_cuid('aut'::text)"))
+  name              String
+  description       String?
+  createdAt         DateTime      @default(now())
+  isEnabled         Boolean       @default(false)
+  scheduleFrequency TaskFrequency @default(daily)
+  lastRunAt         DateTime?
 
   chatHistory        String?
   evaluationCriteria String?
diff --git a/packages/db/prisma/schema/browserbase-context.prisma b/packages/db/prisma/schema/browserbase-context.prisma
index 5841a1021b..9c29d19778 100644
--- a/packages/db/prisma/schema/browserbase-context.prisma
+++ b/packages/db/prisma/schema/browserbase-context.prisma
@@ -1,101 +1,100 @@
 /// Stores Browserbase context IDs for browser-based automation
 /// One context per organization - shared like a normal browser
 model BrowserbaseContext {
-    id String @id @default(dbgenerated("generate_prefixed_cuid('bbc'::text)"))
+  id String @id @default(dbgenerated("generate_prefixed_cuid('bbc'::text)"))
 
-    /// Organization that owns this browser context
-    organizationId String       @unique
-    organization   Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade)
+  /// Organization that owns this browser context
+  organizationId String       @unique
+  organization   Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade)
 
-    /// Browserbase context ID from their API
-    contextId String
+  /// Browserbase context ID from their API
+  contextId String
 
-    createdAt DateTime @default(now())
-    updatedAt DateTime @updatedAt
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
 
-    @@index([organizationId])
+  @@index([organizationId])
 }
 
 /// Browser automation configuration linked to a task
 model BrowserAutomation {
-    id          String  @id @default(dbgenerated("generate_prefixed_cuid('bau'::text)"))
-    name        String
-    description String?
+  id          String  @id @default(dbgenerated("generate_prefixed_cuid('bau'::text)"))
+  name        String
+  description String?
 
-    /// Task this automation belongs to
-    taskId String
-    task   Task   @relation(fields: [taskId], references: [id], onDelete: Cascade)
+  /// Task this automation belongs to
+  taskId String
+  task   Task   @relation(fields: [taskId], references: [id], onDelete: Cascade)
 
-    /// Starting URL for the automation
-    targetUrl String
+  /// Starting URL for the automation
+  targetUrl String
 
-    /// Natural language instruction for the AI agent
-    instruction String
+  /// Natural language instruction for the AI agent
+  instruction String
 
-    /// Optional natural-language criteria used to evaluate whether the
-    /// automation's outcome satisfies the auditor's requirement.
-    /// When null, runs don't produce a pass/fail verdict — only a screenshot.
-    evaluationCriteria String?
+  /// Optional natural-language criteria used to evaluate whether the
+  /// automation's outcome satisfies the auditor's requirement.
+  /// When null, runs don't produce a pass/fail verdict — only a screenshot.
+  evaluationCriteria String?
 
-    /// Whether automation is enabled for scheduled runs
-    isEnabled Boolean @default(false)
+  /// Whether automation is enabled for scheduled runs
+  isEnabled         Boolean       @default(false)
+  scheduleFrequency TaskFrequency @default(daily)
+  lastRunAt         DateTime?
 
-    /// Cron expression for scheduled runs (null = manual only)
-    schedule String?
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
 
-    createdAt DateTime @default(now())
-    updatedAt DateTime @updatedAt
+  runs BrowserAutomationRun[]
 
-    runs BrowserAutomationRun[]
-
-    @@index([taskId])
+  @@index([taskId])
 }
 
 /// Records of browser automation executions
 model BrowserAutomationRun {
-    id String @id @default(dbgenerated("generate_prefixed_cuid('bar'::text)"))
+  id String @id @default(dbgenerated("generate_prefixed_cuid('bar'::text)"))
 
-    /// Parent automation
-    automationId String
-    automation   BrowserAutomation @relation(fields: [automationId], references: [id], onDelete: Cascade)
+  /// Parent automation
+  automationId String
+  automation   BrowserAutomation @relation(fields: [automationId], references: [id], onDelete: Cascade)
 
-    /// Execution status
-    status BrowserAutomationRunStatus @default(pending)
+  /// Execution status
+  status BrowserAutomationRunStatus @default(pending)
 
-    /// Timestamps
-    startedAt   DateTime?
-    completedAt DateTime?
+  /// Timestamps
+  startedAt   DateTime?
+  completedAt DateTime?
 
-    /// Duration in milliseconds
-    durationMs Int?
+  /// Duration in milliseconds
+  durationMs Int?
 
-    /// Screenshot URL in S3 (if successful)
-    screenshotUrl String?
+  /// Screenshot URL in S3 (if successful)
+  screenshotUrl String?
 
-    /// Evaluation result - whether the automation fulfilled the task requirements
-    evaluationStatus BrowserAutomationEvaluationStatus?
+  /// Evaluation result - whether the automation fulfilled the task requirements
+  evaluationStatus BrowserAutomationEvaluationStatus?
 
-    /// AI explanation of why it passed or failed
-    evaluationReason String?
+  /// AI explanation of why it passed or failed
+  evaluationReason String?
 
-    /// Error message (if failed)
-    error String?
+  /// Error message (if failed)
+  error String?
 
-    createdAt DateTime @default(now())
+  createdAt DateTime @default(now())
 
-    @@index([automationId])
-    @@index([status])
-    @@index([createdAt])
+  @@index([automationId])
+  @@index([status])
+  @@index([createdAt])
 }
 
 enum BrowserAutomationEvaluationStatus {
-    pass
-    fail
+  pass
+  fail
 }
 
 enum BrowserAutomationRunStatus {
-    pending
-    running
-    completed
-    failed
+  pending
+  running
+  completed
+  failed
 }
diff --git a/packages/db/prisma/schema/control.prisma b/packages/db/prisma/schema/control.prisma
index 14672cb972..0a70fc5a9e 100644
--- a/packages/db/prisma/schema/control.prisma
+++ b/packages/db/prisma/schema/control.prisma
@@ -15,13 +15,13 @@ model Control {
   archivedAt DateTime?
 
   // Relationships
-  organization       Organization                    @relation(fields: [organizationId], references: [id], onDelete: Cascade)
-  organizationId     String
-  requirementsMapped RequirementMap[]
-  tasks              Task[]
-  policies           Policy[]
-  controlTemplateId  String?
-  controlTemplate    FrameworkEditorControlTemplate? @relation(fields: [controlTemplateId], references: [id])
+  organization         Organization                    @relation(fields: [organizationId], references: [id], onDelete: Cascade)
+  organizationId       String
+  requirementsMapped   RequirementMap[]
+  tasks                Task[]
+  policies             Policy[]
+  controlTemplateId    String?
+  controlTemplate      FrameworkEditorControlTemplate? @relation(fields: [controlTemplateId], references: [id])
   controlDocumentTypes ControlDocumentType[]
 
   @@index([organizationId])
diff --git a/packages/db/prisma/schema/device.prisma b/packages/db/prisma/schema/device.prisma
index 68d5af86f8..3a609c3eb7 100644
--- a/packages/db/prisma/schema/device.prisma
+++ b/packages/db/prisma/schema/device.prisma
@@ -15,17 +15,17 @@ model Device {
   agentSessionId String?
   agentSession   Session? @relation("DeviceAgentSession", fields: [agentSessionId], references: [id], onDelete: SetNull)
 
-  isCompliant           Boolean  @default(false)
-  diskEncryptionEnabled Boolean  @default(false)
-  antivirusEnabled      Boolean  @default(false)
-  passwordPolicySet     Boolean  @default(false)
-  screenLockEnabled     Boolean  @default(false)
+  isCompliant           Boolean @default(false)
+  diskEncryptionEnabled Boolean @default(false)
+  antivirusEnabled      Boolean @default(false)
+  passwordPolicySet     Boolean @default(false)
+  screenLockEnabled     Boolean @default(false)
   checkDetails          Json?
 
   lastCheckIn  DateTime?
   agentVersion String?
-  installedAt  DateTime @default(now())
-  updatedAt    DateTime @updatedAt
+  installedAt  DateTime  @default(now())
+  updatedAt    DateTime  @updatedAt
 
   findings Finding[]
 
diff --git a/packages/db/prisma/schema/dynamic-integration.prisma b/packages/db/prisma/schema/dynamic-integration.prisma
index 7aac3b288a..58163d17de 100644
--- a/packages/db/prisma/schema/dynamic-integration.prisma
+++ b/packages/db/prisma/schema/dynamic-integration.prisma
@@ -4,95 +4,95 @@
 
 /// Stores a full integration manifest as JSON — replaces hand-written TypeScript manifests
 model DynamicIntegration {
-    id          String  @id @default(dbgenerated("generate_prefixed_cuid('din'::text)"))
-    /// Unique slug (e.g., "azure-devops", "office-365")
-    slug        String  @unique
-    /// Display name
-    name        String
-    /// Short description for catalog
-    description String
-    /// Category for grouping
-    category    String
-    /// Logo URL
-    logoUrl     String
-    /// URL to documentation
-    docsUrl     String?
-
-    /// API base URL for ctx.fetch
-    baseUrl     String?
-    /// Default headers (JSON object)
-    defaultHeaders Json?
-
-    /// Auth strategy config (JSON — matches AuthStrategy type: oauth2/api_key/basic/jwt/custom)
-    authConfig  Json
-
-    /// Capabilities JSON array (default ["checks"])
-    capabilities Json @default("[\"checks\"]")
-
-    /// Whether multiple connections per org are allowed
-    supportsMultipleConnections Boolean @default(false)
-
-    /// Declarative sync definition (JSON — DSL steps that produce employee list)
-    /// When present and capabilities includes 'sync', enables employee sync
-    syncDefinition  Json?
-
-    /// Services metadata (JSON array of { id, name, description, enabledByDefault?, implemented? })
-    services    Json?
-
-    /// Whether this dynamic integration is active
-    isActive    Boolean @default(true)
-
-    createdAt   DateTime @default(now())
-    updatedAt   DateTime @updatedAt
-
-    checks      DynamicCheck[]
-
-    @@index([slug])
-    @@index([category])
-    @@index([isActive])
+  id          String  @id @default(dbgenerated("generate_prefixed_cuid('din'::text)"))
+  /// Unique slug (e.g., "azure-devops", "office-365")
+  slug        String  @unique
+  /// Display name
+  name        String
+  /// Short description for catalog
+  description String
+  /// Category for grouping
+  category    String
+  /// Logo URL
+  logoUrl     String
+  /// URL to documentation
+  docsUrl     String?
+
+  /// API base URL for ctx.fetch
+  baseUrl        String?
+  /// Default headers (JSON object)
+  defaultHeaders Json?
+
+  /// Auth strategy config (JSON — matches AuthStrategy type: oauth2/api_key/basic/jwt/custom)
+  authConfig Json
+
+  /// Capabilities JSON array (default ["checks"])
+  capabilities Json @default("[\"checks\"]")
+
+  /// Whether multiple connections per org are allowed
+  supportsMultipleConnections Boolean @default(false)
+
+  /// Declarative sync definition (JSON — DSL steps that produce employee list)
+  /// When present and capabilities includes 'sync', enables employee sync
+  syncDefinition Json?
+
+  /// Services metadata (JSON array of { id, name, description, enabledByDefault?, implemented? })
+  services Json?
+
+  /// Whether this dynamic integration is active
+  isActive Boolean @default(true)
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  checks DynamicCheck[]
+
+  @@index([slug])
+  @@index([category])
+  @@index([isActive])
 }
 
 /// Stores a declarative check definition — DSL JSON replaces hand-written run() functions
 model DynamicCheck {
-    id              String  @id @default(dbgenerated("generate_prefixed_cuid('dck'::text)"))
+  id String @id @default(dbgenerated("generate_prefixed_cuid('dck'::text)"))
 
-    /// Parent integration
-    integrationId   String
-    integration     DynamicIntegration @relation(fields: [integrationId], references: [id], onDelete: Cascade)
+  /// Parent integration
+  integrationId String
+  integration   DynamicIntegration @relation(fields: [integrationId], references: [id], onDelete: Cascade)
 
-    /// Unique slug within integration (e.g., "mfa_enabled")
-    checkSlug       String
+  /// Unique slug within integration (e.g., "mfa_enabled")
+  checkSlug String
 
-    /// Human-readable name
-    name            String
-    /// Description of what this check does
-    description     String
+  /// Human-readable name
+  name        String
+  /// Description of what this check does
+  description String
 
-    /// Task template ID for auto-completion (references TASK_TEMPLATES)
-    taskMapping     String?
+  /// Task template ID for auto-completion (references TASK_TEMPLATES)
+  taskMapping String?
 
-    /// Default severity for findings
-    defaultSeverity String  @default("medium")
+  /// Default severity for findings
+  defaultSeverity String @default("medium")
 
-    /// Service ID this check belongs to (groups checks under a service)
-    service         String?
+  /// Service ID this check belongs to (groups checks under a service)
+  service String?
 
-    /// Declarative DSL definition (JSON — the step-by-step instructions)
-    definition      Json
+  /// Declarative DSL definition (JSON — the step-by-step instructions)
+  definition Json
 
-    /// Check-level variables (JSON array of CheckVariable)
-    variables       Json    @default("[]")
+  /// Check-level variables (JSON array of CheckVariable)
+  variables Json @default("[]")
 
-    /// Whether this check is enabled
-    isEnabled       Boolean @default(true)
+  /// Whether this check is enabled
+  isEnabled Boolean @default(true)
 
-    /// Display order
-    sortOrder       Int     @default(0)
+  /// Display order
+  sortOrder Int @default(0)
 
-    createdAt       DateTime @default(now())
-    updatedAt       DateTime @updatedAt
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
 
-    @@unique([integrationId, checkSlug])
-    @@index([integrationId])
-    @@index([isEnabled])
+  @@unique([integrationId, checkSlug])
+  @@index([integrationId])
+  @@index([isEnabled])
 }
diff --git a/packages/db/prisma/schema/framework-editor.prisma b/packages/db/prisma/schema/framework-editor.prisma
index ee06645f89..6bb6e302f5 100644
--- a/packages/db/prisma/schema/framework-editor.prisma
+++ b/packages/db/prisma/schema/framework-editor.prisma
@@ -69,8 +69,8 @@ model FrameworkEditorTaskTemplate {
   id               String               @id @default(dbgenerated("generate_prefixed_cuid('frk_tt'::text)"))
   name             String
   description      String
-  frequency        Frequency            // Using the enum from shared.prisma
-  department       Departments          // Using the enum from shared.prisma
+  frequency        Frequency // Using the enum from shared.prisma
+  department       Departments // Using the enum from shared.prisma
   automationStatus TaskAutomationStatus @default(AUTOMATED)
 
   controlTemplates FrameworkEditorControlTemplate[]
diff --git a/packages/db/prisma/schema/framework-version.prisma b/packages/db/prisma/schema/framework-version.prisma
index 9708c3f40c..40c5ca7709 100644
--- a/packages/db/prisma/schema/framework-version.prisma
+++ b/packages/db/prisma/schema/framework-version.prisma
@@ -1,20 +1,20 @@
 model FrameworkVersion {
-  id               String   @id @default(dbgenerated("generate_prefixed_cuid('fvr'::text)"))
-  frameworkId      String
-  framework        FrameworkEditorFramework @relation(fields: [frameworkId], references: [id], onDelete: Cascade)
+  id          String                   @id @default(dbgenerated("generate_prefixed_cuid('fvr'::text)"))
+  frameworkId String
+  framework   FrameworkEditorFramework @relation(fields: [frameworkId], references: [id], onDelete: Cascade)
 
-  version          String   // semver-ish, e.g., "1.0.0", "2.1.0"
-  publishedAt      DateTime @default(now())
-  publishedById    String?
-  publishedBy      User?    @relation("FrameworkVersionPublisher", fields: [publishedById], references: [id], onDelete: SetNull)
+  version       String // semver-ish, e.g., "1.0.0", "2.1.0"
+  publishedAt   DateTime @default(now())
+  publishedById String?
+  publishedBy   User?    @relation("FrameworkVersionPublisher", fields: [publishedById], references: [id], onDelete: SetNull)
 
-  releaseNotes     String?  // markdown
+  releaseNotes String? // markdown
 
   // Full snapshot of all templates at publish time (see manifest.types.ts).
   // Immutable once published.
-  manifest         Json
+  manifest Json
 
-  frameworkInstances FrameworkInstance[] @relation("FrameworkInstanceCurrentVersion")
+  frameworkInstances FrameworkInstance[]      @relation("FrameworkInstanceCurrentVersion")
   syncOperationsFrom FrameworkSyncOperation[] @relation("FrameworkSyncOperationFromVersion")
   syncOperationsTo   FrameworkSyncOperation[] @relation("FrameworkSyncOperationToVersion")
 
diff --git a/packages/db/prisma/schema/integration-platform.prisma b/packages/db/prisma/schema/integration-platform.prisma
index 8b28153ac7..98cd949e9e 100644
--- a/packages/db/prisma/schema/integration-platform.prisma
+++ b/packages/db/prisma/schema/integration-platform.prisma
@@ -3,424 +3,424 @@
 
 /// Stores metadata about available integration providers (synced from code manifests)
 model IntegrationProvider {
-    id           String  @id @default(dbgenerated("generate_prefixed_cuid('prv'::text)"))
-    /// Unique slug matching manifest ID (e.g., "github", "slack")
-    slug         String  @unique
-    /// Display name
-    name         String
-    /// Category for grouping
-    category     String
-    /// Hash of manifest for detecting changes
-    manifestHash String?
-    /// Capabilities JSON array
-    capabilities Json    @default("[]")
-    /// Whether provider is active
-    isActive     Boolean @default(true)
-
-    createdAt DateTime @default(now())
-    updatedAt DateTime @updatedAt
-
-    connections IntegrationConnection[]
-
-    @@index([slug])
-    @@index([category])
+  id           String  @id @default(dbgenerated("generate_prefixed_cuid('prv'::text)"))
+  /// Unique slug matching manifest ID (e.g., "github", "slack")
+  slug         String  @unique
+  /// Display name
+  name         String
+  /// Category for grouping
+  category     String
+  /// Hash of manifest for detecting changes
+  manifestHash String?
+  /// Capabilities JSON array
+  capabilities Json    @default("[]")
+  /// Whether provider is active
+  isActive     Boolean @default(true)
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  connections IntegrationConnection[]
+
+  @@index([slug])
+  @@index([category])
 }
 
 /// Represents an organization's connection to an integration provider
 model IntegrationConnection {
-    id String @id @default(dbgenerated("generate_prefixed_cuid('icn'::text)"))
+  id String @id @default(dbgenerated("generate_prefixed_cuid('icn'::text)"))
 
-    /// Reference to the provider
-    providerId String
-    provider   IntegrationProvider @relation(fields: [providerId], references: [id], onDelete: Cascade)
+  /// Reference to the provider
+  providerId String
+  provider   IntegrationProvider @relation(fields: [providerId], references: [id], onDelete: Cascade)
 
-    /// Organization that owns this connection
-    organizationId String
-    organization   Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade)
+  /// Organization that owns this connection
+  organizationId String
+  organization   Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade)
 
-    /// Connection status
-    status IntegrationConnectionStatus @default(pending)
+  /// Connection status
+  status IntegrationConnectionStatus @default(pending)
 
-    /// Auth strategy used (oauth2, api_key, basic, jwt, custom)
-    authStrategy String
+  /// Auth strategy used (oauth2, api_key, basic, jwt, custom)
+  authStrategy String
 
-    /// Reference to active credential version
-    activeCredentialVersionId String?
+  /// Reference to active credential version
+  activeCredentialVersionId String?
 
-    /// Last successful sync timestamp
-    lastSyncAt DateTime?
+  /// Last successful sync timestamp
+  lastSyncAt DateTime?
 
-    /// Next scheduled sync timestamp
-    nextSyncAt DateTime?
+  /// Next scheduled sync timestamp
+  nextSyncAt DateTime?
 
-    /// Custom sync cadence (cron expression), null = use default
-    syncCadence String?
+  /// Custom sync cadence (cron expression), null = use default
+  syncCadence String?
 
-    /// Additional metadata (e.g., connected account info)
-    metadata Json?
+  /// Additional metadata (e.g., connected account info)
+  metadata Json?
 
-    /// User-configured variables for checks (collected after OAuth)
-    variables Json?
+  /// User-configured variables for checks (collected after OAuth)
+  variables Json?
 
-    /// Error message if status is error
-    errorMessage String?
+  /// Error message if status is error
+  errorMessage String?
 
-    createdAt DateTime @default(now())
-    updatedAt DateTime @updatedAt
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
 
-    credentialVersions  IntegrationCredentialVersion[]
-    runs                IntegrationRun[]
-    findings            IntegrationPlatformFinding[]
-    checkRuns           IntegrationCheckRun[]
-    syncLogs            IntegrationSyncLog[]
-    remediationActions  RemediationAction[]
-    remediationBatches  RemediationBatch[]
+  credentialVersions IntegrationCredentialVersion[]
+  runs               IntegrationRun[]
+  findings           IntegrationPlatformFinding[]
+  checkRuns          IntegrationCheckRun[]
+  syncLogs           IntegrationSyncLog[]
+  remediationActions RemediationAction[]
+  remediationBatches RemediationBatch[]
 
-    @@index([organizationId])
-    @@index([providerId])
-    @@index([providerId, organizationId])
-    @@index([status])
+  @@index([organizationId])
+  @@index([providerId])
+  @@index([providerId, organizationId])
+  @@index([status])
 }
 
 enum IntegrationConnectionStatus {
-    pending // Awaiting credential setup
-    active // Connected and operational
-    error // Connection has errors
-    paused // Manually paused by user
-    disconnected // User disconnected
+  pending // Awaiting credential setup
+  active // Connected and operational
+  error // Connection has errors
+  paused // Manually paused by user
+  disconnected // User disconnected
 }
 
 /// Stores encrypted credentials with versioning for audit trail
 model IntegrationCredentialVersion {
-    id String @id @default(dbgenerated("generate_prefixed_cuid('icv'::text)"))
+  id String @id @default(dbgenerated("generate_prefixed_cuid('icv'::text)"))
 
-    /// Parent connection
-    connectionId String
-    connection   IntegrationConnection @relation(fields: [connectionId], references: [id], onDelete: Cascade)
+  /// Parent connection
+  connectionId String
+  connection   IntegrationConnection @relation(fields: [connectionId], references: [id], onDelete: Cascade)
 
-    /// Encrypted credential payload (JSON with encrypted fields)
-    encryptedPayload Json
+  /// Encrypted credential payload (JSON with encrypted fields)
+  encryptedPayload Json
 
-    /// Version number (auto-increment per connection)
-    version Int
+  /// Version number (auto-increment per connection)
+  version Int
 
-    /// Token expiration (for OAuth tokens)
-    expiresAt DateTime?
+  /// Token expiration (for OAuth tokens)
+  expiresAt DateTime?
 
-    /// When this version was rotated/replaced
-    rotatedAt DateTime?
+  /// When this version was rotated/replaced
+  rotatedAt DateTime?
 
-    createdAt DateTime @default(now())
+  createdAt DateTime @default(now())
 
-    @@unique([connectionId, version])
-    @@index([connectionId])
+  @@unique([connectionId, version])
+  @@index([connectionId])
 }
 
 /// Records each sync/job execution for audit and debugging
 model IntegrationRun {
-    id String @id @default(dbgenerated("generate_prefixed_cuid('irn'::text)"))
+  id String @id @default(dbgenerated("generate_prefixed_cuid('irn'::text)"))
 
-    /// Parent connection
-    connectionId String
-    connection   IntegrationConnection @relation(fields: [connectionId], references: [id], onDelete: Cascade)
+  /// Parent connection
+  connectionId String
+  connection   IntegrationConnection @relation(fields: [connectionId], references: [id], onDelete: Cascade)
 
-    /// Type of job
-    jobType IntegrationRunJobType
+  /// Type of job
+  jobType IntegrationRunJobType
 
-    /// Execution status
-    status IntegrationRunStatus @default(pending)
+  /// Execution status
+  status IntegrationRunStatus @default(pending)
 
-    /// Timestamps
-    startedAt   DateTime?
-    completedAt DateTime?
+  /// Timestamps
+  startedAt   DateTime?
+  completedAt DateTime?
 
-    /// Duration in milliseconds
-    durationMs Int?
+  /// Duration in milliseconds
+  durationMs Int?
 
-    /// Number of findings from this run
-    findingsCount Int @default(0)
+  /// Number of findings from this run
+  findingsCount Int @default(0)
 
-    /// Error details if failed
-    error Json?
+  /// Error details if failed
+  error Json?
 
-    /// Additional metadata (trigger source, cursor, etc.)
-    metadata Json?
+  /// Additional metadata (trigger source, cursor, etc.)
+  metadata Json?
 
-    createdAt DateTime @default(now())
+  createdAt DateTime @default(now())
 
-    findings IntegrationPlatformFinding[]
+  findings IntegrationPlatformFinding[]
 
-    @@index([connectionId])
-    @@index([status])
-    @@index([createdAt])
+  @@index([connectionId])
+  @@index([status])
+  @@index([createdAt])
 }
 
 enum IntegrationRunJobType {
-    full_sync
-    delta_sync
-    webhook
-    manual
-    test_connection
+  full_sync
+  delta_sync
+  webhook
+  manual
+  test_connection
 }
 
 enum IntegrationRunStatus {
-    pending
-    running
-    success
-    failed
-    cancelled
+  pending
+  running
+  success
+  failed
+  cancelled
 }
 
 /// Stores findings/results from integration syncs
 model IntegrationPlatformFinding {
-    id String @id @default(dbgenerated("generate_prefixed_cuid('ipf'::text)"))
+  id String @id @default(dbgenerated("generate_prefixed_cuid('ipf'::text)"))
 
-    /// Parent run (optional - webhooks may not have runs)
-    runId String?
-    run   IntegrationRun? @relation(fields: [runId], references: [id], onDelete: SetNull)
+  /// Parent run (optional - webhooks may not have runs)
+  runId String?
+  run   IntegrationRun? @relation(fields: [runId], references: [id], onDelete: SetNull)
 
-    /// Parent connection
-    connectionId String
-    connection   IntegrationConnection @relation(fields: [connectionId], references: [id], onDelete: Cascade)
+  /// Parent connection
+  connectionId String
+  connection   IntegrationConnection @relation(fields: [connectionId], references: [id], onDelete: Cascade)
 
-    /// Resource classification
-    resourceType String
-    resourceId   String
+  /// Resource classification
+  resourceType String
+  resourceId   String
 
-    /// Finding details
-    title       String
-    description String?
+  /// Finding details
+  title       String
+  description String?
 
-    /// Severity level
-    severity IntegrationFindingSeverity @default(info)
+  /// Severity level
+  severity IntegrationFindingSeverity @default(info)
 
-    /// Finding status
-    status IntegrationFindingStatus @default(open)
+  /// Finding status
+  status IntegrationFindingStatus @default(open)
 
-    /// Remediation guidance
-    remediation String?
+  /// Remediation guidance
+  remediation String?
 
-    /// Raw payload from provider
-    rawPayload Json?
+  /// Raw payload from provider
+  rawPayload Json?
 
-    createdAt DateTime @default(now())
-    updatedAt DateTime @updatedAt
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
 
-    @@index([connectionId])
-    @@index([runId])
-    @@index([resourceType, resourceId])
-    @@index([severity])
-    @@index([status])
+  @@index([connectionId])
+  @@index([runId])
+  @@index([resourceType, resourceId])
+  @@index([severity])
+  @@index([status])
 }
 
 enum IntegrationFindingSeverity {
-    info
-    low
-    medium
-    high
-    critical
+  info
+  low
+  medium
+  high
+  critical
 }
 
 enum IntegrationFindingStatus {
-    open
-    resolved
-    ignored
+  open
+  resolved
+  ignored
 }
 
 /// Stores OAuth state for CSRF protection during OAuth flow
 model IntegrationOAuthState {
-    id String @id @default(dbgenerated("generate_prefixed_cuid('ios'::text)"))
+  id String @id @default(dbgenerated("generate_prefixed_cuid('ios'::text)"))
 
-    /// Random state parameter
-    state String @unique
+  /// Random state parameter
+  state String @unique
 
-    /// Provider slug
-    providerSlug String
+  /// Provider slug
+  providerSlug String
 
-    /// Organization initiating the OAuth
-    organizationId String
+  /// Organization initiating the OAuth
+  organizationId String
 
-    /// User initiating the OAuth
-    userId String
+  /// User initiating the OAuth
+  userId String
 
-    /// PKCE code verifier (if using PKCE)
-    codeVerifier String?
+  /// PKCE code verifier (if using PKCE)
+  codeVerifier String?
 
-    /// Redirect URL after OAuth completes
-    redirectUrl String?
+  /// Redirect URL after OAuth completes
+  redirectUrl String?
 
-    /// Expiration timestamp
-    expiresAt DateTime
+  /// Expiration timestamp
+  expiresAt DateTime
 
-    createdAt DateTime @default(now())
+  createdAt DateTime @default(now())
 
-    @@index([state])
-    @@index([expiresAt])
+  @@index([state])
+  @@index([expiresAt])
 }
 
 /// Stores organization-level OAuth app credentials
 /// Allows orgs (especially self-hosters) to use their own OAuth apps
 model IntegrationOAuthApp {
-    id String @id @default(dbgenerated("generate_prefixed_cuid('ioa'::text)"))
+  id String @id @default(dbgenerated("generate_prefixed_cuid('ioa'::text)"))
 
-    /// Provider slug (e.g., "github", "slack")
-    providerSlug String
+  /// Provider slug (e.g., "github", "slack")
+  providerSlug String
 
-    /// Organization that owns this OAuth app config
-    organizationId String
-    organization   Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade)
+  /// Organization that owns this OAuth app config
+  organizationId String
+  organization   Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade)
 
-    /// Encrypted client ID
-    encryptedClientId Json
+  /// Encrypted client ID
+  encryptedClientId Json
 
-    /// Encrypted client secret
-    encryptedClientSecret Json
+  /// Encrypted client secret
+  encryptedClientSecret Json
 
-    /// Optional: custom scopes (overrides manifest defaults)
-    customScopes String[]
+  /// Optional: custom scopes (overrides manifest defaults)
+  customScopes String[]
 
-    /// Provider-specific settings (e.g., Rippling app name for authorize URL)
-    /// Stored as JSON: { "appName": "compai533c" }
-    customSettings Json?
+  /// Provider-specific settings (e.g., Rippling app name for authorize URL)
+  /// Stored as JSON: { "appName": "compai533c" }
+  customSettings Json?
 
-    /// Whether this config is active
-    isActive Boolean @default(true)
+  /// Whether this config is active
+  isActive Boolean @default(true)
 
-    createdAt DateTime @default(now())
-    updatedAt DateTime @updatedAt
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
 
-    @@unique([providerSlug, organizationId])
-    @@index([organizationId])
-    @@index([providerSlug])
+  @@unique([providerSlug, organizationId])
+  @@index([organizationId])
+  @@index([providerSlug])
 }
 
 /// Records check runs linked to tasks for compliance verification
 model IntegrationCheckRun {
-    id String @id @default(dbgenerated("generate_prefixed_cuid('icr'::text)"))
+  id String @id @default(dbgenerated("generate_prefixed_cuid('icr'::text)"))
 
-    /// Parent connection
-    connectionId String
-    connection   IntegrationConnection @relation(fields: [connectionId], references: [id], onDelete: Cascade)
+  /// Parent connection
+  connectionId String
+  connection   IntegrationConnection @relation(fields: [connectionId], references: [id], onDelete: Cascade)
 
-    /// Task being verified (optional - checks can run without a task)
-    taskId String?
-    task   Task?   @relation(fields: [taskId], references: [id], onDelete: SetNull)
+  /// Task being verified (optional - checks can run without a task)
+  taskId String?
+  task   Task?   @relation(fields: [taskId], references: [id], onDelete: SetNull)
 
-    /// Check ID from the manifest
-    checkId String
+  /// Check ID from the manifest
+  checkId String
 
-    /// Check name (denormalized for display)
-    checkName String
+  /// Check name (denormalized for display)
+  checkName String
 
-    /// Execution status
-    status IntegrationRunStatus @default(pending)
+  /// Execution status
+  status IntegrationRunStatus @default(pending)
 
-    /// Timestamps
-    startedAt   DateTime?
-    completedAt DateTime?
+  /// Timestamps
+  startedAt   DateTime?
+  completedAt DateTime?
 
-    /// Duration in milliseconds
-    durationMs Int?
+  /// Duration in milliseconds
+  durationMs Int?
 
-    /// Summary counts
-    totalChecked Int @default(0)
-    passedCount  Int @default(0)
-    failedCount  Int @default(0)
+  /// Summary counts
+  totalChecked Int @default(0)
+  passedCount  Int @default(0)
+  failedCount  Int @default(0)
 
-    /// Error message if failed
-    errorMessage String?
+  /// Error message if failed
+  errorMessage String?
 
-    /// Full execution logs (JSON array)
-    logs Json?
+  /// Full execution logs (JSON array)
+  logs Json?
 
-    createdAt DateTime @default(now())
+  createdAt DateTime @default(now())
 
-    /// Results from this check run
-    results IntegrationCheckResult[]
+  /// Results from this check run
+  results IntegrationCheckResult[]
 
-    @@index([connectionId])
-    @@index([taskId])
-    @@index([checkId])
-    @@index([status])
-    @@index([createdAt])
+  @@index([connectionId])
+  @@index([taskId])
+  @@index([checkId])
+  @@index([status])
+  @@index([createdAt])
 }
 
 /// Stores individual results (pass/fail) from check runs
 model IntegrationCheckResult {
-    id String @id @default(dbgenerated("generate_prefixed_cuid('icx'::text)"))
+  id String @id @default(dbgenerated("generate_prefixed_cuid('icx'::text)"))
 
-    /// Parent check run
-    checkRunId String
-    checkRun   IntegrationCheckRun @relation(fields: [checkRunId], references: [id], onDelete: Cascade)
+  /// Parent check run
+  checkRunId String
+  checkRun   IntegrationCheckRun @relation(fields: [checkRunId], references: [id], onDelete: Cascade)
 
-    /// Whether this result is a pass or fail
-    passed Boolean
+  /// Whether this result is a pass or fail
+  passed Boolean
 
-    /// Resource classification
-    resourceType String
-    resourceId   String
+  /// Resource classification
+  resourceType String
+  resourceId   String
 
-    /// Result details
-    title       String
-    description String?
+  /// Result details
+  title       String
+  description String?
 
-    /// Severity (for failures)
-    severity IntegrationFindingSeverity?
+  /// Severity (for failures)
+  severity IntegrationFindingSeverity?
 
-    /// Remediation guidance (for failures)
-    remediation String?
+  /// Remediation guidance (for failures)
+  remediation String?
 
-    /// Evidence/proof (JSON - API response data)
-    evidence Json?
+  /// Evidence/proof (JSON - API response data)
+  evidence Json?
 
-    /// When this evidence was collected
-    collectedAt DateTime @default(now())
+  /// When this evidence was collected
+  collectedAt DateTime @default(now())
 
-    remediationActions RemediationAction[]
+  remediationActions RemediationAction[]
 
-    @@index([checkRunId])
-    @@index([passed])
-    @@index([resourceType, resourceId])
+  @@index([checkRunId])
+  @@index([passed])
+  @@index([resourceType, resourceId])
 }
 
 /// Stores platform-wide OAuth app credentials
 /// Used by platform operators to provide default OAuth apps for all users
 model IntegrationPlatformCredential {
-    id String @id @default(dbgenerated("generate_prefixed_cuid('ipc'::text)"))
+  id String @id @default(dbgenerated("generate_prefixed_cuid('ipc'::text)"))
 
-    /// Provider slug (e.g., "github", "slack") - unique per platform
-    providerSlug String @unique
+  /// Provider slug (e.g., "github", "slack") - unique per platform
+  providerSlug String @unique
 
-    /// Encrypted client ID
-    encryptedClientId Json
+  /// Encrypted client ID
+  encryptedClientId Json
 
-    /// Encrypted client secret
-    encryptedClientSecret Json
+  /// Encrypted client secret
+  encryptedClientSecret Json
 
-    /// Masked display hint for client ID (computed at write time)
-    clientIdHint String?
+  /// Masked display hint for client ID (computed at write time)
+  clientIdHint String?
 
-    /// Masked display hint for client secret (computed at write time)
-    clientSecretHint String?
+  /// Masked display hint for client secret (computed at write time)
+  clientSecretHint String?
 
-    /// Optional: custom scopes (overrides manifest defaults)
-    customScopes String[]
+  /// Optional: custom scopes (overrides manifest defaults)
+  customScopes String[]
 
-    /// Provider-specific settings (e.g., Rippling app name for authorize URL)
-    /// Stored as JSON: { "appName": "compai533c" }
-    customSettings Json?
+  /// Provider-specific settings (e.g., Rippling app name for authorize URL)
+  /// Stored as JSON: { "appName": "compai533c" }
+  customSettings Json?
 
-    /// Whether this credential is active
-    isActive Boolean @default(true)
+  /// Whether this credential is active
+  isActive Boolean @default(true)
 
-    /// Who created this credential
-    createdById String?
+  /// Who created this credential
+  createdById String?
 
-    /// Who last updated this credential
-    updatedById String?
+  /// Who last updated this credential
+  updatedById String?
 
-    createdAt DateTime @default(now())
-    updatedAt DateTime @updatedAt
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
 
-    @@index([providerSlug])
+  @@index([providerSlug])
 }
diff --git a/packages/db/prisma/schema/integration-sync-log.prisma b/packages/db/prisma/schema/integration-sync-log.prisma
index 5cce4660a4..b57767b7a5 100644
--- a/packages/db/prisma/schema/integration-sync-log.prisma
+++ b/packages/db/prisma/schema/integration-sync-log.prisma
@@ -2,11 +2,11 @@
 // Generic audit trail for integration sync operations (employee sync, role discovery, etc.)
 
 model IntegrationSyncLog {
-  id             String                   @id @default(dbgenerated("generate_prefixed_cuid('isl'::text)"))
+  id             String                @id @default(dbgenerated("generate_prefixed_cuid('isl'::text)"))
   connectionId   String
-  connection     IntegrationConnection    @relation(fields: [connectionId], references: [id], onDelete: Cascade)
+  connection     IntegrationConnection @relation(fields: [connectionId], references: [id], onDelete: Cascade)
   organizationId String
-  organization   Organization             @relation(fields: [organizationId], references: [id], onDelete: Cascade)
+  organization   Organization          @relation(fields: [organizationId], references: [id], onDelete: Cascade)
 
   /// Provider slug (e.g., "google-workspace", "rippling", "jumpcloud")
   provider    String
diff --git a/packages/db/prisma/schema/notification-policy.prisma b/packages/db/prisma/schema/notification-policy.prisma
index 2a789aa955..8674ebc741 100644
--- a/packages/db/prisma/schema/notification-policy.prisma
+++ b/packages/db/prisma/schema/notification-policy.prisma
@@ -1,8 +1,8 @@
 model RoleNotificationSetting {
-  id                   String       @id @default(dbgenerated("generate_prefixed_cuid('rns'::text)"))
-  organizationId       String
-  organization         Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade)
-  role                 String // "owner", "admin", "auditor", "employee", "contractor", or custom role name
+  id             String       @id @default(dbgenerated("generate_prefixed_cuid('rns'::text)"))
+  organizationId String
+  organization   Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade)
+  role           String // "owner", "admin", "auditor", "employee", "contractor", or custom role name
 
   policyNotifications  Boolean @default(true)
   taskReminders        Boolean @default(true)
diff --git a/packages/db/prisma/schema/organization-billing.prisma b/packages/db/prisma/schema/organization-billing.prisma
index ba4c522c10..b6c610ae6a 100644
--- a/packages/db/prisma/schema/organization-billing.prisma
+++ b/packages/db/prisma/schema/organization-billing.prisma
@@ -5,7 +5,7 @@ model OrganizationBilling {
   createdAt        DateTime @default(now()) @map("created_at")
   updatedAt        DateTime @updatedAt @map("updated_at")
 
-  organization        Organization        @relation(fields: [organizationId], references: [id], onDelete: Cascade)
+  organization        Organization         @relation(fields: [organizationId], references: [id], onDelete: Cascade)
   pentestSubscription PentestSubscription?
 
   @@map("organization_billing")
diff --git a/packages/db/prisma/schema/organization.prisma b/packages/db/prisma/schema/organization.prisma
index f6e9111d03..ceadcd5655 100644
--- a/packages/db/prisma/schema/organization.prisma
+++ b/packages/db/prisma/schema/organization.prisma
@@ -1,20 +1,20 @@
 model Organization {
-  id                  String      @id @default(dbgenerated("generate_prefixed_cuid('org'::text)"))
-  name                String
-  slug                String      @unique @default(dbgenerated("generate_prefixed_cuid('slug'::text)"))
-  logo                String?
-  createdAt           DateTime    @default(now())
-  metadata            String?
-  onboarding          Onboarding?
-  website             String?
-  onboardingCompleted Boolean     @default(false)
-  hasAccess           Boolean     @default(false)
-  advancedModeEnabled             Boolean     @default(false)
-  evidenceApprovalEnabled         Boolean     @default(false)
-  deviceAgentStepEnabled          Boolean     @default(true)
-  securityTrainingStepEnabled     Boolean     @default(true)
-  whistleblowerReportEnabled      Boolean     @default(true)
-  accessRequestFormEnabled        Boolean     @default(true)
+  id                          String      @id @default(dbgenerated("generate_prefixed_cuid('org'::text)"))
+  name                        String
+  slug                        String      @unique @default(dbgenerated("generate_prefixed_cuid('slug'::text)"))
+  logo                        String?
+  createdAt                   DateTime    @default(now())
+  metadata                    String?
+  onboarding                  Onboarding?
+  website                     String?
+  onboardingCompleted         Boolean     @default(false)
+  hasAccess                   Boolean     @default(false)
+  advancedModeEnabled         Boolean     @default(false)
+  evidenceApprovalEnabled     Boolean     @default(false)
+  deviceAgentStepEnabled      Boolean     @default(true)
+  securityTrainingStepEnabled Boolean     @default(true)
+  whistleblowerReportEnabled  Boolean     @default(true)
+  accessRequestFormEnabled    Boolean     @default(true)
 
   // FleetDM
   fleetDmLabelId        Int?
@@ -78,11 +78,11 @@ model Organization {
   organizationChart OrganizationChart?
 
   // RBAC
-  organizationRoles          OrganizationRole[]
-  roleNotificationSettings   RoleNotificationSetting[]
+  organizationRoles        OrganizationRole[]
+  roleNotificationSettings RoleNotificationSetting[]
 
   // Timeline
-  timelineInstances          TimelineInstance[]
+  timelineInstances TimelineInstance[]
 
   // Custom frameworks / requirements authored by this org
   customFrameworks   CustomFramework[]
diff --git a/packages/db/prisma/schema/policy.prisma b/packages/db/prisma/schema/policy.prisma
index 945e203c52..461ec471b6 100644
--- a/packages/db/prisma/schema/policy.prisma
+++ b/packages/db/prisma/schema/policy.prisma
@@ -4,7 +4,7 @@ enum PolicyDisplayFormat {
 }
 
 enum PolicyVisibility {
-  ALL        // Visible to everyone in organization
+  ALL // Visible to everyone in organization
   DEPARTMENT // Only visible to specified departments
 }
 
@@ -66,8 +66,8 @@ model PolicyVersion {
   updatedAt DateTime @updatedAt
 
   // Relations
-  policyId String
-  policy   Policy @relation("PolicyVersions", fields: [policyId], references: [id], onDelete: Cascade)
+  policyId         String
+  policy           Policy  @relation("PolicyVersions", fields: [policyId], references: [id], onDelete: Cascade)
   currentForPolicy Policy? @relation("PolicyCurrentVersion")
 
   // Version details
diff --git a/packages/db/prisma/schema/remediation-action.prisma b/packages/db/prisma/schema/remediation-action.prisma
index c43e6a6795..e84d34aba0 100644
--- a/packages/db/prisma/schema/remediation-action.prisma
+++ b/packages/db/prisma/schema/remediation-action.prisma
@@ -1,28 +1,28 @@
 model RemediationAction {
-    id             String   @id @default(dbgenerated("generate_prefixed_cuid('rma'::text)"))
-    checkResultId  String
-    connectionId   String
-    organizationId String
-    initiatedById  String
-    remediationKey String
-    resourceId     String
-    resourceType   String
-    previousState  Json
-    appliedState   Json
-    status         String   @default("pending")
-    riskLevel      String?
-    acknowledgmentText String?
-    acknowledgedAt DateTime?
-    errorMessage   String?
-    executedAt     DateTime?
-    rolledBackAt   DateTime?
-    createdAt      DateTime @default(now())
-    updatedAt      DateTime @updatedAt
+  id                 String    @id @default(dbgenerated("generate_prefixed_cuid('rma'::text)"))
+  checkResultId      String
+  connectionId       String
+  organizationId     String
+  initiatedById      String
+  remediationKey     String
+  resourceId         String
+  resourceType       String
+  previousState      Json
+  appliedState       Json
+  status             String    @default("pending")
+  riskLevel          String?
+  acknowledgmentText String?
+  acknowledgedAt     DateTime?
+  errorMessage       String?
+  executedAt         DateTime?
+  rolledBackAt       DateTime?
+  createdAt          DateTime  @default(now())
+  updatedAt          DateTime  @updatedAt
 
-    checkResult IntegrationCheckResult @relation(fields: [checkResultId], references: [id], onDelete: Cascade)
-    connection  IntegrationConnection  @relation(fields: [connectionId], references: [id], onDelete: Cascade)
+  checkResult IntegrationCheckResult @relation(fields: [checkResultId], references: [id], onDelete: Cascade)
+  connection  IntegrationConnection  @relation(fields: [connectionId], references: [id], onDelete: Cascade)
 
-    @@index([connectionId])
-    @@index([organizationId])
-    @@index([checkResultId])
+  @@index([connectionId])
+  @@index([organizationId])
+  @@index([checkResultId])
 }
diff --git a/packages/db/prisma/schema/remediation-batch.prisma b/packages/db/prisma/schema/remediation-batch.prisma
index 7ae3f446ea..28eccf2d31 100644
--- a/packages/db/prisma/schema/remediation-batch.prisma
+++ b/packages/db/prisma/schema/remediation-batch.prisma
@@ -1,20 +1,20 @@
 model RemediationBatch {
-    id             String   @id @default(dbgenerated("generate_prefixed_cuid('rmb'::text)"))
-    connectionId   String
-    organizationId String
-    initiatedById  String
-    triggerRunId   String?
-    status         String   @default("pending") // pending, running, done, cancelled
-    findings       Json     @default("[]") // Array of { id, key, title, status, error? }
-    fixed          Int      @default(0)
-    skipped        Int      @default(0)
-    failed         Int      @default(0)
-    createdAt      DateTime @default(now())
-    updatedAt      DateTime @updatedAt
+  id             String   @id @default(dbgenerated("generate_prefixed_cuid('rmb'::text)"))
+  connectionId   String
+  organizationId String
+  initiatedById  String
+  triggerRunId   String?
+  status         String   @default("pending") // pending, running, done, cancelled
+  findings       Json     @default("[]") // Array of { id, key, title, status, error? }
+  fixed          Int      @default(0)
+  skipped        Int      @default(0)
+  failed         Int      @default(0)
+  createdAt      DateTime @default(now())
+  updatedAt      DateTime @updatedAt
 
-    connection IntegrationConnection @relation(fields: [connectionId], references: [id], onDelete: Cascade)
+  connection IntegrationConnection @relation(fields: [connectionId], references: [id], onDelete: Cascade)
 
-    @@index([connectionId])
-    @@index([organizationId])
-    @@index([status])
+  @@index([connectionId])
+  @@index([organizationId])
+  @@index([status])
 }
diff --git a/packages/db/prisma/schema/security-penetration-test-run.prisma b/packages/db/prisma/schema/security-penetration-test-run.prisma
index 033a5f31f4..8a2ee79548 100644
--- a/packages/db/prisma/schema/security-penetration-test-run.prisma
+++ b/packages/db/prisma/schema/security-penetration-test-run.prisma
@@ -1,9 +1,9 @@
 model SecurityPenetrationTestRun {
-  id           String   @id @default(dbgenerated("generate_prefixed_cuid('ptr'::text)"))
-  organizationId String @map("organization_id")
-  providerRunId String  @map("provider_run_id")
-  createdAt    DateTime @default(now()) @map("created_at")
-  updatedAt    DateTime @updatedAt @map("updated_at")
+  id             String   @id @default(dbgenerated("generate_prefixed_cuid('ptr'::text)"))
+  organizationId String   @map("organization_id")
+  providerRunId  String   @map("provider_run_id")
+  createdAt      DateTime @default(now()) @map("created_at")
+  updatedAt      DateTime @updatedAt @map("updated_at")
 
   organization Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade)
 
diff --git a/packages/db/prisma/schema/soa.prisma b/packages/db/prisma/schema/soa.prisma
index d3f28d386f..d8b1de1554 100644
--- a/packages/db/prisma/schema/soa.prisma
+++ b/packages/db/prisma/schema/soa.prisma
@@ -60,9 +60,9 @@ model SOADocument {
   answeredQuestions Int @default(0) // Number of questions with answers
 
   // Approval tracking
-  preparedBy String  @default("Comp AI") // Always "Comp AI"
+  preparedBy String    @default("Comp AI") // Always "Comp AI"
   approverId String? // Member ID who will approve this document (set when submitted for approval)
-  approver   Member? @relation("SOADocumentApprover", fields: [approverId], references: [id], onDelete: SetNull, onUpdate: Cascade)
+  approver   Member?   @relation("SOADocumentApprover", fields: [approverId], references: [id], onDelete: SetNull, onUpdate: Cascade)
   approvedAt DateTime? // When document was approved
 
   // Dates
diff --git a/packages/db/prisma/schema/task-item.prisma b/packages/db/prisma/schema/task-item.prisma
index f0da7a8331..8141176e82 100644
--- a/packages/db/prisma/schema/task-item.prisma
+++ b/packages/db/prisma/schema/task-item.prisma
@@ -1,32 +1,32 @@
 model TaskItem {
-  id          String            @id @default(dbgenerated("generate_prefixed_cuid('tski'::text)"))
+  id          String           @id @default(dbgenerated("generate_prefixed_cuid('tski'::text)"))
   title       String
   description String?
-  status      TaskItemStatus    @default(todo)
-  priority    TaskItemPriority  @default(medium)
-  
+  status      TaskItemStatus   @default(todo)
+  priority    TaskItemPriority @default(medium)
+
   // Polymorphic relation (like Comment and Attachment)
   entityId   String
   entityType TaskItemEntityType
-  
+
   // Assignment (nullable)
-  assigneeId  String?
-  assignee   Member?           @relation("TaskItemAssignee", fields: [assigneeId], references: [id], onDelete: SetNull)
-  
+  assigneeId String?
+  assignee   Member? @relation("TaskItemAssignee", fields: [assigneeId], references: [id], onDelete: SetNull)
+
   // Creator & Updater
   createdById String
-  createdBy   Member           @relation("TaskItemCreator", fields: [createdById], references: [id])
+  createdBy   Member  @relation("TaskItemCreator", fields: [createdById], references: [id])
   updatedById String?
-  updatedBy   Member?          @relation("TaskItemUpdater", fields: [updatedById], references: [id])
-  
+  updatedBy   Member? @relation("TaskItemUpdater", fields: [updatedById], references: [id])
+
   // Relationships
   organizationId String
   organization   Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade)
-  
+
   // Dates
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
-  
+
   @@index([entityId, entityType])
   @@index([organizationId])
   @@index([assigneeId])
@@ -52,4 +52,4 @@ enum TaskItemPriority {
 enum TaskItemEntityType {
   vendor
   risk
-}
\ No newline at end of file
+}
diff --git a/packages/db/prisma/schema/task.prisma b/packages/db/prisma/schema/task.prisma
index 1872ea549e..020fc904fd 100644
--- a/packages/db/prisma/schema/task.prisma
+++ b/packages/db/prisma/schema/task.prisma
@@ -1,13 +1,15 @@
 model Task {
   // Metadata
-  id          String         @id @default(dbgenerated("generate_prefixed_cuid('tsk'::text)"))
-  title       String
-  description String
-  status           TaskStatus           @default(todo)
-  automationStatus TaskAutomationStatus @default(AUTOMATED)
-  frequency        TaskFrequency?
-  department  Departments?   @default(none)
-  order       Int            @default(0)
+  id                           String               @id @default(dbgenerated("generate_prefixed_cuid('tsk'::text)"))
+  title                        String
+  description                  String
+  status                       TaskStatus           @default(todo)
+  automationStatus             TaskAutomationStatus @default(AUTOMATED)
+  frequency                    TaskFrequency?
+  integrationScheduleFrequency TaskFrequency        @default(daily)
+  integrationLastRunAt         DateTime?
+  department                   Departments?         @default(none)
+  order                        Int                  @default(0)
 
   // Dates
   createdAt       DateTime  @default(now())
@@ -29,8 +31,8 @@ model Task {
   browserAutomations  BrowserAutomation[]
 
   evidenceAutomationRuns EvidenceAutomationRun[]
-  integrationCheckRuns  IntegrationCheckRun[]
-  findings              Finding[]
+  integrationCheckRuns   IntegrationCheckRun[]
+  findings               Finding[]
 
   // Evidence approval
   approverId     String?
diff --git a/packages/db/prisma/schema/timeline.prisma b/packages/db/prisma/schema/timeline.prisma
index 7f3d63ee30..44f546bbab 100644
--- a/packages/db/prisma/schema/timeline.prisma
+++ b/packages/db/prisma/schema/timeline.prisma
@@ -45,75 +45,75 @@ model TimelineTemplate {
 }
 
 model TimelinePhaseTemplate {
-  id                   String              @id @default(dbgenerated("generate_prefixed_cuid('tpt'::text)"))
-  templateId           String
-  name                 String
-  description          String?
-  groupLabel           String?
-  orderIndex           Int
-  defaultDurationWeeks Int
-  completionType       PhaseCompletionType @default(MANUAL)
-  locksTimelineOnComplete Boolean          @default(false)
-  createdAt            DateTime            @default(now())
-  updatedAt            DateTime            @updatedAt
+  id                      String              @id @default(dbgenerated("generate_prefixed_cuid('tpt'::text)"))
+  templateId              String
+  name                    String
+  description             String?
+  groupLabel              String?
+  orderIndex              Int
+  defaultDurationWeeks    Int
+  completionType          PhaseCompletionType @default(MANUAL)
+  locksTimelineOnComplete Boolean             @default(false)
+  createdAt               DateTime            @default(now())
+  updatedAt               DateTime            @updatedAt
 
   template TimelineTemplate @relation(fields: [templateId], references: [id], onDelete: Cascade)
   phases   TimelinePhase[]
 }
 
 model TimelineInstance {
-  id                 String         @id @default(dbgenerated("generate_prefixed_cuid('tli'::text)"))
-  organizationId     String
+  id                  String         @id @default(dbgenerated("generate_prefixed_cuid('tli'::text)"))
+  organizationId      String
   frameworkInstanceId String
-  templateId         String
-  trackKey           String         @default("primary")
-  cycleNumber        Int
-  status             TimelineStatus @default(DRAFT)
-  startDate          DateTime?
-  pausedAt           DateTime?
-  lockedAt           DateTime?
-  lockedById         String?
-  unlockedAt         DateTime?
-  unlockedById       String?
-  unlockReason       String?
-  completedAt        DateTime?
-  createdAt          DateTime       @default(now())
-  updatedAt          DateTime       @updatedAt
+  templateId          String
+  trackKey            String         @default("primary")
+  cycleNumber         Int
+  status              TimelineStatus @default(DRAFT)
+  startDate           DateTime?
+  pausedAt            DateTime?
+  lockedAt            DateTime?
+  lockedById          String?
+  unlockedAt          DateTime?
+  unlockedById        String?
+  unlockReason        String?
+  completedAt         DateTime?
+  createdAt           DateTime       @default(now())
+  updatedAt           DateTime       @updatedAt
 
-  organization     Organization     @relation(fields: [organizationId], references: [id], onDelete: Cascade)
+  organization      Organization      @relation(fields: [organizationId], references: [id], onDelete: Cascade)
   frameworkInstance FrameworkInstance @relation(fields: [frameworkInstanceId], references: [id], onDelete: Cascade)
-  template         TimelineTemplate @relation(fields: [templateId], references: [id])
-  lockedBy         User?            @relation("TimelineInstanceLockedBy", fields: [lockedById], references: [id])
-  unlockedBy       User?            @relation("TimelineInstanceUnlockedBy", fields: [unlockedById], references: [id])
-  phases           TimelinePhase[]
+  template          TimelineTemplate  @relation(fields: [templateId], references: [id])
+  lockedBy          User?             @relation("TimelineInstanceLockedBy", fields: [lockedById], references: [id])
+  unlockedBy        User?             @relation("TimelineInstanceUnlockedBy", fields: [unlockedById], references: [id])
+  phases            TimelinePhase[]
 
   @@unique([frameworkInstanceId, trackKey, cycleNumber])
 }
 
 model TimelinePhase {
-  id               String              @id @default(dbgenerated("generate_prefixed_cuid('tlp'::text)"))
-  instanceId       String
-  phaseTemplateId  String?
-  name             String
-  description      String?
-  groupLabel       String?
-  orderIndex       Int
-  status           TimelinePhaseStatus @default(PENDING)
-  startDate        DateTime?
-  endDate          DateTime?
-  durationWeeks    Int
-  completionType   PhaseCompletionType @default(MANUAL)
-  locksTimelineOnComplete Boolean       @default(false)
-  regressedAt       DateTime?
-  datesPinned      Boolean             @default(false)
-  completedAt      DateTime?
-  completedById    String?
-  readyForReview   Boolean             @default(false)
-  readyForReviewAt DateTime?
-  documentUrl      String?
-  documentName     String?
-  createdAt        DateTime            @default(now())
-  updatedAt        DateTime            @updatedAt
+  id                      String              @id @default(dbgenerated("generate_prefixed_cuid('tlp'::text)"))
+  instanceId              String
+  phaseTemplateId         String?
+  name                    String
+  description             String?
+  groupLabel              String?
+  orderIndex              Int
+  status                  TimelinePhaseStatus @default(PENDING)
+  startDate               DateTime?
+  endDate                 DateTime?
+  durationWeeks           Int
+  completionType          PhaseCompletionType @default(MANUAL)
+  locksTimelineOnComplete Boolean             @default(false)
+  regressedAt             DateTime?
+  datesPinned             Boolean             @default(false)
+  completedAt             DateTime?
+  completedById           String?
+  readyForReview          Boolean             @default(false)
+  readyForReviewAt        DateTime?
+  documentUrl             String?
+  documentName            String?
+  createdAt               DateTime            @default(now())
+  updatedAt               DateTime            @updatedAt
 
   instance      TimelineInstance       @relation(fields: [instanceId], references: [id], onDelete: Cascade)
   phaseTemplate TimelinePhaseTemplate? @relation(fields: [phaseTemplateId], references: [id])

From a27bc431c8a2ef84c2d2980b545ede469e5c6196 Mon Sep 17 00:00:00 2001
From: Mariano Fuentes <marfuen98@gmail.com>
Date: Sat, 25 Apr 2026 09:48:03 -0700
Subject: [PATCH 33/40] chore(db): publish flattened dist/schema.prisma for
 external consumers (#2677)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The native v7 multi-file schema refactor (c58045f) removed the legacy
combine-schemas step that produced a single-file schema in dist/. That
worked inside the monorepo (apps read prisma/schema/ directly), but
broke external consumers like comp-private's enterprise-api/cx-dashboard/
framework-editor/trust apps, which all run

  cp ../../node_modules/@trycompai/db/dist/schema.prisma prisma/schema.prisma

at build time. The 2.0.1 publish was the first to consume the post-
refactor build, and shipped without dist/schema.prisma — breaking every
consumer's db:getschema script and blocking SALE-49's comp-private PR.

Add scripts/build-dist-schema.js: concatenates prisma/schema/*.prisma
(schema.prisma generator+datasource first, models alphabetically after)
into dist/schema.prisma during build. Output matches the v2.0.0 shape
exactly so consumers don't need to change. Wire into the build script
after tsc.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 packages/db/package.json                 |  2 +-
 packages/db/scripts/build-dist-schema.js | 37 ++++++++++++++++++++++++
 2 files changed, 38 insertions(+), 1 deletion(-)
 create mode 100644 packages/db/scripts/build-dist-schema.js

diff --git a/packages/db/package.json b/packages/db/package.json
index adfa4d79d4..c5aafc210b 100644
--- a/packages/db/package.json
+++ b/packages/db/package.json
@@ -44,7 +44,7 @@
     },
     "scripts": {
         "backfill:framework-versions": "bun src/scripts/backfill-framework-versions.ts",
-        "build": "rm -rf dist && node scripts/generate-prisma-client-js.js && tsc",
+        "build": "rm -rf dist && node scripts/generate-prisma-client-js.js && tsc && node scripts/build-dist-schema.js",
         "check-types": "tsc --noEmit",
         "db:generate": "node scripts/generate-prisma-client-js.js",
         "db:migrate": "prisma migrate dev",
diff --git a/packages/db/scripts/build-dist-schema.js b/packages/db/scripts/build-dist-schema.js
new file mode 100644
index 0000000000..54ee61176e
--- /dev/null
+++ b/packages/db/scripts/build-dist-schema.js
@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+/**
+ * Builds dist/schema.prisma from prisma/schema/*.prisma so consumers that
+ * pull from the published @trycompai/db package (e.g. comp-private apps,
+ * which run `cp .../@trycompai/db/dist/schema.prisma prisma/schema.prisma`)
+ * receive a single, ready-to-use schema.
+ *
+ * Native multi-file Prisma v7 schemas live in `prisma/schema/`. Inside the
+ * monorepo, consumers can read those files directly. Outside the monorepo
+ * they cannot, so we ship a flattened copy in dist/.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const root = path.join(__dirname, '..');
+const schemaDir = path.join(root, 'prisma/schema');
+const distDir = path.join(root, 'dist');
+const outFile = path.join(distDir, 'schema.prisma');
+
+if (!fs.existsSync(distDir)) fs.mkdirSync(distDir, { recursive: true });
+
+// schema.prisma (generator + datasource) must come first; everything else
+// after, in deterministic order.
+const all = fs.readdirSync(schemaDir).filter((f) => f.endsWith('.prisma'));
+const ordered = [
+  'schema.prisma',
+  ...all.filter((f) => f !== 'schema.prisma').sort(),
+];
+
+const parts = ordered.map((file) => {
+  const body = fs.readFileSync(path.join(schemaDir, file), 'utf8').trimEnd();
+  if (file === 'schema.prisma') return body;
+  return `// ===== ${file} =====\n${body}`;
+});
+
+fs.writeFileSync(outFile, parts.join('\n\n') + '\n');
+console.log(`[build-dist-schema] wrote ${outFile} (${ordered.length} files)`);

From a0a518b767c83fb9890910317bc201cea6c5c209 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Sat, 25 Apr 2026 12:53:46 -0400
Subject: [PATCH 34/40] [dev] [Marfuen] mariano/fix-db-dist-schema (#2678)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(db): publish flattened dist/schema.prisma for external consumers

The native v7 multi-file schema refactor (c58045f) removed the legacy
combine-schemas step that produced a single-file schema in dist/. That
worked inside the monorepo (apps read prisma/schema/ directly), but
broke external consumers like comp-private's enterprise-api/cx-dashboard/
framework-editor/trust apps, which all run

  cp ../../node_modules/@trycompai/db/dist/schema.prisma prisma/schema.prisma

at build time. The 2.0.1 publish was the first to consume the post-
refactor build, and shipped without dist/schema.prisma — breaking every
consumer's db:getschema script and blocking SALE-49's comp-private PR.

Add scripts/build-dist-schema.js: concatenates prisma/schema/*.prisma
(schema.prisma generator+datasource first, models alphabetically after)
into dist/schema.prisma during build. Output matches the v2.0.0 shape
exactly so consumers don't need to change. Wire into the build script
after tsc.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore(db): align package version with manually-published 2.0.1

The 2.0.1 publish was done manually via `npm publish` and never tagged
in git, so semantic-release would otherwise try to bump from v2.0.0 →
v2.0.1 and conflict with what's already on npm. Setting the source
version to 2.0.1 lines up the package.json with the registry; the next
release bumps to 2.0.2 from this baseline.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Mariano <marfuen98@gmail.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 packages/db/package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/db/package.json b/packages/db/package.json
index c5aafc210b..677692735a 100644
--- a/packages/db/package.json
+++ b/packages/db/package.json
@@ -1,7 +1,7 @@
 {
     "name": "@trycompai/db",
     "description": "Database package with Prisma client and schema for Comp AI",
-    "version": "2.0.0",
+    "version": "2.0.1",
     "dependencies": {
         "@prisma/adapter-pg": "7.6.0",
         "@prisma/client": "7.6.0",

From e8a751b39d79c95e78ec6f18d06b1e711be2175f Mon Sep 17 00:00:00 2001
From: Lewis Carhart <lewis@trycomp.ai>
Date: Mon, 27 Apr 2026 14:37:28 +0100
Subject: [PATCH 35/40] feat: add comprehensive project rules and guidelines
 documentation

- Introduced AGENTS.md to outline project rules, tooling, code style, authentication, API architecture, RBAC, design system, data fetching, testing, database, and Git practices.
- Added SKILL.md files for various auditing skills including design system compliance, hooks and API usage patterns, RBAC, unit tests, and more.
- Established clear conventions for new feature setup, Prisma schema management, and infrastructure practices.

This documentation aims to enhance consistency and quality across the codebase, ensuring all contributors adhere to established standards.
---
 .agents/skills/audit-design-system/SKILL.md   |  23 +
 .agents/skills/audit-hooks/SKILL.md           |  34 ++
 .agents/skills/audit-rbac/SKILL.md            |  42 ++
 .agents/skills/audit-tests/SKILL.md           |  30 ++
 .agents/skills/code/SKILL.md                  | 185 +++++++
 .agents/skills/cursor-usage/SKILL.md          | 269 ++++++++++
 .agents/skills/data/SKILL.md                  | 141 ++++++
 .agents/skills/essentials/SKILL.md            | 108 ++++
 .agents/skills/forms/SKILL.md                 | 180 +++++++
 .agents/skills/infra/SKILL.md                 | 135 +++++
 .agents/skills/new-feature-setup/SKILL.md     | 114 +++++
 .agents/skills/prisma/SKILL.md                | 147 ++++++
 .agents/skills/production-readiness/SKILL.md  |  21 +
 .agents/skills/prompt-engineering/SKILL.md    | 187 +++++++
 .../skills/stale-worktree-cleanup/SKILL.md    | 174 +++++++
 .../skills/trigger-advanced-tasks/SKILL.md    | 460 ++++++++++++++++++
 .agents/skills/trigger-basic/SKILL.md         | 194 ++++++++
 .agents/skills/trigger-config/SKILL.md        | 355 ++++++++++++++
 .agents/skills/trigger-realtime/SKILL.md      | 281 +++++++++++
 .../skills/trigger-scheduled-tasks/SKILL.md   | 126 +++++
 .agents/skills/ui/SKILL.md                    | 137 ++++++
 .claude/skills/code/SKILL.md                  | 185 +++++++
 .claude/skills/cursor-usage/SKILL.md          | 269 ++++++++++
 .claude/skills/data/SKILL.md                  | 141 ++++++
 .claude/skills/essentials/SKILL.md            | 108 ++++
 .claude/skills/forms/SKILL.md                 | 180 +++++++
 .claude/skills/infra/SKILL.md                 | 135 +++++
 .claude/skills/prisma/SKILL.md                | 147 ++++++
 .claude/skills/prompt-engineering/SKILL.md    | 187 +++++++
 .../skills/trigger-advanced-tasks/SKILL.md    | 460 ++++++++++++++++++
 .claude/skills/trigger-basic/SKILL.md         | 194 ++++++++
 .claude/skills/trigger-config/SKILL.md        | 355 ++++++++++++++
 .claude/skills/trigger-realtime/SKILL.md      | 281 +++++++++++
 .../skills/trigger-scheduled-tasks/SKILL.md   | 126 +++++
 .claude/skills/ui/SKILL.md                    | 137 ++++++
 AGENTS.md                                     | 154 ++++++
 36 files changed, 6402 insertions(+)
 create mode 100644 .agents/skills/audit-design-system/SKILL.md
 create mode 100644 .agents/skills/audit-hooks/SKILL.md
 create mode 100644 .agents/skills/audit-rbac/SKILL.md
 create mode 100644 .agents/skills/audit-tests/SKILL.md
 create mode 100644 .agents/skills/code/SKILL.md
 create mode 100644 .agents/skills/cursor-usage/SKILL.md
 create mode 100644 .agents/skills/data/SKILL.md
 create mode 100644 .agents/skills/essentials/SKILL.md
 create mode 100644 .agents/skills/forms/SKILL.md
 create mode 100644 .agents/skills/infra/SKILL.md
 create mode 100644 .agents/skills/new-feature-setup/SKILL.md
 create mode 100644 .agents/skills/prisma/SKILL.md
 create mode 100644 .agents/skills/production-readiness/SKILL.md
 create mode 100644 .agents/skills/prompt-engineering/SKILL.md
 create mode 100644 .agents/skills/stale-worktree-cleanup/SKILL.md
 create mode 100644 .agents/skills/trigger-advanced-tasks/SKILL.md
 create mode 100644 .agents/skills/trigger-basic/SKILL.md
 create mode 100644 .agents/skills/trigger-config/SKILL.md
 create mode 100644 .agents/skills/trigger-realtime/SKILL.md
 create mode 100644 .agents/skills/trigger-scheduled-tasks/SKILL.md
 create mode 100644 .agents/skills/ui/SKILL.md
 create mode 100644 .claude/skills/code/SKILL.md
 create mode 100644 .claude/skills/cursor-usage/SKILL.md
 create mode 100644 .claude/skills/data/SKILL.md
 create mode 100644 .claude/skills/essentials/SKILL.md
 create mode 100644 .claude/skills/forms/SKILL.md
 create mode 100644 .claude/skills/infra/SKILL.md
 create mode 100644 .claude/skills/prisma/SKILL.md
 create mode 100644 .claude/skills/prompt-engineering/SKILL.md
 create mode 100644 .claude/skills/trigger-advanced-tasks/SKILL.md
 create mode 100644 .claude/skills/trigger-basic/SKILL.md
 create mode 100644 .claude/skills/trigger-config/SKILL.md
 create mode 100644 .claude/skills/trigger-realtime/SKILL.md
 create mode 100644 .claude/skills/trigger-scheduled-tasks/SKILL.md
 create mode 100644 .claude/skills/ui/SKILL.md
 create mode 100644 AGENTS.md

diff --git a/.agents/skills/audit-design-system/SKILL.md b/.agents/skills/audit-design-system/SKILL.md
new file mode 100644
index 0000000000..a0f25f6319
--- /dev/null
+++ b/.agents/skills/audit-design-system/SKILL.md
@@ -0,0 +1,23 @@
+---
+name: audit-design-system
+description: Audit & fix design system usage — migrate @trycompai/ui and lucide-react to @trycompai/design-system
+---
+
+Audit the specified files for design system compliance. **Fix every issue found immediately.**
+
+## Rules
+
+1. **`@trycompai/design-system`** is the primary component library. `@trycompai/ui` is legacy — only use as last resort when no DS equivalent exists.
+2. **Always check DS exports first** before reaching for `@trycompai/ui`. Run `node -e "console.log(Object.keys(require('@trycompai/design-system')))"` to check.
+3. **Icons**: Use `@trycompai/design-system/icons` (Carbon icons), NOT `lucide-react`. Check with `node -e "const i = require('@trycompai/design-system/icons'); console.log(Object.keys(i).filter(k => k.match(/YourSearch/i)))"`.
+4. **DS components that do NOT accept `className`**: `Text`, `Stack`, `HStack`, `Badge`, `Button` — wrap in `<div>` for custom styling.
+5. **Button**: Use DS `Button` with `loading`, `iconLeft`, `iconRight` props instead of manually rendering spinners/icons.
+6. **Layout**: Use `PageLayout`, `PageHeader`, `Stack`, `HStack`, `Section`, `SettingGroup`.
+7. **Patterns**: Sheet (`Sheet > SheetContent > SheetHeader + SheetBody`), Drawer, Collapsible.
+
+## Process
+1. Read files specified in `$ARGUMENTS`
+2. Find `@trycompai/ui` imports — check if DS equivalent exists
+3. Find `lucide-react` imports — find matching Carbon icons
+4. Migrate components and icons
+5. Run build to verify: `npx turbo run typecheck --filter=@trycompai/app`
diff --git a/.agents/skills/audit-hooks/SKILL.md b/.agents/skills/audit-hooks/SKILL.md
new file mode 100644
index 0000000000..d3f60a1752
--- /dev/null
+++ b/.agents/skills/audit-hooks/SKILL.md
@@ -0,0 +1,34 @@
+---
+name: audit-hooks
+description: Audit & fix hooks and API usage patterns — eliminate server actions, raw fetch, and stale patterns
+---
+
+Audit the specified files for hook and API usage compliance. **Fix every issue found immediately.**
+
+## Forbidden Patterns (fix immediately)
+
+1. **`useAction` from `next-safe-action`** → replace with SWR hook or custom mutation hook
+2. **Server actions mutating via `@db`** → delete and use API hook instead
+3. **Direct `@db` in client components** → replace with `apiClient` via hook
+4. **Direct `@db` in Next.js pages for mutations** → replace with `serverApi`
+5. **Raw `fetch()` without `credentials: 'include'`** → use `apiClient`
+6. **`window.location.reload()` after mutations** → use SWR `mutate()`
+7. **`router.refresh()` after mutations** → use SWR `mutate()`
+8. **`useEffect` + `apiClient.get` for data fetching** → replace with `useSWR`
+9. **Callback props for data refresh** (`onXxxAdded`, `onSuccess`) → remove, rely on SWR cache sharing
+
+## Required Patterns
+
+- **Client data fetching**: `useSWR` with `apiClient` or custom hook
+- **Client mutations**: custom hooks wrapping `apiClient` with `mutate()` for cache invalidation
+- **Server components**: `serverApi` from `apps/app/src/lib/api-server.ts`
+- **SWR**: `fallbackData` for SSR data, `revalidateOnMount: !initialData`
+- **API response**: lists = `response.data.data`, single = `response.data`
+- **`mutate()` safety**: guard against `undefined` in optimistic update functions
+- **`Array.isArray()` checks**: when consuming SWR data that could be stale
+
+## Process
+1. Read files specified in `$ARGUMENTS`
+2. Find forbidden patterns and fix them
+3. Ensure all data fetching uses SWR hooks
+4. Run typecheck to verify: `npx turbo run typecheck --filter=@trycompai/app`
diff --git a/.agents/skills/audit-rbac/SKILL.md b/.agents/skills/audit-rbac/SKILL.md
new file mode 100644
index 0000000000..dbb5f7e0da
--- /dev/null
+++ b/.agents/skills/audit-rbac/SKILL.md
@@ -0,0 +1,42 @@
+---
+name: audit-rbac
+description: Audit & fix RBAC and audit log compliance in API endpoints and frontend components
+---
+
+Audit the specified files or directories for RBAC and audit log compliance. **Fix every issue found immediately.**
+
+## Rules
+
+### API Endpoints (NestJS — `apps/api/src/`)
+1. **Every mutation endpoint** (POST, PATCH, PUT, DELETE) MUST have `@RequirePermission('resource', 'action')`. If missing, **add it**.
+2. **Read endpoints** (GET) should have `@RequirePermission('resource', 'read')`. If missing, **add it**.
+3. **Self-endpoints** (e.g., `/me/preferences`) may skip `@RequirePermission` — authentication via `HybridAuthGuard` is sufficient.
+4. **Controller format**: Must use `@Controller({ path: 'name', version: '1' })`, NOT `@Controller('v1/name')`. If wrong, **fix it**.
+5. **Guards**: Use `@UseGuards(HybridAuthGuard, PermissionGuard)` at controller or endpoint level. Never skip PermissionGuard.
+6. **Webhooks**: External webhook endpoints use `@Public()` — no auth required.
+
+### Frontend Components (`apps/app/src/`)
+1. **Every mutation element** (button, form submit, toggle, switch, file upload) MUST be gated with `usePermissions` from `@/hooks/use-permissions`. If not:
+   - **Create/Add buttons**: Wrap with `{hasPermission('resource', 'create') && <Button>...`
+   - **Edit/Delete in dropdown menus**: Wrap the menu item
+   - **Inline form fields on detail pages**: Add `disabled={!canUpdate}`
+   - **Status/property selectors**: Add `disabled={!canUpdate}`
+2. **Actions columns** in tables: hide entire column when user lacks write permission.
+3. **No manual role string parsing** (`role.includes('admin')`) — use `hasPermission()`.
+4. **Nav items**: gate with `canAccessRoute(permissions, 'routeSegment')`.
+5. **Page-level**: call `requireRoutePermission('segment', orgId)` server-side.
+
+### Permission Resources
+`organization`, `member`, `control`, `evidence`, `policy`, `risk`, `vendor`, `task`, `framework`, `audit`, `finding`, `questionnaire`, `integration`, `apiKey`, `trust`, `pentest`, `app`, `compliance`
+
+### Multi-Product RBAC
+- Products (compliance, pen testing) are org-level feature flags — NOT RBAC
+- `app:read` gates compliance dashboard; `pentest:read` gates security product
+- Custom roles can grant access to any combination of resources
+- Portal-only resources (`policy`, `compliance`) do NOT grant app access
+
+## Process
+1. Read files specified in `$ARGUMENTS` (or scan the directory)
+2. Check each rule above
+3. **Fix every violation immediately** — don't just report
+4. Run typecheck to verify: `npx turbo run typecheck --filter=@trycompai/api --filter=@trycompai/app`
diff --git a/.agents/skills/audit-tests/SKILL.md b/.agents/skills/audit-tests/SKILL.md
new file mode 100644
index 0000000000..9d80007715
--- /dev/null
+++ b/.agents/skills/audit-tests/SKILL.md
@@ -0,0 +1,30 @@
+---
+name: audit-tests
+description: Audit & fix unit tests for permission-gated components
+---
+
+Check that unit tests exist and pass for permission-gated components. **Write missing tests immediately.**
+
+## Infrastructure
+- **Framework**: Vitest with jsdom
+- **Component testing**: `@testing-library/react` + `@testing-library/jest-dom`
+- **Setup**: `apps/app/src/test-utils/setup.ts`
+- **Permission mocks**: `apps/app/src/test-utils/mocks/permissions.ts`
+- **Run**: `cd apps/app && npx vitest run`
+
+## Required Test Pattern
+
+Every component importing `usePermissions` MUST have tests covering:
+
+1. **Admin (write) user**: mutation elements visible/enabled
+2. **Auditor (read-only)**: mutation elements hidden/disabled
+3. **Data always visible**: read-only content renders regardless of permissions
+
+Use `setMockPermissions`, `ADMIN_PERMISSIONS`, `AUDITOR_PERMISSIONS` from test utils.
+
+## Process
+1. Find components with `usePermissions` in `$ARGUMENTS`
+2. Check for corresponding `.test.tsx` files
+3. Write missing tests following the pattern above
+4. Fix any failing tests
+5. Run: `cd apps/app && npx vitest run`
diff --git a/.agents/skills/code/SKILL.md b/.agents/skills/code/SKILL.md
new file mode 100644
index 0000000000..d6028d192f
--- /dev/null
+++ b/.agents/skills/code/SKILL.md
@@ -0,0 +1,185 @@
+---
+name: code
+description: "Use when writing TypeScript/React code - covers type safety, component patterns, and file organization"
+---
+
+Source Cursor rule: `.cursor/rules/code.mdc`.
+Original Cursor alwaysApply: `false`.
+
+# Code Standards
+
+## TypeScript
+
+### No `any`, No Unsafe Casts
+
+```tsx
+// ✅ Validate with zod
+const TaskSchema = z.object({ id: z.string(), title: z.string() });
+const task = TaskSchema.parse(response.data);
+
+// ✅ Use unknown and narrow
+const parseResponse = (data: unknown): Task => {
+  if (!isTask(data)) throw new Error('Invalid');
+  return data;
+};
+
+// ❌ Never
+const data: any = fetchData();
+const task = response as Task;
+const name = user!.name;
+// @ts-ignore
+```
+
+### Generics Over Any
+
+```tsx
+// ✅ Generic
+const first = <T>(items: T[]): T | undefined => items[0];
+
+// ❌ Any
+const first = (items: any[]): any => items[0];
+```
+
+## React Patterns
+
+### Named Exports, PascalCase
+
+```tsx
+// ✅ Named export, PascalCase file
+// TaskCard.tsx
+export function TaskCard({ task }: TaskCardProps) { ... }
+
+// ❌ Default export, lowercase
+export default function taskCard() { ... }
+```
+
+### Derive State, Avoid useEffect
+
+```tsx
+// ✅ Derived
+const completedCount = tasks.filter(t => t.completed).length;
+
+// ❌ Synced state
+const [count, setCount] = useState(0);
+useEffect(() => {
+  setCount(tasks.filter(t => t.completed).length);
+}, [tasks]);
+```
+
+### When useEffect IS Appropriate
+
+```tsx
+// External subscriptions
+useEffect(() => {
+  const sub = eventSource.subscribe(handler);
+  return () => sub.unsubscribe();
+}, []);
+
+// DOM measurements
+useEffect(() => {
+  setHeight(ref.current?.getBoundingClientRect().height);
+}, []);
+```
+
+### Toasts with Sonner
+
+```tsx
+import { toast } from 'sonner';
+
+toast.success('Task created');
+toast.error('Failed to save');
+toast.promise(saveTask(), {
+  loading: 'Saving...',
+  success: 'Saved!',
+  error: 'Failed',
+});
+```
+
+## File Structure
+
+### Colocate at Route Level
+
+```
+app/(app)/[orgId]/tasks/
+├── page.tsx              # Server component
+├── components/
+│   └── TaskList.tsx      # Client component
+├── hooks/
+│   └── useTasks.ts       # SWR hook
+└── data/
+    └── queries.ts        # Server queries
+```
+
+### Share Only When Reused 3+ Times
+
+```
+src/components/shared/    # Cross-page components
+src/hooks/                # Shared hooks (useApiSWR, useDebounce)
+```
+
+## Code Quality
+
+### File Size Limit: 300 Lines
+
+Split large files into focused components.
+
+### Named Parameters for 2+ Args
+
+```tsx
+// ✅ Named
+const createTask = ({ title, assigneeId }: CreateTaskParams) => { ... };
+createTask({ title: 'Review PR', assigneeId: user.id });
+
+// ❌ Positional
+const createTask = (title: string, assigneeId: string) => { ... };
+createTask('Review PR', user.id); // What's the 2nd param?
+```
+
+### Early Returns
+
+```tsx
+// ✅ Early return
+function processTask(task: Task | null) {
+  if (!task) return null;
+  if (task.deleted) return null;
+  return <TaskCard task={task} />;
+}
+
+// ❌ Nested
+function processTask(task) {
+  if (task) {
+    if (!task.deleted) {
+      return <TaskCard task={task} />;
+    }
+  }
+  return null;
+}
+```
+
+### Event Handler Naming
+
+```tsx
+// ✅ Prefix with "handle"
+const handleClick = () => { ... };
+const handleSubmit = (e: FormEvent) => { ... };
+const handleTaskCreate = (task: Task) => { ... };
+```
+
+## Accessibility
+
+```tsx
+// Interactive elements need keyboard support
+<div
+  role="button"
+  tabIndex={0}
+  onClick={handleClick}
+  onKeyDown={(e) => e.key === 'Enter' && handleClick()}
+  aria-label="Delete task"
+>
+  <TrashIcon />
+</div>
+
+// Form inputs need labels
+<label htmlFor="task-name">Task Name</label>
+<input id="task-name" type="text" />
+```
diff --git a/.agents/skills/cursor-usage/SKILL.md b/.agents/skills/cursor-usage/SKILL.md
new file mode 100644
index 0000000000..b2b96b6c5c
--- /dev/null
+++ b/.agents/skills/cursor-usage/SKILL.md
@@ -0,0 +1,269 @@
+---
+name: cursor-usage
+description: "How to write and manage Cursor rules - invoke with @cursor-usage"
+---
+
+Source Cursor rule: `.cursor/rules/cursor-usage.mdc`.
+Original file scope: `.cursor/rules/*.mdc`.
+Original Cursor alwaysApply: `false`.
+
+# Using Cursor Rules
+
+## Overview
+
+Cursor rules provide system-level instructions to the AI to maintain code consistency, quality, and adherence to project standards. They are stored in the `.cursor/rules/` directory as `.mdc` (Markdown with frontmatter) files.
+
+## Rule File Structure
+
+Each `.mdc` rule file consists of two parts:
+
+### 1. Frontmatter (YAML metadata)
+
+```yaml
+---
+description: Brief overview of what this rule enforces
+globs: **/*.{ts,tsx}
+alwaysApply: true
+---
+```
+
+**Frontmatter Fields:**
+
+- `description`: A clear, concise explanation of the rule's purpose
+- `globs`: Glob pattern to match files where this rule should apply (plain string, no quotes or arrays)
+  - Examples:
+    - `**/*.tsx` - All TSX files
+    - `**/*.{ts,tsx}` - All TS and TSX files
+    - `apps/*/components/**/*.tsx` - All TSX files in any app's components directory
+    - `**/trigger/**/*.ts` - All TS files in trigger directories
+- `alwaysApply`: Boolean indicating if the rule should always be active
+  - `true`: Rule is always active when working on matching files
+  - `false`: Rule can be selectively invoked with `@rule-name`
+
+### 2. Content (Markdown)
+
+The body of the rule file contains the actual guidelines, examples, and instructions written in Markdown format.
+
+## How Rules Are Applied
+
+### Automatic Application
+
+Rules with `alwaysApply: true` are automatically loaded when:
+
+- You open a file matching the `globs` pattern
+- You're working on code that matches the pattern
+- Cursor AI generates or suggests code for matching files
+
+### Manual Invocation
+
+You can reference specific rules in your prompts:
+
+```
+@design-system create a new button component
+```
+
+This explicitly tells Cursor to apply the design-system rule.
+
+## Best Practices for Writing Rules
+
+### 1. Keep Rules Focused
+
+- Each rule file should cover a specific domain (e.g., design system, API patterns, testing)
+- Avoid mixing unrelated concerns in a single rule file
+- Aim for rules under 500 lines for better AI comprehension
+
+### 2. Provide Concrete Examples
+
+Always include:
+
+- ✅ Good examples (what TO do)
+- ❌ Bad examples (what NOT to do)
+- Real code snippets from your project
+
+```tsx
+// ✅ Good: Use semantic tokens
+<div className="bg-background text-foreground">Content</div>
+
+// ❌ Bad: Hardcoded colors
+<div className="bg-white text-black">Content</div>
+```
+
+### 3. Use Clear Section Headers
+
+Organize content with descriptive headers:
+
+```markdown
+## Core Principles
+
+## Rules
+
+## Examples
+
+## Exceptions
+
+## Common Mistakes
+```
+
+### 4. Define Exceptions Explicitly
+
+If there are cases where rules don't apply, state them clearly:
+
+```markdown
+## Exceptions
+
+The ONLY time you can pass className to a design system component is for:
+
+1. Width utilities: `w-full`, `max-w-md`
+2. Responsive display: `hidden`, `md:block`
+```
+
+### 5. Include Checklists
+
+Provide actionable checklists for validation:
+
+```markdown
+## Code Review Checklist
+
+Before committing:
+
+- [ ] Uses semantic color tokens
+- [ ] Works in both light and dark mode
+- [ ] Fully responsive
+```
+
+## Managing Rules
+
+### Creating a New Rule
+
+1. Create a new `.mdc` file in `.cursor/rules/`
+2. Add appropriate frontmatter
+3. Write clear guidelines with examples
+4. Test by working on matching files
+
+### Updating Existing Rules
+
+1. Edit the `.mdc` file
+2. Rules are automatically reloaded
+3. Test changes with relevant files
+
+### Organizing Rules
+
+Recommended structure:
+
+```
+.cursor/rules/
+├── design-system.mdc       # Component usage, variants, composition
+├── code-standards.mdc      # General code quality rules
+├── typescript-rules.mdc    # TypeScript type safety
+├── react-code.mdc          # React patterns and conventions
+├── data-fetching.mdc       # Server/client data patterns
+└── cursor-usage.mdc        # This file - how to use rules
+```
+
+## Rule Scope with Globs
+
+### Common Glob Patterns
+
+```yaml
+# All TypeScript/TSX files
+globs: **/*.{ts,tsx}
+
+# Only TSX files (React components)
+globs: **/*.tsx
+
+# Only trigger task files
+globs: **/trigger/**/*.ts
+
+# Prisma schema files
+globs: **/*.prisma
+
+# All JSON and TypeScript files
+globs: **/*.{ts,tsx,json}
+```
+
+### Glob Pattern Tips
+
+- Use `**` for recursive directory matching
+- Use `*` for single-level wildcard
+- Use `{ts,tsx}` for multiple extensions
+- No quotes or array brackets needed
+- Be specific to avoid over-applying rules
+
+## Debugging Rules
+
+### Rule Not Applying?
+
+1. Check the `globs` pattern matches your file
+2. Verify frontmatter YAML syntax is correct
+3. Ensure `alwaysApply` is set appropriately
+4. Try manually invoking with `@ruleName`
+
+### Rule Conflicting?
+
+1. Check if multiple rules apply to the same files
+2. Make rules more specific with tighter `globs`
+3. Consolidate related rules into one file
+
+## Advanced Features
+
+### Conditional Rules
+
+Use `alwaysApply: false` for rules that should only apply in specific contexts:
+
+```yaml
+---
+description: Performance optimization guidelines
+globs: **/*.ts
+alwaysApply: false
+---
+```
+
+Invoke with: `@performance-optimization refactor this component`
+
+### Hierarchical Rules
+
+More specific globs take precedence:
+
+- `design-system.mdc` with `globs: **/*.tsx` (broad)
+- `trigger.basic.mdc` with `globs: **/trigger/**/*.ts` (specific)
+
+The specific rule will have more weight for trigger files.
+
+## Quick Reference
+
+### Create a New Rule
+
+```bash
+touch .cursor/rules/my-new-rule.mdc
+```
+
+```yaml
+---
+description: What this rule enforces
+globs: **/*.{ts,tsx}
+alwaysApply: true
+---
+
+# Rule Title
+
+## Guidelines
+
+- Point 1
+- Point 2
+```
+
+### Apply a Rule
+
+- Automatic: Save a file matching the `globs` pattern
+- Manual: Use `@my-new-rule` in your prompt
+
+### Debug a Rule
+
+1. Check file matches `globs` pattern
+2. Verify YAML frontmatter syntax
+3. Look for conflicting rules
+4. Try manual invocation
+
+---
+
+**Remember**: Rules are here to help, not hinder. If a rule doesn't make sense for a specific case, discuss with the team and update the rule accordingly.
diff --git a/.agents/skills/data/SKILL.md b/.agents/skills/data/SKILL.md
new file mode 100644
index 0000000000..a670937c2d
--- /dev/null
+++ b/.agents/skills/data/SKILL.md
@@ -0,0 +1,141 @@
+---
+name: data
+description: "Use when implementing data fetching, API calls, server/client components, or SWR hooks"
+---
+
+Source Cursor rule: `.cursor/rules/data.mdc`.
+Original Cursor alwaysApply: `false`.
+
+# Data Fetching
+
+## Core Pattern: Server → Client → SWR
+
+### 1. Server Page Fetches Data
+
+```tsx
+// app/(app)/[orgId]/tasks/page.tsx
+export default async function TasksPage({ params }: { params: Promise<{ orgId: string }> }) {
+  const { orgId } = await params; // From URL, NOT session
+  const tasks = await getTasks(orgId);
+  return <TaskListClient organizationId={orgId} initialTasks={tasks} />;
+}
+```
+
+### 2. Client Component Receives Initial Data
+
+```tsx
+// components/TaskListClient.tsx
+'use client';
+
+export function TaskListClient({ organizationId, initialTasks }: Props) {
+  const { tasks, createTask, updateTask } = useTasks({
+    organizationId,
+    initialData: initialTasks,
+  });
+  // Initial render is instant - no loading state
+}
+```
+
+### 3. SWR Hook with fallbackData
+
+```tsx
+// hooks/useTasks.ts
+export function useTasks({ organizationId, initialData }: UseTasksOptions) {
+  const { data, mutate } = useSWR(
+    ['/v1/tasks', organizationId], // Include orgId for cache isolation
+    async ([endpoint, orgId]) => {
+      const response = await apiClient.get(endpoint, orgId);
+      return response.data?.tasks ?? [];
+    },
+    { fallbackData: initialData }
+  );
+
+  const createTask = async (input: CreateTaskInput) => {
+    await apiClient.post('/v1/tasks', input, organizationId);
+    mutate(); // Revalidate
+  };
+
+  return { tasks: data ?? [], createTask, mutate };
+}
+```
+
+## API Client
+
+Use `apiClient` from `@/lib/api-client`:
+
+```tsx
+import { apiClient } from '@/lib/api-client';
+
+await apiClient.get<ResponseType>('/v1/endpoint', organizationId);
+await apiClient.post<ResponseType>('/v1/endpoint', body, organizationId);
+await apiClient.put<ResponseType>('/v1/endpoint', body, organizationId);
+await apiClient.delete('/v1/endpoint', organizationId);
+```
+
+## Server vs Client Components
+
+**Layouts = server.** Interactive logic in separate client components.
+
+```tsx
+// layout.tsx (server)
+export default function Layout({ children }) {
+  return (
+    <PageLayout>
+      <PageHeader title="Title" />
+      <ClientTabs /> {/* Client component */}
+      {children}
+    </PageLayout>
+  );
+}
+
+// components/ClientTabs.tsx
+'use client';
+export function ClientTabs() {
+  const router = useRouter();
+  // Interactive logic here
+}
+```
+
+## State Management
+
+**No `nuqs`** - use React state or Next.js patterns:
+
+```tsx
+// ✅ React state for UI
+const [isOpen, setIsOpen] = useState(false);
+
+// ✅ Next.js for URL state
+const router = useRouter();
+const searchParams = useSearchParams();
+
+// ❌ No nuqs
+import { useQueryState } from 'nuqs';
+```
+
+## Rules
+
+```tsx
+// ✅ Always
+const { orgId } = await params;                    // From URL params
+const { data } = useSWR(key, f, { fallbackData }); // With initial data
+await apiClient.get('/v1/endpoint', orgId);        // Use apiClient
+useSWR(['/v1/tasks', orgId], fetcher);            // Include orgId in key
+
+// ❌ Never
+const orgId = session?.activeOrganizationId;       // From session
+const { data } = useSWR('/api/data');              // No initial data
+await fetch('/api/endpoint');                      // Direct fetch
+```
+
+## File Structure
+
+```
+app/(app)/[orgId]/tasks/
+├── page.tsx                 # Server - fetches data
+├── components/
+│   └── TaskListClient.tsx   # Client - receives initialData
+├── hooks/
+│   └── useTasks.ts          # SWR hook with mutations
+└── data/
+    └── queries.ts           # Server-side queries
+```
diff --git a/.agents/skills/essentials/SKILL.md b/.agents/skills/essentials/SKILL.md
new file mode 100644
index 0000000000..21711433da
--- /dev/null
+++ b/.agents/skills/essentials/SKILL.md
@@ -0,0 +1,108 @@
+---
+name: essentials
+description: "Critical rules that must always be followed"
+---
+
+Source Cursor rule: `.cursor/rules/essentials.mdc`.
+Original file scope: `**/*.{ts,tsx}`.
+Original Cursor alwaysApply: `true`.
+
+# Essentials
+
+## Package Manager
+
+Use `bun`, never npm/yarn/pnpm.
+
+```bash
+bun install          # Install deps
+bun add <pkg>        # Add package
+bun run <script>     # Run script
+bunx <cmd>           # Execute binary
+```
+
+## Components
+
+**Use `@trycompai/design-system` first**, `@trycompai/ui` only as fallback.
+
+```tsx
+// ✅ Design system
+import { Button, Card, Input, Select } from '@trycompai/design-system';
+import { Add, Close } from '@trycompai/design-system/icons';
+
+// ❌ Don't use when DS has the component
+import { Button } from '@trycompai/ui/button';
+import { Plus } from 'lucide-react';
+```
+
+**No `className` on DS components** - use variants and props only.
+
+```tsx
+// ✅ Use variants
+<Button variant="destructive" size="sm">Delete</Button>
+
+// ❌ No className overrides
+<Button className="bg-red-500">Delete</Button>
+```
+
+## TypeScript
+
+**No `any`. No unsafe type assertions.**
+
+```tsx
+// ✅ Validate external data with zod
+const TaskSchema = z.object({ id: z.string(), title: z.string() });
+const task = TaskSchema.parse(response.data);
+
+// ❌ Never
+const data: any = fetchData();
+const task = response as Task;
+```
+
+## Data Fetching
+
+**Get `organizationId` from URL params, not session.**
+
+```tsx
+// ✅ From params
+export default async function Page({ params }: { params: Promise<{ orgId: string }> }) {
+  const { orgId } = await params;
+}
+
+// ❌ Not from session
+const session = await auth.api.getSession();
+const orgId = session?.session?.activeOrganizationId;
+```
+
+**Server components fetch, pass to client with SWR `fallbackData`.**
+
+```tsx
+// Server page
+const data = await fetchData(orgId);
+return <ClientComponent initialData={data} />;
+
+// Client component
+const { data } = useSWR(key, fetcher, { fallbackData: initialData });
+```
+
+## State Management
+
+**No `nuqs`** - use React `useState` for UI state, Next.js for URL state.
+
+```tsx
+// ✅ React state for UI
+const [isOpen, setIsOpen] = useState(false);
+
+// ❌ No nuqs
+import { useQueryState } from 'nuqs';
+```
+
+## After Changes
+
+**Always run checks after code changes:**
+
+```bash
+bun run typecheck
+bun run lint
+```
+
+Fix all errors before committing.
diff --git a/.agents/skills/forms/SKILL.md b/.agents/skills/forms/SKILL.md
new file mode 100644
index 0000000000..bcb8beafa8
--- /dev/null
+++ b/.agents/skills/forms/SKILL.md
@@ -0,0 +1,180 @@
+---
+name: forms
+description: "Use when building forms - covers React Hook Form, Zod validation, and form patterns"
+---
+
+Source Cursor rule: `.cursor/rules/forms.mdc`.
+Original Cursor alwaysApply: `false`.
+
+# Forms: React Hook Form + Zod
+
+**All forms MUST use React Hook Form with Zod validation.**
+
+## Basic Pattern
+
+```tsx
+import { zodResolver } from '@hookform/resolvers/zod';
+import { useForm } from 'react-hook-form';
+import { z } from 'zod';
+import { Button, Input } from '@trycompai/design-system';
+
+// 1. Define schema
+const formSchema = z.object({
+  email: z.string().email('Invalid email'),
+  password: z.string().min(8, 'Min 8 characters'),
+});
+
+// 2. Infer type
+type FormData = z.infer<typeof formSchema>;
+
+// 3. Use in component
+function MyForm() {
+  const {
+    register,
+    handleSubmit,
+    formState: { errors, isSubmitting },
+  } = useForm<FormData>({
+    resolver: zodResolver(formSchema),
+  });
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <Input {...register('email')} />
+      {errors.email && <p>{errors.email.message}</p>}
+      
+      <Button type="submit" loading={isSubmitting}>
+        Submit
+      </Button>
+    </form>
+  );
+}
+```
+
+## Zod Schema Patterns
+
+```tsx
+const schema = z.object({
+  // Strings
+  name: z.string().min(1, 'Required'),
+  email: z.string().email(),
+  website: z.string().url().optional(),
+  
+  // Numbers (coerce for inputs)
+  age: z.coerce.number().int().min(0),
+  price: z.coerce.number().positive(),
+  
+  // Arrays
+  tags: z.array(z.string()).min(1),
+  
+  // Enums
+  status: z.enum(['active', 'inactive']),
+});
+
+// Cross-field validation
+const schema = z.object({
+  password: z.string().min(8),
+  confirmPassword: z.string(),
+}).refine(d => d.password === d.confirmPassword, {
+  message: "Passwords don't match",
+  path: ['confirmPassword'],
+});
+```
+
+## Controller for Complex Components
+
+```tsx
+import { Controller } from 'react-hook-form';
+import { Select, SelectContent, SelectItem, SelectTrigger } from '@trycompai/design-system';
+
+<Controller
+  name="status"
+  control={control}
+  render={({ field }) => (
+    <Select onValueChange={field.onChange} value={field.value}>
+      <SelectTrigger>{field.value || 'Select...'}</SelectTrigger>
+      <SelectContent>
+        <SelectItem value="active">Active</SelectItem>
+        <SelectItem value="inactive">Inactive</SelectItem>
+      </SelectContent>
+    </Select>
+  )}
+/>
+```
+
+## Form State
+
+```tsx
+const {
+  register,
+  handleSubmit,
+  control,
+  watch,           // Watch field values
+  setValue,        // Set field programmatically
+  reset,           // Reset form
+  setError,        // Set error manually
+  formState: {
+    errors,        // Field errors
+    isSubmitting,  // Submitting
+    isValid,       // All valid
+    isDirty,       // Modified
+  },
+} = useForm<FormData>({
+  resolver: zodResolver(schema),
+  mode: 'onChange', // Validate on change
+});
+```
+
+## Error Handling
+
+```tsx
+const onSubmit = async (data: FormData) => {
+  try {
+    await submitToApi(data);
+  } catch (error) {
+    // Field-specific error
+    setError('email', { message: 'Email taken' });
+    // Or root error
+    setError('root', { message: 'Something went wrong' });
+  }
+};
+
+// Display root error
+{errors.root && <p>{errors.root.message}</p>}
+```
+
+## Dynamic Fields
+
+```tsx
+import { useFieldArray } from 'react-hook-form';
+
+const { fields, append, remove } = useFieldArray({
+  control,
+  name: 'items',
+});
+
+{fields.map((field, index) => (
+  <div key={field.id}>
+    <Input {...register(`items.${index}.name`)} />
+    <Button type="button" onClick={() => remove(index)}>Remove</Button>
+  </div>
+))}
+<Button type="button" onClick={() => append({ name: '' })}>Add</Button>
+```
+
+## Anti-Patterns
+
+```tsx
+// ❌ useState for form fields
+const [email, setEmail] = useState('');
+
+// ❌ Manual validation
+if (email.length < 5) setError('Too short');
+
+// ❌ Missing button type (defaults to submit)
+<Button onClick={handleCancel}>Cancel</Button>
+
+// ✅ Correct
+const { register } = useForm();
+const schema = z.object({ email: z.string().min(5) });
+<Button type="button" onClick={handleCancel}>Cancel</Button>
+```
diff --git a/.agents/skills/infra/SKILL.md b/.agents/skills/infra/SKILL.md
new file mode 100644
index 0000000000..bf073598f8
--- /dev/null
+++ b/.agents/skills/infra/SKILL.md
@@ -0,0 +1,135 @@
+---
+name: infra
+description: "Use when working with packages, dependencies, monorepo structure, or build configuration"
+---
+
+Source Cursor rule: `.cursor/rules/infra.mdc`.
+Original Cursor alwaysApply: `false`.
+
+# Infrastructure
+
+## Package Manager
+
+**Use `bun`, never npm/yarn/pnpm.**
+
+```bash
+bun install              # Install deps
+bun add <pkg>            # Add package
+bun add -D <pkg>         # Add dev dependency
+bun run <script>         # Run script
+bunx <cmd>               # Execute binary
+```
+
+## Monorepo Structure
+
+```
+comp/
+├── apps/
+│   ├── api/             # NestJS backend
+│   ├── app/             # Next.js main app
+│   └── portal/          # Next.js portal
+├── packages/
+│   ├── db/              # Prisma (@trycompai/db)
+│   ├── ui/              # UI components (@trycompai/ui)
+│   └── ...
+├── turbo.json
+└── package.json
+```
+
+## Running Commands
+
+```bash
+# Multi-package (via turbo)
+bun run build            # Build all
+bun run lint             # Lint all
+bun run typecheck        # Type check all
+bun run dev              # Dev all
+
+# Single package
+bun run -F apps/app dev
+bun run -F @trycompai/db prisma:generate
+turbo build --filter=@trycompai/ui
+```
+
+## Importing Between Packages
+
+```tsx
+// ✅ Import from package name
+import { Button } from '@trycompai/design-system';
+import { prisma } from '@trycompai/db';
+
+// ❌ Never relative paths across packages
+import { Button } from '../../../packages/ui/src/button';
+```
+
+## Adding Dependencies
+
+```bash
+# To specific package
+bun add axios -F apps/app
+bun add -D vitest -F @trycompai/ui
+
+# To root (dev tools only)
+bun add -D -w prettier typescript
+```
+
+## After Code Changes
+
+**Always run checks:**
+
+```bash
+bun run typecheck
+bun run lint
+```
+
+Fix all errors before committing.
+
+## Common TypeScript Fixes
+
+- **Property does not exist**: Check interface definitions
+- **Type mismatch**: Verify expected vs actual type
+- **Empty interface extends**: Use `type X = SomeType` instead
+
+## Common ESLint Fixes
+
+- **Unused variables**: Remove or prefix with `_`
+- **Any type**: Add proper typing
+- **Empty object type**: Use `type` instead of `interface`
+
+## Creating a New Package
+
+```bash
+mkdir packages/my-package
+```
+
+```json
+// packages/my-package/package.json
+{
+  "name": "@trycompai/my-package",
+  "version": "0.0.0",
+  "private": true,
+  "main": "./src/index.ts",
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "typecheck": "tsc --noEmit"
+  }
+}
+```
+
+```json
+// packages/my-package/tsconfig.json
+{
+  "extends": "@trycompai/tsconfig/base.json",
+  "include": ["src"]
+}
+```
+
+## Package Boundaries
+
+**✅ Create packages for:**
+- Code used by 2+ apps
+- Self-contained, focused functionality
+
+**❌ Don't create packages for:**
+- Code only used in one app (colocate instead)
+- App-specific business logic
diff --git a/.agents/skills/new-feature-setup/SKILL.md b/.agents/skills/new-feature-setup/SKILL.md
new file mode 100644
index 0000000000..5c5be80363
--- /dev/null
+++ b/.agents/skills/new-feature-setup/SKILL.md
@@ -0,0 +1,114 @@
+---
+name: new-feature-setup
+description: Use when starting a new feature, Linear ticket, or bugfix in this repo — establishes the branch + worktree + env + DB + dev-server conventions so the work is immediately ready to code without fighting infra. Triggers on "start a new feature", "spin up a worktree", "begin ticket", "new branch".
+---
+
+# New Feature Setup (comp monorepo)
+
+## Overview
+
+This repo has a lot of infrastructure pre-wired into `git worktree add`. Use it. Don't reinvent env copying, database setup, or dependency install flows in every new session.
+
+## When to Use
+
+- User says "start a new feature", "spin up a worktree for X", "begin this Linear ticket", "new branch for …"
+- Before running `bun install` / `bun run db:generate` manually in a new directory
+- Before copying `.env` files around by hand
+
+## When NOT to Use
+
+- User is editing an existing worktree (already set up)
+- Infra repair / debugging of the hook itself (read `.githooks/README.md` instead)
+
+## Workflow
+
+### 1. Create the worktree from `origin/main`
+
+```sh
+cd /Users/mariano/code/comp   # must be the MAIN clone, not another worktree
+git fetch origin main
+git worktree add .worktrees/<short-slug> -b <branch-name> origin/main
+```
+
+- For Linear tickets, use Linear's suggested branch name (`mariano/<ticket-slug>`).
+- For infra / chore work, use `mariano/<short-descriptive-name>` or `chore/<topic>`.
+- The `<short-slug>` on the worktree path should match the branch's suffix (it becomes the Postgres DB slug after `tr '-' '_'`).
+
+### 2. Let the hook do everything else
+
+`git worktree add` fires the `post-checkout` hook at `.githooks/post-checkout`, which runs synchronously:
+
+1. Creates `compdev_<slug>` Postgres database (isolated per worktree)
+2. Links `.env*` files from the main clone (copies the ones with `DATABASE_URL`, rewriting it to the isolated URL; symlinks the rest so API keys auto-propagate)
+3. Runs `bun install`, applies Prisma migrations, regenerates clients
+
+**Do not** run any of these by hand. If the hook logs a failure, diagnose and fix at the source — don't paper over with a manual install.
+
+Skip toggles (rare):
+- `SKIP_WORKTREE_DB=1` — share the main `comp` DB (drift risk; only for read-only worktrees)
+- `SKIP_WORKTREE_SETUP=1` — skip install + migrate + generate (for a "just files" worktree)
+- `SETUP_WORKTREE_WITH_BUILD=1` — also run `bun run build` (adds minutes; only when you need the built artifacts)
+
+### 3. Start the dev server — coordinate with the "active worktree" rule
+
+Trigger.dev's `trigger dev` CLI **cannot** be isolated per worktree. Running `bun run dev` in multiple worktrees stomps on task registration.
+
+- **One active worktree** runs `bun run dev` (full stack with `trigger dev`).
+- **All other worktrees** run:
+  ```sh
+  bun run --filter '@trycompai/app' dev:no-trigger    # Next.js only
+  bun run --filter '@trycompai/api' dev:no-trigger    # NestJS only
+  ```
+- Non-active worktrees need a different `PORT` to avoid collision — add `PORT=3001` (or `3334`, etc.) to the worktree's `.env.local`. `.env.local` is not symlinked and stays per-worktree.
+- When swapping which worktree is active, kill the old full `bun run dev` first so task registration is clean.
+
+### 4. Code the feature
+
+Standard repo conventions apply (see `AGENTS.md`). Highlights:
+- TDD for any non-trivial change (`superpowers:test-driven-development`)
+- Brainstorm before building new UX (`superpowers:brainstorming`)
+- Plans + subagent-driven execution for multi-step work
+- Run `audit-design-system` after any frontend component edit
+- Always run typecheck before declaring a change done (`npx turbo run typecheck --filter=<pkg>`)
+
+### 5. When done, clean up
+
+Use the `stale-worktree-cleanup` skill when worktrees accumulate. It handles both `git worktree remove` and dropping the `compdev_<slug>` database in one pass. Never leave orphan databases — they pile up silently because git has no `pre-worktree-remove` hook.
+
+## Quick Reference
+
+```sh
+# Spin up a new worktree (does env + DB + install + migrate + generate automatically)
+git worktree add .worktrees/<slug> -b mariano/<branch-name> origin/main
+
+# Start dev — ONLY in the worktree you're actively iterating on
+cd .worktrees/<slug>
+bun run dev
+
+# Start dev in a background worktree (no trigger dev, custom port via .env.local)
+echo "PORT=3001" >> apps/app/.env.local
+bun run --filter '@trycompai/app' dev:no-trigger
+
+# Clean up when branch is done
+# (use the stale-worktree-cleanup skill)
+```
+
+## Red Flags
+
+If you catch yourself doing any of these, stop — the hook should have handled it:
+
+- Running `bun install` manually in a new worktree
+- `cp` or `ln -s` to copy `.env` files into a worktree
+- Writing a script that "creates a database for my branch"
+- Running `bun run db:migrate` in a worktree right after creating it
+- Ignoring a failing `bun run dev` in two worktrees instead of swapping to `dev:no-trigger`
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Creating the worktree from another worktree instead of the main clone | Always `cd` to `/Users/mariano/code/comp` first |
+| Editing `.env` in a worktree and expecting it to propagate | If it's a symlink, yes; if it's a real copy (has `DATABASE_URL`), no. Check with `ls -la`. |
+| Forgetting to bump `PORT` → two dev servers collide | Put `PORT=<free-port>` in the worktree's `.env.local` |
+| Running `trigger dev` in multiple worktrees | Switch to `dev:no-trigger` in all but one |
+| Not cleaning up → orphan `compdev_*` databases piling up | Use the `stale-worktree-cleanup` skill regularly |
diff --git a/.agents/skills/prisma/SKILL.md b/.agents/skills/prisma/SKILL.md
new file mode 100644
index 0000000000..effc4003a0
--- /dev/null
+++ b/.agents/skills/prisma/SKILL.md
@@ -0,0 +1,147 @@
+---
+name: prisma
+description: "Prisma schema conventions and migration workflow"
+---
+
+Source Cursor rule: `.cursor/rules/prisma.mdc`.
+Original file scope: `**/*.prisma`.
+Original Cursor alwaysApply: `false`.
+
+# Prisma Schema
+
+## Migration Workflow
+
+**Schema changes happen in `packages/db`, then regenerate types in each app.**
+
+### Step 1: Edit Schema
+
+```bash
+# Schema files are in packages/db/prisma/schema/
+packages/db/prisma/schema/
+├── schema.prisma      # Main schema with datasource
+├── user.prisma        # User models
+├── task.prisma        # Task models
+└── ...
+```
+
+### Step 2: Create Migration
+
+```bash
+# Run from packages/db
+cd packages/db
+bunx prisma migrate dev --name your_migration_name
+```
+
+### Step 3: Regenerate Types in Apps
+
+```bash
+# Each app needs to regenerate Prisma client types
+bun run -F apps/app db:generate
+bun run -F apps/api db:generate
+bun run -F apps/portal db:generate
+
+# Or from root (if configured)
+bun run prisma:generate
+```
+
+### ✅ Always Do This
+
+```bash
+# 1. Make schema changes in packages/db
+# 2. Create migration
+cd packages/db && bunx prisma migrate dev --name add_user_role
+
+# 3. Regenerate types in ALL apps that use the db
+bun run -F apps/app db:generate
+bun run -F apps/api db:generate
+```
+
+### ❌ Never Do This
+
+```bash
+# Don't edit schema in app directories
+apps/app/prisma/schema.prisma  # ❌ Wrong location
+
+# Don't forget to regenerate types
+bunx prisma migrate dev  # ✅ Created migration
+# ... forgot to run db:generate in apps  # ❌ Types out of sync
+```
+
+## Core Rule
+
+**Always use prefixed CUIDs for IDs** using `generate_prefixed_cuid`.
+
+## ID Pattern
+
+### ✅ Always Do This
+
+```prisma
+model User {
+  id String @id @default(dbgenerated("generate_prefixed_cuid('usr'::text)"))
+  // ... other fields
+}
+
+model Task {
+  id String @id @default(dbgenerated("generate_prefixed_cuid('tsk'::text)"))
+  // ... other fields
+}
+
+model Organization {
+  id String @id @default(dbgenerated("generate_prefixed_cuid('org'::text)"))
+  // ... other fields
+}
+```
+
+### ❌ Never Do This
+
+```prisma
+// Don't use UUID
+model User {
+  id String @id @default(uuid())
+}
+
+// Don't use auto-increment
+model User {
+  id Int @id @default(autoincrement())
+}
+
+// Don't forget ::text cast
+model User {
+  id String @id @default(dbgenerated("generate_prefixed_cuid('usr')")) // ❌ Missing ::text
+}
+```
+
+## Prefix Guidelines
+
+| Entity       | Prefix | Example ID                     |
+| ------------ | ------ | ------------------------------ |
+| User         | `usr`  | `usr_BJRIZLgRPuWt8MvMjkSY82f1` |
+| Organization | `org`  | `org_cK9xMnPqRs2tUvWx3yZa4b5c` |
+| Task         | `tsk`  | `tsk_dE6fGhIj7kLmNoP8qRsT9uVw` |
+| Control      | `ctl`  | `ctl_xY0zAaBb1cDdEe2fFgGh3iIj` |
+| Policy       | `pol`  | `pol_kK4lLmMn5oOpPq6rRsSt7uUv` |
+
+## Rules
+
+1. **Short prefixes** - Use 2-3 characters
+2. **Unique prefixes** - Each model gets its own prefix
+3. **Always cast** - Include `::text` in the function call
+4. **Use dbgenerated** - Wrap the function call in `dbgenerated()`
+
+## Benefits
+
+- Human-readable IDs at a glance (`usr_` vs `org_`)
+- Easy debugging in logs
+- Safe to expose in URLs
+- Unique across all tables
+
+## Checklist
+
+After schema changes:
+
+- [ ] Schema edited in `packages/db/prisma/schema/`
+- [ ] Migration created with `bunx prisma migrate dev`
+- [ ] Types regenerated in `apps/app` with `db:generate`
+- [ ] Types regenerated in `apps/api` with `db:generate`
+- [ ] Types regenerated in `apps/portal` with `db:generate`
+- [ ] New models use prefixed CUID IDs
diff --git a/.agents/skills/production-readiness/SKILL.md b/.agents/skills/production-readiness/SKILL.md
new file mode 100644
index 0000000000..0300513a9e
--- /dev/null
+++ b/.agents/skills/production-readiness/SKILL.md
@@ -0,0 +1,21 @@
+---
+name: production-readiness
+description: Run all audit checks (RBAC, hooks, design system, tests) and verify build
+disable-model-invocation: true
+---
+
+Run a comprehensive production readiness check on $ARGUMENTS.
+
+Use parallel subagents to run all four audits simultaneously:
+1. audit-rbac on $ARGUMENTS
+2. audit-hooks on $ARGUMENTS
+3. audit-design-system on $ARGUMENTS
+4. audit-tests on $ARGUMENTS
+
+Then run full monorepo verification:
+```bash
+npx turbo run typecheck --filter=@trycompai/api --filter=@trycompai/app
+cd apps/app && npx vitest run
+```
+
+Output a Production Readiness Report summarizing all fixes applied and build status.
diff --git a/.agents/skills/prompt-engineering/SKILL.md b/.agents/skills/prompt-engineering/SKILL.md
new file mode 100644
index 0000000000..46d7c6b58c
--- /dev/null
+++ b/.agents/skills/prompt-engineering/SKILL.md
@@ -0,0 +1,187 @@
+---
+name: prompt-engineering
+description: "Prompt engineering best practices - invoke with @prompt-engineering"
+---
+
+Source Cursor rule: `.cursor/rules/prompt-engineering.mdc`.
+Original file scope: `.cursor/rules/*.mdc`.
+Original Cursor alwaysApply: `false`.
+
+# Prompt Engineering Best Practices
+
+Based on [Claude's Prompt Engineering Documentation](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview)
+
+## Core Principles
+
+### 1. Define Success Criteria First
+
+Before writing prompts:
+
+- **Establish clear objectives**: What constitutes a successful response?
+- **Create evaluation metrics**: How will you measure prompt effectiveness?
+- **Draft and iterate**: Start with a first draft and refine based on results
+
+### 2. When to Use Prompt Engineering vs Fine-tuning
+
+Prompt engineering is preferred because:
+
+- **Resource efficient**: Only requires text input, no GPUs
+- **Cost effective**: Uses base model pricing
+- **Maintains updates**: Works across model versions
+- **Time saving**: Instant results vs hours/days for fine-tuning
+- **Minimal data needs**: Works with zero-shot or few-shot
+- **Flexible iteration**: Quick experimentation cycle
+- **Preserves knowledge**: No catastrophic forgetting
+- **Transparent**: Human-readable, easy to debug
+
+---
+
+## The 8 Core Techniques
+
+### 1. Be Clear and Direct
+
+**Principle**: Provide explicit, unambiguous instructions.
+
+```
+❌ Bad: "Tell me about it"
+✅ Good: "Summarize the following article in three bullet points, focusing on key findings"
+
+❌ Bad: "Help with code"
+✅ Good: "Debug this Python function that should return the sum of even numbers in a list"
+```
+
+**Tips**:
+
+- State the task explicitly at the start
+- Specify the desired output format (bullet points, JSON, paragraphs)
+- Include constraints (word count, tone, audience)
+- Mention what to include AND what to exclude
+
+### 2. Use Examples (Multishot Prompting)
+
+**Principle**: Show the model what you want through examples.
+
+```xml
+<examples>
+  <example>
+    <input>The movie was absolutely terrible, waste of time</input>
+    <output>{"sentiment": "negative", "confidence": 0.95}</output>
+  </example>
+  <example>
+    <input>Decent film, not great but watchable</input>
+    <output>{"sentiment": "neutral", "confidence": 0.7}</output>
+  </example>
+  <example>
+    <input>Best movie I've seen this year!</input>
+    <output>{"sentiment": "positive", "confidence": 0.9}</output>
+  </example>
+</examples>
+
+Now analyze: "The special effects were amazing but the plot was confusing"
+```
+
+**Tips**:
+
+- Include 3-5 diverse examples covering edge cases
+- Show examples of BOTH good and bad outputs
+- Match example complexity to your actual use case
+- Order examples from simple to complex
+
+### 3. Let Claude Think (Chain of Thought)
+
+**Principle**: Encourage step-by-step reasoning for complex tasks.
+
+```xml
+<instruction>
+Solve this problem step by step. Show your reasoning before giving the final answer.
+</instruction>
+
+<problem>
+A train leaves Station A at 9:00 AM traveling at 60 mph. Another train leaves
+Station B at 10:00 AM traveling at 80 mph toward Station A. The stations are
+280 miles apart. When will the trains meet?
+</problem>
+
+<thinking>
+[Let Claude work through the problem here]
+</thinking>
+
+<answer>
+[Final answer after reasoning]
+</answer>
+```
+
+**Tips**:
+
+- Use phrases like "Think step by step" or "Explain your reasoning"
+- For complex tasks, explicitly request a thinking section
+- Chain of thought improves accuracy on math, logic, and multi-step problems
+- Can use `<thinking>` tags to separate reasoning from output
+
+### 4. Use XML Tags
+
+**Principle**: Structure prompts with clear delimiters for better parsing.
+
+```xml
+<context>
+You are helping debug a penetration testing tool that automates security scans.
+</context>
+
+<task>
+Analyze the following error log and identify the root cause.
+</task>
+
+<error_log>
+[2024-01-15 10:23:45] ERROR: Connection timeout after 30s
+[2024-01-15 10:23:45] DEBUG: Target: 192.168.1.1:443
+[2024-01-15 10:23:45] DEBUG: Retry attempt 3 of 3
+</error_log>
+
+<output_format>
+Provide your analysis in this format:
+- Root cause: [one sentence]
+- Evidence: [relevant log lines]
+- Recommended fix: [actionable steps]
+</output_format>
+```
+
+**Common XML Tags**:
+
+- `<context>` - Background information
+- `<task>` or `<instruction>` - What to do
+- `<examples>` - Sample inputs/outputs
+- `<constraints>` - Limitations or rules
+- `<output_format>` - Expected response structure
+- `<thinking>` - Reasoning section
+- `<answer>` - Final response
+
+### 5. Give Claude a Role (System Prompts)
+
+**Principle**: Assign a persona to influence response style and expertise.
+
+```xml
+<role>
+You are a senior security researcher with 15 years of experience in penetration
+testing. You specialize in web application security and have discovered multiple
+CVEs. You communicate findings clearly and prioritize actionable recommendations.
+</role>
+
+<task>
+Review this HTTP response and identify potential security vulnerabilities.
+</task>
+```
+
+**Effective Role Elements**:
+
+- Expertise level (senior, expert, specialist)
+- Domain knowledge (security, finance, medicine)
+- Communication style (technical, friendly, formal)
+- Priorities (accuracy, brevity, thoroughness)
+
+### 6. Prefill Claude's Response
+
+**Principle**: Start the response to guide format and direction.
+
+```
+Human: List the top 3 security vulnerabilities in this code.
+```
diff --git a/.agents/skills/stale-worktree-cleanup/SKILL.md b/.agents/skills/stale-worktree-cleanup/SKILL.md
new file mode 100644
index 0000000000..dcd19860f1
--- /dev/null
+++ b/.agents/skills/stale-worktree-cleanup/SKILL.md
@@ -0,0 +1,174 @@
+---
+name: stale-worktree-cleanup
+description: Use when cleaning up old git worktrees, removing worktrees whose branches have merged or been abandoned, or dropping orphaned compdev_* Postgres databases. Triggers on "clean up worktrees", "delete stale worktrees", "worktrees piling up", "orphaned databases", "remove unused worktree".
+---
+
+# Stale Worktree Cleanup
+
+## Overview
+
+This repo's `.githooks/post-checkout` creates a per-worktree Postgres database (`compdev_<slug>`) on every `git worktree add`. Git has no `pre-worktree-remove` hook, so dead databases pile up over time. This skill defines a safe, reversible process to reap both the worktree directories and their dangling databases together.
+
+**Core principle**: never delete work the user might still want. Classify first, ask second, remove last.
+
+## When to Use
+
+- User says "clean up worktrees", "delete stale worktrees", "remove old worktrees", "worktrees piling up"
+- User mentions orphaned `compdev_*` DBs or running out of disk space from dead `node_modules`
+- Starting a new feature and noticing many old worktree dirs
+
+## When NOT to Use
+
+- User wants to remove ONE specific worktree (just run `git worktree remove <path>` + drop its DB directly — don't load the whole process)
+- User is actively working in a worktree (never touch active work)
+
+## Process
+
+### Step 1 — Inventory
+
+Run these four commands (parallel-safe) and capture the output:
+
+```sh
+git worktree list --porcelain
+gh pr list --author @me --state all --limit 50 --json headRefName,state,url,number
+git branch --no-color | cat
+```
+
+Then query the DB for `compdev_*` databases. The management URL is the main worktree's `DATABASE_URL` with the database path swapped to `postgres`:
+
+```sh
+bun -e '
+  import { Client } from "pg";
+  const raw = require("fs").readFileSync("packages/db/.env", "utf8");
+  const url = raw.match(/^DATABASE_URL=(.*)$/m)[1].replace(/^["\x27]|["\x27]$/g, "");
+  const mgmt = url.replace(/\/[^/?]+(\?|$)/, "/postgres$1");
+  const c = new Client({ connectionString: mgmt });
+  await c.connect();
+  const r = await c.query("SELECT datname FROM pg_database WHERE datname LIKE \x27compdev\\\\_%\x27 ORDER BY 1");
+  for (const row of r.rows) console.log(row.datname);
+  await c.end();
+'
+```
+
+### Step 2 — Classify each worktree
+
+For each worktree (skip the main one):
+
+| Signal | Classification |
+|---|---|
+| Branch merged to main AND clean working tree AND no unpushed commits | **safe** |
+| PR is `CLOSED` (not merged) | **needs-confirm** |
+| Uncommitted changes OR unpushed commits | **needs-confirm** |
+| No matching PR, no merge, has local commits | **keep** (user may still be working on it) |
+| Is the main worktree | **skip** |
+
+Gather per worktree:
+- `cd <path> && git status --porcelain | wc -l` — uncommitted changes count
+- `cd <path> && git log @{upstream}..HEAD --oneline 2>/dev/null | wc -l` — unpushed commits (0 if no upstream)
+- Branch → PR lookup from step 1
+
+### Step 3 — Present to user
+
+Show a table and explicit recommendations. Example:
+
+```
+Path                                    Branch                              PR state  Changes  Recommendation
+.worktrees/sale-45-…                    mariano/sale-45-…                   MERGED    0 / 0    ✅ safe to remove
+.worktrees/old-experiment               mariano/scratch                     —         3 / 0    ⚠ uncommitted — confirm first
+.worktrees/worktree-env-auto-link       mariano/worktree-env-auto-link      OPEN      0 / 0    ⏳ keep (PR open)
+
+Orphan databases (no worktree dir):
+  compdev_abandoned_feature
+  compdev_old_migration_test
+```
+
+Then ask: **"Remove the items marked ✅? Confirm by listing anything you want me to also nuke from the ⚠ / ⏳ set."**
+
+### Step 4 — Remove confirmed items
+
+For each worktree the user approved:
+
+```sh
+# 1. Remove the worktree dir (use --force only if user confirmed dirty-removal)
+git worktree remove "<path>"           # clean case
+git worktree remove --force "<path>"   # only after explicit user OK
+
+# 2. Derive the slug and drop the database
+slug=$(basename "<path>" | tr '[:upper:]' '[:lower:]' | tr '-' '_' | tr -cd 'a-z0-9_')
+bun -e '
+  import { Client } from "pg";
+  const raw = require("fs").readFileSync("packages/db/.env", "utf8");
+  const url = raw.match(/^DATABASE_URL=(.*)$/m)[1].replace(/^["\x27]|["\x27]$/g, "");
+  const mgmt = url.replace(/\/[^/?]+(\?|$)/, "/postgres$1");
+  const c = new Client({ connectionString: mgmt });
+  await c.connect();
+  await c.query(`DROP DATABASE IF EXISTS "compdev_'"$slug"'"`);
+  await c.end();
+  console.log("dropped compdev_'"$slug"'");
+'
+```
+
+For orphan databases (no matching worktree dir), just drop them — no worktree to remove.
+
+**Do NOT** delete the local branch unless the user explicitly asked. Branches can be recreated from `origin` cheaply; worktrees cannot.
+
+### Step 5 — Verify and report
+
+```sh
+git worktree list
+# then re-run the compdev_* query from step 1
+```
+
+Report back:
+- Worktrees removed (paths)
+- Databases dropped (names)
+- Anything skipped and why
+- What's left (still-active worktrees)
+
+## Safety Rules
+
+- **Never remove the main worktree.** Its path is always the first line of `git worktree list --porcelain`.
+- **Never `--force` without confirmation.** Dirty worktrees can contain un-stashed work.
+- **Never `DROP DATABASE` on anything not matching `^compdev_[a-z0-9_]+$`.** Never drop `comp`, `postgres`, or any production-looking name.
+- **Never delete a local branch** as part of cleanup unless the user explicitly asks. Orphaned branches are cheap; lost work isn't.
+- **Never run this inside a worktree you're about to delete.** `cd` to the main worktree first.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Dropping the DB but leaving the worktree dir | Run `git worktree prune` then `git worktree remove` |
+| Removing the worktree but leaving the DB (accumulates orphans) | Always do both in the same pass |
+| Using hyphens in the DB name | The hook slug rule is `tr '-' '_'` — always underscores |
+| Running from inside a doomed worktree | `cd` to the main worktree before starting the process |
+| Using `gh pr list` on a branch with no PR | Missing data is not "abandoned" — needs `needs-confirm` classification |
+
+## Red Flags
+
+If any of these show up mid-process, **stop and ask the user**:
+
+- A worktree has unpushed commits AND no PR → might be unreleased work
+- The classification returned >10 "safe to remove" items → unusual volume, double-check
+- `git worktree remove` errors with "working tree is not clean" → never retry with `--force` without explicit consent
+- A `compdev_*` name has weird characters or unexpected format → don't drop
+
+## Quick Reference
+
+```sh
+# List everything
+git worktree list --porcelain
+gh pr list --author @me --state all --limit 50 --json headRefName,state
+
+# Per-worktree inspection
+git -C <path> status --porcelain
+git -C <path> log @{upstream}..HEAD --oneline 2>/dev/null
+
+# Clean removal
+git worktree remove <path>
+
+# Dirty removal (requires user confirmation first)
+git worktree remove --force <path>
+
+# Database drop (run from main worktree)
+# See the bun -e snippets above for the exact invocation
+```
diff --git a/.agents/skills/trigger-advanced-tasks/SKILL.md b/.agents/skills/trigger-advanced-tasks/SKILL.md
new file mode 100644
index 0000000000..2b18faabf5
--- /dev/null
+++ b/.agents/skills/trigger-advanced-tasks/SKILL.md
@@ -0,0 +1,460 @@
+---
+name: trigger-advanced-tasks
+description: "Comprehensive rules to help you write advanced Trigger.dev tasks"
+---
+
+Source Cursor rule: `.cursor/rules/trigger.advanced-tasks.mdc`.
+Original file scope: `**/trigger/**/*.ts`.
+Original Cursor alwaysApply: `false`.
+
+# Trigger.dev Advanced Tasks (v4)
+
+**Advanced patterns and features for writing tasks**
+
+## Tags & Organization
+
+```ts
+import { task, tags } from '@trigger.dev/sdk';
+
+export const processUser = task({
+  id: 'process-user',
+  run: async (payload: { userId: string; orgId: string }, { ctx }) => {
+    // Add tags during execution
+    await tags.add(`user_${payload.userId}`);
+    await tags.add(`org_${payload.orgId}`);
+
+    return { processed: true };
+  },
+});
+
+// Trigger with tags
+await processUser.trigger(
+  { userId: '123', orgId: 'abc' },
+  { tags: ['priority', 'user_123', 'org_abc'] }, // Max 10 tags per run
+);
+
+// Subscribe to tagged runs
+for await (const run of runs.subscribeToRunsWithTag('user_123')) {
+  console.log(`User task ${run.id}: ${run.status}`);
+}
+```
+
+**Tag Best Practices:**
+
+- Use prefixes: `user_123`, `org_abc`, `video:456`
+- Max 10 tags per run, 1-64 characters each
+- Tags don't propagate to child tasks automatically
+
+## Concurrency & Queues
+
+```ts
+import { task, queue } from '@trigger.dev/sdk';
+
+// Shared queue for related tasks
+const emailQueue = queue({
+  name: 'email-processing',
+  concurrencyLimit: 5, // Max 5 emails processing simultaneously
+});
+
+// Task-level concurrency
+export const oneAtATime = task({
+  id: 'sequential-task',
+  queue: { concurrencyLimit: 1 }, // Process one at a time
+  run: async (payload) => {
+    // Critical section - only one instance runs
+  },
+});
+
+// Per-user concurrency
+export const processUserData = task({
+  id: 'process-user-data',
+  run: async (payload: { userId: string }) => {
+    // Override queue with user-specific concurrency
+    await childTask.trigger(payload, {
+      queue: {
+        name: `user-${payload.userId}`,
+        concurrencyLimit: 2,
+      },
+    });
+  },
+});
+
+export const emailTask = task({
+  id: 'send-email',
+  queue: emailQueue, // Use shared queue
+  run: async (payload: { to: string }) => {
+    // Send email logic
+  },
+});
+```
+
+## Error Handling & Retries
+
+```ts
+import { task, retry, AbortTaskRunError } from '@trigger.dev/sdk';
+
+export const resilientTask = task({
+  id: 'resilient-task',
+  retry: {
+    maxAttempts: 10,
+    factor: 1.8, // Exponential backoff multiplier
+    minTimeoutInMs: 500,
+    maxTimeoutInMs: 30_000,
+    randomize: false,
+  },
+  catchError: async ({ error, ctx }) => {
+    // Custom error handling
+    if (error.code === 'FATAL_ERROR') {
+      throw new AbortTaskRunError('Cannot retry this error');
+    }
+
+    // Log error details
+    console.error(`Task ${ctx.task.id} failed:`, error);
+
+    // Allow retry by returning nothing
+    return { retryAt: new Date(Date.now() + 60000) }; // Retry in 1 minute
+  },
+  run: async (payload) => {
+    // Retry specific operations
+    const result = await retry.onThrow(
+      async () => {
+        return await unstableApiCall(payload);
+      },
+      { maxAttempts: 3 },
+    );
+
+    // Conditional HTTP retries
+    const response = await retry.fetch('https://api.example.com', {
+      retry: {
+        maxAttempts: 5,
+        condition: (response, error) => {
+          return response?.status === 429 || response?.status >= 500;
+        },
+      },
+    });
+
+    return result;
+  },
+});
+```
+
+## Machines & Performance
+
+```ts
+export const heavyTask = task({
+  id: 'heavy-computation',
+  machine: { preset: 'large-2x' }, // 8 vCPU, 16 GB RAM
+  maxDuration: 1800, // 30 minutes timeout
+  run: async (payload, { ctx }) => {
+    // Resource-intensive computation
+    if (ctx.machine.preset === 'large-2x') {
+      // Use all available cores
+      return await parallelProcessing(payload);
+    }
+
+    return await standardProcessing(payload);
+  },
+});
+
+// Override machine when triggering
+await heavyTask.trigger(payload, {
+  machine: { preset: 'medium-1x' }, // Override for this run
+});
+```
+
+**Machine Presets:**
+
+- `micro`: 0.25 vCPU, 0.25 GB RAM
+- `small-1x`: 0.5 vCPU, 0.5 GB RAM (default)
+- `small-2x`: 1 vCPU, 1 GB RAM
+- `medium-1x`: 1 vCPU, 2 GB RAM
+- `medium-2x`: 2 vCPU, 4 GB RAM
+- `large-1x`: 4 vCPU, 8 GB RAM
+- `large-2x`: 8 vCPU, 16 GB RAM
+
+## Idempotency
+
+```ts
+import { task, idempotencyKeys } from '@trigger.dev/sdk';
+
+export const paymentTask = task({
+  id: 'process-payment',
+  retry: {
+    maxAttempts: 3,
+  },
+  run: async (payload: { orderId: string; amount: number }) => {
+    // Automatically scoped to this task run, so if the task is retried, the idempotency key will be the same
+    const idempotencyKey = await idempotencyKeys.create(`payment-${payload.orderId}`);
+
+    // Ensure payment is processed only once
+    await chargeCustomer.trigger(payload, {
+      idempotencyKey,
+      idempotencyKeyTTL: '24h', // Key expires in 24 hours
+    });
+  },
+});
+
+// Payload-based idempotency
+import { createHash } from 'node:crypto';
+
+function createPayloadHash(payload: any): string {
+  const hash = createHash('sha256');
+  hash.update(JSON.stringify(payload));
+  return hash.digest('hex');
+}
+
+export const deduplicatedTask = task({
+  id: 'deduplicated-task',
+  run: async (payload) => {
+    const payloadHash = createPayloadHash(payload);
+    const idempotencyKey = await idempotencyKeys.create(payloadHash);
+
+    await processData.trigger(payload, { idempotencyKey });
+  },
+});
+```
+
+## Metadata & Progress Tracking
+
+```ts
+import { task, metadata } from '@trigger.dev/sdk';
+
+export const batchProcessor = task({
+  id: 'batch-processor',
+  run: async (payload: { items: any[] }, { ctx }) => {
+    const totalItems = payload.items.length;
+
+    // Initialize progress metadata
+    metadata
+      .set('progress', 0)
+      .set('totalItems', totalItems)
+      .set('processedItems', 0)
+      .set('status', 'starting');
+
+    const results = [];
+
+    for (let i = 0; i < payload.items.length; i++) {
+      const item = payload.items[i];
+
+      // Process item
+      const result = await processItem(item);
+      results.push(result);
+
+      // Update progress
+      const progress = ((i + 1) / totalItems) * 100;
+      metadata
+        .set('progress', progress)
+        .increment('processedItems', 1)
+        .append('logs', `Processed item ${i + 1}/${totalItems}`)
+        .set('currentItem', item.id);
+    }
+
+    // Final status
+    metadata.set('status', 'completed');
+
+    return { results, totalProcessed: results.length };
+  },
+});
+
+// Update parent metadata from child task
+export const childTask = task({
+  id: 'child-task',
+  run: async (payload, { ctx }) => {
+    // Update parent task metadata
+    metadata.parent.set('childStatus', 'processing');
+    metadata.root.increment('childrenCompleted', 1);
+
+    return { processed: true };
+  },
+});
+```
+
+## Advanced Triggering
+
+### Frontend Triggering (React)
+
+```tsx
+'use client';
+import { useTaskTrigger } from '@trigger.dev/react-hooks';
+import type { myTask } from '../trigger/tasks';
+
+function TriggerButton({ accessToken }: { accessToken: string }) {
+  const { submit, handle, isLoading } = useTaskTrigger<typeof myTask>('my-task', { accessToken });
+
+  return (
+    <button onClick={() => submit({ data: 'from frontend' })} disabled={isLoading}>
+      Trigger Task
+    </button>
+  );
+}
+```
+
+### Large Payloads
+
+```ts
+// For payloads > 512KB (max 10MB)
+export const largeDataTask = task({
+  id: 'large-data-task',
+  run: async (payload: { dataUrl: string }) => {
+    // Trigger.dev automatically handles large payloads
+    // For > 10MB, use external storage
+    const response = await fetch(payload.dataUrl);
+    const largeData = await response.json();
+
+    return { processed: largeData.length };
+  },
+});
+
+// Best practice: Use presigned URLs for very large files
+await largeDataTask.trigger({
+  dataUrl: 'https://s3.amazonaws.com/bucket/large-file.json?presigned=true',
+});
+```
+
+### Advanced Options
+
+```ts
+await myTask.trigger(payload, {
+  delay: '2h30m', // Delay execution
+  ttl: '24h', // Expire if not started within 24 hours
+  priority: 100, // Higher priority (time offset in seconds)
+  tags: ['urgent', 'user_123'],
+  metadata: { source: 'api', version: 'v2' },
+  queue: {
+    name: 'priority-queue',
+    concurrencyLimit: 10,
+  },
+  idempotencyKey: 'unique-operation-id',
+  idempotencyKeyTTL: '1h',
+  machine: { preset: 'large-1x' },
+  maxAttempts: 5,
+});
+```
+
+## Hidden Tasks
+
+```ts
+// Hidden task - not exported, only used internally
+const internalProcessor = task({
+  id: 'internal-processor',
+  run: async (payload: { data: string }) => {
+    return { processed: payload.data.toUpperCase() };
+  },
+});
+
+// Public task that uses hidden task
+export const publicWorkflow = task({
+  id: 'public-workflow',
+  run: async (payload: { input: string }) => {
+    // Use hidden task internally
+    const result = await internalProcessor.triggerAndWait({
+      data: payload.input,
+    });
+
+    if (result.ok) {
+      return { output: result.output.processed };
+    }
+
+    throw new Error('Internal processing failed');
+  },
+});
+```
+
+## Logging & Tracing
+
+```ts
+import { task, logger } from '@trigger.dev/sdk';
+
+export const tracedTask = task({
+  id: 'traced-task',
+  run: async (payload, { ctx }) => {
+    logger.info('Task started', { userId: payload.userId });
+
+    // Custom trace with attributes
+    const user = await logger.trace(
+      'fetch-user',
+      async (span) => {
+        span.setAttribute('user.id', payload.userId);
+        span.setAttribute('operation', 'database-fetch');
+
+        const userData = await database.findUser(payload.userId);
+        span.setAttribute('user.found', !!userData);
+
+        return userData;
+      },
+      { userId: payload.userId },
+    );
+
+    logger.debug('User fetched', { user: user.id });
+
+    try {
+      const result = await processUser(user);
+      logger.info('Processing completed', { result });
+      return result;
+    } catch (error) {
+      logger.error('Processing failed', {
+        error: error.message,
+        userId: payload.userId,
+      });
+      throw error;
+    }
+  },
+});
+```
+
+## Usage Monitoring
+
+```ts
+import { task, usage } from '@trigger.dev/sdk';
+
+export const monitoredTask = task({
+  id: 'monitored-task',
+  run: async (payload) => {
+    // Get current run cost
+    const currentUsage = await usage.getCurrent();
+    logger.info('Current cost', {
+      costInCents: currentUsage.costInCents,
+      durationMs: currentUsage.durationMs,
+    });
+
+    // Measure specific operation
+    const { result, compute } = await usage.measure(async () => {
+      return await expensiveOperation(payload);
+    });
+
+    logger.info('Operation cost', {
+      costInCents: compute.costInCents,
+      durationMs: compute.durationMs,
+    });
+
+    return result;
+  },
+});
+```
+
+## Run Management
+
+```ts
+// Cancel runs
+await runs.cancel('run_123');
+
+// Replay runs with same payload
+await runs.replay('run_123');
+
+// Retrieve run with cost details
+const run = await runs.retrieve('run_123');
+console.log(`Cost: ${run.costInCents} cents, Duration: ${run.durationMs}ms`);
+```
+
+## Best Practices
+
+- **Concurrency**: Use queues to prevent overwhelming external services
+- **Retries**: Configure exponential backoff for transient failures
+- **Idempotency**: Always use for payment/critical operations
+- **Metadata**: Track progress for long-running tasks
+- **Machines**: Match machine size to computational requirements
+- **Tags**: Use consistent naming patterns for filtering
+- **Large Payloads**: Use external storage for files > 10MB
+- **Error Handling**: Distinguish between retryable and fatal errors
+
+Design tasks to be stateless, idempotent, and resilient to failures. Use metadata for state tracking and queues for resource management.
diff --git a/.agents/skills/trigger-basic/SKILL.md b/.agents/skills/trigger-basic/SKILL.md
new file mode 100644
index 0000000000..3efd8127fc
--- /dev/null
+++ b/.agents/skills/trigger-basic/SKILL.md
@@ -0,0 +1,194 @@
+---
+name: trigger-basic
+description: "Only the most important rules for writing basic Trigger.dev tasks"
+---
+
+Source Cursor rule: `.cursor/rules/trigger.basic.mdc`.
+Original file scope: `**/trigger/**/*.ts`.
+Original Cursor alwaysApply: `false`.
+
+# Trigger.dev Basic Tasks (v4)
+
+**MUST use `@trigger.dev/sdk` (v4), NEVER `client.defineJob`**
+
+## Basic Task
+
+```ts
+import { task } from "@trigger.dev/sdk";
+
+export const processData = task({
+  id: "process-data",
+  retry: {
+    maxAttempts: 10,
+    factor: 1.8,
+    minTimeoutInMs: 500,
+    maxTimeoutInMs: 30_000,
+    randomize: false,
+  },
+  run: async (payload: { userId: string; data: any[] }) => {
+    // Task logic - runs for long time, no timeouts
+    console.log(`Processing ${payload.data.length} items for user ${payload.userId}`);
+    return { processed: payload.data.length };
+  },
+});
+```
+
+## Schema Task (with validation)
+
+```ts
+import { schemaTask } from "@trigger.dev/sdk";
+import { z } from "zod";
+
+export const validatedTask = schemaTask({
+  id: "validated-task",
+  schema: z.object({
+    name: z.string(),
+    age: z.number(),
+    email: z.string().email(),
+  }),
+  run: async (payload) => {
+    // Payload is automatically validated and typed
+    return { message: `Hello ${payload.name}, age ${payload.age}` };
+  },
+});
+```
+
+## Scheduled Task
+
+```ts
+import { schedules } from "@trigger.dev/sdk";
+
+const dailyReport = schedules.task({
+  id: "daily-report",
+  cron: "0 9 * * *", // Daily at 9:00 AM UTC
+  // or with timezone: cron: { pattern: "0 9 * * *", timezone: "America/New_York" },
+  run: async (payload) => {
+    console.log("Scheduled run at:", payload.timestamp);
+    console.log("Last run was:", payload.lastTimestamp);
+    console.log("Next 5 runs:", payload.upcoming);
+
+    // Generate daily report logic
+    return { reportGenerated: true, date: payload.timestamp };
+  },
+});
+```
+
+## Triggering Tasks
+
+### From Backend Code
+
+```ts
+import { tasks } from "@trigger.dev/sdk";
+import type { processData } from "./trigger/tasks";
+
+// Single trigger
+const handle = await tasks.trigger<typeof processData>("process-data", {
+  userId: "123",
+  data: [{ id: 1 }, { id: 2 }],
+});
+
+// Batch trigger
+const batchHandle = await tasks.batchTrigger<typeof processData>("process-data", [
+  { payload: { userId: "123", data: [{ id: 1 }] } },
+  { payload: { userId: "456", data: [{ id: 2 }] } },
+]);
+```
+
+### From Inside Tasks (with Result handling)
+
+```ts
+export const parentTask = task({
+  id: "parent-task",
+  run: async (payload) => {
+    // Trigger and continue
+    const handle = await childTask.trigger({ data: "value" });
+
+    // Trigger and wait - returns Result object, NOT task output
+    const result = await childTask.triggerAndWait({ data: "value" });
+    if (result.ok) {
+      console.log("Task output:", result.output); // Actual task return value
+    } else {
+      console.error("Task failed:", result.error);
+    }
+
+    // Quick unwrap (throws on error)
+    const output = await childTask.triggerAndWait({ data: "value" }).unwrap();
+
+    // Batch trigger and wait
+    const results = await childTask.batchTriggerAndWait([
+      { payload: { data: "item1" } },
+      { payload: { data: "item2" } },
+    ]);
+
+    for (const run of results) {
+      if (run.ok) {
+        console.log("Success:", run.output);
+      } else {
+        console.log("Failed:", run.error);
+      }
+    }
+  },
+});
+
+export const childTask = task({
+  id: "child-task",
+  run: async (payload: { data: string }) => {
+    return { processed: payload.data };
+  },
+});
+```
+
+> Never wrap triggerAndWait or batchTriggerAndWait calls in a Promise.all or Promise.allSettled as this is not supported in Trigger.dev tasks.
+
+## Waits
+
+```ts
+import { task, wait } from "@trigger.dev/sdk";
+
+export const taskWithWaits = task({
+  id: "task-with-waits",
+  run: async (payload) => {
+    console.log("Starting task");
+
+    // Wait for specific duration
+    await wait.for({ seconds: 30 });
+    await wait.for({ minutes: 5 });
+    await wait.for({ hours: 1 });
+    await wait.for({ days: 1 });
+
+    // Wait until specific date
+    await wait.until({ date: new Date("2024-12-25") });
+
+    // Wait for token (from external system)
+    await wait.forToken({
+      token: "user-approval-token",
+      timeoutInSeconds: 3600, // 1 hour timeout
+    });
+
+    console.log("All waits completed");
+    return { status: "completed" };
+  },
+});
+```
+
+> Never wrap wait calls in a Promise.all or Promise.allSettled as this is not supported in Trigger.dev tasks.
+
+## Key Points
+
+- **Result vs Output**: `triggerAndWait()` returns a `Result` object with `ok`, `output`, `error` properties - NOT the direct task output
+- **Type safety**: Use `import type` for task references when triggering from backend
+- **Waits > 5 seconds**: Automatically checkpointed, don't count toward compute usage
+
+## NEVER Use (v2 deprecated)
+
+```ts
+// BREAKS APPLICATION
+client.defineJob({
+  id: "job-id",
+  run: async (payload, io) => {
+    /* ... */
+  },
+});
+```
+
+Use v4 SDK (`@trigger.dev/sdk`), check `result.ok` before accessing `result.output`
diff --git a/.agents/skills/trigger-config/SKILL.md b/.agents/skills/trigger-config/SKILL.md
new file mode 100644
index 0000000000..a55d845fdf
--- /dev/null
+++ b/.agents/skills/trigger-config/SKILL.md
@@ -0,0 +1,355 @@
+---
+name: trigger-config
+description: "Configure your Trigger.dev project with a trigger.config.ts file"
+---
+
+Source Cursor rule: `.cursor/rules/trigger.config.mdc`.
+Original file scope: `**/trigger.config.ts`.
+Original Cursor alwaysApply: `false`.
+
+# Trigger.dev Configuration (v4)
+
+**Complete guide to configuring `trigger.config.ts` with build extensions**
+
+## Basic Configuration
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk";
+
+export default defineConfig({
+  project: "<project-ref>", // Required: Your project reference
+  dirs: ["./trigger"], // Task directories
+  runtime: "node", // "node", "node-22", or "bun"
+  logLevel: "info", // "debug", "info", "warn", "error"
+
+  // Default retry settings
+  retries: {
+    enabledInDev: false,
+    default: {
+      maxAttempts: 3,
+      minTimeoutInMs: 1000,
+      maxTimeoutInMs: 10000,
+      factor: 2,
+      randomize: true,
+    },
+  },
+
+  // Build configuration
+  build: {
+    autoDetectExternal: true,
+    keepNames: true,
+    minify: false,
+    extensions: [], // Build extensions go here
+  },
+
+  // Global lifecycle hooks
+  onStart: async ({ payload, ctx }) => {
+    console.log("Global task start");
+  },
+  onSuccess: async ({ payload, output, ctx }) => {
+    console.log("Global task success");
+  },
+  onFailure: async ({ payload, error, ctx }) => {
+    console.log("Global task failure");
+  },
+});
+```
+
+## Build Extensions
+
+### Database & ORM
+
+#### Prisma
+
+```ts
+import { prismaExtension } from "@trigger.dev/build/extensions/prisma";
+
+extensions: [
+  prismaExtension({
+    schema: "prisma/schema.prisma",
+    version: "5.19.0", // Optional: specify version
+    migrate: true, // Run migrations during build
+    directUrlEnvVarName: "DIRECT_DATABASE_URL",
+    typedSql: true, // Enable TypedSQL support
+  }),
+];
+```
+
+#### TypeScript Decorators (for TypeORM)
+
+```ts
+import { emitDecoratorMetadata } from "@trigger.dev/build/extensions/typescript";
+
+extensions: [
+  emitDecoratorMetadata(), // Enables decorator metadata
+];
+```
+
+### Scripting Languages
+
+#### Python
+
+```ts
+import { pythonExtension } from "@trigger.dev/build/extensions/python";
+
+extensions: [
+  pythonExtension({
+    scripts: ["./python/**/*.py"], // Copy Python files
+    requirementsFile: "./requirements.txt", // Install packages
+    devPythonBinaryPath: ".venv/bin/python", // Dev mode binary
+  }),
+];
+
+// Usage in tasks
+const result = await python.runInline(`print("Hello, world!")`);
+const output = await python.runScript("./python/script.py", ["arg1"]);
+```
+
+### Browser Automation
+
+#### Playwright
+
+```ts
+import { playwright } from "@trigger.dev/build/extensions/playwright";
+
+extensions: [
+  playwright({
+    browsers: ["chromium", "firefox", "webkit"], // Default: ["chromium"]
+    headless: true, // Default: true
+  }),
+];
+```
+
+#### Puppeteer
+
+```ts
+import { puppeteer } from "@trigger.dev/build/extensions/puppeteer";
+
+extensions: [puppeteer()];
+
+// Environment variable needed:
+// PUPPETEER_EXECUTABLE_PATH: "/usr/bin/google-chrome-stable"
+```
+
+#### Lightpanda
+
+```ts
+import { lightpanda } from "@trigger.dev/build/extensions/lightpanda";
+
+extensions: [
+  lightpanda({
+    version: "latest", // or "nightly"
+    disableTelemetry: false,
+  }),
+];
+```
+
+### Media Processing
+
+#### FFmpeg
+
+```ts
+import { ffmpeg } from "@trigger.dev/build/extensions/core";
+
+extensions: [
+  ffmpeg({ version: "7" }), // Static build, or omit for Debian version
+];
+
+// Automatically sets FFMPEG_PATH and FFPROBE_PATH
+// Add fluent-ffmpeg to external packages if using
+```
+
+#### Audio Waveform
+
+```ts
+import { audioWaveform } from "@trigger.dev/build/extensions/audioWaveform";
+
+extensions: [
+  audioWaveform(), // Installs Audio Waveform 1.1.0
+];
+```
+
+### System & Package Management
+
+#### System Packages (apt-get)
+
+```ts
+import { aptGet } from "@trigger.dev/build/extensions/core";
+
+extensions: [
+  aptGet({
+    packages: ["ffmpeg", "imagemagick", "curl=7.68.0-1"], // Can specify versions
+  }),
+];
+```
+
+#### Additional NPM Packages
+
+Only use this for installing CLI tools, NOT packages you import in your code.
+
+```ts
+import { additionalPackages } from "@trigger.dev/build/extensions/core";
+
+extensions: [
+  additionalPackages({
+    packages: ["wrangler"], // CLI tools and specific versions
+  }),
+];
+```
+
+#### Additional Files
+
+```ts
+import { additionalFiles } from "@trigger.dev/build/extensions/core";
+
+extensions: [
+  additionalFiles({
+    files: ["wrangler.toml", "./assets/**", "./fonts/**"], // Glob patterns supported
+  }),
+];
+```
+
+### Environment & Build Tools
+
+#### Environment Variable Sync
+
+```ts
+import { syncEnvVars } from "@trigger.dev/build/extensions/core";
+
+extensions: [
+  syncEnvVars(async (ctx) => {
+    // ctx contains: environment, projectRef, env
+    return [
+      { name: "SECRET_KEY", value: await getSecret(ctx.environment) },
+      { name: "API_URL", value: ctx.environment === "prod" ? "api.prod.com" : "api.dev.com" },
+    ];
+  }),
+];
+```
+
+#### ESBuild Plugins
+
+```ts
+import { esbuildPlugin } from "@trigger.dev/build/extensions";
+import { sentryEsbuildPlugin } from "@sentry/esbuild-plugin";
+
+extensions: [
+  esbuildPlugin(
+    sentryEsbuildPlugin({
+      org: process.env.SENTRY_ORG,
+      project: process.env.SENTRY_PROJECT,
+      authToken: process.env.SENTRY_AUTH_TOKEN,
+    }),
+    { placement: "last", target: "deploy" } // Optional config
+  ),
+];
+```
+
+## Custom Build Extensions
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk";
+
+const customExtension = {
+  name: "my-custom-extension",
+
+  externalsForTarget: (target) => {
+    return ["some-native-module"]; // Add external dependencies
+  },
+
+  onBuildStart: async (context) => {
+    console.log(`Build starting for ${context.target}`);
+    // Register esbuild plugins, modify build context
+  },
+
+  onBuildComplete: async (context, manifest) => {
+    console.log("Build complete, adding layers");
+    // Add build layers, modify deployment
+    context.addLayer({
+      id: "my-layer",
+      files: [{ source: "./custom-file", destination: "/app/custom" }],
+      commands: ["chmod +x /app/custom"],
+    });
+  },
+};
+
+export default defineConfig({
+  project: "my-project",
+  build: {
+    extensions: [customExtension],
+  },
+});
+```
+
+## Advanced Configuration
+
+### Telemetry
+
+```ts
+import { PrismaInstrumentation } from "@prisma/instrumentation";
+import { OpenAIInstrumentation } from "@langfuse/openai";
+
+export default defineConfig({
+  // ... other config
+  telemetry: {
+    instrumentations: [new PrismaInstrumentation(), new OpenAIInstrumentation()],
+    exporters: [customExporter], // Optional custom exporters
+  },
+});
+```
+
+### Machine & Performance
+
+```ts
+export default defineConfig({
+  // ... other config
+  defaultMachine: "large-1x", // Default machine for all tasks
+  maxDuration: 300, // Default max duration (seconds)
+  enableConsoleLogging: true, // Console logging in development
+});
+```
+
+## Common Extension Combinations
+
+### Full-Stack Web App
+
+```ts
+extensions: [
+  prismaExtension({ schema: "prisma/schema.prisma", migrate: true }),
+  additionalFiles({ files: ["./public/**", "./assets/**"] }),
+  syncEnvVars(async (ctx) => [...envVars]),
+];
+```
+
+### AI/ML Processing
+
+```ts
+extensions: [
+  pythonExtension({
+    scripts: ["./ai/**/*.py"],
+    requirementsFile: "./requirements.txt",
+  }),
+  ffmpeg({ version: "7" }),
+  additionalPackages({ packages: ["wrangler"] }),
+];
+```
+
+### Web Scraping
+
+```ts
+extensions: [
+  playwright({ browsers: ["chromium"] }),
+  puppeteer(),
+  additionalFiles({ files: ["./selectors.json", "./proxies.txt"] }),
+];
+```
+
+## Best Practices
+
+- **Use specific versions**: Pin extension versions for reproducible builds
+- **External packages**: Add modules with native addons to the `build.external` array
+- **Environment sync**: Use `syncEnvVars` for dynamic secrets
+- **File paths**: Use glob patterns for flexible file inclusion
+- **Debug builds**: Use `--log-level debug --dry-run` for troubleshooting
+
+Extensions only affect deployment, not local development. Use `external` array for packages that shouldn't be bundled.
diff --git a/.agents/skills/trigger-realtime/SKILL.md b/.agents/skills/trigger-realtime/SKILL.md
new file mode 100644
index 0000000000..872e7a1ab0
--- /dev/null
+++ b/.agents/skills/trigger-realtime/SKILL.md
@@ -0,0 +1,281 @@
+---
+name: trigger-realtime
+description: "How to use realtime in your Trigger.dev tasks and your frontend"
+---
+
+Source Cursor rule: `.cursor/rules/trigger.realtime.mdc`.
+Original file scope: `**/trigger/**/*.ts`.
+Original Cursor alwaysApply: `false`.
+
+# Trigger.dev Realtime (v4)
+
+**Real-time monitoring and updates for runs**
+
+## Core Concepts
+
+Realtime allows you to:
+
+- Subscribe to run status changes, metadata updates, and streams
+- Build real-time dashboards and UI updates
+- Monitor task progress from frontend and backend
+
+## Authentication
+
+### Public Access Tokens
+
+```ts
+import { auth } from "@trigger.dev/sdk";
+
+// Read-only token for specific runs
+const publicToken = await auth.createPublicToken({
+  scopes: {
+    read: {
+      runs: ["run_123", "run_456"],
+      tasks: ["my-task-1", "my-task-2"],
+    },
+  },
+  expirationTime: "1h", // Default: 15 minutes
+});
+```
+
+### Trigger Tokens (Frontend only)
+
+```ts
+// Single-use token for triggering tasks
+const triggerToken = await auth.createTriggerPublicToken("my-task", {
+  expirationTime: "30m",
+});
+```
+
+## Backend Usage
+
+### Subscribe to Runs
+
+```ts
+import { runs, tasks } from "@trigger.dev/sdk";
+
+// Trigger and subscribe
+const handle = await tasks.trigger("my-task", { data: "value" });
+
+// Subscribe to specific run
+for await (const run of runs.subscribeToRun<typeof myTask>(handle.id)) {
+  console.log(`Status: ${run.status}, Progress: ${run.metadata?.progress}`);
+  if (run.status === "COMPLETED") break;
+}
+
+// Subscribe to runs with tag
+for await (const run of runs.subscribeToRunsWithTag("user-123")) {
+  console.log(`Tagged run ${run.id}: ${run.status}`);
+}
+
+// Subscribe to batch
+for await (const run of runs.subscribeToBatch(batchId)) {
+  console.log(`Batch run ${run.id}: ${run.status}`);
+}
+```
+
+### Streams
+
+```ts
+import { task, metadata } from "@trigger.dev/sdk";
+
+// Task that streams data
+export type STREAMS = {
+  openai: OpenAI.ChatCompletionChunk;
+};
+
+export const streamingTask = task({
+  id: "streaming-task",
+  run: async (payload) => {
+    const completion = await openai.chat.completions.create({
+      model: "gpt-4",
+      messages: [{ role: "user", content: payload.prompt }],
+      stream: true,
+    });
+
+    // Register stream
+    const stream = await metadata.stream("openai", completion);
+
+    let text = "";
+    for await (const chunk of stream) {
+      text += chunk.choices[0]?.delta?.content || "";
+    }
+
+    return { text };
+  },
+});
+
+// Subscribe to streams
+for await (const part of runs.subscribeToRun(runId).withStreams<STREAMS>()) {
+  switch (part.type) {
+    case "run":
+      console.log("Run update:", part.run.status);
+      break;
+    case "openai":
+      console.log("Stream chunk:", part.chunk);
+      break;
+  }
+}
+```
+
+## React Frontend Usage
+
+### Installation
+
+```bash
+bun add @trigger.dev/react-hooks
+```
+
+### Triggering Tasks
+
+```tsx
+"use client";
+import { useTaskTrigger, useRealtimeTaskTrigger } from "@trigger.dev/react-hooks";
+import type { myTask } from "../trigger/tasks";
+
+function TriggerComponent({ accessToken }: { accessToken: string }) {
+  // Basic trigger
+  const { submit, handle, isLoading } = useTaskTrigger<typeof myTask>("my-task", {
+    accessToken,
+  });
+
+  // Trigger with realtime updates
+  const {
+    submit: realtimeSubmit,
+    run,
+    isLoading: isRealtimeLoading,
+  } = useRealtimeTaskTrigger<typeof myTask>("my-task", { accessToken });
+
+  return (
+    <div>
+      <button onClick={() => submit({ data: "value" })} disabled={isLoading}>
+        Trigger Task
+      </button>
+
+      <button onClick={() => realtimeSubmit({ data: "realtime" })} disabled={isRealtimeLoading}>
+        Trigger with Realtime
+      </button>
+
+      {run && <div>Status: {run.status}</div>}
+    </div>
+  );
+}
+```
+
+### Subscribing to Runs
+
+```tsx
+"use client";
+import { useRealtimeRun, useRealtimeRunsWithTag } from "@trigger.dev/react-hooks";
+import type { myTask } from "../trigger/tasks";
+
+function SubscribeComponent({ runId, accessToken }: { runId: string; accessToken: string }) {
+  // Subscribe to specific run
+  const { run, error } = useRealtimeRun<typeof myTask>(runId, {
+    accessToken,
+    onComplete: (run) => {
+      console.log("Task completed:", run.output);
+    },
+  });
+
+  // Subscribe to tagged runs
+  const { runs } = useRealtimeRunsWithTag("user-123", { accessToken });
+
+  if (error) return <div>Error: {error.message}</div>;
+  if (!run) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <div>Status: {run.status}</div>
+      <div>Progress: {run.metadata?.progress || 0}%</div>
+      {run.output && <div>Result: {JSON.stringify(run.output)}</div>}
+
+      <h3>Tagged Runs:</h3>
+      {runs.map((r) => (
+        <div key={r.id}>
+          {r.id}: {r.status}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### Streams with React
+
+```tsx
+"use client";
+import { useRealtimeRunWithStreams } from "@trigger.dev/react-hooks";
+import type { streamingTask, STREAMS } from "../trigger/tasks";
+
+function StreamComponent({ runId, accessToken }: { runId: string; accessToken: string }) {
+  const { run, streams } = useRealtimeRunWithStreams<typeof streamingTask, STREAMS>(runId, {
+    accessToken,
+  });
+
+  const text = streams.openai
+    .filter((chunk) => chunk.choices[0]?.delta?.content)
+    .map((chunk) => chunk.choices[0].delta.content)
+    .join("");
+
+  return (
+    <div>
+      <div>Status: {run?.status}</div>
+      <div>Streamed Text: {text}</div>
+    </div>
+  );
+}
+```
+
+### Wait Tokens
+
+```tsx
+"use client";
+import { useWaitToken } from "@trigger.dev/react-hooks";
+
+function WaitTokenComponent({ tokenId, accessToken }: { tokenId: string; accessToken: string }) {
+  const { complete } = useWaitToken(tokenId, { accessToken });
+
+  return <button onClick={() => complete({ approved: true })}>Approve Task</button>;
+}
+```
+
+### SWR Hooks (Fetch Once)
+
+```tsx
+"use client";
+import { useRun } from "@trigger.dev/react-hooks";
+import type { myTask } from "../trigger/tasks";
+
+function SWRComponent({ runId, accessToken }: { runId: string; accessToken: string }) {
+  const { run, error, isLoading } = useRun<typeof myTask>(runId, {
+    accessToken,
+    refreshInterval: 0, // Disable polling (recommended)
+  });
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return <div>Run: {run?.status}</div>;
+}
+```
+
+## Run Object Properties
+
+Key properties available in run subscriptions:
+
+- `id`: Unique run identifier
+- `status`: `QUEUED`, `EXECUTING`, `COMPLETED`, `FAILED`, `CANCELED`, etc.
+- `payload`: Task input data (typed)
+- `output`: Task result (typed, when completed)
+- `metadata`: Real-time updatable data
+- `createdAt`, `updatedAt`: Timestamps
+- `costInCents`: Execution cost
+
+## Best Practices
+
+- **Use Realtime over SWR**: Recommended for most use cases due to rate limits
+- **Scope tokens properly**: Only grant necessary read/trigger permissions
+- **Handle errors**: Always check for errors in hooks and subscriptions
+- **Type safety**: Use task types for proper payload/output typing
+- **Cleanup subscriptions**: Backend subscriptions auto-complete, frontend hooks auto-cleanup
diff --git a/.agents/skills/trigger-scheduled-tasks/SKILL.md b/.agents/skills/trigger-scheduled-tasks/SKILL.md
new file mode 100644
index 0000000000..911df52259
--- /dev/null
+++ b/.agents/skills/trigger-scheduled-tasks/SKILL.md
@@ -0,0 +1,126 @@
+---
+name: trigger-scheduled-tasks
+description: "How to write and use scheduled Trigger.dev tasks"
+---
+
+Source Cursor rule: `.cursor/rules/trigger.scheduled-tasks.mdc`.
+Original file scope: `**/trigger/**/*.ts`.
+Original Cursor alwaysApply: `false`.
+
+# Scheduled tasks (cron)
+
+Recurring tasks using cron. For one-off future runs, use the **delay** option.
+
+## Define a scheduled task
+
+```ts
+import { schedules } from "@trigger.dev/sdk";
+
+export const task = schedules.task({
+  id: "first-scheduled-task",
+  run: async (payload) => {
+    payload.timestamp; // Date (scheduled time, UTC)
+    payload.lastTimestamp; // Date | undefined
+    payload.timezone; // IANA, e.g. "America/New_York" (default "UTC")
+    payload.scheduleId; // string
+    payload.externalId; // string | undefined
+    payload.upcoming; // Date[]
+
+    payload.timestamp.toLocaleString("en-US", { timeZone: payload.timezone });
+  },
+});
+```
+
+> Scheduled tasks need at least one schedule attached to run.
+
+## Attach schedules
+
+**Declarative (sync on dev/deploy):**
+
+```ts
+schedules.task({
+  id: "every-2h",
+  cron: "0 */2 * * *", // UTC
+  run: async () => {},
+});
+
+schedules.task({
+  id: "tokyo-5am",
+  cron: { pattern: "0 5 * * *", timezone: "Asia/Tokyo", environments: ["PRODUCTION", "STAGING"] },
+  run: async () => {},
+});
+```
+
+**Imperative (SDK or dashboard):**
+
+```ts
+await schedules.create({
+  task: task.id,
+  cron: "0 0 * * *",
+  timezone: "America/New_York", // DST-aware
+  externalId: "user_123",
+  deduplicationKey: "user_123-daily", // updates if reused
+});
+```
+
+### Dynamic / multi-tenant example
+
+```ts
+// /trigger/reminder.ts
+export const reminderTask = schedules.task({
+  id: "todo-reminder",
+  run: async (p) => {
+    if (!p.externalId) throw new Error("externalId is required");
+    const user = await db.getUser(p.externalId);
+    await sendReminderEmail(user);
+  },
+});
+```
+
+```ts
+// app/reminders/route.ts
+export async function POST(req: Request) {
+  const data = await req.json();
+  return Response.json(
+    await schedules.create({
+      task: reminderTask.id,
+      cron: "0 8 * * *",
+      timezone: data.timezone,
+      externalId: data.userId,
+      deduplicationKey: `${data.userId}-reminder`,
+    })
+  );
+}
+```
+
+## Cron syntax (no seconds)
+
+```
+* * * * *
+| | | | └ day of week (0–7 or 1L–7L; 0/7=Sun; L=last)
+| | | └── month (1–12)
+| | └──── day of month (1–31 or L)
+| └────── hour (0–23)
+└──────── minute (0–59)
+```
+
+## When schedules won't trigger
+
+- **Dev:** only when the dev CLI is running.
+- **Staging/Production:** only for tasks in the **latest deployment**.
+
+## SDK management (quick refs)
+
+```ts
+await schedules.retrieve(id);
+await schedules.list();
+await schedules.update(id, { cron: "0 0 1 * *", externalId: "ext", deduplicationKey: "key" });
+await schedules.deactivate(id);
+await schedules.activate(id);
+await schedules.del(id);
+await schedules.timezones(); // list of IANA timezones
+```
+
+## Dashboard
+
+Create/attach schedules visually (Task, Cron pattern, Timezone, Optional: External ID, Dedup key, Environments). Test scheduled tasks from the **Test** page.
diff --git a/.agents/skills/ui/SKILL.md b/.agents/skills/ui/SKILL.md
new file mode 100644
index 0000000000..7dc3e4edfd
--- /dev/null
+++ b/.agents/skills/ui/SKILL.md
@@ -0,0 +1,137 @@
+---
+name: ui
+description: "Use when building or editing frontend UI components, layouts, styling, design system usage, colors, dark mode, or icons."
+---
+
+Source Cursor rule: `.cursor/rules/ui.mdc`.
+Original Cursor alwaysApply: `true`.
+
+# UI Components
+
+## Design System Priority
+
+1. **First choice:** `@trycompai/design-system`
+2. **Fallback:** `@trycompai/ui` only if DS doesn't have the component
+
+```tsx
+// ✅ Design system
+import { Button, Card, Input, Sheet, Badge } from '@trycompai/design-system';
+import { Add, Close, ArrowRight } from '@trycompai/design-system/icons';
+
+// ❌ Don't use when DS has it
+import { Button } from '@trycompai/ui/button';
+import { Plus } from 'lucide-react';
+```
+
+## No className on DS Components
+
+DS components don't accept `className`. Use variants and props only.
+
+```tsx
+// ✅ Use variants
+<Button variant="destructive" size="sm" loading={isLoading}>Delete</Button>
+<Button type="submit" iconRight={<ArrowRight size={16} />}>Continue</Button>
+<Badge variant="outline">Active</Badge>
+
+// ❌ TypeScript will error
+<Button className="bg-red-500">Delete</Button>
+```
+
+## Layout with Wrapper Divs
+
+For layout concerns, wrap DS components:
+
+```tsx
+// ✅ Wrapper for width
+<div className="w-full">
+  <Button>Full Width</Button>
+</div>
+
+// ✅ Use Stack for spacing
+<Stack gap="4" direction="row">
+  <Button>First</Button>
+  <Button>Second</Button>
+</Stack>
+```
+
+## Componentize Repeated Patterns
+
+If a pattern appears 2+ times, extract it:
+
+```tsx
+// Repeated? Make a component
+<div className="flex items-center gap-2">
+  <div className="w-2 h-2 rounded-full bg-green-500" />
+  <span className="text-sm">Active</span>
+</div>
+// → Create <StatusDot status="active" />
+```
+
+## Extension Strategy
+
+When you need new styling:
+
+1. **Check existing variants** - component may already support it
+2. **Add a variant** to the component's `cva` definition
+3. **Create a new component** if it's a genuinely new pattern
+
+```tsx
+// Adding a variant
+const badgeVariants = cva("...", {
+  variants: {
+    variant: {
+      // existing...
+      counter: "bg-muted text-muted-foreground tabular-nums font-mono",
+    },
+  },
+});
+```
+
+## Semantic Colors
+
+Use CSS variables, not hardcoded colors:
+
+```tsx
+// ✅ Semantic tokens
+<div className="bg-background text-foreground border-border">
+<div className="bg-muted text-muted-foreground">
+<div className="bg-destructive/10 text-destructive">
+
+// ❌ Hardcoded
+<div className="bg-white text-black">
+<div className="bg-[#059669]">
+```
+
+## Dark Mode
+
+Always support both modes:
+
+```tsx
+// Status colors with dark variants
+<div className="bg-green-50 dark:bg-green-950/20 text-green-600 dark:text-green-400">
+<div className="bg-red-50 dark:bg-red-950/20 text-red-600 dark:text-red-400">
+```
+
+## Icons
+
+Carbon icons from DS, not lucide:
+
+```tsx
+// ✅ Design system icons with size prop
+import { Add, Close, ChevronDown } from '@trycompai/design-system/icons';
+<Add size={16} />
+
+// ❌ Don't use lucide
+import { Plus, X } from 'lucide-react';
+<Plus className="h-4 w-4" />
+```
+
+## Anti-Patterns
+
+```tsx
+// ❌ Never do these
+<div style={{ display: 'flex' }}>              // Inline styles
+<Button className="bg-red-500">               // className on DS
+<div className="bg-[#059669]">                // Hardcoded colors
+<div className="w-[847px]">                   // Arbitrary values
+```
diff --git a/.claude/skills/code/SKILL.md b/.claude/skills/code/SKILL.md
new file mode 100644
index 0000000000..d6028d192f
--- /dev/null
+++ b/.claude/skills/code/SKILL.md
@@ -0,0 +1,185 @@
+---
+name: code
+description: "Use when writing TypeScript/React code - covers type safety, component patterns, and file organization"
+---
+
+Source Cursor rule: `.cursor/rules/code.mdc`.
+Original Cursor alwaysApply: `false`.
+
+# Code Standards
+
+## TypeScript
+
+### No `any`, No Unsafe Casts
+
+```tsx
+// ✅ Validate with zod
+const TaskSchema = z.object({ id: z.string(), title: z.string() });
+const task = TaskSchema.parse(response.data);
+
+// ✅ Use unknown and narrow
+const parseResponse = (data: unknown): Task => {
+  if (!isTask(data)) throw new Error('Invalid');
+  return data;
+};
+
+// ❌ Never
+const data: any = fetchData();
+const task = response as Task;
+const name = user!.name;
+// @ts-ignore
+```
+
+### Generics Over Any
+
+```tsx
+// ✅ Generic
+const first = <T>(items: T[]): T | undefined => items[0];
+
+// ❌ Any
+const first = (items: any[]): any => items[0];
+```
+
+## React Patterns
+
+### Named Exports, PascalCase
+
+```tsx
+// ✅ Named export, PascalCase file
+// TaskCard.tsx
+export function TaskCard({ task }: TaskCardProps) { ... }
+
+// ❌ Default export, lowercase
+export default function taskCard() { ... }
+```
+
+### Derive State, Avoid useEffect
+
+```tsx
+// ✅ Derived
+const completedCount = tasks.filter(t => t.completed).length;
+
+// ❌ Synced state
+const [count, setCount] = useState(0);
+useEffect(() => {
+  setCount(tasks.filter(t => t.completed).length);
+}, [tasks]);
+```
+
+### When useEffect IS Appropriate
+
+```tsx
+// External subscriptions
+useEffect(() => {
+  const sub = eventSource.subscribe(handler);
+  return () => sub.unsubscribe();
+}, []);
+
+// DOM measurements
+useEffect(() => {
+  setHeight(ref.current?.getBoundingClientRect().height);
+}, []);
+```
+
+### Toasts with Sonner
+
+```tsx
+import { toast } from 'sonner';
+
+toast.success('Task created');
+toast.error('Failed to save');
+toast.promise(saveTask(), {
+  loading: 'Saving...',
+  success: 'Saved!',
+  error: 'Failed',
+});
+```
+
+## File Structure
+
+### Colocate at Route Level
+
+```
+app/(app)/[orgId]/tasks/
+├── page.tsx              # Server component
+├── components/
+│   └── TaskList.tsx      # Client component
+├── hooks/
+│   └── useTasks.ts       # SWR hook
+└── data/
+    └── queries.ts        # Server queries
+```
+
+### Share Only When Reused 3+ Times
+
+```
+src/components/shared/    # Cross-page components
+src/hooks/                # Shared hooks (useApiSWR, useDebounce)
+```
+
+## Code Quality
+
+### File Size Limit: 300 Lines
+
+Split large files into focused components.
+
+### Named Parameters for 2+ Args
+
+```tsx
+// ✅ Named
+const createTask = ({ title, assigneeId }: CreateTaskParams) => { ... };
+createTask({ title: 'Review PR', assigneeId: user.id });
+
+// ❌ Positional
+const createTask = (title: string, assigneeId: string) => { ... };
+createTask('Review PR', user.id); // What's the 2nd param?
+```
+
+### Early Returns
+
+```tsx
+// ✅ Early return
+function processTask(task: Task | null) {
+  if (!task) return null;
+  if (task.deleted) return null;
+  return <TaskCard task={task} />;
+}
+
+// ❌ Nested
+function processTask(task) {
+  if (task) {
+    if (!task.deleted) {
+      return <TaskCard task={task} />;
+    }
+  }
+  return null;
+}
+```
+
+### Event Handler Naming
+
+```tsx
+// ✅ Prefix with "handle"
+const handleClick = () => { ... };
+const handleSubmit = (e: FormEvent) => { ... };
+const handleTaskCreate = (task: Task) => { ... };
+```
+
+## Accessibility
+
+```tsx
+// Interactive elements need keyboard support
+<div
+  role="button"
+  tabIndex={0}
+  onClick={handleClick}
+  onKeyDown={(e) => e.key === 'Enter' && handleClick()}
+  aria-label="Delete task"
+>
+  <TrashIcon />
+</div>
+
+// Form inputs need labels
+<label htmlFor="task-name">Task Name</label>
+<input id="task-name" type="text" />
+```
diff --git a/.claude/skills/cursor-usage/SKILL.md b/.claude/skills/cursor-usage/SKILL.md
new file mode 100644
index 0000000000..b2b96b6c5c
--- /dev/null
+++ b/.claude/skills/cursor-usage/SKILL.md
@@ -0,0 +1,269 @@
+---
+name: cursor-usage
+description: "How to write and manage Cursor rules - invoke with @cursor-usage"
+---
+
+Source Cursor rule: `.cursor/rules/cursor-usage.mdc`.
+Original file scope: `.cursor/rules/*.mdc`.
+Original Cursor alwaysApply: `false`.
+
+# Using Cursor Rules
+
+## Overview
+
+Cursor rules provide system-level instructions to the AI to maintain code consistency, quality, and adherence to project standards. They are stored in the `.cursor/rules/` directory as `.mdc` (Markdown with frontmatter) files.
+
+## Rule File Structure
+
+Each `.mdc` rule file consists of two parts:
+
+### 1. Frontmatter (YAML metadata)
+
+```yaml
+---
+description: Brief overview of what this rule enforces
+globs: **/*.{ts,tsx}
+alwaysApply: true
+---
+```
+
+**Frontmatter Fields:**
+
+- `description`: A clear, concise explanation of the rule's purpose
+- `globs`: Glob pattern to match files where this rule should apply (plain string, no quotes or arrays)
+  - Examples:
+    - `**/*.tsx` - All TSX files
+    - `**/*.{ts,tsx}` - All TS and TSX files
+    - `apps/*/components/**/*.tsx` - All TSX files in any app's components directory
+    - `**/trigger/**/*.ts` - All TS files in trigger directories
+- `alwaysApply`: Boolean indicating if the rule should always be active
+  - `true`: Rule is always active when working on matching files
+  - `false`: Rule can be selectively invoked with `@rule-name`
+
+### 2. Content (Markdown)
+
+The body of the rule file contains the actual guidelines, examples, and instructions written in Markdown format.
+
+## How Rules Are Applied
+
+### Automatic Application
+
+Rules with `alwaysApply: true` are automatically loaded when:
+
+- You open a file matching the `globs` pattern
+- You're working on code that matches the pattern
+- Cursor AI generates or suggests code for matching files
+
+### Manual Invocation
+
+You can reference specific rules in your prompts:
+
+```
+@design-system create a new button component
+```
+
+This explicitly tells Cursor to apply the design-system rule.
+
+## Best Practices for Writing Rules
+
+### 1. Keep Rules Focused
+
+- Each rule file should cover a specific domain (e.g., design system, API patterns, testing)
+- Avoid mixing unrelated concerns in a single rule file
+- Aim for rules under 500 lines for better AI comprehension
+
+### 2. Provide Concrete Examples
+
+Always include:
+
+- ✅ Good examples (what TO do)
+- ❌ Bad examples (what NOT to do)
+- Real code snippets from your project
+
+```tsx
+// ✅ Good: Use semantic tokens
+<div className="bg-background text-foreground">Content</div>
+
+// ❌ Bad: Hardcoded colors
+<div className="bg-white text-black">Content</div>
+```
+
+### 3. Use Clear Section Headers
+
+Organize content with descriptive headers:
+
+```markdown
+## Core Principles
+
+## Rules
+
+## Examples
+
+## Exceptions
+
+## Common Mistakes
+```
+
+### 4. Define Exceptions Explicitly
+
+If there are cases where rules don't apply, state them clearly:
+
+```markdown
+## Exceptions
+
+The ONLY time you can pass className to a design system component is for:
+
+1. Width utilities: `w-full`, `max-w-md`
+2. Responsive display: `hidden`, `md:block`
+```
+
+### 5. Include Checklists
+
+Provide actionable checklists for validation:
+
+```markdown
+## Code Review Checklist
+
+Before committing:
+
+- [ ] Uses semantic color tokens
+- [ ] Works in both light and dark mode
+- [ ] Fully responsive
+```
+
+## Managing Rules
+
+### Creating a New Rule
+
+1. Create a new `.mdc` file in `.cursor/rules/`
+2. Add appropriate frontmatter
+3. Write clear guidelines with examples
+4. Test by working on matching files
+
+### Updating Existing Rules
+
+1. Edit the `.mdc` file
+2. Rules are automatically reloaded
+3. Test changes with relevant files
+
+### Organizing Rules
+
+Recommended structure:
+
+```
+.cursor/rules/
+├── design-system.mdc       # Component usage, variants, composition
+├── code-standards.mdc      # General code quality rules
+├── typescript-rules.mdc    # TypeScript type safety
+├── react-code.mdc          # React patterns and conventions
+├── data-fetching.mdc       # Server/client data patterns
+└── cursor-usage.mdc        # This file - how to use rules
+```
+
+## Rule Scope with Globs
+
+### Common Glob Patterns
+
+```yaml
+# All TypeScript/TSX files
+globs: **/*.{ts,tsx}
+
+# Only TSX files (React components)
+globs: **/*.tsx
+
+# Only trigger task files
+globs: **/trigger/**/*.ts
+
+# Prisma schema files
+globs: **/*.prisma
+
+# All JSON and TypeScript files
+globs: **/*.{ts,tsx,json}
+```
+
+### Glob Pattern Tips
+
+- Use `**` for recursive directory matching
+- Use `*` for single-level wildcard
+- Use `{ts,tsx}` for multiple extensions
+- No quotes or array brackets needed
+- Be specific to avoid over-applying rules
+
+## Debugging Rules
+
+### Rule Not Applying?
+
+1. Check the `globs` pattern matches your file
+2. Verify frontmatter YAML syntax is correct
+3. Ensure `alwaysApply` is set appropriately
+4. Try manually invoking with `@ruleName`
+
+### Rule Conflicting?
+
+1. Check if multiple rules apply to the same files
+2. Make rules more specific with tighter `globs`
+3. Consolidate related rules into one file
+
+## Advanced Features
+
+### Conditional Rules
+
+Use `alwaysApply: false` for rules that should only apply in specific contexts:
+
+```yaml
+---
+description: Performance optimization guidelines
+globs: **/*.ts
+alwaysApply: false
+---
+```
+
+Invoke with: `@performance-optimization refactor this component`
+
+### Hierarchical Rules
+
+More specific globs take precedence:
+
+- `design-system.mdc` with `globs: **/*.tsx` (broad)
+- `trigger.basic.mdc` with `globs: **/trigger/**/*.ts` (specific)
+
+The specific rule will have more weight for trigger files.
+
+## Quick Reference
+
+### Create a New Rule
+
+```bash
+touch .cursor/rules/my-new-rule.mdc
+```
+
+```yaml
+---
+description: What this rule enforces
+globs: **/*.{ts,tsx}
+alwaysApply: true
+---
+
+# Rule Title
+
+## Guidelines
+
+- Point 1
+- Point 2
+```
+
+### Apply a Rule
+
+- Automatic: Save a file matching the `globs` pattern
+- Manual: Use `@my-new-rule` in your prompt
+
+### Debug a Rule
+
+1. Check file matches `globs` pattern
+2. Verify YAML frontmatter syntax
+3. Look for conflicting rules
+4. Try manual invocation
+
+---
+
+**Remember**: Rules are here to help, not hinder. If a rule doesn't make sense for a specific case, discuss with the team and update the rule accordingly.
diff --git a/.claude/skills/data/SKILL.md b/.claude/skills/data/SKILL.md
new file mode 100644
index 0000000000..a670937c2d
--- /dev/null
+++ b/.claude/skills/data/SKILL.md
@@ -0,0 +1,141 @@
+---
+name: data
+description: "Use when implementing data fetching, API calls, server/client components, or SWR hooks"
+---
+
+Source Cursor rule: `.cursor/rules/data.mdc`.
+Original Cursor alwaysApply: `false`.
+
+# Data Fetching
+
+## Core Pattern: Server → Client → SWR
+
+### 1. Server Page Fetches Data
+
+```tsx
+// app/(app)/[orgId]/tasks/page.tsx
+export default async function TasksPage({ params }: { params: Promise<{ orgId: string }> }) {
+  const { orgId } = await params; // From URL, NOT session
+  const tasks = await getTasks(orgId);
+  return <TaskListClient organizationId={orgId} initialTasks={tasks} />;
+}
+```
+
+### 2. Client Component Receives Initial Data
+
+```tsx
+// components/TaskListClient.tsx
+'use client';
+
+export function TaskListClient({ organizationId, initialTasks }: Props) {
+  const { tasks, createTask, updateTask } = useTasks({
+    organizationId,
+    initialData: initialTasks,
+  });
+  // Initial render is instant - no loading state
+}
+```
+
+### 3. SWR Hook with fallbackData
+
+```tsx
+// hooks/useTasks.ts
+export function useTasks({ organizationId, initialData }: UseTasksOptions) {
+  const { data, mutate } = useSWR(
+    ['/v1/tasks', organizationId], // Include orgId for cache isolation
+    async ([endpoint, orgId]) => {
+      const response = await apiClient.get(endpoint, orgId);
+      return response.data?.tasks ?? [];
+    },
+    { fallbackData: initialData }
+  );
+
+  const createTask = async (input: CreateTaskInput) => {
+    await apiClient.post('/v1/tasks', input, organizationId);
+    mutate(); // Revalidate
+  };
+
+  return { tasks: data ?? [], createTask, mutate };
+}
+```
+
+## API Client
+
+Use `apiClient` from `@/lib/api-client`:
+
+```tsx
+import { apiClient } from '@/lib/api-client';
+
+await apiClient.get<ResponseType>('/v1/endpoint', organizationId);
+await apiClient.post<ResponseType>('/v1/endpoint', body, organizationId);
+await apiClient.put<ResponseType>('/v1/endpoint', body, organizationId);
+await apiClient.delete('/v1/endpoint', organizationId);
+```
+
+## Server vs Client Components
+
+**Layouts = server.** Interactive logic in separate client components.
+
+```tsx
+// layout.tsx (server)
+export default function Layout({ children }) {
+  return (
+    <PageLayout>
+      <PageHeader title="Title" />
+      <ClientTabs /> {/* Client component */}
+      {children}
+    </PageLayout>
+  );
+}
+
+// components/ClientTabs.tsx
+'use client';
+export function ClientTabs() {
+  const router = useRouter();
+  // Interactive logic here
+}
+```
+
+## State Management
+
+**No `nuqs`** - use React state or Next.js patterns:
+
+```tsx
+// ✅ React state for UI
+const [isOpen, setIsOpen] = useState(false);
+
+// ✅ Next.js for URL state
+const router = useRouter();
+const searchParams = useSearchParams();
+
+// ❌ No nuqs
+import { useQueryState } from 'nuqs';
+```
+
+## Rules
+
+```tsx
+// ✅ Always
+const { orgId } = await params;                    // From URL params
+const { data } = useSWR(key, f, { fallbackData }); // With initial data
+await apiClient.get('/v1/endpoint', orgId);        // Use apiClient
+useSWR(['/v1/tasks', orgId], fetcher);            // Include orgId in key
+
+// ❌ Never
+const orgId = session?.activeOrganizationId;       // From session
+const { data } = useSWR('/api/data');              // No initial data
+await fetch('/api/endpoint');                      // Direct fetch
+```
+
+## File Structure
+
+```
+app/(app)/[orgId]/tasks/
+├── page.tsx                 # Server - fetches data
+├── components/
+│   └── TaskListClient.tsx   # Client - receives initialData
+├── hooks/
+│   └── useTasks.ts          # SWR hook with mutations
+└── data/
+    └── queries.ts           # Server-side queries
+```
diff --git a/.claude/skills/essentials/SKILL.md b/.claude/skills/essentials/SKILL.md
new file mode 100644
index 0000000000..21711433da
--- /dev/null
+++ b/.claude/skills/essentials/SKILL.md
@@ -0,0 +1,108 @@
+---
+name: essentials
+description: "Critical rules that must always be followed"
+---
+
+Source Cursor rule: `.cursor/rules/essentials.mdc`.
+Original file scope: `**/*.{ts,tsx}`.
+Original Cursor alwaysApply: `true`.
+
+# Essentials
+
+## Package Manager
+
+Use `bun`, never npm/yarn/pnpm.
+
+```bash
+bun install          # Install deps
+bun add <pkg>        # Add package
+bun run <script>     # Run script
+bunx <cmd>           # Execute binary
+```
+
+## Components
+
+**Use `@trycompai/design-system` first**, `@trycompai/ui` only as fallback.
+
+```tsx
+// ✅ Design system
+import { Button, Card, Input, Select } from '@trycompai/design-system';
+import { Add, Close } from '@trycompai/design-system/icons';
+
+// ❌ Don't use when DS has the component
+import { Button } from '@trycompai/ui/button';
+import { Plus } from 'lucide-react';
+```
+
+**No `className` on DS components** - use variants and props only.
+
+```tsx
+// ✅ Use variants
+<Button variant="destructive" size="sm">Delete</Button>
+
+// ❌ No className overrides
+<Button className="bg-red-500">Delete</Button>
+```
+
+## TypeScript
+
+**No `any`. No unsafe type assertions.**
+
+```tsx
+// ✅ Validate external data with zod
+const TaskSchema = z.object({ id: z.string(), title: z.string() });
+const task = TaskSchema.parse(response.data);
+
+// ❌ Never
+const data: any = fetchData();
+const task = response as Task;
+```
+
+## Data Fetching
+
+**Get `organizationId` from URL params, not session.**
+
+```tsx
+// ✅ From params
+export default async function Page({ params }: { params: Promise<{ orgId: string }> }) {
+  const { orgId } = await params;
+}
+
+// ❌ Not from session
+const session = await auth.api.getSession();
+const orgId = session?.session?.activeOrganizationId;
+```
+
+**Server components fetch, pass to client with SWR `fallbackData`.**
+
+```tsx
+// Server page
+const data = await fetchData(orgId);
+return <ClientComponent initialData={data} />;
+
+// Client component
+const { data } = useSWR(key, fetcher, { fallbackData: initialData });
+```
+
+## State Management
+
+**No `nuqs`** - use React `useState` for UI state, Next.js for URL state.
+
+```tsx
+// ✅ React state for UI
+const [isOpen, setIsOpen] = useState(false);
+
+// ❌ No nuqs
+import { useQueryState } from 'nuqs';
+```
+
+## After Changes
+
+**Always run checks after code changes:**
+
+```bash
+bun run typecheck
+bun run lint
+```
+
+Fix all errors before committing.
diff --git a/.claude/skills/forms/SKILL.md b/.claude/skills/forms/SKILL.md
new file mode 100644
index 0000000000..bcb8beafa8
--- /dev/null
+++ b/.claude/skills/forms/SKILL.md
@@ -0,0 +1,180 @@
+---
+name: forms
+description: "Use when building forms - covers React Hook Form, Zod validation, and form patterns"
+---
+
+Source Cursor rule: `.cursor/rules/forms.mdc`.
+Original Cursor alwaysApply: `false`.
+
+# Forms: React Hook Form + Zod
+
+**All forms MUST use React Hook Form with Zod validation.**
+
+## Basic Pattern
+
+```tsx
+import { zodResolver } from '@hookform/resolvers/zod';
+import { useForm } from 'react-hook-form';
+import { z } from 'zod';
+import { Button, Input } from '@trycompai/design-system';
+
+// 1. Define schema
+const formSchema = z.object({
+  email: z.string().email('Invalid email'),
+  password: z.string().min(8, 'Min 8 characters'),
+});
+
+// 2. Infer type
+type FormData = z.infer<typeof formSchema>;
+
+// 3. Use in component
+function MyForm() {
+  const {
+    register,
+    handleSubmit,
+    formState: { errors, isSubmitting },
+  } = useForm<FormData>({
+    resolver: zodResolver(formSchema),
+  });
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <Input {...register('email')} />
+      {errors.email && <p>{errors.email.message}</p>}
+      
+      <Button type="submit" loading={isSubmitting}>
+        Submit
+      </Button>
+    </form>
+  );
+}
+```
+
+## Zod Schema Patterns
+
+```tsx
+const schema = z.object({
+  // Strings
+  name: z.string().min(1, 'Required'),
+  email: z.string().email(),
+  website: z.string().url().optional(),
+  
+  // Numbers (coerce for inputs)
+  age: z.coerce.number().int().min(0),
+  price: z.coerce.number().positive(),
+  
+  // Arrays
+  tags: z.array(z.string()).min(1),
+  
+  // Enums
+  status: z.enum(['active', 'inactive']),
+});
+
+// Cross-field validation
+const schema = z.object({
+  password: z.string().min(8),
+  confirmPassword: z.string(),
+}).refine(d => d.password === d.confirmPassword, {
+  message: "Passwords don't match",
+  path: ['confirmPassword'],
+});
+```
+
+## Controller for Complex Components
+
+```tsx
+import { Controller } from 'react-hook-form';
+import { Select, SelectContent, SelectItem, SelectTrigger } from '@trycompai/design-system';
+
+<Controller
+  name="status"
+  control={control}
+  render={({ field }) => (
+    <Select onValueChange={field.onChange} value={field.value}>
+      <SelectTrigger>{field.value || 'Select...'}</SelectTrigger>
+      <SelectContent>
+        <SelectItem value="active">Active</SelectItem>
+        <SelectItem value="inactive">Inactive</SelectItem>
+      </SelectContent>
+    </Select>
+  )}
+/>
+```
+
+## Form State
+
+```tsx
+const {
+  register,
+  handleSubmit,
+  control,
+  watch,           // Watch field values
+  setValue,        // Set field programmatically
+  reset,           // Reset form
+  setError,        // Set error manually
+  formState: {
+    errors,        // Field errors
+    isSubmitting,  // Submitting
+    isValid,       // All valid
+    isDirty,       // Modified
+  },
+} = useForm<FormData>({
+  resolver: zodResolver(schema),
+  mode: 'onChange', // Validate on change
+});
+```
+
+## Error Handling
+
+```tsx
+const onSubmit = async (data: FormData) => {
+  try {
+    await submitToApi(data);
+  } catch (error) {
+    // Field-specific error
+    setError('email', { message: 'Email taken' });
+    // Or root error
+    setError('root', { message: 'Something went wrong' });
+  }
+};
+
+// Display root error
+{errors.root && <p>{errors.root.message}</p>}
+```
+
+## Dynamic Fields
+
+```tsx
+import { useFieldArray } from 'react-hook-form';
+
+const { fields, append, remove } = useFieldArray({
+  control,
+  name: 'items',
+});
+
+{fields.map((field, index) => (
+  <div key={field.id}>
+    <Input {...register(`items.${index}.name`)} />
+    <Button type="button" onClick={() => remove(index)}>Remove</Button>
+  </div>
+))}
+<Button type="button" onClick={() => append({ name: '' })}>Add</Button>
+```
+
+## Anti-Patterns
+
+```tsx
+// ❌ useState for form fields
+const [email, setEmail] = useState('');
+
+// ❌ Manual validation
+if (email.length < 5) setError('Too short');
+
+// ❌ Missing button type (defaults to submit)
+<Button onClick={handleCancel}>Cancel</Button>
+
+// ✅ Correct
+const { register } = useForm();
+const schema = z.object({ email: z.string().min(5) });
+<Button type="button" onClick={handleCancel}>Cancel</Button>
+```
diff --git a/.claude/skills/infra/SKILL.md b/.claude/skills/infra/SKILL.md
new file mode 100644
index 0000000000..bf073598f8
--- /dev/null
+++ b/.claude/skills/infra/SKILL.md
@@ -0,0 +1,135 @@
+---
+name: infra
+description: "Use when working with packages, dependencies, monorepo structure, or build configuration"
+---
+
+Source Cursor rule: `.cursor/rules/infra.mdc`.
+Original Cursor alwaysApply: `false`.
+
+# Infrastructure
+
+## Package Manager
+
+**Use `bun`, never npm/yarn/pnpm.**
+
+```bash
+bun install              # Install deps
+bun add <pkg>            # Add package
+bun add -D <pkg>         # Add dev dependency
+bun run <script>         # Run script
+bunx <cmd>               # Execute binary
+```
+
+## Monorepo Structure
+
+```
+comp/
+├── apps/
+│   ├── api/             # NestJS backend
+│   ├── app/             # Next.js main app
+│   └── portal/          # Next.js portal
+├── packages/
+│   ├── db/              # Prisma (@trycompai/db)
+│   ├── ui/              # UI components (@trycompai/ui)
+│   └── ...
+├── turbo.json
+└── package.json
+```
+
+## Running Commands
+
+```bash
+# Multi-package (via turbo)
+bun run build            # Build all
+bun run lint             # Lint all
+bun run typecheck        # Type check all
+bun run dev              # Dev all
+
+# Single package
+bun run -F apps/app dev
+bun run -F @trycompai/db prisma:generate
+turbo build --filter=@trycompai/ui
+```
+
+## Importing Between Packages
+
+```tsx
+// ✅ Import from package name
+import { Button } from '@trycompai/design-system';
+import { prisma } from '@trycompai/db';
+
+// ❌ Never relative paths across packages
+import { Button } from '../../../packages/ui/src/button';
+```
+
+## Adding Dependencies
+
+```bash
+# To specific package
+bun add axios -F apps/app
+bun add -D vitest -F @trycompai/ui
+
+# To root (dev tools only)
+bun add -D -w prettier typescript
+```
+
+## After Code Changes
+
+**Always run checks:**
+
+```bash
+bun run typecheck
+bun run lint
+```
+
+Fix all errors before committing.
+
+## Common TypeScript Fixes
+
+- **Property does not exist**: Check interface definitions
+- **Type mismatch**: Verify expected vs actual type
+- **Empty interface extends**: Use `type X = SomeType` instead
+
+## Common ESLint Fixes
+
+- **Unused variables**: Remove or prefix with `_`
+- **Any type**: Add proper typing
+- **Empty object type**: Use `type` instead of `interface`
+
+## Creating a New Package
+
+```bash
+mkdir packages/my-package
+```
+
+```json
+// packages/my-package/package.json
+{
+  "name": "@trycompai/my-package",
+  "version": "0.0.0",
+  "private": true,
+  "main": "./src/index.ts",
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "typecheck": "tsc --noEmit"
+  }
+}
+```
+
+```json
+// packages/my-package/tsconfig.json
+{
+  "extends": "@trycompai/tsconfig/base.json",
+  "include": ["src"]
+}
+```
+
+## Package Boundaries
+
+**✅ Create packages for:**
+- Code used by 2+ apps
+- Self-contained, focused functionality
+
+**❌ Don't create packages for:**
+- Code only used in one app (colocate instead)
+- App-specific business logic
diff --git a/.claude/skills/prisma/SKILL.md b/.claude/skills/prisma/SKILL.md
new file mode 100644
index 0000000000..effc4003a0
--- /dev/null
+++ b/.claude/skills/prisma/SKILL.md
@@ -0,0 +1,147 @@
+---
+name: prisma
+description: "Prisma schema conventions and migration workflow"
+---
+
+Source Cursor rule: `.cursor/rules/prisma.mdc`.
+Original file scope: `**/*.prisma`.
+Original Cursor alwaysApply: `false`.
+
+# Prisma Schema
+
+## Migration Workflow
+
+**Schema changes happen in `packages/db`, then regenerate types in each app.**
+
+### Step 1: Edit Schema
+
+```bash
+# Schema files are in packages/db/prisma/schema/
+packages/db/prisma/schema/
+├── schema.prisma      # Main schema with datasource
+├── user.prisma        # User models
+├── task.prisma        # Task models
+└── ...
+```
+
+### Step 2: Create Migration
+
+```bash
+# Run from packages/db
+cd packages/db
+bunx prisma migrate dev --name your_migration_name
+```
+
+### Step 3: Regenerate Types in Apps
+
+```bash
+# Each app needs to regenerate Prisma client types
+bun run -F apps/app db:generate
+bun run -F apps/api db:generate
+bun run -F apps/portal db:generate
+
+# Or from root (if configured)
+bun run prisma:generate
+```
+
+### ✅ Always Do This
+
+```bash
+# 1. Make schema changes in packages/db
+# 2. Create migration
+cd packages/db && bunx prisma migrate dev --name add_user_role
+
+# 3. Regenerate types in ALL apps that use the db
+bun run -F apps/app db:generate
+bun run -F apps/api db:generate
+```
+
+### ❌ Never Do This
+
+```bash
+# Don't edit schema in app directories
+apps/app/prisma/schema.prisma  # ❌ Wrong location
+
+# Don't forget to regenerate types
+bunx prisma migrate dev  # ✅ Created migration
+# ... forgot to run db:generate in apps  # ❌ Types out of sync
+```
+
+## Core Rule
+
+**Always use prefixed CUIDs for IDs** using `generate_prefixed_cuid`.
+
+## ID Pattern
+
+### ✅ Always Do This
+
+```prisma
+model User {
+  id String @id @default(dbgenerated("generate_prefixed_cuid('usr'::text)"))
+  // ... other fields
+}
+
+model Task {
+  id String @id @default(dbgenerated("generate_prefixed_cuid('tsk'::text)"))
+  // ... other fields
+}
+
+model Organization {
+  id String @id @default(dbgenerated("generate_prefixed_cuid('org'::text)"))
+  // ... other fields
+}
+```
+
+### ❌ Never Do This
+
+```prisma
+// Don't use UUID
+model User {
+  id String @id @default(uuid())
+}
+
+// Don't use auto-increment
+model User {
+  id Int @id @default(autoincrement())
+}
+
+// Don't forget ::text cast
+model User {
+  id String @id @default(dbgenerated("generate_prefixed_cuid('usr')")) // ❌ Missing ::text
+}
+```
+
+## Prefix Guidelines
+
+| Entity       | Prefix | Example ID                     |
+| ------------ | ------ | ------------------------------ |
+| User         | `usr`  | `usr_BJRIZLgRPuWt8MvMjkSY82f1` |
+| Organization | `org`  | `org_cK9xMnPqRs2tUvWx3yZa4b5c` |
+| Task         | `tsk`  | `tsk_dE6fGhIj7kLmNoP8qRsT9uVw` |
+| Control      | `ctl`  | `ctl_xY0zAaBb1cDdEe2fFgGh3iIj` |
+| Policy       | `pol`  | `pol_kK4lLmMn5oOpPq6rRsSt7uUv` |
+
+## Rules
+
+1. **Short prefixes** - Use 2-3 characters
+2. **Unique prefixes** - Each model gets its own prefix
+3. **Always cast** - Include `::text` in the function call
+4. **Use dbgenerated** - Wrap the function call in `dbgenerated()`
+
+## Benefits
+
+- Human-readable IDs at a glance (`usr_` vs `org_`)
+- Easy debugging in logs
+- Safe to expose in URLs
+- Unique across all tables
+
+## Checklist
+
+After schema changes:
+
+- [ ] Schema edited in `packages/db/prisma/schema/`
+- [ ] Migration created with `bunx prisma migrate dev`
+- [ ] Types regenerated in `apps/app` with `db:generate`
+- [ ] Types regenerated in `apps/api` with `db:generate`
+- [ ] Types regenerated in `apps/portal` with `db:generate`
+- [ ] New models use prefixed CUID IDs
diff --git a/.claude/skills/prompt-engineering/SKILL.md b/.claude/skills/prompt-engineering/SKILL.md
new file mode 100644
index 0000000000..46d7c6b58c
--- /dev/null
+++ b/.claude/skills/prompt-engineering/SKILL.md
@@ -0,0 +1,187 @@
+---
+name: prompt-engineering
+description: "Prompt engineering best practices - invoke with @prompt-engineering"
+---
+
+Source Cursor rule: `.cursor/rules/prompt-engineering.mdc`.
+Original file scope: `.cursor/rules/*.mdc`.
+Original Cursor alwaysApply: `false`.
+
+# Prompt Engineering Best Practices
+
+Based on [Claude's Prompt Engineering Documentation](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview)
+
+## Core Principles
+
+### 1. Define Success Criteria First
+
+Before writing prompts:
+
+- **Establish clear objectives**: What constitutes a successful response?
+- **Create evaluation metrics**: How will you measure prompt effectiveness?
+- **Draft and iterate**: Start with a first draft and refine based on results
+
+### 2. When to Use Prompt Engineering vs Fine-tuning
+
+Prompt engineering is preferred because:
+
+- **Resource efficient**: Only requires text input, no GPUs
+- **Cost effective**: Uses base model pricing
+- **Maintains updates**: Works across model versions
+- **Time saving**: Instant results vs hours/days for fine-tuning
+- **Minimal data needs**: Works with zero-shot or few-shot
+- **Flexible iteration**: Quick experimentation cycle
+- **Preserves knowledge**: No catastrophic forgetting
+- **Transparent**: Human-readable, easy to debug
+
+---
+
+## The 8 Core Techniques
+
+### 1. Be Clear and Direct
+
+**Principle**: Provide explicit, unambiguous instructions.
+
+```
+❌ Bad: "Tell me about it"
+✅ Good: "Summarize the following article in three bullet points, focusing on key findings"
+
+❌ Bad: "Help with code"
+✅ Good: "Debug this Python function that should return the sum of even numbers in a list"
+```
+
+**Tips**:
+
+- State the task explicitly at the start
+- Specify the desired output format (bullet points, JSON, paragraphs)
+- Include constraints (word count, tone, audience)
+- Mention what to include AND what to exclude
+
+### 2. Use Examples (Multishot Prompting)
+
+**Principle**: Show the model what you want through examples.
+
+```xml
+<examples>
+  <example>
+    <input>The movie was absolutely terrible, waste of time</input>
+    <output>{"sentiment": "negative", "confidence": 0.95}</output>
+  </example>
+  <example>
+    <input>Decent film, not great but watchable</input>
+    <output>{"sentiment": "neutral", "confidence": 0.7}</output>
+  </example>
+  <example>
+    <input>Best movie I've seen this year!</input>
+    <output>{"sentiment": "positive", "confidence": 0.9}</output>
+  </example>
+</examples>
+
+Now analyze: "The special effects were amazing but the plot was confusing"
+```
+
+**Tips**:
+
+- Include 3-5 diverse examples covering edge cases
+- Show examples of BOTH good and bad outputs
+- Match example complexity to your actual use case
+- Order examples from simple to complex
+
+### 3. Let Claude Think (Chain of Thought)
+
+**Principle**: Encourage step-by-step reasoning for complex tasks.
+
+```xml
+<instruction>
+Solve this problem step by step. Show your reasoning before giving the final answer.
+</instruction>
+
+<problem>
+A train leaves Station A at 9:00 AM traveling at 60 mph. Another train leaves
+Station B at 10:00 AM traveling at 80 mph toward Station A. The stations are
+280 miles apart. When will the trains meet?
+</problem>
+
+<thinking>
+[Let Claude work through the problem here]
+</thinking>
+
+<answer>
+[Final answer after reasoning]
+</answer>
+```
+
+**Tips**:
+
+- Use phrases like "Think step by step" or "Explain your reasoning"
+- For complex tasks, explicitly request a thinking section
+- Chain of thought improves accuracy on math, logic, and multi-step problems
+- Can use `<thinking>` tags to separate reasoning from output
+
+### 4. Use XML Tags
+
+**Principle**: Structure prompts with clear delimiters for better parsing.
+
+```xml
+<context>
+You are helping debug a penetration testing tool that automates security scans.
+</context>
+
+<task>
+Analyze the following error log and identify the root cause.
+</task>
+
+<error_log>
+[2024-01-15 10:23:45] ERROR: Connection timeout after 30s
+[2024-01-15 10:23:45] DEBUG: Target: 192.168.1.1:443
+[2024-01-15 10:23:45] DEBUG: Retry attempt 3 of 3
+</error_log>
+
+<output_format>
+Provide your analysis in this format:
+- Root cause: [one sentence]
+- Evidence: [relevant log lines]
+- Recommended fix: [actionable steps]
+</output_format>
+```
+
+**Common XML Tags**:
+
+- `<context>` - Background information
+- `<task>` or `<instruction>` - What to do
+- `<examples>` - Sample inputs/outputs
+- `<constraints>` - Limitations or rules
+- `<output_format>` - Expected response structure
+- `<thinking>` - Reasoning section
+- `<answer>` - Final response
+
+### 5. Give Claude a Role (System Prompts)
+
+**Principle**: Assign a persona to influence response style and expertise.
+
+```xml
+<role>
+You are a senior security researcher with 15 years of experience in penetration
+testing. You specialize in web application security and have discovered multiple
+CVEs. You communicate findings clearly and prioritize actionable recommendations.
+</role>
+
+<task>
+Review this HTTP response and identify potential security vulnerabilities.
+</task>
+```
+
+**Effective Role Elements**:
+
+- Expertise level (senior, expert, specialist)
+- Domain knowledge (security, finance, medicine)
+- Communication style (technical, friendly, formal)
+- Priorities (accuracy, brevity, thoroughness)
+
+### 6. Prefill Claude's Response
+
+**Principle**: Start the response to guide format and direction.
+
+```
+Human: List the top 3 security vulnerabilities in this code.
+```
diff --git a/.claude/skills/trigger-advanced-tasks/SKILL.md b/.claude/skills/trigger-advanced-tasks/SKILL.md
new file mode 100644
index 0000000000..2b18faabf5
--- /dev/null
+++ b/.claude/skills/trigger-advanced-tasks/SKILL.md
@@ -0,0 +1,460 @@
+---
+name: trigger-advanced-tasks
+description: "Comprehensive rules to help you write advanced Trigger.dev tasks"
+---
+
+Source Cursor rule: `.cursor/rules/trigger.advanced-tasks.mdc`.
+Original file scope: `**/trigger/**/*.ts`.
+Original Cursor alwaysApply: `false`.
+
+# Trigger.dev Advanced Tasks (v4)
+
+**Advanced patterns and features for writing tasks**
+
+## Tags & Organization
+
+```ts
+import { task, tags } from '@trigger.dev/sdk';
+
+export const processUser = task({
+  id: 'process-user',
+  run: async (payload: { userId: string; orgId: string }, { ctx }) => {
+    // Add tags during execution
+    await tags.add(`user_${payload.userId}`);
+    await tags.add(`org_${payload.orgId}`);
+
+    return { processed: true };
+  },
+});
+
+// Trigger with tags
+await processUser.trigger(
+  { userId: '123', orgId: 'abc' },
+  { tags: ['priority', 'user_123', 'org_abc'] }, // Max 10 tags per run
+);
+
+// Subscribe to tagged runs
+for await (const run of runs.subscribeToRunsWithTag('user_123')) {
+  console.log(`User task ${run.id}: ${run.status}`);
+}
+```
+
+**Tag Best Practices:**
+
+- Use prefixes: `user_123`, `org_abc`, `video:456`
+- Max 10 tags per run, 1-64 characters each
+- Tags don't propagate to child tasks automatically
+
+## Concurrency & Queues
+
+```ts
+import { task, queue } from '@trigger.dev/sdk';
+
+// Shared queue for related tasks
+const emailQueue = queue({
+  name: 'email-processing',
+  concurrencyLimit: 5, // Max 5 emails processing simultaneously
+});
+
+// Task-level concurrency
+export const oneAtATime = task({
+  id: 'sequential-task',
+  queue: { concurrencyLimit: 1 }, // Process one at a time
+  run: async (payload) => {
+    // Critical section - only one instance runs
+  },
+});
+
+// Per-user concurrency
+export const processUserData = task({
+  id: 'process-user-data',
+  run: async (payload: { userId: string }) => {
+    // Override queue with user-specific concurrency
+    await childTask.trigger(payload, {
+      queue: {
+        name: `user-${payload.userId}`,
+        concurrencyLimit: 2,
+      },
+    });
+  },
+});
+
+export const emailTask = task({
+  id: 'send-email',
+  queue: emailQueue, // Use shared queue
+  run: async (payload: { to: string }) => {
+    // Send email logic
+  },
+});
+```
+
+## Error Handling & Retries
+
+```ts
+import { task, retry, AbortTaskRunError } from '@trigger.dev/sdk';
+
+export const resilientTask = task({
+  id: 'resilient-task',
+  retry: {
+    maxAttempts: 10,
+    factor: 1.8, // Exponential backoff multiplier
+    minTimeoutInMs: 500,
+    maxTimeoutInMs: 30_000,
+    randomize: false,
+  },
+  catchError: async ({ error, ctx }) => {
+    // Custom error handling
+    if (error.code === 'FATAL_ERROR') {
+      throw new AbortTaskRunError('Cannot retry this error');
+    }
+
+    // Log error details
+    console.error(`Task ${ctx.task.id} failed:`, error);
+
+    // Allow retry by returning nothing
+    return { retryAt: new Date(Date.now() + 60000) }; // Retry in 1 minute
+  },
+  run: async (payload) => {
+    // Retry specific operations
+    const result = await retry.onThrow(
+      async () => {
+        return await unstableApiCall(payload);
+      },
+      { maxAttempts: 3 },
+    );
+
+    // Conditional HTTP retries
+    const response = await retry.fetch('https://api.example.com', {
+      retry: {
+        maxAttempts: 5,
+        condition: (response, error) => {
+          return response?.status === 429 || response?.status >= 500;
+        },
+      },
+    });
+
+    return result;
+  },
+});
+```
+
+## Machines & Performance
+
+```ts
+export const heavyTask = task({
+  id: 'heavy-computation',
+  machine: { preset: 'large-2x' }, // 8 vCPU, 16 GB RAM
+  maxDuration: 1800, // 30 minutes timeout
+  run: async (payload, { ctx }) => {
+    // Resource-intensive computation
+    if (ctx.machine.preset === 'large-2x') {
+      // Use all available cores
+      return await parallelProcessing(payload);
+    }
+
+    return await standardProcessing(payload);
+  },
+});
+
+// Override machine when triggering
+await heavyTask.trigger(payload, {
+  machine: { preset: 'medium-1x' }, // Override for this run
+});
+```
+
+**Machine Presets:**
+
+- `micro`: 0.25 vCPU, 0.25 GB RAM
+- `small-1x`: 0.5 vCPU, 0.5 GB RAM (default)
+- `small-2x`: 1 vCPU, 1 GB RAM
+- `medium-1x`: 1 vCPU, 2 GB RAM
+- `medium-2x`: 2 vCPU, 4 GB RAM
+- `large-1x`: 4 vCPU, 8 GB RAM
+- `large-2x`: 8 vCPU, 16 GB RAM
+
+## Idempotency
+
+```ts
+import { task, idempotencyKeys } from '@trigger.dev/sdk';
+
+export const paymentTask = task({
+  id: 'process-payment',
+  retry: {
+    maxAttempts: 3,
+  },
+  run: async (payload: { orderId: string; amount: number }) => {
+    // Automatically scoped to this task run, so if the task is retried, the idempotency key will be the same
+    const idempotencyKey = await idempotencyKeys.create(`payment-${payload.orderId}`);
+
+    // Ensure payment is processed only once
+    await chargeCustomer.trigger(payload, {
+      idempotencyKey,
+      idempotencyKeyTTL: '24h', // Key expires in 24 hours
+    });
+  },
+});
+
+// Payload-based idempotency
+import { createHash } from 'node:crypto';
+
+function createPayloadHash(payload: any): string {
+  const hash = createHash('sha256');
+  hash.update(JSON.stringify(payload));
+  return hash.digest('hex');
+}
+
+export const deduplicatedTask = task({
+  id: 'deduplicated-task',
+  run: async (payload) => {
+    const payloadHash = createPayloadHash(payload);
+    const idempotencyKey = await idempotencyKeys.create(payloadHash);
+
+    await processData.trigger(payload, { idempotencyKey });
+  },
+});
+```
+
+## Metadata & Progress Tracking
+
+```ts
+import { task, metadata } from '@trigger.dev/sdk';
+
+export const batchProcessor = task({
+  id: 'batch-processor',
+  run: async (payload: { items: any[] }, { ctx }) => {
+    const totalItems = payload.items.length;
+
+    // Initialize progress metadata
+    metadata
+      .set('progress', 0)
+      .set('totalItems', totalItems)
+      .set('processedItems', 0)
+      .set('status', 'starting');
+
+    const results = [];
+
+    for (let i = 0; i < payload.items.length; i++) {
+      const item = payload.items[i];
+
+      // Process item
+      const result = await processItem(item);
+      results.push(result);
+
+      // Update progress
+      const progress = ((i + 1) / totalItems) * 100;
+      metadata
+        .set('progress', progress)
+        .increment('processedItems', 1)
+        .append('logs', `Processed item ${i + 1}/${totalItems}`)
+        .set('currentItem', item.id);
+    }
+
+    // Final status
+    metadata.set('status', 'completed');
+
+    return { results, totalProcessed: results.length };
+  },
+});
+
+// Update parent metadata from child task
+export const childTask = task({
+  id: 'child-task',
+  run: async (payload, { ctx }) => {
+    // Update parent task metadata
+    metadata.parent.set('childStatus', 'processing');
+    metadata.root.increment('childrenCompleted', 1);
+
+    return { processed: true };
+  },
+});
+```
+
+## Advanced Triggering
+
+### Frontend Triggering (React)
+
+```tsx
+'use client';
+import { useTaskTrigger } from '@trigger.dev/react-hooks';
+import type { myTask } from '../trigger/tasks';
+
+function TriggerButton({ accessToken }: { accessToken: string }) {
+  const { submit, handle, isLoading } = useTaskTrigger<typeof myTask>('my-task', { accessToken });
+
+  return (
+    <button onClick={() => submit({ data: 'from frontend' })} disabled={isLoading}>
+      Trigger Task
+    </button>
+  );
+}
+```
+
+### Large Payloads
+
+```ts
+// For payloads > 512KB (max 10MB)
+export const largeDataTask = task({
+  id: 'large-data-task',
+  run: async (payload: { dataUrl: string }) => {
+    // Trigger.dev automatically handles large payloads
+    // For > 10MB, use external storage
+    const response = await fetch(payload.dataUrl);
+    const largeData = await response.json();
+
+    return { processed: largeData.length };
+  },
+});
+
+// Best practice: Use presigned URLs for very large files
+await largeDataTask.trigger({
+  dataUrl: 'https://s3.amazonaws.com/bucket/large-file.json?presigned=true',
+});
+```
+
+### Advanced Options
+
+```ts
+await myTask.trigger(payload, {
+  delay: '2h30m', // Delay execution
+  ttl: '24h', // Expire if not started within 24 hours
+  priority: 100, // Higher priority (time offset in seconds)
+  tags: ['urgent', 'user_123'],
+  metadata: { source: 'api', version: 'v2' },
+  queue: {
+    name: 'priority-queue',
+    concurrencyLimit: 10,
+  },
+  idempotencyKey: 'unique-operation-id',
+  idempotencyKeyTTL: '1h',
+  machine: { preset: 'large-1x' },
+  maxAttempts: 5,
+});
+```
+
+## Hidden Tasks
+
+```ts
+// Hidden task - not exported, only used internally
+const internalProcessor = task({
+  id: 'internal-processor',
+  run: async (payload: { data: string }) => {
+    return { processed: payload.data.toUpperCase() };
+  },
+});
+
+// Public task that uses hidden task
+export const publicWorkflow = task({
+  id: 'public-workflow',
+  run: async (payload: { input: string }) => {
+    // Use hidden task internally
+    const result = await internalProcessor.triggerAndWait({
+      data: payload.input,
+    });
+
+    if (result.ok) {
+      return { output: result.output.processed };
+    }
+
+    throw new Error('Internal processing failed');
+  },
+});
+```
+
+## Logging & Tracing
+
+```ts
+import { task, logger } from '@trigger.dev/sdk';
+
+export const tracedTask = task({
+  id: 'traced-task',
+  run: async (payload, { ctx }) => {
+    logger.info('Task started', { userId: payload.userId });
+
+    // Custom trace with attributes
+    const user = await logger.trace(
+      'fetch-user',
+      async (span) => {
+        span.setAttribute('user.id', payload.userId);
+        span.setAttribute('operation', 'database-fetch');
+
+        const userData = await database.findUser(payload.userId);
+        span.setAttribute('user.found', !!userData);
+
+        return userData;
+      },
+      { userId: payload.userId },
+    );
+
+    logger.debug('User fetched', { user: user.id });
+
+    try {
+      const result = await processUser(user);
+      logger.info('Processing completed', { result });
+      return result;
+    } catch (error) {
+      logger.error('Processing failed', {
+        error: error.message,
+        userId: payload.userId,
+      });
+      throw error;
+    }
+  },
+});
+```
+
+## Usage Monitoring
+
+```ts
+import { task, usage } from '@trigger.dev/sdk';
+
+export const monitoredTask = task({
+  id: 'monitored-task',
+  run: async (payload) => {
+    // Get current run cost
+    const currentUsage = await usage.getCurrent();
+    logger.info('Current cost', {
+      costInCents: currentUsage.costInCents,
+      durationMs: currentUsage.durationMs,
+    });
+
+    // Measure specific operation
+    const { result, compute } = await usage.measure(async () => {
+      return await expensiveOperation(payload);
+    });
+
+    logger.info('Operation cost', {
+      costInCents: compute.costInCents,
+      durationMs: compute.durationMs,
+    });
+
+    return result;
+  },
+});
+```
+
+## Run Management
+
+```ts
+// Cancel runs
+await runs.cancel('run_123');
+
+// Replay runs with same payload
+await runs.replay('run_123');
+
+// Retrieve run with cost details
+const run = await runs.retrieve('run_123');
+console.log(`Cost: ${run.costInCents} cents, Duration: ${run.durationMs}ms`);
+```
+
+## Best Practices
+
+- **Concurrency**: Use queues to prevent overwhelming external services
+- **Retries**: Configure exponential backoff for transient failures
+- **Idempotency**: Always use for payment/critical operations
+- **Metadata**: Track progress for long-running tasks
+- **Machines**: Match machine size to computational requirements
+- **Tags**: Use consistent naming patterns for filtering
+- **Large Payloads**: Use external storage for files > 10MB
+- **Error Handling**: Distinguish between retryable and fatal errors
+
+Design tasks to be stateless, idempotent, and resilient to failures. Use metadata for state tracking and queues for resource management.
diff --git a/.claude/skills/trigger-basic/SKILL.md b/.claude/skills/trigger-basic/SKILL.md
new file mode 100644
index 0000000000..3efd8127fc
--- /dev/null
+++ b/.claude/skills/trigger-basic/SKILL.md
@@ -0,0 +1,194 @@
+---
+name: trigger-basic
+description: "Only the most important rules for writing basic Trigger.dev tasks"
+---
+
+Source Cursor rule: `.cursor/rules/trigger.basic.mdc`.
+Original file scope: `**/trigger/**/*.ts`.
+Original Cursor alwaysApply: `false`.
+
+# Trigger.dev Basic Tasks (v4)
+
+**MUST use `@trigger.dev/sdk` (v4), NEVER `client.defineJob`**
+
+## Basic Task
+
+```ts
+import { task } from "@trigger.dev/sdk";
+
+export const processData = task({
+  id: "process-data",
+  retry: {
+    maxAttempts: 10,
+    factor: 1.8,
+    minTimeoutInMs: 500,
+    maxTimeoutInMs: 30_000,
+    randomize: false,
+  },
+  run: async (payload: { userId: string; data: any[] }) => {
+    // Task logic - runs for long time, no timeouts
+    console.log(`Processing ${payload.data.length} items for user ${payload.userId}`);
+    return { processed: payload.data.length };
+  },
+});
+```
+
+## Schema Task (with validation)
+
+```ts
+import { schemaTask } from "@trigger.dev/sdk";
+import { z } from "zod";
+
+export const validatedTask = schemaTask({
+  id: "validated-task",
+  schema: z.object({
+    name: z.string(),
+    age: z.number(),
+    email: z.string().email(),
+  }),
+  run: async (payload) => {
+    // Payload is automatically validated and typed
+    return { message: `Hello ${payload.name}, age ${payload.age}` };
+  },
+});
+```
+
+## Scheduled Task
+
+```ts
+import { schedules } from "@trigger.dev/sdk";
+
+const dailyReport = schedules.task({
+  id: "daily-report",
+  cron: "0 9 * * *", // Daily at 9:00 AM UTC
+  // or with timezone: cron: { pattern: "0 9 * * *", timezone: "America/New_York" },
+  run: async (payload) => {
+    console.log("Scheduled run at:", payload.timestamp);
+    console.log("Last run was:", payload.lastTimestamp);
+    console.log("Next 5 runs:", payload.upcoming);
+
+    // Generate daily report logic
+    return { reportGenerated: true, date: payload.timestamp };
+  },
+});
+```
+
+## Triggering Tasks
+
+### From Backend Code
+
+```ts
+import { tasks } from "@trigger.dev/sdk";
+import type { processData } from "./trigger/tasks";
+
+// Single trigger
+const handle = await tasks.trigger<typeof processData>("process-data", {
+  userId: "123",
+  data: [{ id: 1 }, { id: 2 }],
+});
+
+// Batch trigger
+const batchHandle = await tasks.batchTrigger<typeof processData>("process-data", [
+  { payload: { userId: "123", data: [{ id: 1 }] } },
+  { payload: { userId: "456", data: [{ id: 2 }] } },
+]);
+```
+
+### From Inside Tasks (with Result handling)
+
+```ts
+export const parentTask = task({
+  id: "parent-task",
+  run: async (payload) => {
+    // Trigger and continue
+    const handle = await childTask.trigger({ data: "value" });
+
+    // Trigger and wait - returns Result object, NOT task output
+    const result = await childTask.triggerAndWait({ data: "value" });
+    if (result.ok) {
+      console.log("Task output:", result.output); // Actual task return value
+    } else {
+      console.error("Task failed:", result.error);
+    }
+
+    // Quick unwrap (throws on error)
+    const output = await childTask.triggerAndWait({ data: "value" }).unwrap();
+
+    // Batch trigger and wait
+    const results = await childTask.batchTriggerAndWait([
+      { payload: { data: "item1" } },
+      { payload: { data: "item2" } },
+    ]);
+
+    for (const run of results) {
+      if (run.ok) {
+        console.log("Success:", run.output);
+      } else {
+        console.log("Failed:", run.error);
+      }
+    }
+  },
+});
+
+export const childTask = task({
+  id: "child-task",
+  run: async (payload: { data: string }) => {
+    return { processed: payload.data };
+  },
+});
+```
+
+> Never wrap triggerAndWait or batchTriggerAndWait calls in a Promise.all or Promise.allSettled as this is not supported in Trigger.dev tasks.
+
+## Waits
+
+```ts
+import { task, wait } from "@trigger.dev/sdk";
+
+export const taskWithWaits = task({
+  id: "task-with-waits",
+  run: async (payload) => {
+    console.log("Starting task");
+
+    // Wait for specific duration
+    await wait.for({ seconds: 30 });
+    await wait.for({ minutes: 5 });
+    await wait.for({ hours: 1 });
+    await wait.for({ days: 1 });
+
+    // Wait until specific date
+    await wait.until({ date: new Date("2024-12-25") });
+
+    // Wait for token (from external system)
+    await wait.forToken({
+      token: "user-approval-token",
+      timeoutInSeconds: 3600, // 1 hour timeout
+    });
+
+    console.log("All waits completed");
+    return { status: "completed" };
+  },
+});
+```
+
+> Never wrap wait calls in a Promise.all or Promise.allSettled as this is not supported in Trigger.dev tasks.
+
+## Key Points
+
+- **Result vs Output**: `triggerAndWait()` returns a `Result` object with `ok`, `output`, `error` properties - NOT the direct task output
+- **Type safety**: Use `import type` for task references when triggering from backend
+- **Waits > 5 seconds**: Automatically checkpointed, don't count toward compute usage
+
+## NEVER Use (v2 deprecated)
+
+```ts
+// BREAKS APPLICATION
+client.defineJob({
+  id: "job-id",
+  run: async (payload, io) => {
+    /* ... */
+  },
+});
+```
+
+Use v4 SDK (`@trigger.dev/sdk`), check `result.ok` before accessing `result.output`
diff --git a/.claude/skills/trigger-config/SKILL.md b/.claude/skills/trigger-config/SKILL.md
new file mode 100644
index 0000000000..a55d845fdf
--- /dev/null
+++ b/.claude/skills/trigger-config/SKILL.md
@@ -0,0 +1,355 @@
+---
+name: trigger-config
+description: "Configure your Trigger.dev project with a trigger.config.ts file"
+---
+
+Source Cursor rule: `.cursor/rules/trigger.config.mdc`.
+Original file scope: `**/trigger.config.ts`.
+Original Cursor alwaysApply: `false`.
+
+# Trigger.dev Configuration (v4)
+
+**Complete guide to configuring `trigger.config.ts` with build extensions**
+
+## Basic Configuration
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk";
+
+export default defineConfig({
+  project: "<project-ref>", // Required: Your project reference
+  dirs: ["./trigger"], // Task directories
+  runtime: "node", // "node", "node-22", or "bun"
+  logLevel: "info", // "debug", "info", "warn", "error"
+
+  // Default retry settings
+  retries: {
+    enabledInDev: false,
+    default: {
+      maxAttempts: 3,
+      minTimeoutInMs: 1000,
+      maxTimeoutInMs: 10000,
+      factor: 2,
+      randomize: true,
+    },
+  },
+
+  // Build configuration
+  build: {
+    autoDetectExternal: true,
+    keepNames: true,
+    minify: false,
+    extensions: [], // Build extensions go here
+  },
+
+  // Global lifecycle hooks
+  onStart: async ({ payload, ctx }) => {
+    console.log("Global task start");
+  },
+  onSuccess: async ({ payload, output, ctx }) => {
+    console.log("Global task success");
+  },
+  onFailure: async ({ payload, error, ctx }) => {
+    console.log("Global task failure");
+  },
+});
+```
+
+## Build Extensions
+
+### Database & ORM
+
+#### Prisma
+
+```ts
+import { prismaExtension } from "@trigger.dev/build/extensions/prisma";
+
+extensions: [
+  prismaExtension({
+    schema: "prisma/schema.prisma",
+    version: "5.19.0", // Optional: specify version
+    migrate: true, // Run migrations during build
+    directUrlEnvVarName: "DIRECT_DATABASE_URL",
+    typedSql: true, // Enable TypedSQL support
+  }),
+];
+```
+
+#### TypeScript Decorators (for TypeORM)
+
+```ts
+import { emitDecoratorMetadata } from "@trigger.dev/build/extensions/typescript";
+
+extensions: [
+  emitDecoratorMetadata(), // Enables decorator metadata
+];
+```
+
+### Scripting Languages
+
+#### Python
+
+```ts
+import { pythonExtension } from "@trigger.dev/build/extensions/python";
+
+extensions: [
+  pythonExtension({
+    scripts: ["./python/**/*.py"], // Copy Python files
+    requirementsFile: "./requirements.txt", // Install packages
+    devPythonBinaryPath: ".venv/bin/python", // Dev mode binary
+  }),
+];
+
+// Usage in tasks
+const result = await python.runInline(`print("Hello, world!")`);
+const output = await python.runScript("./python/script.py", ["arg1"]);
+```
+
+### Browser Automation
+
+#### Playwright
+
+```ts
+import { playwright } from "@trigger.dev/build/extensions/playwright";
+
+extensions: [
+  playwright({
+    browsers: ["chromium", "firefox", "webkit"], // Default: ["chromium"]
+    headless: true, // Default: true
+  }),
+];
+```
+
+#### Puppeteer
+
+```ts
+import { puppeteer } from "@trigger.dev/build/extensions/puppeteer";
+
+extensions: [puppeteer()];
+
+// Environment variable needed:
+// PUPPETEER_EXECUTABLE_PATH: "/usr/bin/google-chrome-stable"
+```
+
+#### Lightpanda
+
+```ts
+import { lightpanda } from "@trigger.dev/build/extensions/lightpanda";
+
+extensions: [
+  lightpanda({
+    version: "latest", // or "nightly"
+    disableTelemetry: false,
+  }),
+];
+```
+
+### Media Processing
+
+#### FFmpeg
+
+```ts
+import { ffmpeg } from "@trigger.dev/build/extensions/core";
+
+extensions: [
+  ffmpeg({ version: "7" }), // Static build, or omit for Debian version
+];
+
+// Automatically sets FFMPEG_PATH and FFPROBE_PATH
+// Add fluent-ffmpeg to external packages if using
+```
+
+#### Audio Waveform
+
+```ts
+import { audioWaveform } from "@trigger.dev/build/extensions/audioWaveform";
+
+extensions: [
+  audioWaveform(), // Installs Audio Waveform 1.1.0
+];
+```
+
+### System & Package Management
+
+#### System Packages (apt-get)
+
+```ts
+import { aptGet } from "@trigger.dev/build/extensions/core";
+
+extensions: [
+  aptGet({
+    packages: ["ffmpeg", "imagemagick", "curl=7.68.0-1"], // Can specify versions
+  }),
+];
+```
+
+#### Additional NPM Packages
+
+Only use this for installing CLI tools, NOT packages you import in your code.
+
+```ts
+import { additionalPackages } from "@trigger.dev/build/extensions/core";
+
+extensions: [
+  additionalPackages({
+    packages: ["wrangler"], // CLI tools and specific versions
+  }),
+];
+```
+
+#### Additional Files
+
+```ts
+import { additionalFiles } from "@trigger.dev/build/extensions/core";
+
+extensions: [
+  additionalFiles({
+    files: ["wrangler.toml", "./assets/**", "./fonts/**"], // Glob patterns supported
+  }),
+];
+```
+
+### Environment & Build Tools
+
+#### Environment Variable Sync
+
+```ts
+import { syncEnvVars } from "@trigger.dev/build/extensions/core";
+
+extensions: [
+  syncEnvVars(async (ctx) => {
+    // ctx contains: environment, projectRef, env
+    return [
+      { name: "SECRET_KEY", value: await getSecret(ctx.environment) },
+      { name: "API_URL", value: ctx.environment === "prod" ? "api.prod.com" : "api.dev.com" },
+    ];
+  }),
+];
+```
+
+#### ESBuild Plugins
+
+```ts
+import { esbuildPlugin } from "@trigger.dev/build/extensions";
+import { sentryEsbuildPlugin } from "@sentry/esbuild-plugin";
+
+extensions: [
+  esbuildPlugin(
+    sentryEsbuildPlugin({
+      org: process.env.SENTRY_ORG,
+      project: process.env.SENTRY_PROJECT,
+      authToken: process.env.SENTRY_AUTH_TOKEN,
+    }),
+    { placement: "last", target: "deploy" } // Optional config
+  ),
+];
+```
+
+## Custom Build Extensions
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk";
+
+const customExtension = {
+  name: "my-custom-extension",
+
+  externalsForTarget: (target) => {
+    return ["some-native-module"]; // Add external dependencies
+  },
+
+  onBuildStart: async (context) => {
+    console.log(`Build starting for ${context.target}`);
+    // Register esbuild plugins, modify build context
+  },
+
+  onBuildComplete: async (context, manifest) => {
+    console.log("Build complete, adding layers");
+    // Add build layers, modify deployment
+    context.addLayer({
+      id: "my-layer",
+      files: [{ source: "./custom-file", destination: "/app/custom" }],
+      commands: ["chmod +x /app/custom"],
+    });
+  },
+};
+
+export default defineConfig({
+  project: "my-project",
+  build: {
+    extensions: [customExtension],
+  },
+});
+```
+
+## Advanced Configuration
+
+### Telemetry
+
+```ts
+import { PrismaInstrumentation } from "@prisma/instrumentation";
+import { OpenAIInstrumentation } from "@langfuse/openai";
+
+export default defineConfig({
+  // ... other config
+  telemetry: {
+    instrumentations: [new PrismaInstrumentation(), new OpenAIInstrumentation()],
+    exporters: [customExporter], // Optional custom exporters
+  },
+});
+```
+
+### Machine & Performance
+
+```ts
+export default defineConfig({
+  // ... other config
+  defaultMachine: "large-1x", // Default machine for all tasks
+  maxDuration: 300, // Default max duration (seconds)
+  enableConsoleLogging: true, // Console logging in development
+});
+```
+
+## Common Extension Combinations
+
+### Full-Stack Web App
+
+```ts
+extensions: [
+  prismaExtension({ schema: "prisma/schema.prisma", migrate: true }),
+  additionalFiles({ files: ["./public/**", "./assets/**"] }),
+  syncEnvVars(async (ctx) => [...envVars]),
+];
+```
+
+### AI/ML Processing
+
+```ts
+extensions: [
+  pythonExtension({
+    scripts: ["./ai/**/*.py"],
+    requirementsFile: "./requirements.txt",
+  }),
+  ffmpeg({ version: "7" }),
+  additionalPackages({ packages: ["wrangler"] }),
+];
+```
+
+### Web Scraping
+
+```ts
+extensions: [
+  playwright({ browsers: ["chromium"] }),
+  puppeteer(),
+  additionalFiles({ files: ["./selectors.json", "./proxies.txt"] }),
+];
+```
+
+## Best Practices
+
+- **Use specific versions**: Pin extension versions for reproducible builds
+- **External packages**: Add modules with native addons to the `build.external` array
+- **Environment sync**: Use `syncEnvVars` for dynamic secrets
+- **File paths**: Use glob patterns for flexible file inclusion
+- **Debug builds**: Use `--log-level debug --dry-run` for troubleshooting
+
+Extensions only affect deployment, not local development. Use `external` array for packages that shouldn't be bundled.
diff --git a/.claude/skills/trigger-realtime/SKILL.md b/.claude/skills/trigger-realtime/SKILL.md
new file mode 100644
index 0000000000..872e7a1ab0
--- /dev/null
+++ b/.claude/skills/trigger-realtime/SKILL.md
@@ -0,0 +1,281 @@
+---
+name: trigger-realtime
+description: "How to use realtime in your Trigger.dev tasks and your frontend"
+---
+
+Source Cursor rule: `.cursor/rules/trigger.realtime.mdc`.
+Original file scope: `**/trigger/**/*.ts`.
+Original Cursor alwaysApply: `false`.
+
+# Trigger.dev Realtime (v4)
+
+**Real-time monitoring and updates for runs**
+
+## Core Concepts
+
+Realtime allows you to:
+
+- Subscribe to run status changes, metadata updates, and streams
+- Build real-time dashboards and UI updates
+- Monitor task progress from frontend and backend
+
+## Authentication
+
+### Public Access Tokens
+
+```ts
+import { auth } from "@trigger.dev/sdk";
+
+// Read-only token for specific runs
+const publicToken = await auth.createPublicToken({
+  scopes: {
+    read: {
+      runs: ["run_123", "run_456"],
+      tasks: ["my-task-1", "my-task-2"],
+    },
+  },
+  expirationTime: "1h", // Default: 15 minutes
+});
+```
+
+### Trigger Tokens (Frontend only)
+
+```ts
+// Single-use token for triggering tasks
+const triggerToken = await auth.createTriggerPublicToken("my-task", {
+  expirationTime: "30m",
+});
+```
+
+## Backend Usage
+
+### Subscribe to Runs
+
+```ts
+import { runs, tasks } from "@trigger.dev/sdk";
+
+// Trigger and subscribe
+const handle = await tasks.trigger("my-task", { data: "value" });
+
+// Subscribe to specific run
+for await (const run of runs.subscribeToRun<typeof myTask>(handle.id)) {
+  console.log(`Status: ${run.status}, Progress: ${run.metadata?.progress}`);
+  if (run.status === "COMPLETED") break;
+}
+
+// Subscribe to runs with tag
+for await (const run of runs.subscribeToRunsWithTag("user-123")) {
+  console.log(`Tagged run ${run.id}: ${run.status}`);
+}
+
+// Subscribe to batch
+for await (const run of runs.subscribeToBatch(batchId)) {
+  console.log(`Batch run ${run.id}: ${run.status}`);
+}
+```
+
+### Streams
+
+```ts
+import { task, metadata } from "@trigger.dev/sdk";
+
+// Task that streams data
+export type STREAMS = {
+  openai: OpenAI.ChatCompletionChunk;
+};
+
+export const streamingTask = task({
+  id: "streaming-task",
+  run: async (payload) => {
+    const completion = await openai.chat.completions.create({
+      model: "gpt-4",
+      messages: [{ role: "user", content: payload.prompt }],
+      stream: true,
+    });
+
+    // Register stream
+    const stream = await metadata.stream("openai", completion);
+
+    let text = "";
+    for await (const chunk of stream) {
+      text += chunk.choices[0]?.delta?.content || "";
+    }
+
+    return { text };
+  },
+});
+
+// Subscribe to streams
+for await (const part of runs.subscribeToRun(runId).withStreams<STREAMS>()) {
+  switch (part.type) {
+    case "run":
+      console.log("Run update:", part.run.status);
+      break;
+    case "openai":
+      console.log("Stream chunk:", part.chunk);
+      break;
+  }
+}
+```
+
+## React Frontend Usage
+
+### Installation
+
+```bash
+bun add @trigger.dev/react-hooks
+```
+
+### Triggering Tasks
+
+```tsx
+"use client";
+import { useTaskTrigger, useRealtimeTaskTrigger } from "@trigger.dev/react-hooks";
+import type { myTask } from "../trigger/tasks";
+
+function TriggerComponent({ accessToken }: { accessToken: string }) {
+  // Basic trigger
+  const { submit, handle, isLoading } = useTaskTrigger<typeof myTask>("my-task", {
+    accessToken,
+  });
+
+  // Trigger with realtime updates
+  const {
+    submit: realtimeSubmit,
+    run,
+    isLoading: isRealtimeLoading,
+  } = useRealtimeTaskTrigger<typeof myTask>("my-task", { accessToken });
+
+  return (
+    <div>
+      <button onClick={() => submit({ data: "value" })} disabled={isLoading}>
+        Trigger Task
+      </button>
+
+      <button onClick={() => realtimeSubmit({ data: "realtime" })} disabled={isRealtimeLoading}>
+        Trigger with Realtime
+      </button>
+
+      {run && <div>Status: {run.status}</div>}
+    </div>
+  );
+}
+```
+
+### Subscribing to Runs
+
+```tsx
+"use client";
+import { useRealtimeRun, useRealtimeRunsWithTag } from "@trigger.dev/react-hooks";
+import type { myTask } from "../trigger/tasks";
+
+function SubscribeComponent({ runId, accessToken }: { runId: string; accessToken: string }) {
+  // Subscribe to specific run
+  const { run, error } = useRealtimeRun<typeof myTask>(runId, {
+    accessToken,
+    onComplete: (run) => {
+      console.log("Task completed:", run.output);
+    },
+  });
+
+  // Subscribe to tagged runs
+  const { runs } = useRealtimeRunsWithTag("user-123", { accessToken });
+
+  if (error) return <div>Error: {error.message}</div>;
+  if (!run) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <div>Status: {run.status}</div>
+      <div>Progress: {run.metadata?.progress || 0}%</div>
+      {run.output && <div>Result: {JSON.stringify(run.output)}</div>}
+
+      <h3>Tagged Runs:</h3>
+      {runs.map((r) => (
+        <div key={r.id}>
+          {r.id}: {r.status}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### Streams with React
+
+```tsx
+"use client";
+import { useRealtimeRunWithStreams } from "@trigger.dev/react-hooks";
+import type { streamingTask, STREAMS } from "../trigger/tasks";
+
+function StreamComponent({ runId, accessToken }: { runId: string; accessToken: string }) {
+  const { run, streams } = useRealtimeRunWithStreams<typeof streamingTask, STREAMS>(runId, {
+    accessToken,
+  });
+
+  const text = streams.openai
+    .filter((chunk) => chunk.choices[0]?.delta?.content)
+    .map((chunk) => chunk.choices[0].delta.content)
+    .join("");
+
+  return (
+    <div>
+      <div>Status: {run?.status}</div>
+      <div>Streamed Text: {text}</div>
+    </div>
+  );
+}
+```
+
+### Wait Tokens
+
+```tsx
+"use client";
+import { useWaitToken } from "@trigger.dev/react-hooks";
+
+function WaitTokenComponent({ tokenId, accessToken }: { tokenId: string; accessToken: string }) {
+  const { complete } = useWaitToken(tokenId, { accessToken });
+
+  return <button onClick={() => complete({ approved: true })}>Approve Task</button>;
+}
+```
+
+### SWR Hooks (Fetch Once)
+
+```tsx
+"use client";
+import { useRun } from "@trigger.dev/react-hooks";
+import type { myTask } from "../trigger/tasks";
+
+function SWRComponent({ runId, accessToken }: { runId: string; accessToken: string }) {
+  const { run, error, isLoading } = useRun<typeof myTask>(runId, {
+    accessToken,
+    refreshInterval: 0, // Disable polling (recommended)
+  });
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return <div>Run: {run?.status}</div>;
+}
+```
+
+## Run Object Properties
+
+Key properties available in run subscriptions:
+
+- `id`: Unique run identifier
+- `status`: `QUEUED`, `EXECUTING`, `COMPLETED`, `FAILED`, `CANCELED`, etc.
+- `payload`: Task input data (typed)
+- `output`: Task result (typed, when completed)
+- `metadata`: Real-time updatable data
+- `createdAt`, `updatedAt`: Timestamps
+- `costInCents`: Execution cost
+
+## Best Practices
+
+- **Use Realtime over SWR**: Recommended for most use cases due to rate limits
+- **Scope tokens properly**: Only grant necessary read/trigger permissions
+- **Handle errors**: Always check for errors in hooks and subscriptions
+- **Type safety**: Use task types for proper payload/output typing
+- **Cleanup subscriptions**: Backend subscriptions auto-complete, frontend hooks auto-cleanup
diff --git a/.claude/skills/trigger-scheduled-tasks/SKILL.md b/.claude/skills/trigger-scheduled-tasks/SKILL.md
new file mode 100644
index 0000000000..911df52259
--- /dev/null
+++ b/.claude/skills/trigger-scheduled-tasks/SKILL.md
@@ -0,0 +1,126 @@
+---
+name: trigger-scheduled-tasks
+description: "How to write and use scheduled Trigger.dev tasks"
+---
+
+Source Cursor rule: `.cursor/rules/trigger.scheduled-tasks.mdc`.
+Original file scope: `**/trigger/**/*.ts`.
+Original Cursor alwaysApply: `false`.
+
+# Scheduled tasks (cron)
+
+Recurring tasks using cron. For one-off future runs, use the **delay** option.
+
+## Define a scheduled task
+
+```ts
+import { schedules } from "@trigger.dev/sdk";
+
+export const task = schedules.task({
+  id: "first-scheduled-task",
+  run: async (payload) => {
+    payload.timestamp; // Date (scheduled time, UTC)
+    payload.lastTimestamp; // Date | undefined
+    payload.timezone; // IANA, e.g. "America/New_York" (default "UTC")
+    payload.scheduleId; // string
+    payload.externalId; // string | undefined
+    payload.upcoming; // Date[]
+
+    payload.timestamp.toLocaleString("en-US", { timeZone: payload.timezone });
+  },
+});
+```
+
+> Scheduled tasks need at least one schedule attached to run.
+
+## Attach schedules
+
+**Declarative (sync on dev/deploy):**
+
+```ts
+schedules.task({
+  id: "every-2h",
+  cron: "0 */2 * * *", // UTC
+  run: async () => {},
+});
+
+schedules.task({
+  id: "tokyo-5am",
+  cron: { pattern: "0 5 * * *", timezone: "Asia/Tokyo", environments: ["PRODUCTION", "STAGING"] },
+  run: async () => {},
+});
+```
+
+**Imperative (SDK or dashboard):**
+
+```ts
+await schedules.create({
+  task: task.id,
+  cron: "0 0 * * *",
+  timezone: "America/New_York", // DST-aware
+  externalId: "user_123",
+  deduplicationKey: "user_123-daily", // updates if reused
+});
+```
+
+### Dynamic / multi-tenant example
+
+```ts
+// /trigger/reminder.ts
+export const reminderTask = schedules.task({
+  id: "todo-reminder",
+  run: async (p) => {
+    if (!p.externalId) throw new Error("externalId is required");
+    const user = await db.getUser(p.externalId);
+    await sendReminderEmail(user);
+  },
+});
+```
+
+```ts
+// app/reminders/route.ts
+export async function POST(req: Request) {
+  const data = await req.json();
+  return Response.json(
+    await schedules.create({
+      task: reminderTask.id,
+      cron: "0 8 * * *",
+      timezone: data.timezone,
+      externalId: data.userId,
+      deduplicationKey: `${data.userId}-reminder`,
+    })
+  );
+}
+```
+
+## Cron syntax (no seconds)
+
+```
+* * * * *
+| | | | └ day of week (0–7 or 1L–7L; 0/7=Sun; L=last)
+| | | └── month (1–12)
+| | └──── day of month (1–31 or L)
+| └────── hour (0–23)
+└──────── minute (0–59)
+```
+
+## When schedules won't trigger
+
+- **Dev:** only when the dev CLI is running.
+- **Staging/Production:** only for tasks in the **latest deployment**.
+
+## SDK management (quick refs)
+
+```ts
+await schedules.retrieve(id);
+await schedules.list();
+await schedules.update(id, { cron: "0 0 1 * *", externalId: "ext", deduplicationKey: "key" });
+await schedules.deactivate(id);
+await schedules.activate(id);
+await schedules.del(id);
+await schedules.timezones(); // list of IANA timezones
+```
+
+## Dashboard
+
+Create/attach schedules visually (Task, Cron pattern, Timezone, Optional: External ID, Dedup key, Environments). Test scheduled tasks from the **Test** page.
diff --git a/.claude/skills/ui/SKILL.md b/.claude/skills/ui/SKILL.md
new file mode 100644
index 0000000000..7dc3e4edfd
--- /dev/null
+++ b/.claude/skills/ui/SKILL.md
@@ -0,0 +1,137 @@
+---
+name: ui
+description: "Use when building or editing frontend UI components, layouts, styling, design system usage, colors, dark mode, or icons."
+---
+
+Source Cursor rule: `.cursor/rules/ui.mdc`.
+Original Cursor alwaysApply: `true`.
+
+# UI Components
+
+## Design System Priority
+
+1. **First choice:** `@trycompai/design-system`
+2. **Fallback:** `@trycompai/ui` only if DS doesn't have the component
+
+```tsx
+// ✅ Design system
+import { Button, Card, Input, Sheet, Badge } from '@trycompai/design-system';
+import { Add, Close, ArrowRight } from '@trycompai/design-system/icons';
+
+// ❌ Don't use when DS has it
+import { Button } from '@trycompai/ui/button';
+import { Plus } from 'lucide-react';
+```
+
+## No className on DS Components
+
+DS components don't accept `className`. Use variants and props only.
+
+```tsx
+// ✅ Use variants
+<Button variant="destructive" size="sm" loading={isLoading}>Delete</Button>
+<Button type="submit" iconRight={<ArrowRight size={16} />}>Continue</Button>
+<Badge variant="outline">Active</Badge>
+
+// ❌ TypeScript will error
+<Button className="bg-red-500">Delete</Button>
+```
+
+## Layout with Wrapper Divs
+
+For layout concerns, wrap DS components:
+
+```tsx
+// ✅ Wrapper for width
+<div className="w-full">
+  <Button>Full Width</Button>
+</div>
+
+// ✅ Use Stack for spacing
+<Stack gap="4" direction="row">
+  <Button>First</Button>
+  <Button>Second</Button>
+</Stack>
+```
+
+## Componentize Repeated Patterns
+
+If a pattern appears 2+ times, extract it:
+
+```tsx
+// Repeated? Make a component
+<div className="flex items-center gap-2">
+  <div className="w-2 h-2 rounded-full bg-green-500" />
+  <span className="text-sm">Active</span>
+</div>
+// → Create <StatusDot status="active" />
+```
+
+## Extension Strategy
+
+When you need new styling:
+
+1. **Check existing variants** - component may already support it
+2. **Add a variant** to the component's `cva` definition
+3. **Create a new component** if it's a genuinely new pattern
+
+```tsx
+// Adding a variant
+const badgeVariants = cva("...", {
+  variants: {
+    variant: {
+      // existing...
+      counter: "bg-muted text-muted-foreground tabular-nums font-mono",
+    },
+  },
+});
+```
+
+## Semantic Colors
+
+Use CSS variables, not hardcoded colors:
+
+```tsx
+// ✅ Semantic tokens
+<div className="bg-background text-foreground border-border">
+<div className="bg-muted text-muted-foreground">
+<div className="bg-destructive/10 text-destructive">
+
+// ❌ Hardcoded
+<div className="bg-white text-black">
+<div className="bg-[#059669]">
+```
+
+## Dark Mode
+
+Always support both modes:
+
+```tsx
+// Status colors with dark variants
+<div className="bg-green-50 dark:bg-green-950/20 text-green-600 dark:text-green-400">
+<div className="bg-red-50 dark:bg-red-950/20 text-red-600 dark:text-red-400">
+```
+
+## Icons
+
+Carbon icons from DS, not lucide:
+
+```tsx
+// ✅ Design system icons with size prop
+import { Add, Close, ChevronDown } from '@trycompai/design-system/icons';
+<Add size={16} />
+
+// ❌ Don't use lucide
+import { Plus, X } from 'lucide-react';
+<Plus className="h-4 w-4" />
+```
+
+## Anti-Patterns
+
+```tsx
+// ❌ Never do these
+<div style={{ display: 'flex' }}>              // Inline styles
+<Button className="bg-red-500">               // className on DS
+<div className="bg-[#059669]">                // Hardcoded colors
+<div className="w-[847px]">                   // Arbitrary values
+```
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000000..cfecc4842d
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,154 @@
+# Project Rules
+
+## Tooling
+
+- **Package manager**: `bun` (never npm/yarn/pnpm)
+- **Build**: `bun run build` (uses turbo). Filter: `bun run --filter '@trycompai/app' build`
+- **Typecheck**: `bun run typecheck` or `npx turbo run typecheck --filter=@trycompai/api`
+- **Tests (app)**: `cd apps/app && npx vitest run`
+- **Tests (api)**: `cd apps/api && npx jest src/<module> --passWithNoTests`
+- **Lint**: `bun run lint`
+
+## Code Style
+
+- **Max 300 lines per file.** Split into focused modules if exceeded.
+- **No `as any` casts.** Ever. Use proper types, generics, or `unknown` with type guards.
+- **No `@ts-ignore` or `@ts-expect-error`.** Fix the type instead.
+- **Strict TypeScript**: Use zod for runtime validation, generics over `any`.
+- **Early returns** to avoid nested conditionals.
+- **Named parameters** for functions with 2+ arguments.
+- **Event handlers**: prefix with `handle` (e.g., `handleSubmit`).
+
+## Monorepo Structure
+
+```
+apps/
+  api/          # NestJS API (auth, RBAC, business logic)
+  app/          # Next.js frontend (compliance + security products)
+  portal/       # Employee portal
+packages/
+  auth/         # RBAC definitions (permissions.ts) — single source of truth
+  db/           # Prisma schema + client
+  ui/           # Legacy component library (being phased out)
+```
+
+## Authentication & Session
+
+- **Auth lives in `apps/api` (NestJS).** The API is the single source of truth for authentication via better-auth. All apps and packages that need to authenticate (app, portal, device-agent, etc.) MUST go through the API — never run a local better-auth instance or handle auth directly in a frontend app.
+- **Session-based auth only.** No JWT tokens. Cross-subdomain cookies (`.trycomp.ai`) allow sessions to work across all apps.
+- **HybridAuthGuard** supports 3 methods in order: API Key (`x-api-key`), Service Token (`x-service-token`), Session (cookies). `@Public()` skips auth.
+- **Client-side auth**: `authClient` (better-auth client) with `baseURL` pointing to the API, NOT the current app.
+- **Client-side data**: `apiClient` from `@/lib/api-client` (always sends cookies).
+- **Server-side data**: `serverApi` from `@/lib/api-server.ts`.
+- **Server-side session checks**: Proxy to the API's `/api/auth/get-session` endpoint — do NOT instantiate better-auth locally.
+- **Raw `fetch()` to API**: MUST include `credentials: 'include'`, otherwise 401.
+
+## API Architecture
+
+We are migrating away from Next.js server actions toward calling the NestJS API directly.
+
+### Simple CRUD operations
+Client components call the NestJS API via custom SWR hooks. No server action wrapper needed.
+
+### Multi-step orchestration
+When an operation requires multiple API calls (e.g., S3 upload + PATCH), create a Next.js API route (`apps/app/src/app/api/...`) that orchestrates them.
+
+### What NOT to do
+- Do NOT use server actions for new features
+- Do NOT keep server actions as wrappers around API calls
+- Do NOT add direct database (`@db`) access in the Next.js app for mutations — always go through the API
+- Do NOT use `useAction` from `next-safe-action` for new code
+
+### API Client
+- Server-side (Next.js API routes/pages): `serverApi` from `apps/app/src/lib/api-server.ts`
+- Client-side (hooks): `apiClient` / `api` from `@/lib/api-client`
+
+### API Response Format
+- **List endpoints**: `{ data: [...], count, authType, authenticatedUser }` → access via `response.data.data`
+- **Single resource endpoints**: `{ ...entity, authType, authenticatedUser }` → access via `response.data`
+- Both `apiClient` and `serverApi` wrap in `{ data, error, status }`
+
+## RBAC
+
+### Permissions Model
+- Flat `resource:action` model (e.g., `pentest:read`, `control:update`)
+- Single source of truth: `packages/auth/src/permissions.ts`
+- Built-in roles: `owner`, `admin`, `auditor`, `employee`, `contractor`
+- Custom roles: stored in `organization_role` table per organization
+- Multiple roles per user (comma-separated in `member.role`)
+
+### Multi-Product Architecture
+- **Products** (compliance, pen testing) are org-level subscription/feature flags — NOT RBAC
+- **RBAC** controls user access within products
+- `app:read` gates the compliance dashboard; `pentest:read` gates security product
+- Portal-only resources (`policy`, `compliance`) do NOT grant app access
+
+### API Endpoint Requirements
+Every customer-facing API endpoint MUST have:
+```typescript
+@UseGuards(HybridAuthGuard, PermissionGuard)  // at controller or endpoint level
+@RequirePermission('resource', 'action')       // on every endpoint
+```
+- Controller format: `@Controller({ path: 'name', version: '1' })`, NOT `@Controller('v1/name')`
+- `@Public()` for unauthenticated endpoints (webhooks, etc.)
+- The `AuditLogInterceptor` only logs when `@RequirePermission` metadata is present
+
+### Frontend Permission Gating
+- **Nav items**: Gate with `canAccessRoute(permissions, 'routeSegment')`
+- **Rail icons**: Gate product sections (Compliance, Security, Trust, Settings) by permission
+- **Mutation buttons**: Gate with `hasPermission(permissions, 'resource', 'action')`
+- **Page-level**: Every product layout uses `requireRoutePermission('segment', orgId)` server-side
+- **Route permissions**: Defined in `ROUTE_PERMISSIONS` in `apps/app/src/lib/permissions.ts`
+- No manual role string parsing (`role.includes('admin')`) — always use permission checks
+
+### Permission Resources
+`organization`, `member`, `control`, `evidence`, `policy`, `risk`, `vendor`, `task`, `framework`, `audit`, `finding`, `questionnaire`, `integration`, `apiKey`, `trust`, `pentest`, `app`, `compliance`
+
+## Design System
+
+- **Always prefer `@trycompai/design-system`** over `@trycompai/ui`. Check DS exports first.
+- `@trycompai/ui` is the legacy library being phased out — only use as last resort.
+- **Icons**: `@trycompai/design-system/icons` (Carbon icons), NOT `lucide-react`
+- **DS components that do NOT accept `className`**: `Text`, `Stack`, `HStack`, `Badge`, `Button` — wrap in `<div>` for custom styling
+- **Layout**: Use `PageLayout`, `PageHeader`, `Stack`, `HStack`, `Section`, `SettingGroup`
+- **Patterns**: Sheet (`Sheet > SheetContent > SheetHeader + SheetBody`), Drawer, Collapsible
+- **After editing any frontend component**: Run the `audit-design-system` skill to catch `@trycompai/ui` or `lucide-react` imports that should be migrated
+
+## Data Fetching
+
+- **Server components**: Fetch with `serverApi`, pass as `fallbackData` to client
+- **Client components**: `useSWR` with `apiClient` or custom hooks (e.g., `usePolicy`, `useTask`)
+- **SWR hooks**: Use `fallbackData` for SSR initial data, `revalidateOnMount: !initialData`
+- **`mutate()` safety**: Guard against `undefined` in optimistic update functions
+- **`Array.isArray()` checks**: When consuming SWR data that could be stale
+
+## Testing
+
+- **Every new feature MUST include tests.** No exceptions.
+- **TDD preferred**: Write failing tests first, then make them pass.
+- **App tests**: Vitest + @testing-library/react (jsdom environment)
+- **API tests**: Jest with NestJS testing utilities
+- **Permission tests**: Test admin (write) and read-only user scenarios
+- **Run from package dir**: `cd apps/app && npx vitest run` or `cd apps/api && npx jest`
+
+## Database
+
+- **Schema**: `packages/db/prisma/schema/` (split into files per model)
+- **IDs**: Always use prefixed CUIDs: `@default(dbgenerated("generate_prefixed_cuid('prefix'::text)"))`
+- **Migrations**: `cd packages/db && bunx prisma migrate dev --name your_name`
+- **Multi-tenancy**: Always scope queries by `organizationId`
+- **Transactions**: Use for operations modifying multiple records
+
+## Git
+
+- **Conventional commits**: `<type>(<scope>): <description>` (imperative, lowercase)
+- **Never use `git stash`** unless explicitly asked
+- **Never skip hooks** (`--no-verify`)
+- **Never force push** to main/master
+
+## Forms
+
+- All forms use **React Hook Form + Zod** validation
+- Define Zod schema first, infer type with `z.infer<typeof schema>`
+- Use `Controller` for complex components (Select, Combobox)
+- Never use `useState` for form field values

From 2da22b6f8b678ee4888e7e168dc20c933338ceb0 Mon Sep 17 00:00:00 2001
From: Lewis Carhart <lewis@trycomp.ai>
Date: Mon, 27 Apr 2026 14:56:04 +0100
Subject: [PATCH 36/40] chore(docs): update documentation for typecheck and
 testing commands

- Replaced `npx` with `bunx` in various SKILL.md files to standardize command usage for typechecking and testing across the codebase.
- Updated AGENTS.md to reflect the new command format for running typechecks and tests in the app and API directories.
- Clarified the preferred usage of `@trycompai/design-system` over `@trycompai/ui` in infrastructure documentation.
---
 .agents/skills/audit-design-system/SKILL.md        |  2 +-
 .agents/skills/audit-hooks/SKILL.md                |  2 +-
 .agents/skills/audit-rbac/SKILL.md                 |  2 +-
 .agents/skills/audit-tests/SKILL.md                |  4 ++--
 .agents/skills/better-auth-best-practices/SKILL.md | 12 ++++++------
 .agents/skills/data/SKILL.md                       |  7 ++++++-
 .agents/skills/forms/SKILL.md                      |  4 ++--
 .agents/skills/infra/SKILL.md                      |  2 +-
 .agents/skills/new-feature-setup/SKILL.md          |  2 +-
 .agents/skills/prisma/SKILL.md                     |  1 +
 .agents/skills/production-readiness/SKILL.md       |  4 ++--
 .agents/skills/prompt-engineering/SKILL.md         |  2 +-
 .agents/skills/trigger-advanced-tasks/SKILL.md     |  4 ++--
 .agents/skills/trigger-basic/SKILL.md              |  4 ++--
 .claude/agents/test-writer.md                      |  4 ++--
 .claude/skills/audit-design-system/SKILL.md        |  2 +-
 .claude/skills/audit-hooks/SKILL.md                |  2 +-
 .claude/skills/audit-rbac/SKILL.md                 |  2 +-
 .claude/skills/audit-tests/SKILL.md                |  4 ++--
 .claude/skills/data/SKILL.md                       |  7 ++++++-
 .claude/skills/forms/SKILL.md                      |  4 ++--
 .claude/skills/infra/SKILL.md                      |  2 +-
 .claude/skills/new-feature-setup/SKILL.md          |  2 +-
 .claude/skills/prisma/SKILL.md                     |  1 +
 .claude/skills/production-readiness/SKILL.md       |  4 ++--
 .claude/skills/prompt-engineering/SKILL.md         |  2 +-
 .claude/skills/trigger-advanced-tasks/SKILL.md     |  4 ++--
 .claude/skills/trigger-basic/SKILL.md              |  4 ++--
 .cursor/rules/data.mdc                             |  7 ++++++-
 .cursor/rules/forms.mdc                            |  4 ++--
 .cursor/rules/infra.mdc                            |  2 +-
 .cursor/rules/prisma.mdc                           |  1 +
 .cursor/rules/prompt-engineering.mdc               |  2 +-
 .cursor/rules/trigger.advanced-tasks.mdc           |  4 ++--
 .cursor/rules/trigger.basic.mdc                    |  4 ++--
 .cursor/rules/trigger.realtime.mdc                 |  2 +-
 AGENTS.md                                          |  8 ++++----
 37 files changed, 74 insertions(+), 56 deletions(-)

diff --git a/.agents/skills/audit-design-system/SKILL.md b/.agents/skills/audit-design-system/SKILL.md
index a0f25f6319..a0c7d0dc22 100644
--- a/.agents/skills/audit-design-system/SKILL.md
+++ b/.agents/skills/audit-design-system/SKILL.md
@@ -20,4 +20,4 @@ Audit the specified files for design system compliance. **Fix every issue found
 2. Find `@trycompai/ui` imports — check if DS equivalent exists
 3. Find `lucide-react` imports — find matching Carbon icons
 4. Migrate components and icons
-5. Run build to verify: `npx turbo run typecheck --filter=@trycompai/app`
+5. Run build to verify: `bunx turbo run typecheck --filter=@trycompai/app`
diff --git a/.agents/skills/audit-hooks/SKILL.md b/.agents/skills/audit-hooks/SKILL.md
index d3f60a1752..7c14d1a240 100644
--- a/.agents/skills/audit-hooks/SKILL.md
+++ b/.agents/skills/audit-hooks/SKILL.md
@@ -31,4 +31,4 @@ Audit the specified files for hook and API usage compliance. **Fix every issue f
 1. Read files specified in `$ARGUMENTS`
 2. Find forbidden patterns and fix them
 3. Ensure all data fetching uses SWR hooks
-4. Run typecheck to verify: `npx turbo run typecheck --filter=@trycompai/app`
+4. Run typecheck to verify: `bunx turbo run typecheck --filter=@trycompai/app`
diff --git a/.agents/skills/audit-rbac/SKILL.md b/.agents/skills/audit-rbac/SKILL.md
index dbb5f7e0da..df0786bcb0 100644
--- a/.agents/skills/audit-rbac/SKILL.md
+++ b/.agents/skills/audit-rbac/SKILL.md
@@ -39,4 +39,4 @@ Audit the specified files or directories for RBAC and audit log compliance. **Fi
 1. Read files specified in `$ARGUMENTS` (or scan the directory)
 2. Check each rule above
 3. **Fix every violation immediately** — don't just report
-4. Run typecheck to verify: `npx turbo run typecheck --filter=@trycompai/api --filter=@trycompai/app`
+4. Run typecheck to verify: `bunx turbo run typecheck --filter=@trycompai/api --filter=@trycompai/app`
diff --git a/.agents/skills/audit-tests/SKILL.md b/.agents/skills/audit-tests/SKILL.md
index 9d80007715..ae7a3b1459 100644
--- a/.agents/skills/audit-tests/SKILL.md
+++ b/.agents/skills/audit-tests/SKILL.md
@@ -10,7 +10,7 @@ Check that unit tests exist and pass for permission-gated components. **Write mi
 - **Component testing**: `@testing-library/react` + `@testing-library/jest-dom`
 - **Setup**: `apps/app/src/test-utils/setup.ts`
 - **Permission mocks**: `apps/app/src/test-utils/mocks/permissions.ts`
-- **Run**: `cd apps/app && npx vitest run`
+- **Run**: `cd apps/app && bunx vitest run`
 
 ## Required Test Pattern
 
@@ -27,4 +27,4 @@ Use `setMockPermissions`, `ADMIN_PERMISSIONS`, `AUDITOR_PERMISSIONS` from test u
 2. Check for corresponding `.test.tsx` files
 3. Write missing tests following the pattern above
 4. Fix any failing tests
-5. Run: `cd apps/app && npx vitest run`
+5. Run: `cd apps/app && bunx vitest run`
diff --git a/.agents/skills/better-auth-best-practices/SKILL.md b/.agents/skills/better-auth-best-practices/SKILL.md
index 3e6a4e1972..5e4b8d9edc 100644
--- a/.agents/skills/better-auth-best-practices/SKILL.md
+++ b/.agents/skills/better-auth-best-practices/SKILL.md
@@ -11,11 +11,11 @@ description: Configure Better Auth server and client, set up database adapters,
 
 ## Setup Workflow
 
-1. Install: `npm install better-auth`
+1. Install: `bun add better-auth`
 2. Set env vars: `BETTER_AUTH_SECRET` and `BETTER_AUTH_URL`
 3. Create `auth.ts` with database + config
 4. Create route handler for your framework
-5. Run `npx @better-auth/cli@latest migrate`
+5. Run `bunx @better-auth/cli@latest migrate`
 6. Verify: call `GET /api/auth/ok` — should return `{ status: "ok" }`
 
 ---
@@ -32,9 +32,9 @@ Only define `baseURL`/`secret` in config if env vars are NOT set.
 CLI looks for `auth.ts` in: `./`, `./lib`, `./utils`, or under `./src`. Use `--config` for custom path.
 
 ### CLI Commands
-- `npx @better-auth/cli@latest migrate` - Apply schema (built-in adapter)
-- `npx @better-auth/cli@latest generate` - Generate schema for Prisma/Drizzle
-- `npx @better-auth/cli mcp --cursor` - Add MCP to AI tools
+- `bunx @better-auth/cli@latest migrate` - Apply schema (built-in adapter)
+- `bunx @better-auth/cli@latest generate` - Generate schema for Prisma/Drizzle
+- `bunx @better-auth/cli@latest mcp --cursor` - Add MCP to AI tools
 
 **Re-run after adding/changing plugins.**
 
@@ -172,4 +172,4 @@ For separate client/server projects: `createAuthClient<typeof auth>()`.
 - [Options Reference](https://better-auth.com/docs/reference/options)
 - [LLMs.txt](https://better-auth.com/llms.txt)
 - [GitHub](https://github.com/better-auth/better-auth)
-- [Init Options Source](https://github.com/better-auth/better-auth/blob/main/packages/core/src/types/init-options.ts)
\ No newline at end of file
+- [Init Options Source](https://github.com/better-auth/better-auth/blob/main/packages/core/src/types/init-options.ts)
diff --git a/.agents/skills/data/SKILL.md b/.agents/skills/data/SKILL.md
index a670937c2d..9acffa3874 100644
--- a/.agents/skills/data/SKILL.md
+++ b/.agents/skills/data/SKILL.md
@@ -55,7 +55,12 @@ export function useTasks({ organizationId, initialData }: UseTasksOptions) {
     mutate(); // Revalidate
   };
 
-  return { tasks: data ?? [], createTask, mutate };
+  const updateTask = async ({ taskId, input }: { taskId: string; input: UpdateTaskInput }) => {
+    await apiClient.put(`/v1/tasks/${taskId}`, input, organizationId);
+    mutate(); // Revalidate
+  };
+
+  return { tasks: data ?? [], createTask, updateTask, mutate };
 }
 ```
 
diff --git a/.agents/skills/forms/SKILL.md b/.agents/skills/forms/SKILL.md
index bcb8beafa8..fd481da527 100644
--- a/.agents/skills/forms/SKILL.md
+++ b/.agents/skills/forms/SKILL.md
@@ -53,7 +53,7 @@ function MyForm() {
 ## Zod Schema Patterns
 
 ```tsx
-const schema = z.object({
+const profileSchema = z.object({
   // Strings
   name: z.string().min(1, 'Required'),
   email: z.string().email(),
@@ -71,7 +71,7 @@ const schema = z.object({
 });
 
 // Cross-field validation
-const schema = z.object({
+const passwordSchema = z.object({
   password: z.string().min(8),
   confirmPassword: z.string(),
 }).refine(d => d.password === d.confirmPassword, {
diff --git a/.agents/skills/infra/SKILL.md b/.agents/skills/infra/SKILL.md
index bf073598f8..70323555da 100644
--- a/.agents/skills/infra/SKILL.md
+++ b/.agents/skills/infra/SKILL.md
@@ -30,7 +30,7 @@ comp/
 │   └── portal/          # Next.js portal
 ├── packages/
 │   ├── db/              # Prisma (@trycompai/db)
-│   ├── ui/              # UI components (@trycompai/ui)
+│   ├── ui/              # Legacy UI (@trycompai/ui); prefer @trycompai/design-system
 │   └── ...
 ├── turbo.json
 └── package.json
diff --git a/.agents/skills/new-feature-setup/SKILL.md b/.agents/skills/new-feature-setup/SKILL.md
index 5c5be80363..37ad78a023 100644
--- a/.agents/skills/new-feature-setup/SKILL.md
+++ b/.agents/skills/new-feature-setup/SKILL.md
@@ -69,7 +69,7 @@ Standard repo conventions apply (see `AGENTS.md`). Highlights:
 - Brainstorm before building new UX (`superpowers:brainstorming`)
 - Plans + subagent-driven execution for multi-step work
 - Run `audit-design-system` after any frontend component edit
-- Always run typecheck before declaring a change done (`npx turbo run typecheck --filter=<pkg>`)
+- Always run typecheck before declaring a change done (`bunx turbo run typecheck --filter=<pkg>`)
 
 ### 5. When done, clean up
 
diff --git a/.agents/skills/prisma/SKILL.md b/.agents/skills/prisma/SKILL.md
index effc4003a0..39e0d85c19 100644
--- a/.agents/skills/prisma/SKILL.md
+++ b/.agents/skills/prisma/SKILL.md
@@ -54,6 +54,7 @@ cd packages/db && bunx prisma migrate dev --name add_user_role
 # 3. Regenerate types in ALL apps that use the db
 bun run -F apps/app db:generate
 bun run -F apps/api db:generate
+bun run -F apps/portal db:generate
 ```
 
 ### ❌ Never Do This
diff --git a/.agents/skills/production-readiness/SKILL.md b/.agents/skills/production-readiness/SKILL.md
index 0300513a9e..1a377c0b45 100644
--- a/.agents/skills/production-readiness/SKILL.md
+++ b/.agents/skills/production-readiness/SKILL.md
@@ -14,8 +14,8 @@ Use parallel subagents to run all four audits simultaneously:
 
 Then run full monorepo verification:
 ```bash
-npx turbo run typecheck --filter=@trycompai/api --filter=@trycompai/app
-cd apps/app && npx vitest run
+bunx turbo run typecheck --filter=@trycompai/api --filter=@trycompai/app
+cd apps/app && bunx vitest run
 ```
 
 Output a Production Readiness Report summarizing all fixes applied and build status.
diff --git a/.agents/skills/prompt-engineering/SKILL.md b/.agents/skills/prompt-engineering/SKILL.md
index 46d7c6b58c..cea633b7d8 100644
--- a/.agents/skills/prompt-engineering/SKILL.md
+++ b/.agents/skills/prompt-engineering/SKILL.md
@@ -36,7 +36,7 @@ Prompt engineering is preferred because:
 
 ---
 
-## The 8 Core Techniques
+## The 6 Core Techniques
 
 ### 1. Be Clear and Direct
 
diff --git a/.agents/skills/trigger-advanced-tasks/SKILL.md b/.agents/skills/trigger-advanced-tasks/SKILL.md
index 2b18faabf5..e5f5471ad5 100644
--- a/.agents/skills/trigger-advanced-tasks/SKILL.md
+++ b/.agents/skills/trigger-advanced-tasks/SKILL.md
@@ -42,7 +42,7 @@ for await (const run of runs.subscribeToRunsWithTag('user_123')) {
 **Tag Best Practices:**
 
 - Use prefixes: `user_123`, `org_abc`, `video:456`
-- Max 10 tags per run, 1-64 characters each
+- Max 10 tags per run, 1-128 characters each
 - Tags don't propagate to child tasks automatically
 
 ## Concurrency & Queues
@@ -405,7 +405,7 @@ export const tracedTask = task({
 ## Usage Monitoring
 
 ```ts
-import { task, usage } from '@trigger.dev/sdk';
+import { logger, task, usage } from '@trigger.dev/sdk';
 
 export const monitoredTask = task({
   id: 'monitored-task',
diff --git a/.agents/skills/trigger-basic/SKILL.md b/.agents/skills/trigger-basic/SKILL.md
index 3efd8127fc..6be5d8f536 100644
--- a/.agents/skills/trigger-basic/SKILL.md
+++ b/.agents/skills/trigger-basic/SKILL.md
@@ -156,8 +156,8 @@ export const taskWithWaits = task({
     await wait.for({ hours: 1 });
     await wait.for({ days: 1 });
 
-    // Wait until specific date
-    await wait.until({ date: new Date("2024-12-25") });
+    // Wait until a future date
+    await wait.until({ date: new Date(Date.now() + 24 * 60 * 60 * 1000) });
 
     // Wait for token (from external system)
     await wait.forToken({
diff --git a/.claude/agents/test-writer.md b/.claude/agents/test-writer.md
index f4300b9195..621e78c06c 100644
--- a/.claude/agents/test-writer.md
+++ b/.claude/agents/test-writer.md
@@ -12,7 +12,7 @@ You write unit tests for React components that use `usePermissions` for RBAC gat
 - **Libraries**: `@testing-library/react` + `@testing-library/jest-dom`
 - **Setup**: `apps/app/src/test-utils/setup.ts`
 - **Permission mocks**: `apps/app/src/test-utils/mocks/permissions.ts`
-- **Run**: `cd apps/app && npx vitest run path/to/test`
+- **Run**: `cd apps/app && bunx vitest run path/to/test`
 
 ## Process
 
@@ -84,4 +84,4 @@ describe('ComponentUnderTest', () => {
 - Mock all external hooks (`useSWR`, `useRouter`, `apiClient`, etc.)
 - Use `screen.queryBy*` for elements that should NOT exist (returns null instead of throwing)
 - Use `screen.getBy*` for elements that MUST exist
-- Run the test after writing to verify it passes: `cd apps/app && npx vitest run path/to/file.test.tsx`
+- Run the test after writing to verify it passes: `cd apps/app && bunx vitest run path/to/file.test.tsx`
diff --git a/.claude/skills/audit-design-system/SKILL.md b/.claude/skills/audit-design-system/SKILL.md
index a0f25f6319..a0c7d0dc22 100644
--- a/.claude/skills/audit-design-system/SKILL.md
+++ b/.claude/skills/audit-design-system/SKILL.md
@@ -20,4 +20,4 @@ Audit the specified files for design system compliance. **Fix every issue found
 2. Find `@trycompai/ui` imports — check if DS equivalent exists
 3. Find `lucide-react` imports — find matching Carbon icons
 4. Migrate components and icons
-5. Run build to verify: `npx turbo run typecheck --filter=@trycompai/app`
+5. Run build to verify: `bunx turbo run typecheck --filter=@trycompai/app`
diff --git a/.claude/skills/audit-hooks/SKILL.md b/.claude/skills/audit-hooks/SKILL.md
index d3f60a1752..7c14d1a240 100644
--- a/.claude/skills/audit-hooks/SKILL.md
+++ b/.claude/skills/audit-hooks/SKILL.md
@@ -31,4 +31,4 @@ Audit the specified files for hook and API usage compliance. **Fix every issue f
 1. Read files specified in `$ARGUMENTS`
 2. Find forbidden patterns and fix them
 3. Ensure all data fetching uses SWR hooks
-4. Run typecheck to verify: `npx turbo run typecheck --filter=@trycompai/app`
+4. Run typecheck to verify: `bunx turbo run typecheck --filter=@trycompai/app`
diff --git a/.claude/skills/audit-rbac/SKILL.md b/.claude/skills/audit-rbac/SKILL.md
index dbb5f7e0da..df0786bcb0 100644
--- a/.claude/skills/audit-rbac/SKILL.md
+++ b/.claude/skills/audit-rbac/SKILL.md
@@ -39,4 +39,4 @@ Audit the specified files or directories for RBAC and audit log compliance. **Fi
 1. Read files specified in `$ARGUMENTS` (or scan the directory)
 2. Check each rule above
 3. **Fix every violation immediately** — don't just report
-4. Run typecheck to verify: `npx turbo run typecheck --filter=@trycompai/api --filter=@trycompai/app`
+4. Run typecheck to verify: `bunx turbo run typecheck --filter=@trycompai/api --filter=@trycompai/app`
diff --git a/.claude/skills/audit-tests/SKILL.md b/.claude/skills/audit-tests/SKILL.md
index 9d80007715..ae7a3b1459 100644
--- a/.claude/skills/audit-tests/SKILL.md
+++ b/.claude/skills/audit-tests/SKILL.md
@@ -10,7 +10,7 @@ Check that unit tests exist and pass for permission-gated components. **Write mi
 - **Component testing**: `@testing-library/react` + `@testing-library/jest-dom`
 - **Setup**: `apps/app/src/test-utils/setup.ts`
 - **Permission mocks**: `apps/app/src/test-utils/mocks/permissions.ts`
-- **Run**: `cd apps/app && npx vitest run`
+- **Run**: `cd apps/app && bunx vitest run`
 
 ## Required Test Pattern
 
@@ -27,4 +27,4 @@ Use `setMockPermissions`, `ADMIN_PERMISSIONS`, `AUDITOR_PERMISSIONS` from test u
 2. Check for corresponding `.test.tsx` files
 3. Write missing tests following the pattern above
 4. Fix any failing tests
-5. Run: `cd apps/app && npx vitest run`
+5. Run: `cd apps/app && bunx vitest run`
diff --git a/.claude/skills/data/SKILL.md b/.claude/skills/data/SKILL.md
index a670937c2d..9acffa3874 100644
--- a/.claude/skills/data/SKILL.md
+++ b/.claude/skills/data/SKILL.md
@@ -55,7 +55,12 @@ export function useTasks({ organizationId, initialData }: UseTasksOptions) {
     mutate(); // Revalidate
   };
 
-  return { tasks: data ?? [], createTask, mutate };
+  const updateTask = async ({ taskId, input }: { taskId: string; input: UpdateTaskInput }) => {
+    await apiClient.put(`/v1/tasks/${taskId}`, input, organizationId);
+    mutate(); // Revalidate
+  };
+
+  return { tasks: data ?? [], createTask, updateTask, mutate };
 }
 ```
 
diff --git a/.claude/skills/forms/SKILL.md b/.claude/skills/forms/SKILL.md
index bcb8beafa8..fd481da527 100644
--- a/.claude/skills/forms/SKILL.md
+++ b/.claude/skills/forms/SKILL.md
@@ -53,7 +53,7 @@ function MyForm() {
 ## Zod Schema Patterns
 
 ```tsx
-const schema = z.object({
+const profileSchema = z.object({
   // Strings
   name: z.string().min(1, 'Required'),
   email: z.string().email(),
@@ -71,7 +71,7 @@ const schema = z.object({
 });
 
 // Cross-field validation
-const schema = z.object({
+const passwordSchema = z.object({
   password: z.string().min(8),
   confirmPassword: z.string(),
 }).refine(d => d.password === d.confirmPassword, {
diff --git a/.claude/skills/infra/SKILL.md b/.claude/skills/infra/SKILL.md
index bf073598f8..70323555da 100644
--- a/.claude/skills/infra/SKILL.md
+++ b/.claude/skills/infra/SKILL.md
@@ -30,7 +30,7 @@ comp/
 │   └── portal/          # Next.js portal
 ├── packages/
 │   ├── db/              # Prisma (@trycompai/db)
-│   ├── ui/              # UI components (@trycompai/ui)
+│   ├── ui/              # Legacy UI (@trycompai/ui); prefer @trycompai/design-system
 │   └── ...
 ├── turbo.json
 └── package.json
diff --git a/.claude/skills/new-feature-setup/SKILL.md b/.claude/skills/new-feature-setup/SKILL.md
index 79f281de21..7ac3e75dc3 100644
--- a/.claude/skills/new-feature-setup/SKILL.md
+++ b/.claude/skills/new-feature-setup/SKILL.md
@@ -69,7 +69,7 @@ Standard repo conventions apply (see `CLAUDE.md`). Highlights:
 - Brainstorm before building new UX (`superpowers:brainstorming`)
 - Plans + subagent-driven execution for multi-step work
 - Run `audit-design-system` after any frontend component edit
-- Always run typecheck before declaring a change done (`npx turbo run typecheck --filter=<pkg>`)
+- Always run typecheck before declaring a change done (`bunx turbo run typecheck --filter=<pkg>`)
 
 ### 5. When done, clean up
 
diff --git a/.claude/skills/prisma/SKILL.md b/.claude/skills/prisma/SKILL.md
index effc4003a0..39e0d85c19 100644
--- a/.claude/skills/prisma/SKILL.md
+++ b/.claude/skills/prisma/SKILL.md
@@ -54,6 +54,7 @@ cd packages/db && bunx prisma migrate dev --name add_user_role
 # 3. Regenerate types in ALL apps that use the db
 bun run -F apps/app db:generate
 bun run -F apps/api db:generate
+bun run -F apps/portal db:generate
 ```
 
 ### ❌ Never Do This
diff --git a/.claude/skills/production-readiness/SKILL.md b/.claude/skills/production-readiness/SKILL.md
index 0300513a9e..1a377c0b45 100644
--- a/.claude/skills/production-readiness/SKILL.md
+++ b/.claude/skills/production-readiness/SKILL.md
@@ -14,8 +14,8 @@ Use parallel subagents to run all four audits simultaneously:
 
 Then run full monorepo verification:
 ```bash
-npx turbo run typecheck --filter=@trycompai/api --filter=@trycompai/app
-cd apps/app && npx vitest run
+bunx turbo run typecheck --filter=@trycompai/api --filter=@trycompai/app
+cd apps/app && bunx vitest run
 ```
 
 Output a Production Readiness Report summarizing all fixes applied and build status.
diff --git a/.claude/skills/prompt-engineering/SKILL.md b/.claude/skills/prompt-engineering/SKILL.md
index 46d7c6b58c..cea633b7d8 100644
--- a/.claude/skills/prompt-engineering/SKILL.md
+++ b/.claude/skills/prompt-engineering/SKILL.md
@@ -36,7 +36,7 @@ Prompt engineering is preferred because:
 
 ---
 
-## The 8 Core Techniques
+## The 6 Core Techniques
 
 ### 1. Be Clear and Direct
 
diff --git a/.claude/skills/trigger-advanced-tasks/SKILL.md b/.claude/skills/trigger-advanced-tasks/SKILL.md
index 2b18faabf5..e5f5471ad5 100644
--- a/.claude/skills/trigger-advanced-tasks/SKILL.md
+++ b/.claude/skills/trigger-advanced-tasks/SKILL.md
@@ -42,7 +42,7 @@ for await (const run of runs.subscribeToRunsWithTag('user_123')) {
 **Tag Best Practices:**
 
 - Use prefixes: `user_123`, `org_abc`, `video:456`
-- Max 10 tags per run, 1-64 characters each
+- Max 10 tags per run, 1-128 characters each
 - Tags don't propagate to child tasks automatically
 
 ## Concurrency & Queues
@@ -405,7 +405,7 @@ export const tracedTask = task({
 ## Usage Monitoring
 
 ```ts
-import { task, usage } from '@trigger.dev/sdk';
+import { logger, task, usage } from '@trigger.dev/sdk';
 
 export const monitoredTask = task({
   id: 'monitored-task',
diff --git a/.claude/skills/trigger-basic/SKILL.md b/.claude/skills/trigger-basic/SKILL.md
index 3efd8127fc..6be5d8f536 100644
--- a/.claude/skills/trigger-basic/SKILL.md
+++ b/.claude/skills/trigger-basic/SKILL.md
@@ -156,8 +156,8 @@ export const taskWithWaits = task({
     await wait.for({ hours: 1 });
     await wait.for({ days: 1 });
 
-    // Wait until specific date
-    await wait.until({ date: new Date("2024-12-25") });
+    // Wait until a future date
+    await wait.until({ date: new Date(Date.now() + 24 * 60 * 60 * 1000) });
 
     // Wait for token (from external system)
     await wait.forToken({
diff --git a/.cursor/rules/data.mdc b/.cursor/rules/data.mdc
index a37dc49fce..d93d7407b6 100644
--- a/.cursor/rules/data.mdc
+++ b/.cursor/rules/data.mdc
@@ -52,7 +52,12 @@ export function useTasks({ organizationId, initialData }: UseTasksOptions) {
     mutate(); // Revalidate
   };
 
-  return { tasks: data ?? [], createTask, mutate };
+  const updateTask = async ({ taskId, input }: { taskId: string; input: UpdateTaskInput }) => {
+    await apiClient.put(`/v1/tasks/${taskId}`, input, organizationId);
+    mutate(); // Revalidate
+  };
+
+  return { tasks: data ?? [], createTask, updateTask, mutate };
 }
 ```
 
diff --git a/.cursor/rules/forms.mdc b/.cursor/rules/forms.mdc
index 0d0551fea0..57df237271 100644
--- a/.cursor/rules/forms.mdc
+++ b/.cursor/rules/forms.mdc
@@ -50,7 +50,7 @@ function MyForm() {
 ## Zod Schema Patterns
 
 ```tsx
-const schema = z.object({
+const profileSchema = z.object({
   // Strings
   name: z.string().min(1, 'Required'),
   email: z.string().email(),
@@ -68,7 +68,7 @@ const schema = z.object({
 });
 
 // Cross-field validation
-const schema = z.object({
+const passwordSchema = z.object({
   password: z.string().min(8),
   confirmPassword: z.string(),
 }).refine(d => d.password === d.confirmPassword, {
diff --git a/.cursor/rules/infra.mdc b/.cursor/rules/infra.mdc
index e6d9e0fefd..ba9fcc518c 100644
--- a/.cursor/rules/infra.mdc
+++ b/.cursor/rules/infra.mdc
@@ -27,7 +27,7 @@ comp/
 │   └── portal/          # Next.js portal
 ├── packages/
 │   ├── db/              # Prisma (@trycompai/db)
-│   ├── ui/              # UI components (@trycompai/ui)
+│   ├── ui/              # Legacy UI (@trycompai/ui); prefer @trycompai/design-system
 │   └── ...
 ├── turbo.json
 └── package.json
diff --git a/.cursor/rules/prisma.mdc b/.cursor/rules/prisma.mdc
index 4f490eed12..1e1ff634c5 100644
--- a/.cursor/rules/prisma.mdc
+++ b/.cursor/rules/prisma.mdc
@@ -51,6 +51,7 @@ cd packages/db && bunx prisma migrate dev --name add_user_role
 # 3. Regenerate types in ALL apps that use the db
 bun run -F apps/app db:generate
 bun run -F apps/api db:generate
+bun run -F apps/portal db:generate
 ```
 
 ### ❌ Never Do This
diff --git a/.cursor/rules/prompt-engineering.mdc b/.cursor/rules/prompt-engineering.mdc
index 59fd25f840..0ce75820b2 100644
--- a/.cursor/rules/prompt-engineering.mdc
+++ b/.cursor/rules/prompt-engineering.mdc
@@ -33,7 +33,7 @@ Prompt engineering is preferred because:
 
 ---
 
-## The 8 Core Techniques
+## The 6 Core Techniques
 
 ### 1. Be Clear and Direct
 
diff --git a/.cursor/rules/trigger.advanced-tasks.mdc b/.cursor/rules/trigger.advanced-tasks.mdc
index 910871ff6f..acce06d7ff 100644
--- a/.cursor/rules/trigger.advanced-tasks.mdc
+++ b/.cursor/rules/trigger.advanced-tasks.mdc
@@ -39,7 +39,7 @@ for await (const run of runs.subscribeToRunsWithTag('user_123')) {
 **Tag Best Practices:**
 
 - Use prefixes: `user_123`, `org_abc`, `video:456`
-- Max 10 tags per run, 1-64 characters each
+- Max 10 tags per run, 1-128 characters each
 - Tags don't propagate to child tasks automatically
 
 ## Concurrency & Queues
@@ -402,7 +402,7 @@ export const tracedTask = task({
 ## Usage Monitoring
 
 ```ts
-import { task, usage } from '@trigger.dev/sdk';
+import { logger, task, usage } from '@trigger.dev/sdk';
 
 export const monitoredTask = task({
   id: 'monitored-task',
diff --git a/.cursor/rules/trigger.basic.mdc b/.cursor/rules/trigger.basic.mdc
index 3d96e66577..bccdf0fe3c 100644
--- a/.cursor/rules/trigger.basic.mdc
+++ b/.cursor/rules/trigger.basic.mdc
@@ -152,8 +152,8 @@ export const taskWithWaits = task({
     await wait.for({ hours: 1 });
     await wait.for({ days: 1 });
 
-    // Wait until specific date
-    await wait.until({ date: new Date("2024-12-25") });
+    // Wait until a future date
+    await wait.until({ date: new Date(Date.now() + 24 * 60 * 60 * 1000) });
 
     // Wait for token (from external system)
     await wait.forToken({
diff --git a/.cursor/rules/trigger.realtime.mdc b/.cursor/rules/trigger.realtime.mdc
index b1e94fd722..aff95ec66a 100644
--- a/.cursor/rules/trigger.realtime.mdc
+++ b/.cursor/rules/trigger.realtime.mdc
@@ -119,7 +119,7 @@ for await (const part of runs.subscribeToRun(runId).withStreams<STREAMS>()) {
 ### Installation
 
 ```bash
-npm add @trigger.dev/react-hooks
+bun add @trigger.dev/react-hooks
 ```
 
 ### Triggering Tasks
diff --git a/AGENTS.md b/AGENTS.md
index cfecc4842d..b22fd7b139 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,9 +4,9 @@
 
 - **Package manager**: `bun` (never npm/yarn/pnpm)
 - **Build**: `bun run build` (uses turbo). Filter: `bun run --filter '@trycompai/app' build`
-- **Typecheck**: `bun run typecheck` or `npx turbo run typecheck --filter=@trycompai/api`
-- **Tests (app)**: `cd apps/app && npx vitest run`
-- **Tests (api)**: `cd apps/api && npx jest src/<module> --passWithNoTests`
+- **Typecheck**: `bun run typecheck` or `bunx turbo run typecheck --filter=@trycompai/api`
+- **Tests (app)**: `cd apps/app && bunx vitest run`
+- **Tests (api)**: `cd apps/api && bunx jest src/<module> --passWithNoTests`
 - **Lint**: `bun run lint`
 
 ## Code Style
@@ -129,7 +129,7 @@ Every customer-facing API endpoint MUST have:
 - **App tests**: Vitest + @testing-library/react (jsdom environment)
 - **API tests**: Jest with NestJS testing utilities
 - **Permission tests**: Test admin (write) and read-only user scenarios
-- **Run from package dir**: `cd apps/app && npx vitest run` or `cd apps/api && npx jest`
+- **Run from package dir**: `cd apps/app && bunx vitest run` or `cd apps/api && bunx jest`
 
 ## Database
 

From 65e60ccb227bbc26edc50ad9c89cde09dad48249 Mon Sep 17 00:00:00 2001
From: Tofik Hasanov <annexcies@gmail.com>
Date: Mon, 27 Apr 2026 10:21:16 -0400
Subject: [PATCH 37/40] fix(gws): coerce target_org_units to array in
 check-user-filter

The target_org_units variable (multi-select) can be stored as a string
when a single value is saved. The code assumed it was always an array,
causing .join() and .some() to crash with 'join is not a function'.

Coerce string values to a single-element array in parseGoogleWorkspaceCheckUserFilter.

Fixes: Snoonu customer GWS 2FA check failing with 'userFilterConfig.targetOrgUnits.join is not a function'
---
 .../__tests__/check-user-filter.test.ts           | 15 +++++++++++++++
 .../google-workspace/check-user-filter.ts         |  6 +++++-
 2 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/packages/integration-platform/src/manifests/google-workspace/__tests__/check-user-filter.test.ts b/packages/integration-platform/src/manifests/google-workspace/__tests__/check-user-filter.test.ts
index d32a462d52..772454e89a 100644
--- a/packages/integration-platform/src/manifests/google-workspace/__tests__/check-user-filter.test.ts
+++ b/packages/integration-platform/src/manifests/google-workspace/__tests__/check-user-filter.test.ts
@@ -36,6 +36,21 @@ describe('parseGoogleWorkspaceCheckUserFilter', () => {
     expect(config.userFilterMode).toBe('exclude');
     expect(config.includeSuspended).toBe(false);
   });
+
+  it('coerces a string target_org_units into an array', () => {
+    const config = parseGoogleWorkspaceCheckUserFilter({
+      target_org_units: '/Staff' as unknown as string[],
+      include_suspended: 'false',
+    });
+    expect(config.targetOrgUnits).toEqual(['/Staff']);
+  });
+
+  it('returns undefined for missing target_org_units', () => {
+    const config = parseGoogleWorkspaceCheckUserFilter({
+      include_suspended: 'false',
+    });
+    expect(config.targetOrgUnits).toBeUndefined();
+  });
 });
 
 describe('shouldIncludeGoogleWorkspaceUserForCheck', () => {
diff --git a/packages/integration-platform/src/manifests/google-workspace/check-user-filter.ts b/packages/integration-platform/src/manifests/google-workspace/check-user-filter.ts
index 04446131d5..09837c877a 100644
--- a/packages/integration-platform/src/manifests/google-workspace/check-user-filter.ts
+++ b/packages/integration-platform/src/manifests/google-workspace/check-user-filter.ts
@@ -21,7 +21,11 @@ export function parseGoogleWorkspaceCheckUserFilter(
   variables: CheckVariableValues,
 ): GoogleWorkspaceCheckUserFilterConfig {
   return {
-    targetOrgUnits: variables.target_org_units as string[] | undefined,
+    targetOrgUnits: Array.isArray(variables.target_org_units)
+      ? variables.target_org_units
+      : typeof variables.target_org_units === 'string'
+        ? [variables.target_org_units]
+        : undefined,
     excludedTerms: parseSyncFilterTerms(
       variables.sync_excluded_emails ?? variables.excluded_emails,
     ),

From 9463c5a47f60ecf2e2f47b5679c9c88124ff8783 Mon Sep 17 00:00:00 2001
From: Tofik Hasanov <annexcies@gmail.com>
Date: Mon, 27 Apr 2026 11:49:23 -0400
Subject: [PATCH 38/40] feat(integrations): split GitHub sanitized inputs check
 into two automations

Splits the combined "Sanitized Inputs & Code Scanning" GitHub check into
two separate IntegrationChecks so each renders as its own card in the
integrations UI:

- input_validation - "Input Validation" - scans for validation libraries
  in package.json / requirements.txt / pyproject.toml / composer.json
- code_scanning - "Code Scanning" - detects CodeQL default setup,
  custom CodeQL workflows, or third-party SARIF uploaders

Both checks remain mapped to the existing sanitizedInputs task template;
the runner aggregates pass/fail across checks per task, so auto-completion
behavior is preserved (task only completes when both pass for every repo).

Detection logic is unchanged - the JS/PY/PHP package catalogs and the
CodeQL detection flow (default-setup API + workflow file fallback) move
verbatim into the new files. Shared catalogs are extracted to
validation-libraries.ts; CodeQL detection helpers are extracted to
code-scanning-detector.ts to keep each file under the 300-line limit.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../github/checks/code-scanning-detector.ts   | 149 +++++
 .../manifests/github/checks/code-scanning.ts  | 175 ++++++
 .../src/manifests/github/checks/index.ts      |   3 +-
 .../github/checks/input-validation.ts         | 273 +++++++++
 .../github/checks/sanitized-inputs.ts         | 549 ------------------
 .../github/checks/validation-libraries.ts     |  43 ++
 .../src/manifests/github/index.ts             |  11 +-
 7 files changed, 651 insertions(+), 552 deletions(-)
 create mode 100644 packages/integration-platform/src/manifests/github/checks/code-scanning-detector.ts
 create mode 100644 packages/integration-platform/src/manifests/github/checks/code-scanning.ts
 create mode 100644 packages/integration-platform/src/manifests/github/checks/input-validation.ts
 delete mode 100644 packages/integration-platform/src/manifests/github/checks/sanitized-inputs.ts
 create mode 100644 packages/integration-platform/src/manifests/github/checks/validation-libraries.ts

diff --git a/packages/integration-platform/src/manifests/github/checks/code-scanning-detector.ts b/packages/integration-platform/src/manifests/github/checks/code-scanning-detector.ts
new file mode 100644
index 0000000000..3f00984a72
--- /dev/null
+++ b/packages/integration-platform/src/manifests/github/checks/code-scanning-detector.ts
@@ -0,0 +1,149 @@
+/**
+ * Code scanning detection logic for the Code Scanning check.
+ * Determines whether a repo has CodeQL or an equivalent static analysis
+ * tool configured, falling back from the default-setup API to scanning
+ * workflow files for SARIF uploaders.
+ */
+
+import type { CheckContext } from '../../../types';
+import type { GitHubCodeScanningDefaultSetup, GitHubTreeEntry } from '../types';
+
+// Patterns that indicate code scanning is configured in a workflow
+const CODE_SCANNING_PATTERNS = [
+  'github/codeql-action/init',
+  'github/codeql-action/analyze',
+  'github/codeql-action/upload-sarif',
+  'codeql-action/init',
+  'codeql-action/analyze',
+  'codeql-action/upload-sarif',
+  'upload-sarif', // Generic SARIF upload
+];
+
+interface GitHubFileResponse {
+  content: string;
+  encoding: 'base64' | 'utf-8';
+  path: string;
+}
+
+export type CodeScanningStatus =
+  | {
+      status: 'enabled';
+      method: 'default-setup' | 'workflow';
+      languages?: string[];
+      workflow?: string;
+    }
+  | { status: 'not-configured' }
+  | { status: 'permission-denied'; isPrivate: boolean }
+  | { status: 'ghas-required' };
+
+const decodeFile = (file: GitHubFileResponse): string => {
+  if (!file?.content) return '';
+  if (file.encoding === 'base64') {
+    return Buffer.from(file.content, 'base64').toString('utf-8');
+  }
+  return file.content;
+};
+
+const hasCodeScanningInWorkflow = (content: string): boolean => {
+  const lower = content.toLowerCase();
+  return CODE_SCANNING_PATTERNS.some((pattern) => lower.includes(pattern.toLowerCase()));
+};
+
+const findCodeScanningWorkflows = async (
+  ctx: CheckContext,
+  repoName: string,
+  tree: GitHubTreeEntry[],
+): Promise<string[]> => {
+  const workflowFiles = tree.filter(
+    (entry) =>
+      entry.type === 'blob' &&
+      entry.path.startsWith('.github/workflows/') &&
+      (entry.path.endsWith('.yml') || entry.path.endsWith('.yaml')),
+  );
+
+  const codeScanningWorkflows: string[] = [];
+
+  for (const entry of workflowFiles) {
+    try {
+      const file = await ctx.fetch<GitHubFileResponse>(
+        `/repos/${repoName}/contents/${entry.path}`,
+      );
+      const content = decodeFile(file);
+      if (content && hasCodeScanningInWorkflow(content)) {
+        codeScanningWorkflows.push(entry.path);
+      }
+    } catch {
+      // Skip workflows we can't read
+    }
+  }
+
+  return codeScanningWorkflows;
+};
+
+export const getCodeScanningStatus = async ({
+  ctx,
+  repoName,
+  tree,
+  isPrivate,
+  isGhasEnabled,
+}: {
+  ctx: CheckContext;
+  repoName: string;
+  tree: GitHubTreeEntry[];
+  isPrivate: boolean;
+  isGhasEnabled: boolean;
+}): Promise<CodeScanningStatus> => {
+  let apiGot403 = false;
+
+  // First, try the default setup API
+  try {
+    const setup = await ctx.fetch<GitHubCodeScanningDefaultSetup>(
+      `/repos/${repoName}/code-scanning/default-setup`,
+    );
+    if (setup.state === 'configured') {
+      return {
+        status: 'enabled',
+        method: 'default-setup',
+        languages: setup.languages || [],
+      };
+    }
+  } catch (error) {
+    const errorStr = String(error);
+
+    if (errorStr.includes('403') || errorStr.includes('Forbidden')) {
+      // The code-scanning API requires GHAS for private repos, but reading
+      // workflow file contents only requires contents:read. A 403 here does
+      // not mean we can't check for code scanning workflows.
+      ctx.log(
+        `Code scanning API returned 403 for ${repoName} (private: ${isPrivate}, ghas: ${isGhasEnabled}). Falling back to workflow file scanning.`,
+      );
+      apiGot403 = true;
+    } else {
+      ctx.log(`Code scanning default setup not available for ${repoName}: ${errorStr}`);
+    }
+  }
+
+  // Fall back to checking for workflow files with code scanning.
+  // This catches repos using third-party SAST tools (Semgrep, Snyk, Trivy, etc.)
+  // that upload SARIF results via github/codeql-action/upload-sarif.
+  const codeScanningWorkflows = await findCodeScanningWorkflows(ctx, repoName, tree);
+  if (codeScanningWorkflows.length > 0) {
+    return {
+      status: 'enabled',
+      method: 'workflow',
+      workflow: codeScanningWorkflows[0],
+    };
+  }
+
+  if (apiGot403) {
+    if (isPrivate) {
+      if (isGhasEnabled) {
+        return { status: 'permission-denied', isPrivate };
+      }
+      return { status: 'ghas-required' };
+    }
+    return { status: 'permission-denied', isPrivate };
+  }
+
+  return { status: 'not-configured' };
+};
diff --git a/packages/integration-platform/src/manifests/github/checks/code-scanning.ts b/packages/integration-platform/src/manifests/github/checks/code-scanning.ts
new file mode 100644
index 0000000000..272204fbda
--- /dev/null
+++ b/packages/integration-platform/src/manifests/github/checks/code-scanning.ts
@@ -0,0 +1,175 @@
+/**
+ * Code Scanning Check
+ *
+ * Verifies repositories have automated static analysis configured. Detects:
+ * - GitHub CodeQL default setup
+ * - Custom CodeQL workflow files (.github/workflows/*.yml with codeql-action)
+ * - Third-party SARIF uploaders (Semgrep, Snyk, Trivy, etc.)
+ */
+
+import { TASK_TEMPLATES } from '../../../task-mappings';
+import type { IntegrationCheck } from '../../../types';
+import type { GitHubRepo, GitHubTreeEntry, GitHubTreeResponse } from '../types';
+import { parseRepoBranch, targetReposVariable } from '../variables';
+import { getCodeScanningStatus } from './code-scanning-detector';
+
+export const codeScanningCheck: IntegrationCheck = {
+  id: 'code_scanning',
+  name: 'Code Scanning',
+  description:
+    'Verifies repositories have GitHub CodeQL or an equivalent static analysis tool configured. Detects default-setup CodeQL, custom CodeQL workflows, and third-party SARIF uploaders.',
+  service: 'code-security',
+  taskMapping: TASK_TEMPLATES.sanitizedInputs,
+  defaultSeverity: 'medium',
+  variables: [targetReposVariable],
+
+  run: async (ctx) => {
+    const targetReposRaw = (ctx.variables.target_repos as string[] | undefined) ?? [];
+    const targetRepos = targetReposRaw.map((v) => parseRepoBranch(v).repo);
+
+    if (targetRepos.length === 0) {
+      ctx.fail({
+        title: 'No repositories selected',
+        description:
+          'Select at least one repository to monitor in the integration settings so we can verify code scanning.',
+        resourceType: 'integration',
+        resourceId: 'github',
+        severity: 'low',
+        remediation: 'Open the integration settings and choose repositories to monitor.',
+      });
+      return;
+    }
+
+    const fetchRepo = async (fullName: string): Promise<GitHubRepo | null> => {
+      try {
+        return await ctx.fetch<GitHubRepo>(`/repos/${fullName}`);
+      } catch (error) {
+        ctx.warn(`Failed to fetch repo ${fullName}: ${String(error)}`);
+        return null;
+      }
+    };
+
+    const fetchRepoTree = async (repoName: string, branch: string): Promise<GitHubTreeEntry[]> => {
+      try {
+        const tree = await ctx.fetch<GitHubTreeResponse>(
+          `/repos/${repoName}/git/trees/${branch}?recursive=1`,
+        );
+        if (tree.truncated) {
+          ctx.warn(`Repository ${repoName} has too many files, tree was truncated`);
+        }
+        return tree.tree;
+      } catch (error) {
+        ctx.warn(`Failed to fetch tree for ${repoName}: ${String(error)}`);
+        return [];
+      }
+    };
+
+    for (const repoName of targetRepos) {
+      const repo = await fetchRepo(repoName);
+      if (!repo) continue;
+
+      const tree = await fetchRepoTree(repo.full_name, repo.default_branch);
+      const isGhasEnabled = repo.security_and_analysis?.advanced_security?.status === 'enabled';
+
+      const codeScanningStatus = await getCodeScanningStatus({
+        ctx,
+        repoName: repo.full_name,
+        tree,
+        isPrivate: repo.private,
+        isGhasEnabled,
+      });
+
+      switch (codeScanningStatus.status) {
+        case 'enabled': {
+          const methodDescription =
+            codeScanningStatus.method === 'default-setup'
+              ? 'GitHub CodeQL default setup is enabled.'
+              : `Code scanning configured via workflow: ${codeScanningStatus.workflow}`;
+
+          ctx.pass({
+            title: `CodeQL scanning configured for ${repo.name}`,
+            description: methodDescription,
+            resourceType: 'repository',
+            resourceId: repo.full_name,
+            evidence: {
+              [repo.full_name]: {
+                code_scanning: {
+                  status: 'enabled',
+                  method: codeScanningStatus.method,
+                  ...(codeScanningStatus.languages && { languages: codeScanningStatus.languages }),
+                  ...(codeScanningStatus.workflow && { workflow: codeScanningStatus.workflow }),
+                  checked_at: new Date().toISOString(),
+                },
+              },
+            },
+          });
+          break;
+        }
+
+        case 'ghas-required':
+          ctx.fail({
+            title: `Code scanning requires GitHub Advanced Security for ${repo.name}`,
+            description:
+              'This is a private repository. GitHub Advanced Security (GHAS) must be enabled before CodeQL can be configured. GHAS is a paid feature for private repositories.',
+            resourceType: 'repository',
+            resourceId: repo.full_name,
+            severity: 'medium',
+            remediation:
+              'Enable GitHub Advanced Security in the repository settings (Settings → Code security and analysis → GitHub Advanced Security), then enable CodeQL.',
+            evidence: {
+              [repo.full_name]: {
+                code_scanning: {
+                  status: 'ghas_required',
+                  checked_at: new Date().toISOString(),
+                },
+              },
+            },
+          });
+          break;
+
+        case 'permission-denied':
+          ctx.fail({
+            title: `Cannot access code scanning configuration for ${repo.name}`,
+            description:
+              'The GitHub integration does not have permission to read code scanning configuration. This may be due to missing permissions or organization policies.',
+            resourceType: 'repository',
+            resourceId: repo.full_name,
+            severity: 'medium',
+            remediation:
+              'Ensure the GitHub App has "Code scanning alerts: Read" permission. If this is an organization repository, check that organization policies allow access.',
+            evidence: {
+              [repo.full_name]: {
+                code_scanning: {
+                  status: 'permission_denied',
+                  checked_at: new Date().toISOString(),
+                },
+              },
+            },
+          });
+          break;
+
+        case 'not-configured':
+        default:
+          ctx.fail({
+            title: `Code scanning not enabled for ${repo.name}`,
+            description:
+              'GitHub CodeQL (or an equivalent static analysis tool) is not configured. Enable it to automatically detect insecure patterns.',
+            resourceType: 'repository',
+            resourceId: repo.full_name,
+            severity: 'medium',
+            remediation:
+              'In the repository Security tab, enable CodeQL default setup (or add a custom workflow) to run on every push.',
+            evidence: {
+              [repo.full_name]: {
+                code_scanning: {
+                  status: 'not_configured',
+                  checked_at: new Date().toISOString(),
+                },
+              },
+            },
+          });
+          break;
+      }
+    }
+  },
+};
diff --git a/packages/integration-platform/src/manifests/github/checks/index.ts b/packages/integration-platform/src/manifests/github/checks/index.ts
index 980cc6fa95..3528e1c459 100644
--- a/packages/integration-platform/src/manifests/github/checks/index.ts
+++ b/packages/integration-platform/src/manifests/github/checks/index.ts
@@ -4,6 +4,7 @@
  */
 
 export { branchProtectionCheck } from './branch-protection';
+export { codeScanningCheck } from './code-scanning';
 export { dependabotCheck } from './dependabot';
-export { sanitizedInputsCheck } from './sanitized-inputs';
+export { inputValidationCheck } from './input-validation';
 export { twoFactorAuthCheck } from './two-factor-auth';
diff --git a/packages/integration-platform/src/manifests/github/checks/input-validation.ts b/packages/integration-platform/src/manifests/github/checks/input-validation.ts
new file mode 100644
index 0000000000..7dcd950d6b
--- /dev/null
+++ b/packages/integration-platform/src/manifests/github/checks/input-validation.ts
@@ -0,0 +1,273 @@
+/**
+ * Input Validation Check
+ *
+ * Verifies repositories use a modern validation/sanitization library.
+ * Supports monorepos by scanning all package.json / requirements.txt /
+ * pyproject.toml / composer.json files in the repository tree.
+ *
+ * Detection covers JS/TS, Python, and PHP ecosystems.
+ */
+
+import { TASK_TEMPLATES } from '../../../task-mappings';
+import type { IntegrationCheck } from '../../../types';
+import type { GitHubRepo, GitHubTreeEntry, GitHubTreeResponse } from '../types';
+import { parseRepoBranch, targetReposVariable } from '../variables';
+import {
+  JS_VALIDATION_PACKAGES,
+  PHP_VALIDATION_PACKAGES,
+  PY_VALIDATION_PACKAGES,
+  VALIDATION_TARGET_FILES,
+} from './validation-libraries';
+
+interface GitHubFileResponse {
+  content: string;
+  encoding: 'base64' | 'utf-8';
+  path: string;
+}
+
+interface ValidationMatch {
+  library: string;
+  file: string;
+}
+
+const decodeFile = (file: GitHubFileResponse): string => {
+  if (!file?.content) return '';
+  if (file.encoding === 'base64') {
+    return Buffer.from(file.content, 'base64').toString('utf-8');
+  }
+  return file.content;
+};
+
+const getFileName = (path: string): string => {
+  const parts = path.split('/');
+  return parts[parts.length - 1] ?? path;
+};
+
+const escapeRegex = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+const checkPackageJson = (content: string, filePath: string): ValidationMatch | null => {
+  try {
+    const pkg = JSON.parse(content);
+    const deps = {
+      ...(pkg.dependencies || {}),
+      ...(pkg.devDependencies || {}),
+    };
+    for (const candidate of JS_VALIDATION_PACKAGES) {
+      if (deps[candidate]) {
+        return { library: candidate, file: filePath };
+      }
+    }
+  } catch {
+    // Invalid JSON, skip
+  }
+  return null;
+};
+
+const checkPythonFile = (
+  content: string,
+  filePath: string,
+  fileName: string,
+): ValidationMatch | null => {
+  // Parse line-by-line so we can strip comments and match package names as
+  // standalone tokens (e.g. don't match "schema" inside "jsonschema" or inside
+  // a prose comment).
+  //
+  // Comment syntax differs between the two Python dependency file formats:
+  //   - pyproject.toml (TOML): `#` starts a comment anywhere outside a string.
+  //     Dependency values are always quoted, so stripping at any `#` is safe
+  //     — the package name in `"name @ url#egg=name"` appears before the URL.
+  //   - requirements.txt (pip): `#` only starts a comment when preceded by
+  //     whitespace (or at line start). This preserves VCS URL fragments like
+  //     `git+https://...#egg=pydantic` used for editable installs.
+  const isTOML = fileName === 'pyproject.toml';
+  const stripCommentRegex = isTOML ? /#.*$/ : /(^|\s)#.*$/;
+  const lines = content.split('\n');
+  for (const rawLine of lines) {
+    const line = rawLine.replace(stripCommentRegex, '').toLowerCase();
+    if (!line.trim()) continue;
+    for (const candidate of PY_VALIDATION_PACKAGES) {
+      const escaped = escapeRegex(candidate.toLowerCase());
+      // Match the package name as a standalone token. Leading context: start
+      // of line or a separator commonly preceding a package name (whitespace,
+      // quote, bracket, comma, semicolon, or `=` for `#egg=name` VCS syntax).
+      // Trailing context: end of line or a separator that can follow a
+      // package name (whitespace, version operator, bracket, quote, comma,
+      // semicolon).
+      const pattern = new RegExp(
+        `(?:^|[\\s"'\\[,;=])${escaped}(?:$|[\\s=<>!~\\[\\]"',;])`,
+      );
+      if (pattern.test(line)) {
+        return { library: candidate, file: filePath };
+      }
+    }
+  }
+  return null;
+};
+
+const checkComposerJson = (content: string, filePath: string): ValidationMatch | null => {
+  try {
+    const pkg = JSON.parse(content);
+    const deps = {
+      ...(pkg.require || {}),
+      ...(pkg['require-dev'] || {}),
+    };
+    for (const candidate of PHP_VALIDATION_PACKAGES) {
+      if (deps[candidate]) {
+        return { library: candidate, file: filePath };
+      }
+    }
+  } catch {
+    // Invalid JSON, skip
+  }
+  return null;
+};
+
+export const inputValidationCheck: IntegrationCheck = {
+  id: 'input_validation',
+  name: 'Input Validation',
+  description:
+    'Verifies repositories use a supported input-validation library (JS/TS, Python, or PHP). Scans entire repository including monorepo subdirectories.',
+  service: 'code-security',
+  taskMapping: TASK_TEMPLATES.sanitizedInputs,
+  defaultSeverity: 'medium',
+  variables: [targetReposVariable],
+
+  run: async (ctx) => {
+    const targetReposRaw = (ctx.variables.target_repos as string[] | undefined) ?? [];
+    // Extract just the repo names (values may be in "owner/repo:branch" format)
+    const targetRepos = targetReposRaw.map((v) => parseRepoBranch(v).repo);
+
+    if (targetRepos.length === 0) {
+      ctx.fail({
+        title: 'No repositories selected',
+        description:
+          'Select at least one repository to monitor in the integration settings so we can verify input validation.',
+        resourceType: 'integration',
+        resourceId: 'github',
+        severity: 'low',
+        remediation: 'Open the integration settings and choose repositories to monitor.',
+      });
+      return;
+    }
+
+    const fetchRepo = async (fullName: string): Promise<GitHubRepo | null> => {
+      try {
+        return await ctx.fetch<GitHubRepo>(`/repos/${fullName}`);
+      } catch (error) {
+        ctx.warn(`Failed to fetch repo ${fullName}: ${String(error)}`);
+        return null;
+      }
+    };
+
+    const fetchRepoTree = async (repoName: string, branch: string): Promise<GitHubTreeEntry[]> => {
+      try {
+        const tree = await ctx.fetch<GitHubTreeResponse>(
+          `/repos/${repoName}/git/trees/${branch}?recursive=1`,
+        );
+        if (tree.truncated) {
+          ctx.warn(`Repository ${repoName} has too many files, tree was truncated`);
+        }
+        return tree.tree;
+      } catch (error) {
+        ctx.warn(`Failed to fetch tree for ${repoName}: ${String(error)}`);
+        return [];
+      }
+    };
+
+    const fetchFile = async (repoName: string, path: string): Promise<string | null> => {
+      try {
+        const file = await ctx.fetch<GitHubFileResponse>(`/repos/${repoName}/contents/${path}`);
+        return decodeFile(file);
+      } catch {
+        return null;
+      }
+    };
+
+    const findValidationLibraries = async (
+      repoName: string,
+      tree: GitHubTreeEntry[],
+    ): Promise<ValidationMatch[]> => {
+      const matches: ValidationMatch[] = [];
+
+      const targetEntries = tree.filter(
+        (entry) => entry.type === 'blob' && VALIDATION_TARGET_FILES.includes(getFileName(entry.path)),
+      );
+
+      for (const entry of targetEntries) {
+        const content = await fetchFile(repoName, entry.path);
+        if (!content) continue;
+
+        const fileName = getFileName(entry.path);
+
+        if (fileName === 'package.json') {
+          const match = checkPackageJson(content, entry.path);
+          if (match) matches.push(match);
+        } else if (fileName === 'requirements.txt' || fileName === 'pyproject.toml') {
+          const match = checkPythonFile(content, entry.path, fileName);
+          if (match) matches.push(match);
+        } else if (fileName === 'composer.json') {
+          const match = checkComposerJson(content, entry.path);
+          if (match) matches.push(match);
+        }
+      }
+
+      return matches;
+    };
+
+    for (const repoName of targetRepos) {
+      const repo = await fetchRepo(repoName);
+      if (!repo) continue;
+
+      const tree = await fetchRepoTree(repo.full_name, repo.default_branch);
+      const validationMatches = await findValidationLibraries(repo.full_name, tree);
+
+      if (validationMatches.length > 0) {
+        ctx.pass({
+          title: `Input validation enabled in ${repo.name}`,
+          description: `Found ${validationMatches.length} location(s) with validation libraries: ${validationMatches.map((m) => `${m.library} (${m.file})`).join(', ')}.`,
+          resourceType: 'repository',
+          resourceId: repo.full_name,
+          evidence: {
+            [repo.full_name]: {
+              validation: {
+                status: 'enabled',
+                matches: validationMatches,
+                checked_at: new Date().toISOString(),
+              },
+            },
+          },
+        });
+      } else {
+        const checkedFiles = tree
+          .filter((e) => e.type === 'blob' && VALIDATION_TARGET_FILES.includes(getFileName(e.path)))
+          .map((e) => e.path);
+
+        const supportedLibraries = [
+          ...JS_VALIDATION_PACKAGES,
+          ...PY_VALIDATION_PACKAGES,
+          ...PHP_VALIDATION_PACKAGES,
+        ].join(', ');
+
+        ctx.fail({
+          title: `No input validation library found in ${repo.name}`,
+          description: `Could not detect a supported validation library in any package.json, requirements.txt, pyproject.toml, or composer.json. Checked for: ${supportedLibraries}. If you use a different library, you can mark this task manually with evidence.`,
+          resourceType: 'repository',
+          resourceId: repo.full_name,
+          severity: 'medium',
+          remediation:
+            'Add a supported input-validation library (e.g. Zod/Yup/Joi/Valibot for JS/TS, Pydantic/Marshmallow for Python, Laravel/Respect-Validation for PHP) to enforce schema validation on inbound data.',
+          evidence: {
+            [repo.full_name]: {
+              validation: {
+                status: 'not_found',
+                checked_files:
+                  checkedFiles.length > 0 ? checkedFiles : ['No dependency files found'],
+                checked_at: new Date().toISOString(),
+              },
+            },
+          },
+        });
+      }
+    }
+  },
+};
diff --git a/packages/integration-platform/src/manifests/github/checks/sanitized-inputs.ts b/packages/integration-platform/src/manifests/github/checks/sanitized-inputs.ts
deleted file mode 100644
index 20364da685..0000000000
--- a/packages/integration-platform/src/manifests/github/checks/sanitized-inputs.ts
+++ /dev/null
@@ -1,549 +0,0 @@
-/**
- * Sanitized Inputs Check
- *
- * Ensures repositories use a modern validation/sanitization library and have
- * automated static analysis (CodeQL) enabled. Supports monorepos by scanning
- * all package.json / requirements.txt / pyproject.toml / composer.json files.
- *
- * Validation-library detection covers JS/TS, Python, and PHP ecosystems.
- *
- * Code scanning detection supports:
- * - GitHub CodeQL default setup
- * - Custom CodeQL workflow files (.github/workflows/*.yml with codeql-action)
- * - Third-party SARIF uploaders
- */
-
-import { TASK_TEMPLATES } from '../../../task-mappings';
-import type { IntegrationCheck } from '../../../types';
-import type {
-  GitHubCodeScanningDefaultSetup,
-  GitHubRepo,
-  GitHubTreeEntry,
-  GitHubTreeResponse,
-} from '../types';
-import { parseRepoBranch, targetReposVariable } from '../variables';
-
-const JS_VALIDATION_PACKAGES = [
-  'zod',
-  'yup',
-  'joi',
-  '@effect/schema',
-  'effect',
-  'valibot',
-  'ajv',
-  'class-validator',
-  'io-ts',
-  'superstruct',
-  'runtypes',
-];
-
-const PY_VALIDATION_PACKAGES = [
-  'pydantic',
-  'marshmallow',
-  'cerberus',
-  'voluptuous',
-  'jsonschema',
-  'schematics',
-  'typeguard',
-];
-
-const PHP_VALIDATION_PACKAGES = [
-  'laravel/framework',
-  'respect/validation',
-  'symfony/validator',
-  'vlucas/valitron',
-];
-
-const TARGET_FILES = [
-  'package.json',
-  'requirements.txt',
-  'pyproject.toml',
-  'composer.json',
-];
-
-// Patterns that indicate code scanning is configured in a workflow
-const CODE_SCANNING_PATTERNS = [
-  'github/codeql-action/init',
-  'github/codeql-action/analyze',
-  'github/codeql-action/upload-sarif',
-  'codeql-action/init',
-  'codeql-action/analyze',
-  'codeql-action/upload-sarif',
-  'upload-sarif', // Generic SARIF upload
-];
-
-interface GitHubFileResponse {
-  content: string;
-  encoding: 'base64' | 'utf-8';
-  path: string;
-}
-
-interface ValidationMatch {
-  library: string;
-  file: string;
-}
-
-type CodeScanningStatus =
-  | {
-      status: 'enabled';
-      method: 'default-setup' | 'workflow';
-      languages?: string[];
-      workflow?: string;
-    }
-  | { status: 'not-configured' }
-  | { status: 'permission-denied'; isPrivate: boolean }
-  | { status: 'ghas-required' };
-
-const decodeFile = (file: GitHubFileResponse): string => {
-  if (!file?.content) return '';
-  if (file.encoding === 'base64') {
-    return Buffer.from(file.content, 'base64').toString('utf-8');
-  }
-  return file.content;
-};
-
-const getFileName = (path: string): string => {
-  const parts = path.split('/');
-  return parts[parts.length - 1] ?? path;
-};
-
-export const sanitizedInputsCheck: IntegrationCheck = {
-  id: 'sanitized_inputs',
-  name: 'Sanitized Inputs & Code Scanning',
-  description:
-    'Verifies repositories use a supported input-validation library (JS/TS, Python, or PHP) and have GitHub CodeQL scanning enabled. Scans entire repository including monorepo subdirectories.',
-  service: 'code-security',
-  taskMapping: TASK_TEMPLATES.sanitizedInputs,
-  defaultSeverity: 'medium',
-  variables: [targetReposVariable],
-
-  run: async (ctx) => {
-    const targetReposRaw = (ctx.variables.target_repos as string[] | undefined) ?? [];
-    // Extract just the repo names (values may be in "owner/repo:branch" format)
-    const targetRepos = targetReposRaw.map((v) => parseRepoBranch(v).repo);
-
-    if (targetRepos.length === 0) {
-      ctx.fail({
-        title: 'No repositories selected',
-        description:
-          'Select at least one repository to monitor in the integration settings so we can verify sanitized inputs.',
-        resourceType: 'integration',
-        resourceId: 'github',
-        severity: 'low',
-        remediation: 'Open the integration settings and choose repositories to monitor.',
-      });
-      return;
-    }
-
-    const fetchRepo = async (fullName: string): Promise<GitHubRepo | null> => {
-      try {
-        return await ctx.fetch<GitHubRepo>(`/repos/${fullName}`);
-      } catch (error) {
-        ctx.warn(`Failed to fetch repo ${fullName}: ${String(error)}`);
-        return null;
-      }
-    };
-
-    const fetchRepoTree = async (repoName: string, branch: string): Promise<GitHubTreeEntry[]> => {
-      try {
-        const tree = await ctx.fetch<GitHubTreeResponse>(
-          `/repos/${repoName}/git/trees/${branch}?recursive=1`,
-        );
-        if (tree.truncated) {
-          ctx.warn(`Repository ${repoName} has too many files, tree was truncated`);
-        }
-        return tree.tree;
-      } catch (error) {
-        ctx.warn(`Failed to fetch tree for ${repoName}: ${String(error)}`);
-        return [];
-      }
-    };
-
-    const fetchFile = async (repoName: string, path: string): Promise<string | null> => {
-      try {
-        const file = await ctx.fetch<GitHubFileResponse>(`/repos/${repoName}/contents/${path}`);
-        return decodeFile(file);
-      } catch {
-        return null;
-      }
-    };
-
-    const checkPackageJson = (content: string, filePath: string): ValidationMatch | null => {
-      try {
-        const pkg = JSON.parse(content);
-        const deps = {
-          ...(pkg.dependencies || {}),
-          ...(pkg.devDependencies || {}),
-        };
-        for (const candidate of JS_VALIDATION_PACKAGES) {
-          if (deps[candidate]) {
-            return { library: candidate, file: filePath };
-          }
-        }
-      } catch {
-        // Invalid JSON, skip
-      }
-      return null;
-    };
-
-    const escapeRegex = (s: string): string =>
-      s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-
-    const checkPythonFile = (
-      content: string,
-      filePath: string,
-      fileName: string,
-    ): ValidationMatch | null => {
-      // Parse line-by-line so we can strip comments and match package names as
-      // standalone tokens (e.g. don't match "schema" inside "jsonschema" or inside
-      // a prose comment).
-      //
-      // Comment syntax differs between the two Python dependency file formats:
-      //   - pyproject.toml (TOML): `#` starts a comment anywhere outside a string.
-      //     Dependency values are always quoted, so stripping at any `#` is safe
-      //     — the package name in `"name @ url#egg=name"` appears before the URL.
-      //   - requirements.txt (pip): `#` only starts a comment when preceded by
-      //     whitespace (or at line start). This preserves VCS URL fragments like
-      //     `git+https://...#egg=pydantic` used for editable installs.
-      const isTOML = fileName === 'pyproject.toml';
-      const stripCommentRegex = isTOML ? /#.*$/ : /(^|\s)#.*$/;
-      const lines = content.split('\n');
-      for (const rawLine of lines) {
-        const line = rawLine.replace(stripCommentRegex, '').toLowerCase();
-        if (!line.trim()) continue;
-        for (const candidate of PY_VALIDATION_PACKAGES) {
-          const escaped = escapeRegex(candidate.toLowerCase());
-          // Match the package name as a standalone token. Leading context: start
-          // of line or a separator commonly preceding a package name (whitespace,
-          // quote, bracket, comma, semicolon, or `=` for `#egg=name` VCS syntax).
-          // Trailing context: end of line or a separator that can follow a
-          // package name (whitespace, version operator, bracket, quote, comma,
-          // semicolon).
-          const pattern = new RegExp(
-            `(?:^|[\\s"'\\[,;=])${escaped}(?:$|[\\s=<>!~\\[\\]"',;])`,
-          );
-          if (pattern.test(line)) {
-            return { library: candidate, file: filePath };
-          }
-        }
-      }
-      return null;
-    };
-
-    const checkComposerJson = (content: string, filePath: string): ValidationMatch | null => {
-      try {
-        const pkg = JSON.parse(content);
-        const deps = {
-          ...(pkg.require || {}),
-          ...(pkg['require-dev'] || {}),
-        };
-        for (const candidate of PHP_VALIDATION_PACKAGES) {
-          if (deps[candidate]) {
-            return { library: candidate, file: filePath };
-          }
-        }
-      } catch {
-        // Invalid JSON, skip
-      }
-      return null;
-    };
-
-    const findValidationLibraries = async (
-      repoName: string,
-      tree: GitHubTreeEntry[],
-    ): Promise<ValidationMatch[]> => {
-      const matches: ValidationMatch[] = [];
-
-      // Find all target files in the tree
-      const targetEntries = tree.filter(
-        (entry) => entry.type === 'blob' && TARGET_FILES.includes(getFileName(entry.path)),
-      );
-
-      for (const entry of targetEntries) {
-        const content = await fetchFile(repoName, entry.path);
-        if (!content) continue;
-
-        const fileName = getFileName(entry.path);
-
-        if (fileName === 'package.json') {
-          const match = checkPackageJson(content, entry.path);
-          if (match) matches.push(match);
-        } else if (fileName === 'requirements.txt' || fileName === 'pyproject.toml') {
-          const match = checkPythonFile(content, entry.path, fileName);
-          if (match) matches.push(match);
-        } else if (fileName === 'composer.json') {
-          const match = checkComposerJson(content, entry.path);
-          if (match) matches.push(match);
-        }
-      }
-
-      return matches;
-    };
-
-    /**
-     * Check if a workflow file contains code scanning configuration
-     */
-    const hasCodeScanningInWorkflow = (content: string): boolean => {
-      const lower = content.toLowerCase();
-      return CODE_SCANNING_PATTERNS.some((pattern) => lower.includes(pattern.toLowerCase()));
-    };
-
-    /**
-     * Find workflow files that configure code scanning
-     */
-    const findCodeScanningWorkflows = async (
-      repoName: string,
-      tree: GitHubTreeEntry[],
-    ): Promise<string[]> => {
-      const workflowFiles = tree.filter(
-        (entry) =>
-          entry.type === 'blob' &&
-          entry.path.startsWith('.github/workflows/') &&
-          (entry.path.endsWith('.yml') || entry.path.endsWith('.yaml')),
-      );
-
-      const codeScanningWorkflows: string[] = [];
-
-      for (const entry of workflowFiles) {
-        const content = await fetchFile(repoName, entry.path);
-        if (content && hasCodeScanningInWorkflow(content)) {
-          codeScanningWorkflows.push(entry.path);
-        }
-      }
-
-      return codeScanningWorkflows;
-    };
-
-    /**
-     * Check code scanning status using multiple detection methods
-     */
-    const getCodeScanningStatus = async ({
-      repoName,
-      tree,
-      isPrivate,
-      isGhasEnabled,
-    }: {
-      repoName: string;
-      tree: GitHubTreeEntry[];
-      isPrivate: boolean;
-      isGhasEnabled: boolean;
-    }): Promise<CodeScanningStatus> => {
-      let apiGot403 = false;
-
-      // First, try the default setup API
-      try {
-        const setup = await ctx.fetch<GitHubCodeScanningDefaultSetup>(
-          `/repos/${repoName}/code-scanning/default-setup`,
-        );
-        if (setup.state === 'configured') {
-          return {
-            status: 'enabled',
-            method: 'default-setup',
-            languages: setup.languages || [],
-          };
-        }
-      } catch (error) {
-        const errorStr = String(error);
-
-        if (errorStr.includes('403') || errorStr.includes('Forbidden')) {
-          // The code-scanning API requires GHAS for private repos, but reading
-          // workflow file contents only requires contents:read. A 403 here does
-          // not mean we can't check for code scanning workflows.
-          ctx.log(
-            `Code scanning API returned 403 for ${repoName} (private: ${isPrivate}, ghas: ${isGhasEnabled}). Falling back to workflow file scanning.`,
-          );
-          apiGot403 = true;
-        } else {
-          // Other errors - API might not be available, continue to check workflows
-          ctx.log(`Code scanning default setup not available for ${repoName}: ${errorStr}`);
-        }
-      }
-
-      // Fall back to checking for workflow files with code scanning
-      // This catches repos using third-party SAST tools (Semgrep, Snyk, Trivy, etc.)
-      // that upload SARIF results via github/codeql-action/upload-sarif
-      const codeScanningWorkflows = await findCodeScanningWorkflows(repoName, tree);
-      if (codeScanningWorkflows.length > 0) {
-        return {
-          status: 'enabled',
-          method: 'workflow',
-          workflow: codeScanningWorkflows[0],
-        };
-      }
-
-      // No workflows found either - determine appropriate failure status
-      if (apiGot403) {
-        if (isPrivate) {
-          if (isGhasEnabled) {
-            return { status: 'permission-denied', isPrivate };
-          }
-          return { status: 'ghas-required' };
-        }
-        return { status: 'permission-denied', isPrivate };
-      }
-
-      return { status: 'not-configured' };
-    };
-
-    for (const repoName of targetRepos) {
-      const repo = await fetchRepo(repoName);
-      if (!repo) continue;
-
-      // Fetch the full tree to find all package.json/requirements.txt files
-      const tree = await fetchRepoTree(repo.full_name, repo.default_branch);
-      const validationMatches = await findValidationLibraries(repo.full_name, tree);
-
-      // Check if GHAS is enabled (for private repos, this helps distinguish permission issues)
-      const isGhasEnabled = repo.security_and_analysis?.advanced_security?.status === 'enabled';
-
-      const codeScanningStatus = await getCodeScanningStatus({
-        repoName: repo.full_name,
-        tree,
-        isPrivate: repo.private,
-        isGhasEnabled,
-      });
-
-      // Report input validation results
-      if (validationMatches.length > 0) {
-        ctx.pass({
-          title: `Input validation enabled in ${repo.name}`,
-          description: `Found ${validationMatches.length} location(s) with validation libraries: ${validationMatches.map((m) => `${m.library} (${m.file})`).join(', ')}.`,
-          resourceType: 'repository',
-          resourceId: repo.full_name,
-          evidence: {
-            [repo.full_name]: {
-              validation: {
-                status: 'enabled',
-                matches: validationMatches,
-                checked_at: new Date().toISOString(),
-              },
-            },
-          },
-        });
-      } else {
-        const checkedFiles = tree
-          .filter((e) => e.type === 'blob' && TARGET_FILES.includes(getFileName(e.path)))
-          .map((e) => e.path);
-
-        const supportedLibraries = [
-          ...JS_VALIDATION_PACKAGES,
-          ...PY_VALIDATION_PACKAGES,
-          ...PHP_VALIDATION_PACKAGES,
-        ].join(', ');
-
-        ctx.fail({
-          title: `No input validation library found in ${repo.name}`,
-          description: `Could not detect a supported validation library in any package.json, requirements.txt, pyproject.toml, or composer.json. Checked for: ${supportedLibraries}. If you use a different library, you can mark this task manually with evidence.`,
-          resourceType: 'repository',
-          resourceId: repo.full_name,
-          severity: 'medium',
-          remediation:
-            'Add a supported input-validation library (e.g. Zod/Yup/Joi/Valibot for JS/TS, Pydantic/Marshmallow for Python, Laravel/Respect-Validation for PHP) to enforce schema validation on inbound data.',
-          evidence: {
-            [repo.full_name]: {
-              validation: {
-                status: 'not_found',
-                checked_files:
-                  checkedFiles.length > 0 ? checkedFiles : ['No dependency files found'],
-                checked_at: new Date().toISOString(),
-              },
-            },
-          },
-        });
-      }
-
-      // Report code scanning results based on status
-      switch (codeScanningStatus.status) {
-        case 'enabled': {
-          const methodDescription =
-            codeScanningStatus.method === 'default-setup'
-              ? 'GitHub CodeQL default setup is enabled.'
-              : `Code scanning configured via workflow: ${codeScanningStatus.workflow}`;
-
-          ctx.pass({
-            title: `CodeQL scanning configured for ${repo.name}`,
-            description: methodDescription,
-            resourceType: 'repository',
-            resourceId: repo.full_name,
-            evidence: {
-              [repo.full_name]: {
-                code_scanning: {
-                  status: 'enabled',
-                  method: codeScanningStatus.method,
-                  ...(codeScanningStatus.languages && { languages: codeScanningStatus.languages }),
-                  ...(codeScanningStatus.workflow && { workflow: codeScanningStatus.workflow }),
-                  checked_at: new Date().toISOString(),
-                },
-              },
-            },
-          });
-          break;
-        }
-
-        case 'ghas-required':
-          ctx.fail({
-            title: `Code scanning requires GitHub Advanced Security for ${repo.name}`,
-            description:
-              'This is a private repository. GitHub Advanced Security (GHAS) must be enabled before CodeQL can be configured. GHAS is a paid feature for private repositories.',
-            resourceType: 'repository',
-            resourceId: repo.full_name,
-            severity: 'medium',
-            remediation:
-              'Enable GitHub Advanced Security in the repository settings (Settings → Code security and analysis → GitHub Advanced Security), then enable CodeQL.',
-            evidence: {
-              [repo.full_name]: {
-                code_scanning: {
-                  status: 'ghas_required',
-                  checked_at: new Date().toISOString(),
-                },
-              },
-            },
-          });
-          break;
-
-        case 'permission-denied':
-          ctx.fail({
-            title: `Cannot access code scanning configuration for ${repo.name}`,
-            description:
-              'The GitHub integration does not have permission to read code scanning configuration. This may be due to missing permissions or organization policies.',
-            resourceType: 'repository',
-            resourceId: repo.full_name,
-            severity: 'medium',
-            remediation:
-              'Ensure the GitHub App has "Code scanning alerts: Read" permission. If this is an organization repository, check that organization policies allow access.',
-            evidence: {
-              [repo.full_name]: {
-                code_scanning: {
-                  status: 'permission_denied',
-                  checked_at: new Date().toISOString(),
-                },
-              },
-            },
-          });
-          break;
-
-        case 'not-configured':
-        default:
-          ctx.fail({
-            title: `Code scanning not enabled for ${repo.name}`,
-            description:
-              'GitHub CodeQL (or an equivalent static analysis tool) is not configured. Enable it to automatically detect insecure patterns.',
-            resourceType: 'repository',
-            resourceId: repo.full_name,
-            severity: 'medium',
-            remediation:
-              'In the repository Security tab, enable CodeQL default setup (or add a custom workflow) to run on every push.',
-            evidence: {
-              [repo.full_name]: {
-                code_scanning: {
-                  status: 'not_configured',
-                  checked_at: new Date().toISOString(),
-                },
-              },
-            },
-          });
-          break;
-      }
-    }
-  },
-};
diff --git a/packages/integration-platform/src/manifests/github/checks/validation-libraries.ts b/packages/integration-platform/src/manifests/github/checks/validation-libraries.ts
new file mode 100644
index 0000000000..0a6377119a
--- /dev/null
+++ b/packages/integration-platform/src/manifests/github/checks/validation-libraries.ts
@@ -0,0 +1,43 @@
+/**
+ * Validation library catalogs for the Input Validation check.
+ * Lists the package names we accept as evidence of input validation /
+ * sanitization being in place across JS/TS, Python, and PHP ecosystems.
+ */
+
+export const JS_VALIDATION_PACKAGES = [
+  'zod',
+  'yup',
+  'joi',
+  '@effect/schema',
+  'effect',
+  'valibot',
+  'ajv',
+  'class-validator',
+  'io-ts',
+  'superstruct',
+  'runtypes',
+];
+
+export const PY_VALIDATION_PACKAGES = [
+  'pydantic',
+  'marshmallow',
+  'cerberus',
+  'voluptuous',
+  'jsonschema',
+  'schematics',
+  'typeguard',
+];
+
+export const PHP_VALIDATION_PACKAGES = [
+  'laravel/framework',
+  'respect/validation',
+  'symfony/validator',
+  'vlucas/valitron',
+];
+
+export const VALIDATION_TARGET_FILES = [
+  'package.json',
+  'requirements.txt',
+  'pyproject.toml',
+  'composer.json',
+];
diff --git a/packages/integration-platform/src/manifests/github/index.ts b/packages/integration-platform/src/manifests/github/index.ts
index db43a9171c..2fa94540cb 100644
--- a/packages/integration-platform/src/manifests/github/index.ts
+++ b/packages/integration-platform/src/manifests/github/index.ts
@@ -7,8 +7,9 @@
 
 import type { IntegrationManifest } from '../../types';
 import { branchProtectionCheck } from './checks/branch-protection';
+import { codeScanningCheck } from './checks/code-scanning';
 import { dependabotCheck } from './checks/dependabot';
-import { sanitizedInputsCheck } from './checks/sanitized-inputs';
+import { inputValidationCheck } from './checks/input-validation';
 import { twoFactorAuthCheck } from './checks/two-factor-auth';
 
 export const manifest: IntegrationManifest = {
@@ -82,7 +83,13 @@ export const manifest: IntegrationManifest = {
   ],
 
   // Compliance checks that run daily and can auto-complete tasks
-  checks: [branchProtectionCheck, dependabotCheck, sanitizedInputsCheck, twoFactorAuthCheck],
+  checks: [
+    branchProtectionCheck,
+    codeScanningCheck,
+    dependabotCheck,
+    inputValidationCheck,
+    twoFactorAuthCheck,
+  ],
 
   isActive: true,
 };

From 07739f872ba70bf3d0bf329a56d46dfb68e1ea25 Mon Sep 17 00:00:00 2001
From: Tofik Hasanov <annexcies@gmail.com>
Date: Mon, 27 Apr 2026 12:14:47 -0400
Subject: [PATCH 39/40] refactor(integrations): keep sanitized-inputs.ts in
 place, only add code-scanning

Reverts the previous split structure to a more conservative approach:
keep sanitized-inputs.ts (and its check id 'sanitized_inputs') and just
strip the code-scanning logic out of it. Code scanning becomes a single
new self-contained file (code-scanning.ts).

This preserves continuity for existing customers:
- IntegrationCheckRun records under 'sanitized_inputs' continue to be
  the same automation
- IntegrationConnection.metadata.disabledTaskChecks entries that
  reference 'sanitized_inputs' remain valid

Removes the helper modules (input-validation.ts, validation-libraries.ts,
code-scanning-detector.ts) introduced in the previous commit.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../github/checks/code-scanning-detector.ts   | 149 ------------
 .../manifests/github/checks/code-scanning.ts  | 149 +++++++++++-
 .../src/manifests/github/checks/index.ts      |   2 +-
 ...nput-validation.ts => sanitized-inputs.ts} | 218 ++++++++++--------
 .../github/checks/validation-libraries.ts     |  43 ----
 .../src/manifests/github/index.ts             |   4 +-
 6 files changed, 272 insertions(+), 293 deletions(-)
 delete mode 100644 packages/integration-platform/src/manifests/github/checks/code-scanning-detector.ts
 rename packages/integration-platform/src/manifests/github/checks/{input-validation.ts => sanitized-inputs.ts} (61%)
 delete mode 100644 packages/integration-platform/src/manifests/github/checks/validation-libraries.ts

diff --git a/packages/integration-platform/src/manifests/github/checks/code-scanning-detector.ts b/packages/integration-platform/src/manifests/github/checks/code-scanning-detector.ts
deleted file mode 100644
index 3f00984a72..0000000000
--- a/packages/integration-platform/src/manifests/github/checks/code-scanning-detector.ts
+++ /dev/null
@@ -1,149 +0,0 @@
-/**
- * Code scanning detection logic for the Code Scanning check.
- * Determines whether a repo has CodeQL or an equivalent static analysis
- * tool configured, falling back from the default-setup API to scanning
- * workflow files for SARIF uploaders.
- */
-
-import type { CheckContext } from '../../../types';
-import type { GitHubCodeScanningDefaultSetup, GitHubTreeEntry } from '../types';
-
-// Patterns that indicate code scanning is configured in a workflow
-const CODE_SCANNING_PATTERNS = [
-  'github/codeql-action/init',
-  'github/codeql-action/analyze',
-  'github/codeql-action/upload-sarif',
-  'codeql-action/init',
-  'codeql-action/analyze',
-  'codeql-action/upload-sarif',
-  'upload-sarif', // Generic SARIF upload
-];
-
-interface GitHubFileResponse {
-  content: string;
-  encoding: 'base64' | 'utf-8';
-  path: string;
-}
-
-export type CodeScanningStatus =
-  | {
-      status: 'enabled';
-      method: 'default-setup' | 'workflow';
-      languages?: string[];
-      workflow?: string;
-    }
-  | { status: 'not-configured' }
-  | { status: 'permission-denied'; isPrivate: boolean }
-  | { status: 'ghas-required' };
-
-const decodeFile = (file: GitHubFileResponse): string => {
-  if (!file?.content) return '';
-  if (file.encoding === 'base64') {
-    return Buffer.from(file.content, 'base64').toString('utf-8');
-  }
-  return file.content;
-};
-
-const hasCodeScanningInWorkflow = (content: string): boolean => {
-  const lower = content.toLowerCase();
-  return CODE_SCANNING_PATTERNS.some((pattern) => lower.includes(pattern.toLowerCase()));
-};
-
-const findCodeScanningWorkflows = async (
-  ctx: CheckContext,
-  repoName: string,
-  tree: GitHubTreeEntry[],
-): Promise<string[]> => {
-  const workflowFiles = tree.filter(
-    (entry) =>
-      entry.type === 'blob' &&
-      entry.path.startsWith('.github/workflows/') &&
-      (entry.path.endsWith('.yml') || entry.path.endsWith('.yaml')),
-  );
-
-  const codeScanningWorkflows: string[] = [];
-
-  for (const entry of workflowFiles) {
-    try {
-      const file = await ctx.fetch<GitHubFileResponse>(
-        `/repos/${repoName}/contents/${entry.path}`,
-      );
-      const content = decodeFile(file);
-      if (content && hasCodeScanningInWorkflow(content)) {
-        codeScanningWorkflows.push(entry.path);
-      }
-    } catch {
-      // Skip workflows we can't read
-    }
-  }
-
-  return codeScanningWorkflows;
-};
-
-export const getCodeScanningStatus = async ({
-  ctx,
-  repoName,
-  tree,
-  isPrivate,
-  isGhasEnabled,
-}: {
-  ctx: CheckContext;
-  repoName: string;
-  tree: GitHubTreeEntry[];
-  isPrivate: boolean;
-  isGhasEnabled: boolean;
-}): Promise<CodeScanningStatus> => {
-  let apiGot403 = false;
-
-  // First, try the default setup API
-  try {
-    const setup = await ctx.fetch<GitHubCodeScanningDefaultSetup>(
-      `/repos/${repoName}/code-scanning/default-setup`,
-    );
-    if (setup.state === 'configured') {
-      return {
-        status: 'enabled',
-        method: 'default-setup',
-        languages: setup.languages || [],
-      };
-    }
-  } catch (error) {
-    const errorStr = String(error);
-
-    if (errorStr.includes('403') || errorStr.includes('Forbidden')) {
-      // The code-scanning API requires GHAS for private repos, but reading
-      // workflow file contents only requires contents:read. A 403 here does
-      // not mean we can't check for code scanning workflows.
-      ctx.log(
-        `Code scanning API returned 403 for ${repoName} (private: ${isPrivate}, ghas: ${isGhasEnabled}). Falling back to workflow file scanning.`,
-      );
-      apiGot403 = true;
-    } else {
-      ctx.log(`Code scanning default setup not available for ${repoName}: ${errorStr}`);
-    }
-  }
-
-  // Fall back to checking for workflow files with code scanning.
-  // This catches repos using third-party SAST tools (Semgrep, Snyk, Trivy, etc.)
-  // that upload SARIF results via github/codeql-action/upload-sarif.
-  const codeScanningWorkflows = await findCodeScanningWorkflows(ctx, repoName, tree);
-  if (codeScanningWorkflows.length > 0) {
-    return {
-      status: 'enabled',
-      method: 'workflow',
-      workflow: codeScanningWorkflows[0],
-    };
-  }
-
-  if (apiGot403) {
-    if (isPrivate) {
-      if (isGhasEnabled) {
-        return { status: 'permission-denied', isPrivate };
-      }
-      return { status: 'ghas-required' };
-    }
-    return { status: 'permission-denied', isPrivate };
-  }
-
-  return { status: 'not-configured' };
-};
diff --git a/packages/integration-platform/src/manifests/github/checks/code-scanning.ts b/packages/integration-platform/src/manifests/github/checks/code-scanning.ts
index 272204fbda..b0b336c6de 100644
--- a/packages/integration-platform/src/manifests/github/checks/code-scanning.ts
+++ b/packages/integration-platform/src/manifests/github/checks/code-scanning.ts
@@ -9,9 +9,49 @@
 
 import { TASK_TEMPLATES } from '../../../task-mappings';
 import type { IntegrationCheck } from '../../../types';
-import type { GitHubRepo, GitHubTreeEntry, GitHubTreeResponse } from '../types';
+import type {
+  GitHubCodeScanningDefaultSetup,
+  GitHubRepo,
+  GitHubTreeEntry,
+  GitHubTreeResponse,
+} from '../types';
 import { parseRepoBranch, targetReposVariable } from '../variables';
-import { getCodeScanningStatus } from './code-scanning-detector';
+
+// Patterns that indicate code scanning is configured in a workflow
+const CODE_SCANNING_PATTERNS = [
+  'github/codeql-action/init',
+  'github/codeql-action/analyze',
+  'github/codeql-action/upload-sarif',
+  'codeql-action/init',
+  'codeql-action/analyze',
+  'codeql-action/upload-sarif',
+  'upload-sarif', // Generic SARIF upload
+];
+
+interface GitHubFileResponse {
+  content: string;
+  encoding: 'base64' | 'utf-8';
+  path: string;
+}
+
+type CodeScanningStatus =
+  | {
+      status: 'enabled';
+      method: 'default-setup' | 'workflow';
+      languages?: string[];
+      workflow?: string;
+    }
+  | { status: 'not-configured' }
+  | { status: 'permission-denied'; isPrivate: boolean }
+  | { status: 'ghas-required' };
+
+const decodeFile = (file: GitHubFileResponse): string => {
+  if (!file?.content) return '';
+  if (file.encoding === 'base64') {
+    return Buffer.from(file.content, 'base64').toString('utf-8');
+  }
+  return file.content;
+};
 
 export const codeScanningCheck: IntegrationCheck = {
   id: 'code_scanning',
@@ -64,6 +104,110 @@ export const codeScanningCheck: IntegrationCheck = {
       }
     };
 
+    const fetchFile = async (repoName: string, path: string): Promise<string | null> => {
+      try {
+        const file = await ctx.fetch<GitHubFileResponse>(`/repos/${repoName}/contents/${path}`);
+        return decodeFile(file);
+      } catch {
+        return null;
+      }
+    };
+
+    const hasCodeScanningInWorkflow = (content: string): boolean => {
+      const lower = content.toLowerCase();
+      return CODE_SCANNING_PATTERNS.some((pattern) => lower.includes(pattern.toLowerCase()));
+    };
+
+    const findCodeScanningWorkflows = async (
+      repoName: string,
+      tree: GitHubTreeEntry[],
+    ): Promise<string[]> => {
+      const workflowFiles = tree.filter(
+        (entry) =>
+          entry.type === 'blob' &&
+          entry.path.startsWith('.github/workflows/') &&
+          (entry.path.endsWith('.yml') || entry.path.endsWith('.yaml')),
+      );
+
+      const codeScanningWorkflows: string[] = [];
+
+      for (const entry of workflowFiles) {
+        const content = await fetchFile(repoName, entry.path);
+        if (content && hasCodeScanningInWorkflow(content)) {
+          codeScanningWorkflows.push(entry.path);
+        }
+      }
+
+      return codeScanningWorkflows;
+    };
+
+    const getCodeScanningStatus = async ({
+      repoName,
+      tree,
+      isPrivate,
+      isGhasEnabled,
+    }: {
+      repoName: string;
+      tree: GitHubTreeEntry[];
+      isPrivate: boolean;
+      isGhasEnabled: boolean;
+    }): Promise<CodeScanningStatus> => {
+      let apiGot403 = false;
+
+      // First, try the default setup API
+      try {
+        const setup = await ctx.fetch<GitHubCodeScanningDefaultSetup>(
+          `/repos/${repoName}/code-scanning/default-setup`,
+        );
+        if (setup.state === 'configured') {
+          return {
+            status: 'enabled',
+            method: 'default-setup',
+            languages: setup.languages || [],
+          };
+        }
+      } catch (error) {
+        const errorStr = String(error);
+
+        if (errorStr.includes('403') || errorStr.includes('Forbidden')) {
+          // The code-scanning API requires GHAS for private repos, but reading
+          // workflow file contents only requires contents:read. A 403 here does
+          // not mean we can't check for code scanning workflows.
+          ctx.log(
+            `Code scanning API returned 403 for ${repoName} (private: ${isPrivate}, ghas: ${isGhasEnabled}). Falling back to workflow file scanning.`,
+          );
+          apiGot403 = true;
+        } else {
+          // Other errors - API might not be available, continue to check workflows
+          ctx.log(`Code scanning default setup not available for ${repoName}: ${errorStr}`);
+        }
+      }
+
+      // Fall back to checking for workflow files with code scanning.
+      // This catches repos using third-party SAST tools (Semgrep, Snyk, Trivy, etc.)
+      // that upload SARIF results via github/codeql-action/upload-sarif.
+      const codeScanningWorkflows = await findCodeScanningWorkflows(repoName, tree);
+      if (codeScanningWorkflows.length > 0) {
+        return {
+          status: 'enabled',
+          method: 'workflow',
+          workflow: codeScanningWorkflows[0],
+        };
+      }
+
+      if (apiGot403) {
+        if (isPrivate) {
+          if (isGhasEnabled) {
+            return { status: 'permission-denied', isPrivate };
+          }
+          return { status: 'ghas-required' };
+        }
+        return { status: 'permission-denied', isPrivate };
+      }
+
+      return { status: 'not-configured' };
+    };
+
     for (const repoName of targetRepos) {
       const repo = await fetchRepo(repoName);
       if (!repo) continue;
@@ -72,7 +216,6 @@ export const codeScanningCheck: IntegrationCheck = {
       const isGhasEnabled = repo.security_and_analysis?.advanced_security?.status === 'enabled';
 
       const codeScanningStatus = await getCodeScanningStatus({
-        ctx,
         repoName: repo.full_name,
         tree,
         isPrivate: repo.private,
diff --git a/packages/integration-platform/src/manifests/github/checks/index.ts b/packages/integration-platform/src/manifests/github/checks/index.ts
index 3528e1c459..2c2a5eaec1 100644
--- a/packages/integration-platform/src/manifests/github/checks/index.ts
+++ b/packages/integration-platform/src/manifests/github/checks/index.ts
@@ -6,5 +6,5 @@
 export { branchProtectionCheck } from './branch-protection';
 export { codeScanningCheck } from './code-scanning';
 export { dependabotCheck } from './dependabot';
-export { inputValidationCheck } from './input-validation';
+export { sanitizedInputsCheck } from './sanitized-inputs';
 export { twoFactorAuthCheck } from './two-factor-auth';
diff --git a/packages/integration-platform/src/manifests/github/checks/input-validation.ts b/packages/integration-platform/src/manifests/github/checks/sanitized-inputs.ts
similarity index 61%
rename from packages/integration-platform/src/manifests/github/checks/input-validation.ts
rename to packages/integration-platform/src/manifests/github/checks/sanitized-inputs.ts
index 7dcd950d6b..d3988f7107 100644
--- a/packages/integration-platform/src/manifests/github/checks/input-validation.ts
+++ b/packages/integration-platform/src/manifests/github/checks/sanitized-inputs.ts
@@ -1,23 +1,55 @@
 /**
- * Input Validation Check
+ * Sanitized Inputs Check
  *
- * Verifies repositories use a modern validation/sanitization library.
+ * Ensures repositories use a modern validation/sanitization library.
  * Supports monorepos by scanning all package.json / requirements.txt /
- * pyproject.toml / composer.json files in the repository tree.
+ * pyproject.toml / composer.json files.
  *
- * Detection covers JS/TS, Python, and PHP ecosystems.
+ * Validation-library detection covers JS/TS, Python, and PHP ecosystems.
  */
 
 import { TASK_TEMPLATES } from '../../../task-mappings';
 import type { IntegrationCheck } from '../../../types';
 import type { GitHubRepo, GitHubTreeEntry, GitHubTreeResponse } from '../types';
 import { parseRepoBranch, targetReposVariable } from '../variables';
-import {
-  JS_VALIDATION_PACKAGES,
-  PHP_VALIDATION_PACKAGES,
-  PY_VALIDATION_PACKAGES,
-  VALIDATION_TARGET_FILES,
-} from './validation-libraries';
+
+const JS_VALIDATION_PACKAGES = [
+  'zod',
+  'yup',
+  'joi',
+  '@effect/schema',
+  'effect',
+  'valibot',
+  'ajv',
+  'class-validator',
+  'io-ts',
+  'superstruct',
+  'runtypes',
+];
+
+const PY_VALIDATION_PACKAGES = [
+  'pydantic',
+  'marshmallow',
+  'cerberus',
+  'voluptuous',
+  'jsonschema',
+  'schematics',
+  'typeguard',
+];
+
+const PHP_VALIDATION_PACKAGES = [
+  'laravel/framework',
+  'respect/validation',
+  'symfony/validator',
+  'vlucas/valitron',
+];
+
+const TARGET_FILES = [
+  'package.json',
+  'requirements.txt',
+  'pyproject.toml',
+  'composer.json',
+];
 
 interface GitHubFileResponse {
   content: string;
@@ -43,88 +75,9 @@ const getFileName = (path: string): string => {
   return parts[parts.length - 1] ?? path;
 };
 
-const escapeRegex = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-
-const checkPackageJson = (content: string, filePath: string): ValidationMatch | null => {
-  try {
-    const pkg = JSON.parse(content);
-    const deps = {
-      ...(pkg.dependencies || {}),
-      ...(pkg.devDependencies || {}),
-    };
-    for (const candidate of JS_VALIDATION_PACKAGES) {
-      if (deps[candidate]) {
-        return { library: candidate, file: filePath };
-      }
-    }
-  } catch {
-    // Invalid JSON, skip
-  }
-  return null;
-};
-
-const checkPythonFile = (
-  content: string,
-  filePath: string,
-  fileName: string,
-): ValidationMatch | null => {
-  // Parse line-by-line so we can strip comments and match package names as
-  // standalone tokens (e.g. don't match "schema" inside "jsonschema" or inside
-  // a prose comment).
-  //
-  // Comment syntax differs between the two Python dependency file formats:
-  //   - pyproject.toml (TOML): `#` starts a comment anywhere outside a string.
-  //     Dependency values are always quoted, so stripping at any `#` is safe
-  //     — the package name in `"name @ url#egg=name"` appears before the URL.
-  //   - requirements.txt (pip): `#` only starts a comment when preceded by
-  //     whitespace (or at line start). This preserves VCS URL fragments like
-  //     `git+https://...#egg=pydantic` used for editable installs.
-  const isTOML = fileName === 'pyproject.toml';
-  const stripCommentRegex = isTOML ? /#.*$/ : /(^|\s)#.*$/;
-  const lines = content.split('\n');
-  for (const rawLine of lines) {
-    const line = rawLine.replace(stripCommentRegex, '').toLowerCase();
-    if (!line.trim()) continue;
-    for (const candidate of PY_VALIDATION_PACKAGES) {
-      const escaped = escapeRegex(candidate.toLowerCase());
-      // Match the package name as a standalone token. Leading context: start
-      // of line or a separator commonly preceding a package name (whitespace,
-      // quote, bracket, comma, semicolon, or `=` for `#egg=name` VCS syntax).
-      // Trailing context: end of line or a separator that can follow a
-      // package name (whitespace, version operator, bracket, quote, comma,
-      // semicolon).
-      const pattern = new RegExp(
-        `(?:^|[\\s"'\\[,;=])${escaped}(?:$|[\\s=<>!~\\[\\]"',;])`,
-      );
-      if (pattern.test(line)) {
-        return { library: candidate, file: filePath };
-      }
-    }
-  }
-  return null;
-};
-
-const checkComposerJson = (content: string, filePath: string): ValidationMatch | null => {
-  try {
-    const pkg = JSON.parse(content);
-    const deps = {
-      ...(pkg.require || {}),
-      ...(pkg['require-dev'] || {}),
-    };
-    for (const candidate of PHP_VALIDATION_PACKAGES) {
-      if (deps[candidate]) {
-        return { library: candidate, file: filePath };
-      }
-    }
-  } catch {
-    // Invalid JSON, skip
-  }
-  return null;
-};
-
-export const inputValidationCheck: IntegrationCheck = {
-  id: 'input_validation',
-  name: 'Input Validation',
+export const sanitizedInputsCheck: IntegrationCheck = {
+  id: 'sanitized_inputs',
+  name: 'Sanitized Inputs',
   description:
     'Verifies repositories use a supported input-validation library (JS/TS, Python, or PHP). Scans entire repository including monorepo subdirectories.',
   service: 'code-security',
@@ -141,7 +94,7 @@ export const inputValidationCheck: IntegrationCheck = {
       ctx.fail({
         title: 'No repositories selected',
         description:
-          'Select at least one repository to monitor in the integration settings so we can verify input validation.',
+          'Select at least one repository to monitor in the integration settings so we can verify sanitized inputs.',
         resourceType: 'integration',
         resourceId: 'github',
         severity: 'low',
@@ -183,14 +136,89 @@ export const inputValidationCheck: IntegrationCheck = {
       }
     };
 
+    const checkPackageJson = (content: string, filePath: string): ValidationMatch | null => {
+      try {
+        const pkg = JSON.parse(content);
+        const deps = {
+          ...(pkg.dependencies || {}),
+          ...(pkg.devDependencies || {}),
+        };
+        for (const candidate of JS_VALIDATION_PACKAGES) {
+          if (deps[candidate]) {
+            return { library: candidate, file: filePath };
+          }
+        }
+      } catch {
+        // Invalid JSON, skip
+      }
+      return null;
+    };
+
+    const escapeRegex = (s: string): string =>
+      s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+    const checkPythonFile = (
+      content: string,
+      filePath: string,
+      fileName: string,
+    ): ValidationMatch | null => {
+      // Parse line-by-line; strip comments and match package names as standalone
+      // tokens to avoid matching "schema" inside "jsonschema" or in prose comments.
+      // requirements.txt only treats `#` as a comment when whitespace-preceded —
+      // that preserves VCS URL fragments like `git+https://...#egg=pydantic`.
+      // pyproject.toml uses normal `#` since dependency values are always quoted.
+      const isTOML = fileName === 'pyproject.toml';
+      const stripCommentRegex = isTOML ? /#.*$/ : /(^|\s)#.*$/;
+      const lines = content.split('\n');
+      for (const rawLine of lines) {
+        const line = rawLine.replace(stripCommentRegex, '').toLowerCase();
+        if (!line.trim()) continue;
+        for (const candidate of PY_VALIDATION_PACKAGES) {
+          const escaped = escapeRegex(candidate.toLowerCase());
+          // Match the package name as a standalone token. Leading context: start
+          // of line or a separator commonly preceding a package name (whitespace,
+          // quote, bracket, comma, semicolon, or `=` for `#egg=name` VCS syntax).
+          // Trailing context: end of line or a separator that can follow a
+          // package name (whitespace, version operator, bracket, quote, comma,
+          // semicolon).
+          const pattern = new RegExp(
+            `(?:^|[\\s"'\\[,;=])${escaped}(?:$|[\\s=<>!~\\[\\]"',;])`,
+          );
+          if (pattern.test(line)) {
+            return { library: candidate, file: filePath };
+          }
+        }
+      }
+      return null;
+    };
+
+    const checkComposerJson = (content: string, filePath: string): ValidationMatch | null => {
+      try {
+        const pkg = JSON.parse(content);
+        const deps = {
+          ...(pkg.require || {}),
+          ...(pkg['require-dev'] || {}),
+        };
+        for (const candidate of PHP_VALIDATION_PACKAGES) {
+          if (deps[candidate]) {
+            return { library: candidate, file: filePath };
+          }
+        }
+      } catch {
+        // Invalid JSON, skip
+      }
+      return null;
+    };
+
     const findValidationLibraries = async (
       repoName: string,
       tree: GitHubTreeEntry[],
     ): Promise<ValidationMatch[]> => {
       const matches: ValidationMatch[] = [];
 
+      // Find all target files in the tree
       const targetEntries = tree.filter(
-        (entry) => entry.type === 'blob' && VALIDATION_TARGET_FILES.includes(getFileName(entry.path)),
+        (entry) => entry.type === 'blob' && TARGET_FILES.includes(getFileName(entry.path)),
       );
 
       for (const entry of targetEntries) {
@@ -239,7 +267,7 @@ export const inputValidationCheck: IntegrationCheck = {
         });
       } else {
         const checkedFiles = tree
-          .filter((e) => e.type === 'blob' && VALIDATION_TARGET_FILES.includes(getFileName(e.path)))
+          .filter((e) => e.type === 'blob' && TARGET_FILES.includes(getFileName(e.path)))
           .map((e) => e.path);
 
         const supportedLibraries = [
diff --git a/packages/integration-platform/src/manifests/github/checks/validation-libraries.ts b/packages/integration-platform/src/manifests/github/checks/validation-libraries.ts
deleted file mode 100644
index 0a6377119a..0000000000
--- a/packages/integration-platform/src/manifests/github/checks/validation-libraries.ts
+++ /dev/null
@@ -1,43 +0,0 @@
-/**
- * Validation library catalogs for the Input Validation check.
- * Lists the package names we accept as evidence of input validation /
- * sanitization being in place across JS/TS, Python, and PHP ecosystems.
- */
-
-export const JS_VALIDATION_PACKAGES = [
-  'zod',
-  'yup',
-  'joi',
-  '@effect/schema',
-  'effect',
-  'valibot',
-  'ajv',
-  'class-validator',
-  'io-ts',
-  'superstruct',
-  'runtypes',
-];
-
-export const PY_VALIDATION_PACKAGES = [
-  'pydantic',
-  'marshmallow',
-  'cerberus',
-  'voluptuous',
-  'jsonschema',
-  'schematics',
-  'typeguard',
-];
-
-export const PHP_VALIDATION_PACKAGES = [
-  'laravel/framework',
-  'respect/validation',
-  'symfony/validator',
-  'vlucas/valitron',
-];
-
-export const VALIDATION_TARGET_FILES = [
-  'package.json',
-  'requirements.txt',
-  'pyproject.toml',
-  'composer.json',
-];
diff --git a/packages/integration-platform/src/manifests/github/index.ts b/packages/integration-platform/src/manifests/github/index.ts
index 2fa94540cb..c1a5d94746 100644
--- a/packages/integration-platform/src/manifests/github/index.ts
+++ b/packages/integration-platform/src/manifests/github/index.ts
@@ -9,7 +9,7 @@ import type { IntegrationManifest } from '../../types';
 import { branchProtectionCheck } from './checks/branch-protection';
 import { codeScanningCheck } from './checks/code-scanning';
 import { dependabotCheck } from './checks/dependabot';
-import { inputValidationCheck } from './checks/input-validation';
+import { sanitizedInputsCheck } from './checks/sanitized-inputs';
 import { twoFactorAuthCheck } from './checks/two-factor-auth';
 
 export const manifest: IntegrationManifest = {
@@ -87,7 +87,7 @@ export const manifest: IntegrationManifest = {
     branchProtectionCheck,
     codeScanningCheck,
     dependabotCheck,
-    inputValidationCheck,
+    sanitizedInputsCheck,
     twoFactorAuthCheck,
   ],
 

From bfd1f5f19898540b35d257fd4966e07c03536fb5 Mon Sep 17 00:00:00 2001
From: chasprowebdev <chasgarciaprowebdev@gmail.com>
Date: Mon, 27 Apr 2026 14:10:29 -0400
Subject: [PATCH 40/40] fix(api): add non-empty validation for requirement
 fields in ExportSOADocumentDto

---
 apps/api/src/soa/dto/export-soa-document.dto.ts | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/apps/api/src/soa/dto/export-soa-document.dto.ts b/apps/api/src/soa/dto/export-soa-document.dto.ts
index 84c62cbade..498d79fe23 100644
--- a/apps/api/src/soa/dto/export-soa-document.dto.ts
+++ b/apps/api/src/soa/dto/export-soa-document.dto.ts
@@ -1,10 +1,12 @@
-import { IsIn, IsString } from 'class-validator';
+import { IsIn, IsNotEmpty, IsString } from 'class-validator';
 
 export class ExportSOADocumentDto {
   @IsString()
+  @IsNotEmpty()
   documentId!: string;
 
   @IsString()
+  @IsNotEmpty()
   organizationId!: string;
 
   @IsIn(['pdf'])