@quanticjs/create-app 0.1.1

package/templates/claude/rules/database-patterns.md

@@ -0,0 +1,96 @@
+---
+globs: "src/**/*.ts"
+---
+
+# Database Patterns
+
+## TypeORM Code-First Migrations
+
+Generate migrations from entity changes — never write SQL by hand:
+
+```bash
+npx typeorm migration:generate src/migrations/AddItemTable
+npx typeorm migration:run
+```
+
+## Schema Per Service
+
+Each service gets its own PostgreSQL schema (e.g., `identity`, `billing`).
+Migrations reference the schema explicitly.
+
+## CRITICAL: TypeORM Uses camelCase Column Names
+
+TypeORM's default naming strategy maps entity properties directly to column names.
+**Column names in the database are camelCase, NOT snake_case.**
+
+```typescript
+// Entity property: displayLatitude
+// Database column: "displayLatitude" (NOT display_latitude)
+
+// ❌ WRONG
+CREATE INDEX idx_post_lat ON activity.posts ("display_latitude");
+
+// ✅ CORRECT
+CREATE INDEX idx_post_lat ON activity.posts ("displayLatitude");
+```
+
+When referencing tables in raw SQL, use `schema.tableName` (NOT `"schema"."tableName"` with the schema quoted):
+```sql
+-- ❌ WRONG
+SELECT * FROM "activity"."post";
+
+-- ✅ CORRECT
+SELECT * FROM activity.posts;
+```
+
+## Entity Index Patterns — No Duplicates
+
+Use EITHER class-level `@Index` OR property-level `@Index`, never both for the same column.
+
+## Migration SQL Rules
+
+### CREATE INDEX CONCURRENTLY — Non-Transactional Migrations Only
+
+TypeORM migrations run inside transactions by default. `CONCURRENTLY` cannot run in a transaction. For normal migrations, use regular `CREATE INDEX`:
+
+```typescript
+// ❌ WRONG — CONCURRENTLY inside a default (transactional) migration
+await queryRunner.query(`CREATE INDEX CONCURRENTLY idx_name ON schema.table ("column")`);
+
+// ✅ CORRECT — regular index in a transactional migration
+await queryRunner.query(`CREATE INDEX idx_name ON schema.table ("column")`);
+```
+
+For large tables (millions of rows) where locking must be avoided, create a **separate migration file** with `transaction = false`:
+
+```typescript
+export class AddIndexOnOrderLocationConcurrently1234567890 implements MigrationInterface {
+  transaction = false as const;
+
+  async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_order_location ON catalog.orders ("latitude", "longitude")`,
+    );
+  }
+
+  async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP INDEX IF EXISTS catalog.idx_order_location`);
+  }
+}
+```
+
+### NEVER Write Hand-Crafted Migrations That Duplicate Entities
+
+If a TypeORM entity defines a table, run `migration:generate`. Do NOT also write a manual `CREATE TABLE`.
+
+## Migration Naming Convention
+
+Use descriptive names: `AddItemTable`, `AddStatusColumnToOrder`, `CreateIndexOnEmail`.
+
+## NEVER
+
+- **NEVER** use `synchronize: true` in staging or production
+- **NEVER** write snake_case column names
+- **NEVER** use `CREATE INDEX CONCURRENTLY` inside transactional migrations
+- **NEVER** write manual `CREATE TABLE` for tables with TypeORM entities
+- **NEVER** access another module's tables directly

package/templates/claude/rules/docker-patterns.md

@@ -0,0 +1,86 @@
+---
+globs: "Dockerfile, client/Dockerfile, docker-compose*.yml, scripts/**"
+---
+
+# Docker Patterns
+
+## Local Dev Uses Docker Compose (Internal Network)
+
+```bash
+# Daily development
+docker compose up                        # Start infra + backend (watch mode)
+cd client && npm run dev                 # Start Vite natively (separate terminal)
+```
+
+## Architecture: Modular Monolith — Two Dockerfiles
+
+| Service | Dockerfile | What it builds |
+|---------|-----------|----------------|
+| Backend (NestJS) | `Dockerfile` (project root) | All backend modules in one image |
+| Frontend (React) | `client/Dockerfile` | Vite build → nginx (K8s only) |
+
+## docker-compose.yml Design
+
+- **Only `backend` and `keycloak` have `ports:` sections** (3000, 8080)
+- **Backend uses Docker hostnames** (`postgres`, `redis`, `keycloak`) — NOT `localhost`
+- **Source code is volume-mounted** (`./src:/app/src:cached`)
+- **Keycloak uses dev-mem mode** for fast startup
+- **Database init** handled by `scripts/init-db.sh`
+
+## Backend Dockerfile (multi-stage)
+
+```dockerfile
+# Development target — used by docker-compose.yml
+FROM node:20-alpine AS development
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY tsconfig*.json nest-cli.json ./
+# src/ volume-mounted at runtime
+CMD ["npm", "run", "start:dev"]
+
+# Production target
+FROM node:20-alpine AS production
+WORKDIR /app
+ENV NODE_ENV=production
+COPY package*.json ./
+RUN npm ci --only=production && npm cache clean --force
+COPY --from=builder /app/dist ./dist
+CMD ["node", "dist/main.js"]
+```
+
+## Vite Proxy Configuration (critical for BFF auth)
+
+```typescript
+// client/vite.config.ts
+export default defineConfig({
+  server: {
+    proxy: {
+      '/api': { target: 'http://localhost:3000', changeOrigin: true },
+      '/auth': { target: 'http://localhost:3000', changeOrigin: true },
+    },
+  },
+});
+```
+
+## Kubernetes (Integration Testing Only)
+
+```bash
+scripts/local-dev-up.sh           # Create Kind cluster + deploy
+scripts/helm-deploy-local.sh      # Re-deploy after Helm changes
+```
+
+Use Helm release-prefixed service names, not Docker Compose short names.
+
+## NEVER
+
+- **NEVER** expose infrastructure ports to the host (except Keycloak 8080 for OIDC redirects)
+- **NEVER** run Vite inside Docker — HMR is unreliable with volume mounts
+- **NEVER** create per-service Dockerfiles — this is a monolith
+- **NEVER** run services as root in production images
+- **NEVER** copy `node_modules/` into the image — always `npm ci`
+- **NEVER** use `docker compose up` for E2E or integration tests — use `docker compose -f docker-compose.test.yml up` (isolated ports: API 3099, Keycloak 8099, Frontend 5199)
+- **NEVER** hardcode API URLs in frontend — use relative paths (`/api/items`)
+- **NEVER** use Docker Compose short hostnames in Helm values
+- **NEVER** mount host `node_modules` into Kubernetes pods
+- **NEVER** use local K8s for daily feature development — use Docker Compose

package/templates/claude/rules/frontend-patterns.md

@@ -0,0 +1,262 @@
+---
+globs: "client/**/*.{ts,tsx}"
+---
+
+# Frontend Patterns
+
+## State Management — Decision Tree
+
+| State type | Tool | When |
+|---|---|---|
+| **Server/remote data** | TanStack Query (`useQuery` / `useMutation`) | Data from API |
+| **URL-derived state** | `useSearchParams` (React Router) | Filters, tabs, pagination — anything bookmarkable |
+| **Local UI state** | `useState` | Open/closed, hover, animation — never leaves the component |
+| **Shared client state** | Zustand store | Client-only state needed by 2+ unrelated components |
+| **Form state** | `useForm` (`@quanticjs/react-forms`) + Zod | Multi-field forms with validation + automatic server error mapping |
+
+### TanStack Query — All API Calls
+
+```typescript
+const { data, isLoading } = useQuery({
+  queryKey: ['items', id],
+  queryFn: () => api.getItem(id),
+});
+```
+
+Same `queryKey` in multiple components = one network request (auto-dedup).
+
+### Zustand — Selectors Only
+
+```typescript
+// ✅ CORRECT — only re-renders when radius changes
+const radius = useFilterStore((s) => s.radius);
+
+// ❌ WRONG — re-renders on ANY store change
+const { radius, category } = useFilterStore();
+```
+
+### URL State
+
+```typescript
+const [searchParams, setSearchParams] = useSearchParams();
+const tab = searchParams.get('tab') ?? 'discover';
+```
+
+## API Error Handling
+
+The backend returns RFC 9457 problem-details JSON on all errors. The API client parses these into `ApiError` instances. Three tiers handle them: forms → toast → root ErrorBoundary (see provider stack below).
+
+### Error classification
+
+| ApiError property | HTTP status | UI behavior |
+|---|---|---|
+| `isValidation` | 400, 422 | Field errors on form, or detailed toast |
+| `isNotFound` | 404 | Navigate to "not found" page or show empty state |
+| `isForbidden` | 403 | Show "access denied" — do NOT retry |
+| `isUnauthorized` | 401 | Automatic — refresh token → retry → redirect to login |
+| `isConflict` | 409 | Show "already exists" or "was modified" — suggest refresh |
+| 5xx | 500, 502, 503 | Generic "Something went wrong" toast — **never** show `error.detail` (may contain stack traces) |
+
+Always include `error.correlationId` in error UI so users can report it to support.
+
+### Forms — automatic server-to-field mapping
+
+```typescript
+const { register, handleSubmit, errors } = useForm({
+  schema: z.object({ name: z.string().min(1), email: z.string().email() }),
+  onSubmit: async (data) => await api.post('/items', data),
+});
+// Server { errors: { email: "already taken" } } → errors.email auto-set
+// Non-field errors → errors._root
+```
+
+### Non-form mutations — MANDATORY `onError`
+
+```typescript
+const mutation = useMutation({
+  mutationFn: (id: string) => api.delete(`/items/${id}`),
+  onError: (error) => {
+    if (error instanceof ApiError) {
+      toast.error(error); // ApiError-aware — extracts title + detail
+    }
+  },
+});
+```
+
+## App Root Provider Stack (MANDATORY)
+
+The app root must wrap providers in this exact order. Outer providers are available to inner ones.
+
+```tsx
+<Sentry.ErrorBoundary fallback={<ErrorFallback />}>
+  <QuanticProvider client={apiClient}>
+    <QuanticQueryProvider>
+      <ToastProvider>
+        <ErrorBoundary
+          fallback={(error, reset) => <AppErrorPage error={error} onRetry={reset} />}
+          onError={(error) => Sentry.captureException(error)}
+        >
+          <RouterProvider router={router} />
+        </ErrorBoundary>
+      </ToastProvider>
+    </QuanticQueryProvider>
+  </QuanticProvider>
+</Sentry.ErrorBoundary>
+```
+
+**Why this order:**
+- `Sentry.ErrorBoundary` outermost — catches errors even if inner providers fail to mount
+- `QuanticProvider` — API client context, needed by everything below
+- `QuanticQueryProvider` — TanStack Query with smart defaults (no 4xx retry, 30s stale time)
+- `ToastProvider` — toast context must wrap ErrorBoundary so error fallbacks can show toasts
+- `ErrorBoundary` — catches render errors, shows recoverable UI, reports to Sentry
+- `RouterProvider` innermost — pages and components
+
+## shadcn/ui Components
+
+Use shadcn/ui primitives from `@/components/ui`. Compose into feature components — never modify primitives directly. All components must accept `className` for extension and forward refs.
+
+## Component Library Requirements
+
+- Every shared component must have a Storybook entry showing variants, states (loading, disabled, error), and usage
+- Accessibility enforced in CI via axe-core at WCAG 2.1 Level AA — violations block PR merges
+
+## Dark Mode
+
+Use CSS variables: `hsl(var(--background))`, `hsl(var(--primary))`, etc.
+
+## TypeScript Strict Mode
+
+All code uses `strict: true`, `noUncheckedIndexedAccess: true`. No `any`, no `@ts-ignore`.
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true
+  }
+}
+```
+
+## Browser Type Safety
+
+```typescript
+// ❌ WRONG — requires @types/node
+const timer: NodeJS.Timeout = setTimeout(() => {}, 1000);
+
+// ✅ CORRECT
+const timer: ReturnType<typeof setTimeout> = setTimeout(() => {}, 1000);
+```
+
+## Page Components
+
+All page components are lazy-loaded with `React.lazy()` and wrapped in `<Suspense>`.
+
+## Design Tokens
+
+No hardcoded hex values in application code. All visual values come from design tokens/CSS variables.
+
+## QuanticJS Framework Usage
+
+All frontend code uses framework packages from `@quanticjs/*`. These are the canonical tools — do not introduce alternatives.
+
+### Packages
+
+| Package | Purpose | Used by |
+|---|---|---|
+| `@quanticjs/react-core` | API client, `ApiError`, `useClient`, `usePermissions`, `QuanticProvider`, `QuanticQueryProvider` | App roots, data hooks |
+| `@quanticjs/react-forms` | `useForm` with Zod + automatic server error mapping | All forms |
+| `@quanticjs/workflow-ui` | `WorkflowProvider`, task hooks (`useTaskList`, `useTask`, `useTaskClaim`, `useTaskAction`, `useProcessTimeline`), `TaskInbox`, `WorkflowForm`, `TaskDetail`, `TaskActions`, `ProcessTimeline` | Workflow apps |
+
+### API Client and Errors
+
+Use `useClient()` from `@quanticjs/react-core` for API calls. The client parses RFC 9457 responses into `ApiError` instances.
+
+```typescript
+import { useClient, ApiError, isApiError } from '@quanticjs/react-core';
+```
+
+### Mutation Error Handling
+
+Every `useMutation` must have an `onError` callback that uses `ApiError`-aware toasting:
+
+```typescript
+onError: (error) => {
+  if (error instanceof ApiError) {
+    toast({
+      title: error.isServerError ? 'Something went wrong' : error.title,
+      description: error.isServerError
+        ? `Please try again. (ref: ${error.correlationId ?? 'unknown'})`
+        : `${error.detail ?? ''} (ref: ${error.correlationId ?? 'unknown'})`,
+      variant: 'destructive',
+    });
+  }
+},
+```
+
+### Toast Provider
+
+Use the app's `useToast()` hook (from `@/components/toast-provider` or `WorkflowProvider`). Toasts always include `correlationId` for error cases.
+
+### Library Components (`@quanticjs/workflow-ui`)
+
+All exported components MUST:
+- Accept `className` prop for style extension
+- Forward refs where applicable
+- Use CSS variables / Tailwind semantic classes — no hardcoded hex or spacing values
+- No `console.log` / `console.warn` — use Sentry or structured error reporting
+
+### Third-Party Library Integration (bpmn-js)
+
+bpmn-js lacks TypeScript types. All `any` casts must be isolated behind a typed adapter module (`bpmn-types.ts`) that provides typed wrappers for `modeler.get()`:
+
+```typescript
+// bpmn-types.ts — centralized typed access
+import type Modeler from 'bpmn-js/lib/Modeler';
+import type Viewer from 'bpmn-js/lib/Viewer';
+
+interface BpmnCanvas { zoom(level: number | 'fit-viewport'): number; addMarker(id: string, cls: string): void; removeMarker(id: string, cls: string): void; scrollToElement(el: BpmnElement): void; }
+interface BpmnCommandStack { canUndo(): boolean; canRedo(): boolean; undo(): void; redo(): void; }
+interface BpmnElementRegistry { get(id: string): BpmnElement | undefined; }
+interface BpmnModeling { updateProperties(element: BpmnElement, props: Record<string, unknown>): void; }
+interface BpmnSelection { select(element: BpmnElement): void; }
+interface BpmnOverlays { add(id: string, type: string, overlay: unknown): void; remove(filter: Record<string, unknown>): void; }
+interface BpmnModdle { create(type: string, props?: Record<string, unknown>): unknown; }
+export interface BpmnElement { id: string; type: string; businessObject?: Record<string, unknown>; width?: number; height?: number; source?: BpmnElement; [key: string]: unknown; }
+
+type ServiceMap = { canvas: BpmnCanvas; commandStack: BpmnCommandStack; elementRegistry: BpmnElementRegistry; modeling: BpmnModeling; selection: BpmnSelection; overlays: BpmnOverlays; moddle: BpmnModdle; };
+
+export function getService<K extends keyof ServiceMap>(modeler: Modeler | Viewer, name: K): ServiceMap[K] {
+  return (modeler as Record<string, unknown>).get(name) as ServiceMap[K];
+}
+```
+
+## NEVER
+
+- **NEVER** fetch data with `useEffect` + `useState` — use TanStack Query
+- **NEVER** copy query data into `useState` — it creates a stale snapshot
+- **NEVER** mirror URL params into `useState` — read from `useSearchParams` directly
+- **NEVER** put server data in Zustand — use TanStack Query
+- **NEVER** destructure entire Zustand store without selectors
+- **NEVER** add Redux, MobX, Jotai, Recoil, or Valtio
+- **NEVER** use `console.log` in production code — use Sentry
+- **NEVER** use `any` — use `unknown` and narrow
+- **NEVER** use `@ts-ignore` — use `@ts-expect-error` with comment
+- **NEVER** use `NodeJS.Timeout` or other Node.js types in frontend code
+- **NEVER** hardcode hex colors or spacing values — use design tokens
+- **NEVER** prop-drill through components that don't use the prop
+- **NEVER** parse API error responses manually — use `ApiError` properties (`detail`, `fieldErrors`, `correlationId`)
+- **NEVER** show raw error messages to users in production — map `ApiError.status` to user-friendly messages
+- **NEVER** show `error.detail` from 5xx responses — may contain stack traces; use generic message instead
+- **NEVER** write `catch (e) { console.log(e) }` on mutations — swallowing errors silently is a bug
+- **NEVER** omit `onError` on non-form mutations — every mutation failure must be visible to the user
+- **PREFER** `<ErrorBoundary>` on page components — allows recovering a single page without resetting the entire app (the root boundary is the fallback)
+- **NEVER** use `react-hook-form` directly — use `useForm` from `@quanticjs/react-forms` which adds automatic server error mapping
+- **NEVER** manually map server validation errors to form fields — `useForm` does this automatically via `ApiError.fieldErrors`
+- **NEVER** scatter `(modeler as any).get(...)` across components — isolate all bpmn-js `any` casts in a single `bpmn-types.ts` adapter module
+- **NEVER** use `console.warn` or `console.error` in library packages — use Sentry or structured error reporting
+- **NEVER** export components from `@quanticjs/*` packages without `className` prop support
+- **NEVER** use inline `style={{ gap: '1rem' }}` — use Tailwind gap utilities (`gap-4`) or CSS variables

package/templates/claude/rules/observability-backend.md

@@ -0,0 +1,132 @@
+---
+globs: "src/**/*.ts"
+---
+
+# Backend Observability
+
+## Three Pillars
+
+| Pillar | Tool | Purpose |
+|--------|------|---------|
+| **Logging** | ELK via `nestjs-pino` | Structured JSON logs with correlation IDs |
+| **Metrics** | Prometheus + Grafana | Latency, error rates, Redis stream lag |
+| **Tracing** | OpenTelemetry → Elasticsearch APM | Distributed traces across HTTP, CQRS, Redis |
+
+## Structured Logging
+
+All logging uses Pino (`nestjs-pino`). Every request gets a `requestId` propagated through the CQRS pipeline. All logs must be structured JSON (key-value pairs), not string interpolation.
+
+```typescript
+// ✅ CORRECT
+this.logger.info({ userId }, 'User created');
+
+// ❌ WRONG
+this.logger.info('User created: ' + userId);
+```
+
+**Log levels:**
+
+| Level | When |
+|-------|------|
+| `error` | Unrecoverable failures — DB down, DLQ events, uncaught exceptions |
+| `warn` | Degraded operation — retry triggered, cache miss on hot path, slow query (>1s) |
+| `info` | Normal operation — request start/end, command executed, event published |
+| `debug` | Dev-only — query params, cache key computed, lock acquired |
+
+## CQRS Pipeline Logging
+
+Automatic via `LogBehavior`: one structured entry per command/query with name, duration, result, correlationId, userId.
+
+## Sensitive Field Handling (LogBehavior)
+
+The `LogBehavior` pipeline step handles sensitive data automatically at three levels:
+
+**1. Built-in PII masking (automatic — no configuration needed):**
+
+These fields are auto-detected and masked in every command/query payload:
+
+| Field name | Masking |
+|------------|---------|
+| `email` | `j***@example.com` (first char + domain) |
+| `password` | `[REDACTED]` |
+| `token` | `[REDACTED]` |
+| `accessToken` | `[REDACTED]` |
+| `githubAccessToken` | `[REDACTED]` |
+| `secretKey` | `[REDACTED]` |
+
+**2. Per-command field exclusion (`logExclude`):**
+
+Commands can exclude additional fields via a static property. Excluded fields show `[excluded]` in logs:
+
+```typescript
+export class CreateIntegrationCommand {
+  static logExclude = ['webhookSecret', 'apiKey'];
+
+  constructor(
+    readonly name: string,
+    readonly webhookSecret: string,
+    readonly apiKey: string,
+  ) {}
+}
+// Logs: { name: "Stripe", webhookSecret: "[excluded]", apiKey: "[excluded]" }
+```
+
+**3. Suppressing entire payload (`@Log({ logPayload: false })`):**
+
+For commands where the entire payload is sensitive, disable payload logging — only metadata (name, duration, result status) is logged:
+
+```typescript
+@Log({ logPayload: false })
+@Validate(BulkImportValidator)
+export class BulkImportCommand {
+  constructor(readonly records: SensitiveRecord[]) {}
+}
+```
+
+## Payload Sanitization (automatic)
+
+LogBehavior sanitizes all payloads before logging:
+
+| Rule | Behavior |
+|------|----------|
+| Strings > 200 chars | Truncated: `"value..."` + `(N chars)` |
+| Arrays > 5 items | First 5 items + `"... +N more"` |
+| Object depth > 2 | Nested objects show `[nested]` |
+
+## Pino HTTP Serializers
+
+HTTP request/response logs are stripped to safe fields only:
+- **Request:** `id`, `method`, `url`, `correlationId`
+- **Response:** `statusCode`
+
+No headers, bodies, or query parameters are logged at the HTTP layer.
+
+## Handler Skip — Not Supported
+
+There is no mechanism to skip logging for an entire handler. All commands/queries pass through `LogBehavior`. Use `@Log({ logPayload: false })` to suppress payload if needed.
+
+## Key Metrics
+
+- `http_request_duration_seconds`, `http_requests_total`
+- `cqrs_command_duration_seconds`, `cqrs_command_errors_total`
+- `redis_stream_lag`, `redis_stream_dlq_length`
+- `typeorm_query_duration_seconds`
+
+## Alerting Thresholds
+
+| Alert | Condition | Severity |
+|-------|-----------|----------|
+| High API latency | p95 > 2s for 5 min | Warning |
+| API error rate | 5xx > 5% for 5 min | Critical |
+| Redis stream lag | Pending > 1000 for 10 min | Warning |
+| DLQ growing | DLQ > 100 in 1 hour | Critical |
+| Connection pool exhausted | Active > 90% pool | Critical |
+| Pod OOM kill | Container OOMKilled restart | Critical |
+
+## NEVER
+
+- **NEVER** use `console.log` in application code — use Pino via the injected logger
+- **NEVER** use unstructured log messages — all logs must be structured JSON key-value pairs
+- **NEVER** log sensitive data (passwords, tokens, PII) — use `logExclude` or `@Log({ logPayload: false })`
+- **NEVER** rely solely on built-in PII masking for domain-specific secrets — add them to `logExclude`
+- **NEVER** leave critical paths without alerting

package/templates/claude/rules/observability-frontend.md

@@ -0,0 +1,49 @@
+---
+globs: "client/src/**/*.{ts,tsx}"
+---
+
+# Frontend Observability
+
+## Sentry — Error Tracking + Performance
+
+```typescript
+Sentry.init({
+  dsn: import.meta.env.VITE_SENTRY_DSN,
+  integrations: [Sentry.browserTracingIntegration(), Sentry.replayIntegration({ maskAllText: true })],
+  tracesSampleRate: import.meta.env.VITE_ENV === 'production' ? 0.1 : 1.0,
+  replaysOnErrorSampleRate: 1.0,
+});
+```
+
+## Environment Configuration
+
+| Environment | Error tracking | Performance sampling | Session replay |
+|---|---|---|---|
+| Local dev | Disabled | Disabled | Disabled |
+| Dev / Staging | All errors | 100% | On error only |
+| Production | All errors | 10% | On error only |
+
+## Alert Triage
+
+Unresolved Sentry issues must be triaged within 48 hours — assign an owner or mark as expected behavior.
+
+## Web Vitals
+
+LCP < 2.5s, INP < 200ms, CLS < 0.1. JS bundle < 200KB gzipped.
+
+## Backend Correlation
+
+Every API request includes `x-request-id` header for end-to-end tracing.
+
+```typescript
+api.interceptors.request.use((config) => {
+  config.headers['x-request-id'] = crypto.randomUUID();
+  return config;
+});
+```
+
+## NEVER
+
+- **NEVER** use `console.log` in application code — use Sentry
+- **NEVER** include monitoring tools (pino-pretty, debug transports) in production frontend bundles
+- **NEVER** log PII to Sentry