@clipboard-health/ai-rules 1.6.43 → 1.7.0

package/fullstack/AGENTS.md

@@ -1,1251 +1,1138 @@
 <!-- Generated by Ruler -->
 
-<!-- Source: .ruler/backend/nestJsApis.md -->
+<!-- Source: .ruler/backend/architecture.md -->
 
-# NestJS APIs
+# Architecture
 
-- 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.
+## Three-Tier Architecture
 
-<!-- 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">
-
-### `triggerChunked`
-
-`triggerChunked` stores the full, immutable trigger request at job enqueue time, eliminating issues with stale data, chunking requests to stay under provider limits, and idempotency key conflicts that can occur if the request is updated at job execution time.
-
-1. Search your service for `triggerNotification.constants.ts`, `triggerNotification.job.ts` and `notifications.service.ts`. If they don't exist, create them:
-
-   ```ts
-   // triggerNotification.constants.ts
-   export const TRIGGER_NOTIFICATION_JOB_NAME = "TriggerNotificationJob";
-   ```
-
-   ```ts
-   // triggerNotification.job.ts
-   import { type BaseHandler } from "@clipboard-health/background-jobs-adapter";
-   import {
-     type SerializableTriggerChunkedRequest,
-     toTriggerChunkedRequest,
-   } from "@clipboard-health/notifications";
-   import { isFailure } from "@clipboard-health/util-ts";
-
-   import { type NotificationsService } from "./notifications.service";
-   import { CBHLogger } from "./setup";
-   import { TRIGGER_NOTIFICATION_JOB_NAME } from "./triggerNotification.constants";
-
-   /**
-    * For @clipboard-health/mongo-jobs:
-    * 1. Implement `HandlerInterface<SerializableTriggerChunkedRequest>`.
-    * 2. The 10 default `maxAttempts` with exponential backoff of `2^attemptsCount` means ~17 minutes
-    *    of cumulative delay. If your notification could be stale before this, set
-    *    `SerializableTriggerChunkedRequest.expiresAt` when enqueueing.
-    *
-    * For @clipboard-health/background-jobs-postgres:
-    * 1. Implement `Handler<SerializableTriggerChunkedRequest>`.
-    * 2. The 20 default `maxRetryAttempts` with exponential backoff of `10s * 2^(attempt - 1)` means
-    *    ~121 days of cumulative delay. If your notification could be stale before this, set
-    *    `maxRetryAttempts` (and `SerializableTriggerChunkedRequest.expiresAt`) when enqueueing.
-    */
-   export class TriggerNotificationJob implements BaseHandler<SerializableTriggerChunkedRequest> {
-     // For background-jobs-postgres, use `public static queueName = TRIGGER_NOTIFICATION_JOB_NAME;`
-     public name = TRIGGER_NOTIFICATION_JOB_NAME;
-     private readonly logger = new CBHLogger({
-       defaultMeta: {
-         logContext: TRIGGER_NOTIFICATION_JOB_NAME,
-       },
-     });
-
-     public constructor(private readonly service: NotificationsService) {}
-
-     public async perform(
-       data: SerializableTriggerChunkedRequest,
-       /**
-        * For mongo-jobs, implement `BackgroundJobType<SerializableTriggerChunkedRequest>`, which has
-        *    `_id`, `attemptsCount`, and `uniqueKey`.
-        *
-        * For background-jobs-postgres, implement `Job<SerializableTriggerChunkedRequest>`, which has
-        *    `id`, `retryAttempts`, and `idempotencyKey`.
-        */
-       job: { _id: string; attemptsCount: number; uniqueKey?: string },
-     ) {
-       const metadata = {
-         // For background-jobs-postgres, this is called `retryAttempts`.
-         attempt: job.attemptsCount + 1,
-         jobId: job._id,
-         recipientCount: data.body.recipients.length,
-         workflowKey: data.workflowKey,
-       };
-       this.logger.info("TriggerNotificationJob processing", metadata);
-
-       try {
-         const request = toTriggerChunkedRequest(data, {
-           attempt: metadata.attempt,
-           idempotencyKey: job.uniqueKey ?? metadata.jobId,
-         });
-         const result = await this.service.triggerChunked(request);
-
-         if (isFailure(result)) {
-           throw result.error;
-         }
-
-         const success = "TriggerNotificationJob success";
-         this.logger.info(success, { ...metadata, response: result.value });
-         // For background-jobs-postgres, return the `success` string result.
-       } catch (error) {
-         this.logger.error("TriggerNotificationJob failure", { ...metadata, error });
-         throw error;
-       }
-     }
-   }
-   ```
-
-   ```ts
-   // notifications.service.ts
-   import { NotificationClient } from "@clipboard-health/notifications";
-
-   import { CBHLogger, toLogger, tracer } from "./setup";
-
-   export class NotificationsService {
-     private readonly client: NotificationClient;
-
-     constructor() {
-       this.client = new NotificationClient({
-         apiKey: "YOUR_KNOCK_API_KEY",
-         logger: toLogger(new CBHLogger()),
-         tracer,
-       });
-     }
-
-     async triggerChunked(
-       params: Parameters<NotificationClient["triggerChunked"]>[0],
-     ): ReturnType<NotificationClient["triggerChunked"]> {
-       return await this.client.triggerChunked(params);
-     }
-   }
-   ```
-
-2. Search the service for a constant that stores workflow keys. If there isn't one, create it:
-
-   ```ts
-   /* eslint sort-keys: "error" */
-
-   /**
-    * Alphabetical list of workflow keys.
-    */
-   export const WORKFLOW_KEYS = {
-     eventStartingReminder: "event-starting-reminder",
-   } as const;
-   ```
-
-3. Build your `SerializableTriggerChunkedRequest` and enqueue your job. Think of queuing `TriggerNotificationJob` as a function call to send notifications in a best practices way. You should NOT call `triggerChunked` directly. If, for example, your notification is delayed, create a background job that runs in the future, does any necessary checks to ensure you should notify, and then queue `TriggerNotificationJob`.
-
-   ```ts
-   import { type BackgroundJobsAdapter } from "@clipboard-health/background-jobs-adapter";
-   import { type SerializableTriggerChunkedRequest } from "@clipboard-health/notifications";
-
-   import { BackgroundJobsService } from "./setup";
-   import { TRIGGER_NOTIFICATION_JOB_NAME } from "./triggerNotification.constants";
-   import { WORKFLOW_KEYS } from "./workflowKeys";
-
-   /**
-    * Enqueue a notification job in the same database transaction as the changes it's notifying about.
-    * The `session` option is called `transaction` in `background-jobs-postgres`.
-    */
-   async function enqueueTriggerNotificationJob(adapter: BackgroundJobsAdapter) {
-     // Assume this comes from a database and are used as template variables...
-     const notificationData = {
-       favoriteColor: "blue",
-       // Use @clipboard-health/date-time's formatShortDateTime in your service for consistency.
-       favoriteAt: new Date().toISOString(),
-       secret: "2",
-     };
-
-     const jobData: SerializableTriggerChunkedRequest = {
-       // Important: Read the TypeDoc documentation for additional context.
-       body: {
-         recipients: ["userId-1", "userId-2"],
-         data: notificationData,
-       },
-       // Helpful when controlling notifications with feature flags.
-       dryRun: false,
-       // 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(),
-       // Keys to redact from logs
-       keysToRedact: ["secret"],
-       workflowKey: WORKFLOW_KEYS.eventStartingReminder,
-     };
-
-     // Option 1 (default): Automatically use background job ID as idempotency key.
-     await adapter.enqueue(TRIGGER_NOTIFICATION_JOB_NAME, jobData, { session: "..." });
-
-     // Option 2 (advanced): Provide custom idempotency key to job and notification libraries for more
-     // control. You'd use this to provide enqueue-time deduplication. For example, if you enqueue when
-     // a user clicks a button and only want them to receive one notification.
-     await adapter.enqueue(TRIGGER_NOTIFICATION_JOB_NAME, jobData, {
-       // Called `idempotencyKey` in `background-jobs-postgres`.
-       unique: `meeting-123-reminder`,
-       session: "...",
-     });
-   }
-
-   // eslint-disable-next-line unicorn/prefer-top-level-await
-   void enqueueTriggerNotificationJob(
-     // Use your instance of `@clipboard-health/mongo-jobs` or `@clipboard-health/background-jobs-postgres` here.
-     new BackgroundJobsService(),
-   );
-   ```
-
-</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`.
+All NestJS microservices follow a three-tier layered architecture:
 
-<!-- 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.
+```text
+┌─────────────────────────────────────────────────────────────────┐
+│  Entrypoints (Controllers, message consumers)                   │
+│  - HTTP request/response, JSON:API DTO translation, auth        │
+├─────────────────────────────────────────────────────────────────┤
+│  Logic (NestJS services, message publishers, background jobs)   │
+│  - ALL business logic; works with DOs only                      │
+│  - Knows nothing about HTTP or database specifics               │
+├─────────────────────────────────────────────────────────────────┤
+│  Data (Data repositories, gateways)                             │
+│  - Database via ORM (Prisma/Mongoose), DAO ↔ DO translation     │
+│  - External service integrations (Gateways)                     │
+└─────────────────────────────────────────────────────────────────┘
+```
 
-<!-- Source: .ruler/common/typeScript.md -->
+**Module Structure:**
 
-# TypeScript usage
+```text
+modules/
+└── example/
+    ├── data/
+    │   ├── example.dao.mapper.ts
+    │   ├── example.repo.ts
+    │   └── notification.gateway.ts
+    ├── entrypoints/
+    │   ├── example.controller.ts
+    │   ├── example.consumer.ts
+    │   └── example.dto.mapper.ts
+    ├── logic/
+    │   ├── jobs/
+    │   │   └── exampleCreated.job.ts
+    │   ├── example.do.ts
+    │   └── example.service.ts
+    └── example.module.ts
+```
 
-- 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`.
+**File Patterns:**
 
-<!-- Source: .ruler/frontend/custom-hooks.md -->
+```text
+*.controller.ts  - HTTP controllers (entrypoints)
+*.consumer.ts    - Message consumers (entrypoints)
+*.service.ts     - Business logic (logic)
+*.job.ts         - Background jobs (logic)
+*.repo.ts        - Database access (data)
+*.gateway.ts     - External services (data)
+*.do.ts          - Domain objects
+*.dto.mapper.ts  - DTO transformation
+*.dao.mapper.ts  - DAO transformation
+```
 
-# Custom Hook Standards
+**Tier Rules:**
 
-## Hook Structure
+- Controllers → Services (never repos directly)
+- Services → Repos/Gateways within module (never controllers)
+- Repos → Database only (never services/repos/controllers)
+- Entry points are thin layers calling services
+- Enforce with `dependency-cruiser`
 
-```typescript
-export function useFeature(params: Params, options: UseFeatureOptions = {}) {
-  const query = useQuery(...);
-  const computed = useMemo(() => transformData(query.data), [query.data]);
-  const handleAction = useCallback(async () => { /* ... */ }, []);
+**Microservices Principles:**
 
-  return { data: computed, isLoading: query.isLoading, handleAction };
-}
-```
+- One domain = one module (bounded contexts)
+- Specific modules know about generic, not vice versa
+- Don't block Node.js thread—use background jobs for expensive operations
 
-## Naming Rules
+<!-- Source: .ruler/backend/asyncMessagingBackgroundJobs.md -->
 
-- **Always** prefix with `use`
-- Boolean: Use `useIs*`, `useHas*`, or `useCan*` (e.g., `useIsEnabled`, `useHasPermission`, `useCanEdit`)
-- Data: `useGetUser`, `useFeatureData`
-- Actions: `useSubmitForm`
+# Async Messaging & Background Jobs
 
-## Return Values
+## When to Use
 
-- Return objects (not arrays) for complex hooks
-- Name clearly: `isLoading` not `loading`
+| Scenario                         | Solution          |
+| -------------------------------- | ----------------- |
+| Same service producer/consumer   | Background Jobs   |
+| Cross-service communication      | EventBridge + SQS |
+| Deferred work from API path      | Background Jobs   |
+| Replacing `void` fire-and-forget | Background Jobs   |
+| Scaling CRON jobs                | Background Jobs   |
 
-## State Management with Constate
+## Background Jobs
 
-Use `constate` for shared state between components:
+**Creation with Transaction:**
 
 ```typescript
-import constate from "constate";
-
-function useFilters() {
-  const [filters, setFilters] = useState<Filters>({});
-  return { filters, setFilters };
+async function createLicense() {
+  await db.transaction(async (tx) => {
+    const license = await tx.license.create({ data });
+    await jobs.enqueue(VerificationJob, { licenseId: license.id }, { transaction: tx });
+  });
 }
-
-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
+**Handler Pattern:**
 
 ```typescript
-// Boolean hooks
-export function useIsFeatureEnabled(): boolean {
-  return useFeatureFlags().includes("feature");
+class ShiftReminderJob implements Handler<ShiftReminderPayload> {
+  static queueName = "shift.reminder";
+
+  async perform(payload: ShiftReminderPayload, job: Job): Promise<string> {
+    const { shiftId } = payload;
+
+    // Fetch fresh data—don't trust stale payload
+    const shift = await this.shiftRepo.findById({ id: shiftId });
+
+    if (!shift || shift.isCancelled) {
+      return `Skipping: shift ${shiftId} not found or cancelled`;
+    }
+
+    try {
+      await this.notificationService.performSideEffect(shift);
+      return `Reminder sent for shift ${shiftId}`;
+    } catch (error) {
+      if (error instanceof KnownRecoverableError) throw error; // Retry
+      return `Skipping: ${error.message}`; // No retry
+    }
+  }
 }
+```
 
-// Data transformation
-export function useTransformedData() {
-  const { data, isLoading } = useGetRawData();
-  const transformed = useMemo(() => data?.map(format), [data]);
-  return { data: transformed, isLoading };
-}
+**Key Practices:**
 
-// Composite hooks
-export function useBookingsData() {
-  const shifts = useGetShifts();
-  const invites = useGetInvites();
+- Pass minimal arguments (IDs, not objects)
+- Fetch fresh data in handler
+- Implement idempotency
+- Check state before action
+- Use Expand/Contract for job code updates
 
-  const combined = useMemo(
-    () => [...(shifts.data ?? []), ...(invites.data ?? [])],
-    [shifts.data, invites.data],
-  );
+**Avoid Circular Dependencies:**
 
-  return { data: combined, isLoading: shifts.isLoading || invites.isLoading };
+```typescript
+// Shared types file
+export const NOTIFICATION_JOB = "shift-notification";
+export interface NotificationJobPayload {
+  shiftId: string;
 }
+
+// Enqueue by string name
+await jobs.enqueue<NotificationJobPayload>(NOTIFICATION_JOB, { shiftId });
 ```
 
-## Best Practices
+## SQS/EventBridge
 
-- Use options object for flexibility
-- Be explicit about dependencies
-- API hooks in `api/`, logic hooks in `hooks/`
-- Return stable references with `useCallback`/`useMemo`
+**Producer:** Single producer per message type, publish atomically (use jobs as outbox), deterministic message IDs, don't rely on strict ordering.
 
-<!-- Source: .ruler/frontend/data-fetching.md -->
+**Consumer:** Own queue per consumer, must be idempotent, separate process from API, don't auto-consume DLQs.
 
-# Data Fetching Standards
+<!-- Source: .ruler/backend/databasePatterns.md -->
 
-## Technology Stack
+# Database Patterns
 
-- **React Query** (@tanstack/react-query) for all API calls
-- **Zod** for response validation
+## MongoDB/Mongoose
 
-## Core Principles
+**ObjectId:**
 
-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
+```typescript
+import mongoose, { Types, Schema } from "mongoose";
 
-## Hook Patterns
+const id = new Types.ObjectId();
 
-```typescript
-// Simple query
-export function useGetUser(userId: string) {
-  return useQuery({
-    queryKey: ["users", userId],
-    queryFn: () => api.get(`/users/${userId}`),
-    responseSchema: userSchema,
-    enabled: !!userId,
-  });
-}
+// In schemas
+const schema = new Schema({
+  authorId: { type: Schema.Types.ObjectId, ref: "User" },
+});
 
-// Paginated query
-export function usePaginatedItems(params: Params) {
-  return useInfiniteQuery({
-    queryKey: ["items", params],
-    queryFn: ({ pageParam }) => api.get("/items", { cursor: pageParam, ...params }),
-    getNextPageParam: (lastPage) => lastPage.nextCursor,
-  });
+// In interfaces
+interface Post {
+  authorId: Types.ObjectId;
 }
 
-// Mutations
-export function useCreateItem() {
-  const queryClient = useQueryClient();
-  return useMutation({
-    mutationFn: (data: CreateItemRequest) => api.post("/items", data),
-    onSuccess: () => queryClient.invalidateQueries(["items"]),
-  });
+// Validation
+if (mongoose.isObjectIdOrHexString(value)) {
 }
 ```
 
-## Error Handling
-
-For detailed error handling strategies, see `error-handling.md`.
+**Aggregations:**
 
 ```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;
-  },
-});
+const result = await Users.aggregate<ResultType>()
+  .match({ active: true })
+  .group({ _id: "$department", count: { $sum: 1 } })
+  .project({ department: "$_id", count: 1 });
 ```
 
-## Query Keys
+**Indexes:**
 
-```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,
-};
+- Add only when needed (slower writes tradeoff)
+- Apply via code only
+- Separate `indexes.ts` from `schema.ts`
+- Index definitions only in owning service
+- Set `autoIndex: false`
+- Design covering indexes for high-traffic queries
+
+```text
+models/User/
+├── schema.ts    # Schema only
+├── indexes.ts   # Indexes only
+└── index.ts     # Model export
 ```
 
-## Conditional Fetching
+**Verify query plans:**
 
 ```typescript
-const { data } = useQuery({
-  queryKey: ["resource", id],
-  queryFn: () => fetchResource(id),
-  enabled: !!id, // Only fetch when id exists
-});
+const explanation = await ShiftModel.find(query).explain("executionStats");
+// Check: totalDocsExamined ≈ totalDocsReturned
+// Good: stage 'IXSCAN'; Bad: stage 'COLLSCAN'
 ```
 
-## Naming Conventions
+**Transactions:**
 
-- `useGetX` - Simple queries
-- `usePaginatedX` - Infinite queries
-- `useCreateX`, `useUpdateX`, `useDeleteX` - Mutations
+```typescript
+const session = await mongoose.startSession();
+try {
+  session.startTransaction();
+  await Model.create([data], { session });
+  await session.commitTransaction();
+} catch (error) {
+  await session.abortTransaction();
+  throw error;
+} finally {
+  await session.endSession();
+}
+```
 
-## Hook Location
+## Repository Pattern
 
-Place in `api/` folder within feature directory. One endpoint = one hook.
+```typescript
+class UserRepo {
+  // Named methods over generic CRUD
+  async findById(request: { id: UserId }): Promise<UserDo> {}
+  async findByEmail(request: { email: string }): Promise<UserDo> {}
+  async updateEmail(request: { id: UserId; email: string }): Promise<UserDo> {}
+}
+```
 
-<!-- Source: .ruler/frontend/error-handling.md -->
+<!-- Source: .ruler/backend/errorHandling.md -->
 
-# Error Handling Standards
+# Error Handling
 
-## React Query Error Handling
+## Service Errors
 
 ```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;
-  },
+import { ServiceError } from "@clipboard-health/util-ts";
+
+throw new ServiceError({
+  code: "SHIFT_NOT_FOUND",
+  message: `Shift ${shiftId} not found`,
+  httpStatus: 404,
 });
 ```
 
-## Component Error States
-
-```typescript
-export function DataComponent() {
-  const { data, isLoading, isError, refetch } = useGetData();
+- Favor `Either` type for expected errors over `try/catch`
+- Guard clauses for preconditions
+- Early returns for error conditions
+- Happy path last
 
-  if (isLoading) return <LoadingState />;
-  if (isError) return <ErrorState onRetry={refetch} />;
+## Controller Translation
 
-  return <DataDisplay data={data} />;
-}
+```typescript
+@UseFilters(HttpExceptionFilter)
+@Controller("shifts")
+export class ShiftController {}
 ```
 
-## Mutation Error Handling
+## Background Job Errors
 
 ```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");
-    },
-  });
+async perform(payload: JobPayload): Promise<string> {
+  try {
+    // Main logic
+  } catch (error) {
+    if (error instanceof RecoverableError) throw error;  // Retry
+    return `Skipping: ${error.message}`;  // No retry
+  }
 }
 ```
 
-## Validation Errors
+<!-- Source: .ruler/backend/notifications.md -->
+
+# Notifications
+
+Send via [Knock](https://docs.knock.app) using `@clipboard-health/notifications`.
+
+Use `triggerChunked` to store full trigger request at job enqueue time. See package documentation for setup of `triggerNotification.job.ts`, `notifications.service.ts`, and workflow keys.
+
+**Job enqueue pattern:**
 
 ```typescript
-// Zod validation
-const formSchema = z.object({
-  email: z.string().email("Invalid email"),
-  age: z.number().min(18, "Must be 18+"),
-});
+const jobData: SerializableTriggerChunkedRequest = {
+  body: { recipients: ["userId-1"], data: notificationData },
+  expiresAt: new Date(Date.now() + 60 * 60_000).toISOString(),
+  keysToRedact: ["secret"],
+  workflowKey: WORKFLOW_KEYS.eventStartingReminder,
+};
 
-try {
-  const validated = formSchema.parse(formData);
-} catch (error) {
-  if (error instanceof z.ZodError) {
-    error.errors.forEach((err) => showFieldError(err.path.join("."), err.message));
-  }
-}
+await adapter.enqueue(TRIGGER_NOTIFICATION_JOB_NAME, jobData, { session });
 ```
 
-## Error Boundaries
+<!-- Source: .ruler/backend/restApiDesign.md -->
 
-```typescript
-export class ErrorBoundary extends Component<Props, State> {
-  state = { hasError: false };
+# REST API Design
 
-  static getDerivedStateFromError(error: Error) {
-    return { hasError: true, error };
-  }
+## JSON:API Specification
 
-  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
-    logEvent("ERROR_BOUNDARY", { error: error.message });
-  }
+Follow [JSON:API spec](https://jsonapi.org/).
 
-  render() {
-    return this.state.hasError ? <ErrorFallback /> : this.props.children;
-  }
+```json
+{
+  "data": [
+    {
+      "id": "1",
+      "type": "worker",
+      "attributes": { "firstName": "Alex", "lastName": "Smith" }
+    }
+  ]
 }
 ```
 
-## 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
+- Singular `type` values: `"worker"` not `"workers"`
+- Links optional (use only for pagination)
+- Use `include` for related resources
+- Avoid `meta` unless necessary
 
-<!-- Source: .ruler/frontend/file-organization.md -->
+## URLs
 
-# File Organization Standards
+```text
+GET /urgent-shifts                    # lowercase kebab-case, plural nouns
+GET /workers/:workerId/shifts
+POST /workers/:workerId/referral-codes
+```
 
-## Feature-based Structure
+## HTTP Methods
+
+| Method | Usage                              |
+| ------ | ---------------------------------- |
+| GET    | Retrieve (idempotent)              |
+| POST   | Create single resource, return DTO |
+| PATCH  | Update, return updated resource    |
+| DELETE | Remove                             |
+| PUT    | Not supported                      |
+
+## HTTP Status Codes
+
+| Code | Meaning                                                 |
+| ---- | ------------------------------------------------------- |
+| 200  | OK (GET, PATCH, DELETE)                                 |
+| 201  | Created (POST)                                          |
+| 202  | Accepted (async started)                                |
+| 400  | Bad Request (syntax error)                              |
+| 401  | Unauthorized (auth failed)                              |
+| 403  | Forbidden (authz failed)                                |
+| 404  | Not Found                                               |
+| 409  | Conflict (already exists)                               |
+| 422  | Unprocessable (semantic error, unsupported filter/sort) |
+| 429  | Rate limited                                            |
+| 500  | Server error                                            |
+
+## Filtering, Sorting, Pagination
 
 ```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)
+GET /shifts?filter[verified]=true&sort=startDate,-urgency&page[cursor]=abc&page[size]=50
 ```
 
-## Naming Conventions
+- Cursor-based pagination only (not offset)
+- Avoid count totals (performance)
+- Only implement filters/sorts clients need
+
+## Contracts
 
-- 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`
+- Add contracts to `contract-<repo-name>` package
+- Use `ts-rest` with composable Zod schemas
 
-<!-- Source: .ruler/frontend/react-patterns.md -->
+<!-- Source: .ruler/backend/serviceTests.md -->
 
-# React Component Patterns
+# Service Tests (Primary Testing Approach)
 
-## Component Structure
+Test the public contract (REST endpoints, events) with real local dependencies (Postgres, Mongo, Redis). Fake slow/external services (Zendesk, Stripe).
 
 ```typescript
-interface Props {
-  userId: string;
-  onUpdate?: (user: User) => void;
-}
+describe("Documents", () => {
+  let tc: TestContext;
+
+  describe("GET /documents", () => {
+    it("returns existing documents for authenticated user", async () => {
+      // Arrange
+      const authToken = await tc.auth.createUser({ role: "employee" });
+      await tc.fixtures.createDocument({ name: "doc-1" });
+
+      // Act
+      const response = await tc.http.get("/documents", {
+        headers: { authorization: authToken },
+      });
+
+      // Assert
+      expect(response.statusCode).toBe(200);
+      expect(response.parsedBody.data).toHaveLength(1);
+    });
+  });
+});
+```
 
-export function UserProfile({ userId, onUpdate }: Props) {
-  // 1. Hooks
-  const { data, isLoading, error } = useGetUser(userId);
-  const [isEditing, setIsEditing] = useState(false);
+**Qualities:** One behavior per test, no shared setup, no mocking, <1 second, parallelizable.
 
-  // 2. Derived state (avoid useMemo for inexpensive operations)
-  const displayName = formatName(data);
+<!-- Source: .ruler/common/commitMessages.md -->
 
-  // 3. Event handlers
-  const handleSave = useCallback(async () => {
-    await saveUser(data);
-    onUpdate?.(data);
-  }, [data, onUpdate]);
+# Commit Messages
 
-  // 4. Early returns
-  if (isLoading) return <Loading />;
-  if (error) return <Error message={error.message} />;
-  if (!data) return <NotFound />;
+Follow Conventional Commits 1.0 spec for commit messages and PR titles.
 
-  // 5. Main render
-  return (
-    <Card>
-      <Typography>{displayName}</Typography>
-      <Button onClick={handleSave}>Save</Button>
-    </Card>
-  );
-}
+<!-- Source: .ruler/common/configuration.md -->
+
+# Configuration
+
+```text
+Contains secrets?
+  └── Yes → SSM Parameter Store
+  └── No → Engineers-only, tolerate 1hr propagation?
+      └── Yes → Hardcode with @clipboard-health/config
+      └── No → 1:1 with DB entity OR needs custom UI?
+          └── Yes → Database
+          └── No → LaunchDarkly feature flag
 ```
 
-## Naming Conventions
+<!-- Source: .ruler/common/featureFlags.md -->
 
-- Components: `PascalCase` (`UserProfile`)
-- Props interface: `Props` (co-located with component) or `ComponentNameProps` (exported/shared)
-- Event handlers: `handle*` (`handleClick`, `handleSubmit`)
-- Boolean props: `is*`, `has*`, `should*`
+# Feature Flags
 
-## Props Patterns
+**Naming:** `YYYY-MM-[kind]-[subject]` (e.g., `2024-03-release-new-booking-flow`)
 
-```typescript
-// Simple props
-interface Props {
-  title: string;
-  count: number;
-  onAction: () => void;
-}
+| Kind         | Purpose                  |
+| ------------ | ------------------------ |
+| `release`    | Gradual rollout to 100%  |
+| `enable`     | Kill switch              |
+| `experiment` | Trial for small audience |
+| `configure`  | Runtime config           |
 
-// Discriminated unions for variants
-type ButtonProps = { variant: "link"; href: string } | { variant: "button"; onClick: () => void };
+**Rules:**
 
-// Optional callbacks
-interface Props {
-  onSuccess?: (data: Data) => void;
-  onError?: (error: Error) => void;
-}
-```
+- "Off" = default/safer value
+- No permanent flags (except `configure`)
+- Create archival ticket when creating flag
+- Validate staging before production
+- Always provide default values in code
+- Clean up after full launch
 
-## Composition Patterns
+<!-- Source: .ruler/common/loggingObservability.md -->
 
-```typescript
-// Container/Presentational
-export function UserListContainer() {
-  const { data, isLoading, error } = useUsers();
-  if (isLoading) return <Loading />;
-  if (error) return <Error />;
-  return <UserList users={data} />;
-}
+# Logging & Observability
 
-// 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>
-```
+## Log Levels
+
+| Level | When                                       |
+| ----- | ------------------------------------------ |
+| ERROR | Required functionality broken (2am pager?) |
+| WARN  | Optional broken OR recovered from failure  |
+| INFO  | Informative, ignorable during normal ops   |
+| DEBUG | Local only, not production                 |
 
-## Children Patterns
+## Best Practices
 
 ```typescript
-// Typed children
-interface Props {
-  children: ReactNode;
-}
+// Bad
+logger.error("Operation failed");
+logger.error(`Operation failed for workplace ${workplaceId}`);
+
+// Good—structured context
+logger.error("Exporting urgent shifts to CSV failed", {
+  workplaceId,
+  startDate,
+  endDate,
+});
+```
 
-// Render prop pattern
-interface Props {
-  children: (data: Data) => ReactNode;
-}
+**Never log:** PII, PHI, tokens, secrets, SSN, account numbers, entire request/response/headers.
 
-// Element restrictions
-interface Props {
-  children: ReactElement<ButtonProps>;
-}
+Use metrics for counting:
+
+```typescript
+datadogMetrics.increment("negotiation.errors", { state: "New York" });
 ```
 
-## List Rendering
+<!-- Source: .ruler/common/pullRequests.md -->
 
-```typescript
-// ✅ Proper keys
-{users.map((user) => <UserCard key={user.id} user={user} />)}
+# Pull Requests
 
-// ✅ Empty states
-{users.length === 0 ? <EmptyState /> : users.map(...)}
+**Requirements:**
 
-// ❌ Never use index as key when list can change
-{items.map((item, index) => <Item key={index} />)} // Wrong!
-```
+1. Clear title: change summary + ticket; Conventional Commits 1.0
+2. Thorough description: why, not just what
+3. Small & focused: single concept
+4. Tested: service tests + validation proof
+5. Passing CI
 
-## Conditional Rendering
+**Description:** Link ticket, context, reasoning, areas of concern.
 
-```typescript
-// Simple conditional
-{isLoading && <Spinner />}
+<!-- Source: .ruler/common/security.md -->
 
-// If-else
-{isError ? <Error /> : <Success />}
+# Security
 
-// Multiple conditions
-{isLoading ? <Loading /> : isError ? <Error /> : <Data />}
+**Secrets:**
 
-// With early returns (preferred for complex logic)
-if (isLoading) return <Loading />;
-if (isError) return <Error />;
-return <Data />;
-```
+- `.env` locally (gitignored)
+- Production: AWS SSM Parameter Store
+- Prefer short-lived tokens
+
+**Naming:** `[ENV]_[VENDOR]_[TYPE]_usedBy_[CLIENT]_[SCOPE]_[CREATED_AT]_[OWNER]`
+
+<!-- Source: .ruler/common/structuredConcurrency.md -->
 
-## Performance
+# Structured Concurrency
 
 ```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} />
-    </>
-  );
+// Cancellation propagation
+async function fetchWithTimeout(url: string, timeoutMs: number): Promise<Response> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, { signal: controller.signal });
+  } finally {
+    clearTimeout(timeoutId);
+  }
 }
+
+// All results regardless of failures
+const results = await Promise.allSettled(operations);
+const succeeded = results.filter((r) => r.status === "fulfilled");
+const failed = results.filter((r) => r.status === "rejected");
 ```
 
-## Best Practices
+<!-- Source: .ruler/common/testing.md -->
 
-- **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
+# Testing
 
-<!-- Source: .ruler/frontend/react.md -->
+## Unit Tests
 
-# React
+Use when: error handling hard to trigger black-box, concurrency scenarios, >5 variations, pure function logic.
 
-- 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
+## Conventions
 
-<!-- Source: .ruler/frontend/styling.md -->
+- Use `it` not `test`; `describe` for grouping
+- Arrange-Act-Assert with newlines between
+- Variables: `mockX`, `input`, `expected`, `actual`
+- Prefer `it.each` for multiple cases
+- No conditional logic in tests
 
-# Styling Standards
+<!-- Source: .ruler/common/typeScript.md -->
 
-## Core Principles
+# TypeScript
 
-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
+## Naming Conventions
 
-## Restricted Patterns
+| Element               | Convention            | Example                      |
+| --------------------- | --------------------- | ---------------------------- |
+| File-scope constants  | UPPER_SNAKE_CASE      | `MAX_RETRY_COUNT`            |
+| Acronyms in camelCase | Lowercase after first | `httpRequest`, `gpsPosition` |
+| Files                 | Singular, dotted      | `user.service.ts`            |
 
-❌ **DO NOT USE:**
+## Core Rules
 
-- `styled()` or `makeStyles()` from MUI
-- CSS/SCSS/SASS files
-- Inline `style` prop (use `sx` instead)
-- String paths for theme (`"text.secondary"` - not type-safe)
+- Strict-mode TypeScript; prefer interfaces over types
+- Avoid enums—use const maps
+- NEVER use `any`—use `unknown` or generics
+- Avoid type assertions (`as`, `!`) unless absolutely necessary
+- Use `function` keyword for declarations, not `const`
+- Prefer `undefined` over `null`
+- Explicit return types on functions
+- Files read top-to-bottom: exports first, internal helpers below
+- Boolean props: `is*`, `has*`, `should*`, `can*`
+- Use const assertions for constants: `as const`
 
-## Type-Safe Theme Access
+## Types
 
 ```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
-}} />
+// Strong typing
+function process(arg: unknown) {} // Better than any
+function process<T>(arg: T) {} // Best
+
+// Nullable checks
+if (foo == null) {
+} // Clear intent
+if (isDefined(foo)) {
+} // Better with utility
+
+// Quantity values—always unambiguous
+const money = { amountInMinorUnits: 500, currencyCode: "USD" };
+const durationMinutes = 30;
 ```
 
-## Spacing System
+**Type Techniques:**
 
-Use indices 1-12 (4px-64px):
+- Union, intersection, conditional types for complex definitions
+- Mapped types: `Partial<T>`, `Pick<T>`, `Omit<T>`
+- `keyof`, index access types, discriminated unions
+- `as const`, `typeof`, `instanceof`, `satisfies`, type guards
+- Exhaustiveness checking with `never`
+- `readonly` for parameter immutability
+
+## Functions
 
 ```typescript
-<Box sx={{ padding: 5 }} />    // → 16px
-<Box sx={{ marginX: 4 }} />    // → 12px left and right
-<Box sx={{ gap: 3 }} />        // → 8px
+// Object arguments with interfaces
+interface CreateUserRequest {
+  email: string;
+  name?: string;
+}
+
+function createUser(request: CreateUserRequest): User {
+  const { email, name } = request; // Destructure inside
+  // ...
+}
+
+// Guard clauses for early returns
+function processOrder(order: Order): Result {
+  if (!order.isValid) {
+    return { error: "Invalid order" };
+  }
+  // Main logic
+}
 ```
 
-**Use `rem` for fonts/heights (scales with user zoom), `px` for spacing:**
+## Objects & Arrays
 
 ```typescript
-<Box sx={(theme) => ({
-  height: "3rem", // ✅ Scales
-  fontSize: theme.typography.body1.fontSize,
-  padding: 5, // ✅ Prevents overflow
-})} />
+// Spread over Object.assign
+const updated = { ...original, name: "New Name" };
+
+// Array methods over loops (unless breaking early)
+const doubled = items.map((item) => item * 2);
+const sorted = items.toSorted((a, b) => a - b); // Immutable
+
+// For early exit
+for (const item of items) {
+  if (condition) break;
+}
 ```
 
-## Responsive Styles
+## Async
 
 ```typescript
-<Box sx={{
-  width: { xs: "100%", md: "50%" },
-  padding: { xs: 1, md: 3 },
-}} />
+// async/await over .then()
+async function fetchData(): Promise<Data> {
+  const response = await api.get("/data");
+  return response.data;
+}
+
+// Parallel
+const results = await Promise.all(items.map(processItem));
+
+// Sequential (when needed)
+for (const item of items) {
+  // eslint-disable-next-line no-await-in-loop
+  await processItem(item);
+}
 ```
 
-## Pseudo-classes
+## Classes
 
 ```typescript
-<Box sx={(theme) => ({
-  "&:hover": { backgroundColor: theme.palette.primary.dark },
-  "&:disabled": { opacity: 0.5 },
-  "& .child": { color: theme.palette.text.secondary },
-})} />
+class UserService {
+  public async findById(request: FindByIdRequest): Promise<User> {}
+  private validateUser(user: User): boolean {}
+}
+
+// Extract pure functions outside classes
+function formatUserName(first: string, last: string): string {
+  return `${first} ${last}`;
+}
 ```
 
-## Shorthand Properties
+<!-- Source: .ruler/frontend/customHooks.md -->
+
+# Custom Hooks
 
-✅ Use full names: `padding`, `paddingX`, `marginY`
-❌ Avoid abbreviations: `p`, `px`, `my`
+## Naming
 
-## Layout Components
+- Prefix with `use`
+- Boolean: `useIs*`, `useHas*`, `useCan*`
+- Data: `useGet*`, `use*Data`
+- Actions: `useSubmit*`, `useCreate*`
 
-Safe to import directly from MUI:
+## Structure
 
 ```typescript
-import { Box, Stack, Container, Grid } from "@mui/material";
+export function useFeature(params: Params, options: Options = {}) {
+  const query = useQuery(...);
+  const computed = useMemo(() => transform(query.data), [query.data]);
+  const handleAction = useCallback(async () => { ... }, []);
+
+  return { data: computed, isLoading: query.isLoading, handleAction };
+}
 ```
 
-## Best Practices
+## Shared State with Constate
 
-- Type-safe access with `sx={(theme) => ({...})}`
-- Use semantic token names
-- Full property names, not abbreviations
+```typescript
+import constate from "constate";
 
-<!-- Source: .ruler/frontend/testing.md -->
+function useFilters() {
+  const [filters, setFilters] = useState<Filters>({});
+  return { filters, setFilters };
+}
 
-# Testing Standards
+export const [FiltersProvider, useFiltersContext] = constate(useFilters);
+```
 
-## Testing Trophy Philosophy
+Use constate for: sharing state between siblings, feature-level state.
+Don't use for: server state (use React Query), simple parent-child (use props).
 
-Focus on **Integration tests** - test how components work together as users experience them.
+<!-- Source: .ruler/frontend/dataFetching.md -->
 
-**Investment Priority:**
+# Data Fetching
 
-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
+## Core Rules
 
-**Key Principle:** Test as close to how users interact with your app as possible.
+1. Use React Query for all API calls
+2. Define Zod schemas for all request/response types
+3. Use `isLoading`, `isError`, `isSuccess`—don't create custom state
+4. Use `enabled` option for conditional fetching
+5. Use `invalidateQueries` (not `refetch`) for disabled queries
 
-## Technology Stack
+## Hook Pattern
 
-- **Vitest** for test runner
-- **@testing-library/react** for component testing
-- **@testing-library/user-event** for user interactions
-- **Mock Service Worker (MSW)** for API mocking
+```typescript
+// Define in: FeatureName/api/useGetFeature.ts
+const responseSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+});
 
-## Test Structure
+export type FeatureResponse = z.infer<typeof responseSchema>;
 
-```typescript
-describe("ComponentName", () => {
-  it("should render correctly", () => {
-    render(<Component />);
-    expect(screen.getByText("Expected")).toBeInTheDocument();
+export function useGetFeature(id: string, options = {}) {
+  return useGetQuery({
+    url: `feature/${id}`,
+    responseSchema,
+    enabled: !!id,
+    meta: { logErrorMessage: APP_EVENTS.GET_FEATURE_FAILURE },
+    ...options,
   });
+}
+```
 
-  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());
+## Query Keys
+
+Include URL and params for predictable cache invalidation:
+
+```typescript
+queryKey: ["users", userId];
+queryKey: ["users", userId, "posts"];
+```
+
+## Conditional Fetching
+
+```typescript
+const { data } = useGetFeature(
+  { id: dependencyData?.id },
+  { enabled: isDefined(dependencyData?.id) },
+);
+```
+
+## Mutations
+
+```typescript
+export function useCreateItem() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (data: CreateItemRequest) => api.post("/items", data),
+    onSuccess: () => queryClient.invalidateQueries(["items"]),
+    onError: (error) => logError("CREATE_ITEM_FAILURE", error),
   });
-});
+}
 ```
 
-## Test Naming
+<!-- Source: .ruler/frontend/e2eTesting.md -->
+
+# E2E Testing (Playwright)
+
+## Core Rules
 
-Pattern: `should [behavior] when [condition]`
+- Test critical user flows only—not exhaustive scenarios
+- Each test sets up its own data (no shared state between tests)
+- Mock feature flags and third-party services
+- Use user-centric locators (role, label, text)—avoid CSS selectors
 
-## Querying Elements - Priority Order
+## Locator Priority
 
-1. `getByRole` - Best for accessibility
-2. `getByLabelText` - For form fields
-3. `getByText` - For non-interactive content
-4. `getByTestId` - ⚠️ **LAST RESORT**
+1. `page.getByRole()`
+2. `page.getByLabel()`
+3. `page.getByPlaceholder()`
+4. `page.getByText()`
+5. `page.getByTestId()` (last resort)
+
+## Assertions
 
 ```typescript
-// ✅ Prefer
-screen.getByRole("button", { name: /submit/i });
-screen.getByLabelText("Email");
+// ✅ Assert visibility
+await expect(page.getByText("Submit")).toBeVisible();
 
-// ❌ Avoid
-screen.getByClassName("user-card");
-screen.getByTestId("element");
+// ❌ Don't assert DOM attachment
+await expect(page.getByText("Submit")).toBeAttached();
 ```
 
-## User Interactions
+## Avoid
+
+- Hard-coded timeouts (`page.waitForTimeout`)
+- Testing loading states (non-deterministic)
+- Shared data between tests
+- CSS/XPath selectors
+
+<!-- Source: .ruler/frontend/errorHandling.md -->
+
+# Error Handling
+
+## Component Level
 
 ```typescript
-it("should handle form submission", async () => {
-  const user = userEvent.setup();
-  const onSubmit = vi.fn();
-  render(<Form onSubmit={onSubmit} />);
+export function DataComponent() {
+  const { data, isLoading, isError, refetch } = useGetData();
 
-  await user.type(screen.getByLabelText("Name"), "John");
-  await user.click(screen.getByRole("button", { name: "Submit" }));
+  if (isLoading) return <LoadingState />;
+  if (isError) return <ErrorState onRetry={refetch} />;
 
-  expect(onSubmit).toHaveBeenCalledWith({ name: "John" });
-});
+  return <DataDisplay data={data} />;
+}
 ```
 
-## Hook Testing
+## Mutation Level
 
 ```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);
-  });
+useMutation({
+  mutationFn: createItem,
+  onSuccess: () => showSuccessToast("Created"),
+  onError: (error) => {
+    logError("CREATE_FAILURE", error);
+    showErrorToast("Failed to create");
+  },
 });
 ```
 
-## MSW Pattern
-
-**Always export factory functions, not static handlers:**
+## Validation
 
 ```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));
+try {
+  const validated = formSchema.parse(formData);
+} catch (error) {
+  if (error instanceof z.ZodError) {
+    error.errors.forEach((err) => showFieldError(err.path.join("."), err.message));
+  }
+}
 ```
 
-## Mocking
+<!-- Source: .ruler/frontend/fileOrganization.md -->
 
-```typescript
-vi.mock("@/lib/api", () => ({
-  get: vi.fn().mockResolvedValue({ data: { id: "1" } }),
-}));
+# File Organization
+
+```text
+FeatureName/
+├── api/                    # Data fetching hooks
+│   └── useGetFeature.ts
+├── components/             # Feature-specific components
+│   └── FeatureCard.tsx
+├── hooks/                  # Non-API hooks
+│   └── useFeatureLogic.ts
+├── utils/                  # Utilities + tests
+│   ├── formatFeature.ts
+│   └── formatFeature.test.ts
+├── Page.tsx                # Main page
+├── Router.tsx              # Routes
+├── paths.ts                # Route constants
+└── types.ts                # Shared types
 ```
 
-## What to Test
+## Naming
+
+- Components: `PascalCase.tsx`
+- Hooks: `camelCase.ts` (prefixed with `use`)
+- Utils: `camelCase.ts`
+- Tests: `*.test.tsx`
+
+<!-- Source: .ruler/frontend/frontendTechnologyStack.md -->
 
-**✅ Do Test:**
+# Frontend Technology Stack
 
-- Integration tests for features
-- Unit tests for utilities
-- All states (loading, success, error)
-- User interactions
+- **React** with TypeScript (strict mode)
+- **MUI** for UI components
+- **React Query** (@tanstack/react-query) for data fetching
+- **Zod** for runtime validation
+- **Vitest** + **@testing-library/react** for testing
+- **MSW** for API mocking
+- **Playwright** for E2E tests
+- **constate** for shared state
+
+<!-- Source: .ruler/frontend/interactiveElements.md -->
+
+# Interactive Elements
 
-**❌ Don't Test:**
+Never add `onClick` to `div` or `span`. Use:
 
-- Implementation details
-- Third-party libraries
-- Styles/CSS
+- `<button>` for actions
+- `<a>` (Link) for navigation
+- MUI interactive components (`Button`, `IconButton`, `ListItemButton`)
 
-<!-- Source: .ruler/frontend/typeScript.md -->
+This ensures proper accessibility: focus states, keyboard navigation, ARIA roles.
 
-# TypeScript Standards
+<!-- Source: .ruler/frontend/modalRoutes.md -->
 
-## Core Principles
+# Modal Routes
 
-- **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
+Modal visibility is driven by URL, not local state:
+
+```typescript
+<ModalRoute
+  path={`${basePath}/confirm`}
+  closeModalPath={basePath}
+  render={({ modalState }) => (
+    <ConfirmDialog modalState={modalState} />
+  )}
+/>
+```
+
+Use `history.replace` (not `push`) when navigating between modals to avoid awkward back-button behavior.
+
+<!-- Source: .ruler/frontend/reactComponents.md -->
+
+# React Components
 
 ## Type vs Interface
 
 ```typescript
-// ✅ Use interface for: props, object shapes, extensible types
+// Use interface for: props, object shapes, extensible types
 interface UserCardProps {
   user: User;
   onSelect: (id: string) => void;
 }
+```
 
-interface BaseEntity {
-  id: string;
-  createdAt: string;
-}
+## Structure Order
 
-interface User extends BaseEntity {
-  name: string;
-}
+```typescript
+export function Component({ userId, onUpdate }: Props) {
+  // 1. Hooks
+  const { data, isLoading } = useGetUser(userId);
+  const [isEditing, setIsEditing] = useState(false);
+
+  // 2. Derived state (no useMemo for cheap operations)
+  const displayName = formatName(data);
 
-// ✅ 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;
+  // 3. Event handlers
+  const handleSave = useCallback(async () => { ... }, [deps]);
+
+  // 4. Early returns for loading/error/empty
+  if (isLoading) return <Loading />;
+  if (!data) return <NotFound />;
+
+  // 5. Main render
+  return <Card>...</Card>;
+}
 ```
 
 ## Naming Conventions
 
+- Components: `PascalCase`
+- Event handlers: `handle*` (e.g., `handleClick`)
+- Props interface: `Props` (co-located) or `ComponentNameProps` (exported)
+
+## Component Guidelines
+
+- **One file per component**—never extract JSX into local variables
+- **Composition over configuration**—prefer `children` over many props
+- **Presentational components**: stateless, UI-focused, no API calls
+- **Container components**: feature logic, data fetching, state management
+- Pass primitives as props, not entire API response objects
+
 ```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;
+// ❌ Bad—coupled to API shape
+interface Props {
+  shift: ShiftApiResponse;
+}
+
+// ✅ Good—only required fields
+interface Props {
+  shiftId: string;
+  shiftPay: number;
+  workplaceId: string;
 }
 ```
 
-## Zod Integration
+## Inline JSX and Handlers
 
 ```typescript
-// Define schema, infer type
-const userSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-});
+// ❌ Don't extract JSX to variables
+const content = <p>Content</p>;
+return <>{content}</>;
 
-export type User = z.infer<typeof userSchema>;
+// ✅ Keep inline or extract to new component file
+return <p>Content</p>;
 
-// Validate API responses
-const response = await get({
-  url: "/api/users",
-  responseSchema: userSchema,
-});
+// ❌ Don't extract handlers unnecessarily
+const handleChange = (e) => { ... };
+return <Input onChange={handleChange} />;
+
+// ✅ Keep inline
+return <Input onChange={(e) => { ... }} />;
 ```
 
-## Type Guards
+## List Rendering
 
 ```typescript
-export function isUser(value: unknown): value is User {
-  return userSchema.safeParse(value).success;
-}
+// ✅ Always use stable keys
+{users.map((user) => <UserCard key={user.id} user={user} />)}
 
-// Usage
-if (isUser(data)) {
-  console.log(data.name); // TypeScript knows data is User
-}
+// ❌ Never use index as key for dynamic lists
+{items.map((item, i) => <Item key={i} />)}
 ```
 
-## Constants
+<!-- Source: .ruler/frontend/styling.md -->
+
+# Styling
+
+## Core Rules
+
+1. **Always use `sx` prop**—never CSS/SCSS/SASS/styled()/makeStyles()
+2. **Use theme tokens**—never use raw string values for colors/spacing
+3. **Type-safe theme access**—use `sx={(theme) => ({...})}`
+4. **Use semantic token names**—`theme.palette.text.primary`, not `common.white`
+
+## Patterns
 
 ```typescript
-// Use const assertions
-export const STATUSES = {
-  DRAFT: "draft",
-  PUBLISHED: "published",
-} as const;
+// ✅ Correct
+<Box sx={(theme) => ({
+  backgroundColor: theme.palette.background.primary,
+  color: theme.palette.text.secondary,
+  padding: theme.spacing(4), // or just: padding: 4
+})} />
 
-export type Status = (typeof STATUSES)[keyof typeof STATUSES];
+// ❌ Wrong
+<Box sx={{
+  backgroundColor: "red",      // raw color
+  padding: "16px",             // raw size
+  color: "text.secondary",     // string path (not type-safe)
+}} />
 ```
 
-## Utility Types
+## Spacing
+
+Use theme spacing indices 1-12:
 
 ```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>;
+<Box sx={{ padding: 5 }} />
+<Box sx={{ marginX: 4 }} />
 ```
 
-## Avoiding `any`
+Use `rem` for fonts/heights (scales with user zoom), spacing indices for padding/margin.
 
-```typescript
-// ❌ Bad - Loses type safety
-function process(data: any) { ... }
+## Property Names
 
-// ✅ Use unknown for truly unknown types
-function process(data: unknown) {
-  if (typeof data === "object" && data !== null) {
-    // Type guard
-  }
-}
+- ✅ Use full names: `padding`, `paddingX`, `marginY`
+- ❌ Avoid abbreviations: `p`, `px`, `my`
 
-// ✅ Better - Use generics
-function process<T extends { value: string }>(data: T) {
-  return data.value;
-}
+## Pseudo-classes
 
-// ✅ Best - Use Zod
-const dataSchema = z.object({ value: z.string() });
-function process(data: unknown) {
-  const parsed = dataSchema.parse(data);
-  return parsed.value;
-}
+```typescript
+<Box sx={(theme) => ({
+  "&:hover": { backgroundColor: theme.palette.primary.dark },
+  "&:disabled": { opacity: 0.5 },
+  "& .MuiTypography-root": { color: theme.palette.text.secondary },
+})} />
 ```
 
-## Generics
+<!-- Source: .ruler/frontend/testing.md -->
 
-```typescript
-// Generic function
-function getFirst<T>(array: T[]): T | undefined {
-  return array[0];
-}
+# Testing
 
-// Generic component
-interface ListProps<T> {
-  items: T[];
-  renderItem: (item: T) => ReactNode;
-}
+## Philosophy
 
-export function List<T>({ items, renderItem }: ListProps<T>) {
-  return <>{items.map((item) => renderItem(item))}</>;
-}
+Focus on integration tests—test how components work together as users experience them.
 
-// Constrained generics
-function findById<T extends { id: string }>(items: T[], id: string): T | undefined {
-  return items.find((item) => item.id === id);
-}
-```
+**Priority:** Static (TS/ESLint) → Integration → Unit (pure utilities only) → E2E (critical flows only)
 
-## Discriminated Unions
+## Test Structure
 
 ```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
-}
+describe("ComponentName", () => {
+  it("should [behavior] when [condition]", async () => {
+    const user = userEvent.setup();
+    render(<Component />);
 
-// Actions
-type Action = { type: "SET_USER"; payload: User } | { type: "CLEAR_USER" };
+    await user.click(screen.getByRole("button", { name: "Submit" }));
 
-function reducer(state: State, action: Action) {
-  switch (action.type) {
-    case "SET_USER":
-      return { ...state, user: action.payload };
-    case "CLEAR_USER":
-      return { ...state, user: null };
-  }
-}
+    await waitFor(() => {
+      expect(screen.getByText("Success")).toBeInTheDocument();
+    });
+  });
+});
 ```
 
-## Type Narrowing
+## Query Priority
 
-```typescript
-// typeof
-function format(value: string | number) {
-  if (typeof value === "string") {
-    return value.toUpperCase();
-  }
-  return value.toFixed(2);
-}
+1. `getByRole` (best for accessibility)
+2. `getByLabelText` (form fields)
+3. `getByText` (non-interactive content)
+4. `getByTestId` (last resort only)
 
-// in operator
-function move(animal: Fish | Bird) {
-  if ("swim" in animal) {
-    animal.swim();
-  } else {
-    animal.fly();
-  }
-}
+```typescript
+// ✅ Prefer
+screen.getByRole("button", { name: /submit/i });
+screen.getByLabelText("Email");
 
-// instanceof
-function handleError(error: unknown) {
-  if (error instanceof Error) {
-    console.log(error.message);
-  }
-}
+// ❌ Avoid
+screen.getByTestId("submit-button");
 ```
 
-## Common Patterns
-
-```typescript
-// Optional chaining
-const userName = user?.profile?.name;
+## MSW Handlers
 
-// Nullish coalescing
-const displayName = userName ?? "Anonymous";
+Export factory functions, not static handlers:
 
-// Non-null assertion (use sparingly)
-const user = getUser()!;
+```typescript
+// ✅ Good—flexible per test
+export const createUserHandler = (userData: User) =>
+  rest.get("/api/user", (req, res, ctx) => res(ctx.json(userData)));
 
-// Template literal types
-type Route = `/users/${string}` | `/posts/${string}`;
-type EventHandler = `on${Capitalize<string>}`;
+// Usage
+mockServer.use(createUserHandler(customData));
 ```
 
-## Best Practices
+## What to Test
 
-- **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
+✅ Test: user interactions, all states (loading/success/error), integration between components
+❌ Don't test: implementation details, third-party libraries, styles