@clipboard-health/ai-rules 1.2.0 → 1.2.2

package/frontend/CLAUDE.md

@@ -1,1037 +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
-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