@clipboard-health/ai-rules 1.1.1 → 1.2.1

package/frontend/CLAUDE.md

@@ -1,4184 +1 @@
-<!-- Source: .ruler/common/codeStyleAndStructure.md -->
-
-# Code style and structure
-
-- Write concise, technical TypeScript code with accurate examples.
-- Use functional and declarative programming patterns.
-- Prefer iteration and modularization over code duplication.
-- Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).
-- Structure files: constants, types, exported functions, non-exported functions.
-- Avoid magic strings and numbers; define constants.
-- Use camelCase for files and directories (e.g., modules/shiftOffers.ts).
-- When declaring functions, use the `function` keyword, not `const`.
-- Files should read from top to bottom: `export`ed items live on top and the internal functions and methods they call go below them.
-- Prefer data immutability.
-
-# Commit messages
-
-- Follow the Conventional Commits 1.0 spec for commit messages and in pull request titles.
-
-<!-- Source: .ruler/common/errorHandlingAndValidation.md -->
-
-# Error handling and validation
-
-- Sanitize user input.
-- Handle errors and edge cases at the beginning of functions.
-- Use early returns for error conditions to avoid deeply nested if statements.
-- Place the happy path last in the function for improved readability.
-- Avoid unnecessary else statements; use the if-return pattern instead.
-- Use guard clauses to handle preconditions and invalid states early.
-- Implement proper error logging and user-friendly error messages.
-- Favor `@clipboard-health/util-ts`'s `Either` type for expected errors instead of `try`/`catch`.
-
-<!-- Source: .ruler/common/testing.md -->
-
-# Testing
-
-- Follow the Arrange-Act-Assert convention for tests with newlines between each section.
-- Name test variables using the `mockX`, `input`, `expected`, `actual` convention.
-- Aim for high test coverage, writing both positive and negative test cases.
-- Prefer `it.each` for multiple test cases.
-- Avoid conditional logic in tests.
-
-<!-- Source: .ruler/common/typeScript.md -->
-
-# TypeScript usage
-
-- Use strict-mode TypeScript for all code; prefer interfaces over types.
-- Avoid enums; use const maps instead.
-- Strive for precise types. Look for type definitions in the codebase and create your own if none exist.
-- Avoid using type assertions like `as` or `!` unless absolutely necessary.
-- Use the `unknown` type instead of `any` when the type is truly unknown.
-- Use an object to pass multiple function params and to return results.
-- Leverage union types, intersection types, and conditional types for complex type definitions.
-- Use mapped types and utility types (e.g., `Partial<T>`, `Pick<T>`, `Omit<T>`) to transform existing types.
-- Implement generic types to create reusable, flexible type definitions.
-- Utilize the `keyof` operator and index access types for dynamic property access.
-- Implement discriminated unions for type-safe handling of different object shapes where appropriate.
-- Use the `infer` keyword in conditional types for type inference.
-- Leverage `readonly` properties for function parameter immutability.
-- Prefer narrow types whenever possible with `as const` assertions, `typeof`, `instanceof`, `satisfies`, and custom type guards.
-- Implement exhaustiveness checking using `never`.
-
-<!-- Source: .ruler/frontend/custom-hooks.md -->
-
-# Custom Hook Standards
-
-## Hook Structure
-
-```typescript
-interface UseFeatureOptions {
-  enabled?: boolean;
-  refetchInterval?: number;
-}
-
-export function useFeature(params: Params, options: UseFeatureOptions = {}) {
-  const { enabled = true } = options;
-
-  // Multiple queries/hooks
-  const query1 = useQuery(...);
-  const query2 = useQuery(...);
-
-  // Derived state
-  const computed = useMemo(() => {
-    // Combine data
-    return transformData(query1.data, query2.data);
-  }, [query1.data, query2.data]);
-
-  // Callbacks
-  const handleAction = useCallback(async () => {
-    // Perform action
-  }, [dependencies]);
-
-  // Return structured object
-  return {
-    // Data
-    data: computed,
-
-    // Loading states
-    isLoading: query1.isLoading || query2.isLoading,
-    isError: query1.isError || query2.isError,
-
-    // Actions
-    refetch: async () => {
-      await Promise.all([query1.refetch(), query2.refetch()]);
-    },
-    handleAction,
-  };
-}
-```
-
-## Naming Rules
-
-- **Always** prefix with `use`
-- Boolean hooks: `useIsFeatureEnabled`, `useShouldShowModal`, `useHasPermission`
-- Data hooks: `useGetData`, `useFeatureData`
-- Action hooks: `useBookShift`, `useSubmitForm`
-
-## Return Values
-
-- Return objects (not arrays) for complex hooks
-- Name properties clearly: `isLoading` not `loading`, `refetch` not `refresh`
-- Group related properties together
-
-```typescript
-// Good - clear property names
-return {
-  data,
-  isLoading,
-  isError,
-  refetch,
-};
-
-// Avoid - array destructuring for complex returns
-return [data, isLoading, refetch]; // Only for very simple hooks
-```
-
-## State Management with Constate
-
-For local/shared state management, use **`constate`** to create context with minimal boilerplate:
-
-```typescript
-import constate from "constate";
-import { useState, useCallback } from "react";
-
-// Define your hook with state logic
-function useShiftFilters() {
-  const [filters, setFilters] = useState<Filters>({});
-  const [isLoading, setIsLoading] = useState(false);
-
-  const applyFilters = useCallback((newFilters: Filters) => {
-    setFilters(newFilters);
-  }, []);
-
-  const clearFilters = useCallback(() => {
-    setFilters({});
-  }, []);
-
-  return {
-    filters,
-    isLoading,
-    applyFilters,
-    clearFilters,
-  };
-}
-
-// Create provider and hook with constate
-export const [ShiftFiltersProvider, useShiftFiltersContext] = constate(useShiftFilters);
-```
-
-**Usage:**
-
-```typescript
-// Wrap components that need access
-function ShiftsPage() {
-  return (
-    <ShiftFiltersProvider>
-      <ShiftList />
-      <FilterPanel />
-    </ShiftFiltersProvider>
-  );
-}
-
-// Use in child components
-function ShiftList() {
-  const { filters, applyFilters } = useShiftFiltersContext();
-
-  // Use shared state
-  return <div>{/* ... */}</div>;
-}
-```
-
-**Benefits:**
-
-- Minimal boilerplate compared to raw Context API
-- TypeScript support out of the box
-- Avoids prop drilling
-- Clean separation of state logic
-
-**When to use Constate:**
-
-- Sharing state between multiple sibling components
-- Complex feature-level state (filters, UI state, form state)
-- Alternative to prop drilling
-
-**When NOT to use Constate:**
-
-- Server state (use React Query instead)
-- Global app state (consider if it's truly needed)
-- Simple parent-child communication (use props)
-
-## Boolean Hooks
-
-```typescript
-// Pattern: useIs*, useHas*, useShould*
-export function useIsFeatureEnabled(): boolean {
-  const flags = useFeatureFlags();
-  return flags.includes("new-feature");
-}
-
-export function useHasPermission(permission: string): boolean {
-  const user = useUser();
-  return user.permissions.includes(permission);
-}
-
-export function useShouldShowModal(): boolean {
-  const hasSeenModal = usePreference("hasSeenModal");
-  return !hasSeenModal;
-}
-```
-
-## Data Transformation Hooks
-
-```typescript
-export function useTransformedData() {
-  const { data: rawData, isLoading, isError } = useGetRawData();
-
-  const transformedData = useMemo(() => {
-    if (!rawData) return undefined;
-
-    return rawData.map((item) => ({
-      ...item,
-      displayName: formatName(item),
-    }));
-  }, [rawData]);
-
-  return {
-    data: transformedData,
-    isLoading,
-    isError,
-  };
-}
-```
-
-## Side Effect Hooks
-
-```typescript
-// Hooks that perform side effects (logging, tracking, etc.)
-export function useTrackPageView(pageName: string) {
-  useEffect(() => {
-    logEvent("PAGE_VIEWED", { pageName });
-  }, [pageName]);
-}
-
-// Usage
-export function MyPage() {
-  useTrackPageView("MyPage");
-  // ... rest of component
-}
-```
-
-## Composite Hooks
-
-```typescript
-// Combines multiple hooks and data sources
-export function useWorkerBookingsData() {
-  const worker = useDefinedWorker();
-  const isFeatureEnabled = useIsFeatureEnabled("new-bookings");
-
-  const {
-    data: shifts,
-    isLoading: isLoadingShifts,
-    refetch: refetchShifts,
-  } = useGetShifts(worker.id);
-
-  const {
-    data: invites,
-    isLoading: isLoadingInvites,
-    refetch: refetchInvites,
-  } = useGetInvites(worker.id, { enabled: isFeatureEnabled });
-
-  // Combine data
-  const bookings = useMemo(() => {
-    return [...(shifts ?? []), ...(invites ?? [])].sort(sortByDate);
-  }, [shifts, invites]);
-
-  // Combined loading state
-  const isLoading = isLoadingShifts || isLoadingInvites;
-
-  // Combined refetch
-  async function refreshAllData() {
-    await Promise.all([refetchShifts(), refetchInvites()]);
-  }
-
-  return {
-    // Data
-    bookings,
-
-    // States
-    isLoading,
-    isFeatureEnabled,
-
-    // Actions
-    refreshAllData,
-  };
-}
-```
-
-## Co-location
-
-- Place hooks in `hooks/` folder within feature directory
-- Place API hooks in `api/` folder
-- Keep generic/shared hooks in `lib/` or `utils/`
-
-```text
-FeatureName/
-├── api/
-│   ├── useGetFeature.ts      # API data fetching
-│   └── useUpdateFeature.ts
-├── hooks/
-│   ├── useFeatureLogic.ts    # Business logic hooks
-│   ├── useFeatureState.ts    # Constate state hooks
-│   └── useFeatureFilters.ts
-└── components/
-    └── FeatureComponent.tsx
-```
-
-## Options Pattern
-
-```typescript
-// Always use options object for flexibility
-interface UseFeatureOptions {
-  enabled?: boolean;
-  refetchInterval?: number;
-  onSuccess?: (data: Data) => void;
-}
-
-export function useFeature(params: Params, options: UseFeatureOptions = {}) {
-  const { enabled = true, refetchInterval, onSuccess } = options;
-
-  // Use options in queries
-  return useQuery({
-    enabled,
-    refetchInterval,
-    onSuccess,
-    // ...
-  });
-}
-```
-
-## Hook Dependencies
-
-```typescript
-// Be explicit about dependencies
-export function useFormattedData(rawData: Data[]) {
-  return useMemo(() => {
-    return rawData.map(format);
-  }, [rawData]); // Clear dependency
-}
-
-// Avoid creating functions in dependency arrays
-export function useHandler() {
-  const [value, setValue] = useState();
-
-  // Good - stable reference
-  const handleChange = useCallback((newValue: string) => {
-    setValue(newValue);
-  }, []); // No dependencies on value
-
-  return handleChange;
-}
-```
-
-## Best Practices
-
-- **Prefix with `use`** - Always
-- **Return objects, not arrays** - For hooks with multiple values
-- **Use constate for shared state** - Avoid prop drilling
-- **API hooks in `api/`** - Logic hooks in `hooks/`
-- **Clear property names** - `isLoading`, not `loading`
-- **Options pattern** - For flexible configuration
-- **Explicit dependencies** - In useMemo/useCallback
-
-<!-- Source: .ruler/frontend/data-fetching.md -->
-
-# Data Fetching Standards
-
-## Technology Stack
-
-- **React Query** (@tanstack/react-query) for all API calls
-- **Axios** for HTTP requests
-- **Zod** for response validation
-
-## Core Principles
-
-1. **Use URL and query parameters in query keys** - Makes cache invalidation predictable
-2. **Always use `useGetQuery` hook** - Provides consistent structure, logging, and validation
-3. **Define Zod schemas** for all API requests and responses
-4. **Log errors with centralized constants** - From `APP_V2_APP_EVENTS`, never inline strings
-5. **Rely on React Query state** - Use `isLoading`, `isError`, `isSuccess` - don't reinvent state management
-6. **Use `enabled` for conditional fetching** - With `isDefined()` helper
-7. **Use `invalidateQueries` for disabled queries** - Not `refetch()` which ignores enabled state
-
-## Hook Patterns
-
-### Simple Query
-
-```typescript
-export function useGetUser(userId: string) {
-  return useGetQuery({
-    url: `/api/users/${userId}`,
-    responseSchema: userSchema,
-    enabled: isDefined(userId),
-    staleTime: minutesToMilliseconds(5),
-    meta: {
-      logErrorMessage: APP_V2_APP_EVENTS.GET_USER_FAILURE,
-    },
-  });
-}
-```
-
-### Infinite/Paginated Query
-
-```typescript
-export function usePaginatedShifts(params: Params) {
-  return useInfiniteQuery({
-    queryKey: ["shifts", params],
-    queryFn: async ({ pageParam }) => {
-      const response = await get({
-        url: "/api/shifts",
-        queryParams: { cursor: pageParam, ...params },
-        responseSchema: shiftsResponseSchema,
-      });
-      return response.data;
-    },
-    getNextPageParam: (lastPage) => lastPage.links.nextCursor,
-  });
-}
-```
-
-### Composite Data Fetching
-
-```typescript
-// Hook that combines multiple queries
-export function useWorkerBookingsData() {
-  const { data: shifts, isLoading: isLoadingShifts, refetch: refetchShifts } = useGetShifts();
-  const { data: invites, isLoading: isLoadingInvites, refetch: refetchInvites } = useGetInvites();
-
-  // Combine data
-  const bookings = useMemo(() => {
-    return [...(shifts ?? []), ...(invites ?? [])];
-  }, [shifts, invites]);
-
-  // Combine loading states
-  const isLoading = isLoadingShifts || isLoadingInvites;
-
-  // Combine refetch functions
-  async function refreshAllData() {
-    await Promise.all([refetchShifts(), refetchInvites()]);
-  }
-
-  return {
-    bookings,
-    isLoading,
-    refreshAllData,
-  };
-}
-```
-
-## Error Handling
-
-Always use centralized error constants and handle expected errors gracefully:
-
-```typescript
-useGetQuery({
-  url: "/api/resource",
-  responseSchema: schema,
-  meta: {
-    logErrorMessage: APP_V2_APP_EVENTS.GET_RESOURCE_FAILURE, // ✅ Centralized
-    userErrorMessage: "Failed to load data", // Shows alert to user
-  },
-  useErrorBoundary: (error) => {
-    // Don't show error boundary for 404s (expected errors)
-    return !(axios.isAxiosError(error) && error.response?.status === 404);
-  },
-  retry: (failureCount, error) => {
-    // Don't retry 404s or 401s
-    if (axios.isAxiosError(error)) {
-      const status = error.response?.status;
-      return ![404, 401].includes(status ?? 0);
-    }
-    return failureCount < 3;
-  },
-});
-```
-
-## State Management - Don't Reinvent the Wheel
-
-❌ **Don't** create your own loading/error state:
-
-```typescript
-const [data, setData] = useState();
-const [isLoading, setIsLoading] = useState(false);
-const [error, setError] = useState();
-
-useEffect(() => {
-  async function fetchData() {
-    try {
-      setIsLoading(true);
-      const result = await api.get("/data");
-      setData(result);
-    } catch (err) {
-      setError(err);
-    } finally {
-      setIsLoading(false);
-    }
-  }
-  fetchData();
-}, []);
-```
-
-✅ **Do** use React Query states:
-
-```typescript
-const { data, isLoading, isError, isSuccess } = useGetQuery({...});
-
-if (isLoading) return <Loading />;
-if (isError) return <Error />;
-if (isSuccess) return <div>{data.property}</div>;
-```
-
-## Mutations
-
-```typescript
-export function useCreateDocument() {
-  const queryClient = useQueryClient();
-
-  return useMutation({
-    mutationFn: async (data: CreateDocumentRequest) => {
-      return await post({
-        url: "/api/documents",
-        data,
-        responseSchema: documentSchema,
-      });
-    },
-    onSuccess: () => {
-      // Invalidate queries to refetch
-      queryClient.invalidateQueries(["documents"]);
-    },
-    onError: (error) => {
-      logEvent(APP_V2_APP_EVENTS.CREATE_DOCUMENT_FAILURE, { error });
-    },
-  });
-}
-```
-
-## Query Keys
-
-Always include URL and parameters in query keys:
-
-```typescript
-// ❌ Don't use static strings
-useQuery({ queryKey: "users", ... });
-
-// ✅ Do include URL and params
-useQuery({ queryKey: [`/api/users?${status}`, { status }], ... });
-
-// Consistent query key structure
-export const queryKeys = {
-  users: ["users"] as const,
-  user: (id: string) => ["users", id] as const,
-  userShifts: (id: string) => ["users", id, "shifts"] as const,
-};
-
-// Usage
-useQuery({
-  queryKey: queryKeys.user(userId),
-  // ...
-});
-```
-
-## Refetch Intervals
-
-```typescript
-useGetQuery({
-  url: "/api/resource",
-  responseSchema: schema,
-  refetchInterval: (data) => {
-    // Dynamic refetch based on data state
-    if (!data?.isComplete) {
-      return 1000; // Poll every second until complete
-    }
-    return 0; // Stop refetching
-  },
-});
-```
-
-## Conditional Fetching
-
-Use `enabled` option with `isDefined()` helper:
-
-```typescript
-import { isDefined } from "@/lib/utils";
-
-const { data } = useGetQuery({
-  url: "/api/resource",
-  responseSchema: schema,
-  // Only fetch when conditions are met
-  enabled: isDefined(userId) && isFeatureEnabled,
-});
-```
-
-## Refetch vs InvalidateQueries
-
-**Important:** For disabled queries, use `invalidateQueries` instead of `refetch`:
-
-❌ **Don't** use `refetch()` on disabled queries:
-
-```typescript
-const { refetch, data } = useGetQuery({
-  enabled: isDefined(shift.agentId),
-  ...
-});
-
-// Will fetch even if agentId is undefined!
-refetch();
-```
-
-✅ **Do** use `invalidateQueries`:
-
-```typescript
-const queryClient = useQueryClient();
-
-const { data } = useGetQuery({
-  enabled: isDefined(shift.agentId),
-  ...
-});
-
-// Respects the enabled state
-queryClient.invalidateQueries({ queryKey: [myQueryKey] });
-```
-
-## Query Cancellation
-
-```typescript
-export function usePaginatedData() {
-  const queryClient = useQueryClient();
-
-  return useInfiniteQuery({
-    queryKey: ["data"],
-    queryFn: async ({ pageParam }) => {
-      // Cancel previous in-flight requests
-      await queryClient.cancelQueries({ queryKey: ["data"] });
-
-      const response = await get({
-        url: "/api/data",
-        queryParams: { cursor: pageParam },
-      });
-      return response.data;
-    },
-    // ...
-  });
-}
-```
-
-## Naming Conventions
-
-- **useGet\*** - Simple queries: `useGetUser`, `useGetShift`
-- **usePaginated\*** - Infinite queries: `usePaginatedPlacements`
-- **useFetch\*** - Complex fetching logic: `useFetchPaginatedInterviews`
-- **Mutations**: `useCreateDocument`, `useUpdateShift`, `useDeletePlacement`
-
-## Response Transformation
-
-```typescript
-export function useGetUser(userId: string) {
-  return useGetQuery({
-    url: `/api/users/${userId}`,
-    responseSchema: userResponseSchema,
-    select: (data) => {
-      // Transform response data
-      return {
-        ...data,
-        fullName: `${data.firstName} ${data.lastName}`,
-      };
-    },
-  });
-}
-```
-
-## Hook Location
-
-- **API hooks** → Place in `api/` folder within feature directory
-- **One endpoint = one hook** principle
-- Export types inferred from Zod: `export type User = z.infer<typeof userSchema>`
-
-Example:
-
-```text
-Feature/
-├── api/
-│   ├── useGetResource.ts
-│   ├── useCreateResource.ts
-│   └── schemas.ts  (optional)
-```
-
-<!-- Source: .ruler/frontend/error-handling.md -->
-
-# Error Handling Standards
-
-## React Query Error Handling
-
-### Basic Error Configuration
-
-```typescript
-useGetQuery({
-  url: "/api/resource",
-  responseSchema: schema,
-  meta: {
-    logErrorMessage: APP_V2_APP_EVENTS.GET_RESOURCE_FAILURE,
-  },
-  useErrorBoundary: (error) => {
-    // Show error boundary for 500s, not for 404s
-    return !(axios.isAxiosError(error) && error.response?.status === 404);
-  },
-  retry: (failureCount, error) => {
-    // Don't retry 404s or 401s
-    if (axios.isAxiosError(error)) {
-      const status = error.response?.status;
-      return ![404, 401].includes(status ?? 0);
-    }
-    return failureCount < 3;
-  },
-});
-```
-
-### Error Boundary Strategy
-
-- **Show error boundary** for unexpected errors (500s, network failures)
-- **Don't show error boundary** for expected errors (404s, validation errors)
-- Use `useErrorBoundary` to control this behavior
-
-```typescript
-useErrorBoundary: (error) => {
-  // Only show error boundary for server errors
-  if (axios.isAxiosError(error)) {
-    const status = error.response?.status;
-    return status !== undefined && status >= 500;
-  }
-  return true; // Show for non-Axios errors
-};
-```
-
-### Retry Configuration
-
-```typescript
-// Don't retry client errors
-retry: (failureCount, error) => {
-  if (axios.isAxiosError(error)) {
-    const status = error.response?.status;
-    // Don't retry 4xx errors
-    if (status !== undefined && status >= 400 && status < 500) {
-      return false;
-    }
-  }
-  // Retry server errors up to 3 times
-  return failureCount < 3;
-};
-```
-
-### Exponential Backoff
-
-```typescript
-import { type QueryClient } from "@tanstack/react-query";
-
-const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      retry: 3,
-      retryDelay: (attemptIndex) => {
-        // Exponential backoff: 1s, 2s, 4s
-        return Math.min(1000 * 2 ** attemptIndex, 30000);
-      },
-    },
-  },
-});
-```
-
-## Component Error States
-
-### Pattern: Loading → Error → Success
-
-```typescript
-export function DataComponent() {
-  const { data, isLoading, isError, error, refetch } = useGetData();
-
-  if (isLoading) {
-    return <LoadingState />;
-  }
-
-  if (isError) {
-    return <ErrorState message="Failed to load data" onRetry={refetch} error={error} />;
-  }
-
-  // Happy path
-  return <DataDisplay data={data} />;
-}
-```
-
-### Inline Error Messages
-
-```typescript
-export function FormComponent() {
-  const mutation = useCreateResource();
-
-  return (
-    <form onSubmit={handleSubmit}>
-      {mutation.isError && <Alert severity="error">Failed to save. Please try again.</Alert>}
-
-      <Button type="submit" loading={mutation.isLoading} disabled={mutation.isLoading}>
-        Save
-      </Button>
-    </form>
-  );
-}
-```
-
-### Graceful Degradation
-
-```typescript
-export function OptionalDataComponent() {
-  const { data, isError } = useGetOptionalData();
-
-  // Don't block UI for optional data
-  if (isError) {
-    logError("Failed to load optional data");
-    return null; // or show simplified version
-  }
-
-  if (!data) {
-    return null;
-  }
-
-  return <EnhancedView data={data} />;
-}
-```
-
-## Mutation Error Handling
-
-### onError Callback
-
-```typescript
-export function useCreateDocument() {
-  const queryClient = useQueryClient();
-
-  return useMutation({
-    mutationFn: createDocumentApi,
-    onSuccess: (data) => {
-      queryClient.invalidateQueries(["documents"]);
-      showSuccessToast("Document created");
-    },
-    onError: (error) => {
-      logEvent(APP_V2_APP_EVENTS.CREATE_DOCUMENT_FAILURE, {
-        error: error.message,
-      });
-      showErrorToast("Failed to create document");
-    },
-  });
-}
-```
-
-### Handling Specific Errors
-
-```typescript
-export function useUpdateProfile() {
-  return useMutation({
-    mutationFn: updateProfileApi,
-    onError: (error: AxiosError) => {
-      if (error.response?.status === 409) {
-        showErrorToast("Email already exists");
-      } else if (error.response?.status === 422) {
-        showErrorToast("Invalid data provided");
-      } else {
-        showErrorToast("Failed to update profile");
-      }
-    },
-  });
-}
-```
-
-## Logging and Monitoring
-
-### Event Logging
-
-```typescript
-import { logEvent } from '@/lib/analytics';
-import { APP_EVENTS } from '@/constants/events';
-
-// In query configuration
-meta: {
-  logErrorMessage: APP_V2_APP_EVENTS.GET_SHIFTS_FAILURE,
-}
-
-// In error handlers
-onError: (error) => {
-  logEvent(APP_V2_APP_EVENTS.BOOKING_FAILED, {
-    shiftId,
-    error: error.message,
-    userId: worker.id,
-  });
-}
-```
-
-### Error Context
-
-Always include relevant context when logging errors:
-
-```typescript
-logEvent(APP_V2_APP_EVENTS.API_ERROR, {
-  endpoint: "/api/shifts",
-  method: "GET",
-  statusCode: error.response?.status,
-  errorMessage: error.message,
-  userId: worker.id,
-  timestamp: new Date().toISOString(),
-});
-```
-
-## Validation Errors
-
-### Zod Validation
-
-```typescript
-import { z } from "zod";
-
-const formSchema = z.object({
-  email: z.string().email("Invalid email address"),
-  age: z.number().min(18, "Must be 18 or older"),
-});
-
-try {
-  const validated = formSchema.parse(formData);
-  // Use validated data
-} catch (error) {
-  if (error instanceof z.ZodError) {
-    // Handle validation errors
-    error.errors.forEach((err) => {
-      showFieldError(err.path.join("."), err.message);
-    });
-  }
-}
-```
-
-### API Validation Errors
-
-```typescript
-interface ApiValidationError {
-  field: string;
-  message: string;
-}
-
-function handleApiValidationError(error: AxiosError) {
-  const validationErrors = error.response?.data?.errors as ApiValidationError[];
-
-  if (validationErrors) {
-    validationErrors.forEach(({ field, message }) => {
-      setFieldError(field, message);
-    });
-  }
-}
-```
-
-## Network Errors
-
-### Offline Detection
-
-```typescript
-export function useNetworkStatus() {
-  const [isOnline, setIsOnline] = useState(navigator.onLine);
-
-  useEffect(() => {
-    function handleOnline() {
-      setIsOnline(true);
-    }
-
-    function handleOffline() {
-      setIsOnline(false);
-    }
-
-    window.addEventListener("online", handleOnline);
-    window.addEventListener("offline", handleOffline);
-
-    return () => {
-      window.removeEventListener("online", handleOnline);
-      window.removeEventListener("offline", handleOffline);
-    };
-  }, []);
-
-  return isOnline;
-}
-```
-
-### Offline UI
-
-```typescript
-export function AppContainer() {
-  const isOnline = useNetworkStatus();
-
-  return (
-    <>
-      {!isOnline && (
-        <Banner severity="warning">You are offline. Some features may not be available.</Banner>
-      )}
-      <App />
-    </>
-  );
-}
-```
-
-## Timeout Handling
-
-### Request Timeouts
-
-```typescript
-import axios from "axios";
-
-const api = axios.create({
-  timeout: 30000, // 30 seconds
-});
-
-api.interceptors.response.use(
-  (response) => response,
-  (error) => {
-    if (error.code === "ECONNABORTED") {
-      showErrorToast("Request timed out. Please try again.");
-    }
-    return Promise.reject(error);
-  },
-);
-```
-
-## Error Boundaries
-
-### React Error Boundary
-
-```typescript
-import { Component, type ReactNode } from "react";
-
-interface Props {
-  children: ReactNode;
-  fallback?: ReactNode;
-}
-
-interface State {
-  hasError: boolean;
-  error?: Error;
-}
-
-export class ErrorBoundary extends Component<Props, State> {
-  constructor(props: Props) {
-    super(props);
-    this.state = { hasError: false };
-  }
-
-  static getDerivedStateFromError(error: Error): State {
-    return { hasError: true, error };
-  }
-
-  componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
-    logEvent("ERROR_BOUNDARY_TRIGGERED", {
-      error: error.message,
-      componentStack: errorInfo.componentStack,
-    });
-  }
-
-  render() {
-    if (this.state.hasError) {
-      return this.props.fallback || <ErrorFallback />;
-    }
-
-    return this.props.children;
-  }
-}
-```
-
-## Best Practices
-
-### 1. Always Handle Errors
-
-```typescript
-// ❌ Don't ignore errors
-const { data } = useGetData();
-
-// ✅ Handle error states
-const { data, isError, error } = useGetData();
-if (isError) {
-  return <ErrorState error={error} />;
-}
-```
-
-### 2. Provide User-Friendly Messages
-
-```typescript
-// ❌ Show technical errors to users
-<Alert>{error.message}</Alert>
-
-// ✅ Show helpful messages
-<Alert>
-  We couldn't load your shifts. Please check your connection and try again.
-</Alert>
-```
-
-### 3. Log Errors for Debugging
-
-```typescript
-// Always log errors for monitoring
-onError: (error) => {
-  logEvent(APP_V2_APP_EVENTS.ERROR, {
-    context: "shift-booking",
-    error: error.message,
-  });
-  showErrorToast("Booking failed");
-};
-```
-
-### 4. Provide Recovery Actions
-
-```typescript
-// ✅ Give users a way to recover
-<ErrorState message="Failed to load data" onRetry={refetch} onDismiss={() => navigate("/home")} />
-```
-
-### 5. Different Strategies for Different Errors
-
-```typescript
-// Critical errors: Show error boundary
-useErrorBoundary: (error) => isCriticalError(error);
-
-// Expected errors: Show inline message
-if (isError && error.response?.status === 404) {
-  return <NotFoundMessage />;
-}
-
-// Transient errors: Auto-retry with backoff
-retry: (failureCount) => failureCount < 3;
-```
-
-<!-- Source: .ruler/frontend/file-organization.md -->
-
-# File Organization Standards
-
-## Feature-Based Structure
-
-```text
-FeatureName/
-├── api/                          # Data fetching hooks
-│   ├── useGetFeature.ts
-│   ├── useUpdateFeature.ts
-│   └── useDeleteFeature.ts
-├── components/                   # Feature-specific components
-│   ├── FeatureCard.tsx
-│   ├── FeatureList.tsx
-│   └── FeatureHeader.tsx
-├── hooks/                        # Feature-specific hooks (non-API)
-│   ├── useFeatureLogic.ts
-│   └── useFeatureState.ts
-├── utils/                        # Feature utilities
-│   ├── formatFeature.ts
-│   ├── formatFeature.test.ts
-│   └── validateFeature.ts
-├── __tests__/                    # Integration tests (optional)
-│   └── FeatureFlow.test.tsx
-├── Page.tsx                      # Main page component
-├── Router.tsx                    # Feature routes
-├── paths.ts                      # Route paths
-├── types.ts                      # Shared types
-├── constants.ts                  # Constants
-└── README.md                     # Feature documentation (optional)
-```
-
-## File Naming Conventions
-
-### React Components
-
-- **PascalCase** for all React components
-- Examples: `Button.tsx`, `UserProfile.tsx`, `ShiftCard.tsx`
-
-### Avoid Path Stuttering
-
-Don't repeat directory names in file names - the full path provides enough context:
-
-❌ **Bad** - Path stuttering:
-
-```text
-Shift/
-  ShiftInvites/
-    ShiftInviteCard.tsx      // ❌ "Shift" repeated 3 times in path
-    ShiftInviteList.tsx      // ❌ Import: Shift/ShiftInvites/ShiftInviteCard
-```
-
-✅ **Good** - Clean, concise:
-
-```text
-Shift/
-  Invites/
-    Card.tsx                 // ✅ Path: Shift/Invites/Card
-    List.tsx                 // ✅ Import: Shift/Invites/List
-```
-
-**Reasoning:**
-
-- The full path already provides context (`Shift/Invites/Card` is clear)
-- Repeating names makes imports verbose: `import { ShiftInviteCard } from 'Shift/ShiftInvites/ShiftInviteCard'`
-- Shorter names are easier to work with in the editor
-
-### Utilities and Hooks
-
-- **camelCase** for utilities, hooks, and non-component files
-- Examples: `formatDate.ts`, `useAuth.ts`, `calculateTotal.ts`
-
-### Multi-word Non-Components
-
-- **camelCase** for multi-word utility and configuration files
-- Examples: `userProfileUtils.ts`, `apiHelpers.ts`
-
-### Test Files
-
-- Co-locate with source: `Button.test.tsx` next to `Button.tsx`
-- Test folder: `__tests__/` for integration tests
-- Pattern: `*.test.ts` or `*.test.tsx`
-
-### Constants and Types
-
-- `types.ts` - Shared types for the feature
-- `constants.ts` - Feature constants
-- `paths.ts` - Route path constants
-
-## Import Organization
-
-### Import Order
-
-```typescript
-// 1. External dependencies (React, third-party)
-import { useState, useEffect } from "react";
-import { useQuery } from "@tanstack/react-query";
-import { parseISO, format } from "date-fns";
-
-// 2. Internal packages (@clipboard-health, @src)
-import { Button } from "@clipboard-health/ui-components";
-import { CbhIcon } from "@clipboard-health/ui-components";
-import { formatDate } from "@src/appV2/lib/dates";
-import { useDefinedWorker } from "@src/appV2/Worker/useDefinedWorker";
-
-// 3. Relative imports (same feature)
-import { useFeatureData } from "./hooks/useFeatureData";
-import { FeatureCard } from "./components/FeatureCard";
-import { FEATURE_PATHS } from "./paths";
-import { type FeatureData } from "./types";
-```
-
-### Import Grouping Rules
-
-- Add blank lines between groups
-- Sort alphabetically within each group (optional but recommended)
-- Group type imports with their module: `import { type User } from './types'`
-
-## Path Management
-
-### Defining Paths
-
-```typescript
-// paths.ts
-import { APP_PATHS } from "@/constants/paths";
-
-export const FEATURE_BASE_PATH = "feature";
-export const FEATURE_FULL_PATH = `${APP_PATHS.APP_V2_HOME}/${FEATURE_BASE_PATH}`;
-export const FEATURE_PATHS = {
-  ROOT: FEATURE_FULL_PATH,
-  DETAILS: `${FEATURE_FULL_PATH}/:id`,
-  EDIT: `${FEATURE_FULL_PATH}/:id/edit`,
-  CREATE: `${FEATURE_FULL_PATH}/create`,
-} as const;
-```
-
-### Using Paths
-
-```typescript
-import { useHistory } from "react-router-dom";
-import { FEATURE_PATHS } from "./paths";
-
-// Navigation
-history.push(FEATURE_PATHS.DETAILS.replace(":id", featureId));
-
-// Route definition
-<Route path={FEATURE_PATHS.DETAILS} component={FeatureDetailsPage} />;
-```
-
-## Types and Interfaces
-
-### Separate vs Co-located Types
-
-```typescript
-// Option 1: Separate types.ts for shared types
-// types.ts
-export interface Feature {
-  id: string;
-  name: string;
-}
-
-export type FeatureStatus = "active" | "inactive";
-
-// Option 2: Co-located with component for component-specific types
-// FeatureCard.tsx
-interface FeatureCardProps {
-  feature: Feature;
-  onSelect: (id: string) => void;
-}
-
-export function FeatureCard(props: FeatureCardProps) {
-  // ...
-}
-```
-
-## Constants
-
-### Defining Constants
-
-```typescript
-// constants.ts
-export const FEATURE_STATUS = {
-  ACTIVE: "active",
-  INACTIVE: "inactive",
-  PENDING: "pending",
-} as const;
-
-export type FeatureStatus = (typeof FEATURE_STATUS)[keyof typeof FEATURE_STATUS];
-
-export const MAX_ITEMS = 100;
-export const DEFAULT_PAGE_SIZE = 20;
-
-export const FEATURE_EVENTS = {
-  VIEWED: "FEATURE_VIEWED",
-  CREATED: "FEATURE_CREATED",
-  UPDATED: "FEATURE_UPDATED",
-} as const;
-```
-
-## Folder Depth Guidelines
-
-- **Maximum 3 levels deep** for feature folders
-- For deeper nesting, consider splitting into separate features
-- Use meaningful folder names that describe the content
-
-```text
-Good:
-├── Shift/
-│   ├── Calendar/
-│   │   └── ShiftCalendarCore.tsx
-│   └── Card/
-│       └── ShiftCard.tsx
-
-Avoid:
-├── Shift/
-│   ├── Components/
-│   │   ├── Display/
-│   │   │   ├── Calendar/
-│   │   │   │   └── Core/
-│   │   │   │       └── ShiftCalendarCore.tsx  # Too deep!
-```
-
-## Module Exports
-
-### Index Files
-
-Avoid using `index.ts` files in the redesign folder. Prefer explicit imports.
-
-```typescript
-// Avoid
-// index.ts
-export * from "./Button";
-export * from "./Card";
-
-// Prefer explicit imports
-import { Button } from "@/components/Button";
-import { Card } from "@/components/Card";
-```
-
-### Named Exports
-
-Always use named exports (not default exports) in redesign code.
-
-```typescript
-// Good
-export function Button(props: ButtonProps) {}
-
-// Avoid
-export default function Button(props: ButtonProps) {}
-```
-
-## API Folder Structure
-
-```text
-api/
-├── useGetFeatures.ts          # GET requests
-├── useCreateFeature.ts        # POST requests
-├── useUpdateFeature.ts        # PUT/PATCH requests
-├── useDeleteFeature.ts        # DELETE requests
-└── schemas.ts                 # Zod schemas (optional)
-```
-
-## Utils Folder Guidelines
-
-- Keep utilities pure functions when possible
-- Co-locate tests with utilities
-- Export individual functions (not as objects)
-
-```typescript
-// Good
-// utils/formatFeatureName.ts
-export function formatFeatureName(name: string): string {
-  return name.trim().toUpperCase();
-}
-
-// utils/formatFeatureName.test.ts
-import { formatFeatureName } from "./formatFeatureName";
-
-describe("formatFeatureName", () => {
-  it("should format name correctly", () => {
-    expect(formatFeatureName("  test  ")).toBe("TEST");
-  });
-});
-```
-
-<!-- Source: .ruler/frontend/imports.md -->
-
-# Import Standards
-
-## Component Wrapper Pattern
-
-Many projects wrap third-party UI library components to add app-specific functionality. This can be enforced via ESLint rules.
-
-## Restricted MUI Imports
-
-### ❌ Component Restrictions (Example)
-
-Some projects restrict direct imports of certain components from `@mui/material`:
-
-```typescript
-// ❌ Forbidden
-import {
-  Avatar,
-  Accordion,
-  AccordionDetails,
-  AccordionSummary,
-  Badge,
-  Button,
-  Card,
-  Chip,
-  Dialog,
-  DialogTitle,
-  Divider,
-  Drawer,
-  FilledInput,
-  Icon,
-  IconButton,
-  InputBase,
-  List,
-  ListItem,
-  ListItemButton,
-  ListItemIcon,
-  ListItemText,
-  Modal,
-  OutlinedInput,
-  Rating,
-  Slider,
-  TextField,
-  Typography,
-  Tab,
-  Tabs,
-  SvgIcon,
-} from "@mui/material";
-```
-
-### ✅ Use Internal Wrappers
-
-```typescript
-// ✅ Correct - Use project wrappers
-import { Button } from "@clipboard-health/ui-components/Button";
-import { IconButton } from "@clipboard-health/ui-components/IconButton";
-import { LoadingButton } from "@clipboard-health/ui-components/LoadingButton";
-```
-
-### Rationale
-
-1. Wrappers provide app-specific functionality and consistent behavior
-2. Use `sx` prop for custom styles with theme access
-3. Prefer app-specific dialog components over generic Modal components
-
-## Icon Restrictions
-
-### ❌ Third-Party Icons (Example)
-
-```typescript
-// ❌ Avoid direct imports from icon libraries
-import SearchIcon from "@mui/icons-material/Search";
-import CloseIcon from "@mui/icons-material/Close";
-import AddIcon from "@mui/icons-material/Add";
-```
-
-### ✅ Use Project Icon Component
-
-```typescript
-// ✅ Correct - Use project's icon system
-import { Icon } from '@clipboard-health/ui-components';
-
-<Icon type="search" size="large" />
-<Icon type="close" size="medium" />
-<Icon type="plus" size="small" />
-```
-
-Many projects maintain their own icon system for consistency and customization.
-
-## Allowed MUI Imports
-
-### ✅ Safe to Import from MUI
-
-These components can be imported directly:
-
-```typescript
-import {
-  Box,
-  Stack,
-  Container,
-  Grid,
-  Paper,
-  Skeleton,
-  CircularProgress,
-  LinearProgress,
-  BottomNavigation,
-  BottomNavigationAction,
-  ThemeProvider,
-  useTheme,
-  useMediaQuery,
-} from "@mui/material";
-```
-
-Layout and utility components are generally safe.
-
-## Path Aliases
-
-### Use @ Prefix for Absolute Imports
-
-```typescript
-// ✅ Use path aliases configured in tsconfig
-import { formatDate } from "@/lib/dates";
-import { useUser } from "@/features/user/hooks/useUser";
-import { Button } from "@clipboard-health/ui-components/Button";
-import { theme } from "@/theme";
-
-// ❌ Avoid relative paths to distant folders
-import { formatDate } from "../../../lib/dates";
-```
-
-### Relative Imports for Same Feature
-
-```typescript
-// ✅ Relative imports within the same feature
-import { FeatureCard } from "./components/FeatureCard";
-import { useFeatureData } from "./hooks/useFeatureData";
-import { FEATURE_PATHS } from "./paths";
-import { type FeatureData } from "./types";
-```
-
-## Import Grouping
-
-### Standard Order
-
-```typescript
-// 1. External dependencies (React, third-party libraries)
-import { useState, useEffect, useMemo } from "react";
-import { useQuery } from "@tanstack/react-query";
-import { parseISO, format } from "date-fns";
-import { z } from "zod";
-
-// 2. Internal absolute imports (via path aliases)
-import { Button, Icon } from "@clipboard-health/ui-components";
-import { theme } from "@/theme";
-import { formatDate } from "@/lib/dates";
-import { useUser } from "@/features/user/hooks/useUser";
-import { APP_PATHS } from "@/constants/paths";
-
-// 3. Relative imports (same feature/module)
-import { useFeatureData } from "./hooks/useFeatureData";
-import { FeatureCard } from "./components/FeatureCard";
-import { FEATURE_PATHS } from "./paths";
-import { type FeatureData, type FeatureOptions } from "./types";
-```
-
-### Blank Lines Between Groups
-
-- Add blank line between each group
-- Helps with readability and organization
-- ESLint/Prettier can auto-format this
-
-## Type Imports
-
-### Inline Type Imports
-
-```typescript
-// ✅ Preferred: Inline type imports
-import { type User, type UserOptions } from "./types";
-import { formatUser } from "./utils";
-```
-
-### Separate Type Imports
-
-```typescript
-// ✅ Also acceptable
-import type { User, UserOptions } from "./types";
-import { formatUser } from "./utils";
-```
-
-## Barrel Exports (index.ts)
-
-### Consider Avoiding Barrel Exports
-
-```typescript
-// ❌ Barrel exports can slow build times
-// index.ts
-export * from "./Button";
-export * from "./Card";
-```
-
-### ✅ Use Explicit Imports
-
-```typescript
-// ✅ Import directly from files for better tree-shaking
-import { Button } from "@clipboard-health/ui-components/Button";
-import { Card } from "@clipboard-health/ui-components/Card";
-```
-
-Note: Barrel exports can cause issues with circular dependencies and slow down builds, especially in large projects.
-
-## Dynamic Imports
-
-### Code Splitting
-
-```typescript
-// For large components or routes
-const HeavyComponent = lazy(() => import("./HeavyComponent"));
-
-// In component
-<Suspense fallback={<Loading />}>
-  <HeavyComponent />
-</Suspense>;
-```
-
-## Common Import Patterns
-
-### API Utilities
-
-```typescript
-import { useQuery } from "@/lib/api/hooks";
-import { api } from "@/lib/api/client";
-```
-
-### React Query
-
-```typescript
-import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
-import { type UseQueryOptions, type UseQueryResult } from "@tanstack/react-query";
-```
-
-### Routing
-
-```typescript
-import { useHistory, useLocation, useParams } from "react-router-dom";
-import { type LocationState } from "history";
-```
-
-### Date Utilities
-
-```typescript
-import { parseISO, format, addDays, isBefore } from "date-fns";
-```
-
-### Validation
-
-```typescript
-import { z } from "zod";
-import { zodResolver } from "@hookform/resolvers/zod";
-```
-
-## ESLint Configuration
-
-Import restrictions can be enforced with ESLint's `no-restricted-imports` rule:
-
-```javascript
-module.exports = {
-  rules: {
-    "no-restricted-imports": [
-      "error",
-      {
-        paths: [
-          {
-            name: "@mui/material",
-            importNames: ["Button", "TextField", "Dialog"],
-            message: "Use wrapper components from @/components",
-          },
-        ],
-        patterns: [
-          {
-            group: ["@mui/icons-material/*"],
-            message: "Use project icon component instead",
-          },
-        ],
-      },
-    ],
-  },
-};
-```
-
-## Checking for Violations
-
-```bash
-# Lint your code
-npm run lint
-
-# Auto-fix import issues
-npm run lint:fix
-```
-
-## Migration Guide
-
-### When You See Import Errors
-
-1. **Wrapper Component Error**
-   - Check if wrapper exists in `@/components/`
-   - If yes, import from there
-   - If no, discuss with team about creating wrapper
-
-2. **Icon Error**
-   - Find equivalent in project icon system
-   - Use project's icon component
-   - Check available icon names in documentation
-
-3. **Deprecated Pattern Error**
-   - Follow the suggested replacement pattern
-   - Move to modern alternatives (e.g., `sx` prop instead of `styled`)
-
-## Summary
-
-✅ **DO**:
-
-- Use project wrapper components instead of third-party components directly
-- Use project icon system for consistency
-- Use path aliases (e.g., `@/`) for absolute imports
-- Group imports by external, internal, relative
-- Consider avoiding barrel exports for better build performance
-
-❌ **DON'T**:
-
-- Import third-party UI components directly if wrappers exist
-- Import icon libraries directly if project has custom icon system
-- Use deprecated styling patterns (check project guidelines)
-- Use relative imports for distant files
-- Create excessive barrel exports that hurt tree-shaking
-
-<!-- Source: .ruler/frontend/performance.md -->
-
-# Performance Standards
-
-## React Query Optimization
-
-### Stale Time Configuration
-
-```typescript
-// Set appropriate staleTime to avoid unnecessary refetch
-useGetQuery({
-  url: "/api/resource",
-  responseSchema: schema,
-  staleTime: minutesToMilliseconds(5), // Don't refetch for 5 minutes
-  cacheTime: minutesToMilliseconds(30), // Keep in cache for 30 minutes
-});
-```
-
-### Conditional Fetching
-
-```typescript
-// Only fetch when conditions are met
-const { data } = useGetQuery({
-  url: `/api/users/${userId}`,
-  responseSchema: userSchema,
-  enabled: isDefined(userId) && isFeatureEnabled, // Don't fetch until ready
-});
-```
-
-### Query Cancellation
-
-```typescript
-export function usePaginatedData(params: Params) {
-  const queryClient = useQueryClient();
-
-  return useInfiniteQuery({
-    queryKey: ["data", params],
-    queryFn: async ({ pageParam }) => {
-      // Cancel previous in-flight requests
-      await queryClient.cancelQueries({ queryKey: ["data"] });
-
-      const response = await get({
-        url: "/api/data",
-        queryParams: { cursor: pageParam, ...params },
-      });
-      return response.data;
-    },
-    getNextPageParam: (lastPage) => lastPage.nextCursor,
-  });
-}
-```
-
-### Prefetching
-
-```typescript
-export function usePreloadNextPage(nextUserId: string) {
-  const queryClient = useQueryClient();
-
-  useEffect(() => {
-    if (nextUserId) {
-      // Prefetch next page in background
-      queryClient.prefetchQuery({
-        queryKey: ["user", nextUserId],
-        queryFn: () => fetchUser(nextUserId),
-        staleTime: minutesToMilliseconds(5),
-      });
-    }
-  }, [nextUserId, queryClient]);
-}
-```
-
-## React Optimization
-
-### useMemo for Expensive Computations
-
-```typescript
-export function DataList({ items }: { items: Item[] }) {
-  // Memoize expensive sorting/filtering
-  const sortedItems = useMemo(() => {
-    return items.filter((item) => item.isActive).sort((a, b) => a.priority - b.priority);
-  }, [items]);
-
-  return <List items={sortedItems} />;
-}
-```
-
-### useCallback for Event Handlers
-
-```typescript
-export function ParentComponent() {
-  const [selected, setSelected] = useState<string>();
-
-  // Memoize callback to prevent child re-renders
-  const handleSelect = useCallback((id: string) => {
-    setSelected(id);
-    logEvent("ITEM_SELECTED", { id });
-  }, []); // Stable reference
-
-  return <ChildComponent onSelect={handleSelect} />;
-}
-```
-
-### React.memo for Pure Components
-
-```typescript
-import { memo } from "react";
-
-interface ItemCardProps {
-  item: Item;
-  onSelect: (id: string) => void;
-}
-
-// Memoize component to prevent unnecessary re-renders
-export const ItemCard = memo(function ItemCard({ item, onSelect }: ItemCardProps) {
-  return (
-    <Card onClick={() => onSelect(item.id)}>
-      <h3>{item.name}</h3>
-    </Card>
-  );
-});
-```
-
-### Avoid Inline Object/Array Creation
-
-```typescript
-// ❌ Creates new object on every render
-<Component style={{ padding: 8 }} />
-<Component items={[1, 2, 3]} />
-
-// ✅ Define outside or use useMemo
-const style = { padding: 8 };
-const items = [1, 2, 3];
-<Component style={style} items={items} />
-
-// ✅ Or use useMemo for dynamic values
-const style = useMemo(() => ({ padding: spacing }), [spacing]);
-```
-
-## List Rendering
-
-### Key Prop for Lists
-
-```typescript
-// ✅ Use stable, unique keys
-items.map((item) => <ItemCard key={item.id} item={item} />);
-
-// ❌ Don't use index as key (unless list never changes)
-items.map((item, index) => <ItemCard key={index} item={item} />);
-```
-
-### Virtualization for Long Lists
-
-```typescript
-import { FixedSizeList } from "react-window";
-
-export function VirtualizedList({ items }: { items: Item[] }) {
-  return (
-    <FixedSizeList height={600} itemCount={items.length} itemSize={80} width="100%">
-      {({ index, style }) => (
-        <div style={style}>
-          <ItemCard item={items[index]} />
-        </div>
-      )}
-    </FixedSizeList>
-  );
-}
-```
-
-### Pagination Instead of Infinite Data
-
-```typescript
-// For large datasets, use pagination
-export function PaginatedList() {
-  const [page, setPage] = useState(1);
-  const pageSize = 20;
-
-  const { data, isLoading } = useGetPaginatedData({
-    page,
-    pageSize,
-  });
-
-  return (
-    <>
-      <List items={data?.items} />
-      <Pagination page={page} total={data?.total} pageSize={pageSize} onChange={setPage} />
-    </>
-  );
-}
-```
-
-## Data Fetching Patterns
-
-### Parallel Queries
-
-```typescript
-export function useParallelData() {
-  // Fetch in parallel
-  const users = useGetUsers();
-  const shifts = useGetShifts();
-  const workplaces = useGetWorkplaces();
-
-  // All queries run simultaneously
-  const isLoading = users.isLoading || shifts.isLoading || workplaces.isLoading;
-
-  return {
-    users: users.data,
-    shifts: shifts.data,
-    workplaces: workplaces.data,
-    isLoading,
-  };
-}
-```
-
-### Dependent Queries
-
-```typescript
-export function useDependentData(userId?: string) {
-  // First query
-  const { data: user } = useGetUser(userId, {
-    enabled: isDefined(userId),
-  });
-
-  // Second query depends on first
-  const { data: shifts } = useGetUserShifts(user?.id, {
-    enabled: isDefined(user?.id), // Only fetch when user is loaded
-  });
-
-  return { user, shifts };
-}
-```
-
-### Debouncing Search Queries
-
-```typescript
-import { useDebouncedValue } from "@/lib/hooks";
-
-export function SearchComponent() {
-  const [searchTerm, setSearchTerm] = useState("");
-  const debouncedSearch = useDebouncedValue(searchTerm, 300);
-
-  const { data } = useSearchQuery(debouncedSearch, {
-    enabled: debouncedSearch.length > 2,
-  });
-
-  return (
-    <>
-      <input value={searchTerm} onChange={(e) => setSearchTerm(e.target.value)} />
-      <Results data={data} />
-    </>
-  );
-}
-```
-
-## Code Splitting
-
-### Route-Based Splitting
-
-```typescript
-import { lazy, Suspense } from "react";
-
-// Lazy load route components
-const ShiftDetailsPage = lazy(() => import("./Shift/DetailsPage"));
-const ProfilePage = lazy(() => import("./Profile/Page"));
-
-export function Router() {
-  return (
-    <Suspense fallback={<LoadingScreen />}>
-      <Routes>
-        <Route path="/shifts/:id" element={<ShiftDetailsPage />} />
-        <Route path="/profile" element={<ProfilePage />} />
-      </Routes>
-    </Suspense>
-  );
-}
-```
-
-### Component-Based Splitting
-
-```typescript
-// Split large components that aren't immediately needed
-const HeavyChart = lazy(() => import("./HeavyChart"));
-
-export function Dashboard() {
-  const [showChart, setShowChart] = useState(false);
-
-  return (
-    <div>
-      <Summary />
-      {showChart && (
-        <Suspense fallback={<ChartSkeleton />}>
-          <HeavyChart />
-        </Suspense>
-      )}
-    </div>
-  );
-}
-```
-
-## Image Optimization
-
-### Lazy Loading Images
-
-```typescript
-<img
-  src={imageUrl}
-  alt={alt}
-  loading="lazy" // Native lazy loading
-/>
-```
-
-### Responsive Images
-
-```typescript
-<img
-  srcSet={`
-    ${image_small} 480w,
-    ${image_medium} 800w,
-    ${image_large} 1200w
-  `}
-  sizes="(max-width: 480px) 480px, (max-width: 800px) 800px, 1200px"
-  src={image_medium}
-  alt={alt}
-/>
-```
-
-## State Management
-
-### Avoid Prop Drilling
-
-```typescript
-// ❌ Prop drilling
-<Parent>
-  <Child data={data}>
-    <GrandChild data={data}>
-      <GreatGrandChild data={data} />
-    </GrandChild>
-  </Child>
-</Parent>;
-
-// ✅ Use context for deeply nested data
-const DataContext = createContext<Data | undefined>(undefined);
-
-<DataContext.Provider value={data}>
-  <Parent>
-    <Child>
-      <GrandChild>
-        <GreatGrandChild />
-      </GrandChild>
-    </Child>
-  </Parent>
-</DataContext.Provider>;
-```
-
-### Local State Over Global State
-
-```typescript
-// ✅ Keep state as local as possible
-export function FormComponent() {
-  const [formData, setFormData] = useState({}); // Local state
-  // Only lift state up when needed by multiple components
-}
-```
-
-## Bundle Size Optimization
-
-### Tree Shaking
-
-```typescript
-// ✅ Import only what you need
-import { format } from "date-fns";
-
-// ❌ Imports entire library
-import * as dateFns from "date-fns";
-```
-
-### Avoid Large Dependencies
-
-```typescript
-// Check bundle size before adding dependencies
-// Use lighter alternatives when possible
-
-// ❌ Heavy library for simple task
-import moment from "moment";
-
-// ✅ Lighter alternative
-import { format } from "date-fns";
-```
-
-## Monitoring Performance
-
-### React DevTools Profiler
-
-```typescript
-// Wrap components to profile
-<Profiler id="ShiftList" onRender={onRenderCallback}>
-  <ShiftList />
-</Profiler>
-```
-
-### Web Vitals
-
-```typescript
-import { getCLS, getFID, getFCP, getLCP, getTTFB } from "web-vitals";
-
-// Track Core Web Vitals
-getCLS(console.log);
-getFID(console.log);
-getFCP(console.log);
-getLCP(console.log);
-getTTFB(console.log);
-```
-
-## Best Practices Summary
-
-### ✅ DO
-
-- Set appropriate `staleTime` and `cacheTime` for queries
-- Use `useMemo` for expensive computations
-- Use `useCallback` for callbacks passed to children
-- Use React.memo for pure components
-- Virtualize long lists
-- Lazy load routes and heavy components
-- Use pagination for large datasets
-- Debounce search inputs
-- Cancel queries when component unmounts
-- Prefetch data when predictable
-
-### ❌ DON'T
-
-- Fetch data unnecessarily
-- Create objects/arrays inline in props
-- Use index as key for dynamic lists
-- Render all items in very long lists
-- Import entire libraries when only need parts
-- Keep all state global
-- Ignore performance warnings in console
-- Skip memoization for expensive operations
-
-<!-- Source: .ruler/frontend/react-patterns.md -->
-
-# React Component Patterns
-
-## Core Principles
-
-- **Storybook is the single source of truth** for UI components, not Figma
-- **Named exports only** (prefer named exports over default exports)
-- **Explicit types** for all props and return values
-- **Handle all states**: loading, error, empty, success
-- **Composition over configuration** - prefer children over complex props
-
-## Component Structure
-
-Follow this consistent structure for all components:
-
-```typescript
-// 1. Imports (grouped with blank lines between groups)
-import { useState, useMemo, useCallback } from "react";
-import { Box, Typography } from "@mui/material";
-
-import { useGetUser } from "@/api/hooks/useGetUser";
-import { formatDate } from "@/utils/date";
-
-import { ChildComponent } from "./ChildComponent";
-
-// 2. Types (interfaces for props, types for unions)
-interface UserCardProps {
-  userId: string;
-  onAction: (action: string) => void;
-  isHighlighted?: boolean;
-}
-
-// 3. Component definition
-export function UserCard({ userId, onAction, isHighlighted = false }: UserCardProps) {
-  // A. React Query hooks first
-  const { data: user, isLoading, isError } = useGetUser(userId);
-
-  // B. Local state
-  const [isExpanded, setIsExpanded] = useState(false);
-
-  // C. Derived values (with useMemo for expensive computations)
-  const displayName = useMemo(
-    () => (user ? `${user.firstName} ${user.lastName}` : "Unknown"),
-    [user]
-  );
-
-  // D. Event handlers (with useCallback when passed to children)
-  const handleToggle = useCallback(() => {
-    setIsExpanded((prev) => !prev);
-    onAction("toggle");
-  }, [onAction]);
-
-  // E. Early returns for loading/error states
-  if (isLoading) return <LoadingState />;
-  if (isError) return <ErrorState message="Failed to load user" />;
-  if (!user) return <EmptyState message="User not found" />;
-
-  // F. Render
-  return (
-    <Box sx={{ padding: 2, backgroundColor: isHighlighted ? "primary.light" : "background.paper" }}>
-      <Typography variant="h6">{displayName}</Typography>
-      <ChildComponent onClick={handleToggle} />
-    </Box>
-  );
-}
-```
-
-## Why This Structure?
-
-1. **Imports grouped** - Easy to see dependencies
-2. **Types first** - Documents component API
-3. **Hooks at top** - React rules of hooks
-4. **Derived values next** - Shows data flow
-5. **Handlers together** - Easy to find event logic
-6. **Early returns** - Fail fast, reduce nesting
-7. **Render last** - Main component logic
-
-## Component Naming
-
-- **PascalCase** for components: `UserProfile`, `DataCard`
-- **camelCase** for hooks and utilities: `useUserData`, `formatDate`
-- Prefer named exports over default exports for better refactoring support
-
-## Props
-
-- Always define explicit prop types
-- Use destructuring with types
-- Avoid prop spreading unless wrapping a component
-
-```typescript
-// Good
-interface ButtonProps {
-  onClick: () => void;
-  label: string;
-  disabled?: boolean;
-}
-
-export function Button({ onClick, label, disabled = false }: ButtonProps) {
-  return (
-    <button onClick={onClick} disabled={disabled}>
-      {label}
-    </button>
-  );
-}
-
-// Acceptable for wrappers
-export function CustomButton(props: ButtonProps) {
-  return <ButtonBase {...props} LinkComponent={InternalLink} />;
-}
-```
-
-## Wrappers
-
-- Wrap third-party components to add app-specific functionality
-- Example: Wrapping a third-party Button with custom link handling
-
-```typescript
-import {
-  Button as ButtonBase,
-  type ButtonProps as ButtonPropsBase,
-} from "@some-ui-library/components";
-import { type LocationState } from "history";
-
-import { InternalLink } from "./InternalLink";
-
-interface ButtonProps extends Omit<ButtonPropsBase, "LinkComponent"> {
-  locationState?: LocationState;
-}
-
-export function Button(props: ButtonProps) {
-  return <ButtonBase {...props} LinkComponent={InternalLink} />;
-}
-```
-
-## State Management
-
-- Use `useState` for local component state
-- Use `useMemo` for expensive computations
-- Use `useCallback` for functions passed to children
-- Lift state up when needed by multiple components
-
-## Conditional Rendering
-
-```typescript
-// Early returns for loading/error states
-if (isLoading) return <LoadingState />;
-if (isError) return <ErrorState />;
-
-// Ternary for simple conditions
-return isActive ? <ActiveView /> : <InactiveView />;
-
-// && for conditional rendering
-return <div>{hasData && <DataDisplay data={data} />}</div>;
-```
-
-## Component Composition
-
-Prefer composition over complex props. Build small, focused components that compose together.
-
-```typescript
-// ✅ Good - Composition pattern
-interface CardProps {
-  children: ReactNode;
-}
-
-export function Card({ children }: CardProps) {
-  return <Box sx={{ padding: 3, borderRadius: 2, boxShadow: 1 }}>{children}</Box>;
-}
-
-export function CardHeader({ children }: { children: ReactNode }) {
-  return (
-    <Box sx={{ marginBottom: 2 }}>
-      <Typography variant="h6">{children}</Typography>
-    </Box>
-  );
-}
-
-export function CardContent({ children }: { children: ReactNode }) {
-  return <Box>{children}</Box>;
-}
-
-// Usage - Flexible and composable
-<Card>
-  <CardHeader>User Profile</CardHeader>
-  <CardContent>
-    <UserDetails user={user} />
-    <UserActions onEdit={handleEdit} />
-  </CardContent>
-</Card>;
-
-// ❌ Bad - Complex props that limit flexibility
-interface ComplexCardProps {
-  title: string;
-  subtitle?: string;
-  actions?: ReactNode;
-  content: ReactNode;
-  variant?: "default" | "highlighted" | "error";
-  showBorder?: boolean;
-  elevation?: number;
-}
-
-export function ComplexCard(props: ComplexCardProps) {
-  // Too many props, hard to extend
-  // ...
-}
-```
-
-## Children Patterns
-
-### Render Props Pattern
-
-Use when child components need access to parent state:
-
-```typescript
-interface DataProviderProps {
-  children: (data: Data, isLoading: boolean) => ReactNode;
-}
-
-export function DataProvider({ children }: DataProviderProps) {
-  const { data, isLoading } = useGetData();
-
-  return <>{children(data, isLoading)}</>;
-}
-
-// Usage
-<DataProvider>
-  {(data, isLoading) => (isLoading ? <Loading /> : <DataDisplay data={data} />)}
-</DataProvider>;
-```
-
-### Compound Components Pattern
-
-For components that work together:
-
-```typescript
-interface TabsContextValue {
-  activeTab: string;
-  setActiveTab: (tab: string) => void;
-}
-
-const TabsContext = createContext<TabsContextValue | undefined>(undefined);
-
-export function Tabs({ children, defaultTab }: { children: ReactNode; defaultTab: string }) {
-  const [activeTab, setActiveTab] = useState(defaultTab);
-
-  return (
-    <TabsContext.Provider value={{ activeTab, setActiveTab }}>
-      <Box>{children}</Box>
-    </TabsContext.Provider>
-  );
-}
-
-export function TabList({ children }: { children: ReactNode }) {
-  return <Box sx={{ display: "flex", gap: 1 }}>{children}</Box>;
-}
-
-export function Tab({ value, children }: { value: string; children: ReactNode }) {
-  const context = useContext(TabsContext);
-  if (!context) throw new Error("Tab must be used within Tabs");
-
-  const { activeTab, setActiveTab } = context;
-  const isActive = activeTab === value;
-
-  return (
-    <Button onClick={() => setActiveTab(value)} variant={isActive ? "contained" : "text"}>
-      {children}
-    </Button>
-  );
-}
-
-export function TabPanel({ value, children }: { value: string; children: ReactNode }) {
-  const context = useContext(TabsContext);
-  if (!context) throw new Error("TabPanel must be used within Tabs");
-
-  if (context.activeTab !== value) return null;
-  return <Box sx={{ padding: 2 }}>{children}</Box>;
-}
-
-// Usage - Intuitive API
-<Tabs defaultTab="profile">
-  <TabList>
-    <Tab value="profile">Profile</Tab>
-    <Tab value="settings">Settings</Tab>
-  </TabList>
-  <TabPanel value="profile">
-    <ProfileContent />
-  </TabPanel>
-  <TabPanel value="settings">
-    <SettingsContent />
-  </TabPanel>
-</Tabs>;
-```
-
-## Error Boundaries
-
-Use error boundaries for graceful error handling:
-
-```typescript
-interface ErrorBoundaryProps {
-  children: ReactNode;
-  fallback?: ReactNode;
-}
-
-interface ErrorBoundaryState {
-  hasError: boolean;
-  error?: Error;
-}
-
-export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
-  constructor(props: ErrorBoundaryProps) {
-    super(props);
-    this.state = { hasError: false };
-  }
-
-  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
-    return { hasError: true, error };
-  }
-
-  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
-    console.error("Error caught by boundary:", error, errorInfo);
-    // Log to error tracking service
-  }
-
-  render() {
-    if (this.state.hasError) {
-      return this.props.fallback || <ErrorFallback error={this.state.error} />;
-    }
-
-    return this.props.children;
-  }
-}
-
-// Usage
-<ErrorBoundary fallback={<ErrorPage />}>
-  <App />
-</ErrorBoundary>;
-```
-
-## Handling Lists
-
-### Key Props
-
-Always use stable, unique keys (never index):
-
-```typescript
-// ✅ Good - Unique, stable ID
-{
-  users.map((user) => <UserCard key={user.id} user={user} />);
-}
-
-// ❌ Bad - Index as key (causes bugs when list changes)
-{
-  users.map((user, index) => <UserCard key={index} user={user} />);
-}
-
-// ✅ Acceptable - Composite key when no ID available
-{
-  items.map((item) => <ItemCard key={`${item.type}-${item.name}`} item={item} />);
-}
-```
-
-### Empty States
-
-Always handle empty lists:
-
-```typescript
-export function UserList({ users }: { users: User[] }) {
-  if (users.length === 0) {
-    return (
-      <EmptyState
-        icon={<PersonIcon />}
-        title="No users found"
-        description="Try adjusting your search criteria"
-      />
-    );
-  }
-
-  return (
-    <Box>
-      {users.map((user) => (
-        <UserCard key={user.id} user={user} />
-      ))}
-    </Box>
-  );
-}
-```
-
-## Conditional Rendering Best Practices
-
-```typescript
-export function ItemCard({ item }: { item: Item }) {
-  // ✅ Good - Early returns for invalid states
-  if (!item) return null;
-  if (item.isDeleted) return null;
-
-  // ✅ Good - Ternary for simple either/or
-  const statusColor = item.isUrgent ? "error" : "default";
-
-  return (
-    <Box>
-      <Typography color={statusColor}>{item.title}</Typography>
-
-      {/* ✅ Good - && for optional elements */}
-      {item.isFeatured && <FeaturedBadge />}
-
-      {/* ✅ Good - Ternary for alternate content */}
-      {item.isAvailable ? <AvailableStatus /> : <UnavailableStatus />}
-
-      {/* ❌ Bad - Nested ternaries (hard to read) */}
-      {item.status === "urgent" ? (
-        <UrgentBadge />
-      ) : item.status === "normal" ? (
-        <NormalBadge />
-      ) : (
-        <DefaultBadge />
-      )}
-
-      {/* ✅ Good - Extract to variable or switch */}
-      <StatusBadge status={item.status} />
-    </Box>
-  );
-}
-```
-
-## Performance Optimization
-
-### When to Use `useMemo`
-
-```typescript
-// ✅ Do - Expensive computation
-const sortedUsers = useMemo(() => [...users].sort((a, b) => a.name.localeCompare(b.name)), [users]);
-
-// ❌ Don't - Simple operations (premature optimization)
-const fullName = useMemo(() => `${firstName} ${lastName}`, [firstName, lastName]);
-```
-
-### When to Use `useCallback`
-
-```typescript
-// ✅ Do - Function passed to memoized child
-const MemoizedChild = React.memo(ChildComponent);
-
-function Parent() {
-  const handleClick = useCallback(() => {
-    console.log("clicked");
-  }, []);
-
-  return <MemoizedChild onClick={handleClick} />;
-}
-
-// ❌ Don't - Function not passed to children
-const handleSubmit = useCallback(() => {
-  // No child components use this
-}, []);
-```
-
-<!-- Source: .ruler/frontend/react.md -->
-
-# React
-
-- Destructure props in function body rather than in function signature
-- Prefer inline JSX rather than extracting variables and functions as variables outside of JSX
-- Use useModalState for any showing/hiding functionality like dialogs
-- Utilize custom hooks to encapsulate and reuse stateful logic
-- When performing data-fetching in a custom hook, always use Zod to define any request and response schemas
-- Use react-hook-form for all form UIs and use zod resolver for form schema validation
-- Use date-fns for any Date based operations like formatting
-
-<!-- Source: .ruler/frontend/styling.md -->
-
-# Styling Standards
-
-## Technology Stack
-
-- **Material UI (MUI)** with custom theme
-- **sx prop** for custom styles (NOT `styled()`)
-- Custom component wrappers for consistent UI
-- **Storybook** as single source of truth for UI components
-
-## Core Principles
-
-1. **Always use `sx` prop** - Never CSS/SCSS/SASS files
-2. **Use theme tokens** - Never hardcode colors, spacing, or sizes
-3. **Leverage meaningful tokens** - Use semantic names like `theme.palette.text.primary`, not `common.white`
-4. **Type-safe theme access** - Use `sx={(theme) => ({...})}`, not string paths like `"text.secondary"`
-5. **Follow spacing system** - Use indices 1-12 (4px-64px)
-6. **Storybook is source of truth** - Check Storybook before Figma
-
-## Restricted Patterns
-
-### ❌ DO NOT USE
-
-- `styled()` from MUI (deprecated in our codebase)
-- `makeStyles()` from MUI (deprecated)
-- CSS/SCSS/SASS files
-- Direct MUI icons from `@mui/icons-material`
-- Direct MUI components without wrappers (except layout primitives; see list below)
-- Inline styles via `style` prop (use `sx` instead)
-- String paths for theme tokens (not type-safe)
-
-### Rationale
-
-1. Component wrappers provide consistent behavior and app-specific functionality
-2. `sx` prop provides type-safe access to theme tokens
-3. Project-specific dialog components ensure consistent UX patterns
-
-## Storybook as Source of Truth
-
-**Important:** Storybook reflects what's actually implemented, not Figma designs.
-
-### When Storybook Differs from Figma
-
-1. **Check Storybook first** - It shows real, implemented components
-2. **Use closest existing variant** - Don't create one-off font sizes/colors
-3. **Confirm changes are intentional** - Consult with team before updating components
-4. **Create follow-up ticket** - If component needs updating but you're short on time
-5. **Make changes system-wide** - Component updates should benefit entire app
-
-### Process
-
-- **Minor differences** (font sizes, colors) → Stick to Storybook
-- **Component looks different** → Confirm with team, update component intentionally
-- **Missing component** → Check with team - it may exist with a different name
-
-## Use Internal Components
-
-### ✅ ALWAYS USE Project Wrappers
-
-Instead of importing directly from `@mui/material`, use project wrappers:
-
-```typescript
-// ❌ Don't
-import { Button, IconButton } from "@mui/material";
-
-// ✅ Do
-import { Button } from "@/components/Button";
-import { IconButton } from "@clipboard-health/ui-components";
-```
-
-### Component Wrapper List (Example)
-
-Common components that may have wrappers:
-
-- `Button`, `LoadingButton`, `IconButton`
-- `Avatar`, `Accordion`, `Badge`
-- `Card`, `Chip`, `Dialog`
-- `Drawer`, `List`, `ListItem`
-- `Rating`, `Slider`, `Switch`
-- `TextField`, `Typography`, `Tab`, `Tabs`
-
-Check your project's ESLint configuration for the full list.
-
-## Icons
-
-### Use Project Icon Component
-
-```typescript
-// ❌ Don't use third-party icons directly
-import SearchIcon from '@mui/icons-material/Search';
-
-// ✅ Use project's icon system
-import { CbhIcon } from '@clipboard-health/ui-components';
-
-<CbhIcon type="search" size="large" />
-<CbhIcon type="search-colored" size="medium" />
-```
-
-### Icon Variants
-
-- Many icon systems have variants for different states (e.g., `-colored` for active states)
-- Check your project's icon documentation for available variants
-
-## Styling with sx Prop
-
-### Basic Usage - Type-Safe Theme Access
-
-❌ **Never** hardcode values or use string paths:
-
-```typescript
-<Box
-  sx={{
-    backgroundColor: "red", // ❌ Raw color
-    color: "#ADFF11", // ❌ Hex code
-    padding: "16px", // ❌ Raw size
-    color: "text.secondary", // ❌ String path (no TypeScript support)
-  }}
-/>
-```
-
-✅ **Always** use theme with type safety:
-
-```typescript
-<Box
-  sx={(theme) => ({
-    backgroundColor: theme.palette.background.primary, // ✅ Semantic token
-    color: theme.palette.text.secondary, // ✅ Type-safe
-    padding: theme.spacing(4), // or just: padding: 4   // ✅ Spacing system
-  })}
-/>
-```
-
-### Use Meaningful Tokens
-
-❌ **Avoid** non-descriptive tokens:
-
-```typescript
-theme.palette.common.white; // ❌ No context about usage
-theme.palette.green300; // ❌ Which green? When to use?
-```
-
-✅ **Use** semantic tokens:
-
-```typescript
-theme.palette.background.tertiary; // ✅ Clear purpose
-theme.palette.instantPay.background; // ✅ Intent is obvious
-theme.palette.text.primary; // ✅ Meaningful
-```
-
-## Spacing System
-
-We use a strict index-based spacing system:
-
-| Index | 1   | 2   | 3   | 4    | 5    | 6    | 7    | 8    | 9    | 10   | 11   | 12   |
-| ----- | --- | --- | --- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- |
-| Size  | 4px | 6px | 8px | 12px | 16px | 20px | 24px | 32px | 40px | 48px | 56px | 64px |
-
-**Usage:**
-
-```typescript
-<Box sx={{ padding: 5 }} />    // → 16px
-<Box sx={{ marginX: 4 }} />    // → 12px left and right
-<Box sx={{ gap: 3 }} />        // → 8px
-```
-
-**Use `rem` for fonts and heights:**
-
-```typescript
-<Box
-  sx={(theme) => ({
-    height: "3rem", // ✅ Scales with user zoom
-    fontSize: theme.typography.body1.fontSize, // ✅ From theme
-    padding: 5, // ✅ px prevents overflow when zoomed
-  })}
-/>
-```
-
-**Reasoning:** Users who adjust device-wide zoom need `rem` for fonts/heights to scale properly, but `px` spacing prevents layout overflow.
-
-## Theme Integration
-
-### Responsive Styles
-
-```typescript
-<Box
-  sx={{
-    width: {
-      xs: "100%", // Mobile
-      sm: "75%", // Tablet
-      md: "50%", // Desktop
-    },
-    padding: {
-      xs: 1,
-      md: 3,
-    },
-  }}
-/>
-```
-
-### Pseudo-classes and Hover States
-
-```typescript
-<Box
-  sx={(theme) => ({
-    "&:hover": {
-      backgroundColor: theme.palette.primary.dark,
-      cursor: "pointer",
-    },
-    "&:disabled": {
-      opacity: 0.5,
-    },
-    "&.active": {
-      borderColor: theme.palette.primary.main,
-    },
-  })}
-/>
-```
-
-### Nested Selectors
-
-```typescript
-<Box
-  sx={(theme) => ({
-    "& .child-element": {
-      color: theme.palette.text.secondary,
-    },
-    "& > div": {
-      marginBottom: 1,
-    },
-    // Target nested MUI components
-    "& .MuiTypography-root": {
-      color: theme.palette.intent?.disabled.text,
-    },
-  })}
-/>
-```
-
-## Shorthand Properties
-
-MUI provides shorthand properties - use full names, not abbreviations:
-
-✅ **Use full names:**
-
-```typescript
-<Box
-  sx={{
-    padding: 2, // ✅ Clear
-    paddingX: 4, // ✅ Readable
-    marginY: 2, // ✅ Explicit
-  }}
-/>
-```
-
-❌ **Avoid abbreviations** (per naming conventions best practice):
-
-```typescript
-<Box
-  sx={{
-    p: 2, // ❌ Too terse
-    px: 4, // ❌ Not clear
-    my: 2, // ❌ What does this mean?
-  }}
-/>
-```
-
-[Full list of shorthand properties](https://mui.com/system/properties/)
-
-## Merging sx Props
-
-For generic components accepting an `sx` prop, merge default styles with custom styles:
-
-```typescript
-// Option 1: Array syntax (MUI native)
-<Box
-  sx={[
-    (theme) => ({
-      backgroundColor: theme.palette.background.tertiary,
-      padding: 2,
-    }),
-    sx, // User's custom sx prop
-  ]}
-  {...restProps}
-/>
-
-// Option 2: Use a utility function if your project provides one
-import { mergeSxProps } from "@clipboard-health/ui-components";
-
-<Box
-  sx={mergeSxProps(defaultStyles, sx)}
-  {...restProps}
-/>;
-```
-
-## Theme Access
-
-### Using useTheme Hook
-
-```typescript
-import { useTheme } from "@mui/material";
-
-export function Component() {
-  const theme = useTheme();
-
-  return (
-    <Box sx={{ color: theme.palette.primary.main }}>
-      {/* Your components */}
-    </Box>
-  );
-}
-```
-
-### Theme Properties
-
-```typescript
-const theme = useTheme();
-
-// Colors
-theme.palette.primary.main;
-theme.palette.secondary.main;
-theme.palette.error.main;
-theme.palette.text.primary;
-theme.palette.background.default;
-
-// Spacing
-theme.spacing(1); // Project-defined (see spacing system above)
-theme.spacing(2); // Project-defined (see spacing system above)
-
-// Typography
-theme.typography.h1;
-theme.typography.body1;
-
-// Breakpoints
-theme.breakpoints.up("md");
-theme.breakpoints.down("sm");
-```
-
-## Modal Patterns
-
-### ❌ Avoid Generic Modal
-
-```typescript
-// Avoid generic Modal when project has specific dialog components
-import { Modal } from "@mui/material";
-```
-
-### ✅ Use Project-Specific Dialog Components
-
-```typescript
-// For mobile-friendly modals
-import { BottomSheet } from "@/components/BottomSheet";
-
-// For full-screen views
-import { FullScreenDialog } from "@/components/FullScreenDialog";
-
-// For standard dialogs
-import { Dialog } from "@/components/Dialog";
-```
-
-Check your project's component library for available dialog/modal components.
-
-## Layout Components
-
-### Use MUI Layout Components
-
-These are safe to import directly from MUI:
-
-```typescript
-import { Box, Stack, Container, Grid } from '@mui/material';
-
-// Stack for vertical/horizontal layouts
-<Stack spacing={2} direction="row">
-  <Item />
-  <Item />
-</Stack>
-
-// Box for flexible containers
-<Box sx={{ display: 'flex', gap: 2 }}>
-  <Child />
-</Box>
-
-// Grid for responsive layouts
-<Grid container spacing={2}>
-  <Grid item xs={12} md={6}>
-    <Content />
-  </Grid>
-</Grid>
-```
-
-## MUI Theme Augmentation
-
-### Type Safety
-
-Projects often augment MUI's theme with custom properties:
-
-```typescript
-// Example: Custom theme augmentation
-declare module "@mui/material/styles" {
-  interface Theme {
-    customSpacing: {
-      small: string;
-      large: string;
-    };
-  }
-  interface ThemeOptions {
-    customSpacing?: {
-      small?: string;
-      large?: string;
-    };
-  }
-}
-```
-
-Check your project's type definitions for available theme augmentations.
-
-## Common Patterns
-
-### Card with Custom Styling
-
-```typescript
-import { Card, CardContent } from "@mui/material";
-
-<Card
-  sx={{
-    borderRadius: 2,
-    boxShadow: 2,
-    "&:hover": {
-      boxShadow: 4,
-    },
-  }}
->
-  <CardContent>Content here</CardContent>
-</Card>;
-```
-
-### Buttons with Theme Colors
-
-```typescript
-import { Button } from "@/components/Button";
-
-<Button
-  variant="contained"
-  color="primary"
-  sx={{
-    textTransform: "none", // Override uppercase
-    fontWeight: "bold",
-  }}
->
-  Submit
-</Button>;
-```
-
-### Conditional Styles
-
-```typescript
-<Box
-  sx={(theme) => ({
-    backgroundColor: isActive
-      ? theme.palette.primary.main
-      : theme.palette.grey[200],
-    padding: 2,
-  })}
->
-  {content}
-</Box>
-```
-
-## Best Practices
-
-- **Check Storybook first** - It's the single source of truth
-- **Use theme tokens** - Never hardcode colors/spacing
-- **Type-safe access** - Function form: `sx={(theme) => ({...})}`
-- **Meaningful tokens** - Semantic names over raw colors
-- **Spacing system** - Indices 1-12 (or `theme.spacing(n)`)
-- **Use shorthand props** - `paddingX`, `marginY` (full names, not `px`, `my`)
-- **Leverage pseudo-classes** - For hover, focus, disabled states
-- **Prefer `sx` over direct props** - `sx` takes priority and is more flexible
-
-<!-- Source: .ruler/frontend/testing.md -->
-
-# Testing Standards
-
-## The Testing Trophy Philosophy
-
-Our testing strategy follows the **Testing Trophy** model:
-
-```text
-        /\_
-       /E2E\         ← End-to-End (smallest layer)
-      /-----\
-     / Integ \       ← Integration (largest layer - FOCUS HERE!)
-    /---------\
-   /   Unit    \     ← Unit Tests (helpers/utilities only)
-  /-------------\
- /    Static     \   ← TypeScript + ESLint (foundation)
-```
-
-**Investment Priority:**
-
-1. **Static** (TypeScript/ESLint) - Free confidence, catches typos and type errors
-2. **Integration** - Most valuable, test how components work together as users experience them
-3. **Unit** - For pure helpers/utilities, NOT UI components
-4. **E2E** - Critical user flows only, slow and expensive
-
-**Key Principle:** Test as close to how users interact with your app as possible. Users don't shallow-render components or call functions in isolation - they interact with features.
-
-## Technology Stack
-
-- **Vitest** for test runner
-- **@testing-library/react** for component testing
-- **@testing-library/user-event** for user interactions
-- **Mock Service Worker (MSW)** for API mocking
-
-## Test File Structure
-
-```typescript
-import { render, screen, waitFor } from "@testing-library/react";
-import { renderHook } from "@testing-library/react";
-import userEvent from "@testing-library/user-event";
-import { describe, expect, it, vi, beforeEach } from "vitest";
-
-describe("ComponentName", () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it("should render correctly", () => {
-    render(<Component />);
-    expect(screen.getByText("Expected")).toBeInTheDocument();
-  });
-
-  it("should handle user interaction", async () => {
-    const user = userEvent.setup();
-    render(<Component />);
-
-    await user.click(screen.getByRole("button", { name: "Submit" }));
-
-    await waitFor(() => {
-      expect(screen.getByText("Success")).toBeInTheDocument();
-    });
-  });
-});
-```
-
-## Test Naming Conventions
-
-### Describe Blocks
-
-- Use the component/function name: `describe('ComponentName', ...)`
-- Nest describe blocks for complex scenarios
-
-```typescript
-describe("ShiftCard", () => {
-  describe("when shift is urgent", () => {
-    it("should display urgent badge", () => {
-      // ...
-    });
-  });
-
-  describe("when shift is booked", () => {
-    it("should show booked status", () => {
-      // ...
-    });
-  });
-});
-```
-
-### Test Names
-
-- Pattern: `'should [expected behavior] when [condition]'`
-- Be descriptive and specific
-
-```typescript
-// Good
-it("should show loading spinner when data is fetching", () => {});
-it("should display error message when API call fails", () => {});
-it("should enable submit button when form is valid", () => {});
-
-// Avoid
-it("works", () => {});
-it("loading state", () => {});
-```
-
-## Parameterized Tests
-
-### Using it.each
-
-```typescript
-it.each([
-  { input: { isUrgent: true }, expected: "URGENT" },
-  { input: { isUrgent: false }, expected: "REGULAR" },
-])("should return $expected when isUrgent is $input.isUrgent", ({ input, expected }) => {
-  expect(getShiftType(input)).toBe(expected);
-});
-```
-
-### Table-Driven Tests
-
-```typescript
-describe("calculateShiftPay", () => {
-  it.each([
-    { hours: 8, rate: 30, expected: 240 },
-    { hours: 10, rate: 25, expected: 250 },
-    { hours: 12, rate: 35, expected: 420 },
-  ])("should calculate $expected for $hours hours at $rate/hr", ({ hours, rate, expected }) => {
-    expect(calculateShiftPay(hours, rate)).toBe(expected);
-  });
-});
-```
-
-## Component Testing (Integration Tests)
-
-Integration tests form the largest part of the Testing Trophy. Test features, not isolated components.
-
-### Rendering Components
-
-```typescript
-import { render, screen } from "@testing-library/react";
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-
-function renderWithProviders(component: ReactElement) {
-  const queryClient = new QueryClient({
-    defaultOptions: {
-      queries: { retry: false },
-    },
-  });
-
-  return render(<QueryClientProvider client={queryClient}>{component}</QueryClientProvider>);
-}
-
-it("should render user name", () => {
-  renderWithProviders(<UserProfile userId="123" />);
-  expect(screen.getByText("John Doe")).toBeInTheDocument();
-});
-```
-
-### Querying Elements - Priority Order
-
-Follow [Testing Library's query priority](https://testing-library.com/docs/queries/about#priority):
-
-1. **`getByRole`** - Best for accessibility (buttons, links, inputs)
-2. **`getByLabelText`** - For form fields with labels
-3. **`getByPlaceholderText`** - For inputs without labels
-4. **`getByText`** - For non-interactive content
-5. **`getByDisplayValue`** - For current input values
-6. **`getByAltText`** - For images
-7. **`getByTitle`** - Less common
-8. **`getByTestId`** - ⚠️ **LAST RESORT** - Use only when no other option exists
-
-```typescript
-// ✅ Prefer accessible queries
-screen.getByRole("button", { name: /submit/i });
-screen.getByLabelText("Email address");
-screen.getByText("Welcome back");
-
-// ❌ Avoid CSS selectors and implementation details
-screen.getByClassName("user-card"); // Users don't see classes
-wrapper.find("UserCard").prop("user"); // Testing implementation
-screen.getByTestId("custom-element"); // Last resort only
-```
-
-### User Interactions
-
-```typescript
-import userEvent from "@testing-library/user-event";
-
-it("should handle form submission", async () => {
-  const user = userEvent.setup();
-  const onSubmit = vi.fn();
-
-  render(<Form onSubmit={onSubmit} />);
-
-  // Type in input
-  await user.type(screen.getByLabelText("Name"), "John Doe");
-
-  // Click button
-  await user.click(screen.getByRole("button", { name: "Submit" }));
-
-  // Assert
-  expect(onSubmit).toHaveBeenCalledWith({ name: "John Doe" });
-});
-```
-
-## Hook Testing (Unit Tests)
-
-Only write unit tests for hooks that contain business logic, not for UI components.
-
-### Using renderHook
-
-```typescript
-import { renderHook, waitFor } from "@testing-library/react";
-
-describe("useCustomHook", () => {
-  it("should return loading state initially", () => {
-    const { result } = renderHook(() => useCustomHook());
-
-    expect(result.current.isLoading).toBe(true);
-  });
-
-  it("should return data after loading", async () => {
-    const { result } = renderHook(() => useCustomHook());
-
-    await waitFor(() => {
-      expect(result.current.isLoading).toBe(false);
-    });
-
-    expect(result.current.data).toEqual(expectedData);
-  });
-});
-```
-
-### Testing Hook Updates
-
-```typescript
-it("should update when dependencies change", async () => {
-  const { result, rerender } = renderHook(({ userId }) => useGetUser(userId), {
-    initialProps: { userId: "1" },
-  });
-
-  await waitFor(() => {
-    expect(result.current.data?.id).toBe("1");
-  });
-
-  // Update props
-  rerender({ userId: "2" });
-
-  await waitFor(() => {
-    expect(result.current.data?.id).toBe("2");
-  });
-});
-```
-
-## MSW (Mock Service Worker)
-
-### Factory Functions Pattern - IMPORTANT
-
-**Always export factory functions, not static handlers**. This allows tests to customize mock responses.
-
-❌ **Don't** export static handlers (ties tests to single response):
-
-```typescript
-// Bad - can only return this one mock
-export const facilityNotesSuccessScenario = rest.get(
-  `${TEST_API_URL}/facilityNotes`,
-  async (_, res, ctx) => res(ctx.status(200), ctx.json(mockFacilityNotes)),
-);
-```
-
-✅ **Do** export factory functions (flexible per test):
-
-```typescript
-// Good - each test can provide custom data
-export const createFacilityNotesTestHandler = (facilityNotes: FacilityNote[]) => {
-  return rest.get<string, Record<string, string>, FacilityNotesResponse>(
-    `${TEST_API_URL}/facilityNotes/:facilityId`,
-    async (_req, res, ctx) => {
-      return res(ctx.status(200), ctx.json(facilityNotes));
-    },
-  );
-};
-
-// Export default success scenario for convenience
-export const facilityNotesTestHandlers = [createFacilityNotesTestHandler(mockFacilityNotes)];
-```
-
-**Usage in tests:**
-
-```typescript
-// In test setup
-mockApiServer.use(
-  createFacilityNotesTestHandler(myCustomFacilityNotes),
-  createExtraTimePaySettingsTestHandler({ payload: customSettings }),
-);
-```
-
-**Rationale:** When endpoints need different responses for different test scenarios, factory functions avoid duplication and inline mocks that become hard to maintain.
-
-## Mocking
-
-### Mocking Modules
-
-```typescript
-import { vi } from "vitest";
-import * as useUserModule from "@/features/user/hooks/useUser";
-
-// Mock entire module
-vi.mock("@/features/user/hooks/useUser");
-
-// Spy on specific function
-const useDefinedWorkerSpy = vi.spyOn(useDefinedWorkerModule, "useDefinedWorker");
-useDefinedWorkerSpy.mockReturnValue(getMockWorker({ id: "123" }));
-```
-
-### Mocking Functions
-
-```typescript
-it("should call callback on success", async () => {
-  const onSuccess = vi.fn();
-
-  render(<Component onSuccess={onSuccess} />);
-
-  await user.click(screen.getByRole("button"));
-
-  await waitFor(() => {
-    expect(onSuccess).toHaveBeenCalledWith(expectedData);
-  });
-});
-```
-
-### Mocking API Calls
-
-```typescript
-import { vi } from "vitest";
-
-vi.mock("@/lib/api", () => ({
-  get: vi.fn().mockResolvedValue({
-    data: { id: "1", name: "Test" },
-  }),
-}));
-```
-
-## Async Testing
-
-### Using waitFor
-
-```typescript
-it("should display data after loading", async () => {
-  render(<AsyncComponent />);
-
-  expect(screen.getByText("Loading...")).toBeInTheDocument();
-
-  await waitFor(() => {
-    expect(screen.getByText("Data loaded")).toBeInTheDocument();
-  });
-});
-```
-
-### Using findBy Queries
-
-```typescript
-it("should display user name", async () => {
-  render(<UserProfile />);
-
-  // findBy automatically waits
-  const name = await screen.findByText("John Doe");
-  expect(name).toBeInTheDocument();
-});
-```
-
-## Test Organization
-
-### Co-location
-
-- Place test files next to source files
-- Use same name with `.test.ts` or `.test.tsx` extension
-
-```text
-Feature/
-├── Component.tsx
-├── Component.test.tsx
-├── utils.ts
-└── utils.test.ts
-```
-
-### Test Helpers
-
-- Create test utilities in `testUtils.ts` or `test-utils.ts`
-- Reusable mocks in `mocks/` folder
-
-```typescript
-// testUtils.ts
-export function getMockShift(overrides = {}): Shift {
-  return {
-    id: "1",
-    title: "Test Shift",
-    ...overrides,
-  };
-}
-```
-
-## What to Test
-
-### ✅ Do Test
-
-- **Integration tests for features** - Multiple components working together
-- **Unit tests for helpers/utilities** - Pure business logic
-- **All states** - Loading, success, error
-- **User interactions** - Clicks, typing, form submissions
-- **Conditional rendering** - Different states/permissions
-
-### ❌ Don't Test
-
-- **UI components in isolation** - Users never shallow-render
-- **Implementation details** - Internal state, function calls
-- **Third-party libraries** - Trust they're tested
-- **Styles/CSS** - Visual regression tests are separate
-
-## Coverage Guidelines
-
-- Aim for high coverage on business logic and utilities
-- Don't obsess over 100% coverage on UI components
-- **Focus on testing behavior**, not implementation
-- If you can't query it the way a user would, you're testing wrong
-
-## Common Patterns
-
-### Testing Loading States
-
-```typescript
-it("should show loading state", () => {
-  render(<Component />);
-  expect(screen.getByRole("progressbar")).toBeInTheDocument();
-});
-```
-
-### Testing Error States
-
-```typescript
-it("should display error message on failure", async () => {
-  // Mock API error
-  vi.mocked(get).mockRejectedValue(new Error("API Error"));
-
-  render(<Component />);
-
-  expect(await screen.findByText("Error loading data")).toBeInTheDocument();
-});
-```
-
-### Testing Conditional Rendering
-
-```typescript
-it("should show premium badge when user is premium", () => {
-  render(<UserCard user={{ ...mockUser, isPremium: true }} />);
-  expect(screen.getByText("Premium")).toBeInTheDocument();
-});
-
-it("should not show premium badge when user is not premium", () => {
-  render(<UserCard user={{ ...mockUser, isPremium: false }} />);
-  expect(screen.queryByText("Premium")).not.toBeInTheDocument();
-});
-```
-
-<!-- Source: .ruler/frontend/typeScript.md -->
-
-# TypeScript Standards
-
-## Core Principles
-
-- **Strict mode enabled** - no `any` unless absolutely necessary (document why)
-- **Prefer type inference** - let TypeScript infer when possible
-- **Explicit return types** for exported functions
-- **Zod for runtime validation** - single source of truth for types and validation
-- **No type assertions** unless unavoidable (prefer type guards)
-
-## Type vs Interface
-
-Use the right tool for the job:
-
-### Use `interface` for:
-
-- **Component props**
-- **Object shapes**
-- **Class definitions**
-- **Anything that might be extended**
-
-```typescript
-// ✅ Good - Interface for props
-interface UserCardProps {
-  user: User;
-  onSelect: (id: string) => void;
-  isHighlighted?: boolean;
-}
-
-// ✅ Good - Interface can be extended
-interface BaseEntity {
-  id: string;
-  createdAt: string;
-}
-
-interface User extends BaseEntity {
-  name: string;
-  email: string;
-}
-```
-
-### Use `type` for:
-
-- **Unions**
-- **Intersections**
-- **Tuples**
-- **Derived/conditional types**
-- **Type aliases**
-
-```typescript
-// ✅ Good - Type for unions
-type Status = "pending" | "active" | "completed" | "failed";
-
-// ✅ Good - Type for intersections
-type UserWithPermissions = User & { permissions: string[] };
-
-// ✅ Good - Type for tuples
-type Coordinate = [number, number];
-
-// ✅ Good - Derived types
-type UserKeys = keyof User;
-type PartialUser = Partial<User>;
-```
-
-## Naming Conventions
-
-### Types and Interfaces
-
-- **Suffix with purpose**: `Props`, `Response`, `Request`, `Options`, `Params`, `State`
-- **No `I` or `T` prefix** (we're not in C# or Java)
-- **PascalCase** for type names
-
-```typescript
-// ✅ Good
-interface ButtonProps { ... }
-type ApiResponse = { ... };
-type UserOptions = { ... };
-
-// ❌ Bad
-interface IButton { ... }  // No I prefix
-type TResponse = { ... };   // No T prefix
-interface buttonProps { ... }  // Wrong case
-```
-
-### Boolean Properties
-
-Always prefix with `is`, `has`, `should`, `can`, `will`:
-
-```typescript
-// ✅ Good
-interface User {
-  isActive: boolean;
-  hasPermission: boolean;
-  shouldNotify: boolean;
-  canEdit: boolean;
-  willExpire: boolean;
-}
-
-// ❌ Bad
-interface User {
-  active: boolean; // Unclear
-  permission: boolean; // Unclear
-  notify: boolean; // Unclear
-}
-```
-
-## Zod Integration
-
-```typescript
-// Define schema first
-const userSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-});
-
-// Infer type from schema
-export type User = z.infer<typeof userSchema>;
-
-// Use for API validation
-const response = await get({
-  url: "/api/users",
-  responseSchema: userSchema,
-});
-```
-
-## Type Guards
-
-```typescript
-export function isEventKey(key: string): key is EventKey {
-  return VALID_EVENT_KEYS.includes(key as EventKey);
-}
-```
-
-## Constants
-
-```typescript
-// Use const assertions for readonly values
-export const STAGES = {
-  DRAFT: "draft",
-  PUBLISHED: "published",
-} as const;
-
-export type Stage = (typeof STAGES)[keyof typeof STAGES];
-```
-
-## Function Types
-
-```typescript
-// Explicit return types for exported functions
-export function calculateTotal(items: Item[]): number {
-  return items.reduce((sum, item) => sum + item.price, 0);
-}
-
-// Prefer interfaces for function props
-interface HandleSubmitProps {
-  userId: string;
-  data: FormData;
-}
-
-export function handleSubmit(props: HandleSubmitProps): Promise<void> {
-  // ...
-}
-```
-
-## Utility Types
-
-TypeScript provides powerful built-in utility types. Use them:
-
-```typescript
-// Partial - Make all properties optional
-type PartialUser = Partial<User>;
-
-// Required - Make all properties required
-type RequiredUser = Required<User>;
-
-// Readonly - Make all properties readonly
-type ReadonlyUser = Readonly<User>;
-
-// Pick - Select specific properties
-type UserIdOnly = Pick<User, "id" | "name">;
-
-// Omit - Remove specific properties
-type UserWithoutPassword = Omit<User, "password">;
-
-// Record - Create object type with specific key/value types
-type UserMap = Record<string, User>;
-
-// NonNullable - Remove null and undefined
-type DefinedString = NonNullable<string | null | undefined>; // string
-
-// ReturnType - Extract return type from function
-function getUser() { return { id: '1', name: 'John' }; }
-type GetUserResult = ReturnType<typeof getUser>;
-
-// Parameters - Extract parameter types from function
-function updateUser(id: string, data: UserData) { ... }
-type UpdateUserParams = Parameters<typeof updateUser>; // [string, UserData]
-```
-
-## Avoiding `any`
-
-The `any` type defeats the purpose of TypeScript. Use alternatives:
-
-```typescript
-// ❌ Bad - Loses all type safety
-function process(data: any) {
-  return data.value; // No error if value doesn't exist!
-}
-
-// ✅ Good - Use unknown for truly unknown types
-function process(data: unknown) {
-  if (typeof data === "object" && data !== null && "value" in data) {
-    return (data as { value: string }).value;
-  }
-  throw new Error("Invalid data");
-}
-
-// ✅ Better - Use generics
-function process<T extends { value: string }>(data: T) {
-  return data.value; // Type safe!
-}
-
-// ✅ Best - Use Zod for runtime validation
-const dataSchema = z.object({ value: z.string() });
-function process(data: unknown) {
-  const parsed = dataSchema.parse(data); // Throws if invalid
-  return parsed.value; // Type safe!
-}
-```
-
-## Generics
-
-Use generics for reusable, type-safe code:
-
-```typescript
-// ✅ Good - Generic function
-function getFirst<T>(array: T[]): T | undefined {
-  return array[0];
-}
-
-const firstNumber = getFirst([1, 2, 3]); // number | undefined
-const firstName = getFirst(["a", "b"]); // string | undefined
-
-// ✅ Good - Generic component
-interface ListProps<T> {
-  items: T[];
-  renderItem: (item: T) => ReactNode;
-  keyExtractor: (item: T) => string;
-}
-
-export function List<T>({ items, renderItem, keyExtractor }: ListProps<T>) {
-  return (
-    <Box>
-      {items.map((item) => (
-        <Box key={keyExtractor(item)}>{renderItem(item)}</Box>
-      ))}
-    </Box>
-  );
-}
-
-// Usage - Type inferred!
-<List
-  items={users}
-  renderItem={(user) => <UserCard user={user} />} // user is User
-  keyExtractor={(user) => user.id}
-/>;
-
-// ✅ Good - Constrained generics
-interface HasId {
-  id: string;
-}
-
-function findById<T extends HasId>(items: T[], id: string): T | undefined {
-  return items.find((item) => item.id === id);
-}
-```
-
-## Runtime Type Checking
-
-Use type guards for runtime type checking:
-
-```typescript
-// ✅ Good - Type predicate
-export function isUser(value: unknown): value is User {
-  return (
-    typeof value === "object" &&
-    value !== null &&
-    "id" in value &&
-    "name" in value &&
-    typeof value.id === "string" &&
-    typeof value.name === "string"
-  );
-}
-
-// Usage
-function processData(data: unknown) {
-  if (isUser(data)) {
-    console.log(data.name); // TypeScript knows data is User
-  }
-}
-
-// ✅ Better - Use Zod (runtime validation + type guard)
-const userSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-});
-
-export function isUser(value: unknown): value is User {
-  return userSchema.safeParse(value).success;
-}
-
-// ✅ Good - Discriminated unions
-type ApiResponse =
-  | { status: "success"; data: User }
-  | { status: "error"; error: string }
-  | { status: "loading" };
-
-function handleResponse(response: ApiResponse) {
-  switch (response.status) {
-    case "success":
-      console.log(response.data); // TypeScript knows data exists
-      break;
-    case "error":
-      console.log(response.error); // TypeScript knows error exists
-      break;
-    case "loading":
-      // TypeScript knows no data or error exists
-      break;
-  }
-}
-```
-
-## Const Assertions
-
-Use `as const` for readonly literal types:
-
-```typescript
-// ✅ Good - Const assertion for object
-export const STATUSES = {
-  PENDING: "pending",
-  ACTIVE: "active",
-  COMPLETED: "completed",
-} as const;
-
-// Type: 'pending' | 'active' | 'completed'
-export type Status = (typeof STATUSES)[keyof typeof STATUSES];
-
-// ✅ Good - Const assertion for array
-export const COLORS = ["red", "blue", "green"] as const;
-export type Color = (typeof COLORS)[number]; // 'red' | 'blue' | 'green'
-
-// ❌ Bad - Without const assertion
-export const STATUSES = {
-  PENDING: "pending", // Type: string (too loose!)
-  ACTIVE: "active",
-};
-```
-
-## Discriminated Unions
-
-Use for state machines and API responses:
-
-```typescript
-// ✅ Good - Discriminated union for query state
-type QueryState<T> =
-  | { status: "idle" }
-  | { status: "loading" }
-  | { status: "success"; data: T }
-  | { status: "error"; error: Error };
-
-function useQueryState<T>(): QueryState<T> {
-  // ...
-}
-
-// Usage - Type narrowing works automatically
-const state = useQueryState<User>();
-
-if (state.status === "success") {
-  console.log(state.data); // TypeScript knows data exists
-}
-
-// ✅ Good - Discriminated union for actions
-type Action =
-  | { type: "SET_USER"; payload: User }
-  | { type: "CLEAR_USER" }
-  | { type: "UPDATE_USER"; payload: Partial<User> };
-
-function reducer(state: State, action: Action) {
-  switch (action.type) {
-    case "SET_USER":
-      return { ...state, user: action.payload }; // payload is User
-    case "CLEAR_USER":
-      return { ...state, user: null }; // no payload
-    case "UPDATE_USER":
-      return { ...state, user: { ...state.user, ...action.payload } };
-  }
-}
-```
-
-## Function Overloads
-
-Use for functions with different parameter/return combinations:
-
-```typescript
-// ✅ Good - Function overloads
-function formatValue(value: string): string;
-function formatValue(value: number): string;
-function formatValue(value: Date): string;
-function formatValue(value: string | number | Date): string {
-  if (typeof value === "string") return value;
-  if (typeof value === "number") return value.toString();
-  return value.toISOString();
-}
-
-// TypeScript knows the return type based on input
-const str1 = formatValue("hello"); // string
-const str2 = formatValue(123); // string
-const str3 = formatValue(new Date()); // string
-```
-
-## Template Literal Types
-
-Use for type-safe string patterns:
-
-```typescript
-// ✅ Good - Event handler props with enforced naming
-type EventHandlers<T extends string> = {
-  [K in T as `on${Capitalize<K>}`]: () => void;
-};
-
-type Props = EventHandlers<"click" | "hover" | "submit">;
-// Results in: { onClick: () => void; onHover: () => void; onSubmit: () => void; }
-
-// ✅ Good - Validate event handler keys
-type ValidateEventKey<K extends string> = K extends `on${Capitalize<string>}` ? K : never;
-
-interface ComponentProps {
-  onClick: () => void; // ✅ Valid
-  onHover: () => void; // ✅ Valid
-  // click: () => void; // ❌ Does not satisfy ValidateEventKey
-}
-
-// ✅ Good - Route paths
-type Route = `/users/${string}` | `/posts/${string}` | "/";
-
-const validRoute: Route = "/users/123"; // ✅
-const invalidRoute: Route = "users/123"; // ❌ Error
-
-// ✅ Good - CSS properties
-type CSSProperty = `${"margin" | "padding"}${"Top" | "Bottom" | "Left" | "Right"}`;
-// 'marginTop' | 'marginBottom' | 'marginLeft' | 'marginRight' | 'paddingTop' | ...
-```
-
-## Mapped Types
-
-Create new types by transforming existing ones:
-
-```typescript
-// ✅ Good - Make all properties optional
-type Optional<T> = {
-  [K in keyof T]?: T[K];
-};
-
-// ✅ Good - Make all properties readonly
-type Immutable<T> = {
-  readonly [K in keyof T]: T[K];
-};
-
-// ✅ Good - Add suffix to all keys
-type Prefixed<T, P extends string> = {
-  [K in keyof T as `${P}${Capitalize<string & K>}`]: T[K];
-};
-
-type User = { name: string; age: number };
-type PrefixedUser = Prefixed<User, "user">;
-// { userName: string; userAge: number }
-```
-
-## Type Narrowing
-
-Let TypeScript narrow types automatically:
-
-```typescript
-// ✅ Good - Typeof narrowing
-function format(value: string | number) {
-  if (typeof value === "string") {
-    return value.toUpperCase(); // TypeScript knows value is string
-  }
-  return value.toFixed(2); // TypeScript knows value is number
-}
-
-// ✅ Good - Truthiness narrowing
-function getLength(value: string | null) {
-  if (value) {
-    return value.length; // TypeScript knows value is string
-  }
-  return 0;
-}
-
-// ✅ Good - In narrowing
-interface Fish {
-  swim: () => void;
-}
-interface Bird {
-  fly: () => void;
-}
-
-function move(animal: Fish | Bird) {
-  if ("swim" in animal) {
-    animal.swim(); // TypeScript knows animal is Fish
-  } else {
-    animal.fly(); // TypeScript knows animal is Bird
-  }
-}
-
-// ✅ Good - Instanceof narrowing
-function handleError(error: unknown) {
-  if (error instanceof Error) {
-    console.log(error.message); // TypeScript knows error is Error
-  }
-}
-```
-
-## Common Patterns
-
-### Optional Chaining & Nullish Coalescing
-
-```typescript
-// ✅ Good - Optional chaining
-const userName = user?.profile?.name;
-
-// ✅ Good - Nullish coalescing (only null/undefined, not '')
-const displayName = userName ?? "Anonymous";
-
-// ❌ Bad - Logical OR (treats '' and 0 as falsy)
-const displayName = userName || "Anonymous";
-```
-
-### Non-null Assertion (Use Sparingly)
-
-```typescript
-// ⚠️ Use sparingly - Only when you're 100% sure
-const user = getUser()!; // Tells TS: trust me, it's not null
-
-// ✅ Better - Handle null case
-const user = getUser();
-if (!user) throw new Error("User not found");
-// Now TypeScript knows user exists
-```
-
-<!-- Source: .ruler/frontend/uiAndStyling.md -->
-
-# UI and Styling
-
-- Use Material UI for components and styling and a mobile-first approach.
-- Favor TanStack Query over "useEffect".
+@AGENTS.md