From 2b21d1cff71f3f95c839470272a6e41e83a8da3c Mon Sep 17 00:00:00 2001
From: Tofik Hasanov <annexcies@gmail.com>
Date: Fri, 22 May 2026 10:04:33 -0400
Subject: [PATCH 1/6] fix(trust): persist portal branding settings

---
 .../components/BrandSettings.test.tsx         |  47 +++-
 .../components/BrandSettings.tsx              | 202 +++++++++++-------
 .../TrustPortalBrandingSettings.test.tsx      |  50 +++++
 .../TrustPortalBrandingSettings.tsx           |  42 ++++
 .../components/TrustPortalSwitch.test.tsx     |  63 ++++--
 .../components/TrustPortalSwitch.tsx          |  32 ++-
 .../components/UpdateTrustFavicon.test.tsx    | 112 +++++++---
 .../components/UpdateTrustFavicon.tsx         |  44 +++-
 8 files changed, 419 insertions(+), 173 deletions(-)
 create mode 100644 apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/TrustPortalBrandingSettings.test.tsx
 create mode 100644 apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/TrustPortalBrandingSettings.tsx

diff --git a/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/BrandSettings.test.tsx b/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/BrandSettings.test.tsx
index 09aece5784..33b7102c1f 100644
--- a/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/BrandSettings.test.tsx
+++ b/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/BrandSettings.test.tsx
@@ -1,11 +1,19 @@
-import { render, screen } from '@testing-library/react';
-import { beforeEach, describe, expect, it, vi } from 'vitest';
 import {
-  setMockPermissions,
   ADMIN_PERMISSIONS,
   AUDITOR_PERMISSIONS,
   mockHasPermission,
+  setMockPermissions,
 } from '@/test-utils/mocks/permissions';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const navigationMock = vi.hoisted(() => ({
+  refresh: vi.fn(),
+}));
+
+const trustPortalSettingsMock = vi.hoisted(() => ({
+  updateToggleSettings: vi.fn(),
+}));
 
 vi.mock('@/hooks/use-permissions', () => ({
   usePermissions: () => ({
@@ -16,7 +24,7 @@ vi.mock('@/hooks/use-permissions', () => ({
 
 vi.mock('@/hooks/use-trust-portal-settings', () => ({
   useTrustPortalSettings: () => ({
-    updateToggleSettings: vi.fn(),
+    updateToggleSettings: trustPortalSettingsMock.updateToggleSettings,
   }),
 }));
 
@@ -24,6 +32,10 @@ vi.mock('@/hooks/useDebounce', () => ({
   useDebounce: (value: string) => value,
 }));
 
+vi.mock('next/navigation', () => ({
+  useRouter: () => ({ refresh: navigationMock.refresh }),
+}));
+
 vi.mock('sonner', () => ({
   toast: { success: vi.fn(), error: vi.fn() },
 }));
@@ -32,21 +44,21 @@ import { BrandSettings } from './BrandSettings';
 
 describe('BrandSettings permission gating', () => {
   const defaultProps = {
-    orgId: 'org-1',
     primaryColor: '#FF0000',
   };
 
   beforeEach(() => {
     vi.clearAllMocks();
+    trustPortalSettingsMock.updateToggleSettings.mockResolvedValue({
+      success: true,
+    });
   });
 
   it('renders title and description regardless of permissions', () => {
     setMockPermissions({});
     render(<BrandSettings {...defaultProps} />);
     expect(screen.getByText('Brand Settings')).toBeInTheDocument();
-    expect(
-      screen.getByText('Customize the appearance of your trust portal'),
-    ).toBeInTheDocument();
+    expect(screen.getByText('Customize the appearance of your trust portal')).toBeInTheDocument();
   });
 
   it('enables the color picker input when user has trust:update permission', () => {
@@ -75,4 +87,23 @@ describe('BrandSettings permission gating', () => {
     render(<BrandSettings {...defaultProps} />);
     expect(screen.getByText('Brand Color')).toBeInTheDocument();
   });
+
+  it('persists a valid brand color and refreshes settings', async () => {
+    setMockPermissions(ADMIN_PERMISSIONS);
+    const handlePrimaryColorChange = vi.fn();
+
+    render(<BrandSettings {...defaultProps} onPrimaryColorChange={handlePrimaryColorChange} />);
+
+    const textInput = screen.getByRole('textbox');
+    fireEvent.change(textInput, { target: { value: '#00ff00' } });
+
+    await waitFor(() => {
+      expect(trustPortalSettingsMock.updateToggleSettings).toHaveBeenCalledWith({
+        enabled: true,
+        primaryColor: '#00FF00',
+      });
+    });
+    expect(handlePrimaryColorChange).toHaveBeenCalledWith('#00FF00');
+    expect(navigationMock.refresh).toHaveBeenCalled();
+  });
 });
diff --git a/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/BrandSettings.tsx b/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/BrandSettings.tsx
index ed82a875e0..85fcfed401 100644
--- a/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/BrandSettings.tsx
+++ b/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/BrandSettings.tsx
@@ -1,29 +1,50 @@
 'use client';
 
-import { useDebounce } from '@/hooks/useDebounce';
 import { usePermissions } from '@/hooks/use-permissions';
 import { useTrustPortalSettings } from '@/hooks/use-trust-portal-settings';
-import { Card, CardContent, CardDescription, CardHeader, CardTitle, Input } from '@trycompai/design-system';
-import { Form, FormControl, FormField, FormItem, FormLabel } from '@trycompai/ui/form';
+import { useDebounce } from '@/hooks/useDebounce';
 import { zodResolver } from '@hookform/resolvers/zod';
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  Field,
+  FieldLabel,
+  Input,
+} from '@trycompai/design-system';
+import { useRouter } from 'next/navigation';
 import { useCallback, useEffect, useRef, useState } from 'react';
-import { useForm } from 'react-hook-form';
+import { Controller, useForm } from 'react-hook-form';
 import { toast } from 'sonner';
 import { z } from 'zod';
 
+const DEFAULT_PRIMARY_COLOR = '#000000';
+const HEX_COLOR_PATTERN = /^#[0-9a-fA-F]{6}$/;
+
 const trustSettingsSchema = z.object({
-  primaryColor: z.string().optional(),
+  primaryColor: z.string().regex(HEX_COLOR_PATTERN, 'Enter a valid hex color').optional(),
 });
 
 interface BrandSettingsProps {
-  orgId: string;
+  enabled?: boolean;
   primaryColor: string | null;
+  onPrimaryColorChange?: (primaryColor: string | null) => void;
+}
+
+function normalizePrimaryColor(value: unknown): string | null {
+  if (typeof value !== 'string' || value.length === 0) return null;
+  if (!HEX_COLOR_PATTERN.test(value)) return null;
+  return value.toUpperCase();
 }
 
 export function BrandSettings({
-  orgId,
+  enabled = true,
   primaryColor,
+  onPrimaryColorChange,
 }: BrandSettingsProps) {
+  const router = useRouter();
   const { hasPermission } = usePermissions();
   const canUpdate = hasPermission('trust', 'update');
   const { updateToggleSettings } = useTrustPortalSettings();
@@ -36,7 +57,7 @@ export function BrandSettings({
   });
 
   const lastSaved = useRef<{ [key: string]: string | null }>({
-    primaryColor: primaryColor ?? null,
+    primaryColor: normalizePrimaryColor(primaryColor),
   });
 
   const savingRef = useRef<{ [key: string]: boolean }>({
@@ -49,16 +70,25 @@ export function BrandSettings({
         return;
       }
 
-      if (lastSaved.current[field] !== value) {
+      const nextPrimaryColor = normalizePrimaryColor(value);
+      if (!nextPrimaryColor) {
+        return;
+      }
+
+      if (lastSaved.current[field] !== nextPrimaryColor) {
         savingRef.current[field] = true;
         try {
           await updateToggleSettings({
-            enabled: true,
+            enabled,
             primaryColor:
-              field === 'primaryColor' ? (value as string) : (form.getValues('primaryColor') ?? undefined),
+              field === 'primaryColor'
+                ? nextPrimaryColor
+                : (form.getValues('primaryColor') ?? undefined),
           });
           toast.success('Brand settings updated');
-          lastSaved.current[field] = value as string | null;
+          lastSaved.current[field] = nextPrimaryColor;
+          onPrimaryColorChange?.(nextPrimaryColor);
+          router.refresh();
         } catch {
           toast.error('Failed to update brand settings');
         } finally {
@@ -66,30 +96,43 @@ export function BrandSettings({
         }
       }
     },
-    [form, updateToggleSettings],
+    [enabled, form, onPrimaryColorChange, router, updateToggleSettings],
   );
 
   const [primaryColorValue, setPrimaryColorValue] = useState(form.getValues('primaryColor') || '');
   const debouncedPrimaryColor = useDebounce(primaryColorValue, 800);
 
+  useEffect(() => {
+    const normalizedPrimaryColor = normalizePrimaryColor(primaryColor);
+    form.reset({ primaryColor: normalizedPrimaryColor ?? undefined });
+    setPrimaryColorValue(normalizedPrimaryColor ?? '');
+    lastSaved.current.primaryColor = normalizedPrimaryColor;
+  }, [form, primaryColor]);
+
   useEffect(() => {
     if (
       debouncedPrimaryColor !== undefined &&
-      debouncedPrimaryColor !== lastSaved.current.primaryColor &&
+      normalizePrimaryColor(debouncedPrimaryColor) !== lastSaved.current.primaryColor &&
       !savingRef.current.primaryColor
     ) {
-      form.setValue('primaryColor', debouncedPrimaryColor || undefined);
-      void autoSave('primaryColor', debouncedPrimaryColor || null);
+      const normalizedPrimaryColor = normalizePrimaryColor(debouncedPrimaryColor);
+      if (normalizedPrimaryColor) {
+        form.setValue('primaryColor', normalizedPrimaryColor);
+        void autoSave('primaryColor', normalizedPrimaryColor);
+      }
     }
   }, [debouncedPrimaryColor, autoSave, form]);
 
   const handlePrimaryColorBlur = useCallback(
     (e: React.FocusEvent<HTMLInputElement>) => {
-      const value = e.target.value;
-      if (value) {
-        form.setValue('primaryColor', value);
+      const value = normalizePrimaryColor(e.target.value);
+      if (!value) {
+        toast.error('Enter a valid hex color');
+        return;
       }
-      void autoSave('primaryColor', value || null);
+      form.setValue('primaryColor', value);
+      setPrimaryColorValue(value);
+      void autoSave('primaryColor', value);
     },
     [form, autoSave],
   );
@@ -101,69 +144,68 @@ export function BrandSettings({
         <CardDescription>Customize the appearance of your trust portal</CardDescription>
       </CardHeader>
       <CardContent>
-        <Form {...form}>
-          <div className="space-y-4">
-            <FormField
-              control={form.control}
-              name="primaryColor"
-              render={({ field }) => (
-                <FormItem className="w-full">
-                  <FormLabel>Brand Color</FormLabel>
-                  <FormControl>
+        <div className="space-y-4">
+          <Controller
+            control={form.control}
+            name="primaryColor"
+            render={({ field }) => (
+              <Field>
+                <FieldLabel htmlFor="color-picker">Brand Color</FieldLabel>
+                <div className="relative">
+                  <div className="flex items-center gap-2">
                     <div className="relative">
-                      <div className="flex items-center gap-2">
-                        <div className="relative">
-                          <input
-                            {...field}
-                            value={primaryColorValue ?? '#000000'}
-                            onChange={(e) => {
-                              field.onChange(e);
-                              setPrimaryColorValue(e.target.value);
-                            }}
-                            onBlur={handlePrimaryColorBlur}
-                            type="color"
-                            className="sr-only"
-                            id="color-picker"
-                            disabled={!canUpdate}
-                          />
-                          <label
-                            htmlFor="color-picker"
-                            className="flex h-9 w-9 shrink-0 cursor-pointer items-center justify-center rounded-lg border-2 border-border shadow-sm transition-all hover:scale-105 hover:shadow-md"
-                            style={{ backgroundColor: primaryColorValue || '#000000' }}
-                          >
-                            <span className="sr-only">Pick a color</span>
-                          </label>
-                        </div>
-                        <div className="flex-1">
-                          <div className="font-mono">
-                            <Input
-                              value={primaryColorValue?.toUpperCase() || '#000000'}
-                              onChange={(e) => {
-                                let value = e.target.value;
-                                if (!value.startsWith('#')) {
-                                  value = '#' + value;
-                                }
-                                field.onChange(value);
-                                setPrimaryColorValue(value);
-                              }}
-                              onBlur={handlePrimaryColorBlur}
-                              placeholder="#000000"
-                              maxLength={7}
-                              disabled={!canUpdate}
-                            />
-                          </div>
-                        </div>
+                      <input
+                        {...field}
+                        value={normalizePrimaryColor(primaryColorValue) ?? DEFAULT_PRIMARY_COLOR}
+                        onChange={(e) => {
+                          field.onChange(e);
+                          setPrimaryColorValue(e.target.value);
+                        }}
+                        onBlur={handlePrimaryColorBlur}
+                        type="color"
+                        className="sr-only"
+                        id="color-picker"
+                        disabled={!canUpdate}
+                      />
+                      <label
+                        htmlFor="color-picker"
+                        className="flex h-9 w-9 shrink-0 cursor-pointer items-center justify-center rounded-lg border-2 border-border shadow-sm transition-all hover:scale-105 hover:shadow-md"
+                        style={{
+                          backgroundColor:
+                            normalizePrimaryColor(primaryColorValue) ?? DEFAULT_PRIMARY_COLOR,
+                        }}
+                      >
+                        <span className="sr-only">Pick a color</span>
+                      </label>
+                    </div>
+                    <div className="flex-1">
+                      <div className="font-mono">
+                        <Input
+                          value={primaryColorValue?.toUpperCase() || DEFAULT_PRIMARY_COLOR}
+                          onChange={(e) => {
+                            let value = e.target.value;
+                            if (value.length > 0 && !value.startsWith('#')) {
+                              value = '#' + value;
+                            }
+                            field.onChange(value);
+                            setPrimaryColorValue(value);
+                          }}
+                          onBlur={handlePrimaryColorBlur}
+                          placeholder="#000000"
+                          maxLength={7}
+                          disabled={!canUpdate}
+                        />
                       </div>
                     </div>
-                  </FormControl>
-                </FormItem>
-              )}
-            />
-            <p className="text-xs text-muted-foreground">
-              Used for branding across your trust portal
-            </p>
-          </div>
-        </Form>
+                  </div>
+                </div>
+              </Field>
+            )}
+          />
+          <p className="text-xs text-muted-foreground">
+            Used for branding across your trust portal
+          </p>
+        </div>
       </CardContent>
     </Card>
   );
diff --git a/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/TrustPortalBrandingSettings.test.tsx b/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/TrustPortalBrandingSettings.test.tsx
new file mode 100644
index 0000000000..9f653b2472
--- /dev/null
+++ b/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/TrustPortalBrandingSettings.test.tsx
@@ -0,0 +1,50 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import { TrustPortalBrandingSettings } from './TrustPortalBrandingSettings';
+
+interface MockFaviconProps {
+  currentFaviconUrl: string | null;
+  onFaviconChange?: (faviconUrl: string | null) => void;
+}
+
+interface MockBrandProps {
+  primaryColor: string | null;
+  onPrimaryColorChange?: (primaryColor: string | null) => void;
+}
+
+vi.mock('./UpdateTrustFavicon', () => ({
+  UpdateTrustFavicon: ({ currentFaviconUrl, onFaviconChange }: MockFaviconProps) => (
+    <div>
+      <div data-testid="favicon-url">{currentFaviconUrl ?? 'default'}</div>
+      <button type="button" onClick={() => onFaviconChange?.('https://example.com/favicon.png')}>
+        Set favicon
+      </button>
+    </div>
+  ),
+}));
+
+vi.mock('./BrandSettings', () => ({
+  BrandSettings: ({ primaryColor, onPrimaryColorChange }: MockBrandProps) => (
+    <div>
+      <div data-testid="primary-color">{primaryColor ?? 'default'}</div>
+      <button type="button" onClick={() => onPrimaryColorChange?.('#00FF00')}>
+        Set color
+      </button>
+    </div>
+  ),
+}));
+
+describe('TrustPortalBrandingSettings', () => {
+  it('keeps saved branding values available for remounted tab content', () => {
+    render(<TrustPortalBrandingSettings enabled={true} primaryColor={null} faviconUrl={null} />);
+
+    expect(screen.getByTestId('favicon-url')).toHaveTextContent('default');
+    expect(screen.getByTestId('primary-color')).toHaveTextContent('default');
+
+    fireEvent.click(screen.getByRole('button', { name: /set favicon/i }));
+    fireEvent.click(screen.getByRole('button', { name: /set color/i }));
+
+    expect(screen.getByTestId('favicon-url')).toHaveTextContent('https://example.com/favicon.png');
+    expect(screen.getByTestId('primary-color')).toHaveTextContent('#00FF00');
+  });
+});
diff --git a/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/TrustPortalBrandingSettings.tsx b/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/TrustPortalBrandingSettings.tsx
new file mode 100644
index 0000000000..4ca0f86900
--- /dev/null
+++ b/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/TrustPortalBrandingSettings.tsx
@@ -0,0 +1,42 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { BrandSettings } from './BrandSettings';
+import { UpdateTrustFavicon } from './UpdateTrustFavicon';
+
+interface TrustPortalBrandingSettingsProps {
+  enabled: boolean;
+  primaryColor: string | null;
+  faviconUrl: string | null;
+}
+
+export function TrustPortalBrandingSettings({
+  enabled,
+  primaryColor,
+  faviconUrl,
+}: TrustPortalBrandingSettingsProps) {
+  const [currentPrimaryColor, setCurrentPrimaryColor] = useState(primaryColor);
+  const [currentFaviconUrl, setCurrentFaviconUrl] = useState(faviconUrl);
+
+  useEffect(() => {
+    setCurrentPrimaryColor(primaryColor);
+  }, [primaryColor]);
+
+  useEffect(() => {
+    setCurrentFaviconUrl(faviconUrl);
+  }, [faviconUrl]);
+
+  return (
+    <div className="space-y-6">
+      <UpdateTrustFavicon
+        currentFaviconUrl={currentFaviconUrl}
+        onFaviconChange={setCurrentFaviconUrl}
+      />
+      <BrandSettings
+        enabled={enabled}
+        primaryColor={currentPrimaryColor}
+        onPrimaryColorChange={setCurrentPrimaryColor}
+      />
+    </div>
+  );
+}
diff --git a/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/TrustPortalSwitch.test.tsx b/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/TrustPortalSwitch.test.tsx
index 56a1be66ba..90c2e71e89 100644
--- a/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/TrustPortalSwitch.test.tsx
+++ b/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/TrustPortalSwitch.test.tsx
@@ -1,11 +1,11 @@
-import { render, screen } from '@testing-library/react';
-import { beforeEach, describe, expect, it, vi } from 'vitest';
 import {
-  setMockPermissions,
   ADMIN_PERMISSIONS,
   AUDITOR_PERMISSIONS,
   mockHasPermission,
+  setMockPermissions,
 } from '@/test-utils/mocks/permissions';
+import { render, screen } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 vi.mock('@/hooks/use-permissions', () => ({
   usePermissions: () => ({
@@ -100,8 +100,12 @@ vi.mock('@dnd-kit/utilities', () => ({
 
 // Mock design system
 vi.mock('@trycompai/design-system', () => ({
-  Button: ({ children, onClick, disabled, iconLeft, iconRight, ...props }: any) => (
-    <button onClick={onClick} disabled={disabled} {...props}>{iconLeft}{children}{iconRight}</button>
+  Button: ({ children, onClick, disabled, iconLeft, iconRight, loading, ...props }: any) => (
+    <button onClick={onClick} disabled={disabled} {...props}>
+      {iconLeft}
+      {children}
+      {iconRight}
+    </button>
   ),
   Card: ({ children }: any) => <div>{children}</div>,
   CardContent: ({ children }: any) => <div>{children}</div>,
@@ -112,6 +116,8 @@ vi.mock('@trycompai/design-system', () => ({
   DropdownMenuContent: ({ children }: any) => <div>{children}</div>,
   DropdownMenuItem: ({ children, onClick }: any) => <button onClick={onClick}>{children}</button>,
   DropdownMenuTrigger: ({ children }: any) => <button>{children}</button>,
+  Field: ({ children }: any) => <div>{children}</div>,
+  FieldLabel: ({ children }: any) => <label>{children}</label>,
   Input: (props: any) => <input {...props} />,
   Select: ({ children, disabled }: any) => <div data-disabled={disabled}>{children}</div>,
   SelectContent: ({ children }: any) => <div>{children}</div>,
@@ -130,7 +136,11 @@ vi.mock('@trycompai/design-system', () => ({
   Tabs: ({ children }: any) => <div>{children}</div>,
   TabsContent: ({ children, value }: any) => <div data-value={value}>{children}</div>,
   TabsList: ({ children }: any) => <div role="tablist">{children}</div>,
-  TabsTrigger: ({ children, value }: any) => <button role="tab" data-value={value}>{children}</button>,
+  TabsTrigger: ({ children, value }: any) => (
+    <button role="tab" data-value={value}>
+      {children}
+    </button>
+  ),
   Textarea: (props: any) => <textarea {...props} />,
   Tooltip: ({ children }: any) => <div>{children}</div>,
   TooltipContent: ({ children }: any) => <div>{children}</div>,
@@ -139,46 +149,49 @@ vi.mock('@trycompai/design-system', () => ({
 
 vi.mock('@trycompai/design-system/icons', () => ({
   Add: () => <span />,
+  CertificateCheck: () => <span />,
   ChevronLeft: () => <span />,
   ChevronRight: () => <span />,
   Close: () => <span />,
+  Download: () => <span />,
   Edit: () => <span />,
   Link: () => <span />,
   OverflowMenuVertical: () => <span />,
   TrashCan: () => <span />,
+  Upload: () => <span />,
   View: () => <span />,
   ViewOff: () => <span />,
 }));
 
-vi.mock('lucide-react', () => ({
-  ChevronDown: () => <span />,
-  ChevronUp: () => <span />,
-  Download: () => <span />,
-  Eye: () => <span />,
-  FileCheck2: () => <span />,
-  FileText: () => <span />,
-  GripVertical: () => <span />,
-  Loader2: () => <span />,
-  Plus: () => <span />,
-  Save: () => <span />,
-  Trash2: () => <span />,
-  Upload: () => <span />,
-}));
-
 vi.mock('./logos', () => ({
+  CCPA: () => <span />,
+  CCPAInProgress: () => <span />,
   GDPR: () => <span />,
+  GDPRInProgress: () => <span />,
   HIPAA: () => <span />,
+  HIPAAInProgress: () => <span />,
   ISO27001: () => <span />,
+  ISO27001InProgress: () => <span />,
   ISO42001: () => <span />,
+  ISO42001InProgress: () => <span />,
   ISO9001: () => <span />,
+  ISO9001InProgress: () => <span />,
   NEN7510: () => <span />,
+  NEN7510InProgress: () => <span />,
   PCIDSS: () => <span />,
+  PCIDSSInProgress: () => <span />,
+  PIPEDA: () => <span />,
+  PIPEDAInProgress: () => <span />,
   SOC2Type1: () => <span />,
+  SOC2Type1InProgress: () => <span />,
   SOC2Type2: () => <span />,
+  SOC2Type2InProgress: () => <span />,
+  SOC3: () => <span />,
+  SOC3InProgress: () => <span />,
 }));
 
-vi.mock('./UpdateTrustFavicon', () => ({
-  UpdateTrustFavicon: () => <div data-testid="update-trust-favicon" />,
+vi.mock('./TrustPortalBrandingSettings', () => ({
+  TrustPortalBrandingSettings: () => <div data-testid="trust-portal-branding-settings" />,
 }));
 
 vi.mock('next/image', () => ({
@@ -218,6 +231,10 @@ describe('TrustPortalSwitch permission gating', () => {
     nen7510Status: 'started' as const,
     iso9001: false,
     iso9001Status: 'started' as const,
+    pipeda: false,
+    pipedaStatus: 'started' as const,
+    ccpa: false,
+    ccpaStatus: 'started' as const,
     faqs: [],
     additionalDocuments: [],
     overview: {
diff --git a/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/TrustPortalSwitch.tsx b/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/TrustPortalSwitch.tsx
index f8abc03618..dff2d249a3 100644
--- a/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/TrustPortalSwitch.tsx
+++ b/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/TrustPortalSwitch.tsx
@@ -24,20 +24,19 @@ import {
   TooltipContent,
   TooltipTrigger,
 } from '@trycompai/design-system';
+import { CertificateCheck, Download, Upload, View } from '@trycompai/design-system/icons';
 import { Form } from '@trycompai/ui/form';
-import { Download, Eye, FileCheck2, Upload } from 'lucide-react';
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { useForm } from 'react-hook-form';
 import { toast } from 'sonner';
 import { z } from 'zod';
-import { BrandSettings } from './BrandSettings';
 import {
+  CCPA,
+  CCPAInProgress,
   GDPR,
   GDPRInProgress,
   HIPAA,
   HIPAAInProgress,
-  CCPA,
-  CCPAInProgress,
   ISO27001,
   ISO27001InProgress,
   ISO42001,
@@ -61,11 +60,11 @@ import {
   TrustPortalAdditionalDocumentsSection,
   type TrustPortalDocument,
 } from './TrustPortalAdditionalDocumentsSection';
+import { TrustPortalBrandingSettings } from './TrustPortalBrandingSettings';
 import { TrustPortalCustomLinks } from './TrustPortalCustomLinks';
 import { TrustPortalFaqBuilder } from './TrustPortalFaqBuilder';
 import { TrustPortalOverview } from './TrustPortalOverview';
 import { TrustPortalVendors } from './TrustPortalVendors';
-import { UpdateTrustFavicon } from './UpdateTrustFavicon';
 
 // Client-side form schema (includes all fields for form state)
 const trustPortalSwitchSchema = z.object({
@@ -149,15 +148,7 @@ type TrustCustomLink = {
 };
 
 type ComplianceBadge = {
-  type:
-    | 'soc2'
-    | 'iso27001'
-    | 'iso42001'
-    | 'gdpr'
-    | 'hipaa'
-    | 'pci_dss'
-    | 'nen7510'
-    | 'iso9001';
+  type: 'soc2' | 'iso27001' | 'iso42001' | 'gdpr' | 'hipaa' | 'pci_dss' | 'nen7510' | 'iso9001';
   verified: boolean;
 };
 
@@ -1022,9 +1013,12 @@ export function TrustPortalSwitch({
 
           {/* Branding Tab */}
           <TabsContent value="branding">
-            <div className="pt-6 space-y-6">
-              <UpdateTrustFavicon currentFaviconUrl={faviconUrl ?? null} />
-              <BrandSettings orgId={orgId} primaryColor={primaryColor ?? null} />
+            <div className="pt-6">
+              <TrustPortalBrandingSettings
+                enabled={enabled}
+                primaryColor={primaryColor ?? null}
+                faviconUrl={faviconUrl ?? null}
+              />
             </div>
           </TabsContent>
 
@@ -1340,7 +1334,7 @@ function ComplianceFramework({
                 <div className="rounded-lg bg-muted/40 border border-border/50 p-4 space-y-3">
                   <div className="flex items-center gap-3 animate-in fade-in-0 slide-in-from-top-1 duration-200">
                     <div className="flex h-10 w-10 shrink-0 items-center justify-center rounded-lg bg-primary/10">
-                      <FileCheck2 className="h-5 w-5 text-primary" />
+                      <CertificateCheck className="h-5 w-5 text-primary" />
                     </div>
                     <div className="flex-1 min-w-0">
                       <p className="text-sm font-medium text-foreground truncate">{fileName}</p>
@@ -1367,7 +1361,7 @@ function ComplianceFramework({
                             />
                           }
                         >
-                          <Eye className="h-3.5 w-3.5" />
+                          <View className="h-3.5 w-3.5" />
                           View
                         </TooltipTrigger>
                         <TooltipContent>Open certificate in new tab</TooltipContent>
diff --git a/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/UpdateTrustFavicon.test.tsx b/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/UpdateTrustFavicon.test.tsx
index 91e99af222..b4f98f2112 100644
--- a/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/UpdateTrustFavicon.test.tsx
+++ b/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/UpdateTrustFavicon.test.tsx
@@ -1,11 +1,21 @@
-import { render, screen } from '@testing-library/react';
-import { beforeEach, describe, expect, it, vi } from 'vitest';
 import {
-  setMockPermissions,
   ADMIN_PERMISSIONS,
   AUDITOR_PERMISSIONS,
   mockHasPermission,
+  setMockPermissions,
 } from '@/test-utils/mocks/permissions';
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const navigationMock = vi.hoisted(() => ({
+  refresh: vi.fn(),
+}));
+
+const trustPortalSettingsMock = vi.hoisted(() => ({
+  uploadFavicon: vi.fn(),
+  removeFavicon: vi.fn(),
+}));
 
 vi.mock('@/hooks/use-permissions', () => ({
   usePermissions: () => ({
@@ -16,11 +26,15 @@ vi.mock('@/hooks/use-permissions', () => ({
 
 vi.mock('@/hooks/use-trust-portal-settings', () => ({
   useTrustPortalSettings: () => ({
-    uploadFavicon: vi.fn(),
-    removeFavicon: vi.fn(),
+    uploadFavicon: trustPortalSettingsMock.uploadFavicon,
+    removeFavicon: trustPortalSettingsMock.removeFavicon,
   }),
 }));
 
+vi.mock('next/navigation', () => ({
+  useRouter: () => ({ refresh: navigationMock.refresh }),
+}));
+
 vi.mock('next/image', () => ({
   default: (props: Record<string, unknown>) => (
     // eslint-disable-next-line @next/next/no-img-element
@@ -40,55 +54,42 @@ import { UpdateTrustFavicon } from './UpdateTrustFavicon';
 describe('UpdateTrustFavicon permission gating', () => {
   beforeEach(() => {
     vi.clearAllMocks();
+    trustPortalSettingsMock.uploadFavicon.mockResolvedValue({
+      success: true,
+      faviconUrl: 'https://example.com/new-favicon.png',
+    });
+    trustPortalSettingsMock.removeFavicon.mockResolvedValue({ success: true });
   });
 
   it('shows upload button when user has portal:update permission', () => {
     setMockPermissions(ADMIN_PERMISSIONS);
     render(<UpdateTrustFavicon currentFaviconUrl={null} />);
-    expect(
-      screen.getByRole('button', { name: /upload favicon/i }),
-    ).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: /upload favicon/i })).toBeInTheDocument();
   });
 
   it('hides upload button when user lacks portal:update permission', () => {
     setMockPermissions(AUDITOR_PERMISSIONS);
     render(<UpdateTrustFavicon currentFaviconUrl={null} />);
-    expect(
-      screen.queryByRole('button', { name: /upload favicon/i }),
-    ).not.toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: /upload favicon/i })).not.toBeInTheDocument();
   });
 
   it('shows remove button when user has portal:update and a favicon exists', () => {
     setMockPermissions(ADMIN_PERMISSIONS);
-    render(
-      <UpdateTrustFavicon currentFaviconUrl="https://example.com/favicon.ico" />,
-    );
-    expect(
-      screen.getByRole('button', { name: /remove/i }),
-    ).toBeInTheDocument();
+    render(<UpdateTrustFavicon currentFaviconUrl="https://example.com/favicon.ico" />);
+    expect(screen.getByRole('button', { name: /remove/i })).toBeInTheDocument();
   });
 
   it('hides remove button when user lacks portal:update even if favicon exists', () => {
     setMockPermissions(AUDITOR_PERMISSIONS);
-    render(
-      <UpdateTrustFavicon currentFaviconUrl="https://example.com/favicon.ico" />,
-    );
-    expect(
-      screen.queryByRole('button', { name: /remove/i }),
-    ).not.toBeInTheDocument();
+    render(<UpdateTrustFavicon currentFaviconUrl="https://example.com/favicon.ico" />);
+    expect(screen.queryByRole('button', { name: /remove/i })).not.toBeInTheDocument();
   });
 
   it('hides both buttons when user has no permissions', () => {
     setMockPermissions({});
-    render(
-      <UpdateTrustFavicon currentFaviconUrl="https://example.com/favicon.ico" />,
-    );
-    expect(
-      screen.queryByRole('button', { name: /upload favicon/i }),
-    ).not.toBeInTheDocument();
-    expect(
-      screen.queryByRole('button', { name: /remove/i }),
-    ).not.toBeInTheDocument();
+    render(<UpdateTrustFavicon currentFaviconUrl="https://example.com/favicon.ico" />);
+    expect(screen.queryByRole('button', { name: /upload favicon/i })).not.toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: /remove/i })).not.toBeInTheDocument();
   });
 
   it('renders title regardless of permissions', () => {
@@ -96,4 +97,51 @@ describe('UpdateTrustFavicon permission gating', () => {
     render(<UpdateTrustFavicon currentFaviconUrl={null} />);
     expect(screen.getByText('Trust Portal Favicon')).toBeInTheDocument();
   });
+
+  it('uploads a favicon and refreshes settings', async () => {
+    setMockPermissions(ADMIN_PERMISSIONS);
+    const handleFaviconChange = vi.fn();
+    const { container } = render(
+      <UpdateTrustFavicon currentFaviconUrl={null} onFaviconChange={handleFaviconChange} />,
+    );
+
+    const fileInput = container.querySelector('input[type="file"]');
+    if (!(fileInput instanceof HTMLInputElement)) {
+      throw new Error('file input not found');
+    }
+
+    const file = new File(['favicon'], 'favicon.png', { type: 'image/png' });
+    await userEvent.upload(fileInput, file);
+
+    await waitFor(() => {
+      expect(trustPortalSettingsMock.uploadFavicon).toHaveBeenCalledWith(
+        'favicon.png',
+        'image/png',
+        expect.any(String),
+      );
+    });
+    expect(handleFaviconChange).toHaveBeenCalledWith('https://example.com/new-favicon.png');
+    expect(navigationMock.refresh).toHaveBeenCalled();
+  });
+
+  it('removes a favicon and refreshes settings', async () => {
+    setMockPermissions(ADMIN_PERMISSIONS);
+    const user = userEvent.setup();
+    const handleFaviconChange = vi.fn();
+
+    render(
+      <UpdateTrustFavicon
+        currentFaviconUrl="https://example.com/favicon.ico"
+        onFaviconChange={handleFaviconChange}
+      />,
+    );
+
+    await user.click(screen.getByRole('button', { name: /remove/i }));
+
+    await waitFor(() => {
+      expect(trustPortalSettingsMock.removeFavicon).toHaveBeenCalled();
+    });
+    expect(handleFaviconChange).toHaveBeenCalledWith(null);
+    expect(navigationMock.refresh).toHaveBeenCalled();
+  });
 });
diff --git a/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/UpdateTrustFavicon.tsx b/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/UpdateTrustFavicon.tsx
index b2a6a7c5ad..cddbe5c0e5 100644
--- a/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/UpdateTrustFavicon.tsx
+++ b/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/UpdateTrustFavicon.tsx
@@ -2,17 +2,31 @@
 
 import { usePermissions } from '@/hooks/use-permissions';
 import { useTrustPortalSettings } from '@/hooks/use-trust-portal-settings';
-import { Button, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from '@trycompai/design-system';
+import {
+  Button,
+  Card,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+} from '@trycompai/design-system';
 import { Add, TrashCan } from '@trycompai/design-system/icons';
 import Image from 'next/image';
-import { useCallback, useRef, useState } from 'react';
+import { useRouter } from 'next/navigation';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import { toast } from 'sonner';
 
 interface UpdateTrustFaviconProps {
   currentFaviconUrl: string | null;
+  onFaviconChange?: (faviconUrl: string | null) => void;
 }
 
-export function UpdateTrustFavicon({ currentFaviconUrl }: UpdateTrustFaviconProps) {
+export function UpdateTrustFavicon({
+  currentFaviconUrl,
+  onFaviconChange,
+}: UpdateTrustFaviconProps) {
+  const router = useRouter();
   const { hasPermission } = usePermissions();
   const canUpdatePortal = hasPermission('trust', 'update');
   const { uploadFavicon, removeFavicon } = useTrustPortalSettings();
@@ -21,24 +35,29 @@ export function UpdateTrustFavicon({ currentFaviconUrl }: UpdateTrustFaviconProp
   const [isRemoving, setIsRemoving] = useState(false);
   const fileInputRef = useRef<HTMLInputElement>(null);
 
+  useEffect(() => {
+    setPreviewUrl(currentFaviconUrl);
+  }, [currentFaviconUrl]);
+
   const handleUpload = useCallback(
     async (fileName: string, fileType: string, fileData: string) => {
       setIsUploading(true);
       try {
         const result = await uploadFavicon(fileName, fileType, fileData);
-        if (result && typeof result === 'object' && 'faviconUrl' in result) {
-          setPreviewUrl((result as { faviconUrl: string }).faviconUrl);
+        if (!result?.faviconUrl) {
+          throw new Error('Unexpected API response');
         }
+        setPreviewUrl(result.faviconUrl);
+        onFaviconChange?.(result.faviconUrl);
+        router.refresh();
         toast.success('Favicon updated');
       } catch (error) {
-        toast.error(
-          error instanceof Error ? error.message : 'Failed to upload favicon',
-        );
+        toast.error(error instanceof Error ? error.message : 'Failed to upload favicon');
       } finally {
         setIsUploading(false);
       }
     },
-    [uploadFavicon],
+    [onFaviconChange, router, uploadFavicon],
   );
 
   const handleRemove = useCallback(async () => {
@@ -46,13 +65,15 @@ export function UpdateTrustFavicon({ currentFaviconUrl }: UpdateTrustFaviconProp
     try {
       await removeFavicon();
       setPreviewUrl(null);
+      onFaviconChange?.(null);
+      router.refresh();
       toast.success('Favicon removed');
     } catch {
       toast.error('Failed to remove favicon');
     } finally {
       setIsRemoving(false);
     }
-  }, [removeFavicon]);
+  }, [onFaviconChange, removeFavicon, router]);
 
   const handleFileChange = async (e: React.ChangeEvent<HTMLInputElement>) => {
     const file = e.target.files?.[0];
@@ -154,7 +175,8 @@ export function UpdateTrustFavicon({ currentFaviconUrl }: UpdateTrustFaviconProp
       </CardContent>
       <CardFooter>
         <div className="text-muted-foreground text-xs">
-          Recommended: Square image (16x16, 32x32, or 180x180px). Formats: .ico, .png, or .svg. Max 100KB.
+          Recommended: Square image (16x16, 32x32, or 180x180px). Formats: .ico, .png, or .svg. Max
+          100KB.
         </div>
       </CardFooter>
     </Card>

From e89b189c18b147b7b89fa3e8a6f67495a04960c2 Mon Sep 17 00:00:00 2001
From: Tofik Hasanov <annexcies@gmail.com>
Date: Fri, 22 May 2026 10:44:36 -0400
Subject: [PATCH 2/6] fix(trust): allow clearing brand color

---
 .../components/BrandSettings.test.tsx         | 32 ++++++++++++++++++
 .../components/BrandSettings.tsx              | 33 +++++++++++--------
 2 files changed, 51 insertions(+), 14 deletions(-)

diff --git a/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/BrandSettings.test.tsx b/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/BrandSettings.test.tsx
index 33b7102c1f..af69fde670 100644
--- a/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/BrandSettings.test.tsx
+++ b/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/BrandSettings.test.tsx
@@ -106,4 +106,36 @@ describe('BrandSettings permission gating', () => {
     expect(handlePrimaryColorChange).toHaveBeenCalledWith('#00FF00');
     expect(navigationMock.refresh).toHaveBeenCalled();
   });
+
+  it('persists an empty brand color as a reset to default branding', async () => {
+    setMockPermissions(ADMIN_PERMISSIONS);
+    const handlePrimaryColorChange = vi.fn();
+
+    render(<BrandSettings {...defaultProps} onPrimaryColorChange={handlePrimaryColorChange} />);
+
+    const textInput = screen.getByRole('textbox');
+    fireEvent.change(textInput, { target: { value: '' } });
+
+    await waitFor(() => {
+      expect(trustPortalSettingsMock.updateToggleSettings).toHaveBeenCalledWith({
+        enabled: true,
+        primaryColor: '',
+      });
+    });
+    expect(handlePrimaryColorChange).toHaveBeenCalledWith(null);
+    expect(navigationMock.refresh).toHaveBeenCalled();
+  });
+
+  it('does not persist an invalid brand color', () => {
+    setMockPermissions(ADMIN_PERMISSIONS);
+
+    render(<BrandSettings {...defaultProps} />);
+
+    const textInput = screen.getByRole('textbox');
+    fireEvent.change(textInput, { target: { value: 'zzzzzz' } });
+    fireEvent.blur(textInput);
+
+    expect(trustPortalSettingsMock.updateToggleSettings).not.toHaveBeenCalled();
+    expect(navigationMock.refresh).not.toHaveBeenCalled();
+  });
 });
diff --git a/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/BrandSettings.tsx b/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/BrandSettings.tsx
index 85fcfed401..3fd2089bb4 100644
--- a/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/BrandSettings.tsx
+++ b/apps/app/src/app/(app)/[orgId]/trust/portal-settings/components/BrandSettings.tsx
@@ -33,10 +33,15 @@ interface BrandSettingsProps {
   onPrimaryColorChange?: (primaryColor: string | null) => void;
 }
 
-function normalizePrimaryColor(value: unknown): string | null {
-  if (typeof value !== 'string' || value.length === 0) return null;
-  if (!HEX_COLOR_PATTERN.test(value)) return null;
-  return value.toUpperCase();
+function normalizePrimaryColor(value: unknown): string | null | undefined {
+  if (value === null) return null;
+  if (typeof value !== 'string') return undefined;
+
+  const trimmedValue = value.trim();
+  if (trimmedValue.length === 0) return null;
+  if (!HEX_COLOR_PATTERN.test(trimmedValue)) return undefined;
+
+  return trimmedValue.toUpperCase();
 }
 
 export function BrandSettings({
@@ -57,7 +62,7 @@ export function BrandSettings({
   });
 
   const lastSaved = useRef<{ [key: string]: string | null }>({
-    primaryColor: normalizePrimaryColor(primaryColor),
+    primaryColor: normalizePrimaryColor(primaryColor) ?? null,
   });
 
   const savingRef = useRef<{ [key: string]: boolean }>({
@@ -71,7 +76,7 @@ export function BrandSettings({
       }
 
       const nextPrimaryColor = normalizePrimaryColor(value);
-      if (!nextPrimaryColor) {
+      if (nextPrimaryColor === undefined) {
         return;
       }
 
@@ -82,7 +87,7 @@ export function BrandSettings({
             enabled,
             primaryColor:
               field === 'primaryColor'
-                ? nextPrimaryColor
+                ? (nextPrimaryColor ?? '')
                 : (form.getValues('primaryColor') ?? undefined),
           });
           toast.success('Brand settings updated');
@@ -106,7 +111,7 @@ export function BrandSettings({
     const normalizedPrimaryColor = normalizePrimaryColor(primaryColor);
     form.reset({ primaryColor: normalizedPrimaryColor ?? undefined });
     setPrimaryColorValue(normalizedPrimaryColor ?? '');
-    lastSaved.current.primaryColor = normalizedPrimaryColor;
+    lastSaved.current.primaryColor = normalizedPrimaryColor ?? null;
   }, [form, primaryColor]);
 
   useEffect(() => {
@@ -116,8 +121,8 @@ export function BrandSettings({
       !savingRef.current.primaryColor
     ) {
       const normalizedPrimaryColor = normalizePrimaryColor(debouncedPrimaryColor);
-      if (normalizedPrimaryColor) {
-        form.setValue('primaryColor', normalizedPrimaryColor);
+      if (normalizedPrimaryColor !== undefined) {
+        form.setValue('primaryColor', normalizedPrimaryColor ?? undefined);
         void autoSave('primaryColor', normalizedPrimaryColor);
       }
     }
@@ -126,12 +131,12 @@ export function BrandSettings({
   const handlePrimaryColorBlur = useCallback(
     (e: React.FocusEvent<HTMLInputElement>) => {
       const value = normalizePrimaryColor(e.target.value);
-      if (!value) {
+      if (value === undefined) {
         toast.error('Enter a valid hex color');
         return;
       }
-      form.setValue('primaryColor', value);
-      setPrimaryColorValue(value);
+      form.setValue('primaryColor', value ?? undefined);
+      setPrimaryColorValue(value ?? '');
       void autoSave('primaryColor', value);
     },
     [form, autoSave],
@@ -181,7 +186,7 @@ export function BrandSettings({
                     <div className="flex-1">
                       <div className="font-mono">
                         <Input
-                          value={primaryColorValue?.toUpperCase() || DEFAULT_PRIMARY_COLOR}
+                          value={primaryColorValue?.toUpperCase() ?? ''}
                           onChange={(e) => {
                             let value = e.target.value;
                             if (value.length > 0 && !value.startsWith('#')) {

From ddb4b725230df49cd6a9987d23aba385609cfdde Mon Sep 17 00:00:00 2001
From: Tofik Hasanov <annexcies@gmail.com>
Date: Fri, 22 May 2026 10:53:09 -0400
Subject: [PATCH 3/6] fix(people): remove background check exception label

---
 .../components/BackgroundCheckPathCard.tsx    |  8 ++--
 .../components/BackgroundCheckV1Page.tsx      | 37 ++++++++-----------
 .../EmployeeBackgroundCheck.test.tsx          |  1 +
 3 files changed, 19 insertions(+), 27 deletions(-)

diff --git a/apps/app/src/app/(app)/[orgId]/people/[employeeId]/components/BackgroundCheckPathCard.tsx b/apps/app/src/app/(app)/[orgId]/people/[employeeId]/components/BackgroundCheckPathCard.tsx
index 7fdc36afad..e7dee2ff32 100644
--- a/apps/app/src/app/(app)/[orgId]/people/[employeeId]/components/BackgroundCheckPathCard.tsx
+++ b/apps/app/src/app/(app)/[orgId]/people/[employeeId]/components/BackgroundCheckPathCard.tsx
@@ -13,7 +13,7 @@ export interface PathCardProps {
   iconTone?: 'default' | 'warning';
   title: string;
   description: string;
-  meta: ReactNode;
+  meta?: ReactNode;
   disabled?: boolean;
 }
 
@@ -57,9 +57,7 @@ export function BackgroundCheckPathCard({
       className={cn(
         'group relative rounded-[var(--radius)] border px-4 py-3.5 transition-colors duration-200 ease-out',
         'outline-none focus-visible:ring-[3px] focus-visible:ring-primary/20',
-        disabled
-          ? 'cursor-not-allowed opacity-60'
-          : 'cursor-pointer hover:border-muted-foreground',
+        disabled ? 'cursor-not-allowed opacity-60' : 'cursor-pointer hover:border-muted-foreground',
         selected
           ? 'border-primary bg-[oklch(0.985_0.012_167)] shadow-[inset_0_0_0_1px_var(--primary)]'
           : 'border-border bg-background',
@@ -81,7 +79,7 @@ export function BackgroundCheckPathCard({
       </div>
       <div className="mb-[3px] text-sm font-normal text-foreground">{title}</div>
       <div className="mb-2 text-[13px] leading-[1.4] text-muted-foreground">{description}</div>
-      <div className="font-mono text-xs">{meta}</div>
+      {meta ? <div className="font-mono text-xs">{meta}</div> : null}
     </div>
   );
 }
diff --git a/apps/app/src/app/(app)/[orgId]/people/[employeeId]/components/BackgroundCheckV1Page.tsx b/apps/app/src/app/(app)/[orgId]/people/[employeeId]/components/BackgroundCheckV1Page.tsx
index 952c5272e1..8fd80206c6 100644
--- a/apps/app/src/app/(app)/[orgId]/people/[employeeId]/components/BackgroundCheckV1Page.tsx
+++ b/apps/app/src/app/(app)/[orgId]/people/[employeeId]/components/BackgroundCheckV1Page.tsx
@@ -1,20 +1,11 @@
 'use client';
 
 import { Text } from '@trycompai/design-system';
-import { Attachment, Flash, Security, Warning } from '@trycompai/design-system/icons';
+import { Attachment, Flash, Security } from '@trycompai/design-system/icons';
 import { useState } from 'react';
-import {
-  BackgroundCheckAttachForm,
-  type AttachFormValues,
-} from './BackgroundCheckAttachForm';
-import {
-  BackgroundCheckExemptForm,
-  type ExemptFormValues,
-} from './BackgroundCheckExemptForm';
-import {
-  BackgroundCheckOrderForm,
-  type OrderFormValues,
-} from './BackgroundCheckOrderForm';
+import { BackgroundCheckAttachForm, type AttachFormValues } from './BackgroundCheckAttachForm';
+import { BackgroundCheckExemptForm, type ExemptFormValues } from './BackgroundCheckExemptForm';
+import { BackgroundCheckOrderForm, type OrderFormValues } from './BackgroundCheckOrderForm';
 import { BackgroundCheckPathCard } from './BackgroundCheckPathCard';
 import { BackgroundCheckScopePanel } from './BackgroundCheckScopePanel';
 import { BackgroundCheckStatusStrip } from './BackgroundCheckStatusStrip';
@@ -90,7 +81,11 @@ export function BackgroundCheckV1Page(props: V1PageProps) {
         How would you like to proceed?
       </div>
 
-      <div role="radiogroup" aria-label="How would you like to proceed?" className="mb-6 grid gap-3 md:grid-cols-3">
+      <div
+        role="radiogroup"
+        aria-label="How would you like to proceed?"
+        className="mb-6 grid gap-3 md:grid-cols-3"
+      >
         <BackgroundCheckPathCard
           selected={selectedPath === 'order'}
           onSelect={() => handleSelect('order')}
@@ -116,12 +111,6 @@ export function BackgroundCheckV1Page(props: V1PageProps) {
           icon={Security}
           title="Mark as exempt"
           description="This employee won't be required to pass a check."
-          meta={
-            <span className="inline-flex items-center gap-1 text-[var(--warning)]">
-              <Warning size={12} />
-              Logs a compliance exception
-            </span>
-          }
         />
       </div>
 
@@ -141,7 +130,9 @@ export function BackgroundCheckV1Page(props: V1PageProps) {
                 Boolean(props.orderValues.employeeEmail)
               }
               disabledReason={
-                !props.hasAllowance ? "You're out of credits. Choose a plan to continue." : undefined
+                !props.hasAllowance
+                  ? "You're out of credits. Choose a plan to continue."
+                  : undefined
               }
             />
           )}
@@ -152,7 +143,9 @@ export function BackgroundCheckV1Page(props: V1PageProps) {
               onSubmit={props.onAttachSubmit}
               submitting={props.isAttachSubmitting}
               canSubmit={
-                props.canRequest && Boolean(props.attachValues.vendor) && Boolean(props.attachValues.file)
+                props.canRequest &&
+                Boolean(props.attachValues.vendor) &&
+                Boolean(props.attachValues.file)
               }
             />
           )}
diff --git a/apps/app/src/app/(app)/[orgId]/people/[employeeId]/components/EmployeeBackgroundCheck.test.tsx b/apps/app/src/app/(app)/[orgId]/people/[employeeId]/components/EmployeeBackgroundCheck.test.tsx
index 16e427dbaa..e6ea6fbe95 100644
--- a/apps/app/src/app/(app)/[orgId]/people/[employeeId]/components/EmployeeBackgroundCheck.test.tsx
+++ b/apps/app/src/app/(app)/[orgId]/people/[employeeId]/components/EmployeeBackgroundCheck.test.tsx
@@ -93,6 +93,7 @@ describe('EmployeeBackgroundCheck — V1 two-paths', () => {
     expect(screen.getByText('Order a new check')).toBeInTheDocument();
     expect(screen.getByText('Attach an existing report')).toBeInTheDocument();
     expect(screen.getByText('Mark as exempt')).toBeInTheDocument();
+    expect(screen.queryByText('Logs a compliance exception')).not.toBeInTheDocument();
 
     const orderCard = screen.getByRole('radio', { name: /Order a new check/i });
     expect(orderCard).toHaveAttribute('aria-checked', 'true');

From ebce8a3e6662627ee043a4ed6766d74ece84a724 Mon Sep 17 00:00:00 2001
From: Tofik Hasanov <annexcies@gmail.com>
Date: Fri, 22 May 2026 11:28:49 -0400
Subject: [PATCH 4/6] feat(cloud-tests): manual-steps generator + broader
 auto-fix pattern coverage
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds the building blocks for the manual-steps fallback shipped in the
next two commits, plus broadens the pattern matcher and actionable-
prefix list so more findings exercise the existing auto-repair paths
instead of bailing out:

1. New `AiRemediationService.generateManualSteps(...)`: takes the
   finding, the failed plan, and the concrete failure reason, and
   returns real customer-facing manual instructions via Sonnet (kept
   on the cheap model since this only fires on failure paths and is
   plain natural language). Hard fallback to the adapter remediation
   text if the AI call itself throws, so the customer never sees a
   raw error.

2. `looksLikeValidationError` now matches `MissingParameter`,
   "must contain the parameter", "missing parameter",
   "parameter is required", "must specify" — covers the EC2-style
   error wording that the previous regex missed.

3. `ACTIONABLE_PREFIXES` adds `Authorize`, `Revoke`, `Allow`, `Deny`,
   `Disable`, `Detach`, `Add`, `Remove`, `Register`, `Deregister`,
   `Tag`, `Untag`. Security-group / IAM-style fix plans now produce
   meaningful `willChange` diffs instead of `{}` `{}`.

4. Exports `FindingContext` so it can be reused by the orchestration
   service (next commit) when invoking the new fallback path.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../ai-remediation.service.spec.ts            | 109 ++++++++++++++++
 .../cloud-security/ai-remediation.service.ts  | 117 +++++++++++++++++-
 .../cloud-security/aws-command-executor.ts    |   6 +-
 3 files changed, 230 insertions(+), 2 deletions(-)

diff --git a/apps/api/src/cloud-security/ai-remediation.service.spec.ts b/apps/api/src/cloud-security/ai-remediation.service.spec.ts
index aa0774e67f..22bb90eb62 100644
--- a/apps/api/src/cloud-security/ai-remediation.service.spec.ts
+++ b/apps/api/src/cloud-security/ai-remediation.service.spec.ts
@@ -399,3 +399,112 @@ describe('AiRemediationService.refineStepFromError', () => {
     expect(callArgs.temperature).toBe(0);
   });
 });
+
+describe('AiRemediationService.generateManualSteps', () => {
+  const generateObjectMock = generateObject as unknown as jest.Mock;
+
+  const finding = {
+    title: 'No CloudTrail trails configured',
+    description: 'Account has no active CloudTrail trails.',
+    severity: 'high',
+    resourceType: 'AwsAccount',
+    resourceId: 'account-level',
+    remediation: 'Create a multi-region trail with log file validation.',
+    findingKey: 'cloudtrail-no-trails',
+    evidence: { awsAccountId: '123456789012', region: 'us-east-1' },
+  };
+
+  beforeEach(() => {
+    generateObjectMock.mockReset();
+  });
+
+  it('returns AI-generated guidedSteps + reason in the happy path', async () => {
+    generateObjectMock.mockResolvedValueOnce({
+      object: {
+        guidedSteps: [
+          'Open AWS Console → CloudTrail → Trails.',
+          'Click "Create trail" and name it compai-cloudtrail.',
+          'Enable multi-region and log file validation, then Save.',
+        ],
+        reason:
+          'Auto-fix could not generate valid create-trail params for this account.',
+      },
+    });
+
+    const result = await new AiRemediationService().generateManualSteps({
+      finding,
+      failureReason: 'Required param "S3BucketName" is missing or empty',
+    });
+
+    expect(result.guidedSteps).toHaveLength(3);
+    expect(result.guidedSteps[0]).toMatch(/CloudTrail/);
+    expect(result.reason).toMatch(/Auto-fix could not/);
+  });
+
+  it('falls back to the adapter remediation text when the AI call throws', async () => {
+    // Hard guarantee: even if the AI is down, the customer must see
+    // SOMETHING actionable instead of a raw error.
+    generateObjectMock.mockRejectedValueOnce(new Error('AI provider down'));
+
+    const result = await new AiRemediationService().generateManualSteps({
+      finding,
+      failureReason: 'anything',
+    });
+
+    expect(result.guidedSteps).toEqual([
+      'Create a multi-region trail with log file validation.',
+    ]);
+    expect(result.reason).toMatch(/Automatic fix is not available/i);
+  });
+
+  it('falls back to a generic step when there is no adapter remediation text either', async () => {
+    generateObjectMock.mockRejectedValueOnce(new Error('AI down'));
+
+    const result = await new AiRemediationService().generateManualSteps({
+      finding: { ...finding, remediation: null },
+      failureReason: 'x',
+    });
+
+    expect(result.guidedSteps).toHaveLength(1);
+    expect(result.guidedSteps[0]).toMatch(/AWS Console/i);
+  });
+
+  it('passes failing-step context to the model so manual steps reference the same resources', async () => {
+    generateObjectMock.mockResolvedValueOnce({
+      object: { guidedSteps: ['x'], reason: 'y' },
+    });
+
+    await new AiRemediationService().generateManualSteps({
+      finding,
+      failedPlan: {
+        canAutoFix: true,
+        risk: 'low',
+        description: 'd',
+        currentState: {},
+        proposedState: {},
+        requiredPermissions: [],
+        readSteps: [],
+        fixSteps: [
+          {
+            service: 's3',
+            command: 'CreateBucketCommand',
+            params: { Bucket: '' },
+            purpose: 'create log bucket',
+          },
+        ],
+        rollbackSteps: [],
+        rollbackSupported: false,
+        requiresAcknowledgment: false,
+      },
+      failureReason: 'Required param "Bucket" is missing or empty',
+    });
+
+    const callArgs = generateObjectMock.mock.calls[0][0];
+    // The prompt must include both the failing reason AND the original
+    // command so the model can translate it into a real manual step,
+    // not just regurgitate the finding text.
+    expect(callArgs.prompt).toContain('Required param "Bucket" is missing');
+    expect(callArgs.prompt).toContain('s3:CreateBucketCommand');
+    expect(callArgs.prompt).toContain('account-level');
+  });
+});
diff --git a/apps/api/src/cloud-security/ai-remediation.service.ts b/apps/api/src/cloud-security/ai-remediation.service.ts
index 85a788d057..0bafbbdb7d 100644
--- a/apps/api/src/cloud-security/ai-remediation.service.ts
+++ b/apps/api/src/cloud-security/ai-remediation.service.ts
@@ -1,6 +1,7 @@
 import { Injectable, Logger } from '@nestjs/common';
 import { generateObject } from 'ai';
 import { anthropic } from '@ai-sdk/anthropic';
+import { z } from 'zod';
 import {
   type FixPlan,
   type PermissionFix,
@@ -28,9 +29,13 @@ import {
 import { normalizeFixPlan } from './plan-normalizer';
 
 const MODEL = anthropic('claude-opus-4-6');
+// Cheaper, faster model for the manual-steps fallback. The output is pure
+// natural language with no SDK-call shape to validate, so the strongest
+// model is overkill — we just need clear instructions.
+const FALLBACK_MODEL = anthropic('claude-sonnet-4-5');
 const REMEDIATION_ROLE_NAME = 'CompAI-Remediator';
 
-interface FindingContext {
+export interface FindingContext {
   title: string;
   description: string | null;
   severity: string | null;
@@ -328,6 +333,104 @@ INSTRUCTIONS:
     }
   }
 
+  /**
+   * Generate real, user-actionable manual steps when auto-fix cannot
+   * proceed for a finding. Called by the remediation service as a
+   * fallback so customers never see a raw "Fix could not be applied —
+   * <cryptic error>" — they get clear instructions instead.
+   *
+   * Inputs:
+   *  - the finding (so the AI knows what's actually broken),
+   *  - the fix plan we tried to apply (so steps reference the same
+   *    resources / commands the customer expected),
+   *  - the concrete failure reason from validation or AWS execution.
+   *
+   * Output: ordered list of steps that the customer can copy-paste
+   * into AWS Console / CLI to resolve the finding manually.
+   *
+   * Uses Sonnet for cost — this only fires on the failure path and
+   * the output is plain natural language. On AI failure, falls back
+   * to the finding's `remediation` text so the customer at least sees
+   * the adapter's pre-baked guidance instead of an error.
+   */
+  async generateManualSteps(params: {
+    finding: FindingContext;
+    failedPlan?: FixPlan;
+    failureReason: string;
+  }): Promise<{ guidedSteps: string[]; reason: string }> {
+    const fallback = (): { guidedSteps: string[]; reason: string } => ({
+      guidedSteps: params.finding.remediation
+        ? [params.finding.remediation]
+        : [
+            'Review the finding in your AWS Console and apply the recommended remediation manually.',
+          ],
+      reason:
+        'Automatic fix is not available for this finding. Follow the guided steps to resolve it manually.',
+    });
+
+    try {
+      const stepsSummary = params.failedPlan?.fixSteps
+        ? params.failedPlan.fixSteps
+            .map(
+              (s, i) =>
+                `${i + 1}. ${s.service}:${s.command} — ${s.purpose}`,
+            )
+            .join('\n')
+        : '(no fix steps were generated)';
+
+      const { object } = await generateObject({
+        model: FALLBACK_MODEL,
+        schema: z.object({
+          guidedSteps: z
+            .array(z.string())
+            .min(1)
+            .describe(
+              'Ordered list of clear, copy-pasteable manual instructions the customer can follow in AWS Console or CLI. Each step is one concrete action.',
+            ),
+          reason: z
+            .string()
+            .describe(
+              'One-sentence summary of WHY automatic fix could not proceed — phrased for the customer, not for an engineer.',
+            ),
+        }),
+        system:
+          'You are an AWS security expert writing manual remediation steps for a customer whose automatic fix failed. Be concrete: name exact services, exact resources, and exact actions. Prefer AWS Console clicks over CLI when the path is short, but include CLI commands when they are clearer. Never reference SDK class names. Never apologize. Never speculate about "if the issue persists" — just give the steps.',
+        prompt: `A finding could not be auto-remediated. Generate clear manual steps the customer can follow.
+
+FINDING:
+- title: ${params.finding.title}
+- description: ${params.finding.description ?? '(none)'}
+- severity: ${params.finding.severity ?? '(unknown)'}
+- resource type: ${params.finding.resourceType}
+- resource id: ${params.finding.resourceId}
+- adapter remediation guidance: ${params.finding.remediation ?? '(none)'}
+- evidence: ${JSON.stringify(params.finding.evidence ?? {}, null, 2)}
+
+WHAT WE TRIED TO DO AUTOMATICALLY (do not just repeat — translate into customer-facing actions):
+${stepsSummary}
+
+WHY IT FAILED:
+${params.failureReason}
+
+Produce 3-8 ordered steps. Each step is a single concrete action the customer can perform in AWS Console or CLI. Reference the EXACT resource (${params.finding.resourceType} ${params.finding.resourceId}) and the EXACT region from evidence when relevant. End with a verification step so the customer knows they fixed it.`,
+        temperature: 0.2,
+      });
+
+      this.logger.log(
+        `Manual-steps fallback for ${params.finding.findingKey}: ${object.guidedSteps.length} step(s)`,
+      );
+      return {
+        guidedSteps: object.guidedSteps,
+        reason: object.reason,
+      };
+    } catch (err) {
+      this.logger.warn(
+        `Manual-steps AI call failed for ${params.finding.findingKey}; using adapter remediation as fallback. ${err instanceof Error ? err.message : String(err)}`,
+      );
+      return fallback();
+    }
+  }
+
   // ─── GCP Methods ──────────────────────────────────────────────────────
 
   async generateGcpFixPlan(finding: FindingContext): Promise<GcpFixPlan> {
@@ -556,6 +659,18 @@ const ACTIONABLE_PREFIXES = [
   'Enable',
   'Attach',
   'Set',
+  'Authorize',
+  'Revoke',
+  'Allow',
+  'Deny',
+  'Disable',
+  'Detach',
+  'Add',
+  'Remove',
+  'Register',
+  'Deregister',
+  'Tag',
+  'Untag',
 ] as const;
 
 /**
diff --git a/apps/api/src/cloud-security/aws-command-executor.ts b/apps/api/src/cloud-security/aws-command-executor.ts
index af6022e555..26a913a4c5 100644
--- a/apps/api/src/cloud-security/aws-command-executor.ts
+++ b/apps/api/src/cloud-security/aws-command-executor.ts
@@ -428,7 +428,11 @@ export function looksLikeValidationError(message: string): boolean {
     lower.includes('must be a valid') ||
     lower.includes('is required') ||
     lower.includes('missing required') ||
-    lower.includes('must contain')
+    lower.includes('must contain') ||
+    lower.includes('missingparameter') ||
+    lower.includes('missing parameter') ||
+    lower.includes('parameter is required') ||
+    lower.includes('must specify')
   );
 }
 

From 43253401d3f38780f1b31f45c381e22716a88a7c Mon Sep 17 00:00:00 2001
From: Tofik Hasanov <annexcies@gmail.com>
Date: Fri, 22 May 2026 11:29:04 -0400
Subject: [PATCH 5/6] fix(cloud-tests): graceful manual-step fallback for AWS
 auto-remediation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Customers were seeing raw "Fix could not be applied — <cryptic error>"
when the AI's refined plan failed pre-execution validation or AWS
rejected a step the executor couldn't auto-repair. The fix swaps every
throw inside executeRemediation for a graceful fallback that returns
real, AI-generated manual instructions in the existing `canAutoFix:false`
response shape — so the frontend renders them with the guided-steps UI
it already supports.

Concrete changes inside the AWS executeRemediation flow:

- Hoist `findingCtx` once at the top of the function so the refineFixPlan
  call, the per-step repair callback, and the new fallback path all see
  the same context.

- Read-step validation failures → fall back to manual instead of
  throwing. (Read steps rarely fail; skipping repair here keeps the
  flow simple.)

- "Refined plan has no fix steps" → fall back to manual instead of
  throwing. There's nothing to repair.

- Refined-plan fix-step validation failures → NEW: attempt one AI
  repair pass on the offending steps (`repairInvalidSteps` parses the
  step indices from the validator errors and calls `refineStepFromError`
  per step), then re-validate. If still invalid, fall back to manual.
  Closes the gap where the executor's own AI step-repair never got a
  chance because the plan never reached execution.

- Executor returned an unrecoverable error → fall back to manual,
  except for permission errors which still flow through the existing
  catch block (parseAwsPermissionError already has a polished
  fixScript payload — don't shadow it).

GCP and Azure remediation services have the same throw-on-validation
patterns and would benefit from the same treatment; left for a
follow-up PR per the original scope.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../src/cloud-security/remediation.service.ts | 219 +++++++++++++++---
 1 file changed, 187 insertions(+), 32 deletions(-)

diff --git a/apps/api/src/cloud-security/remediation.service.ts b/apps/api/src/cloud-security/remediation.service.ts
index bf29f982d5..7b7275b605 100644
--- a/apps/api/src/cloud-security/remediation.service.ts
+++ b/apps/api/src/cloud-security/remediation.service.ts
@@ -3,7 +3,10 @@ import { db, Prisma } from '@db';
 import { CredentialVaultService } from '../integration-platform/services/credential-vault.service';
 import { parseAwsPermissionError } from './remediation-error.utils';
 import { AWSSecurityService } from './providers/aws-security.service';
-import { AiRemediationService } from './ai-remediation.service';
+import {
+  AiRemediationService,
+  type FindingContext,
+} from './ai-remediation.service';
 import { GcpRemediationService } from './gcp-remediation.service';
 import { AzureRemediationService } from './azure-remediation.service';
 import {
@@ -498,11 +501,34 @@ export class RemediationService {
       },
     });
 
+    // Build the finding context once — reused by refineFixPlan, the
+    // step-repair callback, and the manual-steps fallback path.
+    const evidence = (finding.evidence ?? {}) as Record<string, unknown>;
+    const findingCtx: FindingContext = {
+      title: finding.title ?? 'Unknown',
+      description: finding.description,
+      severity: finding.severity,
+      resourceType: finding.resourceType,
+      resourceId: finding.resourceId,
+      remediation: finding.remediation,
+      findingKey: evidence.findingKey as string,
+      evidence,
+    };
+
     try {
       // Validate read steps first
       const readErrors = validatePlanSteps(plan.readSteps);
       if (readErrors.length > 0) {
-        throw new Error(`Invalid read steps: ${readErrors.join('; ')}`);
+        // Read step validation rarely fails (Get*/Describe* commands are
+        // simple), so don't attempt repair here — fall straight to
+        // manual steps using the original plan for context.
+        return await this.respondWithManualSteps({
+          actionId: action.id,
+          finding: findingCtx,
+          failedPlan: plan,
+          failureReason: `Read steps invalid: ${readErrors.join('; ')}`,
+          resourceId: finding.resourceId,
+        });
       }
 
       const remediationCreds =
@@ -523,18 +549,8 @@ export class RemediationService {
       );
 
       // Phase 2: Send real AWS state back to AI to generate EXACT fix steps
-      const evidence = (finding.evidence ?? {}) as Record<string, unknown>;
       const refinedPlan = await this.aiRemediationService.refineFixPlan({
-        finding: {
-          title: finding.title ?? 'Unknown',
-          description: finding.description,
-          severity: finding.severity,
-          resourceType: finding.resourceType,
-          resourceId: finding.resourceId,
-          remediation: finding.remediation,
-          findingKey: evidence.findingKey as string,
-          evidence,
-        },
+        finding: findingCtx,
         originalPlan: plan,
         realAwsState: previousState,
       });
@@ -561,11 +577,45 @@ export class RemediationService {
 
       // Validate refined fix steps
       if (!refinedPlan.fixSteps || refinedPlan.fixSteps.length === 0) {
-        throw new Error('AI refined plan has no fix steps. Cannot proceed.');
+        return await this.respondWithManualSteps({
+          actionId: action.id,
+          finding: findingCtx,
+          failedPlan: refinedPlan,
+          failureReason: 'AI refined plan produced no executable fix steps.',
+          resourceId: finding.resourceId,
+        });
       }
-      const fixErrors = validatePlanSteps(refinedPlan.fixSteps);
+
+      // First validation pass over the refined plan. If anything fails,
+      // attempt a single AI repair pass on the offending steps and
+      // re-validate — many "missing required param" cases the AI's
+      // first refinement misses are recoverable when given the exact
+      // error back as context. If repair still doesn't satisfy the
+      // validator, fall back to real manual steps so the customer
+      // never sees a raw "Invalid fix steps" error.
+      let plannedFix = refinedPlan;
+      let fixErrors = validatePlanSteps(plannedFix.fixSteps);
       if (fixErrors.length > 0) {
-        throw new Error(`Invalid fix steps: ${fixErrors.join('; ')}`);
+        this.logger.warn(
+          `Refined plan failed validation (${fixErrors.length} error(s)); attempting AI repair before falling back to manual.`,
+        );
+        plannedFix = await this.repairInvalidSteps({
+          plan: plannedFix,
+          validationErrors: fixErrors,
+          finding: findingCtx,
+          syntheticErrorPrefix:
+            'Pre-execution validator rejected this step:',
+        });
+        fixErrors = validatePlanSteps(plannedFix.fixSteps);
+      }
+      if (fixErrors.length > 0) {
+        return await this.respondWithManualSteps({
+          actionId: action.id,
+          finding: findingCtx,
+          failedPlan: plannedFix,
+          failureReason: `Even after AI repair the plan still has invalid steps: ${fixErrors.join('; ')}`,
+          resourceId: finding.resourceId,
+        });
       }
 
       // Phase 3: Execute the refined fix steps (now with REAL values).
@@ -575,27 +625,18 @@ export class RemediationService {
       // we give up — universal fix for "AI omitted a required param"
       // bugs that no per-command map can fully cover.
       const fixResult = await executePlanSteps({
-        steps: refinedPlan.fixSteps,
+        steps: plannedFix.fixSteps,
         credentials: remediationCreds,
         region,
-        autoRollbackSteps: refinedPlan.rollbackSteps,
+        autoRollbackSteps: plannedFix.rollbackSteps,
         repairStep: async ({ step, awsError }) =>
           this.aiRemediationService.refineStepFromError({
             step,
             awsError,
-            finding: {
-              title: finding.title ?? 'Unknown',
-              description: finding.description,
-              severity: finding.severity,
-              resourceType: finding.resourceType,
-              resourceId: finding.resourceId,
-              remediation: finding.remediation,
-              findingKey: evidence.findingKey as string,
-              evidence,
-            },
+            finding: findingCtx,
             planContext: {
-              fixSteps: refinedPlan.fixSteps,
-              readSteps: refinedPlan.readSteps,
+              fixSteps: plannedFix.fixSteps,
+              readSteps: plannedFix.readSteps,
             },
           }),
       });
@@ -607,7 +648,21 @@ export class RemediationService {
         this.logger.error(
           `Step params: ${JSON.stringify(fixResult.error.step.params).slice(0, 500)}`,
         );
-        throw new Error(fixResult.error.message);
+        // Permission errors still flow through the catch block below
+        // (parseAwsPermissionError produces the polished `fixScript`
+        // payload). For all OTHER unrecoverable execution errors fall
+        // back to manual steps so the customer sees real instructions
+        // rather than the raw AWS message.
+        if (parseAwsPermissionError(fixResult.error.message).isPermissionError) {
+          throw new Error(fixResult.error.message);
+        }
+        return await this.respondWithManualSteps({
+          actionId: action.id,
+          finding: findingCtx,
+          failedPlan: plannedFix,
+          failureReason: `Step ${fixResult.error.stepIndex + 1} (${fixResult.error.step.service}:${fixResult.error.step.command}) was rejected by AWS: ${fixResult.error.message}`,
+          resourceId: finding.resourceId,
+        });
       }
 
       const appliedState = {
@@ -615,7 +670,7 @@ export class RemediationService {
           command: `${r.step.service}:${r.step.command}`,
           output: r.output,
         })),
-        rollbackSteps: refinedPlan.rollbackSteps,
+        rollbackSteps: plannedFix.rollbackSteps,
       };
 
       await db.remediationAction.update({
@@ -1068,4 +1123,104 @@ export class RemediationService {
     if (withBucket !== required && existing.has(withBucket)) return true;
     return false;
   }
+
+  /**
+   * Best-effort AI repair pass over fix steps that failed validation.
+   * Parses step indices from the error strings (format
+   * "Step N (Command): ..."), then asks `refineStepFromError` to
+   * regenerate just those steps. If repair returns a new step, replace
+   * it; otherwise leave it alone for the caller to re-validate.
+   *
+   * Why this exists: `validatePlanSteps` runs BEFORE the executor, so
+   * the executor's own AI repair never gets a chance to fix
+   * empty-required-param plans. Without this pass, customers would see
+   * raw "Invalid fix steps" errors. With it, every plan gets one shot
+   * at AI repair before we fall back to manual guidance.
+   */
+  private async repairInvalidSteps(args: {
+    plan: FixPlan;
+    validationErrors: string[];
+    finding: FindingContext;
+    syntheticErrorPrefix: string;
+  }): Promise<FixPlan> {
+    const failingIndices = new Set<number>();
+    for (const err of args.validationErrors) {
+      const m = err.match(/^Step (\d+)\s*\(/);
+      if (m) failingIndices.add(Number(m[1]) - 1);
+    }
+    if (failingIndices.size === 0) return args.plan;
+
+    const newSteps = [...args.plan.fixSteps];
+    let anyRepaired = false;
+    for (const idx of failingIndices) {
+      const step = newSteps[idx];
+      if (!step) continue;
+      // Group the validator's complaints for THIS step into a synthetic
+      // "AWS error" the repair prompt can reason about.
+      const stepErrors = args.validationErrors
+        .filter((e) => e.startsWith(`Step ${idx + 1} `))
+        .join('; ');
+      const awsError = `${args.syntheticErrorPrefix} ${stepErrors}`;
+      const repaired = await this.aiRemediationService.refineStepFromError({
+        step,
+        awsError,
+        finding: args.finding,
+        planContext: {
+          fixSteps: args.plan.fixSteps,
+          readSteps: args.plan.readSteps,
+        },
+      });
+      if (repaired) {
+        newSteps[idx] = repaired;
+        anyRepaired = true;
+      }
+    }
+    return anyRepaired ? { ...args.plan, fixSteps: newSteps } : args.plan;
+  }
+
+  /**
+   * Universal "graceful fallback to manual steps" path. Called when an
+   * auto-fix attempt cannot succeed (validation rejects after repair,
+   * executor returns an unrecoverable error, plan has no usable steps).
+   *
+   * Persists the action as failed, generates real customer-facing
+   * manual instructions via the AI, and returns the same shape the
+   * frontend already renders for `canAutoFix: false` plans — so the
+   * customer sees clear steps instead of a raw error.
+   */
+  private async respondWithManualSteps(args: {
+    actionId: string;
+    finding: FindingContext;
+    failedPlan?: FixPlan;
+    failureReason: string;
+    resourceId: string;
+  }) {
+    const { guidedSteps, reason } =
+      await this.aiRemediationService.generateManualSteps({
+        finding: args.finding,
+        failedPlan: args.failedPlan,
+        failureReason: args.failureReason,
+      });
+
+    await db.remediationAction.update({
+      where: { id: args.actionId },
+      data: {
+        status: 'failed',
+        errorMessage: reason,
+      },
+    });
+
+    this.logger.warn(
+      `Manual-steps fallback for action ${args.actionId}: ${args.failureReason}`,
+    );
+
+    return {
+      actionId: args.actionId,
+      status: 'failed' as const,
+      resourceId: args.resourceId,
+      error: reason,
+      guidedSteps,
+      guidedOnly: true,
+    };
+  }
 }

From c883aee2f39915dc5193504333e16c85611136a8 Mon Sep 17 00:00:00 2001
From: Tofik Hasanov <annexcies@gmail.com>
Date: Fri, 22 May 2026 11:29:18 -0400
Subject: [PATCH 6/6] feat(cloud-tests): surface manual-step fallback through
 trigger + dialog
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The API change in the previous commit returns
`{ guidedOnly: true, guidedSteps, error }` when auto-fix gives up. This
commit threads that response shape through the trigger-task progress
metadata and the Remediation dialog so customers actually see the
manual steps instead of a raw error.

- `classifyExecuteResult` recognizes the new shape and emits a
  `{ type: 'manual', reason, guidedSteps }` classification. Defensive
  parsing strips non-string entries and ignores `guidedOnly` without
  real steps. Permission errors keep their existing precedence.

- `remediateSingle` trigger task carries a new `phase: 'manual'` plus
  `guidedSteps` in its progress payload.

- `RemediationDialog` reacts to the new phase by switching its
  preview state into the existing guided-only rendering (same UI used
  for plans where the AI declared `canAutoFix: false` upfront).

- The two batch-fix paths (single-account + integrations) treat the
  manual classification as `failed` with the AI-generated reason — the
  batch UI doesn't render per-finding guided steps, but the
  user-facing message is now meaningful instead of cryptic. The
  per-finding manual steps remain available via the single-fix dialog.

8 new tests on `execute-result.test.ts` (10 total) cover the manual
classification, the precedence rules, and the defensive parsing.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../[orgId]/cloud-tests/actions/batch-fix.ts  |  7 ++
 .../components/RemediationDialog.tsx          | 23 +++++-
 .../integrations/[slug]/actions/batch-fix.ts  |  3 +
 .../cloud-security/execute-result.test.ts     | 74 +++++++++++++++++++
 .../tasks/cloud-security/execute-result.ts    | 27 +++++++
 .../cloud-security/remediate-batch-helpers.ts |  3 +
 .../tasks/cloud-security/remediate-single.ts  | 19 ++++-
 7 files changed, 154 insertions(+), 2 deletions(-)

diff --git a/apps/app/src/app/(app)/[orgId]/cloud-tests/actions/batch-fix.ts b/apps/app/src/app/(app)/[orgId]/cloud-tests/actions/batch-fix.ts
index c089343b4c..f50c8db977 100644
--- a/apps/app/src/app/(app)/[orgId]/cloud-tests/actions/batch-fix.ts
+++ b/apps/app/src/app/(app)/[orgId]/cloud-tests/actions/batch-fix.ts
@@ -195,6 +195,13 @@ export async function retryFinding(
         missingPermissions: result.permissionError.missingActions,
       };
     }
+    if (result.type === 'manual') {
+      // Batch flow doesn't surface per-finding manual steps in the UI
+      // today — mark as failed with the AI-generated reason so the
+      // user knows it needs manual attention. (Per-finding manual
+      // steps are available via the single-fix dialog.)
+      return { status: 'failed', error: result.reason };
+    }
 
     return { status: 'failed', error: result.error };
   } catch (err) {
diff --git a/apps/app/src/app/(app)/[orgId]/cloud-tests/components/RemediationDialog.tsx b/apps/app/src/app/(app)/[orgId]/cloud-tests/components/RemediationDialog.tsx
index de9b051038..62e28ab1f0 100644
--- a/apps/app/src/app/(app)/[orgId]/cloud-tests/components/RemediationDialog.tsx
+++ b/apps/app/src/app/(app)/[orgId]/cloud-tests/components/RemediationDialog.tsx
@@ -24,10 +24,11 @@ interface PreviewProgress {
 }
 
 interface SingleFixProgress {
-  phase: 'executing' | 'success' | 'failed' | 'needs_permissions';
+  phase: 'executing' | 'success' | 'failed' | 'needs_permissions' | 'manual';
   error?: string;
   actionId?: string;
   permissionError?: { missingActions: string[]; fixScript?: string };
+  guidedSteps?: string[];
 }
 
 interface RemediationDialogProps {
@@ -379,6 +380,26 @@ export function RemediationDialog({
         setExecuteRunId(null);
         setExecuteAccessToken(null);
       }, 4000);
+    } else if (progress.phase === 'manual') {
+      // Auto-fix gave up but the API returned real manual steps.
+      // Switch the dialog into guided rendering instead of showing a
+      // raw error — same UI the preview flow already uses for
+      // canAutoFix:false plans.
+      setIsExecuting(false);
+      setError(null);
+      const steps = progress.guidedSteps ?? [];
+      setPreview({
+        currentState: {},
+        proposedState: {},
+        description: progress.error ?? description ?? '',
+        risk: risk ?? 'medium',
+        apiCalls: [],
+        guidedOnly: true,
+        guidedSteps: steps,
+        rollbackSupported: false,
+      });
+      setExecuteRunId(null);
+      setExecuteAccessToken(null);
     } else if (progress.phase === 'failed') {
       setIsExecuting(false);
       setError(progress.error || 'Remediation failed');
diff --git a/apps/app/src/app/(app)/[orgId]/integrations/[slug]/actions/batch-fix.ts b/apps/app/src/app/(app)/[orgId]/integrations/[slug]/actions/batch-fix.ts
index c089343b4c..597f7d7b1e 100644
--- a/apps/app/src/app/(app)/[orgId]/integrations/[slug]/actions/batch-fix.ts
+++ b/apps/app/src/app/(app)/[orgId]/integrations/[slug]/actions/batch-fix.ts
@@ -195,6 +195,9 @@ export async function retryFinding(
         missingPermissions: result.permissionError.missingActions,
       };
     }
+    if (result.type === 'manual') {
+      return { status: 'failed', error: result.reason };
+    }
 
     return { status: 'failed', error: result.error };
   } catch (err) {
diff --git a/apps/app/src/trigger/tasks/cloud-security/execute-result.test.ts b/apps/app/src/trigger/tasks/cloud-security/execute-result.test.ts
index 3dde1ef486..2f9941e8c8 100644
--- a/apps/app/src/trigger/tasks/cloud-security/execute-result.test.ts
+++ b/apps/app/src/trigger/tasks/cloud-security/execute-result.test.ts
@@ -49,4 +49,78 @@ describe('classifyExecuteResult', () => {
       },
     });
   });
+
+  // ─── Manual-steps fallback (new in this PR) ────────────────────────
+
+  it('classifies a guidedOnly response with steps as the new manual type', () => {
+    expect(
+      classifyExecuteResult({
+        status: 'failed',
+        error: 'Plan still invalid after AI repair.',
+        guidedOnly: true,
+        guidedSteps: [
+          'Open AWS Console → CloudTrail',
+          'Create a new multi-region trail named compai-cloudtrail',
+        ],
+      }),
+    ).toEqual({
+      type: 'manual',
+      reason: 'Plan still invalid after AI repair.',
+      guidedSteps: [
+        'Open AWS Console → CloudTrail',
+        'Create a new multi-region trail named compai-cloudtrail',
+      ],
+    });
+  });
+
+  it('falls back to a generic reason when manual response omits error text', () => {
+    const result = classifyExecuteResult({
+      guidedOnly: true,
+      guidedSteps: ['Do thing X'],
+    });
+    expect(result.type).toBe('manual');
+    if (result.type !== 'manual') return;
+    expect(result.reason).toMatch(/Automatic fix could not be applied/i);
+    expect(result.guidedSteps).toEqual(['Do thing X']);
+  });
+
+  it('does NOT trigger the manual type when guidedOnly is true but steps are missing or empty', () => {
+    // Must have BOTH the flag and a non-empty list. Without real steps,
+    // the customer would see "manual mode" with nothing to do.
+    expect(
+      classifyExecuteResult({ guidedOnly: true, guidedSteps: [] }).type,
+    ).not.toBe('manual');
+    expect(
+      classifyExecuteResult({ guidedOnly: true }).type,
+    ).not.toBe('manual');
+    expect(
+      classifyExecuteResult({
+        guidedOnly: true,
+        guidedSteps: ['', '   '],
+      }).type,
+    ).not.toBe('manual');
+  });
+
+  it('strips non-string entries from guidedSteps before declaring manual', () => {
+    const result = classifyExecuteResult({
+      guidedOnly: true,
+      guidedSteps: ['valid step', 42, null, 'another step'],
+    });
+    expect(result.type).toBe('manual');
+    if (result.type !== 'manual') return;
+    expect(result.guidedSteps).toEqual(['valid step', 'another step']);
+  });
+
+  it('prefers permission-error classification over manual when both fields are present', () => {
+    // Permission errors have a polished dedicated UX (fixScript). Don't
+    // shadow them with a generic manual-steps view.
+    const result = classifyExecuteResult({
+      status: 'failed',
+      error: 'Access denied',
+      permissionError: { missingActions: ['s3:CreateBucket'] },
+      guidedOnly: true,
+      guidedSteps: ['Do something'],
+    });
+    expect(result.type).toBe('needs_permissions');
+  });
 });
diff --git a/apps/app/src/trigger/tasks/cloud-security/execute-result.ts b/apps/app/src/trigger/tasks/cloud-security/execute-result.ts
index ba6672467d..8a4b7be24e 100644
--- a/apps/app/src/trigger/tasks/cloud-security/execute-result.ts
+++ b/apps/app/src/trigger/tasks/cloud-security/execute-result.ts
@@ -10,6 +10,11 @@ type ExecuteClassification =
       error: string;
       permissionError: PermissionError;
     }
+  | {
+      type: 'manual';
+      reason: string;
+      guidedSteps: string[];
+    }
   | { type: 'failed'; error: string };
 
 export function classifyExecuteResult(value: unknown): ExecuteClassification {
@@ -30,6 +35,20 @@ export function classifyExecuteResult(value: unknown): ExecuteClassification {
     };
   }
 
+  // Manual-steps fallback: the API decided auto-fix can't proceed and
+  // is returning real, customer-actionable instructions. Surface them
+  // verbatim so the dialog can render them instead of a raw error.
+  const guidedSteps = parseGuidedSteps(record.guidedSteps);
+  if (record.guidedOnly === true && guidedSteps && guidedSteps.length > 0) {
+    return {
+      type: 'manual',
+      reason:
+        error ??
+        'Automatic fix could not be applied — follow the guided steps.',
+      guidedSteps,
+    };
+  }
+
   if (status === 'success') {
     return {
       type: 'success',
@@ -54,6 +73,14 @@ export function classifyExecuteResult(value: unknown): ExecuteClassification {
   };
 }
 
+function parseGuidedSteps(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const steps = value.filter(
+    (step): step is string => typeof step === 'string' && step.trim().length > 0,
+  );
+  return steps.length > 0 ? steps : undefined;
+}
+
 function parsePermissionError(value: unknown): PermissionError | undefined {
   if (!value || typeof value !== 'object') return undefined;
 
diff --git a/apps/app/src/trigger/tasks/cloud-security/remediate-batch-helpers.ts b/apps/app/src/trigger/tasks/cloud-security/remediate-batch-helpers.ts
index 19b4d6e702..c315245c28 100644
--- a/apps/app/src/trigger/tasks/cloud-security/remediate-batch-helpers.ts
+++ b/apps/app/src/trigger/tasks/cloud-security/remediate-batch-helpers.ts
@@ -110,6 +110,9 @@ export async function tryFix(
       missingPerms: result.permissionError.missingActions,
     };
   }
+  if (result.type === 'manual') {
+    return { status: 'failed', error: result.reason };
+  }
 
   return { status: 'failed', error: result.error };
 }
diff --git a/apps/app/src/trigger/tasks/cloud-security/remediate-single.ts b/apps/app/src/trigger/tasks/cloud-security/remediate-single.ts
index 3382f3b16f..e362a0926e 100644
--- a/apps/app/src/trigger/tasks/cloud-security/remediate-single.ts
+++ b/apps/app/src/trigger/tasks/cloud-security/remediate-single.ts
@@ -7,10 +7,11 @@ import {
 import { classifyExecuteResult } from './execute-result';
 
 interface SingleFixProgress {
-  phase: 'executing' | 'success' | 'failed' | 'needs_permissions';
+  phase: 'executing' | 'success' | 'failed' | 'needs_permissions' | 'manual';
   error?: string;
   actionId?: string;
   permissionError?: { missingActions: string[]; fixScript?: string };
+  guidedSteps?: string[];
 }
 
 function sync(progress: SingleFixProgress) {
@@ -86,6 +87,22 @@ export const remediateSingle = task({
         };
       }
 
+      if (result.type === 'manual') {
+        progress.phase = 'manual';
+        progress.error = result.reason;
+        progress.guidedSteps = result.guidedSteps;
+        sync(progress);
+        logger.info(
+          `Single fix fell back to manual steps: ${result.guidedSteps.length} step(s)`,
+        );
+        return {
+          success: false,
+          manual: true,
+          guidedSteps: result.guidedSteps,
+          reason: result.reason,
+        };
+      }
+
       progress.phase = 'failed';
       progress.error = result.error;
       sync(progress);