@clipboard-health/ai-rules 1.2.0 → 1.2.2

package/fullstack/CLAUDE.md

@@ -1,1195 +1 @@
-<!-- Source: .ruler/backend/nestJsApis.md -->
-
-# NestJS APIs
-
-- Use a three-tier architecture:
-  - Controllers in the entrypoints tier translate from data transfer objects (DTOs) to domain objects (DOs) and call the logic tier.
-  - Logic tier services call other services in the logic tier and repos and gateways at the data tier. The logic tier operates only on DOs.
-  - Data tier repos translate from DOs to data access objects (DAOs), call the database using either Prisma for Postgres or Mongoose for MongoDB, and then translate from DAOs to DOs before returning to the logic tier.
-- Use ts-rest to define contracts using Zod schemas, one contract per resource.
-- A controller implements each ts-rest contract.
-- Requests and responses follow the JSON:API specification, including pagination for listings.
-- Use TypeDoc to document public functions, classes, methods, and complex code blocks.
-
-<!-- Source: .ruler/backend/notifications.md -->
-
-# Notifications
-
-Send notifications through [Knock](https://docs.knock.app) using the `@clipboard-health/notifications` NPM library.
-
-## Usage
-
-<embedex source="packages/notifications/examples/usage.md">
-
-1. Search your service for a `NotificationJobEnqueuer` instance. If there isn't one, create and export it:
-
-   ```ts
-   import { NotificationJobEnqueuer } from "@clipboard-health/notifications";
-
-   import { BackgroundJobsService } from "./setup";
-
-   // Create and export one instance of this in your microservice.
-   export const notificationJobEnqueuer = new NotificationJobEnqueuer({
-     // Use your instance of `@clipboard-health/mongo-jobs` or `@clipboard-health/background-jobs-postgres` here.
-     adapter: new BackgroundJobsService(),
-   });
-   ```
-
-1. Implement a minimal job, calling off to a NestJS service for any business logic and to send the notification.
-
-   ```ts
-   import { type BaseHandler } from "@clipboard-health/background-jobs-adapter";
-   import { type NotificationData } from "@clipboard-health/notifications";
-   import { isFailure, toError } from "@clipboard-health/util-ts";
-
-   import { type ExampleNotificationService } from "./exampleNotification.service";
-
-   export type ExampleNotificationData = NotificationData<{
-     workplaceId: string;
-   }>;
-
-   export const EXAMPLE_NOTIFICATION_JOB_NAME = "ExampleNotificationJob";
-
-   // For mongo-jobs, you'll implement HandlerInterface<ExampleNotificationData["Job"]>
-   // For background-jobs-postgres, you'll implement Handler<ExampleNotificationData["Job"]>
-   export class ExampleNotificationJob implements BaseHandler<ExampleNotificationData["Job"]> {
-     public name = EXAMPLE_NOTIFICATION_JOB_NAME;
-
-     constructor(private readonly service: ExampleNotificationService) {}
-
-     async perform(data: ExampleNotificationData["Job"], job: { attemptsCount: number }) {
-       const result = await this.service.sendNotification({
-         ...data,
-         // Include the job's attempts count for debugging, this is called `retryAttempts` in `background-jobs-postgres`.
-         attempt: job.attemptsCount + 1,
-       });
-
-       if (isFailure(result)) {
-         throw toError(result.error);
-       }
-     }
-   }
-   ```
-
-1. Search your service for a constant that stores workflow keys. If there isn't one, create and export it:
-
-   ```ts
-   export const WORKFLOW_KEYS = {
-     eventStartingReminder: "event-starting-reminder",
-   } as const;
-   ```
-
-1. Enqueue your job:
-
-   ```ts
-   import {
-     EXAMPLE_NOTIFICATION_JOB_NAME,
-     type ExampleNotificationData,
-   } from "./exampleNotification.job";
-   import { notificationJobEnqueuer } from "./notificationJobEnqueuer";
-   import { WORKFLOW_KEYS } from "./workflowKeys";
-
-   async function enqueueNotificationJob() {
-     await notificationJobEnqueuer.enqueueOneOrMore<ExampleNotificationData["Enqueue"]>(
-       EXAMPLE_NOTIFICATION_JOB_NAME,
-       // Important: Read the TypeDoc documentation for additional context.
-       {
-         /**
-          * Set expiresAt at enqueue-time so it remains stable across job retries. Use date-fns in your
-          * service instead of this manual calculation.
-          */
-         expiresAt: new Date(Date.now() + 60 * 60_000).toISOString(),
-         // Set idempotencyKey at enqueue-time so it remains stable across job retries.
-         idempotencyKey: {
-           resourceId: "event-123",
-         },
-         // Set recipients at enqueue-time so they respect our notification provider's limits.
-         recipients: ["userId-1"],
-
-         workflowKey: WORKFLOW_KEYS.eventStartingReminder,
-
-         // Any additional enqueue-time data passed to the job:
-         workplaceId: "workplaceId-123",
-       },
-     );
-   }
-
-   // eslint-disable-next-line unicorn/prefer-top-level-await
-   void enqueueNotificationJob();
-   ```
-
-1. Trigger the job in your NestJS service:
-
-   ```ts
-   import { type NotificationClient } from "@clipboard-health/notifications";
-
-   import { type ExampleNotificationData } from "./exampleNotification.job";
-
-   type ExampleNotificationDo = ExampleNotificationData["Job"] & { attempt: number };
-
-   export class ExampleNotificationService {
-     constructor(private readonly client: NotificationClient) {}
-
-     async sendNotification(params: ExampleNotificationDo) {
-       const { attempt, expiresAt, idempotencyKey, recipients, workflowKey, workplaceId } = params;
-
-       // Assume this comes from a database and are used as template variables...
-       // Use @clipboard-health/date-time's formatShortDateTime in your service for consistency.
-       const data = { favoriteColor: "blue", favoriteAt: new Date().toISOString(), secret: "2" };
-
-       // Important: Read the TypeDoc documentation for additional context.
-       return await this.client.trigger({
-         attempt,
-         body: {
-           data,
-           recipients,
-           workplaceId,
-         },
-         expiresAt: new Date(expiresAt),
-         idempotencyKey,
-         keysToRedact: ["secret"],
-         workflowKey,
-       });
-     }
-   }
-   ```
-
-</embedex>
-
-<!-- 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
-export function useFeature(params: Params, options: UseFeatureOptions = {}) {
-  const query = useQuery(...);
-  const computed = useMemo(() => transformData(query.data), [query.data]);
-  const handleAction = useCallback(async () => { /* ... */ }, []);
-
-  return { data: computed, isLoading: query.isLoading, handleAction };
-}
-```
-
-## Naming Rules
-
-- **Always** prefix with `use`
-- Boolean: Use `useIs*`, `useHas*`, or `useCan*` (e.g., `useIsEnabled`, `useHasPermission`, `useCanEdit`)
-- Data: `useGetUser`, `useFeatureData`
-- Actions: `useSubmitForm`
-
-## Return Values
-
-- Return objects (not arrays) for complex hooks
-- Name clearly: `isLoading` not `loading`
-
-## State Management with Constate
-
-Use `constate` for shared state between components:
-
-```typescript
-import constate from "constate";
-
-function useFilters() {
-  const [filters, setFilters] = useState<Filters>({});
-  return { filters, setFilters };
-}
-
-export const [FiltersProvider, useFiltersContext] = constate(useFilters);
-```
-
-**When to use:** Sharing state between siblings, feature-level state
-**When NOT:** Server state (use React Query), simple parent-child (use props)
-
-## Hook Patterns
-
-```typescript
-// Boolean hooks
-export function useIsFeatureEnabled(): boolean {
-  return useFeatureFlags().includes("feature");
-}
-
-// Data transformation
-export function useTransformedData() {
-  const { data, isLoading } = useGetRawData();
-  const transformed = useMemo(() => data?.map(format), [data]);
-  return { data: transformed, isLoading };
-}
-
-// Composite hooks
-export function useBookingsData() {
-  const shifts = useGetShifts();
-  const invites = useGetInvites();
-
-  const combined = useMemo(
-    () => [...(shifts.data ?? []), ...(invites.data ?? [])],
-    [shifts.data, invites.data],
-  );
-
-  return { data: combined, isLoading: shifts.isLoading || invites.isLoading };
-}
-```
-
-## Best Practices
-
-- Use options object for flexibility
-- Be explicit about dependencies
-- API hooks in `api/`, logic hooks in `hooks/`
-- Return stable references with `useCallback`/`useMemo`
-
-<!-- Source: .ruler/frontend/data-fetching.md -->
-
-# Data Fetching Standards
-
-## Technology Stack
-
-- **React Query** (@tanstack/react-query) for all API calls
-- **Zod** for response validation
-
-## Core Principles
-
-1. **Use URL and query parameters in query keys** - Makes cache invalidation predictable
-2. **Define Zod schemas** for all API requests/responses
-3. **Rely on React Query state** - Use `isLoading`, `isError`, `isSuccess`
-4. **Use `enabled` for conditional fetching**
-5. **Use `invalidateQueries` for disabled queries** - Not `refetch()` which ignores enabled state
-
-## Hook Patterns
-
-```typescript
-// Simple query
-export function useGetUser(userId: string) {
-  return useQuery({
-    queryKey: ["users", userId],
-    queryFn: () => api.get(`/users/${userId}`),
-    responseSchema: userSchema,
-    enabled: !!userId,
-  });
-}
-
-// Paginated query
-export function usePaginatedItems(params: Params) {
-  return useInfiniteQuery({
-    queryKey: ["items", params],
-    queryFn: ({ pageParam }) => api.get("/items", { cursor: pageParam, ...params }),
-    getNextPageParam: (lastPage) => lastPage.nextCursor,
-  });
-}
-
-// Mutations
-export function useCreateItem() {
-  const queryClient = useQueryClient();
-  return useMutation({
-    mutationFn: (data: CreateItemRequest) => api.post("/items", data),
-    onSuccess: () => queryClient.invalidateQueries(["items"]),
-  });
-}
-```
-
-## Error Handling
-
-For detailed error handling strategies, see `error-handling.md`.
-
-```typescript
-useQuery({
-  queryKey: ["resource"],
-  queryFn: fetchResource,
-  useErrorBoundary: (error) => {
-    // Show error boundary for 500s, not 404s
-    return !(axios.isAxiosError(error) && error.response?.status === 404);
-  },
-  retry: (failureCount, error) => {
-    // Don't retry 4xx errors
-    if (axios.isAxiosError(error) && error.response?.status < 500) return false;
-    return failureCount < 3;
-  },
-});
-```
-
-## Query Keys
-
-```typescript
-// Include URL and params for predictable cache invalidation
-export const queryKeys = {
-  users: ["users"] as const,
-  user: (id: string) => ["users", id] as const,
-  userPosts: (id: string) => ["users", id, "posts"] as const,
-};
-```
-
-## Conditional Fetching
-
-```typescript
-const { data } = useQuery({
-  queryKey: ["resource", id],
-  queryFn: () => fetchResource(id),
-  enabled: !!id, // Only fetch when id exists
-});
-```
-
-## Naming Conventions
-
-- `useGetX` - Simple queries
-- `usePaginatedX` - Infinite queries
-- `useCreateX`, `useUpdateX`, `useDeleteX` - Mutations
-
-## Hook Location
-
-Place in `api/` folder within feature directory. One endpoint = one hook.
-
-<!-- Source: .ruler/frontend/error-handling.md -->
-
-# Error Handling Standards
-
-## React Query Error Handling
-
-```typescript
-useQuery({
-  queryKey: ["resource"],
-  queryFn: fetchResource,
-  useErrorBoundary: (error) => {
-    // Show error boundary for 500s, not 404s
-    return !(axios.isAxiosError(error) && error.response?.status === 404);
-  },
-  retry: (failureCount, error) => {
-    // Don't retry 4xx errors
-    if (axios.isAxiosError(error) && error.response?.status < 500) return false;
-    return failureCount < 3;
-  },
-});
-```
-
-## Component Error States
-
-```typescript
-export function DataComponent() {
-  const { data, isLoading, isError, refetch } = useGetData();
-
-  if (isLoading) return <LoadingState />;
-  if (isError) return <ErrorState onRetry={refetch} />;
-
-  return <DataDisplay data={data} />;
-}
-```
-
-## Mutation Error Handling
-
-```typescript
-export function useCreateDocument() {
-  return useMutation({
-    mutationFn: createDocumentApi,
-    onSuccess: () => {
-      queryClient.invalidateQueries(["documents"]);
-      showSuccessToast("Document created");
-    },
-    onError: (error) => {
-      logError("CREATE_DOCUMENT_FAILURE", error);
-      showErrorToast("Failed to create document");
-    },
-  });
-}
-```
-
-## Validation Errors
-
-```typescript
-// Zod validation
-const formSchema = z.object({
-  email: z.string().email("Invalid email"),
-  age: z.number().min(18, "Must be 18+"),
-});
-
-try {
-  const validated = formSchema.parse(formData);
-} catch (error) {
-  if (error instanceof z.ZodError) {
-    error.errors.forEach((err) => showFieldError(err.path.join("."), err.message));
-  }
-}
-```
-
-## Error Boundaries
-
-```typescript
-export class ErrorBoundary extends Component<Props, State> {
-  state = { hasError: false };
-
-  static getDerivedStateFromError(error: Error) {
-    return { hasError: true, error };
-  }
-
-  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
-    logEvent("ERROR_BOUNDARY", { error: error.message });
-  }
-
-  render() {
-    return this.state.hasError ? <ErrorFallback /> : this.props.children;
-  }
-}
-```
-
-## Best Practices
-
-- **Always handle errors** - Check `isError` state
-- **User-friendly messages** - Don't show technical errors
-- **Log for debugging** - Include context
-- **Provide recovery actions** - Retry, dismiss, navigate
-- **Different strategies** - Error boundary vs inline vs retry
-
-<!-- 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)
-```
-
-## Naming Conventions
-
-- Components: `PascalCase.tsx` (`UserProfile.tsx`)
-- Hooks: `camelCase.ts` (`useUserProfile.ts`)
-- Utils: `camelCase.ts` (`formatDate.ts`)
-- Types: `camelCase.types.ts` (`user.types.ts`)
-- Tests: `ComponentName.test.tsx`
-
-<!-- Source: .ruler/frontend/react-patterns.md -->
-
-# React Component Patterns
-
-## Component Structure
-
-```typescript
-interface Props {
-  userId: string;
-  onUpdate?: (user: User) => void;
-}
-
-export function UserProfile({ userId, onUpdate }: Props) {
-  // 1. Hooks
-  const { data, isLoading, error } = useGetUser(userId);
-  const [isEditing, setIsEditing] = useState(false);
-
-  // 2. Derived state (avoid useMemo for inexpensive operations)
-  const displayName = formatName(data);
-
-  // 3. Event handlers
-  const handleSave = useCallback(async () => {
-    await saveUser(data);
-    onUpdate?.(data);
-  }, [data, onUpdate]);
-
-  // 4. Early returns
-  if (isLoading) return <Loading />;
-  if (error) return <Error message={error.message} />;
-  if (!data) return <NotFound />;
-
-  // 5. Main render
-  return (
-    <Card>
-      <Typography>{displayName}</Typography>
-      <Button onClick={handleSave}>Save</Button>
-    </Card>
-  );
-}
-```
-
-## Naming Conventions
-
-- Components: `PascalCase` (`UserProfile`)
-- Props interface: `Props` (co-located with component) or `ComponentNameProps` (exported/shared)
-- Event handlers: `handle*` (`handleClick`, `handleSubmit`)
-- Boolean props: `is*`, `has*`, `should*`
-
-## Props Patterns
-
-```typescript
-// Simple props
-interface Props {
-  title: string;
-  count: number;
-  onAction: () => void;
-}
-
-// Discriminated unions for variants
-type ButtonProps = { variant: "link"; href: string } | { variant: "button"; onClick: () => void };
-
-// Optional callbacks
-interface Props {
-  onSuccess?: (data: Data) => void;
-  onError?: (error: Error) => void;
-}
-```
-
-## Composition Patterns
-
-```typescript
-// Container/Presentational
-export function UserListContainer() {
-  const { data, isLoading, error } = useUsers();
-  if (isLoading) return <Loading />;
-  if (error) return <Error />;
-  return <UserList users={data} />;
-}
-
-// Compound components
-<Card>
-  <Card.Header title="User" />
-  <Card.Body>Content</Card.Body>
-  <Card.Actions>
-    <Button>Save</Button>
-  </Card.Actions>
-</Card>
-
-// Render props
-<DataProvider>
-  {({ data, isLoading }) => (
-    isLoading ? <Loading /> : <Display data={data} />
-  )}
-</DataProvider>
-```
-
-## Children Patterns
-
-```typescript
-// Typed children
-interface Props {
-  children: ReactNode;
-}
-
-// Render prop pattern
-interface Props {
-  children: (data: Data) => ReactNode;
-}
-
-// Element restrictions
-interface Props {
-  children: ReactElement<ButtonProps>;
-}
-```
-
-## List Rendering
-
-```typescript
-// ✅ Proper keys
-{users.map((user) => <UserCard key={user.id} user={user} />)}
-
-// ✅ Empty states
-{users.length === 0 ? <EmptyState /> : users.map(...)}
-
-// ❌ Never use index as key when list can change
-{items.map((item, index) => <Item key={index} />)} // Wrong!
-```
-
-## Conditional Rendering
-
-```typescript
-// Simple conditional
-{isLoading && <Spinner />}
-
-// If-else
-{isError ? <Error /> : <Success />}
-
-// Multiple conditions
-{isLoading ? <Loading /> : isError ? <Error /> : <Data />}
-
-// With early returns (preferred for complex logic)
-if (isLoading) return <Loading />;
-if (isError) return <Error />;
-return <Data />;
-```
-
-## Performance
-
-```typescript
-// Memoize expensive components
-const MemoItem = memo(({ item }: Props) => <div>{item.name}</div>);
-
-// Split state to avoid re-renders
-function Parent() {
-  const [count, setCount] = useState(0);
-  const [text, setText] = useState("");
-
-  // Only CountDisplay re-renders when count changes
-  return (
-    <>
-      <CountDisplay count={count} />
-      <TextInput value={text} onChange={setText} />
-    </>
-  );
-}
-```
-
-## Best Practices
-
-- **Single Responsibility** - One component, one purpose
-- **Composition over Props** - Use children and compound components
-- **Colocate State** - Keep state close to where it's used
-- **Type Everything** - Full TypeScript coverage
-- **Test Behavior** - Test user interactions, not implementation
-
-<!-- Source: .ruler/frontend/react.md -->
-
-# React
-
-- Destructure props in function body (improves readability and prop documentation)
-- Prefer inline JSX over extracted variables
-- Use custom hooks to encapsulate and reuse stateful logic
-- Use Zod for request/response schemas in data-fetching hooks
-- Use react-hook-form with Zod resolver for forms
-- Use date-fns for date operations
-
-<!-- Source: .ruler/frontend/styling.md -->
-
-# Styling Standards
-
-## Core Principles
-
-1. **Always use `sx` prop** - Never CSS/SCSS/SASS files
-2. **Use theme tokens** - Never hardcode colors/spacing
-3. **Type-safe theme access** - Use `sx={(theme) => ({...})}`
-4. **Use semantic names** - `theme.palette.text.primary`, not `common.white`
-5. **Check Storybook first** - It's the single source of truth
-
-## Restricted Patterns
-
-❌ **DO NOT USE:**
-
-- `styled()` or `makeStyles()` from MUI
-- CSS/SCSS/SASS files
-- Inline `style` prop (use `sx` instead)
-- String paths for theme (`"text.secondary"` - not type-safe)
-
-## Type-Safe Theme Access
-
-```typescript
-// ✅ Always use function form for type safety
-<Box sx={(theme) => ({
-  backgroundColor: theme.palette.background.primary,
-  color: theme.palette.text.secondary,
-  padding: theme.spacing(4), // or just: 4
-})} />
-
-// ❌ Never hardcode
-<Box sx={{
-  backgroundColor: "red", // ❌ Raw color
-  padding: "16px", // ❌ Raw size
-  color: "text.secondary", // ❌ String path
-}} />
-```
-
-## Spacing System
-
-Use indices 1-12 (4px-64px):
-
-```typescript
-<Box sx={{ padding: 5 }} />    // → 16px
-<Box sx={{ marginX: 4 }} />    // → 12px left and right
-<Box sx={{ gap: 3 }} />        // → 8px
-```
-
-**Use `rem` for fonts/heights (scales with user zoom), `px` for spacing:**
-
-```typescript
-<Box sx={(theme) => ({
-  height: "3rem", // ✅ Scales
-  fontSize: theme.typography.body1.fontSize,
-  padding: 5, // ✅ Prevents overflow
-})} />
-```
-
-## Responsive Styles
-
-```typescript
-<Box sx={{
-  width: { xs: "100%", md: "50%" },
-  padding: { xs: 1, md: 3 },
-}} />
-```
-
-## Pseudo-classes
-
-```typescript
-<Box sx={(theme) => ({
-  "&:hover": { backgroundColor: theme.palette.primary.dark },
-  "&:disabled": { opacity: 0.5 },
-  "& .child": { color: theme.palette.text.secondary },
-})} />
-```
-
-## Shorthand Properties
-
-✅ Use full names: `padding`, `paddingX`, `marginY`
-❌ Avoid abbreviations: `p`, `px`, `my`
-
-## Layout Components
-
-Safe to import directly from MUI:
-
-```typescript
-import { Box, Stack, Container, Grid } from "@mui/material";
-```
-
-## Best Practices
-
-- Type-safe access with `sx={(theme) => ({...})}`
-- Use semantic token names
-- Full property names, not abbreviations
-
-<!-- Source: .ruler/frontend/testing.md -->
-
-# Testing Standards
-
-## Testing Trophy Philosophy
-
-Focus on **Integration tests** - test how components work together as users experience them.
-
-**Investment Priority:**
-
-1. **Static** (TypeScript/ESLint) - Free confidence
-2. **Integration** - Most valuable, test features not isolated components
-3. **Unit** - For pure helpers/utilities only
-4. **E2E** - Critical flows only
-
-**Key Principle:** Test as close to how users interact with your app as possible.
-
-## 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 Structure
-
-```typescript
-describe("ComponentName", () => {
-  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
-
-Pattern: `should [behavior] when [condition]`
-
-## Querying Elements - Priority Order
-
-1. `getByRole` - Best for accessibility
-2. `getByLabelText` - For form fields
-3. `getByText` - For non-interactive content
-4. `getByTestId` - ⚠️ **LAST RESORT**
-
-```typescript
-// ✅ Prefer
-screen.getByRole("button", { name: /submit/i });
-screen.getByLabelText("Email");
-
-// ❌ Avoid
-screen.getByClassName("user-card");
-screen.getByTestId("element");
-```
-
-## User Interactions
-
-```typescript
-it("should handle form submission", async () => {
-  const user = userEvent.setup();
-  const onSubmit = vi.fn();
-  render(<Form onSubmit={onSubmit} />);
-
-  await user.type(screen.getByLabelText("Name"), "John");
-  await user.click(screen.getByRole("button", { name: "Submit" }));
-
-  expect(onSubmit).toHaveBeenCalledWith({ name: "John" });
-});
-```
-
-## Hook Testing
-
-```typescript
-describe("useCustomHook", () => {
-  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);
-  });
-});
-```
-
-## MSW Pattern
-
-**Always export factory functions, not static handlers:**
-
-```typescript
-// ✅ Good - flexible per test
-export const createTestHandler = (data: Data[]) =>
-  rest.get(`/api/resource`, (req, res, ctx) => res(ctx.json(data)));
-
-// Usage
-mockServer.use(createTestHandler(customData));
-```
-
-## Mocking
-
-```typescript
-vi.mock("@/lib/api", () => ({
-  get: vi.fn().mockResolvedValue({ data: { id: "1" } }),
-}));
-```
-
-## What to Test
-
-**✅ Do Test:**
-
-- Integration tests for features
-- Unit tests for utilities
-- All states (loading, success, error)
-- User interactions
-
-**❌ Don't Test:**
-
-- Implementation details
-- Third-party libraries
-- Styles/CSS
-
-<!-- Source: .ruler/frontend/typeScript.md -->
-
-# TypeScript Standards
-
-## Core Principles
-
-- **Strict mode enabled** - Avoid `any`
-- **Prefer type inference** - Let TypeScript infer when possible
-- **Explicit return types** for exported functions
-- **Zod for runtime validation** - Single source of truth
-- **No type assertions** unless unavoidable
-
-## Type vs Interface
-
-```typescript
-// ✅ Use interface for: props, object shapes, extensible types
-interface UserCardProps {
-  user: User;
-  onSelect: (id: string) => void;
-}
-
-interface BaseEntity {
-  id: string;
-  createdAt: string;
-}
-
-interface User extends BaseEntity {
-  name: string;
-}
-
-// ✅ Use type for: unions, intersections, tuples, derived types
-type Status = "pending" | "active" | "completed";
-type UserWithRoles = User & { roles: string[] };
-type Coordinate = [number, number];
-type UserKeys = keyof User;
-```
-
-## Naming Conventions
-
-```typescript
-// ✅ Suffix with purpose (no I or T prefix)
-interface ButtonProps { ... }
-type ApiResponse = { ... };
-type UserOptions = { ... };
-
-// ✅ Boolean properties
-interface User {
-  isActive: boolean;
-  hasPermission: boolean;
-  shouldNotify: boolean;
-}
-```
-
-## Zod Integration
-
-```typescript
-// Define schema, infer type
-const userSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-});
-
-export type User = z.infer<typeof userSchema>;
-
-// Validate API responses
-const response = await get({
-  url: "/api/users",
-  responseSchema: userSchema,
-});
-```
-
-## Type Guards
-
-```typescript
-export function isUser(value: unknown): value is User {
-  return userSchema.safeParse(value).success;
-}
-
-// Usage
-if (isUser(data)) {
-  console.log(data.name); // TypeScript knows data is User
-}
-```
-
-## Constants
-
-```typescript
-// Use const assertions
-export const STATUSES = {
-  DRAFT: "draft",
-  PUBLISHED: "published",
-} as const;
-
-export type Status = (typeof STATUSES)[keyof typeof STATUSES];
-```
-
-## Utility Types
-
-```typescript
-// Built-in utilities
-type PartialUser = Partial<User>;
-type RequiredUser = Required<User>;
-type ReadonlyUser = Readonly<User>;
-type UserIdOnly = Pick<User, "id" | "name">;
-type UserWithoutPassword = Omit<User, "password">;
-type UserMap = Record<string, User>;
-type DefinedString = NonNullable<string | null>;
-
-// Function utilities
-type GetUserResult = ReturnType<typeof getUser>;
-type UpdateUserParams = Parameters<typeof updateUser>;
-```
-
-## Avoiding `any`
-
-```typescript
-// ❌ Bad - Loses type safety
-function process(data: any) { ... }
-
-// ✅ Use unknown for truly unknown types
-function process(data: unknown) {
-  if (typeof data === "object" && data !== null) {
-    // Type guard
-  }
-}
-
-// ✅ Better - Use generics
-function process<T extends { value: string }>(data: T) {
-  return data.value;
-}
-
-// ✅ Best - Use Zod
-const dataSchema = z.object({ value: z.string() });
-function process(data: unknown) {
-  const parsed = dataSchema.parse(data);
-  return parsed.value;
-}
-```
-
-## Generics
-
-```typescript
-// Generic function
-function getFirst<T>(array: T[]): T | undefined {
-  return array[0];
-}
-
-// Generic component
-interface ListProps<T> {
-  items: T[];
-  renderItem: (item: T) => ReactNode;
-}
-
-export function List<T>({ items, renderItem }: ListProps<T>) {
-  return <>{items.map((item) => renderItem(item))}</>;
-}
-
-// Constrained generics
-function findById<T extends { id: string }>(items: T[], id: string): T | undefined {
-  return items.find((item) => item.id === id);
-}
-```
-
-## Discriminated Unions
-
-```typescript
-// State machine
-type QueryState<T> =
-  | { status: "idle" }
-  | { status: "loading" }
-  | { status: "success"; data: T }
-  | { status: "error"; error: Error };
-
-// Automatic type narrowing
-if (state.status === "success") {
-  console.log(state.data); // TypeScript knows data exists
-}
-
-// Actions
-type Action = { type: "SET_USER"; payload: User } | { type: "CLEAR_USER" };
-
-function reducer(state: State, action: Action) {
-  switch (action.type) {
-    case "SET_USER":
-      return { ...state, user: action.payload };
-    case "CLEAR_USER":
-      return { ...state, user: null };
-  }
-}
-```
-
-## Type Narrowing
-
-```typescript
-// typeof
-function format(value: string | number) {
-  if (typeof value === "string") {
-    return value.toUpperCase();
-  }
-  return value.toFixed(2);
-}
-
-// in operator
-function move(animal: Fish | Bird) {
-  if ("swim" in animal) {
-    animal.swim();
-  } else {
-    animal.fly();
-  }
-}
-
-// instanceof
-function handleError(error: unknown) {
-  if (error instanceof Error) {
-    console.log(error.message);
-  }
-}
-```
-
-## Common Patterns
-
-```typescript
-// Optional chaining
-const userName = user?.profile?.name;
-
-// Nullish coalescing
-const displayName = userName ?? "Anonymous";
-
-// Non-null assertion (use sparingly)
-const user = getUser()!;
-
-// Template literal types
-type Route = `/users/${string}` | `/posts/${string}`;
-type EventHandler = `on${Capitalize<string>}`;
-```
-
-## Best Practices
-
-- **Never use `any`** - Use `unknown` or generics
-- **Discriminated unions** for state machines
-- **Zod** for runtime validation
-- **Type guards** over type assertions
-- **Const assertions** for readonly values
-- **Utility types** to transform existing types
+@AGENTS.md