v0.6.25: cloudwatch, cloudformation, live kb sync, linear fixes, posthog upgrade

* feat(cloudformation): add AWS CloudFormation integration with 7 operations

* fix(cloudformation): add pagination to list-stack-resources, describe-stacks, and describe-stack-events routes

.agents/skills/add-block/SKILL.md

@@ -0,0 +1,825 @@
+---
+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
+
+## Block Configuration Structure
+
+```typescript
+import { {ServiceName}Icon } from '@/components/icons'
+import type { BlockConfig } from '@/blocks/types'
+import { AuthMode } 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'
+  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 } 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',
+  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
+
+- [ ] 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

.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."

.agents/skills/add-connector/SKILL.md

@@ -0,0 +1,528 @@
+---
+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
+
+## 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`

.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."

.agents/skills/add-integration/SKILL.md

@@ -0,0 +1,760 @@
+---
+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
+
+## 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 } 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
+
+## 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`

.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."

.agents/skills/add-tools/SKILL.md

@@ -0,0 +1,321 @@
+---
+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
+
+## 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)

.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."

.agents/skills/add-trigger/SKILL.md

@@ -0,0 +1,708 @@
+---
+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 Skill
+
+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
+
+When the user asks you to create triggers for a service:
+1. Research what webhook events the service supports
+2. Create the trigger files using the generic builder
+3. Register triggers and connect them to the block
+
+## Directory Structure
+
+```
+apps/sim/triggers/{service}/
+├── index.ts              # Barrel exports
+├── utils.ts              # Service-specific helpers (trigger options, setup instructions, extra fields)
+├── {event_a}.ts          # Primary trigger (includes dropdown)
+├── {event_b}.ts          # Secondary trigger (no dropdown)
+├── {event_c}.ts          # Secondary trigger (no dropdown)
+└── webhook.ts            # Generic webhook trigger (optional, for "all events")
+```
+
+## Step 1: Create utils.ts
+
+This file contains service-specific helpers used by all triggers.
+
+```typescript
+import type { SubBlockConfig } from '@/blocks/types'
+import type { TriggerOutput } from '@/triggers/types'
+
+/**
+ * Dropdown options for the trigger type selector.
+ * These appear in the primary trigger's dropdown.
+ */
+export const {service}TriggerOptions = [
+  { label: 'Event A', id: '{service}_event_a' },
+  { label: 'Event B', id: '{service}_event_b' },
+  { label: 'Event C', id: '{service}_event_c' },
+  { label: 'Generic Webhook (All Events)', id: '{service}_webhook' },
+]
+
+/**
+ * Generates HTML setup instructions for the trigger.
+ * Displayed to users to help them configure webhooks in the external service.
+ */
+export function {service}SetupInstructions(eventType: string): string {
+  const instructions = [
+    'Copy the <strong>Webhook URL</strong> above',
+    'Go to <strong>{Service} Settings > Webhooks</strong>',
+    'Click <strong>Add Webhook</strong>',
+    'Paste the webhook URL',
+    `Select the <strong>${eventType}</strong> event type`,
+    'Save the webhook configuration',
+    'Click "Save" above to activate your trigger',
+  ]
+
+  return instructions
+    .map((instruction, index) =>
+      `<div class="mb-3"><strong>${index + 1}.</strong> ${instruction}</div>`
+    )
+    .join('')
+}
+
+/**
+ * Service-specific extra fields to add to triggers.
+ * These are inserted between webhookUrl and triggerSave.
+ */
+export function build{Service}ExtraFields(triggerId: string): SubBlockConfig[] {
+  return [
+    {
+      id: 'projectId',
+      title: 'Project ID (Optional)',
+      type: 'short-input',
+      placeholder: 'Leave empty for all projects',
+      description: 'Optionally filter to a specific project',
+      mode: 'trigger',
+      condition: { field: 'selectedTriggerId', value: triggerId },
+    },
+  ]
+}
+
+/**
+ * Build outputs for this trigger type.
+ * Outputs define what data is available to downstream blocks.
+ */
+export function build{Service}Outputs(): Record<string, TriggerOutput> {
+  return {
+    eventType: { type: 'string', description: 'The type of event that triggered this workflow' },
+    resourceId: { type: 'string', description: 'ID of the affected resource' },
+    timestamp: { type: 'string', description: 'When the event occurred (ISO 8601)' },
+    // Nested outputs for complex data
+    resource: {
+      id: { type: 'string', description: 'Resource ID' },
+      name: { type: 'string', description: 'Resource name' },
+      status: { type: 'string', description: 'Current status' },
+    },
+    webhook: { type: 'json', description: 'Full webhook payload' },
+  }
+}
+```
+
+## Step 2: Create the Primary Trigger
+
+The **primary trigger** is the first one listed. It MUST include `includeDropdown: true` so users can switch between trigger types.
+
+```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'
+
+/**
+ * {Service} Event A Trigger
+ *
+ * This is the PRIMARY trigger - it includes the dropdown for selecting trigger type.
+ */
+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,  // PRIMARY TRIGGER - includes dropdown
+    setupInstructions: {service}SetupInstructions('Event A'),
+    extraFields: build{Service}ExtraFields('{service}_event_a'),
+  }),
+
+  outputs: build{Service}Outputs(),
+
+  webhook: {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+  },
+}
+```
+
+## Step 3: Create Secondary Triggers
+
+Secondary triggers do NOT include the dropdown (it's already in the primary trigger).
+
+```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'
+
+/**
+ * {Service} Event B Trigger
+ */
+export const {service}EventBTrigger: TriggerConfig = {
+  id: '{service}_event_b',
+  name: '{Service} Event B',
+  provider: '{service}',
+  description: 'Trigger workflow when Event B occurs',
+  version: '1.0.0',
+  icon: {Service}Icon,
+
+  subBlocks: buildTriggerSubBlocks({
+    triggerId: '{service}_event_b',
+    triggerOptions: {service}TriggerOptions,
+    // NO includeDropdown - secondary trigger
+    setupInstructions: {service}SetupInstructions('Event B'),
+    extraFields: build{Service}ExtraFields('{service}_event_b'),
+  }),
+
+  outputs: build{Service}Outputs(),
+
+  webhook: {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+  },
+}
+```
+
+## Step 4: Create index.ts Barrel Export
+
+```typescript
+export { {service}EventATrigger } from './event_a'
+export { {service}EventBTrigger } from './event_b'
+export { {service}EventCTrigger } from './event_c'
+export { {service}WebhookTrigger } from './webhook'
+```
+
+## Step 5: Register Triggers
+
+### Trigger Registry (`apps/sim/triggers/registry.ts`)
+
+```typescript
+// Add import
+import {
+  {service}EventATrigger,
+  {service}EventBTrigger,
+  {service}EventCTrigger,
+  {service}WebhookTrigger,
+} from '@/triggers/{service}'
+
+// Add to TRIGGER_REGISTRY
+export const TRIGGER_REGISTRY: TriggerRegistry = {
+  // ... existing triggers ...
+  {service}_event_a: {service}EventATrigger,
+  {service}_event_b: {service}EventBTrigger,
+  {service}_event_c: {service}EventCTrigger,
+  {service}_webhook: {service}WebhookTrigger,
+}
+```
+
+## Step 6: Connect Triggers to Block
+
+In the block file (`apps/sim/blocks/blocks/{service}.ts`):
+
+```typescript
+import { {Service}Icon } from '@/components/icons'
+import { getTrigger } from '@/triggers'
+import type { BlockConfig } from '@/blocks/types'
+
+export const {Service}Block: BlockConfig = {
+  type: '{service}',
+  name: '{Service}',
+  // ... other config ...
+
+  // Enable triggers and list available trigger IDs
+  triggers: {
+    enabled: true,
+    available: [
+      '{service}_event_a',
+      '{service}_event_b',
+      '{service}_event_c',
+      '{service}_webhook',
+    ],
+  },
+
+  subBlocks: [
+    // Regular tool subBlocks first
+    { id: 'operation', /* ... */ },
+    { id: 'credential', /* ... */ },
+    // ... other tool fields ...
+
+    // Then spread ALL trigger subBlocks
+    ...getTrigger('{service}_event_a').subBlocks,
+    ...getTrigger('{service}_event_b').subBlocks,
+    ...getTrigger('{service}_event_c').subBlocks,
+    ...getTrigger('{service}_webhook').subBlocks,
+  ],
+
+  // ... tools config ...
+}
+```
+
+## Automatic Webhook Registration (Preferred)
+
+If the service's API supports programmatic webhook creation, implement automatic webhook registration instead of requiring users to manually configure webhooks. This provides a much better user experience.
+
+### When to Use Automatic Registration
+
+Check the service's API documentation for endpoints like:
+- `POST /webhooks` or `POST /hooks` - Create webhook
+- `DELETE /webhooks/{id}` - Delete webhook
+
+Services that support this pattern include: Grain, Lemlist, Calendly, Airtable, Webflow, Typeform, etc.
+
+### Implementation Steps
+
+#### 1. Add API Key to Extra Fields
+
+Update your `build{Service}ExtraFields` function to include an API key field:
+
+```typescript
+export function build{Service}ExtraFields(triggerId: string): SubBlockConfig[] {
+  return [
+    {
+      id: 'apiKey',
+      title: 'API Key',
+      type: 'short-input',
+      placeholder: 'Enter your {Service} API key',
+      description: 'Required to create the webhook in {Service}.',
+      password: true,
+      required: true,
+      mode: 'trigger',
+      condition: { field: 'selectedTriggerId', value: triggerId },
+    },
+    // Other optional fields (e.g., campaign filter, project filter)
+    {
+      id: 'projectId',
+      title: 'Project ID (Optional)',
+      type: 'short-input',
+      placeholder: 'Leave empty for all projects',
+      mode: 'trigger',
+      condition: { field: 'selectedTriggerId', value: triggerId },
+    },
+  ]
+}
+```
+
+#### 2. Update Setup Instructions for Automatic Creation
+
+Change instructions to indicate automatic webhook creation:
+
+```typescript
+export function {service}SetupInstructions(eventType: string): string {
+  const instructions = [
+    'Enter your {Service} API Key above.',
+    'You can find your API key in {Service} at <strong>Settings > API</strong>.',
+    `Click <strong>"Save Configuration"</strong> to automatically create the webhook in {Service} for <strong>${eventType}</strong> events.`,
+    'The webhook will be automatically deleted when you remove this trigger.',
+  ]
+
+  return instructions
+    .map((instruction, index) =>
+      `<div class="mb-3"><strong>${index + 1}.</strong> ${instruction}</div>`
+    )
+    .join('')
+}
+```
+
+#### 3. Add Webhook Creation to API Route
+
+In `apps/sim/app/api/webhooks/route.ts`, add provider-specific logic after the database save:
+
+```typescript
+// --- {Service} specific logic ---
+if (savedWebhook && provider === '{service}') {
+  logger.info(`[${requestId}] {Service} provider detected. Creating webhook subscription.`)
+  try {
+    const result = await create{Service}WebhookSubscription(
+      {
+        id: savedWebhook.id,
+        path: savedWebhook.path,
+        providerConfig: savedWebhook.providerConfig,
+      },
+      requestId
+    )
+
+    if (result) {
+      // Update the webhook record with the external webhook ID
+      const updatedConfig = {
+        ...(savedWebhook.providerConfig as Record<string, any>),
+        externalId: result.id,
+      }
+      await db
+        .update(webhook)
+        .set({
+          providerConfig: updatedConfig,
+          updatedAt: new Date(),
+        })
+        .where(eq(webhook.id, savedWebhook.id))
+
+      savedWebhook.providerConfig = updatedConfig
+      logger.info(`[${requestId}] Successfully created {Service} webhook`, {
+        externalHookId: result.id,
+        webhookId: savedWebhook.id,
+      })
+    }
+  } catch (err) {
+    logger.error(
+      `[${requestId}] Error creating {Service} webhook subscription, rolling back webhook`,
+      err
+    )
+    await db.delete(webhook).where(eq(webhook.id, savedWebhook.id))
+    return NextResponse.json(
+      {
+        error: 'Failed to create webhook in {Service}',
+        details: err instanceof Error ? err.message : 'Unknown error',
+      },
+      { status: 500 }
+    )
+  }
+}
+// --- End {Service} specific logic ---
+```
+
+Then add the helper function at the end of the file:
+
+```typescript
+async function create{Service}WebhookSubscription(
+  webhookData: any,
+  requestId: string
+): Promise<{ id: string } | undefined> {
+  try {
+    const { path, providerConfig } = webhookData
+    const { apiKey, triggerId, projectId } = providerConfig || {}
+
+    if (!apiKey) {
+      throw new Error('{Service} API Key is required.')
+    }
+
+    // Map trigger IDs to service event types
+    const eventTypeMap: Record<string, string | undefined> = {
+      {service}_event_a: 'eventA',
+      {service}_event_b: 'eventB',
+      {service}_webhook: undefined, // Generic - no filter
+    }
+
+    const eventType = eventTypeMap[triggerId]
+    const notificationUrl = `${getBaseUrl()}/api/webhooks/trigger/${path}`
+
+    const requestBody: Record<string, any> = {
+      url: notificationUrl,
+    }
+
+    if (eventType) {
+      requestBody.eventType = eventType
+    }
+
+    if (projectId) {
+      requestBody.projectId = projectId
+    }
+
+    const response = await fetch('https://api.{service}.com/webhooks', {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(requestBody),
+    })
+
+    const responseBody = await response.json()
+
+    if (!response.ok) {
+      const errorMessage = responseBody.message || 'Unknown API error'
+      let userFriendlyMessage = 'Failed to create webhook in {Service}'
+
+      if (response.status === 401) {
+        userFriendlyMessage = 'Invalid API Key. Please verify and try again.'
+      } else if (errorMessage) {
+        userFriendlyMessage = `{Service} error: ${errorMessage}`
+      }
+
+      throw new Error(userFriendlyMessage)
+    }
+
+    return { id: responseBody.id }
+  } catch (error: any) {
+    logger.error(`Exception during {Service} webhook creation`, { error: error.message })
+    throw error
+  }
+}
+```
+
+#### 4. Add Webhook Deletion to Provider Subscriptions
+
+In `apps/sim/lib/webhooks/provider-subscriptions.ts`:
+
+1. Add a logger:
+```typescript
+const {service}Logger = createLogger('{Service}Webhook')
+```
+
+2. Add the delete function:
+```typescript
+export async function delete{Service}Webhook(webhook: any, requestId: string): Promise<void> {
+  try {
+    const config = getProviderConfig(webhook)
+    const apiKey = config.apiKey as string | undefined
+    const externalId = config.externalId as string | undefined
+
+    if (!apiKey || !externalId) {
+      {service}Logger.warn(`[${requestId}] Missing apiKey or externalId, skipping cleanup`)
+      return
+    }
+
+    const response = await fetch(`https://api.{service}.com/webhooks/${externalId}`, {
+      method: 'DELETE',
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+      },
+    })
+
+    if (!response.ok && response.status !== 404) {
+      {service}Logger.warn(`[${requestId}] Failed to delete webhook (non-fatal): ${response.status}`)
+    } else {
+      {service}Logger.info(`[${requestId}] Successfully deleted webhook ${externalId}`)
+    }
+  } catch (error) {
+    {service}Logger.warn(`[${requestId}] Error deleting webhook (non-fatal)`, error)
+  }
+}
+```
+
+3. Add to `cleanupExternalWebhook`:
+```typescript
+export async function cleanupExternalWebhook(...): Promise<void> {
+  // ... existing providers ...
+  } else if (webhook.provider === '{service}') {
+    await delete{Service}Webhook(webhook, requestId)
+  }
+}
+```
+
+### Key Points for Automatic Registration
+
+- **API Key visibility**: Always use `password: true` for API key fields
+- **Error handling**: Roll back the database webhook if external creation fails
+- **External ID storage**: Save the external webhook ID in `providerConfig.externalId`
+- **Graceful cleanup**: Don't fail webhook deletion if cleanup fails (use non-fatal logging)
+- **User-friendly errors**: Map HTTP status codes to helpful error messages
+
+## The buildTriggerSubBlocks Helper
+
+This is the generic helper from `@/triggers` that creates consistent trigger subBlocks.
+
+### Function Signature
+
+```typescript
+interface BuildTriggerSubBlocksOptions {
+  triggerId: string                              // e.g., 'service_event_a'
+  triggerOptions: Array<{ label: string; id: string }>  // Dropdown options
+  includeDropdown?: boolean                      // true only for primary trigger
+  setupInstructions: string                      // HTML instructions
+  extraFields?: SubBlockConfig[]                 // Service-specific fields
+  webhookPlaceholder?: string                    // Custom placeholder text
+}
+
+function buildTriggerSubBlocks(options: BuildTriggerSubBlocksOptions): SubBlockConfig[]
+```
+
+### What It Creates
+
+The helper creates this structure:
+1. **Dropdown** (only if `includeDropdown: true`) - Trigger type selector
+2. **Webhook URL** - Read-only field with copy button
+3. **Extra Fields** - Your service-specific fields (filters, options, etc.)
+4. **Save Button** - Activates the trigger
+5. **Instructions** - Setup guide for users
+
+All fields automatically have:
+- `mode: 'trigger'` - Only shown in trigger mode
+- `condition: { field: 'selectedTriggerId', value: triggerId }` - Only shown when this trigger is selected
+
+## Trigger Outputs & Webhook Input Formatting
+
+### Important: Two Sources of Truth
+
+There are two related but separate concerns:
+
+1. **Trigger `outputs`** - Schema/contract defining what fields SHOULD be available. Used by UI for tag dropdown.
+2. **`formatWebhookInput`** - Implementation that transforms raw webhook payload into actual data. Located in `apps/sim/lib/webhooks/utils.server.ts`.
+
+**These MUST be aligned.** The fields returned by `formatWebhookInput` should match what's defined in trigger `outputs`. If they differ:
+- Tag dropdown shows fields that don't exist (broken variable resolution)
+- Or actual data has fields not shown in dropdown (users can't discover them)
+
+### When to Add a formatWebhookInput Handler
+
+- **Simple providers**: If the raw webhook payload structure already matches your outputs, you don't need a handler. The generic fallback returns `body` directly.
+- **Complex providers**: If you need to transform, flatten, extract nested data, compute fields, or handle conditional logic, add a handler.
+
+### Adding a Handler
+
+In `apps/sim/lib/webhooks/utils.server.ts`, add a handler block:
+
+```typescript
+if (foundWebhook.provider === '{service}') {
+  // Transform raw webhook body to match trigger outputs
+  return {
+    eventType: body.type,
+    resourceId: body.data?.id || '',
+    timestamp: body.created_at,
+    resource: body.data,
+  }
+}
+```
+
+**Key rules:**
+- Return fields that match your trigger `outputs` definition exactly
+- No wrapper objects like `webhook: { data: ... }` or `{service}: { ... }`
+- No duplication (don't spread body AND add individual fields)
+- Use `null` for missing optional data, not empty objects with empty strings
+
+### Verify Alignment
+
+Run the alignment checker:
+```bash
+bunx scripts/check-trigger-alignment.ts {service}
+```
+
+## Trigger Outputs
+
+Trigger outputs use the same schema as block outputs (NOT tool outputs).
+
+**Supported:**
+- `type` and `description` for simple fields
+- Nested object structure for complex data
+
+**NOT Supported:**
+- `optional: true` (tool outputs only)
+- `items` property (tool outputs only)
+
+```typescript
+export function buildOutputs(): Record<string, TriggerOutput> {
+  return {
+    // Simple fields
+    eventType: { type: 'string', description: 'Event type' },
+    timestamp: { type: 'string', description: 'When it occurred' },
+
+    // Complex data - use type: 'json'
+    payload: { type: 'json', description: 'Full event payload' },
+
+    // Nested structure
+    resource: {
+      id: { type: 'string', description: 'Resource ID' },
+      name: { type: 'string', description: 'Resource name' },
+    },
+  }
+}
+```
+
+## Generic Webhook Trigger Pattern
+
+For services with many event types, create a generic webhook that accepts all events:
+
+```typescript
+export const {service}WebhookTrigger: TriggerConfig = {
+  id: '{service}_webhook',
+  name: '{Service} Webhook (All Events)',
+  // ...
+
+  subBlocks: buildTriggerSubBlocks({
+    triggerId: '{service}_webhook',
+    triggerOptions: {service}TriggerOptions,
+    setupInstructions: {service}SetupInstructions('All Events'),
+    extraFields: [
+      // Event type filter (optional)
+      {
+        id: 'eventTypes',
+        title: 'Event Types',
+        type: 'dropdown',
+        multiSelect: true,
+        options: [
+          { label: 'Event A', id: 'event_a' },
+          { label: 'Event B', id: 'event_b' },
+        ],
+        placeholder: 'Leave empty for all events',
+        mode: 'trigger',
+        condition: { field: 'selectedTriggerId', value: '{service}_webhook' },
+      },
+      // Plus any other service-specific fields
+      ...build{Service}ExtraFields('{service}_webhook'),
+    ],
+  }),
+}
+```
+
+## Checklist Before Finishing
+
+### Utils
+- [ ] Created `{service}TriggerOptions` array with all trigger IDs
+- [ ] Created `{service}SetupInstructions` function with clear steps
+- [ ] Created `build{Service}ExtraFields` for service-specific fields
+- [ ] Created output builders for each trigger type
+
+### Triggers
+- [ ] Primary trigger has `includeDropdown: true`
+- [ ] Secondary triggers do NOT have `includeDropdown`
+- [ ] All triggers use `buildTriggerSubBlocks` helper
+- [ ] All triggers have proper outputs defined
+- [ ] Created `index.ts` barrel export
+
+### Registration
+- [ ] All triggers imported in `triggers/registry.ts`
+- [ ] All triggers added to `TRIGGER_REGISTRY`
+- [ ] Block has `triggers.enabled: true`
+- [ ] Block has all trigger IDs in `triggers.available`
+- [ ] Block spreads all trigger subBlocks: `...getTrigger('id').subBlocks`
+
+### Automatic Webhook Registration (if supported)
+- [ ] Added API key field to `build{Service}ExtraFields` with `password: true`
+- [ ] Updated setup instructions for automatic webhook creation
+- [ ] Added provider-specific logic to `apps/sim/app/api/webhooks/route.ts`
+- [ ] Added `create{Service}WebhookSubscription` helper function
+- [ ] Added `delete{Service}Webhook` function to `provider-subscriptions.ts`
+- [ ] Added provider to `cleanupExternalWebhook` function
+
+### Webhook Input Formatting
+- [ ] Added handler in `apps/sim/lib/webhooks/utils.server.ts` (if custom formatting needed)
+- [ ] Handler returns fields matching trigger `outputs` exactly
+- [ ] Run `bunx scripts/check-trigger-alignment.ts {service}` to verify alignment
+
+### Testing
+- [ ] Run `bun run type-check` to verify no TypeScript errors
+- [ ] Restart dev server to pick up new triggers
+- [ ] Test trigger UI shows correctly in the block
+- [ ] Test automatic webhook creation works (if applicable)

.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."

.agents/skills/validate-connector/SKILL.md

@@ -0,0 +1,333 @@
+---
+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.
+
+## 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
+
+### 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
+
+## 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

.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."

.agents/skills/validate-integration/SKILL.md

@@ -0,0 +1,289 @@
+---
+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
+
+## 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

.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."

.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

.claude/commands/add-connector.md

@@ -0,0 +1,437 @@
+---
+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) => {
+    // Paginate via cursor, extract text, compute SHA-256 hash
+    // Return { documents: ExternalDocument[], nextCursor?, hasMore }
+  },
+
+  getDocument: async (accessToken, sourceConfig, externalId) => {
+    // Return ExternalDocument 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
+  mimeType: 'text/plain'     // Always text/plain (content is extracted)
+  contentHash: string         // SHA-256 of content (change detection)
+  sourceUrl?: string          // Link back to original (stored on document record)
+  metadata?: Record<string, unknown>  // Source-specific data (fed to mapTags)
+}
+```
+
+## Content Hashing (Required)
+
+The sync engine uses content hashes for change detection:
+
+```typescript
+async function computeContentHash(content: string): Promise<string> {
+  const data = new TextEncoder().encode(content)
+  const hashBuffer = await crypto.subtle.digest('SHA-256', data)
+  return Array.from(new Uint8Array(hashBuffer)).map(b => b.toString(16).padStart(2, '0')).join('')
+}
+```
+
+## 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**: `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 and computes content hashes
+- [ ] `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`

.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`

.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)

.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

.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

.claude/rules/sim-testing.md

@@ -8,51 +8,210 @@ 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`
+- `drizzle-orm` → `drizzleOrmMock`
+- `@sim/logger` → `loggerMock`
+- `@/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(),
+}))
+```
+
+### NEVER use `mockAuth()`, `mockConsoleLogger()`, or `setupCommonApiMocks()` from `@sim/testing`
+
+These helpers internally use `vi.doMock()` which is slow. Use direct `vi.hoisted()` + `vi.mock()` instead.
+
+### 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()
+```
+
+## Mock Pattern Reference
+
+### Auth mocking (API routes)
+
+```typescript
+const { mockGetSession } = vi.hoisted(() => ({
+  mockGetSession: vi.fn(),
+}))
+
+vi.mock('@/lib/auth', () => ({
+  auth: { api: { getSession: vi.fn() } },
+  getSession: mockGetSession,
+}))
+
+// In tests:
+mockGetSession.mockResolvedValue({ user: { id: 'user-1', email: 'test@example.com' } })
+mockGetSession.mockResolvedValue(null) // unauthenticated
+```
+
+### Hybrid auth mocking
+
+```typescript
+const { mockCheckSessionOrInternalAuth } = vi.hoisted(() => ({
+  mockCheckSessionOrInternalAuth: vi.fn(),
+}))
+
+vi.mock('@/lib/auth/hybrid', () => ({
+  checkSessionOrInternalAuth: mockCheckSessionOrInternalAuth,
+}))
+
+// In tests:
+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()` |
+| **Mocks** | `loggerMock`, `databaseMock`, `drizzleOrmMock`, `setupGlobalFetchMock()` |
+| **Factories** | `createSession()`, `createWorkflowRecord()`, `createBlock()`, `createExecutionContext()` |
 | **Builders** | `WorkflowBuilder`, `ExecutionContextBuilder` |
 | **Assertions** | `expectWorkflowAccessGranted()`, `expectBlockExecuted()` |
+| **Requests** | `createMockRequest()`, `createEnvMock()` |
 
-## 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. `vi.hoisted()` + `vi.mock()` + static imports — never `vi.resetModules()` + `vi.doMock()` + dynamic imports
+3. `vi.mock()` calls before importing mocked modules
+4. `@sim/testing` utilities over local mocks
+5. `beforeEach(() => vi.clearAllMocks())` to reset state — no redundant `afterEach`
+6. No `vi.importActual()` — mock everything explicitly
+7. No `mockAuth()`, `mockConsoleLogger()`, `setupCommonApiMocks()` — use direct mocks
+8. Mock heavy deps (`@/blocks`, `@/tools/registry`, `@/triggers`) in tests that don't need them
+9. Use absolute imports in test files
+10. Avoid real timers — use 1ms delays or `vi.useFakeTimers()`

.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.

.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)

.cursor/rules/sim-testing.mdc

@@ -7,51 +7,210 @@ globs: ["apps/sim/**/*.test.ts", "apps/sim/**/*.test.tsx"]
 
 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`
+- `drizzle-orm` → `drizzleOrmMock`
+- `@sim/logger` → `loggerMock`
+- `@/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(),
+}))
+```
+
+### NEVER use `mockAuth()`, `mockConsoleLogger()`, or `setupCommonApiMocks()` from `@sim/testing`
+
+These helpers internally use `vi.doMock()` which is slow. Use direct `vi.hoisted()` + `vi.mock()` instead.
+
+### 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()
+```
+
+## Mock Pattern Reference
+
+### Auth mocking (API routes)
+
+```typescript
+const { mockGetSession } = vi.hoisted(() => ({
+  mockGetSession: vi.fn(),
+}))
+
+vi.mock('@/lib/auth', () => ({
+  auth: { api: { getSession: vi.fn() } },
+  getSession: mockGetSession,
+}))
+
+// In tests:
+mockGetSession.mockResolvedValue({ user: { id: 'user-1', email: 'test@example.com' } })
+mockGetSession.mockResolvedValue(null) // unauthenticated
+```
+
+### Hybrid auth mocking
+
+```typescript
+const { mockCheckSessionOrInternalAuth } = vi.hoisted(() => ({
+  mockCheckSessionOrInternalAuth: vi.fn(),
+}))
+
+vi.mock('@/lib/auth/hybrid', () => ({
+  checkSessionOrInternalAuth: mockCheckSessionOrInternalAuth,
+}))
+
+// In tests:
+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()` |
+| **Mocks** | `loggerMock`, `databaseMock`, `drizzleOrmMock`, `setupGlobalFetchMock()` |
+| **Factories** | `createSession()`, `createWorkflowRecord()`, `createBlock()`, `createExecutionContext()` |
 | **Builders** | `WorkflowBuilder`, `ExecutionContextBuilder` |
 | **Assertions** | `expectWorkflowAccessGranted()`, `expectBlockExecuted()` |
+| **Requests** | `createMockRequest()`, `createEnvMock()` |
 
-## 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. `vi.hoisted()` + `vi.mock()` + static imports — never `vi.resetModules()` + `vi.doMock()` + dynamic imports
+3. `vi.mock()` calls before importing mocked modules
+4. `@sim/testing` utilities over local mocks
+5. `beforeEach(() => vi.clearAllMocks())` to reset state — no redundant `afterEach`
+6. No `vi.importActual()` — mock everything explicitly
+7. No `mockAuth()`, `mockConsoleLogger()`, `setupCommonApiMocks()` — use direct mocks
+8. Mock heavy deps (`@/blocks`, `@/tools/registry`, `@/triggers`) in tests that don't need them
+9. Use absolute imports in test files
+10. Avoid real timers — use 1ms delays or `vi.useFakeTimers()`

.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

.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 \

.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
@@ -23,7 +23,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 }}
@@ -49,7 +49,7 @@ jobs:
   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' || github.ref == 'refs/heads/dev')
     runs-on: blacksmith-8vcpu-ubuntu-2404
     permissions:
       contents: read
@@ -75,8 +75,8 @@ jobs:
       - 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
@@ -109,6 +109,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
@@ -144,7 +146,6 @@ jobs:
           tags: ${{ steps.meta.outputs.tags }}
           provenance: false
           sbom: false
-          no-cache: true
 
   # Build ARM64 images for GHCR (main branch only, runs in parallel)
   build-ghcr-arm64:
@@ -205,7 +206,6 @@ jobs:
           tags: ${{ steps.meta.outputs.tags }}
           provenance: false
           sbom: false
-          no-cache: true
 
   # Create GHCR multi-arch manifests (only for main, after both builds)
   create-ghcr-manifests:

.github/workflows/docs-embeddings.yml

@@ -20,7 +20,7 @@ jobs:
       - 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

.github/workflows/i18n.yml

@@ -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
@@ -122,7 +122,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

.github/workflows/images.yml

@@ -36,8 +36,8 @@ jobs:
       - 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
@@ -97,7 +99,6 @@ jobs:
           tags: ${{ steps.meta.outputs.tags }}
           provenance: false
           sbom: false
-          no-cache: true
 
   build-ghcr-arm64:
     name: Build ARM64 (GHCR Only)
@@ -144,11 +145,10 @@ jobs:
           tags: ${{ steps.meta.outputs.tags }}
           provenance: false
           sbom: false
-          no-cache: true
 
   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:

.github/workflows/migrations.yml

@@ -19,7 +19,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

.github/workflows/publish-cli.yml

@@ -19,7 +19,7 @@ jobs:
       - 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

.github/workflows/publish-ts-sdk.yml

@@ -19,7 +19,7 @@ jobs:
       - 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

.github/workflows/test-build.yml

@@ -10,7 +10,7 @@ permissions:
 jobs:
   test-build:
     name: Test and Build
-    runs-on: blacksmith-4vcpu-ubuntu-2404
+    runs-on: blacksmith-8vcpu-ubuntu-2404
 
     steps:
       - name: Checkout code
@@ -19,7 +19,7 @@ jobs:
       - 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,6 +90,16 @@ 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
 
@@ -85,6 +109,7 @@ jobs:
           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
@@ -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

.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/

AGENTS.md

@@ -0,0 +1,383 @@
+# 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
+- **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

CLAUDE.md

@@ -134,21 +134,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 +210,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
 

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,11 @@ docker compose -f docker-compose.prod.yml up -d
 
 Open [http://localhost:3000](http://localhost:3000)
 
-#### Using Local Models with Ollama
+#### Background worker note
 
-Run Sim with local AI models using [Ollama](https://ollama.ai) - no external APIs required:
+The Docker Compose stack starts a dedicated worker container by default. If `REDIS_URL` is not configured, the worker will start, log that it is idle, and do no queue processing. This is expected. Queue-backed API, webhook, and schedule execution requires Redis; installs without Redis continue to use the inline execution path.
 
-```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 +90,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 +105,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,16 +117,18 @@ 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, realtime socket server, and the BullMQ worker
 ```
 
-Or run separately: `bun run dev` (Next.js) and `cd apps/sim && bun run dev:sockets` (realtime).
+If `REDIS_URL` is not configured, the worker will remain idle and execution continues inline.
+
+Or run separately: `bun run dev` (Next.js), `cd apps/sim && bun run dev:sockets` (realtime), and `cd apps/sim && bun run worker` (BullMQ worker).
 
 ## Copilot API Keys
 
@@ -159,18 +139,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
 

apps/docs/app/[lang]/[[...slug]]/page.tsx

@@ -1,5 +1,8 @@
 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'
@@ -12,28 +15,75 @@ 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'
 
+const SUPPORTED_LANGUAGES: Set<string> = new Set(i18n.languages)
+const BASE_URL = 'https://docs.sim.ai'
+
+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 +91,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 +106,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}`,
         })
       }
     })
@@ -73,7 +123,6 @@ export default async function Page(props: { params: Promise<{ slug?: string[]; l
 
   const CustomFooter = () => (
     <div className='mt-12'>
-      {/* Navigation links */}
       <div className='flex items-center justify-between py-8'>
         {neighbours?.previous ? (
           <Link
@@ -100,10 +149,8 @@ export default async function Page(props: { params: Promise<{ slug?: string[]; l
         )}
       </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'
@@ -169,13 +216,70 @@ export default async function Page(props: { params: Promise<{ slug?: string[]; l
     </div>
   )
 
+  if (isOpenAPI && data.getAPIPageProps) {
+    const apiProps = data.getAPIPageProps()
+    const apiPageContent = getApiSpecContent(
+      data.title,
+      data.description,
+      apiProps.operations ?? []
+    )
+
+    return (
+      <>
+        <StructuredData
+          title={data.title}
+          description={data.description || ''}
+          url={`${BASE_URL}${page.url}`}
+          lang={lang}
+          breadcrumb={breadcrumbs}
+        />
+        <style>{`#nd-page { grid-column: main-start / toc-end !important; max-width: 1400px !important; }`}</style>
+        <DocsPage
+          toc={data.toc}
+          breadcrumb={{
+            enabled: false,
+          }}
+          tableOfContent={{
+            style: 'clerk',
+            enabled: false,
+          }}
+          tableOfContentPopover={{
+            style: 'clerk',
+            enabled: false,
+          }}
+          footer={{
+            enabled: true,
+            component: <CustomFooter />,
+          }}
+        >
+          <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>{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
@@ -252,27 +356,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 platform to build AI agents and run your agentic workforce.',
     keywords: [
-      'AI workflow builder',
-      'visual workflow editor',
-      'AI automation',
-      'workflow automation',
       'AI agents',
-      'no-code AI',
-      'drag and drop workflows',
+      'agentic workforce',
+      'AI agent platform',
+      'agentic workflows',
+      'LLM orchestration',
+      'AI automation',
+      'knowledge base',
+      'AI integrations',
       data.title?.toLowerCase().split(' '),
     ]
       .flat()
@@ -282,14 +388,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 platform to build AI agents and run your agentic workforce.',
       url: fullUrl,
       siteName: 'Sim Documentation',
       type: 'article',
-      locale: params.lang === 'en' ? 'en_US' : `${params.lang}_${params.lang.toUpperCase()}`,
+      locale: lang === 'en' ? 'en_US' : `${lang}_${lang.toUpperCase()}`,
       alternateLocale: ['en', 'es', 'fr', 'de', 'ja', 'zh']
-        .filter((lang) => lang !== params.lang)
-        .map((lang) => (lang === 'en' ? 'en_US' : `${lang}_${lang.toUpperCase()}`)),
+        .filter((l) => l !== lang)
+        .map((l) => (l === 'en' ? 'en_US' : `${l}_${l.toUpperCase()}`)),
       images: [
         {
           url: ogImageUrl,
@@ -303,7 +410,8 @@ 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 platform to build AI agents and run your agentic workforce.',
       images: [ogImageUrl],
       creator: '@simdotai',
       site: '@simdotai',
@@ -323,13 +431,13 @@ export async function generateMetadata(props: {
     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}`, '')}`,
       },
     },
   }

apps/docs/app/[lang]/layout.tsx

@@ -10,6 +10,7 @@ import {
   SidebarSeparator,
 } from '@/components/docs-layout/sidebar-components'
 import { Navbar } from '@/components/navbar/navbar'
+import { AnimatedBlocks } from '@/components/ui/animated-blocks'
 import { SimLogoFull } from '@/components/ui/sim-logo'
 import { i18n } from '@/lib/i18n'
 import { source } from '@/lib/source'
@@ -55,15 +56,18 @@ 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.',
+      'Documentation for Sim — the open-source platform to build AI agents and run your agentic workforce. Connect 1,000+ integrations and LLMs to deploy and orchestrate agentic workflows.',
     url: 'https://docs.sim.ai',
     publisher: {
       '@type': 'Organization',
@@ -99,6 +103,7 @@ 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' />
+        <AnimatedBlocks />
         <RootProvider i18n={provider(lang)}>
           <Navbar />
           <DocsLayout
@@ -107,6 +112,7 @@ export default async function Layout({ children, params }: LayoutProps) {
               title: <SimLogoFull className='h-7 w-auto' />,
             }}
             sidebar={{
+              tabs: false,
               defaultOpenLevel: 0,
               collapsible: false,
               footer: null,

apps/docs/app/global.css

@@ -1,6 +1,7 @@
 @import "tailwindcss";
 @import "fumadocs-ui/css/neutral.css";
 @import "fumadocs-ui/css/preset.css";
+@import "fumadocs-openapi/css/preset.css";
 
 /* Prevent overscroll bounce effect on the page */
 html,
@@ -8,19 +9,24 @@ body {
   overscroll-behavior: none;
 }
 
+/* Prevent modals/dialogs from shifting layout via scroll-lock compensation */
+html,
+body {
+  padding-right: 0 !important;
+  margin-right: 0 !important;
+}
+
 @theme {
-  --color-fd-primary: #33c482; /* Green from Sim logo */
-  --font-geist-sans: var(--font-geist-sans);
-  --font-geist-mono: var(--font-geist-mono);
-}
-
-/* Ensure primary color is set in both light and dark modes */
-:root {
-  --color-fd-primary: #33c482;
+  --color-fd-primary: var(--color-fd-foreground);
 }
 
+/* Match landing page dark background (#1b1b1b) */
 .dark {
-  --color-fd-primary: #33c482;
+  --color-fd-background: hsl(0, 0%, 10.6%) !important;
+  --color-fd-card: hsl(0, 0%, 13%) !important;
+  --color-fd-popover: hsl(0, 0%, 14%) !important;
+  --color-fd-secondary: hsl(0, 0%, 15.5%) !important;
+  --color-fd-muted: hsl(0, 0%, 18%) !important;
 }
 
 /* Font family utilities */
@@ -34,16 +40,10 @@ body {
     "Liberation Mono", "Courier New", monospace;
 }
 
-/* Target any potential border classes */
-* {
-  --fd-border-sidebar: transparent !important;
-}
-
-/* Override any CSS custom properties for borders */
 :root {
   --fd-border: transparent !important;
   --fd-border-sidebar: transparent !important;
-  --fd-nav-height: 65px; /* Custom navbar height (h-16 = 64px + 1px border) */
+  --fd-nav-height: 93px; /* Custom navbar height (52px top + 1px divider + 40px tabs) */
   /* Content container width used to center main content */
   --spacing-fd-container: 1400px;
   /* Edge gutter = leftover space on each side of centered container */
@@ -59,34 +59,31 @@ body {
   --content-gap: 1.75rem;
 }
 
-/* Light mode navbar and search styling */
+/* Light mode navbar background */
 :root:not(.dark) nav {
   background-color: hsla(0, 0%, 96%, 0.85) !important;
 }
 
-:root:not(.dark) nav button[type="button"] {
-  background-color: hsla(0, 0%, 93%, 0.85) !important;
+/* Dark mode navbar background */
+:root.dark nav {
+  background-color: hsla(0, 0%, 10.6%, 0.92) !important;
+}
+
+:root.dark nav button[type="button"] {
+  background-color: hsla(0, 0%, 15%, 0.85) !important;
   backdrop-filter: blur(33px) saturate(180%) !important;
   -webkit-backdrop-filter: blur(33px) saturate(180%) !important;
-  color: rgba(0, 0, 0, 0.6) !important;
+  color: rgba(255, 255, 255, 0.5) !important;
 }
 
-:root:not(.dark) nav button[type="button"] kbd {
-  color: rgba(0, 0, 0, 0.6) !important;
-}
-
-/* Dark mode navbar and search styling */
-:root.dark nav {
-  background-color: hsla(0, 0%, 7.04%, 0.92) !important;
-  backdrop-filter: blur(25px) saturate(180%) brightness(0.6) !important;
-  -webkit-backdrop-filter: blur(25px) saturate(180%) brightness(0.6) !important;
+:root.dark nav button[type="button"] kbd {
+  color: rgba(255, 255, 255, 0.4) !important;
 }
 
 /* Floating sidebar appearance - remove background */
 [data-sidebar-container],
 #nd-sidebar {
   background: transparent !important;
-  background-color: transparent !important;
   border: none !important;
   --color-fd-muted: transparent !important;
   --color-fd-card: transparent !important;
@@ -96,9 +93,7 @@ body {
 aside[data-sidebar],
 aside#nd-sidebar {
   background: transparent !important;
-  background-color: transparent !important;
   border: none !important;
-  border-right: none !important;
 }
 
 /* Fumadocs v16: Add sidebar placeholder styling for grid area */
@@ -111,7 +106,7 @@ aside#nd-sidebar {
   display: none !important;
 }
 
-/* Mobile only: Reduce gap between navbar and content */
+/* Mobile only: Reduce gap between navbar and content (custom navbar hidden on mobile) */
 @media (max-width: 1023px) {
   #nd-docs-layout {
     margin-top: -25px;
@@ -135,11 +130,11 @@ aside#nd-sidebar {
 /* On mobile, let fumadocs handle the layout natively */
 @media (min-width: 1024px) {
   :root {
-    --fd-banner-height: 65px !important; /* 64px navbar + 1px border */
+    --fd-banner-height: 93px !important; /* 52px top + 1px divider + 40px tabs */
   }
 
   #nd-docs-layout {
-    --fd-docs-height: calc(100dvh - 65px) !important; /* 64px navbar + 1px border */
+    --fd-docs-height: calc(100dvh - 93px) !important; /* 52px top + 1px divider + 40px tabs */
     --fd-sidebar-width: 300px !important;
     margin-left: var(--sidebar-offset) !important;
     margin-right: var(--toc-offset) !important;
@@ -157,7 +152,6 @@ aside#nd-sidebar {
 #nd-sidebar > div {
   padding: 0.5rem 12px 12px;
   background: transparent !important;
-  background-color: transparent !important;
 }
 
 /* Override sidebar item styling to match Raindrop */
@@ -434,10 +428,6 @@ aside[data-sidebar],
 #nd-sidebar,
 #nd-sidebar * {
   border: none !important;
-  border-right: none !important;
-  border-left: none !important;
-  border-top: none !important;
-  border-bottom: none !important;
 }
 
 /* Override fumadocs background colors for sidebar */
@@ -447,7 +437,6 @@ aside[data-sidebar],
   --color-fd-muted: transparent !important;
   --color-fd-secondary: transparent !important;
   background: transparent !important;
-  background-color: transparent !important;
 }
 
 /* Force normal text flow in sidebar */
@@ -564,16 +553,700 @@ main[data-main] {
   padding-top: 1.5rem !important;
 }
 
-/* Override Fumadocs default content padding */
-article[data-content],
-div[data-content] {
-  padding-top: 1.5rem !important;
-}
-
-/* Remove any unwanted borders/outlines from video elements */
+/* Remove any unwanted outlines from video elements */
 video {
   outline: none !important;
-  border-style: solid !important;
+}
+
+/* API Reference Pages — Mintlify-style overrides */
+
+/* OpenAPI pages: span main + TOC grid columns for wide two-column layout.
+   Use named grid lines from grid-template-areas so this works regardless
+   of whether the grid has 3 columns (production) or 5 columns (local dev). */
+#nd-page:has(.api-page-header) {
+  grid-column: main-start / toc-end !important;
+  max-width: 1400px !important;
+}
+
+/* Hide the empty TOC aside on OpenAPI pages so it doesn't overlay content */
+#nd-docs-layout:has(#nd-page:has(.api-page-header)) #nd-toc {
+  display: none;
+}
+
+/* Hide the default "Response Body" heading rendered by fumadocs-openapi */
+.response-section-wrapper > .response-section-content > h2,
+.response-section-wrapper > .response-section-content > h3 {
+  display: none !important;
+}
+
+/* Hide default accordion triggers (status code rows) — we show our own dropdown */
+.response-section-wrapper [data-orientation="vertical"] > [data-state] > h3 {
+  display: none !important;
+}
+
+/* Ensure API reference pages use the same font as the rest of the docs */
+#nd-page:has(.api-page-header),
+#nd-page:has(.api-page-header) h2,
+#nd-page:has(.api-page-header) h3,
+#nd-page:has(.api-page-header) h4,
+#nd-page:has(.api-page-header) p,
+#nd-page:has(.api-page-header) span,
+#nd-page:has(.api-page-header) div,
+#nd-page:has(.api-page-header) label,
+#nd-page:has(.api-page-header) button {
+  font-family: var(--font-geist-sans), ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont,
+    "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+}
+
+/* Method badge pills — shared background colors (page + sidebar) */
+span.font-mono.font-medium[data-method="get"],
+span.font-mono.font-medium[data-method="head"],
+span.font-mono.font-medium[data-method="options"] {
+  background-color: rgb(220 252 231 / 0.85);
+}
+html.dark span.font-mono.font-medium[data-method="get"],
+html.dark span.font-mono.font-medium[data-method="head"],
+html.dark span.font-mono.font-medium[data-method="options"] {
+  background-color: rgb(34 197 94 / 0.15);
+}
+span.font-mono.font-medium[data-method="post"] {
+  background-color: rgb(219 234 254 / 0.85);
+}
+html.dark span.font-mono.font-medium[data-method="post"] {
+  background-color: rgb(59 130 246 / 0.15);
+}
+span.font-mono.font-medium[data-method="put"] {
+  background-color: rgb(254 249 195 / 0.85);
+}
+html.dark span.font-mono.font-medium[data-method="put"] {
+  background-color: rgb(234 179 8 / 0.15);
+}
+span.font-mono.font-medium[data-method="patch"] {
+  background-color: rgb(255 237 213 / 0.85);
+}
+html.dark span.font-mono.font-medium[data-method="patch"] {
+  background-color: rgb(249 115 22 / 0.15);
+}
+span.font-mono.font-medium[data-method="delete"] {
+  background-color: rgb(254 226 226 / 0.85);
+}
+html.dark span.font-mono.font-medium[data-method="delete"] {
+  background-color: rgb(239 68 68 / 0.15);
+}
+
+/* Sidebar links with method badges — flex for vertical centering */
+#nd-sidebar a:has(span.font-mono.font-medium) {
+  display: flex !important;
+  align-items: center !important;
+  gap: 0.375rem;
+}
+
+/* Sidebar method badges — fixed-width for right-aligned labels */
+#nd-sidebar a span.font-mono.font-medium {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 2.625rem;
+  font-size: 0.625rem !important;
+  line-height: 1 !important;
+  padding: 0.15625rem 0.25rem;
+  border-radius: 0.1875rem;
+  flex-shrink: 0;
+}
+
+/* Footer navigation method badges — pill styling to match sidebar */
+#nd-page span.font-mono.font-medium[data-method] {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 0.625rem !important;
+  line-height: 1 !important;
+  padding: 0.15625rem 0.375rem;
+  border-radius: 0.1875rem;
+}
+
+/* Code block containers — match regular docs styling */
+#nd-page:has(.api-page-header) figure.shiki {
+  border-radius: 0.75rem !important;
+  background-color: var(--color-fd-card) !important;
+}
+
+/* Hide "Filter Properties" search bar everywhere — main page and popovers */
+input[placeholder="Filter Properties"] {
+  display: none !important;
+}
+div:has(> input[placeholder="Filter Properties"]) {
+  display: none !important;
+}
+/* Remove top border on first visible property after hidden Filter Properties */
+div:has(> input[placeholder="Filter Properties"]) + .text-sm.border-t {
+  border-top: none !important;
+}
+
+/* Hide "TypeScript Definitions" copy panel on API pages */
+#nd-page:has(.api-page-header) div.not-prose.rounded-xl.border.p-3.mb-4 {
+  display: none !important;
+}
+#nd-page:has(.api-page-header) div.not-prose.rounded-xl.border.p-3:has(> div > p.font-medium) {
+  display: none !important;
+}
+
+/* Hide info tags (Format, Default, etc.) everywhere — main page and popovers */
+div.flex.flex-row.gap-2.flex-wrap.not-prose:has(> div.bg-fd-secondary) {
+  display: none !important;
+}
+div.flex.flex-row.items-start.bg-fd-secondary.border.rounded-lg.text-xs {
+  display: none !important;
+}
+
+/* Method+path bar — cleaner, lighter styling like Gumloop.
+   Override bg-fd-card CSS variable directly for reliability. */
+#nd-page:has(.api-page-header) div.flex.flex-row.items-center.rounded-xl.border.not-prose {
+  --color-fd-card: rgb(249 250 251) !important;
+  background-color: rgb(249 250 251) !important;
+  border-color: rgb(229 231 235) !important;
+}
+html.dark
+  #nd-page:has(.api-page-header)
+  div.flex.flex-row.items-center.rounded-xl.border.not-prose {
+  --color-fd-card: rgb(24 24 27) !important;
+  background-color: rgb(24 24 27) !important;
+  border-color: rgb(63 63 70) !important;
+}
+/* Method badge inside path bar — cleaner sans-serif, softer colors */
+#nd-page:has(.api-page-header)
+  div.flex.flex-row.items-center.rounded-xl.border.not-prose
+  span.font-mono.font-medium {
+  font-family: var(--font-geist-sans), ui-sans-serif, system-ui, sans-serif !important;
+  font-weight: 600 !important;
+  font-size: 0.6875rem !important;
+  letter-spacing: 0.025em;
+  text-transform: uppercase;
+  padding: 0.125rem 0.5rem !important;
+  border-radius: 0.375rem !important;
+}
+/* Path bar per-method colors (fumadocs renders these, so we match by class) */
+/* GET */
+#nd-page:has(.api-page-header)
+  div.flex.flex-row.items-center.rounded-xl.border.not-prose
+  span.font-mono.font-medium[class*="text-green"] {
+  color: rgb(22 163 74) !important;
+  background-color: rgb(220 252 231 / 0.7) !important;
+}
+html.dark
+  #nd-page:has(.api-page-header)
+  div.flex.flex-row.items-center.rounded-xl.border.not-prose
+  span.font-mono.font-medium[class*="text-green"] {
+  color: rgb(74 222 128) !important;
+  background-color: rgb(34 197 94 / 0.15) !important;
+}
+/* POST */
+#nd-page:has(.api-page-header)
+  div.flex.flex-row.items-center.rounded-xl.border.not-prose
+  span.font-mono.font-medium[class*="text-blue"] {
+  color: rgb(37 99 235) !important;
+  background-color: rgb(219 234 254 / 0.7) !important;
+}
+html.dark
+  #nd-page:has(.api-page-header)
+  div.flex.flex-row.items-center.rounded-xl.border.not-prose
+  span.font-mono.font-medium[class*="text-blue"] {
+  color: rgb(96 165 250) !important;
+  background-color: rgb(59 130 246 / 0.15) !important;
+}
+/* PUT */
+#nd-page:has(.api-page-header)
+  div.flex.flex-row.items-center.rounded-xl.border.not-prose
+  span.font-mono.font-medium[class*="text-yellow"] {
+  color: rgb(161 98 7) !important;
+  background-color: rgb(254 249 195 / 0.7) !important;
+}
+html.dark
+  #nd-page:has(.api-page-header)
+  div.flex.flex-row.items-center.rounded-xl.border.not-prose
+  span.font-mono.font-medium[class*="text-yellow"] {
+  color: rgb(250 204 21) !important;
+  background-color: rgb(234 179 8 / 0.15) !important;
+}
+/* PATCH */
+#nd-page:has(.api-page-header)
+  div.flex.flex-row.items-center.rounded-xl.border.not-prose
+  span.font-mono.font-medium[class*="text-orange"] {
+  color: rgb(194 65 12) !important;
+  background-color: rgb(255 237 213 / 0.7) !important;
+}
+html.dark
+  #nd-page:has(.api-page-header)
+  div.flex.flex-row.items-center.rounded-xl.border.not-prose
+  span.font-mono.font-medium[class*="text-orange"] {
+  color: rgb(251 146 60) !important;
+  background-color: rgb(249 115 22 / 0.15) !important;
+}
+/* DELETE */
+#nd-page:has(.api-page-header)
+  div.flex.flex-row.items-center.rounded-xl.border.not-prose
+  span.font-mono.font-medium[class*="text-red"] {
+  color: rgb(185 28 28) !important;
+  background-color: rgb(254 226 226 / 0.7) !important;
+}
+html.dark
+  #nd-page:has(.api-page-header)
+  div.flex.flex-row.items-center.rounded-xl.border.not-prose
+  span.font-mono.font-medium[class*="text-red"] {
+  color: rgb(248 113 113) !important;
+  background-color: rgb(239 68 68 / 0.15) !important;
+}
+
+/* Path text inside method+path bar — monospace, bright like Gumloop */
+#nd-page:has(.api-page-header) div.flex.flex-row.items-center.rounded-xl.border.not-prose code {
+  color: rgb(55 65 81) !important;
+  background: none !important;
+  border: none !important;
+  padding: 0 !important;
+  font-size: 0.8125rem !important;
+}
+html.dark
+  #nd-page:has(.api-page-header)
+  div.flex.flex-row.items-center.rounded-xl.border.not-prose
+  code {
+  color: rgb(229 231 235) !important;
+}
+
+/* Inline code in API pages — neutral color instead of red.
+   Exclude code inside the method+path bar (handled above). */
+#nd-page:has(.api-page-header) .prose :not(pre) > code {
+  color: rgb(79 70 229) !important;
+}
+html.dark #nd-page:has(.api-page-header) .prose :not(pre) > code {
+  color: rgb(165 180 252) !important;
+}
+
+/* Response Section — custom dropdown-based rendering (Mintlify style) */
+
+/* Hide divider lines between accordion items */
+.response-section-wrapper [data-orientation="vertical"].divide-y > * {
+  border-top-width: 0 !important;
+  border-bottom-width: 0 !important;
+}
+.response-section-wrapper [data-orientation="vertical"].divide-y {
+  border-top: none !important;
+}
+
+/* Remove content type labels inside accordion items (we show one in the header) */
+.response-section-wrapper [data-orientation="vertical"] p.not-prose:has(code.text-xs) {
+  display: none !important;
+}
+
+/* Hide the top-level response description (e.g. "Execution was successfully cancelled.")
+   but NOT field descriptions inside Schema which also use prose-no-margin.
+   The response description is a direct child of AccordionContent (role=region) with mb-2. */
+.response-section-wrapper [data-orientation="vertical"] [role="region"] > .prose-no-margin.mb-2,
+.response-section-wrapper
+  [data-orientation="vertical"]
+  [role="region"]
+  > div
+  > .prose-no-margin.mb-2 {
+  display: none !important;
+}
+
+/* Remove left padding on accordion content so it aligns with Path Parameters */
+.response-section-wrapper [data-orientation="vertical"] [role="region"] {
+  padding-inline-start: 0 !important;
+}
+
+/* Response section header */
+.response-section-header {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  margin-top: 1.75rem;
+  margin-bottom: 0.5rem;
+}
+
+.response-section-title {
+  font-size: 1.5rem;
+  font-weight: 600;
+  margin: 0;
+  color: var(--color-fd-foreground);
+  font-family: var(--font-geist-sans), ui-sans-serif, system-ui, -apple-system, sans-serif;
+}
+
+.response-section-meta {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  margin-left: auto;
+}
+
+/* Status code dropdown */
+.response-section-dropdown-wrapper {
+  position: relative;
+}
+
+.response-section-dropdown-trigger {
+  display: flex;
+  align-items: center;
+  gap: 0.25rem;
+  padding: 0.125rem 0.25rem;
+  font-size: 0.875rem;
+  font-weight: 500;
+  color: var(--color-fd-muted-foreground);
+  background: none;
+  border: none;
+  cursor: pointer;
+  border-radius: 0.25rem;
+  transition: color 0.15s;
+  font-family: var(--font-geist-sans), ui-sans-serif, system-ui, sans-serif;
+}
+.response-section-dropdown-trigger:hover {
+  color: var(--color-fd-foreground);
+}
+
+.response-section-chevron {
+  width: 0.75rem;
+  height: 0.75rem;
+  transition: transform 0.15s;
+}
+.response-section-chevron-open {
+  transform: rotate(180deg);
+}
+
+.response-section-dropdown-menu {
+  position: absolute;
+  top: calc(100% + 0.25rem);
+  left: 0;
+  z-index: 50;
+  min-width: 5rem;
+  background-color: white;
+  border: 1px solid rgb(229 231 235);
+  border-radius: 0.5rem;
+  box-shadow:
+    0 4px 6px -1px rgb(0 0 0 / 0.1),
+    0 2px 4px -2px rgb(0 0 0 / 0.1);
+  padding: 0.25rem;
+  overflow: hidden;
+}
+html.dark .response-section-dropdown-menu {
+  background-color: rgb(24 24 27);
+  border-color: rgb(63 63 70);
+  box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.3);
+}
+
+.response-section-dropdown-item {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+  padding: 0.375rem 0.5rem;
+  font-size: 0.875rem;
+  color: var(--color-fd-muted-foreground);
+  background: none;
+  border: none;
+  cursor: pointer;
+  border-radius: 0.25rem;
+  transition:
+    background-color 0.1s,
+    color 0.1s;
+  font-family: var(--font-geist-sans), ui-sans-serif, system-ui, sans-serif;
+}
+.response-section-dropdown-item:hover {
+  background-color: rgb(243 244 246);
+  color: var(--color-fd-foreground);
+}
+html.dark .response-section-dropdown-item:hover {
+  background-color: rgb(39 39 42);
+}
+.response-section-dropdown-item-selected {
+  color: var(--color-fd-foreground);
+}
+
+.response-section-check {
+  width: 0.875rem;
+  height: 0.875rem;
+}
+
+.response-section-content-type {
+  font-size: 0.875rem;
+  color: var(--color-fd-muted-foreground);
+  font-family: var(--font-geist-sans), ui-sans-serif, system-ui, sans-serif;
+}
+
+/* Response schema container — remove border to match Path Parameters style */
+.response-section-wrapper [data-orientation="vertical"] .border.px-3.py-2.rounded-lg {
+  border: none !important;
+  padding: 0 !important;
+  border-radius: 0 !important;
+  background-color: transparent;
+}
+
+/* Property row — reorder: name (1) → type badge (2) → required badge (3) */
+#nd-page:has(.api-page-header) .flex.flex-wrap.items-center.gap-3.not-prose {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+}
+
+/* Name span — order 1 */
+#nd-page:has(.api-page-header)
+  .flex.flex-wrap.items-center.gap-3.not-prose
+  > span.font-medium.font-mono.text-fd-primary {
+  order: 1;
+}
+
+/* Type badge — order 2, grey pill */
+#nd-page:has(.api-page-header)
+  .flex.flex-wrap.items-center.gap-3.not-prose
+  > span.text-sm.font-mono.text-fd-muted-foreground {
+  order: 2;
+  background-color: rgb(241 245 249);
+  color: rgb(71 85 105);
+  padding: 0.1875rem 0.5rem;
+  border-radius: 0.375rem;
+  font-size: 0.6875rem;
+  line-height: 1.125rem;
+  font-weight: 500;
+  font-family: var(--font-geist-sans), ui-sans-serif, system-ui, sans-serif;
+}
+html.dark
+  #nd-page:has(.api-page-header)
+  .flex.flex-wrap.items-center.gap-3.not-prose
+  > span.text-sm.font-mono.text-fd-muted-foreground {
+  background-color: rgb(51 51 56);
+  color: rgb(212 212 220);
+}
+
+/* Hide the "*" inside the name span — we'll add "required" as a ::after on the flex row */
+#nd-page:has(.api-page-header) span.font-medium.font-mono.text-fd-primary > span.text-red-400 {
+  display: none;
+}
+
+/* Required badge — order 3, red pill */
+#nd-page:has(.api-page-header)
+  .flex.flex-wrap.items-center.gap-3.not-prose:has(span.text-red-400)::after {
+  content: "required";
+  order: 3;
+  display: inline-flex;
+  align-items: center;
+  background-color: rgb(254 226 226);
+  color: rgb(185 28 28);
+  padding: 0.1875rem 0.5rem;
+  border-radius: 0.375rem;
+  font-size: 0.6875rem;
+  line-height: 1.125rem;
+  font-weight: 500;
+  font-family: var(--font-geist-sans), ui-sans-serif, system-ui, sans-serif;
+}
+html.dark
+  #nd-page:has(.api-page-header)
+  .flex.flex-wrap.items-center.gap-3.not-prose:has(span.text-red-400)::after {
+  background-color: rgb(153 27 27 / 0.3);
+  color: rgb(252 165 165);
+}
+
+/* Optional "?" indicator — hide it */
+#nd-page:has(.api-page-header)
+  span.font-medium.font-mono.text-fd-primary
+  > span.text-fd-muted-foreground {
+  display: none;
+}
+
+/* Hide the auth scheme type label (e.g. "apiKey") next to Authorization heading */
+#nd-page:has(.api-page-header) .flex.items-start.justify-between.gap-2 > div.not-prose {
+  display: none !important;
+}
+
+/* Auth property — replace "<token>" with "string" badge, add "header" and "required" badges.
+   Auth properties use my-4 (vs py-4 for regular properties). */
+
+/* Auth property flex row — name: order 1, type: order 2, ::before "header": order 3, ::after "required": order 4 */
+#nd-page:has(.api-page-header)
+  div.my-4
+  > .flex.flex-wrap.items-center.gap-3.not-prose
+  > span.font-medium.font-mono.text-fd-primary {
+  order: 1;
+}
+#nd-page:has(.api-page-header)
+  div.my-4
+  > .flex.flex-wrap.items-center.gap-3.not-prose
+  > span.text-sm.font-mono.text-fd-muted-foreground {
+  order: 2;
+  font-size: 0;
+  padding: 0 !important;
+  background: none !important;
+  line-height: 0;
+}
+#nd-page:has(.api-page-header)
+  div.my-4
+  > .flex.flex-wrap.items-center.gap-3.not-prose
+  > span.text-sm.font-mono.text-fd-muted-foreground::after {
+  content: "string";
+  font-size: 0.6875rem;
+  line-height: 1.125rem;
+  font-weight: 500;
+  font-family: var(--font-geist-sans), ui-sans-serif, system-ui, sans-serif;
+  background-color: rgb(241 245 249);
+  color: rgb(71 85 105);
+  padding: 0.1875rem 0.5rem;
+  border-radius: 0.375rem;
+  display: inline-flex;
+  align-items: center;
+}
+html.dark
+  #nd-page:has(.api-page-header)
+  div.my-4
+  > .flex.flex-wrap.items-center.gap-3.not-prose
+  > span.text-sm.font-mono.text-fd-muted-foreground::after {
+  background-color: rgb(51 51 56);
+  color: rgb(212 212 220);
+}
+
+/* "header" badge via ::before on the auth flex row */
+#nd-page:has(.api-page-header) div.my-4 > .flex.flex-wrap.items-center.gap-3.not-prose::before {
+  content: "header";
+  order: 3;
+  display: inline-flex;
+  align-items: center;
+  background-color: rgb(241 245 249);
+  color: rgb(71 85 105);
+  padding: 0.1875rem 0.5rem;
+  border-radius: 0.375rem;
+  font-size: 0.6875rem;
+  line-height: 1.125rem;
+  font-weight: 500;
+  font-family: var(--font-geist-sans), ui-sans-serif, system-ui, sans-serif;
+}
+html.dark
+  #nd-page:has(.api-page-header)
+  div.my-4
+  > .flex.flex-wrap.items-center.gap-3.not-prose::before {
+  background-color: rgb(51 51 56);
+  color: rgb(212 212 220);
+}
+
+/* "required" badge via ::after on the auth flex row — red pill */
+#nd-page:has(.api-page-header) div.my-4 > .flex.flex-wrap.items-center.gap-3.not-prose::after {
+  content: "required";
+  order: 4;
+  display: inline-flex;
+  align-items: center;
+  background-color: rgb(254 226 226);
+  color: rgb(185 28 28);
+  padding: 0.1875rem 0.5rem;
+  border-radius: 0.375rem;
+  font-size: 0.6875rem;
+  line-height: 1.125rem;
+  font-weight: 500;
+  font-family: var(--font-geist-sans), ui-sans-serif, system-ui, sans-serif;
+}
+html.dark
+  #nd-page:has(.api-page-header)
+  div.my-4
+  > .flex.flex-wrap.items-center.gap-3.not-prose::after {
+  background-color: rgb(153 27 27 / 0.3);
+  color: rgb(252 165 165);
+}
+
+/* Hide "In: header" text below auth property — redundant with the header badge */
+#nd-page:has(.api-page-header) div.my-4 .prose-no-margin p:has(> code) {
+  display: none !important;
+}
+
+/* Section dividers — bottom border after Authorization and Body sections. */
+.api-section-divider {
+  padding-bottom: 0.5rem;
+  border-bottom: 1px solid rgb(229 231 235 / 0.6);
+}
+html.dark .api-section-divider {
+  border-bottom-color: rgb(255 255 255 / 0.07);
+}
+
+/* Property rows — breathing room like Mintlify.
+   Regular properties use border-t py-4; auth properties use border-t my-4. */
+#nd-page:has(.api-page-header) .text-sm.border-t.py-4 {
+  padding-top: 1.25rem !important;
+  padding-bottom: 1.25rem !important;
+}
+#nd-page:has(.api-page-header) .text-sm.border-t.my-4 {
+  margin-top: 1.25rem !important;
+  margin-bottom: 1.25rem !important;
+  padding-top: 1.25rem;
+}
+
+/* Divider lines between fields — very subtle like Mintlify */
+#nd-page:has(.api-page-header) .text-sm.border-t {
+  border-color: rgb(229 231 235 / 0.6);
+}
+html.dark #nd-page:has(.api-page-header) .text-sm.border-t {
+  border-color: rgb(255 255 255 / 0.07);
+}
+
+/* Body/Callback section "application/json" label — remove inline code styling */
+#nd-page:has(.api-page-header) .flex.gap-2.items-center.justify-between p.not-prose code.text-xs,
+#nd-page:has(.api-page-header) .flex.justify-between.gap-2.items-end p.not-prose code.text-xs {
+  background: none !important;
+  border: none !important;
+  padding: 0 !important;
+  color: var(--color-fd-muted-foreground) !important;
+  font-size: 0.875rem !important;
+  font-family: var(--font-geist-sans), ui-sans-serif, system-ui, sans-serif !important;
+}
+
+/* Object/array type triggers in property rows — order 2 + badge chip styling */
+#nd-page:has(.api-page-header) .flex.flex-wrap.items-center.gap-3.not-prose > button,
+#nd-page:has(.api-page-header) .flex.flex-wrap.items-center.gap-3.not-prose > span:has(> button) {
+  order: 2;
+  background-color: rgb(241 245 249);
+  color: rgb(71 85 105);
+  padding: 0.1875rem 0.5rem;
+  border-radius: 0.375rem;
+  font-size: 0.6875rem;
+  line-height: 1.125rem;
+  font-weight: 500;
+  font-family: var(--font-geist-sans), ui-sans-serif, system-ui, sans-serif;
+}
+html.dark #nd-page:has(.api-page-header) .flex.flex-wrap.items-center.gap-3.not-prose > button,
+html.dark
+  #nd-page:has(.api-page-header)
+  .flex.flex-wrap.items-center.gap-3.not-prose
+  > span:has(> button) {
+  background-color: rgb(51 51 56);
+  color: rgb(212 212 220);
+}
+
+/* Section headings (Authorization, Path Parameters, etc.) — consistent top spacing */
+#nd-page:has(.api-page-header) .min-w-0.flex-1 h2 {
+  margin-top: 1.75rem !important;
+  margin-bottom: 0.25rem !important;
+}
+
+/* Code examples in right column — wrap long lines instead of horizontal scroll */
+#nd-page:has(.api-page-header) pre {
+  white-space: pre-wrap !important;
+  word-break: break-all !important;
+}
+#nd-page:has(.api-page-header) pre code {
+  width: 100% !important;
+  word-break: break-all !important;
+  overflow-wrap: break-word !important;
+}
+
+/* API page header — constrain title/copy-page to left content column, not full width.
+   Only applies on OpenAPI pages (which have the two-column layout). */
+@media (min-width: 1280px) {
+  .api-page-header {
+    max-width: calc(100% - 400px - 1.5rem);
+  }
+}
+
+/* Footer navigation — constrain to left content column on OpenAPI pages only.
+   Target pages that contain the two-column layout via :has() selector. */
+#nd-page:has(.api-page-header) > div:last-child {
+  max-width: calc(100% - 400px - 1.5rem);
+}
+@media (max-width: 1024px) {
+  #nd-page:has(.api-page-header) > div:last-child {
+    max-width: 100%;
+  }
 }
 
 /* Tailwind v4 content sources */

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
-      </>
-    ),
-  },
-}

apps/docs/app/layout.tsx

@@ -1,32 +1,46 @@
 import type { ReactNode } from 'react'
+import type { Viewport } from 'next'
 
 export default function RootLayout({ children }: { children: ReactNode }) {
   return children
 }
 
+export const viewport: Viewport = {
+  width: 'device-width',
+  initialScale: 1,
+  themeColor: [
+    { media: '(prefers-color-scheme: light)', color: '#ffffff' },
+    { media: '(prefers-color-scheme: dark)', color: '#0c0c0c' },
+  ],
+}
+
 export const metadata = {
   metadataBase: new URL('https://docs.sim.ai'),
   title: {
-    default: 'Sim Documentation - Visual Workflow Builder for AI Applications',
-    template: '%s',
+    default: 'Sim Documentation — Build AI Agents & Run Your Agentic Workforce',
+    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 platform to build AI agents and run your agentic workforce. Connect 1,000+ integrations and LLMs to deploy and orchestrate agentic workflows.',
+  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 agents',
-    'no-code AI',
-    'drag and drop workflows',
+    'agentic workforce',
+    'AI agent platform',
+    'open-source AI agents',
+    'agentic workflows',
+    'LLM orchestration',
     'AI integrations',
-    'workflow canvas',
-    'AI Agent Workflow Builder',
-    'workflow orchestration',
-    'agent builder',
-    'AI workflow automation',
-    'visual programming',
+    'knowledge base',
+    'AI automation',
+    'workflow builder',
+    'AI workflow orchestration',
+    'enterprise AI',
+    'AI agent deployment',
+    'intelligent automation',
+    'AI tools',
   ],
   authors: [{ name: 'Sim Team', url: 'https://sim.ai' }],
   creator: 'Sim',
@@ -36,26 +50,37 @@ export const metadata = {
   manifest: '/favicon/site.webmanifest',
   icons: {
     icon: [
+      { url: '/icon.svg', type: 'image/svg+xml', sizes: 'any' },
       { url: '/favicon/favicon-16x16.png', sizes: '16x16', type: 'image/png' },
       { url: '/favicon/favicon-32x32.png', sizes: '32x32', type: 'image/png' },
+      { url: '/favicon/android-chrome-192x192.png', sizes: '192x192', type: 'image/png' },
+      { url: '/favicon/android-chrome-512x512.png', sizes: '512x512', type: 'image/png' },
     ],
     apple: '/favicon/apple-touch-icon.png',
-    shortcut: '/favicon/favicon.ico',
+    shortcut: '/icon.svg',
   },
   appleWebApp: {
     capable: true,
     statusBarStyle: 'default',
     title: 'Sim Docs',
   },
+  formatDetection: {
+    telephone: false,
+  },
+  other: {
+    'apple-mobile-web-app-capable': 'yes',
+    'mobile-web-app-capable': 'yes',
+    'msapplication-TileColor': '#33C482',
+  },
   openGraph: {
     type: 'website',
     locale: 'en_US',
     alternateLocale: ['es_ES', 'fr_FR', 'de_DE', 'ja_JP', 'zh_CN'],
     url: 'https://docs.sim.ai',
     siteName: 'Sim Documentation',
-    title: 'Sim Documentation - Visual Workflow Builder for AI Applications',
+    title: 'Sim Documentation — Build AI Agents & Run Your Agentic Workforce',
     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 platform to build AI agents and run your agentic workforce. Connect 1,000+ integrations and LLMs to deploy and orchestrate agentic workflows.',
     images: [
       {
         url: 'https://docs.sim.ai/api/og?title=Sim%20Documentation',
@@ -67,9 +92,9 @@ export const metadata = {
   },
   twitter: {
     card: 'summary_large_image',
-    title: 'Sim Documentation - Visual Workflow Builder for AI Applications',
+    title: 'Sim Documentation — Build AI Agents & Run Your Agentic Workforce',
     description:
-      'Comprehensive documentation for Sim - the visual workflow builder for AI applications.',
+      'Documentation for Sim — the open-source platform to build AI agents and run your agentic workforce. Connect 1,000+ integrations and LLMs to deploy and orchestrate agentic workflows.',
     creator: '@simdotai',
     site: '@simdotai',
     images: ['https://docs.sim.ai/api/og?title=Sim%20Documentation'],

apps/docs/app/llms.txt/route.ts

@@ -37,9 +37,9 @@ export async function GET() {
 
     const manifest = `# Sim Documentation
 
-> Visual Workflow Builder for AI Applications
+> The open-source platform to build AI agents and run your agentic workforce.
 
-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 platform to build AI agents and run your agentic workforce. Connect 1,000+ integrations and LLMs to deploy and orchestrate agentic workflows. Create agents, workflows, knowledge bases, tables, and docs. Trusted by over 100,000 builders.
 
 ## Documentation Overview
 

apps/docs/components/docs-layout/sidebar-components.tsx

@@ -52,15 +52,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
 
@@ -157,16 +168,18 @@ export function SidebarFolder({ item, children }: { item: Folder; children: Reac
       {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'>
+            {/* 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>
         </div>
       )}
     </div>

apps/docs/components/docs-layout/toc-footer.tsx

@@ -1,38 +1,36 @@
 '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'>Trusted by over 100,000 builders.</div>
         <div className='text-muted-foreground'>
-          Build Agentic workflows visually on a drag-and-drop canvas or with natural language.
+          The open-source platform to build AI agents and run your agentic workforce.
         </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'
+          className='group mt-2 inline-flex h-8 w-fit items-center justify-center gap-2 whitespace-nowrap rounded-[5px] border border-[#33C482] bg-[#33C482] px-[10px] font-medium text-black text-sm outline-none transition-[filter] hover:brightness-110 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 className='relative inline-flex h-4 w-4 transition-transform duration-200 group-hover:translate-x-0.5'>
+            <ChevronRight
+              className='absolute inset-0 h-4 w-4 transition-opacity duration-200 group-hover:opacity-0'
+              aria-hidden='true'
+            />
+            <ArrowRight
+              className='absolute inset-0 h-4 w-4 opacity-0 transition-opacity duration-200 group-hover:opacity-100'
+              aria-hidden='true'
+            />
           </span>
         </Link>
       </div>

apps/docs/components/navbar/navbar.tsx

@@ -1,53 +1,95 @@
 '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,
+  },
+  { label: 'Mothership', href: 'https://sim.ai', external: true },
+] 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)',
           }}
         >
-          {/* 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-7 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 />
           </div>
         </div>
+
+        {/* Divider — only spans content width */}
+        <div
+          className='border-b'
+          style={{
+            marginLeft: 'calc(var(--sidebar-offset) + 32px)',
+            marginRight: 'calc(var(--toc-offset) + 60px)',
+            borderColor: 'rgba(128, 128, 128, 0.1)',
+          }}
+        />
+
+        {/* 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) + 32px)',
+          }}
+        >
+          {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-[550] text-neutral-800 dark:border-neutral-500 dark:text-neutral-200'
+                    : 'border-transparent font-medium text-fd-muted-foreground hover:border-neutral-300 hover:text-neutral-600 dark:hover:border-neutral-600 dark:hover:text-neutral-400'
+                )}
+              >
+                {/* Invisible bold text reserves width to prevent layout shift */}
+                <span className='invisible font-[550]'>{tab.label}</span>
+                <span className='absolute'>{tab.label}</span>
+              </Link>
+            )
+          })}
+        </div>
       </div>
     </nav>
   )

apps/docs/components/structured-data.tsx

@@ -25,8 +25,8 @@ export function StructuredData({
     headline: title,
     description: description,
     url: url,
-    datePublished: dateModified || new Date().toISOString(),
-    dateModified: dateModified || new Date().toISOString(),
+    ...(dateModified && { datePublished: dateModified }),
+    ...(dateModified && { dateModified }),
     author: {
       '@type': 'Organization',
       name: 'Sim Team',
@@ -74,7 +74,7 @@ export function StructuredData({
     name: 'Sim Documentation',
     url: baseUrl,
     description:
-      'Comprehensive documentation for Sim visual workflow builder for AI applications. Create powerful AI agents, automation workflows, and data processing pipelines.',
+      'Documentation for Sim — the open-source platform to build AI agents and run your agentic workforce. Connect 1,000+ integrations and LLMs to deploy and orchestrate agentic workflows.',
     publisher: {
       '@type': 'Organization',
       name: 'Sim',
@@ -91,12 +91,6 @@ export function StructuredData({
     inLanguage: ['en', 'es', 'fr', 'de', 'ja', 'zh'],
   }
 
-  const faqStructuredData = title.toLowerCase().includes('faq') && {
-    '@context': 'https://schema.org',
-    '@type': 'FAQPage',
-    mainEntity: [],
-  }
-
   const softwareStructuredData = {
     '@context': 'https://schema.org',
     '@type': 'SoftwareApplication',
@@ -104,7 +98,7 @@ export function StructuredData({
     applicationCategory: 'DeveloperApplication',
     operatingSystem: 'Any',
     description:
-      '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.',
+      'Sim is the open-source platform to build AI agents and run your agentic workforce. Connect 1,000+ integrations and LLMs to deploy and orchestrate agentic workflows. Create agents, workflows, knowledge bases, tables, and docs.',
     url: baseUrl,
     author: {
       '@type': 'Organization',
@@ -115,12 +109,13 @@ export function StructuredData({
       category: 'Developer Tools',
     },
     featureList: [
-      'Visual workflow builder with drag-and-drop interface',
-      'AI agent creation and automation',
-      '80+ built-in integrations',
-      'Real-time team collaboration',
-      'Multiple deployment options',
-      'Custom integrations via MCP protocol',
+      'AI agent creation',
+      'Agentic workflow orchestration',
+      '1,000+ integrations',
+      'LLM orchestration (OpenAI, Anthropic, Google, xAI, Mistral, Perplexity)',
+      'Knowledge base creation',
+      'Table creation',
+      'Document creation',
     ],
   }
 
@@ -151,15 +146,6 @@ export function StructuredData({
           }}
         />
       )}
-      {faqStructuredData && (
-        <Script
-          id='faq-structured-data'
-          type='application/ld+json'
-          dangerouslySetInnerHTML={{
-            __html: JSON.stringify(faqStructuredData),
-          }}
-        />
-      )}
       {url === baseUrl && (
         <Script
           id='software-structured-data'

apps/docs/components/ui/animated-blocks.tsx

@@ -0,0 +1,195 @@
+import { memo } from 'react'
+
+const RX = '2.59574'
+
+interface BlockRect {
+  opacity: number
+  width: string
+  height: string
+  fill: string
+  x?: string
+  y?: string
+  transform?: string
+}
+
+const RECTS = {
+  topRight: [
+    { opacity: 1, x: '0', y: '0', width: '16.8626', height: '33.7252', fill: '#2ABBF8' },
+    { opacity: 0.6, x: '0', y: '0', width: '85.3433', height: '16.8626', fill: '#2ABBF8' },
+    { opacity: 1, x: '0', y: '0', width: '16.8626', height: '16.8626', fill: '#2ABBF8' },
+    { opacity: 0.6, x: '34.2403', y: '0', width: '34.2403', height: '33.7252', fill: '#2ABBF8' },
+    { opacity: 1, x: '34.2403', y: '0', width: '16.8626', height: '16.8626', fill: '#2ABBF8' },
+    {
+      opacity: 1,
+      x: '51.6188',
+      y: '16.8626',
+      width: '16.8626',
+      height: '16.8626',
+      fill: '#2ABBF8',
+    },
+    { opacity: 1, x: '68.4812', y: '0', width: '54.6502', height: '16.8626', fill: '#00F701' },
+    { opacity: 0.6, x: '106.268', y: '0', width: '34.2403', height: '33.7252', fill: '#00F701' },
+    { opacity: 0.6, x: '106.268', y: '0', width: '51.103', height: '16.8626', fill: '#00F701' },
+    {
+      opacity: 1,
+      x: '123.6484',
+      y: '16.8626',
+      width: '16.8626',
+      height: '16.8626',
+      fill: '#00F701',
+    },
+    { opacity: 0.6, x: '157.371', y: '0', width: '34.2403', height: '16.8626', fill: '#FFCC02' },
+    { opacity: 1, x: '157.371', y: '0', width: '16.8626', height: '16.8626', fill: '#FFCC02' },
+    { opacity: 0.6, x: '208.993', y: '0', width: '68.4805', height: '16.8626', fill: '#FA4EDF' },
+    { opacity: 0.6, x: '209.137', y: '0', width: '16.8626', height: '33.7252', fill: '#FA4EDF' },
+    { opacity: 0.6, x: '243.233', y: '0', width: '34.2403', height: '33.7252', fill: '#FA4EDF' },
+    { opacity: 1, x: '243.233', y: '0', width: '16.8626', height: '16.8626', fill: '#FA4EDF' },
+    { opacity: 0.6, x: '260.096', y: '0', width: '34.04', height: '16.8626', fill: '#FA4EDF' },
+    {
+      opacity: 1,
+      x: '260.611',
+      y: '16.8626',
+      width: '16.8626',
+      height: '16.8626',
+      fill: '#FA4EDF',
+    },
+  ],
+  bottomLeft: [
+    { opacity: 1, x: '0', y: '0', width: '16.8626', height: '33.7252', fill: '#2ABBF8' },
+    { opacity: 0.6, x: '0', y: '0', width: '85.3433', height: '16.8626', fill: '#2ABBF8' },
+    { opacity: 1, x: '0', y: '0', width: '16.8626', height: '16.8626', fill: '#2ABBF8' },
+    { opacity: 0.6, x: '34.2403', y: '0', width: '34.2403', height: '33.7252', fill: '#2ABBF8' },
+    { opacity: 1, x: '34.2403', y: '0', width: '16.8626', height: '16.8626', fill: '#2ABBF8' },
+    {
+      opacity: 1,
+      x: '51.6188',
+      y: '16.8626',
+      width: '16.8626',
+      height: '16.8626',
+      fill: '#2ABBF8',
+    },
+    { opacity: 1, x: '68.4812', y: '0', width: '54.6502', height: '16.8626', fill: '#00F701' },
+    { opacity: 0.6, x: '106.268', y: '0', width: '34.2403', height: '33.7252', fill: '#00F701' },
+    { opacity: 0.6, x: '106.268', y: '0', width: '51.103', height: '16.8626', fill: '#00F701' },
+    {
+      opacity: 1,
+      x: '123.6484',
+      y: '16.8626',
+      width: '16.8626',
+      height: '16.8626',
+      fill: '#00F701',
+    },
+  ],
+  bottomRight: [
+    {
+      opacity: 0.6,
+      width: '16.8626',
+      height: '33.726',
+      fill: '#FA4EDF',
+      transform: 'matrix(0 1 1 0 0 0)',
+    },
+    {
+      opacity: 0.6,
+      width: '34.241',
+      height: '16.8626',
+      fill: '#FA4EDF',
+      transform: 'matrix(0 1 1 0 16.891 0)',
+    },
+    {
+      opacity: 0.6,
+      width: '16.8626',
+      height: '68.482',
+      fill: '#FA4EDF',
+      transform: 'matrix(-1 0 0 1 33.739 16.888)',
+    },
+    {
+      opacity: 0.6,
+      width: '16.8626',
+      height: '33.726',
+      fill: '#FA4EDF',
+      transform: 'matrix(0 1 1 0 0 33.776)',
+    },
+    {
+      opacity: 1,
+      width: '16.8626',
+      height: '16.8626',
+      fill: '#FA4EDF',
+      transform: 'matrix(-1 0 0 1 33.739 34.272)',
+    },
+    {
+      opacity: 0.6,
+      width: '16.8626',
+      height: '34.24',
+      fill: '#2ABBF8',
+      transform: 'matrix(-1 0 0 1 33.787 68)',
+    },
+    {
+      opacity: 0.4,
+      width: '16.8626',
+      height: '16.8626',
+      fill: '#1A8FCC',
+      transform: 'matrix(-1 0 0 1 33.787 85)',
+    },
+  ],
+} as const satisfies Record<string, readonly BlockRect[]>
+
+const GLOBAL_OPACITY = 0.55
+
+const BlockGroup = memo(function BlockGroup({
+  width,
+  height,
+  viewBox,
+  rects,
+}: {
+  width: number
+  height: number
+  viewBox: string
+  rects: readonly BlockRect[]
+}) {
+  return (
+    <svg
+      width={width}
+      height={height}
+      viewBox={viewBox}
+      fill='none'
+      xmlns='http://www.w3.org/2000/svg'
+      className='h-auto w-full'
+      style={{ opacity: GLOBAL_OPACITY }}
+    >
+      {rects.map((r, i) => (
+        <rect
+          key={i}
+          x={r.x}
+          y={r.y}
+          width={r.width}
+          height={r.height}
+          rx={RX}
+          fill={r.fill}
+          transform={r.transform}
+          opacity={r.opacity}
+        />
+      ))}
+    </svg>
+  )
+})
+
+export function AnimatedBlocks() {
+  return (
+    <div
+      className='pointer-events-none fixed inset-0 z-0 hidden overflow-hidden lg:block'
+      aria-hidden='true'
+    >
+      <div className='absolute top-[93px] right-0 w-[calc(140px+10.76vw)] max-w-[295px]'>
+        <BlockGroup width={295} height={34} viewBox='0 0 295 34' rects={RECTS.topRight} />
+      </div>
+
+      <div className='-left-24 absolute bottom-0 w-[calc(140px+10.76vw)] max-w-[295px] rotate-180'>
+        <BlockGroup width={295} height={34} viewBox='0 0 295 34' rects={RECTS.bottomLeft} />
+      </div>
+
+      <div className='-bottom-2 absolute right-0 w-[calc(16px+1.25vw)] max-w-[34px]'>
+        <BlockGroup width={34} height={102} viewBox='0 0 34 102' rects={RECTS.bottomRight} />
+      </div>
+    </div>
+  )
+}

apps/docs/components/ui/dropdown-menu.tsx

@@ -0,0 +1,73 @@
+'use client'
+
+import * as React from 'react'
+import * as DropdownMenuPrimitive from '@radix-ui/react-dropdown-menu'
+import { Check } from 'lucide-react'
+import { cn } from '@/lib/utils'
+
+const DropdownMenu = DropdownMenuPrimitive.Root
+const DropdownMenuTrigger = DropdownMenuPrimitive.Trigger
+
+const DropdownMenuContent = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Content>
+>(({ className, sideOffset = 4, ...props }, ref) => (
+  <DropdownMenuPrimitive.Portal>
+    <DropdownMenuPrimitive.Content
+      ref={ref}
+      sideOffset={sideOffset}
+      className={cn(
+        'data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 max-h-[var(--radix-dropdown-menu-content-available-height)] min-w-[8rem] origin-[--radix-dropdown-menu-content-transform-origin] overflow-y-auto overflow-x-hidden rounded-md border bg-popover p-1 text-popover-foreground shadow-md data-[state=closed]:animate-out data-[state=open]:animate-in',
+        className
+      )}
+      {...props}
+    />
+  </DropdownMenuPrimitive.Portal>
+))
+DropdownMenuContent.displayName = DropdownMenuPrimitive.Content.displayName
+
+const DropdownMenuItem = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.Item>,
+  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Item>
+>(({ className, ...props }, ref) => (
+  <DropdownMenuPrimitive.Item
+    ref={ref}
+    className={cn(
+      'relative flex cursor-default select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none transition-colors focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
+      className
+    )}
+    {...props}
+  />
+))
+DropdownMenuItem.displayName = DropdownMenuPrimitive.Item.displayName
+
+const DropdownMenuCheckboxItem = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.CheckboxItem>,
+  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.CheckboxItem>
+>(({ className, children, checked, ...props }, ref) => (
+  <DropdownMenuPrimitive.CheckboxItem
+    ref={ref}
+    className={cn(
+      'relative flex cursor-default select-none items-center rounded-sm py-1.5 pr-2 pl-8 text-sm outline-none transition-colors focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
+      className
+    )}
+    checked={checked}
+    {...props}
+  >
+    <span className='absolute left-2 flex h-3.5 w-3.5 items-center justify-center'>
+      <DropdownMenuPrimitive.ItemIndicator>
+        <Check className='h-4 w-4' />
+      </DropdownMenuPrimitive.ItemIndicator>
+    </span>
+    {children}
+  </DropdownMenuPrimitive.CheckboxItem>
+))
+DropdownMenuCheckboxItem.displayName = DropdownMenuPrimitive.CheckboxItem.displayName
+
+export {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuCheckboxItem,
+}

apps/docs/components/ui/faq.tsx

@@ -0,0 +1,47 @@
+'use client'
+
+import { useState } from 'react'
+import { ChevronRight } from 'lucide-react'
+
+interface FAQItem {
+  question: string
+  answer: string
+}
+
+interface FAQProps {
+  items: FAQItem[]
+  title?: string
+}
+
+export function FAQ({ items, title = 'Common Questions' }: FAQProps) {
+  const [openIndex, setOpenIndex] = useState<number | null>(null)
+
+  return (
+    <div className='mt-12'>
+      <h2 className='mb-4 font-bold text-xl'>{title}</h2>
+      <div className='rounded-xl border border-border'>
+        {items.map((item, index) => (
+          <div key={index} className={index !== items.length - 1 ? 'border-border border-b' : ''}>
+            <button
+              type='button'
+              onClick={() => setOpenIndex(openIndex === index ? null : index)}
+              className='flex w-full cursor-pointer items-center gap-3 px-5 py-4 text-left font-medium text-[0.9375rem]'
+            >
+              <ChevronRight
+                className={`h-4 w-4 shrink-0 text-fd-muted-foreground transition-transform duration-200 ${
+                  openIndex === index ? 'rotate-90' : ''
+                }`}
+              />
+              {item.question}
+            </button>
+            {openIndex === index && (
+              <div className='px-5 pb-4 pl-12 text-[0.9375rem] text-fd-muted-foreground leading-relaxed'>
+                {item.answer}
+              </div>
+            )}
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}

apps/docs/components/ui/icon-mapping.ts

@@ -5,70 +5,103 @@
 import type { ComponentType, SVGProps } from 'react'
 import {
   A2AIcon,
+  AgentMailIcon,
   AhrefsIcon,
   AirtableIcon,
   AirweaveIcon,
   AlgoliaIcon,
+  AmplitudeIcon,
   ApifyIcon,
   ApolloIcon,
   ArxivIcon,
   AsanaIcon,
+  AshbyIcon,
+  AttioIcon,
+  AzureIcon,
+  BoxCompanyIcon,
   BrainIcon,
+  BrandfetchIcon,
   BrowserUseIcon,
   CalComIcon,
   CalendlyIcon,
   CirclebackIcon,
   ClayIcon,
   ClerkIcon,
+  CloudFormationIcon,
   CloudflareIcon,
+  CloudWatchIcon,
   ConfluenceIcon,
   CursorIcon,
+  DatabricksIcon,
   DatadogIcon,
+  DevinIcon,
   DiscordIcon,
   DocumentIcon,
+  DocuSignIcon,
   DropboxIcon,
   DsPyIcon,
+  DubIcon,
   DuckDuckGoIcon,
   DynamoDBIcon,
   ElasticsearchIcon,
   ElevenLabsIcon,
   EnrichSoIcon,
+  EvernoteIcon,
   ExaAIIcon,
+  ExtendIcon,
   EyeIcon,
+  FathomIcon,
   FirecrawlIcon,
   FirefliesIcon,
+  GammaIcon,
   GithubIcon,
   GitLabIcon,
   GmailIcon,
+  GongIcon,
+  GoogleAdsIcon,
+  GoogleBigQueryIcon,
   GoogleBooksIcon,
   GoogleCalendarIcon,
+  GoogleContactsIcon,
   GoogleDocsIcon,
   GoogleDriveIcon,
   GoogleFormsIcon,
   GoogleGroupsIcon,
   GoogleIcon,
   GoogleMapsIcon,
+  GoogleMeetIcon,
+  GooglePagespeedIcon,
   GoogleSheetsIcon,
   GoogleSlidesIcon,
+  GoogleTasksIcon,
+  GoogleTranslateIcon,
   GoogleVaultIcon,
   GrafanaIcon,
   GrainIcon,
+  GranolaIcon,
+  GreenhouseIcon,
   GreptileIcon,
+  HexIcon,
   HubspotIcon,
   HuggingFaceIcon,
   HunterIOIcon,
   ImageIcon,
   IncidentioIcon,
+  InfisicalIcon,
   IntercomIcon,
   JinaAIIcon,
   JiraIcon,
   JiraServiceManagementIcon,
   KalshiIcon,
+  KetchIcon,
   LangsmithIcon,
+  LaunchDarklyIcon,
   LemlistIcon,
   LinearIcon,
   LinkedInIcon,
   LinkupIcon,
+  LoopsIcon,
+  LumaIcon,
   MailchimpIcon,
   MailgunIcon,
   MailServerIcon,
@@ -84,10 +117,13 @@ import {
   MySQLIcon,
   Neo4jIcon,
   NotionIcon,
+  ObsidianIcon,
+  OktaIcon,
   OnePasswordIcon,
   OpenAIIcon,
   OutlookIcon,
   PackageSearchIcon,
+  PagerDutyIcon,
   ParallelIcon,
   PerplexityIcon,
   PineconeIcon,
@@ -95,17 +131,22 @@ import {
   PolymarketIcon,
   PostgresIcon,
   PosthogIcon,
+  ProfoundIcon,
   PulseIcon,
   QdrantIcon,
+  QuiverIcon,
   RDSIcon,
   RedditIcon,
   RedisIcon,
   ReductoIcon,
   ResendIcon,
   RevenueCatIcon,
+  RipplingIcon,
+  RootlyIcon,
   S3Icon,
   SalesforceIcon,
   SearchIcon,
+  SecretsManagerIcon,
   SendgridIcon,
   SentryIcon,
   SerperIcon,
@@ -121,6 +162,7 @@ import {
   StagehandIcon,
   StripeIcon,
   SupabaseIcon,
+  TailscaleIcon,
   TavilyIcon,
   TelegramIcon,
   TextractIcon,
@@ -138,6 +180,7 @@ import {
   WhatsAppIcon,
   WikipediaIcon,
   WordpressIcon,
+  WorkdayIcon,
   xIcon,
   YouTubeIcon,
   ZendeskIcon,
@@ -149,14 +192,20 @@ type IconComponent = ComponentType<SVGProps<SVGSVGElement>>
 
 export const blockTypeToIconMap: Record<string, IconComponent> = {
   a2a: A2AIcon,
+  agentmail: AgentMailIcon,
   ahrefs: AhrefsIcon,
   airtable: AirtableIcon,
   airweave: AirweaveIcon,
   algolia: AlgoliaIcon,
+  amplitude: AmplitudeIcon,
   apify: ApifyIcon,
   apollo: ApolloIcon,
   arxiv: ArxivIcon,
   asana: AsanaIcon,
+  ashby: AshbyIcon,
+  attio: AttioIcon,
+  box: BoxCompanyIcon,
+  brandfetch: BrandfetchIcon,
   browser_use: BrowserUseIcon,
   calcom: CalComIcon,
   calendly: CalendlyIcon,
@@ -164,59 +213,86 @@ export const blockTypeToIconMap: Record<string, IconComponent> = {
   clay: ClayIcon,
   clerk: ClerkIcon,
   cloudflare: CloudflareIcon,
+  cloudformation: CloudFormationIcon,
+  cloudwatch: CloudWatchIcon,
   confluence_v2: ConfluenceIcon,
   cursor_v2: CursorIcon,
+  databricks: DatabricksIcon,
   datadog: DatadogIcon,
+  devin: DevinIcon,
   discord: DiscordIcon,
+  docusign: DocuSignIcon,
   dropbox: DropboxIcon,
   dspy: DsPyIcon,
+  dub: DubIcon,
   duckduckgo: DuckDuckGoIcon,
   dynamodb: DynamoDBIcon,
   elasticsearch: ElasticsearchIcon,
   elevenlabs: ElevenLabsIcon,
   enrich: EnrichSoIcon,
+  evernote: EvernoteIcon,
   exa: ExaAIIcon,
+  extend_v2: ExtendIcon,
+  fathom: FathomIcon,
   file_v3: DocumentIcon,
   firecrawl: FirecrawlIcon,
   fireflies_v2: FirefliesIcon,
+  gamma: GammaIcon,
   github_v2: GithubIcon,
   gitlab: GitLabIcon,
   gmail_v2: GmailIcon,
+  gong: GongIcon,
+  google_ads: GoogleAdsIcon,
+  google_bigquery: GoogleBigQueryIcon,
   google_books: GoogleBooksIcon,
   google_calendar_v2: GoogleCalendarIcon,
+  google_contacts: GoogleContactsIcon,
   google_docs: GoogleDocsIcon,
   google_drive: GoogleDriveIcon,
   google_forms: GoogleFormsIcon,
   google_groups: GoogleGroupsIcon,
   google_maps: GoogleMapsIcon,
+  google_meet: GoogleMeetIcon,
+  google_pagespeed: GooglePagespeedIcon,
   google_search: GoogleIcon,
   google_sheets_v2: GoogleSheetsIcon,
   google_slides_v2: GoogleSlidesIcon,
+  google_tasks: GoogleTasksIcon,
+  google_translate: GoogleTranslateIcon,
   google_vault: GoogleVaultIcon,
   grafana: GrafanaIcon,
   grain: GrainIcon,
+  granola: GranolaIcon,
+  greenhouse: GreenhouseIcon,
   greptile: GreptileIcon,
+  hex: HexIcon,
   hubspot: HubspotIcon,
   huggingface: HuggingFaceIcon,
   hunter: HunterIOIcon,
   image_generator: ImageIcon,
   imap: MailServerIcon,
   incidentio: IncidentioIcon,
+  infisical: InfisicalIcon,
   intercom_v2: IntercomIcon,
   jina: JinaAIIcon,
   jira: JiraIcon,
   jira_service_management: JiraServiceManagementIcon,
   kalshi_v2: KalshiIcon,
+  ketch: KetchIcon,
   knowledge: PackageSearchIcon,
   langsmith: LangsmithIcon,
+  launchdarkly: LaunchDarklyIcon,
   lemlist: LemlistIcon,
   linear: LinearIcon,
   linkedin: LinkedInIcon,
   linkup: LinkupIcon,
+  loops: LoopsIcon,
+  luma: LumaIcon,
   mailchimp: MailchimpIcon,
   mailgun: MailgunIcon,
   mem0: Mem0Icon,
   memory: BrainIcon,
+  microsoft_ad: AzureIcon,
   microsoft_dataverse: MicrosoftDataverseIcon,
   microsoft_excel_v2: MicrosoftExcelIcon,
   microsoft_planner: MicrosoftPlannerIcon,
@@ -226,10 +302,13 @@ export const blockTypeToIconMap: Record<string, IconComponent> = {
   mysql: MySQLIcon,
   neo4j: Neo4jIcon,
   notion_v2: NotionIcon,
+  obsidian: ObsidianIcon,
+  okta: OktaIcon,
   onedrive: MicrosoftOneDriveIcon,
   onepassword: OnePasswordIcon,
   openai: OpenAIIcon,
   outlook: OutlookIcon,
+  pagerduty: PagerDutyIcon,
   parallel_ai: ParallelIcon,
   perplexity: PerplexityIcon,
   pinecone: PineconeIcon,
@@ -237,17 +316,22 @@ export const blockTypeToIconMap: Record<string, IconComponent> = {
   polymarket: PolymarketIcon,
   postgresql: PostgresIcon,
   posthog: PosthogIcon,
+  profound: ProfoundIcon,
   pulse_v2: PulseIcon,
   qdrant: QdrantIcon,
+  quiver: QuiverIcon,
   rds: RDSIcon,
   reddit: RedditIcon,
   redis: RedisIcon,
   reducto_v2: ReductoIcon,
   resend: ResendIcon,
   revenuecat: RevenueCatIcon,
+  rippling: RipplingIcon,
+  rootly: RootlyIcon,
   s3: S3Icon,
   salesforce: SalesforceIcon,
   search: SearchIcon,
+  secrets_manager: SecretsManagerIcon,
   sendgrid: SendgridIcon,
   sentry: SentryIcon,
   serper: SerperIcon,
@@ -264,6 +348,7 @@ export const blockTypeToIconMap: Record<string, IconComponent> = {
   stripe: StripeIcon,
   stt_v2: STTIcon,
   supabase: SupabaseIcon,
+  tailscale: TailscaleIcon,
   tavily: TavilyIcon,
   telegram: TelegramIcon,
   textract_v2: TextractIcon,
@@ -283,6 +368,7 @@ export const blockTypeToIconMap: Record<string, IconComponent> = {
   whatsapp: WhatsAppIcon,
   wikipedia: WikipediaIcon,
   wordpress: WordpressIcon,
+  workday: WorkdayIcon,
   x: xIcon,
   youtube: YouTubeIcon,
   zendesk: ZendeskIcon,

apps/docs/components/ui/image.tsx

@@ -30,7 +30,7 @@ export function Image({
       <NextImage
         className={cn(
           'overflow-hidden rounded-xl border border-border object-cover shadow-sm',
-          enableLightbox && 'cursor-pointer transition-opacity hover:opacity-90',
+          enableLightbox && 'cursor-pointer transition-opacity hover:opacity-95',
           className
         )}
         alt={alt}

apps/docs/components/ui/lightbox.tsx

@@ -55,8 +55,9 @@ export function Lightbox({ isOpen, onClose, src, alt, type }: LightboxProps) {
           <img
             src={src}
             alt={alt}
-            className='max-h-[calc(100vh-6rem)] max-w-[calc(100vw-6rem)] rounded-xl object-contain'
+            className='max-h-[75vh] max-w-[75vw] cursor-pointer rounded-xl object-contain'
             loading='lazy'
+            onClick={onClose}
           />
         ) : (
           <video
@@ -65,7 +66,8 @@ export function Lightbox({ isOpen, onClose, src, alt, type }: LightboxProps) {
             loop
             muted
             playsInline
-            className='max-h-[calc(100vh-6rem)] max-w-[calc(100vw-6rem)] rounded-xl outline-none focus:outline-none'
+            className='max-h-[75vh] max-w-[75vw] cursor-pointer rounded-xl outline-none focus:outline-none'
+            onClick={onClose}
           />
         )}
       </div>

apps/docs/components/ui/response-section.tsx

@@ -0,0 +1,169 @@
+'use client'
+
+import { useEffect, useRef, useState } from 'react'
+import { ChevronDown } from 'lucide-react'
+import { cn } from '@/lib/utils'
+
+interface ResponseSectionProps {
+  children: React.ReactNode
+}
+
+export function ResponseSection({ children }: ResponseSectionProps) {
+  const containerRef = useRef<HTMLDivElement>(null)
+  const [statusCodes, setStatusCodes] = useState<string[]>([])
+  const [selectedCode, setSelectedCode] = useState<string>('')
+  const [isOpen, setIsOpen] = useState(false)
+  const dropdownRef = useRef<HTMLDivElement>(null)
+
+  function getAccordionItems() {
+    const root = containerRef.current?.querySelector('[data-orientation="vertical"]')
+    if (!root) return []
+    return Array.from(root.children).filter(
+      (el) => el.getAttribute('data-state') !== null
+    ) as HTMLElement[]
+  }
+
+  function showStatusCode(code: string) {
+    const items = getAccordionItems()
+    for (const item of items) {
+      const triggerBtn = item.querySelector('h3 button') as HTMLButtonElement | null
+      const text = triggerBtn?.textContent?.trim() ?? ''
+      const itemCode = text.match(/^\d{3}/)?.[0]
+
+      if (itemCode === code) {
+        item.style.display = ''
+        if (item.getAttribute('data-state') === 'closed' && triggerBtn) {
+          triggerBtn.click()
+        }
+      } else {
+        item.style.display = 'none'
+        if (item.getAttribute('data-state') === 'open' && triggerBtn) {
+          triggerBtn.click()
+        }
+      }
+    }
+  }
+
+  /**
+   * Detect when the fumadocs accordion children mount via MutationObserver,
+   * then extract status codes and show the first one.
+   * Replaces the previous approach that used `children` as a dependency
+   * (which triggered on every render since children is a new object each time).
+   */
+  useEffect(() => {
+    const container = containerRef.current
+    if (!container) return
+
+    const initialize = () => {
+      const items = getAccordionItems()
+      if (items.length === 0) return false
+
+      const codes: string[] = []
+      const seen = new Set<string>()
+
+      for (const item of items) {
+        const triggerBtn = item.querySelector('h3 button')
+        if (triggerBtn) {
+          const text = triggerBtn.textContent?.trim() ?? ''
+          const code = text.match(/^\d{3}/)?.[0]
+          if (code && !seen.has(code)) {
+            seen.add(code)
+            codes.push(code)
+          }
+        }
+      }
+
+      if (codes.length > 0) {
+        setStatusCodes(codes)
+        setSelectedCode(codes[0])
+        showStatusCode(codes[0])
+        return true
+      }
+      return false
+    }
+
+    if (initialize()) return
+
+    const observer = new MutationObserver(() => {
+      if (initialize()) {
+        observer.disconnect()
+      }
+    })
+    observer.observe(container, { childList: true, subtree: true })
+
+    return () => observer.disconnect()
+  }, []) // eslint-disable-line react-hooks/exhaustive-deps
+
+  function handleSelectCode(code: string) {
+    setSelectedCode(code)
+    setIsOpen(false)
+    showStatusCode(code)
+  }
+
+  useEffect(() => {
+    function handleClickOutside(event: MouseEvent) {
+      if (dropdownRef.current && !dropdownRef.current.contains(event.target as Node)) {
+        setIsOpen(false)
+      }
+    }
+    document.addEventListener('mousedown', handleClickOutside)
+    return () => document.removeEventListener('mousedown', handleClickOutside)
+  }, [])
+
+  return (
+    <div ref={containerRef} className='response-section-wrapper'>
+      {statusCodes.length > 0 && (
+        <div className='response-section-header'>
+          <h2 className='response-section-title'>Response</h2>
+          <div className='response-section-meta'>
+            <div ref={dropdownRef} className='response-section-dropdown-wrapper'>
+              <button
+                type='button'
+                className='response-section-dropdown-trigger'
+                onClick={() => setIsOpen(!isOpen)}
+              >
+                <span>{selectedCode}</span>
+                <ChevronDown
+                  className={cn(
+                    'response-section-chevron',
+                    isOpen && 'response-section-chevron-open'
+                  )}
+                />
+              </button>
+              {isOpen && (
+                <div className='response-section-dropdown-menu'>
+                  {statusCodes.map((code) => (
+                    <button
+                      key={code}
+                      type='button'
+                      className={cn(
+                        'response-section-dropdown-item',
+                        code === selectedCode && 'response-section-dropdown-item-selected'
+                      )}
+                      onClick={() => handleSelectCode(code)}
+                    >
+                      <span>{code}</span>
+                      {code === selectedCode && (
+                        <svg
+                          className='response-section-check'
+                          viewBox='0 0 24 24'
+                          fill='none'
+                          stroke='currentColor'
+                          strokeWidth='2'
+                        >
+                          <polyline points='20 6 9 17 4 12' />
+                        </svg>
+                      )}
+                    </button>
+                  ))}
+                </div>
+              )}
+            </div>
+            <span className='response-section-content-type'>application/json</span>
+          </div>
+        </div>
+      )}
+      <div className='response-section-content'>{children}</div>
+    </div>
+  )
+}

apps/docs/components/ui/search-trigger.tsx

@@ -15,23 +15,14 @@ export function SearchTrigger() {
   return (
     <button
       type='button'
-      className='flex h-10 w-[460px] cursor-pointer items-center gap-2 rounded-xl border border-border/50 px-3 py-2 text-sm backdrop-blur-xl transition-colors hover:border-border'
-      style={{
-        backgroundColor: 'hsla(0, 0%, 5%, 0.85)',
-        backdropFilter: 'blur(33px) saturate(180%)',
-        WebkitBackdropFilter: 'blur(33px) saturate(180%)',
-        color: 'rgba(255, 255, 255, 0.6)',
-      }}
+      className='flex h-9 w-[360px] cursor-pointer items-center gap-2 rounded-lg border border-border/50 bg-fd-muted/50 px-3 text-[13px] text-fd-muted-foreground transition-colors hover:border-border hover:text-fd-foreground'
       onClick={handleClick}
     >
-      <Search className='h-4 w-4' />
+      <Search className='h-3.5 w-3.5' />
       <span>Search...</span>
-      <kbd
-        className='ml-auto flex items-center gap-0.5 font-medium'
-        style={{ color: 'rgba(255, 255, 255, 0.6)' }}
-      >
-        <span style={{ fontSize: '15px', lineHeight: '1' }}>⌘</span>
-        <span style={{ fontSize: '13px', lineHeight: '1' }}>K</span>
+      <kbd className='ml-auto flex items-center font-medium'>
+        <span className='text-[15px]'>⌘</span>
+        <span className='text-[12px]'>K</span>
       </kbd>
     </button>
   )

apps/docs/components/ui/video.tsx

@@ -38,7 +38,7 @@ export function Video({
         loop={loop}
         muted={muted}
         playsInline={playsInline}
-        className={`${className} ${enableLightbox ? 'cursor-pointer transition-opacity hover:opacity-90' : ''}`}
+        className={`${className} ${enableLightbox ? 'cursor-pointer transition-opacity hover:opacity-95' : ''}`}
         src={getAssetUrl(src)}
         onClick={handleVideoClick}
       />

apps/docs/content/docs/de/api-reference/authentication.mdx

@@ -0,0 +1,94 @@
+---
+title: Authentication
+description: API key types, generation, and how to authenticate requests
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+
+To access the Sim API, you need an API key. Sim supports two types of API keys — **personal keys** and **workspace keys** — each with different billing and access behaviors.
+
+## Key Types
+
+|  | **Personal Keys** | **Workspace Keys** |
+| --- | --- | --- |
+| **Billed to** | Your individual account | Workspace owner |
+| **Scope** | Across workspaces you have access to | Shared across the workspace |
+| **Managed by** | Each user individually | Workspace admins |
+| **Permissions** | Must be enabled at workspace level | Require admin permissions |
+
+<Callout type="info">
+  Workspace admins can disable personal API key usage for their workspace. If disabled, only workspace keys can be used.
+</Callout>
+
+## Generating API Keys
+
+To generate a key, open the Sim dashboard and navigate to **Settings**, then go to **Sim Keys** and click **Create**.
+
+<Callout type="warn">
+  API keys are only shown once when generated. Store your key securely — you will not be able to view it again.
+</Callout>
+
+## Using API Keys
+
+Pass your API key in the `X-API-Key` header with every request:
+
+<Tabs items={['curl', 'TypeScript', 'Python']}>
+  <Tab value="curl">
+    ```bash
+    curl -X POST https://www.sim.ai/api/workflows/{workflowId}/execute \
+      -H "Content-Type: application/json" \
+      -H "X-API-Key: YOUR_API_KEY" \
+      -d '{"inputs": {}}'
+    ```
+  </Tab>
+  <Tab value="TypeScript">
+    ```typescript
+    const response = await fetch(
+      'https://www.sim.ai/api/workflows/{workflowId}/execute',
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-API-Key': process.env.SIM_API_KEY!,
+        },
+        body: JSON.stringify({ inputs: {} }),
+      }
+    )
+    ```
+  </Tab>
+  <Tab value="Python">
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://www.sim.ai/api/workflows/{workflowId}/execute",
+        headers={
+            "Content-Type": "application/json",
+            "X-API-Key": os.environ["SIM_API_KEY"],
+        },
+        json={"inputs": {}},
+    )
+    ```
+  </Tab>
+</Tabs>
+
+## Where Keys Are Used
+
+API keys authenticate access to:
+
+- **Workflow execution** — run deployed workflows via the API
+- **Logs API** — query workflow execution logs and metrics
+- **MCP servers** — authenticate connections to deployed MCP servers
+- **SDKs** — the [Python](/api-reference/python) and [TypeScript](/api-reference/typescript) SDKs use API keys for all operations
+
+## Security
+
+- Keys use the `sk-sim-` prefix and are encrypted at rest
+- Keys can be revoked at any time from the dashboard
+- Use environment variables to store keys — never hardcode them in source code
+- For browser-based applications, use a backend proxy to avoid exposing keys to the client
+
+<Callout type="warn">
+  Never expose your API key in client-side code. Use a server-side proxy to make authenticated requests on behalf of your frontend.
+</Callout>

apps/docs/content/docs/de/api-reference/getting-started.mdx

@@ -0,0 +1,210 @@
+---
+title: Getting Started
+description: Base URL, first API call, response format, error handling, and pagination
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+import { Step, Steps } from 'fumadocs-ui/components/steps'
+
+## Base URL
+
+All API requests are made to:
+
+```
+https://www.sim.ai
+```
+
+## Quick Start
+
+<Steps>
+
+<Step>
+### Get your API key
+
+Go to the Sim dashboard and navigate to **Settings → Sim Keys**, then click **Create**. See [Authentication](/api-reference/authentication) for details on key types.
+</Step>
+
+<Step>
+### Find your workflow ID
+
+Open a workflow in the Sim editor. The workflow ID is in the URL:
+
+```
+https://www.sim.ai/workspace/{workspaceId}/w/{workflowId}
+```
+
+You can also use the [List Workflows](/api-reference/workflows/listWorkflows) endpoint to get all workflow IDs in a workspace.
+</Step>
+
+<Step>
+### Deploy your workflow
+
+A workflow must be deployed before it can be executed via the API. Click the **Deploy** button in the editor toolbar.
+</Step>
+
+<Step>
+### Make your first request
+
+<Tabs items={['curl', 'TypeScript', 'Python']}>
+  <Tab value="curl">
+    ```bash
+    curl -X POST https://www.sim.ai/api/workflows/{workflowId}/execute \
+      -H "Content-Type: application/json" \
+      -H "X-API-Key: YOUR_API_KEY" \
+      -d '{"inputs": {}}'
+    ```
+  </Tab>
+  <Tab value="TypeScript">
+    ```typescript
+    const response = await fetch(
+      `https://www.sim.ai/api/workflows/${workflowId}/execute`,
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-API-Key': process.env.SIM_API_KEY!,
+        },
+        body: JSON.stringify({ inputs: {} }),
+      }
+    )
+
+    const data = await response.json()
+    console.log(data.output)
+    ```
+  </Tab>
+  <Tab value="Python">
+    ```python
+    import requests
+    import os
+
+    response = requests.post(
+        f"https://www.sim.ai/api/workflows/{workflow_id}/execute",
+        headers={
+            "Content-Type": "application/json",
+            "X-API-Key": os.environ["SIM_API_KEY"],
+        },
+        json={"inputs": {}},
+    )
+
+    data = response.json()
+    print(data["output"])
+    ```
+  </Tab>
+</Tabs>
+</Step>
+
+</Steps>
+
+## Sync vs Async Execution
+
+By default, workflow executions are **synchronous** — the API blocks until the workflow completes and returns the result directly.
+
+For long-running workflows, use **asynchronous execution** by passing `async: true`:
+
+```bash
+curl -X POST https://www.sim.ai/api/workflows/{workflowId}/execute \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: YOUR_API_KEY" \
+  -d '{"inputs": {}, "async": true}'
+```
+
+This returns immediately with a `taskId`:
+
+```json
+{
+  "success": true,
+  "taskId": "job_abc123",
+  "status": "queued"
+}
+```
+
+Poll the [Get Job Status](/api-reference/workflows/getJobStatus) endpoint until the status is `completed` or `failed`:
+
+```bash
+curl https://www.sim.ai/api/jobs/{taskId} \
+  -H "X-API-Key: YOUR_API_KEY"
+```
+
+<Callout type="info">
+  Job status transitions follow: `queued` → `processing` → `completed` or `failed`. The `output` field is only present when status is `completed`.
+</Callout>
+
+## Response Format
+
+Successful responses include an `output` object with your workflow results and a `limits` object with your current rate limit and usage status:
+
+```json
+{
+  "success": true,
+  "output": {
+    "result": "Hello, world!"
+  },
+  "limits": {
+    "workflowExecutionRateLimit": {
+      "sync": {
+        "requestsPerMinute": 60,
+        "maxBurst": 10,
+        "remaining": 59,
+        "resetAt": "2025-01-01T00:01:00Z"
+      },
+      "async": {
+        "requestsPerMinute": 30,
+        "maxBurst": 5,
+        "remaining": 30,
+        "resetAt": "2025-01-01T00:01:00Z"
+      }
+    },
+    "usage": {
+      "currentPeriodCost": 1.25,
+      "limit": 50.00,
+      "plan": "pro",
+      "isExceeded": false
+    }
+  }
+}
+```
+
+## Error Handling
+
+The API uses standard HTTP status codes. Error responses include a human-readable `error` message:
+
+```json
+{
+  "error": "Workflow not found"
+}
+```
+
+| Status | Meaning | What to do |
+| --- | --- | --- |
+| `400` | Invalid request parameters | Check the `details` array for specific field errors |
+| `401` | Missing or invalid API key | Verify your `X-API-Key` header |
+| `403` | Access denied | Check you have permission for this resource |
+| `404` | Resource not found | Verify the ID exists and belongs to your workspace |
+| `429` | Rate limit exceeded | Wait for the duration in the `Retry-After` header |
+
+<Callout type="info">
+  Use the [Get Usage Limits](/api-reference/usage/getUsageLimits) endpoint to check your current rate limit status and billing usage at any time.
+</Callout>
+
+## Rate Limits
+
+Rate limits depend on your subscription plan and apply separately to synchronous and asynchronous executions. Every execution response includes a `limits` object showing your current rate limit status.
+
+When rate limited, the API returns a `429` response with a `Retry-After` header indicating how many seconds to wait before retrying.
+
+## Pagination
+
+List endpoints (workflows, logs, audit logs) use **cursor-based pagination**:
+
+```bash
+# First page
+curl "https://www.sim.ai/api/v1/logs?limit=20" \
+  -H "X-API-Key: YOUR_API_KEY"
+
+# Next page — use the nextCursor from the previous response
+curl "https://www.sim.ai/api/v1/logs?limit=20&cursor=abc123" \
+  -H "X-API-Key: YOUR_API_KEY"
+```
+
+The response includes a `nextCursor` field. When `nextCursor` is absent or `null`, you have reached the last page.

apps/docs/content/docs/de/api-reference/meta.json

@@ -0,0 +1,18 @@
+{
+  "title": "API Reference",
+  "root": true,
+  "pages": [
+    "getting-started",
+    "authentication",
+    "---SDKs---",
+    "python",
+    "typescript",
+    "---Endpoints---",
+    "(generated)/workflows",
+    "(generated)/logs",
+    "(generated)/usage",
+    "(generated)/audit-logs",
+    "(generated)/tables",
+    "(generated)/files"
+  ]
+}

apps/docs/content/docs/de/api-reference/python.mdx

@@ -0,0 +1,766 @@
+---
+title: Python
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Card, Cards } from 'fumadocs-ui/components/card'
+import { Step, Steps } from 'fumadocs-ui/components/steps'
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+
+Das offizielle Python SDK für Sim ermöglicht es Ihnen, Workflows programmatisch aus Ihren Python-Anwendungen heraus mit dem offiziellen Python SDK auszuführen.
+
+<Callout type="info">
+  Das Python SDK unterstützt Python 3.8+ mit Unterstützung für asynchrone Ausführung, automatischer Ratenbegrenzung mit exponentiellem Backoff und Nutzungsverfolgung.
+</Callout>
+
+## Installation
+
+Installieren Sie das SDK mit pip:
+
+```bash
+pip install simstudio-sdk
+```
+
+## Schnellstart
+
+Hier ist ein einfaches Beispiel für den Einstieg:
+
+```python
+from simstudio import SimStudioClient
+
+# Initialize the client
+client = SimStudioClient(
+    api_key="your-api-key-here",
+    base_url="https://sim.ai"  # optional, defaults to https://sim.ai
+)
+
+# Execute a workflow
+try:
+    result = client.execute_workflow("workflow-id")
+    print("Workflow executed successfully:", result)
+except Exception as error:
+    print("Workflow execution failed:", error)
+```
+
+## API-Referenz
+
+### SimStudioClient
+
+#### Konstruktor
+
+```python
+SimStudioClient(api_key: str, base_url: str = "https://sim.ai")
+```
+
+**Parameter:**
+- `api_key` (str): Ihr Sim API-Schlüssel
+- `base_url` (str, optional): Basis-URL für die Sim API
+
+#### Methoden
+
+##### execute_workflow()
+
+Führt einen Workflow mit optionalen Eingabedaten aus.
+
+```python
+result = client.execute_workflow(
+    "workflow-id",
+    input_data={"message": "Hello, world!"},
+    timeout=30.0  # 30 seconds
+)
+```
+
+**Parameter:**
+- `workflow_id` (str): Die ID des auszuführenden Workflows
+- `input_data` (dict, optional): Eingabedaten, die an den Workflow übergeben werden
+- `timeout` (float, optional): Timeout in Sekunden (Standard: 30.0)
+- `stream` (bool, optional): Streaming-Antworten aktivieren (Standard: False)
+- `selected_outputs` (list[str], optional): Block-Ausgaben zum Streamen im Format `blockName.attribute` (z. B. `["agent1.content"]`)
+- `async_execution` (bool, optional): Asynchron ausführen (Standard: False)
+
+**Rückgabewert:** `WorkflowExecutionResult | AsyncExecutionResult`
+
+Wenn `async_execution=True`, wird sofort mit einer Task-ID zum Polling zurückgegeben. Andernfalls wird auf die Fertigstellung gewartet.
+
+##### get_workflow_status()
+
+Ruft den Status eines Workflows ab (Deployment-Status usw.).
+
+```python
+status = client.get_workflow_status("workflow-id")
+print("Is deployed:", status.is_deployed)
+```
+
+**Parameter:**
+- `workflow_id` (str): Die ID des Workflows
+
+**Rückgabe:** `WorkflowStatus`
+
+##### validate_workflow()
+
+Überprüft, ob ein Workflow zur Ausführung bereit ist.
+
+```python
+is_ready = client.validate_workflow("workflow-id")
+if is_ready:
+    # Workflow is deployed and ready
+    pass
+```
+
+**Parameter:**
+- `workflow_id` (str): Die ID des Workflows
+
+**Rückgabe:** `bool`
+
+##### get_job_status()
+
+Ruft den Status einer asynchronen Job-Ausführung ab.
+
+```python
+status = client.get_job_status("task-id-from-async-execution")
+print("Status:", status["status"])  # 'queued', 'processing', 'completed', 'failed'
+if status["status"] == "completed":
+    print("Output:", status["output"])
+```
+
+**Parameter:**
+- `task_id` (str): Die Task-ID, die von der asynchronen Ausführung zurückgegeben wurde
+
+**Rückgabe:** `Dict[str, Any]`
+
+**Antwortfelder:**
+- `success` (bool): Ob die Anfrage erfolgreich war
+- `taskId` (str): Die Task-ID
+- `status` (str): Einer von `'queued'`, `'processing'`, `'completed'`, `'failed'`, `'cancelled'`
+- `metadata` (dict): Enthält `startedAt`, `completedAt` und `duration`
+- `output` (any, optional): Die Workflow-Ausgabe (wenn abgeschlossen)
+- `error` (any, optional): Fehlerdetails (wenn fehlgeschlagen)
+- `estimatedDuration` (int, optional): Geschätzte Dauer in Millisekunden (wenn in Bearbeitung/in Warteschlange)
+
+##### execute_with_retry()
+
+Führt einen Workflow mit automatischer Wiederholung bei Rate-Limit-Fehlern unter Verwendung von exponentiellem Backoff aus.
+
+```python
+result = client.execute_with_retry(
+    "workflow-id",
+    input_data={"message": "Hello"},
+    timeout=30.0,
+    max_retries=3,           # Maximum number of retries
+    initial_delay=1.0,       # Initial delay in seconds
+    max_delay=30.0,          # Maximum delay in seconds
+    backoff_multiplier=2.0   # Exponential backoff multiplier
+)
+```
+
+**Parameter:**
+- `workflow_id` (str): Die ID des auszuführenden Workflows
+- `input_data` (dict, optional): Eingabedaten, die an den Workflow übergeben werden
+- `timeout` (float, optional): Timeout in Sekunden
+- `stream` (bool, optional): Streaming-Antworten aktivieren
+- `selected_outputs` (list, optional): Block-Ausgaben zum Streamen
+- `async_execution` (bool, optional): Asynchron ausführen
+- `max_retries` (int, optional): Maximale Anzahl von Wiederholungen (Standard: 3)
+- `initial_delay` (float, optional): Anfangsverzögerung in Sekunden (Standard: 1.0)
+- `max_delay` (float, optional): Maximale Verzögerung in Sekunden (Standard: 30.0)
+- `backoff_multiplier` (float, optional): Backoff-Multiplikator (Standard: 2.0)
+
+**Rückgabe:** `WorkflowExecutionResult | AsyncExecutionResult`
+
+Die Wiederholungslogik verwendet exponentielles Backoff (1s → 2s → 4s → 8s...) mit ±25% Jitter, um Thundering Herd zu verhindern. Wenn die API einen `retry-after`-Header bereitstellt, wird dieser stattdessen verwendet.
+
+##### get_rate_limit_info()
+
+Ruft die aktuellen Rate-Limit-Informationen aus der letzten API-Antwort ab.
+
+```python
+rate_limit_info = client.get_rate_limit_info()
+if rate_limit_info:
+    print("Limit:", rate_limit_info.limit)
+    print("Remaining:", rate_limit_info.remaining)
+    print("Reset:", datetime.fromtimestamp(rate_limit_info.reset))
+```
+
+**Rückgabewert:** `RateLimitInfo | None`
+
+##### get_usage_limits()
+
+Ruft aktuelle Nutzungslimits und Kontingentinformationen für Ihr Konto ab.
+
+```python
+limits = client.get_usage_limits()
+print("Sync requests remaining:", limits.rate_limit["sync"]["remaining"])
+print("Async requests remaining:", limits.rate_limit["async"]["remaining"])
+print("Current period cost:", limits.usage["currentPeriodCost"])
+print("Plan:", limits.usage["plan"])
+```
+
+**Rückgabewert:** `UsageLimits`
+
+**Antwortstruktur:**
+
+```python
+{
+    "success": bool,
+    "rateLimit": {
+        "sync": {
+            "isLimited": bool,
+            "limit": int,
+            "remaining": int,
+            "resetAt": str
+        },
+        "async": {
+            "isLimited": bool,
+            "limit": int,
+            "remaining": int,
+            "resetAt": str
+        },
+        "authType": str  # 'api' or 'manual'
+    },
+    "usage": {
+        "currentPeriodCost": float,
+        "limit": float,
+        "plan": str  # e.g., 'free', 'pro'
+    }
+}
+```
+
+##### set_api_key()
+
+Aktualisiert den API-Schlüssel.
+
+```python
+client.set_api_key("new-api-key")
+```
+
+##### set_base_url()
+
+Aktualisiert die Basis-URL.
+
+```python
+client.set_base_url("https://my-custom-domain.com")
+```
+
+##### close()
+
+Schließt die zugrunde liegende HTTP-Sitzung.
+
+```python
+client.close()
+```
+
+## Datenklassen
+
+### WorkflowExecutionResult
+
+```python
+@dataclass
+class WorkflowExecutionResult:
+    success: bool
+    output: Optional[Any] = None
+    error: Optional[str] = None
+    logs: Optional[List[Any]] = None
+    metadata: Optional[Dict[str, Any]] = None
+    trace_spans: Optional[List[Any]] = None
+    total_duration: Optional[float] = None
+```
+
+### AsyncExecutionResult
+
+```python
+@dataclass
+class AsyncExecutionResult:
+    success: bool
+    task_id: str
+    status: str  # 'queued'
+    created_at: str
+    links: Dict[str, str]  # e.g., {"status": "/api/jobs/{taskId}"}
+```
+
+### WorkflowStatus
+
+```python
+@dataclass
+class WorkflowStatus:
+    is_deployed: bool
+    deployed_at: Optional[str] = None
+    needs_redeployment: bool = False
+```
+
+### RateLimitInfo
+
+```python
+@dataclass
+class RateLimitInfo:
+    limit: int
+    remaining: int
+    reset: int
+    retry_after: Optional[int] = None
+```
+
+### UsageLimits
+
+```python
+@dataclass
+class UsageLimits:
+    success: bool
+    rate_limit: Dict[str, Any]
+    usage: Dict[str, Any]
+```
+
+### SimStudioError
+
+```python
+class SimStudioError(Exception):
+    def __init__(self, message: str, code: Optional[str] = None, status: Optional[int] = None):
+        super().__init__(message)
+        self.code = code
+        self.status = status
+```
+
+**Häufige Fehlercodes:**
+- `UNAUTHORIZED`: Ungültiger API-Schlüssel
+- `TIMEOUT`: Zeitüberschreitung der Anfrage
+- `RATE_LIMIT_EXCEEDED`: Ratenlimit überschritten
+- `USAGE_LIMIT_EXCEEDED`: Nutzungslimit überschritten
+- `EXECUTION_ERROR`: Workflow-Ausführung fehlgeschlagen
+
+## Beispiele
+
+### Grundlegende Workflow-Ausführung
+
+<Steps>
+  <Step title="Client initialisieren">
+    Richten Sie den SimStudioClient mit Ihrem API-Schlüssel ein.
+  </Step>
+  <Step title="Workflow validieren">
+    Prüfen Sie, ob der Workflow bereitgestellt und zur Ausführung bereit ist.
+  </Step>
+  <Step title="Workflow ausführen">
+    Führen Sie den Workflow mit Ihren Eingabedaten aus.
+  </Step>
+  <Step title="Ergebnis verarbeiten">
+    Verarbeiten Sie das Ausführungsergebnis und behandeln Sie eventuelle Fehler.
+  </Step>
+</Steps>
+
+```python
+import os
+from simstudio import SimStudioClient
+
+client = SimStudioClient(api_key=os.getenv("SIM_API_KEY"))
+
+def run_workflow():
+    try:
+        # Check if workflow is ready
+        is_ready = client.validate_workflow("my-workflow-id")
+        if not is_ready:
+            raise Exception("Workflow is not deployed or ready")
+
+        # Execute the workflow
+        result = client.execute_workflow(
+            "my-workflow-id",
+            input_data={
+                "message": "Process this data",
+                "user_id": "12345"
+            }
+        )
+
+        if result.success:
+            print("Output:", result.output)
+            print("Duration:", result.metadata.get("duration") if result.metadata else None)
+        else:
+            print("Workflow failed:", result.error)
+            
+    except Exception as error:
+        print("Error:", error)
+
+run_workflow()
+```
+
+### Fehlerbehandlung
+
+Behandeln Sie verschiedene Fehlertypen, die während der Workflow-Ausführung auftreten können:
+
+```python
+from simstudio import SimStudioClient, SimStudioError
+import os
+
+client = SimStudioClient(api_key=os.getenv("SIM_API_KEY"))
+
+def execute_with_error_handling():
+    try:
+        result = client.execute_workflow("workflow-id")
+        return result
+    except SimStudioError as error:
+        if error.code == "UNAUTHORIZED":
+            print("Invalid API key")
+        elif error.code == "TIMEOUT":
+            print("Workflow execution timed out")
+        elif error.code == "USAGE_LIMIT_EXCEEDED":
+            print("Usage limit exceeded")
+        elif error.code == "INVALID_JSON":
+            print("Invalid JSON in request body")
+        else:
+            print(f"Workflow error: {error}")
+        raise
+    except Exception as error:
+        print(f"Unexpected error: {error}")
+        raise
+```
+
+### Verwendung des Context-Managers
+
+Verwenden Sie den Client als Context-Manager, um die Ressourcenbereinigung automatisch zu handhaben:
+
+```python
+from simstudio import SimStudioClient
+import os
+
+# Using context manager to automatically close the session
+with SimStudioClient(api_key=os.getenv("SIM_API_KEY")) as client:
+    result = client.execute_workflow("workflow-id")
+    print("Result:", result)
+# Session is automatically closed here
+```
+
+### Batch-Workflow-Ausführung
+
+Führen Sie mehrere Workflows effizient aus:
+
+```python
+from simstudio import SimStudioClient
+import os
+
+client = SimStudioClient(api_key=os.getenv("SIM_API_KEY"))   
+
+def execute_workflows_batch(workflow_data_pairs):
+    """Execute multiple workflows with different input data."""
+    results = []
+    
+    for workflow_id, input_data in workflow_data_pairs:
+        try:
+            # Validate workflow before execution
+            if not client.validate_workflow(workflow_id):
+                print(f"Skipping {workflow_id}: not deployed")
+                continue
+                
+            result = client.execute_workflow(workflow_id, input_data)
+            results.append({
+                "workflow_id": workflow_id,
+                "success": result.success,
+                "output": result.output,
+                "error": result.error
+            })
+            
+        except Exception as error:
+            results.append({
+                "workflow_id": workflow_id,
+                "success": False,
+                "error": str(error)
+            })
+    
+    return results
+
+# Example usage
+workflows = [
+    ("workflow-1", {"type": "analysis", "data": "sample1"}),
+    ("workflow-2", {"type": "processing", "data": "sample2"}),
+]
+
+results = execute_workflows_batch(workflows)
+for result in results:
+    print(f"Workflow {result['workflow_id']}: {'Success' if result['success'] else 'Failed'}")
+```
+
+### Asynchrone Workflow-Ausführung
+
+Führen Sie Workflows asynchron für langwierige Aufgaben aus:
+
+```python
+import os
+import time
+from simstudio import SimStudioClient
+
+client = SimStudioClient(api_key=os.getenv("SIM_API_KEY"))
+
+def execute_async():
+    try:
+        # Start async execution
+        result = client.execute_workflow(
+            "workflow-id",
+            input_data={"data": "large dataset"},
+            async_execution=True  # Execute asynchronously
+        )
+
+        # Check if result is an async execution
+        if hasattr(result, 'task_id'):
+            print(f"Task ID: {result.task_id}")
+            print(f"Status endpoint: {result.links['status']}")
+
+            # Poll for completion
+            status = client.get_job_status(result.task_id)
+
+            while status["status"] in ["queued", "processing"]:
+                print(f"Current status: {status['status']}")
+                time.sleep(2)  # Wait 2 seconds
+                status = client.get_job_status(result.task_id)
+
+            if status["status"] == "completed":
+                print("Workflow completed!")
+                print(f"Output: {status['output']}")
+                print(f"Duration: {status['metadata']['duration']}")
+            else:
+                print(f"Workflow failed: {status['error']}")
+
+    except Exception as error:
+        print(f"Error: {error}")
+
+execute_async()
+```
+
+### Ratenlimitierung und Wiederholung
+
+Behandeln Sie Ratenbegrenzungen automatisch mit exponentiellem Backoff:
+
+```python
+import os
+from simstudio import SimStudioClient, SimStudioError
+
+client = SimStudioClient(api_key=os.getenv("SIM_API_KEY"))
+
+def execute_with_retry_handling():
+    try:
+        # Automatically retries on rate limit
+        result = client.execute_with_retry(
+            "workflow-id",
+            input_data={"message": "Process this"},
+            max_retries=5,
+            initial_delay=1.0,
+            max_delay=60.0,
+            backoff_multiplier=2.0
+        )
+
+        print(f"Success: {result}")
+    except SimStudioError as error:
+        if error.code == "RATE_LIMIT_EXCEEDED":
+            print("Rate limit exceeded after all retries")
+
+            # Check rate limit info
+            rate_limit_info = client.get_rate_limit_info()
+            if rate_limit_info:
+                from datetime import datetime
+                reset_time = datetime.fromtimestamp(rate_limit_info.reset)
+                print(f"Rate limit resets at: {reset_time}")
+
+execute_with_retry_handling()
+```
+
+### Nutzungsüberwachung
+
+Überwachen Sie die Nutzung und Limits Ihres Kontos:
+
+```python
+import os
+from simstudio import SimStudioClient
+
+client = SimStudioClient(api_key=os.getenv("SIM_API_KEY"))
+
+def check_usage():
+    try:
+        limits = client.get_usage_limits()
+
+        print("=== Rate Limits ===")
+        print("Sync requests:")
+        print(f"  Limit: {limits.rate_limit['sync']['limit']}")
+        print(f"  Remaining: {limits.rate_limit['sync']['remaining']}")
+        print(f"  Resets at: {limits.rate_limit['sync']['resetAt']}")
+        print(f"  Is limited: {limits.rate_limit['sync']['isLimited']}")
+
+        print("\nAsync requests:")
+        print(f"  Limit: {limits.rate_limit['async']['limit']}")
+        print(f"  Remaining: {limits.rate_limit['async']['remaining']}")
+        print(f"  Resets at: {limits.rate_limit['async']['resetAt']}")
+        print(f"  Is limited: {limits.rate_limit['async']['isLimited']}")
+
+        print("\n=== Usage ===")
+        print(f"Current period cost: ${limits.usage['currentPeriodCost']:.2f}")
+        print(f"Limit: ${limits.usage['limit']:.2f}")
+        print(f"Plan: {limits.usage['plan']}")
+
+        percent_used = (limits.usage['currentPeriodCost'] / limits.usage['limit']) * 100
+        print(f"Usage: {percent_used:.1f}%")
+
+        if percent_used > 80:
+            print("⚠️  Warning: You are approaching your usage limit!")
+
+    except Exception as error:
+        print(f"Error checking usage: {error}")
+
+check_usage()
+```
+
+### Streaming-Workflow-Ausführung
+
+Führen Sie Workflows mit Echtzeit-Streaming-Antworten aus:
+
+```python
+from simstudio import SimStudioClient
+import os
+
+client = SimStudioClient(api_key=os.getenv("SIM_API_KEY"))
+
+def execute_with_streaming():
+    """Execute workflow with streaming enabled."""
+    try:
+        # Enable streaming for specific block outputs
+        result = client.execute_workflow(
+            "workflow-id",
+            input_data={"message": "Count to five"},
+            stream=True,
+            selected_outputs=["agent1.content"]  # Use blockName.attribute format
+        )
+
+        print("Workflow result:", result)
+    except Exception as error:
+        print("Error:", error)
+
+execute_with_streaming()
+```
+
+Die Streaming-Antwort folgt dem Server-Sent-Events- (SSE-) Format:
+
+```
+data: {"blockId":"7b7735b9-19e5-4bd6-818b-46aae2596e9f","chunk":"One"}
+
+data: {"blockId":"7b7735b9-19e5-4bd6-818b-46aae2596e9f","chunk":", two"}
+
+data: {"event":"done","success":true,"output":{},"metadata":{"duration":610}}
+
+data: [DONE]
+```
+
+**Flask-Streaming-Beispiel:**
+
+```python
+from flask import Flask, Response, stream_with_context
+import requests
+import json
+import os
+
+app = Flask(__name__)
+
+@app.route('/stream-workflow')
+def stream_workflow():
+    """Stream workflow execution to the client."""
+
+    def generate():
+        response = requests.post(
+            'https://sim.ai/api/workflows/WORKFLOW_ID/execute',
+            headers={
+                'Content-Type': 'application/json',
+                'X-API-Key': os.getenv('SIM_API_KEY')
+            },
+            json={
+                'message': 'Generate a story',
+                'stream': True,
+                'selectedOutputs': ['agent1.content']
+            },
+            stream=True
+        )
+
+        for line in response.iter_lines():
+            if line:
+                decoded_line = line.decode('utf-8')
+                if decoded_line.startswith('data: '):
+                    data = decoded_line[6:]  # Remove 'data: ' prefix
+
+                    if data == '[DONE]':
+                        break
+
+                    try:
+                        parsed = json.loads(data)
+                        if 'chunk' in parsed:
+                            yield f"data: {json.dumps(parsed)}\n\n"
+                        elif parsed.get('event') == 'done':
+                            yield f"data: {json.dumps(parsed)}\n\n"
+                            print("Execution complete:", parsed.get('metadata'))
+                    except json.JSONDecodeError:
+                        pass
+
+    return Response(
+        stream_with_context(generate()),
+        mimetype='text/event-stream'
+    )
+
+if __name__ == '__main__':
+    app.run(debug=True)
+```
+
+### Umgebungs­konfiguration
+
+Konfigurieren Sie den Client mit Umgebungsvariablen:
+
+<Tabs items={['Development', 'Production']}>
+  <Tab value="Development">
+
+    ```python
+    import os
+    from simstudio import SimStudioClient
+
+    # Development configuration
+    client = SimStudioClient(
+        api_key=os.getenv("SIM_API_KEY")
+        base_url=os.getenv("SIM_BASE_URL", "https://sim.ai")
+    )
+    ```
+
+  </Tab>
+  <Tab value="Production">
+
+    ```python
+    import os
+    from simstudio import SimStudioClient
+
+    # Production configuration with error handling
+    api_key = os.getenv("SIM_API_KEY")
+    if not api_key:
+        raise ValueError("SIM_API_KEY environment variable is required")
+
+    client = SimStudioClient(
+        api_key=api_key,
+        base_url=os.getenv("SIM_BASE_URL", "https://sim.ai")
+    )
+    ```
+
+  </Tab>
+</Tabs>
+
+## Ihren API-Schlüssel erhalten
+
+<Steps>
+  <Step title="Bei Sim anmelden">
+    Navigieren Sie zu [Sim](https://sim.ai) und melden Sie sich in Ihrem Konto an.
+  </Step>
+  <Step title="Workflow öffnen">
+    Navigieren Sie zu dem Workflow, den Sie programmatisch ausführen möchten.
+  </Step>
+  <Step title="Workflow bereitstellen">
+    Klicken Sie auf "Bereitstellen", um Ihren Workflow bereitzustellen, falls dies noch nicht geschehen ist.
+  </Step>
+  <Step title="API-Schlüssel erstellen oder auswählen">
+    Wählen oder erstellen Sie während des Bereitstellungsprozesses einen API-Schlüssel.
+  </Step>
+  <Step title="API-Schlüssel kopieren">
+    Kopieren Sie den API-Schlüssel, um ihn in Ihrer Python-Anwendung zu verwenden.
+  </Step>
+</Steps>
+
+## Voraussetzungen
+
+- Python 3.8+
+- requests >= 2.25.0
+
+## Lizenz
+
+Apache-2.0

apps/docs/content/docs/de/blocks/guardrails.mdx

@@ -131,7 +131,7 @@ Erkennt personenbezogene Daten mithilfe von Microsoft Presidio. Unterstützt üb
 **Anwendungsfälle:**
 - Blockieren von Inhalten mit sensiblen persönlichen Informationen
 - Maskieren von personenbezogenen Daten vor der Protokollierung oder Speicherung
-- Einhaltung der DSGVO, HIPAA und anderer Datenschutzbestimmungen
+- Einhaltung der DSGVO und anderer Datenschutzbestimmungen
 - Bereinigung von Benutzereingaben vor der Verarbeitung
 
 ## Konfiguration

apps/docs/content/docs/de/blocks/loop.mdx

@@ -190,13 +190,8 @@ console.log(`${processedItems} gültige Elemente verarbeitet`);
 
 ### Einschränkungen
 
-<Callout type="warning">
-  Container-Blöcke (Schleifen und Parallele) können nicht ineinander verschachtelt werden. Das bedeutet:
-  - Du kannst keinen Schleifenblock in einen anderen Schleifenblock platzieren
-  - Du kannst keinen Parallel-Block in einen Schleifenblock platzieren
-  - Du kannst keinen Container-Block in einen anderen Container-Block platzieren
-  
-  Wenn du mehrdimensionale Iterationen benötigst, erwäge eine Umstrukturierung deines Workflows, um sequentielle Schleifen zu verwenden oder Daten in Stufen zu verarbeiten.
+<Callout type="info">
+  Container-Blöcke (Schleifen und Parallele) unterstützen Verschachtelung. Du kannst Schleifen in Schleifen, Parallele in Schleifen und jede Kombination von Container-Blöcken platzieren, um komplexe mehrdimensionale Workflows zu erstellen.
 </Callout>
 
 <Callout type="info">

apps/docs/content/docs/de/blocks/parallel.mdx

@@ -142,11 +142,8 @@ Jede parallele Instanz läuft unabhängig:
 
 ### Einschränkungen
 
-<Callout type="warning">
-  Container-Blöcke (Schleifen und Parallele) können nicht ineinander verschachtelt werden. Das bedeutet:
-  - Sie können keinen Schleifenblock in einen Parallelblock platzieren
-  - Sie können keinen weiteren Parallelblock in einen Parallelblock platzieren
-  - Sie können keinen Container-Block in einen anderen Container-Block platzieren
+<Callout type="info">
+  Container-Blöcke (Schleifen und Parallele) unterstützen Verschachtelung. Sie können Parallele in Parallele, Schleifen in Parallele und jede Kombination von Container-Blöcken platzieren, um komplexe mehrdimensionale Workflows zu erstellen.
 </Callout>
 
 <Callout type="info">

apps/docs/content/docs/de/meta.json

@@ -0,0 +1,24 @@
+{
+  "title": "Sim Documentation",
+  "pages": [
+    "./introduction/index",
+    "./getting-started/index",
+    "./quick-reference/index",
+    "triggers",
+    "blocks",
+    "tools",
+    "connections",
+    "mcp",
+    "copilot",
+    "skills",
+    "knowledgebase",
+    "variables",
+    "credentials",
+    "execution",
+    "permissions",
+    "self-hosting",
+    "./enterprise/index",
+    "./keyboard-shortcuts/index"
+  ],
+  "defaultOpen": false
+}

apps/docs/content/docs/de/variables/environment-variables.mdx

@@ -1,96 +0,0 @@
----
-title: Umgebungsvariablen
----
-
-import { Callout } from 'fumadocs-ui/components/callout'
-import { Image } from '@/components/ui/image'
-
-Umgebungsvariablen bieten eine sichere Möglichkeit, Konfigurationswerte und Geheimnisse in Ihren Workflows zu verwalten, einschließlich API-Schlüssel und anderer sensibler Daten, auf die Ihre Workflows zugreifen müssen. Sie halten Geheimnisse aus Ihren Workflow-Definitionen heraus und machen sie während der Ausführung verfügbar.
-
-## Variablentypen
-
-Umgebungsvariablen in Sim funktionieren auf zwei Ebenen:
-
-- **Persönliche Umgebungsvariablen**: Privat für Ihr Konto, nur Sie können sie sehen und verwenden
-- **Workspace-Umgebungsvariablen**: Werden im gesamten Workspace geteilt und sind für alle Teammitglieder verfügbar
-
-<Callout type="info">
-Workspace-Umgebungsvariablen haben Vorrang vor persönlichen Variablen, wenn es einen Namenskonflikt gibt.
-</Callout>
-
-## Einrichten von Umgebungsvariablen
-
-Navigieren Sie zu den Einstellungen, um Ihre Umgebungsvariablen zu konfigurieren:
-
-<Image
-  src="/static/environment/environment-1.png"
-  alt="Umgebungsvariablen-Modal zum Erstellen neuer Variablen"
-  width={500}
-  height={350}
-/>
-
-In Ihren Workspace-Einstellungen können Sie sowohl persönliche als auch Workspace-Umgebungsvariablen erstellen und verwalten. Persönliche Variablen sind privat für Ihr Konto, während Workspace-Variablen mit allen Teammitgliedern geteilt werden.
-
-### Variablen auf Workspace-Ebene setzen
-
-Verwenden Sie den Workspace-Bereichsschalter, um Variablen für Ihr gesamtes Team verfügbar zu machen:
-
-<Image
-  src="/static/environment/environment-2.png"
-  alt="Workspace-Bereich für Umgebungsvariablen umschalten"
-  width={500}
-  height={350}
-/>
-
-Wenn Sie den Workspace-Bereich aktivieren, wird die Variable für alle Workspace-Mitglieder verfügbar und kann in jedem Workflow innerhalb dieses Workspaces verwendet werden.
-
-### Ansicht der Workspace-Variablen
-
-Sobald Sie Workspace-Variablen haben, erscheinen sie in Ihrer Liste der Umgebungsvariablen:
-
-<Image
-  src="/static/environment/environment-3.png"
-  alt="Workspace-Variablen in der Liste der Umgebungsvariablen"
-  width={500}
-  height={350}
-/>
-
-## Verwendung von Variablen in Workflows
-
-Um Umgebungsvariablen in Ihren Workflows zu referenzieren, verwenden Sie die `{{}}` Notation. Wenn Sie `{{` in ein beliebiges Eingabefeld eingeben, erscheint ein Dropdown-Menü mit Ihren persönlichen und Workspace-Umgebungsvariablen. Wählen Sie einfach die Variable aus, die Sie verwenden möchten.
-
-<Image
-  src="/static/environment/environment-4.png"
-  alt="Verwendung von Umgebungsvariablen mit doppelter Klammernotation"
-  width={500}
-  height={350}
-/>
-
-## Wie Variablen aufgelöst werden
-
-**Workspace-Variablen haben immer Vorrang** vor persönlichen Variablen, unabhängig davon, wer den Workflow ausführt.
-
-Wenn keine Workspace-Variable für einen Schlüssel existiert, werden persönliche Variablen verwendet:
-- **Manuelle Ausführungen (UI)**: Ihre persönlichen Variablen
-- **Automatisierte Ausführungen (API, Webhook, Zeitplan, bereitgestellter Chat)**: Persönliche Variablen des Workflow-Besitzers
-
-<Callout type="info">
-Persönliche Variablen eignen sich am besten zum Testen. Verwenden Sie Workspace-Variablen für Produktions-Workflows.
-</Callout>
-
-## Sicherheits-Best-Practices
-
-### Für sensible Daten
-- Speichern Sie API-Schlüssel, Tokens und Passwörter als Umgebungsvariablen anstatt sie im Code festzuschreiben
-- Verwenden Sie Workspace-Variablen für gemeinsam genutzte Ressourcen, die mehrere Teammitglieder benötigen
-- Bewahren Sie persönliche Anmeldedaten in persönlichen Variablen auf
-
-### Variablenbenennung
-- Verwenden Sie beschreibende Namen: `DATABASE_URL` anstatt `DB`
-- Folgen Sie einheitlichen Benennungskonventionen in Ihrem Team
-- Erwägen Sie Präfixe, um Konflikte zu vermeiden: `PROD_API_KEY`, `DEV_API_KEY`
-
-### Zugriffskontrolle
-- Workspace-Umgebungsvariablen respektieren Workspace-Berechtigungen
-- Nur Benutzer mit Schreibzugriff oder höher können Workspace-Variablen erstellen/ändern
-- Persönliche Variablen sind immer privat für den einzelnen Benutzer

apps/docs/content/docs/en/api-reference/(generated)/workflows/meta.json

@@ -0,0 +1,3 @@
+{
+  "pages": ["executeWorkflow", "cancelExecution", "listWorkflows", "getWorkflow", "getJobStatus"]
+}

apps/docs/content/docs/en/api-reference/authentication.mdx

@@ -0,0 +1,94 @@
+---
+title: Authentication
+description: API key types, generation, and how to authenticate requests
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+
+To access the Sim API, you need an API key. Sim supports two types of API keys — **personal keys** and **workspace keys** — each with different billing and access behaviors.
+
+## Key Types
+
+|  | **Personal Keys** | **Workspace Keys** |
+| --- | --- | --- |
+| **Billed to** | Your individual account | Workspace owner |
+| **Scope** | Across workspaces you have access to | Shared across the workspace |
+| **Managed by** | Each user individually | Workspace admins |
+| **Permissions** | Must be enabled at workspace level | Require admin permissions |
+
+<Callout type="info">
+  Workspace admins can disable personal API key usage for their workspace. If disabled, only workspace keys can be used.
+</Callout>
+
+## Generating API Keys
+
+To generate a key, open the Sim dashboard and navigate to **Settings**, then go to **Sim Keys** and click **Create**.
+
+<Callout type="warn">
+  API keys are only shown once when generated. Store your key securely — you will not be able to view it again.
+</Callout>
+
+## Using API Keys
+
+Pass your API key in the `X-API-Key` header with every request:
+
+<Tabs items={['curl', 'TypeScript', 'Python']}>
+  <Tab value="curl">
+    ```bash
+    curl -X POST https://www.sim.ai/api/workflows/{workflowId}/execute \
+      -H "Content-Type: application/json" \
+      -H "X-API-Key: YOUR_API_KEY" \
+      -d '{"inputs": {}}'
+    ```
+  </Tab>
+  <Tab value="TypeScript">
+    ```typescript
+    const response = await fetch(
+      'https://www.sim.ai/api/workflows/{workflowId}/execute',
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-API-Key': process.env.SIM_API_KEY!,
+        },
+        body: JSON.stringify({ inputs: {} }),
+      }
+    )
+    ```
+  </Tab>
+  <Tab value="Python">
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://www.sim.ai/api/workflows/{workflowId}/execute",
+        headers={
+            "Content-Type": "application/json",
+            "X-API-Key": os.environ["SIM_API_KEY"],
+        },
+        json={"inputs": {}},
+    )
+    ```
+  </Tab>
+</Tabs>
+
+## Where Keys Are Used
+
+API keys authenticate access to:
+
+- **Workflow execution** — run deployed workflows via the API
+- **Logs API** — query workflow execution logs and metrics
+- **MCP servers** — authenticate connections to deployed MCP servers
+- **SDKs** — the [Python](/api-reference/python) and [TypeScript](/api-reference/typescript) SDKs use API keys for all operations
+
+## Security
+
+- Keys use the `sk-sim-` prefix and are encrypted at rest
+- Keys can be revoked at any time from the dashboard
+- Use environment variables to store keys — never hardcode them in source code
+- For browser-based applications, use a backend proxy to avoid exposing keys to the client
+
+<Callout type="warn">
+  Never expose your API key in client-side code. Use a server-side proxy to make authenticated requests on behalf of your frontend.
+</Callout>

apps/docs/content/docs/en/api-reference/getting-started.mdx

@@ -0,0 +1,210 @@
+---
+title: Getting Started
+description: Base URL, first API call, response format, error handling, and pagination
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+import { Step, Steps } from 'fumadocs-ui/components/steps'
+
+## Base URL
+
+All API requests are made to:
+
+```
+https://www.sim.ai
+```
+
+## Quick Start
+
+<Steps>
+
+<Step>
+### Get your API key
+
+Go to the Sim platform and navigate to **Settings**, then go to **Sim Keys** and click **Create**. See [Authentication](/api-reference/authentication) for details on key types.
+</Step>
+
+<Step>
+### Find your workflow ID
+
+Open a workflow in the Sim editor. The workflow ID is in the URL:
+
+```
+https://www.sim.ai/workspace/{workspaceId}/w/{workflowId}
+```
+
+You can also use the [List Workflows](/api-reference/workflows/listWorkflows) endpoint to get all workflow IDs in a workspace.
+</Step>
+
+<Step>
+### Deploy your workflow
+
+A workflow must be deployed before it can be executed via the API. Click the **Deploy** button in the editor toolbar, or use the dashboard to manage deployments.
+</Step>
+
+<Step>
+### Make your first request
+
+<Tabs items={['curl', 'TypeScript', 'Python']}>
+  <Tab value="curl">
+    ```bash
+    curl -X POST https://www.sim.ai/api/workflows/{workflowId}/execute \
+      -H "Content-Type: application/json" \
+      -H "X-API-Key: YOUR_API_KEY" \
+      -d '{"inputs": {}}'
+    ```
+  </Tab>
+  <Tab value="TypeScript">
+    ```typescript
+    const response = await fetch(
+      `https://www.sim.ai/api/workflows/${workflowId}/execute`,
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-API-Key': process.env.SIM_API_KEY!,
+        },
+        body: JSON.stringify({ inputs: {} }),
+      }
+    )
+
+    const data = await response.json()
+    console.log(data.output)
+    ```
+  </Tab>
+  <Tab value="Python">
+    ```python
+    import requests
+    import os
+
+    response = requests.post(
+        f"https://www.sim.ai/api/workflows/{workflow_id}/execute",
+        headers={
+            "Content-Type": "application/json",
+            "X-API-Key": os.environ["SIM_API_KEY"],
+        },
+        json={"inputs": {}},
+    )
+
+    data = response.json()
+    print(data["output"])
+    ```
+  </Tab>
+</Tabs>
+</Step>
+
+</Steps>
+
+## Sync vs Async Execution
+
+By default, workflow executions are **synchronous** — the API blocks until the workflow completes and returns the result directly.
+
+For long-running workflows, use **asynchronous execution** by passing `async: true`:
+
+```bash
+curl -X POST https://www.sim.ai/api/workflows/{workflowId}/execute \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: YOUR_API_KEY" \
+  -d '{"inputs": {}, "async": true}'
+```
+
+This returns immediately with a `taskId`:
+
+```json
+{
+  "success": true,
+  "taskId": "job_abc123",
+  "status": "queued"
+}
+```
+
+Poll the [Get Job Status](/api-reference/workflows/getJobStatus) endpoint until the status is `completed` or `failed`:
+
+```bash
+curl https://www.sim.ai/api/jobs/{taskId} \
+  -H "X-API-Key: YOUR_API_KEY"
+```
+
+<Callout type="info">
+  Job status transitions follow: `queued` → `processing` → `completed` or `failed`. The `output` field is only present when status is `completed`.
+</Callout>
+
+## Response Format
+
+Successful responses include an `output` object with your workflow results and a `limits` object with your current rate limit and usage status:
+
+```json
+{
+  "success": true,
+  "output": {
+    "result": "Hello, world!"
+  },
+  "limits": {
+    "workflowExecutionRateLimit": {
+      "sync": {
+        "requestsPerMinute": 60,
+        "maxBurst": 10,
+        "remaining": 59,
+        "resetAt": "2025-01-01T00:01:00Z"
+      },
+      "async": {
+        "requestsPerMinute": 30,
+        "maxBurst": 5,
+        "remaining": 30,
+        "resetAt": "2025-01-01T00:01:00Z"
+      }
+    },
+    "usage": {
+      "currentPeriodCost": 1.25,
+      "limit": 50.00,
+      "plan": "pro",
+      "isExceeded": false
+    }
+  }
+}
+```
+
+## Error Handling
+
+The API uses standard HTTP status codes. Error responses include a human-readable `error` message:
+
+```json
+{
+  "error": "Workflow not found"
+}
+```
+
+| Status | Meaning | What to do |
+| --- | --- | --- |
+| `400` | Invalid request parameters | Check the `details` array for specific field errors |
+| `401` | Missing or invalid API key | Verify your `X-API-Key` header |
+| `403` | Access denied | Check you have permission for this resource |
+| `404` | Resource not found | Verify the ID exists and belongs to your workspace |
+| `429` | Rate limit exceeded | Wait for the duration in the `Retry-After` header |
+
+<Callout type="info">
+  Use the [Get Usage Limits](/api-reference/usage/getUsageLimits) endpoint to check your current rate limit status and billing usage at any time.
+</Callout>
+
+## Rate Limits
+
+Rate limits depend on your subscription plan and apply separately to synchronous and asynchronous executions. Every execution response includes a `limits` object showing your current rate limit status.
+
+When rate limited, the API returns a `429` response with a `Retry-After` header indicating how many seconds to wait before retrying.
+
+## Pagination
+
+List endpoints (workflows, logs, audit logs) use **cursor-based pagination**:
+
+```bash
+# First page
+curl "https://www.sim.ai/api/v1/logs?limit=20" \
+  -H "X-API-Key: YOUR_API_KEY"
+
+# Next page — use the nextCursor from the previous response
+curl "https://www.sim.ai/api/v1/logs?limit=20&cursor=abc123" \
+  -H "X-API-Key: YOUR_API_KEY"
+```
+
+The response includes a `nextCursor` field. When `nextCursor` is absent or `null`, you have reached the last page.

apps/docs/content/docs/en/api-reference/meta.json

@@ -0,0 +1,19 @@
+{
+  "title": "API Reference",
+  "root": true,
+  "pages": [
+    "getting-started",
+    "authentication",
+    "---SDKs---",
+    "python",
+    "typescript",
+    "---Endpoints---",
+    "(generated)/workflows",
+    "(generated)/logs",
+    "(generated)/usage",
+    "(generated)/audit-logs",
+    "(generated)/tables",
+    "(generated)/files",
+    "(generated)/knowledge-bases"
+  ]
+}

apps/docs/content/docs/en/api-reference/python.mdx

@@ -0,0 +1,761 @@
+---
+title: Python
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Card, Cards } from 'fumadocs-ui/components/card'
+import { Step, Steps } from 'fumadocs-ui/components/steps'
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+
+The official Python SDK for Sim allows you to execute workflows programmatically from your Python applications using the official Python SDK.
+
+<Callout type="info">
+  The Python SDK supports Python 3.8+ with async execution support, automatic rate limiting with exponential backoff, and usage tracking.
+</Callout>
+
+## Installation
+
+Install the SDK using pip:
+
+```bash
+pip install simstudio-sdk
+```
+
+## Quick Start
+
+Here's a simple example to get you started:
+
+```python
+from simstudio import SimStudioClient
+
+# Initialize the client
+client = SimStudioClient(
+    api_key="your-api-key-here",
+    base_url="https://sim.ai"  # optional, defaults to https://sim.ai
+)
+
+# Execute a workflow
+try:
+    result = client.execute_workflow("workflow-id")
+    print("Workflow executed successfully:", result)
+except Exception as error:
+    print("Workflow execution failed:", error)
+```
+
+## API Reference
+
+### SimStudioClient
+
+#### Constructor
+
+```python
+SimStudioClient(api_key: str, base_url: str = "https://sim.ai")
+```
+
+**Parameters:**
+- `api_key` (str): Your Sim API key
+- `base_url` (str, optional): Base URL for the Sim API
+
+#### Methods
+
+##### execute_workflow()
+
+Execute a workflow with optional input data.
+
+```python
+result = client.execute_workflow(
+    "workflow-id",
+    input_data={"message": "Hello, world!"},
+    timeout=30.0  # 30 seconds
+)
+```
+
+**Parameters:**
+- `workflow_id` (str): The ID of the workflow to execute
+- `input_data` (dict, optional): Input data to pass to the workflow
+- `timeout` (float, optional): Timeout in seconds (default: 30.0)
+- `stream` (bool, optional): Enable streaming responses (default: False)
+- `selected_outputs` (list[str], optional): Block outputs to stream in `blockName.attribute` format (e.g., `["agent1.content"]`)
+- `async_execution` (bool, optional): Execute asynchronously (default: False)
+
+**Returns:** `WorkflowExecutionResult | AsyncExecutionResult`
+
+When `async_execution=True`, returns immediately with a task ID for polling. Otherwise, waits for completion.
+
+##### get_workflow_status()
+
+Get the status of a workflow (deployment status, etc.).
+
+```python
+status = client.get_workflow_status("workflow-id")
+print("Is deployed:", status.is_deployed)
+```
+
+**Parameters:**
+- `workflow_id` (str): The ID of the workflow
+
+**Returns:** `WorkflowStatus`
+
+##### validate_workflow()
+
+Validate that a workflow is ready for execution.
+
+```python
+is_ready = client.validate_workflow("workflow-id")
+if is_ready:
+    # Workflow is deployed and ready
+    pass
+```
+
+**Parameters:**
+- `workflow_id` (str): The ID of the workflow
+
+**Returns:** `bool`
+
+##### get_job_status()
+
+Get the status of an async job execution.
+
+```python
+status = client.get_job_status("task-id-from-async-execution")
+print("Status:", status["status"])  # 'queued', 'processing', 'completed', 'failed'
+if status["status"] == "completed":
+    print("Output:", status["output"])
+```
+
+**Parameters:**
+- `task_id` (str): The task ID returned from async execution
+
+**Returns:** `Dict[str, Any]`
+
+**Response fields:**
+- `success` (bool): Whether the request was successful
+- `taskId` (str): The task ID
+- `status` (str): One of `'queued'`, `'processing'`, `'completed'`, `'failed'`, `'cancelled'`
+- `metadata` (dict): Contains `startedAt`, `completedAt`, and `duration`
+- `output` (any, optional): The workflow output (when completed)
+- `error` (any, optional): Error details (when failed)
+- `estimatedDuration` (int, optional): Estimated duration in milliseconds (when processing/queued)
+
+##### execute_with_retry()
+
+Execute a workflow with automatic retry on rate limit errors using exponential backoff.
+
+```python
+result = client.execute_with_retry(
+    "workflow-id",
+    input_data={"message": "Hello"},
+    timeout=30.0,
+    max_retries=3,           # Maximum number of retries
+    initial_delay=1.0,       # Initial delay in seconds
+    max_delay=30.0,          # Maximum delay in seconds
+    backoff_multiplier=2.0   # Exponential backoff multiplier
+)
+```
+
+**Parameters:**
+- `workflow_id` (str): The ID of the workflow to execute
+- `input_data` (dict, optional): Input data to pass to the workflow
+- `timeout` (float, optional): Timeout in seconds
+- `stream` (bool, optional): Enable streaming responses
+- `selected_outputs` (list, optional): Block outputs to stream
+- `async_execution` (bool, optional): Execute asynchronously
+- `max_retries` (int, optional): Maximum number of retries (default: 3)
+- `initial_delay` (float, optional): Initial delay in seconds (default: 1.0)
+- `max_delay` (float, optional): Maximum delay in seconds (default: 30.0)
+- `backoff_multiplier` (float, optional): Backoff multiplier (default: 2.0)
+
+**Returns:** `WorkflowExecutionResult | AsyncExecutionResult`
+
+The retry logic uses exponential backoff (1s → 2s → 4s → 8s...) with ±25% jitter to prevent thundering herd. If the API provides a `retry-after` header, it will be used instead.
+
+##### get_rate_limit_info()
+
+Get the current rate limit information from the last API response.
+
+```python
+rate_limit_info = client.get_rate_limit_info()
+if rate_limit_info:
+    print("Limit:", rate_limit_info.limit)
+    print("Remaining:", rate_limit_info.remaining)
+    print("Reset:", datetime.fromtimestamp(rate_limit_info.reset))
+```
+
+**Returns:** `RateLimitInfo | None`
+
+##### get_usage_limits()
+
+Get current usage limits and quota information for your account.
+
+```python
+limits = client.get_usage_limits()
+print("Sync requests remaining:", limits.rate_limit["sync"]["remaining"])
+print("Async requests remaining:", limits.rate_limit["async"]["remaining"])
+print("Current period cost:", limits.usage["currentPeriodCost"])
+print("Plan:", limits.usage["plan"])
+```
+
+**Returns:** `UsageLimits`
+
+**Response structure:**
+```python
+{
+    "success": bool,
+    "rateLimit": {
+        "sync": {
+            "isLimited": bool,
+            "limit": int,
+            "remaining": int,
+            "resetAt": str
+        },
+        "async": {
+            "isLimited": bool,
+            "limit": int,
+            "remaining": int,
+            "resetAt": str
+        },
+        "authType": str  # 'api' or 'manual'
+    },
+    "usage": {
+        "currentPeriodCost": float,
+        "limit": float,
+        "plan": str  # e.g., 'free', 'pro'
+    }
+}
+```
+
+##### set_api_key()
+
+Update the API key.
+
+```python
+client.set_api_key("new-api-key")
+```
+
+##### set_base_url()
+
+Update the base URL.
+
+```python
+client.set_base_url("https://my-custom-domain.com")
+```
+
+##### close()
+
+Close the underlying HTTP session.
+
+```python
+client.close()
+```
+
+## Data Classes
+
+### WorkflowExecutionResult
+
+```python
+@dataclass
+class WorkflowExecutionResult:
+    success: bool
+    output: Optional[Any] = None
+    error: Optional[str] = None
+    logs: Optional[List[Any]] = None
+    metadata: Optional[Dict[str, Any]] = None
+    trace_spans: Optional[List[Any]] = None
+    total_duration: Optional[float] = None
+```
+
+### AsyncExecutionResult
+
+```python
+@dataclass
+class AsyncExecutionResult:
+    success: bool
+    task_id: str
+    status: str  # 'queued'
+    created_at: str
+    links: Dict[str, str]  # e.g., {"status": "/api/jobs/{taskId}"}
+```
+
+### WorkflowStatus
+
+```python
+@dataclass
+class WorkflowStatus:
+    is_deployed: bool
+    deployed_at: Optional[str] = None
+    needs_redeployment: bool = False
+```
+
+### RateLimitInfo
+
+```python
+@dataclass
+class RateLimitInfo:
+    limit: int
+    remaining: int
+    reset: int
+    retry_after: Optional[int] = None
+```
+
+### UsageLimits
+
+```python
+@dataclass
+class UsageLimits:
+    success: bool
+    rate_limit: Dict[str, Any]
+    usage: Dict[str, Any]
+```
+
+### SimStudioError
+
+```python
+class SimStudioError(Exception):
+    def __init__(self, message: str, code: Optional[str] = None, status: Optional[int] = None):
+        super().__init__(message)
+        self.code = code
+        self.status = status
+```
+
+**Common error codes:**
+- `UNAUTHORIZED`: Invalid API key
+- `TIMEOUT`: Request timed out
+- `RATE_LIMIT_EXCEEDED`: Rate limit exceeded
+- `USAGE_LIMIT_EXCEEDED`: Usage limit exceeded
+- `EXECUTION_ERROR`: Workflow execution failed
+
+## Examples
+
+### Basic Workflow Execution
+
+<Steps>
+  <Step title="Initialize the client">
+    Set up the SimStudioClient with your API key.
+  </Step>
+  <Step title="Validate the workflow">
+    Check if the workflow is deployed and ready for execution.
+  </Step>
+  <Step title="Execute the workflow">
+    Run the workflow with your input data.
+  </Step>
+  <Step title="Handle the result">
+    Process the execution result and handle any errors.
+  </Step>
+</Steps>
+
+```python
+import os
+from simstudio import SimStudioClient
+
+client = SimStudioClient(api_key=os.getenv("SIM_API_KEY"))
+
+def run_workflow():
+    try:
+        # Check if workflow is ready
+        is_ready = client.validate_workflow("my-workflow-id")
+        if not is_ready:
+            raise Exception("Workflow is not deployed or ready")
+
+        # Execute the workflow
+        result = client.execute_workflow(
+            "my-workflow-id",
+            input_data={
+                "message": "Process this data",
+                "user_id": "12345"
+            }
+        )
+
+        if result.success:
+            print("Output:", result.output)
+            print("Duration:", result.metadata.get("duration") if result.metadata else None)
+        else:
+            print("Workflow failed:", result.error)
+            
+    except Exception as error:
+        print("Error:", error)
+
+run_workflow()
+```
+
+### Error Handling
+
+Handle different types of errors that may occur during workflow execution:
+
+```python
+from simstudio import SimStudioClient, SimStudioError
+import os
+
+client = SimStudioClient(api_key=os.getenv("SIM_API_KEY"))
+
+def execute_with_error_handling():
+    try:
+        result = client.execute_workflow("workflow-id")
+        return result
+    except SimStudioError as error:
+        if error.code == "UNAUTHORIZED":
+            print("Invalid API key")
+        elif error.code == "TIMEOUT":
+            print("Workflow execution timed out")
+        elif error.code == "USAGE_LIMIT_EXCEEDED":
+            print("Usage limit exceeded")
+        elif error.code == "INVALID_JSON":
+            print("Invalid JSON in request body")
+        else:
+            print(f"Workflow error: {error}")
+        raise
+    except Exception as error:
+        print(f"Unexpected error: {error}")
+        raise
+```
+
+### Context Manager Usage
+
+Use the client as a context manager to automatically handle resource cleanup:
+
+```python
+from simstudio import SimStudioClient
+import os
+
+# Using context manager to automatically close the session
+with SimStudioClient(api_key=os.getenv("SIM_API_KEY")) as client:
+    result = client.execute_workflow("workflow-id")
+    print("Result:", result)
+# Session is automatically closed here
+```
+
+### Batch Workflow Execution
+
+Execute multiple workflows efficiently:
+
+```python
+from simstudio import SimStudioClient
+import os
+
+client = SimStudioClient(api_key=os.getenv("SIM_API_KEY"))   
+
+def execute_workflows_batch(workflow_data_pairs):
+    """Execute multiple workflows with different input data."""
+    results = []
+    
+    for workflow_id, input_data in workflow_data_pairs:
+        try:
+            # Validate workflow before execution
+            if not client.validate_workflow(workflow_id):
+                print(f"Skipping {workflow_id}: not deployed")
+                continue
+                
+            result = client.execute_workflow(workflow_id, input_data)
+            results.append({
+                "workflow_id": workflow_id,
+                "success": result.success,
+                "output": result.output,
+                "error": result.error
+            })
+            
+        except Exception as error:
+            results.append({
+                "workflow_id": workflow_id,
+                "success": False,
+                "error": str(error)
+            })
+    
+    return results
+
+# Example usage
+workflows = [
+    ("workflow-1", {"type": "analysis", "data": "sample1"}),
+    ("workflow-2", {"type": "processing", "data": "sample2"}),
+]
+
+results = execute_workflows_batch(workflows)
+for result in results:
+    print(f"Workflow {result['workflow_id']}: {'Success' if result['success'] else 'Failed'}")
+```
+
+### Async Workflow Execution
+
+Execute workflows asynchronously for long-running tasks:
+
+```python
+import os
+import time
+from simstudio import SimStudioClient
+
+client = SimStudioClient(api_key=os.getenv("SIM_API_KEY"))
+
+def execute_async():
+    try:
+        # Start async execution
+        result = client.execute_workflow(
+            "workflow-id",
+            input_data={"data": "large dataset"},
+            async_execution=True  # Execute asynchronously
+        )
+
+        # Check if result is an async execution
+        if hasattr(result, 'task_id'):
+            print(f"Task ID: {result.task_id}")
+            print(f"Status endpoint: {result.links['status']}")
+
+            # Poll for completion
+            status = client.get_job_status(result.task_id)
+
+            while status["status"] in ["queued", "processing"]:
+                print(f"Current status: {status['status']}")
+                time.sleep(2)  # Wait 2 seconds
+                status = client.get_job_status(result.task_id)
+
+            if status["status"] == "completed":
+                print("Workflow completed!")
+                print(f"Output: {status['output']}")
+                print(f"Duration: {status['metadata']['duration']}")
+            else:
+                print(f"Workflow failed: {status['error']}")
+
+    except Exception as error:
+        print(f"Error: {error}")
+
+execute_async()
+```
+
+### Rate Limiting and Retry
+
+Handle rate limits automatically with exponential backoff:
+
+```python
+import os
+from simstudio import SimStudioClient, SimStudioError
+
+client = SimStudioClient(api_key=os.getenv("SIM_API_KEY"))
+
+def execute_with_retry_handling():
+    try:
+        # Automatically retries on rate limit
+        result = client.execute_with_retry(
+            "workflow-id",
+            input_data={"message": "Process this"},
+            max_retries=5,
+            initial_delay=1.0,
+            max_delay=60.0,
+            backoff_multiplier=2.0
+        )
+
+        print(f"Success: {result}")
+    except SimStudioError as error:
+        if error.code == "RATE_LIMIT_EXCEEDED":
+            print("Rate limit exceeded after all retries")
+
+            # Check rate limit info
+            rate_limit_info = client.get_rate_limit_info()
+            if rate_limit_info:
+                from datetime import datetime
+                reset_time = datetime.fromtimestamp(rate_limit_info.reset)
+                print(f"Rate limit resets at: {reset_time}")
+
+execute_with_retry_handling()
+```
+
+### Usage Monitoring
+
+Monitor your account usage and limits:
+
+```python
+import os
+from simstudio import SimStudioClient
+
+client = SimStudioClient(api_key=os.getenv("SIM_API_KEY"))
+
+def check_usage():
+    try:
+        limits = client.get_usage_limits()
+
+        print("=== Rate Limits ===")
+        print("Sync requests:")
+        print(f"  Limit: {limits.rate_limit['sync']['limit']}")
+        print(f"  Remaining: {limits.rate_limit['sync']['remaining']}")
+        print(f"  Resets at: {limits.rate_limit['sync']['resetAt']}")
+        print(f"  Is limited: {limits.rate_limit['sync']['isLimited']}")
+
+        print("\nAsync requests:")
+        print(f"  Limit: {limits.rate_limit['async']['limit']}")
+        print(f"  Remaining: {limits.rate_limit['async']['remaining']}")
+        print(f"  Resets at: {limits.rate_limit['async']['resetAt']}")
+        print(f"  Is limited: {limits.rate_limit['async']['isLimited']}")
+
+        print("\n=== Usage ===")
+        print(f"Current period cost: ${limits.usage['currentPeriodCost']:.2f}")
+        print(f"Limit: ${limits.usage['limit']:.2f}")
+        print(f"Plan: {limits.usage['plan']}")
+
+        percent_used = (limits.usage['currentPeriodCost'] / limits.usage['limit']) * 100
+        print(f"Usage: {percent_used:.1f}%")
+
+        if percent_used > 80:
+            print("⚠️  Warning: You are approaching your usage limit!")
+
+    except Exception as error:
+        print(f"Error checking usage: {error}")
+
+check_usage()
+```
+
+### Streaming Workflow Execution
+
+Execute workflows with real-time streaming responses:
+
+```python
+from simstudio import SimStudioClient
+import os
+
+client = SimStudioClient(api_key=os.getenv("SIM_API_KEY"))
+
+def execute_with_streaming():
+    """Execute workflow with streaming enabled."""
+    try:
+        # Enable streaming for specific block outputs
+        result = client.execute_workflow(
+            "workflow-id",
+            input_data={"message": "Count to five"},
+            stream=True,
+            selected_outputs=["agent1.content"]  # Use blockName.attribute format
+        )
+
+        print("Workflow result:", result)
+    except Exception as error:
+        print("Error:", error)
+
+execute_with_streaming()
+```
+
+The streaming response follows the Server-Sent Events (SSE) format:
+
+```
+data: {"blockId":"7b7735b9-19e5-4bd6-818b-46aae2596e9f","chunk":"One"}
+
+data: {"blockId":"7b7735b9-19e5-4bd6-818b-46aae2596e9f","chunk":", two"}
+
+data: {"event":"done","success":true,"output":{},"metadata":{"duration":610}}
+
+data: [DONE]
+```
+
+**Flask Streaming Example:**
+
+```python
+from flask import Flask, Response, stream_with_context
+import requests
+import json
+import os
+
+app = Flask(__name__)
+
+@app.route('/stream-workflow')
+def stream_workflow():
+    """Stream workflow execution to the client."""
+
+    def generate():
+        response = requests.post(
+            'https://sim.ai/api/workflows/WORKFLOW_ID/execute',
+            headers={
+                'Content-Type': 'application/json',
+                'X-API-Key': os.getenv('SIM_API_KEY')
+            },
+            json={
+                'message': 'Generate a story',
+                'stream': True,
+                'selectedOutputs': ['agent1.content']
+            },
+            stream=True
+        )
+
+        for line in response.iter_lines():
+            if line:
+                decoded_line = line.decode('utf-8')
+                if decoded_line.startswith('data: '):
+                    data = decoded_line[6:]  # Remove 'data: ' prefix
+
+                    if data == '[DONE]':
+                        break
+
+                    try:
+                        parsed = json.loads(data)
+                        if 'chunk' in parsed:
+                            yield f"data: {json.dumps(parsed)}\n\n"
+                        elif parsed.get('event') == 'done':
+                            yield f"data: {json.dumps(parsed)}\n\n"
+                            print("Execution complete:", parsed.get('metadata'))
+                    except json.JSONDecodeError:
+                        pass
+
+    return Response(
+        stream_with_context(generate()),
+        mimetype='text/event-stream'
+    )
+
+if __name__ == '__main__':
+    app.run(debug=True)
+```
+
+### Environment Configuration
+
+Configure the client using environment variables:
+
+<Tabs items={['Development', 'Production']}>
+  <Tab value="Development">
+    ```python
+    import os
+    from simstudio import SimStudioClient
+
+    # Development configuration
+    client = SimStudioClient(
+        api_key=os.getenv("SIM_API_KEY")
+        base_url=os.getenv("SIM_BASE_URL", "https://sim.ai")
+    )
+    ```
+  </Tab>
+  <Tab value="Production">
+    ```python
+    import os
+    from simstudio import SimStudioClient
+
+    # Production configuration with error handling
+    api_key = os.getenv("SIM_API_KEY")
+    if not api_key:
+        raise ValueError("SIM_API_KEY environment variable is required")
+
+    client = SimStudioClient(
+        api_key=api_key,
+        base_url=os.getenv("SIM_BASE_URL", "https://sim.ai")
+    )
+    ```
+  </Tab>
+</Tabs>
+
+## Getting Your API Key
+
+<Steps>
+  <Step title="Log in to Sim">
+    Navigate to [Sim](https://sim.ai) and log in to your account.
+  </Step>
+  <Step title="Open your workflow">
+    Navigate to the workflow you want to execute programmatically.
+  </Step>
+  <Step title="Deploy your workflow">
+    Click on "Deploy" to deploy your workflow if it hasn't been deployed yet.
+  </Step>
+  <Step title="Create or select an API key">
+    During the deployment process, select or create an API key.
+  </Step>
+  <Step title="Copy the API key">
+    Copy the API key to use in your Python application.
+  </Step>
+</Steps>
+
+## Requirements
+
+- Python 3.8+
+- requests >= 2.25.0
+
+## License
+
+Apache-2.0 

apps/docs/content/docs/en/blocks/agent.mdx

@@ -5,6 +5,7 @@ title: Agent
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
 import { Image } from '@/components/ui/image'
+import { FAQ } from '@/components/ui/faq'
 
 The Agent block connects your workflow to Large Language Models (LLMs). It processes natural language inputs, calls external tools, and generates structured or unstructured outputs.
 
@@ -58,7 +59,7 @@ Controls response randomness and creativity:
 
 ### Max Output Tokens
 
-Controls the maximum length of the model's response. For Anthropic models, Sim uses reliable defaults: streaming executions use the model's full capacity (e.g. 64,000 tokens for Claude 4.5), while non-streaming executions default to 8,192 to avoid timeout issues. When using tools with Anthropic models, intermediate tool-calling requests use a capped limit of 8,192 tokens to avoid SDK timeout errors, regardless of your configured max tokens—the final streaming response uses your full configured limit. This only affects Anthropic's direct API; AWS Bedrock handles this automatically. For long-form content generation via API, explicitly set a higher value.
+Controls the maximum length of the model's response. Each model defaults to its full max output token limit (e.g., 64,000 tokens for Claude Sonnet 4.5). You can override this with a custom value using the Max Tokens setting. For Anthropic models, when non-streaming requests exceed the SDK's internal threshold, the provider automatically uses internal streaming to avoid timeouts.
 
 ### API Key
 
@@ -78,7 +79,7 @@ Extend agent capabilities with external integrations. Select from 60+ pre-built
 **Execution Modes:**
 - **Auto**: Model decides when to use tools based on context
 - **Required**: Tool must be called in every request
-- **None**: Tool available but not suggested to model
+- **None**: Tool is completely filtered out and not sent to the model — effectively disables the tool
 
 ### Response Format
 
@@ -113,7 +114,7 @@ After an agent completes, you can access its outputs:
 
 - **`<agent.content>`**: The agent's response text or structured data
 - **`<agent.tokens>`**: Token usage statistics (prompt, completion, total)
-- **`<agent.tool_calls>`**: Details of any tools the agent used during execution
+- **`<agent.toolCalls>`**: Details of any tools the agent used during execution
 - **`<agent.cost>`**: Estimated cost of the API call (if available)
 
 ## Advanced Features
@@ -131,8 +132,9 @@ See the [`Memory`](/tools/memory) block reference for details.
 ## Outputs
 
 - **`<agent.content>`**: Agent's response text
+- **`<agent.model>`**: Model identifier used for the request
 - **`<agent.tokens>`**: Token usage statistics
-- **`<agent.tool_calls>`**: Tool execution details
+- **`<agent.toolCalls>`**: Tool execution details
 - **`<agent.cost>`**: Estimated API call cost
 
 ## Example Use Cases
@@ -157,3 +159,13 @@ Input → Agent (Google Search, Notion) → Function (Compile Report)
 - **Be specific in system prompts**: Clearly define the agent's role, tone, and limitations. The more specific your instructions are, the better the agent will be able to fulfill its intended purpose.
 - **Choose the right temperature setting**: Use lower temperature settings (0-0.3) when accuracy is important, or increase temperature (0.7-2.0) for more creative or varied responses
 - **Leverage tools effectively**: Integrate tools that complement the agent's purpose and enhance its capabilities. Be selective about which tools you provide to avoid overwhelming the agent. For tasks with little overlap, use another Agent block for the best results.
+
+<FAQ items={[
+  { question: "What LLM providers does the Agent block support?", answer: "The Agent block supports OpenAI, Anthropic, Google (Gemini), xAI (Grok), DeepSeek, Groq, Cerebras, Azure OpenAI, Azure Anthropic, Google Vertex AI, AWS Bedrock, OpenRouter, and local models via Ollama or VLLM. You can type or select any supported model from the model combobox." },
+  { question: "What are the memory options for the Agent block?", answer: "The Agent block has four memory modes: None (no memory, each request is independent), Conversation (full conversation history keyed by a conversation ID), Sliding Window by messages (keeps the N most recent messages), and Sliding Window by tokens (keeps messages up to a token limit). Memory requires a conversation ID to persist across runs." },
+  { question: "What is the difference between the tool execution modes (Auto, Required, None)?", answer: "In Auto mode, the model decides when to call a tool based on context. In Required mode, the model must call the tool on every request. In None mode, the tool is completely filtered out and never sent to the model — it effectively disables that tool without removing it from the configuration." },
+  { question: "How does the Response Format work?", answer: "Response Format enforces structured output by providing a JSON Schema. When set, the model's response is constrained to match the schema exactly. Fields from the structured response can be accessed directly by downstream blocks using <agent.fieldName> syntax. If no response format is set, the agent returns its standard outputs: content, model, tokens, and toolCalls." },
+  { question: "What does the Reasoning Effort / Thinking Level setting do?", answer: "These are advanced settings that appear only for models that support extended reasoning. Reasoning Effort (for OpenAI o-series and GPT-5 models) and Thinking Level (for Anthropic Claude and Gemini models with thinking) control how much compute the model spends reasoning before responding. Higher levels produce more thorough answers but cost more tokens and take longer." },
+  { question: "How does max output tokens work with Anthropic models specifically?", answer: "The Agent block uses each Anthropic model's full max output token limit by default (e.g., 64,000 for Claude Sonnet 4.5). You can override this with the Max Tokens setting. For non-streaming requests that exceed the SDK's internal threshold, the provider automatically uses internal streaming to avoid timeouts." },
+  { question: "Can I use the Agent block with a custom or self-hosted model?", answer: "Yes. You can use any Ollama or VLLM-compatible model by typing the model name directly into the model combobox. This lets you connect to locally hosted or custom-deployed models as long as they expose a compatible API endpoint." },
+]} />

apps/docs/content/docs/en/blocks/api.mdx

@@ -5,6 +5,7 @@ title: API
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
 import { Image } from '@/components/ui/image'
+import { FAQ } from '@/components/ui/faq'
 
 The API block connects your workflow to external services through HTTP requests. Supports GET, POST, PUT, DELETE, and PATCH methods for interacting with REST APIs.
 
@@ -79,7 +80,6 @@ After an API request completes, you can access its outputs:
 - **`<api.data>`**: The response body data from the API
 - **`<api.status>`**: HTTP status code (200, 404, 500, etc.)
 - **`<api.headers>`**: Response headers from the server
-- **`<api.error>`**: Error details if the request failed
 
 ## Advanced Features
 
@@ -95,11 +95,17 @@ const apiUrl = `https://api.example.com/users/${userId}/profile`;
 
 ### Request Retries
 
-The API block automatically handles:
-- Network timeouts with exponential backoff
-- Rate limit responses (429 status codes)
-- Server errors (5xx status codes) with retry logic
-- Connection failures with reconnection attempts
+The API block supports **configurable retries** (see the block’s **Advanced** settings):
+
+- **Retries**: Number of retry attempts (additional tries after the first request)
+- **Retry delay (ms)**: Initial delay before retrying (uses exponential backoff)
+- **Max retry delay (ms)**: Maximum delay between retries
+- **Retry non-idempotent methods**: Allow retries for **POST/PATCH** (may create duplicate requests)
+
+Retries are attempted for:
+
+- Network/connection failures and timeouts (with exponential backoff)
+- Rate limits (**429**) and server errors (**5xx**)
 
 ### Response Validation
 
@@ -121,7 +127,6 @@ if (<api.status> === 200) {
 - **`<api.data>`**: Response body data from the API
 - **`<api.status>`**: HTTP status code
 - **`<api.headers>`**: Response headers
-- **`<api.error>`**: Error details if request failed
 
 ## Example Use Cases
 
@@ -141,3 +146,12 @@ Function (Validate) → API (Stripe) → Condition (Success) → Supabase (Updat
 - **Handle errors gracefully**: Connect error handling logic for failed requests
 - **Validate responses**: Check status codes and response formats before processing data
 - **Respect rate limits**: Be mindful of API rate limits and implement appropriate throttling
+
+<FAQ items={[
+  { question: "What is the default request timeout?", answer: "The default timeout is 300,000 milliseconds (5 minutes). You can configure it up to a maximum of 600,000 milliseconds (10 minutes) in the block's Advanced settings." },
+  { question: "Which HTTP errors trigger automatic retries?", answer: "Retries are attempted for network/connection failures, timeouts, rate limit responses (HTTP 429), and server errors (5xx). Client errors like 400 or 404 are not retried." },
+  { question: "How does retry backoff work?", answer: "Retries use exponential backoff starting from the configured retry delay (default 500ms). Each subsequent retry doubles the delay, up to the maximum retry delay (default 30,000ms)." },
+  { question: "Are POST and PATCH requests retried by default?", answer: "No. POST and PATCH are non-idempotent methods, so retries are disabled for them by default to avoid creating duplicate resources. You can enable retries for these methods with the 'Retry non-idempotent methods' toggle in Advanced settings, but be aware this may cause duplicate requests." },
+  { question: "What headers are included automatically?", answer: "Standard headers such as User-Agent, Accept, and Cache-Control are added automatically. Any custom headers you configure will be merged with these defaults, and your custom values will override automatic headers with the same name." },
+  { question: "Can I send form data or file uploads?", answer: "The API block primarily sends JSON request bodies through the UI. The underlying HTTP tool also supports form data natively — if you pass form data parameters, it will construct a proper multipart/form-data request automatically. For most use cases, the JSON body field in the block UI is sufficient." },
+]} />

apps/docs/content/docs/en/blocks/condition.mdx

@@ -5,6 +5,7 @@ title: Condition
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
 import { Image } from '@/components/ui/image'
+import { FAQ } from '@/components/ui/faq'
 
 The Condition block branches workflow execution based on boolean expressions. Evaluate conditions using previous block outputs and route to different paths without requiring an LLM.
 
@@ -60,10 +61,9 @@ Conditions use JavaScript syntax and can reference input values from previous bl
 
 After a condition evaluates, you can access its outputs:
 
-- **`<condition.result>`**: Boolean result of the condition evaluation
-- **`<condition.matched_condition>`**: ID of the condition that was matched
-- **`<condition.content>`**: Description of the evaluation result
-- **`<condition.path>`**: Details of the chosen routing destination
+- **`<condition.conditionResult>`**: Boolean result of the condition evaluation
+- **`<condition.selectedOption>`**: ID of the condition that was matched
+- **`<condition.selectedPath>`**: Details of the chosen routing destination
 
 ## Advanced Features
 
@@ -102,18 +102,13 @@ true
 
 ### Error Handling
 
-Conditions automatically handle:
-- Undefined or null values with safe evaluation
-- Type mismatches with appropriate fallbacks
-- Invalid expressions with error logging
-- Missing variables with default values
+If a condition expression references an undefined variable or throws a runtime error, the block will throw an error and the execution will fail (or follow the error path if one is connected). Use optional chaining (`?.`) or explicit null checks in your expressions to handle missing values safely.
 
 ## Outputs
 
-- **`<condition.result>`**: Boolean result of the evaluation
-- **`<condition.matched_condition>`**: ID of the matched condition
-- **`<condition.content>`**: Description of the evaluation result
-- **`<condition.path>`**: Details of the chosen routing destination
+- **`<condition.conditionResult>`**: Boolean result of the evaluation
+- **`<condition.selectedOption>`**: ID of the matched condition
+- **`<condition.selectedPath>`**: Details of the chosen routing destination
 
 ## Example Use Cases
 
@@ -139,3 +134,11 @@ Function (Process) → Condition (account_type === 'enterprise') → Advanced or
 - **Keep expressions simple**: Use clear, straightforward boolean expressions for better readability and easier debugging
 - **Document your conditions**: Add descriptions to explain the purpose of each condition for better team collaboration and maintenance
 - **Test edge cases**: Verify conditions handle boundary values correctly by testing with values at the edges of your condition ranges
+
+<FAQ items={[
+  { question: "Does the Condition block use an LLM?", answer: "No. The Condition block evaluates boolean expressions using JavaScript syntax directly — it does not call any AI model. This makes it fast, deterministic, and free of API costs. If you need AI-powered routing decisions, use the Router block instead." },
+  { question: "What happens if no condition matches?", answer: "If none of your defined conditions evaluate to true, the workflow follows the else branch. If the else branch is not connected to any downstream block, that workflow path ends gracefully without an error. Add a fallback condition of simply true as the last condition to guarantee a match." },
+  { question: "In what order are conditions evaluated?", answer: "Conditions are evaluated from top to bottom in the order they are defined. The first condition that evaluates to true determines the execution path. Subsequent conditions are not evaluated after a match is found, so place more specific conditions before general ones." },
+  { question: "What JavaScript features can I use in condition expressions?", answer: "You can use standard JavaScript operators and methods including comparison operators (===, !==, >, <), logical operators (&&, ||, !), string methods (.includes(), .endsWith(), .toLowerCase()), array methods (.includes(), .length), mathematical operations, and Date comparisons. Reference block outputs using <blockName.output> syntax." },
+  { question: "How does the Condition block handle null or undefined values?", answer: "If a condition expression references an undefined variable or throws a runtime error, the Condition block will throw an error and the execution will fail (or follow the error path if one is connected). Use optional chaining (?.) or explicit null checks in your expressions to handle missing values safely." },
+]} />

apps/docs/content/docs/en/blocks/credential.mdx

@@ -0,0 +1,150 @@
+---
+title: Credential
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+import { Image } from '@/components/ui/image'
+import { FAQ } from '@/components/ui/faq'
+
+The Credential block has two operations: **Select Credential** picks a single OAuth credential and outputs its ID reference for downstream blocks; **List Credentials** returns all OAuth credentials in the workspace (optionally filtered by provider) as an array for iteration.
+
+<div className="flex justify-center">
+  <Image
+    src="/static/blocks/credential.png"
+    alt="Credential Block"
+    width={400}
+    height={300}
+    className="my-6"
+  />
+</div>
+
+<Callout>
+  The Credential block outputs credential **ID references**, not secrets. Downstream blocks receive the ID and resolve the actual OAuth token securely during their own execution.
+</Callout>
+
+## Configuration Options
+
+### Operation
+
+| Value | Description |
+|---|---|
+| **Select Credential** | Pick one OAuth credential and output its reference — use this to wire a single credential into downstream blocks |
+| **List Credentials** | Return all OAuth credentials in the workspace as an array — use this with a ForEach loop |
+
+### Credential (Select operation)
+
+Select an OAuth credential from your workspace. The dropdown shows all connected OAuth accounts (Google, GitHub, Slack, etc.).
+
+In advanced mode, paste a credential ID directly. You can copy a credential ID from your workspace's Credentials settings page.
+
+### Provider (List operation)
+
+Filter the returned OAuth credentials by provider. Select one or more providers from the dropdown — only providers you have credentials for will appear. Leave empty to return all OAuth credentials.
+
+| Example | Returns |
+|---|---|
+| Gmail | Gmail credentials only |
+| Slack | Slack credentials only |
+| Gmail + Slack | Gmail and Slack credentials |
+
+## Outputs
+
+<Tabs items={['Select Credential', 'List Credentials']}>
+  <Tab>
+    | Output | Type | Description |
+    |---|---|---|
+    | `credentialId` | `string` | The credential ID — pipe this into other blocks' credential fields |
+    | `displayName` | `string` | Human-readable name (e.g. "waleed@company.com") |
+    | `providerId` | `string` | OAuth provider ID (e.g. `google-email`, `slack`) |
+  </Tab>
+  <Tab>
+    | Output | Type | Description |
+    |---|---|---|
+    | `credentials` | `json` | Array of OAuth credential objects (see shape below) |
+    | `count` | `number` | Number of credentials returned |
+
+    Each object in the `credentials` array:
+
+    | Field | Type | Description |
+    |---|---|---|
+    | `credentialId` | `string` | The credential ID |
+    | `displayName` | `string` | Human-readable name |
+    | `providerId` | `string` | OAuth provider ID |
+  </Tab>
+</Tabs>
+
+## Example Use Cases
+
+**Shared credential across multiple blocks** — Define once, use everywhere
+```
+Credential (Select, Google) → Gmail (Send) & Google Drive (Upload) & Google Calendar (Create)
+```
+
+**Multi-account workflows** — Route to different credentials based on logic
+```
+Agent (Determine account) → Condition → Credential A or Credential B → Slack (Post)
+```
+
+**Iterate over all Gmail accounts**
+```
+Credential (List, Provider: Gmail) → ForEach Loop → Gmail (Send) using <loop.currentItem.credentialId>
+```
+
+<div className="flex justify-center">
+  <Image
+    src="/static/blocks/credential-loop.png"
+    alt="Credential List wired into a ForEach Loop"
+    width={900}
+    height={400}
+    className="my-6"
+  />
+</div>
+
+## How to wire a Credential block
+
+### Select Credential
+
+1. Drop a **Credential** block and select your OAuth credential from the picker
+2. In the downstream block, switch to **advanced mode** on its credential field
+3. Enter `<credentialBlockName.credentialId>` as the value
+
+<Tabs items={['Gmail', 'Slack']}>
+  <Tab>
+    In the Gmail block's credential field (advanced mode):
+    ```
+    <myCredential.credentialId>
+    ```
+  </Tab>
+  <Tab>
+    In the Slack block's credential field (advanced mode):
+    ```
+    <myCredential.credentialId>
+    ```
+  </Tab>
+</Tabs>
+
+### List Credentials
+
+1. Drop a **Credential** block, set Operation to **List Credentials**
+2. Optionally select one or more **Providers** to narrow results (only your connected providers appear)
+3. Wire `<credentialBlockName.credentials>` into a **ForEach Loop** as the items source
+4. Inside the loop, reference `<loop.currentItem.credentialId>` in downstream blocks' credential fields
+
+## Best Practices
+
+- **Define once, reference many times**: When five blocks use the same Google account, use one Credential block and wire all five to `<credential.credentialId>` instead of selecting the account five times
+- **Outputs are safe to log**: The `credentialId` output is a UUID reference, not a secret. It is safe to inspect in execution logs
+- **Use for environment switching**: Pair with a Condition block to route to a production or staging OAuth credential based on a workflow variable
+- **Advanced mode is required**: Downstream blocks must be in advanced mode on their credential field to accept a dynamic reference
+- **Use List + ForEach for fan-out**: When you need to run the same action across all accounts of a provider, List Credentials feeds naturally into a ForEach loop
+- **Narrow by provider**: Use the Provider multiselect to filter to specific services — only providers you have credentials for are shown
+
+<FAQ items={[
+  { question: "Does the Credential block expose my secret or token?", answer: "No. The block outputs a credential ID (a UUID), not the actual OAuth token. Downstream blocks receive the ID and resolve the token securely in their own execution context. Secrets never appear in workflow state, logs, or the canvas." },
+  { question: "What credential types does it support?", answer: "OAuth connected accounts only (Google, GitHub, Slack, etc.). Environment variables and service accounts cannot be resolved by ID in downstream blocks, so they are not supported." },
+  { question: "How is Select different from just copying a credential ID into advanced mode?", answer: "Functionally identical — both pass the same credential ID to the downstream block. The Credential block adds value when you need to use one credential in many blocks (change it once), or when you want to select between credentials dynamically using a Condition block." },
+  { question: "Can I list all OAuth credentials in my workspace?", answer: "Yes. Set the Operation to 'List Credentials'. Optionally filter by provider using the Provider multiselect. Wire the credentials output into a ForEach loop to process each credential individually." },
+  { question: "Can I use a Credential block output in a Function block?", answer: "Yes. Reference <credential.credentialId> in your Function block's code. Note that the function will receive the raw UUID string — if you need the resolved token, the downstream block must handle the resolution (as integration blocks do). The Function block does not automatically resolve credential IDs." },
+  { question: "What happens if the credential is deleted?", answer: "The Select operation will throw an error at execution time: 'Credential not found'. The List operation will simply omit the deleted credential from the results. Update the Credential block to select a valid credential before re-running." },
+]} />

apps/docs/content/docs/en/blocks/evaluator.mdx

@@ -5,6 +5,7 @@ title: Evaluator
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
 import { Image } from '@/components/ui/image'
+import { FAQ } from '@/components/ui/faq'
 
 The Evaluator block uses AI to score and assess content quality against custom metrics. Perfect for quality control, A/B testing, and ensuring AI outputs meet specific standards.
 
@@ -49,12 +50,12 @@ The content to be evaluated. This can be:
 Choose an AI model to perform the evaluation:
 
 - **OpenAI**: GPT-4o, o1, o3, o4-mini, gpt-4.1
-- **Anthropic**: Claude 3.7 Sonnet
+- **Anthropic**: Claude Sonnet 4.5
 - **Google**: Gemini 2.5 Pro, Gemini 2.0 Flash
 - **Other Providers**: Groq, Cerebras, xAI, DeepSeek
 - **Local Models**: Ollama or VLLM compatible models
 
-Use models with strong reasoning capabilities like GPT-4o or Claude 3.7 Sonnet for best results.
+Use models with strong reasoning capabilities like GPT-4o or Claude Sonnet 4.5 for best results.
 
 ### API Key
 
@@ -91,3 +92,12 @@ Agent (Support Response) → Evaluator (Score) → Function (Log) → Condition
 - **Connect with Agent blocks**: Use Evaluator blocks to assess Agent block outputs and create feedback loops
 - **Use consistent metrics**: For comparative analysis, maintain consistent metrics across similar evaluations
 - **Combine multiple metrics**: Use several metrics to get a comprehensive evaluation
+
+<FAQ items={[
+  { question: "What format does the Evaluator return scores in?", answer: "The Evaluator returns a JSON object where each key is the lowercase version of your metric name and the value is a numeric score within the range you defined. For example, a metric named 'Accuracy' with range 1-5 would appear as { \"accuracy\": 4 } in the output." },
+  { question: "Which models work best for evaluation?", answer: "Models with strong reasoning capabilities produce the most consistent evaluations. GPT-4o and Claude Sonnet are recommended. The default model is Claude Sonnet 4.5." },
+  { question: "Can I evaluate non-text content?", answer: "The content field accepts any string input. If you pass JSON or structured data, the Evaluator will automatically detect and format it before evaluation. However, the evaluation is text-based — it cannot directly evaluate images or audio." },
+  { question: "What happens if a metric name is invalid or incomplete?", answer: "Metrics missing a name or range are automatically filtered out. The Evaluator only scores metrics that have both a valid name and a defined min/max range." },
+  { question: "Does the Evaluator use structured output?", answer: "Yes. The Evaluator generates a JSON Schema response format based on your metrics and enforces strict mode, so the LLM is constrained to return only the expected metric scores as numbers — no extra text or explanations." },
+  { question: "How are evaluation costs calculated?", answer: "Costs are based on the token usage of the underlying LLM call. The Evaluator outputs include token counts (prompt, completion, total) and cost breakdown (input, output, total) so you can track spending per evaluation." },
+]} />

apps/docs/content/docs/en/blocks/function.mdx

@@ -3,6 +3,7 @@ title: Function
 ---
 
 import { Image } from '@/components/ui/image'
+import { FAQ } from '@/components/ui/faq'
 
 The Function block executes custom JavaScript or TypeScript code in your workflows. Transform data, perform calculations, or implement custom logic.
 
@@ -71,3 +72,12 @@ return {
 - **Test edge cases**: Ensure your code handles unusual inputs, null values, and boundary conditions correctly
 - **Optimize for performance**: Be mindful of computational complexity and memory usage for large datasets
 - **Use console.log() for debugging**: Leverage stdout output to debug and monitor function execution
+
+<FAQ items={[
+  { question: "What languages does the Function block support?", answer: "The Function block supports JavaScript and Python. JavaScript is the default. Python support requires the E2B feature to be enabled, as Python code always runs in a secure E2B sandbox environment." },
+  { question: "When does code run locally vs. in a sandbox?", answer: "JavaScript code without external imports runs in a local isolated VM for fast execution. JavaScript code that uses import or require statements requires E2B and runs in a secure sandbox. Python code always runs in the E2B sandbox regardless of whether it has imports." },
+  { question: "How do I reference outputs from other blocks inside my code?", answer: "Use the angle bracket syntax directly in your code, like <agent.content> or <api.data>. Do not wrap these references in quotes — the system replaces them with actual values before execution. For environment variables, use double curly braces: {{API_KEY}}." },
+  { question: "What does the Function block return?", answer: "The Function block has two outputs: result (the return value of your code, accessed via <function.result>) and stdout (anything logged with console.log(), accessed via <function.stdout>). Make sure your code includes a return statement if you need to pass data to downstream blocks." },
+  { question: "Can I make HTTP requests from a Function block?", answer: "Yes. The fetch() API is available in the JavaScript execution environment. You can use async/await with fetch to call external APIs. However, you cannot use libraries like axios or request — only the built-in fetch is supported. Your code runs inside an async context automatically, so you can use await directly." },
+  { question: "Is there a timeout for Function block execution?", answer: "Yes. Function blocks have a configurable execution timeout. If your code exceeds the timeout, the execution is terminated and the block reports an error. Keep this in mind when making external API calls or processing large datasets." },
+]} />

apps/docs/content/docs/en/blocks/guardrails.mdx

@@ -5,6 +5,7 @@ title: Guardrails
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Image } from '@/components/ui/image'
 import { Video } from '@/components/ui/video'
+import { FAQ } from '@/components/ui/faq'
 
 The Guardrails block validates and protects your AI workflows by checking content against multiple validation types. Ensure data quality, prevent hallucinations, detect PII, and enforce format requirements before content moves through your workflow.
 
@@ -66,8 +67,8 @@ Uses Retrieval-Augmented Generation (RAG) with LLM scoring to detect when AI-gen
 - **Knowledge Base**: Select from your existing knowledge bases
 - **Model**: Choose LLM for scoring (requires strong reasoning - GPT-4o, Claude 3.7 Sonnet recommended)
 - **API Key**: Authentication for selected LLM provider (auto-hidden for hosted/Ollama or VLLM compatible models)
-- **Confidence Threshold**: Minimum score to pass (0-10, default: 3)
-- **Top K** (Advanced): Number of knowledge base chunks to retrieve (default: 10)
+- **Confidence**: Minimum score to pass (0-10, default: 3)
+- **Top K** (Advanced): Number of knowledge base chunks to retrieve (default: 5)
 
 **Output:**
 - `passed`: `true` if confidence score ≥ threshold
@@ -83,7 +84,7 @@ Uses Retrieval-Augmented Generation (RAG) with LLM scoring to detect when AI-gen
 
 ### PII Detection
 
-Detects personally identifiable information using Microsoft Presidio. Supports 40+ entity types across multiple countries and languages.
+Detects personally identifiable information using Microsoft Presidio. Supports over 30 entity types across multiple countries and languages.
 
 <div className="flex justify-center">
   <Image
@@ -98,7 +99,7 @@ Detects personally identifiable information using Microsoft Presidio. Supports 4
 **How It Works:**
 1. Pass content to validate (e.g., `<agent1.content>`)
 2. Select PII types to detect using the modal selector
-3. Choose detection mode (Detect or Mask)
+3. Choose the action (Block Request or Mask PII)
 4. Content is scanned for matching PII entities
 5. Returns detection results and optionally masked text
 
@@ -109,17 +110,17 @@ Detects personally identifiable information using Microsoft Presidio. Supports 4
 **Configuration:**
 - **PII Types to Detect**: Select from grouped categories via modal selector
   - **Common**: Person name, Email, Phone, Credit card, IP address, etc.
-  - **USA**: SSN, Driver's license, Passport, etc.
+  - **USA**: SSN, Driver's license, Passport, Bank account number, ITIN
   - **UK**: NHS number, National insurance number
-  - **Spain**: NIF, NIE, CIF
-  - **Italy**: Fiscal code, Driver's license, VAT code
-  - **Poland**: PESEL, NIP, REGON
-  - **Singapore**: NRIC/FIN, UEN
+  - **Spain**: NIF, NIE
+  - **Italy**: Fiscal code, Driver's license, Identity card, Passport
+  - **Poland**: PESEL
+  - **Singapore**: NRIC/FIN
   - **Australia**: ABN, ACN, TFN, Medicare
-  - **India**: Aadhaar, PAN, Passport, Voter number
-- **Mode**: 
-  - **Detect**: Only identify PII (default)
-  - **Mask**: Replace detected PII with masked values
+  - **India**: Aadhaar, PAN, Vehicle registration, Voter number, Passport
+- **Action**:
+  - **Block Request**: Only identify PII (default)
+  - **Mask PII**: Replace detected PII with masked values
 - **Language**: Detection language (default: English)
 
 **Output:**
@@ -131,7 +132,7 @@ Detects personally identifiable information using Microsoft Presidio. Supports 4
 **Use Cases:**
 - Block content containing sensitive personal information
 - Mask PII before logging or storing data
-- Compliance with GDPR, HIPAA, and other privacy regulations
+- Compliance with GDPR and other privacy regulations
 - Sanitize user inputs before processing
 
 ## Configuration
@@ -140,7 +141,7 @@ Detects personally identifiable information using Microsoft Presidio. Supports 4
 
 The input content to validate. This typically comes from:
 - Agent block outputs: `<agent.content>`
-- Function block results: `<function.output>`
+- Function block results: `<function.result>`
 - API responses: `<api.output>`
 - Any other block output
 
@@ -203,3 +204,13 @@ Input → Guardrails (Detect PII) → Condition (No PII) → Process or Reject
   Guardrails validation happens synchronously in your workflow. For hallucination detection, choose faster models (like GPT-4o-mini) if latency is critical.
 </Callout>
 
+<FAQ items={[
+  { question: "Can I run multiple validation types on the same content?", answer: "Each Guardrails block performs one validation type at a time. To apply multiple validations, chain several Guardrails blocks in sequence — for example, first validate JSON format, then check for PII." },
+  { question: "What does the hallucination confidence score mean?", answer: "The score ranges from 0 to 10. A score of 0 means the content is completely ungrounded (full hallucination), and 10 means it is fully supported by the knowledge base. Validation passes when the score meets or exceeds your configured threshold (default: 3)." },
+  { question: "How many knowledge base chunks are retrieved for hallucination detection?", answer: "By default, 5 chunks are retrieved. You can adjust this up to 20 in the Advanced settings using the 'Number of Chunks to Retrieve' slider. More chunks provide broader context but increase latency and token usage." },
+  { question: "What PII detection engine is used?", answer: "PII detection is powered by Microsoft Presidio. It supports over 30 entity types across multiple countries including the US, UK, Spain, Italy, Poland, Singapore, Australia, and India." },
+  { question: "What is the difference between Block and Mask modes for PII?", answer: "Block mode fails the validation (passed = false) if any selected PII types are detected. Mask mode also detects PII but replaces it with masked values in the output, making the content safe to use downstream. Both modes return the list of detected entities." },
+  { question: "Which languages does PII detection support?", answer: "PII detection supports English, Spanish, Italian, Polish, and Finnish. The language setting affects the NLP models used for entity recognition, so selecting the correct language improves detection accuracy." },
+  { question: "Does JSON validation check schema structure or just syntax?", answer: "JSON validation only checks that the content is syntactically valid JSON (i.e., it can be parsed without errors). It does not validate against a specific schema. For schema validation, use a Function block after the Guardrails check." },
+]} />
+

apps/docs/content/docs/en/blocks/human-in-the-loop.mdx

@@ -6,6 +6,7 @@ import { Callout } from 'fumadocs-ui/components/callout'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
 import { Image } from '@/components/ui/image'
 import { Video } from '@/components/ui/video'
+import { FAQ } from '@/components/ui/faq'
 
 The Human in the Loop block pauses workflow execution and waits for human intervention before continuing. Use it to add approval gates, collect feedback, or gather additional input at critical decision points.
 
@@ -33,7 +34,7 @@ When execution reaches this block, the workflow pauses indefinitely until a huma
 
 ## Configuration Options
 
-### Paused Output
+### Display Data
 
 Defines what data is displayed to the approver. This is the context shown in the approval portal to help them make an informed decision.
 
@@ -60,7 +61,7 @@ Configures how approvers are alerted when approval is needed. Supported channels
 
 Include the approval URL (`<blockId.url>`) in your notification messages so approvers can access the portal.
 
-### Resume Input
+### Resume Form
 
 Defines the fields approvers fill in when responding. This data becomes available to downstream blocks after the workflow resumes.
 
@@ -136,8 +137,12 @@ Agent (Generate) → Human in the Loop (QA) → Gmail (Send)
 
 ## Block Outputs
 
-**`url`** - Unique URL for the approval portal  
-**`resumeInput.*`** - All fields defined in Resume Input become available after the workflow resumes
+**`url`** - Unique URL for the approval portal
+**`resumeEndpoint`** - Resume API endpoint URL
+**`response`** - Display data shown to the approver (json)
+**`submission`** - Form submission data from the approver (json)
+**`submittedAt`** - ISO timestamp when the workflow was resumed
+**`resumeInput.*`** - All fields defined in Resume Form become available after the workflow resumes
 
 Access using `<blockId.resumeInput.fieldName>`.
 
@@ -176,3 +181,12 @@ The example below shows an approval portal as seen by an approver after the work
 - **[Condition](/blocks/condition)** - Branch based on approval decisions
 - **[Variables](/blocks/variables)** - Store approval history and metadata
 - **[Response](/blocks/response)** - Return workflow results to API callers
+
+<FAQ items={[
+  { question: "How long does the workflow stay paused?", answer: "The workflow pauses indefinitely until a human provides input through the approval portal, the REST API, or a webhook. There is no automatic timeout — it will wait until someone responds." },
+  { question: "What notification channels can I use to alert approvers?", answer: "You can configure notifications through Slack, Gmail, Microsoft Teams, SMS (via Twilio), or custom webhooks. Include the approval URL in your notification message so approvers can access the portal directly." },
+  { question: "How do I access the approver's input in downstream blocks?", answer: "Use the syntax <blockId.resumeInput.fieldName> to reference specific fields from the resume form. For example, if your block ID is 'approval1' and the form has an 'approved' field, use <approval1.resumeInput.approved>." },
+  { question: "Can I chain multiple Human in the Loop blocks for multi-stage approvals?", answer: "Yes. You can place multiple Human in the Loop blocks in sequence to create multi-stage approval workflows. Each block pauses independently and can have its own notification configuration and resume form fields." },
+  { question: "Can I resume the workflow programmatically without the portal?", answer: "Yes. Each block exposes a resume API endpoint that you can call with a POST request containing the form data as JSON. This lets you build custom approval UIs or integrate with existing systems like Jira or ServiceNow." },
+  { question: "What outputs are available after the workflow resumes?", answer: "The block outputs include the approval portal URL, the resume API endpoint URL, the display data shown to the approver, the form submission data, the raw resume input, and an ISO timestamp of when the workflow was resumed." },
+]} />

apps/docs/content/docs/en/blocks/index.mdx

@@ -7,6 +7,7 @@ import { Card, Cards } from 'fumadocs-ui/components/card'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
 import { Video } from '@/components/ui/video'
+import { FAQ } from '@/components/ui/faq'
 
 Blocks are the building components you connect together to create AI workflows. Think of them as specialized modules that each handle a specific task—from chatting with AI models to making API calls or processing data.
 
@@ -138,3 +139,12 @@ Each block type has specific configuration options:
     Pause workflow execution for specified time delays
   </Card>
 </Cards>
+
+<FAQ items={[
+  { question: "How many block types are available in Sim?", answer: "Sim has over 200 blocks in its registry, spanning core workflow blocks (Agent, Function, Condition, Router, etc.), integration blocks for third-party services (Gmail, Slack, GitHub, Notion, and many more), and trigger blocks that start workflows from external events like webhooks or schedules. Loop and parallel execution are built into the execution engine as container constructs on the canvas, rather than being standalone registry blocks." },
+  { question: "Can one block's output connect to multiple downstream blocks?", answer: "Yes. A single output port can connect to multiple input ports on different blocks. This lets you fan out data from one processing step to several parallel paths without needing to duplicate the block." },
+  { question: "What happens if a block in the middle of a workflow fails?", answer: "When a block encounters an error, the workflow stops executing along that path. Blocks that support error handling (like the Router) can route to an error path so you can handle failures gracefully instead of halting the entire workflow." },
+  { question: "What is the difference between Processing blocks and Logic blocks?", answer: "Processing blocks (Agent, Function, API) transform or generate data — they do the actual work. Logic blocks (Condition, Router, Evaluator) make decisions about which path the workflow should take based on the data, without modifying it themselves." },
+  { question: "Can I use blocks from different categories together in one workflow?", answer: "Absolutely. A typical workflow combines blocks from multiple categories. For example, you might use a trigger block to start the workflow, an Agent block to process input, a Condition block to branch logic, and an integration block like Gmail to send results." },
+  { question: "Are there container blocks that can hold other blocks inside them?", answer: "Yes. Loop and Parallel are execution engine constructs that appear as container regions on the canvas. You drag other blocks inside them. Loop containers execute their contained blocks repeatedly, while Parallel containers execute their contained blocks concurrently across multiple branches. Unlike registry blocks, these are handled directly by the execution engine." },
+]} />

apps/docs/content/docs/en/blocks/loop.mdx

@@ -5,6 +5,7 @@ title: Loop
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
 import { Image } from '@/components/ui/image'
+import { FAQ } from '@/components/ui/faq'
 
 The Loop block is a container that executes blocks repeatedly. Iterate over collections, repeat operations a fixed number of times, or continue while a condition is met.
 
@@ -184,13 +185,8 @@ Variables (i=0) → Loop (While i<10) → Agent (Process) → Variables (i++)
 
 ### Limitations
 
-<Callout type="warning">
-  Container blocks (Loops and Parallels) cannot be nested inside each other. This means:
-  - You cannot place a Loop block inside another Loop block
-  - You cannot place a Parallel block inside a Loop block
-  - You cannot place any container block inside another container block
-  
-  If you need multi-dimensional iteration, consider restructuring your workflow to use sequential loops or process data in stages.
+<Callout type="info">
+  Container blocks (Loops and Parallels) support nesting. You can place loops inside loops, parallels inside loops, and any combination of container blocks to build complex multi-dimensional workflows.
 </Callout>
 
 <Callout type="info">
@@ -250,3 +246,13 @@ Variables (i=0) → Loop (While i<10) → Agent (Process) → Variables (i++)
 - **Set reasonable limits**: Keep iteration counts reasonable to avoid long execution times
 - **Use ForEach for collections**: When processing arrays or objects, use ForEach instead of For loops
 - **Handle errors gracefully**: Consider adding error handling inside loops for robust workflows
+
+<FAQ items={[
+  { question: "What is the maximum number of iterations a loop can run?", answer: "For loops (fixed count) and ForEach loops are capped at 1,000 iterations/items (from executor constants). While loops and Do-While loops with a condition have no hard iteration cap — they run until the condition evaluates to false. Do-While loops without a condition fall back to a fixed iteration count, which is capped at 1,000. Always ensure your While/Do-While conditions will eventually become false to avoid infinite loops." },
+  { question: "Do loops execute iterations in parallel or sequentially?", answer: "Loops execute all iterations sequentially, one after another. If you need concurrent execution across items, use the Parallel block instead. You can also nest a Parallel block inside a Loop if you need both iteration patterns." },
+  { question: "How do I access the current item inside a ForEach loop?", answer: "Inside the loop, use <loop.currentItem> to get the current item being processed and <loop.index> for the zero-based iteration number. These references are only available to blocks placed inside the loop container — blocks outside the loop cannot access them." },
+  { question: "How do I access loop results after it finishes?", answer: "After the loop completes, reference the loop block by its normalized name (lowercase, no spaces) using <blockname.results>. This returns an array of all iteration results in order. For example, if your loop block is named 'Process Items', use <processitems.results>. Do not use <loop.> syntax outside the loop — that only works inside." },
+  { question: "Can I nest loops inside each other?", answer: "Yes. Container blocks (Loops and Parallels) fully support nesting. You can place loops inside loops, parallels inside loops, loops inside parallels, and any combination. Each nested container maintains its own scope and iteration context independently." },
+  { question: "What is the difference between a While loop and a Do-While loop?", answer: "A While loop checks its condition before each iteration, so it may execute zero times if the condition is false initially. A Do-While loop executes its body at least once, then checks the condition after each iteration to decide whether to continue. Use Do-While when you need guaranteed first execution." },
+  { question: "What happens if a ForEach loop receives an empty collection?", answer: "If the ForEach loop's collection is empty, the loop body is skipped entirely and the loop outputs an empty results array. The workflow continues normally to any blocks connected after the loop." },
+]} />

apps/docs/content/docs/en/blocks/meta.json

@@ -4,6 +4,7 @@
     "agent",
     "api",
     "condition",
+    "credential",
     "evaluator",
     "function",
     "guardrails",

apps/docs/content/docs/en/blocks/parallel.mdx

@@ -5,6 +5,7 @@ title: Parallel
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
 import { Image } from '@/components/ui/image'
+import { FAQ } from '@/components/ui/faq'
 
 The Parallel block is a container that executes multiple instances concurrently for faster workflow processing. Process items simultaneously instead of sequentially.
 
@@ -148,11 +149,8 @@ Each parallel instance runs independently:
 
 ### Limitations
 
-<Callout type="warning">
-  Container blocks (Loops and Parallels) cannot be nested inside each other. This means:
-  - You cannot place a Loop block inside a Parallel block
-  - You cannot place another Parallel block inside a Parallel block
-  - You cannot place any container block inside another container block
+<Callout type="info">
+  Container blocks (Loops and Parallels) support nesting. You can place parallels inside parallels, loops inside parallels, and any combination of container blocks to build complex multi-dimensional workflows.
 </Callout>
 
 <Callout type="info">
@@ -221,3 +219,13 @@ Understanding when to use each:
 - **Independent operations only**: Ensure operations don't depend on each other
 - **Handle rate limits**: Add delays or throttling for API-heavy workflows
 - **Error handling**: Each instance should handle its own errors gracefully
+
+<FAQ items={[
+  { question: "What is the maximum number of concurrent instances?", answer: "The maximum is 20 concurrent instances. This limit exists to prevent resource exhaustion and ensure stable execution." },
+  { question: "Can parallel instances share state with each other?", answer: "No. Each parallel instance runs in complete isolation with its own variable scope. There is no shared state between instances, and one instance cannot read or write data from another during execution." },
+  { question: "What happens if one parallel instance fails?", answer: "Failures in one instance do not affect other instances. Each instance runs independently, so the remaining instances will continue to execute normally." },
+  { question: "Can I nest Parallel blocks inside other Parallel or Loop blocks?", answer: "Yes. Container blocks (Parallels and Loops) support nesting. You can place parallels inside parallels, loops inside parallels, and any combination to build multi-dimensional workflows." },
+  { question: "How do I access results after the Parallel block completes?", answer: "Use <blockname.results> where blockname is the normalized name of your Parallel block (lowercase, no spaces). This returns an array containing the results from all instances." },
+  { question: "Is the order of results guaranteed?", answer: "No. Because instances execute concurrently, the order of results in the output array is not guaranteed to match the input order. If ordering matters, include an index or identifier in each instance's output." },
+  { question: "What is the difference between count-based and collection-based parallel?", answer: "Count-based runs a fixed number of identical instances (e.g., run 5 times). Collection-based distributes items from an array or object across instances, with each instance processing one item. Use count-based for repeated operations and collection-based for batch processing." },
+]} />

apps/docs/content/docs/en/blocks/response.mdx

@@ -5,6 +5,7 @@ title: Response
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
 import { Image } from '@/components/ui/image'
+import { FAQ } from '@/components/ui/faq'
 
 The Response block formats and sends structured HTTP responses back to API callers. Use it to return workflow results with proper status codes and headers.
 
@@ -35,23 +36,15 @@ The response data is the main content that will be sent back to the API caller.
 
 ### Status Code
 
-Set the HTTP status code for the response (defaults to 200):
+A free-text input field where you can enter any valid HTTP status code (the default placeholder is 200). Common examples include:
 
-**Success (2xx):**
 - **200**: OK - Standard success response
 - **201**: Created - Resource successfully created
-- **204**: No Content - Success with no response body
-
-**Client Error (4xx):**
 - **400**: Bad Request - Invalid request parameters
-- **401**: Unauthorized - Authentication required
 - **404**: Not Found - Resource doesn't exist
-- **422**: Unprocessable Entity - Validation errors
-
-**Server Error (5xx):**
 - **500**: Internal Server Error - Server-side error
-- **502**: Bad Gateway - External service error
-- **503**: Service Unavailable - Service temporarily down
+
+Any valid HTTP status code can be entered directly into the field.
 
 ### Response Headers
 
@@ -84,7 +77,7 @@ Condition (Error Detected) → Router → Response (400/500, Error Details)
 
 ## Outputs
 
-Response blocks are terminal - they end workflow execution and send the HTTP response to the API caller. No outputs are available to downstream blocks.
+Response blocks are terminal — no downstream blocks execute after them. However, the block does define outputs (`data`, `status`, `headers`) which are used to construct the HTTP response sent back to the API caller.
 
 ## Variable References
 
@@ -116,3 +109,11 @@ Use the `<variable.name>` syntax to dynamically insert workflow variables into y
 - **Handle errors gracefully**: Use conditional logic in your workflow to set appropriate error responses with descriptive messages
 - **Validate variable references**: Ensure all referenced variables exist and contain the expected data types before the Response block executes
 
+<FAQ items={[
+  { question: "Can I have multiple Response blocks in a workflow?", answer: "No. The Response block is a single-instance block — only one is allowed per workflow. If you need different responses for different conditions, use a Condition or Router block upstream to determine what data reaches the single Response block." },
+  { question: "What triggers require a Response block?", answer: "The Response block is designed for use with the API Trigger. When your workflow is invoked via the API, the Response block sends the structured HTTP response back to the caller. Other trigger types (like webhooks or schedules) do not require a Response block." },
+  { question: "What is the difference between Builder and Editor mode?", answer: "Builder mode provides a visual interface for constructing your response structure with fields and types. Editor mode gives you a raw JSON code editor where you can write the response body directly. Builder mode is recommended for most use cases." },
+  { question: "What is the default status code?", answer: "If you do not specify a status code, the Response block defaults to 200 (OK). You can set any valid HTTP status code including error codes like 400, 404, or 500." },
+  { question: "Can the Response block connect to downstream blocks?", answer: "No. Response blocks are terminal — they end workflow execution and send the HTTP response. No further blocks can be connected after a Response block." },
+]} />
+

apps/docs/content/docs/en/blocks/router.mdx

@@ -4,6 +4,7 @@ title: Router
 
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
 import { Image } from '@/components/ui/image'
+import { FAQ } from '@/components/ui/faq'
 
 The Router block uses AI to intelligently route workflows based on content analysis. Unlike Condition blocks that use simple rules, Routers understand context and intent. Each route you define creates a separate output port, allowing you to connect different paths to different downstream blocks.
 
@@ -54,12 +55,12 @@ Each route you add creates a **separate output port** on the Router block. Conne
 Choose an AI model to power the routing decision:
 
 - **OpenAI**: GPT-4o, o1, o3, o4-mini, gpt-4.1
-- **Anthropic**: Claude 3.7 Sonnet
+- **Anthropic**: Claude Sonnet 4.5
 - **Google**: Gemini 2.5 Pro, Gemini 2.0 Flash
 - **Other Providers**: Groq, Cerebras, xAI, DeepSeek
 - **Local Models**: Ollama or VLLM compatible models
 
-Use models with strong reasoning capabilities like GPT-4o or Claude 3.7 Sonnet for best results.
+Use models with strong reasoning capabilities like GPT-4o or Claude Sonnet 4.5 for best results.
 
 ### API Key
 
@@ -68,11 +69,12 @@ Your API key for the selected LLM provider. This is securely stored and used for
 ## Outputs
 
 - **`<router.context>`**: The context that was analyzed
-- **`<router.selectedRoute>`**: The ID of the selected route
-- **`<router.selected_path>`**: Details of the chosen destination block
+- **`<router.model>`**: Model used for decision-making
 - **`<router.tokens>`**: Token usage statistics
 - **`<router.cost>`**: Estimated routing cost
-- **`<router.model>`**: Model used for decision-making
+- **`<router.selectedRoute>`**: The ID of the selected route
+- **`<router.reasoning>`**: Explanation of why this route was chosen
+- **`<router.selectedPath>`**: Details of the chosen destination block
 
 ## Example Use Cases
 
@@ -117,3 +119,12 @@ When the Router cannot determine an appropriate route for the given context, it
 - **Test with diverse inputs**: Ensure the Router handles various input types, edge cases, and unexpected content.
 - **Monitor routing performance**: Review routing decisions regularly and refine route descriptions based on actual usage patterns.
 - **Choose appropriate models**: Use models with strong reasoning capabilities for complex routing decisions.
+
+<FAQ items={[
+  { question: "How does the Router decide which route to take?", answer: "The Router sends your context and all route descriptions to an LLM, which analyzes the input and selects the route whose description best matches. The LLM is prompted to be deterministic: it always prefers selecting a route over returning no match, and only reports NO_MATCH if the context is completely unrelated to every route description." },
+  { question: "What happens when the Router cannot match any route?", answer: "When the LLM determines that the context does not match any defined route, it returns NO_MATCH and the Router directs execution to the error path. Connect an error handler to this path for graceful fallback behavior rather than letting the workflow fail silently." },
+  { question: "Does the Router cost money to run?", answer: "Yes. The Router uses an LLM API call for every routing decision, which consumes tokens and incurs costs. You can monitor this via the <router.tokens> and <router.cost> outputs. If your routing logic can be expressed as simple boolean conditions, use the Condition block instead — it is free and faster." },
+  { question: "Can I see why the Router chose a particular route?", answer: "Yes. The Router V2 block outputs a reasoning field (<router.reasoning>) that contains a brief 1-2 sentence explanation of why the selected route was chosen. This is useful for debugging and understanding routing decisions." },
+  { question: "What models work best for routing?", answer: "Models with strong reasoning capabilities like GPT-4o or Claude Sonnet 4.5 tend to produce the most accurate routing decisions. For simpler routing scenarios with clearly distinct routes, a faster and cheaper model like GPT-4o-mini or Gemini Flash may be sufficient." },
+  { question: "How many routes can I define?", answer: "There is no hard limit on the number of routes. Each route you define creates a separate output port on the block. However, keep in mind that more routes with overlapping descriptions make it harder for the LLM to distinguish between them, so aim for clear, mutually exclusive route descriptions." },
+]} />

apps/docs/content/docs/en/blocks/variables.mdx

@@ -5,6 +5,7 @@ title: Variables
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
 import { Image } from '@/components/ui/image'
+import { FAQ } from '@/components/ui/faq'
 
 The Variables block updates workflow variables during execution. Variables must first be initialized in your workflow's Variables section, then you can use this block to update their values as your workflow runs.
 
@@ -73,7 +74,7 @@ API (Fetch Profile) → Variables (userId, userTier) → Agent (Personalize)
 
 ## Outputs
 
-- **`<variables.assignments>`**: JSON object with all variable assignments from this block
+The Variables block does not produce traditional block outputs. Variables are accessed globally via `<variable.variableName>` syntax from any block in the workflow, not through block output connections.
 
 ## Best Practices
 
@@ -81,3 +82,12 @@ API (Fetch Profile) → Variables (userId, userTier) → Agent (Personalize)
 - **Update dynamically**: Use Variables blocks to update values based on block outputs or calculations
 - **Use in loops**: Perfect for tracking state across iterations
 - **Name descriptively**: Use clear names like `currentIndex`, `totalProcessed`, or `lastError`
+
+<FAQ items={[
+  { question: "Do variables persist between workflow executions?", answer: "No. Variables are workflow-scoped and only persist for the duration of a single execution. Each new execution starts with the initial values defined in your workflow's Variables section." },
+  { question: "Can multiple Variables blocks update the same variable?", answer: "Yes. All Variables blocks share the same namespace. A later Variables block can overwrite a value set by an earlier one by using the same variable name." },
+  { question: "How do I reference a variable in other blocks?", answer: "Use the <variable.variableName> syntax in any block's input field. For example, <variable.retryCount> or <variable.customerEmail>." },
+  { question: "Do Variables blocks produce outputs I can wire to other blocks?", answer: "Variables do not appear as traditional block outputs in the connection UI. Instead, they are accessed globally via the <variable.variableName> prefix from any block in the workflow." },
+  { question: "What naming convention should I use for variables?", answer: "Use descriptive names in camelCase or snake_case. Variable names are case-sensitive, so 'retryCount' and 'RetryCount' are treated as different variables." },
+  { question: "Can I use block outputs to set variable values?", answer: "Yes. You can reference any block output when setting a variable value, such as setting customerEmail to <api.email> or incrementing a counter based on previous values." },
+]} />

apps/docs/content/docs/en/blocks/wait.mdx

@@ -5,6 +5,7 @@ title: Wait
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
 import { Image } from '@/components/ui/image'
+import { FAQ } from '@/components/ui/faq'
 
 The Wait block pauses your workflow for a specified amount of time before continuing to the next block. Use it to add delays between actions, respect API rate limits, or space out operations.
 
@@ -62,3 +63,11 @@ API (Trigger Job) → Wait (30s) → API (Check Status)
 
 - **Keep waits reasonable**: Use Wait for delays up to 10 minutes. For longer delays, consider scheduled workflows
 - **Monitor execution time**: Remember that waits extend total workflow duration
+
+<FAQ items={[
+  { question: "What is the maximum wait time?", answer: "The maximum wait time is 600 seconds (10 minutes). You can specify the duration in either seconds or minutes." },
+  { question: "Can a Wait block be cancelled?", answer: "Yes. Wait blocks are interruptible via workflow cancellation. If the workflow is stopped while a Wait block is active, the wait is cancelled and the status output will reflect 'cancelled'." },
+  { question: "What happens if I enter a value exceeding the maximum?", answer: "The wait is capped at 600 seconds. If you enter a value greater than 600 seconds (or greater than 10 minutes), it will be limited to the maximum allowed duration." },
+  { question: "Does the Wait block consume resources while paused?", answer: "The Wait block performs a simple sleep for the configured duration. It does not actively consume compute resources during the wait, but the workflow execution remains open until the wait completes." },
+  { question: "What outputs does the Wait block provide?", answer: "The Wait block outputs the wait duration in milliseconds (waitDuration) and a status string that indicates whether the wait is 'waiting', 'completed', or 'cancelled'." },
+]} />

apps/docs/content/docs/en/blocks/webhook.mdx

@@ -4,6 +4,7 @@ title: Webhook
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Image } from '@/components/ui/image'
+import { FAQ } from '@/components/ui/faq'
 
 The Webhook block sends HTTP POST requests to external webhook endpoints with automatic webhook headers and optional HMAC signing.
 
@@ -85,3 +86,11 @@ Condition (check) → Webhook (trigger) → Response
 <Callout>
 The Webhook block always uses POST. For other HTTP methods or more control, use the [API block](/blocks/api).
 </Callout>
+
+<FAQ items={[
+  { question: "Can I use HTTP methods other than POST?", answer: "No. The Webhook block always sends POST requests. If you need GET, PUT, DELETE, or PATCH, use the API block instead, which supports all standard HTTP methods." },
+  { question: "How does HMAC payload signing work?", answer: "When you provide a signing secret, the block generates an HMAC-SHA256 signature of the payload and includes it in the X-Webhook-Signature header in the format t=timestamp,v1=signature. The receiver can verify by computing HMAC-SHA256(secret, \"timestamp.body\") and comparing with the v1 value." },
+  { question: "What headers are added automatically?", answer: "Every webhook request automatically includes Content-Type (application/json), X-Webhook-Timestamp (Unix timestamp in milliseconds), X-Delivery-ID (unique UUID), and Idempotency-Key (same as X-Delivery-ID for deduplication)." },
+  { question: "Can custom headers override the automatic ones?", answer: "Yes. Any custom headers you define in the Additional Headers section will override automatic headers that share the same name." },
+  { question: "How is the Webhook block different from the API block?", answer: "The Webhook block is purpose-built for webhook delivery: it is POST-only, automatically adds webhook-specific headers (timestamp, delivery ID, idempotency key), and supports optional HMAC signing. The API block is more general-purpose with support for all HTTP methods, query parameters, and configurable retries." },
+]} />

apps/docs/content/docs/en/blocks/workflow.mdx

@@ -39,6 +39,8 @@ Drop a Workflow block when you want to call a child workflow as part of a larger
    - `result` – the child workflow's final response
    - `success` – whether it ran without errors
    - `error` – message when the run fails
+   - `childWorkflowName` – the name of the child workflow (string)
+   - `childWorkflowId` – the ID of the child workflow (string)
 
 ## Deployment Status Badge
 
@@ -61,3 +63,14 @@ The Workflow block always executes the most recent deployed version of the child
 <Callout>
 Keep child workflows focused. Small, reusable flows make it easier to combine them without creating deep nesting.
 </Callout>
+
+import { FAQ } from '@/components/ui/faq'
+
+<FAQ items={[
+  { question: "Can a workflow call itself recursively?", answer: "No. The workflow selector blocks self-references to prevent infinite loops. Additionally, Sim tracks the call chain across nested executions using an internal header and enforces a maximum call chain depth of 25 hops. If the limit is exceeded, the execution is rejected with a 409 error." },
+  { question: "What is the maximum nesting depth for sub-workflows?", answer: "The maximum call chain depth is 25. This means workflow A can call B, which calls C, and so on up to 25 levels deep. This limit applies across all chained calls, not just direct parent-child relationships." },
+  { question: "Does the Workflow block use the deployed or draft version of the child workflow?", answer: "The child workflow inherits the execution context of the parent. If the parent is running in a deployed context (API, schedule, webhook), the child also uses its deployed version. If the parent is running in draft mode (manual run from the editor), the child also uses its draft state. This lets you test nested workflows end-to-end before deploying." },
+  { question: "How do I pass data to a child workflow?", answer: "Use the Inputs field on the Workflow block. If the child workflow has an Input Form trigger, each field appears in the block configuration and you can map parent variables to them. The mapped values are available as start.input in the child workflow." },
+  { question: "What outputs does the Workflow block return?", answer: "The block returns a success boolean, the child workflow's result (its final response output), the child workflow's name and ID, and an error message if the run failed. You can reference these outputs from downstream blocks using the tag syntax." },
+  { question: "What happens if the child workflow fails?", answer: "The Workflow block raises an error that propagates to the parent workflow. If you need to handle failures gracefully, connect an error path from the Workflow block to a downstream block that processes the error." },
+]} />

apps/docs/content/docs/en/connections/basics.mdx

@@ -5,6 +5,7 @@ title: Basics
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
 import { Video } from '@/components/ui/video'
+import { FAQ } from '@/components/ui/faq'
 
 ## How Connections Work
 
@@ -47,3 +48,13 @@ The flow of data through connections follows these principles:
   Deleting a connection will immediately stop data flow between the blocks. Make sure this is
   intended before removing connections.
 </Callout>
+
+<FAQ items={[
+  { question: "How does Sim determine the order blocks execute in?", answer: "Sim builds a directed acyclic graph (DAG) from your connections. Blocks with no unresolved incoming edges execute first. Once a block completes, the engine removes its edge from downstream blocks and queues any block whose incoming edges are all satisfied. This means execution order is entirely determined by how you wire your connections." },
+  { question: "Can a block have multiple incoming connections?", answer: "Yes. A block with multiple incoming connections will wait until all source blocks have completed before it executes. The engine tracks incoming edges and only marks a block as ready when every incoming edge has been resolved." },
+  { question: "Can a block send its output to multiple downstream blocks?", answer: "Yes. A single block can have outgoing connections to multiple destination blocks. When the source block completes, all connected downstream blocks that are ready (all their other incoming edges are satisfied) will be queued for execution." },
+  { question: "What happens to downstream blocks when a Condition or Router block picks a specific path?", answer: "The engine activates only the edge matching the selected condition or route. Edges on unselected paths are deactivated, and any blocks reachable only through those deactivated edges are cascadingly skipped for that execution." },
+  { question: "Are connections between blocks inside a Loop or Parallel block handled differently?", answer: "Yes. The engine inserts sentinel nodes (start and end) around Loop and Parallel subflows. Connections that cross a loop boundary are redirected through these sentinels, and Loop back-edges are wired automatically so blocks inside the loop re-execute on each iteration." },
+  { question: "Is there an error-handling path for connections?", answer: "Yes. Connections can use an error source handle. If a block produces an error, only edges marked with the error handle are activated, while the normal source edges are deactivated. This lets you route errors to a dedicated error-handling branch in your workflow." },
+]} />
+

apps/docs/content/docs/en/connections/data-structure.mdx

@@ -4,6 +4,7 @@ title: Data Structure
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+import { FAQ } from '@/components/ui/faq'
 
 When you connect blocks, understanding the data structure of different block outputs is important because the output data structure from the source block determines what values are available in the destination block. Each block type produces a specific output structure that you can reference in downstream blocks.
 
@@ -185,3 +186,13 @@ For example:
 - `<agent1.tokens.total>` - Access the total tokens from an Agent block
 - `<api1.data.results[0].id>` - Access the ID of the first result from an API response
 - `<function1.result.calculations.total>` - Access a nested field in a Function block's result
+
+<FAQ items={[
+  { question: "What output fields does an Agent block produce?", answer: "An Agent block outputs content (the text response), model (the model used, e.g. gpt-4o), tokens (an object with prompt, completion, and total counts), and optionally toolCalls, cost, and usage arrays when tools are invoked." },
+  { question: "What does the API block output look like?", answer: "The API block returns data (the response body, which can be any type), status (the HTTP status code as a number), and headers (an object containing the response HTTP headers)." },
+  { question: "What does a Function block return?", answer: "A Function block outputs result (the return value of your function, which can be any type) and stdout (any console output captured during execution)." },
+  { question: "How does the Condition block output differ from the Router block?", answer: "The Condition block outputs conditionResult (a boolean), selectedPath (with blockId, blockType, and blockTitle of the next block), and selectedOption (the ID of the matched condition). The Router block outputs content (the routing decision text), model, tokens, and selectedPath, but does not include conditionResult or selectedOption." },
+  { question: "What happens to the Agent block output when a response format schema is configured?", answer: "When you define a response format on an Agent block, the output structure matches your defined schema instead of the standard content/model/tokens structure. Always verify the actual output shape when using response formats." },
+  { question: "How do I access deeply nested data from an API response?", answer: "Use dot notation with bracket indices in your connection tags. For example, <api1.data.results[0].id> navigates into the data field, then into the results array at index 0, and retrieves the id property." },
+]} />
+

apps/docs/content/docs/en/connections/index.mdx

@@ -7,6 +7,7 @@ import { Callout } from 'fumadocs-ui/components/callout'
 import { Card, Cards } from 'fumadocs-ui/components/card'
 import { ConnectIcon } from '@/components/icons'
 import { Video } from '@/components/ui/video'
+import { FAQ } from '@/components/ui/faq'
 
 Connections are the pathways that allow data to flow between blocks in your workflow. They define how information is passed from one block to another, enabling you to create sophisticated, multi-step processes.
 
@@ -40,3 +41,12 @@ Sim supports different types of connections that enable various workflow pattern
     Follow recommended patterns for effective connection management
   </Card>
 </Cards>
+
+<FAQ items={[
+  { question: "How does data actually flow between connected blocks?", answer: "The execution engine builds a directed acyclic graph (DAG) from your connections and processes blocks in dependency order. When a block finishes, its output is stored in the execution context. Downstream blocks reference that output using connection tags like <BlockName.response>, which the variable resolver replaces with the actual data at execution time." },
+  { question: "Can a block receive input from multiple upstream blocks?", answer: "Yes. A block waits until all of its incoming connections have been fulfilled before it executes. The engine tracks incoming edges for each node and only marks a block as ready when every upstream dependency has completed. You can reference outputs from any connected block using their respective connection tags." },
+  { question: "What happens if an upstream block fails?", answer: "If a block errors, the engine activates the error edge (if one exists) and deactivates the normal output edge. Downstream blocks on the success path will not execute. You can connect an error handle to a separate block to build fallback or recovery logic." },
+  { question: "Do connections support conditional branching?", answer: "Yes. Router and Condition blocks produce a selected route or option that determines which outgoing edge is activated. Only the blocks on the chosen path will execute. Edges on unselected paths are deactivated and their entire downstream subgraph is skipped." },
+  { question: "Can blocks in parallel branches share data with each other?", answer: "Blocks within the same parallel branch cannot directly reference blocks in a sibling branch because branches execute independently. However, once all branches complete and the parallel block exits, downstream blocks can access the aggregated results from all branches." },
+  { question: "How are connection tags formatted?", answer: "Connection tags use angle-bracket syntax: <BlockName.property>. For nested data you can chain dot notation, such as <BlockName.response.items[0].name>. The resolver walks the object path at execution time and substitutes the resolved value into your input field." },
+]} />

apps/docs/content/docs/en/connections/tags.mdx

@@ -4,6 +4,7 @@ title: Tags
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Video } from '@/components/ui/video'
+import { FAQ } from '@/components/ui/faq'
 
 Connection tags are visual representations of the data available from connected blocks, providing an easy way to reference data between blocks and outputs from previous blocks in your workflow.
 
@@ -107,3 +108,14 @@ const total = <apiBlock.data.total> * 1.1; // Add 10% tax
   When using connection tags in numeric contexts, make sure the referenced data is actually a number
   to avoid type conversion issues.
 </Callout>
+
+<FAQ items={[
+  { question: "How are tag references resolved at runtime?", answer: "The executor uses a chain of resolvers. Each reference like <blockName.path> is matched against resolvers in order: loop references, parallel references, workflow variables, environment variables, and finally block output references. The first resolver that recognizes the reference handles it." },
+  { question: "Does the block name in a tag reference need to match exactly?", answer: "Block names are normalized by converting to lowercase and removing spaces before matching. So <My Agent.content> and <myagent.content> resolve to the same block. However, the field path after the block name (e.g., content, data.users) is case-sensitive." },
+  { question: "Can I reference environment variables in tag syntax?", answer: "Yes, but environment variables use double-brace syntax instead of angle brackets: {{MY_VAR}}. These are resolved by a dedicated environment variable resolver during execution." },
+  { question: "What happens if I reference a block that did not execute on the current path?", answer: "If the referenced block exists in the workflow but did not produce output (for example, it was on an unselected condition branch), the reference resolves to an empty value. In most blocks this becomes an empty string; in Function blocks it becomes null." },
+  { question: "Can I access array elements inside a tag reference?", answer: "Yes. Use bracket notation for array indices within the dot path, for example <api1.data.users[0].name>. The resolver supports multiple levels of array indexing like items[0][1] as well." },
+  { question: "How are tag values formatted inside Function blocks versus other blocks?", answer: "In Function blocks, resolved values are formatted as code literals (strings are quoted, objects are JSON, null stays as null) so they can be used directly in JavaScript or Python code. In other block types, objects are JSON-stringified and primitives are converted to plain strings." },
+  { question: "Can I mix static text with tag references?", answer: "Yes. You can embed tag references anywhere in a text string, such as \"Hello, <agent1.content>! Your order total is <api1.data.total>.\" The resolver replaces each tag in place while leaving the surrounding text intact." },
+]} />
+

apps/docs/content/docs/en/copilot/index.mdx

@@ -5,7 +5,7 @@ title: Copilot
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Card, Cards } from 'fumadocs-ui/components/card'
 import { Image } from '@/components/ui/image'
-import { MessageCircle, Hammer, Zap, Globe, Paperclip, History, RotateCcw, Brain } from 'lucide-react'
+import { MessageCircle, Hammer, ListChecks, Zap, Globe, Paperclip, History, RotateCcw, Brain } from 'lucide-react'
 
 Copilot is your in-editor assistant that helps you build and edit workflows. It can:
 
@@ -49,6 +49,18 @@ Switch between modes using the mode selector at the bottom of the input area.
       Workflow building mode. Copilot can add blocks, wire connections, edit configurations, and debug issues.
     </div>
   </Card>
+  <Card
+    title={
+      <span className="inline-flex items-center gap-2">
+        <ListChecks className="h-4 w-4 text-muted-foreground" />
+        Plan
+      </span>
+    }
+  >
+    <div className="m-0 text-sm">
+      Creates a step-by-step implementation plan for your workflow without making any changes. Helps you think through the approach before building.
+    </div>
+  </Card>
 </Cards>
 
 ## Models
@@ -185,10 +197,10 @@ Selected options are highlighted; unselected options appear struck through.
 
 ## Usage Limits
 
-Copilot usage is billed per token from the underlying LLM. If you reach your usage limit, Copilot will prompt you to increase your limit. You can add usage in increments ($50, $100) from your current base.
+Copilot usage is billed per token from the underlying LLM and counts toward your plan's credit usage. If you reach your usage limit, enable on-demand billing from Settings → Subscription to continue using Copilot beyond your plan's included credits.
 
 <Callout type="info">
-  See the [Cost Calculation page](/execution/costs) for billing details.
+  See the [Cost Calculation page](/execution/costs) for billing and plan details.
 </Callout>
 ## Copilot MCP
 
@@ -286,3 +298,15 @@ Replace `YOUR_COPILOT_API_KEY` with your key.
   For self-hosted deployments, replace `https://www.sim.ai` with your self-hosted Sim URL.
 </Callout>
 
+import { FAQ } from '@/components/ui/faq'
+
+<FAQ items={[
+  { question: "What is the difference between Ask, Build, and Plan mode?", answer: "Copilot has three modes. Ask mode is a read-only Q&A mode for explanations, guidance, and suggestions without making any changes to your workflow. Build mode allows Copilot to actively modify your workflow by adding blocks, wiring connections, editing configurations, and debugging issues. Plan mode creates a step-by-step implementation plan for your request without making any changes, so you can review the approach before committing. Use Ask when you want to learn or explore ideas, Plan when you want to see a proposed approach first, and Build when you want Copilot to make changes directly." },
+  { question: "Does Copilot have access to my full workflow when answering questions?", answer: "Copilot has access to the workflow you are currently editing as context. You can also use the @ context menu to reference other workflows, previous chats, execution logs, knowledge bases, documentation, and templates to give Copilot additional context for your request." },
+  { question: "How do I use Copilot from an external editor like Cursor or VS Code?", answer: "You can use Copilot as an MCP server from external editors. First, generate a Copilot API key from Settings > Copilot on sim.ai. Then add the MCP server configuration to your editor using the endpoint https://www.sim.ai/api/mcp/copilot with your API key in the X-API-Key header. Configuration examples are available for Cursor, Claude Code, Claude Desktop, and VS Code." },
+  { question: "Can I revert changes that Copilot made to my workflow?", answer: "Yes. When Copilot makes changes in Build mode, it saves checkpoints of your workflow state. You can hover over a Copilot message and click the checkpoints icon to see saved states, then click Revert on any checkpoint to restore your workflow. Note that reverting cannot be undone, so review the checkpoint before confirming." },
+  { question: "How does Copilot billing work?", answer: "Copilot usage is billed per token from the underlying LLM and counts toward your plan's credit usage. More capable models like Claude Opus cost more per token than lighter models like Haiku. If you reach your usage limit, you can enable on-demand billing from Settings > Subscription to continue using Copilot." },
+  { question: "What do the slash commands like /research and /search do?", answer: "Slash commands trigger specialized behaviors. /fast enables fast mode execution, /research activates a research and exploration mode, and /actions executes agent actions. Web commands like /search, /read, /scrape, and /crawl let Copilot interact with the web to search for information, read URLs, scrape page content, or crawl multiple pages to gather context for your request." },
+  { question: "How do I set up Copilot for a self-hosted deployment?", answer: "For self-hosted deployments, go to sim.ai > Settings > Copilot and generate a Copilot API key. Then set the COPILOT_API_KEY environment variable in your self-hosted environment. Copilot is a Sim-managed service, so the self-hosted instance communicates with Sim's servers to process requests." },
+]} />
+

apps/docs/content/docs/en/credentials/google-service-account.mdx

@@ -0,0 +1,206 @@
+---
+title: Google Service Accounts
+description: Set up Google service accounts with domain-wide delegation for Gmail, Sheets, Drive, Calendar, and other Google services
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Step, Steps } from 'fumadocs-ui/components/steps'
+import { Image } from '@/components/ui/image'
+import { FAQ } from '@/components/ui/faq'
+
+Google service accounts with domain-wide delegation let your workflows access Google APIs on behalf of users in your Google Workspace domain — without requiring each user to complete an OAuth consent flow. This is ideal for automated workflows that need to send emails, read spreadsheets, or manage files across your organization.
+
+For example, you could build a workflow that iterates through a list of employees, impersonates each one to read their Google Docs, and uploads the contents to a shared knowledge base — all without requiring any of those users to sign in.
+
+## Prerequisites
+
+Before adding a service account to Sim, you need to configure it in the Google Cloud Console and Google Workspace Admin Console.
+
+### 1. Create a Service Account in Google Cloud
+
+<Steps>
+  <Step>
+    Go to the [Google Cloud Console](https://console.cloud.google.com/) and select your project (or create one)
+  </Step>
+  <Step>
+    Navigate to **IAM & Admin** → **Service Accounts**
+  </Step>
+  <Step>
+    Click **Create Service Account**, give it a name and description, then click **Create and Continue**
+
+    <div className="flex justify-center">
+      <Image
+        src="/static/credentials/gcp-create-service-account.png"
+        alt="Google Cloud Console — Create service account form"
+        width={700}
+        height={500}
+        className="my-4"
+      />
+    </div>
+  </Step>
+  <Step>
+    Skip the optional role and user access steps and click **Done**
+  </Step>
+  <Step>
+    Click on the newly created service account, go to the **Keys** tab, and click **Add Key** → **Create new key**
+  </Step>
+  <Step>
+    Select **JSON** as the key type and click **Create**. A JSON key file will download — keep this safe
+
+    <div className="flex justify-center">
+      <Image
+        src="/static/credentials/gcp-create-private-key.png"
+        alt="Google Cloud Console — Create private key dialog with JSON selected"
+        width={700}
+        height={400}
+        className="my-4"
+      />
+    </div>
+  </Step>
+</Steps>
+
+<Callout type="warn">
+The JSON key file contains your service account's private key. Treat it like a password — do not commit it to source control or share it publicly.
+</Callout>
+
+### 2. Enable the Required APIs
+
+In the Google Cloud Console, go to **APIs & Services** → **Library** and enable the APIs for the services your workflows will use. See the [scopes reference](#scopes-reference) below for the full list of APIs by service.
+
+### 3. Set Up Domain-Wide Delegation
+
+<Steps>
+  <Step>
+    In the Google Cloud Console, go to **IAM & Admin** → **Service Accounts**, click on your service account, and copy the **Client ID** (the numeric ID, not the email)
+  </Step>
+  <Step>
+    Open the [Google Workspace Admin Console](https://admin.google.com/) and navigate to **Security** → **Access and data control** → **API controls**
+  </Step>
+  <Step>
+    Click **Manage Domain Wide Delegation**, then click **Add new**
+  </Step>
+  <Step>
+    Paste the **Client ID** from your service account, then add the OAuth scopes for the services your workflows need. Copy the full scope URLs from the [scopes reference](#scopes-reference) below — only authorize scopes for services you plan to use.
+
+    <div className="flex justify-center">
+      <Image
+        src="/static/credentials/gcp-add-client-id.png"
+        alt="Google Workspace Admin Console — Add a new client ID with OAuth scopes"
+        width={350}
+        height={300}
+        className="my-4"
+      />
+    </div>
+  </Step>
+  <Step>
+    Click **Authorize**
+  </Step>
+</Steps>
+
+<Callout type="info">
+Domain-wide delegation must be configured by a Google Workspace admin. If you are not an admin, send the Client ID and required scopes to your admin.
+</Callout>
+
+### Scopes Reference
+
+The table below lists every Google service that supports service account authentication in Sim, the API to enable in Google Cloud Console, and the delegation scopes to authorize. Copy the scope string for each service you need and paste it into the Google Workspace Admin Console.
+
+<table>
+  <thead>
+    <tr>
+      <th className="whitespace-nowrap">Service</th>
+      <th className="whitespace-nowrap">API to Enable</th>
+      <th>Delegation Scopes</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr><td>Gmail</td><td>Gmail API</td><td><code>{'https://www.googleapis.com/auth/gmail.send'}</code><br/><code>{'https://www.googleapis.com/auth/gmail.modify'}</code><br/><code>{'https://www.googleapis.com/auth/gmail.labels'}</code></td></tr>
+    <tr><td>Google Sheets</td><td>Google Sheets API, Google Drive API</td><td><code>{'https://www.googleapis.com/auth/drive'}</code><br/><code>{'https://www.googleapis.com/auth/drive.file'}</code></td></tr>
+    <tr><td>Google Drive</td><td>Google Drive API</td><td><code>{'https://www.googleapis.com/auth/drive'}</code><br/><code>{'https://www.googleapis.com/auth/drive.file'}</code></td></tr>
+    <tr><td>Google Docs</td><td>Google Docs API, Google Drive API</td><td><code>{'https://www.googleapis.com/auth/drive'}</code><br/><code>{'https://www.googleapis.com/auth/drive.file'}</code></td></tr>
+    <tr><td>Google Slides</td><td>Google Slides API, Google Drive API</td><td><code>{'https://www.googleapis.com/auth/drive'}</code><br/><code>{'https://www.googleapis.com/auth/drive.file'}</code></td></tr>
+    <tr><td>Google Forms</td><td>Google Forms API, Google Drive API</td><td><code>{'https://www.googleapis.com/auth/drive'}</code><br/><code>{'https://www.googleapis.com/auth/forms.body'}</code><br/><code>{'https://www.googleapis.com/auth/forms.responses.readonly'}</code></td></tr>
+    <tr><td>Google Calendar</td><td>Google Calendar API</td><td><code>{'https://www.googleapis.com/auth/calendar'}</code></td></tr>
+    <tr><td>Google Contacts</td><td>People API</td><td><code>{'https://www.googleapis.com/auth/contacts'}</code></td></tr>
+    <tr><td>BigQuery</td><td>BigQuery API</td><td><code>{'https://www.googleapis.com/auth/bigquery'}</code></td></tr>
+    <tr><td>Google Tasks</td><td>Tasks API</td><td><code>{'https://www.googleapis.com/auth/tasks'}</code></td></tr>
+    <tr><td>Google Vault</td><td>Vault API, Cloud Storage API</td><td><code>{'https://www.googleapis.com/auth/ediscovery'}</code><br/><code>{'https://www.googleapis.com/auth/devstorage.read_only'}</code></td></tr>
+    <tr><td>Google Groups</td><td>Admin SDK API</td><td><code>{'https://www.googleapis.com/auth/admin.directory.group'}</code><br/><code>{'https://www.googleapis.com/auth/admin.directory.group.member'}</code></td></tr>
+    <tr><td>Google Meet</td><td>Google Meet API</td><td><code>{'https://www.googleapis.com/auth/meetings.space.created'}</code><br/><code>{'https://www.googleapis.com/auth/meetings.space.readonly'}</code></td></tr>
+  </tbody>
+</table>
+
+<Callout type="info">
+You only need to enable APIs and authorize scopes for the services you plan to use. When authorizing multiple services, combine their scope strings with commas into a single entry in the Admin Console.
+</Callout>
+
+## Adding the Service Account to Sim
+
+Once Google Cloud and Workspace are configured, add the service account as a credential in Sim.
+
+<Steps>
+  <Step>
+    Open your workspace **Settings** and go to the **Integrations** tab
+  </Step>
+  <Step>
+    Search for "Google Service Account" and click **Connect**
+
+    <div className="flex justify-center">
+      <Image
+        src="/static/credentials/integrations-service-account.png"
+        alt="Integrations page showing Google Service Account"
+        width={800}
+        height={150}
+        className="my-4"
+      />
+    </div>
+  </Step>
+  <Step>
+    Paste the full contents of your JSON key file into the text area
+    <div className="flex justify-center">
+      <Image
+        src="/static/credentials/add-service-account.png"
+        alt="Add Google Service Account dialog"
+        width={350}
+        height={420}
+        className="my-6"
+      />
+    </div>
+  </Step>
+  <Step>
+    Give the credential a display name (the service account email is used by default)
+  </Step>
+  <Step>
+    Click **Save**
+  </Step>
+</Steps>
+
+The JSON key file is validated for the required fields (`type`, `client_email`, `private_key`, `project_id`) and encrypted before being stored.
+
+## Using Delegated Access in Workflows
+
+When you use a Google block (Gmail, Sheets, Drive, etc.) in a workflow and select a service account credential, an **Impersonate User Email** field appears below the credential selector.
+
+Enter the email address of the Google Workspace user you want the service account to act as. For example, if you enter `alice@yourcompany.com`, the workflow will send emails from Alice's account, read her spreadsheets, or access her calendar — depending on the scopes you authorized.
+
+<div className="flex justify-center">
+  <Image
+    src="/static/credentials/workflow-impersonated-account.png"
+    alt="Gmail block in a workflow showing the Impersonated Account field with a service account credential"
+    width={800}
+    height={350}
+    className="my-4"
+  />
+</div>
+
+<Callout type="warn">
+The impersonated email must belong to a user in the Google Workspace domain where you configured domain-wide delegation. Impersonating external email addresses will fail.
+</Callout>
+
+<FAQ items={[
+  { question: "Can I use a service account without domain-wide delegation?", answer: "Yes, but it will only be able to access resources owned by the service account itself (e.g., spreadsheets shared directly with the service account email). Without delegation, you cannot impersonate users or access their personal data like Gmail." },
+  { question: "What happens if the impersonation email field is left blank?", answer: "The service account will authenticate as itself. This works for accessing shared resources (like a Google Sheet shared with the service account email) but will fail for user-specific APIs like Gmail." },
+  { question: "Can I use the same service account for multiple Google services?", answer: "Yes. A single service account can be used across Gmail, Sheets, Drive, Calendar, and other Google services — as long as the required API is enabled in Google Cloud and the corresponding scopes are authorized in the Workspace admin console." },
+  { question: "How do I rotate the service account key?", answer: "Create a new JSON key in the Google Cloud Console under your service account's Keys tab, then update the credential in Sim with the new key. Delete the old key from Google Cloud once the new one is working." },
+  { question: "Does the impersonated user need a Google Workspace license?", answer: "Yes. Domain-wide delegation only works with users who have a Google Workspace account in the domain. Consumer Gmail accounts (e.g., @gmail.com) cannot be impersonated." },
+]} />

apps/docs/content/docs/en/credentials/index.mdx

@@ -0,0 +1,203 @@
+---
+title: Credentials
+description: Manage secrets, API keys, and OAuth connections for your workflows
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Image } from '@/components/ui/image'
+import { Step, Steps } from 'fumadocs-ui/components/steps'
+import { FAQ } from '@/components/ui/faq'
+
+Credentials provide a secure way to manage API keys, tokens, and third-party service connections across your workflows. Instead of hardcoding sensitive values into your workflow, you store them as credentials and reference them at runtime.
+
+Sim supports two categories of credentials: **secrets** for static values like API keys, and **OAuth accounts** for authenticated service connections like Google or Slack.
+
+## Getting Started
+
+To manage credentials, open your workspace **Settings** and navigate to the **Secrets** tab.
+
+<Image
+  src="/static/credentials/settings-secrets.png"
+  alt="Settings modal showing the Secrets tab with a list of saved credentials"
+  width={700}
+  height={200}
+/>
+
+From here you can search, create, and delete both secrets and OAuth connections.
+
+## Secrets
+
+Secrets are key-value pairs that store sensitive data like API keys, tokens, and passwords. Each secret has a **key** (used to reference it in workflows) and a **value** (the actual secret).
+
+### Creating a Secret
+
+<Image
+  src="/static/credentials/create-secret.png"
+  alt="Create Secret dialog with fields for key, value, description, and scope toggle"
+  width={500}
+  height={400}
+/>
+
+<Steps>
+  <Step>
+    Click **+ Add** and select **Secret** as the type
+  </Step>
+  <Step>
+    Enter a **Key** name (letters, numbers, and underscores only, e.g. `OPENAI_API_KEY`)
+  </Step>
+  <Step>
+    Enter the **Value**
+  </Step>
+  <Step>
+    Optionally add a **Description** to help your team understand what the secret is for
+  </Step>
+  <Step>
+    Choose the **Scope** — Workspace or Personal
+  </Step>
+  <Step>
+    Click **Create**
+  </Step>
+</Steps>
+
+### Using Secrets in Workflows
+
+To reference a secret in any input field, type `{{` to open the dropdown. It will show your available secrets grouped by scope.
+
+<Image
+  src="/static/credentials/secret-dropdown.png"
+  alt="Typing {{ in a code block opens a dropdown showing available workspace secrets"
+  width={400}
+  height={250}
+/>
+
+Select the secret you want to use. The reference will appear highlighted in blue, indicating it will be resolved at runtime.
+
+<Image
+  src="/static/credentials/secret-resolved.png"
+  alt="A resolved secret reference shown in blue text as {{OPENAI_API_KEY}}"
+  width={400}
+  height={200}
+/>
+
+<Callout type="warn">
+Secret values are never exposed in the workflow editor or logs. They are only resolved during execution.
+</Callout>
+
+### Bulk Import
+
+You can import multiple secrets at once by pasting `.env`-style content:
+
+1. Click **+ Add**, then switch to **Bulk** mode
+2. Paste your environment variables in `KEY=VALUE` format
+3. Choose the scope for all imported secrets
+4. Click **Create**
+
+The parser supports standard `KEY=VALUE` pairs, quoted values, comments (`#`), and blank lines.
+
+## OAuth Accounts
+
+OAuth accounts are authenticated connections to third-party services like Google, Slack, GitHub, and more. Sim handles the OAuth flow, token storage, and automatic refresh.
+
+You can connect **multiple accounts per provider** — for example, two separate Gmail accounts for different workflows.
+
+### Connecting an OAuth Account
+
+<Image
+  src="/static/credentials/create-oauth.png"
+  alt="Create Secret dialog with OAuth Account type selected, showing display name and provider dropdown"
+  width={500}
+  height={400}
+/>
+
+<Steps>
+  <Step>
+    Click **+ Add** and select **OAuth Account** as the type
+  </Step>
+  <Step>
+    Enter a **Display name** to identify this connection (e.g. "Work Gmail" or "Marketing Slack")
+  </Step>
+  <Step>
+    Optionally add a **Description**
+  </Step>
+  <Step>
+    Select the **Account** provider from the dropdown
+  </Step>
+  <Step>
+    Click **Connect** and complete the authorization flow
+  </Step>
+</Steps>
+
+### Using OAuth Accounts in Workflows
+
+Blocks that require authentication (e.g. Gmail, Slack, Google Sheets) display a credential selector dropdown. Select the OAuth account you want the block to use.
+
+<Image
+  src="/static/credentials/oauth-selector.png"
+  alt="Gmail block showing the account selector dropdown with a connected account and option to connect another"
+  width={500}
+  height={350}
+/>
+
+You can also connect additional accounts directly from the block by selecting **Connect another account** at the bottom of the dropdown.
+
+<Callout type="info">
+If a block requires an OAuth connection and none is selected, the workflow will fail at that step.
+</Callout>
+
+## Workspace vs. Personal
+
+Credentials can be scoped to your **workspace** (shared with your team) or kept **personal** (private to you).
+
+| | Workspace | Personal |
+|---|---|---|
+| **Visibility** | All workspace members | Only you |
+| **Use in workflows** | Any member can use | Only you can use |
+| **Best for** | Production workflows, shared services | Testing, personal API keys |
+| **Who can edit** | Workspace admins | Only you |
+| **Auto-shared** | Yes — all members get access on creation | No — only you have access |
+
+<Callout type="info">
+When a workspace and personal secret share the same key name, the **workspace secret takes precedence**.
+</Callout>
+
+### Resolution Order
+
+When a workflow runs, Sim resolves secrets in this order:
+
+1. **Workspace secrets** are checked first
+2. **Personal secrets** are used as a fallback — from the user who triggered the run (manual) or the workflow owner (automated runs via API, webhook, or schedule)
+
+## Access Control
+
+Each credential has role-based access control:
+
+- **Admin** — can view, edit, delete, and manage who has access
+- **Member** — can use the credential in workflows (read-only)
+
+When you create a workspace secret, all current workspace members are automatically granted access. Personal secrets are only accessible to you by default.
+
+### Sharing a Credential
+
+To share a credential with specific team members:
+
+1. Click **Details** on the credential
+2. Invite members by email
+3. Assign them an **Admin** or **Member** role
+
+## Best Practices
+
+- **Use workspace credentials for production** so workflows work regardless of who triggers them
+- **Use personal credentials for development** to keep your test keys separate
+- **Name keys descriptively** — `STRIPE_SECRET_KEY` over `KEY1`
+- **Connect multiple OAuth accounts** when you need different permissions or identities per workflow
+- **Never hardcode secrets** in workflow input fields — always use `{{KEY}}` references
+
+<FAQ items={[
+  { question: "Are my secrets encrypted at rest?", answer: "Yes. Secret values and OAuth tokens are encrypted before being stored in the database. The platform uses server-side encryption so that raw secret values are never persisted in plaintext. Secret values are also never exposed in the workflow editor, logs, or API responses." },
+  { question: "What happens if both a workspace secret and a personal secret have the same key name?", answer: "The workspace secret takes precedence. During execution, the resolver checks workspace secrets first and uses personal secrets only as a fallback. This ensures that production workflows use the shared, team-managed value." },
+  { question: "Who determines which personal secret is used for automated runs?", answer: "For manual runs, the personal secrets of the user who clicked Run are used as fallback. For automated runs triggered by API, webhook, or schedule, the personal secrets of the workflow owner are used instead." },
+  { question: "Does Sim handle OAuth token refresh automatically?", answer: "Yes. When an OAuth token is used during execution, the platform checks whether the access token has expired and automatically refreshes it using the stored refresh token before making the API call. You do not need to handle token refresh manually." },
+  { question: "Can I connect multiple OAuth accounts for the same provider?", answer: "Yes. You can connect multiple accounts per provider (for example, two separate Gmail accounts). Each block that requires OAuth lets you select which specific account to use from the credential dropdown. This is useful when different workflows or blocks need different permissions or identities." },
+  { question: "What happens if I delete a credential that is used in a workflow?", answer: "If a block references a deleted credential, the workflow will fail at that block during execution because the credential cannot be resolved. Make sure to update any blocks that reference a credential before deleting it." },
+  { question: "Can I import secrets from a .env file?", answer: "Yes. The bulk import feature lets you paste .env-style content in KEY=VALUE format. The parser supports quoted values, comments (lines starting with #), and blank lines. All imported secrets are created with the scope you choose (workspace or personal)." },
+]} />

apps/docs/content/docs/en/credentials/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Credentials",
+  "pages": ["index", "google-service-account"],
+  "defaultOpen": false
+}