chore: import upstream snapshot with attribution

.cursor/rules/constitution.mdc

@@ -0,0 +1,76 @@
+---
+description: Sim product language, positioning, and tone guidelines
+globs: ["apps/sim/app/(landing)/**", "apps/docs/**", "apps/sim/app/manifest.ts", "apps/sim/app/sitemap.ts", "apps/sim/app/robots.ts", "apps/sim/app/llms.txt/**", "apps/sim/app/llms-full.txt/**", "apps/sim/app/(landing)/**/structured-data*", "apps/docs/**/structured-data*", "**/metadata*", "**/seo*"]
+---
+
+# Sim — Language & Positioning
+
+When editing user-facing copy (landing pages, docs, metadata, marketing), follow these rules.
+
+## Identity
+
+Sim is the **AI workspace** where teams build and run AI agents. Not a workflow tool, not an agent framework, not an automation platform.
+
+**Short definition:** Sim is the open-source AI workspace where teams build, deploy, and manage AI agents.
+
+**Full definition:** Sim is the open-source AI workspace where teams build, deploy, and manage AI agents. Connect 1,000+ integrations and every major LLM to create agents that automate real work — visually, conversationally, or with code.
+
+## Audience
+
+**Primary:** Teams building AI agents for their organization — IT, operations, and technical teams who need governance, security, lifecycle management, and collaboration.
+
+**Secondary:** Individual builders and developers who care about speed, flexibility, and open source.
+
+## Required Language
+
+| Concept | Use | Never use |
+|---------|-----|-----------|
+| The product | "AI workspace" | "workflow tool", "automation platform", "agent framework" |
+| Building | "build agents", "create agents" | "create workflows" (unless describing the workflow module specifically) |
+| Visual builder | "workflow builder" or "visual builder" | "canvas", "graph editor" |
+| Mothership | "Mothership" (capitalized) | "chat", "AI assistant", "copilot" |
+| Deployment | "deploy", "ship" | "publish", "activate" |
+| Audience | "teams", "builders" | "users", "customers" (in marketing copy) |
+| What agents do | "automate real work" | "automate tasks", "automate workflows" |
+| Our advantage | "open-source AI workspace" | "open-source platform" |
+
+## Tone
+
+- **Direct.** Short sentences. Active voice. Lead with what it does.
+- **Concrete.** Name specific things — "Slack bots, compliance agents, data pipelines" — not abstractions.
+- **Confident, not loud.** No exclamation marks or superlatives.
+- **Simple.** If a 16-year-old can't understand the sentence, rewrite it.
+
+## Claim Hierarchy
+
+When describing Sim, always lead with the most differentiated claim:
+
+1. **What it is:** "The AI workspace for teams"
+2. **What you do:** "Build, deploy, and manage AI agents"
+3. **How:** "Visually, conversationally, or with code"
+4. **Scale:** "1,000+ integrations, every major LLM"
+5. **Trust:** "Open source. SOC2. Trusted by 100,000+ builders."
+
+## Module Descriptions
+
+| Module | One-liner |
+|--------|-----------|
+| **Mothership** | Your AI command center. Build and manage everything in natural language. |
+| **Workflows** | The visual builder. Connect blocks, models, and integrations into agent logic. |
+| **Knowledge Base** | Your agents' memory. Upload docs, sync sources, build vector databases. |
+| **Tables** | A database, built in. Store, query, and wire structured data into agent runs. |
+| **Files** | Upload, create, and share. One store for your team and every agent. |
+| **Logs** | Full visibility, every run. Trace execution block by block. |
+
+## What We Never Say
+
+- Never call Sim "just a workflow tool"
+- Never compare only on integration count — we win on AI-native capabilities
+- Never use "no-code" as the primary descriptor — say "visually, conversationally, or with code"
+- Never promise unshipped features
+- Never use jargon ("RAG", "vector database", "MCP") without plain-English explanation on public pages
+- Avoid "agentic workforce" as a primary term — use "AI agents"
+
+## Vision
+
+Sim becomes the default environment where teams build AI agents — not a tool you visit for one task, but a workspace you live in. Workflows are one module; Mothership is another. The workspace is the constant; the interface adapts.

.cursor/rules/emcn-components.mdc

@@ -0,0 +1,42 @@
+---
+description: EMCN component library patterns
+globs: ["apps/sim/components/emcn/**"]
+---
+# EMCN Components
+
+Import from `@sim/emcn`, never from subpaths (except CSS files). The **chip family** is the platform's primary chrome — always reach for it over the legacy primitives it is progressively replacing (`Input`→`ChipInput`, `Textarea`→`ChipTextarea`, `Modal`→`ChipModal`, `Select`/`Combobox`→`ChipSelect`/`ChipCombobox`/`ChipDropdown`, `Switch`→`ChipSwitch`, date field→`ChipDatePicker`). For context/action menus the canonical control is `DropdownMenu` — the standard menu (not a chip, and never a hand-rolled popover).
+
+## Chip chrome — single source of truth
+
+Never hand-roll the chip pill from raw class strings (they go stale). Compose from the canonical sources:
+
+- **Surface, typography + content tokens:** `chip/chip-chrome.ts` — `chipFilledSurfaceTokens`, `chipFieldSurfaceClass`, `chipFieldTextClass` (text fields and the dropdown search box build on these), plus the chip-content chrome `chipContentGap`, `chipGeometryClass`, `chipContentIconClass`, `chipContentLabelClass`, and `cellIconNodeClass` (non-chip surfaces that must visually match chip content, e.g. resource table cells). All are re-exported from the `@sim/emcn` barrel — no subpath import needed.
+- **Pill geometry:** `chip/chip.tsx` — `chipVariants` (30px tall, `rounded-lg`, `px-2`, icon↔text `gap-1.5`). Every pill-shaped trigger (`ChipDropdown`, `ChipSelect`, `ChipSwitch`) reuses it for visual parity.
+
+Canonical look: normal font-weight (never `font-medium`/`font-semibold`), value text `--text-body`, icons `--text-icon` at `size-[14px]`, placeholder `--text-muted`, `transition-colors`, **no focus ring** (the caret marks focus). Filled surface is `--surface-5` light / `--surface-4` dark with a `--border-1` border.
+
+The menu surface intentionally diverges from the pill: `dropdown-menu.tsx` items use `text-small` and `gap-2` (a menu convention, not the chip pill). Keep them distinct.
+
+## Component catalogue
+
+- **`Chip` / `ChipLink`** — the pill button (`<button>` / Next `<Link>`). Variants: `ghost`, `filled`, `primary`, `destructive`, `border-shadow`. `leftIcon`/`rightIcon`, `active`, `fullWidth`, `flush`.
+- **`ChipInput`** — single-line text field. `icon`, `endAdornment`, `error`, `inputClassName` (inner `<input>`); `className` styles the chrome wrapper.
+- **`ChipTextarea`** — multi-line sibling. `error`, `resizable` (off by default).
+- **`ChipDropdown`** — pill that opens a menu. Single OR multi-select via the discriminated `multiple` prop (one component, not two). Owns its trailing chevron — no `rightIcon`.
+- **`ChipSelect` / `ChipCombobox`** — `Combobox`-backed pickers with search, groups, multi-select; for richer lists than `ChipDropdown`.
+- **`ChipModal` + `ChipModalField`** — declarative compact modal. The field's `type` (`input` | `email` | `textarea` | `dropdown` | `file` | `emails` | `custom`) picks the control and **owns all chrome** — consumers describe intent, never pass `variant`/`className`/`id` to the inner control. `custom` is the escape hatch. **Every body field MUST be a `ChipModalField`** — never hand-roll a field row (raw `<div>` + hand-rolled `<p>`/`<label>` title + bare `ChipInput`/`ChipTextarea`). `ChipModalBody` applies `px-2` + `gap-4`; `ChipModalField` adds another `px-2`, so each field lands at effective `px-4`, exactly matching the `px-4` header/footer — a hand-rolled row skips that gutter and sits misaligned at `px-2`. For controls the field doesn't cover (`ChipCombobox`, `ChipSelect`, `DatePicker`, `TimePicker`, `ButtonGroup`, arbitrary JSX), use `type='custom'` with a `title` — it still applies the gutter and renders the canonical `Label`.
+- **`ChipSwitch`** — segmented pill control (built from `chipVariants`).
+- **`ChipTag`** — 20px inline tag/badge (`mono`/`gray`/`invite`), not a pill trigger.
+- **`ChipDatePicker`** — chip-styled date field.
+- **`DropdownMenu`** — the canonical context/action menu (Radix-backed). Not a chip, but the standard menu for command/action lists; reach for it instead of a hand-rolled popover. Its surface intentionally diverges from the chip pill (`text-small`, `gap-2`) — keep them distinct. For a pill that opens a value picker, use `ChipDropdown`/`ChipSelect` instead.
+
+## Authoring principles
+
+- **One source of truth for shared chrome.** Compose from `chip-chrome.ts` / `chipVariants`; never duplicate the chrome string.
+- **`cn()` for a single state toggle, CVA for genuine multiple variants.** A lone `error` boolean is `cn()`, not a CVA variant.
+- **Discriminated-union props for modes** (e.g. `multiple`, the modal field `type`) instead of near-duplicate components.
+- **Delete legacy variants after migration** — don't leave dead paths (this paradigm removed `Input variant='chip'` and `ChipMultiSelect`).
+- **Verify CSS vars exist.** An undefined var resolves to `currentColor` (caused a real black-border bug). Align to the canonical tokens: normal weight, `--text-body`, `--text-icon`.
+- Use Radix UI primitives for accessibility. Export the component and its `variants` (when using CVA). Document with TSDoc + a usage example.
+
+Color tokens and icon-size conventions are canonical in `.claude/rules/sim-styling.md` — follow it rather than restating.

.cursor/rules/global.mdc

@@ -0,0 +1,71 @@
+---
+description: Global coding standards that apply to all files
+alwaysApply: true
+---
+# Global Standards
+
+## Logging
+Import `createLogger` from `@sim/logger`. Use `logger.info`, `logger.warn`, `logger.error` instead of `console.log`. Inside API routes wrapped with `withRouteHandler`, loggers automatically include the request ID.
+
+## API Route Handlers
+All API route handlers must be wrapped with `withRouteHandler` from `@/lib/core/utils/with-route-handler`. Never export a bare `async function GET/POST/...` — always use `export const METHOD = withRouteHandler(...)`.
+
+## Comments
+Use TSDoc for documentation. No `====` separators. No non-TSDoc comments.
+
+## Styling
+Never update global styles. Keep all styling local to components.
+
+## ID Generation
+Never use `crypto.randomUUID()`, `nanoid`, or the `uuid` package directly. Use the utilities from `@sim/utils/id`:
+
+- `generateId()` — UUID v4, use by default
+- `generateShortId(size?)` — short URL-safe ID (default 21 chars), for compact identifiers
+
+Both use `crypto.getRandomValues()` under the hood and work in all contexts including non-secure (HTTP) browsers.
+
+```typescript
+// ✗ Bad
+import { nanoid } from 'nanoid'
+import { v4 as uuidv4 } from 'uuid'
+const id = crypto.randomUUID()
+
+// ✓ Good
+import { generateId, generateShortId } from '@sim/utils/id'
+const uuid = generateId()
+const shortId = generateShortId()
+const tiny = generateShortId(8)
+```
+
+## Common Utilities
+Use shared helpers from `@sim/utils` instead of writing inline implementations:
+
+- `sleep(ms)` from `@sim/utils/helpers` — async delay. Never write `new Promise(resolve => setTimeout(resolve, ms))`
+- `toError(value)` from `@sim/utils/errors` — normalize unknown caught values to `Error`. Never write `e instanceof Error ? e : new Error(String(e))`
+- `getErrorMessage(value, fallback?)` from `@sim/utils/errors` — extract error message string. Never write `e instanceof Error ? e.message : 'fallback'`
+- `structuredClone(value)` — built-in deep clone, no import needed. Never write `JSON.parse(JSON.stringify(obj))`
+- `omit(obj, keys)` from `@sim/utils/object` — remove keys from object
+- `filterUndefined(obj)` from `@sim/utils/object` — strip undefined-valued keys. Never write `Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined))`
+- `truncate(str, maxLength, suffix?)` from `@sim/utils/string` — safe string truncation with ellipsis
+- `backoffWithJitter(attempt, retryAfterMs, options?)` from `@sim/utils/retry` — exponential backoff with jitter
+- `parseRetryAfter(header)` from `@sim/utils/retry` — parse HTTP `Retry-After` header to milliseconds
+
+```typescript
+// ✗ Bad
+await new Promise(resolve => setTimeout(resolve, 1000))
+const msg = error instanceof Error ? error.message : 'Unknown error'
+const clone = JSON.parse(JSON.stringify(obj))
+const filtered = Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined))
+
+// ✓ Good
+import { sleep } from '@sim/utils/helpers'
+import { getErrorMessage, toError } from '@sim/utils/errors'
+import { filterUndefined } from '@sim/utils/object'
+await sleep(1000)
+const msg = getErrorMessage(error, 'Unknown error')
+const clone = structuredClone(obj)
+const filtered = filterUndefined(obj)
+```
+
+## Package Manager
+Use `bun` and `bunx`, not `npm` and `npx`.

.cursor/rules/landing-seo-geo.mdc

@@ -0,0 +1,25 @@
+---
+description: SEO and GEO guidelines for the landing page
+globs: ["apps/sim/app/(landing)/**/*.tsx"]
+---
+# Landing Page — SEO / GEO
+
+## SEO
+
+- One `<h1>` per page, in Hero only — never add another.
+- Strict heading hierarchy: H1 (Hero) → H2 (section titles) → H3 (feature names).
+- Every section: `<section id="…" aria-labelledby="…-heading">`.
+- Decorative/animated elements: `aria-hidden="true"`.
+- All internal routes use Next.js `<Link>` (crawlable). External links get `rel="noopener noreferrer"`.
+- Navbar is a Server Component (no `'use client'`) for immediate crawlability. Logo `<Image>` has `priority` (LCP element).
+- Navbar `<nav>` carries `SiteNavigationElement` schema.org markup.
+- Feature lists must stay in sync with `WebApplication.featureList` in `structured-data.tsx`.
+
+## GEO (Generative Engine Optimisation)
+
+- **Answer-first pattern**: each section's H2 + subtitle should directly answer a user question (e.g. "What is Sim?", "How fast can I deploy?").
+- **Atomic answer blocks**: each feature / template card should be independently extractable by an AI summariser.
+- **Entity consistency**: always write "Sim" by name — never "the platform" or "our tool".
+- **Keyword density**: first 150 visible chars of Hero must name "Sim", "AI workspace", "AI agents".
+- **sr-only summaries**: Hero and Templates each have a `<p className="sr-only">` (~50 words) as an atomic product/catalog summary for AI citation.
+- **Specific numbers**: prefer concrete figures ("1,000+ integrations", "15+ AI providers") over vague claims.

.cursor/rules/sim-architecture.mdc

@@ -0,0 +1,66 @@
+---
+description: Core architecture principles for the Sim app
+globs: ["apps/sim/**"]
+---
+# Sim App Architecture
+
+## Core Principles
+1. **Single Responsibility**: Each component, hook, store has one clear purpose
+2. **Composition Over Complexity**: Break down complex logic into smaller pieces
+3. **Type Safety First**: TypeScript interfaces for all props, state, return types
+4. **Predictable State**: Zustand for global state, useState for UI-only concerns
+
+## Root-Level Structure
+
+```
+apps/
+├── sim/                 # this app (Next.js: UI + API routes + workflow editor)
+│   ├── app/             # Next.js app router (pages, API routes)
+│   ├── blocks/          # Block definitions and registry
+│   ├── components/      # Shared UI (emcn/, ui/)
+│   ├── executor/        # Workflow execution engine
+│   ├── hooks/           # Shared hooks (queries/, selectors/)
+│   ├── lib/             # App-wide utilities
+│   ├── providers/       # LLM provider integrations
+│   ├── stores/          # Zustand stores
+│   ├── tools/           # Tool definitions
+│   └── triggers/        # Trigger definitions
+└── realtime/            # Bun Socket.IO server (collaborative canvas)
+
+packages/                # @sim/* — audit, auth, db, logger, realtime-protocol,
+                         # security, tsconfig, utils, platform-authz,
+                         # workflow-persistence, workflow-types
+```
+
+## Package Boundaries
+
+- `apps/* → packages/*` only. Packages never import from `apps/*`.
+- `apps/realtime` avoids Next.js, React, the block/tool registry, provider SDKs, and the executor; never add `@/lib/webhooks/providers/*`, `@/executor/*`, `@/blocks/*`, or `@/tools/*` imports to any package it consumes. CI enforces this via `scripts/check-monorepo-boundaries.ts` and `scripts/check-realtime-prune-graph.ts`.
+
+## Feature Organization
+
+Features live under `app/workspace/[workspaceId]/`:
+
+```
+feature/
+├── components/          # Feature components
+├── hooks/               # Feature-scoped hooks
+├── utils/               # Feature-scoped utilities (2+ consumers)
+├── feature.tsx          # Main component
+└── page.tsx             # Next.js page entry
+```
+
+## Naming Conventions
+- **Components**: PascalCase (`WorkflowList`)
+- **Hooks**: `use` prefix (`useWorkflowOperations`)
+- **Files**: kebab-case (`workflow-list.tsx`)
+- **Stores**: `stores/feature/store.ts`
+- **Constants**: SCREAMING_SNAKE_CASE
+- **Interfaces**: PascalCase with suffix (`WorkflowListProps`)
+
+## Utils Rules
+
+- **Never create `utils.ts` for single consumer** - inline it
+- **Create `utils.ts` when** 2+ files need the same helper
+- **Check existing sources** before duplicating (`lib/` has many utilities)
+- **Location**: `lib/` (app-wide) → `feature/utils/` (feature-scoped) → inline (single-use)

.cursor/rules/sim-components.mdc

@@ -0,0 +1,13 @@
+---
+description: Component patterns and structure for React components
+globs: ["apps/sim/**/*.tsx"]
+---
+# Component Patterns
+
+Component authoring rules — structure order (refs → external hooks → store hooks → custom hooks → state → useMemo → useCallback → useEffect → return), required props interface, and extraction thresholds (50+ lines / 2+ files vs keep inline < 10 lines) — live in CLAUDE.md > Components.
+
+`.tsx`-specific deltas not covered there:
+
+- `'use client'` only when using React hooks or browser-only APIs.
+- Prefer semantic HTML (`aside`, `nav`, `article`).
+- Optional-chain callbacks: `onAction?.(id)`.

.cursor/rules/sim-hooks.mdc

@@ -0,0 +1,48 @@
+---
+description: Custom hook patterns and best practices
+globs: ["apps/sim/**/use-*.ts", "apps/sim/**/hooks/**/*.ts"]
+---
+# Hook Patterns
+
+## Structure
+
+For server data, use a React Query hook from `hooks/queries/` — do NOT `useState` + `fetch` here (see `.claude/rules/sim-queries.md`). This pattern is for UI/orchestration hooks that hold UI-only state and wrap callbacks.
+
+```typescript
+interface UseFeatureProps {
+  id: string
+  onSelect?: (item: Item) => void
+}
+
+export function useFeature({ id, onSelect }: UseFeatureProps) {
+  // 1. Refs for stable dependencies
+  const idRef = useRef(id)
+  const onSelectRef = useRef(onSelect)
+
+  // 2. UI-only state (never server data)
+  const [isOpen, setIsOpen] = useState(false)
+
+  // 3. Sync refs
+  useEffect(() => {
+    idRef.current = id
+    onSelectRef.current = onSelect
+  }, [id, onSelect])
+
+  // 4. Operations (useCallback with empty deps when using refs)
+  const select = useCallback((item: Item) => {
+    onSelectRef.current?.(item)
+    setIsOpen(false)
+  }, [])
+
+  return { isOpen, setIsOpen, select }
+}
+```
+
+## Rules
+
+1. Single responsibility per hook
+2. Props interface required
+3. Refs for stable callback dependencies
+4. Wrap returned functions in useCallback
+5. Server data goes through React Query (`hooks/queries/`), never `useState` + `fetch`
+6. Keep only UI/orchestration state in these hooks

.cursor/rules/sim-imports.mdc

@@ -0,0 +1,61 @@
+---
+description: Import patterns for the Sim application
+globs: ["apps/sim/**/*.ts", "apps/sim/**/*.tsx"]
+---
+
+# Import Patterns
+
+## Absolute Imports
+
+**Always use absolute imports.** Never use relative imports.
+
+```typescript
+// ✓ Good
+import { useWorkflowStore } from '@/stores/workflows/store'
+import { Button } from '@/components/ui/button'
+
+// ✗ Bad
+import { useWorkflowStore } from '../../../stores/workflows/store'
+```
+
+## Barrel Exports
+
+Use barrel exports (`index.ts`) when a folder has 3+ exports. Import from barrel, not individual files.
+
+```typescript
+// ✓ Good
+import { Dashboard, Sidebar } from '@/app/workspace/[workspaceId]/logs/components'
+
+// ✗ Bad
+import { Dashboard } from '@/app/workspace/[workspaceId]/logs/components/dashboard/dashboard'
+```
+
+## No Re-exports
+
+Do not re-export from non-barrel files. Import directly from the source.
+
+```typescript
+// ✓ Good - import from where it's declared
+import { CORE_TRIGGER_TYPES } from '@/stores/logs/filters/types'
+
+// ✗ Bad - re-exporting in utils.ts then importing from there
+import { CORE_TRIGGER_TYPES } from '@/app/workspace/.../utils'
+```
+
+## Import Order
+
+1. React/core libraries
+2. External libraries
+3. UI components (`@sim/emcn`, `@/components/ui`)
+4. Utilities (`@/lib/...`)
+5. Stores (`@/stores/...`)
+6. Feature imports
+7. CSS imports
+
+## Type Imports
+
+Use `type` keyword for type-only imports:
+
+```typescript
+import type { WorkflowLog } from '@/stores/logs/types'
+```

.cursor/rules/sim-integrations.mdc

@@ -0,0 +1,16 @@
+---
+description: Adding new integrations (tools, blocks, triggers)
+globs: ["apps/sim/tools/**", "apps/sim/blocks/**", "apps/sim/triggers/**"]
+---
+# Adding Integrations
+
+Build order: **Tools** (`tools/{service}/`) → **Block** (`blocks/blocks/{service}.ts`) → **Icon** (`components/icons.tsx`) → optional **Trigger** (`triggers/{service}/`). Always look up the service's API docs first.
+
+The full authoring instructions — tool/block/icon/trigger scaffolding, SubBlock property tables, `condition`/`required`/`dependsOn`/`mode`/`canonicalParamId` syntax, the `normalizeFileInput`/file-handling helper table, and checklists — live in the skills: `/add-integration` (end-to-end), `/add-tools`, `/add-block`, `/add-trigger`.
+
+## Hard rules (don't get these wrong)
+
+- Tool IDs are `snake_case` (`service_action`). Register tools in `tools/registry.ts`, blocks in `blocks/registry-maps.ts` (the `BLOCK_REGISTRY` config map + `BLOCK_META_REGISTRY` catalog-meta map, alphabetically — `blocks/registry.ts` holds only the accessor functions), triggers in `triggers/registry.ts`.
+- Type coercions (`Number()`, etc.) belong in `tools.config.params` (runs at execution, after variable resolution) — never in `tools.config.tool` (runs at serialization; coercing there destroys dynamic `<Block.output>` references).
+- `canonicalParamId` must NOT match any subblock's `id`, must be unique per operation/condition context, and all subblocks in a canonical group must share the same `required` status. The `inputs` section and the params function reference canonical IDs, not raw subblock IDs.
+- Blocks must also set the catalog/UI metadata fields `integrationType`, `tags`, `authMode`, `docsLink`, and export a `{Service}BlockMeta` — see the `/add-block` skill's BlockMeta section for details.

.cursor/rules/sim-queries.mdc

@@ -0,0 +1,138 @@
+---
+description: React Query patterns for the Sim application
+globs: ["apps/sim/hooks/queries/**/*.ts"]
+---
+# React Query Patterns
+
+All React Query hooks live in `hooks/queries/`. All server state must go through React Query — never use `useState` + `fetch` in components for data fetching or mutations.
+
+## Query Key Factory
+
+Every query file defines a hierarchical keys factory with an `all` root key and intermediate plural keys for prefix-level invalidation:
+
+```typescript
+export const entityKeys = {
+  all: ['entity'] as const,
+  lists: () => [...entityKeys.all, 'list'] as const,
+  list: (workspaceId?: string) => [...entityKeys.lists(), workspaceId ?? ''] as const,
+  details: () => [...entityKeys.all, 'detail'] as const,
+  detail: (id?: string) => [...entityKeys.details(), id ?? ''] as const,
+}
+```
+
+Never use inline query keys — always use the factory.
+
+## File Structure
+
+```typescript
+// 1. Query keys factory
+// 2. Types (if needed)
+// 3. Private fetch functions (accept signal parameter)
+// 4. Exported hooks
+```
+
+## Query Hook
+
+- Every `queryFn` must destructure and forward `signal` for request cancellation
+- Every query must have an explicit `staleTime`
+- Use `keepPreviousData` only on variable-key queries (where params change), never on static keys
+- Same-origin JSON calls must go through `requestJson(contract, ...)` from `@/lib/api/client/request` against the contract in `@/lib/api/contracts/**`
+
+```typescript
+import { requestJson } from '@/lib/api/client/request'
+import { listEntitiesContract, type EntityList } from '@/lib/api/contracts/entities'
+
+async function fetchEntities(workspaceId: string, signal?: AbortSignal): Promise<EntityList> {
+  const data = await requestJson(listEntitiesContract, {
+    query: { workspaceId },
+    signal,
+  })
+  return data.entities
+}
+
+export function useEntityList(workspaceId?: string, options?: { enabled?: boolean }) {
+  return useQuery({
+    queryKey: entityKeys.list(workspaceId),
+    queryFn: ({ signal }) => fetchEntities(workspaceId as string, signal),
+    enabled: Boolean(workspaceId) && (options?.enabled ?? true),
+    staleTime: 60 * 1000,
+    placeholderData: keepPreviousData, // OK: workspaceId varies
+  })
+}
+```
+
+## Mutation Hook
+
+- Use targeted invalidation (`entityKeys.lists()`) not broad (`entityKeys.all`) when possible
+- Invalidation must cover all affected query key prefixes (lists, details, related views)
+- Use `onSuccess` invalidation for plain mutations; use `onSettled` for optimistic mutations so the cache is reconciled on both success and error (see Optimistic Updates below)
+- `mutationFn` calls go through `requestJson(contract, { body, signal })` from `@/lib/api/client/request` — same boundary rule as queries
+
+```typescript
+export function useCreateEntity() {
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: (body: CreateEntityBody) => requestJson(createEntityContract, { body }),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: entityKeys.lists() })
+    },
+  })
+}
+```
+
+## Optimistic Updates
+
+For optimistic mutations, use `onSettled` (not `onSuccess`) for cache reconciliation — `onSettled` fires on both success and error, ensuring the cache is always reconciled with the server.
+
+```typescript
+export function useUpdateEntity() {
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: async (variables) => { /* ... */ },
+    onMutate: async (variables) => {
+      await queryClient.cancelQueries({ queryKey: entityKeys.detail(variables.id) })
+      const previous = queryClient.getQueryData(entityKeys.detail(variables.id))
+      queryClient.setQueryData(entityKeys.detail(variables.id), /* optimistic value */)
+      return { previous }
+    },
+    onError: (_err, variables, context) => {
+      queryClient.setQueryData(entityKeys.detail(variables.id), context?.previous)
+    },
+    onSettled: (_data, _error, variables) => {
+      queryClient.invalidateQueries({ queryKey: entityKeys.lists() })
+      queryClient.invalidateQueries({ queryKey: entityKeys.detail(variables.id) })
+    },
+  })
+}
+```
+
+For optimistic mutations syncing with Zustand, use `createOptimisticMutationHandlers` from `@/hooks/queries/utils/optimistic-mutation`.
+
+## useCallback Dependencies
+
+Never include mutation objects (e.g., `createEntity`) in `useCallback` dependency arrays — the mutation object is not referentially stable and changes on every state update. The `.mutate()` and `.mutateAsync()` functions are stable in TanStack Query v5.
+
+```typescript
+// ✗ Bad — causes unnecessary recreations
+const handler = useCallback(() => {
+  createEntity.mutate(data)
+}, [createEntity]) // unstable reference
+
+// ✓ Good — omit from deps, mutate is stable
+const handler = useCallback(() => {
+  createEntity.mutate(data)
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+}, [data])
+```
+
+## Boundary Types
+
+- Hooks import named type aliases from `@/lib/api/contracts/**` (e.g., `import { listEntitiesContract, type EntityList } from '@/lib/api/contracts/entities'`). Never write `z.input<...>` / `z.output<...>` in hooks, and never `import { z } from 'zod'` in client code.
+- Raw `fetch` is allowed only for documented exceptions — multipart uploads, binary downloads, streaming responses, signed-URL flows, OAuth redirects, external origins. Each such raw `fetch(` inside `apps/sim/hooks/queries/**` or `apps/sim/hooks/selectors/**` — and any same-origin `/api/...` fetch elsewhere under `apps/sim/**` outside an API route handler — must be preceded by a `// boundary-raw-fetch: <reason>` annotation (reason non-empty; up to three preceding comment lines tolerated). Enforced by `scripts/check-api-validation-contracts.ts` (`bun run check:api-validation` / `:strict`).
+
+## Naming
+
+- **Keys**: `entityKeys`
+- **Query hooks**: `useEntity`, `useEntityList`
+- **Mutation hooks**: `useCreateEntity`, `useUpdateEntity`, `useDeleteEntity`
+- **Fetch functions**: `fetchEntity`, `fetchEntities` (private)

.cursor/rules/sim-sandbox.mdc

@@ -0,0 +1,85 @@
+---
+description: Isolated-vm sandbox worker security policy. Hard rules for anything that lives in the worker child process that runs user code.
+globs: ["apps/sim/lib/execution/isolated-vm-worker.cjs", "apps/sim/lib/execution/isolated-vm.ts", "apps/sim/lib/execution/sandbox/**", "apps/sim/sandbox-tasks/**"]
+---
+
+# Sim Sandbox — Worker Security Policy
+
+The isolated-vm worker child process at
+`apps/sim/lib/execution/isolated-vm-worker.cjs` runs untrusted user code inside
+V8 isolates. The process itself is a trust boundary. Everything in this rule is
+about what must **never** live in that process.
+
+## Hard rules
+
+1. **No app credentials in the worker process**. The worker must not hold, load,
+   or receive via IPC: database URLs, Redis URLs, AWS keys, Stripe keys,
+   session-signing keys, encryption keys, OAuth client secrets, internal API
+   secrets, or any LLM / email / search provider API keys. If you catch yourself
+   `require`'ing `@/lib/auth`, `@sim/db`, `@/lib/uploads/core/storage-service`,
+   or anything that imports `env` directly inside the worker, stop and use a
+   host-side broker instead.
+
+2. **Host-side brokers own all credentialed work**. The worker can only access
+   resources through `ivm.Reference` / `ivm.Callback` bridges back to the host
+   process. Today the only broker is `workspaceFileBroker`
+   (`apps/sim/lib/execution/sandbox/brokers/workspace-file.ts`); adding a new
+   one requires co-reviewing this file.
+
+3. **Host-side brokers must scope every resource access to a single tenant**.
+   The `SandboxBrokerContext` always carries `workspaceId`. Any new broker that
+   accesses storage, DB, or an external API must use `ctx.workspaceId` to scope
+   the lookup — never accept a raw path, key, or URL from isolate code without
+   validation.
+
+4. **Nothing that runs in the isolate is trusted, even if we wrote it**. The
+   task `bootstrap` and `finalize` strings in `apps/sim/sandbox-tasks/` execute
+   inside the isolate. They must treat `globalThis` as adversarial — no pulling
+   values from it that might have been mutated by user code. The hardening
+   script in `executeTask` undefines dangerous globals before user code runs.
+
+## Why
+
+A V8 JIT bug (Chrome ships these roughly monthly) gives an attacker a native
+code primitive inside the process that owns whatever that process can reach.
+If the worker only holds `isolated-vm` + a single narrow workspace-file broker,
+a V8 escape leaks one tenant's files. If the worker holds a Stripe key or a DB
+connection, a V8 escape leaks the service.
+
+The original `doc-worker.cjs` vulnerability (CVE-class, 225 production secrets
+leaked via `/proc/1/environ`) was the forcing function for this architecture.
+Keep the blast radius small.
+
+## Checklist for changes to `isolated-vm-worker.cjs`
+
+Before landing any change that adds a new `require(...)` or `process.send(...)`
+payload or `ivm.Reference` wrapper in the worker:
+
+- [ ] Does it load a credential, key, connection string, or secret? If yes,
+      move it host-side and expose as a broker.
+- [ ] Does it import from `@/lib/auth`, `@sim/db`, `@/lib/uploads/core/*`,
+      `@/lib/core/config/env`, or any module that reads `process.env` of the
+      main app? If yes, same — move host-side.
+- [ ] Does it expose a resource that's workspace-scoped without taking a
+      `workspaceId`? If yes, re-scope.
+- [ ] Did you update the broker limits (`IVM_MAX_BROKER_ARGS_JSON_CHARS`,
+      `IVM_MAX_BROKER_RESULT_JSON_CHARS`, `IVM_MAX_BROKERS_PER_EXECUTION`) if
+      the new broker can emit large payloads or fire frequently?
+
+## What the worker *may* hold
+
+- `isolated-vm` module
+- Node built-ins: `node:fs` (only for reading the checked-in bundle `.cjs`
+  files) and `node:path`
+- The three prebuilt library bundles under
+  `apps/sim/lib/execution/sandbox/bundles/*.cjs`
+- IPC message handlers for `execute`, `cancel`, `fetchResponse`,
+  `brokerResponse`
+
+The worker deliberately has **no host-side logger**. All errors and
+diagnostics flow through IPC back to the host, which has `@sim/logger`. Do
+not add `createLogger` or console-based logging to the worker — it would
+require pulling the main app's config / env, which is exactly what this
+rule is preventing.
+
+Anything else is suspect.

.cursor/rules/sim-stores.mdc

@@ -0,0 +1,70 @@
+---
+description: Zustand store patterns
+globs: ["apps/sim/**/store.ts", "apps/sim/**/stores/**/*.ts"]
+---
+
+# Zustand Store Patterns
+
+Stores live in `stores/`. Complex stores split into `store.ts` + `types.ts`.
+
+## Basic Store
+
+```typescript
+import { create } from 'zustand'
+import { devtools } from 'zustand/middleware'
+import type { FeatureState } from '@/stores/feature/types'
+
+const initialState = { items: [] as Item[], activeId: null as string | null }
+
+export const useFeatureStore = create<FeatureState>()(
+  devtools(
+    (set, get) => ({
+      ...initialState,
+      setItems: (items) => set({ items }),
+      addItem: (item) => set((state) => ({ items: [...state.items, item] })),
+      reset: () => set(initialState),
+    }),
+    { name: 'feature-store' }
+  )
+)
+```
+
+## Persisted Store
+
+```typescript
+import { create } from 'zustand'
+import { persist } from 'zustand/middleware'
+
+export const useFeatureStore = create<FeatureState>()(
+  persist(
+    (set) => ({
+      width: 300,
+      setWidth: (width) => set({ width }),
+      _hasHydrated: false,
+      setHasHydrated: (v) => set({ _hasHydrated: v }),
+    }),
+    {
+      name: 'feature-state',
+      partialize: (state) => ({ width: state.width }),
+      onRehydrateStorage: () => (state) => state?.setHasHydrated(true),
+    }
+  )
+)
+```
+
+## Rules
+
+1. Use `devtools` middleware (named stores)
+2. Use `persist` only when data should survive reload
+3. `partialize` to persist only necessary state
+4. `_hasHydrated` pattern for persisted stores needing hydration tracking
+5. Immutable updates only
+6. `set((state) => ...)` when depending on previous state
+7. Provide `reset()` action
+
+## Outside React
+
+```typescript
+const items = useFeatureStore.getState().items
+useFeatureStore.setState({ items: newItems })
+```

.cursor/rules/sim-styling.mdc

@@ -0,0 +1,76 @@
+---
+description: Tailwind CSS and styling conventions
+globs: ["apps/sim/**/*.tsx", "apps/sim/**/*.css"]
+---
+# Styling Rules
+
+## Tailwind
+
+1. **No inline styles** - Use Tailwind classes
+2. **No duplicate dark classes** - Skip `dark:` when value matches light mode
+3. **Exact values** - `text-[14px]`, `h-[26px]`
+4. **Transitions** - `transition-colors` for interactive states
+
+## Conditional Classes
+
+```typescript
+import { cn } from '@sim/emcn'
+
+<div className={cn(
+  'base-classes',
+  isActive && 'active-classes',
+  disabled ? 'opacity-60' : 'hover:bg-accent'
+)} />
+```
+
+## CSS Variables
+
+For dynamic values (widths, heights) synced with stores:
+
+```typescript
+// In store
+setWidth: (width) => {
+  set({ width })
+  document.documentElement.style.setProperty('--sidebar-width', `${width}px`)
+}
+
+// In component
+<aside style={{ width: 'var(--sidebar-width)' }} />
+```
+
+## Text Scale
+
+Custom font sizes (`apps/sim/tailwind.config.ts`): `text-micro`=10px, `text-xs`=11px, `text-caption`=12px, `text-small`=13px, `text-base`=15px. `text-sm` is Tailwind default 14px. Field titles use `text-small` (13px); hints/errors use `text-caption` (12px).
+
+Icons default `size-[14px]`. Equal h/w → `size-*` (`size-[14px]`, `size-4`), never `h-N w-N`.
+
+## Color Tokens
+
+Value text `--text-body`; muted/placeholder/labels `--text-muted`; icons `--text-icon`; borders `--border-1` (fields) / `--border` (dividers); surfaces `--surface-5` (light) / `--surface-4` (dark); active row `--surface-active`; error `--text-error`. No focus rings on chip surfaces.
+
+## Chip Components (consumer usage)
+
+`ChipInput`, `ChipTextarea`, `ChipModal*` own their full chrome. Consumers describe intent through PROPS; they never re-style the chrome. The canonical chrome lives in `apps/sim/components/emcn/components/chip/chip-chrome.ts` (all tokens are re-exported from the `@sim/emcn` barrel — no subpath import needed) — never hand-roll `rounded-lg`/`border`/`bg-[var(--surface-5)]`/`h-[30px]`/`px-2`/`text-sm`/focus rings.
+
+### Props over className
+
+- **Errors** → `error` prop. Never `className={cn(err && 'border-[var(--text-error)]')}`.
+- **Leading icon** → `icon` prop (rendered 14px in `--text-icon`).
+- **Trailing buttons** (reveal/copy/fetch) → `endAdornment`.
+- **Inner-input styling** (e.g. `font-mono`, number-spinner reset) → `inputClassName` (ChipInput only). See `app/workspace/[workspaceId]/settings/components/billing/components/usage-limit-field/usage-limit-field.tsx:117`.
+- **`ChipModalField` controls take NO className.** Pass `title`/`value`/`onChange`/`error`/`hint`/`required`/`flush`. The field owns label, control, and error/hint rendering. See `app/workspace/[workspaceId]/skills/components/skill-modal/skill-modal.tsx:170`.
+
+### What className MAY carry
+
+Layout/sizing ONLY: `flex-1`, `w-full`, `w-[Npx]`, `min-w-0`, `max-w-*`, margins, `truncate`. Example: `<ChipInput icon={Search} className='min-w-0 flex-1' .../>` (`app/workspace/[workspaceId]/integrations/integrations.tsx:257`). NEVER re-specify canonical chrome — the component already applies it.
+
+### Form / chip-modal layout rhythm
+
+- **Field row** = `ChipModalField`: label↔control `gap-[9px]`, field gutter `px-2` (`px-0` when `flush`). Title = `Label` at `text-small` (13px), muted, normal weight; hint/error at `text-caption` (12px).
+- **Modal body** (`ChipModalBody`): `gap-4` between fields, padding `px-2 pt-4 pb-4.5`.
+- **Header/footer**: horizontal gutter `px-4` (header `pt-3`; footer `px-4 pt-2 pb-2`, tinted bar).
+- **Every body field MUST be a `ChipModalField`** — NEVER hand-roll a field row (raw `<div>` + hand-rolled `<p>`/`<label>` title + bare `ChipInput`/`ChipTextarea`). WHY: body `px-2` + field `px-2` = effective `px-4`, exactly matching the `px-4` header/footer. A hand-rolled row skips the field gutter, sits at `px-2`, and is visibly misaligned (this bug shipped in the scheduled-tasks "Create new scheduled task" modal). Inline errors go through the `error` prop, not a hand-rolled `<p>`.
+- **Uncovered controls** (`ChipCombobox`, `ChipSelect`, `DatePicker`, `TimePicker`, `ButtonGroup`, arbitrary JSX) → `ChipModalField type='custom'` with a `title`. It still applies the `px-2` gutter and renders the canonical `Label`, so it stays aligned. Never drop such a control into a raw `<div>`, and never add a body-level wrapper `<div>` with a custom `gap-*` that fights `gap-4`.
+- **Page section rhythm** (integrations/skills/settings): muted `text-small` label + `mt-[9px] mb-3 h-px bg-[var(--border)]` divider, sections stacked `gap-7`. Reuse `SettingsSection` (`app/workspace/[workspaceId]/settings/components/settings-section/settings-section.tsx`) rather than re-deriving it.
+
+When a standalone labeled field outside a `ChipModal` needs the same look (e.g. `SkillImport`), match the field rhythm by hand: `flex flex-col gap-[9px]`, muted label, `ChipInput`/`ChipTextarea` control, `text-caption` error below.

.cursor/rules/sim-testing.mdc

@@ -0,0 +1,257 @@
+---
+description: Testing patterns with Vitest and @sim/testing
+globs: ["apps/sim/**/*.test.ts", "apps/sim/**/*.test.tsx"]
+---
+
+
+# Testing Patterns
+
+Use Vitest. Test files: `feature.ts` → `feature.test.ts`
+
+## Global Mocks (vitest.setup.ts)
+
+These modules are mocked globally — do NOT re-mock them in test files unless you need to override behavior:
+
+- `@sim/db` → `databaseMock`
+- `@sim/db/schema` → `schemaMock`
+- `drizzle-orm` → `drizzleOrmMock`
+- `@sim/logger` → `loggerMock`
+- `@/lib/auth` → `authMock`
+- `@/lib/auth/hybrid` → `hybridAuthMock` (with default session-delegating behavior)
+- `@/lib/core/utils/request` → `requestUtilsMock`
+- `@/stores/console/store`, `@/stores/terminal`, `@/stores/execution/store`
+- `@/blocks/registry`
+- `@trigger.dev/sdk`
+- `@sim/platform-authz/workflow` → `workflowAuthzMock`
+
+## Structure
+
+```typescript
+/**
+ * @vitest-environment node
+ */
+import { createMockRequest } from '@sim/testing'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { mockGetSession } = vi.hoisted(() => ({
+  mockGetSession: vi.fn(),
+}))
+
+vi.mock('@/lib/auth', () => ({
+  auth: { api: { getSession: vi.fn() } },
+  getSession: mockGetSession,
+}))
+
+import { GET, POST } from '@/app/api/my-route/route'
+
+describe('my route', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockGetSession.mockResolvedValue({ user: { id: 'user-1' } })
+  })
+
+  it('returns data', async () => {
+    const req = createMockRequest('GET')
+    const res = await GET(req)
+    expect(res.status).toBe(200)
+  })
+})
+```
+
+## Performance Rules (Critical)
+
+### NEVER use `vi.resetModules()` + `vi.doMock()` + `await import()`
+
+This is the #1 cause of slow tests. It forces complete module re-evaluation per test.
+
+```typescript
+// BAD — forces module re-evaluation every test (~50-100ms each)
+beforeEach(() => {
+  vi.resetModules()
+  vi.doMock('@/lib/auth', () => ({ getSession: vi.fn() }))
+})
+it('test', async () => {
+  const { GET } = await import('./route')  // slow dynamic import
+})
+
+// GOOD — module loaded once, mocks reconfigured per test (~1ms each)
+const { mockGetSession } = vi.hoisted(() => ({
+  mockGetSession: vi.fn(),
+}))
+vi.mock('@/lib/auth', () => ({ getSession: mockGetSession }))
+import { GET } from '@/app/api/my-route/route'
+
+beforeEach(() => { vi.clearAllMocks() })
+it('test', () => {
+  mockGetSession.mockResolvedValue({ user: { id: '1' } })
+})
+```
+
+**Only exception:** Singleton modules that cache state at module scope (e.g., Redis clients, connection pools). These genuinely need `vi.resetModules()` + dynamic import to get a fresh instance per test.
+
+### NEVER use `vi.importActual()`
+
+This defeats the purpose of mocking by loading the real module and all its dependencies.
+
+```typescript
+// BAD — loads real module + all transitive deps
+vi.mock('@/lib/workspaces/utils', async () => {
+  const actual = await vi.importActual('@/lib/workspaces/utils')
+  return { ...actual, myFn: vi.fn() }
+})
+
+// GOOD — mock everything, only implement what tests need
+vi.mock('@/lib/workspaces/utils', () => ({
+  myFn: vi.fn(),
+  otherFn: vi.fn(),
+}))
+```
+
+### Mock heavy transitive dependencies
+
+If a module under test imports `@/blocks` (200+ files), `@/tools/registry`, or other heavy modules, mock them:
+
+```typescript
+vi.mock('@/blocks', () => ({
+  getBlock: () => null,
+  getAllBlocks: () => ({}),
+  getAllBlockTypes: () => [],
+  registry: {},
+}))
+```
+
+### Use `@vitest-environment node` unless DOM is needed
+
+Only use `@vitest-environment jsdom` if the test uses `window`, `document`, `FormData`, or other browser APIs. Node environment is significantly faster.
+
+### Avoid real timers in tests
+
+```typescript
+// BAD
+await new Promise(r => setTimeout(r, 500))
+
+// GOOD — use minimal delays or fake timers
+await new Promise(r => setTimeout(r, 1))
+// or
+vi.useFakeTimers()
+```
+
+## Centralized Mocks (prefer over local declarations)
+
+`@sim/testing` exports ready-to-use mock modules for common dependencies. Import and pass directly to `vi.mock()` — no `vi.hoisted()` boilerplate needed. Each paired `*MockFns` object exposes the underlying `vi.fn()`s for per-test overrides.
+
+| Module mocked | Import | Factory form |
+|---|---|---|
+| `@/app/api/auth/oauth/utils` | `authOAuthUtilsMock`, `authOAuthUtilsMockFns` | `vi.mock('@/app/api/auth/oauth/utils', () => authOAuthUtilsMock)` |
+| `@/app/api/knowledge/utils` | `knowledgeApiUtilsMock`, `knowledgeApiUtilsMockFns` | `vi.mock('@/app/api/knowledge/utils', () => knowledgeApiUtilsMock)` |
+| `@/app/api/workflows/utils` | `workflowsApiUtilsMock`, `workflowsApiUtilsMockFns` | `vi.mock('@/app/api/workflows/utils', () => workflowsApiUtilsMock)` |
+| `@sim/audit` | `auditMock`, `auditMockFns` | `vi.mock('@sim/audit', () => auditMock)` |
+| `@/lib/auth` | `authMock`, `authMockFns` | `vi.mock('@/lib/auth', () => authMock)` |
+| `@/lib/auth/hybrid` | `hybridAuthMock`, `hybridAuthMockFns` | `vi.mock('@/lib/auth/hybrid', () => hybridAuthMock)` |
+| `@/lib/copilot/request/http` | `copilotHttpMock`, `copilotHttpMockFns` | `vi.mock('@/lib/copilot/request/http', () => copilotHttpMock)` |
+| `@/lib/core/config/env` | `envMock`, `createEnvMock(overrides)` | `vi.mock('@/lib/core/config/env', () => envMock)` |
+| `@/lib/core/config/env-flags` | `featureFlagsMock` | `vi.mock('@/lib/core/config/env-flags', () => featureFlagsMock)` |
+| `@/lib/core/config/redis` | `redisConfigMock`, `redisConfigMockFns` | `vi.mock('@/lib/core/config/redis', () => redisConfigMock)` |
+| `@/lib/core/security/encryption` | `encryptionMock`, `encryptionMockFns` | `vi.mock('@/lib/core/security/encryption', () => encryptionMock)` |
+| `@/lib/core/security/input-validation.server` | `inputValidationMock`, `inputValidationMockFns` | `vi.mock('@/lib/core/security/input-validation.server', () => inputValidationMock)` |
+| `@/lib/core/utils/request` | `requestUtilsMock`, `requestUtilsMockFns` | `vi.mock('@/lib/core/utils/request', () => requestUtilsMock)` |
+| `@/lib/core/utils/urls` | `urlsMock`, `urlsMockFns` | `vi.mock('@/lib/core/utils/urls', () => urlsMock)` |
+| `@/lib/execution/preprocessing` | `executionPreprocessingMock`, `executionPreprocessingMockFns` | `vi.mock('@/lib/execution/preprocessing', () => executionPreprocessingMock)` |
+| `@/lib/logs/execution/logging-session` | `loggingSessionMock`, `loggingSessionMockFns`, `LoggingSessionMock` | `vi.mock('@/lib/logs/execution/logging-session', () => loggingSessionMock)` |
+| `@/lib/workflows/orchestration` | `workflowsOrchestrationMock`, `workflowsOrchestrationMockFns` | `vi.mock('@/lib/workflows/orchestration', () => workflowsOrchestrationMock)` |
+| `@/lib/workflows/persistence/utils` | `workflowsPersistenceUtilsMock`, `workflowsPersistenceUtilsMockFns` | `vi.mock('@/lib/workflows/persistence/utils', () => workflowsPersistenceUtilsMock)` |
+| `@/lib/workflows/utils` | `workflowsUtilsMock`, `workflowsUtilsMockFns` | `vi.mock('@/lib/workflows/utils', () => workflowsUtilsMock)` |
+| `@/lib/workspaces/permissions/utils` | `permissionsMock`, `permissionsMockFns` | `vi.mock('@/lib/workspaces/permissions/utils', () => permissionsMock)` |
+| `@sim/db/schema` | `schemaMock` | `vi.mock('@sim/db/schema', () => schemaMock)` |
+
+### Auth mocking (API routes)
+
+```typescript
+import { authMock, authMockFns } from '@sim/testing'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('@/lib/auth', () => authMock)
+
+import { GET } from '@/app/api/my-route/route'
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  authMockFns.mockGetSession.mockResolvedValue({ user: { id: 'user-1' } })
+})
+```
+
+Only define a local `vi.mock('@/lib/auth', ...)` if the module under test consumes exports outside the centralized shape (e.g., `auth.api.verifyOneTimeToken`, `auth.api.resetPassword`).
+
+### Hybrid auth mocking
+
+```typescript
+import { hybridAuthMock, hybridAuthMockFns } from '@sim/testing'
+
+vi.mock('@/lib/auth/hybrid', () => hybridAuthMock)
+
+// In tests:
+hybridAuthMockFns.mockCheckSessionOrInternalAuth.mockResolvedValue({
+  success: true, userId: 'user-1', authType: 'session',
+})
+```
+
+### Database chain mocking
+
+Use the centralized `dbChainMock` + `dbChainMockFns` helpers — no `vi.hoisted()` or chain-wiring boilerplate needed.
+
+```typescript
+import { dbChainMock, dbChainMockFns, resetDbChainMock } from '@sim/testing'
+
+vi.mock('@sim/db', () => dbChainMock)
+// Spread for custom exports: vi.mock('@sim/db', () => ({ ...dbChainMock, myTable: {...} }))
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  resetDbChainMock() // only needed if tests use permanent (non-`Once`) overrides
+})
+
+it('reads a row', async () => {
+  dbChainMockFns.limit.mockResolvedValueOnce([{ id: '1', name: 'test' }])
+  // exercise code that hits db.select().from().where().limit()
+  expect(dbChainMockFns.where).toHaveBeenCalled()
+})
+```
+
+**Default chains supported:**
+- `select()/selectDistinct()/selectDistinctOn() → from() → where()/innerJoin()/leftJoin() → where() → limit()/orderBy()/returning()/groupBy()/for()`
+- `insert() → values() → returning()/onConflictDoUpdate()/onConflictDoNothing()`
+- `update() → set() → where() → limit()/orderBy()/returning()/for()`
+- `delete() → where() → limit()/orderBy()/returning()/for()`
+- `db.execute()` resolves `[]`
+- `db.transaction(cb)` calls cb with `dbChainMock.db`
+
+`.for('update')` (Postgres row-level locking) is supported on `where` builders. It returns a thenable with `.limit` / `.orderBy` / `.returning` / `.groupBy` attached, so both `await .where().for('update')` (terminal) and `await .where().for('update').limit(1)` (chained) work. Override the terminal result with `dbChainMockFns.for.mockResolvedValueOnce([...])`; for the chained form, mock the downstream terminal (e.g. `dbChainMockFns.limit.mockResolvedValueOnce([...])`).
+
+All terminals default to `Promise.resolve([])`. Override per-test with `dbChainMockFns.<terminal>.mockResolvedValueOnce(...)`. Use `resetDbChainMock()` in `beforeEach` only when tests replace wiring with `.mockReturnValue` / `.mockResolvedValue` (permanent); tests using only `...Once` variants don't need it.
+
+## @sim/testing Package
+
+Always prefer over local test data.
+
+| Category | Utilities |
+|----------|-----------|
+| **Module mocks** | See "Centralized Mocks" table above |
+| **Logger helpers** | `loggerMock`, `createMockLogger()`, `getLoggerCalls()`, `clearLoggerMocks()` |
+| **Database helpers** | `databaseMock`, `drizzleOrmMock`, `createMockDb()`, `createMockSql()`, `createMockSqlOperators()` |
+| **Fetch helpers** | `setupGlobalFetchMock()`, `createMockFetch()`, `createMockResponse()`, `mockFetchError()` |
+| **Factories** | `createSession()`, `createWorkflowRecord()`, `createBlock()`, `createExecutionContext()` |
+| **Builders** | `WorkflowBuilder`, `ExecutionContextBuilder` |
+| **Assertions** | `expectWorkflowAccessGranted()`, `expectBlockExecuted()` |
+| **Requests** | `createMockRequest()`, `createMockFormDataRequest()` |
+
+## Rules Summary
+
+1. `@vitest-environment node` unless DOM is required
+2. Prefer centralized mocks from `@sim/testing` (see table above) over local `vi.hoisted()` + `vi.mock()` boilerplate
+3. `vi.hoisted()` + `vi.mock()` + static imports — never `vi.resetModules()` + `vi.doMock()` + dynamic imports
+4. `vi.mock()` calls before importing mocked modules
+5. `beforeEach(() => vi.clearAllMocks())` to reset state — no redundant `afterEach`
+6. No `vi.importActual()` — mock everything explicitly
+7. Mock heavy deps (`@/blocks`, `@/tools/registry`, `@/triggers`) in tests that don't need them
+8. Use absolute imports in test files
+9. Avoid real timers — use 1ms delays or `vi.useFakeTimers()`

.cursor/rules/sim-typescript.mdc

@@ -0,0 +1,20 @@
+---
+description: TypeScript conventions and type safety
+globs: ["apps/sim/**/*.ts", "apps/sim/**/*.tsx"]
+---
+
+# TypeScript Rules
+
+1. **No `any`** - Use proper types or `unknown` with type guards
+2. **Props interface** - Always define for components
+3. **Const assertions** - `as const` for constant objects/arrays
+4. **Ref types** - Explicit: `useRef<HTMLDivElement>(null)`
+5. **Type imports** - `import type { X }` for type-only imports
+
+```typescript
+// ✗ Bad
+const handleClick = (e: any) => {}
+
+// ✓ Good
+const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {}
+```