v0.6.52: data retention, docs updates, slack manifest generator, security hardening, contact page, 404 page, access control, SES, SNS

fix(settings): hide data-retention nav item when user lacks enterprise plan (#4256 )
fix(deps): bump drizzle-orm 0.45.2 + adopt MCP SDK 1.25.3 native types (#4252 )
2026-04-28 03:00:29 -04:00 · 2026-04-21 20:25:26 -07:00 · 2026-04-21 20:19:04 -07:00 · 2026-04-21 19:52:15 -07:00 · 2026-04-21 19:22:50 -07:00 · 2026-04-21 18:25:48 -07:00
5638 changed files with 1103271 additions and 138420 deletions
--- a/.agents/skills/add-block/SKILL.md
+++ b/.agents/skills/add-block/SKILL.md
@@ -0,0 +1,848 @@
+---
+name: add-block
+description: Create or update a Sim integration block with correct subBlocks, conditions, dependsOn, modes, canonicalParamId usage, outputs, and tool wiring. Use when working on `apps/sim/blocks/blocks/{service}.ts` or aligning a block with its tools.
+---
+
+# Add Block Skill
+
+You are an expert at creating block configurations for Sim. You understand the serializer, subBlock types, conditions, dependsOn, modes, and all UI patterns.
+
+## Your Task
+
+When the user asks you to create a block:
+1. Create the block file in `apps/sim/blocks/blocks/{service}.ts`
+2. Configure all subBlocks with proper types, conditions, and dependencies
+3. Wire up tools correctly
+
+## Hard Rule: No Guessed Tool Outputs
+
+Blocks depend on tool outputs. If the underlying tool response schema is not documented or live-verified, you MUST tell the user instead of guessing block outputs.
+
+- Do NOT invent block outputs for undocumented tool responses
+- Do NOT describe unknown JSON shapes as if they were confirmed
+- Do NOT wire fields into the block just because they seem likely to exist
+
+If the tool outputs are not known, do one of these instead:
+1. Ask the user for sample tool responses
+2. Ask the user for test credentials so the tool responses can be verified
+3. Limit the block to operations whose outputs are documented
+4. Leave uncertain outputs out and explicitly tell the user what remains unknown
+
+## Block Configuration Structure
+
+```typescript
+import { {ServiceName}Icon } from '@/components/icons'
+import type { BlockConfig } from '@/blocks/types'
+import { AuthMode, IntegrationType } from '@/blocks/types'
+import { getScopesForService } from '@/lib/oauth/utils'
+
+export const {ServiceName}Block: BlockConfig = {
+  type: '{service}',                    // snake_case identifier
+  name: '{Service Name}',               // Human readable
+  description: 'Brief description',     // One sentence
+  longDescription: 'Detailed description for docs',
+  docsLink: 'https://docs.sim.ai/tools/{service}',
+  category: 'tools',                    // 'tools' | 'blocks' | 'triggers'
+  integrationType: IntegrationType.X,   // Primary category (see IntegrationType enum)
+  tags: ['oauth', 'api'],              // Cross-cutting tags (see IntegrationTag type)
+  bgColor: '#HEXCOLOR',                 // Brand color
+  icon: {ServiceName}Icon,
+
+  // Auth mode
+  authMode: AuthMode.OAuth,             // or AuthMode.ApiKey
+
+  subBlocks: [
+    // Define all UI fields here
+  ],
+
+  tools: {
+    access: ['tool_id_1', 'tool_id_2'], // Array of tool IDs this block can use
+    config: {
+      tool: (params) => `{service}_${params.operation}`,  // Tool selector function
+      params: (params) => ({
+        // Transform subBlock values to tool params
+      }),
+    },
+  },
+
+  inputs: {
+    // Optional: define expected inputs from other blocks
+  },
+
+  outputs: {
+    // Define outputs available to downstream blocks
+  },
+}
+```
+
+## SubBlock Types Reference
+
+**Critical:** Every subblock `id` must be unique within the block. Duplicate IDs cause conflicts even with different conditions.
+
+### Text Inputs
+```typescript
+// Single-line input
+{ id: 'field', title: 'Label', type: 'short-input', placeholder: '...' }
+
+// Multi-line input
+{ id: 'field', title: 'Label', type: 'long-input', placeholder: '...', rows: 6 }
+
+// Password input
+{ id: 'apiKey', title: 'API Key', type: 'short-input', password: true }
+```
+
+### Selection Inputs
+```typescript
+// Dropdown (static options)
+{
+  id: 'operation',
+  title: 'Operation',
+  type: 'dropdown',
+  options: [
+    { label: 'Create', id: 'create' },
+    { label: 'Update', id: 'update' },
+  ],
+  value: () => 'create',  // Default value function
+}
+
+// Combobox (searchable dropdown)
+{
+  id: 'field',
+  title: 'Label',
+  type: 'combobox',
+  options: [...],
+  searchable: true,
+}
+```
+
+### Code/JSON Inputs
+```typescript
+{
+  id: 'code',
+  title: 'Code',
+  type: 'code',
+  language: 'javascript',  // 'javascript' | 'json' | 'python'
+  placeholder: '// Enter code...',
+}
+```
+
+### OAuth/Credentials
+```typescript
+{
+  id: 'credential',
+  title: 'Account',
+  type: 'oauth-input',
+  serviceId: '{service}',  // Must match OAuth provider service key
+  requiredScopes: getScopesForService('{service}'),  // Import from @/lib/oauth/utils
+  placeholder: 'Select account',
+  required: true,
+}
+```
+
+**Scopes:** Always use `getScopesForService(serviceId)` from `@/lib/oauth/utils` for `requiredScopes`. Never hardcode scope arrays — the single source of truth is `OAUTH_PROVIDERS` in `lib/oauth/oauth.ts`.
+
+**Scope descriptions:** When adding a new OAuth provider, also add human-readable descriptions for all scopes in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts`.
+
+### Selectors (with dynamic options)
+```typescript
+// Channel selector (Slack, Discord, etc.)
+{
+  id: 'channel',
+  title: 'Channel',
+  type: 'channel-selector',
+  serviceId: '{service}',
+  placeholder: 'Select channel',
+  dependsOn: ['credential'],
+}
+
+// Project selector (Jira, etc.)
+{
+  id: 'project',
+  title: 'Project',
+  type: 'project-selector',
+  serviceId: '{service}',
+  dependsOn: ['credential'],
+}
+
+// File selector (Google Drive, etc.)
+{
+  id: 'file',
+  title: 'File',
+  type: 'file-selector',
+  serviceId: '{service}',
+  mimeType: 'application/pdf',
+  dependsOn: ['credential'],
+}
+
+// User selector
+{
+  id: 'user',
+  title: 'User',
+  type: 'user-selector',
+  serviceId: '{service}',
+  dependsOn: ['credential'],
+}
+```
+
+### Other Types
+```typescript
+// Switch/toggle
+{ id: 'enabled', type: 'switch' }
+
+// Slider
+{ id: 'temperature', title: 'Temperature', type: 'slider', min: 0, max: 2, step: 0.1 }
+
+// Table (key-value pairs)
+{ id: 'headers', title: 'Headers', type: 'table', columns: ['Key', 'Value'] }
+
+// File upload
+{
+  id: 'files',
+  title: 'Attachments',
+  type: 'file-upload',
+  multiple: true,
+  acceptedTypes: 'image/*,application/pdf',
+}
+```
+
+## File Input Handling
+
+When your block accepts file uploads, use the basic/advanced mode pattern with `normalizeFileInput`.
+
+### Basic/Advanced File Pattern
+
+```typescript
+// Basic mode: Visual file upload
+{
+  id: 'uploadFile',
+  title: 'File',
+  type: 'file-upload',
+  canonicalParamId: 'file',  // Both map to 'file' param
+  placeholder: 'Upload file',
+  mode: 'basic',
+  multiple: false,
+  required: true,
+  condition: { field: 'operation', value: 'upload' },
+},
+// Advanced mode: Reference from other blocks
+{
+  id: 'fileRef',
+  title: 'File',
+  type: 'short-input',
+  canonicalParamId: 'file',  // Both map to 'file' param
+  placeholder: 'Reference file (e.g., {{file_block.output}})',
+  mode: 'advanced',
+  required: true,
+  condition: { field: 'operation', value: 'upload' },
+},
+```
+
+**Critical constraints:**
+- `canonicalParamId` must NOT match any subblock's `id` in the same block
+- Values are stored under subblock `id`, not `canonicalParamId`
+
+### Normalizing File Input in tools.config
+
+Use `normalizeFileInput` to handle all input variants:
+
+```typescript
+import { normalizeFileInput } from '@/blocks/utils'
+
+tools: {
+  access: ['service_upload'],
+  config: {
+    tool: (params) => {
+      // Check all field IDs: uploadFile (basic), fileRef (advanced), fileContent (legacy)
+      const normalizedFile = normalizeFileInput(
+        params.uploadFile || params.fileRef || params.fileContent,
+        { single: true }
+      )
+      if (normalizedFile) {
+        params.file = normalizedFile
+      }
+      return `service_${params.operation}`
+    },
+  },
+}
+```
+
+**Why this pattern?**
+- Values come through as `params.uploadFile` or `params.fileRef` (the subblock IDs)
+- `canonicalParamId` only controls UI/schema mapping, not runtime values
+- `normalizeFileInput` handles JSON strings from advanced mode template resolution
+
+### File Input Types in `inputs`
+
+Use `type: 'json'` for file inputs:
+
+```typescript
+inputs: {
+  uploadFile: { type: 'json', description: 'Uploaded file (UserFile)' },
+  fileRef: { type: 'json', description: 'File reference from previous block' },
+  // Legacy field for backwards compatibility
+  fileContent: { type: 'string', description: 'Legacy: base64 encoded content' },
+}
+```
+
+### Multiple Files
+
+For multiple file uploads:
+
+```typescript
+{
+  id: 'attachments',
+  title: 'Attachments',
+  type: 'file-upload',
+  multiple: true,  // Allow multiple files
+  maxSize: 25,     // Max size in MB per file
+  acceptedTypes: 'image/*,application/pdf,.doc,.docx',
+}
+
+// In tools.config:
+const normalizedFiles = normalizeFileInput(
+  params.attachments || params.attachmentRefs,
+  // No { single: true } - returns array
+)
+if (normalizedFiles) {
+  params.files = normalizedFiles
+}
+```
+
+## Condition Syntax
+
+Controls when a field is shown based on other field values.
+
+### Simple Condition
+```typescript
+condition: { field: 'operation', value: 'create' }
+// Shows when operation === 'create'
+```
+
+### Multiple Values (OR)
+```typescript
+condition: { field: 'operation', value: ['create', 'update'] }
+// Shows when operation is 'create' OR 'update'
+```
+
+### Negation
+```typescript
+condition: { field: 'operation', value: 'delete', not: true }
+// Shows when operation !== 'delete'
+```
+
+### Compound (AND)
+```typescript
+condition: {
+  field: 'operation',
+  value: 'send',
+  and: {
+    field: 'type',
+    value: 'dm',
+    not: true,
+  }
+}
+// Shows when operation === 'send' AND type !== 'dm'
+```
+
+### Complex Example
+```typescript
+condition: {
+  field: 'operation',
+  value: ['list', 'search'],
+  not: true,
+  and: {
+    field: 'authMethod',
+    value: 'oauth',
+  }
+}
+// Shows when operation NOT in ['list', 'search'] AND authMethod === 'oauth'
+```
+
+## DependsOn Pattern
+
+Controls when a field is enabled and when its options are refetched.
+
+### Simple Array (all must be set)
+```typescript
+dependsOn: ['credential']
+// Enabled only when credential has a value
+// Options refetch when credential changes
+
+dependsOn: ['credential', 'projectId']
+// Enabled only when BOTH have values
+```
+
+### Complex (all + any)
+```typescript
+dependsOn: {
+  all: ['authMethod'],           // All must be set
+  any: ['credential', 'apiKey']  // At least one must be set
+}
+// Enabled when authMethod is set AND (credential OR apiKey is set)
+```
+
+## Required Pattern
+
+Can be boolean or condition-based.
+
+### Simple Boolean
+```typescript
+required: true
+required: false
+```
+
+### Conditional Required
+```typescript
+required: { field: 'operation', value: 'create' }
+// Required only when operation === 'create'
+
+required: { field: 'operation', value: ['create', 'update'] }
+// Required when operation is 'create' OR 'update'
+```
+
+## Mode Pattern (Basic vs Advanced)
+
+Controls which UI view shows the field.
+
+### Mode Options
+- `'basic'` - Only in basic view (default UI)
+- `'advanced'` - Only in advanced view
+- `'both'` - Both views (default if not specified)
+- `'trigger'` - Only in trigger configuration
+
+### canonicalParamId Pattern
+
+Maps multiple UI fields to a single serialized parameter:
+
+```typescript
+// Basic mode: Visual selector
+{
+  id: 'channel',
+  title: 'Channel',
+  type: 'channel-selector',
+  mode: 'basic',
+  canonicalParamId: 'channel',  // Both map to 'channel' param
+  dependsOn: ['credential'],
+}
+
+// Advanced mode: Manual input
+{
+  id: 'channelId',
+  title: 'Channel ID',
+  type: 'short-input',
+  mode: 'advanced',
+  canonicalParamId: 'channel',  // Both map to 'channel' param
+  placeholder: 'Enter channel ID manually',
+}
+```
+
+**How it works:**
+- In basic mode: `channel` selector value → `params.channel`
+- In advanced mode: `channelId` input value → `params.channel`
+- The serializer consolidates based on current mode
+
+**Critical constraints:**
+- `canonicalParamId` must NOT match any other subblock's `id` in the same block (causes conflicts)
+- `canonicalParamId` must be unique per block (only one basic/advanced pair per canonicalParamId)
+- ONLY use `canonicalParamId` to link basic/advanced mode alternatives for the same logical parameter
+- Do NOT use it for any other purpose
+
+## WandConfig Pattern
+
+Enables AI-assisted field generation.
+
+```typescript
+{
+  id: 'query',
+  title: 'Query',
+  type: 'code',
+  language: 'json',
+  wandConfig: {
+    enabled: true,
+    prompt: 'Generate a query based on the user request. Return ONLY the JSON.',
+    placeholder: 'Describe what you want to query...',
+    generationType: 'json-object',  // Optional: affects AI behavior
+    maintainHistory: true,          // Optional: keeps conversation context
+  },
+}
+```
+
+### Generation Types
+- `'javascript-function-body'` - JS code generation
+- `'json-object'` - Raw JSON (adds "no markdown" instruction)
+- `'json-schema'` - JSON Schema definitions
+- `'sql-query'` - SQL statements
+- `'timestamp'` - Adds current date/time context
+
+## Tools Configuration
+
+**Important:** `tools.config.tool` runs during serialization before variable resolution. Put `Number()` and other type coercions in `tools.config.params` instead, which runs at execution time after variables are resolved.
+
+**Preferred:** Use tool names directly as dropdown option IDs to avoid switch cases:
+```typescript
+// Dropdown options use tool IDs directly
+options: [
+  { label: 'Create', id: 'service_create' },
+  { label: 'Read', id: 'service_read' },
+]
+
+// Tool selector just returns the operation value
+tool: (params) => params.operation,
+```
+
+### With Parameter Transformation
+```typescript
+tools: {
+  access: ['service_action'],
+  config: {
+    tool: (params) => 'service_action',
+    params: (params) => ({
+      id: params.resourceId,
+      data: typeof params.data === 'string' ? JSON.parse(params.data) : params.data,
+    }),
+  },
+}
+```
+
+### V2 Versioned Tool Selector
+```typescript
+import { createVersionedToolSelector } from '@/blocks/utils'
+
+tools: {
+  access: [
+    'service_create_v2',
+    'service_read_v2',
+    'service_update_v2',
+  ],
+  config: {
+    tool: createVersionedToolSelector({
+      baseToolSelector: (params) => `service_${params.operation}`,
+      suffix: '_v2',
+      fallbackToolId: 'service_create_v2',
+    }),
+  },
+}
+```
+
+## Outputs Definition
+
+**IMPORTANT:** Block outputs have a simpler schema than tool outputs. Block outputs do NOT support:
+- `optional: true` - This is only for tool outputs
+- `items` property - This is only for tool outputs with array types
+
+Block outputs only support:
+- `type` - The data type ('string', 'number', 'boolean', 'json', 'array')
+- `description` - Human readable description
+- Nested object structure (for complex types)
+
+```typescript
+outputs: {
+  // Simple outputs
+  id: { type: 'string', description: 'Resource ID' },
+  success: { type: 'boolean', description: 'Whether operation succeeded' },
+
+  // Use type: 'json' for complex objects or arrays (NOT type: 'array' with items)
+  items: { type: 'json', description: 'List of items' },
+  metadata: { type: 'json', description: 'Response metadata' },
+
+  // Nested outputs (for structured data)
+  user: {
+    id: { type: 'string', description: 'User ID' },
+    name: { type: 'string', description: 'User name' },
+    email: { type: 'string', description: 'User email' },
+  },
+}
+```
+
+### Typed JSON Outputs
+
+When using `type: 'json'` and you know the object shape in advance, **describe the inner fields in the description** so downstream blocks know what properties are available. For well-known, stable objects, use nested output definitions instead:
+
+```typescript
+outputs: {
+  // BAD: Opaque json with no info about what's inside
+  plan: { type: 'json', description: 'Zone plan information' },
+
+  // GOOD: Describe the known fields in the description
+  plan: {
+    type: 'json',
+    description: 'Zone plan information (id, name, price, currency, frequency, is_subscribed)',
+  },
+
+  // BEST: Use nested output definition when the shape is stable and well-known
+  plan: {
+    id: { type: 'string', description: 'Plan identifier' },
+    name: { type: 'string', description: 'Plan name' },
+    price: { type: 'number', description: 'Plan price' },
+    currency: { type: 'string', description: 'Price currency' },
+  },
+}
+```
+
+Use the nested pattern when:
+- The object has a small, stable set of fields (< 10)
+- Downstream blocks will commonly access specific properties
+- The API response shape is well-documented and unlikely to change
+
+Use `type: 'json'` with a descriptive string when:
+- The object has many fields or a dynamic shape
+- It represents a list/array of items
+- The shape varies by operation
+
+If the output shape is unknown because the underlying tool response is undocumented, you MUST tell the user and stop. Unknown is not the same as variable. Never guess block outputs.
+
+## V2 Block Pattern
+
+When creating V2 blocks (alongside legacy V1):
+
+```typescript
+// V1 Block - mark as legacy
+export const ServiceBlock: BlockConfig = {
+  type: 'service',
+  name: 'Service (Legacy)',
+  hideFromToolbar: true,  // Hide from toolbar
+  // ... rest of config
+}
+
+// V2 Block - visible, uses V2 tools
+export const ServiceV2Block: BlockConfig = {
+  type: 'service_v2',
+  name: 'Service',              // Clean name
+  hideFromToolbar: false,       // Visible
+  subBlocks: ServiceBlock.subBlocks,  // Reuse UI
+  tools: {
+    access: ServiceBlock.tools?.access?.map(id => `${id}_v2`) || [],
+    config: {
+      tool: createVersionedToolSelector({
+        baseToolSelector: (params) => (ServiceBlock.tools?.config as any)?.tool(params),
+        suffix: '_v2',
+        fallbackToolId: 'service_default_v2',
+      }),
+      params: ServiceBlock.tools?.config?.params,
+    },
+  },
+  outputs: {
+    // Flat, API-aligned outputs (not wrapped in content/metadata)
+  },
+}
+```
+
+## Registering Blocks
+
+After creating the block, remind the user to:
+1. Import in `apps/sim/blocks/registry.ts`
+2. Add to the `registry` object (alphabetically):
+
+```typescript
+import { ServiceBlock } from '@/blocks/blocks/service'
+
+export const registry: Record<string, BlockConfig> = {
+  // ... existing blocks ...
+  service: ServiceBlock,
+}
+```
+
+## Complete Example
+
+```typescript
+import { ServiceIcon } from '@/components/icons'
+import type { BlockConfig } from '@/blocks/types'
+import { AuthMode, IntegrationType } from '@/blocks/types'
+import { getScopesForService } from '@/lib/oauth/utils'
+
+export const ServiceBlock: BlockConfig = {
+  type: 'service',
+  name: 'Service',
+  description: 'Integrate with Service API',
+  longDescription: 'Full description for documentation...',
+  docsLink: 'https://docs.sim.ai/tools/service',
+  category: 'tools',
+  integrationType: IntegrationType.DeveloperTools,
+  tags: ['oauth', 'api'],
+  bgColor: '#FF6B6B',
+  icon: ServiceIcon,
+  authMode: AuthMode.OAuth,
+
+  subBlocks: [
+    {
+      id: 'operation',
+      title: 'Operation',
+      type: 'dropdown',
+      options: [
+        { label: 'Create', id: 'create' },
+        { label: 'Read', id: 'read' },
+        { label: 'Update', id: 'update' },
+        { label: 'Delete', id: 'delete' },
+      ],
+      value: () => 'create',
+    },
+    {
+      id: 'credential',
+      title: 'Service Account',
+      type: 'oauth-input',
+      serviceId: 'service',
+      requiredScopes: getScopesForService('service'),
+      placeholder: 'Select account',
+      required: true,
+    },
+    {
+      id: 'resourceId',
+      title: 'Resource ID',
+      type: 'short-input',
+      placeholder: 'Enter resource ID',
+      condition: { field: 'operation', value: ['read', 'update', 'delete'] },
+      required: { field: 'operation', value: ['read', 'update', 'delete'] },
+    },
+    {
+      id: 'name',
+      title: 'Name',
+      type: 'short-input',
+      placeholder: 'Resource name',
+      condition: { field: 'operation', value: ['create', 'update'] },
+      required: { field: 'operation', value: 'create' },
+    },
+  ],
+
+  tools: {
+    access: ['service_create', 'service_read', 'service_update', 'service_delete'],
+    config: {
+      tool: (params) => `service_${params.operation}`,
+    },
+  },
+
+  outputs: {
+    id: { type: 'string', description: 'Resource ID' },
+    name: { type: 'string', description: 'Resource name' },
+    createdAt: { type: 'string', description: 'Creation timestamp' },
+  },
+}
+```
+
+## Connecting Blocks with Triggers
+
+If the service supports webhooks, connect the block to its triggers.
+
+```typescript
+import { getTrigger } from '@/triggers'
+
+export const ServiceBlock: BlockConfig = {
+  // ... basic config ...
+
+  triggers: {
+    enabled: true,
+    available: ['service_event_a', 'service_event_b', 'service_webhook'],
+  },
+
+  subBlocks: [
+    // Tool subBlocks first...
+    { id: 'operation', /* ... */ },
+
+    // Then spread trigger subBlocks
+    ...getTrigger('service_event_a').subBlocks,
+    ...getTrigger('service_event_b').subBlocks,
+    ...getTrigger('service_webhook').subBlocks,
+  ],
+}
+```
+
+See the `/add-trigger` skill for creating triggers.
+
+## Icon Requirement
+
+If the icon doesn't already exist in `@/components/icons.tsx`, **do NOT search for it yourself**. After completing the block, ask the user to provide the SVG:
+
+```
+The block is complete, but I need an icon for {Service}.
+Please provide the SVG and I'll convert it to a React component.
+
+You can usually find this in the service's brand/press kit page, or copy it from their website.
+```
+
+## Advanced Mode for Optional Fields
+
+Optional fields that are rarely used should be set to `mode: 'advanced'` so they don't clutter the basic UI. This includes:
+- Pagination tokens
+- Time range filters (start/end time)
+- Sort order options
+- Reply settings
+- Rarely used IDs (e.g., reply-to tweet ID, quote tweet ID)
+- Max results / limits
+
+```typescript
+{
+  id: 'startTime',
+  title: 'Start Time',
+  type: 'short-input',
+  placeholder: 'ISO 8601 timestamp',
+  condition: { field: 'operation', value: ['search', 'list'] },
+  mode: 'advanced',  // Rarely used, hide from basic view
+}
+```
+
+## WandConfig for Complex Inputs
+
+Use `wandConfig` for fields that are hard to fill out manually, such as timestamps, comma-separated lists, and complex query strings. This gives users an AI-assisted input experience.
+
+```typescript
+// Timestamps - use generationType: 'timestamp' to inject current date context
+{
+  id: 'startTime',
+  title: 'Start Time',
+  type: 'short-input',
+  mode: 'advanced',
+  wandConfig: {
+    enabled: true,
+    prompt: 'Generate an ISO 8601 timestamp based on the user description. Return ONLY the timestamp string.',
+    generationType: 'timestamp',
+  },
+}
+
+// Comma-separated lists - simple prompt without generationType
+{
+  id: 'mediaIds',
+  title: 'Media IDs',
+  type: 'short-input',
+  mode: 'advanced',
+  wandConfig: {
+    enabled: true,
+    prompt: 'Generate a comma-separated list of media IDs. Return ONLY the comma-separated values.',
+  },
+}
+```
+
+## Naming Convention
+
+All tool IDs referenced in `tools.access` and returned by `tools.config.tool` MUST use `snake_case` (e.g., `x_create_tweet`, `slack_send_message`). Never use camelCase or PascalCase.
+
+## Checklist Before Finishing
+
+- [ ] `integrationType` is set to the correct `IntegrationType` enum value
+- [ ] `tags` array includes all applicable `IntegrationTag` values
+- [ ] All subBlocks have `id`, `title` (except switch), and `type`
+- [ ] Conditions use correct syntax (field, value, not, and)
+- [ ] DependsOn set for fields that need other values
+- [ ] Required fields marked correctly (boolean or condition)
+- [ ] OAuth inputs have correct `serviceId` and `requiredScopes: getScopesForService(serviceId)`
+- [ ] Scope descriptions added to `SCOPE_DESCRIPTIONS` in `lib/oauth/utils.ts` for any new scopes
+- [ ] Tools.access lists all tool IDs (snake_case)
+- [ ] Tools.config.tool returns correct tool ID (snake_case)
+- [ ] Outputs match tool outputs
+- [ ] Block registered in registry.ts
+- [ ] If icon missing: asked user to provide SVG
+- [ ] If triggers exist: `triggers` config set, trigger subBlocks spread
+- [ ] Optional/rarely-used fields set to `mode: 'advanced'`
+- [ ] Timestamps and complex inputs have `wandConfig` enabled
+
+## Final Validation (Required)
+
+After creating the block, you MUST validate it against every tool it references:
+
+1. **Read every tool definition** that appears in `tools.access` — do not skip any
+2. **For each tool, verify the block has correct:**
+   - SubBlock inputs that cover all required tool params (with correct `condition` to show for that operation)
+   - SubBlock input types that match the tool param types (e.g., dropdown for enums, short-input for strings)
+   - `tools.config.params` correctly maps subBlock IDs to tool param names (if they differ)
+   - Type coercions in `tools.config.params` for any params that need conversion (Number(), Boolean(), JSON.parse())
+3. **Verify block outputs** cover the key fields returned by all tools
+4. **Verify conditions** — each subBlock should only show for the operations that actually use it
+5. **If any tool outputs are still unknown**, explicitly tell the user instead of guessing block outputs
--- a/.agents/skills/add-block/agents/openai.yaml
+++ b/.agents/skills/add-block/agents/openai.yaml
@@ -0,0 +1,5 @@
+interface:
+  display_name: "Add Block"
+  short_description: "Build a Sim block definition"
+  brand_color: "#2563EB"
+  default_prompt: "Use $add-block to create or update the block for a Sim integration."
--- a/.agents/skills/add-connector/SKILL.md
+++ b/.agents/skills/add-connector/SKILL.md
@@ -0,0 +1,545 @@
+---
+name: add-connector
+description: Add or update a Sim knowledge base connector for syncing documents from an external source, including auth mode, config fields, pagination, document mapping, tags, and registry wiring. Use when working in `apps/sim/connectors/{service}/` or adding a new external document source.
+---
+
+# Add Connector Skill
+
+You are an expert at adding knowledge base connectors to Sim. A connector syncs documents from an external source (Confluence, Google Drive, Notion, etc.) into a knowledge base.
+
+## Your Task
+
+When the user asks you to create a connector:
+1. Use Context7 or WebFetch to read the service's API documentation
+2. Determine the auth mode: **OAuth** (if Sim already has an OAuth provider for the service) or **API key** (if the service uses API key / Bearer token auth)
+3. Create the connector directory and config
+4. Register it in the connector registry
+
+## Hard Rule: No Guessed Response Or Document Schemas
+
+If the service docs do not clearly show the document list response, document fetch response, pagination shape, or metadata fields, you MUST tell the user instead of guessing.
+
+- Do NOT invent document fields
+- Do NOT guess pagination cursors or next-page fields
+- Do NOT infer metadata/tag mappings from unrelated endpoints
+- Do NOT fabricate `ExternalDocument` content structure from partial docs
+
+If the source schema is unknown, do one of these instead:
+1. Ask the user for sample API responses
+2. Ask the user for test credentials so you can verify live payloads
+3. Implement only the documented parts of the connector
+4. Leave the connector incomplete and explicitly say which fields remain unknown
+
+## Directory Structure
+
+Create files in `apps/sim/connectors/{service}/`:
+```
+connectors/{service}/
+├── index.ts          # Barrel export
+└── {service}.ts      # ConnectorConfig definition
+```
+
+## Authentication
+
+Connectors use a discriminated union for auth config (`ConnectorAuthConfig` in `connectors/types.ts`):
+
+```typescript
+type ConnectorAuthConfig =
+  | { mode: 'oauth'; provider: OAuthService; requiredScopes?: string[] }
+  | { mode: 'apiKey'; label?: string; placeholder?: string }
+```
+
+### OAuth mode
+For services with existing OAuth providers in `apps/sim/lib/oauth/types.ts`. The `provider` must match an `OAuthService`. The modal shows a credential picker and handles token refresh automatically.
+
+### API key mode
+For services that use API key / Bearer token auth. The modal shows a password input with the configured `label` and `placeholder`. The API key is encrypted at rest using AES-256-GCM and stored in a dedicated `encryptedApiKey` column on the connector record. The sync engine decrypts it automatically — connectors receive the raw access token in `listDocuments`, `getDocument`, and `validateConfig`.
+
+## ConnectorConfig Structure
+
+### OAuth connector example
+
+```typescript
+import { createLogger } from '@sim/logger'
+import { {Service}Icon } from '@/components/icons'
+import { fetchWithRetry } from '@/lib/knowledge/documents/utils'
+import type { ConnectorConfig, ExternalDocument, ExternalDocumentList } from '@/connectors/types'
+
+const logger = createLogger('{Service}Connector')
+
+export const {service}Connector: ConnectorConfig = {
+  id: '{service}',
+  name: '{Service}',
+  description: 'Sync documents from {Service} into your knowledge base',
+  version: '1.0.0',
+  icon: {Service}Icon,
+
+  auth: {
+    mode: 'oauth',
+    provider: '{service}',          // Must match OAuthService in lib/oauth/types.ts
+    requiredScopes: ['read:...'],
+  },
+
+  configFields: [
+    // Rendered dynamically by the add-connector modal UI
+    // Supports 'short-input' and 'dropdown' types
+  ],
+
+  listDocuments: async (accessToken, sourceConfig, cursor) => {
+    // Return metadata stubs with contentDeferred: true (if per-doc content fetch needed)
+    // Or full documents with content (if list API returns content inline)
+    // Return { documents: ExternalDocument[], nextCursor?, hasMore }
+  },
+
+  getDocument: async (accessToken, sourceConfig, externalId) => {
+    // Fetch full content for a single document
+    // Return ExternalDocument with contentDeferred: false, or null
+  },
+
+  validateConfig: async (accessToken, sourceConfig) => {
+    // Return { valid: true } or { valid: false, error: 'message' }
+  },
+
+  // Optional: map source metadata to semantic tag keys (translated to slots by sync engine)
+  mapTags: (metadata) => {
+    // Return Record<string, unknown> with keys matching tagDefinitions[].id
+  },
+}
+```
+
+Only map fields in `listDocuments`, `getDocument`, `validateConfig`, and `mapTags` when the source payload shape is documented or live-verified. If not, tell the user and stop rather than guessing.
+
+### API key connector example
+
+```typescript
+export const {service}Connector: ConnectorConfig = {
+  id: '{service}',
+  name: '{Service}',
+  description: 'Sync documents from {Service} into your knowledge base',
+  version: '1.0.0',
+  icon: {Service}Icon,
+
+  auth: {
+    mode: 'apiKey',
+    label: 'API Key',                       // Shown above the input field
+    placeholder: 'Enter your {Service} API key',  // Input placeholder
+  },
+
+  configFields: [ /* ... */ ],
+  listDocuments: async (accessToken, sourceConfig, cursor) => { /* ... */ },
+  getDocument: async (accessToken, sourceConfig, externalId) => { /* ... */ },
+  validateConfig: async (accessToken, sourceConfig) => { /* ... */ },
+}
+```
+
+## ConfigField Types
+
+The add-connector modal renders these automatically — no custom UI needed.
+
+Three field types are supported: `short-input`, `dropdown`, and `selector`.
+
+```typescript
+// Text input
+{
+  id: 'domain',
+  title: 'Domain',
+  type: 'short-input',
+  placeholder: 'yoursite.example.com',
+  required: true,
+}
+
+// Dropdown (static options)
+{
+  id: 'contentType',
+  title: 'Content Type',
+  type: 'dropdown',
+  required: false,
+  options: [
+    { label: 'Pages only', id: 'page' },
+    { label: 'Blog posts only', id: 'blogpost' },
+    { label: 'All content', id: 'all' },
+  ],
+}
+```
+
+## Dynamic Selectors (Canonical Pairs)
+
+Use `type: 'selector'` to fetch options dynamically from the existing selector registry (`hooks/selectors/registry.ts`). Selectors are always paired with a manual fallback input using the **canonical pair** pattern — a `selector` field (basic mode) and a `short-input` field (advanced mode) linked by `canonicalParamId`.
+
+The user sees a toggle button (ArrowLeftRight) to switch between the selector dropdown and manual text input. On submit, the modal resolves each canonical pair to the active mode's value, keyed by `canonicalParamId`.
+
+### Rules
+
+1. **Every selector field MUST have a canonical pair** — a corresponding `short-input` (or `dropdown`) field with the same `canonicalParamId` and `mode: 'advanced'`.
+2. **`required` must be set identically on both fields** in a pair. If the selector is required, the manual input must also be required.
+3. **`canonicalParamId` must match the key the connector expects in `sourceConfig`** (e.g. `baseId`, `channel`, `teamId`). The advanced field's `id` should typically match `canonicalParamId`.
+4. **`dependsOn` references the selector field's `id`**, not the `canonicalParamId`. The modal propagates dependency clearing across canonical siblings automatically — changing either field in a parent pair clears dependent children.
+
+### Selector canonical pair example (Airtable base → table cascade)
+
+```typescript
+configFields: [
+  // Base: selector (basic) + manual (advanced)
+  {
+    id: 'baseSelector',
+    title: 'Base',
+    type: 'selector',
+    selectorKey: 'airtable.bases',     // Must exist in hooks/selectors/registry.ts
+    canonicalParamId: 'baseId',
+    mode: 'basic',
+    placeholder: 'Select a base',
+    required: true,
+  },
+  {
+    id: 'baseId',
+    title: 'Base ID',
+    type: 'short-input',
+    canonicalParamId: 'baseId',
+    mode: 'advanced',
+    placeholder: 'e.g. appXXXXXXXXXXXXXX',
+    required: true,
+  },
+  // Table: selector depends on base (basic) + manual (advanced)
+  {
+    id: 'tableSelector',
+    title: 'Table',
+    type: 'selector',
+    selectorKey: 'airtable.tables',
+    canonicalParamId: 'tableIdOrName',
+    mode: 'basic',
+    dependsOn: ['baseSelector'],       // References the selector field ID
+    placeholder: 'Select a table',
+    required: true,
+  },
+  {
+    id: 'tableIdOrName',
+    title: 'Table Name or ID',
+    type: 'short-input',
+    canonicalParamId: 'tableIdOrName',
+    mode: 'advanced',
+    placeholder: 'e.g. Tasks',
+    required: true,
+  },
+  // Non-selector fields stay as-is
+  { id: 'maxRecords', title: 'Max Records', type: 'short-input', ... },
+]
+```
+
+### Selector with domain dependency (Jira/Confluence pattern)
+
+When a selector depends on a plain `short-input` field (no canonical pair), `dependsOn` references that field's `id` directly. The `domain` field's value maps to `SelectorContext.domain` automatically via `SELECTOR_CONTEXT_FIELDS`.
+
+```typescript
+configFields: [
+  {
+    id: 'domain',
+    title: 'Jira Domain',
+    type: 'short-input',
+    placeholder: 'yoursite.atlassian.net',
+    required: true,
+  },
+  {
+    id: 'projectSelector',
+    title: 'Project',
+    type: 'selector',
+    selectorKey: 'jira.projects',
+    canonicalParamId: 'projectKey',
+    mode: 'basic',
+    dependsOn: ['domain'],
+    placeholder: 'Select a project',
+    required: true,
+  },
+  {
+    id: 'projectKey',
+    title: 'Project Key',
+    type: 'short-input',
+    canonicalParamId: 'projectKey',
+    mode: 'advanced',
+    placeholder: 'e.g. ENG, PROJ',
+    required: true,
+  },
+]
+```
+
+### How `dependsOn` maps to `SelectorContext`
+
+The connector selector field builds a `SelectorContext` from dependency values. For the mapping to work, each dependency's `canonicalParamId` (or field `id` for non-canonical fields) must exist in `SELECTOR_CONTEXT_FIELDS` (`lib/workflows/subblocks/context.ts`):
+
+```
+oauthCredential, domain, teamId, projectId, knowledgeBaseId, planId,
+siteId, collectionId, spreadsheetId, fileId, baseId, datasetId, serviceDeskId
+```
+
+### Available selector keys
+
+Check `hooks/selectors/types.ts` for the full `SelectorKey` union. Common ones for connectors:
+
+| SelectorKey | Context Deps | Returns |
+|-------------|-------------|---------|
+| `airtable.bases` | credential | Base ID + name |
+| `airtable.tables` | credential, `baseId` | Table ID + name |
+| `slack.channels` | credential | Channel ID + name |
+| `gmail.labels` | credential | Label ID + name |
+| `google.calendar` | credential | Calendar ID + name |
+| `linear.teams` | credential | Team ID + name |
+| `linear.projects` | credential, `teamId` | Project ID + name |
+| `jira.projects` | credential, `domain` | Project key + name |
+| `confluence.spaces` | credential, `domain` | Space key + name |
+| `notion.databases` | credential | Database ID + name |
+| `asana.workspaces` | credential | Workspace GID + name |
+| `microsoft.teams` | credential | Team ID + name |
+| `microsoft.channels` | credential, `teamId` | Channel ID + name |
+| `webflow.sites` | credential | Site ID + name |
+| `outlook.folders` | credential | Folder ID + name |
+
+## ExternalDocument Shape
+
+Every document returned from `listDocuments`/`getDocument` must include:
+
+```typescript
+{
+  externalId: string          // Source-specific unique ID
+  title: string               // Document title
+  content: string             // Extracted plain text (or '' if contentDeferred)
+  contentDeferred?: boolean   // true = content will be fetched via getDocument
+  mimeType: 'text/plain'     // Always text/plain (content is extracted)
+  contentHash: string         // Metadata-based hash for change detection
+  sourceUrl?: string          // Link back to original (stored on document record)
+  metadata?: Record<string, unknown>  // Source-specific data (fed to mapTags)
+}
+```
+
+## Content Deferral (Required for file/content-download connectors)
+
+**All connectors that require per-document API calls to fetch content MUST use `contentDeferred: true`.** This is the standard pattern — `listDocuments` returns lightweight metadata stubs, and content is fetched lazily by the sync engine via `getDocument` only for new/changed documents.
+
+This pattern is critical for reliability: the sync engine processes documents in batches and enqueues each batch for processing immediately. If a sync times out, all previously-batched documents are already queued. Without deferral, content downloads during listing can exhaust the sync task's time budget before any documents are saved.
+
+### When to use `contentDeferred: true`
+
+- The service's list API does NOT return document content (only metadata)
+- Content requires a separate download/export API call per document
+- Examples: Google Drive, OneDrive, SharePoint, Dropbox, Notion, Confluence, Gmail, Obsidian, Evernote, GitHub
+
+### When NOT to use `contentDeferred`
+
+- The list API already returns the full content inline (e.g., Slack messages, Reddit posts, HubSpot notes)
+- No per-document API call is needed to get content
+
+### Content Hash Strategy
+
+Use a **metadata-based** `contentHash` — never a content-based hash. The hash must be derivable from the list response metadata alone, so the sync engine can detect changes without downloading content.
+
+Good metadata hash sources:
+- `modifiedTime` / `lastModifiedDateTime` — changes when file is edited
+- Git blob SHA — unique per content version
+- API-provided content hash (e.g., Dropbox `content_hash`)
+- Version number (e.g., Confluence page version)
+
+Format: `{service}:{id}:{changeIndicator}`
+
+```typescript
+// Google Drive: modifiedTime changes on edit
+contentHash: `gdrive:${file.id}:${file.modifiedTime ?? ''}`
+
+// GitHub: blob SHA is a content-addressable hash
+contentHash: `gitsha:${item.sha}`
+
+// Dropbox: API provides content_hash
+contentHash: `dropbox:${entry.id}:${entry.content_hash ?? entry.server_modified}`
+
+// Confluence: version number increments on edit
+contentHash: `confluence:${page.id}:${page.version.number}`
+```
+
+**Critical invariant:** The `contentHash` MUST be identical whether produced by `listDocuments` (stub) or `getDocument` (full doc). Both should use the same stub function to guarantee this.
+
+### Implementation Pattern
+
+```typescript
+// 1. Create a stub function (sync, no API calls)
+function fileToStub(file: ServiceFile): ExternalDocument {
+  return {
+    externalId: file.id,
+    title: file.name || 'Untitled',
+    content: '',
+    contentDeferred: true,
+    mimeType: 'text/plain',
+    sourceUrl: `https://service.com/file/${file.id}`,
+    contentHash: `service:${file.id}:${file.modifiedTime ?? ''}`,
+    metadata: { /* fields needed by mapTags */ },
+  }
+}
+
+// 2. listDocuments returns stubs (fast, metadata only)
+listDocuments: async (accessToken, sourceConfig, cursor) => {
+  const response = await fetchWithRetry(listUrl, { ... })
+  const files = (await response.json()).files
+  const documents = files.map(fileToStub)
+  return { documents, nextCursor, hasMore }
+}
+
+// 3. getDocument fetches content and returns full doc with SAME contentHash
+getDocument: async (accessToken, sourceConfig, externalId) => {
+  const metadata = await fetchWithRetry(metadataUrl, { ... })
+  const file = await metadata.json()
+  if (file.trashed) return null
+
+  try {
+    const content = await fetchContent(accessToken, file)
+    if (!content.trim()) return null
+    const stub = fileToStub(file)
+    return { ...stub, content, contentDeferred: false }
+  } catch (error) {
+    logger.warn(`Failed to fetch content for: ${file.name}`, { error })
+    return null
+  }
+}
+```
+
+### Reference Implementations
+
+- **Google Drive**: `connectors/google-drive/google-drive.ts` — file download/export with `modifiedTime` hash
+- **GitHub**: `connectors/github/github.ts` — git blob SHA hash
+- **Notion**: `connectors/notion/notion.ts` — blocks API with `last_edited_time` hash
+- **Confluence**: `connectors/confluence/confluence.ts` — version number hash
+
+## tagDefinitions — Declared Tag Definitions
+
+Declare which tags the connector populates using semantic IDs. Shown in the add-connector modal as opt-out checkboxes.
+On connector creation, slots are **dynamically assigned** via `getNextAvailableSlot` — connectors never hardcode slot names.
+
+```typescript
+tagDefinitions: [
+  { id: 'labels', displayName: 'Labels', fieldType: 'text' },
+  { id: 'version', displayName: 'Version', fieldType: 'number' },
+  { id: 'lastModified', displayName: 'Last Modified', fieldType: 'date' },
+],
+```
+
+Each entry has:
+- `id`: Semantic key matching a key returned by `mapTags` (e.g. `'labels'`, `'version'`)
+- `displayName`: Human-readable name shown in the UI (e.g. "Labels", "Last Modified")
+- `fieldType`: `'text'` | `'number'` | `'date'` | `'boolean'` — determines which slot pool to draw from
+
+Users can opt out of specific tags in the modal. Disabled IDs are stored in `sourceConfig.disabledTagIds`.
+The assigned mapping (`semantic id → slot`) is stored in `sourceConfig.tagSlotMapping`.
+
+## mapTags — Metadata to Semantic Keys
+
+Maps source metadata to semantic tag keys. Required if `tagDefinitions` is set.
+The sync engine calls this automatically and translates semantic keys to actual DB slots
+using the `tagSlotMapping` stored on the connector.
+
+Return keys must match the `id` values declared in `tagDefinitions`.
+
+```typescript
+mapTags: (metadata: Record<string, unknown>): Record<string, unknown> => {
+  const result: Record<string, unknown> = {}
+
+  // Validate arrays before casting — metadata may be malformed
+  const labels = Array.isArray(metadata.labels) ? (metadata.labels as string[]) : []
+  if (labels.length > 0) result.labels = labels.join(', ')
+
+  // Validate numbers — guard against NaN
+  if (metadata.version != null) {
+    const num = Number(metadata.version)
+    if (!Number.isNaN(num)) result.version = num
+  }
+
+  // Validate dates — guard against Invalid Date
+  if (typeof metadata.lastModified === 'string') {
+    const date = new Date(metadata.lastModified)
+    if (!Number.isNaN(date.getTime())) result.lastModified = date
+  }
+
+  return result
+}
+```
+
+## External API Calls — Use `fetchWithRetry`
+
+All external API calls must use `fetchWithRetry` from `@/lib/knowledge/documents/utils` instead of raw `fetch()`. This provides exponential backoff with retries on 429/502/503/504 errors. It returns a standard `Response` — all `.ok`, `.json()`, `.text()` checks work unchanged.
+
+For `validateConfig` (user-facing, called on save), pass `VALIDATE_RETRY_OPTIONS` to cap wait time at ~7s. Background operations (`listDocuments`, `getDocument`) use the built-in defaults (5 retries, ~31s max).
+
+```typescript
+import { VALIDATE_RETRY_OPTIONS, fetchWithRetry } from '@/lib/knowledge/documents/utils'
+
+// Background sync — use defaults
+const response = await fetchWithRetry(url, {
+  method: 'GET',
+  headers: { Authorization: `Bearer ${accessToken}` },
+})
+
+// validateConfig — tighter retry budget
+const response = await fetchWithRetry(url, { ... }, VALIDATE_RETRY_OPTIONS)
+```
+
+## sourceUrl
+
+If `ExternalDocument.sourceUrl` is set, the sync engine stores it on the document record. Always construct the full URL (not a relative path).
+
+## Sync Engine Behavior (Do Not Modify)
+
+The sync engine (`lib/knowledge/connectors/sync-engine.ts`) is connector-agnostic. It:
+1. Calls `listDocuments` with pagination until `hasMore` is false
+2. Compares `contentHash` to detect new/changed/unchanged documents
+3. Stores `sourceUrl` and calls `mapTags` on insert/update automatically
+4. Handles soft-delete of removed documents
+5. Resolves access tokens automatically — OAuth tokens are refreshed, API keys are decrypted from the `encryptedApiKey` column
+
+You never need to modify the sync engine when adding a connector.
+
+## Icon
+
+The `icon` field on `ConnectorConfig` is used throughout the UI — in the connector list, the add-connector modal, and as the document icon in the knowledge base table (replacing the generic file type icon for connector-sourced documents). The icon is read from `CONNECTOR_REGISTRY[connectorType].icon` at runtime — no separate icon map to maintain.
+
+If the service already has an icon in `apps/sim/components/icons.tsx` (from a tool integration), reuse it. Otherwise, ask the user to provide the SVG.
+
+## Registering
+
+Add one line to `apps/sim/connectors/registry.ts`:
+
+```typescript
+import { {service}Connector } from '@/connectors/{service}'
+
+export const CONNECTOR_REGISTRY: ConnectorRegistry = {
+  // ... existing connectors ...
+  {service}: {service}Connector,
+}
+```
+
+## Reference Implementations
+
+- **OAuth + contentDeferred**: `apps/sim/connectors/google-drive/google-drive.ts` — file download with metadata-based hash, `orderBy` for deterministic pagination
+- **OAuth + contentDeferred (blocks API)**: `apps/sim/connectors/notion/notion.ts` — complex block content extraction deferred to `getDocument`
+- **OAuth + contentDeferred (git)**: `apps/sim/connectors/github/github.ts` — blob SHA hash, tree listing
+- **OAuth + inline content**: `apps/sim/connectors/confluence/confluence.ts` — multiple config field types, `mapTags`, label fetching
+- **API key**: `apps/sim/connectors/fireflies/fireflies.ts` — GraphQL API with Bearer token auth
+
+## Checklist
+
+- [ ] Created `connectors/{service}/{service}.ts` with full ConnectorConfig
+- [ ] Created `connectors/{service}/index.ts` barrel export
+- [ ] **Auth configured correctly:**
+  - OAuth: `auth.provider` matches an existing `OAuthService` in `lib/oauth/types.ts`
+  - API key: `auth.label` and `auth.placeholder` set appropriately
+- [ ] **Selector fields configured correctly (if applicable):**
+  - Every `type: 'selector'` field has a canonical pair (`short-input` or `dropdown` with same `canonicalParamId` and `mode: 'advanced'`)
+  - `required` is identical on both fields in each canonical pair
+  - `selectorKey` exists in `hooks/selectors/registry.ts`
+  - `dependsOn` references selector field IDs (not `canonicalParamId`)
+  - Dependency `canonicalParamId` values exist in `SELECTOR_CONTEXT_FIELDS`
+- [ ] `listDocuments` handles pagination with metadata-based content hashes
+- [ ] `contentDeferred: true` used if content requires per-doc API calls (file download, export, blocks fetch)
+- [ ] `contentHash` is metadata-based (not content-based) and identical between stub and `getDocument`
+- [ ] `sourceUrl` set on each ExternalDocument (full URL, not relative)
+- [ ] `metadata` includes source-specific data for tag mapping
+- [ ] `tagDefinitions` declared for each semantic key returned by `mapTags`
+- [ ] `mapTags` implemented if source has useful metadata (labels, dates, versions)
+- [ ] `validateConfig` verifies the source is accessible
+- [ ] All external API calls use `fetchWithRetry` (not raw `fetch`)
+- [ ] All optional config fields validated in `validateConfig`
+- [ ] Icon exists in `components/icons.tsx` (or asked user to provide SVG)
+- [ ] Registered in `connectors/registry.ts`
--- a/.agents/skills/add-connector/agents/openai.yaml
+++ b/.agents/skills/add-connector/agents/openai.yaml
@@ -0,0 +1,5 @@
+interface:
+  display_name: "Add Connector"
+  short_description: "Build a Sim knowledge connector"
+  brand_color: "#0F766E"
+  default_prompt: "Use $add-connector to add or update a Sim knowledge connector for a service."
--- a/.agents/skills/add-integration/SKILL.md
+++ b/.agents/skills/add-integration/SKILL.md
@@ -0,0 +1,778 @@
+---
+name: add-integration
+description: Add a complete Sim integration from API docs, covering tools, block, icon, optional triggers, registrations, and integration conventions. Use when introducing a new service under `apps/sim/tools`, `apps/sim/blocks`, and `apps/sim/triggers`.
+---
+
+# Add Integration Skill
+
+You are an expert at adding complete integrations to Sim. This skill orchestrates the full process of adding a new service integration.
+
+## Overview
+
+Adding an integration involves these steps in order:
+1. **Research** - Read the service's API documentation
+2. **Create Tools** - Build tool configurations for each API operation
+3. **Create Block** - Build the block UI configuration
+4. **Add Icon** - Add the service's brand icon
+5. **Create Triggers** (optional) - If the service supports webhooks
+6. **Register** - Register tools, block, and triggers in their registries
+7. **Generate Docs** - Run the docs generation script
+
+## Step 1: Research the API
+
+Before writing any code:
+1. Use Context7 to find official documentation: `mcp__plugin_context7_context7__resolve-library-id`
+2. Or use WebFetch to read API docs directly
+3. Identify:
+   - Authentication method (OAuth, API Key, both)
+   - Available operations (CRUD, search, etc.)
+   - Required vs optional parameters
+   - Response structures
+
+### Hard Rule: No Guessed Response Schemas
+
+If the official docs do not clearly show the response JSON shape for an endpoint, you MUST stop and tell the user exactly which outputs are unknown.
+
+- Do NOT guess response field names
+- Do NOT infer nested JSON paths from related endpoints
+- Do NOT invent output properties just because they seem likely
+- Do NOT implement `transformResponse` against unverified payload shapes
+
+If response schemas are missing or incomplete, do one of the following before proceeding:
+1. Ask the user for sample responses
+2. Ask the user for test credentials so you can verify the live payload
+3. Reduce the scope to only endpoints whose response shapes are documented
+4. Leave the tool unimplemented and explicitly report why
+
+## Step 2: Create Tools
+
+### Directory Structure
+```
+apps/sim/tools/{service}/
+├── index.ts          # Barrel exports
+├── types.ts          # TypeScript interfaces
+├── {action1}.ts      # Tool for action 1
+├── {action2}.ts      # Tool for action 2
+└── ...
+```
+
+### Key Patterns
+
+**types.ts:**
+```typescript
+import type { ToolResponse } from '@/tools/types'
+
+export interface {Service}{Action}Params {
+  accessToken: string      // For OAuth services
+  // OR
+  apiKey: string          // For API key services
+
+  requiredParam: string
+  optionalParam?: string
+}
+
+export interface {Service}Response extends ToolResponse {
+  output: {
+    // Define output structure
+  }
+}
+```
+
+**Tool file pattern:**
+```typescript
+export const {service}{Action}Tool: ToolConfig<Params, Response> = {
+  id: '{service}_{action}',
+  name: '{Service} {Action}',
+  description: '...',
+  version: '1.0.0',
+
+  oauth: { required: true, provider: '{service}' },  // If OAuth
+
+  params: {
+    accessToken: { type: 'string', required: true, visibility: 'hidden', description: '...' },
+    // ... other params
+  },
+
+  request: { url, method, headers, body },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    return {
+      success: true,
+      output: {
+        field: data.field ?? null,  // Always handle nullables
+      },
+    }
+  },
+
+  outputs: { /* ... */ },
+}
+```
+
+### Critical Rules
+- `visibility: 'hidden'` for OAuth tokens
+- `visibility: 'user-only'` for API keys and user credentials
+- `visibility: 'user-or-llm'` for operation parameters
+- Always use `?? null` for nullable API response fields
+- Always use `?? []` for optional array fields
+- Set `optional: true` for outputs that may not exist
+- Never output raw JSON dumps - extract meaningful fields
+- When using `type: 'json'` and you know the object shape, define `properties` with the inner fields so downstream consumers know the structure. Only use bare `type: 'json'` when the shape is truly dynamic
+- If you do not know the response JSON shape from docs or verified examples, you MUST tell the user and stop. Never guess outputs or response mappings.
+
+## Step 3: Create Block
+
+### File Location
+`apps/sim/blocks/blocks/{service}.ts`
+
+### Block Structure
+```typescript
+import { {Service}Icon } from '@/components/icons'
+import type { BlockConfig } from '@/blocks/types'
+import { AuthMode } from '@/blocks/types'
+import { getScopesForService } from '@/lib/oauth/utils'
+
+export const {Service}Block: BlockConfig = {
+  type: '{service}',
+  name: '{Service}',
+  description: '...',
+  longDescription: '...',
+  docsLink: 'https://docs.sim.ai/tools/{service}',
+  category: 'tools',
+  bgColor: '#HEXCOLOR',
+  icon: {Service}Icon,
+  authMode: AuthMode.OAuth,  // or AuthMode.ApiKey
+
+  subBlocks: [
+    // Operation dropdown
+    {
+      id: 'operation',
+      title: 'Operation',
+      type: 'dropdown',
+      options: [
+        { label: 'Operation 1', id: 'action1' },
+        { label: 'Operation 2', id: 'action2' },
+      ],
+      value: () => 'action1',
+    },
+    // Credential field
+    {
+      id: 'credential',
+      title: '{Service} Account',
+      type: 'oauth-input',
+      serviceId: '{service}',
+      requiredScopes: getScopesForService('{service}'),
+      required: true,
+    },
+    // Conditional fields per operation
+    // ...
+  ],
+
+  tools: {
+    access: ['{service}_action1', '{service}_action2'],
+    config: {
+      tool: (params) => `{service}_${params.operation}`,
+    },
+  },
+
+  outputs: { /* ... */ },
+}
+```
+
+### Key SubBlock Patterns
+
+**Condition-based visibility:**
+```typescript
+{
+  id: 'resourceId',
+  title: 'Resource ID',
+  type: 'short-input',
+  condition: { field: 'operation', value: ['read', 'update', 'delete'] },
+  required: { field: 'operation', value: ['read', 'update', 'delete'] },
+}
+```
+
+**DependsOn for cascading selectors:**
+```typescript
+{
+  id: 'project',
+  type: 'project-selector',
+  dependsOn: ['credential'],
+},
+{
+  id: 'issue',
+  type: 'file-selector',
+  dependsOn: ['credential', 'project'],
+}
+```
+
+**Basic/Advanced mode for dual UX:**
+```typescript
+// Basic: Visual selector
+{
+  id: 'channel',
+  type: 'channel-selector',
+  mode: 'basic',
+  canonicalParamId: 'channel',
+  dependsOn: ['credential'],
+},
+// Advanced: Manual input
+{
+  id: 'channelId',
+  type: 'short-input',
+  mode: 'advanced',
+  canonicalParamId: 'channel',
+}
+```
+
+**Critical Canonical Param Rules:**
+- `canonicalParamId` must NOT match any subblock's `id` in the block
+- `canonicalParamId` must be unique per operation/condition context
+- Only use `canonicalParamId` to link basic/advanced alternatives for the same logical parameter
+- `mode` only controls UI visibility, NOT serialization. Without `canonicalParamId`, both basic and advanced field values would be sent
+- Every subblock `id` must be unique within the block. Duplicate IDs cause conflicts even with different conditions
+- **Required consistency:** If one subblock in a canonical group has `required: true`, ALL subblocks in that group must have `required: true` (prevents bypassing validation by switching modes)
+- **Inputs section:** Must list canonical param IDs (e.g., `fileId`), NOT raw subblock IDs (e.g., `fileSelector`, `manualFileId`)
+- **Params function:** Must use canonical param IDs, NOT raw subblock IDs (raw IDs are deleted after canonical transformation)
+
+## Step 4: Add Icon
+
+### File Location
+`apps/sim/components/icons.tsx`
+
+### Pattern
+```typescript
+export function {Service}Icon(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      {...props}
+      viewBox="0 0 24 24"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      {/* SVG paths from user-provided SVG */}
+    </svg>
+  )
+}
+```
+
+### Getting Icons
+**Do NOT search for icons yourself.** At the end of implementation, ask the user to provide the SVG:
+
+```
+I've completed the integration. Before I can add the icon, please provide the SVG for {Service}.
+You can usually find this in the service's brand/press kit page, or copy it from their website.
+
+Paste the SVG code here and I'll convert it to a React component.
+```
+
+Once the user provides the SVG:
+1. Extract the SVG paths/content
+2. Create a React component that spreads props
+3. Ensure viewBox is preserved from the original SVG
+
+## Step 5: Create Triggers (Optional)
+
+If the service supports webhooks, create triggers using the generic `buildTriggerSubBlocks` helper.
+
+### Directory Structure
+```
+apps/sim/triggers/{service}/
+├── index.ts      # Barrel exports
+├── utils.ts      # Trigger options, setup instructions, extra fields
+├── {event_a}.ts  # Primary trigger (includes dropdown)
+├── {event_b}.ts  # Secondary triggers (no dropdown)
+└── webhook.ts    # Generic webhook (optional)
+```
+
+### Key Pattern
+
+```typescript
+import { buildTriggerSubBlocks } from '@/triggers'
+import { {service}TriggerOptions, {service}SetupInstructions, build{Service}ExtraFields } from './utils'
+
+// Primary trigger - includeDropdown: true
+export const {service}EventATrigger: TriggerConfig = {
+  id: '{service}_event_a',
+  subBlocks: buildTriggerSubBlocks({
+    triggerId: '{service}_event_a',
+    triggerOptions: {service}TriggerOptions,
+    includeDropdown: true,  // Only for primary trigger!
+    setupInstructions: {service}SetupInstructions('Event A'),
+    extraFields: build{Service}ExtraFields('{service}_event_a'),
+  }),
+  // ...
+}
+
+// Secondary triggers - no dropdown
+export const {service}EventBTrigger: TriggerConfig = {
+  id: '{service}_event_b',
+  subBlocks: buildTriggerSubBlocks({
+    triggerId: '{service}_event_b',
+    triggerOptions: {service}TriggerOptions,
+    // No includeDropdown!
+    setupInstructions: {service}SetupInstructions('Event B'),
+    extraFields: build{Service}ExtraFields('{service}_event_b'),
+  }),
+  // ...
+}
+```
+
+### Connect to Block
+```typescript
+import { getTrigger } from '@/triggers'
+
+export const {Service}Block: BlockConfig = {
+  triggers: {
+    enabled: true,
+    available: ['{service}_event_a', '{service}_event_b'],
+  },
+  subBlocks: [
+    // Tool fields...
+    ...getTrigger('{service}_event_a').subBlocks,
+    ...getTrigger('{service}_event_b').subBlocks,
+  ],
+}
+```
+
+See `/add-trigger` skill for complete documentation.
+
+## Step 6: Register Everything
+
+### Tools Registry (`apps/sim/tools/registry.ts`)
+
+```typescript
+// Add import (alphabetically)
+import {
+  {service}Action1Tool,
+  {service}Action2Tool,
+} from '@/tools/{service}'
+
+// Add to tools object (alphabetically)
+export const tools: Record<string, ToolConfig> = {
+  // ... existing tools ...
+  {service}_action1: {service}Action1Tool,
+  {service}_action2: {service}Action2Tool,
+}
+```
+
+### Block Registry (`apps/sim/blocks/registry.ts`)
+
+```typescript
+// Add import (alphabetically)
+import { {Service}Block } from '@/blocks/blocks/{service}'
+
+// Add to registry (alphabetically)
+export const registry: Record<string, BlockConfig> = {
+  // ... existing blocks ...
+  {service}: {Service}Block,
+}
+```
+
+### Trigger Registry (`apps/sim/triggers/registry.ts`) - If triggers exist
+
+```typescript
+// Add import (alphabetically)
+import {
+  {service}EventATrigger,
+  {service}EventBTrigger,
+  {service}WebhookTrigger,
+} from '@/triggers/{service}'
+
+// Add to TRIGGER_REGISTRY (alphabetically)
+export const TRIGGER_REGISTRY: TriggerRegistry = {
+  // ... existing triggers ...
+  {service}_event_a: {service}EventATrigger,
+  {service}_event_b: {service}EventBTrigger,
+  {service}_webhook: {service}WebhookTrigger,
+}
+```
+
+## Step 7: Generate Docs
+
+Run the documentation generator:
+```bash
+bun run scripts/generate-docs.ts
+```
+
+This creates `apps/docs/content/docs/en/tools/{service}.mdx`
+
+## V2 Integration Pattern
+
+If creating V2 versions (API-aligned outputs):
+
+1. **V2 Tools** - Add `_v2` suffix, version `2.0.0`, flat outputs
+2. **V2 Block** - Add `_v2` type, use `createVersionedToolSelector`
+3. **V1 Block** - Add `(Legacy)` to name, set `hideFromToolbar: true`
+4. **Registry** - Register both versions
+
+```typescript
+// In registry
+{service}: {Service}Block,        // V1 (legacy, hidden)
+{service}_v2: {Service}V2Block,   // V2 (visible)
+```
+
+## Complete Checklist
+
+### Tools
+- [ ] Created `tools/{service}/` directory
+- [ ] Created `types.ts` with all interfaces
+- [ ] Created tool file for each operation
+- [ ] All params have correct visibility
+- [ ] All nullable fields use `?? null`
+- [ ] All optional outputs have `optional: true`
+- [ ] Created `index.ts` barrel export
+- [ ] Registered all tools in `tools/registry.ts`
+
+### Block
+- [ ] Created `blocks/blocks/{service}.ts`
+- [ ] Defined operation dropdown with all operations
+- [ ] Added credential field with `requiredScopes: getScopesForService('{service}')`
+- [ ] Added conditional fields per operation
+- [ ] Set up dependsOn for cascading selectors
+- [ ] Configured tools.access with all tool IDs
+- [ ] Configured tools.config.tool selector
+- [ ] Defined outputs matching tool outputs
+- [ ] Registered block in `blocks/registry.ts`
+- [ ] If triggers: set `triggers.enabled` and `triggers.available`
+- [ ] If triggers: spread trigger subBlocks with `getTrigger()`
+
+### OAuth Scopes (if OAuth service)
+- [ ] Defined scopes in `lib/oauth/oauth.ts` under `OAUTH_PROVIDERS`
+- [ ] Added scope descriptions in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts`
+- [ ] Used `getCanonicalScopesForProvider()` in `auth.ts` (never hardcode)
+- [ ] Used `getScopesForService()` in block `requiredScopes` (never hardcode)
+
+### Icon
+- [ ] Asked user to provide SVG
+- [ ] Added icon to `components/icons.tsx`
+- [ ] Icon spreads props correctly
+
+### Triggers (if service supports webhooks)
+- [ ] Created `triggers/{service}/` directory
+- [ ] Created `utils.ts` with options, instructions, and extra fields helpers
+- [ ] Primary trigger uses `includeDropdown: true`
+- [ ] Secondary triggers do NOT have `includeDropdown`
+- [ ] All triggers use `buildTriggerSubBlocks` helper
+- [ ] Created `index.ts` barrel export
+- [ ] Registered all triggers in `triggers/registry.ts`
+
+### Docs
+- [ ] Ran `bun run scripts/generate-docs.ts`
+- [ ] Verified docs file created
+
+### Final Validation (Required)
+- [ ] Read every tool file and cross-referenced inputs/outputs against the API docs
+- [ ] Verified block subBlocks cover all required tool params with correct conditions
+- [ ] Verified block outputs match what the tools actually return
+- [ ] Verified `tools.config.params` correctly maps and coerces all param types
+- [ ] Verified every tool output and `transformResponse` path against documented or live-verified JSON responses
+- [ ] If any response schema remained unknown, explicitly told the user instead of guessing
+
+## Example Command
+
+When the user asks to add an integration:
+
+```
+User: Add a Stripe integration
+
+You: I'll add the Stripe integration. Let me:
+
+1. First, research the Stripe API using Context7
+2. Create the tools for key operations (payments, subscriptions, etc.)
+3. Create the block with operation dropdown
+4. Register everything
+5. Generate docs
+6. Ask you for the Stripe icon SVG
+
+[Proceed with implementation...]
+
+[After completing steps 1-5...]
+
+I've completed the Stripe integration. Before I can add the icon, please provide the SVG for Stripe.
+You can usually find this in the service's brand/press kit page, or copy it from their website.
+
+Paste the SVG code here and I'll convert it to a React component.
+```
+
+## File Handling
+
+When your integration handles file uploads or downloads, follow these patterns to work with `UserFile` objects consistently.
+
+### What is a UserFile?
+
+A `UserFile` is the standard file representation in Sim:
+
+```typescript
+interface UserFile {
+  id: string       // Unique identifier
+  name: string     // Original filename
+  url: string      // Presigned URL for download
+  size: number     // File size in bytes
+  type: string     // MIME type (e.g., 'application/pdf')
+  base64?: string  // Optional base64 content (if small file)
+  key?: string     // Internal storage key
+  context?: object // Storage context metadata
+}
+```
+
+### File Input Pattern (Uploads)
+
+For tools that accept file uploads, **always route through an internal API endpoint** rather than calling external APIs directly. This ensures proper file content retrieval.
+
+#### 1. Block SubBlocks for File Input
+
+Use the basic/advanced mode pattern:
+
+```typescript
+// Basic mode: File upload UI
+{
+  id: 'uploadFile',
+  title: 'File',
+  type: 'file-upload',
+  canonicalParamId: 'file',  // Maps to 'file' param
+  placeholder: 'Upload file',
+  mode: 'basic',
+  multiple: false,
+  required: true,
+  condition: { field: 'operation', value: 'upload' },
+},
+// Advanced mode: Reference from previous block
+{
+  id: 'fileRef',
+  title: 'File',
+  type: 'short-input',
+  canonicalParamId: 'file',  // Same canonical param
+  placeholder: 'Reference file (e.g., {{file_block.output}})',
+  mode: 'advanced',
+  required: true,
+  condition: { field: 'operation', value: 'upload' },
+},
+```
+
+**Critical:** `canonicalParamId` must NOT match any subblock `id`.
+
+#### 2. Normalize File Input in Block Config
+
+In `tools.config.tool`, use `normalizeFileInput` to handle all input variants:
+
+```typescript
+import { normalizeFileInput } from '@/blocks/utils'
+
+tools: {
+  config: {
+    tool: (params) => {
+      // Normalize file from basic (uploadFile), advanced (fileRef), or legacy (fileContent)
+      const normalizedFile = normalizeFileInput(
+        params.uploadFile || params.fileRef || params.fileContent,
+        { single: true }
+      )
+      if (normalizedFile) {
+        params.file = normalizedFile
+      }
+      return `{service}_${params.operation}`
+    },
+  },
+}
+```
+
+#### 3. Create Internal API Route
+
+Create `apps/sim/app/api/tools/{service}/{action}/route.ts`:
+
+```typescript
+import { createLogger } from '@sim/logger'
+import { NextResponse, type NextRequest } from 'next/server'
+import { z } from 'zod'
+import { checkInternalAuth } from '@/lib/auth/hybrid'
+import { generateRequestId } from '@/lib/core/utils/request'
+import { FileInputSchema, type RawFileInput } from '@/lib/uploads/utils/file-schemas'
+import { processFilesToUserFiles } from '@/lib/uploads/utils/file-utils'
+import { downloadFileFromStorage } from '@/lib/uploads/utils/file-utils.server'
+
+const logger = createLogger('{Service}UploadAPI')
+
+const RequestSchema = z.object({
+  accessToken: z.string(),
+  file: FileInputSchema.optional().nullable(),
+  // Legacy field for backwards compatibility
+  fileContent: z.string().optional().nullable(),
+  // ... other params
+})
+
+export async function POST(request: NextRequest) {
+  const requestId = generateRequestId()
+
+  const authResult = await checkInternalAuth(request, { requireWorkflowId: false })
+  if (!authResult.success) {
+    return NextResponse.json({ success: false, error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const body = await request.json()
+  const data = RequestSchema.parse(body)
+
+  let fileBuffer: Buffer
+  let fileName: string
+
+  // Prefer UserFile input, fall back to legacy base64
+  if (data.file) {
+    const userFiles = processFilesToUserFiles([data.file as RawFileInput], requestId, logger)
+    if (userFiles.length === 0) {
+      return NextResponse.json({ success: false, error: 'Invalid file' }, { status: 400 })
+    }
+    const userFile = userFiles[0]
+    fileBuffer = await downloadFileFromStorage(userFile, requestId, logger)
+    fileName = userFile.name
+  } else if (data.fileContent) {
+    // Legacy: base64 string (backwards compatibility)
+    fileBuffer = Buffer.from(data.fileContent, 'base64')
+    fileName = 'file'
+  } else {
+    return NextResponse.json({ success: false, error: 'File required' }, { status: 400 })
+  }
+
+  // Now call external API with fileBuffer
+  const response = await fetch('https://api.{service}.com/upload', {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${data.accessToken}` },
+    body: new Uint8Array(fileBuffer),  // Convert Buffer for fetch
+  })
+
+  // ... handle response
+}
+```
+
+#### 4. Update Tool to Use Internal Route
+
+```typescript
+export const {service}UploadTool: ToolConfig<Params, Response> = {
+  id: '{service}_upload',
+  // ...
+  params: {
+    file: { type: 'file', required: false, visibility: 'user-or-llm' },
+    fileContent: { type: 'string', required: false, visibility: 'hidden' }, // Legacy
+  },
+  request: {
+    url: '/api/tools/{service}/upload',  // Internal route
+    method: 'POST',
+    body: (params) => ({
+      accessToken: params.accessToken,
+      file: params.file,
+      fileContent: params.fileContent,
+    }),
+  },
+}
+```
+
+### File Output Pattern (Downloads)
+
+For tools that return files, use `FileToolProcessor` to store files and return `UserFile` objects.
+
+#### In Tool transformResponse
+
+```typescript
+import { FileToolProcessor } from '@/executor/utils/file-tool-processor'
+
+transformResponse: async (response, context) => {
+  const data = await response.json()
+
+  // Process file outputs to UserFile objects
+  const fileProcessor = new FileToolProcessor(context)
+  const file = await fileProcessor.processFileData({
+    data: data.content,      // base64 or buffer
+    mimeType: data.mimeType,
+    filename: data.filename,
+  })
+
+  return {
+    success: true,
+    output: { file },
+  }
+}
+```
+
+#### In API Route (for complex file handling)
+
+```typescript
+// Return file data that FileToolProcessor can handle
+return NextResponse.json({
+  success: true,
+  output: {
+    file: {
+      data: base64Content,
+      mimeType: 'application/pdf',
+      filename: 'document.pdf',
+    },
+  },
+})
+```
+
+### Key Helpers Reference
+
+| Helper | Location | Purpose |
+|--------|----------|---------|
+| `normalizeFileInput` | `@/blocks/utils` | Normalize file params in block config |
+| `processFilesToUserFiles` | `@/lib/uploads/utils/file-utils` | Convert raw inputs to UserFile[] |
+| `downloadFileFromStorage` | `@/lib/uploads/utils/file-utils.server` | Get file Buffer from UserFile |
+| `FileToolProcessor` | `@/executor/utils/file-tool-processor` | Process tool output files |
+| `isUserFile` | `@/lib/core/utils/user-file` | Type guard for UserFile objects |
+| `FileInputSchema` | `@/lib/uploads/utils/file-schemas` | Zod schema for file validation |
+
+### Advanced Mode for Optional Fields
+
+Optional fields that are rarely used should be set to `mode: 'advanced'` so they don't clutter the basic UI. Examples: pagination tokens, time range filters, sort order, max results, reply settings.
+
+### WandConfig for Complex Inputs
+
+Use `wandConfig` for fields that are hard to fill out manually:
+- **Timestamps**: Use `generationType: 'timestamp'` to inject current date context into the AI prompt
+- **JSON arrays**: Use `generationType: 'json-object'` for structured data
+- **Complex queries**: Use a descriptive prompt explaining the expected format
+
+```typescript
+{
+  id: 'startTime',
+  title: 'Start Time',
+  type: 'short-input',
+  mode: 'advanced',
+  wandConfig: {
+    enabled: true,
+    prompt: 'Generate an ISO 8601 timestamp. Return ONLY the timestamp string.',
+    generationType: 'timestamp',
+  },
+}
+```
+
+### OAuth Scopes (Centralized System)
+
+Scopes are maintained in a single source of truth and reused everywhere:
+
+1. **Define scopes** in `lib/oauth/oauth.ts` under `OAUTH_PROVIDERS[provider].services[service].scopes`
+2. **Add descriptions** in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts` for the OAuth modal UI
+3. **Reference in auth.ts** using `getCanonicalScopesForProvider(providerId)` from `@/lib/oauth/utils`
+4. **Reference in blocks** using `getScopesForService(serviceId)` from `@/lib/oauth/utils`
+
+**Never hardcode scope arrays** in `auth.ts` or block `requiredScopes`. Always import from the centralized source.
+
+```typescript
+// In auth.ts (Better Auth config)
+scopes: getCanonicalScopesForProvider('{service}'),
+
+// In block credential sub-block
+requiredScopes: getScopesForService('{service}'),
+```
+
+### Common Gotchas
+
+1. **OAuth serviceId must match** - The `serviceId` in oauth-input must match the OAuth provider configuration
+2. **All tool IDs MUST be snake_case** - `stripe_create_payment`, not `stripeCreatePayment`. This applies to tool `id` fields, registry keys, `tools.access` arrays, and `tools.config.tool` return values
+3. **Block type is snake_case** - `type: 'stripe'`, not `type: 'Stripe'`
+4. **Alphabetical ordering** - Keep imports and registry entries alphabetically sorted
+5. **Required can be conditional** - Use `required: { field: 'op', value: 'create' }` instead of always true
+6. **DependsOn clears options** - When a dependency changes, selector options are refetched
+7. **Never pass Buffer directly to fetch** - Convert to `new Uint8Array(buffer)` for TypeScript compatibility
+8. **Always handle legacy file params** - Keep hidden `fileContent` params for backwards compatibility
+9. **Optional fields use advanced mode** - Set `mode: 'advanced'` on rarely-used optional fields
+10. **Complex inputs need wandConfig** - Timestamps, JSON arrays, and other hard-to-type values should have `wandConfig` enabled
+11. **Never hardcode scopes** - Use `getScopesForService()` in blocks and `getCanonicalScopesForProvider()` in auth.ts
+12. **Always add scope descriptions** - New scopes must have entries in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts`
--- a/.agents/skills/add-integration/agents/openai.yaml
+++ b/.agents/skills/add-integration/agents/openai.yaml
@@ -0,0 +1,5 @@
+interface:
+  display_name: "Add Integration"
+  short_description: "Build a full Sim integration"
+  brand_color: "#7C3AED"
+  default_prompt: "Use $add-integration to add a complete Sim integration for a service."
--- a/.agents/skills/add-tools/SKILL.md
+++ b/.agents/skills/add-tools/SKILL.md
@@ -0,0 +1,466 @@
+---
+name: add-tools
+description: Create or update Sim tool configurations from service API docs, including typed params, request mapping, response transforms, outputs, and registry entries. Use when working in `apps/sim/tools/{service}/` or fixing tool definitions for an integration.
+---
+
+# Add Tools Skill
+
+You are an expert at creating tool configurations for Sim integrations. Your job is to read API documentation and create properly structured tool files.
+
+## Your Task
+
+When the user asks you to create tools for a service:
+1. Use Context7 or WebFetch to read the service's API documentation
+2. Create the tools directory structure
+3. Generate properly typed tool configurations
+
+## Hard Rule: No Guessed Response Schemas
+
+If the docs do not clearly show the response JSON for a tool, you MUST tell the user exactly which outputs are unknown and stop short of guessing.
+
+- Do NOT invent response field names
+- Do NOT infer nested paths from nearby endpoints
+- Do NOT guess array item shapes
+- Do NOT write `transformResponse` against unverified payloads
+
+If the response shape is unknown, do one of these instead:
+1. Ask the user for sample responses
+2. Ask the user for test credentials so you can verify live responses
+3. Implement only the endpoints whose outputs are documented
+4. Leave the tool unimplemented and explicitly say why
+
+## Directory Structure
+
+Create files in `apps/sim/tools/{service}/`:
+```
+tools/{service}/
+├── index.ts      # Barrel export
+├── types.ts      # Parameter & response types
+└── {action}.ts   # Individual tool files (one per operation)
+```
+
+## Tool Configuration Structure
+
+Every tool MUST follow this exact structure:
+
+```typescript
+import type { {ServiceName}{Action}Params } from '@/tools/{service}/types'
+import type { ToolConfig } from '@/tools/types'
+
+interface {ServiceName}{Action}Response {
+  success: boolean
+  output: {
+    // Define output structure here
+  }
+}
+
+export const {serviceName}{Action}Tool: ToolConfig<
+  {ServiceName}{Action}Params,
+  {ServiceName}{Action}Response
+> = {
+  id: '{service}_{action}',           // snake_case, matches tool name
+  name: '{Service} {Action}',         // Human readable
+  description: 'Brief description',   // One sentence
+  version: '1.0.0',
+
+  // OAuth config (if service uses OAuth)
+  oauth: {
+    required: true,
+    provider: '{service}',            // Must match OAuth provider ID
+  },
+
+  params: {
+    // Hidden params (system-injected, only use hidden for oauth accessToken)
+    accessToken: {
+      type: 'string',
+      required: true,
+      visibility: 'hidden',
+      description: 'OAuth access token',
+    },
+    // User-only params (credentials, api key, IDs user must provide)
+    someId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'The ID of the resource',
+    },
+    // User-or-LLM params (everything else, can be provided by user OR computed by LLM)
+    query: {
+      type: 'string',
+      required: false,                // Use false for optional
+      visibility: 'user-or-llm',
+      description: 'Search query',
+    },
+  },
+
+  request: {
+    url: (params) => `https://api.service.com/v1/resource/${params.id}`,
+    method: 'POST',
+    headers: (params) => ({
+      Authorization: `Bearer ${params.accessToken}`,
+      'Content-Type': 'application/json',
+    }),
+    body: (params) => ({
+      // Request body - only for POST/PUT/PATCH
+      // Trim ID fields to prevent copy-paste whitespace errors:
+      // userId: params.userId?.trim(),
+    }),
+  },
+
+  transformResponse: async (response: Response) => {
+    const data = await response.json()
+    return {
+      success: true,
+      output: {
+        // Map API response to output
+        // Use ?? null for nullable fields
+        // Use ?? [] for optional arrays
+      },
+    }
+  },
+
+  outputs: {
+    // Define each output field
+  },
+}
+```
+
+## Critical Rules for Parameters
+
+### Visibility Options
+- `'hidden'` - System-injected (OAuth tokens, internal params). User never sees.
+- `'user-only'` - User must provide (credentials, api keys, account-specific IDs)
+- `'user-or-llm'` - User provides OR LLM can compute (search queries, content, filters, most fall into this category)
+
+### Parameter Types
+- `'string'` - Text values
+- `'number'` - Numeric values
+- `'boolean'` - True/false
+- `'json'` - Complex objects (NOT 'object', use 'json')
+- `'file'` - Single file
+- `'file[]'` - Multiple files
+
+### Required vs Optional
+- Always explicitly set `required: true` or `required: false`
+- Optional params should have `required: false`
+
+## Critical Rules for Outputs
+
+### Output Types
+- `'string'`, `'number'`, `'boolean'` - Primitives
+- `'json'` - Complex objects (use this, NOT 'object')
+- `'array'` - Arrays with `items` property
+- `'object'` - Objects with `properties` property
+
+### Optional Outputs
+Add `optional: true` for fields that may not exist in the response:
+```typescript
+closedAt: {
+  type: 'string',
+  description: 'When the issue was closed',
+  optional: true,
+},
+```
+
+### Typed JSON Outputs
+
+When using `type: 'json'` and you know the object shape in advance, **always define the inner structure** using `properties` so downstream consumers know what fields are available:
+
+```typescript
+// BAD: Opaque json with no info about what's inside
+metadata: {
+  type: 'json',
+  description: 'Response metadata',
+},
+
+// GOOD: Define the known properties
+metadata: {
+  type: 'json',
+  description: 'Response metadata',
+  properties: {
+    id: { type: 'string', description: 'Unique ID' },
+    status: { type: 'string', description: 'Current status' },
+    count: { type: 'number', description: 'Total count' },
+  },
+},
+```
+
+For arrays of objects, define the item structure:
+```typescript
+items: {
+  type: 'array',
+  description: 'List of items',
+  items: {
+    type: 'object',
+    properties: {
+      id: { type: 'string', description: 'Item ID' },
+      name: { type: 'string', description: 'Item name' },
+    },
+  },
+},
+```
+
+Only use bare `type: 'json'` without `properties` when the shape is truly dynamic or unknown.
+
+If the response shape is unknown because the docs do not provide it, you MUST tell the user and stop. Unknown is not the same as dynamic. Never guess outputs.
+
+## Critical Rules for transformResponse
+
+### Handle Nullable Fields
+ALWAYS use `?? null` for fields that may be undefined:
+```typescript
+transformResponse: async (response: Response) => {
+  const data = await response.json()
+  return {
+    success: true,
+    output: {
+      id: data.id,
+      title: data.title,
+      body: data.body ?? null,           // May be undefined
+      assignee: data.assignee ?? null,   // May be undefined
+      labels: data.labels ?? [],         // Default to empty array
+      closedAt: data.closed_at ?? null,  // May be undefined
+    },
+  }
+}
+```
+
+### Never Output Raw JSON Dumps
+DON'T do this:
+```typescript
+output: {
+  data: data,  // BAD - raw JSON dump
+}
+```
+
+DO this instead - extract meaningful fields:
+```typescript
+output: {
+  id: data.id,
+  name: data.name,
+  status: data.status,
+  metadata: {
+    createdAt: data.created_at,
+    updatedAt: data.updated_at,
+  },
+}
+```
+
+## Types File Pattern
+
+Create `types.ts` with interfaces for all params and responses:
+
+```typescript
+import type { ToolResponse } from '@/tools/types'
+
+// Parameter interfaces
+export interface {Service}{Action}Params {
+  accessToken: string
+  requiredField: string
+  optionalField?: string
+}
+
+// Response interfaces (extend ToolResponse)
+export interface {Service}{Action}Response extends ToolResponse {
+  output: {
+    field1: string
+    field2: number
+    optionalField?: string | null
+  }
+}
+```
+
+## Index.ts Barrel Export Pattern
+
+```typescript
+// Export all tools
+export { serviceTool1 } from './{action1}'
+export { serviceTool2 } from './{action2}'
+
+// Export types
+export * from './types'
+```
+
+## Registering Tools
+
+After creating tools:
+1. Import tools in `apps/sim/tools/registry.ts`
+2. Add to the `tools` object with snake_case keys (alphabetically):
+```typescript
+import { serviceActionTool } from '@/tools/{service}'
+
+export const tools = {
+  // ... existing tools ...
+  {service}_{action}: serviceActionTool,
+}
+```
+
+## Wiring Tools into the Block (Required)
+
+After registering in `tools/registry.ts`, you MUST also update the block definition at `apps/sim/blocks/blocks/{service}.ts`. This is not optional — tools are only usable from the UI if they are wired into the block.
+
+### 1. Add to `tools.access`
+
+```typescript
+tools: {
+  access: [
+    // existing tools...
+    'service_new_action',   // Add every new tool ID here
+  ],
+  config: { ... }
+}
+```
+
+### 2. Add operation dropdown options
+
+If the block uses an operation dropdown, add an option for each new tool:
+
+```typescript
+{
+  id: 'operation',
+  type: 'dropdown',
+  options: [
+    // existing options...
+    { label: 'New Action', id: 'new_action' },   // id maps to what tools.config.tool returns
+  ],
+}
+```
+
+### 3. Add subBlocks for new tool params
+
+For each new tool, add subBlocks covering all its required params (and optional ones where useful). Apply `condition` to show them only for the right operation, and mark required params with `required`:
+
+```typescript
+// Required param for new_action
+{
+  id: 'someParam',
+  title: 'Some Param',
+  type: 'short-input',
+  placeholder: 'e.g., value',
+  condition: { field: 'operation', value: 'new_action' },
+  required: { field: 'operation', value: 'new_action' },
+},
+// Optional param — put in advanced mode
+{
+  id: 'optionalParam',
+  title: 'Optional Param',
+  type: 'short-input',
+  condition: { field: 'operation', value: 'new_action' },
+  mode: 'advanced',
+},
+```
+
+### 4. Update `tools.config.tool`
+
+Ensure the tool selector returns the correct tool ID for every new operation. The simplest pattern:
+
+```typescript
+tool: (params) => `service_${params.operation}`,
+// If operation dropdown IDs already match tool IDs, this requires no change.
+```
+
+If the dropdown IDs differ from tool IDs, add explicit mappings:
+
+```typescript
+tool: (params) => {
+  const map: Record<string, string> = {
+    new_action: 'service_new_action',
+    // ...
+  }
+  return map[params.operation] ?? `service_${params.operation}`
+},
+```
+
+### 5. Update `tools.config.params`
+
+Add any type coercions needed for new params (runs at execution time, after variable resolution):
+
+```typescript
+params: (params) => {
+  const result: Record<string, unknown> = {}
+  if (params.limit != null && params.limit !== '') result.limit = Number(params.limit)
+  if (params.newParamName) result.toolParamName = params.newParamName  // rename if IDs differ
+  return result
+},
+```
+
+### 6. Add new outputs
+
+Add any new fields returned by the new tools to the block `outputs`:
+
+```typescript
+outputs: {
+  // existing outputs...
+  newField: { type: 'string', description: 'Description of new field' },
+}
+```
+
+### 7. Add new inputs
+
+Add new subBlock param IDs to the block `inputs` section:
+
+```typescript
+inputs: {
+  // existing inputs...
+  someParam: { type: 'string', description: 'Param description' },
+  optionalParam: { type: 'string', description: 'Optional param description' },
+}
+```
+
+### Block wiring checklist
+
+- [ ] New tool IDs added to `tools.access`
+- [ ] Operation dropdown has an option for each new tool
+- [ ] SubBlocks cover all required params for each new tool
+- [ ] SubBlocks have correct `condition` (only show for the right operation)
+- [ ] Optional/rarely-used params set to `mode: 'advanced'`
+- [ ] `tools.config.tool` returns correct ID for every new operation
+- [ ] `tools.config.params` handles any ID remapping or type coercions
+- [ ] New outputs added to block `outputs`
+- [ ] New params added to block `inputs`
+
+## V2 Tool Pattern
+
+If creating V2 tools (API-aligned outputs), use `_v2` suffix:
+- Tool ID: `{service}_{action}_v2`
+- Variable name: `{action}V2Tool`
+- Version: `'2.0.0'`
+- Outputs: Flat, API-aligned (no content/metadata wrapper)
+
+## Naming Convention
+
+All tool IDs MUST use `snake_case`: `{service}_{action}` (e.g., `x_create_tweet`, `slack_send_message`). Never use camelCase or PascalCase for tool IDs.
+
+## Checklist Before Finishing
+
+- [ ] All tool IDs use snake_case
+- [ ] All params have explicit `required: true` or `required: false`
+- [ ] All params have appropriate `visibility`
+- [ ] All nullable response fields use `?? null`
+- [ ] All optional outputs have `optional: true`
+- [ ] No raw JSON dumps in outputs
+- [ ] Types file has all interfaces
+- [ ] Index.ts exports all tools and re-exports types (`export * from './types'`)
+- [ ] Tools registered in `tools/registry.ts`
+- [ ] Block wired: `tools.access`, dropdown options, subBlocks, `tools.config`, outputs, inputs
+
+## Final Validation (Required)
+
+After creating all tools, you MUST validate every tool before finishing:
+
+1. **Read every tool file** you created — do not skip any
+2. **Cross-reference with the API docs** to verify:
+   - All required params are marked `required: true`
+   - All optional params are marked `required: false`
+   - Param types match the API (string, number, boolean, json)
+   - Request URL, method, headers, and body match the API spec
+   - `transformResponse` extracts the correct fields from the API response
+   - All output fields match what the API actually returns
+   - No fields are missing from outputs that the API provides
+   - No extra fields are defined in outputs that the API doesn't return
+   - Every output field and JSON path is backed by docs or live-verified sample responses
+3. **Verify consistency** across tools:
+   - Shared types in `types.ts` match all tools that use them
+   - Tool IDs in the barrel export match the tool file definitions
+   - Error handling is consistent (error checks, meaningful messages)
+4. **If any response schema is still unknown**, explicitly tell the user instead of guessing
--- a/.agents/skills/add-tools/agents/openai.yaml
+++ b/.agents/skills/add-tools/agents/openai.yaml
@@ -0,0 +1,5 @@
+interface:
+  display_name: "Add Tools"
+  short_description: "Build Sim tools from API docs"
+  brand_color: "#EA580C"
+  default_prompt: "Use $add-tools to create or update Sim tool definitions from service API docs."
--- a/.agents/skills/add-trigger/SKILL.md
+++ b/.agents/skills/add-trigger/SKILL.md
@@ -0,0 +1,373 @@
+---
+name: add-trigger
+description: Create or update Sim webhook triggers using the generic trigger builder, service-specific setup instructions, outputs, and registry wiring. Use when working in `apps/sim/triggers/{service}/` or adding webhook support to an integration.
+---
+
+# Add Trigger
+
+You are an expert at creating webhook triggers for Sim. You understand the trigger system, the generic `buildTriggerSubBlocks` helper, and how triggers connect to blocks.
+
+## Your Task
+
+1. Research what webhook events the service supports
+2. Create the trigger files using the generic builder
+3. Create a provider handler if custom auth, formatting, or subscriptions are needed
+4. Register triggers and connect them to the block
+
+## Hard Rule: No Guessed Webhook Payload Schemas
+
+If the service docs do not clearly show the webhook payload JSON for an event, you MUST tell the user instead of guessing trigger outputs or `formatInput` mappings.
+
+- Do NOT invent payload field names
+- Do NOT guess nested event object paths
+- Do NOT infer output fields from the UI or marketing docs
+- Do NOT write `formatInput` against unverified webhook bodies
+
+If the payload shape is unknown, do one of these instead:
+1. Ask the user for sample webhook payloads
+2. Ask the user for a test webhook source so you can inspect a real event
+3. Implement only the event registration/setup portions whose payloads are documented
+4. Leave the trigger unimplemented and explicitly say which payload fields are unknown
+
+## Directory Structure
+
+```
+apps/sim/triggers/{service}/
+├── index.ts              # Barrel exports
+├── utils.ts              # Service-specific helpers (options, instructions, extra fields, outputs)
+├── {event_a}.ts          # Primary trigger (includes dropdown)
+├── {event_b}.ts          # Secondary trigger (no dropdown)
+└── webhook.ts            # Generic webhook trigger (optional, for "all events")
+
+apps/sim/lib/webhooks/
+├── provider-subscription-utils.ts  # Shared subscription helpers (getProviderConfig, getNotificationUrl)
+├── providers/
+│   ├── {service}.ts       # Provider handler (auth, formatInput, matchEvent, subscriptions)
+│   ├── types.ts           # WebhookProviderHandler interface
+│   ├── utils.ts           # Shared helpers (createHmacVerifier, verifyTokenAuth, skipByEventTypes)
+│   └── registry.ts        # Handler map + default handler
+```
+
+## Step 1: Create `utils.ts`
+
+This file contains all service-specific helpers used by triggers.
+
+```typescript
+import type { SubBlockConfig } from '@/blocks/types'
+import type { TriggerOutput } from '@/triggers/types'
+
+export const {service}TriggerOptions = [
+  { label: 'Event A', id: '{service}_event_a' },
+  { label: 'Event B', id: '{service}_event_b' },
+]
+
+export function {service}SetupInstructions(eventType: string): string {
+  const instructions = [
+    'Copy the <strong>Webhook URL</strong> above',
+    'Go to <strong>{Service} Settings > Webhooks</strong>',
+    `Select the <strong>${eventType}</strong> event type`,
+    'Paste the webhook URL and save',
+    'Click "Save" above to activate your trigger',
+  ]
+  return instructions
+    .map((instruction, index) =>
+      `<div class="mb-3"><strong>${index + 1}.</strong> ${instruction}</div>`
+    )
+    .join('')
+}
+
+export function build{Service}ExtraFields(triggerId: string): SubBlockConfig[] {
+  return [
+    {
+      id: 'projectId',
+      title: 'Project ID (Optional)',
+      type: 'short-input',
+      placeholder: 'Leave empty for all projects',
+      mode: 'trigger',
+      condition: { field: 'selectedTriggerId', value: triggerId },
+    },
+  ]
+}
+
+export function build{Service}Outputs(): Record<string, TriggerOutput> {
+  return {
+    eventType: { type: 'string', description: 'The type of event' },
+    resourceId: { type: 'string', description: 'ID of the affected resource' },
+    resource: {
+      id: { type: 'string', description: 'Resource ID' },
+      name: { type: 'string', description: 'Resource name' },
+    },
+  }
+}
+```
+
+## Step 2: Create Trigger Files
+
+**Primary trigger** — MUST include `includeDropdown: true`:
+
+```typescript
+import { {Service}Icon } from '@/components/icons'
+import { buildTriggerSubBlocks } from '@/triggers'
+import { build{Service}ExtraFields, build{Service}Outputs, {service}SetupInstructions, {service}TriggerOptions } from '@/triggers/{service}/utils'
+import type { TriggerConfig } from '@/triggers/types'
+
+export const {service}EventATrigger: TriggerConfig = {
+  id: '{service}_event_a',
+  name: '{Service} Event A',
+  provider: '{service}',
+  description: 'Trigger workflow when Event A occurs',
+  version: '1.0.0',
+  icon: {Service}Icon,
+  subBlocks: buildTriggerSubBlocks({
+    triggerId: '{service}_event_a',
+    triggerOptions: {service}TriggerOptions,
+    includeDropdown: true,
+    setupInstructions: {service}SetupInstructions('Event A'),
+    extraFields: build{Service}ExtraFields('{service}_event_a'),
+  }),
+  outputs: build{Service}Outputs(),
+  webhook: { method: 'POST', headers: { 'Content-Type': 'application/json' } },
+}
+```
+
+**Secondary triggers** — NO `includeDropdown` (it's already in the primary):
+
+```typescript
+export const {service}EventBTrigger: TriggerConfig = {
+  // Same as above but: id: '{service}_event_b', no includeDropdown
+}
+```
+
+## Step 3: Register and Wire
+
+### `apps/sim/triggers/{service}/index.ts`
+
+```typescript
+export { {service}EventATrigger } from './event_a'
+export { {service}EventBTrigger } from './event_b'
+```
+
+### `apps/sim/triggers/registry.ts`
+
+```typescript
+import { {service}EventATrigger, {service}EventBTrigger } from '@/triggers/{service}'
+
+export const TRIGGER_REGISTRY: TriggerRegistry = {
+  // ... existing ...
+  {service}_event_a: {service}EventATrigger,
+  {service}_event_b: {service}EventBTrigger,
+}
+```
+
+### Block file (`apps/sim/blocks/blocks/{service}.ts`)
+
+```typescript
+import { getTrigger } from '@/triggers'
+
+export const {Service}Block: BlockConfig = {
+  // ...
+  triggers: {
+    enabled: true,
+    available: ['{service}_event_a', '{service}_event_b'],
+  },
+  subBlocks: [
+    // Regular tool subBlocks first...
+    ...getTrigger('{service}_event_a').subBlocks,
+    ...getTrigger('{service}_event_b').subBlocks,
+  ],
+}
+```
+
+## Provider Handler
+
+All provider-specific webhook logic lives in a single handler file: `apps/sim/lib/webhooks/providers/{service}.ts`.
+
+### When to Create a Handler
+
+| Behavior | Method | Examples |
+|---|---|---|
+| HMAC signature auth | `verifyAuth` via `createHmacVerifier` | Ashby, Jira, Linear, Typeform |
+| Custom token auth | `verifyAuth` via `verifyTokenAuth` | Generic, Google Forms |
+| Event filtering | `matchEvent` | GitHub, Jira, Attio, HubSpot |
+| Idempotency dedup | `extractIdempotencyId` | Slack, Stripe, Linear, Jira |
+| Custom input formatting | `formatInput` | Slack, Teams, Attio, Ashby |
+| Auto webhook creation | `createSubscription` | Ashby, Grain, Calendly, Airtable |
+| Auto webhook deletion | `deleteSubscription` | Ashby, Grain, Calendly, Airtable |
+| Challenge/verification | `handleChallenge` | Slack, WhatsApp, Teams |
+| Custom success response | `formatSuccessResponse` | Slack, Twilio Voice, Teams |
+
+If none apply, you don't need a handler. The default handler provides bearer token auth.
+
+### Example Handler
+
+```typescript
+import crypto from 'crypto'
+import { createLogger } from '@sim/logger'
+import { safeCompare } from '@/lib/core/security/encryption'
+import type { EventMatchContext, FormatInputContext, FormatInputResult, WebhookProviderHandler } from '@/lib/webhooks/providers/types'
+import { createHmacVerifier } from '@/lib/webhooks/providers/utils'
+
+const logger = createLogger('WebhookProvider:{Service}')
+
+function validate{Service}Signature(secret: string, signature: string, body: string): boolean {
+  if (!secret || !signature || !body) return false
+  const computed = crypto.createHmac('sha256', secret).update(body, 'utf8').digest('hex')
+  return safeCompare(computed, signature)
+}
+
+export const {service}Handler: WebhookProviderHandler = {
+  verifyAuth: createHmacVerifier({
+    configKey: 'webhookSecret',
+    headerName: 'X-{Service}-Signature',
+    validateFn: validate{Service}Signature,
+    providerLabel: '{Service}',
+  }),
+
+  async matchEvent({ body, requestId, providerConfig }: EventMatchContext) {
+    const triggerId = providerConfig.triggerId as string | undefined
+    if (triggerId && triggerId !== '{service}_webhook') {
+      const { is{Service}EventMatch } = await import('@/triggers/{service}/utils')
+      if (!is{Service}EventMatch(triggerId, body as Record<string, unknown>)) return false
+    }
+    return true
+  },
+
+  async formatInput({ body }: FormatInputContext): Promise<FormatInputResult> {
+    const b = body as Record<string, unknown>
+    return {
+      input: {
+        eventType: b.type,
+        resourceId: (b.data as Record<string, unknown>)?.id || '',
+        resource: b.data,
+      },
+    }
+  },
+
+  extractIdempotencyId(body: unknown) {
+    const obj = body as Record<string, unknown>
+    return obj.id && obj.type ? `${obj.type}:${obj.id}` : null
+  },
+}
+```
+
+### Register the Handler
+
+In `apps/sim/lib/webhooks/providers/registry.ts`:
+
+```typescript
+import { {service}Handler } from '@/lib/webhooks/providers/{service}'
+
+const PROVIDER_HANDLERS: Record<string, WebhookProviderHandler> = {
+  // ... existing (alphabetical) ...
+  {service}: {service}Handler,
+}
+```
+
+## Output Alignment (Critical)
+
+There are two sources of truth that **MUST be aligned**:
+
+1. **Trigger `outputs`** — schema defining what fields SHOULD be available (UI tag dropdown)
+2. **`formatInput` on the handler** — implementation that transforms raw payload into actual data
+
+If they differ: the tag dropdown shows fields that don't exist, or actual data has fields users can't discover.
+
+**Rules for `formatInput`:**
+- Return `{ input: { ... } }` where inner keys match trigger `outputs` exactly
+- Return `{ input: ..., skip: { message: '...' } }` to skip execution
+- No wrapper objects or duplication
+- Use `null` for missing optional data
+
+## Automatic Webhook Registration
+
+If the service API supports programmatic webhook creation, implement `createSubscription` and `deleteSubscription` on the handler. The orchestration layer calls these automatically — **no code touches `route.ts`, `provider-subscriptions.ts`, or `deploy.ts`**.
+
+```typescript
+import { getNotificationUrl, getProviderConfig } from '@/lib/webhooks/provider-subscription-utils'
+import type { DeleteSubscriptionContext, SubscriptionContext, SubscriptionResult } from '@/lib/webhooks/providers/types'
+
+export const {service}Handler: WebhookProviderHandler = {
+  async createSubscription(ctx: SubscriptionContext): Promise<SubscriptionResult | undefined> {
+    const config = getProviderConfig(ctx.webhook)
+    const apiKey = config.apiKey as string
+    if (!apiKey) throw new Error('{Service} API Key is required.')
+
+    const res = await fetch('https://api.{service}.com/webhooks', {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ url: getNotificationUrl(ctx.webhook) }),
+    })
+
+    if (!res.ok) throw new Error(`{Service} error: ${res.status}`)
+    const { id } = (await res.json()) as { id: string }
+    return { providerConfigUpdates: { externalId: id } }
+  },
+
+  async deleteSubscription(ctx: DeleteSubscriptionContext): Promise<void> {
+    const config = getProviderConfig(ctx.webhook)
+    const { apiKey, externalId } = config as { apiKey?: string; externalId?: string }
+    if (!apiKey || !externalId) return
+    await fetch(`https://api.{service}.com/webhooks/${externalId}`, {
+      method: 'DELETE',
+      headers: { Authorization: `Bearer ${apiKey}` },
+    }).catch(() => {})
+  },
+}
+```
+
+**Key points:**
+- Throw from `createSubscription` — orchestration rolls back the DB webhook
+- Never throw from `deleteSubscription` — log non-fatally
+- Return `{ providerConfigUpdates: { externalId } }` — orchestration merges into `providerConfig`
+- Add `apiKey` field to `build{Service}ExtraFields` with `password: true`
+
+## Trigger Outputs Schema
+
+Trigger outputs use the same schema as block outputs (NOT tool outputs).
+
+**Supported:** `type` + `description` for leaf fields, nested objects for complex data.
+**NOT supported:** `optional: true`, `items` (those are tool-output-only features).
+
+```typescript
+export function buildOutputs(): Record<string, TriggerOutput> {
+  return {
+    eventType: { type: 'string', description: 'Event type' },
+    timestamp: { type: 'string', description: 'When it occurred' },
+    payload: { type: 'json', description: 'Full event payload' },
+    resource: {
+      id: { type: 'string', description: 'Resource ID' },
+      name: { type: 'string', description: 'Resource name' },
+    },
+  }
+}
+```
+
+## Checklist
+
+### Trigger Definition
+- [ ] Created `utils.ts` with options, instructions, extra fields, and output builders
+- [ ] Primary trigger has `includeDropdown: true`; secondary triggers do NOT
+- [ ] All triggers use `buildTriggerSubBlocks` helper
+- [ ] Created `index.ts` barrel export
+
+### Registration
+- [ ] All triggers in `triggers/registry.ts` → `TRIGGER_REGISTRY`
+- [ ] Block has `triggers.enabled: true` and lists all trigger IDs in `triggers.available`
+- [ ] Block spreads all trigger subBlocks: `...getTrigger('id').subBlocks`
+
+### Provider Handler (if needed)
+- [ ] Handler file at `apps/sim/lib/webhooks/providers/{service}.ts`
+- [ ] Registered in `providers/registry.ts` (alphabetical)
+- [ ] Signature validator is a private function inside the handler file
+- [ ] `formatInput` output keys match trigger `outputs` exactly
+- [ ] Event matching uses dynamic `await import()` for trigger utils
+
+### Auto Registration (if supported)
+- [ ] `createSubscription` and `deleteSubscription` on the handler
+- [ ] NO changes to `route.ts`, `provider-subscriptions.ts`, or `deploy.ts`
+- [ ] API key field uses `password: true`
+
+### Testing
+- [ ] `bun run type-check` passes
+- [ ] Manually verify `formatInput` output keys match trigger `outputs` keys
+- [ ] Trigger UI shows correctly in the block
--- a/.agents/skills/add-trigger/agents/openai.yaml
+++ b/.agents/skills/add-trigger/agents/openai.yaml
@@ -0,0 +1,5 @@
+interface:
+  display_name: "Add Trigger"
+  short_description: "Build Sim webhook triggers"
+  brand_color: "#DC2626"
+  default_prompt: "Use $add-trigger to create or update webhook triggers for a Sim integration."
--- a/.agents/skills/cleanup/SKILL.md
+++ b/.agents/skills/cleanup/SKILL.md
@@ -0,0 +1,25 @@
+---
+name: cleanup
+description: Run all code quality skills in sequence — effects, memo, callbacks, state, React Query, and emcn design review
+---
+
+# Cleanup
+
+Arguments:
+- scope: what to review (default: your current changes). Examples: "diff to main", "PR #123", "src/components/", "whole codebase"
+- fix: whether to apply fixes (default: true). Set to false to only propose changes.
+
+User arguments: $ARGUMENTS
+
+## Steps
+
+Run each of these skills in order on the specified scope, passing through the scope and fix arguments. After each skill completes, move to the next. Do not skip any.
+
+1. `/you-might-not-need-an-effect $ARGUMENTS`
+2. `/you-might-not-need-a-memo $ARGUMENTS`
+3. `/you-might-not-need-a-callback $ARGUMENTS`
+4. `/you-might-not-need-state $ARGUMENTS`
+5. `/react-query-best-practices $ARGUMENTS`
+6. `/emcn-design-review $ARGUMENTS`
+
+After all skills have run, output a summary of what was found and fixed (or proposed) across all six passes.
--- a/.agents/skills/emcn-design-review/SKILL.md
+++ b/.agents/skills/emcn-design-review/SKILL.md
@@ -0,0 +1,335 @@
+---
+name: emcn-design-review
+description: Review UI code for alignment with the emcn design system — components, tokens, patterns, and conventions
+---
+
+# EMCN Design Review
+
+Arguments:
+- scope: what to review (default: your current changes). Examples: "diff to main", "PR #123", "src/components/", "whole codebase"
+- fix: whether to apply fixes (default: true). Set to false to only propose changes.
+
+User arguments: $ARGUMENTS
+
+## Context
+
+This codebase uses **emcn**, a custom component library built on Radix UI primitives with CVA (class-variance-authority) variants and CSS variable design tokens. All UI must use emcn components and tokens — never raw HTML elements or hardcoded colors.
+
+## Steps
+
+1. Read the emcn barrel export at `apps/sim/components/emcn/components/index.ts` to know what's available
+2. Read `apps/sim/app/_styles/globals.css` for the full set of CSS variable tokens
+3. Analyze the specified scope against every rule below
+4. If fix=true, apply the fixes. If fix=false, propose the fixes without applying.
+
+---
+
+## Imports
+
+- Import components from `@/components/emcn`, never from subpaths
+- Import icons from `@/components/emcn/icons` or `lucide-react`
+- Import `cn` from `@/lib/core/utils/cn` for conditional class merging
+- Import app-specific wrappers (Select, VerifiedBadge) from `@/components/ui`
+
+```tsx
+// Good
+import { Button, Modal, Badge } from '@/components/emcn'
+// Bad
+import { Button } from '@/components/emcn/components/button/button'
+```
+
+---
+
+## Design Tokens (CSS Variables)
+
+Never use raw color values. Always use CSS variable tokens via Tailwind arbitrary values: `text-[var(--text-primary)]`, not `text-gray-500` or `#333`. The CSS variable pattern is canonical (1,700+ uses) — do not use Tailwind semantic classes like `text-muted-foreground`.
+
+### Text hierarchy
+| Token | Use |
+|-------|-----|
+| `text-[var(--text-primary)]` | Main content text |
+| `text-[var(--text-secondary)]` | Secondary/supporting text |
+| `text-[var(--text-tertiary)]` | Tertiary text |
+| `text-[var(--text-muted)]` | Disabled, placeholder text |
+| `text-[var(--text-icon)]` | Icon tinting |
+| `text-[var(--text-inverse)]` | Text on dark backgrounds |
+| `text-[var(--text-error)]` | Error/warning messages |
+
+### Surfaces (elevation)
+| Token | Use |
+|-------|-----|
+| `bg-[var(--bg)]` | Page background |
+| `bg-[var(--surface-2)]` through `bg-[var(--surface-7)]` | Increasing elevation |
+| `bg-[var(--surface-hover)]` | Hover state backgrounds |
+| `bg-[var(--surface-active)]` | Active/selected backgrounds |
+
+### Borders
+| Token | Use |
+|-------|-----|
+| `border-[var(--border)]` | Default borders |
+| `border-[var(--border-1)]` | Stronger borders (inputs, cards) |
+| `border-[var(--border-muted)]` | Subtle dividers |
+
+### Status
+| Token | Use |
+|-------|-----|
+| `--success` | Success states |
+| `--error` | Error states |
+| `--caution` | Warning states |
+
+### Brand
+| Token | Use |
+|-------|-----|
+| `--brand-secondary` | Brand color |
+| `--brand-accent` | Accent/CTA color |
+
+### Shadows
+Use shadow tokens, never raw box-shadow values:
+- `shadow-subtle`, `shadow-medium`, `shadow-overlay`
+- `shadow-kbd`, `shadow-card`
+
+### Z-Index
+Use z-index tokens for layering:
+- `z-[var(--z-dropdown)]` (100), `z-[var(--z-modal)]` (200), `z-[var(--z-popover)]` (300), `z-[var(--z-tooltip)]` (400), `z-[var(--z-toast)]` (500)
+
+---
+
+## Component Usage Rules
+
+### Buttons
+Available variants: `default`, `primary`, `destructive`, `ghost`, `outline`, `active`, `secondary`, `tertiary`, `subtle`, `ghost-secondary`, `3d`
+
+| Action type | Variant | Frequency |
+|-------------|---------|-----------|
+| Toolbar, icon-only, utility actions | `ghost` | Most common (28%) |
+| Primary action (create, save, submit) | `primary` | Very common (24%) |
+| Cancel, close, secondary action | `default` | Common |
+| Delete, remove, destructive action | `destructive` | Targeted use only |
+| Active/selected state | `active` | Targeted use only |
+| Toggle, mode switch | `outline` | Moderate |
+
+Sizes: `sm` (compact, 32% of buttons) or `md` (default, used when no size specified). Never create custom button styles — use an existing variant.
+
+Buttons without an explicit variant prop get `default` styling. This is acceptable for cancel/secondary actions.
+
+### Modals (Dialogs)
+Use `Modal` + subcomponents. Never build custom dialog overlays.
+
+```tsx
+<Modal open={open} onOpenChange={setOpen}>
+  <ModalContent size="sm">
+    <ModalHeader>Title</ModalHeader>
+    <ModalBody>Content</ModalBody>
+    <ModalFooter>
+      <Button variant="default" onClick={() => setOpen(false)}>Cancel</Button>
+      <Button variant="primary" onClick={handleSubmit}>Save</Button>
+    </ModalFooter>
+  </ModalContent>
+</Modal>
+```
+
+Modal sizes by frequency: `sm` (440px, most common — confirmations and simple dialogs), `md` (500px, forms), `lg` (600px, content-heavy), `xl` (800px, rare), `full` (1200px, rare).
+
+Footer buttons: Cancel on left (`variant="default"`), primary action on right. This pattern is followed 100% across the codebase.
+
+### Delete/Remove Confirmations
+Always use Modal with `size="sm"`. The established pattern:
+
+```tsx
+<Modal open={open} onOpenChange={setOpen}>
+  <ModalContent size="sm">
+    <ModalHeader>Delete {itemType}</ModalHeader>
+    <ModalBody>
+      <p>Description of consequences</p>
+      <p className="text-[var(--text-error)]">Warning about irreversibility</p>
+    </ModalBody>
+    <ModalFooter>
+      <Button variant="default" onClick={() => setOpen(false)}>Cancel</Button>
+      <Button variant="destructive" onClick={handleDelete} disabled={isDeleting}>
+        Delete
+      </Button>
+    </ModalFooter>
+  </ModalContent>
+</Modal>
+```
+
+Rules:
+- Title: "Delete {ItemType}" or "Remove {ItemType}" (use "Remove" for membership/association changes)
+- Include consequence description
+- Use `text-[var(--text-error)]` for warning text when the action is irreversible
+- `variant="destructive"` for the action button (100% compliance)
+- `variant="default"` for cancel (100% compliance)
+- Cancel left, destructive right (100% compliance)
+- For high-risk deletes (workspaces), require typing the name to confirm
+- Include recovery info if soft-delete: "You can restore it from Recently Deleted in Settings"
+
+### Toast Notifications
+Use the imperative `toast` API from `@/components/emcn`. Never build custom notification UI.
+
+```tsx
+import { toast } from '@/components/emcn'
+
+toast.success('Item saved')
+toast.error('Something went wrong')
+toast.success('Deleted', { action: { label: 'Undo', onClick: handleUndo } })
+```
+
+Variants: `default`, `success`, `error`. Auto-dismiss after 5s. Supports optional action buttons with callbacks.
+
+### Badges
+Use semantic color variants for status:
+
+| Status | Variant | Usage |
+|--------|---------|-------|
+| Error, failed, disconnected | `red` | Most common (15 uses) |
+| Metadata, roles, auth types, scopes | `gray-secondary` | Very common (12 uses) |
+| Type annotations (TS types, field types) | `type` | Very common (12 uses) |
+| Success, active, enabled, running | `green` | Common (7 uses) |
+| Neutral, default, unknown | `gray` | Common (6 uses) |
+| Outline, parameters, public | `outline` | Moderate (6 uses) |
+| Warning, processing | `amber` | Moderate (5 uses) |
+| Paused, warning | `orange` | Occasional |
+| Info, queued | `blue` | Occasional |
+| Data types (arrays) | `purple` | Occasional |
+| Generic with border | `default` | Occasional |
+
+Use `dot` prop for status indicators (19 instances in codebase). `icon` prop is available but rarely used.
+
+### Tooltips
+Use `Tooltip` from emcn with namespace pattern:
+
+```tsx
+<Tooltip.Root>
+  <Tooltip.Trigger asChild>
+    <Button variant="ghost">{icon}</Button>
+  </Tooltip.Trigger>
+  <Tooltip.Content>Helpful text</Tooltip.Content>
+</Tooltip.Root>
+```
+
+Use tooltips for icon-only buttons and truncated text. Don't tooltip self-explanatory elements.
+
+### Popovers
+Use for filters, option menus, and nested navigation:
+
+```tsx
+<Popover open={open} onOpenChange={setOpen} size="sm">
+  <PopoverTrigger asChild>
+    <Button variant="ghost">Trigger</Button>
+  </PopoverTrigger>
+  <PopoverContent side="bottom" align="end" minWidth={160}>
+    <PopoverSection>Section Title</PopoverSection>
+    <PopoverItem active={isActive} onClick={handleClick}>
+      Item Label
+    </PopoverItem>
+    <PopoverDivider />
+  </PopoverContent>
+</Popover>
+```
+
+### Dropdown Menus
+Use for context menus and action menus:
+
+```tsx
+<DropdownMenu>
+  <DropdownMenuTrigger asChild>
+    <Button variant="ghost">
+      <MoreHorizontal className="h-[14px] w-[14px]" />
+    </Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent align="end">
+    <DropdownMenuItem onClick={handleEdit}>Edit</DropdownMenuItem>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem onClick={handleDelete} className="text-[var(--text-error)]">
+      Delete
+    </DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+Destructive items go last, after a separator, in error color.
+
+### Forms
+Use `FormField` wrapper for labeled inputs:
+
+```tsx
+<FormField label="Name" htmlFor="name" error={errors.name} optional>
+  <Input id="name" value={name} onChange={e => setName(e.target.value)} />
+</FormField>
+```
+
+Rules:
+- Use `Input` from emcn, never raw `<input>` (exception: hidden file inputs)
+- Use `Textarea` from emcn, never raw `<textarea>`
+- Use `FormField` for label + input + error layout
+- Mark optional fields with `optional` prop
+- Show errors inline below the input
+- Use `Combobox` for searchable selects
+- Use `TagInput` for multi-value inputs
+
+### Loading States
+Use `Skeleton` for content placeholders:
+
+```tsx
+<Skeleton className="h-5 w-[200px] rounded-md" />
+```
+
+Rules:
+- Mirror the actual UI structure with skeletons
+- Match exact dimensions of the final content
+- Use `rounded-md` to match component radius
+- Stack multiple skeletons for lists
+
+### Icons
+Standard sizing — `h-[14px] w-[14px]` is the dominant pattern (400+ uses):
+
+```tsx
+<Icon className="h-[14px] w-[14px] text-[var(--text-icon)]" />
+```
+
+Size scale by frequency:
+1. `h-[14px] w-[14px]` — default for inline icons (most common)
+2. `h-[16px] w-[16px]` — slightly larger inline icons
+3. `h-3 w-3` (12px) — compact/tight spaces
+4. `h-4 w-4` (16px) — Tailwind equivalent, also common
+5. `h-3.5 w-3.5` (14px) — Tailwind equivalent of 14px
+6. `h-5 w-5` (20px) — larger icons, section headers
+
+Use `text-[var(--text-icon)]` for icon color (113+ uses in codebase).
+
+---
+
+## Styling Rules
+
+1. **Use `cn()` for conditional classes**: `cn('base', condition && 'conditional')` — never template literal concatenation like `` `base ${condition ? 'active' : ''}` ``
+2. **Inline styles**: Avoid. Exception: dynamic values that can't be expressed as Tailwind classes (e.g., `style={{ width: dynamicVar }}` or CSS variable references). Never use inline styles for colors or static values.
+3. **Never hardcode colors**: Use CSS variable tokens. Never `text-gray-500`, `bg-red-100`, `#fff`, or `rgb()`. Always `text-[var(--text-*)]`, `bg-[var(--surface-*)]`, etc.
+4. **Never use Tailwind semantic color classes**: Use `text-[var(--text-muted)]` not `text-muted-foreground`. The CSS variable pattern is canonical.
+5. **Never use global styles**: Keep all styling local to components
+6. **Hover states**: Use `hover-hover:` pseudo-class for hover-capable devices
+7. **Transitions**: Use `transition-colors` for color changes, `transition-colors duration-100` for fast hover
+8. **Border radius**: `rounded-lg` (large cards), `rounded-md` (medium), `rounded-sm` (small), `rounded-xs` (tiny)
+9. **Typography**: Use semantic sizes — `text-small` (13px), `text-caption` (12px), `text-xs` (11px), `text-micro` (10px)
+10. **Font weight**: Use `font-medium` for emphasis, avoid `font-bold` unless for headings
+11. **Spacing**: Use Tailwind gap/padding utilities. Common patterns: `gap-2`, `gap-3`, `px-4 py-2.5`
+
+---
+
+## Anti-patterns to flag
+
+- Raw HTML `<button>` instead of Button component (exception: inside Radix primitives)
+- Raw HTML `<input>` instead of Input component (exception: hidden file inputs, read-only checkboxes in markdown)
+- Hardcoded Tailwind default colors (`text-gray-*`, `bg-red-*`, `text-blue-*`)
+- Hex values in className (`bg-[#fff]`, `text-[#333]`)
+- Tailwind semantic classes (`text-muted-foreground`) instead of CSS variables (`text-[var(--text-muted)]`)
+- Custom modal/dialog implementations instead of `Modal`
+- Custom toast/notification implementations instead of `toast`
+- Inline styles for colors or static values (dynamic values are acceptable)
+- Template literal className concatenation instead of `cn()`
+- Wrong button variant for the action type
+- Missing loading/skeleton states
+- Missing error states on forms
+- Importing from emcn subpaths instead of barrel export
+- Using arbitrary z-index (`z-50`, `z-[9999]`) instead of z-index tokens
+- Custom shadows instead of shadow tokens
+- Icon sizes that don't follow the established scale (default to `h-[14px] w-[14px]`)
--- a/.agents/skills/react-query-best-practices/SKILL.md
+++ b/.agents/skills/react-query-best-practices/SKILL.md
@@ -0,0 +1,54 @@
+---
+name: react-query-best-practices
+description: Audit React Query usage for best practices — key factories, staleTime, mutations, and server state ownership
+---
+
+# React Query Best Practices
+
+Arguments:
+- scope: what to analyze (default: your current changes). Examples: "diff to main", "PR #123", "src/hooks/queries/", "whole codebase"
+- fix: whether to apply fixes (default: true). Set to false to only propose changes.
+
+User arguments: $ARGUMENTS
+
+## Context
+
+This codebase uses React Query (TanStack Query) as the single source of truth for all server state. All query hooks live in `hooks/queries/`. Zustand is used only for client-only UI state. Server data must never be duplicated into useState or Zustand outside of mutation callbacks that coordinate cross-store state.
+
+## References
+
+Read these before analyzing:
+1. https://tkdodo.eu/blog/practical-react-query — foundational defaults, custom hooks, avoiding local state copies
+2. https://tkdodo.eu/blog/effective-react-query-keys — key factory pattern, hierarchical keys, fuzzy invalidation
+3. https://tkdodo.eu/blog/react-query-as-a-state-manager — React Query IS your server state manager
+
+## Rules to enforce
+
+### Query key factories
+- Every file in `hooks/queries/` must have a hierarchical key factory with an `all` root key
+- Keys must include intermediate plural keys (`lists`, `details`) for prefix invalidation
+- Key factories are colocated with their query hooks, not in a global keys file
+
+### Query hooks
+- Every `queryFn` must forward `signal` for request cancellation
+- Every query must have an explicit `staleTime` (default 0 is almost never correct)
+- `keepPreviousData` / `placeholderData` only on variable-key queries (where params change), never on static keys
+- Use `enabled` to prevent queries from running without required params
+
+### Mutations
+- Use `onSettled` (not `onSuccess`) for cache reconciliation — it fires on both success and error
+- For optimistic updates: save previous data in `onMutate`, roll back in `onError`
+- Use targeted invalidation (`entityKeys.lists()`) not broad (`entityKeys.all`) when possible
+- Don't include mutation objects in `useCallback` deps — `.mutate()` is stable
+
+### Server state ownership
+- Never copy query data into useState. Use query data directly in components.
+- Never copy query data into Zustand stores (exception: mutation callbacks that coordinate cross-store state like temp ID replacement)
+- The query cache is not a local state manager — `setQueryData` is for optimistic updates only
+- Forms are the one deliberate exception: copy server data into local form state with `staleTime: Infinity`
+
+## Steps
+
+1. Read the references above to understand the guidelines
+2. Analyze the specified scope against the rules listed above
+3. If fix=true, apply the fixes. If fix=false, propose the fixes without applying.
--- a/.agents/skills/validate-connector/SKILL.md
+++ b/.agents/skills/validate-connector/SKILL.md
@@ -0,0 +1,349 @@
+---
+name: validate-connector
+description: Audit an existing Sim knowledge base connector against the service API docs and repository conventions, then report and fix issues in auth, config fields, pagination, document mapping, tags, and registry entries. Use when validating or repairing code in `apps/sim/connectors/{service}/`.
+---
+
+# Validate Connector Skill
+
+You are an expert auditor for Sim knowledge base connectors. Your job is to thoroughly validate that an existing connector is correct, complete, and follows all conventions.
+
+## Your Task
+
+When the user asks you to validate a connector:
+1. Read the service's API documentation (via Context7 or WebFetch)
+2. Read the connector implementation, OAuth config, and registry entries
+3. Cross-reference everything against the API docs and Sim conventions
+4. Report all issues found, grouped by severity (critical, warning, suggestion)
+5. Fix all issues after reporting them
+
+## Step 1: Gather All Files
+
+Read **every** file for the connector — do not skip any:
+
+```
+apps/sim/connectors/{service}/{service}.ts   # Connector implementation
+apps/sim/connectors/{service}/index.ts       # Barrel export
+apps/sim/connectors/registry.ts              # Connector registry entry
+apps/sim/connectors/types.ts                 # ConnectorConfig interface, ExternalDocument, etc.
+apps/sim/connectors/utils.ts                 # Shared utilities (computeContentHash, htmlToPlainText, etc.)
+apps/sim/lib/oauth/oauth.ts                  # OAUTH_PROVIDERS — single source of truth for scopes
+apps/sim/lib/oauth/utils.ts                  # getCanonicalScopesForProvider, getScopesForService, SCOPE_DESCRIPTIONS
+apps/sim/lib/oauth/types.ts                  # OAuthService union type
+apps/sim/components/icons.tsx                 # Icon definition for the service
+```
+
+If the connector uses selectors, also read:
+```
+apps/sim/hooks/selectors/registry.ts         # Selector key definitions
+apps/sim/hooks/selectors/types.ts            # SelectorKey union type
+apps/sim/lib/workflows/subblocks/context.ts  # SELECTOR_CONTEXT_FIELDS
+```
+
+## Step 2: Pull API Documentation
+
+Fetch the official API docs for the service. This is the **source of truth** for:
+- Endpoint URLs, HTTP methods, and auth headers
+- Required vs optional parameters
+- Parameter types and allowed values
+- Response shapes and field names
+- Pagination patterns (cursor, offset, next token)
+- Rate limits and error formats
+- OAuth scopes and their meanings
+
+Use Context7 (resolve-library-id → query-docs) or WebFetch to retrieve documentation. If both fail, note which claims are based on training knowledge vs verified docs.
+
+### Hard Rule: No Guessed Source Schemas
+
+If the service docs do not clearly show document list responses, document fetch responses, metadata fields, or pagination shapes, you MUST tell the user instead of guessing.
+
+- Do NOT infer document fields from unrelated endpoints
+- Do NOT guess pagination cursors or response wrappers
+- Do NOT assume metadata keys that are not documented
+- Do NOT treat probable shapes as validated
+
+If a schema is unknown, validation must explicitly recommend:
+1. sample API responses,
+2. live test credentials, or
+3. trimming the connector to only documented fields.
+
+## Step 3: Validate API Endpoints
+
+For **every** API call in the connector (`listDocuments`, `getDocument`, `validateConfig`, and any helper functions), verify against the API docs:
+
+### URLs and Methods
+- [ ] Base URL is correct for the service's API version
+- [ ] Endpoint paths match the API docs exactly
+- [ ] HTTP method is correct (GET, POST, PUT, PATCH, DELETE)
+- [ ] Path parameters are correctly interpolated and URI-encoded where needed
+- [ ] Query parameters use correct names and formats per the API docs
+
+### Headers
+- [ ] Authorization header uses the correct format:
+  - OAuth: `Authorization: Bearer ${accessToken}`
+  - API Key: correct header name per the service's docs
+- [ ] `Content-Type` is set for POST/PUT/PATCH requests
+- [ ] Any service-specific headers are present (e.g., `Notion-Version`, `Dropbox-API-Arg`)
+- [ ] No headers are sent that the API doesn't support or silently ignores
+
+### Request Bodies
+- [ ] POST/PUT body fields match API parameter names exactly
+- [ ] Required fields are always sent
+- [ ] Optional fields are conditionally included (not sent as `null` or empty unless the API expects that)
+- [ ] Field value types match API expectations (string vs number vs boolean)
+
+### Input Sanitization
+- [ ] User-controlled values interpolated into query strings are properly escaped:
+  - OData `$filter`: single quotes escaped with `''` (e.g., `externalId.replace(/'/g, "''")`)
+  - SOQL: single quotes escaped with `\'`
+  - GraphQL variables: passed as variables, not interpolated into query strings
+  - URL path segments: `encodeURIComponent()` applied
+- [ ] URL-type config fields (e.g., `siteUrl`, `instanceUrl`) are normalized:
+  - Strip `https://` / `http://` prefix if the API expects bare domains
+  - Strip trailing `/`
+  - Apply `.trim()` before validation
+
+### Response Parsing
+- [ ] Response structure is correctly traversed (e.g., `data.results` vs `data.items` vs `data`)
+- [ ] Field names extracted match what the API actually returns
+- [ ] Nullable fields are handled with `?? null` or `|| undefined`
+- [ ] Error responses are checked before accessing data fields
+- [ ] Every extracted field and pagination value is backed by official docs or live-verified sample payloads
+
+## Step 4: Validate OAuth Scopes (if OAuth connector)
+
+Scopes must be correctly declared and sufficient for all API calls the connector makes.
+
+### Connector requiredScopes
+- [ ] `requiredScopes` in the connector's `auth` config lists all scopes needed by the connector
+- [ ] Each scope in `requiredScopes` is a real, valid scope recognized by the service's API
+- [ ] No invalid, deprecated, or made-up scopes are listed
+- [ ] No unnecessary excess scopes beyond what the connector actually needs
+
+### Scope Subset Validation (CRITICAL)
+- [ ] Every scope in `requiredScopes` exists in the OAuth provider's `scopes` array in `lib/oauth/oauth.ts`
+- [ ] Find the provider in `OAUTH_PROVIDERS[providerGroup].services[serviceId].scopes`
+- [ ] Verify: `requiredScopes` ⊆ `OAUTH_PROVIDERS scopes` (every required scope is present in the provider config)
+- [ ] If a required scope is NOT in the provider config, flag as **critical** — the connector will fail at runtime
+
+### Scope Sufficiency
+For each API endpoint the connector calls:
+- [ ] Identify which scopes are required per the API docs
+- [ ] Verify those scopes are included in the connector's `requiredScopes`
+- [ ] If the connector calls endpoints requiring scopes not in `requiredScopes`, flag as **warning**
+
+### Token Refresh Config
+- [ ] Check the `getOAuthTokenRefreshConfig` function in `lib/oauth/oauth.ts` for this provider
+- [ ] `useBasicAuth` matches the service's token exchange requirements
+- [ ] `supportsRefreshTokenRotation` matches whether the service issues rotating refresh tokens
+- [ ] Token endpoint URL is correct
+
+## Step 5: Validate Pagination
+
+### listDocuments Pagination
+- [ ] Cursor/pagination parameter name matches the API docs
+- [ ] Response pagination field is correctly extracted (e.g., `next_cursor`, `nextPageToken`, `@odata.nextLink`, `offset`)
+- [ ] `hasMore` is correctly determined from the response
+- [ ] `nextCursor` is correctly passed back for the next page
+- [ ] `maxItems` / `maxRecords` cap is correctly applied across pages using `syncContext.totalDocsFetched`
+- [ ] Page size is within the API's allowed range (not exceeding max page size)
+- [ ] Last page precision: when a `maxItems` cap exists, the final page request uses `Math.min(PAGE_SIZE, remaining)` to avoid fetching more records than needed
+- [ ] No off-by-one errors in pagination tracking
+- [ ] The connector does NOT hit known API pagination limits silently (e.g., HubSpot search 10k cap)
+
+### Pagination State Across Pages
+- [ ] `syncContext` is used to cache state across pages (user names, field maps, instance URLs, portal IDs, etc.)
+- [ ] Cached state in `syncContext` is correctly initialized on first page and reused on subsequent pages
+
+## Step 6: Validate Data Transformation
+
+### Content Deferral (CRITICAL)
+Connectors that require per-document API calls to fetch content (file download, export, blocks fetch) MUST use `contentDeferred: true`. This is the standard pattern for reliability — without it, content downloads during listing can exhaust the sync task's time budget before any documents are saved.
+
+- [ ] If the connector downloads content per-doc during `listDocuments`, it MUST use `contentDeferred: true` instead
+- [ ] `listDocuments` returns lightweight stubs with `content: ''` and `contentDeferred: true`
+- [ ] `getDocument` fetches actual content and returns the full document with `contentDeferred: false`
+- [ ] A shared stub function (e.g., `fileToStub`) is used by both `listDocuments` and `getDocument` to guarantee `contentHash` consistency
+- [ ] `contentHash` is metadata-based (e.g., `service:{id}:{modifiedTime}`), NOT content-based — it must be derivable from list metadata alone
+- [ ] The `contentHash` is identical whether produced by `listDocuments` or `getDocument`
+
+Connectors where the list API already returns content inline (e.g., Slack messages, Reddit posts) do NOT need `contentDeferred`.
+
+### ExternalDocument Construction
+- [ ] `externalId` is a stable, unique identifier from the source API
+- [ ] `title` is extracted from the correct field and has a sensible fallback (e.g., `'Untitled'`)
+- [ ] `content` is plain text — HTML content is stripped using `htmlToPlainText` from `@/connectors/utils`
+- [ ] `mimeType` is `'text/plain'`
+- [ ] `contentHash` uses a metadata-based format (e.g., `service:{id}:{modifiedTime}`) for connectors with `contentDeferred: true`, or `computeContentHash` from `@/connectors/utils` for inline-content connectors
+- [ ] `sourceUrl` is a valid, complete URL back to the original resource (not relative)
+- [ ] `metadata` contains all fields referenced by `mapTags` and `tagDefinitions`
+
+### Content Extraction
+- [ ] Rich text / HTML fields are converted to plain text before indexing
+- [ ] Important content is not silently dropped (e.g., nested blocks, table cells, code blocks)
+- [ ] Content is not silently truncated without logging a warning
+- [ ] Empty/blank documents are properly filtered out
+- [ ] Size checks use `Buffer.byteLength(text, 'utf8')` not `text.length` when comparing against byte-based limits (e.g., `MAX_FILE_SIZE` in bytes)
+
+## Step 7: Validate Tag Definitions and mapTags
+
+### tagDefinitions
+- [ ] Each `tagDefinition` has an `id`, `displayName`, and `fieldType`
+- [ ] `fieldType` matches the actual data type: `'text'` for strings, `'number'` for numbers, `'date'` for dates, `'boolean'` for booleans
+- [ ] Every `id` in `tagDefinitions` is returned by `mapTags`
+- [ ] No `tagDefinition` references a field that `mapTags` never produces
+
+### mapTags
+- [ ] Return keys match `tagDefinition` `id` values exactly
+- [ ] Date values are properly parsed using `parseTagDate` from `@/connectors/utils`
+- [ ] Array values are properly joined using `joinTagArray` from `@/connectors/utils`
+- [ ] Number values are validated (not `NaN`)
+- [ ] Metadata field names accessed in `mapTags` match what `listDocuments`/`getDocument` store in `metadata`
+
+## Step 8: Validate Config Fields and Validation
+
+### configFields
+- [ ] Every field has `id`, `title`, `type`
+- [ ] `required` is set explicitly (not omitted)
+- [ ] Dropdown fields have `options` with `label` and `id` for each option
+- [ ] Selector fields follow the canonical pair pattern:
+  - A `type: 'selector'` field with `selectorKey`, `canonicalParamId`, `mode: 'basic'`
+  - A `type: 'short-input'` field with the same `canonicalParamId`, `mode: 'advanced'`
+  - `required` is identical on both fields in the pair
+- [ ] `selectorKey` values exist in the selector registry
+- [ ] `dependsOn` references selector field `id` values, not `canonicalParamId`
+
+### validateConfig
+- [ ] Validates all required fields are present before making API calls
+- [ ] Validates optional numeric fields (checks `Number.isNaN`, positive values)
+- [ ] Makes a lightweight API call to verify access (e.g., fetch 1 record, get profile)
+- [ ] Uses `VALIDATE_RETRY_OPTIONS` for retry budget
+- [ ] Returns `{ valid: true }` on success
+- [ ] Returns `{ valid: false, error: 'descriptive message' }` on failure
+- [ ] Catches exceptions and returns user-friendly error messages
+- [ ] Does NOT make expensive calls (full data listing, large queries)
+
+## Step 9: Validate getDocument
+
+- [ ] Fetches a single document by `externalId`
+- [ ] Returns `null` for 404 / not found (does not throw)
+- [ ] Returns the same `ExternalDocument` shape as `listDocuments`
+- [ ] If `listDocuments` uses `contentDeferred: true`, `getDocument` MUST fetch actual content and return `contentDeferred: false`
+- [ ] If `listDocuments` uses `contentDeferred: true`, `getDocument` MUST use the same stub function to ensure `contentHash` is identical
+- [ ] Handles all content types that `listDocuments` can produce (e.g., if `listDocuments` returns both pages and blogposts, `getDocument` must handle both — not hardcode one endpoint)
+- [ ] Forwards `syncContext` if it needs cached state (user names, field maps, etc.)
+- [ ] Error handling is graceful (catches, logs, returns null or throws with context)
+- [ ] Does not redundantly re-fetch data already included in the initial API response (e.g., if comments come back with the post, don't fetch them again separately)
+
+## Step 10: Validate General Quality
+
+### fetchWithRetry Usage
+- [ ] All external API calls use `fetchWithRetry` from `@/lib/knowledge/documents/utils`
+- [ ] No raw `fetch()` calls to external APIs
+- [ ] `VALIDATE_RETRY_OPTIONS` used in `validateConfig`
+- [ ] If `validateConfig` calls a shared helper (e.g., `linearGraphQL`, `resolveId`), that helper must accept and forward `retryOptions` to `fetchWithRetry`
+- [ ] Default retry options used in `listDocuments`/`getDocument`
+
+### API Efficiency
+- [ ] APIs that support field selection (e.g., `$select`, `sysparm_fields`, `fields`) should request only the fields the connector needs — in both `listDocuments` AND `getDocument`
+- [ ] No redundant API calls: if a helper already fetches data (e.g., site metadata), callers should reuse the result instead of making a second call for the same information
+- [ ] Sequential per-item API calls (fetching details for each document in a loop) should be batched with `Promise.all` and a concurrency limit of 3-5
+
+### Error Handling
+- [ ] Individual document failures are caught and logged without aborting the sync
+- [ ] API error responses include status codes in error messages
+- [ ] No unhandled promise rejections in concurrent operations
+
+### Concurrency
+- [ ] Concurrent API calls use reasonable batch sizes (3-5 is typical)
+- [ ] No unbounded `Promise.all` over large arrays
+
+### Logging
+- [ ] Uses `createLogger` from `@sim/logger` (not `console.log`)
+- [ ] Logs sync progress at `info` level
+- [ ] Logs errors at `warn` or `error` level with context
+
+### Registry
+- [ ] Connector is exported from `connectors/{service}/index.ts`
+- [ ] Connector is registered in `connectors/registry.ts`
+- [ ] Registry key matches the connector's `id` field
+
+## Step 11: Report and Fix
+
+### Report Format
+
+Group findings by severity:
+
+**Critical** (will cause runtime errors, data loss, or auth failures):
+- Wrong API endpoint URL or HTTP method
+- Invalid or missing OAuth scopes (not in provider config)
+- Incorrect response field mapping (accessing wrong path)
+- SOQL/query fields that don't exist on the target object
+- Pagination that silently hits undocumented API limits
+- Missing error handling that would crash the sync
+- `requiredScopes` not a subset of OAuth provider scopes
+- Query/filter injection: user-controlled values interpolated into OData `$filter`, SOQL, or query strings without escaping
+- Per-document content download in `listDocuments` without `contentDeferred: true` — causes sync timeouts for large document sets
+- `contentHash` mismatch between `listDocuments` stub and `getDocument` return — causes unnecessary re-processing every sync
+
+**Warning** (incorrect behavior, data quality issues, or convention violations):
+- HTML content not stripped via `htmlToPlainText`
+- `getDocument` not forwarding `syncContext`
+- `getDocument` hardcoded to one content type when `listDocuments` returns multiple (e.g., only pages but not blogposts)
+- Missing `tagDefinition` for metadata fields returned by `mapTags`
+- Incorrect `useBasicAuth` or `supportsRefreshTokenRotation` in token refresh config
+- Invalid scope names that the API doesn't recognize (even if silently ignored)
+- Private resources excluded from name-based lookup despite scopes being available
+- Silent data truncation without logging
+- Size checks using `text.length` (character count) instead of `Buffer.byteLength` (byte count) for byte-based limits
+- URL-type config fields not normalized (protocol prefix, trailing slashes cause API failures)
+- `VALIDATE_RETRY_OPTIONS` not threaded through helper functions called by `validateConfig`
+
+**Suggestion** (minor improvements):
+- Missing incremental sync support despite API supporting it
+- Overly broad scopes that could be narrowed (not wrong, but could be tighter)
+- Source URL format could be more specific
+- Missing `orderBy` for deterministic pagination
+- Redundant API calls that could be cached in `syncContext`
+- Sequential per-item API calls that could be batched with `Promise.all` (concurrency 3-5)
+- API supports field selection but connector fetches all fields (e.g., missing `$select`, `sysparm_fields`, `fields`)
+- `getDocument` re-fetches data already included in the initial API response (e.g., comments returned with post)
+- Last page of pagination requests full `PAGE_SIZE` when fewer records remain (`Math.min(PAGE_SIZE, remaining)`)
+
+### Fix All Issues
+
+After reporting, fix every **critical** and **warning** issue. Apply **suggestions** where they don't add unnecessary complexity.
+
+### Validation Output
+
+After fixing, confirm:
+1. `bun run lint` passes
+2. TypeScript compiles clean
+3. Re-read all modified files to verify fixes are correct
+4. Any remaining unknown source schemas were explicitly reported to the user instead of guessed
+
+## Checklist Summary
+
+- [ ] Read connector implementation, types, utils, registry, and OAuth config
+- [ ] Pulled and read official API documentation for the service
+- [ ] Validated every API endpoint URL, method, headers, and body against API docs
+- [ ] Validated input sanitization: no query/filter injection, URL fields normalized
+- [ ] Validated OAuth scopes: `requiredScopes` ⊆ OAuth provider `scopes` in `oauth.ts`
+- [ ] Validated each scope is real and recognized by the service's API
+- [ ] Validated scopes are sufficient for all API endpoints the connector calls
+- [ ] Validated token refresh config (`useBasicAuth`, `supportsRefreshTokenRotation`)
+- [ ] Validated pagination: cursor names, page sizes, hasMore logic, no silent caps
+- [ ] Validated content deferral: `contentDeferred: true` used when per-doc content fetch required, metadata-based `contentHash` consistent between stub and `getDocument`
+- [ ] Validated data transformation: plain text extraction, HTML stripping, content hashing
+- [ ] Validated tag definitions match mapTags output, correct fieldTypes
+- [ ] Validated config fields: canonical pairs, selector keys, required flags
+- [ ] Validated validateConfig: lightweight check, error messages, retry options
+- [ ] Validated getDocument: null on 404, all content types handled, no redundant re-fetches, syncContext forwarding
+- [ ] Validated fetchWithRetry used for all external calls (no raw fetch), VALIDATE_RETRY_OPTIONS threaded through helpers
+- [ ] Validated API efficiency: field selection used, no redundant calls, sequential fetches batched
+- [ ] Validated error handling: graceful failures, no unhandled rejections
+- [ ] Validated logging: createLogger, no console.log
+- [ ] Validated registry: correct export, correct key
+- [ ] Reported all issues grouped by severity
+- [ ] Fixed all critical and warning issues
+- [ ] Ran `bun run lint` after fixes
+- [ ] Verified TypeScript compiles clean
--- a/.agents/skills/validate-connector/agents/openai.yaml
+++ b/.agents/skills/validate-connector/agents/openai.yaml
@@ -0,0 +1,5 @@
+interface:
+  display_name: "Validate Connector"
+  short_description: "Audit a Sim knowledge connector"
+  brand_color: "#059669"
+  default_prompt: "Use $validate-connector to audit and fix a Sim knowledge connector against its API docs."
--- a/.agents/skills/validate-integration/SKILL.md
+++ b/.agents/skills/validate-integration/SKILL.md
@@ -0,0 +1,305 @@
+---
+name: validate-integration
+description: Audit an existing Sim integration against the service API docs and repository conventions, then report and fix issues across tools, blocks, outputs, OAuth scopes, triggers, and registry entries. Use when validating or repairing a service integration under `apps/sim/tools`, `apps/sim/blocks`, or `apps/sim/triggers`.
+---
+
+# Validate Integration Skill
+
+You are an expert auditor for Sim integrations. Your job is to thoroughly validate that an existing integration is correct, complete, and follows all conventions.
+
+## Your Task
+
+When the user asks you to validate an integration:
+1. Read the service's API documentation (via WebFetch or Context7)
+2. Read every tool, the block, and registry entries
+3. Cross-reference everything against the API docs and Sim conventions
+4. Report all issues found, grouped by severity (critical, warning, suggestion)
+5. Fix all issues after reporting them
+
+## Step 1: Gather All Files
+
+Read **every** file for the integration — do not skip any:
+
+```
+apps/sim/tools/{service}/          # All tool files, types.ts, index.ts
+apps/sim/blocks/blocks/{service}.ts # Block definition
+apps/sim/tools/registry.ts          # Tool registry entries for this service
+apps/sim/blocks/registry.ts         # Block registry entry for this service
+apps/sim/components/icons.tsx        # Icon definition
+apps/sim/lib/auth/auth.ts           # OAuth config — should use getCanonicalScopesForProvider()
+apps/sim/lib/oauth/oauth.ts         # OAuth provider config — single source of truth for scopes
+apps/sim/lib/oauth/utils.ts               # Scope utilities, SCOPE_DESCRIPTIONS for modal UI
+```
+
+## Step 2: Pull API Documentation
+
+Fetch the official API docs for the service. This is the **source of truth** for:
+- Endpoint URLs, HTTP methods, and auth headers
+- Required vs optional parameters
+- Parameter types and allowed values
+- Response shapes and field names
+- Pagination patterns (which param name, which response field)
+- Rate limits and error formats
+
+### Hard Rule: No Guessed Response Schemas
+
+If the official docs do not clearly show the response JSON shape for an endpoint, you MUST tell the user instead of guessing.
+
+- Do NOT assume field names from nearby endpoints
+- Do NOT infer nested JSON paths without evidence
+- Do NOT treat "likely" fields as confirmed outputs
+- Do NOT accept implementation guesses as valid just because they are defensive
+
+If a response schema is unknown, the validation must explicitly call that out and require:
+1. sample responses from the user,
+2. live test credentials for verification, or
+3. trimming the tool/block down to only documented fields.
+
+## Step 3: Validate Tools
+
+For **every** tool file, check:
+
+### Tool ID and Naming
+- [ ] Tool ID uses `snake_case`: `{service}_{action}` (e.g., `x_create_tweet`, `slack_send_message`)
+- [ ] Tool `name` is human-readable (e.g., `'X Create Tweet'`)
+- [ ] Tool `description` is a concise one-liner describing what it does
+- [ ] Tool `version` is set (`'1.0.0'` or `'2.0.0'` for V2)
+
+### Params
+- [ ] All required API params are marked `required: true`
+- [ ] All optional API params are marked `required: false`
+- [ ] Every param has explicit `required: true` or `required: false` — never omitted
+- [ ] Param types match the API (`'string'`, `'number'`, `'boolean'`, `'json'`)
+- [ ] Visibility is correct:
+  - `'hidden'` — ONLY for OAuth access tokens and system-injected params
+  - `'user-only'` — for API keys, credentials, and account-specific IDs the user must provide
+  - `'user-or-llm'` — for everything else (search queries, content, filters, IDs that could come from other blocks)
+- [ ] Every param has a `description` that explains what it does
+
+### Request
+- [ ] URL matches the API endpoint exactly (correct base URL, path segments, path params)
+- [ ] HTTP method matches the API spec (GET, POST, PUT, PATCH, DELETE)
+- [ ] Headers include correct auth pattern:
+  - OAuth: `Authorization: Bearer ${params.accessToken}`
+  - API Key: correct header name and format per the service's docs
+- [ ] `Content-Type` header is set for POST/PUT/PATCH requests
+- [ ] Body sends all required fields and only includes optional fields when provided
+- [ ] For GET requests with query params: URL is constructed correctly with query string
+- [ ] ID fields in URL paths are `.trim()`-ed to prevent copy-paste whitespace errors
+- [ ] Path params use template literals correctly: `` `https://api.service.com/v1/${params.id.trim()}` ``
+
+### Response / transformResponse
+- [ ] Correctly parses the API response (`await response.json()`)
+- [ ] Extracts the right fields from the response structure (e.g., `data.data` vs `data` vs `data.results`)
+- [ ] All nullable fields use `?? null`
+- [ ] All optional arrays use `?? []`
+- [ ] Error cases are handled: checks for missing/empty data and returns meaningful error
+- [ ] Does NOT do raw JSON dumps — extracts meaningful, individual fields
+- [ ] Every extracted field is backed by official docs or live-verified sample payloads
+
+### Outputs
+- [ ] All output fields match what the API actually returns
+- [ ] No fields are missing that the API provides and users would commonly need
+- [ ] No phantom fields defined that the API doesn't return
+- [ ] `optional: true` is set on fields that may not exist in all responses
+- [ ] When using `type: 'json'` and the shape is known, `properties` defines the inner fields
+- [ ] When using `type: 'array'`, `items` defines the item structure with `properties`
+- [ ] Field descriptions are accurate and helpful
+
+### Types (types.ts)
+- [ ] Has param interfaces for every tool (e.g., `XCreateTweetParams`)
+- [ ] Has response interfaces for every tool (extending `ToolResponse`)
+- [ ] Optional params use `?` in the interface (e.g., `replyTo?: string`)
+- [ ] Field names in types match actual API field names
+- [ ] Shared response types are properly reused (e.g., `XTweetResponse` shared across tweet tools)
+
+### Barrel Export (index.ts)
+- [ ] Every tool is exported
+- [ ] All types are re-exported (`export * from './types'`)
+- [ ] No orphaned exports (tools that don't exist)
+
+### Tool Registry (tools/registry.ts)
+- [ ] Every tool is imported and registered
+- [ ] Registry keys use snake_case and match tool IDs exactly
+- [ ] Entries are in alphabetical order within the file
+
+## Step 4: Validate Block
+
+### Block ↔ Tool Alignment (CRITICAL)
+
+This is the most important validation — the block must be perfectly aligned with every tool it references.
+
+For **each tool** in `tools.access`:
+- [ ] The operation dropdown has an option whose ID matches the tool ID (or the `tools.config.tool` function correctly maps to it)
+- [ ] Every **required** tool param (except `accessToken`) has a corresponding subBlock input that is:
+  - Shown when that operation is selected (correct `condition`)
+  - Marked as `required: true` (or conditionally required)
+- [ ] Every **optional** tool param has a corresponding subBlock input (or is intentionally omitted if truly never needed)
+- [ ] SubBlock `id` values are unique across the entire block — no duplicates even across different conditions
+- [ ] The `tools.config.tool` function returns the correct tool ID for every possible operation value
+- [ ] The `tools.config.params` function correctly maps subBlock IDs to tool param names when they differ
+
+### SubBlocks
+- [ ] Operation dropdown lists ALL tool operations available in `tools.access`
+- [ ] Dropdown option labels are human-readable and descriptive
+- [ ] Conditions use correct syntax:
+  - Single value: `{ field: 'operation', value: 'x_create_tweet' }`
+  - Multiple values (OR): `{ field: 'operation', value: ['x_create_tweet', 'x_delete_tweet'] }`
+  - Negation: `{ field: 'operation', value: 'delete', not: true }`
+  - Compound: `{ field: 'op', value: 'send', and: { field: 'type', value: 'dm' } }`
+- [ ] Condition arrays include ALL operations that use that field — none missing
+- [ ] `dependsOn` is set for fields that need other values (selectors depending on credential, cascading dropdowns)
+- [ ] SubBlock types match tool param types:
+  - Enum/fixed options → `dropdown`
+  - Free text → `short-input`
+  - Long text/content → `long-input`
+  - True/false → `dropdown` with Yes/No options (not `switch` unless purely UI toggle)
+  - Credentials → `oauth-input` with correct `serviceId`
+- [ ] Dropdown `value: () => 'default'` is set for dropdowns with a sensible default
+
+### Advanced Mode
+- [ ] Optional, rarely-used fields are set to `mode: 'advanced'`:
+  - Pagination tokens / next tokens
+  - Time range filters (start/end time)
+  - Sort order / direction options
+  - Max results / per page limits
+  - Reply settings / threading options
+  - Rarely used IDs (reply-to, quote-tweet, etc.)
+  - Exclude filters
+- [ ] **Required** fields are NEVER set to `mode: 'advanced'`
+- [ ] Fields that users fill in most of the time are NOT set to `mode: 'advanced'`
+
+### WandConfig
+- [ ] Timestamp fields have `wandConfig` with `generationType: 'timestamp'`
+- [ ] Comma-separated list fields have `wandConfig` with a descriptive prompt
+- [ ] Complex filter/query fields have `wandConfig` with format examples in the prompt
+- [ ] All `wandConfig` prompts end with "Return ONLY the [format] - no explanations, no extra text."
+- [ ] `wandConfig.placeholder` describes what to type in natural language
+
+### Tools Config
+- [ ] `tools.access` lists **every** tool ID the block can use — none missing
+- [ ] `tools.config.tool` returns the correct tool ID for each operation
+- [ ] Type coercions are in `tools.config.params` (runs at execution time), NOT in `tools.config.tool` (runs at serialization time before variable resolution)
+- [ ] `tools.config.params` handles:
+  - `Number()` conversion for numeric params that come as strings from inputs
+  - `Boolean` / string-to-boolean conversion for toggle params
+  - Empty string → `undefined` conversion for optional dropdown values
+  - Any subBlock ID → tool param name remapping
+- [ ] No `Number()`, `JSON.parse()`, or other coercions in `tools.config.tool` — these would destroy dynamic references like `<Block.output>`
+
+### Block Outputs
+- [ ] Outputs cover the key fields returned by ALL tools (not just one operation)
+- [ ] Output types are correct (`'string'`, `'number'`, `'boolean'`, `'json'`)
+- [ ] `type: 'json'` outputs either:
+  - Describe inner fields in the description string (GOOD): `'User profile (id, name, username, bio)'`
+  - Use nested output definitions (BEST): `{ id: { type: 'string' }, name: { type: 'string' } }`
+- [ ] No opaque `type: 'json'` with vague descriptions like `'Response data'`
+- [ ] Outputs that only appear for certain operations use `condition` if supported, or document which operations return them
+
+### Block Metadata
+- [ ] `type` is snake_case (e.g., `'x'`, `'cloudflare'`)
+- [ ] `name` is human-readable (e.g., `'X'`, `'Cloudflare'`)
+- [ ] `description` is a concise one-liner
+- [ ] `longDescription` provides detail for docs
+- [ ] `docsLink` points to `'https://docs.sim.ai/tools/{service}'`
+- [ ] `category` is `'tools'`
+- [ ] `bgColor` uses the service's brand color hex
+- [ ] `icon` references the correct icon component from `@/components/icons`
+- [ ] `authMode` is set correctly (`AuthMode.OAuth` or `AuthMode.ApiKey`)
+- [ ] Block is registered in `blocks/registry.ts` alphabetically
+
+### Block Inputs
+- [ ] `inputs` section lists all subBlock params that the block accepts
+- [ ] Input types match the subBlock types
+- [ ] When using `canonicalParamId`, inputs list the canonical ID (not the raw subBlock IDs)
+
+## Step 5: Validate OAuth Scopes (if OAuth service)
+
+Scopes are centralized — the single source of truth is `OAUTH_PROVIDERS` in `lib/oauth/oauth.ts`.
+
+- [ ] Scopes defined in `lib/oauth/oauth.ts` under `OAUTH_PROVIDERS[provider].services[service].scopes`
+- [ ] `auth.ts` uses `getCanonicalScopesForProvider(providerId)` — NOT a hardcoded array
+- [ ] Block `requiredScopes` uses `getScopesForService(serviceId)` — NOT a hardcoded array
+- [ ] No hardcoded scope arrays in `auth.ts` or block files (should all use utility functions)
+- [ ] Each scope has a human-readable description in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts`
+- [ ] No excess scopes that aren't needed by any tool
+
+## Step 6: Validate Pagination Consistency
+
+If any tools support pagination:
+- [ ] Pagination param names match the API docs (e.g., `pagination_token` vs `next_token` vs `cursor`)
+- [ ] Different API endpoints that use different pagination param names have separate subBlocks in the block
+- [ ] Pagination response fields (`nextToken`, `cursor`, etc.) are included in tool outputs
+- [ ] Pagination subBlocks are set to `mode: 'advanced'`
+
+## Step 7: Validate Error Handling
+
+- [ ] `transformResponse` checks for error conditions before accessing data
+- [ ] Error responses include meaningful messages (not just generic "failed")
+- [ ] HTTP error status codes are handled (check `response.ok` or status codes)
+
+## Step 8: Report and Fix
+
+### Report Format
+
+Group findings by severity:
+
+**Critical** (will cause runtime errors or incorrect behavior):
+- Wrong endpoint URL or HTTP method
+- Missing required params or wrong `required` flag
+- Incorrect response field mapping (accessing wrong path in response)
+- Missing error handling that would cause crashes
+- Tool ID mismatch between tool file, registry, and block `tools.access`
+- OAuth scopes missing in `auth.ts` that tools need
+- `tools.config.tool` returning wrong tool ID for an operation
+- Type coercions in `tools.config.tool` instead of `tools.config.params`
+
+**Warning** (follows conventions incorrectly or has usability issues):
+- Optional field not set to `mode: 'advanced'`
+- Missing `wandConfig` on timestamp/complex fields
+- Wrong `visibility` on params (e.g., `'hidden'` instead of `'user-or-llm'`)
+- Missing `optional: true` on nullable outputs
+- Opaque `type: 'json'` without property descriptions
+- Missing `.trim()` on ID fields in request URLs
+- Missing `?? null` on nullable response fields
+- Block condition array missing an operation that uses that field
+- Hardcoded scope arrays instead of using `getScopesForService()` / `getCanonicalScopesForProvider()`
+- Missing scope description in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts`
+
+**Suggestion** (minor improvements):
+- Better description text
+- Inconsistent naming across tools
+- Missing `longDescription` or `docsLink`
+- Pagination fields that could benefit from `wandConfig`
+
+### Fix All Issues
+
+After reporting, fix every **critical** and **warning** issue. Apply **suggestions** where they don't add unnecessary complexity.
+
+### Validation Output
+
+After fixing, confirm:
+1. `bun run lint` passes with no fixes needed
+2. TypeScript compiles clean (no type errors)
+3. Re-read all modified files to verify fixes are correct
+4. Any remaining unknown response schemas were explicitly reported to the user instead of guessed
+
+## Checklist Summary
+
+- [ ] Read ALL tool files, block, types, index, and registries
+- [ ] Pulled and read official API documentation
+- [ ] Validated every tool's ID, params, request, response, outputs, and types against API docs
+- [ ] Validated block ↔ tool alignment (every tool param has a subBlock, every condition is correct)
+- [ ] Validated advanced mode on optional/rarely-used fields
+- [ ] Validated wandConfig on timestamps and complex inputs
+- [ ] Validated tools.config mapping, tool selector, and type coercions
+- [ ] Validated block outputs match what tools return, with typed JSON where possible
+- [ ] Validated OAuth scopes use centralized utilities (getScopesForService, getCanonicalScopesForProvider) — no hardcoded arrays
+- [ ] Validated scope descriptions exist in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts` for all scopes
+- [ ] Validated pagination consistency across tools and block
+- [ ] Validated error handling (error checks, meaningful messages)
+- [ ] Validated registry entries (tools and block, alphabetical, correct imports)
+- [ ] Reported all issues grouped by severity
+- [ ] Fixed all critical and warning issues
+- [ ] Ran `bun run lint` after fixes
+- [ ] Verified TypeScript compiles clean
--- a/.agents/skills/validate-integration/agents/openai.yaml
+++ b/.agents/skills/validate-integration/agents/openai.yaml
@@ -0,0 +1,5 @@
+interface:
+  display_name: "Validate Integration"
+  short_description: "Audit a Sim service integration"
+  brand_color: "#B45309"
+  default_prompt: "Use $validate-integration to audit and fix a Sim integration against its API docs."
--- a/.agents/skills/validate-trigger/SKILL.md
+++ b/.agents/skills/validate-trigger/SKILL.md
@@ -0,0 +1,228 @@
+---
+name: validate-trigger
+description: Audit an existing Sim webhook trigger against the service's webhook API docs and repository conventions, then report and fix issues across trigger definitions, provider handler, output alignment, registration, and security. Use when validating or repairing a trigger under `apps/sim/triggers/{service}/` or `apps/sim/lib/webhooks/providers/{service}.ts`.
+---
+
+# Validate Trigger
+
+You are an expert auditor for Sim webhook triggers. Your job is to validate that an existing trigger implementation is correct, complete, secure, and aligned across all layers.
+
+## Your Task
+
+1. Read the service's webhook/API documentation (via WebFetch)
+2. Read every trigger file, provider handler, and registry entry
+3. Cross-reference against the API docs and Sim conventions
+4. Report all issues grouped by severity (critical, warning, suggestion)
+5. Fix all issues after reporting them
+
+## Step 1: Gather All Files
+
+Read **every** file for the trigger — do not skip any:
+
+```
+apps/sim/triggers/{service}/           # All trigger files, utils.ts, index.ts
+apps/sim/lib/webhooks/providers/{service}.ts  # Provider handler (if exists)
+apps/sim/lib/webhooks/providers/registry.ts   # Handler registry
+apps/sim/triggers/registry.ts                 # Trigger registry
+apps/sim/blocks/blocks/{service}.ts           # Block definition (trigger wiring)
+```
+
+Also read for reference:
+```
+apps/sim/lib/webhooks/providers/types.ts            # WebhookProviderHandler interface
+apps/sim/lib/webhooks/providers/utils.ts            # Shared helpers (createHmacVerifier, etc.)
+apps/sim/lib/webhooks/provider-subscription-utils.ts    # Subscription helpers
+apps/sim/lib/webhooks/processor.ts                  # Central webhook processor
+```
+
+## Step 2: Pull API Documentation
+
+Fetch the service's official webhook documentation. This is the **source of truth** for:
+- Webhook event types and payload shapes
+- Signature/auth verification method (HMAC algorithm, header names, secret format)
+- Challenge/verification handshake requirements
+- Webhook subscription API (create/delete endpoints, if applicable)
+- Retry behavior and delivery guarantees
+
+### Hard Rule: No Guessed Webhook Payload Schemas
+
+If the official docs do not clearly show the webhook payload JSON for an event, you MUST tell the user instead of guessing.
+
+- Do NOT invent payload field names
+- Do NOT infer nested payload paths without evidence
+- Do NOT treat likely event shapes as verified
+- Do NOT accept `formatInput` mappings that are not backed by docs or live payloads
+
+If a payload schema is unknown, validation must explicitly recommend:
+1. sample webhook payloads,
+2. a live test webhook source, or
+3. trimming the trigger to only documented outputs.
+
+## Step 3: Validate Trigger Definitions
+
+### utils.ts
+- [ ] `{service}TriggerOptions` lists all trigger IDs accurately
+- [ ] `{service}SetupInstructions` provides clear, correct steps for the service
+- [ ] `build{Service}ExtraFields` includes relevant filter/config fields with correct `condition`
+- [ ] Output builders expose all meaningful fields from the webhook payload
+- [ ] Output builders do NOT use `optional: true` or `items` (tool-output-only features)
+- [ ] Nested output objects correctly model the payload structure
+
+### Trigger Files
+- [ ] Exactly one primary trigger has `includeDropdown: true`
+- [ ] All secondary triggers do NOT have `includeDropdown`
+- [ ] All triggers use `buildTriggerSubBlocks` helper (not hand-rolled subBlocks)
+- [ ] Every trigger's `id` matches the convention `{service}_{event_name}`
+- [ ] Every trigger's `provider` matches the service name used in the handler registry
+- [ ] `index.ts` barrel exports all triggers
+
+### Trigger ↔ Provider Alignment (CRITICAL)
+- [ ] Every trigger ID referenced in `matchEvent` logic exists in `{service}TriggerOptions`
+- [ ] Event matching logic in the provider correctly maps trigger IDs to service event types
+- [ ] Event matching logic in `is{Service}EventMatch` (if exists) correctly identifies events per the API docs
+
+## Step 4: Validate Provider Handler
+
+### Auth Verification
+- [ ] `verifyAuth` correctly validates webhook signatures per the service's documentation
+- [ ] HMAC algorithm matches (SHA-1, SHA-256, SHA-512)
+- [ ] Signature header name matches the API docs exactly
+- [ ] Signature format is handled (raw hex, `sha256=` prefix, base64, etc.)
+- [ ] Uses `safeCompare` for timing-safe comparison (no `===`)
+- [ ] If `webhookSecret` is required, handler rejects when it's missing (fail-closed)
+- [ ] Signature is computed over raw body (not parsed JSON)
+
+### Event Matching
+- [ ] `matchEvent` returns `boolean` (not `NextResponse` or other values)
+- [ ] Challenge/verification events are excluded from matching (e.g., `endpoint.url_validation`)
+- [ ] When `triggerId` is a generic webhook ID, all events pass through
+- [ ] When `triggerId` is specific, only matching events pass
+- [ ] Event matching logic uses dynamic `await import()` for trigger utils (avoids circular deps)
+
+### formatInput (CRITICAL)
+- [ ] Every key in the `formatInput` return matches a key in the trigger `outputs` schema
+- [ ] Every key in the trigger `outputs` schema is populated by `formatInput`
+- [ ] No extra undeclared keys that users can't discover in the UI
+- [ ] No wrapper objects (`webhook: { ... }`, `{service}: { ... }`)
+- [ ] Nested output paths exist at the correct depth (e.g., `resource.id` actually has `resource: { id: ... }`)
+- [ ] `null` is used for missing optional fields (not empty strings or empty objects)
+- [ ] Returns `{ input: { ... } }` — not a bare object
+- [ ] Every mapped payload field is backed by official docs or live-verified webhook payloads
+
+### Idempotency
+- [ ] `extractIdempotencyId` returns a stable, unique key per delivery
+- [ ] Uses provider-specific delivery IDs when available (e.g., `X-Request-Id`, `Linear-Delivery`, `svix-id`)
+- [ ] Falls back to content-based ID (e.g., `${type}:${id}`) when no delivery header exists
+- [ ] Does NOT include timestamps in the idempotency key (would break dedup on retries)
+
+### Challenge Handling (if applicable)
+- [ ] `handleChallenge` correctly implements the service's URL verification handshake
+- [ ] Returns the expected response format per the API docs
+- [ ] Env-backed secrets are resolved via `resolveEnvVarsInObject` if needed
+
+## Step 5: Validate Automatic Subscription Lifecycle
+
+If the service supports programmatic webhook creation:
+
+### createSubscription
+- [ ] Calls the correct API endpoint to create a webhook
+- [ ] Sends the correct event types/filters
+- [ ] Passes the notification URL from `getNotificationUrl(ctx.webhook)`
+- [ ] Returns `{ providerConfigUpdates: { externalId } }` with the external webhook ID
+- [ ] Throws on failure (orchestration handles rollback)
+- [ ] Provides user-friendly error messages (401 → "Invalid API Key", etc.)
+
+### deleteSubscription
+- [ ] Calls the correct API endpoint to delete the webhook
+- [ ] Handles 404 gracefully (webhook already deleted)
+- [ ] Never throws — catches errors and logs non-fatally
+- [ ] Skips gracefully when `apiKey` or `externalId` is missing
+
+### Orchestration Isolation
+- [ ] NO provider-specific logic in `route.ts`, `provider-subscriptions.ts`, or `deploy.ts`
+- [ ] All subscription logic lives on the handler (`createSubscription`/`deleteSubscription`)
+
+## Step 6: Validate Registration and Block Wiring
+
+### Trigger Registry (`triggers/registry.ts`)
+- [ ] All triggers are imported and registered
+- [ ] Registry keys match trigger IDs exactly
+- [ ] No orphaned entries (triggers that don't exist)
+
+### Provider Handler Registry (`providers/registry.ts`)
+- [ ] Handler is imported and registered (if handler exists)
+- [ ] Registry key matches the `provider` field on the trigger configs
+- [ ] Entries are in alphabetical order
+
+### Block Wiring (`blocks/blocks/{service}.ts`)
+- [ ] Block has `triggers.enabled: true`
+- [ ] `triggers.available` lists all trigger IDs
+- [ ] All trigger subBlocks are spread into `subBlocks`: `...getTrigger('id').subBlocks`
+- [ ] No trigger IDs in `triggers.available` that aren't in the registry
+- [ ] No trigger subBlocks spread that aren't in `triggers.available`
+
+## Step 7: Validate Security
+
+- [ ] Webhook secrets are never logged (not even at debug level)
+- [ ] Auth verification runs before any event processing
+- [ ] No secret comparison uses `===` (must use `safeCompare` or `crypto.timingSafeEqual`)
+- [ ] Timestamp/replay protection is reasonable (not too tight for retries, not too loose for security)
+- [ ] Raw body is used for signature verification (not re-serialized JSON)
+
+## Step 8: Report and Fix
+
+### Report Format
+
+Group findings by severity:
+
+**Critical** (runtime errors, security issues, or data loss):
+- Wrong HMAC algorithm or header name
+- `formatInput` keys don't match trigger `outputs`
+- Missing `verifyAuth` when the service sends signed webhooks
+- `matchEvent` returns non-boolean values
+- Provider-specific logic leaking into shared orchestration files
+- Trigger IDs mismatch between trigger files, registry, and block
+- `createSubscription` calling wrong API endpoint
+- Auth comparison using `===` instead of `safeCompare`
+
+**Warning** (convention violations or usability issues):
+- Missing `extractIdempotencyId` when the service provides delivery IDs
+- Timestamps in idempotency keys (breaks dedup on retries)
+- Missing challenge handling when the service requires URL verification
+- Output schema missing fields that `formatInput` returns (undiscoverable data)
+- Overly tight timestamp skew window that rejects legitimate retries
+- `matchEvent` not filtering challenge/verification events
+- Setup instructions missing important steps
+
+**Suggestion** (minor improvements):
+- More specific output field descriptions
+- Additional output fields that could be exposed
+- Better error messages in `createSubscription`
+- Logging improvements
+
+### Fix All Issues
+
+After reporting, fix every **critical** and **warning** issue. Apply **suggestions** where they don't add unnecessary complexity.
+
+### Validation Output
+
+After fixing, confirm:
+1. `bun run type-check` passes
+2. Re-read all modified files to verify fixes are correct
+3. Provider handler tests pass (if they exist): `bun test {service}`
+4. Any remaining unknown webhook payload schemas were explicitly reported to the user instead of guessed
+
+## Checklist Summary
+
+- [ ] Read all trigger files, provider handler, types, registries, and block
+- [ ] Pulled and read official webhook/API documentation
+- [ ] Validated trigger definitions: options, instructions, extra fields, outputs
+- [ ] Validated primary/secondary trigger distinction (`includeDropdown`)
+- [ ] Validated provider handler: auth, matchEvent, formatInput, idempotency
+- [ ] Validated output alignment: every `outputs` key ↔ every `formatInput` key
+- [ ] Validated subscription lifecycle: createSubscription, deleteSubscription, no shared-file edits
+- [ ] Validated registration: trigger registry, handler registry, block wiring
+- [ ] Validated security: safe comparison, no secret logging, replay protection
+- [ ] Reported all issues grouped by severity
+- [ ] Fixed all critical and warning issues
+- [ ] `bun run type-check` passes after fixes
--- a/.agents/skills/you-might-not-need-a-callback/SKILL.md
+++ b/.agents/skills/you-might-not-need-a-callback/SKILL.md
@@ -0,0 +1,51 @@
+---
+name: you-might-not-need-a-callback
+description: Analyze and fix useCallback anti-patterns in your code
+---
+
+# You Might Not Need a Callback
+
+Arguments:
+- scope: what to analyze (default: your current changes). Examples: "diff to main", "PR #123", "src/components/", "whole codebase"
+- fix: whether to apply fixes (default: true). Set to false to only propose changes.
+
+User arguments: $ARGUMENTS
+
+## References
+
+Read before analyzing:
+1. https://react.dev/reference/react/useCallback — official docs on when useCallback is actually needed
+
+## When useCallback IS needed
+
+- Passing a callback to a child wrapped in `React.memo` (to preserve referential equality)
+- The callback is a dependency of another hook (`useEffect`, `useMemo`)
+- The callback is used in a custom hook that documents referential stability requirements
+
+## Anti-patterns to detect
+
+1. **useCallback on functions not passed as props or deps**: If the function is only called within the same component and isn't in any dependency array, useCallback adds overhead for no benefit. Just declare the function normally.
+2. **useCallback with exhaustive deps that change every render**: If the dependency array includes values that change on every render, useCallback recalculates every time. The memoization is wasted. Either stabilize the deps (use refs) or remove the useCallback.
+3. **useCallback on event handlers passed to native elements**: `<button onClick={handleClick}>` — native elements don't benefit from stable references. Only child components wrapped in React.memo do.
+4. **useCallback wrapping a function that creates new objects/arrays**: If the callback returns `{ ...newObj }` or `[...newArr]`, memoizing the callback doesn't prevent the child from re-rendering due to new return values. The memoization is at the wrong level.
+5. **useCallback with an empty dep array when deps are needed**: Stale closures — the callback captures outdated values. Either add proper deps or use refs for values that shouldn't trigger re-creation.
+6. **Pairing useCallback with React.memo unnecessarily**: If the child component is cheap to render, neither useCallback nor React.memo adds value. Only optimize when you've measured a performance problem.
+7. **useCallback in custom hooks that don't need stable references**: Not every hook return needs to be memoized. Only stabilize callbacks when consumers depend on referential equality.
+
+## Codebase-specific notes
+
+This codebase uses a ref pattern for stable callbacks in hooks:
+```tsx
+const idRef = useRef(id)
+useEffect(() => { idRef.current = id }, [id])
+const fetchData = useCallback(async () => {
+  // use idRef.current instead of id
+}, []) // empty deps because refs are used
+```
+This pattern is correct — don't flag it as an anti-pattern.
+
+## Steps
+
+1. Read the reference above
+2. Analyze the specified scope for the anti-patterns listed above
+3. If fix=true, apply the fixes. If fix=false, propose the fixes without applying.
--- a/.agents/skills/you-might-not-need-a-memo/SKILL.md
+++ b/.agents/skills/you-might-not-need-a-memo/SKILL.md
@@ -0,0 +1,33 @@
+---
+name: you-might-not-need-a-memo
+description: Analyze and fix useMemo/React.memo anti-patterns in your code
+---
+
+# You Might Not Need a Memo
+
+Arguments:
+- scope: what to analyze (default: your current changes). Examples: "diff to main", "PR #123", "src/components/", "whole codebase"
+- fix: whether to apply fixes (default: true). Set to false to only propose changes.
+
+User arguments: $ARGUMENTS
+
+## References
+
+Read before analyzing:
+1. https://overreacted.io/before-you-memo/ — two techniques to avoid memo entirely
+
+## Anti-patterns to detect
+
+1. **Wrapping a slow component in React.memo when state can be moved down**: If a component re-renders because of state it doesn't use, move that state into a smaller child component instead of memoizing. The slow component stops re-rendering without memo.
+2. **Wrapping in React.memo when children can be lifted up**: If a parent owns state that changes frequently, extract the stateful part and pass the expensive subtree as `children`. Children passed as props don't re-render when the parent's state changes.
+3. **useMemo on cheap computations**: Filtering or mapping a small array, string concatenation, simple arithmetic — these don't need memoization. Only memoize when you've measured a performance problem.
+4. **useMemo with constantly-changing deps**: If the dependency array changes on every render, useMemo does nothing — it recalculates every time. Fix the deps or remove the memo.
+5. **useMemo to create objects/arrays passed as props**: Instead of memoizing to prevent child re-renders, consider whether the child even needs referential stability. If the child doesn't use React.memo or pass it to a dep array, the memo is wasted.
+6. **React.memo on components that always receive new props**: If the parent always passes new objects, arrays, or callbacks, React.memo's shallow comparison always fails. Fix the parent instead of memoizing the child.
+7. **useMemo for derived state**: If you're computing a value from props or state, just compute it inline during render. React renders are fast. `const fullName = first + ' ' + last` doesn't need useMemo.
+
+## Steps
+
+1. Read the reference above to understand the two core techniques (move state down, lift content up)
+2. Analyze the specified scope for the anti-patterns listed above
+3. If fix=true, apply the fixes. If fix=false, propose the fixes without applying.
--- a/.agents/skills/you-might-not-need-an-effect/SKILL.md
+++ b/.agents/skills/you-might-not-need-an-effect/SKILL.md
@@ -0,0 +1,17 @@
+---
+name: you-might-not-need-an-effect
+description: Analyze and fix useEffect anti-patterns in your code
+---
+
+# You Might Not Need an Effect
+
+Arguments:
+- scope: what to analyze (default: your current changes). Examples: "diff to main", "PR #123", "src/components/", "whole codebase"
+- fix: whether to apply fixes (default: true). Set to false to only propose changes.
+
+User arguments: $ARGUMENTS
+
+Steps:
+1. Read https://react.dev/learn/you-might-not-need-an-effect to understand the guidelines
+2. Analyze the specified scope for useEffect anti-patterns
+3. If fix=true, apply the fixes. If fix=false, propose the fixes without applying.
--- a/.agents/skills/you-might-not-need-state/SKILL.md
+++ b/.agents/skills/you-might-not-need-state/SKILL.md
@@ -0,0 +1,38 @@
+---
+name: you-might-not-need-state
+description: Analyze and fix unnecessary useState, derived state, and server-state-in-local-state anti-patterns
+---
+
+# You Might Not Need State
+
+Arguments:
+- scope: what to analyze (default: your current changes). Examples: "diff to main", "PR #123", "src/components/", "whole codebase"
+- fix: whether to apply fixes (default: true). Set to false to only propose changes.
+
+User arguments: $ARGUMENTS
+
+## Context
+
+This codebase uses React Query for all server state and Zustand for client-only global state. useState should only be used for ephemeral UI concerns (open/closed, hover, local form input). Server data should never be copied into useState or Zustand — React Query is the single source of truth.
+
+## References
+
+Read these before analyzing:
+1. https://react.dev/learn/choosing-the-state-structure — 5 principles for structuring state
+2. https://tkdodo.eu/blog/dont-over-use-state — never store derived/computed values in state
+3. https://tkdodo.eu/blog/putting-props-to-use-state — never mirror props into state via useEffect
+
+## Anti-patterns to detect
+
+1. **Derived state stored in useState**: If a value can be computed from props, other state, or query data, compute it inline during render instead of storing it in state.
+2. **Server state copied into useState**: Never `useState` + `useEffect` to sync React Query data into local state. Use query data directly. The only exception is forms where users edit server data.
+3. **Props mirrored into state**: Never `useState(prop)` + `useEffect(() => setState(prop))`. Use the prop directly, or use a key to reset component state.
+4. **Chained useEffect state updates**: Never chain Effects that set state to trigger other Effects. Calculate all derived values in the event handler or inline during render.
+5. **Storing objects when an ID suffices**: Store `selectedId` not a copy of the selected object. Derive the object: `items.find(i => i.id === selectedId)`.
+6. **State that duplicates Zustand or React Query**: If the data already lives in a store or query cache, don't create a parallel useState.
+
+## Steps
+
+1. Read the references above to understand the guidelines
+2. Analyze the specified scope for the anti-patterns listed above
+3. If fix=true, apply the fixes. If fix=false, propose the fixes without applying.
--- a/.claude/commands/add-block.md
+++ b/.claude/commands/add-block.md
@@ -19,7 +19,8 @@ When the user asks you to create a block:
 ```typescript
 import { {ServiceName}Icon } from '@/components/icons'
 import type { BlockConfig } from '@/blocks/types'
-import { AuthMode } from '@/blocks/types'
+import { AuthMode, IntegrationType } from '@/blocks/types'
+import { getScopesForService } from '@/lib/oauth/utils'

 export const {ServiceName}Block: BlockConfig = {
  type: '{service}',                    // snake_case identifier
@@ -28,6 +29,8 @@ export const {ServiceName}Block: BlockConfig = {
  longDescription: 'Detailed description for docs',
  docsLink: 'https://docs.sim.ai/tools/{service}',
  category: 'tools',                    // 'tools' | 'blocks' | 'triggers'
+  integrationType: IntegrationType.X,   // Primary category (see IntegrationType enum)
+  tags: ['oauth', 'api'],              // Cross-cutting tags (see IntegrationTag type)
  bgColor: '#HEXCOLOR',                 // Brand color
  icon: {ServiceName}Icon,

@@ -115,12 +118,17 @@ export const {ServiceName}Block: BlockConfig = {
  id: 'credential',
  title: 'Account',
  type: 'oauth-input',
-  serviceId: '{service}',  // Must match OAuth provider
+  serviceId: '{service}',  // Must match OAuth provider service key
+  requiredScopes: getScopesForService('{service}'),  // Import from @/lib/oauth/utils
  placeholder: 'Select account',
  required: true,
 }
 ```

+**Scopes:** Always use `getScopesForService(serviceId)` from `@/lib/oauth/utils` for `requiredScopes`. Never hardcode scope arrays — the single source of truth is `OAUTH_PROVIDERS` in `lib/oauth/oauth.ts`.
+
+**Scope descriptions:** When adding a new OAuth provider, also add human-readable descriptions for all scopes in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts`.
+
 ### Selectors (with dynamic options)
 ```typescript
 // Channel selector (Slack, Discord, etc.)
@@ -532,6 +540,41 @@ outputs: {
 }
 ```

+### Typed JSON Outputs
+
+When using `type: 'json'` and you know the object shape in advance, **describe the inner fields in the description** so downstream blocks know what properties are available. For well-known, stable objects, use nested output definitions instead:
+
+```typescript
+outputs: {
+  // BAD: Opaque json with no info about what's inside
+  plan: { type: 'json', description: 'Zone plan information' },
+
+  // GOOD: Describe the known fields in the description
+  plan: {
+    type: 'json',
+    description: 'Zone plan information (id, name, price, currency, frequency, is_subscribed)',
+  },
+
+  // BEST: Use nested output definition when the shape is stable and well-known
+  plan: {
+    id: { type: 'string', description: 'Plan identifier' },
+    name: { type: 'string', description: 'Plan name' },
+    price: { type: 'number', description: 'Plan price' },
+    currency: { type: 'string', description: 'Price currency' },
+  },
+}
+```
+
+Use the nested pattern when:
+- The object has a small, stable set of fields (< 10)
+- Downstream blocks will commonly access specific properties
+- The API response shape is well-documented and unlikely to change
+
+Use `type: 'json'` with a descriptive string when:
+- The object has many fields or a dynamic shape
+- It represents a list/array of items
+- The shape varies by operation
+
 ## V2 Block Pattern

 When creating V2 blocks (alongside legacy V1):
@@ -588,7 +631,8 @@ export const registry: Record<string, BlockConfig> = {
 ```typescript
 import { ServiceIcon } from '@/components/icons'
 import type { BlockConfig } from '@/blocks/types'
-import { AuthMode } from '@/blocks/types'
+import { AuthMode, IntegrationType } from '@/blocks/types'
+import { getScopesForService } from '@/lib/oauth/utils'

 export const ServiceBlock: BlockConfig = {
  type: 'service',
@@ -597,6 +641,8 @@ export const ServiceBlock: BlockConfig = {
  longDescription: 'Full description for documentation...',
  docsLink: 'https://docs.sim.ai/tools/service',
  category: 'tools',
+  integrationType: IntegrationType.DeveloperTools,
+  tags: ['oauth', 'api'],
  bgColor: '#FF6B6B',
  icon: ServiceIcon,
  authMode: AuthMode.OAuth,
@@ -619,6 +665,7 @@ export const ServiceBlock: BlockConfig = {
      title: 'Service Account',
      type: 'oauth-input',
      serviceId: 'service',
+      requiredScopes: getScopesForService('service'),
      placeholder: 'Select account',
      required: true,
    },
@@ -695,16 +742,90 @@ Please provide the SVG and I'll convert it to a React component.
 You can usually find this in the service's brand/press kit page, or copy it from their website.
 ```

+## Advanced Mode for Optional Fields
+
+Optional fields that are rarely used should be set to `mode: 'advanced'` so they don't clutter the basic UI. This includes:
+- Pagination tokens
+- Time range filters (start/end time)
+- Sort order options
+- Reply settings
+- Rarely used IDs (e.g., reply-to tweet ID, quote tweet ID)
+- Max results / limits
+
+```typescript
+{
+  id: 'startTime',
+  title: 'Start Time',
+  type: 'short-input',
+  placeholder: 'ISO 8601 timestamp',
+  condition: { field: 'operation', value: ['search', 'list'] },
+  mode: 'advanced',  // Rarely used, hide from basic view
+}
+```
+
+## WandConfig for Complex Inputs
+
+Use `wandConfig` for fields that are hard to fill out manually, such as timestamps, comma-separated lists, and complex query strings. This gives users an AI-assisted input experience.
+
+```typescript
+// Timestamps - use generationType: 'timestamp' to inject current date context
+{
+  id: 'startTime',
+  title: 'Start Time',
+  type: 'short-input',
+  mode: 'advanced',
+  wandConfig: {
+    enabled: true,
+    prompt: 'Generate an ISO 8601 timestamp based on the user description. Return ONLY the timestamp string.',
+    generationType: 'timestamp',
+  },
+}
+
+// Comma-separated lists - simple prompt without generationType
+{
+  id: 'mediaIds',
+  title: 'Media IDs',
+  type: 'short-input',
+  mode: 'advanced',
+  wandConfig: {
+    enabled: true,
+    prompt: 'Generate a comma-separated list of media IDs. Return ONLY the comma-separated values.',
+  },
+}
+```
+
+## Naming Convention
+
+All tool IDs referenced in `tools.access` and returned by `tools.config.tool` MUST use `snake_case` (e.g., `x_create_tweet`, `slack_send_message`). Never use camelCase or PascalCase.
+
 ## Checklist Before Finishing

+- [ ] `integrationType` is set to the correct `IntegrationType` enum value
+- [ ] `tags` array includes all applicable `IntegrationTag` values
 - [ ] All subBlocks have `id`, `title` (except switch), and `type`
 - [ ] Conditions use correct syntax (field, value, not, and)
 - [ ] DependsOn set for fields that need other values
 - [ ] Required fields marked correctly (boolean or condition)
- [ ] OAuth inputs have correct `serviceId`
- [ ] Tools.access lists all tool IDs
- [ ] Tools.config.tool returns correct tool ID
+- [ ] OAuth inputs have correct `serviceId` and `requiredScopes: getScopesForService(serviceId)`
+- [ ] Scope descriptions added to `SCOPE_DESCRIPTIONS` in `lib/oauth/utils.ts` for any new scopes
+- [ ] Tools.access lists all tool IDs (snake_case)
+- [ ] Tools.config.tool returns correct tool ID (snake_case)
 - [ ] Outputs match tool outputs
 - [ ] Block registered in registry.ts
 - [ ] If icon missing: asked user to provide SVG
 - [ ] If triggers exist: `triggers` config set, trigger subBlocks spread
+- [ ] Optional/rarely-used fields set to `mode: 'advanced'`
+- [ ] Timestamps and complex inputs have `wandConfig` enabled
+
+## Final Validation (Required)
+
+After creating the block, you MUST validate it against every tool it references:
+
+1. **Read every tool definition** that appears in `tools.access` — do not skip any
+2. **For each tool, verify the block has correct:**
+   - SubBlock inputs that cover all required tool params (with correct `condition` to show for that operation)
+   - SubBlock input types that match the tool param types (e.g., dropdown for enums, short-input for strings)
+   - `tools.config.params` correctly maps subBlock IDs to tool param names (if they differ)
+   - Type coercions in `tools.config.params` for any params that need conversion (Number(), Boolean(), JSON.parse())
+3. **Verify block outputs** cover the key fields returned by all tools
+4. **Verify conditions** — each subBlock should only show for the operations that actually use it
--- a/.claude/commands/add-connector.md
+++ b/.claude/commands/add-connector.md
@@ -0,0 +1,528 @@
+---
+description: Add a knowledge base connector for syncing documents from an external source
+argument-hint: <service-name> [api-docs-url]
+---
+
+# Add Connector Skill
+
+You are an expert at adding knowledge base connectors to Sim. A connector syncs documents from an external source (Confluence, Google Drive, Notion, etc.) into a knowledge base.
+
+## Your Task
+
+When the user asks you to create a connector:
+1. Use Context7 or WebFetch to read the service's API documentation
+2. Determine the auth mode: **OAuth** (if Sim already has an OAuth provider for the service) or **API key** (if the service uses API key / Bearer token auth)
+3. Create the connector directory and config
+4. Register it in the connector registry
+
+## Directory Structure
+
+Create files in `apps/sim/connectors/{service}/`:
+```
+connectors/{service}/
+├── index.ts          # Barrel export
+└── {service}.ts      # ConnectorConfig definition
+```
+
+## Authentication
+
+Connectors use a discriminated union for auth config (`ConnectorAuthConfig` in `connectors/types.ts`):
+
+```typescript
+type ConnectorAuthConfig =
+  | { mode: 'oauth'; provider: OAuthService; requiredScopes?: string[] }
+  | { mode: 'apiKey'; label?: string; placeholder?: string }
+```
+
+### OAuth mode
+For services with existing OAuth providers in `apps/sim/lib/oauth/types.ts`. The `provider` must match an `OAuthService`. The modal shows a credential picker and handles token refresh automatically.
+
+### API key mode
+For services that use API key / Bearer token auth. The modal shows a password input with the configured `label` and `placeholder`. The API key is encrypted at rest using AES-256-GCM and stored in a dedicated `encryptedApiKey` column on the connector record. The sync engine decrypts it automatically — connectors receive the raw access token in `listDocuments`, `getDocument`, and `validateConfig`.
+
+## ConnectorConfig Structure
+
+### OAuth connector example
+
+```typescript
+import { createLogger } from '@sim/logger'
+import { {Service}Icon } from '@/components/icons'
+import { fetchWithRetry } from '@/lib/knowledge/documents/utils'
+import type { ConnectorConfig, ExternalDocument, ExternalDocumentList } from '@/connectors/types'
+
+const logger = createLogger('{Service}Connector')
+
+export const {service}Connector: ConnectorConfig = {
+  id: '{service}',
+  name: '{Service}',
+  description: 'Sync documents from {Service} into your knowledge base',
+  version: '1.0.0',
+  icon: {Service}Icon,
+
+  auth: {
+    mode: 'oauth',
+    provider: '{service}',          // Must match OAuthService in lib/oauth/types.ts
+    requiredScopes: ['read:...'],
+  },
+
+  configFields: [
+    // Rendered dynamically by the add-connector modal UI
+    // Supports 'short-input' and 'dropdown' types
+  ],
+
+  listDocuments: async (accessToken, sourceConfig, cursor) => {
+    // Return metadata stubs with contentDeferred: true (if per-doc content fetch needed)
+    // Or full documents with content (if list API returns content inline)
+    // Return { documents: ExternalDocument[], nextCursor?, hasMore }
+  },
+
+  getDocument: async (accessToken, sourceConfig, externalId) => {
+    // Fetch full content for a single document
+    // Return ExternalDocument with contentDeferred: false, or null
+  },
+
+  validateConfig: async (accessToken, sourceConfig) => {
+    // Return { valid: true } or { valid: false, error: 'message' }
+  },
+
+  // Optional: map source metadata to semantic tag keys (translated to slots by sync engine)
+  mapTags: (metadata) => {
+    // Return Record<string, unknown> with keys matching tagDefinitions[].id
+  },
+}
+```
+
+### API key connector example
+
+```typescript
+export const {service}Connector: ConnectorConfig = {
+  id: '{service}',
+  name: '{Service}',
+  description: 'Sync documents from {Service} into your knowledge base',
+  version: '1.0.0',
+  icon: {Service}Icon,
+
+  auth: {
+    mode: 'apiKey',
+    label: 'API Key',                       // Shown above the input field
+    placeholder: 'Enter your {Service} API key',  // Input placeholder
+  },
+
+  configFields: [ /* ... */ ],
+  listDocuments: async (accessToken, sourceConfig, cursor) => { /* ... */ },
+  getDocument: async (accessToken, sourceConfig, externalId) => { /* ... */ },
+  validateConfig: async (accessToken, sourceConfig) => { /* ... */ },
+}
+```
+
+## ConfigField Types
+
+The add-connector modal renders these automatically — no custom UI needed.
+
+Three field types are supported: `short-input`, `dropdown`, and `selector`.
+
+```typescript
+// Text input
+{
+  id: 'domain',
+  title: 'Domain',
+  type: 'short-input',
+  placeholder: 'yoursite.example.com',
+  required: true,
+}
+
+// Dropdown (static options)
+{
+  id: 'contentType',
+  title: 'Content Type',
+  type: 'dropdown',
+  required: false,
+  options: [
+    { label: 'Pages only', id: 'page' },
+    { label: 'Blog posts only', id: 'blogpost' },
+    { label: 'All content', id: 'all' },
+  ],
+}
+```
+
+## Dynamic Selectors (Canonical Pairs)
+
+Use `type: 'selector'` to fetch options dynamically from the existing selector registry (`hooks/selectors/registry.ts`). Selectors are always paired with a manual fallback input using the **canonical pair** pattern — a `selector` field (basic mode) and a `short-input` field (advanced mode) linked by `canonicalParamId`.
+
+The user sees a toggle button (ArrowLeftRight) to switch between the selector dropdown and manual text input. On submit, the modal resolves each canonical pair to the active mode's value, keyed by `canonicalParamId`.
+
+### Rules
+
+1. **Every selector field MUST have a canonical pair** — a corresponding `short-input` (or `dropdown`) field with the same `canonicalParamId` and `mode: 'advanced'`.
+2. **`required` must be set identically on both fields** in a pair. If the selector is required, the manual input must also be required.
+3. **`canonicalParamId` must match the key the connector expects in `sourceConfig`** (e.g. `baseId`, `channel`, `teamId`). The advanced field's `id` should typically match `canonicalParamId`.
+4. **`dependsOn` references the selector field's `id`**, not the `canonicalParamId`. The modal propagates dependency clearing across canonical siblings automatically — changing either field in a parent pair clears dependent children.
+
+### Selector canonical pair example (Airtable base → table cascade)
+
+```typescript
+configFields: [
+  // Base: selector (basic) + manual (advanced)
+  {
+    id: 'baseSelector',
+    title: 'Base',
+    type: 'selector',
+    selectorKey: 'airtable.bases',     // Must exist in hooks/selectors/registry.ts
+    canonicalParamId: 'baseId',
+    mode: 'basic',
+    placeholder: 'Select a base',
+    required: true,
+  },
+  {
+    id: 'baseId',
+    title: 'Base ID',
+    type: 'short-input',
+    canonicalParamId: 'baseId',
+    mode: 'advanced',
+    placeholder: 'e.g. appXXXXXXXXXXXXXX',
+    required: true,
+  },
+  // Table: selector depends on base (basic) + manual (advanced)
+  {
+    id: 'tableSelector',
+    title: 'Table',
+    type: 'selector',
+    selectorKey: 'airtable.tables',
+    canonicalParamId: 'tableIdOrName',
+    mode: 'basic',
+    dependsOn: ['baseSelector'],       // References the selector field ID
+    placeholder: 'Select a table',
+    required: true,
+  },
+  {
+    id: 'tableIdOrName',
+    title: 'Table Name or ID',
+    type: 'short-input',
+    canonicalParamId: 'tableIdOrName',
+    mode: 'advanced',
+    placeholder: 'e.g. Tasks',
+    required: true,
+  },
+  // Non-selector fields stay as-is
+  { id: 'maxRecords', title: 'Max Records', type: 'short-input', ... },
+]
+```
+
+### Selector with domain dependency (Jira/Confluence pattern)
+
+When a selector depends on a plain `short-input` field (no canonical pair), `dependsOn` references that field's `id` directly. The `domain` field's value maps to `SelectorContext.domain` automatically via `SELECTOR_CONTEXT_FIELDS`.
+
+```typescript
+configFields: [
+  {
+    id: 'domain',
+    title: 'Jira Domain',
+    type: 'short-input',
+    placeholder: 'yoursite.atlassian.net',
+    required: true,
+  },
+  {
+    id: 'projectSelector',
+    title: 'Project',
+    type: 'selector',
+    selectorKey: 'jira.projects',
+    canonicalParamId: 'projectKey',
+    mode: 'basic',
+    dependsOn: ['domain'],
+    placeholder: 'Select a project',
+    required: true,
+  },
+  {
+    id: 'projectKey',
+    title: 'Project Key',
+    type: 'short-input',
+    canonicalParamId: 'projectKey',
+    mode: 'advanced',
+    placeholder: 'e.g. ENG, PROJ',
+    required: true,
+  },
+]
+```
+
+### How `dependsOn` maps to `SelectorContext`
+
+The connector selector field builds a `SelectorContext` from dependency values. For the mapping to work, each dependency's `canonicalParamId` (or field `id` for non-canonical fields) must exist in `SELECTOR_CONTEXT_FIELDS` (`lib/workflows/subblocks/context.ts`):
+
+```
+oauthCredential, domain, teamId, projectId, knowledgeBaseId, planId,
+siteId, collectionId, spreadsheetId, fileId, baseId, datasetId, serviceDeskId
+```
+
+### Available selector keys
+
+Check `hooks/selectors/types.ts` for the full `SelectorKey` union. Common ones for connectors:
+
+| SelectorKey | Context Deps | Returns |
+|-------------|-------------|---------|
+| `airtable.bases` | credential | Base ID + name |
+| `airtable.tables` | credential, `baseId` | Table ID + name |
+| `slack.channels` | credential | Channel ID + name |
+| `gmail.labels` | credential | Label ID + name |
+| `google.calendar` | credential | Calendar ID + name |
+| `linear.teams` | credential | Team ID + name |
+| `linear.projects` | credential, `teamId` | Project ID + name |
+| `jira.projects` | credential, `domain` | Project key + name |
+| `confluence.spaces` | credential, `domain` | Space key + name |
+| `notion.databases` | credential | Database ID + name |
+| `asana.workspaces` | credential | Workspace GID + name |
+| `microsoft.teams` | credential | Team ID + name |
+| `microsoft.channels` | credential, `teamId` | Channel ID + name |
+| `webflow.sites` | credential | Site ID + name |
+| `outlook.folders` | credential | Folder ID + name |
+
+## ExternalDocument Shape
+
+Every document returned from `listDocuments`/`getDocument` must include:
+
+```typescript
+{
+  externalId: string          // Source-specific unique ID
+  title: string               // Document title
+  content: string             // Extracted plain text (or '' if contentDeferred)
+  contentDeferred?: boolean   // true = content will be fetched via getDocument
+  mimeType: 'text/plain'     // Always text/plain (content is extracted)
+  contentHash: string         // Metadata-based hash for change detection
+  sourceUrl?: string          // Link back to original (stored on document record)
+  metadata?: Record<string, unknown>  // Source-specific data (fed to mapTags)
+}
+```
+
+## Content Deferral (Required for file/content-download connectors)
+
+**All connectors that require per-document API calls to fetch content MUST use `contentDeferred: true`.** This is the standard pattern — `listDocuments` returns lightweight metadata stubs, and content is fetched lazily by the sync engine via `getDocument` only for new/changed documents.
+
+This pattern is critical for reliability: the sync engine processes documents in batches and enqueues each batch for processing immediately. If a sync times out, all previously-batched documents are already queued. Without deferral, content downloads during listing can exhaust the sync task's time budget before any documents are saved.
+
+### When to use `contentDeferred: true`
+
+- The service's list API does NOT return document content (only metadata)
+- Content requires a separate download/export API call per document
+- Examples: Google Drive, OneDrive, SharePoint, Dropbox, Notion, Confluence, Gmail, Obsidian, Evernote, GitHub
+
+### When NOT to use `contentDeferred`
+
+- The list API already returns the full content inline (e.g., Slack messages, Reddit posts, HubSpot notes)
+- No per-document API call is needed to get content
+
+### Content Hash Strategy
+
+Use a **metadata-based** `contentHash` — never a content-based hash. The hash must be derivable from the list response metadata alone, so the sync engine can detect changes without downloading content.
+
+Good metadata hash sources:
+- `modifiedTime` / `lastModifiedDateTime` — changes when file is edited
+- Git blob SHA — unique per content version
+- API-provided content hash (e.g., Dropbox `content_hash`)
+- Version number (e.g., Confluence page version)
+
+Format: `{service}:{id}:{changeIndicator}`
+
+```typescript
+// Google Drive: modifiedTime changes on edit
+contentHash: `gdrive:${file.id}:${file.modifiedTime ?? ''}`
+
+// GitHub: blob SHA is a content-addressable hash
+contentHash: `gitsha:${item.sha}`
+
+// Dropbox: API provides content_hash
+contentHash: `dropbox:${entry.id}:${entry.content_hash ?? entry.server_modified}`
+
+// Confluence: version number increments on edit
+contentHash: `confluence:${page.id}:${page.version.number}`
+```
+
+**Critical invariant:** The `contentHash` MUST be identical whether produced by `listDocuments` (stub) or `getDocument` (full doc). Both should use the same stub function to guarantee this.
+
+### Implementation Pattern
+
+```typescript
+// 1. Create a stub function (sync, no API calls)
+function fileToStub(file: ServiceFile): ExternalDocument {
+  return {
+    externalId: file.id,
+    title: file.name || 'Untitled',
+    content: '',
+    contentDeferred: true,
+    mimeType: 'text/plain',
+    sourceUrl: `https://service.com/file/${file.id}`,
+    contentHash: `service:${file.id}:${file.modifiedTime ?? ''}`,
+    metadata: { /* fields needed by mapTags */ },
+  }
+}
+
+// 2. listDocuments returns stubs (fast, metadata only)
+listDocuments: async (accessToken, sourceConfig, cursor) => {
+  const response = await fetchWithRetry(listUrl, { ... })
+  const files = (await response.json()).files
+  const documents = files.map(fileToStub)
+  return { documents, nextCursor, hasMore }
+}
+
+// 3. getDocument fetches content and returns full doc with SAME contentHash
+getDocument: async (accessToken, sourceConfig, externalId) => {
+  const metadata = await fetchWithRetry(metadataUrl, { ... })
+  const file = await metadata.json()
+  if (file.trashed) return null
+
+  try {
+    const content = await fetchContent(accessToken, file)
+    if (!content.trim()) return null
+    const stub = fileToStub(file)
+    return { ...stub, content, contentDeferred: false }
+  } catch (error) {
+    logger.warn(`Failed to fetch content for: ${file.name}`, { error })
+    return null
+  }
+}
+```
+
+### Reference Implementations
+
+- **Google Drive**: `connectors/google-drive/google-drive.ts` — file download/export with `modifiedTime` hash
+- **GitHub**: `connectors/github/github.ts` — git blob SHA hash
+- **Notion**: `connectors/notion/notion.ts` — blocks API with `last_edited_time` hash
+- **Confluence**: `connectors/confluence/confluence.ts` — version number hash
+
+## tagDefinitions — Declared Tag Definitions
+
+Declare which tags the connector populates using semantic IDs. Shown in the add-connector modal as opt-out checkboxes.
+On connector creation, slots are **dynamically assigned** via `getNextAvailableSlot` — connectors never hardcode slot names.
+
+```typescript
+tagDefinitions: [
+  { id: 'labels', displayName: 'Labels', fieldType: 'text' },
+  { id: 'version', displayName: 'Version', fieldType: 'number' },
+  { id: 'lastModified', displayName: 'Last Modified', fieldType: 'date' },
+],
+```
+
+Each entry has:
+- `id`: Semantic key matching a key returned by `mapTags` (e.g. `'labels'`, `'version'`)
+- `displayName`: Human-readable name shown in the UI (e.g. "Labels", "Last Modified")
+- `fieldType`: `'text'` | `'number'` | `'date'` | `'boolean'` — determines which slot pool to draw from
+
+Users can opt out of specific tags in the modal. Disabled IDs are stored in `sourceConfig.disabledTagIds`.
+The assigned mapping (`semantic id → slot`) is stored in `sourceConfig.tagSlotMapping`.
+
+## mapTags — Metadata to Semantic Keys
+
+Maps source metadata to semantic tag keys. Required if `tagDefinitions` is set.
+The sync engine calls this automatically and translates semantic keys to actual DB slots
+using the `tagSlotMapping` stored on the connector.
+
+Return keys must match the `id` values declared in `tagDefinitions`.
+
+```typescript
+mapTags: (metadata: Record<string, unknown>): Record<string, unknown> => {
+  const result: Record<string, unknown> = {}
+
+  // Validate arrays before casting — metadata may be malformed
+  const labels = Array.isArray(metadata.labels) ? (metadata.labels as string[]) : []
+  if (labels.length > 0) result.labels = labels.join(', ')
+
+  // Validate numbers — guard against NaN
+  if (metadata.version != null) {
+    const num = Number(metadata.version)
+    if (!Number.isNaN(num)) result.version = num
+  }
+
+  // Validate dates — guard against Invalid Date
+  if (typeof metadata.lastModified === 'string') {
+    const date = new Date(metadata.lastModified)
+    if (!Number.isNaN(date.getTime())) result.lastModified = date
+  }
+
+  return result
+}
+```
+
+## External API Calls — Use `fetchWithRetry`
+
+All external API calls must use `fetchWithRetry` from `@/lib/knowledge/documents/utils` instead of raw `fetch()`. This provides exponential backoff with retries on 429/502/503/504 errors. It returns a standard `Response` — all `.ok`, `.json()`, `.text()` checks work unchanged.
+
+For `validateConfig` (user-facing, called on save), pass `VALIDATE_RETRY_OPTIONS` to cap wait time at ~7s. Background operations (`listDocuments`, `getDocument`) use the built-in defaults (5 retries, ~31s max).
+
+```typescript
+import { VALIDATE_RETRY_OPTIONS, fetchWithRetry } from '@/lib/knowledge/documents/utils'
+
+// Background sync — use defaults
+const response = await fetchWithRetry(url, {
+  method: 'GET',
+  headers: { Authorization: `Bearer ${accessToken}` },
+})
+
+// validateConfig — tighter retry budget
+const response = await fetchWithRetry(url, { ... }, VALIDATE_RETRY_OPTIONS)
+```
+
+## sourceUrl
+
+If `ExternalDocument.sourceUrl` is set, the sync engine stores it on the document record. Always construct the full URL (not a relative path).
+
+## Sync Engine Behavior (Do Not Modify)
+
+The sync engine (`lib/knowledge/connectors/sync-engine.ts`) is connector-agnostic. It:
+1. Calls `listDocuments` with pagination until `hasMore` is false
+2. Compares `contentHash` to detect new/changed/unchanged documents
+3. Stores `sourceUrl` and calls `mapTags` on insert/update automatically
+4. Handles soft-delete of removed documents
+5. Resolves access tokens automatically — OAuth tokens are refreshed, API keys are decrypted from the `encryptedApiKey` column
+
+You never need to modify the sync engine when adding a connector.
+
+## Icon
+
+The `icon` field on `ConnectorConfig` is used throughout the UI — in the connector list, the add-connector modal, and as the document icon in the knowledge base table (replacing the generic file type icon for connector-sourced documents). The icon is read from `CONNECTOR_REGISTRY[connectorType].icon` at runtime — no separate icon map to maintain.
+
+If the service already has an icon in `apps/sim/components/icons.tsx` (from a tool integration), reuse it. Otherwise, ask the user to provide the SVG.
+
+## Registering
+
+Add one line to `apps/sim/connectors/registry.ts`:
+
+```typescript
+import { {service}Connector } from '@/connectors/{service}'
+
+export const CONNECTOR_REGISTRY: ConnectorRegistry = {
+  // ... existing connectors ...
+  {service}: {service}Connector,
+}
+```
+
+## Reference Implementations
+
+- **OAuth + contentDeferred**: `apps/sim/connectors/google-drive/google-drive.ts` — file download with metadata-based hash, `orderBy` for deterministic pagination
+- **OAuth + contentDeferred (blocks API)**: `apps/sim/connectors/notion/notion.ts` — complex block content extraction deferred to `getDocument`
+- **OAuth + contentDeferred (git)**: `apps/sim/connectors/github/github.ts` — blob SHA hash, tree listing
+- **OAuth + inline content**: `apps/sim/connectors/confluence/confluence.ts` — multiple config field types, `mapTags`, label fetching
+- **API key**: `apps/sim/connectors/fireflies/fireflies.ts` — GraphQL API with Bearer token auth
+
+## Checklist
+
+- [ ] Created `connectors/{service}/{service}.ts` with full ConnectorConfig
+- [ ] Created `connectors/{service}/index.ts` barrel export
+- [ ] **Auth configured correctly:**
+  - OAuth: `auth.provider` matches an existing `OAuthService` in `lib/oauth/types.ts`
+  - API key: `auth.label` and `auth.placeholder` set appropriately
+- [ ] **Selector fields configured correctly (if applicable):**
+  - Every `type: 'selector'` field has a canonical pair (`short-input` or `dropdown` with same `canonicalParamId` and `mode: 'advanced'`)
+  - `required` is identical on both fields in each canonical pair
+  - `selectorKey` exists in `hooks/selectors/registry.ts`
+  - `dependsOn` references selector field IDs (not `canonicalParamId`)
+  - Dependency `canonicalParamId` values exist in `SELECTOR_CONTEXT_FIELDS`
+- [ ] `listDocuments` handles pagination with metadata-based content hashes
+- [ ] `contentDeferred: true` used if content requires per-doc API calls (file download, export, blocks fetch)
+- [ ] `contentHash` is metadata-based (not content-based) and identical between stub and `getDocument`
+- [ ] `sourceUrl` set on each ExternalDocument (full URL, not relative)
+- [ ] `metadata` includes source-specific data for tag mapping
+- [ ] `tagDefinitions` declared for each semantic key returned by `mapTags`
+- [ ] `mapTags` implemented if source has useful metadata (labels, dates, versions)
+- [ ] `validateConfig` verifies the source is accessible
+- [ ] All external API calls use `fetchWithRetry` (not raw `fetch`)
+- [ ] All optional config fields validated in `validateConfig`
+- [ ] Icon exists in `components/icons.tsx` (or asked user to provide SVG)
+- [ ] Registered in `connectors/registry.ts`
--- a/.claude/commands/add-hosted-key.md
+++ b/.claude/commands/add-hosted-key.md
@@ -0,0 +1,296 @@
+---
+description: Add hosted API key support to a tool so Sim provides the key when users don't bring their own
+argument-hint: <service-name>
+---
+
+# Adding Hosted Key Support to a Tool
+
+When a tool has hosted key support, Sim provides its own API key if the user hasn't configured one (via BYOK or env var). Usage is metered and billed to the workspace.
+
+## Overview
+
+| Step | What | Where |
+|------|------|-------|
+| 1 | Register BYOK provider ID | `tools/types.ts`, `app/api/workspaces/[id]/byok-keys/route.ts` |
+| 2 | Research the API's pricing and rate limits | API docs / pricing page (before writing any code) |
+| 3 | Add `hosting` config to the tool | `tools/{service}/{action}.ts` |
+| 4 | Hide API key field when hosted | `blocks/blocks/{service}.ts` |
+| 5 | Add to BYOK settings UI | BYOK settings component (`byok.tsx`) |
+| 6 | Summarize pricing and throttling comparison | Output to user (after all code changes) |
+
+## Step 1: Register the BYOK Provider ID
+
+Add the new provider to the `BYOKProviderId` union in `tools/types.ts`:
+
+```typescript
+export type BYOKProviderId =
+  | 'openai'
+  | 'anthropic'
+  // ...existing providers
+  | 'your_service'
+```
+
+Then add it to `VALID_PROVIDERS` in `app/api/workspaces/[id]/byok-keys/route.ts`:
+
+```typescript
+const VALID_PROVIDERS = ['openai', 'anthropic', 'google', 'mistral', 'your_service'] as const
+```
+
+## Step 2: Research the API's Pricing Model and Rate Limits
+
+**Before writing any `getCost` or `rateLimit` code**, look up the service's official documentation for both pricing and rate limits. You need to understand:
+
+### Pricing
+
+1. **How the API charges** — per request, per credit, per token, per step, per minute, etc.
+2. **Whether the API reports cost in its response** — look for fields like `creditsUsed`, `costDollars`, `tokensUsed`, or similar in the response body or headers
+3. **Whether cost varies by endpoint/options** — some APIs charge more for certain features (e.g., Firecrawl charges 1 credit/page base but +4 for JSON format, +4 for enhanced mode)
+4. **The dollar-per-unit rate** — what each credit/token/unit costs in dollars on our plan
+
+### Rate Limits
+
+1. **What rate limits the API enforces** — requests per minute/second, tokens per minute, concurrent requests, etc.
+2. **Whether limits vary by plan tier** — free vs paid vs enterprise often have different ceilings
+3. **Whether limits are per-key or per-account** — determines whether adding more hosted keys actually increases total throughput
+4. **What the API returns when rate limited** — HTTP 429, `Retry-After` header, error body format, etc.
+5. **Whether there are multiple dimensions** — some APIs limit both requests/min AND tokens/min independently
+
+Search the API's docs/pricing page (use WebSearch/WebFetch). Capture the pricing model as a comment in `getCost` so future maintainers know the source of truth.
+
+### Setting Our Rate Limits
+
+Our rate limiter (`lib/core/rate-limiter/hosted-key/`) uses a token-bucket algorithm applied **per billing actor** (workspace). It supports two modes:
+
+- **`per_request`** — simple; just `requestsPerMinute`. Good when the API charges flat per-request or cost doesn't vary much.
+- **`custom`** — `requestsPerMinute` plus additional `dimensions` (e.g., `tokens`, `search_units`). Each dimension has its own `limitPerMinute` and an `extractUsage` function that reads actual usage from the response. Use when the API charges on a variable metric (tokens, credits) and you want to cap that metric too.
+
+When choosing values for `requestsPerMinute` and any dimension limits:
+
+- **Stay well below the API's per-key limit** — our keys are shared across all workspaces. If the API allows 60 RPM per key and we have 3 keys, the global ceiling is ~180 RPM. Set the per-workspace limit low enough (e.g., 20-60 RPM) that many workspaces can coexist without collectively hitting the API's ceiling.
+- **Account for key pooling** — our round-robin distributes requests across `N` hosted keys, so the effective API-side rate per key is `(total requests) / N`. But per-workspace limits are enforced *before* key selection, so they apply regardless of key count.
+- **Prefer conservative defaults** — it's easy to raise limits later but hard to claw back after users depend on high throughput.
+
+## Step 3: Add `hosting` Config to the Tool
+
+Add a `hosting` object to the tool's `ToolConfig`. This tells the execution layer how to acquire hosted keys, calculate cost, and rate-limit.
+
+```typescript
+hosting: {
+  envKeyPrefix: 'YOUR_SERVICE_API_KEY',
+  apiKeyParam: 'apiKey',
+  byokProviderId: 'your_service',
+  pricing: {
+    type: 'custom',
+    getCost: (_params, output) => {
+      if (output.creditsUsed == null) {
+        throw new Error('Response missing creditsUsed field')
+      }
+      const creditsUsed = output.creditsUsed as number
+      const cost = creditsUsed * 0.001 // dollars per credit
+      return { cost, metadata: { creditsUsed } }
+    },
+  },
+  rateLimit: {
+    mode: 'per_request',
+    requestsPerMinute: 100,
+  },
+},
+```
+
+### Hosted Key Env Var Convention
+
+Keys use a numbered naming pattern driven by a count env var:
+
+```
+YOUR_SERVICE_API_KEY_COUNT=3
+YOUR_SERVICE_API_KEY_1=sk-...
+YOUR_SERVICE_API_KEY_2=sk-...
+YOUR_SERVICE_API_KEY_3=sk-...
+```
+
+The `envKeyPrefix` value (`YOUR_SERVICE_API_KEY`) determines which env vars are read at runtime. Adding more keys only requires bumping the count and adding the new env var.
+
+### Pricing: Prefer API-Reported Cost
+
+Always prefer using cost data returned by the API (e.g., `creditsUsed`, `costDollars`). This is the most accurate because it accounts for variable pricing tiers, feature modifiers, and plan-level discounts.
+
+**When the API reports cost** — use it directly and throw if missing:
+
+```typescript
+pricing: {
+  type: 'custom',
+  getCost: (params, output) => {
+    if (output.creditsUsed == null) {
+      throw new Error('Response missing creditsUsed field')
+    }
+    // $0.001 per credit — from https://example.com/pricing
+    const cost = (output.creditsUsed as number) * 0.001
+    return { cost, metadata: { creditsUsed: output.creditsUsed } }
+  },
+},
+```
+
+**When the API does NOT report cost** — compute it from params/output based on the pricing docs, but still validate the data you depend on:
+
+```typescript
+pricing: {
+  type: 'custom',
+  getCost: (params, output) => {
+    if (!Array.isArray(output.searchResults)) {
+      throw new Error('Response missing searchResults, cannot determine cost')
+    }
+    // Serper: 1 credit for <=10 results, 2 credits for >10 — from https://serper.dev/pricing
+    const credits = Number(params.num) > 10 ? 2 : 1
+    return { cost: credits * 0.001, metadata: { credits } }
+  },
+},
+```
+
+**`getCost` must always throw** if it cannot determine cost. Never silently fall back to a default — this would hide billing inaccuracies.
+
+### Capturing Cost Data from the API
+
+If the API returns cost info, capture it in `transformResponse` so `getCost` can read it from the output:
+
+```typescript
+transformResponse: async (response: Response) => {
+  const data = await response.json()
+  return {
+    success: true,
+    output: {
+      results: data.results,
+      creditsUsed: data.creditsUsed,  // pass through for getCost
+    },
+  }
+},
+```
+
+For async/polling tools, capture it in `postProcess` when the job completes:
+
+```typescript
+if (jobData.status === 'completed') {
+  result.output = {
+    data: jobData.data,
+    creditsUsed: jobData.creditsUsed,
+  }
+}
+```
+
+## Step 4: Hide the API Key Field When Hosted
+
+In the block config (`blocks/blocks/{service}.ts`), add `hideWhenHosted: true` to the API key subblock. This hides the field on hosted Sim since the platform provides the key:
+
+```typescript
+{
+  id: 'apiKey',
+  title: 'API Key',
+  type: 'short-input',
+  placeholder: 'Enter your API key',
+  password: true,
+  required: true,
+  hideWhenHosted: true,
+},
+```
+
+The visibility is controlled by `isSubBlockHidden()` in `lib/workflows/subblocks/visibility.ts`, which checks both the `isHosted` feature flag (`hideWhenHosted`) and optional env var conditions (`hideWhenEnvSet`).
+
+### Excluding Specific Operations from Hosted Key Support
+
+When a block has multiple operations but some operations should **not** use a hosted key (e.g., the underlying API is deprecated, unsupported, or too expensive), use the **duplicate apiKey subblock** pattern. This is the same pattern Exa uses for its `research` operation:
+
+1. **Remove the `hosting` config** from the tool definition for that operation — it must not have a `hosting` object at all.
+2. **Duplicate the `apiKey` subblock** in the block config with opposing conditions:
+
+```typescript
+// API Key — hidden when hosted for operations with hosted key support
+{
+  id: 'apiKey',
+  title: 'API Key',
+  type: 'short-input',
+  placeholder: 'Enter your API key',
+  password: true,
+  required: true,
+  hideWhenHosted: true,
+  condition: { field: 'operation', value: 'unsupported_op', not: true },
+},
+// API Key — always visible for unsupported_op (no hosted key support)
+{
+  id: 'apiKey',
+  title: 'API Key',
+  type: 'short-input',
+  placeholder: 'Enter your API key',
+  password: true,
+  required: true,
+  condition: { field: 'operation', value: 'unsupported_op' },
+},
+```
+
+Both subblocks share the same `id: 'apiKey'`, so the same value flows to the tool. The conditions ensure only one is visible at a time. The first has `hideWhenHosted: true` and shows for all hosted operations; the second has no `hideWhenHosted` and shows only for the excluded operation — meaning users must always provide their own key for that operation.
+
+To exclude multiple operations, use an array: `{ field: 'operation', value: ['op_a', 'op_b'] }`.
+
+**Reference implementations:**
+- **Exa** (`blocks/blocks/exa.ts`): `research` operation excluded from hosting — lines 309-329
+- **Google Maps** (`blocks/blocks/google_maps.ts`): `speed_limits` operation excluded from hosting (deprecated Roads API)
+
+## Step 5: Add to the BYOK Settings UI
+
+Add an entry to the `PROVIDERS` array in the BYOK settings component so users can bring their own key. You need the service icon from `components/icons.tsx`:
+
+```typescript
+{
+  id: 'your_service',
+  name: 'Your Service',
+  icon: YourServiceIcon,
+  description: 'What this service does',
+  placeholder: 'Enter your API key',
+},
+```
+
+## Step 6: Summarize Pricing and Throttling Comparison
+
+After all code changes are complete, output a detailed summary to the user covering:
+
+### What to include
+
+1. **API's pricing model** — how the service charges (per token, per credit, per request, etc.), the specific rates found in docs, and whether the API reports cost in responses.
+2. **Our `getCost` approach** — how we calculate cost, what fields we depend on, and any assumptions or estimates (especially when the API doesn't report exact dollar cost).
+3. **API's rate limits** — the documented limits (RPM, TPM, concurrent, etc.), which plan tier they apply to, and whether they're per-key or per-account.
+4. **Our `rateLimit` config** — what we set for `requestsPerMinute` (and dimensions if custom mode), why we chose those values, and how they compare to the API's limits.
+5. **Key pooling impact** — how many hosted keys we expect, and how round-robin distribution affects the effective per-key rate at the API.
+6. **Gaps or risks** — anything the API charges for that we don't meter, rate limit dimensions we chose not to enforce, or pricing that may be inaccurate due to variable model/tier costs.
+
+### Format
+
+Present this as a structured summary with clear headings. Example:
+
+```
+### Pricing
+- **API charges**: $X per 1M tokens (input), $Y per 1M tokens (output) — varies by model
+- **Response reports cost?**: No — only token counts in `usage` field
+- **Our getCost**: Estimates cost at $Z per 1M total tokens based on median model pricing
+- **Risk**: Actual cost varies by model; our estimate may over/undercharge for cheap/expensive models
+
+### Throttling
+- **API limits**: 300 RPM per key (paid tier), 60 RPM (free tier)
+- **Per-key or per-account**: Per key — more keys = more throughput
+- **Our config**: 60 RPM per workspace (per_request mode)
+- **With N keys**: Effective per-key rate is (total RPM across workspaces) / N
+- **Headroom**: Comfortable — even 10 active workspaces at full rate = 600 RPM / 3 keys = 200 RPM per key, under the 300 RPM API limit
+```
+
+This summary helps reviewers verify that the pricing and rate limiting are well-calibrated and surfaces any risks that need monitoring.
+
+## Checklist
+
+- [ ] Provider added to `BYOKProviderId` in `tools/types.ts`
+- [ ] Provider added to `VALID_PROVIDERS` in the BYOK keys API route
+- [ ] API pricing docs researched — understand per-unit cost and whether the API reports cost in responses
+- [ ] API rate limits researched — understand RPM/TPM limits, per-key vs per-account, and plan tiers
+- [ ] `hosting` config added to the tool with `envKeyPrefix`, `apiKeyParam`, `byokProviderId`, `pricing`, and `rateLimit`
+- [ ] `getCost` throws if required cost data is missing from the response
+- [ ] Cost data captured in `transformResponse` or `postProcess` if API provides it
+- [ ] `hideWhenHosted: true` added to the API key subblock in the block config
+- [ ] Provider entry added to the BYOK settings UI with icon and description
+- [ ] Env vars documented: `{PREFIX}_COUNT` and `{PREFIX}_1..N`
+- [ ] Pricing and throttling summary provided to reviewer
--- a/.claude/commands/add-integration.md
+++ b/.claude/commands/add-integration.md
@@ -102,6 +102,7 @@ export const {service}{Action}Tool: ToolConfig<Params, Response> = {
 - Always use `?? []` for optional array fields
 - Set `optional: true` for outputs that may not exist
 - Never output raw JSON dumps - extract meaningful fields
+- When using `type: 'json'` and you know the object shape, define `properties` with the inner fields so downstream consumers know the structure. Only use bare `type: 'json'` when the shape is truly dynamic

 ## Step 3: Create Block

@@ -112,7 +113,8 @@ export const {service}{Action}Tool: ToolConfig<Params, Response> = {
 ```typescript
 import { {Service}Icon } from '@/components/icons'
 import type { BlockConfig } from '@/blocks/types'
-import { AuthMode } from '@/blocks/types'
+import { AuthMode, IntegrationType } from '@/blocks/types'
+import { getScopesForService } from '@/lib/oauth/utils'

 export const {Service}Block: BlockConfig = {
  type: '{service}',
@@ -121,6 +123,8 @@ export const {Service}Block: BlockConfig = {
  longDescription: '...',
  docsLink: 'https://docs.sim.ai/tools/{service}',
  category: 'tools',
+  integrationType: IntegrationType.X,   // Primary category (see IntegrationType enum)
+  tags: ['oauth', 'api'],              // Cross-cutting tags (see IntegrationTag type)
  bgColor: '#HEXCOLOR',
  icon: {Service}Icon,
  authMode: AuthMode.OAuth,  // or AuthMode.ApiKey
@@ -143,6 +147,7 @@ export const {Service}Block: BlockConfig = {
      title: '{Service} Account',
      type: 'oauth-input',
      serviceId: '{service}',
+      requiredScopes: getScopesForService('{service}'),
      required: true,
    },
    // Conditional fields per operation
@@ -407,8 +412,10 @@ If creating V2 versions (API-aligned outputs):

 ### Block
 - [ ] Created `blocks/blocks/{service}.ts`
+- [ ] Set `integrationType` to the correct `IntegrationType` enum value
+- [ ] Set `tags` array with all applicable `IntegrationTag` values
 - [ ] Defined operation dropdown with all operations
- [ ] Added credential field (oauth-input or short-input)
+- [ ] Added credential field with `requiredScopes: getScopesForService('{service}')`
 - [ ] Added conditional fields per operation
 - [ ] Set up dependsOn for cascading selectors
 - [ ] Configured tools.access with all tool IDs
@@ -418,6 +425,12 @@ If creating V2 versions (API-aligned outputs):
 - [ ] If triggers: set `triggers.enabled` and `triggers.available`
 - [ ] If triggers: spread trigger subBlocks with `getTrigger()`

+### OAuth Scopes (if OAuth service)
+- [ ] Defined scopes in `lib/oauth/oauth.ts` under `OAUTH_PROVIDERS`
+- [ ] Added scope descriptions in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts`
+- [ ] Used `getCanonicalScopesForProvider()` in `auth.ts` (never hardcode)
+- [ ] Used `getScopesForService()` in block `requiredScopes` (never hardcode)
+
 ### Icon
 - [ ] Asked user to provide SVG
 - [ ] Added icon to `components/icons.tsx`
@@ -436,6 +449,12 @@ If creating V2 versions (API-aligned outputs):
 - [ ] Ran `bun run scripts/generate-docs.ts`
 - [ ] Verified docs file created

+### Final Validation (Required)
+- [ ] Read every tool file and cross-referenced inputs/outputs against the API docs
+- [ ] Verified block subBlocks cover all required tool params with correct conditions
+- [ ] Verified block outputs match what the tools actually return
+- [ ] Verified `tools.config.params` correctly maps and coerces all param types
+
 ## Example Command

 When the user asks to add an integration:
@@ -685,13 +704,61 @@ return NextResponse.json({
 | `isUserFile` | `@/lib/core/utils/user-file` | Type guard for UserFile objects |
 | `FileInputSchema` | `@/lib/uploads/utils/file-schemas` | Zod schema for file validation |

+### Advanced Mode for Optional Fields
+
+Optional fields that are rarely used should be set to `mode: 'advanced'` so they don't clutter the basic UI. Examples: pagination tokens, time range filters, sort order, max results, reply settings.
+
+### WandConfig for Complex Inputs
+
+Use `wandConfig` for fields that are hard to fill out manually:
+- **Timestamps**: Use `generationType: 'timestamp'` to inject current date context into the AI prompt
+- **JSON arrays**: Use `generationType: 'json-object'` for structured data
+- **Complex queries**: Use a descriptive prompt explaining the expected format
+
+```typescript
+{
+  id: 'startTime',
+  title: 'Start Time',
+  type: 'short-input',
+  mode: 'advanced',
+  wandConfig: {
+    enabled: true,
+    prompt: 'Generate an ISO 8601 timestamp. Return ONLY the timestamp string.',
+    generationType: 'timestamp',
+  },
+}
+```
+
+### OAuth Scopes (Centralized System)
+
+Scopes are maintained in a single source of truth and reused everywhere:
+
+1. **Define scopes** in `lib/oauth/oauth.ts` under `OAUTH_PROVIDERS[provider].services[service].scopes`
+2. **Add descriptions** in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts` for the OAuth modal UI
+3. **Reference in auth.ts** using `getCanonicalScopesForProvider(providerId)` from `@/lib/oauth/utils`
+4. **Reference in blocks** using `getScopesForService(serviceId)` from `@/lib/oauth/utils`
+
+**Never hardcode scope arrays** in `auth.ts` or block `requiredScopes`. Always import from the centralized source.
+
+```typescript
+// In auth.ts (Better Auth config)
+scopes: getCanonicalScopesForProvider('{service}'),
+
+// In block credential sub-block
+requiredScopes: getScopesForService('{service}'),
+```
+
 ### Common Gotchas

 1. **OAuth serviceId must match** - The `serviceId` in oauth-input must match the OAuth provider configuration
-2. **Tool IDs are snake_case** - `stripe_create_payment`, not `stripeCreatePayment`
+2. **All tool IDs MUST be snake_case** - `stripe_create_payment`, not `stripeCreatePayment`. This applies to tool `id` fields, registry keys, `tools.access` arrays, and `tools.config.tool` return values
 3. **Block type is snake_case** - `type: 'stripe'`, not `type: 'Stripe'`
 4. **Alphabetical ordering** - Keep imports and registry entries alphabetically sorted
 5. **Required can be conditional** - Use `required: { field: 'op', value: 'create' }` instead of always true
 6. **DependsOn clears options** - When a dependency changes, selector options are refetched
 7. **Never pass Buffer directly to fetch** - Convert to `new Uint8Array(buffer)` for TypeScript compatibility
 8. **Always handle legacy file params** - Keep hidden `fileContent` params for backwards compatibility
+9. **Optional fields use advanced mode** - Set `mode: 'advanced'` on rarely-used optional fields
+10. **Complex inputs need wandConfig** - Timestamps, JSON arrays, and other hard-to-type values should have `wandConfig` enabled
+11. **Never hardcode scopes** - Use `getScopesForService()` in blocks and `getCanonicalScopesForProvider()` in auth.ts
+12. **Always add scope descriptions** - New scopes must have entries in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts`
--- a/.claude/commands/add-tools.md
+++ b/.claude/commands/add-tools.md
@@ -147,9 +147,18 @@ closedAt: {
 },
 ```

-### Nested Properties
-For complex outputs, define nested structure:
+### Typed JSON Outputs
+
+When using `type: 'json'` and you know the object shape in advance, **always define the inner structure** using `properties` so downstream consumers know what fields are available:
+
 ```typescript
+// BAD: Opaque json with no info about what's inside
+metadata: {
+  type: 'json',
+  description: 'Response metadata',
+},
+
+// GOOD: Define the known properties
 metadata: {
  type: 'json',
  description: 'Response metadata',
@@ -159,7 +168,10 @@ metadata: {
    count: { type: 'number', description: 'Total count' },
  },
 },
+```

+For arrays of objects, define the item structure:
+```typescript
 items: {
  type: 'array',
  description: 'List of items',
@@ -173,6 +185,8 @@ items: {
 },
 ```

+Only use bare `type: 'json'` without `properties` when the shape is truly dynamic or unknown.
+
 ## Critical Rules for transformResponse

 ### Handle Nullable Fields
@@ -272,8 +286,13 @@ If creating V2 tools (API-aligned outputs), use `_v2` suffix:
 - Version: `'2.0.0'`
 - Outputs: Flat, API-aligned (no content/metadata wrapper)

+## Naming Convention
+
+All tool IDs MUST use `snake_case`: `{service}_{action}` (e.g., `x_create_tweet`, `slack_send_message`). Never use camelCase or PascalCase for tool IDs.
+
 ## Checklist Before Finishing

+- [ ] All tool IDs use snake_case
 - [ ] All params have explicit `required: true` or `required: false`
 - [ ] All params have appropriate `visibility`
 - [ ] All nullable response fields use `?? null`
@@ -281,4 +300,22 @@ If creating V2 tools (API-aligned outputs), use `_v2` suffix:
 - [ ] No raw JSON dumps in outputs
 - [ ] Types file has all interfaces
 - [ ] Index.ts exports all tools
- [ ] Tool IDs use snake_case
+
+## Final Validation (Required)
+
+After creating all tools, you MUST validate every tool before finishing:
+
+1. **Read every tool file** you created — do not skip any
+2. **Cross-reference with the API docs** to verify:
+   - All required params are marked `required: true`
+   - All optional params are marked `required: false`
+   - Param types match the API (string, number, boolean, json)
+   - Request URL, method, headers, and body match the API spec
+   - `transformResponse` extracts the correct fields from the API response
+   - All output fields match what the API actually returns
+   - No fields are missing from outputs that the API provides
+   - No extra fields are defined in outputs that the API doesn't return
+3. **Verify consistency** across tools:
+   - Shared types in `types.ts` match all tools that use them
+   - Tool IDs in the barrel export match the tool file definitions
+   - Error handling is consistent (error checks, meaningful messages)
--- a/.claude/commands/add-trigger.md
+++ b/.claude/commands/add-trigger.md
--- a/.claude/commands/cleanup.md
+++ b/.claude/commands/cleanup.md
@@ -0,0 +1,25 @@
+---
+description: Run all code quality skills in sequence — effects, memo, callbacks, state, React Query, and emcn design review
+argument-hint: [scope] [fix=true|false]
+---
+
+# Cleanup
+
+Arguments:
+- scope: what to review (default: your current changes). Examples: "diff to main", "PR #123", "src/components/", "whole codebase"
+- fix: whether to apply fixes (default: true). Set to false to only propose changes.
+
+User arguments: $ARGUMENTS
+
+## Steps
+
+Run each of these skills in order on the specified scope, passing through the scope and fix arguments. After each skill completes, move to the next. Do not skip any.
+
+1. `/you-might-not-need-an-effect $ARGUMENTS`
+2. `/you-might-not-need-a-memo $ARGUMENTS`
+3. `/you-might-not-need-a-callback $ARGUMENTS`
+4. `/you-might-not-need-state $ARGUMENTS`
+5. `/react-query-best-practices $ARGUMENTS`
+6. `/emcn-design-review $ARGUMENTS`
+
+After all skills have run, output a summary of what was found and fixed (or proposed) across all six passes.
--- a/.claude/commands/council.md
+++ b/.claude/commands/council.md
@@ -0,0 +1,12 @@
+---
+description: Spawn task agents to explore a given area of interest in the codebase
+argument-hint: <area-of-interest>
+---
+
+Based on the given area of interest, please:
+
+1. Dig around the codebase in terms of that given area of interest, gather general information such as keywords and architecture overview.
+2. Spawn off n=10 (unless specified otherwise) task agents to dig deeper into the codebase in terms of that given area of interest, some of them should be out of the box for variance.
+3. Once the task agents are done, use the information to do what the user wants.
+
+If user is in plan mode, use the information to create the plan.
--- a/.claude/commands/emcn-design-review.md
+++ b/.claude/commands/emcn-design-review.md
@@ -0,0 +1,79 @@
+---
+description: Review UI code for alignment with the emcn design system — components, tokens, patterns, and conventions
+argument-hint: [scope] [fix=true|false]
+---
+
+# EMCN Design Review
+
+Arguments:
+- scope: what to review (default: your current changes). Examples: "diff to main", "PR #123", "src/components/", "whole codebase"
+- fix: whether to apply fixes (default: true). Set to false to only propose changes.
+
+User arguments: $ARGUMENTS
+
+## Context
+
+This codebase uses **emcn**, a custom component library built on Radix UI primitives with CVA variants and CSS variable design tokens. All UI must use emcn components and tokens.
+
+## Steps
+
+1. Read the emcn barrel export at `apps/sim/components/emcn/components/index.ts` to know what's available
+2. Read `apps/sim/app/_styles/globals.css` for CSS variable tokens
+3. Analyze the specified scope against every rule below
+4. If fix=true, apply the fixes. If fix=false, propose the fixes without applying.
+
+---
+
+## Imports
+
+- Import from `@/components/emcn` barrel, never subpaths
+- Icons from `@/components/emcn/icons` or `lucide-react`
+- Use `cn` from `@/lib/core/utils/cn` for conditional classes
+
+## Design Tokens
+
+Use CSS variable pattern (`text-[var(--text-primary)]`), never Tailwind semantics (`text-muted-foreground`) or hardcoded colors (`text-gray-500`, `#333`).
+
+**Text**: `--text-primary`, `--text-secondary`, `--text-tertiary`, `--text-muted`, `--text-icon`, `--text-inverse`, `--text-error`
+**Surfaces**: `--bg`, `--surface-2` through `--surface-7`, `--surface-hover`, `--surface-active`
+**Borders**: `--border`, `--border-1`, `--border-muted`
+**Z-Index**: `--z-dropdown` (100), `--z-modal` (200), `--z-popover` (300), `--z-tooltip` (400), `--z-toast` (500)
+**Shadows**: `shadow-subtle`, `shadow-medium`, `shadow-overlay`, `shadow-card`
+
+## Buttons
+
+| Action | Variant |
+|--------|---------|
+| Toolbar, icon-only | `ghost` (most common, 28%) |
+| Create, save, submit | `primary` (24%) |
+| Cancel, close | `default` |
+| Delete, remove | `destructive` |
+| Selected state | `active` |
+| Toggle | `outline` |
+
+## Delete/Remove Confirmations
+
+Modal `size="sm"`, title "Delete/Remove {ItemType}", `variant="destructive"` action button, `variant="default"` cancel. Cancel left, action right (100% compliance). Use `text-[var(--text-error)]` for irreversible warnings.
+
+## Toast
+
+`toast.success()`, `toast.error()`, `toast()` from `@/components/emcn`. Never custom notification UI.
+
+## Badges
+
+`red`=error/failed, `gray-secondary`=metadata/roles, `type`=type annotations, `green`=success/active, `gray`=neutral, `amber`=processing, `orange`=paused, `blue`=info. Use `dot` prop for status indicators.
+
+## Icons
+
+Default: `h-[14px] w-[14px]` (400+ uses). Color: `text-[var(--text-icon)]`. Scale: 14px > 16px > 12px > 20px.
+
+## Anti-patterns to flag
+
+- Raw `<button>`/`<input>` instead of emcn components
+- Hardcoded colors (`text-gray-*`, `#hex`, `rgb()`)
+- Tailwind semantics (`text-muted-foreground`) instead of CSS variables
+- Template literal className instead of `cn()`
+- Inline styles for colors/static values (dynamic values OK)
+- Importing from emcn subpaths instead of barrel
+- Arbitrary z-index instead of tokens
+- Wrong button variant for action type
--- a/.claude/commands/react-query-best-practices.md
+++ b/.claude/commands/react-query-best-practices.md
@@ -0,0 +1,54 @@
+---
+description: Audit React Query usage for best practices — key factories, staleTime, mutations, and server state ownership
+argument-hint: [scope] [fix=true|false]
+---
+
+# React Query Best Practices
+
+Arguments:
+- scope: what to analyze (default: your current changes). Examples: "diff to main", "PR #123", "src/hooks/queries/", "whole codebase"
+- fix: whether to apply fixes (default: true). Set to false to only propose changes.
+
+User arguments: $ARGUMENTS
+
+## Context
+
+This codebase uses React Query (TanStack Query) as the single source of truth for all server state. All query hooks live in `hooks/queries/`. Zustand is used only for client-only UI state. Server data must never be duplicated into useState or Zustand outside of mutation callbacks that coordinate cross-store state.
+
+## References
+
+Read these before analyzing:
+1. https://tkdodo.eu/blog/practical-react-query — foundational defaults, custom hooks, avoiding local state copies
+2. https://tkdodo.eu/blog/effective-react-query-keys — key factory pattern, hierarchical keys, fuzzy invalidation
+3. https://tkdodo.eu/blog/react-query-as-a-state-manager — React Query IS your server state manager
+
+## Rules to enforce
+
+### Query key factories
+- Every file in `hooks/queries/` must have a hierarchical key factory with an `all` root key
+- Keys must include intermediate plural keys (`lists`, `details`) for prefix invalidation
+- Key factories are colocated with their query hooks, not in a global keys file
+
+### Query hooks
+- Every `queryFn` must forward `signal` for request cancellation
+- Every query must have an explicit `staleTime` (default 0 is almost never correct)
+- `keepPreviousData` / `placeholderData` only on variable-key queries (where params change), never on static keys
+- Use `enabled` to prevent queries from running without required params
+
+### Mutations
+- Use `onSettled` (not `onSuccess`) for cache reconciliation — it fires on both success and error
+- For optimistic updates: save previous data in `onMutate`, roll back in `onError`
+- Use targeted invalidation (`entityKeys.lists()`) not broad (`entityKeys.all`) when possible
+- Don't include mutation objects in `useCallback` deps — `.mutate()` is stable
+
+### Server state ownership
+- Never copy query data into useState. Use query data directly in components.
+- Never copy query data into Zustand stores (exception: mutation callbacks that coordinate cross-store state like temp ID replacement)
+- The query cache is not a local state manager — `setQueryData` is for optimistic updates only
+- Forms are the one deliberate exception: copy server data into local form state with `staleTime: Infinity`
+
+## Steps
+
+1. Read the references above to understand the guidelines
+2. Analyze the specified scope against the rules listed above
+3. If fix=true, apply the fixes. If fix=false, propose the fixes without applying.
--- a/.claude/commands/validate-connector.md
+++ b/.claude/commands/validate-connector.md
@@ -0,0 +1,316 @@
+---
+description: Validate an existing knowledge base connector against its service's API docs
+argument-hint: <service-name> [api-docs-url]
+---
+
+# Validate Connector Skill
+
+You are an expert auditor for Sim knowledge base connectors. Your job is to thoroughly validate that an existing connector is correct, complete, and follows all conventions.
+
+## Your Task
+
+When the user asks you to validate a connector:
+1. Read the service's API documentation (via Context7 or WebFetch)
+2. Read the connector implementation, OAuth config, and registry entries
+3. Cross-reference everything against the API docs and Sim conventions
+4. Report all issues found, grouped by severity (critical, warning, suggestion)
+5. Fix all issues after reporting them
+
+## Step 1: Gather All Files
+
+Read **every** file for the connector — do not skip any:
+
+```
+apps/sim/connectors/{service}/{service}.ts   # Connector implementation
+apps/sim/connectors/{service}/index.ts       # Barrel export
+apps/sim/connectors/registry.ts              # Connector registry entry
+apps/sim/connectors/types.ts                 # ConnectorConfig interface, ExternalDocument, etc.
+apps/sim/connectors/utils.ts                 # Shared utilities (computeContentHash, htmlToPlainText, etc.)
+apps/sim/lib/oauth/oauth.ts                  # OAUTH_PROVIDERS — single source of truth for scopes
+apps/sim/lib/oauth/utils.ts                  # getCanonicalScopesForProvider, getScopesForService, SCOPE_DESCRIPTIONS
+apps/sim/lib/oauth/types.ts                  # OAuthService union type
+apps/sim/components/icons.tsx                 # Icon definition for the service
+```
+
+If the connector uses selectors, also read:
+```
+apps/sim/hooks/selectors/registry.ts         # Selector key definitions
+apps/sim/hooks/selectors/types.ts            # SelectorKey union type
+apps/sim/lib/workflows/subblocks/context.ts  # SELECTOR_CONTEXT_FIELDS
+```
+
+## Step 2: Pull API Documentation
+
+Fetch the official API docs for the service. This is the **source of truth** for:
+- Endpoint URLs, HTTP methods, and auth headers
+- Required vs optional parameters
+- Parameter types and allowed values
+- Response shapes and field names
+- Pagination patterns (cursor, offset, next token)
+- Rate limits and error formats
+- OAuth scopes and their meanings
+
+Use Context7 (resolve-library-id → query-docs) or WebFetch to retrieve documentation. If both fail, note which claims are based on training knowledge vs verified docs.
+
+## Step 3: Validate API Endpoints
+
+For **every** API call in the connector (`listDocuments`, `getDocument`, `validateConfig`, and any helper functions), verify against the API docs:
+
+### URLs and Methods
+- [ ] Base URL is correct for the service's API version
+- [ ] Endpoint paths match the API docs exactly
+- [ ] HTTP method is correct (GET, POST, PUT, PATCH, DELETE)
+- [ ] Path parameters are correctly interpolated and URI-encoded where needed
+- [ ] Query parameters use correct names and formats per the API docs
+
+### Headers
+- [ ] Authorization header uses the correct format:
+  - OAuth: `Authorization: Bearer ${accessToken}`
+  - API Key: correct header name per the service's docs
+- [ ] `Content-Type` is set for POST/PUT/PATCH requests
+- [ ] Any service-specific headers are present (e.g., `Notion-Version`, `Dropbox-API-Arg`)
+- [ ] No headers are sent that the API doesn't support or silently ignores
+
+### Request Bodies
+- [ ] POST/PUT body fields match API parameter names exactly
+- [ ] Required fields are always sent
+- [ ] Optional fields are conditionally included (not sent as `null` or empty unless the API expects that)
+- [ ] Field value types match API expectations (string vs number vs boolean)
+
+### Input Sanitization
+- [ ] User-controlled values interpolated into query strings are properly escaped:
+  - OData `$filter`: single quotes escaped with `''` (e.g., `externalId.replace(/'/g, "''")`)
+  - SOQL: single quotes escaped with `\'`
+  - GraphQL variables: passed as variables, not interpolated into query strings
+  - URL path segments: `encodeURIComponent()` applied
+- [ ] URL-type config fields (e.g., `siteUrl`, `instanceUrl`) are normalized:
+  - Strip `https://` / `http://` prefix if the API expects bare domains
+  - Strip trailing `/`
+  - Apply `.trim()` before validation
+
+### Response Parsing
+- [ ] Response structure is correctly traversed (e.g., `data.results` vs `data.items` vs `data`)
+- [ ] Field names extracted match what the API actually returns
+- [ ] Nullable fields are handled with `?? null` or `|| undefined`
+- [ ] Error responses are checked before accessing data fields
+
+## Step 4: Validate OAuth Scopes (if OAuth connector)
+
+Scopes must be correctly declared and sufficient for all API calls the connector makes.
+
+### Connector requiredScopes
+- [ ] `requiredScopes` in the connector's `auth` config lists all scopes needed by the connector
+- [ ] Each scope in `requiredScopes` is a real, valid scope recognized by the service's API
+- [ ] No invalid, deprecated, or made-up scopes are listed
+- [ ] No unnecessary excess scopes beyond what the connector actually needs
+
+### Scope Subset Validation (CRITICAL)
+- [ ] Every scope in `requiredScopes` exists in the OAuth provider's `scopes` array in `lib/oauth/oauth.ts`
+- [ ] Find the provider in `OAUTH_PROVIDERS[providerGroup].services[serviceId].scopes`
+- [ ] Verify: `requiredScopes` ⊆ `OAUTH_PROVIDERS scopes` (every required scope is present in the provider config)
+- [ ] If a required scope is NOT in the provider config, flag as **critical** — the connector will fail at runtime
+
+### Scope Sufficiency
+For each API endpoint the connector calls:
+- [ ] Identify which scopes are required per the API docs
+- [ ] Verify those scopes are included in the connector's `requiredScopes`
+- [ ] If the connector calls endpoints requiring scopes not in `requiredScopes`, flag as **warning**
+
+### Token Refresh Config
+- [ ] Check the `getOAuthTokenRefreshConfig` function in `lib/oauth/oauth.ts` for this provider
+- [ ] `useBasicAuth` matches the service's token exchange requirements
+- [ ] `supportsRefreshTokenRotation` matches whether the service issues rotating refresh tokens
+- [ ] Token endpoint URL is correct
+
+## Step 5: Validate Pagination
+
+### listDocuments Pagination
+- [ ] Cursor/pagination parameter name matches the API docs
+- [ ] Response pagination field is correctly extracted (e.g., `next_cursor`, `nextPageToken`, `@odata.nextLink`, `offset`)
+- [ ] `hasMore` is correctly determined from the response
+- [ ] `nextCursor` is correctly passed back for the next page
+- [ ] `maxItems` / `maxRecords` cap is correctly applied across pages using `syncContext.totalDocsFetched`
+- [ ] Page size is within the API's allowed range (not exceeding max page size)
+- [ ] Last page precision: when a `maxItems` cap exists, the final page request uses `Math.min(PAGE_SIZE, remaining)` to avoid fetching more records than needed
+- [ ] No off-by-one errors in pagination tracking
+- [ ] The connector does NOT hit known API pagination limits silently (e.g., HubSpot search 10k cap)
+
+### Pagination State Across Pages
+- [ ] `syncContext` is used to cache state across pages (user names, field maps, instance URLs, portal IDs, etc.)
+- [ ] Cached state in `syncContext` is correctly initialized on first page and reused on subsequent pages
+
+## Step 6: Validate Data Transformation
+
+### ExternalDocument Construction
+- [ ] `externalId` is a stable, unique identifier from the source API
+- [ ] `title` is extracted from the correct field and has a sensible fallback (e.g., `'Untitled'`)
+- [ ] `content` is plain text — HTML content is stripped using `htmlToPlainText` from `@/connectors/utils`
+- [ ] `mimeType` is `'text/plain'`
+- [ ] `contentHash` is computed using `computeContentHash` from `@/connectors/utils`
+- [ ] `sourceUrl` is a valid, complete URL back to the original resource (not relative)
+- [ ] `metadata` contains all fields referenced by `mapTags` and `tagDefinitions`
+
+### Content Extraction
+- [ ] Rich text / HTML fields are converted to plain text before indexing
+- [ ] Important content is not silently dropped (e.g., nested blocks, table cells, code blocks)
+- [ ] Content is not silently truncated without logging a warning
+- [ ] Empty/blank documents are properly filtered out
+- [ ] Size checks use `Buffer.byteLength(text, 'utf8')` not `text.length` when comparing against byte-based limits (e.g., `MAX_FILE_SIZE` in bytes)
+
+## Step 7: Validate Tag Definitions and mapTags
+
+### tagDefinitions
+- [ ] Each `tagDefinition` has an `id`, `displayName`, and `fieldType`
+- [ ] `fieldType` matches the actual data type: `'text'` for strings, `'number'` for numbers, `'date'` for dates, `'boolean'` for booleans
+- [ ] Every `id` in `tagDefinitions` is returned by `mapTags`
+- [ ] No `tagDefinition` references a field that `mapTags` never produces
+
+### mapTags
+- [ ] Return keys match `tagDefinition` `id` values exactly
+- [ ] Date values are properly parsed using `parseTagDate` from `@/connectors/utils`
+- [ ] Array values are properly joined using `joinTagArray` from `@/connectors/utils`
+- [ ] Number values are validated (not `NaN`)
+- [ ] Metadata field names accessed in `mapTags` match what `listDocuments`/`getDocument` store in `metadata`
+
+## Step 8: Validate Config Fields and Validation
+
+### configFields
+- [ ] Every field has `id`, `title`, `type`
+- [ ] `required` is set explicitly (not omitted)
+- [ ] Dropdown fields have `options` with `label` and `id` for each option
+- [ ] Selector fields follow the canonical pair pattern:
+  - A `type: 'selector'` field with `selectorKey`, `canonicalParamId`, `mode: 'basic'`
+  - A `type: 'short-input'` field with the same `canonicalParamId`, `mode: 'advanced'`
+  - `required` is identical on both fields in the pair
+- [ ] `selectorKey` values exist in the selector registry
+- [ ] `dependsOn` references selector field `id` values, not `canonicalParamId`
+
+### validateConfig
+- [ ] Validates all required fields are present before making API calls
+- [ ] Validates optional numeric fields (checks `Number.isNaN`, positive values)
+- [ ] Makes a lightweight API call to verify access (e.g., fetch 1 record, get profile)
+- [ ] Uses `VALIDATE_RETRY_OPTIONS` for retry budget
+- [ ] Returns `{ valid: true }` on success
+- [ ] Returns `{ valid: false, error: 'descriptive message' }` on failure
+- [ ] Catches exceptions and returns user-friendly error messages
+- [ ] Does NOT make expensive calls (full data listing, large queries)
+
+## Step 9: Validate getDocument
+
+- [ ] Fetches a single document by `externalId`
+- [ ] Returns `null` for 404 / not found (does not throw)
+- [ ] Returns the same `ExternalDocument` shape as `listDocuments`
+- [ ] Handles all content types that `listDocuments` can produce (e.g., if `listDocuments` returns both pages and blogposts, `getDocument` must handle both — not hardcode one endpoint)
+- [ ] Forwards `syncContext` if it needs cached state (user names, field maps, etc.)
+- [ ] Error handling is graceful (catches, logs, returns null or throws with context)
+- [ ] Does not redundantly re-fetch data already included in the initial API response (e.g., if comments come back with the post, don't fetch them again separately)
+
+## Step 10: Validate General Quality
+
+### fetchWithRetry Usage
+- [ ] All external API calls use `fetchWithRetry` from `@/lib/knowledge/documents/utils`
+- [ ] No raw `fetch()` calls to external APIs
+- [ ] `VALIDATE_RETRY_OPTIONS` used in `validateConfig`
+- [ ] If `validateConfig` calls a shared helper (e.g., `linearGraphQL`, `resolveId`), that helper must accept and forward `retryOptions` to `fetchWithRetry`
+- [ ] Default retry options used in `listDocuments`/`getDocument`
+
+### API Efficiency
+- [ ] APIs that support field selection (e.g., `$select`, `sysparm_fields`, `fields`) should request only the fields the connector needs — in both `listDocuments` AND `getDocument`
+- [ ] No redundant API calls: if a helper already fetches data (e.g., site metadata), callers should reuse the result instead of making a second call for the same information
+- [ ] Sequential per-item API calls (fetching details for each document in a loop) should be batched with `Promise.all` and a concurrency limit of 3-5
+
+### Error Handling
+- [ ] Individual document failures are caught and logged without aborting the sync
+- [ ] API error responses include status codes in error messages
+- [ ] No unhandled promise rejections in concurrent operations
+
+### Concurrency
+- [ ] Concurrent API calls use reasonable batch sizes (3-5 is typical)
+- [ ] No unbounded `Promise.all` over large arrays
+
+### Logging
+- [ ] Uses `createLogger` from `@sim/logger` (not `console.log`)
+- [ ] Logs sync progress at `info` level
+- [ ] Logs errors at `warn` or `error` level with context
+
+### Registry
+- [ ] Connector is exported from `connectors/{service}/index.ts`
+- [ ] Connector is registered in `connectors/registry.ts`
+- [ ] Registry key matches the connector's `id` field
+
+## Step 11: Report and Fix
+
+### Report Format
+
+Group findings by severity:
+
+**Critical** (will cause runtime errors, data loss, or auth failures):
+- Wrong API endpoint URL or HTTP method
+- Invalid or missing OAuth scopes (not in provider config)
+- Incorrect response field mapping (accessing wrong path)
+- SOQL/query fields that don't exist on the target object
+- Pagination that silently hits undocumented API limits
+- Missing error handling that would crash the sync
+- `requiredScopes` not a subset of OAuth provider scopes
+- Query/filter injection: user-controlled values interpolated into OData `$filter`, SOQL, or query strings without escaping
+
+**Warning** (incorrect behavior, data quality issues, or convention violations):
+- HTML content not stripped via `htmlToPlainText`
+- `getDocument` not forwarding `syncContext`
+- `getDocument` hardcoded to one content type when `listDocuments` returns multiple (e.g., only pages but not blogposts)
+- Missing `tagDefinition` for metadata fields returned by `mapTags`
+- Incorrect `useBasicAuth` or `supportsRefreshTokenRotation` in token refresh config
+- Invalid scope names that the API doesn't recognize (even if silently ignored)
+- Private resources excluded from name-based lookup despite scopes being available
+- Silent data truncation without logging
+- Size checks using `text.length` (character count) instead of `Buffer.byteLength` (byte count) for byte-based limits
+- URL-type config fields not normalized (protocol prefix, trailing slashes cause API failures)
+- `VALIDATE_RETRY_OPTIONS` not threaded through helper functions called by `validateConfig`
+
+**Suggestion** (minor improvements):
+- Missing incremental sync support despite API supporting it
+- Overly broad scopes that could be narrowed (not wrong, but could be tighter)
+- Source URL format could be more specific
+- Missing `orderBy` for deterministic pagination
+- Redundant API calls that could be cached in `syncContext`
+- Sequential per-item API calls that could be batched with `Promise.all` (concurrency 3-5)
+- API supports field selection but connector fetches all fields (e.g., missing `$select`, `sysparm_fields`, `fields`)
+- `getDocument` re-fetches data already included in the initial API response (e.g., comments returned with post)
+- Last page of pagination requests full `PAGE_SIZE` when fewer records remain (`Math.min(PAGE_SIZE, remaining)`)
+
+### Fix All Issues
+
+After reporting, fix every **critical** and **warning** issue. Apply **suggestions** where they don't add unnecessary complexity.
+
+### Validation Output
+
+After fixing, confirm:
+1. `bun run lint` passes
+2. TypeScript compiles clean
+3. Re-read all modified files to verify fixes are correct
+
+## Checklist Summary
+
+- [ ] Read connector implementation, types, utils, registry, and OAuth config
+- [ ] Pulled and read official API documentation for the service
+- [ ] Validated every API endpoint URL, method, headers, and body against API docs
+- [ ] Validated input sanitization: no query/filter injection, URL fields normalized
+- [ ] Validated OAuth scopes: `requiredScopes` ⊆ OAuth provider `scopes` in `oauth.ts`
+- [ ] Validated each scope is real and recognized by the service's API
+- [ ] Validated scopes are sufficient for all API endpoints the connector calls
+- [ ] Validated token refresh config (`useBasicAuth`, `supportsRefreshTokenRotation`)
+- [ ] Validated pagination: cursor names, page sizes, hasMore logic, no silent caps
+- [ ] Validated data transformation: plain text extraction, HTML stripping, content hashing
+- [ ] Validated tag definitions match mapTags output, correct fieldTypes
+- [ ] Validated config fields: canonical pairs, selector keys, required flags
+- [ ] Validated validateConfig: lightweight check, error messages, retry options
+- [ ] Validated getDocument: null on 404, all content types handled, no redundant re-fetches, syncContext forwarding
+- [ ] Validated fetchWithRetry used for all external calls (no raw fetch), VALIDATE_RETRY_OPTIONS threaded through helpers
+- [ ] Validated API efficiency: field selection used, no redundant calls, sequential fetches batched
+- [ ] Validated error handling: graceful failures, no unhandled rejections
+- [ ] Validated logging: createLogger, no console.log
+- [ ] Validated registry: correct export, correct key
+- [ ] Reported all issues grouped by severity
+- [ ] Fixed all critical and warning issues
+- [ ] Ran `bun run lint` after fixes
+- [ ] Verified TypeScript compiles clean
--- a/.claude/commands/validate-integration.md
+++ b/.claude/commands/validate-integration.md
@@ -0,0 +1,289 @@
+---
+description: Validate an existing Sim integration (tools, block, registry) against the service's API docs
+argument-hint: <service-name> [api-docs-url]
+---
+
+# Validate Integration Skill
+
+You are an expert auditor for Sim integrations. Your job is to thoroughly validate that an existing integration is correct, complete, and follows all conventions.
+
+## Your Task
+
+When the user asks you to validate an integration:
+1. Read the service's API documentation (via WebFetch or Context7)
+2. Read every tool, the block, and registry entries
+3. Cross-reference everything against the API docs and Sim conventions
+4. Report all issues found, grouped by severity (critical, warning, suggestion)
+5. Fix all issues after reporting them
+
+## Step 1: Gather All Files
+
+Read **every** file for the integration — do not skip any:
+
+```
+apps/sim/tools/{service}/          # All tool files, types.ts, index.ts
+apps/sim/blocks/blocks/{service}.ts # Block definition
+apps/sim/tools/registry.ts          # Tool registry entries for this service
+apps/sim/blocks/registry.ts         # Block registry entry for this service
+apps/sim/components/icons.tsx        # Icon definition
+apps/sim/lib/auth/auth.ts           # OAuth config — should use getCanonicalScopesForProvider()
+apps/sim/lib/oauth/oauth.ts         # OAuth provider config — single source of truth for scopes
+apps/sim/lib/oauth/utils.ts               # Scope utilities, SCOPE_DESCRIPTIONS for modal UI
+```
+
+## Step 2: Pull API Documentation
+
+Fetch the official API docs for the service. This is the **source of truth** for:
+- Endpoint URLs, HTTP methods, and auth headers
+- Required vs optional parameters
+- Parameter types and allowed values
+- Response shapes and field names
+- Pagination patterns (which param name, which response field)
+- Rate limits and error formats
+
+## Step 3: Validate Tools
+
+For **every** tool file, check:
+
+### Tool ID and Naming
+- [ ] Tool ID uses `snake_case`: `{service}_{action}` (e.g., `x_create_tweet`, `slack_send_message`)
+- [ ] Tool `name` is human-readable (e.g., `'X Create Tweet'`)
+- [ ] Tool `description` is a concise one-liner describing what it does
+- [ ] Tool `version` is set (`'1.0.0'` or `'2.0.0'` for V2)
+
+### Params
+- [ ] All required API params are marked `required: true`
+- [ ] All optional API params are marked `required: false`
+- [ ] Every param has explicit `required: true` or `required: false` — never omitted
+- [ ] Param types match the API (`'string'`, `'number'`, `'boolean'`, `'json'`)
+- [ ] Visibility is correct:
+  - `'hidden'` — ONLY for OAuth access tokens and system-injected params
+  - `'user-only'` — for API keys, credentials, and account-specific IDs the user must provide
+  - `'user-or-llm'` — for everything else (search queries, content, filters, IDs that could come from other blocks)
+- [ ] Every param has a `description` that explains what it does
+
+### Request
+- [ ] URL matches the API endpoint exactly (correct base URL, path segments, path params)
+- [ ] HTTP method matches the API spec (GET, POST, PUT, PATCH, DELETE)
+- [ ] Headers include correct auth pattern:
+  - OAuth: `Authorization: Bearer ${params.accessToken}`
+  - API Key: correct header name and format per the service's docs
+- [ ] `Content-Type` header is set for POST/PUT/PATCH requests
+- [ ] Body sends all required fields and only includes optional fields when provided
+- [ ] For GET requests with query params: URL is constructed correctly with query string
+- [ ] ID fields in URL paths are `.trim()`-ed to prevent copy-paste whitespace errors
+- [ ] Path params use template literals correctly: `` `https://api.service.com/v1/${params.id.trim()}` ``
+
+### Response / transformResponse
+- [ ] Correctly parses the API response (`await response.json()`)
+- [ ] Extracts the right fields from the response structure (e.g., `data.data` vs `data` vs `data.results`)
+- [ ] All nullable fields use `?? null`
+- [ ] All optional arrays use `?? []`
+- [ ] Error cases are handled: checks for missing/empty data and returns meaningful error
+- [ ] Does NOT do raw JSON dumps — extracts meaningful, individual fields
+
+### Outputs
+- [ ] All output fields match what the API actually returns
+- [ ] No fields are missing that the API provides and users would commonly need
+- [ ] No phantom fields defined that the API doesn't return
+- [ ] `optional: true` is set on fields that may not exist in all responses
+- [ ] When using `type: 'json'` and the shape is known, `properties` defines the inner fields
+- [ ] When using `type: 'array'`, `items` defines the item structure with `properties`
+- [ ] Field descriptions are accurate and helpful
+
+### Types (types.ts)
+- [ ] Has param interfaces for every tool (e.g., `XCreateTweetParams`)
+- [ ] Has response interfaces for every tool (extending `ToolResponse`)
+- [ ] Optional params use `?` in the interface (e.g., `replyTo?: string`)
+- [ ] Field names in types match actual API field names
+- [ ] Shared response types are properly reused (e.g., `XTweetResponse` shared across tweet tools)
+
+### Barrel Export (index.ts)
+- [ ] Every tool is exported
+- [ ] All types are re-exported (`export * from './types'`)
+- [ ] No orphaned exports (tools that don't exist)
+
+### Tool Registry (tools/registry.ts)
+- [ ] Every tool is imported and registered
+- [ ] Registry keys use snake_case and match tool IDs exactly
+- [ ] Entries are in alphabetical order within the file
+
+## Step 4: Validate Block
+
+### Block ↔ Tool Alignment (CRITICAL)
+
+This is the most important validation — the block must be perfectly aligned with every tool it references.
+
+For **each tool** in `tools.access`:
+- [ ] The operation dropdown has an option whose ID matches the tool ID (or the `tools.config.tool` function correctly maps to it)
+- [ ] Every **required** tool param (except `accessToken`) has a corresponding subBlock input that is:
+  - Shown when that operation is selected (correct `condition`)
+  - Marked as `required: true` (or conditionally required)
+- [ ] Every **optional** tool param has a corresponding subBlock input (or is intentionally omitted if truly never needed)
+- [ ] SubBlock `id` values are unique across the entire block — no duplicates even across different conditions
+- [ ] The `tools.config.tool` function returns the correct tool ID for every possible operation value
+- [ ] The `tools.config.params` function correctly maps subBlock IDs to tool param names when they differ
+
+### SubBlocks
+- [ ] Operation dropdown lists ALL tool operations available in `tools.access`
+- [ ] Dropdown option labels are human-readable and descriptive
+- [ ] Conditions use correct syntax:
+  - Single value: `{ field: 'operation', value: 'x_create_tweet' }`
+  - Multiple values (OR): `{ field: 'operation', value: ['x_create_tweet', 'x_delete_tweet'] }`
+  - Negation: `{ field: 'operation', value: 'delete', not: true }`
+  - Compound: `{ field: 'op', value: 'send', and: { field: 'type', value: 'dm' } }`
+- [ ] Condition arrays include ALL operations that use that field — none missing
+- [ ] `dependsOn` is set for fields that need other values (selectors depending on credential, cascading dropdowns)
+- [ ] SubBlock types match tool param types:
+  - Enum/fixed options → `dropdown`
+  - Free text → `short-input`
+  - Long text/content → `long-input`
+  - True/false → `dropdown` with Yes/No options (not `switch` unless purely UI toggle)
+  - Credentials → `oauth-input` with correct `serviceId`
+- [ ] Dropdown `value: () => 'default'` is set for dropdowns with a sensible default
+
+### Advanced Mode
+- [ ] Optional, rarely-used fields are set to `mode: 'advanced'`:
+  - Pagination tokens / next tokens
+  - Time range filters (start/end time)
+  - Sort order / direction options
+  - Max results / per page limits
+  - Reply settings / threading options
+  - Rarely used IDs (reply-to, quote-tweet, etc.)
+  - Exclude filters
+- [ ] **Required** fields are NEVER set to `mode: 'advanced'`
+- [ ] Fields that users fill in most of the time are NOT set to `mode: 'advanced'`
+
+### WandConfig
+- [ ] Timestamp fields have `wandConfig` with `generationType: 'timestamp'`
+- [ ] Comma-separated list fields have `wandConfig` with a descriptive prompt
+- [ ] Complex filter/query fields have `wandConfig` with format examples in the prompt
+- [ ] All `wandConfig` prompts end with "Return ONLY the [format] - no explanations, no extra text."
+- [ ] `wandConfig.placeholder` describes what to type in natural language
+
+### Tools Config
+- [ ] `tools.access` lists **every** tool ID the block can use — none missing
+- [ ] `tools.config.tool` returns the correct tool ID for each operation
+- [ ] Type coercions are in `tools.config.params` (runs at execution time), NOT in `tools.config.tool` (runs at serialization time before variable resolution)
+- [ ] `tools.config.params` handles:
+  - `Number()` conversion for numeric params that come as strings from inputs
+  - `Boolean` / string-to-boolean conversion for toggle params
+  - Empty string → `undefined` conversion for optional dropdown values
+  - Any subBlock ID → tool param name remapping
+- [ ] No `Number()`, `JSON.parse()`, or other coercions in `tools.config.tool` — these would destroy dynamic references like `<Block.output>`
+
+### Block Outputs
+- [ ] Outputs cover the key fields returned by ALL tools (not just one operation)
+- [ ] Output types are correct (`'string'`, `'number'`, `'boolean'`, `'json'`)
+- [ ] `type: 'json'` outputs either:
+  - Describe inner fields in the description string (GOOD): `'User profile (id, name, username, bio)'`
+  - Use nested output definitions (BEST): `{ id: { type: 'string' }, name: { type: 'string' } }`
+- [ ] No opaque `type: 'json'` with vague descriptions like `'Response data'`
+- [ ] Outputs that only appear for certain operations use `condition` if supported, or document which operations return them
+
+### Block Metadata
+- [ ] `type` is snake_case (e.g., `'x'`, `'cloudflare'`)
+- [ ] `name` is human-readable (e.g., `'X'`, `'Cloudflare'`)
+- [ ] `description` is a concise one-liner
+- [ ] `longDescription` provides detail for docs
+- [ ] `docsLink` points to `'https://docs.sim.ai/tools/{service}'`
+- [ ] `category` is `'tools'`
+- [ ] `bgColor` uses the service's brand color hex
+- [ ] `icon` references the correct icon component from `@/components/icons`
+- [ ] `authMode` is set correctly (`AuthMode.OAuth` or `AuthMode.ApiKey`)
+- [ ] Block is registered in `blocks/registry.ts` alphabetically
+
+### Block Inputs
+- [ ] `inputs` section lists all subBlock params that the block accepts
+- [ ] Input types match the subBlock types
+- [ ] When using `canonicalParamId`, inputs list the canonical ID (not the raw subBlock IDs)
+
+## Step 5: Validate OAuth Scopes (if OAuth service)
+
+Scopes are centralized — the single source of truth is `OAUTH_PROVIDERS` in `lib/oauth/oauth.ts`.
+
+- [ ] Scopes defined in `lib/oauth/oauth.ts` under `OAUTH_PROVIDERS[provider].services[service].scopes`
+- [ ] `auth.ts` uses `getCanonicalScopesForProvider(providerId)` — NOT a hardcoded array
+- [ ] Block `requiredScopes` uses `getScopesForService(serviceId)` — NOT a hardcoded array
+- [ ] No hardcoded scope arrays in `auth.ts` or block files (should all use utility functions)
+- [ ] Each scope has a human-readable description in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts`
+- [ ] No excess scopes that aren't needed by any tool
+
+## Step 6: Validate Pagination Consistency
+
+If any tools support pagination:
+- [ ] Pagination param names match the API docs (e.g., `pagination_token` vs `next_token` vs `cursor`)
+- [ ] Different API endpoints that use different pagination param names have separate subBlocks in the block
+- [ ] Pagination response fields (`nextToken`, `cursor`, etc.) are included in tool outputs
+- [ ] Pagination subBlocks are set to `mode: 'advanced'`
+
+## Step 7: Validate Error Handling
+
+- [ ] `transformResponse` checks for error conditions before accessing data
+- [ ] Error responses include meaningful messages (not just generic "failed")
+- [ ] HTTP error status codes are handled (check `response.ok` or status codes)
+
+## Step 8: Report and Fix
+
+### Report Format
+
+Group findings by severity:
+
+**Critical** (will cause runtime errors or incorrect behavior):
+- Wrong endpoint URL or HTTP method
+- Missing required params or wrong `required` flag
+- Incorrect response field mapping (accessing wrong path in response)
+- Missing error handling that would cause crashes
+- Tool ID mismatch between tool file, registry, and block `tools.access`
+- OAuth scopes missing in `auth.ts` that tools need
+- `tools.config.tool` returning wrong tool ID for an operation
+- Type coercions in `tools.config.tool` instead of `tools.config.params`
+
+**Warning** (follows conventions incorrectly or has usability issues):
+- Optional field not set to `mode: 'advanced'`
+- Missing `wandConfig` on timestamp/complex fields
+- Wrong `visibility` on params (e.g., `'hidden'` instead of `'user-or-llm'`)
+- Missing `optional: true` on nullable outputs
+- Opaque `type: 'json'` without property descriptions
+- Missing `.trim()` on ID fields in request URLs
+- Missing `?? null` on nullable response fields
+- Block condition array missing an operation that uses that field
+- Hardcoded scope arrays instead of using `getScopesForService()` / `getCanonicalScopesForProvider()`
+- Missing scope description in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts`
+
+**Suggestion** (minor improvements):
+- Better description text
+- Inconsistent naming across tools
+- Missing `longDescription` or `docsLink`
+- Pagination fields that could benefit from `wandConfig`
+
+### Fix All Issues
+
+After reporting, fix every **critical** and **warning** issue. Apply **suggestions** where they don't add unnecessary complexity.
+
+### Validation Output
+
+After fixing, confirm:
+1. `bun run lint` passes with no fixes needed
+2. TypeScript compiles clean (no type errors)
+3. Re-read all modified files to verify fixes are correct
+
+## Checklist Summary
+
+- [ ] Read ALL tool files, block, types, index, and registries
+- [ ] Pulled and read official API documentation
+- [ ] Validated every tool's ID, params, request, response, outputs, and types against API docs
+- [ ] Validated block ↔ tool alignment (every tool param has a subBlock, every condition is correct)
+- [ ] Validated advanced mode on optional/rarely-used fields
+- [ ] Validated wandConfig on timestamps and complex inputs
+- [ ] Validated tools.config mapping, tool selector, and type coercions
+- [ ] Validated block outputs match what tools return, with typed JSON where possible
+- [ ] Validated OAuth scopes use centralized utilities (getScopesForService, getCanonicalScopesForProvider) — no hardcoded arrays
+- [ ] Validated scope descriptions exist in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts` for all scopes
+- [ ] Validated pagination consistency across tools and block
+- [ ] Validated error handling (error checks, meaningful messages)
+- [ ] Validated registry entries (tools and block, alphabetical, correct imports)
+- [ ] Reported all issues grouped by severity
+- [ ] Fixed all critical and warning issues
+- [ ] Ran `bun run lint` after fixes
+- [ ] Verified TypeScript compiles clean
--- a/.claude/commands/validate-trigger.md
+++ b/.claude/commands/validate-trigger.md
@@ -0,0 +1,212 @@
+---
+description: Validate an existing Sim webhook trigger against provider API docs and repository conventions
+argument-hint: <service-name> [api-docs-url]
+---
+
+# Validate Trigger
+
+You are an expert auditor for Sim webhook triggers. Your job is to validate that an existing trigger implementation is correct, complete, secure, and aligned across all layers.
+
+## Your Task
+
+1. Read the service's webhook/API documentation (via WebFetch)
+2. Read every trigger file, provider handler, and registry entry
+3. Cross-reference against the API docs and Sim conventions
+4. Report all issues grouped by severity (critical, warning, suggestion)
+5. Fix all issues after reporting them
+
+## Step 1: Gather All Files
+
+Read **every** file for the trigger — do not skip any:
+
+```
+apps/sim/triggers/{service}/           # All trigger files, utils.ts, index.ts
+apps/sim/lib/webhooks/providers/{service}.ts  # Provider handler (if exists)
+apps/sim/lib/webhooks/providers/registry.ts   # Handler registry
+apps/sim/triggers/registry.ts                 # Trigger registry
+apps/sim/blocks/blocks/{service}.ts           # Block definition (trigger wiring)
+```
+
+Also read for reference:
+```
+apps/sim/lib/webhooks/providers/types.ts            # WebhookProviderHandler interface
+apps/sim/lib/webhooks/providers/utils.ts            # Shared helpers (createHmacVerifier, etc.)
+apps/sim/lib/webhooks/provider-subscription-utils.ts    # Subscription helpers
+apps/sim/lib/webhooks/processor.ts                  # Central webhook processor
+```
+
+## Step 2: Pull API Documentation
+
+Fetch the service's official webhook documentation. This is the **source of truth** for:
+- Webhook event types and payload shapes
+- Signature/auth verification method (HMAC algorithm, header names, secret format)
+- Challenge/verification handshake requirements
+- Webhook subscription API (create/delete endpoints, if applicable)
+- Retry behavior and delivery guarantees
+
+## Step 3: Validate Trigger Definitions
+
+### utils.ts
+- [ ] `{service}TriggerOptions` lists all trigger IDs accurately
+- [ ] `{service}SetupInstructions` provides clear, correct steps for the service
+- [ ] `build{Service}ExtraFields` includes relevant filter/config fields with correct `condition`
+- [ ] Output builders expose all meaningful fields from the webhook payload
+- [ ] Output builders do NOT use `optional: true` or `items` (tool-output-only features)
+- [ ] Nested output objects correctly model the payload structure
+
+### Trigger Files
+- [ ] Exactly one primary trigger has `includeDropdown: true`
+- [ ] All secondary triggers do NOT have `includeDropdown`
+- [ ] All triggers use `buildTriggerSubBlocks` helper (not hand-rolled subBlocks)
+- [ ] Every trigger's `id` matches the convention `{service}_{event_name}`
+- [ ] Every trigger's `provider` matches the service name used in the handler registry
+- [ ] `index.ts` barrel exports all triggers
+
+### Trigger ↔ Provider Alignment (CRITICAL)
+- [ ] Every trigger ID referenced in `matchEvent` logic exists in `{service}TriggerOptions`
+- [ ] Event matching logic in the provider correctly maps trigger IDs to service event types
+- [ ] Event matching logic in `is{Service}EventMatch` (if exists) correctly identifies events per the API docs
+
+## Step 4: Validate Provider Handler
+
+### Auth Verification
+- [ ] `verifyAuth` correctly validates webhook signatures per the service's documentation
+- [ ] HMAC algorithm matches (SHA-1, SHA-256, SHA-512)
+- [ ] Signature header name matches the API docs exactly
+- [ ] Signature format is handled (raw hex, `sha256=` prefix, base64, etc.)
+- [ ] Uses `safeCompare` for timing-safe comparison (no `===`)
+- [ ] If `webhookSecret` is required, handler rejects when it's missing (fail-closed)
+- [ ] Signature is computed over raw body (not parsed JSON)
+
+### Event Matching
+- [ ] `matchEvent` returns `boolean` (not `NextResponse` or other values)
+- [ ] Challenge/verification events are excluded from matching (e.g., `endpoint.url_validation`)
+- [ ] When `triggerId` is a generic webhook ID, all events pass through
+- [ ] When `triggerId` is specific, only matching events pass
+- [ ] Event matching logic uses dynamic `await import()` for trigger utils (avoids circular deps)
+
+### formatInput (CRITICAL)
+- [ ] Every key in the `formatInput` return matches a key in the trigger `outputs` schema
+- [ ] Every key in the trigger `outputs` schema is populated by `formatInput`
+- [ ] No extra undeclared keys that users can't discover in the UI
+- [ ] No wrapper objects (`webhook: { ... }`, `{service}: { ... }`)
+- [ ] Nested output paths exist at the correct depth (e.g., `resource.id` actually has `resource: { id: ... }`)
+- [ ] `null` is used for missing optional fields (not empty strings or empty objects)
+- [ ] Returns `{ input: { ... } }` — not a bare object
+
+### Idempotency
+- [ ] `extractIdempotencyId` returns a stable, unique key per delivery
+- [ ] Uses provider-specific delivery IDs when available (e.g., `X-Request-Id`, `Linear-Delivery`, `svix-id`)
+- [ ] Falls back to content-based ID (e.g., `${type}:${id}`) when no delivery header exists
+- [ ] Does NOT include timestamps in the idempotency key (would break dedup on retries)
+
+### Challenge Handling (if applicable)
+- [ ] `handleChallenge` correctly implements the service's URL verification handshake
+- [ ] Returns the expected response format per the API docs
+- [ ] Env-backed secrets are resolved via `resolveEnvVarsInObject` if needed
+
+## Step 5: Validate Automatic Subscription Lifecycle
+
+If the service supports programmatic webhook creation:
+
+### createSubscription
+- [ ] Calls the correct API endpoint to create a webhook
+- [ ] Sends the correct event types/filters
+- [ ] Passes the notification URL from `getNotificationUrl(ctx.webhook)`
+- [ ] Returns `{ providerConfigUpdates: { externalId } }` with the external webhook ID
+- [ ] Throws on failure (orchestration handles rollback)
+- [ ] Provides user-friendly error messages (401 → "Invalid API Key", etc.)
+
+### deleteSubscription
+- [ ] Calls the correct API endpoint to delete the webhook
+- [ ] Handles 404 gracefully (webhook already deleted)
+- [ ] Never throws — catches errors and logs non-fatally
+- [ ] Skips gracefully when `apiKey` or `externalId` is missing
+
+### Orchestration Isolation
+- [ ] NO provider-specific logic in `route.ts`, `provider-subscriptions.ts`, or `deploy.ts`
+- [ ] All subscription logic lives on the handler (`createSubscription`/`deleteSubscription`)
+
+## Step 6: Validate Registration and Block Wiring
+
+### Trigger Registry (`triggers/registry.ts`)
+- [ ] All triggers are imported and registered
+- [ ] Registry keys match trigger IDs exactly
+- [ ] No orphaned entries (triggers that don't exist)
+
+### Provider Handler Registry (`providers/registry.ts`)
+- [ ] Handler is imported and registered (if handler exists)
+- [ ] Registry key matches the `provider` field on the trigger configs
+- [ ] Entries are in alphabetical order
+
+### Block Wiring (`blocks/blocks/{service}.ts`)
+- [ ] Block has `triggers.enabled: true`
+- [ ] `triggers.available` lists all trigger IDs
+- [ ] All trigger subBlocks are spread into `subBlocks`: `...getTrigger('id').subBlocks`
+- [ ] No trigger IDs in `triggers.available` that aren't in the registry
+- [ ] No trigger subBlocks spread that aren't in `triggers.available`
+
+## Step 7: Validate Security
+
+- [ ] Webhook secrets are never logged (not even at debug level)
+- [ ] Auth verification runs before any event processing
+- [ ] No secret comparison uses `===` (must use `safeCompare` or `crypto.timingSafeEqual`)
+- [ ] Timestamp/replay protection is reasonable (not too tight for retries, not too loose for security)
+- [ ] Raw body is used for signature verification (not re-serialized JSON)
+
+## Step 8: Report and Fix
+
+### Report Format
+
+Group findings by severity:
+
+**Critical** (runtime errors, security issues, or data loss):
+- Wrong HMAC algorithm or header name
+- `formatInput` keys don't match trigger `outputs`
+- Missing `verifyAuth` when the service sends signed webhooks
+- `matchEvent` returns non-boolean values
+- Provider-specific logic leaking into shared orchestration files
+- Trigger IDs mismatch between trigger files, registry, and block
+- `createSubscription` calling wrong API endpoint
+- Auth comparison using `===` instead of `safeCompare`
+
+**Warning** (convention violations or usability issues):
+- Missing `extractIdempotencyId` when the service provides delivery IDs
+- Timestamps in idempotency keys (breaks dedup on retries)
+- Missing challenge handling when the service requires URL verification
+- Output schema missing fields that `formatInput` returns (undiscoverable data)
+- Overly tight timestamp skew window that rejects legitimate retries
+- `matchEvent` not filtering challenge/verification events
+- Setup instructions missing important steps
+
+**Suggestion** (minor improvements):
+- More specific output field descriptions
+- Additional output fields that could be exposed
+- Better error messages in `createSubscription`
+- Logging improvements
+
+### Fix All Issues
+
+After reporting, fix every **critical** and **warning** issue. Apply **suggestions** where they don't add unnecessary complexity.
+
+### Validation Output
+
+After fixing, confirm:
+1. `bun run type-check` passes
+2. Re-read all modified files to verify fixes are correct
+3. Provider handler tests pass (if they exist): `bun test {service}`
+
+## Checklist Summary
+
+- [ ] Read all trigger files, provider handler, types, registries, and block
+- [ ] Pulled and read official webhook/API documentation
+- [ ] Validated trigger definitions: options, instructions, extra fields, outputs
+- [ ] Validated primary/secondary trigger distinction (`includeDropdown`)
+- [ ] Validated provider handler: auth, matchEvent, formatInput, idempotency
+- [ ] Validated output alignment: every `outputs` key ↔ every `formatInput` key
+- [ ] Validated subscription lifecycle: createSubscription, deleteSubscription, no shared-file edits
+- [ ] Validated registration: trigger registry, handler registry, block wiring
+- [ ] Validated security: safe comparison, no secret logging, replay protection
+- [ ] Reported all issues grouped by severity
+- [ ] Fixed all critical and warning issues
+- [ ] `bun run type-check` passes after fixes
--- a/.claude/commands/you-might-not-need-a-callback.md
+++ b/.claude/commands/you-might-not-need-a-callback.md
@@ -0,0 +1,52 @@
+---
+description: Analyze and fix useCallback anti-patterns in your code
+argument-hint: [scope] [fix=true|false]
+---
+
+# You Might Not Need a Callback
+
+Arguments:
+- scope: what to analyze (default: your current changes). Examples: "diff to main", "PR #123", "src/components/", "whole codebase"
+- fix: whether to apply fixes (default: true). Set to false to only propose changes.
+
+User arguments: $ARGUMENTS
+
+## References
+
+Read before analyzing:
+1. https://react.dev/reference/react/useCallback — official docs on when useCallback is actually needed
+
+## The one rule that matters
+
+`useCallback` is only useful when **something observes the reference**. Ask: does anything care if this function gets a new identity on re-render?
+
+Observers that care about reference stability:
+- A `useEffect` that lists the function in its deps array
+- A `useMemo` that lists the function in its deps array
+- Another `useCallback` that lists the function in its deps array
+- A child component wrapped in `React.memo` that receives the function as a prop
+
+If none of those apply — if the function is only called inline, or passed to a non-memoized child, or assigned to a native element event — the reference is unobserved and `useCallback` adds overhead with zero benefit.
+
+## Anti-patterns to detect
+
+1. **No observer tracks the reference**: The function is only called inline in the same component, or passed to a non-memoized child, or used as a native element handler (`<button onClick={fn}>`). Nothing re-runs or bails out based on reference identity. Remove `useCallback`.
+2. **useCallback with deps that change every render**: If a dep is a plain object/array created inline, or state that changes on every interaction, memoization buys nothing — the function gets a new identity anyway.
+3. **useCallback on handlers passed only to native elements**: `<button onClick={fn}>` — React never does reference equality on native element props. No benefit.
+4. **useCallback wrapping functions that return new objects/arrays**: Stable function identity, unstable return value — memoization is at the wrong level. Use `useMemo` on the return value instead, or restructure.
+5. **useCallback with empty deps when deps are needed**: Stale closure — reads initial values forever. This is a correctness bug, not just a performance issue.
+6. **Pairing useCallback + React.memo on trivially cheap renders**: If the child renders in < 1ms and re-renders rarely, the memo infrastructure costs more than it saves.
+
+## Patterns that ARE correct — do not flag
+
+- `useCallback` whose result is in a `useEffect` dep array — prevents the effect from re-running on every render
+- `useCallback` whose result is in a `useMemo` dep array — prevents the memo from recomputing on every render
+- `useCallback` whose result is a dep of another `useCallback` — stabilises a callback chain
+- `useCallback` passed to a `React.memo`-wrapped child — the whole point of the pattern
+- This codebase's ref pattern: `useRef` + callback with empty deps that reads the ref inside — correct, do not flag
+
+## Steps
+
+1. Read the reference above
+2. Analyze the specified scope for the anti-patterns listed above
+3. If fix=true, apply the fixes. If fix=false, propose the fixes without applying.
--- a/.claude/commands/you-might-not-need-a-memo.md
+++ b/.claude/commands/you-might-not-need-a-memo.md
@@ -0,0 +1,33 @@
+---
+description: Analyze and fix useMemo/React.memo anti-patterns in your code
+argument-hint: [scope] [fix=true|false]
+---
+
+# You Might Not Need a Memo
+
+Arguments:
+- scope: what to analyze (default: your current changes). Examples: "diff to main", "PR #123", "src/components/", "whole codebase"
+- fix: whether to apply fixes (default: true). Set to false to only propose changes.
+
+User arguments: $ARGUMENTS
+
+## References
+
+Read before analyzing:
+1. https://overreacted.io/before-you-memo/ — two techniques to avoid memo entirely
+
+## Anti-patterns to detect
+
+1. **State can be moved down instead of memoizing**: Move state into a smaller child so the slow component stops re-rendering without memo.
+2. **Children can be lifted up**: Extract stateful part, pass expensive subtree as `children` — children as props don't re-render when parent state changes.
+3. **useMemo on cheap computations**: Small array filters, string concat, arithmetic don't need memoization.
+4. **useMemo with constantly-changing deps**: Deps change every render = useMemo does nothing.
+5. **useMemo to stabilize props for non-memoized children**: If the child isn't wrapped in React.memo, stable references don't matter.
+6. **React.memo on components that always receive new props**: Fix the parent instead.
+7. **useMemo for derived state**: Just compute inline during render.
+
+## Steps
+
+1. Read the reference above
+2. Analyze the specified scope for the anti-patterns listed above
+3. If fix=true, apply the fixes. If fix=false, propose the fixes without applying.
--- a/.claude/commands/you-might-not-need-an-effect.md
+++ b/.claude/commands/you-might-not-need-an-effect.md
@@ -0,0 +1,17 @@
+---
+description: Analyze and fix useEffect anti-patterns in your code
+argument-hint: [scope] [fix=true|false]
+---
+
+# You Might Not Need an Effect
+
+Arguments:
+- scope: what to analyze (default: your current changes). Examples: "diff to main", "PR #123", "src/components/", "whole codebase"
+- fix: whether to apply fixes (default: true). Set to false to only propose changes.
+
+User arguments: $ARGUMENTS
+
+Steps:
+1. Read https://react.dev/learn/you-might-not-need-an-effect to understand the guidelines
+2. Analyze the specified scope for useEffect anti-patterns
+3. If fix=true, apply the fixes. If fix=false, propose the fixes without applying.
--- a/.claude/commands/you-might-not-need-state.md
+++ b/.claude/commands/you-might-not-need-state.md
@@ -0,0 +1,38 @@
+---
+description: Analyze and fix unnecessary useState, derived state, and server-state-in-local-state anti-patterns
+argument-hint: [scope] [fix=true|false]
+---
+
+# You Might Not Need State
+
+Arguments:
+- scope: what to analyze (default: your current changes). Examples: "diff to main", "PR #123", "src/components/", "whole codebase"
+- fix: whether to apply fixes (default: true). Set to false to only propose changes.
+
+User arguments: $ARGUMENTS
+
+## Context
+
+This codebase uses React Query for all server state and Zustand for client-only global state. useState should only be used for ephemeral UI concerns (open/closed, hover, local form input). Server data should never be copied into useState or Zustand — React Query is the single source of truth.
+
+## References
+
+Read these before analyzing:
+1. https://react.dev/learn/choosing-the-state-structure — 5 principles for structuring state
+2. https://tkdodo.eu/blog/dont-over-use-state — never store derived/computed values in state
+3. https://tkdodo.eu/blog/putting-props-to-use-state — never mirror props into state via useEffect
+
+## Anti-patterns to detect
+
+1. **Derived state stored in useState**: If a value can be computed from props, other state, or query data, compute it inline during render instead of storing it in state.
+2. **Server state copied into useState**: Never `useState` + `useEffect` to sync React Query data into local state. Use query data directly. The only exception is forms where users edit server data.
+3. **Props mirrored into state**: Never `useState(prop)` + `useEffect(() => setState(prop))`. Use the prop directly, or use a key to reset component state.
+4. **Chained useEffect state updates**: Never chain Effects that set state to trigger other Effects. Calculate all derived values in the event handler or inline during render.
+5. **Storing objects when an ID suffices**: Store `selectedId` not a copy of the selected object. Derive the object: `items.find(i => i.id === selectedId)`.
+6. **State that duplicates Zustand or React Query**: If the data already lives in a store or query cache, don't create a parallel useState.
+
+## Steps
+
+1. Read the references above to understand the guidelines
+2. Analyze the specified scope for the anti-patterns listed above
+3. If fix=true, apply the fixes. If fix=false, propose the fixes without applying.
--- a/.claude/rules/constitution.md
+++ b/.claude/rules/constitution.md
@@ -0,0 +1,71 @@
+# 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.
--- a/.claude/rules/global.md
+++ b/.claude/rules/global.md
@@ -1,7 +1,10 @@
 # Global Standards

 ## Logging
-Import `createLogger` from `sim/logger`. Use `logger.info`, `logger.warn`, `logger.error` instead of `console.log`.
+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.
@@ -9,5 +12,47 @@ 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)` — async delay. Never write `new Promise(resolve => setTimeout(resolve, ms))`
+- `toError(value)` — normalize unknown caught values to `Error`. Never write `e instanceof Error ? e : new Error(String(e))`
+- `toError(value).message` — get error message safely. Never write `e instanceof Error ? e.message : String(e)`
+
+```typescript
+// ✗ Bad
+await new Promise(resolve => setTimeout(resolve, 1000))
+const msg = error instanceof Error ? error.message : String(error)
+const err = error instanceof Error ? error : new Error(String(error))
+
+// ✓ Good
+import { sleep } from '@sim/utils/helpers'
+import { toError } from '@sim/utils/errors'
+await sleep(1000)
+const msg = toError(error).message
+const err = toError(error)
+```
+
 ## Package Manager
 Use `bun` and `bunx`, not `npm` and `npx`.
--- a/.claude/rules/landing-seo-geo.md
+++ b/.claude/rules/landing-seo-geo.md
@@ -0,0 +1,26 @@
+---
+paths:
+  - "apps/sim/app/(home)/**/*.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 agents", "agentic workflows".
+- **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.
--- a/.claude/rules/sim-queries.md
+++ b/.claude/rules/sim-queries.md
@@ -5,62 +5,122 @@ paths:

 # React Query Patterns

-All React Query hooks live in `hooks/queries/`.
+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 keys 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,
-  list: (workspaceId?: string) => [...entityKeys.all, 'list', workspaceId ?? ''] as const,
-  detail: (id?: string) => [...entityKeys.all, 'detail', id ?? ''] 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
+// 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
+
 ```typescript
+async function fetchEntities(workspaceId: string, signal?: AbortSignal) {
+  const response = await fetch(`/api/entities?workspaceId=${workspaceId}`, { signal })
+  if (!response.ok) throw new Error('Failed to fetch entities')
+  return response.json()
+}
+
 export function useEntityList(workspaceId?: string, options?: { enabled?: boolean }) {
  return useQuery({
    queryKey: entityKeys.list(workspaceId),
-    queryFn: () => fetchEntities(workspaceId as string),
+    queryFn: ({ signal }) => fetchEntities(workspaceId as string, signal),
    enabled: Boolean(workspaceId) && (options?.enabled ?? true),
    staleTime: 60 * 1000,
-    placeholderData: keepPreviousData,
+    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)
+
 ```typescript
 export function useCreateEntity() {
  const queryClient = useQueryClient()
  return useMutation({
    mutationFn: async (variables) => { /* fetch POST */ },
-    onSuccess: () => queryClient.invalidateQueries({ queryKey: entityKeys.all }),
+    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])
+```
+
 ## Naming

 - **Keys**: `entityKeys`
 - **Query hooks**: `useEntity`, `useEntityList`
- **Mutation hooks**: `useCreateEntity`, `useUpdateEntity`
- **Fetch functions**: `fetchEntity` (private)
+- **Mutation hooks**: `useCreateEntity`, `useUpdateEntity`, `useDeleteEntity`
+- **Fetch functions**: `fetchEntity`, `fetchEntities` (private)
--- a/.claude/rules/sim-testing.md
+++ b/.claude/rules/sim-testing.md
@@ -8,51 +8,256 @@ paths:

 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`
+
 ## Structure

 ```typescript
 /**
 * @vitest-environment node
 */
-import { databaseMock, loggerMock } from '@sim/testing'
-import { describe, expect, it, vi } from 'vitest'
+import { createMockRequest } from '@sim/testing'
+import { beforeEach, describe, expect, it, vi } from 'vitest'

-vi.mock('@sim/db', () => databaseMock)
-vi.mock('@sim/logger', () => loggerMock)
+const { mockGetSession } = vi.hoisted(() => ({
+  mockGetSession: vi.fn(),
+}))

-import { myFunction } from '@/lib/feature'
+vi.mock('@/lib/auth', () => ({
+  auth: { api: { getSession: vi.fn() } },
+  getSession: mockGetSession,
+}))

-describe('myFunction', () => {
-  beforeEach(() => vi.clearAllMocks())
-  it.concurrent('isolated tests run in parallel', () => { ... })
+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)` |
+| `@/lib/audit/log` | `auditMock`, `auditMockFns` | `vi.mock('@/lib/audit/log', () => 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/feature-flags` | `featureFlagsMock` | `vi.mock('@/lib/core/config/feature-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 mocks.
+Always prefer over local test data.

 | Category | Utilities |
 |----------|-----------|
-| **Mocks** | `loggerMock`, `databaseMock`, `setupGlobalFetchMock()` |
-| **Factories** | `createSession()`, `createWorkflowRecord()`, `createBlock()`, `createExecutorContext()` |
+| **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
+## Rules Summary

-1. `@vitest-environment node` directive at file top
-2. `vi.mock()` calls before importing mocked modules
-3. `@sim/testing` utilities over local mocks
-4. `it.concurrent` for isolated tests (no shared mutable state)
-5. `beforeEach(() => vi.clearAllMocks())` to reset state
-
-## Hoisted Mocks
-
-For mutable mock references:
-
-```typescript
-const mockFn = vi.hoisted(() => vi.fn())
-vi.mock('@/lib/module', () => ({ myFunction: mockFn }))
-mockFn.mockResolvedValue({ data: 'test' })
-```
+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()`
--- a/.cursor/commands/add-block.md
+++ b/.cursor/commands/add-block.md
@@ -0,0 +1,826 @@
+# Add Block Skill
+
+You are an expert at creating block configurations for Sim. You understand the serializer, subBlock types, conditions, dependsOn, modes, and all UI patterns.
+
+## Your Task
+
+When the user asks you to create a block:
+1. Create the block file in `apps/sim/blocks/blocks/{service}.ts`
+2. Configure all subBlocks with proper types, conditions, and dependencies
+3. Wire up tools correctly
+
+## Block Configuration Structure
+
+```typescript
+import { {ServiceName}Icon } from '@/components/icons'
+import type { BlockConfig } from '@/blocks/types'
+import { AuthMode, IntegrationType } from '@/blocks/types'
+import { getScopesForService } from '@/lib/oauth/utils'
+
+export const {ServiceName}Block: BlockConfig = {
+  type: '{service}',                    // snake_case identifier
+  name: '{Service Name}',               // Human readable
+  description: 'Brief description',     // One sentence
+  longDescription: 'Detailed description for docs',
+  docsLink: 'https://docs.sim.ai/tools/{service}',
+  category: 'tools',                    // 'tools' | 'blocks' | 'triggers'
+  integrationType: IntegrationType.X,   // Primary category (see IntegrationType enum)
+  tags: ['oauth', 'api'],              // Cross-cutting tags (see IntegrationTag type)
+  bgColor: '#HEXCOLOR',                 // Brand color
+  icon: {ServiceName}Icon,
+
+  // Auth mode
+  authMode: AuthMode.OAuth,             // or AuthMode.ApiKey
+
+  subBlocks: [
+    // Define all UI fields here
+  ],
+
+  tools: {
+    access: ['tool_id_1', 'tool_id_2'], // Array of tool IDs this block can use
+    config: {
+      tool: (params) => `{service}_${params.operation}`,  // Tool selector function
+      params: (params) => ({
+        // Transform subBlock values to tool params
+      }),
+    },
+  },
+
+  inputs: {
+    // Optional: define expected inputs from other blocks
+  },
+
+  outputs: {
+    // Define outputs available to downstream blocks
+  },
+}
+```
+
+## SubBlock Types Reference
+
+**Critical:** Every subblock `id` must be unique within the block. Duplicate IDs cause conflicts even with different conditions.
+
+### Text Inputs
+```typescript
+// Single-line input
+{ id: 'field', title: 'Label', type: 'short-input', placeholder: '...' }
+
+// Multi-line input
+{ id: 'field', title: 'Label', type: 'long-input', placeholder: '...', rows: 6 }
+
+// Password input
+{ id: 'apiKey', title: 'API Key', type: 'short-input', password: true }
+```
+
+### Selection Inputs
+```typescript
+// Dropdown (static options)
+{
+  id: 'operation',
+  title: 'Operation',
+  type: 'dropdown',
+  options: [
+    { label: 'Create', id: 'create' },
+    { label: 'Update', id: 'update' },
+  ],
+  value: () => 'create',  // Default value function
+}
+
+// Combobox (searchable dropdown)
+{
+  id: 'field',
+  title: 'Label',
+  type: 'combobox',
+  options: [...],
+  searchable: true,
+}
+```
+
+### Code/JSON Inputs
+```typescript
+{
+  id: 'code',
+  title: 'Code',
+  type: 'code',
+  language: 'javascript',  // 'javascript' | 'json' | 'python'
+  placeholder: '// Enter code...',
+}
+```
+
+### OAuth/Credentials
+```typescript
+{
+  id: 'credential',
+  title: 'Account',
+  type: 'oauth-input',
+  serviceId: '{service}',  // Must match OAuth provider service key
+  requiredScopes: getScopesForService('{service}'),  // Import from @/lib/oauth/utils
+  placeholder: 'Select account',
+  required: true,
+}
+```
+
+**Scopes:** Always use `getScopesForService(serviceId)` from `@/lib/oauth/utils` for `requiredScopes`. Never hardcode scope arrays — the single source of truth is `OAUTH_PROVIDERS` in `lib/oauth/oauth.ts`.
+
+**Scope descriptions:** When adding a new OAuth provider, also add human-readable descriptions for all scopes in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts`.
+
+### Selectors (with dynamic options)
+```typescript
+// Channel selector (Slack, Discord, etc.)
+{
+  id: 'channel',
+  title: 'Channel',
+  type: 'channel-selector',
+  serviceId: '{service}',
+  placeholder: 'Select channel',
+  dependsOn: ['credential'],
+}
+
+// Project selector (Jira, etc.)
+{
+  id: 'project',
+  title: 'Project',
+  type: 'project-selector',
+  serviceId: '{service}',
+  dependsOn: ['credential'],
+}
+
+// File selector (Google Drive, etc.)
+{
+  id: 'file',
+  title: 'File',
+  type: 'file-selector',
+  serviceId: '{service}',
+  mimeType: 'application/pdf',
+  dependsOn: ['credential'],
+}
+
+// User selector
+{
+  id: 'user',
+  title: 'User',
+  type: 'user-selector',
+  serviceId: '{service}',
+  dependsOn: ['credential'],
+}
+```
+
+### Other Types
+```typescript
+// Switch/toggle
+{ id: 'enabled', type: 'switch' }
+
+// Slider
+{ id: 'temperature', title: 'Temperature', type: 'slider', min: 0, max: 2, step: 0.1 }
+
+// Table (key-value pairs)
+{ id: 'headers', title: 'Headers', type: 'table', columns: ['Key', 'Value'] }
+
+// File upload
+{
+  id: 'files',
+  title: 'Attachments',
+  type: 'file-upload',
+  multiple: true,
+  acceptedTypes: 'image/*,application/pdf',
+}
+```
+
+## File Input Handling
+
+When your block accepts file uploads, use the basic/advanced mode pattern with `normalizeFileInput`.
+
+### Basic/Advanced File Pattern
+
+```typescript
+// Basic mode: Visual file upload
+{
+  id: 'uploadFile',
+  title: 'File',
+  type: 'file-upload',
+  canonicalParamId: 'file',  // Both map to 'file' param
+  placeholder: 'Upload file',
+  mode: 'basic',
+  multiple: false,
+  required: true,
+  condition: { field: 'operation', value: 'upload' },
+},
+// Advanced mode: Reference from other blocks
+{
+  id: 'fileRef',
+  title: 'File',
+  type: 'short-input',
+  canonicalParamId: 'file',  // Both map to 'file' param
+  placeholder: 'Reference file (e.g., {{file_block.output}})',
+  mode: 'advanced',
+  required: true,
+  condition: { field: 'operation', value: 'upload' },
+},
+```
+
+**Critical constraints:**
+- `canonicalParamId` must NOT match any subblock's `id` in the same block
+- Values are stored under subblock `id`, not `canonicalParamId`
+
+### Normalizing File Input in tools.config
+
+Use `normalizeFileInput` to handle all input variants:
+
+```typescript
+import { normalizeFileInput } from '@/blocks/utils'
+
+tools: {
+  access: ['service_upload'],
+  config: {
+    tool: (params) => {
+      // Check all field IDs: uploadFile (basic), fileRef (advanced), fileContent (legacy)
+      const normalizedFile = normalizeFileInput(
+        params.uploadFile || params.fileRef || params.fileContent,
+        { single: true }
+      )
+      if (normalizedFile) {
+        params.file = normalizedFile
+      }
+      return `service_${params.operation}`
+    },
+  },
+}
+```
+
+**Why this pattern?**
+- Values come through as `params.uploadFile` or `params.fileRef` (the subblock IDs)
+- `canonicalParamId` only controls UI/schema mapping, not runtime values
+- `normalizeFileInput` handles JSON strings from advanced mode template resolution
+
+### File Input Types in `inputs`
+
+Use `type: 'json'` for file inputs:
+
+```typescript
+inputs: {
+  uploadFile: { type: 'json', description: 'Uploaded file (UserFile)' },
+  fileRef: { type: 'json', description: 'File reference from previous block' },
+  // Legacy field for backwards compatibility
+  fileContent: { type: 'string', description: 'Legacy: base64 encoded content' },
+}
+```
+
+### Multiple Files
+
+For multiple file uploads:
+
+```typescript
+{
+  id: 'attachments',
+  title: 'Attachments',
+  type: 'file-upload',
+  multiple: true,  // Allow multiple files
+  maxSize: 25,     // Max size in MB per file
+  acceptedTypes: 'image/*,application/pdf,.doc,.docx',
+}
+
+// In tools.config:
+const normalizedFiles = normalizeFileInput(
+  params.attachments || params.attachmentRefs,
+  // No { single: true } - returns array
+)
+if (normalizedFiles) {
+  params.files = normalizedFiles
+}
+```
+
+## Condition Syntax
+
+Controls when a field is shown based on other field values.
+
+### Simple Condition
+```typescript
+condition: { field: 'operation', value: 'create' }
+// Shows when operation === 'create'
+```
+
+### Multiple Values (OR)
+```typescript
+condition: { field: 'operation', value: ['create', 'update'] }
+// Shows when operation is 'create' OR 'update'
+```
+
+### Negation
+```typescript
+condition: { field: 'operation', value: 'delete', not: true }
+// Shows when operation !== 'delete'
+```
+
+### Compound (AND)
+```typescript
+condition: {
+  field: 'operation',
+  value: 'send',
+  and: {
+    field: 'type',
+    value: 'dm',
+    not: true,
+  }
+}
+// Shows when operation === 'send' AND type !== 'dm'
+```
+
+### Complex Example
+```typescript
+condition: {
+  field: 'operation',
+  value: ['list', 'search'],
+  not: true,
+  and: {
+    field: 'authMethod',
+    value: 'oauth',
+  }
+}
+// Shows when operation NOT in ['list', 'search'] AND authMethod === 'oauth'
+```
+
+## DependsOn Pattern
+
+Controls when a field is enabled and when its options are refetched.
+
+### Simple Array (all must be set)
+```typescript
+dependsOn: ['credential']
+// Enabled only when credential has a value
+// Options refetch when credential changes
+
+dependsOn: ['credential', 'projectId']
+// Enabled only when BOTH have values
+```
+
+### Complex (all + any)
+```typescript
+dependsOn: {
+  all: ['authMethod'],           // All must be set
+  any: ['credential', 'apiKey']  // At least one must be set
+}
+// Enabled when authMethod is set AND (credential OR apiKey is set)
+```
+
+## Required Pattern
+
+Can be boolean or condition-based.
+
+### Simple Boolean
+```typescript
+required: true
+required: false
+```
+
+### Conditional Required
+```typescript
+required: { field: 'operation', value: 'create' }
+// Required only when operation === 'create'
+
+required: { field: 'operation', value: ['create', 'update'] }
+// Required when operation is 'create' OR 'update'
+```
+
+## Mode Pattern (Basic vs Advanced)
+
+Controls which UI view shows the field.
+
+### Mode Options
+- `'basic'` - Only in basic view (default UI)
+- `'advanced'` - Only in advanced view
+- `'both'` - Both views (default if not specified)
+- `'trigger'` - Only in trigger configuration
+
+### canonicalParamId Pattern
+
+Maps multiple UI fields to a single serialized parameter:
+
+```typescript
+// Basic mode: Visual selector
+{
+  id: 'channel',
+  title: 'Channel',
+  type: 'channel-selector',
+  mode: 'basic',
+  canonicalParamId: 'channel',  // Both map to 'channel' param
+  dependsOn: ['credential'],
+}
+
+// Advanced mode: Manual input
+{
+  id: 'channelId',
+  title: 'Channel ID',
+  type: 'short-input',
+  mode: 'advanced',
+  canonicalParamId: 'channel',  // Both map to 'channel' param
+  placeholder: 'Enter channel ID manually',
+}
+```
+
+**How it works:**
+- In basic mode: `channel` selector value → `params.channel`
+- In advanced mode: `channelId` input value → `params.channel`
+- The serializer consolidates based on current mode
+
+**Critical constraints:**
+- `canonicalParamId` must NOT match any other subblock's `id` in the same block (causes conflicts)
+- `canonicalParamId` must be unique per block (only one basic/advanced pair per canonicalParamId)
+- ONLY use `canonicalParamId` to link basic/advanced mode alternatives for the same logical parameter
+- Do NOT use it for any other purpose
+
+## WandConfig Pattern
+
+Enables AI-assisted field generation.
+
+```typescript
+{
+  id: 'query',
+  title: 'Query',
+  type: 'code',
+  language: 'json',
+  wandConfig: {
+    enabled: true,
+    prompt: 'Generate a query based on the user request. Return ONLY the JSON.',
+    placeholder: 'Describe what you want to query...',
+    generationType: 'json-object',  // Optional: affects AI behavior
+    maintainHistory: true,          // Optional: keeps conversation context
+  },
+}
+```
+
+### Generation Types
+- `'javascript-function-body'` - JS code generation
+- `'json-object'` - Raw JSON (adds "no markdown" instruction)
+- `'json-schema'` - JSON Schema definitions
+- `'sql-query'` - SQL statements
+- `'timestamp'` - Adds current date/time context
+
+## Tools Configuration
+
+**Important:** `tools.config.tool` runs during serialization before variable resolution. Put `Number()` and other type coercions in `tools.config.params` instead, which runs at execution time after variables are resolved.
+
+**Preferred:** Use tool names directly as dropdown option IDs to avoid switch cases:
+```typescript
+// Dropdown options use tool IDs directly
+options: [
+  { label: 'Create', id: 'service_create' },
+  { label: 'Read', id: 'service_read' },
+]
+
+// Tool selector just returns the operation value
+tool: (params) => params.operation,
+```
+
+### With Parameter Transformation
+```typescript
+tools: {
+  access: ['service_action'],
+  config: {
+    tool: (params) => 'service_action',
+    params: (params) => ({
+      id: params.resourceId,
+      data: typeof params.data === 'string' ? JSON.parse(params.data) : params.data,
+    }),
+  },
+}
+```
+
+### V2 Versioned Tool Selector
+```typescript
+import { createVersionedToolSelector } from '@/blocks/utils'
+
+tools: {
+  access: [
+    'service_create_v2',
+    'service_read_v2',
+    'service_update_v2',
+  ],
+  config: {
+    tool: createVersionedToolSelector({
+      baseToolSelector: (params) => `service_${params.operation}`,
+      suffix: '_v2',
+      fallbackToolId: 'service_create_v2',
+    }),
+  },
+}
+```
+
+## Outputs Definition
+
+**IMPORTANT:** Block outputs have a simpler schema than tool outputs. Block outputs do NOT support:
+- `optional: true` - This is only for tool outputs
+- `items` property - This is only for tool outputs with array types
+
+Block outputs only support:
+- `type` - The data type ('string', 'number', 'boolean', 'json', 'array')
+- `description` - Human readable description
+- Nested object structure (for complex types)
+
+```typescript
+outputs: {
+  // Simple outputs
+  id: { type: 'string', description: 'Resource ID' },
+  success: { type: 'boolean', description: 'Whether operation succeeded' },
+
+  // Use type: 'json' for complex objects or arrays (NOT type: 'array' with items)
+  items: { type: 'json', description: 'List of items' },
+  metadata: { type: 'json', description: 'Response metadata' },
+
+  // Nested outputs (for structured data)
+  user: {
+    id: { type: 'string', description: 'User ID' },
+    name: { type: 'string', description: 'User name' },
+    email: { type: 'string', description: 'User email' },
+  },
+}
+```
+
+### Typed JSON Outputs
+
+When using `type: 'json'` and you know the object shape in advance, **describe the inner fields in the description** so downstream blocks know what properties are available. For well-known, stable objects, use nested output definitions instead:
+
+```typescript
+outputs: {
+  // BAD: Opaque json with no info about what's inside
+  plan: { type: 'json', description: 'Zone plan information' },
+
+  // GOOD: Describe the known fields in the description
+  plan: {
+    type: 'json',
+    description: 'Zone plan information (id, name, price, currency, frequency, is_subscribed)',
+  },
+
+  // BEST: Use nested output definition when the shape is stable and well-known
+  plan: {
+    id: { type: 'string', description: 'Plan identifier' },
+    name: { type: 'string', description: 'Plan name' },
+    price: { type: 'number', description: 'Plan price' },
+    currency: { type: 'string', description: 'Price currency' },
+  },
+}
+```
+
+Use the nested pattern when:
+- The object has a small, stable set of fields (< 10)
+- Downstream blocks will commonly access specific properties
+- The API response shape is well-documented and unlikely to change
+
+Use `type: 'json'` with a descriptive string when:
+- The object has many fields or a dynamic shape
+- It represents a list/array of items
+- The shape varies by operation
+
+## V2 Block Pattern
+
+When creating V2 blocks (alongside legacy V1):
+
+```typescript
+// V1 Block - mark as legacy
+export const ServiceBlock: BlockConfig = {
+  type: 'service',
+  name: 'Service (Legacy)',
+  hideFromToolbar: true,  // Hide from toolbar
+  // ... rest of config
+}
+
+// V2 Block - visible, uses V2 tools
+export const ServiceV2Block: BlockConfig = {
+  type: 'service_v2',
+  name: 'Service',              // Clean name
+  hideFromToolbar: false,       // Visible
+  subBlocks: ServiceBlock.subBlocks,  // Reuse UI
+  tools: {
+    access: ServiceBlock.tools?.access?.map(id => `${id}_v2`) || [],
+    config: {
+      tool: createVersionedToolSelector({
+        baseToolSelector: (params) => (ServiceBlock.tools?.config as any)?.tool(params),
+        suffix: '_v2',
+        fallbackToolId: 'service_default_v2',
+      }),
+      params: ServiceBlock.tools?.config?.params,
+    },
+  },
+  outputs: {
+    // Flat, API-aligned outputs (not wrapped in content/metadata)
+  },
+}
+```
+
+## Registering Blocks
+
+After creating the block, remind the user to:
+1. Import in `apps/sim/blocks/registry.ts`
+2. Add to the `registry` object (alphabetically):
+
+```typescript
+import { ServiceBlock } from '@/blocks/blocks/service'
+
+export const registry: Record<string, BlockConfig> = {
+  // ... existing blocks ...
+  service: ServiceBlock,
+}
+```
+
+## Complete Example
+
+```typescript
+import { ServiceIcon } from '@/components/icons'
+import type { BlockConfig } from '@/blocks/types'
+import { AuthMode, IntegrationType } from '@/blocks/types'
+import { getScopesForService } from '@/lib/oauth/utils'
+
+export const ServiceBlock: BlockConfig = {
+  type: 'service',
+  name: 'Service',
+  description: 'Integrate with Service API',
+  longDescription: 'Full description for documentation...',
+  docsLink: 'https://docs.sim.ai/tools/service',
+  category: 'tools',
+  integrationType: IntegrationType.DeveloperTools,
+  tags: ['oauth', 'api'],
+  bgColor: '#FF6B6B',
+  icon: ServiceIcon,
+  authMode: AuthMode.OAuth,
+
+  subBlocks: [
+    {
+      id: 'operation',
+      title: 'Operation',
+      type: 'dropdown',
+      options: [
+        { label: 'Create', id: 'create' },
+        { label: 'Read', id: 'read' },
+        { label: 'Update', id: 'update' },
+        { label: 'Delete', id: 'delete' },
+      ],
+      value: () => 'create',
+    },
+    {
+      id: 'credential',
+      title: 'Service Account',
+      type: 'oauth-input',
+      serviceId: 'service',
+      requiredScopes: getScopesForService('service'),
+      placeholder: 'Select account',
+      required: true,
+    },
+    {
+      id: 'resourceId',
+      title: 'Resource ID',
+      type: 'short-input',
+      placeholder: 'Enter resource ID',
+      condition: { field: 'operation', value: ['read', 'update', 'delete'] },
+      required: { field: 'operation', value: ['read', 'update', 'delete'] },
+    },
+    {
+      id: 'name',
+      title: 'Name',
+      type: 'short-input',
+      placeholder: 'Resource name',
+      condition: { field: 'operation', value: ['create', 'update'] },
+      required: { field: 'operation', value: 'create' },
+    },
+  ],
+
+  tools: {
+    access: ['service_create', 'service_read', 'service_update', 'service_delete'],
+    config: {
+      tool: (params) => `service_${params.operation}`,
+    },
+  },
+
+  outputs: {
+    id: { type: 'string', description: 'Resource ID' },
+    name: { type: 'string', description: 'Resource name' },
+    createdAt: { type: 'string', description: 'Creation timestamp' },
+  },
+}
+```
+
+## Connecting Blocks with Triggers
+
+If the service supports webhooks, connect the block to its triggers.
+
+```typescript
+import { getTrigger } from '@/triggers'
+
+export const ServiceBlock: BlockConfig = {
+  // ... basic config ...
+
+  triggers: {
+    enabled: true,
+    available: ['service_event_a', 'service_event_b', 'service_webhook'],
+  },
+
+  subBlocks: [
+    // Tool subBlocks first...
+    { id: 'operation', /* ... */ },
+
+    // Then spread trigger subBlocks
+    ...getTrigger('service_event_a').subBlocks,
+    ...getTrigger('service_event_b').subBlocks,
+    ...getTrigger('service_webhook').subBlocks,
+  ],
+}
+```
+
+See the `/add-trigger` skill for creating triggers.
+
+## Icon Requirement
+
+If the icon doesn't already exist in `@/components/icons.tsx`, **do NOT search for it yourself**. After completing the block, ask the user to provide the SVG:
+
+```
+The block is complete, but I need an icon for {Service}.
+Please provide the SVG and I'll convert it to a React component.
+
+You can usually find this in the service's brand/press kit page, or copy it from their website.
+```
+
+## Advanced Mode for Optional Fields
+
+Optional fields that are rarely used should be set to `mode: 'advanced'` so they don't clutter the basic UI. This includes:
+- Pagination tokens
+- Time range filters (start/end time)
+- Sort order options
+- Reply settings
+- Rarely used IDs (e.g., reply-to tweet ID, quote tweet ID)
+- Max results / limits
+
+```typescript
+{
+  id: 'startTime',
+  title: 'Start Time',
+  type: 'short-input',
+  placeholder: 'ISO 8601 timestamp',
+  condition: { field: 'operation', value: ['search', 'list'] },
+  mode: 'advanced',  // Rarely used, hide from basic view
+}
+```
+
+## WandConfig for Complex Inputs
+
+Use `wandConfig` for fields that are hard to fill out manually, such as timestamps, comma-separated lists, and complex query strings. This gives users an AI-assisted input experience.
+
+```typescript
+// Timestamps - use generationType: 'timestamp' to inject current date context
+{
+  id: 'startTime',
+  title: 'Start Time',
+  type: 'short-input',
+  mode: 'advanced',
+  wandConfig: {
+    enabled: true,
+    prompt: 'Generate an ISO 8601 timestamp based on the user description. Return ONLY the timestamp string.',
+    generationType: 'timestamp',
+  },
+}
+
+// Comma-separated lists - simple prompt without generationType
+{
+  id: 'mediaIds',
+  title: 'Media IDs',
+  type: 'short-input',
+  mode: 'advanced',
+  wandConfig: {
+    enabled: true,
+    prompt: 'Generate a comma-separated list of media IDs. Return ONLY the comma-separated values.',
+  },
+}
+```
+
+## Naming Convention
+
+All tool IDs referenced in `tools.access` and returned by `tools.config.tool` MUST use `snake_case` (e.g., `x_create_tweet`, `slack_send_message`). Never use camelCase or PascalCase.
+
+## Checklist Before Finishing
+
+- [ ] `integrationType` is set to the correct `IntegrationType` enum value
+- [ ] `tags` array includes all applicable `IntegrationTag` values
+- [ ] All subBlocks have `id`, `title` (except switch), and `type`
+- [ ] Conditions use correct syntax (field, value, not, and)
+- [ ] DependsOn set for fields that need other values
+- [ ] Required fields marked correctly (boolean or condition)
+- [ ] OAuth inputs have correct `serviceId` and `requiredScopes: getScopesForService(serviceId)`
+- [ ] Scope descriptions added to `SCOPE_DESCRIPTIONS` in `lib/oauth/utils.ts` for any new scopes
+- [ ] Tools.access lists all tool IDs (snake_case)
+- [ ] Tools.config.tool returns correct tool ID (snake_case)
+- [ ] Outputs match tool outputs
+- [ ] Block registered in registry.ts
+- [ ] If icon missing: asked user to provide SVG
+- [ ] If triggers exist: `triggers` config set, trigger subBlocks spread
+- [ ] Optional/rarely-used fields set to `mode: 'advanced'`
+- [ ] Timestamps and complex inputs have `wandConfig` enabled
+
+## Final Validation (Required)
+
+After creating the block, you MUST validate it against every tool it references:
+
+1. **Read every tool definition** that appears in `tools.access` — do not skip any
+2. **For each tool, verify the block has correct:**
+   - SubBlock inputs that cover all required tool params (with correct `condition` to show for that operation)
+   - SubBlock input types that match the tool param types (e.g., dropdown for enums, short-input for strings)
+   - `tools.config.params` correctly maps subBlock IDs to tool param names (if they differ)
+   - Type coercions in `tools.config.params` for any params that need conversion (Number(), Boolean(), JSON.parse())
+3. **Verify block outputs** cover the key fields returned by all tools
+4. **Verify conditions** — each subBlock should only show for the operations that actually use it
--- a/.cursor/commands/add-connector.md
+++ b/.cursor/commands/add-connector.md
@@ -0,0 +1,523 @@
+# Add Connector Skill
+
+You are an expert at adding knowledge base connectors to Sim. A connector syncs documents from an external source (Confluence, Google Drive, Notion, etc.) into a knowledge base.
+
+## Your Task
+
+When the user asks you to create a connector:
+1. Use Context7 or WebFetch to read the service's API documentation
+2. Determine the auth mode: **OAuth** (if Sim already has an OAuth provider for the service) or **API key** (if the service uses API key / Bearer token auth)
+3. Create the connector directory and config
+4. Register it in the connector registry
+
+## Directory Structure
+
+Create files in `apps/sim/connectors/{service}/`:
+```
+connectors/{service}/
+├── index.ts          # Barrel export
+└── {service}.ts      # ConnectorConfig definition
+```
+
+## Authentication
+
+Connectors use a discriminated union for auth config (`ConnectorAuthConfig` in `connectors/types.ts`):
+
+```typescript
+type ConnectorAuthConfig =
+  | { mode: 'oauth'; provider: OAuthService; requiredScopes?: string[] }
+  | { mode: 'apiKey'; label?: string; placeholder?: string }
+```
+
+### OAuth mode
+For services with existing OAuth providers in `apps/sim/lib/oauth/types.ts`. The `provider` must match an `OAuthService`. The modal shows a credential picker and handles token refresh automatically.
+
+### API key mode
+For services that use API key / Bearer token auth. The modal shows a password input with the configured `label` and `placeholder`. The API key is encrypted at rest using AES-256-GCM and stored in a dedicated `encryptedApiKey` column on the connector record. The sync engine decrypts it automatically — connectors receive the raw access token in `listDocuments`, `getDocument`, and `validateConfig`.
+
+## ConnectorConfig Structure
+
+### OAuth connector example
+
+```typescript
+import { createLogger } from '@sim/logger'
+import { {Service}Icon } from '@/components/icons'
+import { fetchWithRetry } from '@/lib/knowledge/documents/utils'
+import type { ConnectorConfig, ExternalDocument, ExternalDocumentList } from '@/connectors/types'
+
+const logger = createLogger('{Service}Connector')
+
+export const {service}Connector: ConnectorConfig = {
+  id: '{service}',
+  name: '{Service}',
+  description: 'Sync documents from {Service} into your knowledge base',
+  version: '1.0.0',
+  icon: {Service}Icon,
+
+  auth: {
+    mode: 'oauth',
+    provider: '{service}',          // Must match OAuthService in lib/oauth/types.ts
+    requiredScopes: ['read:...'],
+  },
+
+  configFields: [
+    // Rendered dynamically by the add-connector modal UI
+    // Supports 'short-input' and 'dropdown' types
+  ],
+
+  listDocuments: async (accessToken, sourceConfig, cursor) => {
+    // Return metadata stubs with contentDeferred: true (if per-doc content fetch needed)
+    // Or full documents with content (if list API returns content inline)
+    // Return { documents: ExternalDocument[], nextCursor?, hasMore }
+  },
+
+  getDocument: async (accessToken, sourceConfig, externalId) => {
+    // Fetch full content for a single document
+    // Return ExternalDocument with contentDeferred: false, or null
+  },
+
+  validateConfig: async (accessToken, sourceConfig) => {
+    // Return { valid: true } or { valid: false, error: 'message' }
+  },
+
+  // Optional: map source metadata to semantic tag keys (translated to slots by sync engine)
+  mapTags: (metadata) => {
+    // Return Record<string, unknown> with keys matching tagDefinitions[].id
+  },
+}
+```
+
+### API key connector example
+
+```typescript
+export const {service}Connector: ConnectorConfig = {
+  id: '{service}',
+  name: '{Service}',
+  description: 'Sync documents from {Service} into your knowledge base',
+  version: '1.0.0',
+  icon: {Service}Icon,
+
+  auth: {
+    mode: 'apiKey',
+    label: 'API Key',                       // Shown above the input field
+    placeholder: 'Enter your {Service} API key',  // Input placeholder
+  },
+
+  configFields: [ /* ... */ ],
+  listDocuments: async (accessToken, sourceConfig, cursor) => { /* ... */ },
+  getDocument: async (accessToken, sourceConfig, externalId) => { /* ... */ },
+  validateConfig: async (accessToken, sourceConfig) => { /* ... */ },
+}
+```
+
+## ConfigField Types
+
+The add-connector modal renders these automatically — no custom UI needed.
+
+Three field types are supported: `short-input`, `dropdown`, and `selector`.
+
+```typescript
+// Text input
+{
+  id: 'domain',
+  title: 'Domain',
+  type: 'short-input',
+  placeholder: 'yoursite.example.com',
+  required: true,
+}
+
+// Dropdown (static options)
+{
+  id: 'contentType',
+  title: 'Content Type',
+  type: 'dropdown',
+  required: false,
+  options: [
+    { label: 'Pages only', id: 'page' },
+    { label: 'Blog posts only', id: 'blogpost' },
+    { label: 'All content', id: 'all' },
+  ],
+}
+```
+
+## Dynamic Selectors (Canonical Pairs)
+
+Use `type: 'selector'` to fetch options dynamically from the existing selector registry (`hooks/selectors/registry.ts`). Selectors are always paired with a manual fallback input using the **canonical pair** pattern — a `selector` field (basic mode) and a `short-input` field (advanced mode) linked by `canonicalParamId`.
+
+The user sees a toggle button (ArrowLeftRight) to switch between the selector dropdown and manual text input. On submit, the modal resolves each canonical pair to the active mode's value, keyed by `canonicalParamId`.
+
+### Rules
+
+1. **Every selector field MUST have a canonical pair** — a corresponding `short-input` (or `dropdown`) field with the same `canonicalParamId` and `mode: 'advanced'`.
+2. **`required` must be set identically on both fields** in a pair. If the selector is required, the manual input must also be required.
+3. **`canonicalParamId` must match the key the connector expects in `sourceConfig`** (e.g. `baseId`, `channel`, `teamId`). The advanced field's `id` should typically match `canonicalParamId`.
+4. **`dependsOn` references the selector field's `id`**, not the `canonicalParamId`. The modal propagates dependency clearing across canonical siblings automatically — changing either field in a parent pair clears dependent children.
+
+### Selector canonical pair example (Airtable base → table cascade)
+
+```typescript
+configFields: [
+  // Base: selector (basic) + manual (advanced)
+  {
+    id: 'baseSelector',
+    title: 'Base',
+    type: 'selector',
+    selectorKey: 'airtable.bases',     // Must exist in hooks/selectors/registry.ts
+    canonicalParamId: 'baseId',
+    mode: 'basic',
+    placeholder: 'Select a base',
+    required: true,
+  },
+  {
+    id: 'baseId',
+    title: 'Base ID',
+    type: 'short-input',
+    canonicalParamId: 'baseId',
+    mode: 'advanced',
+    placeholder: 'e.g. appXXXXXXXXXXXXXX',
+    required: true,
+  },
+  // Table: selector depends on base (basic) + manual (advanced)
+  {
+    id: 'tableSelector',
+    title: 'Table',
+    type: 'selector',
+    selectorKey: 'airtable.tables',
+    canonicalParamId: 'tableIdOrName',
+    mode: 'basic',
+    dependsOn: ['baseSelector'],       // References the selector field ID
+    placeholder: 'Select a table',
+    required: true,
+  },
+  {
+    id: 'tableIdOrName',
+    title: 'Table Name or ID',
+    type: 'short-input',
+    canonicalParamId: 'tableIdOrName',
+    mode: 'advanced',
+    placeholder: 'e.g. Tasks',
+    required: true,
+  },
+  // Non-selector fields stay as-is
+  { id: 'maxRecords', title: 'Max Records', type: 'short-input', ... },
+]
+```
+
+### Selector with domain dependency (Jira/Confluence pattern)
+
+When a selector depends on a plain `short-input` field (no canonical pair), `dependsOn` references that field's `id` directly. The `domain` field's value maps to `SelectorContext.domain` automatically via `SELECTOR_CONTEXT_FIELDS`.
+
+```typescript
+configFields: [
+  {
+    id: 'domain',
+    title: 'Jira Domain',
+    type: 'short-input',
+    placeholder: 'yoursite.atlassian.net',
+    required: true,
+  },
+  {
+    id: 'projectSelector',
+    title: 'Project',
+    type: 'selector',
+    selectorKey: 'jira.projects',
+    canonicalParamId: 'projectKey',
+    mode: 'basic',
+    dependsOn: ['domain'],
+    placeholder: 'Select a project',
+    required: true,
+  },
+  {
+    id: 'projectKey',
+    title: 'Project Key',
+    type: 'short-input',
+    canonicalParamId: 'projectKey',
+    mode: 'advanced',
+    placeholder: 'e.g. ENG, PROJ',
+    required: true,
+  },
+]
+```
+
+### How `dependsOn` maps to `SelectorContext`
+
+The connector selector field builds a `SelectorContext` from dependency values. For the mapping to work, each dependency's `canonicalParamId` (or field `id` for non-canonical fields) must exist in `SELECTOR_CONTEXT_FIELDS` (`lib/workflows/subblocks/context.ts`):
+
+```
+oauthCredential, domain, teamId, projectId, knowledgeBaseId, planId,
+siteId, collectionId, spreadsheetId, fileId, baseId, datasetId, serviceDeskId
+```
+
+### Available selector keys
+
+Check `hooks/selectors/types.ts` for the full `SelectorKey` union. Common ones for connectors:
+
+| SelectorKey | Context Deps | Returns |
+|-------------|-------------|---------|
+| `airtable.bases` | credential | Base ID + name |
+| `airtable.tables` | credential, `baseId` | Table ID + name |
+| `slack.channels` | credential | Channel ID + name |
+| `gmail.labels` | credential | Label ID + name |
+| `google.calendar` | credential | Calendar ID + name |
+| `linear.teams` | credential | Team ID + name |
+| `linear.projects` | credential, `teamId` | Project ID + name |
+| `jira.projects` | credential, `domain` | Project key + name |
+| `confluence.spaces` | credential, `domain` | Space key + name |
+| `notion.databases` | credential | Database ID + name |
+| `asana.workspaces` | credential | Workspace GID + name |
+| `microsoft.teams` | credential | Team ID + name |
+| `microsoft.channels` | credential, `teamId` | Channel ID + name |
+| `webflow.sites` | credential | Site ID + name |
+| `outlook.folders` | credential | Folder ID + name |
+
+## ExternalDocument Shape
+
+Every document returned from `listDocuments`/`getDocument` must include:
+
+```typescript
+{
+  externalId: string          // Source-specific unique ID
+  title: string               // Document title
+  content: string             // Extracted plain text (or '' if contentDeferred)
+  contentDeferred?: boolean   // true = content will be fetched via getDocument
+  mimeType: 'text/plain'     // Always text/plain (content is extracted)
+  contentHash: string         // Metadata-based hash for change detection
+  sourceUrl?: string          // Link back to original (stored on document record)
+  metadata?: Record<string, unknown>  // Source-specific data (fed to mapTags)
+}
+```
+
+## Content Deferral (Required for file/content-download connectors)
+
+**All connectors that require per-document API calls to fetch content MUST use `contentDeferred: true`.** This is the standard pattern — `listDocuments` returns lightweight metadata stubs, and content is fetched lazily by the sync engine via `getDocument` only for new/changed documents.
+
+This pattern is critical for reliability: the sync engine processes documents in batches and enqueues each batch for processing immediately. If a sync times out, all previously-batched documents are already queued. Without deferral, content downloads during listing can exhaust the sync task's time budget before any documents are saved.
+
+### When to use `contentDeferred: true`
+
+- The service's list API does NOT return document content (only metadata)
+- Content requires a separate download/export API call per document
+- Examples: Google Drive, OneDrive, SharePoint, Dropbox, Notion, Confluence, Gmail, Obsidian, Evernote, GitHub
+
+### When NOT to use `contentDeferred`
+
+- The list API already returns the full content inline (e.g., Slack messages, Reddit posts, HubSpot notes)
+- No per-document API call is needed to get content
+
+### Content Hash Strategy
+
+Use a **metadata-based** `contentHash` — never a content-based hash. The hash must be derivable from the list response metadata alone, so the sync engine can detect changes without downloading content.
+
+Good metadata hash sources:
+- `modifiedTime` / `lastModifiedDateTime` — changes when file is edited
+- Git blob SHA — unique per content version
+- API-provided content hash (e.g., Dropbox `content_hash`)
+- Version number (e.g., Confluence page version)
+
+Format: `{service}:{id}:{changeIndicator}`
+
+```typescript
+// Google Drive: modifiedTime changes on edit
+contentHash: `gdrive:${file.id}:${file.modifiedTime ?? ''}`
+
+// GitHub: blob SHA is a content-addressable hash
+contentHash: `gitsha:${item.sha}`
+
+// Dropbox: API provides content_hash
+contentHash: `dropbox:${entry.id}:${entry.content_hash ?? entry.server_modified}`
+
+// Confluence: version number increments on edit
+contentHash: `confluence:${page.id}:${page.version.number}`
+```
+
+**Critical invariant:** The `contentHash` MUST be identical whether produced by `listDocuments` (stub) or `getDocument` (full doc). Both should use the same stub function to guarantee this.
+
+### Implementation Pattern
+
+```typescript
+// 1. Create a stub function (sync, no API calls)
+function fileToStub(file: ServiceFile): ExternalDocument {
+  return {
+    externalId: file.id,
+    title: file.name || 'Untitled',
+    content: '',
+    contentDeferred: true,
+    mimeType: 'text/plain',
+    sourceUrl: `https://service.com/file/${file.id}`,
+    contentHash: `service:${file.id}:${file.modifiedTime ?? ''}`,
+    metadata: { /* fields needed by mapTags */ },
+  }
+}
+
+// 2. listDocuments returns stubs (fast, metadata only)
+listDocuments: async (accessToken, sourceConfig, cursor) => {
+  const response = await fetchWithRetry(listUrl, { ... })
+  const files = (await response.json()).files
+  const documents = files.map(fileToStub)
+  return { documents, nextCursor, hasMore }
+}
+
+// 3. getDocument fetches content and returns full doc with SAME contentHash
+getDocument: async (accessToken, sourceConfig, externalId) => {
+  const metadata = await fetchWithRetry(metadataUrl, { ... })
+  const file = await metadata.json()
+  if (file.trashed) return null
+
+  try {
+    const content = await fetchContent(accessToken, file)
+    if (!content.trim()) return null
+    const stub = fileToStub(file)
+    return { ...stub, content, contentDeferred: false }
+  } catch (error) {
+    logger.warn(`Failed to fetch content for: ${file.name}`, { error })
+    return null
+  }
+}
+```
+
+### Reference Implementations
+
+- **Google Drive**: `connectors/google-drive/google-drive.ts` — file download/export with `modifiedTime` hash
+- **GitHub**: `connectors/github/github.ts` — git blob SHA hash
+- **Notion**: `connectors/notion/notion.ts` — blocks API with `last_edited_time` hash
+- **Confluence**: `connectors/confluence/confluence.ts` — version number hash
+
+## tagDefinitions — Declared Tag Definitions
+
+Declare which tags the connector populates using semantic IDs. Shown in the add-connector modal as opt-out checkboxes.
+On connector creation, slots are **dynamically assigned** via `getNextAvailableSlot` — connectors never hardcode slot names.
+
+```typescript
+tagDefinitions: [
+  { id: 'labels', displayName: 'Labels', fieldType: 'text' },
+  { id: 'version', displayName: 'Version', fieldType: 'number' },
+  { id: 'lastModified', displayName: 'Last Modified', fieldType: 'date' },
+],
+```
+
+Each entry has:
+- `id`: Semantic key matching a key returned by `mapTags` (e.g. `'labels'`, `'version'`)
+- `displayName`: Human-readable name shown in the UI (e.g. "Labels", "Last Modified")
+- `fieldType`: `'text'` | `'number'` | `'date'` | `'boolean'` — determines which slot pool to draw from
+
+Users can opt out of specific tags in the modal. Disabled IDs are stored in `sourceConfig.disabledTagIds`.
+The assigned mapping (`semantic id → slot`) is stored in `sourceConfig.tagSlotMapping`.
+
+## mapTags — Metadata to Semantic Keys
+
+Maps source metadata to semantic tag keys. Required if `tagDefinitions` is set.
+The sync engine calls this automatically and translates semantic keys to actual DB slots
+using the `tagSlotMapping` stored on the connector.
+
+Return keys must match the `id` values declared in `tagDefinitions`.
+
+```typescript
+mapTags: (metadata: Record<string, unknown>): Record<string, unknown> => {
+  const result: Record<string, unknown> = {}
+
+  // Validate arrays before casting — metadata may be malformed
+  const labels = Array.isArray(metadata.labels) ? (metadata.labels as string[]) : []
+  if (labels.length > 0) result.labels = labels.join(', ')
+
+  // Validate numbers — guard against NaN
+  if (metadata.version != null) {
+    const num = Number(metadata.version)
+    if (!Number.isNaN(num)) result.version = num
+  }
+
+  // Validate dates — guard against Invalid Date
+  if (typeof metadata.lastModified === 'string') {
+    const date = new Date(metadata.lastModified)
+    if (!Number.isNaN(date.getTime())) result.lastModified = date
+  }
+
+  return result
+}
+```
+
+## External API Calls — Use `fetchWithRetry`
+
+All external API calls must use `fetchWithRetry` from `@/lib/knowledge/documents/utils` instead of raw `fetch()`. This provides exponential backoff with retries on 429/502/503/504 errors. It returns a standard `Response` — all `.ok`, `.json()`, `.text()` checks work unchanged.
+
+For `validateConfig` (user-facing, called on save), pass `VALIDATE_RETRY_OPTIONS` to cap wait time at ~7s. Background operations (`listDocuments`, `getDocument`) use the built-in defaults (5 retries, ~31s max).
+
+```typescript
+import { VALIDATE_RETRY_OPTIONS, fetchWithRetry } from '@/lib/knowledge/documents/utils'
+
+// Background sync — use defaults
+const response = await fetchWithRetry(url, {
+  method: 'GET',
+  headers: { Authorization: `Bearer ${accessToken}` },
+})
+
+// validateConfig — tighter retry budget
+const response = await fetchWithRetry(url, { ... }, VALIDATE_RETRY_OPTIONS)
+```
+
+## sourceUrl
+
+If `ExternalDocument.sourceUrl` is set, the sync engine stores it on the document record. Always construct the full URL (not a relative path).
+
+## Sync Engine Behavior (Do Not Modify)
+
+The sync engine (`lib/knowledge/connectors/sync-engine.ts`) is connector-agnostic. It:
+1. Calls `listDocuments` with pagination until `hasMore` is false
+2. Compares `contentHash` to detect new/changed/unchanged documents
+3. Stores `sourceUrl` and calls `mapTags` on insert/update automatically
+4. Handles soft-delete of removed documents
+5. Resolves access tokens automatically — OAuth tokens are refreshed, API keys are decrypted from the `encryptedApiKey` column
+
+You never need to modify the sync engine when adding a connector.
+
+## Icon
+
+The `icon` field on `ConnectorConfig` is used throughout the UI — in the connector list, the add-connector modal, and as the document icon in the knowledge base table (replacing the generic file type icon for connector-sourced documents). The icon is read from `CONNECTOR_REGISTRY[connectorType].icon` at runtime — no separate icon map to maintain.
+
+If the service already has an icon in `apps/sim/components/icons.tsx` (from a tool integration), reuse it. Otherwise, ask the user to provide the SVG.
+
+## Registering
+
+Add one line to `apps/sim/connectors/registry.ts`:
+
+```typescript
+import { {service}Connector } from '@/connectors/{service}'
+
+export const CONNECTOR_REGISTRY: ConnectorRegistry = {
+  // ... existing connectors ...
+  {service}: {service}Connector,
+}
+```
+
+## Reference Implementations
+
+- **OAuth + contentDeferred**: `apps/sim/connectors/google-drive/google-drive.ts` — file download with metadata-based hash, `orderBy` for deterministic pagination
+- **OAuth + contentDeferred (blocks API)**: `apps/sim/connectors/notion/notion.ts` — complex block content extraction deferred to `getDocument`
+- **OAuth + contentDeferred (git)**: `apps/sim/connectors/github/github.ts` — blob SHA hash, tree listing
+- **OAuth + inline content**: `apps/sim/connectors/confluence/confluence.ts` — multiple config field types, `mapTags`, label fetching
+- **API key**: `apps/sim/connectors/fireflies/fireflies.ts` — GraphQL API with Bearer token auth
+
+## Checklist
+
+- [ ] Created `connectors/{service}/{service}.ts` with full ConnectorConfig
+- [ ] Created `connectors/{service}/index.ts` barrel export
+- [ ] **Auth configured correctly:**
+  - OAuth: `auth.provider` matches an existing `OAuthService` in `lib/oauth/types.ts`
+  - API key: `auth.label` and `auth.placeholder` set appropriately
+- [ ] **Selector fields configured correctly (if applicable):**
+  - Every `type: 'selector'` field has a canonical pair (`short-input` or `dropdown` with same `canonicalParamId` and `mode: 'advanced'`)
+  - `required` is identical on both fields in each canonical pair
+  - `selectorKey` exists in `hooks/selectors/registry.ts`
+  - `dependsOn` references selector field IDs (not `canonicalParamId`)
+  - Dependency `canonicalParamId` values exist in `SELECTOR_CONTEXT_FIELDS`
+- [ ] `listDocuments` handles pagination with metadata-based content hashes
+- [ ] `contentDeferred: true` used if content requires per-doc API calls (file download, export, blocks fetch)
+- [ ] `contentHash` is metadata-based (not content-based) and identical between stub and `getDocument`
+- [ ] `sourceUrl` set on each ExternalDocument (full URL, not relative)
+- [ ] `metadata` includes source-specific data for tag mapping
+- [ ] `tagDefinitions` declared for each semantic key returned by `mapTags`
+- [ ] `mapTags` implemented if source has useful metadata (labels, dates, versions)
+- [ ] `validateConfig` verifies the source is accessible
+- [ ] All external API calls use `fetchWithRetry` (not raw `fetch`)
+- [ ] All optional config fields validated in `validateConfig`
+- [ ] Icon exists in `components/icons.tsx` (or asked user to provide SVG)
+- [ ] Registered in `connectors/registry.ts`
--- a/.cursor/commands/add-hosted-key.md
+++ b/.cursor/commands/add-hosted-key.md
@@ -0,0 +1,291 @@
+# Adding Hosted Key Support to a Tool
+
+When a tool has hosted key support, Sim provides its own API key if the user hasn't configured one (via BYOK or env var). Usage is metered and billed to the workspace.
+
+## Overview
+
+| Step | What | Where |
+|------|------|-------|
+| 1 | Register BYOK provider ID | `tools/types.ts`, `app/api/workspaces/[id]/byok-keys/route.ts` |
+| 2 | Research the API's pricing and rate limits | API docs / pricing page (before writing any code) |
+| 3 | Add `hosting` config to the tool | `tools/{service}/{action}.ts` |
+| 4 | Hide API key field when hosted | `blocks/blocks/{service}.ts` |
+| 5 | Add to BYOK settings UI | BYOK settings component (`byok.tsx`) |
+| 6 | Summarize pricing and throttling comparison | Output to user (after all code changes) |
+
+## Step 1: Register the BYOK Provider ID
+
+Add the new provider to the `BYOKProviderId` union in `tools/types.ts`:
+
+```typescript
+export type BYOKProviderId =
+  | 'openai'
+  | 'anthropic'
+  // ...existing providers
+  | 'your_service'
+```
+
+Then add it to `VALID_PROVIDERS` in `app/api/workspaces/[id]/byok-keys/route.ts`:
+
+```typescript
+const VALID_PROVIDERS = ['openai', 'anthropic', 'google', 'mistral', 'your_service'] as const
+```
+
+## Step 2: Research the API's Pricing Model and Rate Limits
+
+**Before writing any `getCost` or `rateLimit` code**, look up the service's official documentation for both pricing and rate limits. You need to understand:
+
+### Pricing
+
+1. **How the API charges** — per request, per credit, per token, per step, per minute, etc.
+2. **Whether the API reports cost in its response** — look for fields like `creditsUsed`, `costDollars`, `tokensUsed`, or similar in the response body or headers
+3. **Whether cost varies by endpoint/options** — some APIs charge more for certain features (e.g., Firecrawl charges 1 credit/page base but +4 for JSON format, +4 for enhanced mode)
+4. **The dollar-per-unit rate** — what each credit/token/unit costs in dollars on our plan
+
+### Rate Limits
+
+1. **What rate limits the API enforces** — requests per minute/second, tokens per minute, concurrent requests, etc.
+2. **Whether limits vary by plan tier** — free vs paid vs enterprise often have different ceilings
+3. **Whether limits are per-key or per-account** — determines whether adding more hosted keys actually increases total throughput
+4. **What the API returns when rate limited** — HTTP 429, `Retry-After` header, error body format, etc.
+5. **Whether there are multiple dimensions** — some APIs limit both requests/min AND tokens/min independently
+
+Search the API's docs/pricing page (use WebSearch/WebFetch). Capture the pricing model as a comment in `getCost` so future maintainers know the source of truth.
+
+### Setting Our Rate Limits
+
+Our rate limiter (`lib/core/rate-limiter/hosted-key/`) uses a token-bucket algorithm applied **per billing actor** (workspace). It supports two modes:
+
+- **`per_request`** — simple; just `requestsPerMinute`. Good when the API charges flat per-request or cost doesn't vary much.
+- **`custom`** — `requestsPerMinute` plus additional `dimensions` (e.g., `tokens`, `search_units`). Each dimension has its own `limitPerMinute` and an `extractUsage` function that reads actual usage from the response. Use when the API charges on a variable metric (tokens, credits) and you want to cap that metric too.
+
+When choosing values for `requestsPerMinute` and any dimension limits:
+
+- **Stay well below the API's per-key limit** — our keys are shared across all workspaces. If the API allows 60 RPM per key and we have 3 keys, the global ceiling is ~180 RPM. Set the per-workspace limit low enough (e.g., 20-60 RPM) that many workspaces can coexist without collectively hitting the API's ceiling.
+- **Account for key pooling** — our round-robin distributes requests across `N` hosted keys, so the effective API-side rate per key is `(total requests) / N`. But per-workspace limits are enforced *before* key selection, so they apply regardless of key count.
+- **Prefer conservative defaults** — it's easy to raise limits later but hard to claw back after users depend on high throughput.
+
+## Step 3: Add `hosting` Config to the Tool
+
+Add a `hosting` object to the tool's `ToolConfig`. This tells the execution layer how to acquire hosted keys, calculate cost, and rate-limit.
+
+```typescript
+hosting: {
+  envKeyPrefix: 'YOUR_SERVICE_API_KEY',
+  apiKeyParam: 'apiKey',
+  byokProviderId: 'your_service',
+  pricing: {
+    type: 'custom',
+    getCost: (_params, output) => {
+      if (output.creditsUsed == null) {
+        throw new Error('Response missing creditsUsed field')
+      }
+      const creditsUsed = output.creditsUsed as number
+      const cost = creditsUsed * 0.001 // dollars per credit
+      return { cost, metadata: { creditsUsed } }
+    },
+  },
+  rateLimit: {
+    mode: 'per_request',
+    requestsPerMinute: 100,
+  },
+},
+```
+
+### Hosted Key Env Var Convention
+
+Keys use a numbered naming pattern driven by a count env var:
+
+```
+YOUR_SERVICE_API_KEY_COUNT=3
+YOUR_SERVICE_API_KEY_1=sk-...
+YOUR_SERVICE_API_KEY_2=sk-...
+YOUR_SERVICE_API_KEY_3=sk-...
+```
+
+The `envKeyPrefix` value (`YOUR_SERVICE_API_KEY`) determines which env vars are read at runtime. Adding more keys only requires bumping the count and adding the new env var.
+
+### Pricing: Prefer API-Reported Cost
+
+Always prefer using cost data returned by the API (e.g., `creditsUsed`, `costDollars`). This is the most accurate because it accounts for variable pricing tiers, feature modifiers, and plan-level discounts.
+
+**When the API reports cost** — use it directly and throw if missing:
+
+```typescript
+pricing: {
+  type: 'custom',
+  getCost: (params, output) => {
+    if (output.creditsUsed == null) {
+      throw new Error('Response missing creditsUsed field')
+    }
+    // $0.001 per credit — from https://example.com/pricing
+    const cost = (output.creditsUsed as number) * 0.001
+    return { cost, metadata: { creditsUsed: output.creditsUsed } }
+  },
+},
+```
+
+**When the API does NOT report cost** — compute it from params/output based on the pricing docs, but still validate the data you depend on:
+
+```typescript
+pricing: {
+  type: 'custom',
+  getCost: (params, output) => {
+    if (!Array.isArray(output.searchResults)) {
+      throw new Error('Response missing searchResults, cannot determine cost')
+    }
+    // Serper: 1 credit for <=10 results, 2 credits for >10 — from https://serper.dev/pricing
+    const credits = Number(params.num) > 10 ? 2 : 1
+    return { cost: credits * 0.001, metadata: { credits } }
+  },
+},
+```
+
+**`getCost` must always throw** if it cannot determine cost. Never silently fall back to a default — this would hide billing inaccuracies.
+
+### Capturing Cost Data from the API
+
+If the API returns cost info, capture it in `transformResponse` so `getCost` can read it from the output:
+
+```typescript
+transformResponse: async (response: Response) => {
+  const data = await response.json()
+  return {
+    success: true,
+    output: {
+      results: data.results,
+      creditsUsed: data.creditsUsed,  // pass through for getCost
+    },
+  }
+},
+```
+
+For async/polling tools, capture it in `postProcess` when the job completes:
+
+```typescript
+if (jobData.status === 'completed') {
+  result.output = {
+    data: jobData.data,
+    creditsUsed: jobData.creditsUsed,
+  }
+}
+```
+
+## Step 4: Hide the API Key Field When Hosted
+
+In the block config (`blocks/blocks/{service}.ts`), add `hideWhenHosted: true` to the API key subblock. This hides the field on hosted Sim since the platform provides the key:
+
+```typescript
+{
+  id: 'apiKey',
+  title: 'API Key',
+  type: 'short-input',
+  placeholder: 'Enter your API key',
+  password: true,
+  required: true,
+  hideWhenHosted: true,
+},
+```
+
+The visibility is controlled by `isSubBlockHidden()` in `lib/workflows/subblocks/visibility.ts`, which checks both the `isHosted` feature flag (`hideWhenHosted`) and optional env var conditions (`hideWhenEnvSet`).
+
+### Excluding Specific Operations from Hosted Key Support
+
+When a block has multiple operations but some operations should **not** use a hosted key (e.g., the underlying API is deprecated, unsupported, or too expensive), use the **duplicate apiKey subblock** pattern. This is the same pattern Exa uses for its `research` operation:
+
+1. **Remove the `hosting` config** from the tool definition for that operation — it must not have a `hosting` object at all.
+2. **Duplicate the `apiKey` subblock** in the block config with opposing conditions:
+
+```typescript
+// API Key — hidden when hosted for operations with hosted key support
+{
+  id: 'apiKey',
+  title: 'API Key',
+  type: 'short-input',
+  placeholder: 'Enter your API key',
+  password: true,
+  required: true,
+  hideWhenHosted: true,
+  condition: { field: 'operation', value: 'unsupported_op', not: true },
+},
+// API Key — always visible for unsupported_op (no hosted key support)
+{
+  id: 'apiKey',
+  title: 'API Key',
+  type: 'short-input',
+  placeholder: 'Enter your API key',
+  password: true,
+  required: true,
+  condition: { field: 'operation', value: 'unsupported_op' },
+},
+```
+
+Both subblocks share the same `id: 'apiKey'`, so the same value flows to the tool. The conditions ensure only one is visible at a time. The first has `hideWhenHosted: true` and shows for all hosted operations; the second has no `hideWhenHosted` and shows only for the excluded operation — meaning users must always provide their own key for that operation.
+
+To exclude multiple operations, use an array: `{ field: 'operation', value: ['op_a', 'op_b'] }`.
+
+**Reference implementations:**
+- **Exa** (`blocks/blocks/exa.ts`): `research` operation excluded from hosting — lines 309-329
+- **Google Maps** (`blocks/blocks/google_maps.ts`): `speed_limits` operation excluded from hosting (deprecated Roads API)
+
+## Step 5: Add to the BYOK Settings UI
+
+Add an entry to the `PROVIDERS` array in the BYOK settings component so users can bring their own key. You need the service icon from `components/icons.tsx`:
+
+```typescript
+{
+  id: 'your_service',
+  name: 'Your Service',
+  icon: YourServiceIcon,
+  description: 'What this service does',
+  placeholder: 'Enter your API key',
+},
+```
+
+## Step 6: Summarize Pricing and Throttling Comparison
+
+After all code changes are complete, output a detailed summary to the user covering:
+
+### What to include
+
+1. **API's pricing model** — how the service charges (per token, per credit, per request, etc.), the specific rates found in docs, and whether the API reports cost in responses.
+2. **Our `getCost` approach** — how we calculate cost, what fields we depend on, and any assumptions or estimates (especially when the API doesn't report exact dollar cost).
+3. **API's rate limits** — the documented limits (RPM, TPM, concurrent, etc.), which plan tier they apply to, and whether they're per-key or per-account.
+4. **Our `rateLimit` config** — what we set for `requestsPerMinute` (and dimensions if custom mode), why we chose those values, and how they compare to the API's limits.
+5. **Key pooling impact** — how many hosted keys we expect, and how round-robin distribution affects the effective per-key rate at the API.
+6. **Gaps or risks** — anything the API charges for that we don't meter, rate limit dimensions we chose not to enforce, or pricing that may be inaccurate due to variable model/tier costs.
+
+### Format
+
+Present this as a structured summary with clear headings. Example:
+
+```
+### Pricing
+- **API charges**: $X per 1M tokens (input), $Y per 1M tokens (output) — varies by model
+- **Response reports cost?**: No — only token counts in `usage` field
+- **Our getCost**: Estimates cost at $Z per 1M total tokens based on median model pricing
+- **Risk**: Actual cost varies by model; our estimate may over/undercharge for cheap/expensive models
+
+### Throttling
+- **API limits**: 300 RPM per key (paid tier), 60 RPM (free tier)
+- **Per-key or per-account**: Per key — more keys = more throughput
+- **Our config**: 60 RPM per workspace (per_request mode)
+- **With N keys**: Effective per-key rate is (total RPM across workspaces) / N
+- **Headroom**: Comfortable — even 10 active workspaces at full rate = 600 RPM / 3 keys = 200 RPM per key, under the 300 RPM API limit
+```
+
+This summary helps reviewers verify that the pricing and rate limiting are well-calibrated and surfaces any risks that need monitoring.
+
+## Checklist
+
+- [ ] Provider added to `BYOKProviderId` in `tools/types.ts`
+- [ ] Provider added to `VALID_PROVIDERS` in the BYOK keys API route
+- [ ] API pricing docs researched — understand per-unit cost and whether the API reports cost in responses
+- [ ] API rate limits researched — understand RPM/TPM limits, per-key vs per-account, and plan tiers
+- [ ] `hosting` config added to the tool with `envKeyPrefix`, `apiKeyParam`, `byokProviderId`, `pricing`, and `rateLimit`
+- [ ] `getCost` throws if required cost data is missing from the response
+- [ ] Cost data captured in `transformResponse` or `postProcess` if API provides it
+- [ ] `hideWhenHosted: true` added to the API key subblock in the block config
+- [ ] Provider entry added to the BYOK settings UI with icon and description
+- [ ] Env vars documented: `{PREFIX}_COUNT` and `{PREFIX}_1..N`
+- [ ] Pricing and throttling summary provided to reviewer
--- a/.cursor/commands/add-integration.md
+++ b/.cursor/commands/add-integration.md
@@ -0,0 +1,759 @@
+# Add Integration Skill
+
+You are an expert at adding complete integrations to Sim. This skill orchestrates the full process of adding a new service integration.
+
+## Overview
+
+Adding an integration involves these steps in order:
+1. **Research** - Read the service's API documentation
+2. **Create Tools** - Build tool configurations for each API operation
+3. **Create Block** - Build the block UI configuration
+4. **Add Icon** - Add the service's brand icon
+5. **Create Triggers** (optional) - If the service supports webhooks
+6. **Register** - Register tools, block, and triggers in their registries
+7. **Generate Docs** - Run the docs generation script
+
+## Step 1: Research the API
+
+Before writing any code:
+1. Use Context7 to find official documentation: `mcp__plugin_context7_context7__resolve-library-id`
+2. Or use WebFetch to read API docs directly
+3. Identify:
+   - Authentication method (OAuth, API Key, both)
+   - Available operations (CRUD, search, etc.)
+   - Required vs optional parameters
+   - Response structures
+
+## Step 2: Create Tools
+
+### Directory Structure
+```
+apps/sim/tools/{service}/
+├── index.ts          # Barrel exports
+├── types.ts          # TypeScript interfaces
+├── {action1}.ts      # Tool for action 1
+├── {action2}.ts      # Tool for action 2
+└── ...
+```
+
+### Key Patterns
+
+**types.ts:**
+```typescript
+import type { ToolResponse } from '@/tools/types'
+
+export interface {Service}{Action}Params {
+  accessToken: string      // For OAuth services
+  // OR
+  apiKey: string          // For API key services
+
+  requiredParam: string
+  optionalParam?: string
+}
+
+export interface {Service}Response extends ToolResponse {
+  output: {
+    // Define output structure
+  }
+}
+```
+
+**Tool file pattern:**
+```typescript
+export const {service}{Action}Tool: ToolConfig<Params, Response> = {
+  id: '{service}_{action}',
+  name: '{Service} {Action}',
+  description: '...',
+  version: '1.0.0',
+
+  oauth: { required: true, provider: '{service}' },  // If OAuth
+
+  params: {
+    accessToken: { type: 'string', required: true, visibility: 'hidden', description: '...' },
+    // ... other params
+  },
+
+  request: { url, method, headers, body },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    return {
+      success: true,
+      output: {
+        field: data.field ?? null,  // Always handle nullables
+      },
+    }
+  },
+
+  outputs: { /* ... */ },
+}
+```
+
+### Critical Rules
+- `visibility: 'hidden'` for OAuth tokens
+- `visibility: 'user-only'` for API keys and user credentials
+- `visibility: 'user-or-llm'` for operation parameters
+- Always use `?? null` for nullable API response fields
+- Always use `?? []` for optional array fields
+- Set `optional: true` for outputs that may not exist
+- Never output raw JSON dumps - extract meaningful fields
+- When using `type: 'json'` and you know the object shape, define `properties` with the inner fields so downstream consumers know the structure. Only use bare `type: 'json'` when the shape is truly dynamic
+
+## Step 3: Create Block
+
+### File Location
+`apps/sim/blocks/blocks/{service}.ts`
+
+### Block Structure
+```typescript
+import { {Service}Icon } from '@/components/icons'
+import type { BlockConfig } from '@/blocks/types'
+import { AuthMode, IntegrationType } from '@/blocks/types'
+import { getScopesForService } from '@/lib/oauth/utils'
+
+export const {Service}Block: BlockConfig = {
+  type: '{service}',
+  name: '{Service}',
+  description: '...',
+  longDescription: '...',
+  docsLink: 'https://docs.sim.ai/tools/{service}',
+  category: 'tools',
+  integrationType: IntegrationType.X,   // Primary category (see IntegrationType enum)
+  tags: ['oauth', 'api'],              // Cross-cutting tags (see IntegrationTag type)
+  bgColor: '#HEXCOLOR',
+  icon: {Service}Icon,
+  authMode: AuthMode.OAuth,  // or AuthMode.ApiKey
+
+  subBlocks: [
+    // Operation dropdown
+    {
+      id: 'operation',
+      title: 'Operation',
+      type: 'dropdown',
+      options: [
+        { label: 'Operation 1', id: 'action1' },
+        { label: 'Operation 2', id: 'action2' },
+      ],
+      value: () => 'action1',
+    },
+    // Credential field
+    {
+      id: 'credential',
+      title: '{Service} Account',
+      type: 'oauth-input',
+      serviceId: '{service}',
+      requiredScopes: getScopesForService('{service}'),
+      required: true,
+    },
+    // Conditional fields per operation
+    // ...
+  ],
+
+  tools: {
+    access: ['{service}_action1', '{service}_action2'],
+    config: {
+      tool: (params) => `{service}_${params.operation}`,
+    },
+  },
+
+  outputs: { /* ... */ },
+}
+```
+
+### Key SubBlock Patterns
+
+**Condition-based visibility:**
+```typescript
+{
+  id: 'resourceId',
+  title: 'Resource ID',
+  type: 'short-input',
+  condition: { field: 'operation', value: ['read', 'update', 'delete'] },
+  required: { field: 'operation', value: ['read', 'update', 'delete'] },
+}
+```
+
+**DependsOn for cascading selectors:**
+```typescript
+{
+  id: 'project',
+  type: 'project-selector',
+  dependsOn: ['credential'],
+},
+{
+  id: 'issue',
+  type: 'file-selector',
+  dependsOn: ['credential', 'project'],
+}
+```
+
+**Basic/Advanced mode for dual UX:**
+```typescript
+// Basic: Visual selector
+{
+  id: 'channel',
+  type: 'channel-selector',
+  mode: 'basic',
+  canonicalParamId: 'channel',
+  dependsOn: ['credential'],
+},
+// Advanced: Manual input
+{
+  id: 'channelId',
+  type: 'short-input',
+  mode: 'advanced',
+  canonicalParamId: 'channel',
+}
+```
+
+**Critical Canonical Param Rules:**
+- `canonicalParamId` must NOT match any subblock's `id` in the block
+- `canonicalParamId` must be unique per operation/condition context
+- Only use `canonicalParamId` to link basic/advanced alternatives for the same logical parameter
+- `mode` only controls UI visibility, NOT serialization. Without `canonicalParamId`, both basic and advanced field values would be sent
+- Every subblock `id` must be unique within the block. Duplicate IDs cause conflicts even with different conditions
+- **Required consistency:** If one subblock in a canonical group has `required: true`, ALL subblocks in that group must have `required: true` (prevents bypassing validation by switching modes)
+- **Inputs section:** Must list canonical param IDs (e.g., `fileId`), NOT raw subblock IDs (e.g., `fileSelector`, `manualFileId`)
+- **Params function:** Must use canonical param IDs, NOT raw subblock IDs (raw IDs are deleted after canonical transformation)
+
+## Step 4: Add Icon
+
+### File Location
+`apps/sim/components/icons.tsx`
+
+### Pattern
+```typescript
+export function {Service}Icon(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      {...props}
+      viewBox="0 0 24 24"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      {/* SVG paths from user-provided SVG */}
+    </svg>
+  )
+}
+```
+
+### Getting Icons
+**Do NOT search for icons yourself.** At the end of implementation, ask the user to provide the SVG:
+
+```
+I've completed the integration. Before I can add the icon, please provide the SVG for {Service}.
+You can usually find this in the service's brand/press kit page, or copy it from their website.
+
+Paste the SVG code here and I'll convert it to a React component.
+```
+
+Once the user provides the SVG:
+1. Extract the SVG paths/content
+2. Create a React component that spreads props
+3. Ensure viewBox is preserved from the original SVG
+
+## Step 5: Create Triggers (Optional)
+
+If the service supports webhooks, create triggers using the generic `buildTriggerSubBlocks` helper.
+
+### Directory Structure
+```
+apps/sim/triggers/{service}/
+├── index.ts      # Barrel exports
+├── utils.ts      # Trigger options, setup instructions, extra fields
+├── {event_a}.ts  # Primary trigger (includes dropdown)
+├── {event_b}.ts  # Secondary triggers (no dropdown)
+└── webhook.ts    # Generic webhook (optional)
+```
+
+### Key Pattern
+
+```typescript
+import { buildTriggerSubBlocks } from '@/triggers'
+import { {service}TriggerOptions, {service}SetupInstructions, build{Service}ExtraFields } from './utils'
+
+// Primary trigger - includeDropdown: true
+export const {service}EventATrigger: TriggerConfig = {
+  id: '{service}_event_a',
+  subBlocks: buildTriggerSubBlocks({
+    triggerId: '{service}_event_a',
+    triggerOptions: {service}TriggerOptions,
+    includeDropdown: true,  // Only for primary trigger!
+    setupInstructions: {service}SetupInstructions('Event A'),
+    extraFields: build{Service}ExtraFields('{service}_event_a'),
+  }),
+  // ...
+}
+
+// Secondary triggers - no dropdown
+export const {service}EventBTrigger: TriggerConfig = {
+  id: '{service}_event_b',
+  subBlocks: buildTriggerSubBlocks({
+    triggerId: '{service}_event_b',
+    triggerOptions: {service}TriggerOptions,
+    // No includeDropdown!
+    setupInstructions: {service}SetupInstructions('Event B'),
+    extraFields: build{Service}ExtraFields('{service}_event_b'),
+  }),
+  // ...
+}
+```
+
+### Connect to Block
+```typescript
+import { getTrigger } from '@/triggers'
+
+export const {Service}Block: BlockConfig = {
+  triggers: {
+    enabled: true,
+    available: ['{service}_event_a', '{service}_event_b'],
+  },
+  subBlocks: [
+    // Tool fields...
+    ...getTrigger('{service}_event_a').subBlocks,
+    ...getTrigger('{service}_event_b').subBlocks,
+  ],
+}
+```
+
+See `/add-trigger` skill for complete documentation.
+
+## Step 6: Register Everything
+
+### Tools Registry (`apps/sim/tools/registry.ts`)
+
+```typescript
+// Add import (alphabetically)
+import {
+  {service}Action1Tool,
+  {service}Action2Tool,
+} from '@/tools/{service}'
+
+// Add to tools object (alphabetically)
+export const tools: Record<string, ToolConfig> = {
+  // ... existing tools ...
+  {service}_action1: {service}Action1Tool,
+  {service}_action2: {service}Action2Tool,
+}
+```
+
+### Block Registry (`apps/sim/blocks/registry.ts`)
+
+```typescript
+// Add import (alphabetically)
+import { {Service}Block } from '@/blocks/blocks/{service}'
+
+// Add to registry (alphabetically)
+export const registry: Record<string, BlockConfig> = {
+  // ... existing blocks ...
+  {service}: {Service}Block,
+}
+```
+
+### Trigger Registry (`apps/sim/triggers/registry.ts`) - If triggers exist
+
+```typescript
+// Add import (alphabetically)
+import {
+  {service}EventATrigger,
+  {service}EventBTrigger,
+  {service}WebhookTrigger,
+} from '@/triggers/{service}'
+
+// Add to TRIGGER_REGISTRY (alphabetically)
+export const TRIGGER_REGISTRY: TriggerRegistry = {
+  // ... existing triggers ...
+  {service}_event_a: {service}EventATrigger,
+  {service}_event_b: {service}EventBTrigger,
+  {service}_webhook: {service}WebhookTrigger,
+}
+```
+
+## Step 7: Generate Docs
+
+Run the documentation generator:
+```bash
+bun run scripts/generate-docs.ts
+```
+
+This creates `apps/docs/content/docs/en/tools/{service}.mdx`
+
+## V2 Integration Pattern
+
+If creating V2 versions (API-aligned outputs):
+
+1. **V2 Tools** - Add `_v2` suffix, version `2.0.0`, flat outputs
+2. **V2 Block** - Add `_v2` type, use `createVersionedToolSelector`
+3. **V1 Block** - Add `(Legacy)` to name, set `hideFromToolbar: true`
+4. **Registry** - Register both versions
+
+```typescript
+// In registry
+{service}: {Service}Block,        // V1 (legacy, hidden)
+{service}_v2: {Service}V2Block,   // V2 (visible)
+```
+
+## Complete Checklist
+
+### Tools
+- [ ] Created `tools/{service}/` directory
+- [ ] Created `types.ts` with all interfaces
+- [ ] Created tool file for each operation
+- [ ] All params have correct visibility
+- [ ] All nullable fields use `?? null`
+- [ ] All optional outputs have `optional: true`
+- [ ] Created `index.ts` barrel export
+- [ ] Registered all tools in `tools/registry.ts`
+
+### Block
+- [ ] Created `blocks/blocks/{service}.ts`
+- [ ] Set `integrationType` to the correct `IntegrationType` enum value
+- [ ] Set `tags` array with all applicable `IntegrationTag` values
+- [ ] Defined operation dropdown with all operations
+- [ ] Added credential field with `requiredScopes: getScopesForService('{service}')`
+- [ ] Added conditional fields per operation
+- [ ] Set up dependsOn for cascading selectors
+- [ ] Configured tools.access with all tool IDs
+- [ ] Configured tools.config.tool selector
+- [ ] Defined outputs matching tool outputs
+- [ ] Registered block in `blocks/registry.ts`
+- [ ] If triggers: set `triggers.enabled` and `triggers.available`
+- [ ] If triggers: spread trigger subBlocks with `getTrigger()`
+
+### OAuth Scopes (if OAuth service)
+- [ ] Defined scopes in `lib/oauth/oauth.ts` under `OAUTH_PROVIDERS`
+- [ ] Added scope descriptions in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts`
+- [ ] Used `getCanonicalScopesForProvider()` in `auth.ts` (never hardcode)
+- [ ] Used `getScopesForService()` in block `requiredScopes` (never hardcode)
+
+### Icon
+- [ ] Asked user to provide SVG
+- [ ] Added icon to `components/icons.tsx`
+- [ ] Icon spreads props correctly
+
+### Triggers (if service supports webhooks)
+- [ ] Created `triggers/{service}/` directory
+- [ ] Created `utils.ts` with options, instructions, and extra fields helpers
+- [ ] Primary trigger uses `includeDropdown: true`
+- [ ] Secondary triggers do NOT have `includeDropdown`
+- [ ] All triggers use `buildTriggerSubBlocks` helper
+- [ ] Created `index.ts` barrel export
+- [ ] Registered all triggers in `triggers/registry.ts`
+
+### Docs
+- [ ] Ran `bun run scripts/generate-docs.ts`
+- [ ] Verified docs file created
+
+### Final Validation (Required)
+- [ ] Read every tool file and cross-referenced inputs/outputs against the API docs
+- [ ] Verified block subBlocks cover all required tool params with correct conditions
+- [ ] Verified block outputs match what the tools actually return
+- [ ] Verified `tools.config.params` correctly maps and coerces all param types
+
+## Example Command
+
+When the user asks to add an integration:
+
+```
+User: Add a Stripe integration
+
+You: I'll add the Stripe integration. Let me:
+
+1. First, research the Stripe API using Context7
+2. Create the tools for key operations (payments, subscriptions, etc.)
+3. Create the block with operation dropdown
+4. Register everything
+5. Generate docs
+6. Ask you for the Stripe icon SVG
+
+[Proceed with implementation...]
+
+[After completing steps 1-5...]
+
+I've completed the Stripe integration. Before I can add the icon, please provide the SVG for Stripe.
+You can usually find this in the service's brand/press kit page, or copy it from their website.
+
+Paste the SVG code here and I'll convert it to a React component.
+```
+
+## File Handling
+
+When your integration handles file uploads or downloads, follow these patterns to work with `UserFile` objects consistently.
+
+### What is a UserFile?
+
+A `UserFile` is the standard file representation in Sim:
+
+```typescript
+interface UserFile {
+  id: string       // Unique identifier
+  name: string     // Original filename
+  url: string      // Presigned URL for download
+  size: number     // File size in bytes
+  type: string     // MIME type (e.g., 'application/pdf')
+  base64?: string  // Optional base64 content (if small file)
+  key?: string     // Internal storage key
+  context?: object // Storage context metadata
+}
+```
+
+### File Input Pattern (Uploads)
+
+For tools that accept file uploads, **always route through an internal API endpoint** rather than calling external APIs directly. This ensures proper file content retrieval.
+
+#### 1. Block SubBlocks for File Input
+
+Use the basic/advanced mode pattern:
+
+```typescript
+// Basic mode: File upload UI
+{
+  id: 'uploadFile',
+  title: 'File',
+  type: 'file-upload',
+  canonicalParamId: 'file',  // Maps to 'file' param
+  placeholder: 'Upload file',
+  mode: 'basic',
+  multiple: false,
+  required: true,
+  condition: { field: 'operation', value: 'upload' },
+},
+// Advanced mode: Reference from previous block
+{
+  id: 'fileRef',
+  title: 'File',
+  type: 'short-input',
+  canonicalParamId: 'file',  // Same canonical param
+  placeholder: 'Reference file (e.g., {{file_block.output}})',
+  mode: 'advanced',
+  required: true,
+  condition: { field: 'operation', value: 'upload' },
+},
+```
+
+**Critical:** `canonicalParamId` must NOT match any subblock `id`.
+
+#### 2. Normalize File Input in Block Config
+
+In `tools.config.tool`, use `normalizeFileInput` to handle all input variants:
+
+```typescript
+import { normalizeFileInput } from '@/blocks/utils'
+
+tools: {
+  config: {
+    tool: (params) => {
+      // Normalize file from basic (uploadFile), advanced (fileRef), or legacy (fileContent)
+      const normalizedFile = normalizeFileInput(
+        params.uploadFile || params.fileRef || params.fileContent,
+        { single: true }
+      )
+      if (normalizedFile) {
+        params.file = normalizedFile
+      }
+      return `{service}_${params.operation}`
+    },
+  },
+}
+```
+
+#### 3. Create Internal API Route
+
+Create `apps/sim/app/api/tools/{service}/{action}/route.ts`:
+
+```typescript
+import { createLogger } from '@sim/logger'
+import { NextResponse, type NextRequest } from 'next/server'
+import { z } from 'zod'
+import { checkInternalAuth } from '@/lib/auth/hybrid'
+import { generateRequestId } from '@/lib/core/utils/request'
+import { FileInputSchema, type RawFileInput } from '@/lib/uploads/utils/file-schemas'
+import { processFilesToUserFiles } from '@/lib/uploads/utils/file-utils'
+import { downloadFileFromStorage } from '@/lib/uploads/utils/file-utils.server'
+
+const logger = createLogger('{Service}UploadAPI')
+
+const RequestSchema = z.object({
+  accessToken: z.string(),
+  file: FileInputSchema.optional().nullable(),
+  // Legacy field for backwards compatibility
+  fileContent: z.string().optional().nullable(),
+  // ... other params
+})
+
+export async function POST(request: NextRequest) {
+  const requestId = generateRequestId()
+
+  const authResult = await checkInternalAuth(request, { requireWorkflowId: false })
+  if (!authResult.success) {
+    return NextResponse.json({ success: false, error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const body = await request.json()
+  const data = RequestSchema.parse(body)
+
+  let fileBuffer: Buffer
+  let fileName: string
+
+  // Prefer UserFile input, fall back to legacy base64
+  if (data.file) {
+    const userFiles = processFilesToUserFiles([data.file as RawFileInput], requestId, logger)
+    if (userFiles.length === 0) {
+      return NextResponse.json({ success: false, error: 'Invalid file' }, { status: 400 })
+    }
+    const userFile = userFiles[0]
+    fileBuffer = await downloadFileFromStorage(userFile, requestId, logger)
+    fileName = userFile.name
+  } else if (data.fileContent) {
+    // Legacy: base64 string (backwards compatibility)
+    fileBuffer = Buffer.from(data.fileContent, 'base64')
+    fileName = 'file'
+  } else {
+    return NextResponse.json({ success: false, error: 'File required' }, { status: 400 })
+  }
+
+  // Now call external API with fileBuffer
+  const response = await fetch('https://api.{service}.com/upload', {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${data.accessToken}` },
+    body: new Uint8Array(fileBuffer),  // Convert Buffer for fetch
+  })
+
+  // ... handle response
+}
+```
+
+#### 4. Update Tool to Use Internal Route
+
+```typescript
+export const {service}UploadTool: ToolConfig<Params, Response> = {
+  id: '{service}_upload',
+  // ...
+  params: {
+    file: { type: 'file', required: false, visibility: 'user-or-llm' },
+    fileContent: { type: 'string', required: false, visibility: 'hidden' }, // Legacy
+  },
+  request: {
+    url: '/api/tools/{service}/upload',  // Internal route
+    method: 'POST',
+    body: (params) => ({
+      accessToken: params.accessToken,
+      file: params.file,
+      fileContent: params.fileContent,
+    }),
+  },
+}
+```
+
+### File Output Pattern (Downloads)
+
+For tools that return files, use `FileToolProcessor` to store files and return `UserFile` objects.
+
+#### In Tool transformResponse
+
+```typescript
+import { FileToolProcessor } from '@/executor/utils/file-tool-processor'
+
+transformResponse: async (response, context) => {
+  const data = await response.json()
+
+  // Process file outputs to UserFile objects
+  const fileProcessor = new FileToolProcessor(context)
+  const file = await fileProcessor.processFileData({
+    data: data.content,      // base64 or buffer
+    mimeType: data.mimeType,
+    filename: data.filename,
+  })
+
+  return {
+    success: true,
+    output: { file },
+  }
+}
+```
+
+#### In API Route (for complex file handling)
+
+```typescript
+// Return file data that FileToolProcessor can handle
+return NextResponse.json({
+  success: true,
+  output: {
+    file: {
+      data: base64Content,
+      mimeType: 'application/pdf',
+      filename: 'document.pdf',
+    },
+  },
+})
+```
+
+### Key Helpers Reference
+
+| Helper | Location | Purpose |
+|--------|----------|---------|
+| `normalizeFileInput` | `@/blocks/utils` | Normalize file params in block config |
+| `processFilesToUserFiles` | `@/lib/uploads/utils/file-utils` | Convert raw inputs to UserFile[] |
+| `downloadFileFromStorage` | `@/lib/uploads/utils/file-utils.server` | Get file Buffer from UserFile |
+| `FileToolProcessor` | `@/executor/utils/file-tool-processor` | Process tool output files |
+| `isUserFile` | `@/lib/core/utils/user-file` | Type guard for UserFile objects |
+| `FileInputSchema` | `@/lib/uploads/utils/file-schemas` | Zod schema for file validation |
+
+### Advanced Mode for Optional Fields
+
+Optional fields that are rarely used should be set to `mode: 'advanced'` so they don't clutter the basic UI. Examples: pagination tokens, time range filters, sort order, max results, reply settings.
+
+### WandConfig for Complex Inputs
+
+Use `wandConfig` for fields that are hard to fill out manually:
+- **Timestamps**: Use `generationType: 'timestamp'` to inject current date context into the AI prompt
+- **JSON arrays**: Use `generationType: 'json-object'` for structured data
+- **Complex queries**: Use a descriptive prompt explaining the expected format
+
+```typescript
+{
+  id: 'startTime',
+  title: 'Start Time',
+  type: 'short-input',
+  mode: 'advanced',
+  wandConfig: {
+    enabled: true,
+    prompt: 'Generate an ISO 8601 timestamp. Return ONLY the timestamp string.',
+    generationType: 'timestamp',
+  },
+}
+```
+
+### OAuth Scopes (Centralized System)
+
+Scopes are maintained in a single source of truth and reused everywhere:
+
+1. **Define scopes** in `lib/oauth/oauth.ts` under `OAUTH_PROVIDERS[provider].services[service].scopes`
+2. **Add descriptions** in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts` for the OAuth modal UI
+3. **Reference in auth.ts** using `getCanonicalScopesForProvider(providerId)` from `@/lib/oauth/utils`
+4. **Reference in blocks** using `getScopesForService(serviceId)` from `@/lib/oauth/utils`
+
+**Never hardcode scope arrays** in `auth.ts` or block `requiredScopes`. Always import from the centralized source.
+
+```typescript
+// In auth.ts (Better Auth config)
+scopes: getCanonicalScopesForProvider('{service}'),
+
+// In block credential sub-block
+requiredScopes: getScopesForService('{service}'),
+```
+
+### Common Gotchas
+
+1. **OAuth serviceId must match** - The `serviceId` in oauth-input must match the OAuth provider configuration
+2. **All tool IDs MUST be snake_case** - `stripe_create_payment`, not `stripeCreatePayment`. This applies to tool `id` fields, registry keys, `tools.access` arrays, and `tools.config.tool` return values
+3. **Block type is snake_case** - `type: 'stripe'`, not `type: 'Stripe'`
+4. **Alphabetical ordering** - Keep imports and registry entries alphabetically sorted
+5. **Required can be conditional** - Use `required: { field: 'op', value: 'create' }` instead of always true
+6. **DependsOn clears options** - When a dependency changes, selector options are refetched
+7. **Never pass Buffer directly to fetch** - Convert to `new Uint8Array(buffer)` for TypeScript compatibility
+8. **Always handle legacy file params** - Keep hidden `fileContent` params for backwards compatibility
+9. **Optional fields use advanced mode** - Set `mode: 'advanced'` on rarely-used optional fields
+10. **Complex inputs need wandConfig** - Timestamps, JSON arrays, and other hard-to-type values should have `wandConfig` enabled
+11. **Never hardcode scopes** - Use `getScopesForService()` in blocks and `getCanonicalScopesForProvider()` in auth.ts
+12. **Always add scope descriptions** - New scopes must have entries in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts`
--- a/.cursor/commands/add-tools.md
+++ b/.cursor/commands/add-tools.md
@@ -0,0 +1,316 @@
+# Add Tools Skill
+
+You are an expert at creating tool configurations for Sim integrations. Your job is to read API documentation and create properly structured tool files.
+
+## Your Task
+
+When the user asks you to create tools for a service:
+1. Use Context7 or WebFetch to read the service's API documentation
+2. Create the tools directory structure
+3. Generate properly typed tool configurations
+
+## Directory Structure
+
+Create files in `apps/sim/tools/{service}/`:
+```
+tools/{service}/
+├── index.ts      # Barrel export
+├── types.ts      # Parameter & response types
+└── {action}.ts   # Individual tool files (one per operation)
+```
+
+## Tool Configuration Structure
+
+Every tool MUST follow this exact structure:
+
+```typescript
+import type { {ServiceName}{Action}Params } from '@/tools/{service}/types'
+import type { ToolConfig } from '@/tools/types'
+
+interface {ServiceName}{Action}Response {
+  success: boolean
+  output: {
+    // Define output structure here
+  }
+}
+
+export const {serviceName}{Action}Tool: ToolConfig<
+  {ServiceName}{Action}Params,
+  {ServiceName}{Action}Response
+> = {
+  id: '{service}_{action}',           // snake_case, matches tool name
+  name: '{Service} {Action}',         // Human readable
+  description: 'Brief description',   // One sentence
+  version: '1.0.0',
+
+  // OAuth config (if service uses OAuth)
+  oauth: {
+    required: true,
+    provider: '{service}',            // Must match OAuth provider ID
+  },
+
+  params: {
+    // Hidden params (system-injected, only use hidden for oauth accessToken)
+    accessToken: {
+      type: 'string',
+      required: true,
+      visibility: 'hidden',
+      description: 'OAuth access token',
+    },
+    // User-only params (credentials, api key, IDs user must provide)
+    someId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'The ID of the resource',
+    },
+    // User-or-LLM params (everything else, can be provided by user OR computed by LLM)
+    query: {
+      type: 'string',
+      required: false,                // Use false for optional
+      visibility: 'user-or-llm',
+      description: 'Search query',
+    },
+  },
+
+  request: {
+    url: (params) => `https://api.service.com/v1/resource/${params.id}`,
+    method: 'POST',
+    headers: (params) => ({
+      Authorization: `Bearer ${params.accessToken}`,
+      'Content-Type': 'application/json',
+    }),
+    body: (params) => ({
+      // Request body - only for POST/PUT/PATCH
+      // Trim ID fields to prevent copy-paste whitespace errors:
+      // userId: params.userId?.trim(),
+    }),
+  },
+
+  transformResponse: async (response: Response) => {
+    const data = await response.json()
+    return {
+      success: true,
+      output: {
+        // Map API response to output
+        // Use ?? null for nullable fields
+        // Use ?? [] for optional arrays
+      },
+    }
+  },
+
+  outputs: {
+    // Define each output field
+  },
+}
+```
+
+## Critical Rules for Parameters
+
+### Visibility Options
+- `'hidden'` - System-injected (OAuth tokens, internal params). User never sees.
+- `'user-only'` - User must provide (credentials, api keys, account-specific IDs)
+- `'user-or-llm'` - User provides OR LLM can compute (search queries, content, filters, most fall into this category)
+
+### Parameter Types
+- `'string'` - Text values
+- `'number'` - Numeric values
+- `'boolean'` - True/false
+- `'json'` - Complex objects (NOT 'object', use 'json')
+- `'file'` - Single file
+- `'file[]'` - Multiple files
+
+### Required vs Optional
+- Always explicitly set `required: true` or `required: false`
+- Optional params should have `required: false`
+
+## Critical Rules for Outputs
+
+### Output Types
+- `'string'`, `'number'`, `'boolean'` - Primitives
+- `'json'` - Complex objects (use this, NOT 'object')
+- `'array'` - Arrays with `items` property
+- `'object'` - Objects with `properties` property
+
+### Optional Outputs
+Add `optional: true` for fields that may not exist in the response:
+```typescript
+closedAt: {
+  type: 'string',
+  description: 'When the issue was closed',
+  optional: true,
+},
+```
+
+### Typed JSON Outputs
+
+When using `type: 'json'` and you know the object shape in advance, **always define the inner structure** using `properties` so downstream consumers know what fields are available:
+
+```typescript
+// BAD: Opaque json with no info about what's inside
+metadata: {
+  type: 'json',
+  description: 'Response metadata',
+},
+
+// GOOD: Define the known properties
+metadata: {
+  type: 'json',
+  description: 'Response metadata',
+  properties: {
+    id: { type: 'string', description: 'Unique ID' },
+    status: { type: 'string', description: 'Current status' },
+    count: { type: 'number', description: 'Total count' },
+  },
+},
+```
+
+For arrays of objects, define the item structure:
+```typescript
+items: {
+  type: 'array',
+  description: 'List of items',
+  items: {
+    type: 'object',
+    properties: {
+      id: { type: 'string', description: 'Item ID' },
+      name: { type: 'string', description: 'Item name' },
+    },
+  },
+},
+```
+
+Only use bare `type: 'json'` without `properties` when the shape is truly dynamic or unknown.
+
+## Critical Rules for transformResponse
+
+### Handle Nullable Fields
+ALWAYS use `?? null` for fields that may be undefined:
+```typescript
+transformResponse: async (response: Response) => {
+  const data = await response.json()
+  return {
+    success: true,
+    output: {
+      id: data.id,
+      title: data.title,
+      body: data.body ?? null,           // May be undefined
+      assignee: data.assignee ?? null,   // May be undefined
+      labels: data.labels ?? [],         // Default to empty array
+      closedAt: data.closed_at ?? null,  // May be undefined
+    },
+  }
+}
+```
+
+### Never Output Raw JSON Dumps
+DON'T do this:
+```typescript
+output: {
+  data: data,  // BAD - raw JSON dump
+}
+```
+
+DO this instead - extract meaningful fields:
+```typescript
+output: {
+  id: data.id,
+  name: data.name,
+  status: data.status,
+  metadata: {
+    createdAt: data.created_at,
+    updatedAt: data.updated_at,
+  },
+}
+```
+
+## Types File Pattern
+
+Create `types.ts` with interfaces for all params and responses:
+
+```typescript
+import type { ToolResponse } from '@/tools/types'
+
+// Parameter interfaces
+export interface {Service}{Action}Params {
+  accessToken: string
+  requiredField: string
+  optionalField?: string
+}
+
+// Response interfaces (extend ToolResponse)
+export interface {Service}{Action}Response extends ToolResponse {
+  output: {
+    field1: string
+    field2: number
+    optionalField?: string | null
+  }
+}
+```
+
+## Index.ts Barrel Export Pattern
+
+```typescript
+// Export all tools
+export { serviceTool1 } from './{action1}'
+export { serviceTool2 } from './{action2}'
+
+// Export types
+export * from './types'
+```
+
+## Registering Tools
+
+After creating tools, remind the user to:
+1. Import tools in `apps/sim/tools/registry.ts`
+2. Add to the `tools` object with snake_case keys:
+```typescript
+import { serviceActionTool } from '@/tools/{service}'
+
+export const tools = {
+  // ... existing tools ...
+  {service}_{action}: serviceActionTool,
+}
+```
+
+## V2 Tool Pattern
+
+If creating V2 tools (API-aligned outputs), use `_v2` suffix:
+- Tool ID: `{service}_{action}_v2`
+- Variable name: `{action}V2Tool`
+- Version: `'2.0.0'`
+- Outputs: Flat, API-aligned (no content/metadata wrapper)
+
+## Naming Convention
+
+All tool IDs MUST use `snake_case`: `{service}_{action}` (e.g., `x_create_tweet`, `slack_send_message`). Never use camelCase or PascalCase for tool IDs.
+
+## Checklist Before Finishing
+
+- [ ] All tool IDs use snake_case
+- [ ] All params have explicit `required: true` or `required: false`
+- [ ] All params have appropriate `visibility`
+- [ ] All nullable response fields use `?? null`
+- [ ] All optional outputs have `optional: true`
+- [ ] No raw JSON dumps in outputs
+- [ ] Types file has all interfaces
+- [ ] Index.ts exports all tools
+
+## Final Validation (Required)
+
+After creating all tools, you MUST validate every tool before finishing:
+
+1. **Read every tool file** you created — do not skip any
+2. **Cross-reference with the API docs** to verify:
+   - All required params are marked `required: true`
+   - All optional params are marked `required: false`
+   - Param types match the API (string, number, boolean, json)
+   - Request URL, method, headers, and body match the API spec
+   - `transformResponse` extracts the correct fields from the API response
+   - All output fields match what the API actually returns
+   - No fields are missing from outputs that the API provides
+   - No extra fields are defined in outputs that the API doesn't return
+3. **Verify consistency** across tools:
+   - Shared types in `types.ts` match all tools that use them
+   - Tool IDs in the barrel export match the tool file definitions
+   - Error handling is consistent (error checks, meaningful messages)
--- a/.cursor/commands/add-trigger.md
+++ b/.cursor/commands/add-trigger.md
@@ -0,0 +1,492 @@
+# Add Trigger
+
+You are an expert at creating webhook and polling triggers for Sim. You understand the trigger system, the generic `buildTriggerSubBlocks` helper, polling infrastructure, and how triggers connect to blocks.
+
+## Your Task
+
+1. Research what webhook events the service supports — if the service lacks reliable webhooks, use polling
+2. Create the trigger files using the generic builder (webhook) or manual config (polling)
+3. Create a provider handler (webhook) or polling handler (polling)
+4. Register triggers and connect them to the block
+
+## Directory Structure
+
+```
+apps/sim/triggers/{service}/
+├── index.ts              # Barrel exports
+├── utils.ts              # Service-specific helpers (options, instructions, extra fields, outputs)
+├── {event_a}.ts          # Primary trigger (includes dropdown)
+├── {event_b}.ts          # Secondary trigger (no dropdown)
+└── webhook.ts            # Generic webhook trigger (optional, for "all events")
+
+apps/sim/lib/webhooks/
+├── provider-subscription-utils.ts  # Shared subscription helpers (getProviderConfig, getNotificationUrl)
+├── providers/
+│   ├── {service}.ts       # Provider handler (auth, formatInput, matchEvent, subscriptions)
+│   ├── types.ts           # WebhookProviderHandler interface
+│   ├── utils.ts           # Shared helpers (createHmacVerifier, verifyTokenAuth, skipByEventTypes)
+│   └── registry.ts        # Handler map + default handler
+```
+
+## Step 1: Create `utils.ts`
+
+This file contains all service-specific helpers used by triggers.
+
+```typescript
+import type { SubBlockConfig } from '@/blocks/types'
+import type { TriggerOutput } from '@/triggers/types'
+
+export const {service}TriggerOptions = [
+  { label: 'Event A', id: '{service}_event_a' },
+  { label: 'Event B', id: '{service}_event_b' },
+]
+
+export function {service}SetupInstructions(eventType: string): string {
+  const instructions = [
+    'Copy the <strong>Webhook URL</strong> above',
+    'Go to <strong>{Service} Settings > Webhooks</strong>',
+    `Select the <strong>${eventType}</strong> event type`,
+    'Paste the webhook URL and save',
+    'Click "Save" above to activate your trigger',
+  ]
+  return instructions
+    .map((instruction, index) =>
+      `<div class="mb-3"><strong>${index + 1}.</strong> ${instruction}</div>`
+    )
+    .join('')
+}
+
+export function build{Service}ExtraFields(triggerId: string): SubBlockConfig[] {
+  return [
+    {
+      id: 'projectId',
+      title: 'Project ID (Optional)',
+      type: 'short-input',
+      placeholder: 'Leave empty for all projects',
+      mode: 'trigger',
+      condition: { field: 'selectedTriggerId', value: triggerId },
+    },
+  ]
+}
+
+export function build{Service}Outputs(): Record<string, TriggerOutput> {
+  return {
+    eventType: { type: 'string', description: 'The type of event' },
+    resourceId: { type: 'string', description: 'ID of the affected resource' },
+    resource: {
+      id: { type: 'string', description: 'Resource ID' },
+      name: { type: 'string', description: 'Resource name' },
+    },
+  }
+}
+```
+
+## Step 2: Create Trigger Files
+
+**Primary trigger** — MUST include `includeDropdown: true`:
+
+```typescript
+import { {Service}Icon } from '@/components/icons'
+import { buildTriggerSubBlocks } from '@/triggers'
+import { build{Service}ExtraFields, build{Service}Outputs, {service}SetupInstructions, {service}TriggerOptions } from '@/triggers/{service}/utils'
+import type { TriggerConfig } from '@/triggers/types'
+
+export const {service}EventATrigger: TriggerConfig = {
+  id: '{service}_event_a',
+  name: '{Service} Event A',
+  provider: '{service}',
+  description: 'Trigger workflow when Event A occurs',
+  version: '1.0.0',
+  icon: {Service}Icon,
+  subBlocks: buildTriggerSubBlocks({
+    triggerId: '{service}_event_a',
+    triggerOptions: {service}TriggerOptions,
+    includeDropdown: true,
+    setupInstructions: {service}SetupInstructions('Event A'),
+    extraFields: build{Service}ExtraFields('{service}_event_a'),
+  }),
+  outputs: build{Service}Outputs(),
+  webhook: { method: 'POST', headers: { 'Content-Type': 'application/json' } },
+}
+```
+
+**Secondary triggers** — NO `includeDropdown` (it's already in the primary):
+
+```typescript
+export const {service}EventBTrigger: TriggerConfig = {
+  // Same as above but: id: '{service}_event_b', no includeDropdown
+}
+```
+
+## Step 3: Register and Wire
+
+### `apps/sim/triggers/{service}/index.ts`
+
+```typescript
+export { {service}EventATrigger } from './event_a'
+export { {service}EventBTrigger } from './event_b'
+```
+
+### `apps/sim/triggers/registry.ts`
+
+```typescript
+import { {service}EventATrigger, {service}EventBTrigger } from '@/triggers/{service}'
+
+export const TRIGGER_REGISTRY: TriggerRegistry = {
+  // ... existing ...
+  {service}_event_a: {service}EventATrigger,
+  {service}_event_b: {service}EventBTrigger,
+}
+```
+
+### Block file (`apps/sim/blocks/blocks/{service}.ts`)
+
+Wire triggers into the block so the trigger UI appears and `generate-docs.ts` discovers them. Two changes are needed:
+
+1. **Spread trigger subBlocks** at the end of the block's `subBlocks` array
+2. **Add `triggers` property** after `outputs` with `enabled: true` and `available: [...]`
+
+```typescript
+import { getTrigger } from '@/triggers'
+
+export const {Service}Block: BlockConfig = {
+  // ...
+  subBlocks: [
+    // Regular tool subBlocks first...
+    ...getTrigger('{service}_event_a').subBlocks,
+    ...getTrigger('{service}_event_b').subBlocks,
+  ],
+  // ... tools, inputs, outputs ...
+  triggers: {
+    enabled: true,
+    available: ['{service}_event_a', '{service}_event_b'],
+  },
+}
+```
+
+**Versioned blocks (V1 + V2):** Many integrations have a hidden V1 block and a visible V2 block. Where you add the trigger wiring depends on how V2 inherits from V1:
+
+- **V2 uses `...V1Block` spread** (e.g., Google Calendar): Add trigger to V1 — V2 inherits both `subBlocks` and `triggers` automatically.
+- **V2 defines its own `subBlocks`** (e.g., Google Sheets): Add trigger to V2 (the visible block). V1 is hidden and doesn't need it.
+- **Single block, no V2** (e.g., Google Drive): Add trigger directly.
+
+`generate-docs.ts` deduplicates by base type (first match wins). If V1 is processed first without triggers, the V2 triggers won't appear in `integrations.json`. Always verify by checking the output after running the script.
+
+## Provider Handler
+
+All provider-specific webhook logic lives in a single handler file: `apps/sim/lib/webhooks/providers/{service}.ts`.
+
+### When to Create a Handler
+
+| Behavior | Method | Examples |
+|---|---|---|
+| HMAC signature auth | `verifyAuth` via `createHmacVerifier` | Ashby, Jira, Linear, Typeform |
+| Custom token auth | `verifyAuth` via `verifyTokenAuth` | Generic, Google Forms |
+| Event filtering | `matchEvent` | GitHub, Jira, Attio, HubSpot |
+| Idempotency dedup | `extractIdempotencyId` | Slack, Stripe, Linear, Jira |
+| Custom input formatting | `formatInput` | Slack, Teams, Attio, Ashby |
+| Auto webhook creation | `createSubscription` | Ashby, Grain, Calendly, Airtable |
+| Auto webhook deletion | `deleteSubscription` | Ashby, Grain, Calendly, Airtable |
+| Challenge/verification | `handleChallenge` | Slack, WhatsApp, Teams |
+| Custom success response | `formatSuccessResponse` | Slack, Twilio Voice, Teams |
+
+If none apply, you don't need a handler. The default handler provides bearer token auth.
+
+### Example Handler
+
+```typescript
+import crypto from 'crypto'
+import { createLogger } from '@sim/logger'
+import { safeCompare } from '@/lib/core/security/encryption'
+import type { EventMatchContext, FormatInputContext, FormatInputResult, WebhookProviderHandler } from '@/lib/webhooks/providers/types'
+import { createHmacVerifier } from '@/lib/webhooks/providers/utils'
+
+const logger = createLogger('WebhookProvider:{Service}')
+
+function validate{Service}Signature(secret: string, signature: string, body: string): boolean {
+  if (!secret || !signature || !body) return false
+  const computed = crypto.createHmac('sha256', secret).update(body, 'utf8').digest('hex')
+  return safeCompare(computed, signature)
+}
+
+export const {service}Handler: WebhookProviderHandler = {
+  verifyAuth: createHmacVerifier({
+    configKey: 'webhookSecret',
+    headerName: 'X-{Service}-Signature',
+    validateFn: validate{Service}Signature,
+    providerLabel: '{Service}',
+  }),
+
+  async matchEvent({ body, requestId, providerConfig }: EventMatchContext) {
+    const triggerId = providerConfig.triggerId as string | undefined
+    if (triggerId && triggerId !== '{service}_webhook') {
+      const { is{Service}EventMatch } = await import('@/triggers/{service}/utils')
+      if (!is{Service}EventMatch(triggerId, body as Record<string, unknown>)) return false
+    }
+    return true
+  },
+
+  async formatInput({ body }: FormatInputContext): Promise<FormatInputResult> {
+    const b = body as Record<string, unknown>
+    return {
+      input: {
+        eventType: b.type,
+        resourceId: (b.data as Record<string, unknown>)?.id || '',
+        resource: b.data,
+      },
+    }
+  },
+
+  extractIdempotencyId(body: unknown) {
+    const obj = body as Record<string, unknown>
+    return obj.id && obj.type ? `${obj.type}:${obj.id}` : null
+  },
+}
+```
+
+### Register the Handler
+
+In `apps/sim/lib/webhooks/providers/registry.ts`:
+
+```typescript
+import { {service}Handler } from '@/lib/webhooks/providers/{service}'
+
+const PROVIDER_HANDLERS: Record<string, WebhookProviderHandler> = {
+  // ... existing (alphabetical) ...
+  {service}: {service}Handler,
+}
+```
+
+## Output Alignment (Critical)
+
+There are two sources of truth that **MUST be aligned**:
+
+1. **Trigger `outputs`** — schema defining what fields SHOULD be available (UI tag dropdown)
+2. **`formatInput` on the handler** — implementation that transforms raw payload into actual data
+
+If they differ: the tag dropdown shows fields that don't exist, or actual data has fields users can't discover.
+
+**Rules for `formatInput`:**
+- Return `{ input: { ... } }` where inner keys match trigger `outputs` exactly
+- Return `{ input: ..., skip: { message: '...' } }` to skip execution
+- No wrapper objects or duplication
+- Use `null` for missing optional data
+
+## Automatic Webhook Registration
+
+If the service API supports programmatic webhook creation, implement `createSubscription` and `deleteSubscription` on the handler. The orchestration layer calls these automatically — **no code touches `route.ts`, `provider-subscriptions.ts`, or `deploy.ts`**.
+
+```typescript
+import { getNotificationUrl, getProviderConfig } from '@/lib/webhooks/provider-subscription-utils'
+import type { DeleteSubscriptionContext, SubscriptionContext, SubscriptionResult } from '@/lib/webhooks/providers/types'
+
+export const {service}Handler: WebhookProviderHandler = {
+  async createSubscription(ctx: SubscriptionContext): Promise<SubscriptionResult | undefined> {
+    const config = getProviderConfig(ctx.webhook)
+    const apiKey = config.apiKey as string
+    if (!apiKey) throw new Error('{Service} API Key is required.')
+
+    const res = await fetch('https://api.{service}.com/webhooks', {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ url: getNotificationUrl(ctx.webhook) }),
+    })
+
+    if (!res.ok) throw new Error(`{Service} error: ${res.status}`)
+    const { id } = (await res.json()) as { id: string }
+    return { providerConfigUpdates: { externalId: id } }
+  },
+
+  async deleteSubscription(ctx: DeleteSubscriptionContext): Promise<void> {
+    const config = getProviderConfig(ctx.webhook)
+    const { apiKey, externalId } = config as { apiKey?: string; externalId?: string }
+    if (!apiKey || !externalId) return
+    await fetch(`https://api.{service}.com/webhooks/${externalId}`, {
+      method: 'DELETE',
+      headers: { Authorization: `Bearer ${apiKey}` },
+    }).catch(() => {})
+  },
+}
+```
+
+**Key points:**
+- Throw from `createSubscription` — orchestration rolls back the DB webhook
+- Never throw from `deleteSubscription` — log non-fatally
+- Return `{ providerConfigUpdates: { externalId } }` — orchestration merges into `providerConfig`
+- Add `apiKey` field to `build{Service}ExtraFields` with `password: true`
+
+## Trigger Outputs Schema
+
+Trigger outputs use the same schema as block outputs (NOT tool outputs).
+
+**Supported:** `type` + `description` for leaf fields, nested objects for complex data.
+**NOT supported:** `optional: true`, `items` (those are tool-output-only features).
+
+```typescript
+export function buildOutputs(): Record<string, TriggerOutput> {
+  return {
+    eventType: { type: 'string', description: 'Event type' },
+    timestamp: { type: 'string', description: 'When it occurred' },
+    payload: { type: 'json', description: 'Full event payload' },
+    resource: {
+      id: { type: 'string', description: 'Resource ID' },
+      name: { type: 'string', description: 'Resource name' },
+    },
+  }
+}
+```
+
+## Polling Triggers
+
+Use polling when the service lacks reliable webhooks (e.g., Google Sheets, Google Drive, Google Calendar, Gmail, RSS, IMAP). Polling triggers do NOT use `buildTriggerSubBlocks` — they define subBlocks manually.
+
+### Directory Structure
+
+```
+apps/sim/triggers/{service}/
+├── index.ts              # Barrel export
+└── poller.ts             # TriggerConfig with polling: true
+
+apps/sim/lib/webhooks/polling/
+└── {service}.ts           # PollingProviderHandler implementation
+```
+
+### Polling Handler (`apps/sim/lib/webhooks/polling/{service}.ts`)
+
+```typescript
+import { pollingIdempotency } from '@/lib/core/idempotency/service'
+import type { PollingProviderHandler, PollWebhookContext } from '@/lib/webhooks/polling/types'
+import { markWebhookFailed, markWebhookSuccess, resolveOAuthCredential, updateWebhookProviderConfig } from '@/lib/webhooks/polling/utils'
+import { processPolledWebhookEvent } from '@/lib/webhooks/processor'
+
+export const {service}PollingHandler: PollingProviderHandler = {
+  provider: '{service}',
+  label: '{Service}',
+
+  async pollWebhook(ctx: PollWebhookContext): Promise<'success' | 'failure'> {
+    const { webhookData, workflowData, requestId, logger } = ctx
+    const webhookId = webhookData.id
+
+    try {
+      // For OAuth services:
+      const accessToken = await resolveOAuthCredential(webhookData, '{service}', requestId, logger)
+      const config = webhookData.providerConfig as unknown as {Service}WebhookConfig
+
+      // First poll: seed state, emit nothing
+      if (!config.lastCheckedTimestamp) {
+        await updateWebhookProviderConfig(webhookId, { lastCheckedTimestamp: new Date().toISOString() }, logger)
+        await markWebhookSuccess(webhookId, logger)
+        return 'success'
+      }
+
+      // Fetch changes since last poll, process with idempotency
+      // ...
+
+      await markWebhookSuccess(webhookId, logger)
+      return 'success'
+    } catch (error) {
+      logger.error(`[${requestId}] Error processing {service} webhook ${webhookId}:`, error)
+      await markWebhookFailed(webhookId, logger)
+      return 'failure'
+    }
+  },
+}
+```
+
+**Key patterns:**
+- First poll seeds state and emits nothing (avoids flooding with existing data)
+- Use `pollingIdempotency.executeWithIdempotency(provider, key, callback)` for dedup
+- Use `processPolledWebhookEvent(webhookData, workflowData, payload, requestId)` to fire the workflow
+- Use `updateWebhookProviderConfig(webhookId, partialConfig, logger)` for read-merge-write on state
+- Use the latest server-side timestamp from API responses (not wall clock) to avoid clock skew
+
+### Trigger Config (`apps/sim/triggers/{service}/poller.ts`)
+
+```typescript
+import { {Service}Icon } from '@/components/icons'
+import type { TriggerConfig } from '@/triggers/types'
+
+export const {service}PollingTrigger: TriggerConfig = {
+  id: '{service}_poller',
+  name: '{Service} Trigger',
+  provider: '{service}',
+  description: 'Triggers when ...',
+  version: '1.0.0',
+  icon: {Service}Icon,
+  polling: true,               // REQUIRED — routes to polling infrastructure
+
+  subBlocks: [
+    { id: 'triggerCredentials', type: 'oauth-input', title: 'Credentials', serviceId: '{service}', requiredScopes: [], required: true, mode: 'trigger', supportsCredentialSets: true },
+    // ... service-specific config fields (dropdowns, inputs, switches) ...
+    { id: 'triggerInstructions', type: 'text', title: 'Setup Instructions', hideFromPreview: true, mode: 'trigger', defaultValue: '...' },
+  ],
+
+  outputs: {
+    // Must match the payload shape from processPolledWebhookEvent
+  },
+}
+```
+
+### Registration (3 places)
+
+1. **`apps/sim/triggers/constants.ts`** — add provider to `POLLING_PROVIDERS` Set
+2. **`apps/sim/lib/webhooks/polling/registry.ts`** — import handler, add to `POLLING_HANDLERS`
+3. **`apps/sim/triggers/registry.ts`** — import trigger config, add to `TRIGGER_REGISTRY`
+
+### Helm Cron Job
+
+Add to `helm/sim/values.yaml` under the existing polling cron jobs:
+
+```yaml
+{service}WebhookPoll:
+  schedule: "*/1 * * * *"
+  concurrencyPolicy: Forbid
+  url: "http://sim:3000/api/webhooks/poll/{service}"
+```
+
+### Reference Implementations
+
+- Simple: `apps/sim/lib/webhooks/polling/rss.ts` + `apps/sim/triggers/rss/poller.ts`
+- Complex (OAuth, attachments): `apps/sim/lib/webhooks/polling/gmail.ts` + `apps/sim/triggers/gmail/poller.ts`
+- Cursor-based (changes API): `apps/sim/lib/webhooks/polling/google-drive.ts`
+- Timestamp-based: `apps/sim/lib/webhooks/polling/google-calendar.ts`
+
+## Checklist
+
+### Trigger Definition
+- [ ] Created `utils.ts` with options, instructions, extra fields, and output builders
+- [ ] Primary trigger has `includeDropdown: true`; secondary triggers do NOT
+- [ ] All triggers use `buildTriggerSubBlocks` helper
+- [ ] Created `index.ts` barrel export
+
+### Registration
+- [ ] All triggers in `triggers/registry.ts` → `TRIGGER_REGISTRY`
+- [ ] Block has `triggers.enabled: true` and lists all trigger IDs in `triggers.available`
+- [ ] Block spreads all trigger subBlocks: `...getTrigger('id').subBlocks`
+
+### Provider Handler (if needed)
+- [ ] Handler file at `apps/sim/lib/webhooks/providers/{service}.ts`
+- [ ] Registered in `providers/registry.ts` (alphabetical)
+- [ ] Signature validator is a private function inside the handler file
+- [ ] `formatInput` output keys match trigger `outputs` exactly
+- [ ] Event matching uses dynamic `await import()` for trigger utils
+
+### Auto Registration (if supported)
+- [ ] `createSubscription` and `deleteSubscription` on the handler
+- [ ] NO changes to `route.ts`, `provider-subscriptions.ts`, or `deploy.ts`
+- [ ] API key field uses `password: true`
+
+### Polling Trigger (if applicable)
+- [ ] Handler implements `PollingProviderHandler` at `lib/webhooks/polling/{service}.ts`
+- [ ] Trigger config has `polling: true` and defines subBlocks manually (no `buildTriggerSubBlocks`)
+- [ ] Provider string matches across: trigger config, handler, `POLLING_PROVIDERS`, polling registry
+- [ ] First poll seeds state and emits nothing
+- [ ] Added provider to `POLLING_PROVIDERS` in `triggers/constants.ts`
+- [ ] Added handler to `POLLING_HANDLERS` in `lib/webhooks/polling/registry.ts`
+- [ ] Added cron job to `helm/sim/values.yaml`
+- [ ] Payload shape matches trigger `outputs` schema
+
+### Testing
+- [ ] `bun run type-check` passes
+- [ ] Manually verify output keys match trigger `outputs` keys
+- [ ] Trigger UI shows correctly in the block
--- a/.cursor/commands/cleanup.md
+++ b/.cursor/commands/cleanup.md
@@ -0,0 +1,20 @@
+# Cleanup
+
+Arguments:
+- scope: what to review (default: your current changes). Examples: "diff to main", "PR #123", "src/components/", "whole codebase"
+- fix: whether to apply fixes (default: true). Set to false to only propose changes.
+
+User arguments: $ARGUMENTS
+
+## Steps
+
+Run each of these skills in order on the specified scope, passing through the scope and fix arguments. After each skill completes, move to the next. Do not skip any.
+
+1. `/you-might-not-need-an-effect $ARGUMENTS`
+2. `/you-might-not-need-a-memo $ARGUMENTS`
+3. `/you-might-not-need-a-callback $ARGUMENTS`
+4. `/you-might-not-need-state $ARGUMENTS`
+5. `/react-query-best-practices $ARGUMENTS`
+6. `/emcn-design-review $ARGUMENTS`
+
+After all skills have run, output a summary of what was found and fixed (or proposed) across all six passes.
--- a/.cursor/commands/emcn-design-review.md
+++ b/.cursor/commands/emcn-design-review.md
@@ -0,0 +1,74 @@
+# EMCN Design Review
+
+Arguments:
+- scope: what to review (default: your current changes). Examples: "diff to main", "PR #123", "src/components/", "whole codebase"
+- fix: whether to apply fixes (default: true). Set to false to only propose changes.
+
+User arguments: $ARGUMENTS
+
+## Context
+
+This codebase uses **emcn**, a custom component library built on Radix UI primitives with CVA variants and CSS variable design tokens. All UI must use emcn components and tokens.
+
+## Steps
+
+1. Read the emcn barrel export at `apps/sim/components/emcn/components/index.ts` to know what's available
+2. Read `apps/sim/app/_styles/globals.css` for CSS variable tokens
+3. Analyze the specified scope against every rule below
+4. If fix=true, apply the fixes. If fix=false, propose the fixes without applying.
+
+---
+
+## Imports
+
+- Import from `@/components/emcn` barrel, never subpaths
+- Icons from `@/components/emcn/icons` or `lucide-react`
+- Use `cn` from `@/lib/core/utils/cn` for conditional classes
+
+## Design Tokens
+
+Use CSS variable pattern (`text-[var(--text-primary)]`), never Tailwind semantics (`text-muted-foreground`) or hardcoded colors (`text-gray-500`, `#333`).
+
+**Text**: `--text-primary`, `--text-secondary`, `--text-tertiary`, `--text-muted`, `--text-icon`, `--text-inverse`, `--text-error`
+**Surfaces**: `--bg`, `--surface-2` through `--surface-7`, `--surface-hover`, `--surface-active`
+**Borders**: `--border`, `--border-1`, `--border-muted`
+**Z-Index**: `--z-dropdown` (100), `--z-modal` (200), `--z-popover` (300), `--z-tooltip` (400), `--z-toast` (500)
+**Shadows**: `shadow-subtle`, `shadow-medium`, `shadow-overlay`, `shadow-card`
+
+## Buttons
+
+| Action | Variant |
+|--------|---------|
+| Toolbar, icon-only | `ghost` (most common, 28%) |
+| Create, save, submit | `primary` (24%) |
+| Cancel, close | `default` |
+| Delete, remove | `destructive` |
+| Selected state | `active` |
+| Toggle | `outline` |
+
+## Delete/Remove Confirmations
+
+Modal `size="sm"`, title "Delete/Remove {ItemType}", `variant="destructive"` action button, `variant="default"` cancel. Cancel left, action right (100% compliance). Use `text-[var(--text-error)]` for irreversible warnings.
+
+## Toast
+
+`toast.success()`, `toast.error()`, `toast()` from `@/components/emcn`. Never custom notification UI.
+
+## Badges
+
+`red`=error/failed, `gray-secondary`=metadata/roles, `type`=type annotations, `green`=success/active, `gray`=neutral, `amber`=processing, `orange`=paused, `blue`=info. Use `dot` prop for status indicators.
+
+## Icons
+
+Default: `h-[14px] w-[14px]` (400+ uses). Color: `text-[var(--text-icon)]`. Scale: 14px > 16px > 12px > 20px.
+
+## Anti-patterns to flag
+
+- Raw `<button>`/`<input>` instead of emcn components
+- Hardcoded colors (`text-gray-*`, `#hex`, `rgb()`)
+- Tailwind semantics (`text-muted-foreground`) instead of CSS variables
+- Template literal className instead of `cn()`
+- Inline styles for colors/static values (dynamic values OK)
+- Importing from emcn subpaths instead of barrel
+- Arbitrary z-index instead of tokens
+- Wrong button variant for action type
--- a/.cursor/commands/react-query-best-practices.md
+++ b/.cursor/commands/react-query-best-practices.md
@@ -0,0 +1,49 @@
+# React Query Best Practices
+
+Arguments:
+- scope: what to analyze (default: your current changes). Examples: "diff to main", "PR #123", "src/hooks/queries/", "whole codebase"
+- fix: whether to apply fixes (default: true). Set to false to only propose changes.
+
+User arguments: $ARGUMENTS
+
+## Context
+
+This codebase uses React Query (TanStack Query) as the single source of truth for all server state. All query hooks live in `hooks/queries/`. Zustand is used only for client-only UI state. Server data must never be duplicated into useState or Zustand outside of mutation callbacks that coordinate cross-store state.
+
+## References
+
+Read these before analyzing:
+1. https://tkdodo.eu/blog/practical-react-query — foundational defaults, custom hooks, avoiding local state copies
+2. https://tkdodo.eu/blog/effective-react-query-keys — key factory pattern, hierarchical keys, fuzzy invalidation
+3. https://tkdodo.eu/blog/react-query-as-a-state-manager — React Query IS your server state manager
+
+## Rules to enforce
+
+### Query key factories
+- Every file in `hooks/queries/` must have a hierarchical key factory with an `all` root key
+- Keys must include intermediate plural keys (`lists`, `details`) for prefix invalidation
+- Key factories are colocated with their query hooks, not in a global keys file
+
+### Query hooks
+- Every `queryFn` must forward `signal` for request cancellation
+- Every query must have an explicit `staleTime` (default 0 is almost never correct)
+- `keepPreviousData` / `placeholderData` only on variable-key queries (where params change), never on static keys
+- Use `enabled` to prevent queries from running without required params
+
+### Mutations
+- Use `onSettled` (not `onSuccess`) for cache reconciliation — it fires on both success and error
+- For optimistic updates: save previous data in `onMutate`, roll back in `onError`
+- Use targeted invalidation (`entityKeys.lists()`) not broad (`entityKeys.all`) when possible
+- Don't include mutation objects in `useCallback` deps — `.mutate()` is stable
+
+### Server state ownership
+- Never copy query data into useState. Use query data directly in components.
+- Never copy query data into Zustand stores (exception: mutation callbacks that coordinate cross-store state like temp ID replacement)
+- The query cache is not a local state manager — `setQueryData` is for optimistic updates only
+- Forms are the one deliberate exception: copy server data into local form state with `staleTime: Infinity`
+
+## Steps
+
+1. Read the references above to understand the guidelines
+2. Analyze the specified scope against the rules listed above
+3. If fix=true, apply the fixes. If fix=false, propose the fixes without applying.
--- a/.cursor/commands/validate-connector.md
+++ b/.cursor/commands/validate-connector.md
@@ -0,0 +1,311 @@
+# Validate Connector Skill
+
+You are an expert auditor for Sim knowledge base connectors. Your job is to thoroughly validate that an existing connector is correct, complete, and follows all conventions.
+
+## Your Task
+
+When the user asks you to validate a connector:
+1. Read the service's API documentation (via Context7 or WebFetch)
+2. Read the connector implementation, OAuth config, and registry entries
+3. Cross-reference everything against the API docs and Sim conventions
+4. Report all issues found, grouped by severity (critical, warning, suggestion)
+5. Fix all issues after reporting them
+
+## Step 1: Gather All Files
+
+Read **every** file for the connector — do not skip any:
+
+```
+apps/sim/connectors/{service}/{service}.ts   # Connector implementation
+apps/sim/connectors/{service}/index.ts       # Barrel export
+apps/sim/connectors/registry.ts              # Connector registry entry
+apps/sim/connectors/types.ts                 # ConnectorConfig interface, ExternalDocument, etc.
+apps/sim/connectors/utils.ts                 # Shared utilities (computeContentHash, htmlToPlainText, etc.)
+apps/sim/lib/oauth/oauth.ts                  # OAUTH_PROVIDERS — single source of truth for scopes
+apps/sim/lib/oauth/utils.ts                  # getCanonicalScopesForProvider, getScopesForService, SCOPE_DESCRIPTIONS
+apps/sim/lib/oauth/types.ts                  # OAuthService union type
+apps/sim/components/icons.tsx                 # Icon definition for the service
+```
+
+If the connector uses selectors, also read:
+```
+apps/sim/hooks/selectors/registry.ts         # Selector key definitions
+apps/sim/hooks/selectors/types.ts            # SelectorKey union type
+apps/sim/lib/workflows/subblocks/context.ts  # SELECTOR_CONTEXT_FIELDS
+```
+
+## Step 2: Pull API Documentation
+
+Fetch the official API docs for the service. This is the **source of truth** for:
+- Endpoint URLs, HTTP methods, and auth headers
+- Required vs optional parameters
+- Parameter types and allowed values
+- Response shapes and field names
+- Pagination patterns (cursor, offset, next token)
+- Rate limits and error formats
+- OAuth scopes and their meanings
+
+Use Context7 (resolve-library-id → query-docs) or WebFetch to retrieve documentation. If both fail, note which claims are based on training knowledge vs verified docs.
+
+## Step 3: Validate API Endpoints
+
+For **every** API call in the connector (`listDocuments`, `getDocument`, `validateConfig`, and any helper functions), verify against the API docs:
+
+### URLs and Methods
+- [ ] Base URL is correct for the service's API version
+- [ ] Endpoint paths match the API docs exactly
+- [ ] HTTP method is correct (GET, POST, PUT, PATCH, DELETE)
+- [ ] Path parameters are correctly interpolated and URI-encoded where needed
+- [ ] Query parameters use correct names and formats per the API docs
+
+### Headers
+- [ ] Authorization header uses the correct format:
+  - OAuth: `Authorization: Bearer ${accessToken}`
+  - API Key: correct header name per the service's docs
+- [ ] `Content-Type` is set for POST/PUT/PATCH requests
+- [ ] Any service-specific headers are present (e.g., `Notion-Version`, `Dropbox-API-Arg`)
+- [ ] No headers are sent that the API doesn't support or silently ignores
+
+### Request Bodies
+- [ ] POST/PUT body fields match API parameter names exactly
+- [ ] Required fields are always sent
+- [ ] Optional fields are conditionally included (not sent as `null` or empty unless the API expects that)
+- [ ] Field value types match API expectations (string vs number vs boolean)
+
+### Input Sanitization
+- [ ] User-controlled values interpolated into query strings are properly escaped:
+  - OData `$filter`: single quotes escaped with `''` (e.g., `externalId.replace(/'/g, "''")`)
+  - SOQL: single quotes escaped with `\'`
+  - GraphQL variables: passed as variables, not interpolated into query strings
+  - URL path segments: `encodeURIComponent()` applied
+- [ ] URL-type config fields (e.g., `siteUrl`, `instanceUrl`) are normalized:
+  - Strip `https://` / `http://` prefix if the API expects bare domains
+  - Strip trailing `/`
+  - Apply `.trim()` before validation
+
+### Response Parsing
+- [ ] Response structure is correctly traversed (e.g., `data.results` vs `data.items` vs `data`)
+- [ ] Field names extracted match what the API actually returns
+- [ ] Nullable fields are handled with `?? null` or `|| undefined`
+- [ ] Error responses are checked before accessing data fields
+
+## Step 4: Validate OAuth Scopes (if OAuth connector)
+
+Scopes must be correctly declared and sufficient for all API calls the connector makes.
+
+### Connector requiredScopes
+- [ ] `requiredScopes` in the connector's `auth` config lists all scopes needed by the connector
+- [ ] Each scope in `requiredScopes` is a real, valid scope recognized by the service's API
+- [ ] No invalid, deprecated, or made-up scopes are listed
+- [ ] No unnecessary excess scopes beyond what the connector actually needs
+
+### Scope Subset Validation (CRITICAL)
+- [ ] Every scope in `requiredScopes` exists in the OAuth provider's `scopes` array in `lib/oauth/oauth.ts`
+- [ ] Find the provider in `OAUTH_PROVIDERS[providerGroup].services[serviceId].scopes`
+- [ ] Verify: `requiredScopes` ⊆ `OAUTH_PROVIDERS scopes` (every required scope is present in the provider config)
+- [ ] If a required scope is NOT in the provider config, flag as **critical** — the connector will fail at runtime
+
+### Scope Sufficiency
+For each API endpoint the connector calls:
+- [ ] Identify which scopes are required per the API docs
+- [ ] Verify those scopes are included in the connector's `requiredScopes`
+- [ ] If the connector calls endpoints requiring scopes not in `requiredScopes`, flag as **warning**
+
+### Token Refresh Config
+- [ ] Check the `getOAuthTokenRefreshConfig` function in `lib/oauth/oauth.ts` for this provider
+- [ ] `useBasicAuth` matches the service's token exchange requirements
+- [ ] `supportsRefreshTokenRotation` matches whether the service issues rotating refresh tokens
+- [ ] Token endpoint URL is correct
+
+## Step 5: Validate Pagination
+
+### listDocuments Pagination
+- [ ] Cursor/pagination parameter name matches the API docs
+- [ ] Response pagination field is correctly extracted (e.g., `next_cursor`, `nextPageToken`, `@odata.nextLink`, `offset`)
+- [ ] `hasMore` is correctly determined from the response
+- [ ] `nextCursor` is correctly passed back for the next page
+- [ ] `maxItems` / `maxRecords` cap is correctly applied across pages using `syncContext.totalDocsFetched`
+- [ ] Page size is within the API's allowed range (not exceeding max page size)
+- [ ] Last page precision: when a `maxItems` cap exists, the final page request uses `Math.min(PAGE_SIZE, remaining)` to avoid fetching more records than needed
+- [ ] No off-by-one errors in pagination tracking
+- [ ] The connector does NOT hit known API pagination limits silently (e.g., HubSpot search 10k cap)
+
+### Pagination State Across Pages
+- [ ] `syncContext` is used to cache state across pages (user names, field maps, instance URLs, portal IDs, etc.)
+- [ ] Cached state in `syncContext` is correctly initialized on first page and reused on subsequent pages
+
+## Step 6: Validate Data Transformation
+
+### ExternalDocument Construction
+- [ ] `externalId` is a stable, unique identifier from the source API
+- [ ] `title` is extracted from the correct field and has a sensible fallback (e.g., `'Untitled'`)
+- [ ] `content` is plain text — HTML content is stripped using `htmlToPlainText` from `@/connectors/utils`
+- [ ] `mimeType` is `'text/plain'`
+- [ ] `contentHash` is computed using `computeContentHash` from `@/connectors/utils`
+- [ ] `sourceUrl` is a valid, complete URL back to the original resource (not relative)
+- [ ] `metadata` contains all fields referenced by `mapTags` and `tagDefinitions`
+
+### Content Extraction
+- [ ] Rich text / HTML fields are converted to plain text before indexing
+- [ ] Important content is not silently dropped (e.g., nested blocks, table cells, code blocks)
+- [ ] Content is not silently truncated without logging a warning
+- [ ] Empty/blank documents are properly filtered out
+- [ ] Size checks use `Buffer.byteLength(text, 'utf8')` not `text.length` when comparing against byte-based limits (e.g., `MAX_FILE_SIZE` in bytes)
+
+## Step 7: Validate Tag Definitions and mapTags
+
+### tagDefinitions
+- [ ] Each `tagDefinition` has an `id`, `displayName`, and `fieldType`
+- [ ] `fieldType` matches the actual data type: `'text'` for strings, `'number'` for numbers, `'date'` for dates, `'boolean'` for booleans
+- [ ] Every `id` in `tagDefinitions` is returned by `mapTags`
+- [ ] No `tagDefinition` references a field that `mapTags` never produces
+
+### mapTags
+- [ ] Return keys match `tagDefinition` `id` values exactly
+- [ ] Date values are properly parsed using `parseTagDate` from `@/connectors/utils`
+- [ ] Array values are properly joined using `joinTagArray` from `@/connectors/utils`
+- [ ] Number values are validated (not `NaN`)
+- [ ] Metadata field names accessed in `mapTags` match what `listDocuments`/`getDocument` store in `metadata`
+
+## Step 8: Validate Config Fields and Validation
+
+### configFields
+- [ ] Every field has `id`, `title`, `type`
+- [ ] `required` is set explicitly (not omitted)
+- [ ] Dropdown fields have `options` with `label` and `id` for each option
+- [ ] Selector fields follow the canonical pair pattern:
+  - A `type: 'selector'` field with `selectorKey`, `canonicalParamId`, `mode: 'basic'`
+  - A `type: 'short-input'` field with the same `canonicalParamId`, `mode: 'advanced'`
+  - `required` is identical on both fields in the pair
+- [ ] `selectorKey` values exist in the selector registry
+- [ ] `dependsOn` references selector field `id` values, not `canonicalParamId`
+
+### validateConfig
+- [ ] Validates all required fields are present before making API calls
+- [ ] Validates optional numeric fields (checks `Number.isNaN`, positive values)
+- [ ] Makes a lightweight API call to verify access (e.g., fetch 1 record, get profile)
+- [ ] Uses `VALIDATE_RETRY_OPTIONS` for retry budget
+- [ ] Returns `{ valid: true }` on success
+- [ ] Returns `{ valid: false, error: 'descriptive message' }` on failure
+- [ ] Catches exceptions and returns user-friendly error messages
+- [ ] Does NOT make expensive calls (full data listing, large queries)
+
+## Step 9: Validate getDocument
+
+- [ ] Fetches a single document by `externalId`
+- [ ] Returns `null` for 404 / not found (does not throw)
+- [ ] Returns the same `ExternalDocument` shape as `listDocuments`
+- [ ] Handles all content types that `listDocuments` can produce (e.g., if `listDocuments` returns both pages and blogposts, `getDocument` must handle both — not hardcode one endpoint)
+- [ ] Forwards `syncContext` if it needs cached state (user names, field maps, etc.)
+- [ ] Error handling is graceful (catches, logs, returns null or throws with context)
+- [ ] Does not redundantly re-fetch data already included in the initial API response (e.g., if comments come back with the post, don't fetch them again separately)
+
+## Step 10: Validate General Quality
+
+### fetchWithRetry Usage
+- [ ] All external API calls use `fetchWithRetry` from `@/lib/knowledge/documents/utils`
+- [ ] No raw `fetch()` calls to external APIs
+- [ ] `VALIDATE_RETRY_OPTIONS` used in `validateConfig`
+- [ ] If `validateConfig` calls a shared helper (e.g., `linearGraphQL`, `resolveId`), that helper must accept and forward `retryOptions` to `fetchWithRetry`
+- [ ] Default retry options used in `listDocuments`/`getDocument`
+
+### API Efficiency
+- [ ] APIs that support field selection (e.g., `$select`, `sysparm_fields`, `fields`) should request only the fields the connector needs — in both `listDocuments` AND `getDocument`
+- [ ] No redundant API calls: if a helper already fetches data (e.g., site metadata), callers should reuse the result instead of making a second call for the same information
+- [ ] Sequential per-item API calls (fetching details for each document in a loop) should be batched with `Promise.all` and a concurrency limit of 3-5
+
+### Error Handling
+- [ ] Individual document failures are caught and logged without aborting the sync
+- [ ] API error responses include status codes in error messages
+- [ ] No unhandled promise rejections in concurrent operations
+
+### Concurrency
+- [ ] Concurrent API calls use reasonable batch sizes (3-5 is typical)
+- [ ] No unbounded `Promise.all` over large arrays
+
+### Logging
+- [ ] Uses `createLogger` from `@sim/logger` (not `console.log`)
+- [ ] Logs sync progress at `info` level
+- [ ] Logs errors at `warn` or `error` level with context
+
+### Registry
+- [ ] Connector is exported from `connectors/{service}/index.ts`
+- [ ] Connector is registered in `connectors/registry.ts`
+- [ ] Registry key matches the connector's `id` field
+
+## Step 11: Report and Fix
+
+### Report Format
+
+Group findings by severity:
+
+**Critical** (will cause runtime errors, data loss, or auth failures):
+- Wrong API endpoint URL or HTTP method
+- Invalid or missing OAuth scopes (not in provider config)
+- Incorrect response field mapping (accessing wrong path)
+- SOQL/query fields that don't exist on the target object
+- Pagination that silently hits undocumented API limits
+- Missing error handling that would crash the sync
+- `requiredScopes` not a subset of OAuth provider scopes
+- Query/filter injection: user-controlled values interpolated into OData `$filter`, SOQL, or query strings without escaping
+
+**Warning** (incorrect behavior, data quality issues, or convention violations):
+- HTML content not stripped via `htmlToPlainText`
+- `getDocument` not forwarding `syncContext`
+- `getDocument` hardcoded to one content type when `listDocuments` returns multiple (e.g., only pages but not blogposts)
+- Missing `tagDefinition` for metadata fields returned by `mapTags`
+- Incorrect `useBasicAuth` or `supportsRefreshTokenRotation` in token refresh config
+- Invalid scope names that the API doesn't recognize (even if silently ignored)
+- Private resources excluded from name-based lookup despite scopes being available
+- Silent data truncation without logging
+- Size checks using `text.length` (character count) instead of `Buffer.byteLength` (byte count) for byte-based limits
+- URL-type config fields not normalized (protocol prefix, trailing slashes cause API failures)
+- `VALIDATE_RETRY_OPTIONS` not threaded through helper functions called by `validateConfig`
+
+**Suggestion** (minor improvements):
+- Missing incremental sync support despite API supporting it
+- Overly broad scopes that could be narrowed (not wrong, but could be tighter)
+- Source URL format could be more specific
+- Missing `orderBy` for deterministic pagination
+- Redundant API calls that could be cached in `syncContext`
+- Sequential per-item API calls that could be batched with `Promise.all` (concurrency 3-5)
+- API supports field selection but connector fetches all fields (e.g., missing `$select`, `sysparm_fields`, `fields`)
+- `getDocument` re-fetches data already included in the initial API response (e.g., comments returned with post)
+- Last page of pagination requests full `PAGE_SIZE` when fewer records remain (`Math.min(PAGE_SIZE, remaining)`)
+
+### Fix All Issues
+
+After reporting, fix every **critical** and **warning** issue. Apply **suggestions** where they don't add unnecessary complexity.
+
+### Validation Output
+
+After fixing, confirm:
+1. `bun run lint` passes
+2. TypeScript compiles clean
+3. Re-read all modified files to verify fixes are correct
+
+## Checklist Summary
+
+- [ ] Read connector implementation, types, utils, registry, and OAuth config
+- [ ] Pulled and read official API documentation for the service
+- [ ] Validated every API endpoint URL, method, headers, and body against API docs
+- [ ] Validated input sanitization: no query/filter injection, URL fields normalized
+- [ ] Validated OAuth scopes: `requiredScopes` ⊆ OAuth provider `scopes` in `oauth.ts`
+- [ ] Validated each scope is real and recognized by the service's API
+- [ ] Validated scopes are sufficient for all API endpoints the connector calls
+- [ ] Validated token refresh config (`useBasicAuth`, `supportsRefreshTokenRotation`)
+- [ ] Validated pagination: cursor names, page sizes, hasMore logic, no silent caps
+- [ ] Validated data transformation: plain text extraction, HTML stripping, content hashing
+- [ ] Validated tag definitions match mapTags output, correct fieldTypes
+- [ ] Validated config fields: canonical pairs, selector keys, required flags
+- [ ] Validated validateConfig: lightweight check, error messages, retry options
+- [ ] Validated getDocument: null on 404, all content types handled, no redundant re-fetches, syncContext forwarding
+- [ ] Validated fetchWithRetry used for all external calls (no raw fetch), VALIDATE_RETRY_OPTIONS threaded through helpers
+- [ ] Validated API efficiency: field selection used, no redundant calls, sequential fetches batched
+- [ ] Validated error handling: graceful failures, no unhandled rejections
+- [ ] Validated logging: createLogger, no console.log
+- [ ] Validated registry: correct export, correct key
+- [ ] Reported all issues grouped by severity
+- [ ] Fixed all critical and warning issues
+- [ ] Ran `bun run lint` after fixes
+- [ ] Verified TypeScript compiles clean
--- a/.cursor/commands/validate-integration.md
+++ b/.cursor/commands/validate-integration.md
@@ -0,0 +1,284 @@
+# Validate Integration Skill
+
+You are an expert auditor for Sim integrations. Your job is to thoroughly validate that an existing integration is correct, complete, and follows all conventions.
+
+## Your Task
+
+When the user asks you to validate an integration:
+1. Read the service's API documentation (via WebFetch or Context7)
+2. Read every tool, the block, and registry entries
+3. Cross-reference everything against the API docs and Sim conventions
+4. Report all issues found, grouped by severity (critical, warning, suggestion)
+5. Fix all issues after reporting them
+
+## Step 1: Gather All Files
+
+Read **every** file for the integration — do not skip any:
+
+```
+apps/sim/tools/{service}/          # All tool files, types.ts, index.ts
+apps/sim/blocks/blocks/{service}.ts # Block definition
+apps/sim/tools/registry.ts          # Tool registry entries for this service
+apps/sim/blocks/registry.ts         # Block registry entry for this service
+apps/sim/components/icons.tsx        # Icon definition
+apps/sim/lib/auth/auth.ts           # OAuth config — should use getCanonicalScopesForProvider()
+apps/sim/lib/oauth/oauth.ts         # OAuth provider config — single source of truth for scopes
+apps/sim/lib/oauth/utils.ts               # Scope utilities, SCOPE_DESCRIPTIONS for modal UI
+```
+
+## Step 2: Pull API Documentation
+
+Fetch the official API docs for the service. This is the **source of truth** for:
+- Endpoint URLs, HTTP methods, and auth headers
+- Required vs optional parameters
+- Parameter types and allowed values
+- Response shapes and field names
+- Pagination patterns (which param name, which response field)
+- Rate limits and error formats
+
+## Step 3: Validate Tools
+
+For **every** tool file, check:
+
+### Tool ID and Naming
+- [ ] Tool ID uses `snake_case`: `{service}_{action}` (e.g., `x_create_tweet`, `slack_send_message`)
+- [ ] Tool `name` is human-readable (e.g., `'X Create Tweet'`)
+- [ ] Tool `description` is a concise one-liner describing what it does
+- [ ] Tool `version` is set (`'1.0.0'` or `'2.0.0'` for V2)
+
+### Params
+- [ ] All required API params are marked `required: true`
+- [ ] All optional API params are marked `required: false`
+- [ ] Every param has explicit `required: true` or `required: false` — never omitted
+- [ ] Param types match the API (`'string'`, `'number'`, `'boolean'`, `'json'`)
+- [ ] Visibility is correct:
+  - `'hidden'` — ONLY for OAuth access tokens and system-injected params
+  - `'user-only'` — for API keys, credentials, and account-specific IDs the user must provide
+  - `'user-or-llm'` — for everything else (search queries, content, filters, IDs that could come from other blocks)
+- [ ] Every param has a `description` that explains what it does
+
+### Request
+- [ ] URL matches the API endpoint exactly (correct base URL, path segments, path params)
+- [ ] HTTP method matches the API spec (GET, POST, PUT, PATCH, DELETE)
+- [ ] Headers include correct auth pattern:
+  - OAuth: `Authorization: Bearer ${params.accessToken}`
+  - API Key: correct header name and format per the service's docs
+- [ ] `Content-Type` header is set for POST/PUT/PATCH requests
+- [ ] Body sends all required fields and only includes optional fields when provided
+- [ ] For GET requests with query params: URL is constructed correctly with query string
+- [ ] ID fields in URL paths are `.trim()`-ed to prevent copy-paste whitespace errors
+- [ ] Path params use template literals correctly: `` `https://api.service.com/v1/${params.id.trim()}` ``
+
+### Response / transformResponse
+- [ ] Correctly parses the API response (`await response.json()`)
+- [ ] Extracts the right fields from the response structure (e.g., `data.data` vs `data` vs `data.results`)
+- [ ] All nullable fields use `?? null`
+- [ ] All optional arrays use `?? []`
+- [ ] Error cases are handled: checks for missing/empty data and returns meaningful error
+- [ ] Does NOT do raw JSON dumps — extracts meaningful, individual fields
+
+### Outputs
+- [ ] All output fields match what the API actually returns
+- [ ] No fields are missing that the API provides and users would commonly need
+- [ ] No phantom fields defined that the API doesn't return
+- [ ] `optional: true` is set on fields that may not exist in all responses
+- [ ] When using `type: 'json'` and the shape is known, `properties` defines the inner fields
+- [ ] When using `type: 'array'`, `items` defines the item structure with `properties`
+- [ ] Field descriptions are accurate and helpful
+
+### Types (types.ts)
+- [ ] Has param interfaces for every tool (e.g., `XCreateTweetParams`)
+- [ ] Has response interfaces for every tool (extending `ToolResponse`)
+- [ ] Optional params use `?` in the interface (e.g., `replyTo?: string`)
+- [ ] Field names in types match actual API field names
+- [ ] Shared response types are properly reused (e.g., `XTweetResponse` shared across tweet tools)
+
+### Barrel Export (index.ts)
+- [ ] Every tool is exported
+- [ ] All types are re-exported (`export * from './types'`)
+- [ ] No orphaned exports (tools that don't exist)
+
+### Tool Registry (tools/registry.ts)
+- [ ] Every tool is imported and registered
+- [ ] Registry keys use snake_case and match tool IDs exactly
+- [ ] Entries are in alphabetical order within the file
+
+## Step 4: Validate Block
+
+### Block ↔ Tool Alignment (CRITICAL)
+
+This is the most important validation — the block must be perfectly aligned with every tool it references.
+
+For **each tool** in `tools.access`:
+- [ ] The operation dropdown has an option whose ID matches the tool ID (or the `tools.config.tool` function correctly maps to it)
+- [ ] Every **required** tool param (except `accessToken`) has a corresponding subBlock input that is:
+  - Shown when that operation is selected (correct `condition`)
+  - Marked as `required: true` (or conditionally required)
+- [ ] Every **optional** tool param has a corresponding subBlock input (or is intentionally omitted if truly never needed)
+- [ ] SubBlock `id` values are unique across the entire block — no duplicates even across different conditions
+- [ ] The `tools.config.tool` function returns the correct tool ID for every possible operation value
+- [ ] The `tools.config.params` function correctly maps subBlock IDs to tool param names when they differ
+
+### SubBlocks
+- [ ] Operation dropdown lists ALL tool operations available in `tools.access`
+- [ ] Dropdown option labels are human-readable and descriptive
+- [ ] Conditions use correct syntax:
+  - Single value: `{ field: 'operation', value: 'x_create_tweet' }`
+  - Multiple values (OR): `{ field: 'operation', value: ['x_create_tweet', 'x_delete_tweet'] }`
+  - Negation: `{ field: 'operation', value: 'delete', not: true }`
+  - Compound: `{ field: 'op', value: 'send', and: { field: 'type', value: 'dm' } }`
+- [ ] Condition arrays include ALL operations that use that field — none missing
+- [ ] `dependsOn` is set for fields that need other values (selectors depending on credential, cascading dropdowns)
+- [ ] SubBlock types match tool param types:
+  - Enum/fixed options → `dropdown`
+  - Free text → `short-input`
+  - Long text/content → `long-input`
+  - True/false → `dropdown` with Yes/No options (not `switch` unless purely UI toggle)
+  - Credentials → `oauth-input` with correct `serviceId`
+- [ ] Dropdown `value: () => 'default'` is set for dropdowns with a sensible default
+
+### Advanced Mode
+- [ ] Optional, rarely-used fields are set to `mode: 'advanced'`:
+  - Pagination tokens / next tokens
+  - Time range filters (start/end time)
+  - Sort order / direction options
+  - Max results / per page limits
+  - Reply settings / threading options
+  - Rarely used IDs (reply-to, quote-tweet, etc.)
+  - Exclude filters
+- [ ] **Required** fields are NEVER set to `mode: 'advanced'`
+- [ ] Fields that users fill in most of the time are NOT set to `mode: 'advanced'`
+
+### WandConfig
+- [ ] Timestamp fields have `wandConfig` with `generationType: 'timestamp'`
+- [ ] Comma-separated list fields have `wandConfig` with a descriptive prompt
+- [ ] Complex filter/query fields have `wandConfig` with format examples in the prompt
+- [ ] All `wandConfig` prompts end with "Return ONLY the [format] - no explanations, no extra text."
+- [ ] `wandConfig.placeholder` describes what to type in natural language
+
+### Tools Config
+- [ ] `tools.access` lists **every** tool ID the block can use — none missing
+- [ ] `tools.config.tool` returns the correct tool ID for each operation
+- [ ] Type coercions are in `tools.config.params` (runs at execution time), NOT in `tools.config.tool` (runs at serialization time before variable resolution)
+- [ ] `tools.config.params` handles:
+  - `Number()` conversion for numeric params that come as strings from inputs
+  - `Boolean` / string-to-boolean conversion for toggle params
+  - Empty string → `undefined` conversion for optional dropdown values
+  - Any subBlock ID → tool param name remapping
+- [ ] No `Number()`, `JSON.parse()`, or other coercions in `tools.config.tool` — these would destroy dynamic references like `<Block.output>`
+
+### Block Outputs
+- [ ] Outputs cover the key fields returned by ALL tools (not just one operation)
+- [ ] Output types are correct (`'string'`, `'number'`, `'boolean'`, `'json'`)
+- [ ] `type: 'json'` outputs either:
+  - Describe inner fields in the description string (GOOD): `'User profile (id, name, username, bio)'`
+  - Use nested output definitions (BEST): `{ id: { type: 'string' }, name: { type: 'string' } }`
+- [ ] No opaque `type: 'json'` with vague descriptions like `'Response data'`
+- [ ] Outputs that only appear for certain operations use `condition` if supported, or document which operations return them
+
+### Block Metadata
+- [ ] `type` is snake_case (e.g., `'x'`, `'cloudflare'`)
+- [ ] `name` is human-readable (e.g., `'X'`, `'Cloudflare'`)
+- [ ] `description` is a concise one-liner
+- [ ] `longDescription` provides detail for docs
+- [ ] `docsLink` points to `'https://docs.sim.ai/tools/{service}'`
+- [ ] `category` is `'tools'`
+- [ ] `bgColor` uses the service's brand color hex
+- [ ] `icon` references the correct icon component from `@/components/icons`
+- [ ] `authMode` is set correctly (`AuthMode.OAuth` or `AuthMode.ApiKey`)
+- [ ] Block is registered in `blocks/registry.ts` alphabetically
+
+### Block Inputs
+- [ ] `inputs` section lists all subBlock params that the block accepts
+- [ ] Input types match the subBlock types
+- [ ] When using `canonicalParamId`, inputs list the canonical ID (not the raw subBlock IDs)
+
+## Step 5: Validate OAuth Scopes (if OAuth service)
+
+Scopes are centralized — the single source of truth is `OAUTH_PROVIDERS` in `lib/oauth/oauth.ts`.
+
+- [ ] Scopes defined in `lib/oauth/oauth.ts` under `OAUTH_PROVIDERS[provider].services[service].scopes`
+- [ ] `auth.ts` uses `getCanonicalScopesForProvider(providerId)` — NOT a hardcoded array
+- [ ] Block `requiredScopes` uses `getScopesForService(serviceId)` — NOT a hardcoded array
+- [ ] No hardcoded scope arrays in `auth.ts` or block files (should all use utility functions)
+- [ ] Each scope has a human-readable description in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts`
+- [ ] No excess scopes that aren't needed by any tool
+
+## Step 6: Validate Pagination Consistency
+
+If any tools support pagination:
+- [ ] Pagination param names match the API docs (e.g., `pagination_token` vs `next_token` vs `cursor`)
+- [ ] Different API endpoints that use different pagination param names have separate subBlocks in the block
+- [ ] Pagination response fields (`nextToken`, `cursor`, etc.) are included in tool outputs
+- [ ] Pagination subBlocks are set to `mode: 'advanced'`
+
+## Step 7: Validate Error Handling
+
+- [ ] `transformResponse` checks for error conditions before accessing data
+- [ ] Error responses include meaningful messages (not just generic "failed")
+- [ ] HTTP error status codes are handled (check `response.ok` or status codes)
+
+## Step 8: Report and Fix
+
+### Report Format
+
+Group findings by severity:
+
+**Critical** (will cause runtime errors or incorrect behavior):
+- Wrong endpoint URL or HTTP method
+- Missing required params or wrong `required` flag
+- Incorrect response field mapping (accessing wrong path in response)
+- Missing error handling that would cause crashes
+- Tool ID mismatch between tool file, registry, and block `tools.access`
+- OAuth scopes missing in `auth.ts` that tools need
+- `tools.config.tool` returning wrong tool ID for an operation
+- Type coercions in `tools.config.tool` instead of `tools.config.params`
+
+**Warning** (follows conventions incorrectly or has usability issues):
+- Optional field not set to `mode: 'advanced'`
+- Missing `wandConfig` on timestamp/complex fields
+- Wrong `visibility` on params (e.g., `'hidden'` instead of `'user-or-llm'`)
+- Missing `optional: true` on nullable outputs
+- Opaque `type: 'json'` without property descriptions
+- Missing `.trim()` on ID fields in request URLs
+- Missing `?? null` on nullable response fields
+- Block condition array missing an operation that uses that field
+- Hardcoded scope arrays instead of using `getScopesForService()` / `getCanonicalScopesForProvider()`
+- Missing scope description in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts`
+
+**Suggestion** (minor improvements):
+- Better description text
+- Inconsistent naming across tools
+- Missing `longDescription` or `docsLink`
+- Pagination fields that could benefit from `wandConfig`
+
+### Fix All Issues
+
+After reporting, fix every **critical** and **warning** issue. Apply **suggestions** where they don't add unnecessary complexity.
+
+### Validation Output
+
+After fixing, confirm:
+1. `bun run lint` passes with no fixes needed
+2. TypeScript compiles clean (no type errors)
+3. Re-read all modified files to verify fixes are correct
+
+## Checklist Summary
+
+- [ ] Read ALL tool files, block, types, index, and registries
+- [ ] Pulled and read official API documentation
+- [ ] Validated every tool's ID, params, request, response, outputs, and types against API docs
+- [ ] Validated block ↔ tool alignment (every tool param has a subBlock, every condition is correct)
+- [ ] Validated advanced mode on optional/rarely-used fields
+- [ ] Validated wandConfig on timestamps and complex inputs
+- [ ] Validated tools.config mapping, tool selector, and type coercions
+- [ ] Validated block outputs match what tools return, with typed JSON where possible
+- [ ] Validated OAuth scopes use centralized utilities (getScopesForService, getCanonicalScopesForProvider) — no hardcoded arrays
+- [ ] Validated scope descriptions exist in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts` for all scopes
+- [ ] Validated pagination consistency across tools and block
+- [ ] Validated error handling (error checks, meaningful messages)
+- [ ] Validated registry entries (tools and block, alphabetical, correct imports)
+- [ ] Reported all issues grouped by severity
+- [ ] Fixed all critical and warning issues
+- [ ] Ran `bun run lint` after fixes
+- [ ] Verified TypeScript compiles clean
--- a/.cursor/commands/validate-trigger.md
+++ b/.cursor/commands/validate-trigger.md
@@ -0,0 +1,207 @@
+# Validate Trigger
+
+You are an expert auditor for Sim webhook triggers. Your job is to validate that an existing trigger implementation is correct, complete, secure, and aligned across all layers.
+
+## Your Task
+
+1. Read the service's webhook/API documentation (via WebFetch)
+2. Read every trigger file, provider handler, and registry entry
+3. Cross-reference against the API docs and Sim conventions
+4. Report all issues grouped by severity (critical, warning, suggestion)
+5. Fix all issues after reporting them
+
+## Step 1: Gather All Files
+
+Read **every** file for the trigger — do not skip any:
+
+```
+apps/sim/triggers/{service}/           # All trigger files, utils.ts, index.ts
+apps/sim/lib/webhooks/providers/{service}.ts  # Provider handler (if exists)
+apps/sim/lib/webhooks/providers/registry.ts   # Handler registry
+apps/sim/triggers/registry.ts                 # Trigger registry
+apps/sim/blocks/blocks/{service}.ts           # Block definition (trigger wiring)
+```
+
+Also read for reference:
+```
+apps/sim/lib/webhooks/providers/types.ts            # WebhookProviderHandler interface
+apps/sim/lib/webhooks/providers/utils.ts            # Shared helpers (createHmacVerifier, etc.)
+apps/sim/lib/webhooks/provider-subscription-utils.ts    # Subscription helpers
+apps/sim/lib/webhooks/processor.ts                  # Central webhook processor
+```
+
+## Step 2: Pull API Documentation
+
+Fetch the service's official webhook documentation. This is the **source of truth** for:
+- Webhook event types and payload shapes
+- Signature/auth verification method (HMAC algorithm, header names, secret format)
+- Challenge/verification handshake requirements
+- Webhook subscription API (create/delete endpoints, if applicable)
+- Retry behavior and delivery guarantees
+
+## Step 3: Validate Trigger Definitions
+
+### utils.ts
+- [ ] `{service}TriggerOptions` lists all trigger IDs accurately
+- [ ] `{service}SetupInstructions` provides clear, correct steps for the service
+- [ ] `build{Service}ExtraFields` includes relevant filter/config fields with correct `condition`
+- [ ] Output builders expose all meaningful fields from the webhook payload
+- [ ] Output builders do NOT use `optional: true` or `items` (tool-output-only features)
+- [ ] Nested output objects correctly model the payload structure
+
+### Trigger Files
+- [ ] Exactly one primary trigger has `includeDropdown: true`
+- [ ] All secondary triggers do NOT have `includeDropdown`
+- [ ] All triggers use `buildTriggerSubBlocks` helper (not hand-rolled subBlocks)
+- [ ] Every trigger's `id` matches the convention `{service}_{event_name}`
+- [ ] Every trigger's `provider` matches the service name used in the handler registry
+- [ ] `index.ts` barrel exports all triggers
+
+### Trigger ↔ Provider Alignment (CRITICAL)
+- [ ] Every trigger ID referenced in `matchEvent` logic exists in `{service}TriggerOptions`
+- [ ] Event matching logic in the provider correctly maps trigger IDs to service event types
+- [ ] Event matching logic in `is{Service}EventMatch` (if exists) correctly identifies events per the API docs
+
+## Step 4: Validate Provider Handler
+
+### Auth Verification
+- [ ] `verifyAuth` correctly validates webhook signatures per the service's documentation
+- [ ] HMAC algorithm matches (SHA-1, SHA-256, SHA-512)
+- [ ] Signature header name matches the API docs exactly
+- [ ] Signature format is handled (raw hex, `sha256=` prefix, base64, etc.)
+- [ ] Uses `safeCompare` for timing-safe comparison (no `===`)
+- [ ] If `webhookSecret` is required, handler rejects when it's missing (fail-closed)
+- [ ] Signature is computed over raw body (not parsed JSON)
+
+### Event Matching
+- [ ] `matchEvent` returns `boolean` (not `NextResponse` or other values)
+- [ ] Challenge/verification events are excluded from matching (e.g., `endpoint.url_validation`)
+- [ ] When `triggerId` is a generic webhook ID, all events pass through
+- [ ] When `triggerId` is specific, only matching events pass
+- [ ] Event matching logic uses dynamic `await import()` for trigger utils (avoids circular deps)
+
+### formatInput (CRITICAL)
+- [ ] Every key in the `formatInput` return matches a key in the trigger `outputs` schema
+- [ ] Every key in the trigger `outputs` schema is populated by `formatInput`
+- [ ] No extra undeclared keys that users can't discover in the UI
+- [ ] No wrapper objects (`webhook: { ... }`, `{service}: { ... }`)
+- [ ] Nested output paths exist at the correct depth (e.g., `resource.id` actually has `resource: { id: ... }`)
+- [ ] `null` is used for missing optional fields (not empty strings or empty objects)
+- [ ] Returns `{ input: { ... } }` — not a bare object
+
+### Idempotency
+- [ ] `extractIdempotencyId` returns a stable, unique key per delivery
+- [ ] Uses provider-specific delivery IDs when available (e.g., `X-Request-Id`, `Linear-Delivery`, `svix-id`)
+- [ ] Falls back to content-based ID (e.g., `${type}:${id}`) when no delivery header exists
+- [ ] Does NOT include timestamps in the idempotency key (would break dedup on retries)
+
+### Challenge Handling (if applicable)
+- [ ] `handleChallenge` correctly implements the service's URL verification handshake
+- [ ] Returns the expected response format per the API docs
+- [ ] Env-backed secrets are resolved via `resolveEnvVarsInObject` if needed
+
+## Step 5: Validate Automatic Subscription Lifecycle
+
+If the service supports programmatic webhook creation:
+
+### createSubscription
+- [ ] Calls the correct API endpoint to create a webhook
+- [ ] Sends the correct event types/filters
+- [ ] Passes the notification URL from `getNotificationUrl(ctx.webhook)`
+- [ ] Returns `{ providerConfigUpdates: { externalId } }` with the external webhook ID
+- [ ] Throws on failure (orchestration handles rollback)
+- [ ] Provides user-friendly error messages (401 → "Invalid API Key", etc.)
+
+### deleteSubscription
+- [ ] Calls the correct API endpoint to delete the webhook
+- [ ] Handles 404 gracefully (webhook already deleted)
+- [ ] Never throws — catches errors and logs non-fatally
+- [ ] Skips gracefully when `apiKey` or `externalId` is missing
+
+### Orchestration Isolation
+- [ ] NO provider-specific logic in `route.ts`, `provider-subscriptions.ts`, or `deploy.ts`
+- [ ] All subscription logic lives on the handler (`createSubscription`/`deleteSubscription`)
+
+## Step 6: Validate Registration and Block Wiring
+
+### Trigger Registry (`triggers/registry.ts`)
+- [ ] All triggers are imported and registered
+- [ ] Registry keys match trigger IDs exactly
+- [ ] No orphaned entries (triggers that don't exist)
+
+### Provider Handler Registry (`providers/registry.ts`)
+- [ ] Handler is imported and registered (if handler exists)
+- [ ] Registry key matches the `provider` field on the trigger configs
+- [ ] Entries are in alphabetical order
+
+### Block Wiring (`blocks/blocks/{service}.ts`)
+- [ ] Block has `triggers.enabled: true`
+- [ ] `triggers.available` lists all trigger IDs
+- [ ] All trigger subBlocks are spread into `subBlocks`: `...getTrigger('id').subBlocks`
+- [ ] No trigger IDs in `triggers.available` that aren't in the registry
+- [ ] No trigger subBlocks spread that aren't in `triggers.available`
+
+## Step 7: Validate Security
+
+- [ ] Webhook secrets are never logged (not even at debug level)
+- [ ] Auth verification runs before any event processing
+- [ ] No secret comparison uses `===` (must use `safeCompare` or `crypto.timingSafeEqual`)
+- [ ] Timestamp/replay protection is reasonable (not too tight for retries, not too loose for security)
+- [ ] Raw body is used for signature verification (not re-serialized JSON)
+
+## Step 8: Report and Fix
+
+### Report Format
+
+Group findings by severity:
+
+**Critical** (runtime errors, security issues, or data loss):
+- Wrong HMAC algorithm or header name
+- `formatInput` keys don't match trigger `outputs`
+- Missing `verifyAuth` when the service sends signed webhooks
+- `matchEvent` returns non-boolean values
+- Provider-specific logic leaking into shared orchestration files
+- Trigger IDs mismatch between trigger files, registry, and block
+- `createSubscription` calling wrong API endpoint
+- Auth comparison using `===` instead of `safeCompare`
+
+**Warning** (convention violations or usability issues):
+- Missing `extractIdempotencyId` when the service provides delivery IDs
+- Timestamps in idempotency keys (breaks dedup on retries)
+- Missing challenge handling when the service requires URL verification
+- Output schema missing fields that `formatInput` returns (undiscoverable data)
+- Overly tight timestamp skew window that rejects legitimate retries
+- `matchEvent` not filtering challenge/verification events
+- Setup instructions missing important steps
+
+**Suggestion** (minor improvements):
+- More specific output field descriptions
+- Additional output fields that could be exposed
+- Better error messages in `createSubscription`
+- Logging improvements
+
+### Fix All Issues
+
+After reporting, fix every **critical** and **warning** issue. Apply **suggestions** where they don't add unnecessary complexity.
+
+### Validation Output
+
+After fixing, confirm:
+1. `bun run type-check` passes
+2. Re-read all modified files to verify fixes are correct
+3. Provider handler tests pass (if they exist): `bun test {service}`
+
+## Checklist Summary
+
+- [ ] Read all trigger files, provider handler, types, registries, and block
+- [ ] Pulled and read official webhook/API documentation
+- [ ] Validated trigger definitions: options, instructions, extra fields, outputs
+- [ ] Validated primary/secondary trigger distinction (`includeDropdown`)
+- [ ] Validated provider handler: auth, matchEvent, formatInput, idempotency
+- [ ] Validated output alignment: every `outputs` key ↔ every `formatInput` key
+- [ ] Validated subscription lifecycle: createSubscription, deleteSubscription, no shared-file edits
+- [ ] Validated registration: trigger registry, handler registry, block wiring
+- [ ] Validated security: safe comparison, no secret logging, replay protection
+- [ ] Reported all issues grouped by severity
+- [ ] Fixed all critical and warning issues
+- [ ] `bun run type-check` passes after fixes
--- a/.cursor/commands/you-might-not-need-a-callback.md
+++ b/.cursor/commands/you-might-not-need-a-callback.md
@@ -0,0 +1,30 @@
+# You Might Not Need a Callback
+
+Arguments:
+- scope: what to analyze (default: your current changes). Examples: "diff to main", "PR #123", "src/components/", "whole codebase"
+- fix: whether to apply fixes (default: true). Set to false to only propose changes.
+
+User arguments: $ARGUMENTS
+
+## References
+
+Read before analyzing:
+1. https://react.dev/reference/react/useCallback — official docs on when useCallback is actually needed
+
+## Anti-patterns to detect
+
+1. **useCallback on functions not passed as props or deps**: No benefit if only called within the same component.
+2. **useCallback with deps that change every render**: Memoization is wasted.
+3. **useCallback on handlers passed to native elements**: `<button onClick={fn}>` doesn't benefit from stable references.
+4. **useCallback wrapping functions that return new objects/arrays**: Memoization at the wrong level.
+5. **useCallback with empty deps when deps are needed**: Stale closures.
+6. **Pairing useCallback + React.memo unnecessarily**: Only optimize when you've measured a problem.
+7. **useCallback in hooks that don't need stable references**: Not every hook return needs memoization.
+
+Note: This codebase uses a ref pattern for stable callbacks (`useRef` + empty deps). That pattern is correct — don't flag it.
+
+## Steps
+
+1. Read the reference above
+2. Analyze the specified scope for the anti-patterns listed above
+3. If fix=true, apply the fixes. If fix=false, propose the fixes without applying.
--- a/.cursor/commands/you-might-not-need-a-memo.md
+++ b/.cursor/commands/you-might-not-need-a-memo.md
@@ -0,0 +1,28 @@
+# You Might Not Need a Memo
+
+Arguments:
+- scope: what to analyze (default: your current changes). Examples: "diff to main", "PR #123", "src/components/", "whole codebase"
+- fix: whether to apply fixes (default: true). Set to false to only propose changes.
+
+User arguments: $ARGUMENTS
+
+## References
+
+Read before analyzing:
+1. https://overreacted.io/before-you-memo/ — two techniques to avoid memo entirely
+
+## Anti-patterns to detect
+
+1. **State can be moved down instead of memoizing**: Move state into a smaller child so the slow component stops re-rendering without memo.
+2. **Children can be lifted up**: Extract stateful part, pass expensive subtree as `children` — children as props don't re-render when parent state changes.
+3. **useMemo on cheap computations**: Small array filters, string concat, arithmetic don't need memoization.
+4. **useMemo with constantly-changing deps**: Deps change every render = useMemo does nothing.
+5. **useMemo to stabilize props for non-memoized children**: If the child isn't wrapped in React.memo, stable references don't matter.
+6. **React.memo on components that always receive new props**: Fix the parent instead.
+7. **useMemo for derived state**: Just compute inline during render.
+
+## Steps
+
+1. Read the reference above
+2. Analyze the specified scope for the anti-patterns listed above
+3. If fix=true, apply the fixes. If fix=false, propose the fixes without applying.
--- a/.cursor/commands/you-might-not-need-an-effect.md
+++ b/.cursor/commands/you-might-not-need-an-effect.md
@@ -0,0 +1,12 @@
+# You Might Not Need an Effect
+
+Arguments:
+- scope: what to analyze (default: your current changes). Examples: "diff to main", "PR #123", "src/components/", "whole codebase"
+- fix: whether to apply fixes (default: true). Set to false to only propose changes.
+
+User arguments: $ARGUMENTS
+
+Steps:
+1. Read https://react.dev/learn/you-might-not-need-an-effect to understand the guidelines
+2. Analyze the specified scope for useEffect anti-patterns
+3. If fix=true, apply the fixes. If fix=false, propose the fixes without applying.
--- a/.cursor/commands/you-might-not-need-state.md
+++ b/.cursor/commands/you-might-not-need-state.md
@@ -0,0 +1,33 @@
+# You Might Not Need State
+
+Arguments:
+- scope: what to analyze (default: your current changes). Examples: "diff to main", "PR #123", "src/components/", "whole codebase"
+- fix: whether to apply fixes (default: true). Set to false to only propose changes.
+
+User arguments: $ARGUMENTS
+
+## Context
+
+This codebase uses React Query for all server state and Zustand for client-only global state. useState should only be used for ephemeral UI concerns (open/closed, hover, local form input). Server data should never be copied into useState or Zustand — React Query is the single source of truth.
+
+## References
+
+Read these before analyzing:
+1. https://react.dev/learn/choosing-the-state-structure — 5 principles for structuring state
+2. https://tkdodo.eu/blog/dont-over-use-state — never store derived/computed values in state
+3. https://tkdodo.eu/blog/putting-props-to-use-state — never mirror props into state via useEffect
+
+## Anti-patterns to detect
+
+1. **Derived state stored in useState**: If a value can be computed from props, other state, or query data, compute it inline during render instead of storing it in state.
+2. **Server state copied into useState**: Never `useState` + `useEffect` to sync React Query data into local state. Use query data directly. The only exception is forms where users edit server data.
+3. **Props mirrored into state**: Never `useState(prop)` + `useEffect(() => setState(prop))`. Use the prop directly, or use a key to reset component state.
+4. **Chained useEffect state updates**: Never chain Effects that set state to trigger other Effects. Calculate all derived values in the event handler or inline during render.
+5. **Storing objects when an ID suffices**: Store `selectedId` not a copy of the selected object. Derive the object: `items.find(i => i.id === selectedId)`.
+6. **State that duplicates Zustand or React Query**: If the data already lives in a store or query cache, don't create a parallel useState.
+
+## Steps
+
+1. Read the references above to understand the guidelines
+2. Analyze the specified scope for the anti-patterns listed above
+3. If fix=true, apply the fixes. If fix=false, propose the fixes without applying.
--- a/.cursor/rules/constitution.mdc
+++ b/.cursor/rules/constitution.mdc
@@ -0,0 +1,76 @@
+---
+description: Sim product language, positioning, and tone guidelines
+globs: ["apps/sim/app/(landing)/**", "apps/sim/app/(home)/**", "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.
--- a/.cursor/rules/global.mdc
+++ b/.cursor/rules/global.mdc
@@ -16,5 +16,47 @@ 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)` — async delay. Never write `new Promise(resolve => setTimeout(resolve, ms))`
+- `toError(value)` — normalize unknown caught values to `Error`. Never write `e instanceof Error ? e : new Error(String(e))`
+- `toError(value).message` — get error message safely. Never write `e instanceof Error ? e.message : String(e)`
+
+```typescript
+// ✗ Bad
+await new Promise(resolve => setTimeout(resolve, 1000))
+const msg = error instanceof Error ? error.message : String(error)
+const err = error instanceof Error ? error : new Error(String(error))
+
+// ✓ Good
+import { sleep } from '@sim/utils/helpers'
+import { toError } from '@sim/utils/errors'
+await sleep(1000)
+const msg = toError(error).message
+const err = toError(error)
+```
+
 ## Package Manager
 Use `bun` and `bunx`, not `npm` and `npx`.
--- a/.cursor/rules/landing-seo-geo.mdc
+++ b/.cursor/rules/landing-seo-geo.mdc
@@ -0,0 +1,26 @@
+---
+description: SEO and GEO guidelines for the landing page
+globs: ["apps/sim/app/(home)/**/*.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 agents", "agentic workflows".
+- **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.
--- a/.cursor/rules/sim-queries.mdc
+++ b/.cursor/rules/sim-queries.mdc
@@ -5,62 +5,122 @@ globs: ["apps/sim/hooks/queries/**/*.ts"]

 # React Query Patterns

-All React Query hooks live in `hooks/queries/`.
+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 keys 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,
-  list: (workspaceId?: string) => [...entityKeys.all, 'list', workspaceId ?? ''] as const,
-  detail: (id?: string) => [...entityKeys.all, 'detail', id ?? ''] 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
+// 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
+
 ```typescript
+async function fetchEntities(workspaceId: string, signal?: AbortSignal) {
+  const response = await fetch(`/api/entities?workspaceId=${workspaceId}`, { signal })
+  if (!response.ok) throw new Error('Failed to fetch entities')
+  return response.json()
+}
+
 export function useEntityList(workspaceId?: string, options?: { enabled?: boolean }) {
  return useQuery({
    queryKey: entityKeys.list(workspaceId),
-    queryFn: () => fetchEntities(workspaceId as string),
+    queryFn: ({ signal }) => fetchEntities(workspaceId as string, signal),
    enabled: Boolean(workspaceId) && (options?.enabled ?? true),
    staleTime: 60 * 1000,
-    placeholderData: keepPreviousData,
+    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)
+
 ```typescript
 export function useCreateEntity() {
  const queryClient = useQueryClient()
  return useMutation({
    mutationFn: async (variables) => { /* fetch POST */ },
-    onSuccess: () => queryClient.invalidateQueries({ queryKey: entityKeys.all }),
+    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])
+```
+
 ## Naming

 - **Keys**: `entityKeys`
 - **Query hooks**: `useEntity`, `useEntityList`
- **Mutation hooks**: `useCreateEntity`, `useUpdateEntity`
- **Fetch functions**: `fetchEntity` (private)
+- **Mutation hooks**: `useCreateEntity`, `useUpdateEntity`, `useDeleteEntity`
+- **Fetch functions**: `fetchEntity`, `fetchEntities` (private)
--- a/.cursor/rules/sim-sandbox.mdc
+++ b/.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.
--- a/.cursor/rules/sim-testing.mdc
+++ b/.cursor/rules/sim-testing.mdc
@@ -3,55 +3,240 @@ 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`
+
 ## Structure

 ```typescript
 /**
 * @vitest-environment node
 */
-import { databaseMock, loggerMock } from '@sim/testing'
-import { describe, expect, it, vi } from 'vitest'
+import { createMockRequest } from '@sim/testing'
+import { beforeEach, describe, expect, it, vi } from 'vitest'

-vi.mock('@sim/db', () => databaseMock)
-vi.mock('@sim/logger', () => loggerMock)
+const { mockGetSession } = vi.hoisted(() => ({
+  mockGetSession: vi.fn(),
+}))

-import { myFunction } from '@/lib/feature'
+vi.mock('@/lib/auth', () => ({
+  auth: { api: { getSession: vi.fn() } },
+  getSession: mockGetSession,
+}))

-describe('myFunction', () => {
-  beforeEach(() => vi.clearAllMocks())
-  it.concurrent('isolated tests run in parallel', () => { ... })
+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)` |
+| `@/lib/audit/log` | `auditMock`, `auditMockFns` | `vi.mock('@/lib/audit/log', () => 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/feature-flags` | `featureFlagsMock` | `vi.mock('@/lib/core/config/feature-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
+
+```typescript
+const { mockSelect, mockFrom, mockWhere } = vi.hoisted(() => ({
+  mockSelect: vi.fn(),
+  mockFrom: vi.fn(),
+  mockWhere: vi.fn(),
+}))
+
+vi.mock('@sim/db', () => ({
+  db: { select: mockSelect },
+}))
+
+beforeEach(() => {
+  mockSelect.mockReturnValue({ from: mockFrom })
+  mockFrom.mockReturnValue({ where: mockWhere })
+  mockWhere.mockResolvedValue([{ id: '1', name: 'test' }])
 })
 ```

 ## @sim/testing Package

-Always prefer over local mocks.
+Always prefer over local test data.

 | Category | Utilities |
 |----------|-----------|
-| **Mocks** | `loggerMock`, `databaseMock`, `setupGlobalFetchMock()` |
-| **Factories** | `createSession()`, `createWorkflowRecord()`, `createBlock()`, `createExecutorContext()` |
+| **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
+## Rules Summary

-1. `@vitest-environment node` directive at file top
-2. `vi.mock()` calls before importing mocked modules
-3. `@sim/testing` utilities over local mocks
-4. `it.concurrent` for isolated tests (no shared mutable state)
-5. `beforeEach(() => vi.clearAllMocks())` to reset state
-
-## Hoisted Mocks
-
-For mutable mock references:
-
-```typescript
-const mockFn = vi.hoisted(() => vi.fn())
-vi.mock('@/lib/module', () => ({ myFunction: mockFn }))
-mockFn.mockResolvedValue({ data: 'test' })
-```
+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()`
--- a/.cursor/skills/add-hosted-key/SKILL.md
+++ b/.cursor/skills/add-hosted-key/SKILL.md
@@ -0,0 +1,296 @@
+---
+name: add-hosted-key
+description: Add hosted API key support to a tool so Sim provides the key when users don't bring their own. Use when adding hosted keys, BYOK support, hideWhenHosted, or hosted key pricing to a tool or block.
+---
+
+# Adding Hosted Key Support to a Tool
+
+When a tool has hosted key support, Sim provides its own API key if the user hasn't configured one (via BYOK or env var). Usage is metered and billed to the workspace.
+
+## Overview
+
+| Step | What | Where |
+|------|------|-------|
+| 1 | Register BYOK provider ID | `tools/types.ts`, `app/api/workspaces/[id]/byok-keys/route.ts` |
+| 2 | Research the API's pricing and rate limits | API docs / pricing page (before writing any code) |
+| 3 | Add `hosting` config to the tool | `tools/{service}/{action}.ts` |
+| 4 | Hide API key field when hosted | `blocks/blocks/{service}.ts` |
+| 5 | Add to BYOK settings UI | BYOK settings component (`byok.tsx`) |
+| 6 | Summarize pricing and throttling comparison | Output to user (after all code changes) |
+
+## Step 1: Register the BYOK Provider ID
+
+Add the new provider to the `BYOKProviderId` union in `tools/types.ts`:
+
+```typescript
+export type BYOKProviderId =
+  | 'openai'
+  | 'anthropic'
+  // ...existing providers
+  | 'your_service'
+```
+
+Then add it to `VALID_PROVIDERS` in `app/api/workspaces/[id]/byok-keys/route.ts`:
+
+```typescript
+const VALID_PROVIDERS = ['openai', 'anthropic', 'google', 'mistral', 'your_service'] as const
+```
+
+## Step 2: Research the API's Pricing Model and Rate Limits
+
+**Before writing any `getCost` or `rateLimit` code**, look up the service's official documentation for both pricing and rate limits. You need to understand:
+
+### Pricing
+
+1. **How the API charges** — per request, per credit, per token, per step, per minute, etc.
+2. **Whether the API reports cost in its response** — look for fields like `creditsUsed`, `costDollars`, `tokensUsed`, or similar in the response body or headers
+3. **Whether cost varies by endpoint/options** — some APIs charge more for certain features (e.g., Firecrawl charges 1 credit/page base but +4 for JSON format, +4 for enhanced mode)
+4. **The dollar-per-unit rate** — what each credit/token/unit costs in dollars on our plan
+
+### Rate Limits
+
+1. **What rate limits the API enforces** — requests per minute/second, tokens per minute, concurrent requests, etc.
+2. **Whether limits vary by plan tier** — free vs paid vs enterprise often have different ceilings
+3. **Whether limits are per-key or per-account** — determines whether adding more hosted keys actually increases total throughput
+4. **What the API returns when rate limited** — HTTP 429, `Retry-After` header, error body format, etc.
+5. **Whether there are multiple dimensions** — some APIs limit both requests/min AND tokens/min independently
+
+Search the API's docs/pricing page (use WebSearch/WebFetch). Capture the pricing model as a comment in `getCost` so future maintainers know the source of truth.
+
+### Setting Our Rate Limits
+
+Our rate limiter (`lib/core/rate-limiter/hosted-key/`) uses a token-bucket algorithm applied **per billing actor** (workspace). It supports two modes:
+
+- **`per_request`** — simple; just `requestsPerMinute`. Good when the API charges flat per-request or cost doesn't vary much.
+- **`custom`** — `requestsPerMinute` plus additional `dimensions` (e.g., `tokens`, `search_units`). Each dimension has its own `limitPerMinute` and an `extractUsage` function that reads actual usage from the response. Use when the API charges on a variable metric (tokens, credits) and you want to cap that metric too.
+
+When choosing values for `requestsPerMinute` and any dimension limits:
+
+- **Stay well below the API's per-key limit** — our keys are shared across all workspaces. If the API allows 60 RPM per key and we have 3 keys, the global ceiling is ~180 RPM. Set the per-workspace limit low enough (e.g., 20-60 RPM) that many workspaces can coexist without collectively hitting the API's ceiling.
+- **Account for key pooling** — our round-robin distributes requests across `N` hosted keys, so the effective API-side rate per key is `(total requests) / N`. But per-workspace limits are enforced *before* key selection, so they apply regardless of key count.
+- **Prefer conservative defaults** — it's easy to raise limits later but hard to claw back after users depend on high throughput.
+
+## Step 3: Add `hosting` Config to the Tool
+
+Add a `hosting` object to the tool's `ToolConfig`. This tells the execution layer how to acquire hosted keys, calculate cost, and rate-limit.
+
+```typescript
+hosting: {
+  envKeyPrefix: 'YOUR_SERVICE_API_KEY',
+  apiKeyParam: 'apiKey',
+  byokProviderId: 'your_service',
+  pricing: {
+    type: 'custom',
+    getCost: (_params, output) => {
+      if (output.creditsUsed == null) {
+        throw new Error('Response missing creditsUsed field')
+      }
+      const creditsUsed = output.creditsUsed as number
+      const cost = creditsUsed * 0.001 // dollars per credit
+      return { cost, metadata: { creditsUsed } }
+    },
+  },
+  rateLimit: {
+    mode: 'per_request',
+    requestsPerMinute: 100,
+  },
+},
+```
+
+### Hosted Key Env Var Convention
+
+Keys use a numbered naming pattern driven by a count env var:
+
+```
+YOUR_SERVICE_API_KEY_COUNT=3
+YOUR_SERVICE_API_KEY_1=sk-...
+YOUR_SERVICE_API_KEY_2=sk-...
+YOUR_SERVICE_API_KEY_3=sk-...
+```
+
+The `envKeyPrefix` value (`YOUR_SERVICE_API_KEY`) determines which env vars are read at runtime. Adding more keys only requires bumping the count and adding the new env var.
+
+### Pricing: Prefer API-Reported Cost
+
+Always prefer using cost data returned by the API (e.g., `creditsUsed`, `costDollars`). This is the most accurate because it accounts for variable pricing tiers, feature modifiers, and plan-level discounts.
+
+**When the API reports cost** — use it directly and throw if missing:
+
+```typescript
+pricing: {
+  type: 'custom',
+  getCost: (params, output) => {
+    if (output.creditsUsed == null) {
+      throw new Error('Response missing creditsUsed field')
+    }
+    // $0.001 per credit — from https://example.com/pricing
+    const cost = (output.creditsUsed as number) * 0.001
+    return { cost, metadata: { creditsUsed: output.creditsUsed } }
+  },
+},
+```
+
+**When the API does NOT report cost** — compute it from params/output based on the pricing docs, but still validate the data you depend on:
+
+```typescript
+pricing: {
+  type: 'custom',
+  getCost: (params, output) => {
+    if (!Array.isArray(output.searchResults)) {
+      throw new Error('Response missing searchResults, cannot determine cost')
+    }
+    // Serper: 1 credit for <=10 results, 2 credits for >10 — from https://serper.dev/pricing
+    const credits = Number(params.num) > 10 ? 2 : 1
+    return { cost: credits * 0.001, metadata: { credits } }
+  },
+},
+```
+
+**`getCost` must always throw** if it cannot determine cost. Never silently fall back to a default — this would hide billing inaccuracies.
+
+### Capturing Cost Data from the API
+
+If the API returns cost info, capture it in `transformResponse` so `getCost` can read it from the output:
+
+```typescript
+transformResponse: async (response: Response) => {
+  const data = await response.json()
+  return {
+    success: true,
+    output: {
+      results: data.results,
+      creditsUsed: data.creditsUsed,  // pass through for getCost
+    },
+  }
+},
+```
+
+For async/polling tools, capture it in `postProcess` when the job completes:
+
+```typescript
+if (jobData.status === 'completed') {
+  result.output = {
+    data: jobData.data,
+    creditsUsed: jobData.creditsUsed,
+  }
+}
+```
+
+## Step 4: Hide the API Key Field When Hosted
+
+In the block config (`blocks/blocks/{service}.ts`), add `hideWhenHosted: true` to the API key subblock. This hides the field on hosted Sim since the platform provides the key:
+
+```typescript
+{
+  id: 'apiKey',
+  title: 'API Key',
+  type: 'short-input',
+  placeholder: 'Enter your API key',
+  password: true,
+  required: true,
+  hideWhenHosted: true,
+},
+```
+
+The visibility is controlled by `isSubBlockHidden()` in `lib/workflows/subblocks/visibility.ts`, which checks both the `isHosted` feature flag (`hideWhenHosted`) and optional env var conditions (`hideWhenEnvSet`).
+
+### Excluding Specific Operations from Hosted Key Support
+
+When a block has multiple operations but some operations should **not** use a hosted key (e.g., the underlying API is deprecated, unsupported, or too expensive), use the **duplicate apiKey subblock** pattern. This is the same pattern Exa uses for its `research` operation:
+
+1. **Remove the `hosting` config** from the tool definition for that operation — it must not have a `hosting` object at all.
+2. **Duplicate the `apiKey` subblock** in the block config with opposing conditions:
+
+```typescript
+// API Key — hidden when hosted for operations with hosted key support
+{
+  id: 'apiKey',
+  title: 'API Key',
+  type: 'short-input',
+  placeholder: 'Enter your API key',
+  password: true,
+  required: true,
+  hideWhenHosted: true,
+  condition: { field: 'operation', value: 'unsupported_op', not: true },
+},
+// API Key — always visible for unsupported_op (no hosted key support)
+{
+  id: 'apiKey',
+  title: 'API Key',
+  type: 'short-input',
+  placeholder: 'Enter your API key',
+  password: true,
+  required: true,
+  condition: { field: 'operation', value: 'unsupported_op' },
+},
+```
+
+Both subblocks share the same `id: 'apiKey'`, so the same value flows to the tool. The conditions ensure only one is visible at a time. The first has `hideWhenHosted: true` and shows for all hosted operations; the second has no `hideWhenHosted` and shows only for the excluded operation — meaning users must always provide their own key for that operation.
+
+To exclude multiple operations, use an array: `{ field: 'operation', value: ['op_a', 'op_b'] }`.
+
+**Reference implementations:**
+- **Exa** (`blocks/blocks/exa.ts`): `research` operation excluded from hosting — lines 309-329
+- **Google Maps** (`blocks/blocks/google_maps.ts`): `speed_limits` operation excluded from hosting (deprecated Roads API)
+
+## Step 5: Add to the BYOK Settings UI
+
+Add an entry to the `PROVIDERS` array in the BYOK settings component so users can bring their own key. You need the service icon from `components/icons.tsx`:
+
+```typescript
+{
+  id: 'your_service',
+  name: 'Your Service',
+  icon: YourServiceIcon,
+  description: 'What this service does',
+  placeholder: 'Enter your API key',
+},
+```
+
+## Step 6: Summarize Pricing and Throttling Comparison
+
+After all code changes are complete, output a detailed summary to the user covering:
+
+### What to include
+
+1. **API's pricing model** — how the service charges (per token, per credit, per request, etc.), the specific rates found in docs, and whether the API reports cost in responses.
+2. **Our `getCost` approach** — how we calculate cost, what fields we depend on, and any assumptions or estimates (especially when the API doesn't report exact dollar cost).
+3. **API's rate limits** — the documented limits (RPM, TPM, concurrent, etc.), which plan tier they apply to, and whether they're per-key or per-account.
+4. **Our `rateLimit` config** — what we set for `requestsPerMinute` (and dimensions if custom mode), why we chose those values, and how they compare to the API's limits.
+5. **Key pooling impact** — how many hosted keys we expect, and how round-robin distribution affects the effective per-key rate at the API.
+6. **Gaps or risks** — anything the API charges for that we don't meter, rate limit dimensions we chose not to enforce, or pricing that may be inaccurate due to variable model/tier costs.
+
+### Format
+
+Present this as a structured summary with clear headings. Example:
+
+```
+### Pricing
+- **API charges**: $X per 1M tokens (input), $Y per 1M tokens (output) — varies by model
+- **Response reports cost?**: No — only token counts in `usage` field
+- **Our getCost**: Estimates cost at $Z per 1M total tokens based on median model pricing
+- **Risk**: Actual cost varies by model; our estimate may over/undercharge for cheap/expensive models
+
+### Throttling
+- **API limits**: 300 RPM per key (paid tier), 60 RPM (free tier)
+- **Per-key or per-account**: Per key — more keys = more throughput
+- **Our config**: 60 RPM per workspace (per_request mode)
+- **With N keys**: Effective per-key rate is (total RPM across workspaces) / N
+- **Headroom**: Comfortable — even 10 active workspaces at full rate = 600 RPM / 3 keys = 200 RPM per key, under the 300 RPM API limit
+```
+
+This summary helps reviewers verify that the pricing and rate limiting are well-calibrated and surfaces any risks that need monitoring.
+
+## Checklist
+
+- [ ] Provider added to `BYOKProviderId` in `tools/types.ts`
+- [ ] Provider added to `VALID_PROVIDERS` in the BYOK keys API route
+- [ ] API pricing docs researched — understand per-unit cost and whether the API reports cost in responses
+- [ ] API rate limits researched — understand RPM/TPM limits, per-key vs per-account, and plan tiers
+- [ ] `hosting` config added to the tool with `envKeyPrefix`, `apiKeyParam`, `byokProviderId`, `pricing`, and `rateLimit`
+- [ ] `getCost` throws if required cost data is missing from the response
+- [ ] Cost data captured in `transformResponse` or `postProcess` if API provides it
+- [ ] `hideWhenHosted: true` added to the API key subblock in the block config
+- [ ] Provider entry added to the BYOK settings UI with icon and description
+- [ ] Env vars documented: `{PREFIX}_COUNT` and `{PREFIX}_1..N`
+- [ ] Pricing and throttling summary provided to reviewer
--- a/.devcontainer/Dockerfile
+++ b/.devcontainer/Dockerfile
@@ -1,4 +1,4 @@
-FROM oven/bun:1.3.9-alpine
+FROM oven/bun:1.3.11-alpine

 # Install necessary packages for development
 RUN apk add --no-cache \
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -0,0 +1,28 @@
+# Copilot/Mothership chat streaming entrypoints and replay surfaces.
+/apps/sim/app/api/copilot/chat/ @simstudioai/mothership
+/apps/sim/app/api/copilot/confirm/ @simstudioai/mothership
+/apps/sim/app/api/copilot/chats/ @simstudioai/mothership
+/apps/sim/app/api/mothership/chat/ @simstudioai/mothership
+/apps/sim/app/api/mothership/chats/ @simstudioai/mothership
+/apps/sim/app/api/mothership/execute/ @simstudioai/mothership
+/apps/sim/app/api/v1/copilot/chat/ @simstudioai/mothership
+
+# Server-side stream orchestration, persistence, and protocol.
+/apps/sim/lib/copilot/chat/ @simstudioai/mothership
+/apps/sim/lib/copilot/async-runs/ @simstudioai/mothership
+/apps/sim/lib/copilot/request/ @simstudioai/mothership
+/apps/sim/lib/copilot/generated/ @simstudioai/mothership
+/apps/sim/lib/copilot/constants.ts @simstudioai/mothership
+/apps/sim/lib/core/utils/sse.ts @simstudioai/mothership
+
+# Stream-time tool execution, confirmations, resource persistence, and handlers.
+/apps/sim/lib/copilot/tool-executor/ @simstudioai/mothership
+/apps/sim/lib/copilot/tools/ @simstudioai/mothership
+/apps/sim/lib/copilot/persistence/ @simstudioai/mothership
+/apps/sim/lib/copilot/resources/ @simstudioai/mothership
+
+# Client-side stream consumption, hydration, and reconnect.
+/apps/sim/app/workspace/*/home/hooks/index.ts @simstudioai/mothership
+/apps/sim/app/workspace/*/home/hooks/use-chat.ts @simstudioai/mothership
+/apps/sim/app/workspace/*/home/hooks/use-file-preview-sessions.ts @simstudioai/mothership
+/apps/sim/hooks/queries/tasks.ts @simstudioai/mothership
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -2,13 +2,13 @@ name: CI

 on:
  push:
-    branches: [main, staging]
+    branches: [main, staging, dev]
  pull_request:
-    branches: [main, staging]
+    branches: [main, staging, dev]

 concurrency:
  group: ci-${{ github.ref }}
-  cancel-in-progress: false
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

 permissions:
  contents: read
@@ -16,6 +16,7 @@ permissions:
 jobs:
  test-build:
    name: Test and Build
+    if: github.ref != 'refs/heads/dev' || github.event_name == 'pull_request'
    uses: ./.github/workflows/test-build.yml
    secrets: inherit

@@ -23,7 +24,7 @@ jobs:
  detect-version:
    name: Detect Version
    runs-on: blacksmith-4vcpu-ubuntu-2404
-    if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/staging')
+    if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/staging' || github.ref == 'refs/heads/dev')
    outputs:
      version: ${{ steps.extract.outputs.version }}
      is_release: ${{ steps.extract.outputs.is_release }}
@@ -45,11 +46,72 @@ jobs:
            echo "ℹ️ Not a release commit"
          fi

-  # Build AMD64 images and push to ECR immediately (+ GHCR for main)
+  # Dev: build all 3 images for ECR only (no GHCR, no ARM64)
+  build-dev:
+    name: Build Dev ECR
+    needs: [detect-version]
+    if: github.event_name == 'push' && github.ref == 'refs/heads/dev'
+    runs-on: blacksmith-8vcpu-ubuntu-2404
+    permissions:
+      contents: read
+      id-token: write
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - dockerfile: ./docker/app.Dockerfile
+            ecr_repo_secret: ECR_APP
+          - dockerfile: ./docker/db.Dockerfile
+            ecr_repo_secret: ECR_MIGRATIONS
+          - dockerfile: ./docker/realtime.Dockerfile
+            ecr_repo_secret: ECR_REALTIME
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: ${{ secrets.DEV_AWS_ROLE_TO_ASSUME }}
+          aws-region: ${{ secrets.DEV_AWS_REGION }}
+
+      - name: Login to Amazon ECR
+        id: login-ecr
+        uses: aws-actions/amazon-ecr-login@v2
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Set up Docker Buildx
+        uses: useblacksmith/setup-docker-builder@v1
+
+      - name: Resolve ECR repo name
+        id: ecr-repo
+        run: echo "name=$ECR_REPO" >> $GITHUB_OUTPUT
+        env:
+          ECR_REPO: ${{ matrix.ecr_repo_secret == 'ECR_APP' && secrets.ECR_APP || matrix.ecr_repo_secret == 'ECR_MIGRATIONS' && secrets.ECR_MIGRATIONS || matrix.ecr_repo_secret == 'ECR_REALTIME' && secrets.ECR_REALTIME || '' }}
+
+      - name: Build and push
+        uses: useblacksmith/build-push-action@v2
+        with:
+          context: .
+          file: ${{ matrix.dockerfile }}
+          platforms: linux/amd64
+          push: true
+          tags: ${{ steps.login-ecr.outputs.registry }}/${{ steps.ecr-repo.outputs.name }}:dev
+          provenance: false
+          sbom: false
+
+  # Main/staging: build AMD64 images and push to ECR + GHCR
  build-amd64:
    name: Build AMD64
    needs: [test-build, detect-version]
-    if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/staging')
+    if: >-
+      github.event_name == 'push' &&
+      (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/staging')
    runs-on: blacksmith-8vcpu-ubuntu-2404
    permissions:
      contents: read
@@ -70,7 +132,7 @@ jobs:
            ecr_repo_secret: ECR_REALTIME
    steps:
      - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
@@ -99,14 +161,19 @@ jobs:
      - name: Set up Docker Buildx
        uses: useblacksmith/setup-docker-builder@v1

+      - name: Resolve ECR repo name
+        id: ecr-repo
+        run: echo "name=$ECR_REPO" >> $GITHUB_OUTPUT
+        env:
+          ECR_REPO: ${{ matrix.ecr_repo_secret == 'ECR_APP' && secrets.ECR_APP || matrix.ecr_repo_secret == 'ECR_MIGRATIONS' && secrets.ECR_MIGRATIONS || matrix.ecr_repo_secret == 'ECR_REALTIME' && secrets.ECR_REALTIME || '' }}
+
      - name: Generate tags
        id: meta
        run: |
          ECR_REGISTRY="${{ steps.login-ecr.outputs.registry }}"
-          ECR_REPO="${{ secrets[matrix.ecr_repo_secret] }}"
+          ECR_REPO="${{ steps.ecr-repo.outputs.name }}"
          GHCR_IMAGE="${{ matrix.ghcr_image }}"

-          # ECR tags (always build for ECR)
          if [ "${{ github.ref }}" = "refs/heads/main" ]; then
            ECR_TAG="latest"
          else
@@ -114,16 +181,13 @@ jobs:
          fi
          ECR_IMAGE="${ECR_REGISTRY}/${ECR_REPO}:${ECR_TAG}"

-          # Build tags list
          TAGS="${ECR_IMAGE}"

-          # Add GHCR tags only for main branch
          if [ "${{ github.ref }}" = "refs/heads/main" ]; then
            GHCR_AMD64="${GHCR_IMAGE}:latest-amd64"
            GHCR_SHA="${GHCR_IMAGE}:${{ github.sha }}-amd64"
            TAGS="${TAGS},$GHCR_AMD64,$GHCR_SHA"

-            # Add version tag if this is a release commit
            if [ "${{ needs.detect-version.outputs.is_release }}" = "true" ]; then
              VERSION="${{ needs.detect-version.outputs.version }}"
              GHCR_VERSION="${GHCR_IMAGE}:${VERSION}-amd64"
@@ -148,7 +212,7 @@ jobs:
  # Build ARM64 images for GHCR (main branch only, runs in parallel)
  build-ghcr-arm64:
    name: Build ARM64 (GHCR Only)
-    needs: [test-build, detect-version]
+    needs: [detect-version]
    runs-on: blacksmith-8vcpu-ubuntu-2404-arm
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    permissions:
@@ -167,7 +231,7 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6

      - name: Login to GHCR
        uses: docker/login-action@v3
@@ -254,6 +318,14 @@ jobs:
            docker manifest push "${IMAGE_BASE}:${VERSION}"
          fi

+  # Run database migrations for dev
+  migrate-dev:
+    name: Migrate Dev DB
+    needs: [build-dev]
+    if: github.event_name == 'push' && github.ref == 'refs/heads/dev'
+    uses: ./.github/workflows/migrations.yml
+    secrets: inherit
+
  # Check if docs changed
  check-docs-changes:
    name: Check Docs Changes
@@ -262,10 +334,10 @@ jobs:
    outputs:
      docs_changed: ${{ steps.filter.outputs.docs }}
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
        with:
          fetch-depth: 2  # Need at least 2 commits to detect changes
-      - uses: dorny/paths-filter@v3
+      - uses: dorny/paths-filter@v4
        id: filter
        with:
          filters: |
@@ -292,7 +364,7 @@ jobs:
      contents: write
    steps:
      - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
        with:
          fetch-depth: 0

--- a/.github/workflows/docs-embeddings.yml
+++ b/.github/workflows/docs-embeddings.yml
@@ -15,12 +15,12 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6

      - name: Setup Bun
        uses: oven-sh/setup-bun@v2
        with:
-          bun-version: 1.3.9
+          bun-version: 1.3.11

      - name: Setup Node
        uses: actions/setup-node@v4
--- a/.github/workflows/i18n.yml
+++ b/.github/workflows/i18n.yml
@@ -14,7 +14,7 @@ jobs:
    
    steps:
      - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
        with:
          ref: staging
          token: ${{ secrets.GH_PAT }}
@@ -23,7 +23,7 @@ jobs:
      - name: Setup Bun
        uses: oven-sh/setup-bun@v2
        with:
-          bun-version: 1.3.9
+          bun-version: 1.3.11

      - name: Cache Bun dependencies
        uses: actions/cache@v4
@@ -115,14 +115,14 @@ jobs:
    
    steps:
      - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
        with:
          ref: staging

      - name: Setup Bun
        uses: oven-sh/setup-bun@v2
        with:
-          bun-version: 1.3.9
+          bun-version: 1.3.11

      - name: Cache Bun dependencies
        uses: actions/cache@v4
--- a/.github/workflows/images.yml
+++ b/.github/workflows/images.yml
@@ -31,13 +31,13 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
-          role-to-assume: ${{ github.ref == 'refs/heads/main' && secrets.AWS_ROLE_TO_ASSUME || secrets.STAGING_AWS_ROLE_TO_ASSUME }}
-          aws-region: ${{ github.ref == 'refs/heads/main' && secrets.AWS_REGION || secrets.STAGING_AWS_REGION }}
+          role-to-assume: ${{ github.ref == 'refs/heads/main' && secrets.AWS_ROLE_TO_ASSUME || github.ref == 'refs/heads/dev' && secrets.DEV_AWS_ROLE_TO_ASSUME || secrets.STAGING_AWS_ROLE_TO_ASSUME }}
+          aws-region: ${{ github.ref == 'refs/heads/main' && secrets.AWS_REGION || github.ref == 'refs/heads/dev' && secrets.DEV_AWS_REGION || secrets.STAGING_AWS_REGION }}

      - name: Login to Amazon ECR
        id: login-ecr
@@ -70,6 +70,8 @@ jobs:
          # ECR tags (always build for ECR)
          if [ "${{ github.ref }}" = "refs/heads/main" ]; then
            ECR_TAG="latest"
+          elif [ "${{ github.ref }}" = "refs/heads/dev" ]; then
+            ECR_TAG="dev"
          else
            ECR_TAG="staging"
          fi
@@ -115,7 +117,7 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6

      - name: Login to GHCR
        uses: docker/login-action@v3
@@ -146,7 +148,7 @@ jobs:

  create-ghcr-manifests:
    name: Create GHCR Manifests
-    runs-on: blacksmith-8vcpu-ubuntu-2404
+    runs-on: blacksmith-2vcpu-ubuntu-2404
    needs: [build-amd64, build-ghcr-arm64]
    if: github.ref == 'refs/heads/main'
    strategy:
--- a/.github/workflows/migrations.yml
+++ b/.github/workflows/migrations.yml
@@ -14,12 +14,12 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6

      - name: Setup Bun
        uses: oven-sh/setup-bun@v2
        with:
-          bun-version: 1.3.9
+          bun-version: 1.3.11

      - name: Cache Bun dependencies
        uses: actions/cache@v4
@@ -38,5 +38,5 @@ jobs:
      - name: Apply migrations
        working-directory: ./packages/db
        env:
-          DATABASE_URL: ${{ github.ref == 'refs/heads/main' && secrets.DATABASE_URL || secrets.STAGING_DATABASE_URL }}
+          DATABASE_URL: ${{ github.ref == 'refs/heads/main' && secrets.DATABASE_URL || github.ref == 'refs/heads/dev' && secrets.DEV_DATABASE_URL || secrets.STAGING_DATABASE_URL }}
        run: bunx drizzle-kit migrate --config=./drizzle.config.ts
--- a/.github/workflows/publish-cli.yml
+++ b/.github/workflows/publish-cli.yml
@@ -14,12 +14,12 @@ jobs:
    runs-on: blacksmith-4vcpu-ubuntu-2404
    steps:
      - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6

      - name: Setup Bun
        uses: oven-sh/setup-bun@v2
        with:
-          bun-version: 1.3.9
+          bun-version: 1.3.11

      - name: Setup Node.js for npm publishing
        uses: actions/setup-node@v4
--- a/.github/workflows/publish-python-sdk.yml
+++ b/.github/workflows/publish-python-sdk.yml
@@ -14,7 +14,7 @@ jobs:
    runs-on: blacksmith-4vcpu-ubuntu-2404
    steps:
      - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6

      - name: Setup Python
        uses: actions/setup-python@v5
--- a/.github/workflows/publish-ts-sdk.yml
+++ b/.github/workflows/publish-ts-sdk.yml
@@ -14,12 +14,12 @@ jobs:
    runs-on: blacksmith-4vcpu-ubuntu-2404
    steps:
      - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6

      - name: Setup Bun
        uses: oven-sh/setup-bun@v2
        with:
-          bun-version: 1.3.9
+          bun-version: 1.3.11

      - name: Setup Node.js for npm publishing
        uses: actions/setup-node@v4
--- a/.github/workflows/test-build.yml
+++ b/.github/workflows/test-build.yml
@@ -10,16 +10,16 @@ permissions:
 jobs:
  test-build:
    name: Test and Build
-    runs-on: blacksmith-4vcpu-ubuntu-2404
+    runs-on: blacksmith-8vcpu-ubuntu-2404

    steps:
      - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6

      - name: Setup Bun
        uses: oven-sh/setup-bun@v2
        with:
-          bun-version: 1.3.9
+          bun-version: 1.3.11

      - name: Setup Node
        uses: actions/setup-node@v4
@@ -38,6 +38,20 @@ jobs:
          key: ${{ github.repository }}-node-modules
          path: ./node_modules

+      - name: Mount Turbo cache (Sticky Disk)
+        uses: useblacksmith/stickydisk@v1
+        with:
+          key: ${{ github.repository }}-turbo-cache
+          path: ./.turbo
+
+      - name: Restore Next.js build cache
+        uses: actions/cache@v4
+        with:
+          path: ./apps/sim/.next/cache
+          key: ${{ runner.os }}-nextjs-${{ hashFiles('bun.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-nextjs-
+
      - name: Install dependencies
        run: bun install --frozen-lockfile

@@ -76,15 +90,26 @@ jobs:

          echo "✅ All feature flags are properly configured"

+      - name: Check subblock ID stability
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            BASE_REF="origin/${{ github.base_ref }}"
+            git fetch --depth=1 origin "${{ github.base_ref }}" 2>/dev/null || true
+          else
+            BASE_REF="HEAD~1"
+          fi
+          bun run apps/sim/scripts/check-subblock-id-stability.ts "$BASE_REF"
+
      - name: Lint code
        run: bun run lint:check

      - name: Run tests with coverage
        env:
-          NODE_OPTIONS: '--no-warnings'
+          NODE_OPTIONS: '--no-warnings --max-old-space-size=8192'
          NEXT_PUBLIC_APP_URL: 'https://www.sim.ai'
          DATABASE_URL: 'postgresql://postgres:postgres@localhost:5432/simstudio'
          ENCRYPTION_KEY: '7cf672e460e430c1fba707575c2b0e2ad5a99dddf9b7b7e3b5646e630861db1c' # dummy key for CI only
+          TURBO_CACHE_DIR: .turbo
        run: bun run test

      - name: Check schema and migrations are in sync
@@ -102,7 +127,7 @@ jobs:

      - name: Build application
        env:
-          NODE_OPTIONS: '--no-warnings'
+          NODE_OPTIONS: '--no-warnings --max-old-space-size=8192'
          NEXT_PUBLIC_APP_URL: 'https://www.sim.ai'
          DATABASE_URL: 'postgresql://postgres:postgres@localhost:5432/simstudio'
          STRIPE_SECRET_KEY: 'dummy_key_for_ci_only'
@@ -110,7 +135,8 @@ jobs:
          RESEND_API_KEY: 'dummy_key_for_ci_only'
          AWS_REGION: 'us-west-2'
          ENCRYPTION_KEY: '7cf672e460e430c1fba707575c2b0e2ad5a99dddf9b7b7e3b5646e630861db1c' # dummy key for CI only
-        run: bun run build
+          TURBO_CACHE_DIR: .turbo
+        run: bunx turbo run build --filter=sim

      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v5
--- a/.gitignore
+++ b/.gitignore
@@ -26,6 +26,9 @@ bun-debug.log*
 **/standalone/
 sim-standalone.tar.gz

+# redis
+dump.rdb
+
 # misc
 .DS_Store
 *.pem
@@ -73,3 +76,7 @@ start-collector.sh
 ## Helm Chart Tests
 helm/sim/test
 i18n.cache
+
+## Claude Code
+.claude/launch.json
+.claude/worktrees/
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,384 @@
+# Sim Development Guidelines
+
+You are a professional software engineer. All code must follow best practices: accurate, readable, clean, and efficient.
+
+## Global Standards
+
+- **Logging**: Import `createLogger` from `@sim/logger`. Use `logger.info`, `logger.warn`, `logger.error` instead of `console.log`
+- **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 `uuid` package. Use `generateId()` (UUID v4) or `generateShortId()` (compact) from `@sim/utils/id`
+- **Package Manager**: Use `bun` and `bunx`, not `npm` and `npx`
+
+## 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 Structure
+```
+apps/sim/
+├── 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
+```
+
+### 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`)
+
+## Imports
+
+**Always use absolute imports.** Never use relative imports.
+
+```typescript
+// ✓ Good
+import { useWorkflowStore } from '@/stores/workflows/store'
+
+// ✗ Bad
+import { useWorkflowStore } from '../../../stores/workflows/store'
+```
+
+Use barrel exports (`index.ts`) when a folder has 3+ exports. Do not re-export from non-barrel files; import directly from the source.
+
+### Import Order
+1. React/core libraries
+2. External libraries
+3. UI components (`@/components/emcn`, `@/components/ui`)
+4. Utilities (`@/lib/...`)
+5. Stores (`@/stores/...`)
+6. Feature imports
+7. CSS imports
+
+Use `import type { X }` for type-only imports.
+
+## TypeScript
+
+1. No `any` - Use proper types or `unknown` with type guards
+2. Always define props interface for components
+3. `as const` for constant objects/arrays
+4. Explicit ref types: `useRef<HTMLDivElement>(null)`
+
+## Components
+
+```typescript
+'use client' // Only if using hooks
+
+const CONFIG = { SPACING: 8 } as const
+
+interface ComponentProps {
+  requiredProp: string
+  optionalProp?: boolean
+}
+
+export function Component({ requiredProp, optionalProp = false }: ComponentProps) {
+  // Order: refs → external hooks → store hooks → custom hooks → state → useMemo → useCallback → useEffect → return
+}
+```
+
+Extract when: 50+ lines, used in 2+ files, or has own state/logic. Keep inline when: < 10 lines, single use, purely presentational.
+
+## Hooks
+
+```typescript
+interface UseFeatureProps { id: string }
+
+export function useFeature({ id }: UseFeatureProps) {
+  const idRef = useRef(id)
+  const [data, setData] = useState<Data | null>(null)
+  
+  useEffect(() => { idRef.current = id }, [id])
+  
+  const fetchData = useCallback(async () => { ... }, []) // Empty deps when using refs
+  
+  return { data, fetchData }
+}
+```
+
+## Zustand Stores
+
+Stores live in `stores/`. Complex stores split into `store.ts` + `types.ts`.
+
+```typescript
+import { create } from 'zustand'
+import { devtools } from 'zustand/middleware'
+
+const initialState = { items: [] as Item[] }
+
+export const useFeatureStore = create<FeatureState>()(
+  devtools(
+    (set, get) => ({
+      ...initialState,
+      setItems: (items) => set({ items }),
+      reset: () => set(initialState),
+    }),
+    { name: 'feature-store' }
+  )
+)
+```
+
+Use `devtools` middleware. Use `persist` only when data should survive reload with `partialize` to persist only necessary state.
+
+## React Query
+
+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 file must have a hierarchical key factory with an `all` root key and intermediate plural keys for prefix 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,
+}
+```
+
+### Query Hooks
+
+- Every `queryFn` must 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
+
+```typescript
+export function useEntityList(workspaceId?: string) {
+  return useQuery({
+    queryKey: entityKeys.list(workspaceId),
+    queryFn: ({ signal }) => fetchEntities(workspaceId as string, signal),
+    enabled: Boolean(workspaceId),
+    staleTime: 60 * 1000,
+    placeholderData: keepPreviousData, // OK: workspaceId varies
+  })
+}
+```
+
+### Mutation Hooks
+
+- Use targeted invalidation (`entityKeys.lists()`) not broad (`entityKeys.all`) when possible
+- For optimistic updates: use `onSettled` (not `onSuccess`) for cache reconciliation — `onSettled` fires on both success and error
+- Don't include mutation objects in `useCallback` deps — `.mutate()` is stable in TanStack Query v5
+
+```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 */)
+      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) })
+    },
+  })
+}
+```
+
+## Styling
+
+Use Tailwind only, no inline styles. Use `cn()` from `@/lib/utils` for conditional classes.
+
+```typescript
+<div className={cn('base-classes', isActive && 'active-classes')} />
+```
+
+## EMCN Components
+
+Import from `@/components/emcn`, never from subpaths (except CSS files). Use CVA when 2+ variants exist.
+
+## Testing
+
+Use Vitest. Test files: `feature.ts` → `feature.test.ts`. See `.cursor/rules/sim-testing.mdc` for full details.
+
+### Global Mocks (vitest.setup.ts)
+
+`@sim/db`, `drizzle-orm`, `@sim/logger`, `@/blocks/registry`, `@trigger.dev/sdk`, and store mocks are provided globally. Do NOT re-mock them unless overriding behavior.
+
+### Standard Test Pattern
+
+```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 } from '@/app/api/my-route/route'
+
+describe('my route', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockGetSession.mockResolvedValue({ user: { id: 'user-1' } })
+  })
+  it('returns data', async () => { ... })
+})
+```
+
+### Performance Rules
+
+- **NEVER** use `vi.resetModules()` + `vi.doMock()` + `await import()` — use `vi.hoisted()` + `vi.mock()` + static imports
+- **NEVER** use `vi.importActual()` — mock everything explicitly
+- **NEVER** use `mockAuth()`, `mockConsoleLogger()`, `setupCommonApiMocks()` from `@sim/testing` — they use `vi.doMock()` internally
+- **Mock heavy deps** (`@/blocks`, `@/tools/registry`, `@/triggers`) in tests that don't need them
+- **Use `@vitest-environment node`** unless DOM APIs are needed (`window`, `document`, `FormData`)
+- **Avoid real timers** — use 1ms delays or `vi.useFakeTimers()`
+
+Use `@sim/testing` mocks/factories over local test data.
+
+## Utils Rules
+
+- Never create `utils.ts` for single consumer - inline it
+- Create `utils.ts` when 2+ files need the same helper
+- Check existing sources in `lib/` before duplicating
+
+## Adding Integrations
+
+New integrations require: **Tools** → **Block** → **Icon** → (optional) **Trigger**
+
+Always look up the service's API docs first.
+
+### 1. Tools (`tools/{service}/`)
+
+```
+tools/{service}/
+├── index.ts      # Barrel export
+├── types.ts      # Params/response types
+└── {action}.ts   # Tool implementation
+```
+
+**Tool structure:**
+```typescript
+export const serviceTool: ToolConfig<Params, Response> = {
+  id: 'service_action',
+  name: 'Service Action',
+  description: '...',
+  version: '1.0.0',
+  oauth: { required: true, provider: 'service' },
+  params: { /* ... */ },
+  request: { url: '/api/tools/service/action', method: 'POST', ... },
+  transformResponse: async (response) => { /* ... */ },
+  outputs: { /* ... */ },
+}
+```
+
+Register in `tools/registry.ts`.
+
+### 2. Block (`blocks/blocks/{service}.ts`)
+
+```typescript
+export const ServiceBlock: BlockConfig = {
+  type: 'service',
+  name: 'Service',
+  description: '...',
+  category: 'tools',
+  bgColor: '#hexcolor',
+  icon: ServiceIcon,
+  subBlocks: [ /* see SubBlock Properties */ ],
+  tools: { access: ['service_action'], config: { tool: (p) => `service_${p.operation}`, params: (p) => ({ /* type coercions here */ }) } },
+  inputs: { /* ... */ },
+  outputs: { /* ... */ },
+}
+```
+
+Register in `blocks/registry.ts` (alphabetically).
+
+**Important:** `tools.config.tool` runs during serialization (before variable resolution). Never do `Number()` or other type coercions there — dynamic references like `<Block.output>` will be destroyed. Use `tools.config.params` for type coercions (it runs during execution, after variables are resolved).
+
+**SubBlock Properties:**
+```typescript
+{
+  id: 'field', title: 'Label', type: 'short-input', placeholder: '...',
+  required: true,                    // or condition object
+  condition: { field: 'op', value: 'send' },  // show/hide
+  dependsOn: ['credential'],         // clear when dep changes
+  mode: 'basic',                     // 'basic' | 'advanced' | 'both' | 'trigger'
+}
+```
+
+**condition examples:**
+- `{ field: 'op', value: 'send' }` - show when op === 'send'
+- `{ field: 'op', value: ['a','b'] }` - show when op is 'a' OR 'b'
+- `{ field: 'op', value: 'x', not: true }` - show when op !== 'x'
+- `{ field: 'op', value: 'x', not: true, and: { field: 'type', value: 'dm', not: true } }` - complex
+
+**dependsOn:** `['field']` or `{ all: ['a'], any: ['b', 'c'] }`
+
+**File Input Pattern (basic/advanced mode):**
+```typescript
+// Basic: file-upload UI
+{ id: 'uploadFile', type: 'file-upload', canonicalParamId: 'file', mode: 'basic' },
+// Advanced: reference from other blocks
+{ id: 'fileRef', type: 'short-input', canonicalParamId: 'file', mode: 'advanced' },
+```
+
+In `tools.config.tool`, normalize with:
+```typescript
+import { normalizeFileInput } from '@/blocks/utils'
+const file = normalizeFileInput(params.uploadFile || params.fileRef, { single: true })
+if (file) params.file = file
+```
+
+For file uploads, create an internal API route (`/api/tools/{service}/upload`) that uses `downloadFileFromStorage` to get file content from `UserFile` objects.
+
+### 3. Icon (`components/icons.tsx`)
+
+```typescript
+export function ServiceIcon(props: SVGProps<SVGSVGElement>) {
+  return <svg {...props}>/* SVG from brand assets */</svg>
+}
+```
+
+### 4. Trigger (`triggers/{service}/`) - Optional
+
+```
+triggers/{service}/
+├── index.ts      # Barrel export
+├── webhook.ts    # Webhook handler
+└── {event}.ts    # Event-specific handlers
+```
+
+Register in `triggers/registry.ts`.
+
+### Integration Checklist
+
+- [ ] Look up API docs
+- [ ] Create `tools/{service}/` with types and tools
+- [ ] Register tools in `tools/registry.ts`
+- [ ] Add icon to `components/icons.tsx`
+- [ ] Create block in `blocks/blocks/{service}.ts`
+- [ ] Register block in `blocks/registry.ts`
+- [ ] (Optional) Create and register triggers
+- [ ] (If file uploads) Create internal API route with `downloadFileFromStorage`
+- [ ] (If file uploads) Use `normalizeFileInput` in block config
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,9 +4,12 @@ You are a professional software engineer. All code must follow best practices: a

 ## Global Standards

- **Logging**: Import `createLogger` from `@sim/logger`. Use `logger.info`, `logger.warn`, `logger.error` instead of `console.log`
+- **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 — no manual `withMetadata({ requestId })` needed
+- **API Route Handlers**: All API route handlers (`GET`, `POST`, `PUT`, `DELETE`, `PATCH`) must be wrapped with `withRouteHandler` from `@/lib/core/utils/with-route-handler`. This provides request ID tracking, automatic error logging for 4xx/5xx responses, and unhandled error catching. See "API Route Pattern" section below
 - **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 `uuid` package. Use `generateId()` (UUID v4) or `generateShortId()` (compact) from `@sim/utils/id`
+- **Common Utilities**: Use shared helpers from `@sim/utils` instead of inline implementations. `sleep(ms)` from `@sim/utils/helpers` for delays, `toError(e)` from `@sim/utils/errors` to normalize caught values.
 - **Package Manager**: Use `bun` and `bunx`, not `npm` and `npx`

 ## Architecture
@@ -91,6 +94,41 @@ export function Component({ requiredProp, optionalProp = false }: ComponentProps

 Extract when: 50+ lines, used in 2+ files, or has own state/logic. Keep inline when: < 10 lines, single use, purely presentational.

+## API Route Pattern
+
+Every API route handler must be wrapped with `withRouteHandler`. This sets up `AsyncLocalStorage`-based request context so all loggers in the request lifecycle automatically include the request ID.
+
+```typescript
+import { createLogger } from '@sim/logger'
+import type { NextRequest } from 'next/server'
+import { NextResponse } from 'next/server'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+
+const logger = createLogger('MyAPI')
+
+// Simple route
+export const GET = withRouteHandler(async (request: NextRequest) => {
+  logger.info('Handling request') // automatically includes {requestId=...}
+  return NextResponse.json({ ok: true })
+})
+
+// Route with params
+export const DELETE = withRouteHandler(async (
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) => {
+  const { id } = await params
+  return NextResponse.json({ deleted: id })
+})
+
+// Composing with other middleware (withRouteHandler wraps the outermost layer)
+export const POST = withRouteHandler(withAdminAuth(async (request) => {
+  return NextResponse.json({ ok: true })
+}))
+```
+
+Never export a bare `async function GET/POST/...` — always use `export const METHOD = withRouteHandler(...)`.
+
 ## Hooks

 ```typescript
@@ -134,21 +172,64 @@ Use `devtools` middleware. Use `persist` only when data should survive reload wi

 ## React Query

-All React Query hooks live in `hooks/queries/`.
+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 file must have a hierarchical key factory with an `all` root key and intermediate plural keys for prefix invalidation:

 ```typescript
 export const entityKeys = {
  all: ['entity'] as const,
-  list: (workspaceId?: string) => [...entityKeys.all, 'list', workspaceId ?? ''] 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,
 }
+```

+### Query Hooks
+
+- Every `queryFn` must 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
+
+```typescript
 export function useEntityList(workspaceId?: string) {
  return useQuery({
    queryKey: entityKeys.list(workspaceId),
-    queryFn: () => fetchEntities(workspaceId as string),
+    queryFn: ({ signal }) => fetchEntities(workspaceId as string, signal),
    enabled: Boolean(workspaceId),
    staleTime: 60 * 1000,
-    placeholderData: keepPreviousData,
+    placeholderData: keepPreviousData, // OK: workspaceId varies
+  })
+}
+```
+
+### Mutation Hooks
+
+- Use targeted invalidation (`entityKeys.lists()`) not broad (`entityKeys.all`) when possible
+- For optimistic updates: use `onSettled` (not `onSuccess`) for cache reconciliation — `onSettled` fires on both success and error
+- Don't include mutation objects in `useCallback` deps — `.mutate()` is stable in TanStack Query v5
+
+```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 */)
+      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) })
+    },
  })
 }
 ```
@@ -167,27 +248,51 @@ Import from `@/components/emcn`, never from subpaths (except CSS files). Use CVA

 ## Testing

-Use Vitest. Test files: `feature.ts` → `feature.test.ts`
+Use Vitest. Test files: `feature.ts` → `feature.test.ts`. See `.cursor/rules/sim-testing.mdc` for full details.
+
+### Global Mocks (vitest.setup.ts)
+
+`@sim/db`, `drizzle-orm`, `@sim/logger`, `@/blocks/registry`, `@trigger.dev/sdk`, and store mocks are provided globally. Do NOT re-mock them unless overriding behavior.
+
+### Standard Test Pattern

 ```typescript
 /**
 * @vitest-environment node
 */
-import { databaseMock, loggerMock } from '@sim/testing'
-import { describe, expect, it, vi } from 'vitest'
+import { createMockRequest } from '@sim/testing'
+import { beforeEach, describe, expect, it, vi } from 'vitest'

-vi.mock('@sim/db', () => databaseMock)
-vi.mock('@sim/logger', () => loggerMock)
+const { mockGetSession } = vi.hoisted(() => ({
+  mockGetSession: vi.fn(),
+}))

-import { myFunction } from '@/lib/feature'
+vi.mock('@/lib/auth', () => ({
+  auth: { api: { getSession: vi.fn() } },
+  getSession: mockGetSession,
+}))

-describe('feature', () => {
-  beforeEach(() => vi.clearAllMocks())
-  it.concurrent('runs in parallel', () => { ... })
+import { GET } from '@/app/api/my-route/route'
+
+describe('my route', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockGetSession.mockResolvedValue({ user: { id: 'user-1' } })
+  })
+  it('returns data', async () => { ... })
 })
 ```

-Use `@sim/testing` mocks/factories over local test data. See `.cursor/rules/sim-testing.mdc` for details.
+### Performance Rules
+
+- **NEVER** use `vi.resetModules()` + `vi.doMock()` + `await import()` — use `vi.hoisted()` + `vi.mock()` + static imports
+- **NEVER** use `vi.importActual()` — mock everything explicitly
+- **NEVER** use `mockAuth()`, `mockConsoleLogger()`, `setupCommonApiMocks()` from `@sim/testing` — they use `vi.doMock()` internally
+- **Mock heavy deps** (`@/blocks`, `@/tools/registry`, `@/triggers`) in tests that don't need them
+- **Use `@vitest-environment node`** unless DOM APIs are needed (`window`, `document`, `FormData`)
+- **Avoid real timers** — use 1ms delays or `vi.useFakeTimers()`
+
+Use `@sim/testing` mocks/factories over local test data.

 ## Utils Rules

--- a/README.md
+++ b/README.md
@@ -1,16 +1,20 @@
 <p align="center">
  <a href="https://sim.ai" target="_blank" rel="noopener noreferrer">
-    <img src="apps/sim/public/logo/reverse/text/large.png" alt="Sim Logo" width="500"/>
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="apps/sim/public/logo/wordmark.svg">
+      <source media="(prefers-color-scheme: light)" srcset="apps/sim/public/logo/wordmark-dark.svg">
+      <img src="apps/sim/public/logo/wordmark-dark.svg" alt="Sim Logo" width="380"/>
+    </picture>
  </a>
 </p>

-<p align="center">Build and deploy AI agent workflows in minutes.</p>
+<p align="center">The open-source platform to build AI agents and run your agentic workforce. Connect 1,000+ integrations and LLMs to orchestrate agentic workflows.</p>

 <p align="center">
-  <a href="https://sim.ai" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/sim.ai-6F3DFA" alt="Sim.ai"></a>
+  <a href="https://sim.ai" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/sim.ai-33c482" alt="Sim.ai"></a>
  <a href="https://discord.gg/Hr4UWYEcTT" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/Discord-Join%20Server-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
  <a href="https://x.com/simdotai" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/twitter/follow/simdotai?style=social" alt="Twitter"></a>
-  <a href="https://docs.sim.ai" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/Docs-6F3DFA.svg" alt="Documentation"></a>
+  <a href="https://docs.sim.ai" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/Docs-33c482.svg" alt="Documentation"></a>
 </p>

 <p align="center">
@@ -42,7 +46,7 @@ Upload documents to a vector store and let agents answer questions grounded in y

 ### Cloud-hosted: [sim.ai](https://sim.ai)

-<a href="https://sim.ai" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/sim.ai-6F3DFA?logo=data:image/svg%2bxml;base64,PHN2ZyB3aWR0aD0iNjE2IiBoZWlnaHQ9IjYxNiIgdmlld0JveD0iMCAwIDYxNiA2MTYiIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+CjxnIGNsaXAtcGF0aD0idXJsKCNjbGlwMF8xMTU5XzMxMykiPgo8cGF0aCBkPSJNNjE2IDBIMFY2MTZINjE2VjBaIiBmaWxsPSIjNkYzREZBIi8+CjxwYXRoIGQ9Ik04MyAzNjUuNTY3SDExM0MxMTMgMzczLjgwNSAxMTYgMzgwLjM3MyAxMjIgMzg1LjI3MkMxMjggMzg5Ljk0OCAxMzYuMTExIDM5Mi4yODUgMTQ2LjMzMyAzOTIuMjg1QzE1Ny40NDQgMzkyLjI4NSAxNjYgMzkwLjE3MSAxNzIgMzg1LjkzOUMxNzcuOTk5IDM4MS40ODcgMTgxIDM3NS41ODYgMTgxIDM2OC4yMzlDMTgxIDM2Mi44OTUgMTc5LjMzMyAzNTguNDQyIDE3NiAzNTQuODhDMTcyLjg4OSAzNTEuMzE4IDE2Ny4xMTEgMzQ4LjQyMiAxNTguNjY3IDM0Ni4xOTZMMTMwIDMzOS41MTdDMTE1LjU1NSAzMzUuOTU1IDEwNC43NzggMzMwLjQ5OSA5Ny42NjY1IDMyMy4xNTFDOTAuNzc3NSAzMTUuODA0IDg3LjMzMzQgMzA2LjExOSA4Ny4zMzM0IDI5NC4wOTZDODcuMzMzNCAyODQuMDc2IDg5Ljg4OSAyNzUuMzkyIDk0Ljk5OTYgMjY4LjA0NUMxMDAuMzMzIDI2MC42OTcgMTA3LjU1NSAyNTUuMDIgMTE2LjY2NiAyNTEuMDEyQzEyNiAyNDcuMDA0IDEzNi42NjcgMjQ1IDE0OC42NjYgMjQ1QzE2MC42NjcgMjQ1IDE3MSAyNDcuMTE2IDE3OS42NjcgMjUxLjM0NkMxODguNTU1IDI1NS41NzYgMTk1LjQ0NCAyNjEuNDc3IDIwMC4zMzMgMjY5LjA0N0MyMDUuNDQ0IDI3Ni42MTcgMjA4LjExMSAyODUuNjM0IDIwOC4zMzMgMjk2LjA5OUgxNzguMzMzQzE3OC4xMTEgMjg3LjYzOCAxNzUuMzMzIDI4MS4wNyAxNjkuOTk5IDI3Ni4zOTRDMTY0LjY2NiAyNzEuNzE5IDE1Ny4yMjIgMjY5LjM4MSAxNDcuNjY3IDI2OS4zODFDMTM3Ljg4OSAyNjkuMzgxIDEzMC4zMzMgMjcxLjQ5NiAxMjUgMjc1LjcyNkMxMTkuNjY2IDI3OS45NTcgMTE3IDI4NS43NDYgMTE3IDI5My4wOTNDMTE3IDMwNC4wMDMgMTI1IDMxMS40NjIgMTQxIDMxNS40N0wxNjkuNjY3IDMyMi40ODNDMTgzLjQ0NSAzMjUuNiAxOTMuNzc4IDMzMC43MjIgMjAwLjY2NyAzMzcuODQ3QzIwNy41NTUgMzQ0Ljc0OSAyMTEgMzU0LjIxMiAyMTEgMzY2LjIzNUMyMTEgMzc2LjQ3NyAyMDguMjIyIDM4NS40OTQgMjAyLjY2NiAzOTMuMjg3QzE5Ny4xMTEgNDAwLjg1NyAxODkuNDQ0IDQwNi43NTggMTc5LjY2NyA0MTAuOTg5QzE3MC4xMTEgNDE0Ljk5NiAxNTguNzc4IDQxNyAxNDUuNjY3IDQxN0MxMjYuNTU1IDQxNyAxMTEuMzMzIDQxMi4zMjUgOTkuOTk5NyA0MDIuOTczQzg4LjY2NjggMzkzLjYyMSA4MyAzODEuMTUzIDgzIDM2NS41NjdaIiBmaWxsPSJ3aGl0ZSIvPgo8cGF0aCBkPSJNMjMyLjI5MSA0MTNWMjUwLjA4MkMyNDQuNjg0IDI1NC42MTQgMjUwLjE0OCAyNTQuNjE0IDI2My4zNzEgMjUwLjA4MlY0MTNIMjMyLjI5MVpNMjQ3LjUgMjM5LjMxM0MyNDEuOTkgMjM5LjMxMyAyMzcuMTQgMjM3LjMxMyAyMzIuOTUyIDIzMy4zMTZDMjI4Ljk4NCAyMjkuMDk1IDIyNyAyMjQuMjA5IDIyNyAyMTguNjU2QzIyNyAyMTIuODgyIDIyOC45ODQgMjA3Ljk5NSAyMzIuOTUyIDIwMy45OTdDMjM3LjE0IDE5OS45OTkgMjQxLjk5IDE5OCAyNDcuNSAxOThDMjUzLjIzMSAxOTggMjU4LjA4IDE5OS45OTkgMjYyLjA0OSAyMDMuOTk3QzI2Ni4wMTYgMjA3Ljk5NSAyNjggMjEyLjg4MiAyNjggMjE4LjY1NkMyNjggMjI0LjIwOSAyNjYuMDE2IDIyOS4wOTUgMjYyLjA0OSAyMzMuMzE2QzI1OC4wOCAyMzcuMzEzIDI1My4yMzEgMjM5LjMxMyAyNDcuNSAyMzkuMzEzWiIgZmlsbD0id2hpdGUiLz4KPHBhdGggZD0iTTMxOS4zMzMgNDEzSDI4OFYyNDkuNjc2SDMxNlYyNzcuMjMzQzMxOS4zMzMgMjY4LjEwNCAzMjUuNzc4IDI2MC4zNjQgMzM0LjY2NyAyNTQuMzUyQzM0My43NzggMjQ4LjExNyAzNTQuNzc4IDI0NSAzNjcuNjY3IDI0NUMzODIuMTExIDI0NSAzOTQuMTEyIDI0OC44OTcgNDAzLjY2NyAyNTYuNjlDNDEzLjIyMiAyNjQuNDg0IDQxOS40NDQgMjc0LjgzNyA0MjIuMzM0IDI4Ny43NTJINDE2LjY2N0M0MTguODg5IDI3NC44MzcgNDI1IDI2NC40ODQgNDM1IDI1Ni42OUM0NDUgMjQ4Ljg5NyA0NTcuMzM0IDI0NSA0NzIgMjQ1QzQ5MC42NjYgMjQ1IDUwNS4zMzQgMjUwLjQ1NSA1MTYgMjYxLjM2NkM1MjYuNjY3IDI3Mi4yNzYgNTMyIDI4Ny4xOTUgNTMyIDMwNi4xMjFWNDEzSDUwMS4zMzNWMzEzLjgwNEM1MDEuMzMzIDMwMC44ODkgNDk4IDI5MC45ODEgNDkxLjMzMyAyODQuMDc4QzQ4NC44ODkgMjc2Ljk1MiA0NzYuMTExIDI3My4zOSA0NjUgMjczLjM5QzQ1Ny4yMjIgMjczLjM5IDQ1MC4zMzMgMjc1LjE3MSA0NDQuMzM0IDI3OC43MzRDNDM4LjU1NiAyODIuMDc0IDQzNCAyODYuOTcyIDQzMC42NjcgMjkzLjQzQzQyNy4zMzMgMjk5Ljg4NyA0MjUuNjY3IDMwNy40NTcgNDI1LjY2NyAzMTYuMTQxVjQxM0gzOTQuNjY3VjMxMy40NjlDMzk0LjY2NyAzMDAuNTU1IDM5MS40NDUgMjkwLjc1OCAzODUgMjg0LjA3OEMzNzguNTU2IDI3Ny4xNzUgMzY5Ljc3OCAyNzMuNzI0IDM1OC42NjcgMjczLjcyNEMzNTAuODg5IDI3My43MjQgMzQ0IDI3NS41MDUgMzM4IDI3OS4wNjhDMzMyLjIyMiAyODIuNDA4IDMyNy42NjcgMjg3LjMwNyAzMjQuMzMzIDI5My43NjNDMzIxIDI5OS45OTggMzE5LjMzMyAzMDcuNDU3IDMxOS4zMzMgMzE2LjE0MVY0MTNaIiBmaWxsPSJ3aGl0ZSIvPgo8L2c+CjxkZWZzPgo8Y2xpcFBhdGggaWQ9ImNsaXAwXzExNTlfMzEzIj4KPHJlY3Qgd2lkdGg9IjYxNiIgaGVpZ2h0PSI2MTYiIGZpbGw9IndoaXRlIi8+CjwvY2xpcFBhdGg+CjwvZGVmcz4KPC9zdmc+Cg==&logoColor=white" alt="Sim.ai"></a>
+<a href="https://sim.ai" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/sim.ai-33c482?logo=data:image/svg%2bxml;base64,PHN2ZyB3aWR0aD0iNjE2IiBoZWlnaHQ9IjYxNiIgdmlld0JveD0iMCAwIDYxNiA2MTYiIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+CjxnIGNsaXAtcGF0aD0idXJsKCNjbGlwMF8xMTU5XzMxMykiPgo8cGF0aCBkPSJNNjE2IDBIMFY2MTZINjE2VjBaIiBmaWxsPSIjMzNjNDgyIi8+CjxwYXRoIGQ9Ik04MyAzNjUuNTY3SDExM0MxMTMgMzczLjgwNSAxMTYgMzgwLjM3MyAxMjIgMzg1LjI3MkMxMjggMzg5Ljk0OCAxMzYuMTExIDM5Mi4yODUgMTQ2LjMzMyAzOTIuMjg1QzE1Ny40NDQgMzkyLjI4NSAxNjYgMzkwLjE3MSAxNzIgMzg1LjkzOUMxNzcuOTk5IDM4MS40ODcgMTgxIDM3NS41ODYgMTgxIDM2OC4yMzlDMTgxIDM2Mi44OTUgMTc5LjMzMyAzNTguNDQyIDE3NiAzNTQuODhDMTcyLjg4OSAzNTEuMzE4IDE2Ny4xMTEgMzQ4LjQyMiAxNTguNjY3IDM0Ni4xOTZMMTMwIDMzOS41MTdDMTE1LjU1NSAzMzUuOTU1IDEwNC43NzggMzMwLjQ5OSA5Ny42NjY1IDMyMy4xNTFDOTAuNzc3NSAzMTUuODA0IDg3LjMzMzQgMzA2LjExOSA4Ny4zMzM0IDI5NC4wOTZDODcuMzMzNCAyODQuMDc2IDg5Ljg4OSAyNzUuMzkyIDk0Ljk5OTYgMjY4LjA0NUMxMDAuMzMzIDI2MC42OTcgMTA3LjU1NSAyNTUuMDIgMTE2LjY2NiAyNTEuMDEyQzEyNiAyNDcuMDA0IDEzNi42NjcgMjQ1IDE0OC42NjYgMjQ1QzE2MC42NjcgMjQ1IDE3MSAyNDcuMTE2IDE3OS42NjcgMjUxLjM0NkMxODguNTU1IDI1NS41NzYgMTk1LjQ0NCAyNjEuNDc3IDIwMC4zMzMgMjY5LjA0N0MyMDUuNDQ0IDI3Ni42MTcgMjA4LjExMSAyODUuNjM0IDIwOC4zMzMgMjk2LjA5OUgxNzguMzMzQzE3OC4xMTEgMjg3LjYzOCAxNzUuMzMzIDI4MS4wNyAxNjkuOTk5IDI3Ni4zOTRDMTY0LjY2NiAyNzEuNzE5IDE1Ny4yMjIgMjY5LjM4MSAxNDcuNjY3IDI2OS4zODFDMTM3Ljg4OSAyNjkuMzgxIDEzMC4zMzMgMjcxLjQ5NiAxMjUgMjc1LjcyNkMxMTkuNjY2IDI3OS45NTcgMTE3IDI4NS43NDYgMTE3IDI5My4wOTNDMTE3IDMwNC4wMDMgMTI1IDMxMS40NjIgMTQxIDMxNS40N0wxNjkuNjY3IDMyMi40ODNDMTgzLjQ0NSAzMjUuNiAxOTMuNzc4IDMzMC43MjIgMjAwLjY2NyAzMzcuODQ3QzIwNy41NTUgMzQ0Ljc0OSAyMTEgMzU0LjIxMiAyMTEgMzY2LjIzNUMyMTEgMzc2LjQ3NyAyMDguMjIyIDM4NS40OTQgMjAyLjY2NiAzOTMuMjg3QzE5Ny4xMTEgNDAwLjg1NyAxODkuNDQ0IDQwNi43NTggMTc5LjY2NyA0MTAuOTg5QzE3MC4xMTEgNDE0Ljk5NiAxNTguNzc4IDQxNyAxNDUuNjY3IDQxN0MxMjYuNTU1IDQxNyAxMTEuMzMzIDQxMi4zMjUgOTkuOTk5NyA0MDIuOTczQzg4LjY2NjggMzkzLjYyMSA4MyAzODEuMTUzIDgzIDM2NS41NjdaIiBmaWxsPSJ3aGl0ZSIvPgo8cGF0aCBkPSJNMjMyLjI5MSA0MTNWMjUwLjA4MkMyNDQuNjg0IDI1NC42MTQgMjUwLjE0OCAyNTQuNjE0IDI2My4zNzEgMjUwLjA4MlY0MTNIMjMyLjI5MVpNMjQ3LjUgMjM5LjMxM0MyNDEuOTkgMjM5LjMxMyAyMzcuMTQgMjM3LjMxMyAyMzIuOTUyIDIzMy4zMTZDMjI4Ljk4NCAyMjkuMDk1IDIyNyAyMjQuMjA5IDIyNyAyMTguNjU2QzIyNyAyMTIuODgyIDIyOC45ODQgMjA3Ljk5NSAyMzIuOTUyIDIwMy45OTdDMjM3LjE0IDE5OS45OTkgMjQxLjk5IDE5OCAyNDcuNSAxOThDMjUzLjIzMSAxOTggMjU4LjA4IDE5OS45OTkgMjYyLjA0OSAyMDMuOTk3QzI2Ni4wMTYgMjA3Ljk5NSAyNjggMjEyLjg4MiAyNjggMjE4LjY1NkMyNjggMjI0LjIwOSAyNjYuMDE2IDIyOS4wOTUgMjYyLjA0OSAyMzMuMzE2QzI1OC4wOCAyMzcuMzEzIDI1My4yMzEgMjM5LjMxMyAyNDcuNSAyMzkuMzEzWiIgZmlsbD0id2hpdGUiLz4KPHBhdGggZD0iTTMxOS4zMzMgNDEzSDI4OFYyNDkuNjc2SDMxNlYyNzcuMjMzQzMxOS4zMzMgMjY4LjEwNCAzMjUuNzc4IDI2MC4zNjQgMzM0LjY2NyAyNTQuMzUyQzM0My43NzggMjQ4LjExNyAzNTQuNzc4IDI0NSAzNjcuNjY3IDI0NUMzODIuMTExIDI0NSAzOTQuMTEyIDI0OC44OTcgNDAzLjY2NyAyNTYuNjlDNDEzLjIyMiAyNjQuNDg0IDQxOS40NDQgMjc0LjgzNyA0MjIuMzM0IDI4Ny43NTJINDE2LjY2N0M0MTguODg5IDI3NC44MzcgNDI1IDI2NC40ODQgNDM1IDI1Ni42OUM0NDUgMjQ4Ljg5NyA0NTcuMzM0IDI0NSA0NzIgMjQ1QzQ5MC42NjYgMjQ1IDUwNS4zMzQgMjUwLjQ1NSA1MTYgMjYxLjM2NkM1MjYuNjY3IDI3Mi4yNzYgNTMyIDI4Ny4xOTUgNTMyIDMwNi4xMjFWNDEzSDUwMS4zMzNWMzEzLjgwNEM1MDEuMzMzIDMwMC44ODkgNDk4IDI5MC45ODEgNDkxLjMzMyAyODQuMDc4QzQ4NC44ODkgMjc2Ljk1MiA0NzYuMTExIDI3My4zOSA0NjUgMjczLjM5QzQ1Ny4yMjIgMjczLjM5IDQ1MC4zMzMgMjc1LjE3MSA0NDQuMzM0IDI3OC43MzRDNDM4LjU1NiAyODIuMDc0IDQzNCAyODYuOTcyIDQzMC42NjcgMjkzLjQzQzQyNy4zMzMgMjk5Ljg4NyA0MjUuNjY3IDMwNy40NTcgNDI1LjY2NyAzMTYuMTQxVjQxM0gzOTQuNjY3VjMxMy40NjlDMzk0LjY2NyAzMDAuNTU1IDM5MS40NDUgMjkwLjc1OCAzODUgMjg0LjA3OEMzNzguNTU2IDI3Ny4xNzUgMzY5Ljc3OCAyNzMuNzI0IDM1OC42NjcgMjczLjcyNEMzNTAuODg5IDI3My43MjQgMzQ0IDI3NS41MDUgMzM4IDI3OS4wNjhDMzMyLjIyMiAyODIuNDA4IDMyNy42NjcgMjg3LjMwNyAzMjQuMzMzIDI5My43NjNDMzIxIDI5OS45OTggMzE5LjMzMyAzMDcuNDU3IDMxOS4zMzMgMzE2LjE0MVY0MTNaIiBmaWxsPSJ3aGl0ZSIvPgo8L2c+CjxkZWZzPgo8Y2xpcFBhdGggaWQ9ImNsaXAwXzExNTlfMzEzIj4KPHJlY3Qgd2lkdGg9IjYxNiIgaGVpZ2h0PSI2MTYiIGZpbGw9IndoaXRlIi8+CjwvY2xpcFBhdGg+CjwvZGVmcz4KPC9zdmc+&logoColor=white" alt="Sim.ai"></a>

 ### Self-hosted: NPM Package

@@ -70,43 +74,7 @@ docker compose -f docker-compose.prod.yml up -d

 Open [http://localhost:3000](http://localhost:3000)

-#### Using Local Models with Ollama
-
-Run Sim with local AI models using [Ollama](https://ollama.ai) - no external APIs required:
-
-```bash
-# Start with GPU support (automatically downloads gemma3:4b model)
-docker compose -f docker-compose.ollama.yml --profile setup up -d
-
-# For CPU-only systems:
-docker compose -f docker-compose.ollama.yml --profile cpu --profile setup up -d
-```
-
-Wait for the model to download, then visit [http://localhost:3000](http://localhost:3000). Add more models with:
-```bash
-docker compose -f docker-compose.ollama.yml exec ollama ollama pull llama3.1:8b
-```
-
-#### Using an External Ollama Instance
-
-If Ollama is running on your host machine, use `host.docker.internal` instead of `localhost`:
-
-```bash
-OLLAMA_URL=http://host.docker.internal:11434 docker compose -f docker-compose.prod.yml up -d
-```
-
-On Linux, use your host's IP address or add `extra_hosts: ["host.docker.internal:host-gateway"]` to the compose file.
-
-#### Using vLLM
-
-Sim supports [vLLM](https://docs.vllm.ai/) for self-hosted models. Set `VLLM_BASE_URL` and optionally `VLLM_API_KEY` in your environment.
-
-### Self-hosted: Dev Containers
-
-1. Open VS Code with the [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
-2. Open the project and click "Reopen in Container" when prompted
-3. Run `bun run dev:full` in the terminal or use the `sim-start` alias
-   - This starts both the main application and the realtime socket server
+Sim also supports local models via [Ollama](https://ollama.ai) and [vLLM](https://docs.vllm.ai/) — see the [Docker self-hosting docs](https://docs.sim.ai/self-hosting/docker) for setup details.

 ### Self-hosted: Manual Setup

@@ -118,6 +86,7 @@ Sim supports [vLLM](https://docs.vllm.ai/) for self-hosted models. Set `VLLM_BAS
 git clone https://github.com/simstudioai/sim.git
 cd sim
 bun install
+bun run prepare  # Set up pre-commit hooks
 ```

 2. Set up PostgreSQL with pgvector:
@@ -132,6 +101,11 @@ Or install manually via the [pgvector guide](https://github.com/pgvector/pgvecto

 ```bash
 cp apps/sim/.env.example apps/sim/.env
+# Create your secrets
+perl -i -pe "s/your_encryption_key/$(openssl rand -hex 32)/" apps/sim/.env
+perl -i -pe "s/your_internal_api_secret/$(openssl rand -hex 32)/" apps/sim/.env
+perl -i -pe "s/your_api_encryption_key/$(openssl rand -hex 32)/" apps/sim/.env
+# DB configs for migration
 cp packages/db/.env.example packages/db/.env
 # Edit both .env files to set DATABASE_URL="postgresql://postgres:your_password@localhost:5432/simstudio"
 ```
@@ -139,13 +113,13 @@ cp packages/db/.env.example packages/db/.env
 4. Run migrations:

 ```bash
-cd packages/db && bunx drizzle-kit migrate --config=./drizzle.config.ts
+cd packages/db && bun run db:migrate
 ```

 5. Start development servers:

 ```bash
-bun run dev:full  # Starts both Next.js app and realtime socket server
+bun run dev:full  # Starts Next.js app and realtime socket server
 ```

 Or run separately: `bun run dev` (Next.js) and `cd apps/sim && bun run dev:sockets` (realtime).
@@ -159,18 +133,7 @@ Copilot is a Sim-managed service. To use Copilot on a self-hosted instance:

 ## Environment Variables

-Key environment variables for self-hosted deployments. See [`.env.example`](apps/sim/.env.example) for defaults or [`env.ts`](apps/sim/lib/core/config/env.ts) for the full list.
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `DATABASE_URL` | Yes | PostgreSQL connection string with pgvector |
-| `BETTER_AUTH_SECRET` | Yes | Auth secret (`openssl rand -hex 32`) |
-| `BETTER_AUTH_URL` | Yes | Your app URL (e.g., `http://localhost:3000`) |
-| `NEXT_PUBLIC_APP_URL` | Yes | Public app URL (same as above) |
-| `ENCRYPTION_KEY` | Yes | Encrypts environment variables (`openssl rand -hex 32`) |
-| `INTERNAL_API_SECRET` | Yes | Encrypts internal API routes (`openssl rand -hex 32`) |
-| `API_ENCRYPTION_KEY` | Yes | Encrypts API keys (`openssl rand -hex 32`) |
-| `COPILOT_API_KEY` | No | API key from sim.ai for Copilot features |
+See the [environment variables reference](https://docs.sim.ai/self-hosting/environment-variables) for the full list, or [`apps/sim/.env.example`](apps/sim/.env.example) for defaults.

 ## Tech Stack

@@ -179,13 +142,15 @@ Key environment variables for self-hosted deployments. See [`.env.example`](apps
 - **Database**: PostgreSQL with [Drizzle ORM](https://orm.drizzle.team)
 - **Authentication**: [Better Auth](https://better-auth.com)
 - **UI**: [Shadcn](https://ui.shadcn.com/), [Tailwind CSS](https://tailwindcss.com)
- **State Management**: [Zustand](https://zustand-demo.pmnd.rs/)
+- **Streaming Markdown**: [Streamdown](https://github.com/vercel/streamdown)
+- **State Management**: [Zustand](https://zustand-demo.pmnd.rs/), [TanStack Query](https://tanstack.com/query)
 - **Flow Editor**: [ReactFlow](https://reactflow.dev/)
 - **Docs**: [Fumadocs](https://fumadocs.vercel.app/)
 - **Monorepo**: [Turborepo](https://turborepo.org/)
 - **Realtime**: [Socket.io](https://socket.io/)
 - **Background Jobs**: [Trigger.dev](https://trigger.dev/)
 - **Remote Code Execution**: [E2B](https://www.e2b.dev/)
+- **Isolated Code Execution**: [isolated-vm](https://github.com/laverdet/isolated-vm)

 ## Contributing

--- a/apps/docs/app/[lang]/[[...slug]]/page.tsx
+++ b/apps/docs/app/[lang]/[[...slug]]/page.tsx
@@ -1,39 +1,97 @@
 import type React from 'react'
+import type { Root } from 'fumadocs-core/page-tree'
 import { findNeighbour } from 'fumadocs-core/page-tree'
+import type { ApiPageProps } from 'fumadocs-openapi/ui'
+import { createAPIPage } from 'fumadocs-openapi/ui'
 import { Pre } from 'fumadocs-ui/components/codeblock'
 import defaultMdxComponents from 'fumadocs-ui/mdx'
 import { DocsBody, DocsDescription, DocsPage, DocsTitle } from 'fumadocs-ui/page'
-import { ChevronLeft, ChevronRight } from 'lucide-react'
-import Link from 'next/link'
 import { notFound } from 'next/navigation'
+import { PageFooter } from '@/components/docs-layout/page-footer'
 import { PageNavigationArrows } from '@/components/docs-layout/page-navigation-arrows'
-import { TOCFooter } from '@/components/docs-layout/toc-footer'
 import { LLMCopyButton } from '@/components/page-actions'
 import { StructuredData } from '@/components/structured-data'
 import { CodeBlock } from '@/components/ui/code-block'
 import { Heading } from '@/components/ui/heading'
+import { ResponseSection } from '@/components/ui/response-section'
+import { i18n } from '@/lib/i18n'
+import { getApiSpecContent, openapi } from '@/lib/openapi'
 import { type PageData, source } from '@/lib/source'
+import { DOCS_BASE_URL } from '@/lib/urls'
+
+const SUPPORTED_LANGUAGES: Set<string> = new Set(i18n.languages)
+const BASE_URL = DOCS_BASE_URL
+
+const OG_LOCALE_MAP: Record<string, string> = {
+  en: 'en_US',
+  es: 'es_ES',
+  fr: 'fr_FR',
+  de: 'de_DE',
+  ja: 'ja_JP',
+  zh: 'zh_CN',
+}
+
+function resolveLangAndSlug(params: { slug?: string[]; lang: string }) {
+  const isValidLang = SUPPORTED_LANGUAGES.has(params.lang)
+  const lang = isValidLang ? params.lang : 'en'
+  const slug = isValidLang ? params.slug : [params.lang, ...(params.slug ?? [])]
+  return { lang, slug }
+}
+
+const APIPage = createAPIPage(openapi, {
+  playground: { enabled: false },
+  content: {
+    renderOperationLayout: async (slots) => {
+      return (
+        <div className='flex @4xl:flex-row flex-col @4xl:items-start gap-x-6 gap-y-4'>
+          <div className='min-w-0 flex-1'>
+            {slots.header}
+            {slots.apiPlayground}
+            {slots.authSchemes && <div className='api-section-divider'>{slots.authSchemes}</div>}
+            {slots.paremeters}
+            {slots.body && <div className='api-section-divider'>{slots.body}</div>}
+            <ResponseSection>{slots.responses}</ResponseSection>
+            {slots.callbacks}
+          </div>
+          <div className='@4xl:sticky @4xl:top-[calc(var(--fd-docs-row-1,2rem)+1rem)] @4xl:w-[400px]'>
+            {slots.apiExample}
+          </div>
+        </div>
+      )
+    },
+  },
+})

 export default async function Page(props: { params: Promise<{ slug?: string[]; lang: string }> }) {
  const params = await props.params
-  const page = source.getPage(params.slug, params.lang)
+  const { lang, slug } = resolveLangAndSlug(params)
+  const page = source.getPage(slug, lang)
  if (!page) notFound()

-  const data = page.data as PageData
-  const MDX = data.body
-  const baseUrl = 'https://docs.sim.ai'
-  const markdownContent = await data.getText('processed')
+  const data = page.data as unknown as PageData & {
+    _openapi?: { method?: string }
+    getAPIPageProps?: () => ApiPageProps
+  }
+  const isOpenAPI = '_openapi' in data && data._openapi != null
+  const isApiReference = slug?.some((s) => s === 'api-reference') ?? false

-  const pageTreeRecord = source.pageTree as Record<string, any>
-  const pageTree =
-    pageTreeRecord[params.lang] ?? pageTreeRecord.en ?? Object.values(pageTreeRecord)[0]
-  const neighbours = pageTree ? findNeighbour(pageTree, page.url) : null
+  const pageTreeRecord = source.pageTree as Record<string, Root>
+  const pageTree = pageTreeRecord[lang] ?? pageTreeRecord.en ?? Object.values(pageTreeRecord)[0]
+  const rawNeighbours = pageTree ? findNeighbour(pageTree, page.url) : null
+  const neighbours = isApiReference
+    ? {
+        previous: rawNeighbours?.previous?.url.includes('/api-reference/')
+          ? rawNeighbours.previous
+          : undefined,
+        next: rawNeighbours?.next?.url.includes('/api-reference/') ? rawNeighbours.next : undefined,
+      }
+    : rawNeighbours

  const generateBreadcrumbs = () => {
    const breadcrumbs: Array<{ name: string; url: string }> = [
      {
        name: 'Home',
-        url: baseUrl,
+        url: BASE_URL,
      },
    ]

@@ -41,7 +99,7 @@ export default async function Page(props: { params: Promise<{ slug?: string[]; l
    let currentPath = ''

    urlParts.forEach((part, index) => {
-      if (index === 0 && ['en', 'es', 'fr', 'de', 'ja', 'zh'].includes(part)) {
+      if (index === 0 && SUPPORTED_LANGUAGES.has(part)) {
        currentPath = `/${part}`
        return
      }
@@ -56,12 +114,12 @@ export default async function Page(props: { params: Promise<{ slug?: string[]; l
      if (index === urlParts.length - 1) {
        breadcrumbs.push({
          name: data.title,
-          url: `${baseUrl}${page.url}`,
+          url: `${BASE_URL}${page.url}`,
        })
      } else {
        breadcrumbs.push({
          name: name,
-          url: `${baseUrl}${currentPath}`,
+          url: `${BASE_URL}${currentPath}`,
        })
      }
    })
@@ -70,112 +128,71 @@ export default async function Page(props: { params: Promise<{ slug?: string[]; l
  }

  const breadcrumbs = generateBreadcrumbs()
+  const footer = <PageFooter previous={neighbours?.previous} next={neighbours?.next} />

-  const CustomFooter = () => (
-    <div className='mt-12'>
-      {/* Navigation links */}
-      <div className='flex items-center justify-between py-8'>
-        {neighbours?.previous ? (
-          <Link
-            href={neighbours.previous.url}
-            className='group flex items-center gap-2 text-muted-foreground transition-colors hover:text-foreground'
-          >
-            <ChevronLeft className='group-hover:-translate-x-1 h-4 w-4 transition-transform' />
-            <span className='font-medium'>{neighbours.previous.name}</span>
-          </Link>
-        ) : (
-          <div />
-        )}
+  if (isOpenAPI && data.getAPIPageProps) {
+    const apiProps = data.getAPIPageProps()
+    const apiPageContent = getApiSpecContent(
+      data.title,
+      data.description,
+      apiProps.operations ?? []
+    )

-        {neighbours?.next ? (
-          <Link
-            href={neighbours.next.url}
-            className='group flex items-center gap-2 text-muted-foreground transition-colors hover:text-foreground'
-          >
-            <span className='font-medium'>{neighbours.next.name}</span>
-            <ChevronRight className='h-4 w-4 transition-transform group-hover:translate-x-1' />
-          </Link>
-        ) : (
-          <div />
-        )}
-      </div>
-
-      {/* Divider line */}
-      <div className='border-border border-t' />
-
-      {/* Social icons */}
-      <div className='flex items-center gap-4 py-6'>
-        <Link
-          href='https://x.com/simdotai'
-          target='_blank'
-          rel='noopener noreferrer'
-          aria-label='X (Twitter)'
+    return (
+      <>
+        <StructuredData
+          title={data.title}
+          description={data.description || ''}
+          url={`${BASE_URL}${page.url}`}
+          lang={lang}
+          breadcrumb={breadcrumbs}
+        />
+        <DocsPage
+          toc={data.toc}
+          breadcrumb={{
+            enabled: false,
+          }}
+          tableOfContent={{
+            style: 'clerk',
+            enabled: false,
+          }}
+          tableOfContentPopover={{
+            style: 'clerk',
+            enabled: false,
+          }}
+          footer={{
+            enabled: true,
+            component: footer,
+          }}
        >
-          <div
-            className='h-5 w-5 bg-gray-400 transition-colors hover:bg-gray-500 dark:bg-gray-500 dark:hover:bg-gray-400'
-            style={{
-              maskImage:
-                "url('data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 24 24%22%3E%3Cpath d=%22M18.244 2.25h3.308l-7.227 8.26 8.502 11.24H16.17l-5.214-6.817L4.99 21.75H1.68l7.73-8.835L1.254 2.25H8.08l4.713 6.231zm-1.161 17.52h1.833L7.084 4.126H5.117z%22/%3E%3C/svg%3E')",
-              maskRepeat: 'no-repeat',
-              maskPosition: 'center center',
-              WebkitMaskImage:
-                "url('data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 24 24%22%3E%3Cpath d=%22M18.244 2.25h3.308l-7.227 8.26 8.502 11.24H16.17l-5.214-6.817L4.99 21.75H1.68l7.73-8.835L1.254 2.25H8.08l4.713 6.231zm-1.161 17.52h1.833L7.084 4.126H5.117z%22/%3E%3C/svg%3E')",
-              WebkitMaskRepeat: 'no-repeat',
-              WebkitMaskPosition: 'center center',
-            }}
-          />
-        </Link>
-        <Link
-          href='https://github.com/simstudioai/sim'
-          target='_blank'
-          rel='noopener noreferrer'
-          aria-label='GitHub'
-        >
-          <div
-            className='h-5 w-5 bg-gray-400 transition-colors hover:bg-gray-500 dark:bg-gray-500 dark:hover:bg-gray-400'
-            style={{
-              maskImage:
-                "url('data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 24 24%22%3E%3Cpath d=%22M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z%22/%3E%3C/svg%3E')",
-              maskRepeat: 'no-repeat',
-              maskPosition: 'center center',
-              WebkitMaskImage:
-                "url('data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 24 24%22%3E%3Cpath d=%22M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z%22/%3E%3C/svg%3E')",
-              WebkitMaskRepeat: 'no-repeat',
-              WebkitMaskPosition: 'center center',
-            }}
-          />
-        </Link>
-        <Link
-          href='https://discord.gg/Hr4UWYEcTT'
-          target='_blank'
-          rel='noopener noreferrer'
-          aria-label='Discord'
-        >
-          <div
-            className='h-5 w-5 bg-gray-400 transition-colors hover:bg-gray-500 dark:bg-gray-500 dark:hover:bg-gray-400'
-            style={{
-              maskImage:
-                "url('data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 24 24%22%3E%3Cpath d=%22M20.317 4.37a19.791 19.791 0 0 0-4.885-1.515a.074.074 0 0 0-.079.037c-.21.375-.444.864-.608 1.25a18.27 18.27 0 0 0-5.487 0a12.64 12.64 0 0 0-.617-1.25a.077.077 0 0 0-.079-.037A19.736 19.736 0 0 0 3.677 4.37a.07.07 0 0 0-.032.027C.533 9.046-.32 13.58.099 18.057a.082.082 0 0 0 .031.057a19.9 19.9 0 0 0 5.993 3.03a.078.078 0 0 0 .084-.028a14.09 14.09 0 0 0 1.226-1.994a.076.076 0 0 0-.041-.106a13.107 13.107 0 0 1-1.872-.892a.077.077 0 0 1-.008-.128a10.2 10.2 0 0 0 .372-.292a.074.074 0 0 1 .077-.01c3.928 1.793 8.18 1.793 12.062 0a.074.074 0 0 1 .078.01c.12.098.246.198.373.292a.077.077 0 0 1-.006.127a12.299 12.299 0 0 1-1.873.892a.077.077 0 0 0-.041.107c.36.698.772 1.362 1.225 1.993a.076.076 0 0 0 .084.028a19.839 19.839 0 0 0 6.002-3.03a.077.077 0 0 0 .032-.054c.5-5.177-.838-9.674-3.549-13.66a.061.061 0 0 0-.031-.03zM8.02 15.33c-1.183 0-2.157-1.085-2.157-2.419c0-1.333.956-2.419 2.157-2.419c1.21 0 2.176 1.096 2.157 2.42c0 1.333-.956 2.418-2.157 2.418zm7.975 0c-1.183 0-2.157-1.085-2.157-2.419c0-1.333.955-2.419 2.157-2.419c1.21 0 2.176 1.096 2.157 2.42c0 1.333-.946 2.418-2.157 2.418z%22/%3E%3C/svg%3E')",
-              maskRepeat: 'no-repeat',
-              maskPosition: 'center center',
-              WebkitMaskImage:
-                "url('data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 24 24%22%3E%3Cpath d=%22M20.317 4.37a19.791 19.791 0 0 0-4.885-1.515a.074.074 0 0 0-.079.037c-.21.375-.444.864-.608 1.25a18.27 18.27 0 0 0-5.487 0a12.64 12.64 0 0 0-.617-1.25a.077.077 0 0 0-.079-.037A19.736 19.736 0 0 0 3.677 4.37a.07.07 0 0 0-.032.027C.533 9.046-.32 13.58.099 18.057a.082.082 0 0 0 .031.057a19.9 19.9 0 0 0 5.993 3.03a.078.078 0 0 0 .084-.028a14.09 14.09 0 0 0 1.226-1.994a.076.076 0 0 0-.041-.106a13.107 13.107 0 0 1-1.872-.892a.077.077 0 0 1-.008-.128a10.2 10.2 0 0 0 .372-.292a.074.074 0 0 1 .077-.01c3.928 1.793 8.18 1.793 12.062 0a.074.074 0 0 1 .078.01c.12.098.246.198.373.292a.077.077 0 0 1-.006.127a12.299 12.299 0 0 1-1.873.892a.077.077 0 0 0-.041.107c.36.698.772 1.362 1.225 1.993a.076.076 0 0 0 .084.028a19.839 19.839 0 0 0 6.002-3.03a.077.077 0 0 0 .032-.054c.5-5.177-.838-9.674-3.549-13.66a.061.061 0 0 0-.031-.03zM8.02 15.33c-1.183 0-2.157-1.085-2.157-2.419c0-1.333.956-2.419 2.157-2.419c1.21 0 2.176 1.096 2.157 2.42c0 1.333-.956 2.418-2.157 2.418zm7.975 0c-1.183 0-2.157-1.085-2.157-2.419c0-1.333.955-2.419 2.157-2.419c1.21 0 2.176 1.096 2.157 2.42c0 1.333-.946 2.418-2.157 2.418z%22/%3E%3C/svg%3E')",
-              WebkitMaskRepeat: 'no-repeat',
-              WebkitMaskPosition: 'center center',
-            }}
-          />
-        </Link>
-      </div>
-    </div>
-  )
+          <div className='api-page-header relative mt-6 sm:mt-0'>
+            <div className='absolute top-1 right-0 flex items-center gap-2'>
+              <div className='hidden sm:flex'>
+                <LLMCopyButton content={apiPageContent} />
+              </div>
+              <PageNavigationArrows previous={neighbours?.previous} next={neighbours?.next} />
+            </div>
+            <DocsTitle className='mb-2'>{data.title}</DocsTitle>
+            <DocsDescription>{data.description}</DocsDescription>
+          </div>
+          <DocsBody>
+            <APIPage {...apiProps} />
+          </DocsBody>
+        </DocsPage>
+      </>
+    )
+  }
+
+  const MDX = data.body
+  const markdownContent = await data.getText('processed')

  return (
    <>
      <StructuredData
        title={data.title}
        description={data.description || ''}
-        url={`${baseUrl}${page.url}`}
-        lang={params.lang}
+        url={`${BASE_URL}${page.url}`}
+        lang={lang}
        breadcrumb={breadcrumbs}
      />
      <DocsPage
@@ -187,7 +204,6 @@ export default async function Page(props: { params: Promise<{ slug?: string[]; l
        tableOfContent={{
          style: 'clerk',
          enabled: true,
-          footer: <TOCFooter />,
          single: false,
        }}
        tableOfContentPopover={{
@@ -196,7 +212,7 @@ export default async function Page(props: { params: Promise<{ slug?: string[]; l
        }}
        footer={{
          enabled: true,
-          component: <CustomFooter />,
+          component: footer,
        }}
      >
        <div className='relative mt-6 sm:mt-0'>
@@ -206,7 +222,7 @@ export default async function Page(props: { params: Promise<{ slug?: string[]; l
            </div>
            <PageNavigationArrows previous={neighbours?.previous} next={neighbours?.next} />
          </div>
-          <DocsTitle>{data.title}</DocsTitle>
+          <DocsTitle className='mb-2'>{data.title}</DocsTitle>
          <DocsDescription>{data.description}</DocsDescription>
        </div>
        <DocsBody>
@@ -252,27 +268,29 @@ export async function generateMetadata(props: {
  params: Promise<{ slug?: string[]; lang: string }>
 }) {
  const params = await props.params
-  const page = source.getPage(params.slug, params.lang)
+  const { lang, slug } = resolveLangAndSlug(params)
+  const page = source.getPage(slug, lang)
  if (!page) notFound()

-  const data = page.data as PageData
-  const baseUrl = 'https://docs.sim.ai'
-  const fullUrl = `${baseUrl}${page.url}`
+  const data = page.data as unknown as PageData
+  const fullUrl = `${BASE_URL}${page.url}`

-  const ogImageUrl = `${baseUrl}/api/og?title=${encodeURIComponent(data.title)}`
+  const ogImageUrl = `${BASE_URL}/api/og?title=${encodeURIComponent(data.title)}`

  return {
    title: data.title,
    description:
-      data.description || 'Sim visual workflow builder for AI applications documentation',
+      data.description ||
+      'Documentation for Sim — the open-source AI workspace where teams build, deploy, and manage AI agents.',
    keywords: [
-      'AI workflow builder',
-      'visual workflow editor',
-      'AI automation',
-      'workflow automation',
      'AI agents',
-      'no-code AI',
-      'drag and drop workflows',
+      'AI workspace',
+      'AI agent builder',
+      'build AI agents',
+      'LLM orchestration',
+      'AI automation',
+      'knowledge base',
+      'AI integrations',
      data.title?.toLowerCase().split(' '),
    ]
      .flat()
@@ -282,14 +300,15 @@ export async function generateMetadata(props: {
    openGraph: {
      title: data.title,
      description:
-        data.description || 'Sim visual workflow builder for AI applications documentation',
+        data.description ||
+        'Documentation for Sim — the open-source AI workspace where teams build, deploy, and manage AI agents.',
      url: fullUrl,
      siteName: 'Sim Documentation',
      type: 'article',
-      locale: params.lang === 'en' ? 'en_US' : `${params.lang}_${params.lang.toUpperCase()}`,
-      alternateLocale: ['en', 'es', 'fr', 'de', 'ja', 'zh']
-        .filter((lang) => lang !== params.lang)
-        .map((lang) => (lang === 'en' ? 'en_US' : `${lang}_${lang.toUpperCase()}`)),
+      locale: OG_LOCALE_MAP[lang] ?? 'en_US',
+      alternateLocale: i18n.languages
+        .filter((l) => l !== lang)
+        .map((l) => OG_LOCALE_MAP[l] ?? 'en_US'),
      images: [
        {
          url: ogImageUrl,
@@ -303,33 +322,23 @@ export async function generateMetadata(props: {
      card: 'summary_large_image',
      title: data.title,
      description:
-        data.description || 'Sim visual workflow builder for AI applications documentation',
+        data.description ||
+        'Documentation for Sim — the open-source AI workspace where teams build, deploy, and manage AI agents.',
      images: [ogImageUrl],
      creator: '@simdotai',
      site: '@simdotai',
    },
-    robots: {
-      index: true,
-      follow: true,
-      googleBot: {
-        index: true,
-        follow: true,
-        'max-video-preview': -1,
-        'max-image-preview': 'large',
-        'max-snippet': -1,
-      },
-    },
    canonical: fullUrl,
    alternates: {
      canonical: fullUrl,
      languages: {
-        'x-default': `${baseUrl}${page.url.replace(`/${params.lang}`, '')}`,
-        en: `${baseUrl}${page.url.replace(`/${params.lang}`, '')}`,
-        es: `${baseUrl}/es${page.url.replace(`/${params.lang}`, '')}`,
-        fr: `${baseUrl}/fr${page.url.replace(`/${params.lang}`, '')}`,
-        de: `${baseUrl}/de${page.url.replace(`/${params.lang}`, '')}`,
-        ja: `${baseUrl}/ja${page.url.replace(`/${params.lang}`, '')}`,
-        zh: `${baseUrl}/zh${page.url.replace(`/${params.lang}`, '')}`,
+        'x-default': `${BASE_URL}${page.url.replace(`/${lang}`, '')}`,
+        en: `${BASE_URL}${page.url.replace(`/${lang}`, '')}`,
+        es: `${BASE_URL}/es${page.url.replace(`/${lang}`, '')}`,
+        fr: `${BASE_URL}/fr${page.url.replace(`/${lang}`, '')}`,
+        de: `${BASE_URL}/de${page.url.replace(`/${lang}`, '')}`,
+        ja: `${BASE_URL}/ja${page.url.replace(`/${lang}`, '')}`,
+        zh: `${BASE_URL}/zh${page.url.replace(`/${lang}`, '')}`,
      },
    },
  }
--- a/apps/docs/app/[lang]/layout.tsx
+++ b/apps/docs/app/[lang]/layout.tsx
@@ -3,7 +3,6 @@ import { defineI18nUI } from 'fumadocs-ui/i18n'
 import { DocsLayout } from 'fumadocs-ui/layouts/docs'
 import { RootProvider } from 'fumadocs-ui/provider/next'
 import { Geist_Mono, Inter } from 'next/font/google'
-import Script from 'next/script'
 import {
  SidebarFolder,
  SidebarItem,
@@ -13,6 +12,7 @@ import { Navbar } from '@/components/navbar/navbar'
 import { SimLogoFull } from '@/components/ui/sim-logo'
 import { i18n } from '@/lib/i18n'
 import { source } from '@/lib/source'
+import { DOCS_BASE_URL } from '@/lib/urls'
 import '../global.css'

 const inter = Inter({
@@ -55,23 +55,26 @@ type LayoutProps = {
  params: Promise<{ lang: string }>
 }

+const SUPPORTED_LANGUAGES: Set<string> = new Set(i18n.languages)
+
 export default async function Layout({ children, params }: LayoutProps) {
-  const { lang } = await params
+  const { lang: rawLang } = await params
+  const lang = SUPPORTED_LANGUAGES.has(rawLang) ? rawLang : 'en'

  const structuredData = {
    '@context': 'https://schema.org',
    '@type': 'WebSite',
    name: 'Sim Documentation',
    description:
-      'Comprehensive documentation for Sim - the visual workflow builder for AI Agent Workflows.',
-    url: 'https://docs.sim.ai',
+      'Documentation for Sim — the open-source AI workspace where teams build, deploy, and manage AI agents. Connect 1,000+ integrations and every major LLM.',
+    url: DOCS_BASE_URL,
    publisher: {
      '@type': 'Organization',
      name: 'Sim',
      url: 'https://sim.ai',
      logo: {
        '@type': 'ImageObject',
-        url: 'https://docs.sim.ai/static/logo.png',
+        url: `${DOCS_BASE_URL}/static/logo.png`,
      },
    },
    inLanguage: lang,
@@ -79,7 +82,7 @@ export default async function Layout({ children, params }: LayoutProps) {
      '@type': 'SearchAction',
      target: {
        '@type': 'EntryPoint',
-        urlTemplate: 'https://docs.sim.ai/api/search?q={search_term_string}',
+        urlTemplate: `${DOCS_BASE_URL}/api/search?q={search_term_string}`,
      },
      'query-input': 'required name=search_term_string',
    },
@@ -98,15 +101,15 @@ export default async function Layout({ children, params }: LayoutProps) {
        />
      </head>
      <body className='flex min-h-screen flex-col font-sans'>
-        <Script src='https://assets.onedollarstats.com/stonks.js' strategy='lazyOnload' />
        <RootProvider i18n={provider(lang)}>
          <Navbar />
          <DocsLayout
            tree={source.pageTree[lang]}
            nav={{
-              title: <SimLogoFull className='h-7 w-auto' />,
+              title: <SimLogoFull className='h-[22px] w-auto' />,
            }}
            sidebar={{
+              tabs: false,
              defaultOpenLevel: 0,
              collapsible: false,
              footer: null,
--- a/apps/docs/app/[lang]/not-found.tsx
+++ b/apps/docs/app/[lang]/not-found.tsx
@@ -1,4 +1,5 @@
-import { DocsBody, DocsPage } from 'fumadocs-ui/page'
+import { DocsPage } from 'fumadocs-ui/page'
+import Link from 'next/link'

 export const metadata = {
  title: 'Page Not Found',
@@ -7,17 +8,21 @@ export const metadata = {
 export default function NotFound() {
  return (
    <DocsPage>
-      <DocsBody>
-        <div className='flex min-h-[60vh] flex-col items-center justify-center text-center'>
-          <h1 className='mb-4 bg-gradient-to-b from-[#47d991] to-[#33c482] bg-clip-text font-bold text-8xl text-transparent'>
-            404
-          </h1>
-          <h2 className='mb-2 font-semibold text-2xl text-foreground'>Page Not Found</h2>
-          <p className='text-muted-foreground'>
-            The page you're looking for doesn't exist or has been moved.
-          </p>
-        </div>
-      </DocsBody>
+      <div className='flex min-h-[70vh] flex-col items-center justify-center gap-4 text-center'>
+        <h1 className='bg-gradient-to-b from-[#47d991] to-[#33c482] bg-clip-text font-bold text-8xl text-transparent'>
+          404
+        </h1>
+        <h2 className='font-semibold text-2xl text-foreground'>Page Not Found</h2>
+        <p className='text-muted-foreground'>
+          The page you're looking for doesn't exist or has been moved.
+        </p>
+        <Link
+          href='/'
+          className='ml-1 flex items-center rounded-[8px] bg-[#33c482] px-2.5 py-1.5 text-[13px] text-white transition-colors duration-200 hover:bg-[#2DAC72]'
+        >
+          Go home
+        </Link>
+      </div>
    </DocsPage>
  )
 }
--- a/apps/docs/app/favicon.ico
+++ b/apps/docs/app/favicon.ico
--- a/apps/docs/app/global.css
+++ b/apps/docs/app/global.css
--- a/apps/docs/app/layout.config.tsx
+++ b/apps/docs/app/layout.config.tsx
@@ -1,21 +0,0 @@
-import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared'
-
-/**
- * Shared layout configurations
- *
- * you can customise layouts individually from:
- * Home Layout: app/(home)/layout.tsx
- * Docs Layout: app/docs/layout.tsx
- */
-export const baseOptions: BaseLayoutProps = {
-  nav: {
-    title: (
-      <>
-        <svg width='24' height='24' xmlns='http://www.w3.org/2000/svg' aria-label='Logo'>
-          <circle cx={12} cy={12} r={12} fill='currentColor' />
-        </svg>
-        My App
-      </>
-    ),
-  },
-}
--- a/apps/docs/app/layout.tsx
+++ b/apps/docs/app/layout.tsx
@@ -1,32 +1,42 @@
 import type { ReactNode } from 'react'
+import type { Viewport } from 'next'
+import { DOCS_BASE_URL } from '@/lib/urls'

 export default function RootLayout({ children }: { children: ReactNode }) {
  return children
 }

+export const viewport: Viewport = {
+  width: 'device-width',
+  initialScale: 1,
+  themeColor: '#000000',
+}
+
 export const metadata = {
-  metadataBase: new URL('https://docs.sim.ai'),
+  metadataBase: new URL(DOCS_BASE_URL),
  title: {
-    default: 'Sim Documentation - Visual Workflow Builder for AI Applications',
-    template: '%s',
+    default: 'Sim Documentation — The AI Workspace for Teams',
+    template: '%s | Sim Docs',
  },
  description:
-    'Comprehensive documentation for Sim - the visual workflow builder for AI applications. Create powerful AI agents, automation workflows, and data processing pipelines by connecting blocks on a canvas—no coding required.',
+    'Documentation for Sim — the open-source AI workspace where teams build, deploy, and manage AI agents. Connect 1,000+ integrations and every major LLM.',
+  applicationName: 'Sim Docs',
+  generator: 'Next.js',
+  referrer: 'origin-when-cross-origin' as const,
  keywords: [
-    'AI workflow builder',
-    'visual workflow editor',
-    'AI automation',
-    'workflow automation',
+    'AI workspace',
+    'AI agent builder',
    'AI agents',
-    'no-code AI',
-    'drag and drop workflows',
+    'build AI agents',
+    'open-source AI agents',
+    'LLM orchestration',
    'AI integrations',
-    'workflow canvas',
-    'AI Agent Workflow Builder',
-    'workflow orchestration',
-    'agent builder',
-    'AI workflow automation',
-    'visual programming',
+    'knowledge base',
+    'AI automation',
+    'visual workflow builder',
+    'enterprise AI',
+    'AI agent deployment',
+    'AI tools',
  ],
  authors: [{ name: 'Sim Team', url: 'https://sim.ai' }],
  creator: 'Sim',
@@ -35,30 +45,31 @@ export const metadata = {
  classification: 'Developer Documentation',
  manifest: '/favicon/site.webmanifest',
  icons: {
-    icon: [
-      { url: '/favicon/favicon-16x16.png', sizes: '16x16', type: 'image/png' },
-      { url: '/favicon/favicon-32x32.png', sizes: '32x32', type: 'image/png' },
-    ],
    apple: '/favicon/apple-touch-icon.png',
-    shortcut: '/favicon/favicon.ico',
  },
  appleWebApp: {
    capable: true,
    statusBarStyle: 'default',
    title: 'Sim Docs',
  },
+  formatDetection: {
+    telephone: false,
+  },
+  other: {
+    'msapplication-TileColor': '#000000',
+  },
  openGraph: {
    type: 'website',
    locale: 'en_US',
    alternateLocale: ['es_ES', 'fr_FR', 'de_DE', 'ja_JP', 'zh_CN'],
-    url: 'https://docs.sim.ai',
+    url: DOCS_BASE_URL,
    siteName: 'Sim Documentation',
-    title: 'Sim Documentation - Visual Workflow Builder for AI Applications',
+    title: 'Sim Documentation — The AI Workspace for Teams',
    description:
-      'Comprehensive documentation for Sim - the visual workflow builder for AI applications. Create powerful AI agents, automation workflows, and data processing pipelines.',
+      'Documentation for Sim — the open-source AI workspace where teams build, deploy, and manage AI agents. Connect 1,000+ integrations and every major LLM.',
    images: [
      {
-        url: 'https://docs.sim.ai/api/og?title=Sim%20Documentation',
+        url: `${DOCS_BASE_URL}/api/og?title=Sim%20Documentation`,
        width: 1200,
        height: 630,
        alt: 'Sim Documentation',
@@ -67,12 +78,12 @@ export const metadata = {
  },
  twitter: {
    card: 'summary_large_image',
-    title: 'Sim Documentation - Visual Workflow Builder for AI Applications',
+    title: 'Sim Documentation — The AI Workspace for Teams',
    description:
-      'Comprehensive documentation for Sim - the visual workflow builder for AI applications.',
+      'Documentation for Sim — the open-source AI workspace where teams build, deploy, and manage AI agents. Connect 1,000+ integrations and every major LLM.',
    creator: '@simdotai',
    site: '@simdotai',
-    images: ['https://docs.sim.ai/api/og?title=Sim%20Documentation'],
+    images: [`${DOCS_BASE_URL}/api/og?title=Sim%20Documentation`],
  },
  robots: {
    index: true,
@@ -86,15 +97,15 @@ export const metadata = {
    },
  },
  alternates: {
-    canonical: 'https://docs.sim.ai',
+    canonical: DOCS_BASE_URL,
    languages: {
-      'x-default': 'https://docs.sim.ai',
-      en: 'https://docs.sim.ai',
-      es: 'https://docs.sim.ai/es',
-      fr: 'https://docs.sim.ai/fr',
-      de: 'https://docs.sim.ai/de',
-      ja: 'https://docs.sim.ai/ja',
-      zh: 'https://docs.sim.ai/zh',
+      'x-default': DOCS_BASE_URL,
+      en: DOCS_BASE_URL,
+      es: `${DOCS_BASE_URL}/es`,
+      fr: `${DOCS_BASE_URL}/fr`,
+      de: `${DOCS_BASE_URL}/de`,
+      ja: `${DOCS_BASE_URL}/ja`,
+      zh: `${DOCS_BASE_URL}/zh`,
    },
  },
 }
--- a/apps/docs/app/llms.txt/route.ts
+++ b/apps/docs/app/llms.txt/route.ts
@@ -1,9 +1,10 @@
 import { source } from '@/lib/source'
+import { DOCS_BASE_URL } from '@/lib/urls'

 export const revalidate = false

 export async function GET() {
-  const baseUrl = 'https://docs.sim.ai'
+  const baseUrl = DOCS_BASE_URL

  try {
    const pages = source.getPages().filter((page) => {
@@ -37,9 +38,9 @@ export async function GET() {

    const manifest = `# Sim Documentation

-> Visual Workflow Builder for AI Applications
+> The open-source AI workspace where teams build, deploy, and manage AI agents.

-Sim is a visual workflow builder for AI applications that lets you build AI agent workflows visually. Create powerful AI agents, automation workflows, and data processing pipelines by connecting blocks on a canvas—no coding required.
+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. Trusted by over 100,000 builders.

 ## Documentation Overview

@@ -61,7 +62,7 @@ ${Object.entries(sections)

 - Full documentation content: ${baseUrl}/llms-full.txt
 - Individual page content: ${baseUrl}/llms.mdx/[page-path]
- API documentation: ${baseUrl}/sdks/
+- API documentation: ${baseUrl}/api-reference/
 - Tool integrations: ${baseUrl}/tools/

 ## Statistics
--- a/apps/docs/app/robots.txt/route.ts
+++ b/apps/docs/app/robots.txt/route.ts
@@ -1,71 +1,18 @@
+import { DOCS_BASE_URL } from '@/lib/urls'
+
 export const revalidate = false

 export async function GET() {
-  const baseUrl = 'https://docs.sim.ai'
+  const baseUrl = DOCS_BASE_URL

  const robotsTxt = `# Robots.txt for Sim Documentation
-# Generated on ${new Date().toISOString()}

 User-agent: *
-Allow: /
-
-# Search engine crawlers
-User-agent: Googlebot
-Allow: /
-
-User-agent: Bingbot
-Allow: /
-
-User-agent: Slurp
-Allow: /
-
-User-agent: DuckDuckBot
-Allow: /
-
-User-agent: Baiduspider
-Allow: /
-
-User-agent: YandexBot
-Allow: /
-
-# AI and LLM crawlers - explicitly allowed for documentation indexing
-User-agent: GPTBot
-Allow: /
-
-User-agent: ChatGPT-User
-Allow: /
-
-User-agent: CCBot
-Allow: /
-
-User-agent: anthropic-ai
-Allow: /
-
-User-agent: Claude-Web
-Allow: /
-
-User-agent: Applebot
-Allow: /
-
-User-agent: PerplexityBot
-Allow: /
-
-User-agent: Diffbot
-Allow: /
-
-User-agent: FacebookBot
-Allow: /
-
-User-agent: cohere-ai
-Allow: /
-
-# Disallow admin and internal paths (if any exist)
 Disallow: /.next/
 Disallow: /api/internal/
 Disallow: /_next/static/
 Disallow: /admin/
-
-# Allow but don't prioritize these
+Allow: /
 Allow: /api/search
 Allow: /llms.txt
 Allow: /llms-full.txt
@@ -74,23 +21,12 @@ Allow: /llms.mdx/
 # Sitemaps
 Sitemap: ${baseUrl}/sitemap.xml

-# Crawl delay for aggressive bots (optional)
-# Crawl-delay: 1
-
 # Additional resources for AI indexing
 # See https://github.com/AnswerDotAI/llms-txt for more info
 # LLM-friendly content:
 #   Manifest: ${baseUrl}/llms.txt
 #   Full content: ${baseUrl}/llms-full.txt
-#   Individual pages: ${baseUrl}/llms.mdx/[page-path]
-
-# Multi-language documentation available at:
-# ${baseUrl}/en - English
-# ${baseUrl}/es - Español
-# ${baseUrl}/fr - Français
-# ${baseUrl}/de - Deutsch
-# ${baseUrl}/ja - 日本語
-# ${baseUrl}/zh - 简体中文`
+#   Individual pages: ${baseUrl}/llms.mdx/[page-path]`

  return new Response(robotsTxt, {
    headers: {
--- a/apps/docs/app/sitemap.ts
+++ b/apps/docs/app/sitemap.ts
@@ -0,0 +1,42 @@
+import type { MetadataRoute } from 'next'
+import { i18n } from '@/lib/i18n'
+import { source } from '@/lib/source'
+import { DOCS_BASE_URL } from '@/lib/urls'
+
+export const revalidate = 3600
+
+export default function sitemap(): MetadataRoute.Sitemap {
+  const baseUrl = DOCS_BASE_URL
+  const languages = source.getLanguages()
+
+  const pagesBySlug = new Map<string, Map<string, string>>()
+  for (const { language, pages } of languages) {
+    for (const page of pages) {
+      const key = page.slugs.join('/')
+      if (!pagesBySlug.has(key)) {
+        pagesBySlug.set(key, new Map())
+      }
+      pagesBySlug.get(key)!.set(language, `${baseUrl}${page.url}`)
+    }
+  }
+
+  const entries: MetadataRoute.Sitemap = []
+  for (const [, localeMap] of pagesBySlug) {
+    const defaultUrl = localeMap.get(i18n.defaultLanguage)
+    if (!defaultUrl) continue
+
+    const langAlternates: Record<string, string> = {}
+    for (const [lang, url] of localeMap) {
+      langAlternates[lang] = url
+    }
+
+    langAlternates['x-default'] = defaultUrl
+
+    entries.push({
+      url: defaultUrl,
+      alternates: { languages: langAlternates },
+    })
+  }
+
+  return entries
+}
--- a/apps/docs/app/sitemap.xml/route.ts
+++ b/apps/docs/app/sitemap.xml/route.ts
@@ -1,63 +0,0 @@
-import { i18n } from '@/lib/i18n'
-import { source } from '@/lib/source'
-
-export const revalidate = false
-
-export async function GET() {
-  const baseUrl = 'https://docs.sim.ai'
-
-  const allPages = source.getPages()
-
-  const getPriority = (url: string): string => {
-    if (url === '/introduction' || url === '/') return '1.0'
-    if (url === '/getting-started') return '0.9'
-    if (url.match(/^\/[^/]+$/)) return '0.8'
-    if (url.includes('/sdks/') || url.includes('/tools/')) return '0.7'
-    return '0.6'
-  }
-
-  const urls = allPages
-    .flatMap((page) => {
-      const urlWithoutLang = page.url.replace(/^\/[a-z]{2}\//, '/')
-
-      return i18n.languages.map((lang) => {
-        const url =
-          lang === i18n.defaultLanguage
-            ? `${baseUrl}${urlWithoutLang}`
-            : `${baseUrl}/${lang}${urlWithoutLang}`
-
-        return `  <url>
-    <loc>${url}</loc>
-    <lastmod>${new Date().toISOString().split('T')[0]}</lastmod>
-    <changefreq>weekly</changefreq>
-    <priority>${getPriority(urlWithoutLang)}</priority>
-    ${i18n.languages.length > 1 ? generateAlternateLinks(baseUrl, urlWithoutLang) : ''}
-  </url>`
-      })
-    })
-    .join('\n')
-
-  const sitemap = `<?xml version="1.0" encoding="UTF-8"?>
-<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml">
-${urls}
-</urlset>`
-
-  return new Response(sitemap, {
-    headers: {
-      'Content-Type': 'application/xml',
-      'Cache-Control': 'public, max-age=3600, s-maxage=3600',
-    },
-  })
-}
-
-function generateAlternateLinks(baseUrl: string, urlWithoutLang: string): string {
-  return i18n.languages
-    .map((lang) => {
-      const url =
-        lang === i18n.defaultLanguage
-          ? `${baseUrl}${urlWithoutLang}`
-          : `${baseUrl}/${lang}${urlWithoutLang}`
-      return `    <xhtml:link rel="alternate" hreflang="${lang}" href="${url}" />`
-    })
-    .join('\n')
-}
--- a/apps/docs/components/docs-layout/page-footer.tsx
+++ b/apps/docs/components/docs-layout/page-footer.tsx
@@ -0,0 +1,102 @@
+import type { ReactNode } from 'react'
+import { ChevronLeft, ChevronRight } from 'lucide-react'
+import Link from 'next/link'
+
+interface PageNeighbour {
+  url: string
+  name: ReactNode
+}
+
+interface PageFooterProps {
+  previous?: PageNeighbour
+  next?: PageNeighbour
+}
+
+const SOCIAL_LINKS = [
+  {
+    href: 'https://x.com/simdotai',
+    label: 'X (Twitter)',
+    icon: 'M18.244 2.25h3.308l-7.227 8.26 8.502 11.24H16.17l-5.214-6.817L4.99 21.75H1.68l7.73-8.835L1.254 2.25H8.08l4.713 6.231zm-1.161 17.52h1.833L7.084 4.126H5.117z',
+  },
+  {
+    href: 'https://github.com/simstudioai/sim',
+    label: 'GitHub',
+    icon: 'M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z',
+  },
+  {
+    href: 'https://discord.gg/Hr4UWYEcTT',
+    label: 'Discord',
+    icon: 'M20.317 4.37a19.791 19.791 0 0 0-4.885-1.515.074.074 0 0 0-.079.037c-.21.375-.444.864-.608 1.25a18.27 18.27 0 0 0-5.487 0 12.64 12.64 0 0 0-.617-1.25.077.077 0 0 0-.079-.037A19.736 19.736 0 0 0 3.677 4.37a.07.07 0 0 0-.032.027C.533 9.046-.32 13.58.099 18.057a.082.082 0 0 0 .031.057 19.9 19.9 0 0 0 5.993 3.03.078.078 0 0 0 .084-.028 14.09 14.09 0 0 0 1.226-1.994.076.076 0 0 0-.041-.106 13.107 13.107 0 0 1-1.872-.892.077.077 0 0 1-.008-.128 10.2 10.2 0 0 0 .372-.292.074.074 0 0 1 .077-.01c3.928 1.793 8.18 1.793 12.062 0a.074.074 0 0 1 .078.01c.12.098.246.198.373.292a.077.077 0 0 1-.006.127 12.299 12.299 0 0 1-1.873.892.077.077 0 0 0-.041.107c.36.698.772 1.362 1.225 1.993a.076.076 0 0 0 .084.028 19.839 19.839 0 0 0 6.002-3.03.077.077 0 0 0 .032-.054c.5-5.177-.838-9.674-3.549-13.66a.061.061 0 0 0-.031-.03zM8.02 15.33c-1.183 0-2.157-1.085-2.157-2.419 0-1.333.956-2.419 2.157-2.419 1.21 0 2.176 1.096 2.157 2.42 0 1.333-.956 2.418-2.157 2.418zm7.975 0c-1.183 0-2.157-1.085-2.157-2.419 0-1.333.955-2.419 2.157-2.419 1.21 0 2.176 1.096 2.157 2.42 0 1.333-.946 2.418-2.157 2.418z',
+  },
+] as const
+
+export function PageFooter({ previous, next }: PageFooterProps) {
+  return (
+    <div className='mt-12'>
+      <div className='h-px w-full bg-[rgba(0,0,0,0.08)] dark:bg-[rgba(255,255,255,0.08)]' />
+
+      {(previous || next) && (
+        <div className='flex'>
+          {previous ? (
+            <Link
+              href={previous.url}
+              className='group flex flex-1 flex-col gap-1 px-6 py-5 transition-colors hover:bg-[rgba(0,0,0,0.02)] dark:hover:bg-[rgba(255,255,255,0.03)]'
+            >
+              <span className='text-[rgba(0,0,0,0.4)] text-xs dark:text-[rgba(255,255,255,0.35)]'>
+                Previous
+              </span>
+              <span className='flex items-center gap-1.5 font-[470] text-[rgba(0,0,0,0.7)] text-sm transition-colors group-hover:text-[rgba(0,0,0,0.88)] dark:text-[rgba(255,255,255,0.7)] dark:group-hover:text-[rgba(255,255,255,0.92)]'>
+                <ChevronLeft className='h-3.5 w-3.5 shrink-0' />
+                {previous.name}
+              </span>
+            </Link>
+          ) : (
+            <div className='flex-1' />
+          )}
+
+          {previous && next && (
+            <div className='w-px bg-[rgba(0,0,0,0.08)] dark:bg-[rgba(255,255,255,0.08)]' />
+          )}
+
+          {next ? (
+            <Link
+              href={next.url}
+              className='group flex flex-1 flex-col items-end gap-1 px-6 py-5 transition-colors hover:bg-[rgba(0,0,0,0.02)] dark:hover:bg-[rgba(255,255,255,0.03)]'
+            >
+              <span className='text-[rgba(0,0,0,0.4)] text-xs dark:text-[rgba(255,255,255,0.35)]'>
+                Next
+              </span>
+              <span className='flex items-center gap-1.5 font-[470] text-[rgba(0,0,0,0.7)] text-sm transition-colors group-hover:text-[rgba(0,0,0,0.88)] dark:text-[rgba(255,255,255,0.7)] dark:group-hover:text-[rgba(255,255,255,0.92)]'>
+                {next.name}
+                <ChevronRight className='h-3.5 w-3.5 shrink-0' />
+              </span>
+            </Link>
+          ) : (
+            <div className='flex-1' />
+          )}
+        </div>
+      )}
+
+      <div className='h-px w-full bg-[rgba(0,0,0,0.08)] dark:bg-[rgba(255,255,255,0.08)]' />
+
+      <div className='flex items-center gap-4 pt-10 pb-6'>
+        {SOCIAL_LINKS.map((link) => (
+          <Link
+            key={link.label}
+            href={link.href}
+            target='_blank'
+            rel='noopener noreferrer'
+            aria-label={link.label}
+          >
+            <svg
+              viewBox='0 0 24 24'
+              className='h-5 w-5 fill-gray-400 transition-colors hover:fill-gray-500 dark:fill-gray-500 dark:hover:fill-gray-400'
+            >
+              <path d={link.icon} />
+            </svg>
+          </Link>
+        ))}
+      </div>
+    </div>
+  )
+}
--- a/apps/docs/components/docs-layout/page-navigation-arrows.tsx
+++ b/apps/docs/components/docs-layout/page-navigation-arrows.tsx
@@ -20,7 +20,7 @@ export function PageNavigationArrows({ previous, next }: PageNavigationArrowsPro
      {previous && (
        <Link
          href={previous.url}
-          className='inline-flex items-center justify-center gap-1.5 rounded-lg border border-border/40 bg-background px-2.5 py-1.5 text-muted-foreground/60 text-sm transition-all hover:border-border hover:bg-accent/50 hover:text-muted-foreground'
+          className='inline-flex items-center justify-center rounded-[5px] border border-transparent px-2.5 py-2 text-foreground/40 transition-colors duration-200 hover:border-border/40 hover:bg-neutral-100 hover:text-foreground/70 dark:hover:bg-neutral-800'
          aria-label='Previous page'
          title='Previous page'
        >
@@ -30,7 +30,7 @@ export function PageNavigationArrows({ previous, next }: PageNavigationArrowsPro
      {next && (
        <Link
          href={next.url}
-          className='inline-flex items-center justify-center gap-1.5 rounded-lg border border-border/40 bg-background px-2.5 py-1.5 text-muted-foreground/60 text-sm transition-all hover:border-border hover:bg-accent/50 hover:text-muted-foreground'
+          className='inline-flex items-center justify-center rounded-[5px] border border-transparent px-2.5 py-2 text-foreground/40 transition-colors duration-200 hover:border-border/40 hover:bg-neutral-100 hover:text-foreground/70 dark:hover:bg-neutral-800'
          aria-label='Next page'
          title='Next page'
        >
--- a/apps/docs/components/docs-layout/sidebar-components.tsx
+++ b/apps/docs/components/docs-layout/sidebar-components.tsx
@@ -2,12 +2,36 @@

 import { type ReactNode, useEffect, useState } from 'react'
 import type { Folder, Item, Separator } from 'fumadocs-core/page-tree'
-import { ChevronRight } from 'lucide-react'
 import Link from 'next/link'
 import { usePathname } from 'next/navigation'
+import { i18n } from '@/lib/i18n'
 import { cn } from '@/lib/utils'

-const LANG_PREFIXES = ['/en', '/es', '/fr', '/de', '/ja', '/zh']
+function SidebarChevron({ open, className }: { open: boolean; className?: string }) {
+  return (
+    <svg
+      width='5'
+      height='8'
+      viewBox='0 0 6 10'
+      fill='none'
+      className={cn(
+        'flex-shrink-0 transition-transform duration-200',
+        open && 'rotate-90',
+        className
+      )}
+    >
+      <path
+        d='M1 1L5 5L1 9'
+        stroke='currentColor'
+        strokeWidth='1.33'
+        strokeLinecap='square'
+        strokeLinejoin='miter'
+      />
+    </svg>
+  )
+}
+
+const LANG_PREFIXES = i18n.languages.map((l) => `/${l}`)

 function stripLangPrefix(path: string): string {
  for (const prefix of LANG_PREFIXES) {
@@ -26,6 +50,22 @@ function isActive(url: string, pathname: string, nested = true): boolean {
  )
 }

+const ITEM_BASE =
+  'flex w-full items-center gap-2 rounded-md px-2 py-1.5 text-sm transition-colors text-fd-muted-foreground hover:bg-fd-accent/50 hover:text-fd-accent-foreground'
+const ITEM_ACTIVE_MOBILE = 'bg-fd-primary/10 font-medium text-fd-primary'
+
+const ITEM_DESKTOP =
+  'lg:mb-[0.0625rem] lg:block lg:rounded-lg lg:px-2.5 lg:py-1.5 lg:font-normal lg:text-[13px] lg:leading-tight'
+const ITEM_TEXT = 'lg:text-[#3b3b3b] lg:dark:text-[#cdcdcd]'
+const ITEM_HOVER = 'lg:hover:bg-[#f2f2f2] lg:dark:hover:bg-[#262626]'
+const ITEM_ACTIVE =
+  'lg:bg-[#ececec] lg:font-normal lg:text-[#3b3b3b] lg:dark:bg-[#2c2c2c] lg:dark:text-[#cdcdcd]'
+
+const FOLDER_TEXT = 'lg:text-[#3b3b3b] lg:font-medium lg:dark:text-[#cdcdcd]'
+const FOLDER_HOVER = 'lg:hover:bg-[#f2f2f2] lg:dark:hover:bg-[#262626]'
+const FOLDER_ACTIVE =
+  'lg:bg-[#ececec] lg:text-[#3b3b3b] lg:dark:bg-[#2c2c2c] lg:dark:text-[#cdcdcd]'
+
 export function SidebarItem({ item }: { item: Item }) {
  const pathname = usePathname()
  const active = isActive(item.url, pathname, false)
@@ -35,16 +75,12 @@ export function SidebarItem({ item }: { item: Item }) {
      href={item.url}
      data-active={active}
      className={cn(
-        // Mobile styles (default)
-        'flex w-full items-center gap-2 rounded-md px-2 py-1.5 text-sm transition-colors',
-        'text-fd-muted-foreground hover:bg-fd-accent/50 hover:text-fd-accent-foreground',
-        active && 'bg-fd-primary/10 font-medium text-fd-primary',
-        // Desktop styles (lg+)
-        'lg:mb-[0.0625rem] lg:block lg:rounded-md lg:px-2.5 lg:py-1.5 lg:font-normal lg:text-[13px] lg:leading-tight',
-        'lg:text-gray-600 lg:dark:text-gray-400',
-        !active && 'lg:hover:bg-gray-100/60 lg:dark:hover:bg-gray-800/40',
-        active &&
-          'lg:bg-emerald-50/80 lg:font-normal lg:text-emerald-600 lg:dark:bg-emerald-900/15 lg:dark:text-emerald-400'
+        ITEM_BASE,
+        active && ITEM_ACTIVE_MOBILE,
+        ITEM_DESKTOP,
+        ITEM_TEXT,
+        !active && ITEM_HOVER,
+        active && ITEM_ACTIVE
      )}
    >
      {item.name}
@@ -52,15 +88,26 @@ export function SidebarItem({ item }: { item: Item }) {
  )
 }

+function isApiReferenceFolder(node: Folder): boolean {
+  if (node.index?.url.includes('/api-reference/')) return true
+  for (const child of node.children) {
+    if (child.type === 'page' && child.url.includes('/api-reference/')) return true
+    if (child.type === 'folder' && isApiReferenceFolder(child)) return true
+  }
+  return false
+}
+
 export function SidebarFolder({ item, children }: { item: Folder; children: ReactNode }) {
  const pathname = usePathname()
  const hasActiveChild = checkHasActiveChild(item, pathname)
+  const isApiRef = isApiReferenceFolder(item)
+  const isOnApiRefPage = stripLangPrefix(pathname).startsWith('/api-reference')
  const hasChildren = item.children.length > 0
-  const [open, setOpen] = useState(hasActiveChild)
+  const [open, setOpen] = useState(hasActiveChild || (isApiRef && isOnApiRefPage))

  useEffect(() => {
-    setOpen(hasActiveChild)
-  }, [hasActiveChild])
+    setOpen(hasActiveChild || (isApiRef && isOnApiRefPage))
+  }, [hasActiveChild, isApiRef, isOnApiRefPage])

  const active = item.index ? isActive(item.index.url, pathname, false) : false

@@ -70,16 +117,12 @@ export function SidebarFolder({ item, children }: { item: Folder; children: Reac
        href={item.index.url}
        data-active={active}
        className={cn(
-          // Mobile styles (default)
-          'flex w-full items-center gap-2 rounded-md px-2 py-1.5 text-sm transition-colors',
-          'text-fd-muted-foreground hover:bg-fd-accent/50 hover:text-fd-accent-foreground',
-          active && 'bg-fd-primary/10 font-medium text-fd-primary',
-          // Desktop styles (lg+)
-          'lg:mb-[0.0625rem] lg:block lg:rounded-md lg:px-2.5 lg:py-1.5 lg:font-normal lg:text-[13px] lg:leading-tight',
-          'lg:text-gray-600 lg:dark:text-gray-400',
-          !active && 'lg:hover:bg-gray-100/60 lg:dark:hover:bg-gray-800/40',
-          active &&
-            'lg:bg-emerald-50/80 lg:font-normal lg:text-emerald-600 lg:dark:bg-emerald-900/15 lg:dark:text-emerald-400'
+          ITEM_BASE,
+          active && ITEM_ACTIVE_MOBILE,
+          ITEM_DESKTOP,
+          ITEM_TEXT,
+          !active && ITEM_HOVER,
+          active && ITEM_ACTIVE
        )}
      >
        {item.name}
@@ -91,82 +134,64 @@ export function SidebarFolder({ item, children }: { item: Folder; children: Reac
    <div className='flex flex-col lg:mb-[0.0625rem]'>
      <div className='flex w-full items-center lg:gap-0.5'>
        {item.index ? (
-          <Link
-            href={item.index.url}
-            data-active={active}
-            className={cn(
-              // Mobile styles (default)
-              'flex flex-1 items-center gap-2 rounded-md px-2 py-1.5 text-sm transition-colors',
-              'text-fd-muted-foreground hover:bg-fd-accent/50 hover:text-fd-accent-foreground',
-              active && 'bg-fd-primary/10 font-medium text-fd-primary',
-              // Desktop styles (lg+)
-              'lg:block lg:flex-1 lg:rounded-md lg:px-2.5 lg:py-1.5 lg:font-medium lg:text-[13px] lg:leading-tight',
-              'lg:text-gray-800 lg:dark:text-gray-200',
-              !active && 'lg:hover:bg-gray-100/60 lg:dark:hover:bg-gray-800/40',
-              active &&
-                'lg:bg-emerald-50/80 lg:text-emerald-600 lg:dark:bg-emerald-900/15 lg:dark:text-emerald-400'
+          <>
+            <Link
+              href={item.index.url}
+              data-active={active}
+              className={cn(
+                'flex flex-1 items-center gap-2 rounded-md px-2 py-1.5 text-sm transition-colors',
+                'text-fd-muted-foreground hover:bg-fd-accent/50 hover:text-fd-accent-foreground',
+                active && ITEM_ACTIVE_MOBILE,
+                'lg:block lg:flex-1 lg:rounded-lg lg:px-2.5 lg:py-1.5 lg:text-[13px] lg:leading-tight',
+                FOLDER_TEXT,
+                !active && FOLDER_HOVER,
+                active && FOLDER_ACTIVE
+              )}
+            >
+              {item.name}
+            </Link>
+            {hasChildren && (
+              <button
+                onClick={() => setOpen(!open)}
+                className={cn(
+                  'rounded p-1 hover:bg-fd-accent/50',
+                  'lg:cursor-pointer lg:rounded lg:p-1 lg:transition-colors lg:hover:bg-[#f2f2f2] lg:dark:hover:bg-[#262626]'
+                )}
+                aria-label={open ? 'Collapse' : 'Expand'}
+              >
+                <SidebarChevron open={open} className='text-[#5e5e5e] dark:text-[#939393]' />
+              </button>
            )}
-          >
-            {item.name}
-          </Link>
+          </>
        ) : (
          <button
            onClick={() => setOpen(!open)}
            className={cn(
-              // Mobile styles (default)
              'flex flex-1 items-center gap-2 rounded-md px-2 py-1.5 text-sm transition-colors',
              'text-fd-muted-foreground hover:bg-fd-accent/50',
-              // Desktop styles (lg+)
-              'lg:flex lg:w-full lg:cursor-pointer lg:items-center lg:justify-between lg:rounded-md lg:px-2.5 lg:py-1.5 lg:text-left lg:font-medium lg:text-[13px] lg:leading-tight',
-              'lg:text-gray-800 lg:hover:bg-gray-100/60 lg:dark:text-gray-200 lg:dark:hover:bg-gray-800/40'
+              'lg:flex lg:w-full lg:cursor-pointer lg:items-center lg:justify-between lg:rounded-lg lg:px-2.5 lg:py-1.5 lg:text-left lg:text-[13px] lg:leading-tight',
+              FOLDER_TEXT,
+              FOLDER_HOVER
            )}
          >
            <span>{item.name}</span>
-            {/* Desktop-only chevron for non-index folders */}
-            <ChevronRight
-              className={cn(
-                'ml-auto hidden h-3 w-3 flex-shrink-0 text-gray-400 transition-transform duration-200 ease-in-out lg:block dark:text-gray-500',
-                open && 'rotate-90'
-              )}
-            />
-          </button>
-        )}
-        {hasChildren && (
-          <button
-            onClick={() => setOpen(!open)}
-            className={cn(
-              // Mobile styles
-              'rounded p-1 hover:bg-fd-accent/50',
-              // Desktop styles
-              'lg:cursor-pointer lg:rounded lg:p-1 lg:transition-colors lg:hover:bg-gray-100/60 lg:dark:hover:bg-gray-800/40'
-            )}
-            aria-label={open ? 'Collapse' : 'Expand'}
-          >
-            <ChevronRight
-              className={cn(
-                // Mobile styles
-                'h-4 w-4 transition-transform',
-                // Desktop styles
-                'lg:h-3 lg:w-3 lg:text-gray-400 lg:duration-200 lg:ease-in-out lg:dark:text-gray-500',
-                open && 'rotate-90'
-              )}
-            />
+            <SidebarChevron open={open} className='ml-auto text-[#5e5e5e] dark:text-[#939393]' />
          </button>
        )}
      </div>
      {hasChildren && (
        <div
          className={cn(
-            'overflow-hidden transition-all duration-200 ease-in-out',
-            open ? 'max-h-[10000px] opacity-100' : 'max-h-0 opacity-0'
+            'grid transition-[grid-template-rows,opacity] duration-200 ease-in-out',
+            open ? 'grid-rows-[1fr] opacity-100' : 'grid-rows-[0fr] opacity-0'
          )}
        >
-          {/* Mobile: simple indent */}
-          <div className='ml-4 flex flex-col gap-0.5 lg:hidden'>{children}</div>
-          {/* Desktop: styled with border */}
-          <ul className='mt-0.5 ml-2 hidden space-y-[0.0625rem] border-gray-200/60 border-l pl-2.5 lg:block dark:border-gray-700/60'>
-            {children}
-          </ul>
+          <div className='overflow-hidden'>
+            <div className='ml-4 flex flex-col gap-0.5 lg:hidden'>{children}</div>
+            <ul className='mt-0.5 ml-2 hidden space-y-[0.0625rem] border-[#ececec] border-l pl-2.5 lg:block dark:border-[#2c2c2c]'>
+              {children}
+            </ul>
+          </div>
        </div>
      )}
    </div>
@@ -175,16 +200,24 @@ export function SidebarFolder({ item, children }: { item: Folder; children: Reac

 export function SidebarSeparator({ item }: { item: Separator }) {
  return (
-    <p
-      className={cn(
-        // Mobile styles
-        'mt-4 mb-2 px-2 font-medium text-fd-muted-foreground text-xs',
-        // Desktop styles
-        'lg:mt-4 lg:mb-1.5 lg:px-2.5 lg:font-semibold lg:text-[10px] lg:text-gray-500/80 lg:uppercase lg:tracking-wide lg:dark:text-gray-500'
-      )}
+    <div
+      data-separator
+      className={cn('mt-5 mb-1.5 px-2', 'lg:relative lg:mt-0 lg:mb-1.5 lg:px-[13px] lg:pt-0')}
    >
-      {item.name}
-    </p>
+      <div className='separator-divider hidden'>
+        <div className='h-[20px]' />
+        <div className='h-px bg-[#ececec] dark:bg-[#2c2c2c]' />
+        <div className='h-[20px]' />
+      </div>
+      <p
+        className={cn(
+          'font-medium text-fd-muted-foreground text-xs',
+          'lg:font-semibold lg:text-[#5e5e5e] lg:text-[10px] lg:uppercase lg:tracking-[0.06em] lg:dark:text-[#939393]'
+        )}
+      >
+        {item.name}
+      </p>
+    </div>
  )
 }

--- a/apps/docs/components/docs-layout/toc-footer.tsx
+++ b/apps/docs/components/docs-layout/toc-footer.tsx
@@ -1,41 +0,0 @@
-'use client'
-
-import { useState } from 'react'
-import { ArrowRight, ChevronRight } from 'lucide-react'
-import Link from 'next/link'
-
-export function TOCFooter() {
-  const [isHovered, setIsHovered] = useState(false)
-
-  return (
-    <div className='sticky bottom-0 mt-6'>
-      <div className='flex flex-col gap-2 rounded-lg border border-border bg-secondary p-6 text-sm'>
-        <div className='text-balance font-semibold text-base leading-tight'>
-          Start building today
-        </div>
-        <div className='text-muted-foreground'>Trusted by over 60,000 builders.</div>
-        <div className='text-muted-foreground'>
-          Build Agentic workflows visually on a drag-and-drop canvas or with natural language.
-        </div>
-        <Link
-          href='https://sim.ai/signup'
-          target='_blank'
-          rel='noopener noreferrer'
-          onMouseEnter={() => setIsHovered(true)}
-          onMouseLeave={() => setIsHovered(false)}
-          className='group mt-2 inline-flex h-8 w-fit items-center justify-center gap-1 whitespace-nowrap rounded-[10px] border border-[#2AAD6C] bg-gradient-to-b from-[#3ED990] to-[#2AAD6C] px-3 pr-[10px] pl-[12px] font-medium text-sm text-white shadow-[inset_0_2px_4px_0_#5EE8A8] outline-none transition-all hover:shadow-lg focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50'
-          aria-label='Get started with Sim - Sign up for free'
-        >
-          <span>Get started</span>
-          <span className='inline-flex transition-transform duration-200 group-hover:translate-x-0.5'>
-            {isHovered ? (
-              <ArrowRight className='h-4 w-4' aria-hidden='true' />
-            ) : (
-              <ChevronRight className='h-4 w-4' aria-hidden='true' />
-            )}
-          </span>
-        </Link>
-      </div>
-    </div>
-  )
-}
--- a/apps/docs/components/icons.tsx
+++ b/apps/docs/components/icons.tsx
--- a/apps/docs/components/navbar/navbar.tsx
+++ b/apps/docs/components/navbar/navbar.tsx
@@ -1,53 +1,90 @@
 'use client'

 import Link from 'next/link'
+import { usePathname } from 'next/navigation'
 import { LanguageDropdown } from '@/components/ui/language-dropdown'
 import { SearchTrigger } from '@/components/ui/search-trigger'
 import { SimLogoFull } from '@/components/ui/sim-logo'
 import { ThemeToggle } from '@/components/ui/theme-toggle'
+import { cn } from '@/lib/utils'
+
+const NAV_TABS = [
+  {
+    label: 'Documentation',
+    href: '/introduction',
+    match: (p: string) => !p.includes('/api-reference'),
+    external: false,
+  },
+  {
+    label: 'API Reference',
+    href: '/api-reference/getting-started',
+    match: (p: string) => p.includes('/api-reference'),
+    external: false,
+  },
+] as const

 export function Navbar() {
+  const pathname = usePathname()
+
  return (
-    <nav className='sticky top-0 z-50 border-border/50 border-b bg-background/80 backdrop-blur-md backdrop-saturate-150'>
-      {/* Desktop: Single row layout */}
-      <div className='hidden h-16 w-full items-center lg:flex'>
+    <nav className='sticky top-0 z-50 bg-background/80 backdrop-blur-md backdrop-saturate-150'>
+      <div className='hidden w-full flex-col lg:flex'>
+        {/* Top row: logo, search, controls */}
        <div
-          className='relative flex w-full items-center justify-between'
+          className='relative flex h-[52px] w-full items-center justify-between'
          style={{
-            paddingLeft: 'calc(var(--sidebar-offset) + 32px)',
-            paddingRight: 'calc(var(--toc-offset) + 60px)',
+            paddingLeft: 'calc(var(--sidebar-offset) + var(--nav-inset))',
+            paddingRight: 'calc(var(--toc-offset) + var(--nav-inset))',
          }}
        >
-          {/* Left cluster: logo */}
-          <div className='flex items-center'>
-            <Link href='/' className='flex min-w-[100px] items-center'>
-              <SimLogoFull className='h-7 w-auto' />
-            </Link>
-          </div>
+          <Link href='/' className='flex min-w-[100px] items-center'>
+            <SimLogoFull className='h-[20px] w-auto' />
+          </Link>

-          {/* Center cluster: search - absolutely positioned to center */}
          <div className='-translate-x-1/2 absolute left-1/2 flex items-center justify-center'>
            <SearchTrigger />
          </div>

-          {/* Right cluster aligns with TOC edge */}
-          <div className='flex items-center gap-4'>
-            <Link
-              href='https://sim.ai'
-              target='_blank'
-              rel='noopener noreferrer'
-              className='rounded-xl px-3 py-2 font-normal text-[0.9375rem] text-foreground/60 leading-[1.4] transition-colors hover:bg-foreground/8 hover:text-foreground'
-              style={{
-                fontFamily:
-                  '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
-              }}
-            >
-              Platform
-            </Link>
+          <div className='flex items-center gap-1'>
            <LanguageDropdown />
            <ThemeToggle />
+            <Link
+              href='https://sim.ai'
+              className='ml-1 flex items-center rounded-[8px] bg-[#33c482] px-2.5 py-1.5 text-[13px] text-white transition-colors duration-200 hover:bg-[#2DAC72]'
+            >
+              Get started
+            </Link>
          </div>
        </div>
+
+        {/* Bottom row: navigation tabs — border on row, tabs overlap it */}
+        <div
+          className='flex h-[40px] items-stretch gap-6 border-border/20 border-b'
+          style={{
+            paddingLeft: 'calc(var(--sidebar-offset) + var(--nav-inset))',
+          }}
+        >
+          {NAV_TABS.map((tab) => {
+            const isActive = !tab.external && tab.match(pathname)
+            return (
+              <Link
+                key={tab.label}
+                href={tab.href}
+                {...(tab.external ? { target: '_blank', rel: 'noopener noreferrer' } : {})}
+                className={cn(
+                  '-mb-px relative flex items-center border-b text-[14px] tracking-[-0.01em] transition-colors',
+                  isActive
+                    ? 'border-neutral-400 font-[480] text-neutral-800 dark:border-neutral-500 dark:text-neutral-200'
+                    : 'border-transparent font-[430] text-neutral-500 hover:border-neutral-300 hover:text-neutral-600 dark:text-neutral-400 dark:hover:border-neutral-600 dark:hover:text-neutral-300'
+                )}
+              >
+                {/* Invisible bold text reserves width to prevent layout shift */}
+                <span className='invisible font-[480]'>{tab.label}</span>
+                <span className='absolute'>{tab.label}</span>
+              </Link>
+            )
+          })}
+        </div>
      </div>
    </nav>
  )
--- a/apps/docs/components/page-actions.tsx
+++ b/apps/docs/components/page-actions.tsx
@@ -9,7 +9,7 @@ export function LLMCopyButton({ content }: { content: string }) {
  return (
    <button
      onClick={onClick}
-      className='flex cursor-pointer items-center gap-1.5 rounded-lg border border-border/40 bg-background px-2.5 py-2 text-muted-foreground/60 text-sm leading-none transition-all hover:border-border hover:bg-accent/50 hover:text-muted-foreground'
+      className='flex cursor-pointer items-center gap-1.5 rounded-[5px] border border-transparent px-2.5 py-2 text-[13px] text-foreground/40 leading-none transition-colors duration-200 hover:border-border/40 hover:bg-neutral-100 hover:text-foreground/70 dark:hover:bg-neutral-800'
      aria-label={checked ? 'Copied to clipboard' : 'Copy page content'}
    >
      {checked ? (
--- a/Show More
+++ b/Show More