Fix panel logic

Remove console log
Lint fix
2026-03-15 03:00:33 -04:00 · 2026-03-14 18:53:16 -07:00 · 2026-03-14 18:08:23 -07:00 · 2026-03-14 18:07:02 -07:00 · 2026-03-14 17:54:18 -07:00 · 2026-03-14 16:56:44 -07:00
6693 changed files with 1275864 additions and 159661 deletions
--- a/.claude/commands/add-block.md
+++ b/.claude/commands/add-block.md
@@ -0,0 +1,825 @@
+---
+description: Create a block configuration for a Sim integration with proper subBlocks, conditions, and tool wiring
+argument-hint: <service-name>
+---
+
+# 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
--- a/.claude/commands/add-connector.md
+++ b/.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`
--- a/.claude/commands/add-integration.md
+++ b/.claude/commands/add-integration.md
@@ -0,0 +1,760 @@
+---
+description: Add a complete integration to Sim (tools, block, icon, registration)
+argument-hint: <service-name> [api-docs-url]
+---
+
+# 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`
--- a/.claude/commands/add-tools.md
+++ b/.claude/commands/add-tools.md
@@ -0,0 +1,321 @@
+---
+description: Create tool configurations for a Sim integration by reading API docs
+argument-hint: <service-name> [api-docs-url]
+---
+
+# Add Tools Skill
+
+You are an expert at creating tool configurations for Sim integrations. Your job is to read API documentation and create properly structured tool files.
+
+## Your Task
+
+When the user asks you to create tools for a service:
+1. Use Context7 or WebFetch to read the service's API documentation
+2. Create the tools directory structure
+3. Generate properly typed tool configurations
+
+## Directory Structure
+
+Create files in `apps/sim/tools/{service}/`:
+```
+tools/{service}/
+├── index.ts      # Barrel export
+├── types.ts      # Parameter & response types
+└── {action}.ts   # Individual tool files (one per operation)
+```
+
+## Tool Configuration Structure
+
+Every tool MUST follow this exact structure:
+
+```typescript
+import type { {ServiceName}{Action}Params } from '@/tools/{service}/types'
+import type { ToolConfig } from '@/tools/types'
+
+interface {ServiceName}{Action}Response {
+  success: boolean
+  output: {
+    // Define output structure here
+  }
+}
+
+export const {serviceName}{Action}Tool: ToolConfig<
+  {ServiceName}{Action}Params,
+  {ServiceName}{Action}Response
+> = {
+  id: '{service}_{action}',           // snake_case, matches tool name
+  name: '{Service} {Action}',         // Human readable
+  description: 'Brief description',   // One sentence
+  version: '1.0.0',
+
+  // OAuth config (if service uses OAuth)
+  oauth: {
+    required: true,
+    provider: '{service}',            // Must match OAuth provider ID
+  },
+
+  params: {
+    // Hidden params (system-injected, only use hidden for oauth accessToken)
+    accessToken: {
+      type: 'string',
+      required: true,
+      visibility: 'hidden',
+      description: 'OAuth access token',
+    },
+    // User-only params (credentials, api key, IDs user must provide)
+    someId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'The ID of the resource',
+    },
+    // User-or-LLM params (everything else, can be provided by user OR computed by LLM)
+    query: {
+      type: 'string',
+      required: false,                // Use false for optional
+      visibility: 'user-or-llm',
+      description: 'Search query',
+    },
+  },
+
+  request: {
+    url: (params) => `https://api.service.com/v1/resource/${params.id}`,
+    method: 'POST',
+    headers: (params) => ({
+      Authorization: `Bearer ${params.accessToken}`,
+      'Content-Type': 'application/json',
+    }),
+    body: (params) => ({
+      // Request body - only for POST/PUT/PATCH
+      // Trim ID fields to prevent copy-paste whitespace errors:
+      // userId: params.userId?.trim(),
+    }),
+  },
+
+  transformResponse: async (response: Response) => {
+    const data = await response.json()
+    return {
+      success: true,
+      output: {
+        // Map API response to output
+        // Use ?? null for nullable fields
+        // Use ?? [] for optional arrays
+      },
+    }
+  },
+
+  outputs: {
+    // Define each output field
+  },
+}
+```
+
+## Critical Rules for Parameters
+
+### Visibility Options
+- `'hidden'` - System-injected (OAuth tokens, internal params). User never sees.
+- `'user-only'` - User must provide (credentials, api keys, account-specific IDs)
+- `'user-or-llm'` - User provides OR LLM can compute (search queries, content, filters, most fall into this category)
+
+### Parameter Types
+- `'string'` - Text values
+- `'number'` - Numeric values
+- `'boolean'` - True/false
+- `'json'` - Complex objects (NOT 'object', use 'json')
+- `'file'` - Single file
+- `'file[]'` - Multiple files
+
+### Required vs Optional
+- Always explicitly set `required: true` or `required: false`
+- Optional params should have `required: false`
+
+## Critical Rules for Outputs
+
+### Output Types
+- `'string'`, `'number'`, `'boolean'` - Primitives
+- `'json'` - Complex objects (use this, NOT 'object')
+- `'array'` - Arrays with `items` property
+- `'object'` - Objects with `properties` property
+
+### Optional Outputs
+Add `optional: true` for fields that may not exist in the response:
+```typescript
+closedAt: {
+  type: 'string',
+  description: 'When the issue was closed',
+  optional: true,
+},
+```
+
+### Typed JSON Outputs
+
+When using `type: 'json'` and you know the object shape in advance, **always define the inner structure** using `properties` so downstream consumers know what fields are available:
+
+```typescript
+// BAD: Opaque json with no info about what's inside
+metadata: {
+  type: 'json',
+  description: 'Response metadata',
+},
+
+// GOOD: Define the known properties
+metadata: {
+  type: 'json',
+  description: 'Response metadata',
+  properties: {
+    id: { type: 'string', description: 'Unique ID' },
+    status: { type: 'string', description: 'Current status' },
+    count: { type: 'number', description: 'Total count' },
+  },
+},
+```
+
+For arrays of objects, define the item structure:
+```typescript
+items: {
+  type: 'array',
+  description: 'List of items',
+  items: {
+    type: 'object',
+    properties: {
+      id: { type: 'string', description: 'Item ID' },
+      name: { type: 'string', description: 'Item name' },
+    },
+  },
+},
+```
+
+Only use bare `type: 'json'` without `properties` when the shape is truly dynamic or unknown.
+
+## Critical Rules for transformResponse
+
+### Handle Nullable Fields
+ALWAYS use `?? null` for fields that may be undefined:
+```typescript
+transformResponse: async (response: Response) => {
+  const data = await response.json()
+  return {
+    success: true,
+    output: {
+      id: data.id,
+      title: data.title,
+      body: data.body ?? null,           // May be undefined
+      assignee: data.assignee ?? null,   // May be undefined
+      labels: data.labels ?? [],         // Default to empty array
+      closedAt: data.closed_at ?? null,  // May be undefined
+    },
+  }
+}
+```
+
+### Never Output Raw JSON Dumps
+DON'T do this:
+```typescript
+output: {
+  data: data,  // BAD - raw JSON dump
+}
+```
+
+DO this instead - extract meaningful fields:
+```typescript
+output: {
+  id: data.id,
+  name: data.name,
+  status: data.status,
+  metadata: {
+    createdAt: data.created_at,
+    updatedAt: data.updated_at,
+  },
+}
+```
+
+## Types File Pattern
+
+Create `types.ts` with interfaces for all params and responses:
+
+```typescript
+import type { ToolResponse } from '@/tools/types'
+
+// Parameter interfaces
+export interface {Service}{Action}Params {
+  accessToken: string
+  requiredField: string
+  optionalField?: string
+}
+
+// Response interfaces (extend ToolResponse)
+export interface {Service}{Action}Response extends ToolResponse {
+  output: {
+    field1: string
+    field2: number
+    optionalField?: string | null
+  }
+}
+```
+
+## Index.ts Barrel Export Pattern
+
+```typescript
+// Export all tools
+export { serviceTool1 } from './{action1}'
+export { serviceTool2 } from './{action2}'
+
+// Export types
+export * from './types'
+```
+
+## Registering Tools
+
+After creating tools, remind the user to:
+1. Import tools in `apps/sim/tools/registry.ts`
+2. Add to the `tools` object with snake_case keys:
+```typescript
+import { serviceActionTool } from '@/tools/{service}'
+
+export const tools = {
+  // ... existing tools ...
+  {service}_{action}: serviceActionTool,
+}
+```
+
+## V2 Tool Pattern
+
+If creating V2 tools (API-aligned outputs), use `_v2` suffix:
+- Tool ID: `{service}_{action}_v2`
+- Variable name: `{action}V2Tool`
+- Version: `'2.0.0'`
+- Outputs: Flat, API-aligned (no content/metadata wrapper)
+
+## Naming Convention
+
+All tool IDs MUST use `snake_case`: `{service}_{action}` (e.g., `x_create_tweet`, `slack_send_message`). Never use camelCase or PascalCase for tool IDs.
+
+## Checklist Before Finishing
+
+- [ ] All tool IDs use snake_case
+- [ ] All params have explicit `required: true` or `required: false`
+- [ ] All params have appropriate `visibility`
+- [ ] All nullable response fields use `?? null`
+- [ ] All optional outputs have `optional: true`
+- [ ] No raw JSON dumps in outputs
+- [ ] Types file has all interfaces
+- [ ] Index.ts exports all tools
+
+## Final Validation (Required)
+
+After creating all tools, you MUST validate every tool before finishing:
+
+1. **Read every tool file** you created — do not skip any
+2. **Cross-reference with the API docs** to verify:
+   - All required params are marked `required: true`
+   - All optional params are marked `required: false`
+   - Param types match the API (string, number, boolean, json)
+   - Request URL, method, headers, and body match the API spec
+   - `transformResponse` extracts the correct fields from the API response
+   - All output fields match what the API actually returns
+   - No fields are missing from outputs that the API provides
+   - No extra fields are defined in outputs that the API doesn't return
+3. **Verify consistency** across tools:
+   - Shared types in `types.ts` match all tools that use them
+   - Tool IDs in the barrel export match the tool file definitions
+   - Error handling is consistent (error checks, meaningful messages)
--- a/.claude/commands/add-trigger.md
+++ b/.claude/commands/add-trigger.md
@@ -0,0 +1,708 @@
+---
+description: Create webhook triggers for a Sim integration using the generic trigger builder
+argument-hint: <service-name>
+---
+
+# 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)
--- a/.claude/commands/validate-integration.md
+++ b/.claude/commands/validate-integration.md
@@ -0,0 +1,289 @@
+---
+description: Validate an existing Sim integration (tools, block, registry) against the service's API docs
+argument-hint: <service-name> [api-docs-url]
+---
+
+# Validate Integration Skill
+
+You are an expert auditor for Sim integrations. Your job is to thoroughly validate that an existing integration is correct, complete, and follows all conventions.
+
+## Your Task
+
+When the user asks you to validate an integration:
+1. Read the service's API documentation (via WebFetch or Context7)
+2. Read every tool, the block, and registry entries
+3. Cross-reference everything against the API docs and Sim conventions
+4. Report all issues found, grouped by severity (critical, warning, suggestion)
+5. Fix all issues after reporting them
+
+## Step 1: Gather All Files
+
+Read **every** file for the integration — do not skip any:
+
+```
+apps/sim/tools/{service}/          # All tool files, types.ts, index.ts
+apps/sim/blocks/blocks/{service}.ts # Block definition
+apps/sim/tools/registry.ts          # Tool registry entries for this service
+apps/sim/blocks/registry.ts         # Block registry entry for this service
+apps/sim/components/icons.tsx        # Icon definition
+apps/sim/lib/auth/auth.ts           # OAuth config — should use getCanonicalScopesForProvider()
+apps/sim/lib/oauth/oauth.ts         # OAuth provider config — single source of truth for scopes
+apps/sim/lib/oauth/utils.ts               # Scope utilities, SCOPE_DESCRIPTIONS for modal UI
+```
+
+## Step 2: Pull API Documentation
+
+Fetch the official API docs for the service. This is the **source of truth** for:
+- Endpoint URLs, HTTP methods, and auth headers
+- Required vs optional parameters
+- Parameter types and allowed values
+- Response shapes and field names
+- Pagination patterns (which param name, which response field)
+- Rate limits and error formats
+
+## Step 3: Validate Tools
+
+For **every** tool file, check:
+
+### Tool ID and Naming
+- [ ] Tool ID uses `snake_case`: `{service}_{action}` (e.g., `x_create_tweet`, `slack_send_message`)
+- [ ] Tool `name` is human-readable (e.g., `'X Create Tweet'`)
+- [ ] Tool `description` is a concise one-liner describing what it does
+- [ ] Tool `version` is set (`'1.0.0'` or `'2.0.0'` for V2)
+
+### Params
+- [ ] All required API params are marked `required: true`
+- [ ] All optional API params are marked `required: false`
+- [ ] Every param has explicit `required: true` or `required: false` — never omitted
+- [ ] Param types match the API (`'string'`, `'number'`, `'boolean'`, `'json'`)
+- [ ] Visibility is correct:
+  - `'hidden'` — ONLY for OAuth access tokens and system-injected params
+  - `'user-only'` — for API keys, credentials, and account-specific IDs the user must provide
+  - `'user-or-llm'` — for everything else (search queries, content, filters, IDs that could come from other blocks)
+- [ ] Every param has a `description` that explains what it does
+
+### Request
+- [ ] URL matches the API endpoint exactly (correct base URL, path segments, path params)
+- [ ] HTTP method matches the API spec (GET, POST, PUT, PATCH, DELETE)
+- [ ] Headers include correct auth pattern:
+  - OAuth: `Authorization: Bearer ${params.accessToken}`
+  - API Key: correct header name and format per the service's docs
+- [ ] `Content-Type` header is set for POST/PUT/PATCH requests
+- [ ] Body sends all required fields and only includes optional fields when provided
+- [ ] For GET requests with query params: URL is constructed correctly with query string
+- [ ] ID fields in URL paths are `.trim()`-ed to prevent copy-paste whitespace errors
+- [ ] Path params use template literals correctly: `` `https://api.service.com/v1/${params.id.trim()}` ``
+
+### Response / transformResponse
+- [ ] Correctly parses the API response (`await response.json()`)
+- [ ] Extracts the right fields from the response structure (e.g., `data.data` vs `data` vs `data.results`)
+- [ ] All nullable fields use `?? null`
+- [ ] All optional arrays use `?? []`
+- [ ] Error cases are handled: checks for missing/empty data and returns meaningful error
+- [ ] Does NOT do raw JSON dumps — extracts meaningful, individual fields
+
+### Outputs
+- [ ] All output fields match what the API actually returns
+- [ ] No fields are missing that the API provides and users would commonly need
+- [ ] No phantom fields defined that the API doesn't return
+- [ ] `optional: true` is set on fields that may not exist in all responses
+- [ ] When using `type: 'json'` and the shape is known, `properties` defines the inner fields
+- [ ] When using `type: 'array'`, `items` defines the item structure with `properties`
+- [ ] Field descriptions are accurate and helpful
+
+### Types (types.ts)
+- [ ] Has param interfaces for every tool (e.g., `XCreateTweetParams`)
+- [ ] Has response interfaces for every tool (extending `ToolResponse`)
+- [ ] Optional params use `?` in the interface (e.g., `replyTo?: string`)
+- [ ] Field names in types match actual API field names
+- [ ] Shared response types are properly reused (e.g., `XTweetResponse` shared across tweet tools)
+
+### Barrel Export (index.ts)
+- [ ] Every tool is exported
+- [ ] All types are re-exported (`export * from './types'`)
+- [ ] No orphaned exports (tools that don't exist)
+
+### Tool Registry (tools/registry.ts)
+- [ ] Every tool is imported and registered
+- [ ] Registry keys use snake_case and match tool IDs exactly
+- [ ] Entries are in alphabetical order within the file
+
+## Step 4: Validate Block
+
+### Block ↔ Tool Alignment (CRITICAL)
+
+This is the most important validation — the block must be perfectly aligned with every tool it references.
+
+For **each tool** in `tools.access`:
+- [ ] The operation dropdown has an option whose ID matches the tool ID (or the `tools.config.tool` function correctly maps to it)
+- [ ] Every **required** tool param (except `accessToken`) has a corresponding subBlock input that is:
+  - Shown when that operation is selected (correct `condition`)
+  - Marked as `required: true` (or conditionally required)
+- [ ] Every **optional** tool param has a corresponding subBlock input (or is intentionally omitted if truly never needed)
+- [ ] SubBlock `id` values are unique across the entire block — no duplicates even across different conditions
+- [ ] The `tools.config.tool` function returns the correct tool ID for every possible operation value
+- [ ] The `tools.config.params` function correctly maps subBlock IDs to tool param names when they differ
+
+### SubBlocks
+- [ ] Operation dropdown lists ALL tool operations available in `tools.access`
+- [ ] Dropdown option labels are human-readable and descriptive
+- [ ] Conditions use correct syntax:
+  - Single value: `{ field: 'operation', value: 'x_create_tweet' }`
+  - Multiple values (OR): `{ field: 'operation', value: ['x_create_tweet', 'x_delete_tweet'] }`
+  - Negation: `{ field: 'operation', value: 'delete', not: true }`
+  - Compound: `{ field: 'op', value: 'send', and: { field: 'type', value: 'dm' } }`
+- [ ] Condition arrays include ALL operations that use that field — none missing
+- [ ] `dependsOn` is set for fields that need other values (selectors depending on credential, cascading dropdowns)
+- [ ] SubBlock types match tool param types:
+  - Enum/fixed options → `dropdown`
+  - Free text → `short-input`
+  - Long text/content → `long-input`
+  - True/false → `dropdown` with Yes/No options (not `switch` unless purely UI toggle)
+  - Credentials → `oauth-input` with correct `serviceId`
+- [ ] Dropdown `value: () => 'default'` is set for dropdowns with a sensible default
+
+### Advanced Mode
+- [ ] Optional, rarely-used fields are set to `mode: 'advanced'`:
+  - Pagination tokens / next tokens
+  - Time range filters (start/end time)
+  - Sort order / direction options
+  - Max results / per page limits
+  - Reply settings / threading options
+  - Rarely used IDs (reply-to, quote-tweet, etc.)
+  - Exclude filters
+- [ ] **Required** fields are NEVER set to `mode: 'advanced'`
+- [ ] Fields that users fill in most of the time are NOT set to `mode: 'advanced'`
+
+### WandConfig
+- [ ] Timestamp fields have `wandConfig` with `generationType: 'timestamp'`
+- [ ] Comma-separated list fields have `wandConfig` with a descriptive prompt
+- [ ] Complex filter/query fields have `wandConfig` with format examples in the prompt
+- [ ] All `wandConfig` prompts end with "Return ONLY the [format] - no explanations, no extra text."
+- [ ] `wandConfig.placeholder` describes what to type in natural language
+
+### Tools Config
+- [ ] `tools.access` lists **every** tool ID the block can use — none missing
+- [ ] `tools.config.tool` returns the correct tool ID for each operation
+- [ ] Type coercions are in `tools.config.params` (runs at execution time), NOT in `tools.config.tool` (runs at serialization time before variable resolution)
+- [ ] `tools.config.params` handles:
+  - `Number()` conversion for numeric params that come as strings from inputs
+  - `Boolean` / string-to-boolean conversion for toggle params
+  - Empty string → `undefined` conversion for optional dropdown values
+  - Any subBlock ID → tool param name remapping
+- [ ] No `Number()`, `JSON.parse()`, or other coercions in `tools.config.tool` — these would destroy dynamic references like `<Block.output>`
+
+### Block Outputs
+- [ ] Outputs cover the key fields returned by ALL tools (not just one operation)
+- [ ] Output types are correct (`'string'`, `'number'`, `'boolean'`, `'json'`)
+- [ ] `type: 'json'` outputs either:
+  - Describe inner fields in the description string (GOOD): `'User profile (id, name, username, bio)'`
+  - Use nested output definitions (BEST): `{ id: { type: 'string' }, name: { type: 'string' } }`
+- [ ] No opaque `type: 'json'` with vague descriptions like `'Response data'`
+- [ ] Outputs that only appear for certain operations use `condition` if supported, or document which operations return them
+
+### Block Metadata
+- [ ] `type` is snake_case (e.g., `'x'`, `'cloudflare'`)
+- [ ] `name` is human-readable (e.g., `'X'`, `'Cloudflare'`)
+- [ ] `description` is a concise one-liner
+- [ ] `longDescription` provides detail for docs
+- [ ] `docsLink` points to `'https://docs.sim.ai/tools/{service}'`
+- [ ] `category` is `'tools'`
+- [ ] `bgColor` uses the service's brand color hex
+- [ ] `icon` references the correct icon component from `@/components/icons`
+- [ ] `authMode` is set correctly (`AuthMode.OAuth` or `AuthMode.ApiKey`)
+- [ ] Block is registered in `blocks/registry.ts` alphabetically
+
+### Block Inputs
+- [ ] `inputs` section lists all subBlock params that the block accepts
+- [ ] Input types match the subBlock types
+- [ ] When using `canonicalParamId`, inputs list the canonical ID (not the raw subBlock IDs)
+
+## Step 5: Validate OAuth Scopes (if OAuth service)
+
+Scopes are centralized — the single source of truth is `OAUTH_PROVIDERS` in `lib/oauth/oauth.ts`.
+
+- [ ] Scopes defined in `lib/oauth/oauth.ts` under `OAUTH_PROVIDERS[provider].services[service].scopes`
+- [ ] `auth.ts` uses `getCanonicalScopesForProvider(providerId)` — NOT a hardcoded array
+- [ ] Block `requiredScopes` uses `getScopesForService(serviceId)` — NOT a hardcoded array
+- [ ] No hardcoded scope arrays in `auth.ts` or block files (should all use utility functions)
+- [ ] Each scope has a human-readable description in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts`
+- [ ] No excess scopes that aren't needed by any tool
+
+## Step 6: Validate Pagination Consistency
+
+If any tools support pagination:
+- [ ] Pagination param names match the API docs (e.g., `pagination_token` vs `next_token` vs `cursor`)
+- [ ] Different API endpoints that use different pagination param names have separate subBlocks in the block
+- [ ] Pagination response fields (`nextToken`, `cursor`, etc.) are included in tool outputs
+- [ ] Pagination subBlocks are set to `mode: 'advanced'`
+
+## Step 7: Validate Error Handling
+
+- [ ] `transformResponse` checks for error conditions before accessing data
+- [ ] Error responses include meaningful messages (not just generic "failed")
+- [ ] HTTP error status codes are handled (check `response.ok` or status codes)
+
+## Step 8: Report and Fix
+
+### Report Format
+
+Group findings by severity:
+
+**Critical** (will cause runtime errors or incorrect behavior):
+- Wrong endpoint URL or HTTP method
+- Missing required params or wrong `required` flag
+- Incorrect response field mapping (accessing wrong path in response)
+- Missing error handling that would cause crashes
+- Tool ID mismatch between tool file, registry, and block `tools.access`
+- OAuth scopes missing in `auth.ts` that tools need
+- `tools.config.tool` returning wrong tool ID for an operation
+- Type coercions in `tools.config.tool` instead of `tools.config.params`
+
+**Warning** (follows conventions incorrectly or has usability issues):
+- Optional field not set to `mode: 'advanced'`
+- Missing `wandConfig` on timestamp/complex fields
+- Wrong `visibility` on params (e.g., `'hidden'` instead of `'user-or-llm'`)
+- Missing `optional: true` on nullable outputs
+- Opaque `type: 'json'` without property descriptions
+- Missing `.trim()` on ID fields in request URLs
+- Missing `?? null` on nullable response fields
+- Block condition array missing an operation that uses that field
+- Hardcoded scope arrays instead of using `getScopesForService()` / `getCanonicalScopesForProvider()`
+- Missing scope description in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts`
+
+**Suggestion** (minor improvements):
+- Better description text
+- Inconsistent naming across tools
+- Missing `longDescription` or `docsLink`
+- Pagination fields that could benefit from `wandConfig`
+
+### Fix All Issues
+
+After reporting, fix every **critical** and **warning** issue. Apply **suggestions** where they don't add unnecessary complexity.
+
+### Validation Output
+
+After fixing, confirm:
+1. `bun run lint` passes with no fixes needed
+2. TypeScript compiles clean (no type errors)
+3. Re-read all modified files to verify fixes are correct
+
+## Checklist Summary
+
+- [ ] Read ALL tool files, block, types, index, and registries
+- [ ] Pulled and read official API documentation
+- [ ] Validated every tool's ID, params, request, response, outputs, and types against API docs
+- [ ] Validated block ↔ tool alignment (every tool param has a subBlock, every condition is correct)
+- [ ] Validated advanced mode on optional/rarely-used fields
+- [ ] Validated wandConfig on timestamps and complex inputs
+- [ ] Validated tools.config mapping, tool selector, and type coercions
+- [ ] Validated block outputs match what tools return, with typed JSON where possible
+- [ ] Validated OAuth scopes use centralized utilities (getScopesForService, getCanonicalScopesForProvider) — no hardcoded arrays
+- [ ] Validated scope descriptions exist in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts` for all scopes
+- [ ] Validated pagination consistency across tools and block
+- [ ] Validated error handling (error checks, meaningful messages)
+- [ ] Validated registry entries (tools and block, alphabetical, correct imports)
+- [ ] Reported all issues grouped by severity
+- [ ] Fixed all critical and warning issues
+- [ ] Ran `bun run lint` after fixes
+- [ ] Verified TypeScript compiles clean
--- a/.claude/rules/emcn-components.md
+++ b/.claude/rules/emcn-components.md
@@ -0,0 +1,35 @@
+---
+paths:
+  - "apps/sim/components/emcn/**"
+---
+
+# EMCN Components
+
+Import from `@/components/emcn`, never from subpaths (except CSS files).
+
+## CVA vs Direct Styles
+
+**Use CVA when:** 2+ variants (primary/secondary, sm/md/lg)
+
+```tsx
+const buttonVariants = cva('base-classes', {
+  variants: { variant: { default: '...', primary: '...' } }
+})
+export { Button, buttonVariants }
+```
+
+**Use direct className when:** Single consistent style, no variations
+
+```tsx
+function Label({ className, ...props }) {
+  return <Primitive className={cn('style-classes', className)} {...props} />
+}
+```
+
+## Rules
+
+- Use Radix UI primitives for accessibility
+- Export component and variants (if using CVA)
+- TSDoc with usage examples
+- Consistent tokens: `font-medium`, `text-[12px]`, `rounded-[4px]`
+- `transition-colors` for hover states
--- a/.claude/rules/global.md
+++ b/.claude/rules/global.md
@@ -0,0 +1,13 @@
+# 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`.
--- a/.claude/rules/sim-architecture.md
+++ b/.claude/rules/sim-architecture.md
@@ -0,0 +1,56 @@
+---
+paths:
+  - "apps/sim/**"
+---
+
+# Sim App Architecture
+
+## Core Principles
+1. **Single Responsibility**: Each component, hook, store has one clear purpose
+2. **Composition Over Complexity**: Break down complex logic into smaller pieces
+3. **Type Safety First**: TypeScript interfaces for all props, state, return types
+4. **Predictable State**: Zustand for global state, useState for UI-only concerns
+
+## Root-Level Structure
+
+```
+apps/sim/
+├── 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
+```
+
+## Feature Organization
+
+Features live under `app/workspace/[workspaceId]/`:
+
+```
+feature/
+├── components/          # Feature components
+├── hooks/               # Feature-scoped hooks
+├── utils/               # Feature-scoped utilities (2+ consumers)
+├── feature.tsx          # Main component
+└── page.tsx             # Next.js page entry
+```
+
+## Naming Conventions
+- **Components**: PascalCase (`WorkflowList`)
+- **Hooks**: `use` prefix (`useWorkflowOperations`)
+- **Files**: kebab-case (`workflow-list.tsx`)
+- **Stores**: `stores/feature/store.ts`
+- **Constants**: SCREAMING_SNAKE_CASE
+- **Interfaces**: PascalCase with suffix (`WorkflowListProps`)
+
+## Utils Rules
+
+- **Never create `utils.ts` for single consumer** - inline it
+- **Create `utils.ts` when** 2+ files need the same helper
+- **Check existing sources** before duplicating (`lib/` has many utilities)
+- **Location**: `lib/` (app-wide) → `feature/utils/` (feature-scoped) → inline (single-use)
--- a/.claude/rules/sim-components.md
+++ b/.claude/rules/sim-components.md
@@ -0,0 +1,48 @@
+---
+paths:
+  - "apps/sim/**/*.tsx"
+---
+
+# Component Patterns
+
+## Structure Order
+
+```typescript
+'use client' // Only if using hooks
+
+// Imports (external → internal)
+// Constants at module level
+const CONFIG = { SPACING: 8 } as const
+
+// Props interface
+interface ComponentProps {
+  requiredProp: string
+  optionalProp?: boolean
+}
+
+export function Component({ requiredProp, optionalProp = false }: ComponentProps) {
+  // a. Refs
+  // b. External hooks (useParams, useRouter)
+  // c. Store hooks
+  // d. Custom hooks
+  // e. Local state
+  // f. useMemo
+  // g. useCallback
+  // h. useEffect
+  // i. Return JSX
+}
+```
+
+## Rules
+
+1. `'use client'` only when using React hooks
+2. Always define props interface
+3. Extract constants with `as const`
+4. Semantic HTML (`aside`, `nav`, `article`)
+5. Optional chain callbacks: `onAction?.(id)`
+
+## Component Extraction
+
+**Extract when:** 50+ lines, used in 2+ files, or has own state/logic
+
+**Keep inline when:** < 10 lines, single use, purely presentational
--- a/.claude/rules/sim-hooks.md
+++ b/.claude/rules/sim-hooks.md
@@ -0,0 +1,55 @@
+---
+paths:
+  - "apps/sim/**/use-*.ts"
+  - "apps/sim/**/hooks/**/*.ts"
+---
+
+# Hook Patterns
+
+## Structure
+
+```typescript
+interface UseFeatureProps {
+  id: string
+  onSuccess?: (result: Result) => void
+}
+
+export function useFeature({ id, onSuccess }: UseFeatureProps) {
+  // 1. Refs for stable dependencies
+  const idRef = useRef(id)
+  const onSuccessRef = useRef(onSuccess)
+
+  // 2. State
+  const [data, setData] = useState<Data | null>(null)
+  const [isLoading, setIsLoading] = useState(false)
+
+  // 3. Sync refs
+  useEffect(() => {
+    idRef.current = id
+    onSuccessRef.current = onSuccess
+  }, [id, onSuccess])
+
+  // 4. Operations (useCallback with empty deps when using refs)
+  const fetchData = useCallback(async () => {
+    setIsLoading(true)
+    try {
+      const result = await fetch(`/api/${idRef.current}`).then(r => r.json())
+      setData(result)
+      onSuccessRef.current?.(result)
+    } finally {
+      setIsLoading(false)
+    }
+  }, [])
+
+  return { data, isLoading, fetchData }
+}
+```
+
+## Rules
+
+1. Single responsibility per hook
+2. Props interface required
+3. Refs for stable callback dependencies
+4. Wrap returned functions in useCallback
+5. Always try/catch async operations
+6. Track loading/error states
--- a/.claude/rules/sim-imports.md
+++ b/.claude/rules/sim-imports.md
@@ -0,0 +1,62 @@
+---
+paths:
+  - "apps/sim/**/*.ts"
+  - "apps/sim/**/*.tsx"
+---
+
+# Import Patterns
+
+## Absolute Imports
+
+**Always use absolute imports.** Never use relative imports.
+
+```typescript
+// ✓ Good
+import { useWorkflowStore } from '@/stores/workflows/store'
+import { Button } from '@/components/ui/button'
+
+// ✗ Bad
+import { useWorkflowStore } from '../../../stores/workflows/store'
+```
+
+## Barrel Exports
+
+Use barrel exports (`index.ts`) when a folder has 3+ exports. Import from barrel, not individual files.
+
+```typescript
+// ✓ Good
+import { Dashboard, Sidebar } from '@/app/workspace/[workspaceId]/logs/components'
+
+// ✗ Bad
+import { Dashboard } from '@/app/workspace/[workspaceId]/logs/components/dashboard/dashboard'
+```
+
+## No Re-exports
+
+Do not re-export from non-barrel files. Import directly from the source.
+
+```typescript
+// ✓ Good - import from where it's declared
+import { CORE_TRIGGER_TYPES } from '@/stores/logs/filters/types'
+
+// ✗ Bad - re-exporting in utils.ts then importing from there
+import { CORE_TRIGGER_TYPES } from '@/app/workspace/.../utils'
+```
+
+## Import Order
+
+1. React/core libraries
+2. External libraries
+3. UI components (`@/components/emcn`, `@/components/ui`)
+4. Utilities (`@/lib/...`)
+5. Stores (`@/stores/...`)
+6. Feature imports
+7. CSS imports
+
+## Type Imports
+
+Use `type` keyword for type-only imports:
+
+```typescript
+import type { WorkflowLog } from '@/stores/logs/types'
+```
--- a/.claude/rules/sim-integrations.md
+++ b/.claude/rules/sim-integrations.md
@@ -0,0 +1,287 @@
+---
+paths:
+  - "apps/sim/tools/**"
+  - "apps/sim/blocks/**"
+  - "apps/sim/triggers/**"
+---
+
+# Adding Integrations
+
+## Overview
+
+Adding a new integration typically requires:
+1. **Tools** - API operations (`tools/{service}/`)
+2. **Block** - UI component (`blocks/blocks/{service}.ts`)
+3. **Icon** - SVG icon (`components/icons.tsx`)
+4. **Trigger** (optional) - Webhooks/polling (`triggers/{service}/`)
+
+Always look up the service's API docs first.
+
+## 1. Tools (`tools/{service}/`)
+
+```
+tools/{service}/
+├── index.ts           # Export all tools
+├── types.ts           # Params/response types
+├── {action}.ts        # Individual tool (e.g., send_message.ts)
+└── ...
+```
+
+**Tool file structure:**
+
+```typescript
+// tools/{service}/{action}.ts
+import type { {Service}Params, {Service}Response } from '@/tools/{service}/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const {service}{Action}Tool: ToolConfig<{Service}Params, {Service}Response> = {
+  id: '{service}_{action}',
+  name: '{Service} {Action}',
+  description: 'What this tool does',
+  version: '1.0.0',
+  oauth: { required: true, provider: '{service}' }, // if OAuth
+  params: { /* param definitions */ },
+  request: {
+    url: '/api/tools/{service}/{action}',
+    method: 'POST',
+    headers: () => ({ 'Content-Type': 'application/json' }),
+    body: (params) => ({ ...params }),
+  },
+  transformResponse: async (response) => {
+    const data = await response.json()
+    if (!data.success) throw new Error(data.error)
+    return { success: true, output: data.output }
+  },
+  outputs: { /* output definitions */ },
+}
+```
+
+**Register in `tools/registry.ts`:**
+
+```typescript
+import { {service}{Action}Tool } from '@/tools/{service}'
+// Add to registry object
+{service}_{action}: {service}{Action}Tool,
+```
+
+## 2. Block (`blocks/blocks/{service}.ts`)
+
+```typescript
+import { {Service}Icon } from '@/components/icons'
+import type { BlockConfig } from '@/blocks/types'
+import type { {Service}Response } from '@/tools/{service}/types'
+
+export const {Service}Block: BlockConfig<{Service}Response> = {
+  type: '{service}',
+  name: '{Service}',
+  description: 'Short description',
+  longDescription: 'Detailed description',
+  category: 'tools',
+  bgColor: '#hexcolor',
+  icon: {Service}Icon,
+  subBlocks: [ /* see SubBlock Properties below */ ],
+  tools: {
+    access: ['{service}_{action}', ...],
+    config: {
+      tool: (params) => `{service}_${params.operation}`,
+      params: (params) => ({ ...params }),
+    },
+  },
+  inputs: { /* input definitions */ },
+  outputs: { /* output definitions */ },
+}
+```
+
+### SubBlock Properties
+
+```typescript
+{
+  id: 'fieldName',           // Unique identifier
+  title: 'Field Label',      // UI label
+  type: 'short-input',       // See SubBlock Types below
+  placeholder: 'Hint text',
+  required: true,            // See Required below
+  condition: { ... },        // See Condition below
+  dependsOn: ['otherField'], // See DependsOn below
+  mode: 'basic',             // 'basic' | 'advanced' | 'both' | 'trigger'
+}
+```
+
+**SubBlock Types:** `short-input`, `long-input`, `dropdown`, `code`, `switch`, `slider`, `oauth-input`, `channel-selector`, `user-selector`, `file-upload`, etc.
+
+### `condition` - Show/hide based on another field
+
+```typescript
+// Show when operation === 'send'
+condition: { field: 'operation', value: 'send' }
+
+// Show when operation is 'send' OR 'read'
+condition: { field: 'operation', value: ['send', 'read'] }
+
+// Show when operation !== 'send'
+condition: { field: 'operation', value: 'send', not: true }
+
+// Complex: NOT in list AND another condition
+condition: {
+  field: 'operation',
+  value: ['list_channels', 'list_users'],
+  not: true,
+  and: { field: 'destinationType', value: 'dm', not: true }
+}
+```
+
+### `required` - Field validation
+
+```typescript
+// Always required
+required: true
+
+// Conditionally required (same syntax as condition)
+required: { field: 'operation', value: 'send' }
+```
+
+### `dependsOn` - Clear field when dependencies change
+
+```typescript
+// Clear when credential changes
+dependsOn: ['credential']
+
+// Clear when authMethod changes AND (credential OR botToken) changes
+dependsOn: { all: ['authMethod'], any: ['credential', 'botToken'] }
+```
+
+### `mode` - When to show field
+
+- `'basic'` - Only in basic mode (default UI)
+- `'advanced'` - Only in advanced mode (manual input)
+- `'both'` - Show in both modes (default)
+- `'trigger'` - Only when block is used as trigger
+
+### `canonicalParamId` - Link basic/advanced alternatives
+
+Use to map multiple UI inputs to a single logical parameter:
+
+```typescript
+// Basic mode: Visual selector
+{
+  id: 'fileSelector',
+  type: 'file-selector',
+  mode: 'basic',
+  canonicalParamId: 'fileId',
+  required: true,
+},
+// Advanced mode: Manual input
+{
+  id: 'manualFileId',
+  type: 'short-input',
+  mode: 'advanced',
+  canonicalParamId: 'fileId',
+  required: true,
+},
+```
+
+**Critical Rules:**
+- `canonicalParamId` must NOT match any subblock's `id`
+- `canonicalParamId` must be unique per operation/condition context
+- **Required consistency:** All subblocks in a canonical group must have the same `required` status
+- **Inputs section:** Must list canonical param IDs (e.g., `fileId`), NOT raw subblock IDs
+- **Params function:** Must use canonical param IDs (raw IDs are deleted after canonical transformation)
+
+**Register in `blocks/registry.ts`:**
+
+```typescript
+import { {Service}Block } from '@/blocks/blocks/{service}'
+// Add to registry object (alphabetically)
+{service}: {Service}Block,
+```
+
+## 3. Icon (`components/icons.tsx`)
+
+```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 path from service's brand assets */}
+    </svg>
+  )
+}
+```
+
+## 4. Trigger (`triggers/{service}/`) - Optional
+
+```
+triggers/{service}/
+├── index.ts           # Export all triggers
+├── webhook.ts         # Webhook handler
+├── utils.ts           # Shared utilities
+└── {event}.ts         # Specific event handlers
+```
+
+**Register in `triggers/registry.ts`:**
+
+```typescript
+import { {service}WebhookTrigger } from '@/triggers/{service}'
+// Add to TRIGGER_REGISTRY
+{service}_webhook: {service}WebhookTrigger,
+```
+
+## File Handling
+
+When integrations handle file uploads/downloads, use `UserFile` objects consistently.
+
+### File Input (Uploads)
+
+1. **Block subBlocks:** Use basic/advanced mode pattern with `canonicalParamId`
+2. **Normalize in block config:** Use `normalizeFileInput` from `@/blocks/utils`
+3. **Internal API route:** Create route that uses `downloadFileFromStorage` to get file content
+4. **Tool routes to internal API:** Don't call external APIs directly with files
+
+```typescript
+// In block tools.config:
+import { normalizeFileInput } from '@/blocks/utils'
+
+const normalizedFile = normalizeFileInput(
+  params.uploadFile || params.fileRef || params.fileContent,
+  { single: true }
+)
+if (normalizedFile) params.file = normalizedFile
+```
+
+### File Output (Downloads)
+
+Use `FileToolProcessor` in tool `transformResponse` to store files:
+
+```typescript
+import { FileToolProcessor } from '@/executor/utils/file-tool-processor'
+
+const processor = new FileToolProcessor(context)
+const file = await processor.processFileData({
+  data: base64Content,
+  mimeType: 'application/pdf',
+  filename: 'doc.pdf',
+})
+```
+
+### Key Helpers
+
+| 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 Buffer from UserFile |
+| `FileToolProcessor` | `@/executor/utils/file-tool-processor` | Process tool output files |
+
+## Checklist
+
+- [ ] Look up API docs for the service
+- [ ] Create `tools/{service}/types.ts` with proper types
+- [ ] Create tool files for each operation
+- [ ] Create `tools/{service}/index.ts` barrel export
+- [ ] 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 triggers in `triggers/{service}/`
+- [ ] (Optional) Register triggers in `triggers/registry.ts`
+- [ ] (If file uploads) Create internal API route with `downloadFileFromStorage`
+- [ ] (If file uploads) Use `normalizeFileInput` in block config
--- a/.claude/rules/sim-queries.md
+++ b/.claude/rules/sim-queries.md
@@ -0,0 +1,66 @@
+---
+paths:
+  - "apps/sim/hooks/queries/**/*.ts"
+---
+
+# React Query Patterns
+
+All React Query hooks live in `hooks/queries/`.
+
+## Query Key Factory
+
+Every query file defines a keys factory:
+
+```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,
+}
+```
+
+## File Structure
+
+```typescript
+// 1. Query keys factory
+// 2. Types (if needed)
+// 3. Private fetch functions
+// 4. Exported hooks
+```
+
+## Query Hook
+
+```typescript
+export function useEntityList(workspaceId?: string, options?: { enabled?: boolean }) {
+  return useQuery({
+    queryKey: entityKeys.list(workspaceId),
+    queryFn: () => fetchEntities(workspaceId as string),
+    enabled: Boolean(workspaceId) && (options?.enabled ?? true),
+    staleTime: 60 * 1000,
+    placeholderData: keepPreviousData,
+  })
+}
+```
+
+## Mutation Hook
+
+```typescript
+export function useCreateEntity() {
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: async (variables) => { /* fetch POST */ },
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: entityKeys.all }),
+  })
+}
+```
+
+## Optimistic Updates
+
+For optimistic mutations syncing with Zustand, use `createOptimisticMutationHandlers` from `@/hooks/queries/utils/optimistic-mutation`.
+
+## Naming
+
+- **Keys**: `entityKeys`
+- **Query hooks**: `useEntity`, `useEntityList`
+- **Mutation hooks**: `useCreateEntity`, `useUpdateEntity`
+- **Fetch functions**: `fetchEntity` (private)
--- a/.claude/rules/sim-stores.md
+++ b/.claude/rules/sim-stores.md
@@ -0,0 +1,71 @@
+---
+paths:
+  - "apps/sim/**/store.ts"
+  - "apps/sim/**/stores/**/*.ts"
+---
+
+# Zustand Store Patterns
+
+Stores live in `stores/`. Complex stores split into `store.ts` + `types.ts`.
+
+## Basic Store
+
+```typescript
+import { create } from 'zustand'
+import { devtools } from 'zustand/middleware'
+import type { FeatureState } from '@/stores/feature/types'
+
+const initialState = { items: [] as Item[], activeId: null as string | null }
+
+export const useFeatureStore = create<FeatureState>()(
+  devtools(
+    (set, get) => ({
+      ...initialState,
+      setItems: (items) => set({ items }),
+      addItem: (item) => set((state) => ({ items: [...state.items, item] })),
+      reset: () => set(initialState),
+    }),
+    { name: 'feature-store' }
+  )
+)
+```
+
+## Persisted Store
+
+```typescript
+import { create } from 'zustand'
+import { persist } from 'zustand/middleware'
+
+export const useFeatureStore = create<FeatureState>()(
+  persist(
+    (set) => ({
+      width: 300,
+      setWidth: (width) => set({ width }),
+      _hasHydrated: false,
+      setHasHydrated: (v) => set({ _hasHydrated: v }),
+    }),
+    {
+      name: 'feature-state',
+      partialize: (state) => ({ width: state.width }),
+      onRehydrateStorage: () => (state) => state?.setHasHydrated(true),
+    }
+  )
+)
+```
+
+## Rules
+
+1. Use `devtools` middleware (named stores)
+2. Use `persist` only when data should survive reload
+3. `partialize` to persist only necessary state
+4. `_hasHydrated` pattern for persisted stores needing hydration tracking
+5. Immutable updates only
+6. `set((state) => ...)` when depending on previous state
+7. Provide `reset()` action
+
+## Outside React
+
+```typescript
+const items = useFeatureStore.getState().items
+useFeatureStore.setState({ items: newItems })
+```
--- a/.claude/rules/sim-styling.md
+++ b/.claude/rules/sim-styling.md
@@ -0,0 +1,41 @@
+---
+paths:
+  - "apps/sim/**/*.tsx"
+  - "apps/sim/**/*.css"
+---
+
+# Styling Rules
+
+## Tailwind
+
+1. **No inline styles** - Use Tailwind classes
+2. **No duplicate dark classes** - Skip `dark:` when value matches light mode
+3. **Exact values** - `text-[14px]`, `h-[26px]`
+4. **Transitions** - `transition-colors` for interactive states
+
+## Conditional Classes
+
+```typescript
+import { cn } from '@/lib/utils'
+
+<div className={cn(
+  'base-classes',
+  isActive && 'active-classes',
+  disabled ? 'opacity-60' : 'hover:bg-accent'
+)} />
+```
+
+## CSS Variables
+
+For dynamic values (widths, heights) synced with stores:
+
+```typescript
+// In store
+setWidth: (width) => {
+  set({ width })
+  document.documentElement.style.setProperty('--sidebar-width', `${width}px`)
+}
+
+// In component
+<aside style={{ width: 'var(--sidebar-width)' }} />
+```
--- a/.claude/rules/sim-testing.md
+++ b/.claude/rules/sim-testing.md
@@ -0,0 +1,217 @@
+---
+paths:
+  - "apps/sim/**/*.test.ts"
+  - "apps/sim/**/*.test.tsx"
+---
+
+# Testing Patterns
+
+Use Vitest. Test files: `feature.ts` → `feature.test.ts`
+
+## Global Mocks (vitest.setup.ts)
+
+These modules are mocked globally — do NOT re-mock them in test files unless you need to override behavior:
+
+- `@sim/db` → `databaseMock`
+- `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 { createMockRequest } from '@sim/testing'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { mockGetSession } = vi.hoisted(() => ({
+  mockGetSession: vi.fn(),
+}))
+
+vi.mock('@/lib/auth', () => ({
+  auth: { api: { getSession: vi.fn() } },
+  getSession: mockGetSession,
+}))
+
+import { GET, POST } from '@/app/api/my-route/route'
+
+describe('my route', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockGetSession.mockResolvedValue({ user: { id: 'user-1' } })
+  })
+
+  it('returns data', async () => {
+    const req = createMockRequest('GET')
+    const res = await GET(req)
+    expect(res.status).toBe(200)
+  })
+})
+```
+
+## Performance Rules (Critical)
+
+### NEVER use `vi.resetModules()` + `vi.doMock()` + `await import()`
+
+This is the #1 cause of slow tests. It forces complete module re-evaluation per test.
+
+```typescript
+// BAD — forces module re-evaluation every test (~50-100ms each)
+beforeEach(() => {
+  vi.resetModules()
+  vi.doMock('@/lib/auth', () => ({ getSession: vi.fn() }))
+})
+it('test', async () => {
+  const { GET } = await import('./route')  // slow dynamic import
+})
+
+// GOOD — module loaded once, mocks reconfigured per test (~1ms each)
+const { mockGetSession } = vi.hoisted(() => ({
+  mockGetSession: vi.fn(),
+}))
+vi.mock('@/lib/auth', () => ({ getSession: mockGetSession }))
+import { GET } from '@/app/api/my-route/route'
+
+beforeEach(() => { vi.clearAllMocks() })
+it('test', () => {
+  mockGetSession.mockResolvedValue({ user: { id: '1' } })
+})
+```
+
+**Only exception:** Singleton modules that cache state at module scope (e.g., Redis clients, connection pools). These genuinely need `vi.resetModules()` + dynamic import to get a fresh instance per test.
+
+### NEVER use `vi.importActual()`
+
+This defeats the purpose of mocking by loading the real module and all its dependencies.
+
+```typescript
+// BAD — loads real module + all transitive deps
+vi.mock('@/lib/workspaces/utils', async () => {
+  const actual = await vi.importActual('@/lib/workspaces/utils')
+  return { ...actual, myFn: vi.fn() }
+})
+
+// GOOD — mock everything, only implement what tests need
+vi.mock('@/lib/workspaces/utils', () => ({
+  myFn: vi.fn(),
+  otherFn: vi.fn(),
+}))
+```
+
+### 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 test data.
+
+| Category | Utilities |
+|----------|-----------|
+| **Mocks** | `loggerMock`, `databaseMock`, `drizzleOrmMock`, `setupGlobalFetchMock()` |
+| **Factories** | `createSession()`, `createWorkflowRecord()`, `createBlock()`, `createExecutionContext()` |
+| **Builders** | `WorkflowBuilder`, `ExecutionContextBuilder` |
+| **Assertions** | `expectWorkflowAccessGranted()`, `expectBlockExecuted()` |
+| **Requests** | `createMockRequest()`, `createEnvMock()` |
+
+## Rules Summary
+
+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()`
--- a/.claude/rules/sim-typescript.md
+++ b/.claude/rules/sim-typescript.md
@@ -0,0 +1,21 @@
+---
+paths:
+  - "apps/sim/**/*.ts"
+  - "apps/sim/**/*.tsx"
+---
+
+# TypeScript Rules
+
+1. **No `any`** - Use proper types or `unknown` with type guards
+2. **Props interface** - Always define for components
+3. **Const assertions** - `as const` for constant objects/arrays
+4. **Ref types** - Explicit: `useRef<HTMLDivElement>(null)`
+5. **Type imports** - `import type { X }` for type-only imports
+
+```typescript
+// ✗ Bad
+const handleClick = (e: any) => {}
+
+// ✓ Good
+const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {}
+```
--- a/.cursor/commands/council.md
+++ b/.cursor/commands/council.md
@@ -0,0 +1,7 @@
+Based on the given area of interest, please:
+
+1. Dig around the codebase in terms of that given area of interest, gather general information such as keywords and architecture overview.
+2. Spawn off n=10 (unless specified otherwise) task agents to dig deeper into the codebase in terms of that given area of interest, some of them should be out of the box for variance.
+3. Once the task agents are done, use the information to do what the user wants.
+
+If user is in plan mode, use the information to create the plan.
--- a/.cursor/rules/emcn-components.mdc
+++ b/.cursor/rules/emcn-components.mdc
@@ -1,45 +1,35 @@
 ---
-description: EMCN component library patterns with CVA
+description: EMCN component library patterns
 globs: ["apps/sim/components/emcn/**"]
 ---

-# EMCN Component Guidelines
+# EMCN Components

-## When to Use CVA vs Direct Styles
+Import from `@/components/emcn`, never from subpaths (except CSS files).

-**Use CVA (class-variance-authority) when:**
- 2+ visual variants (primary, secondary, outline)
- Multiple sizes or state variations
- Example: Button with variants
+## CVA vs Direct Styles

-**Use direct className when:**
- Single consistent style
- No variations needed
- Example: Label with one style
+**Use CVA when:** 2+ variants (primary/secondary, sm/md/lg)

-## Patterns
-
-**With CVA:**
 ```tsx
 const buttonVariants = cva('base-classes', {
-  variants: { 
-    variant: { default: '...', primary: '...' },
-    size: { sm: '...', md: '...' }
-  }
+  variants: { variant: { default: '...', primary: '...' } }
 })
 export { Button, buttonVariants }
 ```

-**Without CVA:**
+**Use direct className when:** Single consistent style, no variations
+
 ```tsx
 function Label({ className, ...props }) {
-  return <Primitive className={cn('single-style-classes', className)} {...props} />
+  return <Primitive className={cn('style-classes', className)} {...props} />
 }
 ```

 ## Rules
+
 - Use Radix UI primitives for accessibility
 - Export component and variants (if using CVA)
 - TSDoc with usage examples
 - Consistent tokens: `font-medium`, `text-[12px]`, `rounded-[4px]`
- Always use `transition-colors` for hover states
+- `transition-colors` for hover states
--- a/.cursor/rules/global.mdc
+++ b/.cursor/rules/global.mdc
@@ -8,7 +8,7 @@ alwaysApply: true
 You are a professional software engineer. All code must follow best practices: accurate, readable, clean, and efficient.

 ## Logging
-Use `logger.info`, `logger.warn`, `logger.error` instead of `console.log`.
+Import `createLogger` from `@sim/logger`. Use `logger.info`, `logger.warn`, `logger.error` instead of `console.log`.

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

-## File Organization
+## Root-Level 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
+```
+
+## Feature Organization
+
+Features live under `app/workspace/[workspaceId]/`:

 ```
 feature/
-├── components/        # Feature components
-│   └── sub-feature/   # Sub-feature with own components
-├── hooks/             # Custom hooks
-└── feature.tsx        # Main component
+├── components/          # Feature components
+├── hooks/               # Feature-scoped hooks
+├── utils/               # Feature-scoped utilities (2+ consumers)
+├── feature.tsx          # Main component
+└── page.tsx             # Next.js page entry
 ```

 ## Naming Conventions
- **Components**: PascalCase (`WorkflowList`, `TriggerPanel`)
- **Hooks**: camelCase with `use` prefix (`useWorkflowOperations`)
- **Files**: kebab-case matching export (`workflow-list.tsx`)
- **Stores**: kebab-case in stores/ (`sidebar/store.ts`)
+- **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`)

-## State Management
+## Utils Rules

-**useState**: UI-only concerns (dropdown open, hover, form inputs)
-**Zustand**: Shared state, persistence, global app state
-**useRef**: DOM refs, avoiding dependency issues, mutable non-reactive values
-
-## Component Extraction
-
-**Extract to separate file when:**
- Complex (50+ lines)
- Used across 2+ files
- Has own state/logic
-
-**Keep inline when:**
- Simple (< 10 lines)
- Used in only 1 file
- Purely presentational
-
-**Never import utilities from another component file.** Extract shared helpers to `lib/` or `utils/`.
-
-## Utils Files
-
-**Never create a `utils.ts` file for a single consumer.** Inline the logic directly in the consuming component.
-
-**Create `utils.ts` when:**
- 2+ files import the same helper
-
-**Prefer existing sources of truth:**
- Before duplicating logic, check if a centralized helper already exists (e.g., `lib/logs/get-trigger-options.ts`)
- Import from the source of truth rather than creating wrapper functions
-
-**Location hierarchy:**
- `lib/` — App-wide utilities (auth, billing, core)
- `feature/utils.ts` — Feature-scoped utilities (used by 2+ components in the feature)
- Inline — Single-use helpers (define directly in the component)
+- **Never create `utils.ts` for single consumer** - inline it
+- **Create `utils.ts` when** 2+ files need the same helper
+- **Check existing sources** before duplicating (`lib/` has many utilities)
+- **Location**: `lib/` (app-wide) → `feature/utils/` (feature-scoped) → inline (single-use)
--- a/.cursor/rules/sim-components.mdc
+++ b/.cursor/rules/sim-components.mdc
@@ -6,59 +6,43 @@ globs: ["apps/sim/**/*.tsx"]
 # Component Patterns

 ## Structure Order
+
 ```typescript
 'use client' // Only if using hooks

-// 1. Imports (external → internal → relative)
-// 2. Constants at module level
+// Imports (external → internal)
+// Constants at module level
 const CONFIG = { SPACING: 8 } as const

-// 3. Props interface with TSDoc
+// Props interface
 interface ComponentProps {
-  /** Description */
  requiredProp: string
  optionalProp?: boolean
 }

-// 4. Component with TSDoc
 export function Component({ requiredProp, optionalProp = false }: ComponentProps) {
  // a. Refs
  // b. External hooks (useParams, useRouter)
  // c. Store hooks
  // d. Custom hooks
  // e. Local state
-  // f. useMemo computations
-  // g. useCallback handlers
+  // f. useMemo
+  // g. useCallback
  // h. useEffect
  // i. Return JSX
 }
 ```

 ## Rules
-1. Add `'use client'` when using React hooks
+
+1. `'use client'` only when using React hooks
 2. Always define props interface
-3. TSDoc on component: description, @param, @returns
-4. Extract constants with `as const`
-5. Use Tailwind only, no inline styles
-6. Semantic HTML (`aside`, `nav`, `article`)
-7. Include ARIA attributes where appropriate
-8. Optional chain callbacks: `onAction?.(id)`
+3. Extract constants with `as const`
+4. Semantic HTML (`aside`, `nav`, `article`)
+5. Optional chain callbacks: `onAction?.(id)`

-## Factory Pattern with Caching
+## Component Extraction

-When generating components for a specific signature (e.g., icons):
+**Extract when:** 50+ lines, used in 2+ files, or has own state/logic

-```typescript
-const cache = new Map<string, React.ComponentType<{ className?: string }>>()
-
-function getColorIcon(color: string) {
-  if (cache.has(color)) return cache.get(color)!
-  
-  const Icon = ({ className }: { className?: string }) => (
-    <div className={cn(className, 'rounded-[3px]')} style={{ backgroundColor: color, width: 10, height: 10 }} />
-  )
-  Icon.displayName = `ColorIcon(${color})`
-  cache.set(color, Icon)
-  return Icon
-}
-```
+**Keep inline when:** < 10 lines, single use, purely presentational
--- a/.cursor/rules/sim-hooks.mdc
+++ b/.cursor/rules/sim-hooks.mdc
@@ -6,21 +6,13 @@ globs: ["apps/sim/**/use-*.ts", "apps/sim/**/hooks/**/*.ts"]
 # Hook Patterns

 ## Structure
+
 ```typescript
-import { createLogger } from '@/lib/logs/console/logger'
-
-const logger = createLogger('useFeatureName')
-
 interface UseFeatureProps {
  id: string
  onSuccess?: (result: Result) => void
 }

-/**
- * Hook description.
- * @param props - Configuration
- * @returns State and operations
- */
 export function useFeature({ id, onSuccess }: UseFeatureProps) {
  // 1. Refs for stable dependencies
  const idRef = useRef(id)
@@ -29,7 +21,6 @@ export function useFeature({ id, onSuccess }: UseFeatureProps) {
  // 2. State
  const [data, setData] = useState<Data | null>(null)
  const [isLoading, setIsLoading] = useState(false)
-  const [error, setError] = useState<Error | null>(null)

  // 3. Sync refs
  useEffect(() => {
@@ -37,32 +28,27 @@ export function useFeature({ id, onSuccess }: UseFeatureProps) {
    onSuccessRef.current = onSuccess
  }, [id, onSuccess])

-  // 4. Operations with useCallback
+  // 4. Operations (useCallback with empty deps when using refs)
  const fetchData = useCallback(async () => {
    setIsLoading(true)
    try {
      const result = await fetch(`/api/${idRef.current}`).then(r => r.json())
      setData(result)
      onSuccessRef.current?.(result)
-    } catch (err) {
-      setError(err as Error)
-      logger.error('Failed', { error: err })
    } finally {
      setIsLoading(false)
    }
-  }, []) // Empty deps - using refs
+  }, [])

-  // 5. Return grouped by state/operations
-  return { data, isLoading, error, fetchData }
+  return { data, isLoading, fetchData }
 }
 ```

 ## Rules
+
 1. Single responsibility per hook
 2. Props interface required
-3. TSDoc required
-4. Use logger, not console.log
-5. Refs for stable callback dependencies
-6. Wrap returned functions in useCallback
-7. Always try/catch async operations
-8. Track loading/error states
+3. Refs for stable callback dependencies
+4. Wrap returned functions in useCallback
+5. Always try/catch async operations
+6. Track loading/error states
--- a/.cursor/rules/sim-imports.mdc
+++ b/.cursor/rules/sim-imports.mdc
@@ -5,33 +5,57 @@ globs: ["apps/sim/**/*.ts", "apps/sim/**/*.tsx"]

 # Import Patterns

-## EMCN Components
-Import from `@/components/emcn`, never from subpaths like `@/components/emcn/components/modal/modal`.
+## Absolute Imports

-**Exception**: CSS imports use actual file paths: `import '@/components/emcn/components/code/code.css'`
+**Always use absolute imports.** Never use relative imports.

-## Feature Components
-Import from central folder indexes, not specific subfolders:
 ```typescript
-// ✅ Correct
-import { Dashboard, Sidebar } from '@/app/workspace/[workspaceId]/logs/components'
+// ✓ Good
+import { useWorkflowStore } from '@/stores/workflows/store'
+import { Button } from '@/components/ui/button'

-// ❌ Wrong
-import { Dashboard } from '@/app/workspace/[workspaceId]/logs/components/dashboard'
+// ✗ Bad
+import { useWorkflowStore } from '../../../stores/workflows/store'
 ```

-## Internal vs External
- **Cross-feature**: Absolute paths through central index
- **Within feature**: Relative paths (`./components/...`, `../utils`)
+## Barrel Exports
+
+Use barrel exports (`index.ts`) when a folder has 3+ exports. Import from barrel, not individual files.
+
+```typescript
+// ✓ Good
+import { Dashboard, Sidebar } from '@/app/workspace/[workspaceId]/logs/components'
+
+// ✗ Bad
+import { Dashboard } from '@/app/workspace/[workspaceId]/logs/components/dashboard/dashboard'
+```
+
+## No Re-exports
+
+Do not re-export from non-barrel files. Import directly from the source.
+
+```typescript
+// ✓ Good - import from where it's declared
+import { CORE_TRIGGER_TYPES } from '@/stores/logs/filters/types'
+
+// ✗ Bad - re-exporting in utils.ts then importing from there
+import { CORE_TRIGGER_TYPES } from '@/app/workspace/.../utils'
+```

 ## Import Order
+
 1. React/core libraries
 2. External libraries
 3. UI components (`@/components/emcn`, `@/components/ui`)
 4. Utilities (`@/lib/...`)
-5. Feature imports from indexes
-6. Relative imports
+5. Stores (`@/stores/...`)
+6. Feature imports
 7. CSS imports

-## Types
-Use `type` keyword: `import type { WorkflowLog } from '...'`
+## Type Imports
+
+Use `type` keyword for type-only imports:
+
+```typescript
+import type { WorkflowLog } from '@/stores/logs/types'
+```
--- a/.cursor/rules/sim-integrations.mdc
+++ b/.cursor/rules/sim-integrations.mdc
@@ -0,0 +1,285 @@
+---
+description: Adding new integrations (tools, blocks, triggers)
+globs: ["apps/sim/tools/**", "apps/sim/blocks/**", "apps/sim/triggers/**"]
+---
+
+# Adding Integrations
+
+## Overview
+
+Adding a new integration typically requires:
+1. **Tools** - API operations (`tools/{service}/`)
+2. **Block** - UI component (`blocks/blocks/{service}.ts`)
+3. **Icon** - SVG icon (`components/icons.tsx`)
+4. **Trigger** (optional) - Webhooks/polling (`triggers/{service}/`)
+
+Always look up the service's API docs first.
+
+## 1. Tools (`tools/{service}/`)
+
+```
+tools/{service}/
+├── index.ts           # Export all tools
+├── types.ts           # Params/response types
+├── {action}.ts        # Individual tool (e.g., send_message.ts)
+└── ...
+```
+
+**Tool file structure:**
+
+```typescript
+// tools/{service}/{action}.ts
+import type { {Service}Params, {Service}Response } from '@/tools/{service}/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const {service}{Action}Tool: ToolConfig<{Service}Params, {Service}Response> = {
+  id: '{service}_{action}',
+  name: '{Service} {Action}',
+  description: 'What this tool does',
+  version: '1.0.0',
+  oauth: { required: true, provider: '{service}' }, // if OAuth
+  params: { /* param definitions */ },
+  request: {
+    url: '/api/tools/{service}/{action}',
+    method: 'POST',
+    headers: () => ({ 'Content-Type': 'application/json' }),
+    body: (params) => ({ ...params }),
+  },
+  transformResponse: async (response) => {
+    const data = await response.json()
+    if (!data.success) throw new Error(data.error)
+    return { success: true, output: data.output }
+  },
+  outputs: { /* output definitions */ },
+}
+```
+
+**Register in `tools/registry.ts`:**
+
+```typescript
+import { {service}{Action}Tool } from '@/tools/{service}'
+// Add to registry object
+{service}_{action}: {service}{Action}Tool,
+```
+
+## 2. Block (`blocks/blocks/{service}.ts`)
+
+```typescript
+import { {Service}Icon } from '@/components/icons'
+import type { BlockConfig } from '@/blocks/types'
+import type { {Service}Response } from '@/tools/{service}/types'
+
+export const {Service}Block: BlockConfig<{Service}Response> = {
+  type: '{service}',
+  name: '{Service}',
+  description: 'Short description',
+  longDescription: 'Detailed description',
+  category: 'tools',
+  bgColor: '#hexcolor',
+  icon: {Service}Icon,
+  subBlocks: [ /* see SubBlock Properties below */ ],
+  tools: {
+    access: ['{service}_{action}', ...],
+    config: {
+      tool: (params) => `{service}_${params.operation}`,
+      params: (params) => ({ ...params }),
+    },
+  },
+  inputs: { /* input definitions */ },
+  outputs: { /* output definitions */ },
+}
+```
+
+### SubBlock Properties
+
+```typescript
+{
+  id: 'fieldName',           // Unique identifier
+  title: 'Field Label',      // UI label
+  type: 'short-input',       // See SubBlock Types below
+  placeholder: 'Hint text',
+  required: true,            // See Required below
+  condition: { ... },        // See Condition below
+  dependsOn: ['otherField'], // See DependsOn below
+  mode: 'basic',             // 'basic' | 'advanced' | 'both' | 'trigger'
+}
+```
+
+**SubBlock Types:** `short-input`, `long-input`, `dropdown`, `code`, `switch`, `slider`, `oauth-input`, `channel-selector`, `user-selector`, `file-upload`, etc.
+
+### `condition` - Show/hide based on another field
+
+```typescript
+// Show when operation === 'send'
+condition: { field: 'operation', value: 'send' }
+
+// Show when operation is 'send' OR 'read'
+condition: { field: 'operation', value: ['send', 'read'] }
+
+// Show when operation !== 'send'
+condition: { field: 'operation', value: 'send', not: true }
+
+// Complex: NOT in list AND another condition
+condition: {
+  field: 'operation',
+  value: ['list_channels', 'list_users'],
+  not: true,
+  and: { field: 'destinationType', value: 'dm', not: true }
+}
+```
+
+### `required` - Field validation
+
+```typescript
+// Always required
+required: true
+
+// Conditionally required (same syntax as condition)
+required: { field: 'operation', value: 'send' }
+```
+
+### `dependsOn` - Clear field when dependencies change
+
+```typescript
+// Clear when credential changes
+dependsOn: ['credential']
+
+// Clear when authMethod changes AND (credential OR botToken) changes
+dependsOn: { all: ['authMethod'], any: ['credential', 'botToken'] }
+```
+
+### `mode` - When to show field
+
+- `'basic'` - Only in basic mode (default UI)
+- `'advanced'` - Only in advanced mode (manual input)
+- `'both'` - Show in both modes (default)
+- `'trigger'` - Only when block is used as trigger
+
+### `canonicalParamId` - Link basic/advanced alternatives
+
+Use to map multiple UI inputs to a single logical parameter:
+
+```typescript
+// Basic mode: Visual selector
+{
+  id: 'fileSelector',
+  type: 'file-selector',
+  mode: 'basic',
+  canonicalParamId: 'fileId',
+  required: true,
+},
+// Advanced mode: Manual input
+{
+  id: 'manualFileId',
+  type: 'short-input',
+  mode: 'advanced',
+  canonicalParamId: 'fileId',
+  required: true,
+},
+```
+
+**Critical Rules:**
+- `canonicalParamId` must NOT match any subblock's `id`
+- `canonicalParamId` must be unique per operation/condition context
+- **Required consistency:** All subblocks in a canonical group must have the same `required` status
+- **Inputs section:** Must list canonical param IDs (e.g., `fileId`), NOT raw subblock IDs
+- **Params function:** Must use canonical param IDs (raw IDs are deleted after canonical transformation)
+
+**Register in `blocks/registry.ts`:**
+
+```typescript
+import { {Service}Block } from '@/blocks/blocks/{service}'
+// Add to registry object (alphabetically)
+{service}: {Service}Block,
+```
+
+## 3. Icon (`components/icons.tsx`)
+
+```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 path from service's brand assets */}
+    </svg>
+  )
+}
+```
+
+## 4. Trigger (`triggers/{service}/`) - Optional
+
+```
+triggers/{service}/
+├── index.ts           # Export all triggers
+├── webhook.ts         # Webhook handler
+├── utils.ts           # Shared utilities
+└── {event}.ts         # Specific event handlers
+```
+
+**Register in `triggers/registry.ts`:**
+
+```typescript
+import { {service}WebhookTrigger } from '@/triggers/{service}'
+// Add to TRIGGER_REGISTRY
+{service}_webhook: {service}WebhookTrigger,
+```
+
+## File Handling
+
+When integrations handle file uploads/downloads, use `UserFile` objects consistently.
+
+### File Input (Uploads)
+
+1. **Block subBlocks:** Use basic/advanced mode pattern with `canonicalParamId`
+2. **Normalize in block config:** Use `normalizeFileInput` from `@/blocks/utils`
+3. **Internal API route:** Create route that uses `downloadFileFromStorage` to get file content
+4. **Tool routes to internal API:** Don't call external APIs directly with files
+
+```typescript
+// In block tools.config:
+import { normalizeFileInput } from '@/blocks/utils'
+
+const normalizedFile = normalizeFileInput(
+  params.uploadFile || params.fileRef || params.fileContent,
+  { single: true }
+)
+if (normalizedFile) params.file = normalizedFile
+```
+
+### File Output (Downloads)
+
+Use `FileToolProcessor` in tool `transformResponse` to store files:
+
+```typescript
+import { FileToolProcessor } from '@/executor/utils/file-tool-processor'
+
+const processor = new FileToolProcessor(context)
+const file = await processor.processFileData({
+  data: base64Content,
+  mimeType: 'application/pdf',
+  filename: 'doc.pdf',
+})
+```
+
+### Key Helpers
+
+| 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 Buffer from UserFile |
+| `FileToolProcessor` | `@/executor/utils/file-tool-processor` | Process tool output files |
+
+## Checklist
+
+- [ ] Look up API docs for the service
+- [ ] Create `tools/{service}/types.ts` with proper types
+- [ ] Create tool files for each operation
+- [ ] Create `tools/{service}/index.ts` barrel export
+- [ ] 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 triggers in `triggers/{service}/`
+- [ ] (Optional) Register triggers in `triggers/registry.ts`
+- [ ] (If file uploads) Create internal API route with `downloadFileFromStorage`
+- [ ] (If file uploads) Use `normalizeFileInput` in block config
--- a/.cursor/rules/sim-queries.mdc
+++ b/.cursor/rules/sim-queries.mdc
@@ -0,0 +1,126 @@
+---
+description: React Query patterns for the Sim application
+globs: ["apps/sim/hooks/queries/**/*.ts"]
+---
+
+# React Query Patterns
+
+All React Query hooks live in `hooks/queries/`. All server state must go through React Query — never use `useState` + `fetch` in components for data fetching or mutations.
+
+## Query Key Factory
+
+Every query file defines a hierarchical keys factory with an `all` root key and intermediate plural keys for prefix-level invalidation:
+
+```typescript
+export const entityKeys = {
+  all: ['entity'] as const,
+  lists: () => [...entityKeys.all, 'list'] as const,
+  list: (workspaceId?: string) => [...entityKeys.lists(), workspaceId ?? ''] as const,
+  details: () => [...entityKeys.all, 'detail'] as const,
+  detail: (id?: string) => [...entityKeys.details(), id ?? ''] as const,
+}
+```
+
+Never use inline query keys — always use the factory.
+
+## File Structure
+
+```typescript
+// 1. Query keys factory
+// 2. Types (if needed)
+// 3. Private fetch functions (accept signal parameter)
+// 4. Exported hooks
+```
+
+## Query Hook
+
+- Every `queryFn` must destructure and forward `signal` for request cancellation
+- Every query must have an explicit `staleTime`
+- Use `keepPreviousData` only on variable-key queries (where params change), never on static keys
+
+```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: ({ signal }) => fetchEntities(workspaceId as string, signal),
+    enabled: Boolean(workspaceId) && (options?.enabled ?? true),
+    staleTime: 60 * 1000,
+    placeholderData: keepPreviousData, // OK: workspaceId varies
+  })
+}
+```
+
+## Mutation Hook
+
+- Use targeted invalidation (`entityKeys.lists()`) not broad (`entityKeys.all`) when possible
+- Invalidation must cover all affected query key prefixes (lists, details, related views)
+
+```typescript
+export function useCreateEntity() {
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: async (variables) => { /* fetch POST */ },
+    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`, `useDeleteEntity`
+- **Fetch functions**: `fetchEntity`, `fetchEntities` (private)
--- a/.cursor/rules/sim-stores.mdc
+++ b/.cursor/rules/sim-stores.mdc
@@ -5,53 +5,66 @@ globs: ["apps/sim/**/store.ts", "apps/sim/**/stores/**/*.ts"]

 # Zustand Store Patterns

-## Structure
+Stores live in `stores/`. Complex stores split into `store.ts` + `types.ts`.
+
+## Basic Store
+
+```typescript
+import { create } from 'zustand'
+import { devtools } from 'zustand/middleware'
+import type { FeatureState } from '@/stores/feature/types'
+
+const initialState = { items: [] as Item[], activeId: null as string | null }
+
+export const useFeatureStore = create<FeatureState>()(
+  devtools(
+    (set, get) => ({
+      ...initialState,
+      setItems: (items) => set({ items }),
+      addItem: (item) => set((state) => ({ items: [...state.items, item] })),
+      reset: () => set(initialState),
+    }),
+    { name: 'feature-store' }
+  )
+)
+```
+
+## Persisted Store
+
 ```typescript
 import { create } from 'zustand'
 import { persist } from 'zustand/middleware'

-interface FeatureState {
-  // State
-  items: Item[]
-  activeId: string | null
-  
-  // Actions
-  setItems: (items: Item[]) => void
-  addItem: (item: Item) => void
-  clearState: () => void
-}
-
-const createInitialState = () => ({
-  items: [],
-  activeId: null,
-})
-
 export const useFeatureStore = create<FeatureState>()(
  persist(
    (set) => ({
-      ...createInitialState(),
-
-      setItems: (items) => set({ items }),
-
-      addItem: (item) => set((state) => ({
-        items: [...state.items, item],
-      })),
-
-      clearState: () => set(createInitialState()),
+      width: 300,
+      setWidth: (width) => set({ width }),
+      _hasHydrated: false,
+      setHasHydrated: (v) => set({ _hasHydrated: v }),
    }),
    {
      name: 'feature-state',
-      partialize: (state) => ({ items: state.items }),
+      partialize: (state) => ({ width: state.width }),
+      onRehydrateStorage: () => (state) => state?.setHasHydrated(true),
    }
  )
 )
 ```

 ## Rules
-1. Interface includes state and actions
-2. Extract config to module constants
-3. TSDoc on store
-4. Only persist what's needed
-5. Immutable updates only - never mutate
-6. Use `set((state) => ...)` when depending on previous state
-7. Provide clear/reset actions
+
+1. Use `devtools` middleware (named stores)
+2. Use `persist` only when data should survive reload
+3. `partialize` to persist only necessary state
+4. `_hasHydrated` pattern for persisted stores needing hydration tracking
+5. Immutable updates only
+6. `set((state) => ...)` when depending on previous state
+7. Provide `reset()` action
+
+## Outside React
+
+```typescript
+const items = useFeatureStore.getState().items
+useFeatureStore.setState({ items: newItems })
+```
--- a/.cursor/rules/sim-styling.mdc
+++ b/.cursor/rules/sim-styling.mdc
@@ -6,13 +6,14 @@ globs: ["apps/sim/**/*.tsx", "apps/sim/**/*.css"]
 # Styling Rules

 ## Tailwind
-1. **No inline styles** - Use Tailwind classes exclusively
-2. **No duplicate dark classes** - Don't add `dark:` when value matches light mode
-3. **Exact values** - Use design system values (`text-[14px]`, `h-[25px]`)
-4. **Prefer px** - Use `px-[4px]` over `px-1`
-5. **Transitions** - Add `transition-colors` for interactive states
+
+1. **No inline styles** - Use Tailwind classes
+2. **No duplicate dark classes** - Skip `dark:` when value matches light mode
+3. **Exact values** - `text-[14px]`, `h-[26px]`
+4. **Transitions** - `transition-colors` for interactive states

 ## Conditional Classes
+
 ```typescript
 import { cn } from '@/lib/utils'

@@ -23,25 +24,17 @@ import { cn } from '@/lib/utils'
 )} />
 ```

-## CSS Variables for Dynamic Styles
+## CSS Variables
+
+For dynamic values (widths, heights) synced with stores:
+
 ```typescript
-// In store setter
-setSidebarWidth: (width) => {
-  set({ sidebarWidth: width })
+// In store
+setWidth: (width) => {
+  set({ width })
  document.documentElement.style.setProperty('--sidebar-width', `${width}px`)
 }

 // In component
 <aside style={{ width: 'var(--sidebar-width)' }} />
 ```
-
-## Anti-Patterns
-```typescript
-// ❌ Bad
-<div style={{ width: 200 }}>
-<div className='text-[var(--text-primary)] dark:text-[var(--text-primary)]'>
-
-// ✅ Good
-<div className='w-[200px]'>
-<div className='text-[var(--text-primary)]'>
-```
--- a/.cursor/rules/sim-testing.mdc
+++ b/.cursor/rules/sim-testing.mdc
@@ -0,0 +1,216 @@
+---
+description: Testing patterns with Vitest and @sim/testing
+globs: ["apps/sim/**/*.test.ts", "apps/sim/**/*.test.tsx"]
+---
+
+# Testing Patterns
+
+Use Vitest. Test files: `feature.ts` → `feature.test.ts`
+
+## Global Mocks (vitest.setup.ts)
+
+These modules are mocked globally — do NOT re-mock them in test files unless you need to override behavior:
+
+- `@sim/db` → `databaseMock`
+- `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 { createMockRequest } from '@sim/testing'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { mockGetSession } = vi.hoisted(() => ({
+  mockGetSession: vi.fn(),
+}))
+
+vi.mock('@/lib/auth', () => ({
+  auth: { api: { getSession: vi.fn() } },
+  getSession: mockGetSession,
+}))
+
+import { GET, POST } from '@/app/api/my-route/route'
+
+describe('my route', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockGetSession.mockResolvedValue({ user: { id: 'user-1' } })
+  })
+
+  it('returns data', async () => {
+    const req = createMockRequest('GET')
+    const res = await GET(req)
+    expect(res.status).toBe(200)
+  })
+})
+```
+
+## Performance Rules (Critical)
+
+### NEVER use `vi.resetModules()` + `vi.doMock()` + `await import()`
+
+This is the #1 cause of slow tests. It forces complete module re-evaluation per test.
+
+```typescript
+// BAD — forces module re-evaluation every test (~50-100ms each)
+beforeEach(() => {
+  vi.resetModules()
+  vi.doMock('@/lib/auth', () => ({ getSession: vi.fn() }))
+})
+it('test', async () => {
+  const { GET } = await import('./route')  // slow dynamic import
+})
+
+// GOOD — module loaded once, mocks reconfigured per test (~1ms each)
+const { mockGetSession } = vi.hoisted(() => ({
+  mockGetSession: vi.fn(),
+}))
+vi.mock('@/lib/auth', () => ({ getSession: mockGetSession }))
+import { GET } from '@/app/api/my-route/route'
+
+beforeEach(() => { vi.clearAllMocks() })
+it('test', () => {
+  mockGetSession.mockResolvedValue({ user: { id: '1' } })
+})
+```
+
+**Only exception:** Singleton modules that cache state at module scope (e.g., Redis clients, connection pools). These genuinely need `vi.resetModules()` + dynamic import to get a fresh instance per test.
+
+### NEVER use `vi.importActual()`
+
+This defeats the purpose of mocking by loading the real module and all its dependencies.
+
+```typescript
+// BAD — loads real module + all transitive deps
+vi.mock('@/lib/workspaces/utils', async () => {
+  const actual = await vi.importActual('@/lib/workspaces/utils')
+  return { ...actual, myFn: vi.fn() }
+})
+
+// GOOD — mock everything, only implement what tests need
+vi.mock('@/lib/workspaces/utils', () => ({
+  myFn: vi.fn(),
+  otherFn: vi.fn(),
+}))
+```
+
+### 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 test data.
+
+| Category | Utilities |
+|----------|-----------|
+| **Mocks** | `loggerMock`, `databaseMock`, `drizzleOrmMock`, `setupGlobalFetchMock()` |
+| **Factories** | `createSession()`, `createWorkflowRecord()`, `createBlock()`, `createExecutionContext()` |
+| **Builders** | `WorkflowBuilder`, `ExecutionContextBuilder` |
+| **Assertions** | `expectWorkflowAccessGranted()`, `expectBlockExecuted()` |
+| **Requests** | `createMockRequest()`, `createEnvMock()` |
+
+## Rules Summary
+
+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()`
--- a/.cursor/rules/sim-typescript.mdc
+++ b/.cursor/rules/sim-typescript.mdc
@@ -6,19 +6,15 @@ globs: ["apps/sim/**/*.ts", "apps/sim/**/*.tsx"]
 # TypeScript Rules

 1. **No `any`** - Use proper types or `unknown` with type guards
-2. **Props interface** - Always define, even for simple components
-3. **Callback types** - Full signature with params and return type
-4. **Generics** - Use for reusable components/hooks
-5. **Const assertions** - `as const` for constant objects/arrays
-6. **Ref types** - Explicit: `useRef<HTMLDivElement>(null)`
+2. **Props interface** - Always define for components
+3. **Const assertions** - `as const` for constant objects/arrays
+4. **Ref types** - Explicit: `useRef<HTMLDivElement>(null)`
+5. **Type imports** - `import type { X }` for type-only imports

-## Anti-Patterns
 ```typescript
-// ❌ Bad
+// ✗ Bad
 const handleClick = (e: any) => {}
-useEffect(() => { doSomething(prop) }, []) // Missing dep

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

 # Install necessary packages for development
 RUN apk add --no-cache \
--- a/.devcontainer/docker-compose.yml
+++ b/.devcontainer/docker-compose.yml
@@ -44,7 +44,7 @@ services:
    deploy:
      resources:
        limits:
-          memory: 4G
+          memory: 1G
    environment:
      - NODE_ENV=development
      - DATABASE_URL=postgresql://postgres:postgres@db:5432/simstudio
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -8,7 +8,10 @@ on:

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

 jobs:
  test-build:
@@ -27,10 +30,11 @@ jobs:
    steps:
      - name: Extract version from commit message
        id: extract
+        env:
+          COMMIT_MSG: ${{ github.event.head_commit.message }}
        run: |
-          COMMIT_MSG="${{ github.event.head_commit.message }}"
          # Only tag versions on main branch
-          if [ "${{ github.ref }}" = "refs/heads/main" ] && [[ "$COMMIT_MSG" =~ ^(v[0-9]+\.[0-9]+\.[0-9]+): ]]; then
+          if [ "$GITHUB_REF" = "refs/heads/main" ] && [[ "$COMMIT_MSG" =~ ^(v[0-9]+\.[0-9]+\.[0-9]+): ]]; then
            VERSION="${BASH_REMATCH[1]}"
            echo "version=${VERSION}" >> $GITHUB_OUTPUT
            echo "is_release=true" >> $GITHUB_OUTPUT
@@ -277,3 +281,30 @@ jobs:
    if: needs.check-docs-changes.outputs.docs_changed == 'true'
    uses: ./.github/workflows/docs-embeddings.yml
    secrets: inherit
+
+  # Create GitHub Release (only for version commits on main, after all builds complete)
+  create-release:
+    name: Create GitHub Release
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    needs: [create-ghcr-manifests, detect-version]
+    if: needs.detect-version.outputs.is_release == 'true'
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Create release
+        env:
+          GH_PAT: ${{ secrets.GITHUB_TOKEN }}
+        run: bun run scripts/create-single-release.ts ${{ needs.detect-version.outputs.version }}
--- a/.github/workflows/docs-embeddings.yml
+++ b/.github/workflows/docs-embeddings.yml
@@ -4,6 +4,9 @@ on:
  workflow_call:
  workflow_dispatch: # Allow manual triggering

+permissions:
+  contents: read
+
 jobs:
  process-docs-embeddings:
    name: Process Documentation Embeddings
@@ -17,7 +20,7 @@ jobs:
      - name: Setup Bun
        uses: oven-sh/setup-bun@v2
        with:
-          bun-version: 1.3.3
+          bun-version: 1.3.10

      - name: Setup Node
        uses: actions/setup-node@v4
--- a/.github/workflows/i18n.yml
+++ b/.github/workflows/i18n.yml
@@ -1,11 +1,7 @@
 name: 'Auto-translate Documentation'

 on:
-  push:
-    branches: [ staging ]
-    paths:
-      - 'apps/docs/content/docs/en/**'
-      - 'apps/docs/i18n.json'
+  workflow_dispatch: # Manual trigger only (scheduled runs disabled)

 permissions:
  contents: write
@@ -20,13 +16,14 @@ jobs:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
+          ref: staging
          token: ${{ secrets.GH_PAT }}
          fetch-depth: 0

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

      - name: Cache Bun dependencies
        uses: actions/cache@v4
@@ -68,12 +65,11 @@ jobs:
          title: "feat(i18n): update translations"
          body: |
            ## Summary
-            Automated translation updates triggered by changes to documentation.
-            
-            This PR was automatically created after content changes were made, updating translations for all supported languages using Lingo.dev AI translation engine.
-            
-            **Original trigger**: ${{ github.event.head_commit.message }}
-            **Commit**: ${{ github.sha }}
+            Automated weekly translation updates for documentation.
+
+            This PR was automatically created by the scheduled weekly i18n workflow, updating translations for all supported languages using Lingo.dev AI translation engine.
+
+            **Triggered**: Weekly scheduled run
            **Workflow**: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
            
            ## Type of Change
@@ -107,7 +103,7 @@ jobs:
            ## Screenshots/Videos
            <!-- Translation changes are text-based - no visual changes expected -->
            <!-- Reviewers should check the documentation site renders correctly for all languages -->
-          branch: auto-translate/staging-merge-${{ github.run_id }}
+          branch: auto-translate/weekly-${{ github.run_id }}
          base: staging
          labels: |
            i18n
@@ -126,7 +122,7 @@ jobs:
      - name: Setup Bun
        uses: oven-sh/setup-bun@v2
        with:
-          bun-version: 1.3.3
+          bun-version: 1.3.10

      - name: Cache Bun dependencies
        uses: actions/cache@v4
@@ -145,6 +141,8 @@ jobs:
          bun install --frozen-lockfile

      - name: Build documentation to verify translations
+        env:
+          DATABASE_URL: postgresql://dummy:dummy@localhost:5432/dummy
        run: |
          cd apps/docs
          bun run build
@@ -153,7 +151,7 @@ jobs:
        run: |
          cd apps/docs
          echo "## Translation Status Report" >> $GITHUB_STEP_SUMMARY
-          echo "**Triggered by merge to staging branch**" >> $GITHUB_STEP_SUMMARY
+          echo "**Weekly scheduled translation run**" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          
          en_count=$(find content/docs/en -name "*.mdx" | wc -l)
--- a/.github/workflows/images.yml
+++ b/.github/workflows/images.yml
@@ -146,7 +146,7 @@ jobs:

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

+permissions:
+  contents: read
+
 jobs:
  migrate:
    name: Apply Database Migrations
@@ -16,7 +19,7 @@ jobs:
      - name: Setup Bun
        uses: oven-sh/setup-bun@v2
        with:
-          bun-version: 1.3.3
+          bun-version: 1.3.10

      - name: Cache Bun dependencies
        uses: actions/cache@v4
--- a/.github/workflows/publish-cli.yml
+++ b/.github/workflows/publish-cli.yml
@@ -6,6 +6,9 @@ on:
    paths:
      - 'packages/cli/**'

+permissions:
+  contents: read
+
 jobs:
  publish-npm:
    runs-on: blacksmith-4vcpu-ubuntu-2404
@@ -16,7 +19,7 @@ jobs:
      - name: Setup Bun
        uses: oven-sh/setup-bun@v2
        with:
-          bun-version: 1.3.3
+          bun-version: 1.3.10

      - name: Setup Node.js for npm publishing
        uses: actions/setup-node@v4
--- a/.github/workflows/publish-python-sdk.yml
+++ b/.github/workflows/publish-python-sdk.yml
@@ -6,6 +6,9 @@ on:
    paths:
      - 'packages/python-sdk/**'

+permissions:
+  contents: write
+
 jobs:
  publish-pypi:
    runs-on: blacksmith-4vcpu-ubuntu-2404
--- a/.github/workflows/publish-ts-sdk.yml
+++ b/.github/workflows/publish-ts-sdk.yml
@@ -6,6 +6,9 @@ on:
    paths:
      - 'packages/ts-sdk/**'

+permissions:
+  contents: write
+
 jobs:
  publish-npm:
    runs-on: blacksmith-4vcpu-ubuntu-2404
@@ -16,7 +19,7 @@ jobs:
      - name: Setup Bun
        uses: oven-sh/setup-bun@v2
        with:
-          bun-version: 1.3.3
+          bun-version: 1.3.10

      - name: Setup Node.js for npm publishing
        uses: actions/setup-node@v4
--- a/.github/workflows/test-build.yml
+++ b/.github/workflows/test-build.yml
@@ -4,10 +4,13 @@ on:
  workflow_call:
  workflow_dispatch:

+permissions:
+  contents: read
+
 jobs:
  test-build:
    name: Test and Build
-    runs-on: blacksmith-4vcpu-ubuntu-2404
+    runs-on: blacksmith-8vcpu-ubuntu-2404

    steps:
      - name: Checkout code
@@ -16,27 +19,87 @@ jobs:
      - name: Setup Bun
        uses: oven-sh/setup-bun@v2
        with:
-          bun-version: 1.3.3
+          bun-version: 1.3.10

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: latest

-      - name: Cache Bun dependencies
+      - name: Mount Bun cache (Sticky Disk)
+        uses: useblacksmith/stickydisk@v1
+        with:
+          key: ${{ github.repository }}-bun-cache
+          path: ~/.bun/install/cache
+
+      - name: Mount node_modules (Sticky Disk)
+        uses: useblacksmith/stickydisk@v1
+        with:
+          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: |
-            ~/.bun/install/cache
-            node_modules
-            **/node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lock') }}
+          path: ./apps/sim/.next/cache
+          key: ${{ runner.os }}-nextjs-${{ hashFiles('bun.lock') }}
          restore-keys: |
-            ${{ runner.os }}-bun-
+            ${{ runner.os }}-nextjs-

      - name: Install dependencies
        run: bun install --frozen-lockfile

+      - name: Validate feature flags
+        run: |
+          FILE="apps/sim/lib/core/config/feature-flags.ts"
+          ERRORS=""
+
+          echo "Checking for hardcoded boolean feature flags..."
+
+          # Use perl for multiline matching to catch both:
+          #   export const isHosted = true
+          #   export const isHosted =
+          #     true
+          HARDCODED=$(perl -0777 -ne 'while (/export const (is[A-Za-z]+)\s*=\s*\n?\s*(true|false)\b/g) { print "  $1 = $2\n" }' "$FILE")
+
+          if [ -n "$HARDCODED" ]; then
+            ERRORS="${ERRORS}\n❌ Feature flags must not be hardcoded to boolean literals!\n\nFound hardcoded flags:\n${HARDCODED}\n\nFeature flags should derive their values from environment variables.\n"
+          fi
+
+          echo "Checking feature flag naming conventions..."
+
+          # Check that all export const (except functions) start with 'is'
+          # This finds exports like "export const someFlag" that don't start with "is" or "get"
+          BAD_NAMES=$(grep -E "^export const [a-z]" "$FILE" | grep -vE "^export const (is|get)" | sed 's/export const \([a-zA-Z]*\).*/  \1/')
+
+          if [ -n "$BAD_NAMES" ]; then
+            ERRORS="${ERRORS}\n❌ Feature flags must use 'is' prefix for boolean flags!\n\nFound incorrectly named flags:\n${BAD_NAMES}\n\nExample: 'hostedMode' should be 'isHostedMode'\n"
+          fi
+
+          if [ -n "$ERRORS" ]; then
+            echo ""
+            echo -e "$ERRORS"
+            exit 1
+          fi
+
+          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

@@ -46,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
@@ -71,7 +135,8 @@ jobs:
          RESEND_API_KEY: 'dummy_key_for_ci_only'
          AWS_REGION: 'us-west-2'
          ENCRYPTION_KEY: '7cf672e460e430c1fba707575c2b0e2ad5a99dddf9b7b7e3b5646e630861db1c' # dummy key for CI only
-        run: bun run build
+          TURBO_CACHE_DIR: .turbo
+        run: bunx turbo run build --filter=sim

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

+# redis
+dump.rdb
+
 # misc
 .DS_Store
 *.pem
@@ -73,3 +76,7 @@ start-collector.sh
 ## Helm Chart Tests
 helm/sim/test
 i18n.cache
+
+## Claude Code
+.claude/launch.json
+.claude/worktrees/
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,47 +1,383 @@
-# Expert Programming Standards
+# Sim Development Guidelines

-**You are tasked with implementing solutions that follow best practices. You MUST be accurate, elegant, and efficient as an expert programmer.**
+You are a professional software engineer. All code must follow best practices: accurate, readable, clean, and efficient.

---
+## Global Standards

-# Role
+- **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`

-You are a professional software engineer. All code you write MUST follow best practices, ensuring accuracy, quality, readability, and cleanliness. You MUST make FOCUSED EDITS that are EFFICIENT and ELEGANT.
+## Architecture

-## Logs
+### 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

-ENSURE that you use the logger.info and logger.warn and logger.error instead of the console.log whenever you want to display logs.
+### 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
+```

-## Comments
+### 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`)

-You must use TSDOC for comments. Do not use ==== for comments to separate sections. Do not leave any comments that are not TSDOC.
+## Imports

-## Global Styles
+**Always use absolute imports.** Never use relative imports.

-You should not update the global styles unless it is absolutely necessary. Keep all styling local to components and files.
+```typescript
+// ✓ Good
+import { useWorkflowStore } from '@/stores/workflows/store'

-## Bun
+// ✗ Bad
+import { useWorkflowStore } from '../../../stores/workflows/store'
+```

-Use bun and bunx not npm and npx.
+Use barrel exports (`index.ts`) when a folder has 3+ exports. Do not re-export from non-barrel files; import directly from the source.

-## Code Quality
+### 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

- Write clean, maintainable code that follows the project's existing patterns
- Prefer composition over inheritance
- Keep functions small and focused on a single responsibility
- Use meaningful variable and function names
- Handle errors gracefully and provide useful error messages
- Write type-safe code with proper TypeScript types
+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

- Write tests for new functionality when appropriate
- Ensure existing tests pass before completing work
- Follow the project's testing conventions
+Use Vitest. Test files: `feature.ts` → `feature.test.ts`. See `.cursor/rules/sim-testing.mdc` for full details.

-## Performance
+### Global Mocks (vitest.setup.ts)

- Consider performance implications of your code
- Avoid unnecessary re-renders in React components
- Use appropriate data structures and algorithms
- Profile and optimize when necessary
+`@sim/db`, `drizzle-orm`, `@sim/logger`, `@/blocks/registry`, `@trigger.dev/sdk`, and store mocks are provided globally. Do NOT re-mock them unless overriding behavior.
+
+### Standard Test Pattern
+
+```typescript
+/**
+ * @vitest-environment node
+ */
+import { createMockRequest } from '@sim/testing'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { mockGetSession } = vi.hoisted(() => ({
+  mockGetSession: vi.fn(),
+}))
+
+vi.mock('@/lib/auth', () => ({
+  auth: { api: { getSession: vi.fn() } },
+  getSession: mockGetSession,
+}))
+
+import { GET } from '@/app/api/my-route/route'
+
+describe('my route', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockGetSession.mockResolvedValue({ user: { id: 'user-1' } })
+  })
+  it('returns data', async () => { ... })
+})
+```
+
+### Performance Rules
+
+- **NEVER** use `vi.resetModules()` + `vi.doMock()` + `await import()` — use `vi.hoisted()` + `vi.mock()` + static imports
+- **NEVER** use `vi.importActual()` — mock everything explicitly
+- **NEVER** use `mockAuth()`, `mockConsoleLogger()`, `setupCommonApiMocks()` from `@sim/testing` — they use `vi.doMock()` internally
+- **Mock heavy deps** (`@/blocks`, `@/tools/registry`, `@/triggers`) in tests that don't need them
+- **Use `@vitest-environment node`** unless DOM APIs are needed (`window`, `document`, `FormData`)
+- **Avoid real timers** — use 1ms delays or `vi.useFakeTimers()`
+
+Use `@sim/testing` mocks/factories over local test data.
+
+## Utils Rules
+
+- Never create `utils.ts` for single consumer - inline it
+- Create `utils.ts` when 2+ files need the same helper
+- Check existing sources in `lib/` before duplicating
+
+## Adding Integrations
+
+New integrations require: **Tools** → **Block** → **Icon** → (optional) **Trigger**
+
+Always look up the service's API docs first.
+
+### 1. Tools (`tools/{service}/`)
+
+```
+tools/{service}/
+├── index.ts      # Barrel export
+├── types.ts      # Params/response types
+└── {action}.ts   # Tool implementation
+```
+
+**Tool structure:**
+```typescript
+export const serviceTool: ToolConfig<Params, Response> = {
+  id: 'service_action',
+  name: 'Service Action',
+  description: '...',
+  version: '1.0.0',
+  oauth: { required: true, provider: 'service' },
+  params: { /* ... */ },
+  request: { url: '/api/tools/service/action', method: 'POST', ... },
+  transformResponse: async (response) => { /* ... */ },
+  outputs: { /* ... */ },
+}
+```
+
+Register in `tools/registry.ts`.
+
+### 2. Block (`blocks/blocks/{service}.ts`)
+
+```typescript
+export const ServiceBlock: BlockConfig = {
+  type: 'service',
+  name: 'Service',
+  description: '...',
+  category: 'tools',
+  bgColor: '#hexcolor',
+  icon: ServiceIcon,
+  subBlocks: [ /* see SubBlock Properties */ ],
+  tools: { access: ['service_action'], config: { tool: (p) => `service_${p.operation}`, params: (p) => ({ /* type coercions here */ }) } },
+  inputs: { /* ... */ },
+  outputs: { /* ... */ },
+}
+```
+
+Register in `blocks/registry.ts` (alphabetically).
+
+**Important:** `tools.config.tool` runs during serialization (before variable resolution). Never do `Number()` or other type coercions there — dynamic references like `<Block.output>` will be destroyed. Use `tools.config.params` for type coercions (it runs during execution, after variables are resolved).
+
+**SubBlock Properties:**
+```typescript
+{
+  id: 'field', title: 'Label', type: 'short-input', placeholder: '...',
+  required: true,                    // or condition object
+  condition: { field: 'op', value: 'send' },  // show/hide
+  dependsOn: ['credential'],         // clear when dep changes
+  mode: 'basic',                     // 'basic' | 'advanced' | 'both' | 'trigger'
+}
+```
+
+**condition examples:**
+- `{ field: 'op', value: 'send' }` - show when op === 'send'
+- `{ field: 'op', value: ['a','b'] }` - show when op is 'a' OR 'b'
+- `{ field: 'op', value: 'x', not: true }` - show when op !== 'x'
+- `{ field: 'op', value: 'x', not: true, and: { field: 'type', value: 'dm', not: true } }` - complex
+
+**dependsOn:** `['field']` or `{ all: ['a'], any: ['b', 'c'] }`
+
+**File Input Pattern (basic/advanced mode):**
+```typescript
+// Basic: file-upload UI
+{ id: 'uploadFile', type: 'file-upload', canonicalParamId: 'file', mode: 'basic' },
+// Advanced: reference from other blocks
+{ id: 'fileRef', type: 'short-input', canonicalParamId: 'file', mode: 'advanced' },
+```
+
+In `tools.config.tool`, normalize with:
+```typescript
+import { normalizeFileInput } from '@/blocks/utils'
+const file = normalizeFileInput(params.uploadFile || params.fileRef, { single: true })
+if (file) params.file = file
+```
+
+For file uploads, create an internal API route (`/api/tools/{service}/upload`) that uses `downloadFileFromStorage` to get file content from `UserFile` objects.
+
+### 3. Icon (`components/icons.tsx`)
+
+```typescript
+export function ServiceIcon(props: SVGProps<SVGSVGElement>) {
+  return <svg {...props}>/* SVG from brand assets */</svg>
+}
+```
+
+### 4. Trigger (`triggers/{service}/`) - Optional
+
+```
+triggers/{service}/
+├── index.ts      # Barrel export
+├── webhook.ts    # Webhook handler
+└── {event}.ts    # Event-specific handlers
+```
+
+Register in `triggers/registry.ts`.
+
+### Integration Checklist
+
+- [ ] Look up API docs
+- [ ] Create `tools/{service}/` with types and tools
+- [ ] Register tools in `tools/registry.ts`
+- [ ] Add icon to `components/icons.tsx`
+- [ ] Create block in `blocks/blocks/{service}.ts`
+- [ ] Register block in `blocks/registry.ts`
+- [ ] (Optional) Create and register triggers
+- [ ] (If file uploads) Create internal API route with `downloadFileFromStorage`
+- [ ] (If file uploads) Use `normalizeFileInput` in block config
--- a/2
+++ b/2
@@ -187,7 +187,7 @@
      same "printed page" as the copyright notice for easier
      identification within third-party archives.

-   Copyright 2025 Sim Studio, Inc.
+   Copyright 2026 Sim Studio, Inc.

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
--- a/2
+++ b/2
@@ -1,4 +1,4 @@
 Sim Studio
-Copyright 2025 Sim Studio
+Copyright 2026 Sim Studio

 This product includes software developed for the Sim project. 
--- a/README.md
+++ b/README.md
@@ -4,15 +4,19 @@
  </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://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/simstudioai?style=social" alt="Twitter"></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>
 </p>

+<p align="center">
+  <a href="https://deepwiki.com/simstudioai/sim" target="_blank" rel="noopener noreferrer"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>  <a href="https://cursor.com/link/prompt?text=Help%20me%20set%20up%20Sim%20locally.%20Follow%20these%20steps%3A%0A%0A1.%20First%2C%20verify%20Docker%20is%20installed%20and%20running%3A%0A%20%20%20docker%20--version%0A%20%20%20docker%20info%0A%0A2.%20Clone%20the%20repository%3A%0A%20%20%20git%20clone%20https%3A%2F%2Fgithub.com%2Fsimstudioai%2Fsim.git%0A%20%20%20cd%20sim%0A%0A3.%20Start%20the%20services%20with%20Docker%20Compose%3A%0A%20%20%20docker%20compose%20-f%20docker-compose.prod.yml%20up%20-d%0A%0A4.%20Wait%20for%20all%20containers%20to%20be%20healthy%20(this%20may%20take%201-2%20minutes)%3A%0A%20%20%20docker%20compose%20-f%20docker-compose.prod.yml%20ps%0A%0A5.%20Verify%20the%20app%20is%20accessible%20at%20http%3A%2F%2Flocalhost%3A3000%0A%0AIf%20there%20are%20any%20errors%2C%20help%20me%20troubleshoot%20them.%20Common%20issues%3A%0A-%20Port%203000%2C%203002%2C%20or%205432%20already%20in%20use%0A-%20Docker%20not%20running%0A-%20Insufficient%20memory%20(needs%2012GB%2B%20RAM)%0A%0AFor%20local%20AI%20models%20with%20Ollama%2C%20use%20this%20instead%20of%20step%203%3A%0A%20%20%20docker%20compose%20-f%20docker-compose.ollama.yml%20--profile%20setup%20up%20-d"><img src="https://img.shields.io/badge/Set%20Up%20with-Cursor-000000?logo=cursor&logoColor=white" alt="Set Up with Cursor"></a>
+</p>
+
 ### Build Workflows with Ease
 Design agent workflows visually on a canvas—connect agents, tools, and blocks, then run them instantly.

@@ -60,17 +64,11 @@ Docker must be installed and running on your machine.
 ### Self-hosted: Docker Compose

 ```bash
-# Clone the repository
-git clone https://github.com/simstudioai/sim.git
-
-# Navigate to the project directory
-cd sim
-
-# Start Sim
+git clone https://github.com/simstudioai/sim.git && cd sim
 docker compose -f docker-compose.prod.yml up -d
 ```

-Access the application at [http://localhost:3000/](http://localhost:3000/)
+Open [http://localhost:3000](http://localhost:3000)

 #### Using Local Models with Ollama

@@ -91,33 +89,17 @@ docker compose -f docker-compose.ollama.yml exec ollama ollama pull llama3.1:8b

 #### Using an External Ollama Instance

-If you already have Ollama running on your host machine (outside Docker), you need to configure the `OLLAMA_URL` to use `host.docker.internal` instead of `localhost`:
+If Ollama is running on your host machine, use `host.docker.internal` instead of `localhost`:

 ```bash
-# Docker Desktop (macOS/Windows)
 OLLAMA_URL=http://host.docker.internal:11434 docker compose -f docker-compose.prod.yml up -d
-
-# Linux (add extra_hosts or use host IP)
-docker compose -f docker-compose.prod.yml up -d  # Then set OLLAMA_URL to your host's IP
 ```

-**Why?** When running inside Docker, `localhost` refers to the container itself, not your host machine. `host.docker.internal` is a special DNS name that resolves to the host.
-
-For Linux users, you can either:
- Use your host machine's actual IP address (e.g., `http://192.168.1.100:11434`)
- Add `extra_hosts: ["host.docker.internal:host-gateway"]` to the simstudio service in your compose file
+On Linux, use your host's IP address or add `extra_hosts: ["host.docker.internal:host-gateway"]` to the compose file.

 #### Using vLLM

-Sim also supports [vLLM](https://docs.vllm.ai/) for self-hosted models with OpenAI-compatible API:
-
-```bash
-# Set these environment variables
-VLLM_BASE_URL=http://your-vllm-server:8000
-VLLM_API_KEY=your_optional_api_key  # Only if your vLLM instance requires auth
-```
-
-When running with Docker, use `host.docker.internal` if vLLM is on your host machine (same as Ollama above).
+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

@@ -128,14 +110,9 @@ When running with Docker, use `host.docker.internal` if vLLM is on your host mac

 ### Self-hosted: Manual Setup

-**Requirements:**
- [Bun](https://bun.sh/) runtime
- [Node.js](https://nodejs.org/) v20+ (required for sandboxed code execution)
- PostgreSQL 12+ with [pgvector extension](https://github.com/pgvector/pgvector) (required for AI embeddings)
+**Requirements:** [Bun](https://bun.sh/), [Node.js](https://nodejs.org/) v20+, PostgreSQL 12+ with [pgvector](https://github.com/pgvector/pgvector)

-**Note:** Sim uses vector embeddings for AI features like knowledge bases and semantic search, which requires the `pgvector` PostgreSQL extension.
-
-1. Clone and install dependencies:
+1. Clone and install:

 ```bash
 git clone https://github.com/simstudioai/sim.git
@@ -145,75 +122,33 @@ bun install

 2. Set up PostgreSQL with pgvector:

-You need PostgreSQL with the `vector` extension for embedding support. Choose one option:
-
-**Option A: Using Docker (Recommended)**
 ```bash
-# Start PostgreSQL with pgvector extension
-docker run --name simstudio-db \
-  -e POSTGRES_PASSWORD=your_password \
-  -e POSTGRES_DB=simstudio \
-  -p 5432:5432 -d \
-  pgvector/pgvector:pg17
+docker run --name simstudio-db -e POSTGRES_PASSWORD=your_password -e POSTGRES_DB=simstudio -p 5432:5432 -d pgvector/pgvector:pg17
 ```

-**Option B: Manual Installation**
- Install PostgreSQL 12+ and the pgvector extension
- See [pgvector installation guide](https://github.com/pgvector/pgvector#installation)
+Or install manually via the [pgvector guide](https://github.com/pgvector/pgvector#installation).

-3. Set up environment:
+3. Configure environment:

 ```bash
-cd apps/sim
-cp .env.example .env  # Configure with required variables (DATABASE_URL, BETTER_AUTH_SECRET, BETTER_AUTH_URL)
+cp apps/sim/.env.example apps/sim/.env
+cp packages/db/.env.example packages/db/.env
+# Edit both .env files to set DATABASE_URL="postgresql://postgres:your_password@localhost:5432/simstudio"
 ```

-Update your `.env` file with the database URL:
-```bash
-DATABASE_URL="postgresql://postgres:your_password@localhost:5432/simstudio"
-```
-
-4. Set up the database:
-
-First, configure the database package environment:
-```bash
-cd packages/db
-cp .env.example .env 
-```
-
-Update your `packages/db/.env` file with the database URL:
-```bash
-DATABASE_URL="postgresql://postgres:your_password@localhost:5432/simstudio"
-```
-
-Then run the migrations:
-```bash
-cd packages/db # Required so drizzle picks correct .env file
-bunx drizzle-kit migrate --config=./drizzle.config.ts
-```
-
-5. Start the development servers:
-
-**Recommended approach - run both servers together (from project root):**
+4. Run migrations:

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

-This starts both the main Next.js application and the realtime socket server required for full functionality.
+5. Start development servers:

-**Alternative - run servers separately:**
-
-Next.js app (from project root):
 ```bash
-bun run dev
+bun run dev:full  # Starts both Next.js app and realtime socket server
 ```

-Realtime socket server (from `apps/sim` directory in a separate terminal):
-```bash
-cd apps/sim
-bun run dev:sockets
-```
+Or run separately: `bun run dev` (Next.js) and `cd apps/sim && bun run dev:sockets` (realtime).

 ## Copilot API Keys

@@ -224,7 +159,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 `apps/sim/.env.example` for full list):
+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 |
 |----------|----------|-------------|
@@ -232,36 +167,11 @@ Key environment variables for self-hosted deployments (see `apps/sim/.env.exampl
 | `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 | Encryption key (`openssl rand -hex 32`) |
-| `OLLAMA_URL` | No | Ollama server URL (default: `http://localhost:11434`) |
-| `VLLM_BASE_URL` | No | vLLM server URL for self-hosted models |
+| `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 |

-## Troubleshooting
-
-### Ollama models not showing in dropdown (Docker)
-
-If you're running Ollama on your host machine and Sim in Docker, change `OLLAMA_URL` from `localhost` to `host.docker.internal`:
-
-```bash
-OLLAMA_URL=http://host.docker.internal:11434 docker compose -f docker-compose.prod.yml up -d
-```
-
-See [Using an External Ollama Instance](#using-an-external-ollama-instance) for details.
-
-### Database connection issues
-
-Ensure PostgreSQL has the pgvector extension installed. When using Docker, wait for the database to be healthy before running migrations.
-
-### Port conflicts
-
-If ports 3000, 3002, or 5432 are in use, configure alternatives:
-
-```bash
-# Custom ports
-NEXT_PUBLIC_APP_URL=http://localhost:3100 POSTGRES_PORT=5433 docker compose up -d
-```
-
 ## Tech Stack

 - **Framework**: [Next.js](https://nextjs.org/) (App Router)
--- a/apps/docs/app/[lang]/[[...slug]]/page.tsx
+++ b/apps/docs/app/[lang]/[[...slug]]/page.tsx
@@ -1,5 +1,9 @@
 import type React from 'react'
+import type { Root } from 'fumadocs-core/page-tree'
 import { findNeighbour } from 'fumadocs-core/page-tree'
+import type { ApiPageProps } from 'fumadocs-openapi/ui'
+import { createAPIPage } from 'fumadocs-openapi/ui'
+import { Pre } from 'fumadocs-ui/components/codeblock'
 import defaultMdxComponents from 'fumadocs-ui/mdx'
 import { DocsBody, DocsDescription, DocsPage, DocsTitle } from 'fumadocs-ui/page'
 import { ChevronLeft, ChevronRight } from 'lucide-react'
@@ -11,27 +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 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,
      },
    ]

@@ -39,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
      }
@@ -54,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}`,
        })
      }
    })
@@ -71,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
@@ -98,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'
@@ -167,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
@@ -185,11 +291,6 @@ export default async function Page(props: { params: Promise<{ slug?: string[]; l
        tableOfContent={{
          style: 'clerk',
          enabled: true,
-          header: (
-            <div key='toc-header' className='mb-2 font-medium text-sm'>
-              On this page
-            </div>
-          ),
          footer: <TOCFooter />,
          single: false,
        }}
@@ -205,7 +306,7 @@ export default async function Page(props: { params: Promise<{ slug?: string[]; l
        <div className='relative mt-6 sm:mt-0'>
          <div className='absolute top-1 right-0 flex items-center gap-2'>
            <div className='hidden sm:flex'>
-              <LLMCopyButton markdownUrl={`${page.url}.mdx`} />
+              <LLMCopyButton content={markdownContent} />
            </div>
            <PageNavigationArrows previous={neighbours?.previous} next={neighbours?.next} />
          </div>
@@ -216,7 +317,11 @@ export default async function Page(props: { params: Promise<{ slug?: string[]; l
          <MDX
            components={{
              ...defaultMdxComponents,
-              CodeBlock,
+              pre: (props: React.HTMLAttributes<HTMLPreElement>) => (
+                <CodeBlock {...props}>
+                  <Pre>{props.children}</Pre>
+                </CodeBlock>
+              ),
              h1: (props: React.HTMLAttributes<HTMLHeadingElement>) => (
                <Heading as='h1' {...props} />
              ),
@@ -251,28 +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 description = data.description || ''
-  const ogImageUrl = `${baseUrl}/api/og?title=${encodeURIComponent(data.title)}&category=DOCUMENTATION${description ? `&description=${encodeURIComponent(description)}` : ''}`
+  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}`, '')}`,
      },
    },
  }
--- a/apps/docs/app/[lang]/layout.tsx
+++ b/apps/docs/app/[lang]/layout.tsx
@@ -3,13 +3,15 @@ import { defineI18nUI } from 'fumadocs-ui/i18n'
 import { DocsLayout } from 'fumadocs-ui/layouts/docs'
 import { RootProvider } from 'fumadocs-ui/provider/next'
 import { Geist_Mono, Inter } from 'next/font/google'
-import Image from 'next/image'
+import Script from 'next/script'
 import {
  SidebarFolder,
  SidebarItem,
  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'
 import '../global.css'
@@ -17,11 +19,13 @@ import '../global.css'
 const inter = Inter({
  subsets: ['latin'],
  variable: '--font-geist-sans',
+  display: 'swap',
 })

 const geistMono = Geist_Mono({
  subsets: ['latin'],
  variable: '--font-geist-mono',
+  display: 'swap',
 })

 const { provider } = defineI18nUI(i18n, {
@@ -52,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',
@@ -93,27 +100,19 @@ export default async function Layout({ children, params }: LayoutProps) {
          type='application/ld+json'
          dangerouslySetInnerHTML={{ __html: JSON.stringify(structuredData) }}
        />
-        {/* OneDollarStats Analytics - CDN script handles everything automatically */}
-        <script defer src='https://assets.onedollarstats.com/stonks.js' />
      </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
            tree={source.pageTree[lang]}
            nav={{
-              title: (
-                <Image
-                  src='/static/logo.png'
-                  alt='Sim'
-                  width={72}
-                  height={28}
-                  className='h-7 w-auto'
-                  priority
-                />
-              ),
+              title: <SimLogoFull className='h-7 w-auto' />,
            }}
            sidebar={{
+              tabs: false,
              defaultOpenLevel: 0,
              collapsible: false,
              footer: null,
--- a/apps/docs/app/[lang]/not-found.tsx
+++ b/apps/docs/app/[lang]/not-found.tsx
@@ -9,7 +9,7 @@ export default function NotFound() {
    <DocsPage>
      <DocsBody>
        <div className='flex min-h-[60vh] flex-col items-center justify-center text-center'>
-          <h1 className='mb-4 bg-gradient-to-b from-[#8357FF] to-[#6F3DFA] bg-clip-text font-bold text-8xl text-transparent'>
+          <h1 className='mb-4 bg-gradient-to-b from-[#47d991] to-[#33c482] bg-clip-text font-bold text-8xl text-transparent'>
            404
          </h1>
          <h2 className='mb-2 font-semibold text-2xl text-foreground'>Page Not Found</h2>
--- a/apps/docs/app/api/og/route.tsx
+++ b/apps/docs/app/api/og/route.tsx
@@ -33,18 +33,42 @@ async function loadGoogleFont(font: string, weights: string, text: string): Prom
  throw new Error('Failed to load font data')
 }

+/**
+ * Sim logo with icon and "Sim" text for OG image.
+ */
+function SimLogoFull() {
+  return (
+    <svg height='28' viewBox='720 440 1020 320' fill='none'>
+      {/* Green icon - top left shape with cutout */}
+      <path
+        fillRule='evenodd'
+        clipRule='evenodd'
+        d='M875.791 577.171C875.791 581.922 873.911 586.483 870.576 589.842L870.098 590.323C866.764 593.692 862.234 595.575 857.517 595.575H750.806C740.978 595.575 733 603.6 733 613.498V728.902C733 738.799 740.978 746.826 750.806 746.826H865.382C875.209 746.826 883.177 738.799 883.177 728.902V620.853C883.177 616.448 884.912 612.222 888.008 609.104C891.093 605.997 895.29 604.249 899.664 604.249H1008.16C1017.99 604.249 1025.96 596.224 1025.96 586.327V470.923C1025.96 461.025 1017.99 453 1008.16 453H893.586C883.759 453 875.791 461.025 875.791 470.923V577.171ZM910.562 477.566H991.178C996.922 477.566 1001.57 482.254 1001.57 488.029V569.22C1001.57 574.995 996.922 579.683 991.178 579.683H910.562C904.828 579.683 900.173 574.995 900.173 569.22V488.029C900.173 482.254 904.828 477.566 910.562 477.566Z'
+        fill='#33C482'
+      />
+      {/* Green icon - bottom right square */}
+      <path
+        d='M1008.3 624.59H923.113C912.786 624.59 904.414 633.022 904.414 643.423V728.171C904.414 738.572 912.786 747.004 923.113 747.004H1008.3C1018.63 747.004 1027 738.572 1027 728.171V643.423C1027 633.022 1018.63 624.59 1008.3 624.59Z'
+        fill='#33C482'
+      />
+      {/* "Sim" text - white for dark background */}
+      <path
+        d='M1210.54 515.657C1226.65 515.657 1240.59 518.51 1252.31 524.257H1252.31C1264.3 529.995 1273.63 538.014 1280.26 548.319H1280.26C1287.19 558.635 1290.78 570.899 1291.08 585.068L1291.1 586.089H1249.11L1249.09 585.115C1248.8 574.003 1245.18 565.493 1238.32 559.451C1231.45 553.399 1221.79 550.308 1209.21 550.308C1196.3 550.308 1186.48 553.113 1179.61 558.588C1172.76 564.046 1169.33 571.499 1169.33 581.063C1169.33 588.092 1171.88 593.978 1177.01 598.783C1182.17 603.618 1189.99 607.399 1200.56 610.061H1200.56L1238.77 619.451C1257.24 623.65 1271.21 630.571 1280.57 640.293L1281.01 640.739C1290.13 650.171 1294.64 662.97 1294.64 679.016C1294.64 692.923 1290.88 705.205 1283.34 715.822L1283.33 715.834C1275.81 726.134 1265.44 734.14 1252.26 739.866L1252.25 739.871C1239.36 745.302 1224.12 748 1206.54 748C1180.9 748 1160.36 741.696 1145.02 728.984C1129.67 716.258 1122 699.269 1122 678.121V677.121H1163.99V678.121C1163.99 688.869 1167.87 697.367 1175.61 703.722L1176.34 704.284C1184.04 709.997 1194.37 712.902 1207.43 712.902C1222.13 712.902 1233.3 710.087 1241.07 704.588C1248.8 698.812 1252.64 691.21 1252.64 681.699C1252.64 674.769 1250.5 669.057 1246.25 664.49L1246.23 664.478L1246.22 664.464C1242.28 659.929 1234.83 656.119 1223.64 653.152L1185.43 644.208L1185.42 644.204C1166.05 639.407 1151.49 632.035 1141.83 622.012L1141.83 622.006L1141.82 622C1132.43 611.94 1127.78 598.707 1127.78 582.405C1127.78 568.81 1131.23 556.976 1138.17 546.949L1138.18 546.941L1138.19 546.933C1145.41 536.936 1155.18 529.225 1167.48 523.793L1167.48 523.79C1180.07 518.36 1194.43 515.657 1210.54 515.657ZM1323.39 521.979C1331.68 525.008 1337.55 526.482 1343.51 526.482C1349.48 526.482 1355.64 525.005 1364.49 521.973L1365.82 521.52V742.633H1322.05V521.489L1323.39 521.979ZM1642.01 515.657C1667.11 515.657 1686.94 523.031 1701.39 537.876C1715.83 552.716 1723 572.968 1723 598.507V742.633H1680.12V608.794C1680.12 591.666 1675.72 578.681 1667.07 569.681L1667.06 569.669L1667.04 569.656C1658.67 560.359 1647.26 555.675 1632.68 555.675C1622.47 555.675 1613.47 558.022 1605.64 562.69L1605.63 562.696C1598.11 567.064 1592.17 573.475 1587.8 581.968C1583.44 590.448 1581.25 600.424 1581.25 611.925V742.633H1537.92V608.347C1537.92 591.208 1533.67 578.376 1525.31 569.68L1525.31 569.674L1525.3 569.668C1516.93 560.664 1505.52 556.122 1490.93 556.122C1480.72 556.122 1471.72 558.469 1463.89 563.138L1463.88 563.144C1456.36 567.511 1450.41 573.922 1446.05 582.415L1446.05 582.422L1446.04 582.428C1441.69 590.602 1439.5 600.423 1439.5 611.925V742.633H1395.72V521.919H1435.05V554.803C1439.92 544.379 1447.91 535.465 1458.37 528.356C1470.71 519.875 1485.58 515.657 1502.93 515.657C1522.37 515.657 1538.61 520.931 1551.55 531.538C1560.38 538.771 1567.1 547.628 1571.72 558.091C1576.05 547.619 1582.83 538.757 1592.07 531.524C1605.61 520.93 1622.28 515.657 1642.01 515.657ZM1343.49 452C1351.45 452 1358.23 454.786 1363.75 460.346C1369.27 465.905 1372.04 472.721 1372.04 480.73C1372.04 488.452 1369.27 495.254 1363.77 501.096L1363.76 501.105L1363.75 501.115C1358.23 506.675 1351.45 509.461 1343.49 509.461C1335.81 509.461 1329.05 506.669 1323.25 501.134L1323.23 501.115L1323.21 501.096C1317.71 495.254 1314.94 488.452 1314.94 480.73C1314.94 472.721 1317.7 465.905 1323.23 460.346L1323.24 460.337L1323.25 460.327C1329.05 454.792 1335.81 452 1343.49 452Z'
+        fill='#fafafa'
+      />
+    </svg>
+  )
+}
+
 /**
 * Generates dynamic Open Graph images for documentation pages.
+ * Style matches Cursor docs: dark background, title at top, logo bottom-left, domain bottom-right.
 */
 export async function GET(request: NextRequest) {
  const { searchParams } = new URL(request.url)
  const title = searchParams.get('title') || 'Documentation'
-  const category = searchParams.get('category') || 'DOCUMENTATION'
-  const description = searchParams.get('description') || ''

-  const baseUrl = new URL(request.url).origin
-
-  const allText = `${title}${category}${description}docs.sim.ai`
+  const allText = `${title}docs.sim.ai`
  const fontData = await loadGoogleFont('Geist', '400;500;600', allText)

  return new ImageResponse(
@@ -54,116 +78,40 @@ export async function GET(request: NextRequest) {
        width: '100%',
        display: 'flex',
        flexDirection: 'column',
-        background: '#0c0c0c',
-        position: 'relative',
+        justifyContent: 'space-between',
+        padding: '56px 64px',
+        background: '#121212', // Dark mode background matching docs (hsla 0, 0%, 7%)
        fontFamily: 'Geist',
      }}
    >
-      {/* Base gradient layer - very subtle purple tint across the entire image */}
-      <div
+      {/* Title at top */}
+      <span
        style={{
-          position: 'absolute',
-          top: 0,
-          left: 0,
-          width: '100%',
-          height: '100%',
-          background:
-            'radial-gradient(ellipse 150% 100% at 50% 100%, rgba(88, 28, 135, 0.15) 0%, rgba(88, 28, 135, 0.08) 25%, rgba(88, 28, 135, 0.03) 50%, transparent 80%)',
-          display: 'flex',
-        }}
-      />
-
-      {/* Secondary glow - adds depth without harsh edges */}
-      <div
-        style={{
-          position: 'absolute',
-          top: 0,
-          left: 0,
-          width: '100%',
-          height: '100%',
-          background:
-            'radial-gradient(ellipse 100% 80% at 80% 90%, rgba(112, 31, 252, 0.12) 0%, rgba(112, 31, 252, 0.04) 40%, transparent 70%)',
-          display: 'flex',
-        }}
-      />
-
-      {/* Top darkening - creates natural vignette */}
-      <div
-        style={{
-          position: 'absolute',
-          top: 0,
-          left: 0,
-          width: '100%',
-          height: '100%',
-          background:
-            'linear-gradient(180deg, rgba(0, 0, 0, 0.3) 0%, transparent 40%, transparent 100%)',
-          display: 'flex',
-        }}
-      />
-
-      {/* Content */}
-      <div
-        style={{
-          display: 'flex',
-          flexDirection: 'column',
-          padding: '56px 72px',
-          height: '100%',
-          justifyContent: 'space-between',
+          fontSize: getTitleFontSize(title),
+          fontWeight: 500,
+          color: '#fafafa', // Light text matching docs
+          lineHeight: 1.2,
+          letterSpacing: '-0.02em',
        }}
      >
-        {/* Logo */}
-        <img src={`${baseUrl}/static/logo.png`} alt='sim' height={32} />
+        {title}
+      </span>

-        {/* Category + Title + Description */}
-        <div
-          style={{
-            display: 'flex',
-            flexDirection: 'column',
-            gap: 12,
-          }}
-        >
-          <span
-            style={{
-              fontSize: 15,
-              fontWeight: 600,
-              color: '#802fff',
-              letterSpacing: '0.02em',
-            }}
-          >
-            {category}
-          </span>
-          <span
-            style={{
-              fontSize: getTitleFontSize(title),
-              fontWeight: 600,
-              color: '#ffffff',
-              lineHeight: 1.1,
-              letterSpacing: '-0.02em',
-            }}
-          >
-            {title}
-          </span>
-          {description && (
-            <span
-              style={{
-                fontSize: 18,
-                fontWeight: 400,
-                color: '#a1a1aa',
-                lineHeight: 1.4,
-                marginTop: 4,
-              }}
-            >
-              {description.length > 100 ? `${description.slice(0, 100)}...` : description}
-            </span>
-          )}
-        </div>
-
-        {/* Footer */}
+      {/* Footer: icon left, domain right */}
+      <div
+        style={{
+          display: 'flex',
+          justifyContent: 'space-between',
+          alignItems: 'center',
+          width: '100%',
+        }}
+      >
+        <SimLogoFull />
        <span
          style={{
-            fontSize: 15,
-            fontWeight: 500,
-            color: '#52525b',
+            fontSize: 20,
+            fontWeight: 400,
+            color: '#71717a',
          }}
        >
          docs.sim.ai
--- a/apps/docs/app/api/search/route.ts
+++ b/apps/docs/app/api/search/route.ts
@@ -1,16 +1,211 @@
-import { createFromSource } from 'fumadocs-core/search/server'
-import { source } from '@/lib/source'
+import { sql } from 'drizzle-orm'
+import { type NextRequest, NextResponse } from 'next/server'
+import { db, docsEmbeddings } from '@/lib/db'
+import { generateSearchEmbedding } from '@/lib/embeddings'

-export const revalidate = 3600 // Revalidate every hour
+export const runtime = 'nodejs'
+export const revalidate = 0

-export const { GET } = createFromSource(source, {
-  localeMap: {
-    en: { language: 'english' },
-    es: { language: 'spanish' },
-    fr: { language: 'french' },
-    de: { language: 'german' },
-    // ja and zh are not supported by the stemmer library, so we'll skip language config for them
-    ja: {},
-    zh: {},
-  },
-})
+/**
+ * Hybrid search API endpoint
+ * - English: Vector embeddings + keyword search
+ * - Other languages: Keyword search only
+ */
+export async function GET(request: NextRequest) {
+  try {
+    const searchParams = request.nextUrl.searchParams
+    const query = searchParams.get('query') || searchParams.get('q') || ''
+    const locale = searchParams.get('locale') || 'en'
+    const limit = Number.parseInt(searchParams.get('limit') || '10', 10)
+
+    if (!query || query.trim().length === 0) {
+      return NextResponse.json([])
+    }
+
+    const candidateLimit = limit * 3
+    const similarityThreshold = 0.6
+
+    const localeMap: Record<string, string> = {
+      en: 'english',
+      es: 'spanish',
+      fr: 'french',
+      de: 'german',
+      ja: 'simple', // PostgreSQL doesn't have Japanese support, use simple
+      zh: 'simple', // PostgreSQL doesn't have Chinese support, use simple
+    }
+    const tsConfig = localeMap[locale] || 'simple'
+
+    const useVectorSearch = locale === 'en'
+    let vectorResults: Array<{
+      chunkId: string
+      chunkText: string
+      sourceDocument: string
+      sourceLink: string
+      headerText: string
+      headerLevel: number
+      similarity: number
+      searchType: string
+    }> = []
+
+    if (useVectorSearch) {
+      const queryEmbedding = await generateSearchEmbedding(query)
+      vectorResults = await db
+        .select({
+          chunkId: docsEmbeddings.chunkId,
+          chunkText: docsEmbeddings.chunkText,
+          sourceDocument: docsEmbeddings.sourceDocument,
+          sourceLink: docsEmbeddings.sourceLink,
+          headerText: docsEmbeddings.headerText,
+          headerLevel: docsEmbeddings.headerLevel,
+          similarity: sql<number>`1 - (${docsEmbeddings.embedding} <=> ${JSON.stringify(queryEmbedding)}::vector)`,
+          searchType: sql<string>`'vector'`,
+        })
+        .from(docsEmbeddings)
+        .where(
+          sql`1 - (${docsEmbeddings.embedding} <=> ${JSON.stringify(queryEmbedding)}::vector) >= ${similarityThreshold}`
+        )
+        .orderBy(sql`${docsEmbeddings.embedding} <=> ${JSON.stringify(queryEmbedding)}::vector`)
+        .limit(candidateLimit)
+    }
+
+    const keywordResults = await db
+      .select({
+        chunkId: docsEmbeddings.chunkId,
+        chunkText: docsEmbeddings.chunkText,
+        sourceDocument: docsEmbeddings.sourceDocument,
+        sourceLink: docsEmbeddings.sourceLink,
+        headerText: docsEmbeddings.headerText,
+        headerLevel: docsEmbeddings.headerLevel,
+        similarity: sql<number>`ts_rank(${docsEmbeddings.chunkTextTsv}, plainto_tsquery(${tsConfig}, ${query}))`,
+        searchType: sql<string>`'keyword'`,
+      })
+      .from(docsEmbeddings)
+      .where(sql`${docsEmbeddings.chunkTextTsv} @@ plainto_tsquery(${tsConfig}, ${query})`)
+      .orderBy(
+        sql`ts_rank(${docsEmbeddings.chunkTextTsv}, plainto_tsquery(${tsConfig}, ${query})) DESC`
+      )
+      .limit(candidateLimit)
+
+    const knownLocales = ['en', 'es', 'fr', 'de', 'ja', 'zh']
+
+    const vectorRankMap = new Map<string, number>()
+    vectorResults.forEach((r, idx) => vectorRankMap.set(r.chunkId, idx + 1))
+
+    const keywordRankMap = new Map<string, number>()
+    keywordResults.forEach((r, idx) => keywordRankMap.set(r.chunkId, idx + 1))
+
+    const allChunkIds = new Set([
+      ...vectorResults.map((r) => r.chunkId),
+      ...keywordResults.map((r) => r.chunkId),
+    ])
+
+    const k = 60
+    type ResultWithRRF = (typeof vectorResults)[0] & { rrfScore: number }
+    const scoredResults: ResultWithRRF[] = []
+
+    for (const chunkId of allChunkIds) {
+      const vectorRank = vectorRankMap.get(chunkId) ?? Number.POSITIVE_INFINITY
+      const keywordRank = keywordRankMap.get(chunkId) ?? Number.POSITIVE_INFINITY
+
+      const rrfScore = 1 / (k + vectorRank) + 1 / (k + keywordRank)
+
+      const result =
+        vectorResults.find((r) => r.chunkId === chunkId) ||
+        keywordResults.find((r) => r.chunkId === chunkId)
+
+      if (result) {
+        scoredResults.push({ ...result, rrfScore })
+      }
+    }
+
+    scoredResults.sort((a, b) => b.rrfScore - a.rrfScore)
+
+    const localeFilteredResults = scoredResults.filter((result) => {
+      const firstPart = result.sourceDocument.split('/')[0]
+      if (knownLocales.includes(firstPart)) {
+        return firstPart === locale
+      }
+      return locale === 'en'
+    })
+
+    const queryLower = query.toLowerCase()
+    const getTitleBoost = (result: ResultWithRRF): number => {
+      const fileName = result.sourceDocument
+        .replace('.mdx', '')
+        .split('/')
+        .pop()
+        ?.toLowerCase()
+        ?.replace(/_/g, ' ')
+
+      if (fileName === queryLower) return 0.01
+      if (fileName?.includes(queryLower)) return 0.005
+      return 0
+    }
+
+    localeFilteredResults.sort((a, b) => {
+      return b.rrfScore + getTitleBoost(b) - (a.rrfScore + getTitleBoost(a))
+    })
+
+    const pageMap = new Map<string, ResultWithRRF>()
+
+    for (const result of localeFilteredResults) {
+      const pageKey = result.sourceDocument
+      const existing = pageMap.get(pageKey)
+
+      if (!existing || result.rrfScore > existing.rrfScore) {
+        pageMap.set(pageKey, result)
+      }
+    }
+
+    const deduplicatedResults = Array.from(pageMap.values())
+      .sort((a, b) => b.rrfScore + getTitleBoost(b) - (a.rrfScore + getTitleBoost(a)))
+      .slice(0, limit)
+
+    const searchResults = deduplicatedResults.map((result) => {
+      const title = result.headerText || result.sourceDocument.replace('.mdx', '')
+
+      const pathParts = result.sourceDocument
+        .replace('.mdx', '')
+        .split('/')
+        .filter((part) => part !== 'index' && !knownLocales.includes(part))
+        .map((part) => {
+          return part
+            .replace(/_/g, ' ')
+            .split(' ')
+            .map((word) => {
+              const acronyms = [
+                'api',
+                'mcp',
+                'sdk',
+                'url',
+                'http',
+                'json',
+                'xml',
+                'html',
+                'css',
+                'ai',
+              ]
+              if (acronyms.includes(word.toLowerCase())) {
+                return word.toUpperCase()
+              }
+              return word.charAt(0).toUpperCase() + word.slice(1)
+            })
+            .join(' ')
+        })
+
+      return {
+        id: result.chunkId,
+        type: 'page' as const,
+        url: result.sourceLink,
+        content: title,
+        breadcrumbs: pathParts,
+      }
+    })
+
+    return NextResponse.json(searchResults)
+  } catch (error) {
+    console.error('Semantic search error:', error)
+
+    return NextResponse.json([])
+  }
+}
--- a/apps/docs/app/global.css
+++ b/apps/docs/app/global.css
--- a/apps/docs/app/layout.config.tsx
+++ b/apps/docs/app/layout.config.tsx
@@ -1,21 +0,0 @@
-import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared'
-
-/**
- * Shared layout configurations
- *
- * you can customise layouts individually from:
- * Home Layout: app/(home)/layout.tsx
- * Docs Layout: app/docs/layout.tsx
- */
-export const baseOptions: BaseLayoutProps = {
-  nav: {
-    title: (
-      <>
-        <svg width='24' height='24' xmlns='http://www.w3.org/2000/svg' aria-label='Logo'>
-          <circle cx={12} cy={12} r={12} fill='currentColor' />
-        </svg>
-        My App
-      </>
-    ),
-  },
-}
--- a/apps/docs/app/layout.tsx
+++ b/apps/docs/app/layout.tsx
@@ -7,26 +7,27 @@ export default function RootLayout({ children }: { children: ReactNode }) {
 export const metadata = {
  metadataBase: new URL('https://docs.sim.ai'),
  title: {
-    default: 'Sim Documentation - Visual Workflow Builder for AI Applications',
+    default: 'Sim Documentation — Build AI Agents & Run Your Agentic Workforce',
    template: '%s',
  },
  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.',
  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',
@@ -53,12 +54,12 @@ export const metadata = {
    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&category=DOCUMENTATION',
+        url: 'https://docs.sim.ai/api/og?title=Sim%20Documentation',
        width: 1200,
        height: 630,
        alt: 'Sim Documentation',
@@ -67,12 +68,12 @@ 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&category=DOCUMENTATION'],
+    images: ['https://docs.sim.ai/api/og?title=Sim%20Documentation'],
  },
  robots: {
    index: true,
--- a/apps/docs/app/llms.mdx/[[...slug]]/route.ts
+++ b/apps/docs/app/llms.mdx/[[...slug]]/route.ts
@@ -6,7 +6,10 @@ import { source } from '@/lib/source'

 export const revalidate = false

-export async function GET(_req: NextRequest, { params }: { params: Promise<{ slug?: string[] }> }) {
+export async function GET(
+  _request: NextRequest,
+  { params }: { params: Promise<{ slug?: string[] }> }
+) {
  const { slug } = await params

  let lang: (typeof i18n.languages)[number] = i18n.defaultLanguage
--- a/apps/docs/app/llms.txt/route.ts
+++ b/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

--- a/apps/docs/components/docs-layout/sidebar-components.tsx
+++ b/apps/docs/components/docs-layout/sidebar-components.tsx
@@ -44,7 +44,7 @@ export function SidebarItem({ item }: { item: Item }) {
        'lg:text-gray-600 lg:dark:text-gray-400',
        !active && 'lg:hover:bg-gray-100/60 lg:dark:hover:bg-gray-800/40',
        active &&
-          'lg:bg-purple-50/80 lg:font-normal lg:text-purple-600 lg:dark:bg-purple-900/15 lg:dark:text-purple-400'
+          'lg:bg-emerald-50/80 lg:font-normal lg:text-emerald-600 lg:dark:bg-emerald-900/15 lg:dark:text-emerald-400'
      )}
    >
      {item.name}
@@ -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

@@ -79,7 +90,7 @@ export function SidebarFolder({ item, children }: { item: Folder; children: Reac
          'lg:text-gray-600 lg:dark:text-gray-400',
          !active && 'lg:hover:bg-gray-100/60 lg:dark:hover:bg-gray-800/40',
          active &&
-            'lg:bg-purple-50/80 lg:font-normal lg:text-purple-600 lg:dark:bg-purple-900/15 lg:dark:text-purple-400'
+            'lg:bg-emerald-50/80 lg:font-normal lg:text-emerald-600 lg:dark:bg-emerald-900/15 lg:dark:text-emerald-400'
        )}
      >
        {item.name}
@@ -104,7 +115,7 @@ export function SidebarFolder({ item, children }: { item: Folder; children: Reac
              'lg:text-gray-800 lg:dark:text-gray-200',
              !active && 'lg:hover:bg-gray-100/60 lg:dark:hover:bg-gray-800/40',
              active &&
-                'lg:bg-purple-50/80 lg:text-purple-600 lg:dark:bg-purple-900/15 lg:dark:text-purple-400'
+                'lg:bg-emerald-50/80 lg:text-emerald-600 lg:dark:bg-emerald-900/15 lg:dark:text-emerald-400'
            )}
          >
            {item.name}
@@ -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>
--- a/apps/docs/components/docs-layout/toc-footer.tsx
+++ b/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-[#6F3DFA] bg-gradient-to-b from-[#8357FF] to-[#6F3DFA] px-3 pr-[10px] pl-[12px] font-medium text-sm text-white shadow-[inset_0_2px_4px_0_#9B77FF] 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>
--- a/apps/docs/components/icons.tsx
+++ b/apps/docs/components/icons.tsx
--- a/apps/docs/components/navbar/navbar.tsx
+++ b/apps/docs/components/navbar/navbar.tsx
@@ -1,65 +1,95 @@
 'use client'

-import Image from 'next/image'
 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'
-      style={{
-        backdropFilter: 'blur(25px) saturate(180%)',
-        WebkitBackdropFilter: 'blur(25px) saturate(180%)',
-      }}
-    >
-      {/* 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'>
-              <Image
-                src='/static/logo.png'
-                alt='Sim'
-                width={72}
-                height={28}
-                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>
  )
--- a/apps/docs/components/page-actions.tsx
+++ b/apps/docs/components/page-actions.tsx
@@ -1,45 +1,13 @@
 'use client'

-import { useState } from 'react'
 import { useCopyButton } from 'fumadocs-ui/utils/use-copy-button'
 import { Check, Copy } from 'lucide-react'

-const cache = new Map<string, string>()
-
-export function LLMCopyButton({
-  markdownUrl,
-}: {
-  /**
-   * A URL to fetch the raw Markdown/MDX content of page
-   */
-  markdownUrl: string
-}) {
-  const [isLoading, setLoading] = useState(false)
-  const [checked, onClick] = useCopyButton(async () => {
-    const cached = cache.get(markdownUrl)
-    if (cached) return navigator.clipboard.writeText(cached)
-
-    setLoading(true)
-
-    try {
-      await navigator.clipboard.write([
-        new ClipboardItem({
-          'text/plain': fetch(markdownUrl).then(async (res) => {
-            const content = await res.text()
-            cache.set(markdownUrl, content)
-
-            return content
-          }),
-        }),
-      ])
-    } finally {
-      setLoading(false)
-    }
-  })
+export function LLMCopyButton({ content }: { content: string }) {
+  const [checked, onClick] = useCopyButton(() => navigator.clipboard.writeText(content))

  return (
    <button
-      disabled={isLoading}
      onClick={onClick}
      className='flex cursor-pointer items-center gap-1.5 rounded-lg border border-border/40 bg-background px-2.5 py-2 text-muted-foreground/60 text-sm leading-none transition-all hover:border-border hover:bg-accent/50 hover:text-muted-foreground'
      aria-label={checked ? 'Copied to clipboard' : 'Copy page content'}
--- a/apps/docs/components/structured-data.tsx
+++ b/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'
--- a/apps/docs/components/ui/action-media.tsx
+++ b/apps/docs/components/ui/action-media.tsx
@@ -0,0 +1,87 @@
+'use client'
+
+import { useState } from 'react'
+import { cn, getAssetUrl } from '@/lib/utils'
+import { Lightbox } from './lightbox'
+
+interface ActionImageProps {
+  src: string
+  alt: string
+  enableLightbox?: boolean
+}
+
+interface ActionVideoProps {
+  src: string
+  alt: string
+  enableLightbox?: boolean
+}
+
+export function ActionImage({ src, alt, enableLightbox = true }: ActionImageProps) {
+  const [isLightboxOpen, setIsLightboxOpen] = useState(false)
+
+  const handleClick = () => {
+    if (enableLightbox) {
+      setIsLightboxOpen(true)
+    }
+  }
+
+  return (
+    <>
+      <img
+        src={src}
+        alt={alt}
+        onClick={handleClick}
+        className={cn(
+          'inline-block w-full max-w-[200px] rounded border border-neutral-200 dark:border-neutral-700',
+          enableLightbox && 'cursor-pointer transition-opacity hover:opacity-90'
+        )}
+      />
+      {enableLightbox && (
+        <Lightbox
+          isOpen={isLightboxOpen}
+          onClose={() => setIsLightboxOpen(false)}
+          src={src}
+          alt={alt}
+          type='image'
+        />
+      )}
+    </>
+  )
+}
+
+export function ActionVideo({ src, alt, enableLightbox = true }: ActionVideoProps) {
+  const [isLightboxOpen, setIsLightboxOpen] = useState(false)
+  const resolvedSrc = getAssetUrl(src)
+
+  const handleClick = () => {
+    if (enableLightbox) {
+      setIsLightboxOpen(true)
+    }
+  }
+
+  return (
+    <>
+      <video
+        src={resolvedSrc}
+        autoPlay
+        loop
+        muted
+        playsInline
+        onClick={handleClick}
+        className={cn(
+          'inline-block w-full max-w-[200px] rounded border border-neutral-200 dark:border-neutral-700',
+          enableLightbox && 'cursor-pointer transition-opacity hover:opacity-90'
+        )}
+      />
+      {enableLightbox && (
+        <Lightbox
+          isOpen={isLightboxOpen}
+          onClose={() => setIsLightboxOpen(false)}
+          src={src}
+          alt={alt}
+          type='video'
+        />
+      )}
+    </>
+  )
+}
--- a/apps/docs/components/ui/animated-blocks.tsx
+++ b/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>
+  )
+}
--- a/apps/docs/components/ui/code-block.tsx
+++ b/apps/docs/components/ui/code-block.tsx
@@ -17,23 +17,16 @@ export function CodeBlock(props: React.ComponentProps<typeof FumadocsCodeBlock>)
  return (
    <FumadocsCodeBlock
      {...props}
-      Actions={({ children, className }) => (
+      Actions={({ className }) => (
        <div className={cn('empty:hidden', className)}>
-          {/* Custom copy button */}
          <button
            type='button'
            aria-label={copied ? 'Copied Text' : 'Copy Text'}
            onClick={(e) => {
-              const pre = (e.currentTarget as HTMLElement)
-                .closest('.nd-codeblock')
-                ?.querySelector('pre')
+              const pre = (e.currentTarget as HTMLElement).closest('figure')?.querySelector('pre')
              if (pre) handleCopy(pre.textContent || '')
            }}
-            className={cn(
-              'cursor-pointer rounded-md p-2 transition-all',
-              'border border-border bg-background/80 hover:bg-muted',
-              'backdrop-blur-sm'
-            )}
+            className='cursor-pointer rounded-md p-2 text-muted-foreground transition-colors hover:text-foreground'
          >
            <span className='flex items-center justify-center'>
              {copied ? (
--- a/apps/docs/components/ui/dropdown-menu.tsx
+++ b/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,
+}
--- a/apps/docs/components/ui/faq.tsx
+++ b/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>
+  )
+}
--- a/apps/docs/components/ui/icon-mapping.ts
+++ b/apps/docs/components/ui/icon-mapping.ts
@@ -4,42 +4,76 @@

 import type { ComponentType, SVGProps } from 'react'
 import {
+  A2AIcon,
  AhrefsIcon,
  AirtableIcon,
+  AirweaveIcon,
+  AlgoliaIcon,
+  AmplitudeIcon,
  ApifyIcon,
  ApolloIcon,
  ArxivIcon,
  AsanaIcon,
+  AshbyIcon,
+  AttioIcon,
  BrainIcon,
+  BrandfetchIcon,
  BrowserUseIcon,
+  CalComIcon,
  CalendlyIcon,
+  CirclebackIcon,
  ClayIcon,
+  ClerkIcon,
+  CloudflareIcon,
  ConfluenceIcon,
  CursorIcon,
+  DatabricksIcon,
  DatadogIcon,
+  DevinIcon,
  DiscordIcon,
  DocumentIcon,
  DropboxIcon,
+  DsPyIcon,
+  DubIcon,
  DuckDuckGoIcon,
  DynamoDBIcon,
  ElasticsearchIcon,
  ElevenLabsIcon,
+  EnrichSoIcon,
+  EvernoteIcon,
  ExaAIIcon,
  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,
+  GreenhouseIcon,
+  GreptileIcon,
+  HexIcon,
  HubspotIcon,
  HuggingFaceIcon,
  HunterIOIcon,
@@ -48,13 +82,20 @@ import {
  IntercomIcon,
  JinaAIIcon,
  JiraIcon,
+  JiraServiceManagementIcon,
  KalshiIcon,
+  LangsmithIcon,
+  LemlistIcon,
  LinearIcon,
  LinkedInIcon,
  LinkupIcon,
+  LoopsIcon,
+  LumaIcon,
  MailchimpIcon,
  MailgunIcon,
+  MailServerIcon,
  Mem0Icon,
+  MicrosoftDataverseIcon,
  MicrosoftExcelIcon,
  MicrosoftOneDriveIcon,
  MicrosoftPlannerIcon,
@@ -65,9 +106,12 @@ import {
  MySQLIcon,
  Neo4jIcon,
  NotionIcon,
+  ObsidianIcon,
+  OnePasswordIcon,
  OpenAIIcon,
  OutlookIcon,
  PackageSearchIcon,
+  PagerDutyIcon,
  ParallelIcon,
  PerplexityIcon,
  PineconeIcon,
@@ -75,10 +119,14 @@ import {
  PolymarketIcon,
  PostgresIcon,
  PosthogIcon,
+  PulseIcon,
  QdrantIcon,
  RDSIcon,
  RedditIcon,
+  RedisIcon,
+  ReductoIcon,
  ResendIcon,
+  RevenueCatIcon,
  S3Icon,
  SalesforceIcon,
  SearchIcon,
@@ -88,9 +136,9 @@ import {
  ServiceNowIcon,
  SftpIcon,
  ShopifyIcon,
+  SimilarwebIcon,
  SlackIcon,
  SmtpIcon,
-  SpotifyIcon,
  SQSIcon,
  SshIcon,
  STTIcon,
@@ -99,11 +147,15 @@ import {
  SupabaseIcon,
  TavilyIcon,
  TelegramIcon,
+  TextractIcon,
+  TinybirdIcon,
  TranslateIcon,
  TrelloIcon,
  TTSIcon,
  TwilioIcon,
  TypeformIcon,
+  UpstashIcon,
+  VercelIcon,
  VideoIcon,
  WealthboxIcon,
  WebflowIcon,
@@ -120,117 +172,168 @@ import {
 type IconComponent = ComponentType<SVGProps<SVGSVGElement>>

 export const blockTypeToIconMap: Record<string, IconComponent> = {
-  zoom: ZoomIcon,
-  zep: ZepIcon,
-  zendesk: ZendeskIcon,
-  youtube: YouTubeIcon,
-  x: xIcon,
-  wordpress: WordpressIcon,
-  wikipedia: WikipediaIcon,
-  whatsapp: WhatsAppIcon,
-  webflow: WebflowIcon,
-  wealthbox: WealthboxIcon,
-  vision: EyeIcon,
-  video_generator: VideoIcon,
-  typeform: TypeformIcon,
-  twilio_voice: TwilioIcon,
-  twilio_sms: TwilioIcon,
-  tts: TTSIcon,
-  trello: TrelloIcon,
-  translate: TranslateIcon,
-  thinking: BrainIcon,
-  telegram: TelegramIcon,
-  tavily: TavilyIcon,
-  supabase: SupabaseIcon,
-  stt: STTIcon,
-  stripe: StripeIcon,
-  stagehand: StagehandIcon,
-  ssh: SshIcon,
-  sqs: SQSIcon,
-  spotify: SpotifyIcon,
-  smtp: SmtpIcon,
-  slack: SlackIcon,
-  shopify: ShopifyIcon,
-  sharepoint: MicrosoftSharepointIcon,
-  sftp: SftpIcon,
-  servicenow: ServiceNowIcon,
-  serper: SerperIcon,
-  sentry: SentryIcon,
-  sendgrid: SendgridIcon,
-  search: SearchIcon,
-  salesforce: SalesforceIcon,
-  s3: S3Icon,
-  resend: ResendIcon,
-  reddit: RedditIcon,
-  rds: RDSIcon,
-  qdrant: QdrantIcon,
-  posthog: PosthogIcon,
-  postgresql: PostgresIcon,
-  polymarket: PolymarketIcon,
-  pipedrive: PipedriveIcon,
-  pinecone: PineconeIcon,
-  perplexity: PerplexityIcon,
-  parallel_ai: ParallelIcon,
-  outlook: OutlookIcon,
-  openai: OpenAIIcon,
-  onedrive: MicrosoftOneDriveIcon,
-  notion: NotionIcon,
-  neo4j: Neo4jIcon,
-  mysql: MySQLIcon,
-  mongodb: MongoDBIcon,
-  mistral_parse: MistralIcon,
-  microsoft_teams: MicrosoftTeamsIcon,
-  microsoft_planner: MicrosoftPlannerIcon,
-  microsoft_excel: MicrosoftExcelIcon,
-  memory: BrainIcon,
-  mem0: Mem0Icon,
-  mailgun: MailgunIcon,
-  mailchimp: MailchimpIcon,
-  linkup: LinkupIcon,
-  linkedin: LinkedInIcon,
-  linear: LinearIcon,
-  knowledge: PackageSearchIcon,
-  kalshi: KalshiIcon,
-  jira: JiraIcon,
-  jina: JinaAIIcon,
-  intercom: IntercomIcon,
-  incidentio: IncidentioIcon,
-  image_generator: ImageIcon,
-  hunter: HunterIOIcon,
-  huggingface: HuggingFaceIcon,
-  hubspot: HubspotIcon,
-  grafana: GrafanaIcon,
-  google_vault: GoogleVaultIcon,
-  google_slides: GoogleSlidesIcon,
-  google_sheets: GoogleSheetsIcon,
-  google_groups: GoogleGroupsIcon,
-  google_forms: GoogleFormsIcon,
-  google_drive: GoogleDriveIcon,
-  google_docs: GoogleDocsIcon,
-  google_calendar: GoogleCalendarIcon,
-  google_search: GoogleIcon,
-  gmail: GmailIcon,
-  gitlab: GitLabIcon,
-  github: GithubIcon,
-  firecrawl: FirecrawlIcon,
-  file: DocumentIcon,
-  exa: ExaAIIcon,
-  elevenlabs: ElevenLabsIcon,
-  elasticsearch: ElasticsearchIcon,
-  dynamodb: DynamoDBIcon,
-  duckduckgo: DuckDuckGoIcon,
-  dropbox: DropboxIcon,
-  discord: DiscordIcon,
-  datadog: DatadogIcon,
-  cursor: CursorIcon,
-  confluence: ConfluenceIcon,
-  clay: ClayIcon,
-  calendly: CalendlyIcon,
-  browser_use: BrowserUseIcon,
-  asana: AsanaIcon,
-  arxiv: ArxivIcon,
-  apollo: ApolloIcon,
-  apify: ApifyIcon,
-  airtable: AirtableIcon,
+  a2a: A2AIcon,
  ahrefs: AhrefsIcon,
+  airtable: AirtableIcon,
+  airweave: AirweaveIcon,
+  algolia: AlgoliaIcon,
+  amplitude: AmplitudeIcon,
+  apify: ApifyIcon,
+  apollo: ApolloIcon,
+  arxiv: ArxivIcon,
+  asana: AsanaIcon,
+  ashby: AshbyIcon,
+  attio: AttioIcon,
+  brandfetch: BrandfetchIcon,
+  browser_use: BrowserUseIcon,
+  calcom: CalComIcon,
+  calendly: CalendlyIcon,
+  circleback: CirclebackIcon,
+  clay: ClayIcon,
+  clerk: ClerkIcon,
+  cloudflare: CloudflareIcon,
+  confluence_v2: ConfluenceIcon,
+  cursor_v2: CursorIcon,
+  databricks: DatabricksIcon,
+  datadog: DatadogIcon,
+  devin: DevinIcon,
+  discord: DiscordIcon,
+  dropbox: DropboxIcon,
+  dspy: DsPyIcon,
+  dub: DubIcon,
+  duckduckgo: DuckDuckGoIcon,
+  dynamodb: DynamoDBIcon,
+  elasticsearch: ElasticsearchIcon,
+  elevenlabs: ElevenLabsIcon,
+  enrich: EnrichSoIcon,
+  evernote: EvernoteIcon,
+  exa: ExaAIIcon,
+  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,
+  greenhouse: GreenhouseIcon,
+  greptile: GreptileIcon,
+  hex: HexIcon,
+  hubspot: HubspotIcon,
+  huggingface: HuggingFaceIcon,
+  hunter: HunterIOIcon,
+  image_generator: ImageIcon,
+  imap: MailServerIcon,
+  incidentio: IncidentioIcon,
+  intercom_v2: IntercomIcon,
+  jina: JinaAIIcon,
+  jira: JiraIcon,
+  jira_service_management: JiraServiceManagementIcon,
+  kalshi_v2: KalshiIcon,
+  knowledge: PackageSearchIcon,
+  langsmith: LangsmithIcon,
+  lemlist: LemlistIcon,
+  linear: LinearIcon,
+  linkedin: LinkedInIcon,
+  linkup: LinkupIcon,
+  loops: LoopsIcon,
+  luma: LumaIcon,
+  mailchimp: MailchimpIcon,
+  mailgun: MailgunIcon,
+  mem0: Mem0Icon,
+  memory: BrainIcon,
+  microsoft_dataverse: MicrosoftDataverseIcon,
+  microsoft_excel_v2: MicrosoftExcelIcon,
+  microsoft_planner: MicrosoftPlannerIcon,
+  microsoft_teams: MicrosoftTeamsIcon,
+  mistral_parse_v3: MistralIcon,
+  mongodb: MongoDBIcon,
+  mysql: MySQLIcon,
+  neo4j: Neo4jIcon,
+  notion_v2: NotionIcon,
+  obsidian: ObsidianIcon,
+  onedrive: MicrosoftOneDriveIcon,
+  onepassword: OnePasswordIcon,
+  openai: OpenAIIcon,
+  outlook: OutlookIcon,
+  pagerduty: PagerDutyIcon,
+  parallel_ai: ParallelIcon,
+  perplexity: PerplexityIcon,
+  pinecone: PineconeIcon,
+  pipedrive: PipedriveIcon,
+  polymarket: PolymarketIcon,
+  postgresql: PostgresIcon,
+  posthog: PosthogIcon,
+  pulse_v2: PulseIcon,
+  qdrant: QdrantIcon,
+  rds: RDSIcon,
+  reddit: RedditIcon,
+  redis: RedisIcon,
+  reducto_v2: ReductoIcon,
+  resend: ResendIcon,
+  revenuecat: RevenueCatIcon,
+  s3: S3Icon,
+  salesforce: SalesforceIcon,
+  search: SearchIcon,
+  sendgrid: SendgridIcon,
+  sentry: SentryIcon,
+  serper: SerperIcon,
+  servicenow: ServiceNowIcon,
+  sftp: SftpIcon,
+  sharepoint: MicrosoftSharepointIcon,
+  shopify: ShopifyIcon,
+  similarweb: SimilarwebIcon,
+  slack: SlackIcon,
+  smtp: SmtpIcon,
+  sqs: SQSIcon,
+  ssh: SshIcon,
+  stagehand: StagehandIcon,
+  stripe: StripeIcon,
+  stt_v2: STTIcon,
+  supabase: SupabaseIcon,
+  tavily: TavilyIcon,
+  telegram: TelegramIcon,
+  textract_v2: TextractIcon,
+  tinybird: TinybirdIcon,
+  translate: TranslateIcon,
+  trello: TrelloIcon,
+  tts: TTSIcon,
+  twilio_sms: TwilioIcon,
+  twilio_voice: TwilioIcon,
+  typeform: TypeformIcon,
+  upstash: UpstashIcon,
+  vercel: VercelIcon,
+  video_generator_v2: VideoIcon,
+  vision_v2: EyeIcon,
+  wealthbox: WealthboxIcon,
+  webflow: WebflowIcon,
+  whatsapp: WhatsAppIcon,
+  wikipedia: WikipediaIcon,
+  wordpress: WordpressIcon,
+  x: xIcon,
+  youtube: YouTubeIcon,
+  zendesk: ZendeskIcon,
+  zep: ZepIcon,
+  zoom: ZoomIcon,
 }
--- a/apps/docs/components/ui/image.tsx
+++ b/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}
--- a/apps/docs/components/ui/language-dropdown.tsx
+++ b/apps/docs/components/ui/language-dropdown.tsx
@@ -1,8 +1,9 @@
 'use client'

 import { useEffect, useState } from 'react'
-import { Check, ChevronRight } from 'lucide-react'
+import { Check, ChevronDown } from 'lucide-react'
 import { useParams, usePathname, useRouter } from 'next/navigation'
+import { cn } from '@/lib/utils'

 const languages = {
  en: { name: 'English', flag: '🇺🇸' },
@@ -15,6 +16,7 @@ const languages = {

 export function LanguageDropdown() {
  const [isOpen, setIsOpen] = useState(false)
+  const [hoveredIndex, setHoveredIndex] = useState<number>(-1)
  const pathname = usePathname()
  const params = useParams()
  const router = useRouter()
@@ -71,6 +73,15 @@ export function LanguageDropdown() {
    return () => window.removeEventListener('keydown', onKey)
  }, [isOpen])

+  // Reset hovered index when popover closes
+  useEffect(() => {
+    if (!isOpen) {
+      setHoveredIndex(-1)
+    }
+  }, [isOpen])
+
+  const languageEntries = Object.entries(languages)
+
  return (
    <div className='relative'>
      <button
@@ -82,14 +93,14 @@ export function LanguageDropdown() {
        aria-haspopup='listbox'
        aria-expanded={isOpen}
        aria-controls='language-menu'
-        className='flex cursor-pointer items-center gap-1.5 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 focus:outline-none focus-visible:ring-2 focus-visible:ring-ring'
+        className='flex cursor-pointer items-center gap-1.5 rounded-[6px] px-3 py-2 font-normal text-[0.9375rem] text-foreground/60 leading-[1.4] transition-colors hover:bg-foreground/8 hover:text-foreground focus:outline-none focus-visible:ring-2 focus-visible:ring-ring'
        style={{
          fontFamily:
            '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
        }}
      >
        <span>{languages[currentLang as keyof typeof languages]?.name}</span>
-        <ChevronRight className='h-3.5 w-3.5' />
+        <ChevronDown className={cn('h-3.5 w-3.5 transition-transform', isOpen && 'rotate-180')} />
      </button>

      {isOpen && (
@@ -98,29 +109,37 @@ export function LanguageDropdown() {
          <div
            id='language-menu'
            role='listbox'
-            className='absolute top-full right-0 z-[1001] mt-1 max-h-[75vh] w-56 overflow-auto rounded-xl border border-border/50 bg-white shadow-2xl md:w-44 md:bg-background/95 md:backdrop-blur-md dark:bg-neutral-950 md:dark:bg-background/95'
+            className='absolute top-full right-0 z-[1001] mt-2 max-h-[400px] min-w-[160px] overflow-auto rounded-[6px] bg-white px-[6px] py-[6px] shadow-lg dark:bg-neutral-900'
          >
-            {Object.entries(languages).map(([code, lang]) => (
-              <button
-                key={code}
-                onClick={(e) => {
-                  e.preventDefault()
-                  e.stopPropagation()
-                  handleLanguageChange(code)
-                }}
-                role='option'
-                aria-selected={currentLang === code}
-                className={`flex w-full cursor-pointer items-center gap-3 px-3 py-3 text-base transition-colors first:rounded-t-xl last:rounded-b-xl hover:bg-muted/80 focus:outline-none focus-visible:ring-2 focus-visible:ring-ring md:gap-2 md:px-2.5 md:py-2 md:text-sm ${
-                  currentLang === code ? 'bg-muted/60 font-medium text-primary' : 'text-foreground'
-                }`}
-              >
-                <span className='text-base md:text-sm'>{lang.flag}</span>
-                <span className='leading-none'>{lang.name}</span>
-                {currentLang === code && (
-                  <Check className='ml-auto h-4 w-4 text-primary md:h-3.5 md:w-3.5' />
-                )}
-              </button>
-            ))}
+            {languageEntries.map(([code, lang], index) => {
+              const isSelected = currentLang === code
+              const isHovered = hoveredIndex === index
+
+              return (
+                <button
+                  key={code}
+                  onClick={(e) => {
+                    e.preventDefault()
+                    e.stopPropagation()
+                    handleLanguageChange(code)
+                  }}
+                  onMouseEnter={() => setHoveredIndex(index)}
+                  onMouseLeave={() => setHoveredIndex(-1)}
+                  role='option'
+                  aria-selected={isSelected}
+                  className={cn(
+                    'flex h-[26px] w-full min-w-0 cursor-pointer items-center gap-[8px] rounded-[6px] px-[6px] text-[13px] transition-colors',
+                    'text-neutral-700 dark:text-neutral-200',
+                    isHovered && 'bg-neutral-100 dark:bg-neutral-800',
+                    'focus:outline-none'
+                  )}
+                >
+                  <span className='text-[13px]'>{lang.flag}</span>
+                  <span className='flex-1 text-left leading-none'>{lang.name}</span>
+                  {isSelected && <Check className='ml-auto h-3.5 w-3.5' />}
+                </button>
+              )
+            })}
          </div>
        </>
      )}
--- a/apps/docs/components/ui/lightbox.tsx
+++ b/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>
--- a/apps/docs/components/ui/response-section.tsx
+++ b/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>
+  )
+}
--- a/apps/docs/components/ui/search-trigger.tsx
+++ b/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>
  )
--- a/apps/docs/components/ui/sim-logo.tsx
+++ b/apps/docs/components/ui/sim-logo.tsx
@@ -0,0 +1,108 @@
+'use client'
+
+import { cn } from '@/lib/utils'
+
+interface SimLogoProps {
+  className?: string
+}
+
+/**
+ * Sim logo with icon and text.
+ * The icon stays green (#33C482), text adapts to light/dark mode.
+ */
+export function SimLogo({ className }: SimLogoProps) {
+  return (
+    <svg
+      viewBox='720 440 320 320'
+      fill='none'
+      xmlns='http://www.w3.org/2000/svg'
+      className={cn('h-7 w-auto', className)}
+      aria-label='Sim'
+    >
+      {/* Green icon - top left shape with cutout */}
+      <path
+        fillRule='evenodd'
+        clipRule='evenodd'
+        d='M875.791 577.171C875.791 581.922 873.911 586.483 870.576 589.842L870.098 590.323C866.764 593.692 862.234 595.575 857.517 595.575H750.806C740.978 595.575 733 603.6 733 613.498V728.902C733 738.799 740.978 746.826 750.806 746.826H865.382C875.209 746.826 883.177 738.799 883.177 728.902V620.853C883.177 616.448 884.912 612.222 888.008 609.104C891.093 605.997 895.29 604.249 899.664 604.249H1008.16C1017.99 604.249 1025.96 596.224 1025.96 586.327V470.923C1025.96 461.025 1017.99 453 1008.16 453H893.586C883.759 453 875.791 461.025 875.791 470.923V577.171ZM910.562 477.566H991.178C996.922 477.566 1001.57 482.254 1001.57 488.029V569.22C1001.57 574.995 996.922 579.683 991.178 579.683H910.562C904.828 579.683 900.173 574.995 900.173 569.22V488.029C900.173 482.254 904.828 477.566 910.562 477.566Z'
+        fill='#33C482'
+      />
+      {/* Green icon - bottom right square */}
+      <path
+        d='M1008.3 624.59H923.113C912.786 624.59 904.414 633.022 904.414 643.423V728.171C904.414 738.572 912.786 747.004 923.113 747.004H1008.3C1018.63 747.004 1027 738.572 1027 728.171V643.423C1027 633.022 1018.63 624.59 1008.3 624.59Z'
+        fill='#33C482'
+      />
+      {/* Gradient overlay on bottom right square */}
+      <path
+        d='M1008.3 624.199H923.113C912.786 624.199 904.414 632.631 904.414 643.033V727.78C904.414 738.181 912.786 746.612 923.113 746.612H1008.3C1018.63 746.612 1027 738.181 1027 727.78V643.033C1027 632.631 1018.63 624.199 1008.3 624.199Z'
+        fill='url(#sim-logo-gradient)'
+        fillOpacity='0.2'
+      />
+      <defs>
+        <linearGradient
+          id='sim-logo-gradient'
+          x1='904.414'
+          y1='624.199'
+          x2='978.836'
+          y2='698.447'
+          gradientUnits='userSpaceOnUse'
+        >
+          <stop />
+          <stop offset='1' stopOpacity='0' />
+        </linearGradient>
+      </defs>
+    </svg>
+  )
+}
+
+/**
+ * Full Sim logo with icon and "Sim" text.
+ * The icon stays green (#33C482), text adapts to light/dark mode.
+ */
+export function SimLogoFull({ className }: SimLogoProps) {
+  return (
+    <svg
+      viewBox='720 440 1020 320'
+      fill='none'
+      xmlns='http://www.w3.org/2000/svg'
+      className={cn('h-7 w-auto', className)}
+      aria-label='Sim'
+    >
+      {/* Green icon - top left shape with cutout */}
+      <path
+        fillRule='evenodd'
+        clipRule='evenodd'
+        d='M875.791 577.171C875.791 581.922 873.911 586.483 870.576 589.842L870.098 590.323C866.764 593.692 862.234 595.575 857.517 595.575H750.806C740.978 595.575 733 603.6 733 613.498V728.902C733 738.799 740.978 746.826 750.806 746.826H865.382C875.209 746.826 883.177 738.799 883.177 728.902V620.853C883.177 616.448 884.912 612.222 888.008 609.104C891.093 605.997 895.29 604.249 899.664 604.249H1008.16C1017.99 604.249 1025.96 596.224 1025.96 586.327V470.923C1025.96 461.025 1017.99 453 1008.16 453H893.586C883.759 453 875.791 461.025 875.791 470.923V577.171ZM910.562 477.566H991.178C996.922 477.566 1001.57 482.254 1001.57 488.029V569.22C1001.57 574.995 996.922 579.683 991.178 579.683H910.562C904.828 579.683 900.173 574.995 900.173 569.22V488.029C900.173 482.254 904.828 477.566 910.562 477.566Z'
+        fill='#33C482'
+      />
+      {/* Green icon - bottom right square */}
+      <path
+        d='M1008.3 624.59H923.113C912.786 624.59 904.414 633.022 904.414 643.423V728.171C904.414 738.572 912.786 747.004 923.113 747.004H1008.3C1018.63 747.004 1027 738.572 1027 728.171V643.423C1027 633.022 1018.63 624.59 1008.3 624.59Z'
+        fill='#33C482'
+      />
+      {/* Gradient overlay on bottom right square */}
+      <path
+        d='M1008.3 624.199H923.113C912.786 624.199 904.414 632.631 904.414 643.033V727.78C904.414 738.181 912.786 746.612 923.113 746.612H1008.3C1018.63 746.612 1027 738.181 1027 727.78V643.033C1027 632.631 1018.63 624.199 1008.3 624.199Z'
+        fill='url(#sim-logo-full-gradient)'
+        fillOpacity='0.2'
+      />
+      {/* "Sim" text - adapts to light/dark mode via currentColor */}
+      <path
+        d='M1210.54 515.657C1226.65 515.657 1240.59 518.51 1252.31 524.257H1252.31C1264.3 529.995 1273.63 538.014 1280.26 548.319H1280.26C1287.19 558.635 1290.78 570.899 1291.08 585.068L1291.1 586.089H1249.11L1249.09 585.115C1248.8 574.003 1245.18 565.493 1238.32 559.451C1231.45 553.399 1221.79 550.308 1209.21 550.308C1196.3 550.308 1186.48 553.113 1179.61 558.588C1172.76 564.046 1169.33 571.499 1169.33 581.063C1169.33 588.092 1171.88 593.978 1177.01 598.783C1182.17 603.618 1189.99 607.399 1200.56 610.061H1200.56L1238.77 619.451C1257.24 623.65 1271.21 630.571 1280.57 640.293L1281.01 640.739C1290.13 650.171 1294.64 662.97 1294.64 679.016C1294.64 692.923 1290.88 705.205 1283.34 715.822L1283.33 715.834C1275.81 726.134 1265.44 734.14 1252.26 739.866L1252.25 739.871C1239.36 745.302 1224.12 748 1206.54 748C1180.9 748 1160.36 741.696 1145.02 728.984C1129.67 716.258 1122 699.269 1122 678.121V677.121H1163.99V678.121C1163.99 688.869 1167.87 697.367 1175.61 703.722L1176.34 704.284C1184.04 709.997 1194.37 712.902 1207.43 712.902C1222.13 712.902 1233.3 710.087 1241.07 704.588C1248.8 698.812 1252.64 691.21 1252.64 681.699C1252.64 674.769 1250.5 669.057 1246.25 664.49L1246.23 664.478L1246.22 664.464C1242.28 659.929 1234.83 656.119 1223.64 653.152L1185.43 644.208L1185.42 644.204C1166.05 639.407 1151.49 632.035 1141.83 622.012L1141.83 622.006L1141.82 622C1132.43 611.94 1127.78 598.707 1127.78 582.405C1127.78 568.81 1131.23 556.976 1138.17 546.949L1138.18 546.941L1138.19 546.933C1145.41 536.936 1155.18 529.225 1167.48 523.793L1167.48 523.79C1180.07 518.36 1194.43 515.657 1210.54 515.657ZM1323.39 521.979C1331.68 525.008 1337.55 526.482 1343.51 526.482C1349.48 526.482 1355.64 525.005 1364.49 521.973L1365.82 521.52V742.633H1322.05V521.489L1323.39 521.979ZM1642.01 515.657C1667.11 515.657 1686.94 523.031 1701.39 537.876C1715.83 552.716 1723 572.968 1723 598.507V742.633H1680.12V608.794C1680.12 591.666 1675.72 578.681 1667.07 569.681L1667.06 569.669L1667.04 569.656C1658.67 560.359 1647.26 555.675 1632.68 555.675C1622.47 555.675 1613.47 558.022 1605.64 562.69L1605.63 562.696C1598.11 567.064 1592.17 573.475 1587.8 581.968C1583.44 590.448 1581.25 600.424 1581.25 611.925V742.633H1537.92V608.347C1537.92 591.208 1533.67 578.376 1525.31 569.68L1525.31 569.674L1525.3 569.668C1516.93 560.664 1505.52 556.122 1490.93 556.122C1480.72 556.122 1471.72 558.469 1463.89 563.138L1463.88 563.144C1456.36 567.511 1450.41 573.922 1446.05 582.415L1446.05 582.422L1446.04 582.428C1441.69 590.602 1439.5 600.423 1439.5 611.925V742.633H1395.72V521.919H1435.05V554.803C1439.92 544.379 1447.91 535.465 1458.37 528.356C1470.71 519.875 1485.58 515.657 1502.93 515.657C1522.37 515.657 1538.61 520.931 1551.55 531.538C1560.38 538.771 1567.1 547.628 1571.72 558.091C1576.05 547.619 1582.83 538.757 1592.07 531.524C1605.61 520.93 1622.28 515.657 1642.01 515.657ZM1343.49 452C1351.45 452 1358.23 454.786 1363.75 460.346C1369.27 465.905 1372.04 472.721 1372.04 480.73C1372.04 488.452 1369.27 495.254 1363.77 501.096L1363.76 501.105L1363.75 501.115C1358.23 506.675 1351.45 509.461 1343.49 509.461C1335.81 509.461 1329.05 506.669 1323.25 501.134L1323.23 501.115L1323.21 501.096C1317.71 495.254 1314.94 488.452 1314.94 480.73C1314.94 472.721 1317.7 465.905 1323.23 460.346L1323.24 460.337L1323.25 460.327C1329.05 454.792 1335.81 452 1343.49 452Z'
+        className='fill-neutral-900 dark:fill-white'
+      />
+      <defs>
+        <linearGradient
+          id='sim-logo-full-gradient'
+          x1='904.414'
+          y1='624.199'
+          x2='978.836'
+          y2='698.447'
+          gradientUnits='userSpaceOnUse'
+        >
+          <stop />
+          <stop offset='1' stopOpacity='0' />
+        </linearGradient>
+      </defs>
+    </svg>
+  )
+}
--- a/apps/docs/components/ui/video.tsx
+++ b/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}
      />
--- a/apps/docs/content/docs/de/api-reference/authentication.mdx
+++ b/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>
--- a/apps/docs/content/docs/de/api-reference/getting-started.mdx
+++ b/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.
--- a/apps/docs/content/docs/de/api-reference/meta.json
+++ b/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"
+  ]
+}
--- a/apps/docs/content/docs/de/api-reference/python.mdx
+++ b/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)
+```
+
+### Umgebungskonfiguration
+
+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
--- a/apps/docs/content/docs/de/api-reference/typescript.mdx
+++ b/apps/docs/content/docs/de/api-reference/typescript.mdx
--- a/apps/docs/content/docs/de/blocks/agent.mdx
+++ b/apps/docs/content/docs/de/blocks/agent.mdx
@@ -152,3 +152,9 @@ Input → Agent (Google Search, Notion) → Function (Compile Report)
 - **Sei spezifisch in System-Prompts**: Definiere die Rolle, den Ton und die Einschränkungen des Agenten klar. Je spezifischer deine Anweisungen sind, desto besser kann der Agent seinen vorgesehenen Zweck erfüllen.
 - **Wähle die richtige Temperatureinstellung**: Verwende niedrigere Temperatureinstellungen (0-0,3), wenn Genauigkeit wichtig ist, oder erhöhe die Temperatur (0,7-2,0) für kreativere oder vielfältigere Antworten
 - **Nutze Tools effektiv**: Integriere Tools, die den Zweck des Agenten ergänzen und seine Fähigkeiten erweitern. Sei selektiv bei der Auswahl der Tools, um den Agenten nicht zu überfordern. Für Aufgaben mit wenig Überschneidung verwende einen anderen Agent-Block für die besten Ergebnisse.
+
+## Best Practices
+
+- **Seien Sie spezifisch in System-Prompts**: Definieren Sie die Rolle, den Ton und die Grenzen des Agenten klar. Je spezifischer Ihre Anweisungen sind, desto besser kann der Agent seinen beabsichtigten Zweck erfüllen.
+- **Wählen Sie die richtige Temperatureinstellung**: Verwenden Sie niedrigere Temperatureinstellungen (0–0,3), wenn Genauigkeit wichtig ist, oder erhöhen Sie die Temperatur (0,7–2,0) für kreativere oder vielfältigere Antworten
+- **Nutzen Sie Tools effektiv**: Integrieren Sie Tools, die den Zweck des Agenten ergänzen und seine Fähigkeiten erweitern. Seien Sie selektiv bei der Auswahl der Tools, um den Agenten nicht zu überfordern. Verwenden Sie für Aufgaben mit geringer Überschneidung einen weiteren Agent-Block für die besten Ergebnisse.
--- a/apps/docs/content/docs/de/blocks/loop.mdx
+++ b/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">
@@ -255,3 +250,57 @@ console.log(`${processedItems} gültige Elemente verarbeitet`);
 - **Setzen Sie vernünftige Grenzen**: Halten Sie die Anzahl der Iterationen in einem vernünftigen Rahmen, um lange Ausführungszeiten zu vermeiden
 - **Verwenden Sie ForEach für Sammlungen**: Verwenden Sie beim Verarbeiten von Arrays oder Objekten ForEach anstelle von For-Schleifen
 - **Behandeln Sie Fehler elegant**: Erwägen Sie, Fehlerbehandlung innerhalb von Schleifen hinzuzufügen, um robuste Workflows zu gewährleisten
+
+## Eingaben und Ausgaben
+
+<Tabs items={['Configuration', 'Variables', 'Results']}>
+  <Tab>
+    <ul className="list-disc space-y-2 pl-6">
+      <li>
+        <strong>Schleifentyp</strong>: Wählen Sie zwischen 'for', 'forEach', 'while' oder 'doWhile'
+      </li>
+      <li>
+        <strong>Iterationen</strong>: Anzahl der Ausführungen (für for-Schleifen)
+      </li>
+      <li>
+        <strong>Sammlung</strong>: Array oder Objekt zum Durchlaufen (für forEach-Schleifen)
+      </li>
+      <li>
+        <strong>Bedingung</strong>: Boolescher Ausdruck zur Auswertung (für while/do-while-Schleifen)
+      </li>
+    </ul>
+  </Tab>
+  <Tab>
+    Verfügbar **innerhalb** der Schleife:
+    <ul className="list-disc space-y-2 pl-6">
+      <li>
+        <strong>{"<loop.index>"}</strong>: Aktuelle Iterationsnummer (0-basiert)
+      </li>
+      <li>
+        <strong>{"<loop.currentItem>"}</strong>: Aktuell verarbeitetes Element (nur forEach)
+      </li>
+      <li>
+        <strong>{"<loop.items>"}</strong>: Vollständige Sammlung (nur forEach)
+      </li>
+    </ul>
+  </Tab>
+  <Tab>
+    <ul className="list-disc space-y-2 pl-6">
+      <li>
+        <strong>{"<blockname.results>"}</strong>: Array aller Iterationsergebnisse (Zugriff über Blocknamen)
+      </li>
+      <li>
+        <strong>Struktur</strong>: Ergebnisse behalten die Iterationsreihenfolge bei
+      </li>
+      <li>
+        <strong>Zugriff</strong>: Verfügbar in Blöcken nach Abschluss der Schleife
+      </li>
+    </ul>
+  </Tab>
+</Tabs>
+
+## Best Practices
+
+- **Setzen Sie vernünftige Grenzen**: Halten Sie die Iterationsanzahl angemessen, um lange Ausführungszeiten zu vermeiden
+- **Verwenden Sie ForEach für Sammlungen**: Verwenden Sie beim Verarbeiten von Arrays oder Objekten ForEach anstelle von For-Schleifen
+- **Behandeln Sie Fehler elegant**: Erwägen Sie, Fehlerbehandlung innerhalb von Schleifen hinzuzufügen, um robuste Workflows zu gewährleisten
--- a/apps/docs/content/docs/de/blocks/parallel.mdx
+++ b/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">
@@ -214,3 +211,51 @@ Wann Sie welche Methode verwenden sollten:
 - **Nur unabhängige Operationen**: Stellen Sie sicher, dass Operationen nicht voneinander abhängen
 - **Ratenbegrenzungen berücksichtigen**: Fügen Sie Verzögerungen oder Drosselungen für API-intensive Workflows hinzu
 - **Fehlerbehandlung**: Jede Instanz sollte ihre eigenen Fehler angemessen behandeln
+
+## Eingaben und Ausgaben
+
+<Tabs items={['Konfiguration', 'Variablen', 'Ergebnisse']}>
+  <Tab>
+    <ul className="list-disc space-y-2 pl-6">
+      <li>
+        <strong>Parallel-Typ</strong>: Wählen Sie zwischen „count" oder „collection"
+      </li>
+      <li>
+        <strong>Anzahl</strong>: Anzahl der auszuführenden Instanzen (anzahlbasiert)
+      </li>
+      <li>
+        <strong>Collection</strong>: Array oder Objekt zur Verteilung (sammlungsbasiert)
+      </li>
+    </ul>
+  </Tab>
+  <Tab>
+    Verfügbar **innerhalb** der Parallelverarbeitung:
+    <ul className="list-disc space-y-2 pl-6">
+      <li>
+        <strong>{"<parallel.index>"}</strong>: Instanznummer (0-basiert)
+      </li>
+      <li>
+        <strong>{"<parallel.currentItem>"}</strong>: Element für diese Instanz (nur sammlungsbasiert)
+      </li>
+      <li>
+        <strong>{"<parallel.items>"}</strong>: Vollständige Sammlung (nur sammlungsbasiert)
+      </li>
+    </ul>
+  </Tab>
+  <Tab>
+    <ul className="list-disc space-y-2 pl-6">
+      <li>
+        <strong>{"<blockname.results>"}</strong>: Array aller Instanzergebnisse (Zugriff über Blockname)
+      </li>
+      <li>
+        <strong>Zugriff</strong>: Verfügbar in Blöcken nach Abschluss der Parallelverarbeitung
+      </li>
+    </ul>
+  </Tab>
+</Tabs>
+
+## Best Practices
+
+- **Nur unabhängige Operationen**: Stellen Sie sicher, dass Operationen nicht voneinander abhängen
+- **Rate Limits beachten**: Fügen Sie Verzögerungen oder Drosselung für API-intensive Workflows hinzu
+- **Fehlerbehandlung**: Jede Instanz sollte ihre eigenen Fehler ordnungsgemäß behandeln
--- a/apps/docs/content/docs/de/blocks/router.mdx
+++ b/apps/docs/content/docs/de/blocks/router.mdx
@@ -100,3 +100,18 @@ Input (Lead) → Router → Agent (Enterprise Sales) or Workflow (Self-serve)
 - **Mit verschiedenen Eingaben testen**: Stellen Sie sicher, dass der Router verschiedene Eingabetypen, Grenzfälle und unerwartete Inhalte verarbeiten kann
 - **Routing-Leistung überwachen**: Überprüfen Sie Routing-Entscheidungen regelmäßig und verfeinern Sie Kriterien basierend auf tatsächlichen Nutzungsmustern
 - **Geeignete Modelle auswählen**: Verwenden Sie Modelle mit starken Argumentationsfähigkeiten für komplexe Routing-Entscheidungen
+
+Wenn der Router keine geeignete Route für den gegebenen Kontext ermitteln kann, leitet er stattdessen zum **Fehlerpfad** weiter, anstatt willkürlich eine Route auszuwählen. Dies geschieht, wenn:
+
+- Der Kontext keiner der definierten Routenbeschreibungen eindeutig entspricht
+- Die KI feststellt, dass keine der verfügbaren Routen geeignet ist
+
+## Best Practices
+
+- **Klare Routenbeschreibungen verfassen**: Jede Routenbeschreibung sollte klar erklären, wann diese Route ausgewählt werden sollte. Seien Sie spezifisch bezüglich der Kriterien.
+- **Routen gegenseitig ausschließend gestalten**: Stellen Sie nach Möglichkeit sicher, dass sich Routenbeschreibungen nicht überschneiden, um mehrdeutige Routing-Entscheidungen zu vermeiden.
+- **Einen Fehlerpfad verbinden**: Behandeln Sie Fälle, in denen keine Route passt, indem Sie einen Fehlerbehandler für ein elegantes Fallback-Verhalten verbinden.
+- **Aussagekräftige Routentitel verwenden**: Routentitel erscheinen im Workflow-Canvas, machen Sie sie daher für bessere Lesbarkeit aussagekräftig.
+- **Mit verschiedenen Eingaben testen**: Stellen Sie sicher, dass der Router verschiedene Eingabetypen, Grenzfälle und unerwartete Inhalte verarbeitet.
+- **Routing-Performance überwachen**: Überprüfen Sie Routing-Entscheidungen regelmäßig und verfeinern Sie Routenbeschreibungen basierend auf tatsächlichen Nutzungsmustern.
+- **Geeignete Modelle wählen**: Verwenden Sie Modelle mit starken Reasoning-Fähigkeiten für komplexe Routing-Entscheidungen.
--- a/apps/docs/content/docs/de/blocks/webhook.mdx
+++ b/apps/docs/content/docs/de/blocks/webhook.mdx
@@ -0,0 +1,89 @@
+---
+title: Webhook
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Image } from '@/components/ui/image'
+
+Der Webhook-Block sendet HTTP-POST-Anfragen an externe Webhook-Endpunkte mit automatischen Webhook-Headern und optionaler HMAC-Signierung.
+
+<div className="flex justify-center">
+  <Image
+    src="/static/blocks/webhook.png"
+    alt="Webhook-Block"
+    width={500}
+    height={400}
+    className="my-6"
+  />
+</div>
+
+## Konfiguration
+
+### Webhook-URL
+
+Der Ziel-Endpunkt für Ihre Webhook-Anfrage. Unterstützt sowohl statische URLs als auch dynamische Werte aus anderen Blöcken.
+
+### Payload
+
+JSON-Daten, die im Anfrage-Body gesendet werden. Verwenden Sie den KI-Zauberstab, um Payloads zu generieren oder auf Workflow-Variablen zu verweisen:
+
+```json
+{
+  "event": "workflow.completed",
+  "data": {
+    "result": "<agent.content>",
+    "timestamp": "<function.result>"
+  }
+}
+```
+
+### Signierungsgeheimnis
+
+Optionales Geheimnis für die HMAC-SHA256-Payload-Signierung. Wenn angegeben, wird ein `X-Webhook-Signature`Header hinzugefügt:
+
+```
+X-Webhook-Signature: t=1704067200000,v1=5d41402abc4b2a76b9719d911017c592...
+```
+
+Um Signaturen zu verifizieren, berechnen Sie `HMAC-SHA256(secret, "${timestamp}.${body}")` und vergleichen Sie mit dem `v1`Wert.
+
+### Zusätzliche Header
+
+Benutzerdefinierte Schlüssel-Wert-Header, die in die Anfrage aufgenommen werden. Diese überschreiben alle automatischen Header mit demselben Namen.
+
+## Automatische Header
+
+Jede Anfrage enthält automatisch diese Header:
+
+| Header | Beschreibung |
+|--------|-------------|
+| `Content-Type` | `application/json` |
+| `X-Webhook-Timestamp` | Unix-Zeitstempel in Millisekunden |
+| `X-Delivery-ID` | Eindeutige UUID für diese Zustellung |
+| `Idempotency-Key` | Identisch mit `X-Delivery-ID` zur Deduplizierung |
+
+## Ausgaben
+
+| Ausgabe | Typ | Beschreibung |
+|--------|------|-------------|
+| `data` | json | Antwort-Body vom Endpunkt |
+| `status` | number | HTTP-Statuscode |
+| `headers` | object | Antwort-Header |
+
+## Beispiel-Anwendungsfälle
+
+**Externe Dienste benachrichtigen** - Workflow-Ergebnisse an Slack, Discord oder benutzerdefinierte Endpunkte senden
+
+```
+Agent → Function (format) → Webhook (notify)
+```
+
+**Externe Workflows auslösen** - Prozesse in anderen Systemen starten, wenn Bedingungen erfüllt sind
+
+```
+Condition (check) → Webhook (trigger) → Response
+```
+
+<Callout>
+Der Webhook-Block verwendet immer POST. Für andere HTTP-Methoden oder mehr Kontrolle verwenden Sie den [API-Block](/blocks/api).
+</Callout>
--- a/apps/docs/content/docs/de/copilot/index.mdx
+++ b/apps/docs/content/docs/de/copilot/index.mdx
@@ -169,3 +169,175 @@ copilotCost = (inputTokens × inputPrice + outputTokens × (outputPrice × 1.5))
 <Callout type="info">
  Modellpreise werden pro Million Tokens angegeben. Die Berechnung teilt durch 1.000.000, um die tatsächlichen Kosten zu ermitteln. Siehe <a href="/execution/costs">die Seite zur Kostenberechnung</a> für Hintergründe und Beispiele.
 </Callout>
+
+Fahre mit der Maus über eine deiner Nachrichten und klicke auf **Bearbeiten**, um sie zu ändern und erneut zu senden. Dies ist nützlich, um deine Eingaben zu verfeinern.
+
+### Nachrichtenwarteschlange
+
+Wenn du eine Nachricht sendest, während Copilot noch antwortet, wird sie in die Warteschlange gestellt. Du kannst:
+- Warteschlangennachrichten im erweiterbaren Warteschlangenpanel anzeigen
+- Eine Nachricht aus der Warteschlange sofort senden (bricht die aktuelle Antwort ab)
+- Nachrichten aus der Warteschlange entfernen
+
+## Dateianhänge
+
+Klicke auf das Anhang-Symbol, um Dateien mit deiner Nachricht hochzuladen. Unterstützte Dateitypen umfassen:
+- Bilder (Vorschau-Thumbnails werden angezeigt)
+- PDFs
+- Textdateien, JSON, XML
+- Andere Dokumentformate
+
+Dateien werden als anklickbare Thumbnails angezeigt, die in einem neuen Tab geöffnet werden.
+
+## Checkpoints & Änderungen
+
+Wenn Copilot Änderungen an deinem Workflow vornimmt, speichert es Checkpoints, damit du bei Bedarf zurückkehren kannst.
+
+### Checkpoints anzeigen
+
+Fahre mit der Maus über eine Copilot-Nachricht und klicke auf das Checkpoints-Symbol, um gespeicherte Workflow-Zustände für diese Nachricht anzuzeigen.
+
+### Änderungen rückgängig machen
+
+Klicke bei jedem Checkpoint auf **Rückgängig machen**, um deinen Workflow auf diesen Zustand zurückzusetzen. Ein Bestätigungsdialog warnt dich, dass diese Aktion nicht rückgängig gemacht werden kann.
+
+### Änderungen akzeptieren
+
+Wenn Copilot Änderungen vorschlägt, kannst du:
+- **Akzeptieren**: Die vorgeschlagenen Änderungen anwenden (`Mod+Shift+Enter`)
+- **Ablehnen**: Die Änderungen verwerfen und deinen aktuellen Workflow beibehalten
+
+## Denkblöcke
+
+Bei komplexen Anfragen kann Copilot seinen Denkprozess in erweiterbaren Denkblöcken anzeigen:
+
+- Blöcke werden automatisch erweitert, während Copilot denkt
+- Klicken zum manuellen Erweitern/Reduzieren
+- Zeigt die Dauer des Denkprozesses an
+- Hilft dir zu verstehen, wie Copilot zu seiner Lösung gekommen ist
+
+## Optionsauswahl
+
+Wenn Copilot mehrere Optionen präsentiert, kannst du auswählen mit:
+
+| Steuerung | Aktion |
+|---------|--------|
+| **1-9** | Option nach Nummer auswählen |
+| **Pfeiltaste auf/ab** | Zwischen Optionen navigieren |
+| **Eingabetaste** | Hervorgehobene Option auswählen |
+
+Ausgewählte Optionen sind hervorgehoben; nicht ausgewählte Optionen erscheinen durchgestrichen.
+
+## Tastenkombinationen
+
+| Tastenkombination | Aktion |
+|----------|--------|
+| `@` | Kontextmenü öffnen |
+| `/` | Slash-Befehle öffnen |
+| `Arrow Up/Down` | Menüelemente navigieren |
+| `Enter` | Menüelement auswählen |
+| `Esc` | Menüs schließen |
+| `Mod+Shift+Enter` | Copilot-Änderungen akzeptieren |
+
+## Nutzungslimits
+
+Die Copilot-Nutzung wird pro Token des zugrunde liegenden LLM abgerechnet. Wenn Sie Ihr Nutzungslimit erreichen, fordert Copilot Sie auf, Ihr Limit zu erhöhen. Sie können die Nutzung in Schritten (50 $, 100 $) von Ihrer aktuellen Basis aus hinzufügen.
+
+<Callout type="info">
+  Siehe die [Seite zur Kostenberechnung](/execution/costs) für Abrechnungsdetails.
+</Callout>
+## Copilot MCP
+
+Sie können Copilot als MCP-Server in Ihrem bevorzugten Editor oder AI-Client verwenden. Damit können Sie Sim-Workflows direkt aus Tools wie Cursor, Claude Code, Claude Desktop und VS Code erstellen, testen, bereitstellen und verwalten.
+
+### Generieren eines Copilot-API-Schlüssels
+
+Um sich mit dem Copilot-MCP-Server zu verbinden, benötigen Sie einen **Copilot-API-Schlüssel**:
+
+1. Gehen Sie zu [sim.ai](https://sim.ai) und melden Sie sich an
+2. Navigieren Sie zu **Einstellungen** → **Copilot**
+3. Klicken Sie auf **API-Schlüssel generieren**
+4. Kopieren Sie den Schlüssel – er wird nur einmal angezeigt
+
+Der Schlüssel sieht aus wie `sk-sim-copilot-...`. Sie werden ihn in der folgenden Konfiguration verwenden.
+
+### Cursor
+
+Fügen Sie Folgendes zu Ihrer `.cursor/mcp.json` (Projektebene) oder den globalen Cursor-MCP-Einstellungen hinzu:
+
+```json
+{
+  "mcpServers": {
+    "sim-copilot": {
+      "url": "https://www.sim.ai/api/mcp/copilot",
+      "headers": {
+        "X-API-Key": "YOUR_COPILOT_API_KEY"
+      }
+    }
+  }
+}
+```
+
+Ersetzen Sie `YOUR_COPILOT_API_KEY` durch den oben generierten Schlüssel.
+
+### Claude Code
+
+Führen Sie den folgenden Befehl aus, um den Copilot MCP-Server hinzuzufügen:
+
+```bash
+claude mcp add sim-copilot \
+  --transport http \
+  https://www.sim.ai/api/mcp/copilot \
+  --header "X-API-Key: YOUR_COPILOT_API_KEY"
+```
+
+Ersetzen Sie `YOUR_COPILOT_API_KEY` durch Ihren Schlüssel.
+
+### Claude Desktop
+
+Claude Desktop benötigt [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), um sich mit HTTP-basierten MCP-Servern zu verbinden. Fügen Sie Folgendes zu Ihrer Claude Desktop-Konfigurationsdatei hinzu (`~/Library/Application Support/Claude/claude_desktop_config.json` unter macOS):
+
+```json
+{
+  "mcpServers": {
+    "sim-copilot": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-remote",
+        "https://www.sim.ai/api/mcp/copilot",
+        "--header",
+        "X-API-Key: YOUR_COPILOT_API_KEY"
+      ]
+    }
+  }
+}
+```
+
+Ersetzen Sie `YOUR_COPILOT_API_KEY` durch Ihren Schlüssel.
+
+### VS Code
+
+Fügen Sie Folgendes zu Ihrer VS Code `settings.json` oder Workspace `.vscode/settings.json` hinzu:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "sim-copilot": {
+        "type": "http",
+        "url": "https://www.sim.ai/api/mcp/copilot",
+        "headers": {
+          "X-API-Key": "YOUR_COPILOT_API_KEY"
+        }
+      }
+    }
+  }
+}
+```
+
+Ersetzen Sie `YOUR_COPILOT_API_KEY` durch Ihren Schlüssel.
+
+<Callout type="info">
+  Für selbst gehostete Deployments ersetzen Sie `https://www.sim.ai` durch Ihre selbst gehostete Sim-URL.
+</Callout>
--- a/apps/docs/content/docs/de/enterprise/index.mdx
+++ b/apps/docs/content/docs/de/enterprise/index.mdx
@@ -0,0 +1,114 @@
+---
+title: Enterprise
+description: Enterprise-Funktionen für Organisationen mit erweiterten
+  Sicherheits- und Compliance-Anforderungen
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+
+Sim Enterprise bietet erweiterte Funktionen für Organisationen mit erhöhten Sicherheits-, Compliance- und Verwaltungsanforderungen.
+
+---
+
+## Bring Your Own Key (BYOK)
+
+Verwenden Sie Ihre eigenen API-Schlüssel für KI-Modellanbieter anstelle der gehosteten Schlüssel von Sim.
+
+### Unterstützte Anbieter
+
+| Anbieter | Verwendung |
+|----------|-------|
+| OpenAI | Knowledge Base-Embeddings, Agent-Block |
+| Anthropic | Agent-Block |
+| Google | Agent-Block |
+| Mistral | Knowledge Base OCR |
+
+### Einrichtung
+
+1. Navigieren Sie zu **Einstellungen** → **BYOK** in Ihrem Workspace
+2. Klicken Sie auf **Schlüssel hinzufügen** für Ihren Anbieter
+3. Geben Sie Ihren API-Schlüssel ein und speichern Sie
+
+<Callout type="warn">
+  BYOK-Schlüssel werden verschlüsselt gespeichert. Nur Organisationsadministratoren und -inhaber können Schlüssel verwalten.
+</Callout>
+
+Wenn konfiguriert, verwenden Workflows Ihren Schlüssel anstelle der gehosteten Schlüssel von Sim. Bei Entfernung wechseln Workflows automatisch zu den gehosteten Schlüsseln zurück.
+
+---
+
+## Single Sign-On (SSO)
+
+Enterprise-Authentifizierung mit SAML 2.0- und OIDC-Unterstützung für zentralisiertes Identitätsmanagement.
+
+### Unterstützte Anbieter
+
+- Okta
+- Azure AD / Entra ID
+- Google Workspace
+- OneLogin
+- Jeder SAML 2.0- oder OIDC-Anbieter
+
+### Einrichtung
+
+1. Navigieren Sie zu **Einstellungen** → **SSO** in Ihrem Workspace
+2. Wählen Sie Ihren Identitätsanbieter
+3. Konfigurieren Sie die Verbindung mithilfe der Metadaten Ihres IdP
+4. Aktivieren Sie SSO für Ihre Organisation
+
+<Callout type="info">
+  Sobald SSO aktiviert ist, authentifizieren sich Teammitglieder über Ihren Identitätsanbieter anstelle von E-Mail/Passwort.
+</Callout>
+
+---
+
+## Self-Hosted
+
+Für selbst gehostete Bereitstellungen können Enterprise-Funktionen über Umgebungsvariablen aktiviert werden:
+
+| Variable | Beschreibung |
+|----------|-------------|
+| `SSO_ENABLED`, `NEXT_PUBLIC_SSO_ENABLED` | Single Sign-On mit SAML/OIDC |
+| `CREDENTIAL_SETS_ENABLED`, `NEXT_PUBLIC_CREDENTIAL_SETS_ENABLED` | Polling-Gruppen für E-Mail-Trigger |
+| `DISABLE_INVITATIONS`, `NEXT_PUBLIC_DISABLE_INVITATIONS` | Workspace-/Organisations-Einladungen global deaktivieren |
+
+<Callout type="warn">
+  BYOK ist nur im gehosteten Sim verfügbar. Selbst gehostete Deployments konfigurieren AI-Provider-Schlüssel direkt über Umgebungsvariablen.
+</Callout>
+
+Wenn die Abrechnung deaktiviert ist, verwenden Sie die Admin-API zur Verwaltung von Organisationen:
+
+```bash
+# Create an organization
+curl -X POST https://your-instance/api/v1/admin/organizations \
+  -H "x-admin-key: YOUR_ADMIN_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "My Organization", "ownerId": "user-id-here"}'
+
+# Add a member
+curl -X POST https://your-instance/api/v1/admin/organizations/{orgId}/members \
+  -H "x-admin-key: YOUR_ADMIN_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"userId": "user-id-here", "role": "admin"}'
+```
+
+### Workspace-Mitglieder
+
+Wenn Einladungen deaktiviert sind, verwenden Sie die Admin-API zur direkten Verwaltung von Workspace-Mitgliedschaften:
+
+```bash
+# Add a user to a workspace
+curl -X POST https://your-instance/api/v1/admin/workspaces/{workspaceId}/members \
+  -H "x-admin-key: YOUR_ADMIN_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"userId": "user-id-here", "permissions": "write"}'
+
+# Remove a user from a workspace
+curl -X DELETE "https://your-instance/api/v1/admin/workspaces/{workspaceId}/members?userId=user-id-here" \
+  -H "x-admin-key: YOUR_ADMIN_API_KEY"
+```
+
+### Hinweise
+
+- Die Aktivierung von `ACCESS_CONTROL_ENABLED` aktiviert automatisch Organisationen, da die Zugriffskontrolle eine Organisationsmitgliedschaft erfordert.
+- Wenn `DISABLE_INVITATIONS` gesetzt ist, können Benutzer keine Einladungen versenden. Verwenden Sie stattdessen die Admin-API zur Verwaltung von Workspace- und Organisationsmitgliedschaften.
--- a/apps/docs/content/docs/de/execution/costs.mdx
+++ b/apps/docs/content/docs/de/execution/costs.mdx
@@ -49,40 +49,40 @@ Die Modellaufschlüsselung zeigt:

 <Tabs items={['Hosted Models', 'Bring Your Own API Key']}>
  <Tab>
-    **Gehostete Modelle** - Sim stellt API-Schlüssel mit einem 2,5-fachen Preismultiplikator bereit:
+    **Hosted Models** - Sim bietet API-Schlüssel mit einem 1,4-fachen Preismultiplikator für Agent-Blöcke:

    **OpenAI**
-    | Modell | Basispreis (Eingabe/Ausgabe) | Gehosteter Preis (Eingabe/Ausgabe) |
+    | Modell | Basispreis (Eingabe/Ausgabe) | Hosted-Preis (Eingabe/Ausgabe) |
    |-------|---------------------------|----------------------------|
-    | GPT-5.1 | $1,25 / $10,00 | $3,13 / $25,00 |
-    | GPT-5 | $1,25 / $10,00 | $3,13 / $25,00 |
-    | GPT-5 Mini | $0,25 / $2,00 | $0,63 / $5,00 |
-    | GPT-5 Nano | $0,05 / $0,40 | $0,13 / $1,00 |
-    | GPT-4o | $2,50 / $10,00 | $6,25 / $25,00 |
-    | GPT-4.1 | $2,00 / $8,00 | $5,00 / $20,00 |
-    | GPT-4.1 Mini | $0,40 / $1,60 | $1,00 / $4,00 |
-    | GPT-4.1 Nano | $0,10 / $0,40 | $0,25 / $1,00 |
-    | o1 | $15,00 / $60,00 | $37,50 / $150,00 |
-    | o3 | $2,00 / $8,00 | $5,00 / $20,00 |
-    | o4 Mini | $1,10 / $4,40 | $2,75 / $11,00 |
+    | GPT-5.1 | $1.25 / $10.00 | $1.75 / $14.00 |
+    | GPT-5 | $1.25 / $10.00 | $1.75 / $14.00 |
+    | GPT-5 Mini | $0.25 / $2.00 | $0.35 / $2.80 |
+    | GPT-5 Nano | $0.05 / $0.40 | $0.07 / $0.56 |
+    | GPT-4o | $2.50 / $10.00 | $3.50 / $14.00 |
+    | GPT-4.1 | $2.00 / $8.00 | $2.80 / $11.20 |
+    | GPT-4.1 Mini | $0.40 / $1.60 | $0.56 / $2.24 |
+    | GPT-4.1 Nano | $0.10 / $0.40 | $0.14 / $0.56 |
+    | o1 | $15.00 / $60.00 | $21.00 / $84.00 |
+    | o3 | $2.00 / $8.00 | $2.80 / $11.20 |
+    | o4 Mini | $1.10 / $4.40 | $1.54 / $6.16 |

    **Anthropic**
-    | Modell | Basispreis (Eingabe/Ausgabe) | Gehosteter Preis (Eingabe/Ausgabe) |
+    | Modell | Basispreis (Eingabe/Ausgabe) | Hosted-Preis (Eingabe/Ausgabe) |
    |-------|---------------------------|----------------------------|
-    | Claude Opus 4.5 | $5,00 / $25,00 | $12,50 / $62,50 |
-    | Claude Opus 4.1 | $15,00 / $75,00 | $37,50 / $187,50 |
-    | Claude Sonnet 4.5 | $3,00 / $15,00 | $7,50 / $37,50 |
-    | Claude Sonnet 4.0 | $3,00 / $15,00 | $7,50 / $37,50 |
-    | Claude Haiku 4.5 | $1,00 / $5,00 | $2,50 / $12,50 |
+    | Claude Opus 4.5 | $5.00 / $25.00 | $7.00 / $35.00 |
+    | Claude Opus 4.1 | $15.00 / $75.00 | $21.00 / $105.00 |
+    | Claude Sonnet 4.5 | $3.00 / $15.00 | $4.20 / $21.00 |
+    | Claude Sonnet 4.0 | $3.00 / $15.00 | $4.20 / $21.00 |
+    | Claude Haiku 4.5 | $1.00 / $5.00 | $1.40 / $7.00 |

    **Google**
-    | Modell | Basispreis (Eingabe/Ausgabe) | Gehosteter Preis (Eingabe/Ausgabe) |
+    | Modell | Basispreis (Eingabe/Ausgabe) | Hosted-Preis (Eingabe/Ausgabe) |
    |-------|---------------------------|----------------------------|
-    | Gemini 3 Pro Preview | $2,00 / $12,00 | $5,00 / $30,00 |
-    | Gemini 2.5 Pro | $0,15 / $0,60 | $0,38 / $1,50 |
-    | Gemini 2.5 Flash | $0,15 / $0,60 | $0,38 / $1,50 |
+    | Gemini 3 Pro Preview | $2.00 / $12.00 | $2.80 / $16.80 |
+    | Gemini 2.5 Pro | $1.25 / $10.00 | $1.75 / $14.00 |
+    | Gemini 2.5 Flash | $0.30 / $2.50 | $0.42 / $3.50 |

-    *Der 2,5-fache Multiplikator deckt Infrastruktur- und API-Verwaltungskosten ab.*
+    *Der 1,4-fache Multiplikator deckt Infrastruktur- und API-Verwaltungskosten ab.*
  </Tab>

  <Tab>
@@ -105,28 +105,32 @@ Die Modellaufschlüsselung zeigt:
  Die angezeigten Preise entsprechen den Tarifen vom 10. September 2025. Überprüfen Sie die Dokumentation der Anbieter für aktuelle Preise.
 </Callout>

+## Bring Your Own Key (BYOK)
+
+Sie können Ihre eigenen API-Schlüssel für gehostete Modelle (OpenAI, Anthropic, Google, Mistral) unter **Einstellungen → BYOK** verwenden, um Basispreise zu zahlen. Schlüssel werden verschlüsselt und gelten arbeitsbereichsweit.
+
 ## Strategien zur Kostenoptimierung

- **Modellauswahl**: Wählen Sie Modelle basierend auf der Komplexität der Aufgabe. Einfache Aufgaben können GPT-4.1-nano verwenden, während komplexes Denken möglicherweise o1 oder Claude Opus erfordert.
- **Prompt-Engineering**: Gut strukturierte, präzise Prompts reduzieren den Token-Verbrauch ohne Qualitätseinbußen.
+- **Modellauswahl**: Wählen Sie Modelle basierend auf der Aufgabenkomplexität. Einfache Aufgaben können GPT-4.1-nano verwenden, während komplexes Reasoning o1 oder Claude Opus erfordern könnte.
+- **Prompt Engineering**: Gut strukturierte, prägnante Prompts reduzieren den Token-Verbrauch ohne Qualitätsverlust.
 - **Lokale Modelle**: Verwenden Sie Ollama oder VLLM für unkritische Aufgaben, um API-Kosten vollständig zu eliminieren.
- **Caching und Wiederverwendung**: Speichern Sie häufig verwendete Ergebnisse in Variablen oder Dateien, um wiederholte KI-Modellaufrufe zu vermeiden.
- **Batch-Verarbeitung**: Verarbeiten Sie mehrere Elemente in einer einzigen KI-Anfrage anstatt einzelne Aufrufe zu tätigen.
+- **Caching und Wiederverwendung**: Speichern Sie häufig verwendete Ergebnisse in Variablen oder Dateien, um wiederholte AI-Modellaufrufe zu vermeiden.
+- **Batch-Verarbeitung**: Verarbeiten Sie mehrere Elemente in einer einzigen AI-Anfrage, anstatt einzelne Aufrufe zu tätigen.

 ## Nutzungsüberwachung

 Überwachen Sie Ihre Nutzung und Abrechnung unter Einstellungen → Abonnement:

- **Aktuelle Nutzung**: Echtzeit-Nutzung und -Kosten für den aktuellen Zeitraum
- **Nutzungslimits**: Plangrenzen mit visuellen Fortschrittsanzeigen
+- **Aktuelle Nutzung**: Echtzeit-Nutzung und Kosten für den aktuellen Zeitraum
+- **Nutzungslimits**: Plan-Limits mit visuellen Fortschrittsindikatoren
 - **Abrechnungsdetails**: Prognostizierte Gebühren und Mindestverpflichtungen
- **Planverwaltung**: Upgrade-Optionen und Abrechnungsverlauf
+- **Plan-Verwaltung**: Upgrade-Optionen und Abrechnungsverlauf

-### Programmatische Nutzungsverfolgung
+### Programmatisches Nutzungs-Tracking

 Sie können Ihre aktuelle Nutzung und Limits programmatisch über die API abfragen:

-**Endpunkt:**
+**Endpoint:**

 ```text
 GET /api/users/me/usage-limits
@@ -172,69 +176,110 @@ curl -X GET -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" htt
 ```

 **Rate-Limit-Felder:**
- `requestsPerMinute`: Dauerhafte Rate-Begrenzung (Tokens werden mit dieser Rate aufgefüllt)
- `maxBurst`: Maximale Tokens, die Sie ansammeln können (Burst-Kapazität)
- `remaining`: Aktuell verfügbare Tokens (können bis zu `maxBurst` sein)
+- `requestsPerMinute`: Dauerhaftes Rate-Limit (Tokens werden mit dieser Rate aufgefüllt)
+- `maxBurst`: Maximale Tokens, die Sie akkumulieren können (Burst-Kapazität)
+- `remaining`: Aktuell verfügbare Tokens (kann bis zu `maxBurst` betragen)

 **Antwortfelder:**
- `currentPeriodCost` spiegelt die Nutzung in der aktuellen Abrechnungsperiode wider
- `limit` wird von individuellen Limits (Free/Pro) oder gepoolten Organisationslimits (Team/Enterprise) abgeleitet
- `plan` ist der aktive Plan mit der höchsten Priorität, der mit Ihrem Benutzer verknüpft ist
+- `currentPeriodCost` spiegelt die Nutzung im aktuellen Abrechnungszeitraum wider
+- `limit` wird aus individuellen Limits (Free/Pro) oder gepoolten Organisationslimits (Team/Enterprise) abgeleitet
+- `plan` ist der Plan mit der höchsten Priorität, der Ihrem Benutzer zugeordnet ist

 ## Plan-Limits

-Verschiedene Abonnementpläne haben unterschiedliche Nutzungslimits:
+Verschiedene Abonnement-Pläne haben unterschiedliche Nutzungslimits:

-| Plan | Monatliches Nutzungslimit | Rate-Limits (pro Minute) |
+| Plan | Monatliches Nutzungslimit | Ratenlimits (pro Minute) |
 |------|-------------------|-------------------------|
-| **Free** | $10 | 5 sync, 10 async |
-| **Pro** | $100 | 10 sync, 50 async |
-| **Team** | $500 (gepoolt) | 50 sync, 100 async |
+| **Free** | 20 $ | 5 sync, 10 async |
+| **Pro** | 100 $ | 10 sync, 50 async |
+| **Team** | 500 $ (gemeinsam) | 50 sync, 100 async |
 | **Enterprise** | Individuell | Individuell |

 ## Abrechnungsmodell

-Sim verwendet ein **Basisabonnement + Mehrverbrauch**-Abrechnungsmodell:
+Sim verwendet ein **Basis-Abonnement + Mehrverbrauch**-Abrechnungsmodell:

-### Wie es funktioniert
+### So funktioniert es

-**Pro-Plan ($20/Monat):**
- Monatliches Abonnement beinhaltet $20 Nutzung
- Nutzung unter $20 → Keine zusätzlichen Kosten
- Nutzung über $20 → Zahlen Sie den Mehrverbrauch am Monatsende
- Beispiel: $35 Nutzung = $20 (Abonnement) + $15 (Mehrverbrauch)
+**Pro-Plan (20 $/Monat):**
+- Monatsabonnement beinhaltet 20 $ Nutzung
+- Nutzung unter 20 $ → Keine zusätzlichen Gebühren
+- Nutzung über 20 $ → Mehrverbrauch am Monatsende zahlen
+- Beispiel: 35 $ Nutzung = 20 $ (Abonnement) + 15 $ (Mehrverbrauch)

-**Team-Plan ($40/Benutzer/Monat):**
- Gepoolte Nutzung für alle Teammitglieder
- Mehrverbrauch wird aus der Gesamtnutzung des Teams berechnet
+**Team-Plan (40 $/Platz/Monat):**
+- Gemeinsame Nutzung über alle Teammitglieder
+- Mehrverbrauch wird aus der gesamten Team-Nutzung berechnet
 - Organisationsinhaber erhält eine Rechnung

 **Enterprise-Pläne:**
- Fester monatlicher Preis, kein Mehrverbrauch
+- Fester Monatspreis, kein Mehrverbrauch
 - Individuelle Nutzungslimits gemäß Vereinbarung

 ### Schwellenwert-Abrechnung

-Wenn der nicht abgerechnete Mehrverbrauch $50 erreicht, berechnet Sim automatisch den gesamten nicht abgerechneten Betrag.
+Wenn der nicht abgerechnete Mehrverbrauch 50 $ erreicht, rechnet Sim automatisch den gesamten nicht abgerechneten Betrag ab.

 **Beispiel:**
- Tag 10: $70 Mehrverbrauch → Sofortige Abrechnung von $70
- Tag 15: Zusätzliche $35 Nutzung ($105 insgesamt) → Bereits abgerechnet, keine Aktion
- Tag 20: Weitere $50 Nutzung ($155 insgesamt, $85 nicht abgerechnet) → Sofortige Abrechnung von $85
+- Tag 10: 70 $ Mehrverbrauch → 70 $ sofort abrechnen
+- Tag 15: Zusätzliche 35 $ Nutzung (105 $ gesamt) → Bereits abgerechnet, keine Aktion
+- Tag 20: Weitere 50 $ Nutzung (155 $ gesamt, 85 $ nicht abgerechnet) → 85 $ sofort abrechnen

-Dies verteilt große Überziehungsgebühren über den Monat, anstatt eine große Rechnung am Ende des Abrechnungszeitraums zu erhalten.
+Dies verteilt große Mehrverbrauchsgebühren über den Monat, anstatt einer großen Rechnung am Periodenende.

 ## Best Practices für Kostenmanagement

 1. **Regelmäßig überwachen**: Überprüfen Sie Ihr Nutzungs-Dashboard häufig, um Überraschungen zu vermeiden
-2. **Budgets festlegen**: Nutzen Sie Planlimits als Leitplanken für Ihre Ausgaben
+2. **Budgets festlegen**: Nutzen Sie Plan-Limits als Leitplanken für Ihre Ausgaben
 3. **Workflows optimieren**: Überprüfen Sie kostenintensive Ausführungen und optimieren Sie Prompts oder Modellauswahl
 4. **Passende Modelle verwenden**: Passen Sie die Modellkomplexität an die Aufgabenanforderungen an
-5. **Ähnliche Aufgaben bündeln**: Kombinieren Sie wenn möglich mehrere Anfragen, um den Overhead zu reduzieren
+5. **Ähnliche Aufgaben bündeln**: Kombinieren Sie mehrere Anfragen, wenn möglich, um Overhead zu reduzieren

 ## Nächste Schritte

 - Überprüfen Sie Ihre aktuelle Nutzung unter [Einstellungen → Abonnement](https://sim.ai/settings/subscription)
 - Erfahren Sie mehr über [Protokollierung](/execution/logging), um Ausführungsdetails zu verfolgen
- Erkunden Sie die [Externe API](/execution/api) für programmatische Kostenüberwachung
- Sehen Sie sich [Workflow-Optimierungstechniken](/blocks) an, um Kosten zu reduzieren
+- Entdecken Sie die [externe API](/execution/api) für programmatische Kostenüberwachung
+- Sehen Sie sich [Workflow-Optimierungstechniken](/blocks) an, um Kosten zu reduzieren
+
+**Pro-Tarif (20 $/Monat):**
+- Monatliches Abonnement beinhaltet 20 $ Nutzung
+- Nutzung unter 20 $ → Keine zusätzlichen Gebühren
+- Nutzung über 20 $ → Mehrverbrauch wird am Monatsende abgerechnet
+- Beispiel: 35 $ Nutzung = 20 $ (Abonnement) + 15 $ (Mehrverbrauch)
+
+**Team-Tarif (40 $/Platz/Monat):**
+- Gemeinsame Nutzung über alle Teammitglieder hinweg
+- Mehrverbrauch wird aus der gesamten Teamnutzung berechnet
+- Der Organisationsinhaber erhält eine Rechnung
+
+**Enterprise-Tarife:**
+- Fester Monatspreis, keine Mehrverbräuche
+- Individuelle Nutzungslimits gemäß Vereinbarung
+
+### Schwellenwertabrechnung
+
+Wenn der nicht abgerechnete Mehrverbrauch 50 $ erreicht, rechnet Sim automatisch den gesamten nicht abgerechneten Betrag ab.
+
+**Beispiel:**
+- Tag 10: 70 $ Mehrverbrauch → 70 $ sofort abrechnen
+- Tag 15: Weitere 35 $ Nutzung (105 $ gesamt) → Bereits abgerechnet, keine Aktion
+- Tag 20: Weitere 50 $ Nutzung (155 $ gesamt, 85 $ nicht abgerechnet) → 85 $ sofort abrechnen
+
+Dies verteilt hohe Mehrverbrauchsgebühren über den Monat hinweg, anstatt einer großen Rechnung am Periodenende.
+
+## Best Practices für das Kostenmanagement
+
+1. **Regelmäßig überwachen**: Überprüfen Sie Ihr Nutzungs-Dashboard häufig, um Überraschungen zu vermeiden
+2. **Budgets festlegen**: Nutzen Sie Tariflimits als Leitplanken für Ihre Ausgaben
+3. **Workflows optimieren**: Überprüfen Sie kostenintensive Ausführungen und optimieren Sie Prompts oder Modellauswahl
+4. **Passende Modelle verwenden**: Stimmen Sie die Modellkomplexität auf die Aufgabenanforderungen ab
+5. **Ähnliche Aufgaben bündeln**: Kombinieren Sie mehrere Anfragen, wenn möglich, um den Overhead zu reduzieren
+
+## Nächste Schritte
+
+- Überprüfen Sie Ihre aktuelle Nutzung unter [Einstellungen → Abonnement](https://sim.ai/settings/subscription)
+- Erfahren Sie mehr über [Protokollierung](/execution/logging), um Ausführungsdetails zu verfolgen
+- Erkunden Sie die [externe API](/execution/api) für programmatische Kostenüberwachung
+- Informieren Sie sich über [Workflow-Optimierungstechniken](/blocks), um Kosten zu reduzieren
--- a/apps/docs/content/docs/de/execution/files.mdx
+++ b/apps/docs/content/docs/de/execution/files.mdx
@@ -0,0 +1,172 @@
+---
+title: Dateien übergeben
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+
+Sim macht es einfach, mit Dateien in Ihren Workflows zu arbeiten. Blöcke können Dateien empfangen, verarbeiten und nahtlos an andere Blöcke weitergeben.
+
+## Dateiobjekte
+
+Wenn Blöcke Dateien ausgeben (wie Gmail-Anhänge, generierte Bilder oder geparste Dokumente), geben sie ein standardisiertes Dateiobjekt zurück:
+
+```json
+{
+  "name": "report.pdf",
+  "url": "https://...",
+  "base64": "JVBERi0xLjQK...",
+  "type": "application/pdf",
+  "size": 245678
+}
+```
+
+Sie können auf alle diese Eigenschaften zugreifen, wenn Sie auf Dateien aus vorherigen Blöcken verweisen.
+
+## Der Datei-Block
+
+Der **Datei-Block** ist der universelle Einstiegspunkt für Dateien in Ihren Workflows. Er akzeptiert Dateien aus jeder Quelle und gibt standardisierte Dateiobjekte aus, die mit allen Integrationen funktionieren.
+
+**Eingaben:**
+- **Hochgeladene Dateien** - Dateien direkt per Drag & Drop oder Auswahl hinzufügen
+- **Externe URLs** - Jede öffentlich zugängliche Datei-URL
+- **Dateien von anderen Blöcken** - Dateien von Gmail-Anhängen, Slack-Downloads usw. übergeben
+
+**Ausgaben:**
+- Eine Liste von `UserFile`-Objekten mit konsistenter Struktur (`name`, `url`, `base64`, `type`, `size`)
+- `combinedContent` - Extrahierter Textinhalt aus allen Dateien (für Dokumente)
+
+**Beispielverwendung:**
+
+```
+// Get all files from the File block
+<file.files>
+
+// Get the first file
+<file.files[0]>
+
+// Get combined text content from parsed documents
+<file.combinedContent>
+```
+
+Der Datei-Block führt automatisch folgende Aktionen aus:
+- Erkennt Dateitypen aus URLs und Erweiterungen
+- Extrahiert Text aus PDFs, CSVs und Dokumenten
+- Generiert Base64-Kodierung für Binärdateien
+- Erstellt vorsignierte URLs für sicheren Zugriff
+
+Verwenden Sie den Datei-Block, wenn Sie Dateien aus verschiedenen Quellen normalisieren müssen, bevor Sie sie an andere Blöcke wie Vision, STT oder E-Mail-Integrationen übergeben.
+
+## Dateien zwischen Blöcken übergeben
+
+Verweisen Sie auf Dateien aus vorherigen Blöcken über das Tag-Dropdown. Klicken Sie in ein beliebiges Dateieingabefeld und geben Sie `<` ein, um verfügbare Ausgaben anzuzeigen.
+
+**Häufige Muster:**
+
+```
+// Single file from a block
+<gmail.attachments[0]>
+
+// Pass the whole file object
+<file_parser.files[0]>
+
+// Access specific properties
+<gmail.attachments[0].name>
+<gmail.attachments[0].base64>
+```
+
+Die meisten Blöcke akzeptieren das vollständige Dateiobjekt und extrahieren automatisch, was sie benötigen. Sie müssen `base64` oder `url` in den meisten Fällen nicht manuell extrahieren.
+
+## Workflows mit Dateien auslösen
+
+Wenn Sie einen Workflow über die API aufrufen, der Dateieingaben erwartet, fügen Sie Dateien in Ihre Anfrage ein:
+
+<Tabs items={['Base64', 'URL']}>
+  <Tab value="Base64">
+
+    ```bash
+    curl -X POST "https://sim.ai/api/workflows/YOUR_WORKFLOW_ID/execute" \
+      -H "Content-Type: application/json" \
+      -H "x-api-key: YOUR_API_KEY" \
+      -d '{
+        "document": {
+          "name": "report.pdf",
+          "base64": "JVBERi0xLjQK...",
+          "type": "application/pdf"
+        }
+      }'
+    ```
+
+  </Tab>
+  <Tab value="URL">
+
+    ```bash
+    curl -X POST "https://sim.ai/api/workflows/YOUR_WORKFLOW_ID/execute" \
+      -H "Content-Type: application/json" \
+      -H "x-api-key: YOUR_API_KEY" \
+      -d '{
+        "document": {
+          "name": "report.pdf",
+          "url": "https://example.com/report.pdf",
+          "type": "application/pdf"
+        }
+      }'
+    ```
+
+  </Tab>
+</Tabs>
+
+Der Start-Block des Workflows sollte ein Eingabefeld haben, das für den Empfang des Dateiparameters konfiguriert ist.
+
+## Dateien in API-Antworten empfangen
+
+Wenn ein Workflow Dateien ausgibt, sind diese in der Antwort enthalten:
+
+```json
+{
+  "success": true,
+  "output": {
+    "generatedFile": {
+      "name": "output.png",
+      "url": "https://...",
+      "base64": "iVBORw0KGgo...",
+      "type": "image/png",
+      "size": 34567
+    }
+  }
+}
+```
+
+Verwenden Sie `url` für direkte Downloads oder `base64` für Inline-Verarbeitung.
+
+## Blöcke, die mit Dateien arbeiten
+
+**Dateieingaben:**
+- **File** - Dokumente, Bilder und Textdateien parsen
+- **Vision** - Bilder mit KI-Modellen analysieren
+- **Mistral Parser** - Text aus PDFs extrahieren
+
+**Dateiausgaben:**
+- **Gmail** - E-Mail-Anhänge
+- **Slack** - Heruntergeladene Dateien
+- **TTS** - Generierte Audiodateien
+- **Video Generator** - Generierte Videos
+- **Image Generator** - Generierte Bilder
+
+**Dateispeicherung:**
+- **Supabase** - Upload/Download aus dem Speicher
+- **S3** - AWS S3-Operationen
+- **Google Drive** - Drive-Dateioperationen
+- **Dropbox** - Dropbox-Dateioperationen
+
+<Callout type="info">
+  Dateien sind automatisch für nachgelagerte Blöcke verfügbar. Die Ausführungs-Engine übernimmt die gesamte Dateiübertragung und Formatkonvertierung.
+</Callout>
+
+## Best Practices
+
+1. **Dateiobjekte direkt verwenden** - Übergeben Sie das vollständige Dateiobjekt, anstatt einzelne Eigenschaften zu extrahieren. Blöcke übernehmen die Konvertierung automatisch.
+
+2. **Dateitypen prüfen** - Stellen Sie sicher, dass der Dateityp mit dem übereinstimmt, was der empfangende Block erwartet. Der Vision-Block benötigt Bilder, der File-Block verarbeitet Dokumente.
+
+3. **Dateigröße beachten** – Große Dateien erhöhen die Ausführungszeit. Bei sehr großen Dateien sollten Sie Storage-Blöcke (S3, Supabase) für die Zwischenspeicherung verwenden.
--- a/apps/docs/content/docs/de/execution/form.mdx
+++ b/apps/docs/content/docs/de/execution/form.mdx
@@ -0,0 +1,142 @@
+---
+title: Formular-Bereitstellung
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+
+Stellen Sie Ihren Workflow als einbettbares Formular bereit, das Benutzer auf Ihrer Website ausfüllen oder per Link teilen können. Formularübermittlungen lösen Ihren Workflow mit dem `form` Trigger-Typ aus.
+
+## Übersicht
+
+Die Formular-Bereitstellung verwandelt das Eingabeformat Ihres Workflows in ein responsives Formular, das:
+- Per Direktlink geteilt werden kann (z. B. `https://sim.ai/form/my-survey`)
+- Mit einem iframe in jede Website eingebettet werden kann
+
+Wenn ein Benutzer das Formular absendet, wird Ihr Workflow mit den Formulardaten ausgelöst.
+
+<Callout type="info">
+Formulare leiten ihre Felder vom Eingabeformat des Start-Blocks Ihres Workflows ab. Jedes Feld wird zu einer Formulareingabe mit dem entsprechenden Typ.
+</Callout>
+
+## Erstellen eines Formulars
+
+1. Öffnen Sie Ihren Workflow und klicken Sie auf **Bereitstellen**
+2. Wählen Sie den Tab **Formular**
+3. Konfigurieren Sie:
+   - **URL**: Eindeutige Kennung (z. B. `contact-form` → `sim.ai/form/contact-form`)
+   - **Titel**: Formularüberschrift
+   - **Beschreibung**: Optionaler Untertitel
+   - **Formularfelder**: Passen Sie Beschriftungen und Beschreibungen für jedes Feld an
+   - **Authentifizierung**: Öffentlich, passwortgeschützt oder E-Mail-Whitelist
+   - **Dankesnachricht**: Wird nach der Übermittlung angezeigt
+4. Klicken Sie auf **Starten**
+
+## Feldzuordnung
+
+| Eingabeformat-Typ | Formularfeld |
+|------------------|------------|
+| `string` | Texteingabe |
+| `number` | Zahleneingabe |
+| `boolean` | Umschalter |
+| `object` | JSON-Editor |
+| `array` | JSON-Array-Editor |
+| `files` | Datei-Upload |
+
+## Zugriffskontrolle
+
+| Modus | Beschreibung |
+|------|-------------|
+| **Öffentlich** | Jeder mit dem Link kann absenden |
+| **Passwort** | Benutzer müssen ein Passwort eingeben |
+| **E-Mail-Whitelist** | Nur angegebene E-Mails/Domains können absenden |
+
+Für E-Mail-Whitelist:
+- Exakt: `user@example.com`
+- Domain: `@example.com` (alle E-Mails von der Domain)
+
+## Einbettung
+
+### Direkter Link
+
+```
+https://sim.ai/form/your-identifier
+```
+
+### Iframe
+
+```html
+<iframe
+  src="https://sim.ai/form/your-identifier"
+  width="100%"
+  height="600"
+  frameborder="0"
+  title="Form"
+></iframe>
+```
+
+## API-Übermittlung
+
+Formulare programmatisch übermitteln:
+
+<Tabs items={['cURL', 'TypeScript']}>
+  <Tab value="cURL">
+
+```bash
+curl -X POST https://sim.ai/api/form/your-identifier \
+  -H "Content-Type: application/json" \
+  -d '{
+    "formData": {
+      "name": "John Doe",
+      "email": "john@example.com"
+    }
+  }'
+```
+
+  </Tab>
+  <Tab value="TypeScript">
+
+```typescript
+const response = await fetch('https://sim.ai/api/form/your-identifier', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    formData: {
+      name: 'John Doe',
+      email: 'john@example.com'
+    }
+  })
+});
+
+const result = await response.json();
+// { success: true, data: { executionId: '...' } }
+```
+
+  </Tab>
+</Tabs>
+
+### Geschützte Formulare
+
+Für passwortgeschützte Formulare:
+
+```bash
+curl -X POST https://sim.ai/api/form/your-identifier \
+  -H "Content-Type: application/json" \
+  -d '{ "password": "secret", "formData": { "name": "John" } }'
+```
+
+Für E-Mail-geschützte Formulare:
+
+```bash
+curl -X POST https://sim.ai/api/form/your-identifier \
+  -H "Content-Type: application/json" \
+  -d '{ "email": "allowed@example.com", "formData": { "name": "John" } }'
+```
+
+## Fehlerbehebung
+
+**"Keine Eingabefelder konfiguriert"** - Fügen Sie Eingabeformat-Felder zu Ihrem Start-Block hinzu.
+
+**Formular lädt nicht im Iframe** - Überprüfen Sie, ob die CSP Ihrer Website Iframes von `sim.ai` erlaubt.
+
+**Übermittlungen schlagen fehl** - Überprüfen Sie, ob die Kennung korrekt ist und erforderliche Felder ausgefüllt sind.
--- a/apps/docs/content/docs/de/keyboard-shortcuts/index.mdx
+++ b/apps/docs/content/docs/de/keyboard-shortcuts/index.mdx
@@ -0,0 +1,60 @@
+---
+title: Tastaturkürzel
+description: Meistern Sie die Workflow-Arbeitsfläche mit Tastaturkürzeln und Maussteuerung
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+
+Beschleunigen Sie die Erstellung Ihrer Workflows mit diesen Tastaturkürzeln und Maussteuerungen. Alle Tastenkombinationen funktionieren, wenn die Arbeitsfläche fokussiert ist (nicht beim Tippen in einem Eingabefeld).
+
+<Callout type="info">
+  **Mod** bezieht sich auf `Cmd` unter macOS und `Ctrl` unter Windows/Linux.
+</Callout>
+
+## Arbeitsflächen-Steuerung
+
+### Maussteuerung
+
+| Aktion | Steuerung |
+|--------|---------|
+| Arbeitsfläche verschieben | Linksziehen auf leerer Fläche |
+| Arbeitsfläche verschieben | Scrollen oder Trackpad |
+| Mehrere Blöcke auswählen | Rechtsziehen zum Aufziehen eines Auswahlrahmens |
+| Block ziehen | Linksziehen auf Block-Kopfzeile |
+| Zur Auswahl hinzufügen | `Mod` + Klick auf Blöcke |
+
+### Workflow-Aktionen
+
+| Tastenkombination | Aktion |
+|----------|--------|
+| `Mod` + `Enter` | Workflow ausführen (oder abbrechen, falls aktiv) |
+| `Mod` + `Z` | Rückgängig |
+| `Mod` + `Shift` + `Z` | Wiederholen |
+| `Mod` + `C` | Ausgewählte Blöcke kopieren |
+| `Mod` + `V` | Blöcke einfügen |
+| `Delete` oder `Backspace` | Ausgewählte Blöcke oder Verbindungen löschen |
+| `Shift` + `L` | Arbeitsfläche automatisch anordnen |
+
+## Panel-Navigation
+
+Diese Tastenkombinationen wechseln zwischen den Panel-Tabs auf der rechten Seite der Arbeitsfläche.
+
+| Tastenkombination | Aktion |
+|----------|--------|
+| `Mod` + `F` | Toolbar-Suche fokussieren |
+
+## Globale Navigation
+
+| Tastenkombination | Aktion |
+|----------|--------|
+| `Mod` + `K` | Suche öffnen |
+| `Mod` + `Shift` + `A` | Neuen Agenten-Workflow hinzufügen |
+| `Mod` + `Y` | Zu Vorlagen gehen |
+| `Mod` + `L` | Zu Logs gehen |
+
+## Dienstprogramm
+
+| Tastenkombination | Aktion |
+|----------|--------|
+| `Mod` + `D` | Terminal-Konsole leeren |
+| `Mod` + `E` | Benachrichtigungen löschen |
--- a/apps/docs/content/docs/de/knowledgebase/index.mdx
+++ b/apps/docs/content/docs/de/knowledgebase/index.mdx
@@ -35,81 +35,87 @@ Sobald Ihre Dokumente verarbeitet sind, können Sie die einzelnen Chunks anzeige
 <Image src="/static/knowledgebase/knowledgebase.png" alt="Dokumentchunk-Ansicht mit verarbeiteten Inhalten" width={800} height={500} />

 ### Chunk-Konfiguration
- **Standardgröße der Chunks**: 1.024 Zeichen
- **Konfigurierbarer Bereich**: 100-4.000 Zeichen pro Chunk
- **Intelligente Überlappung**: Standardmäßig 200 Zeichen zur Kontexterhaltung
- **Hierarchische Aufteilung**: Respektiert Dokumentstruktur (Abschnitte, Absätze, Sätze)

-### Bearbeitungsfunktionen
+Beim Erstellen einer Wissensdatenbank können Sie konfigurieren, wie Dokumente in Chunks aufgeteilt werden:
+
+| Einstellung | Einheit | Standard | Bereich | Beschreibung |
+|---------|------|---------|-------|-------------|
+| **Maximale Chunk-Größe** | Tokens | 1.024 | 100-4.000 | Maximale Größe jedes Chunks (1 Token ≈ 4 Zeichen) |
+| **Minimale Chunk-Größe** | Zeichen | 1 | 1-2.000 | Minimale Chunk-Größe, um winzige Fragmente zu vermeiden |
+| **Überlappung** | Zeichen | 200 | 0-500 | Kontextüberlappung zwischen aufeinanderfolgenden Chunks |
+
+- **Hierarchische Aufteilung**: Berücksichtigt die Dokumentstruktur (Abschnitte, Absätze, Sätze)
+
+### Bearbeitungsmöglichkeiten
 - **Chunk-Inhalt bearbeiten**: Textinhalt einzelner Chunks ändern
- **Chunk-Grenzen anpassen**: Chunks bei Bedarf zusammenführen oder teilen
+- **Chunk-Grenzen anpassen**: Chunks nach Bedarf zusammenführen oder aufteilen
 - **Metadaten hinzufügen**: Chunks mit zusätzlichem Kontext anreichern
- **Massenoperationen**: Effiziente Verwaltung mehrerer Chunks
+- **Massenoperationen**: Mehrere Chunks effizient verwalten

 ## Erweiterte PDF-Verarbeitung

 Für PDF-Dokumente bietet Sim erweiterte Verarbeitungsfunktionen:

 ### OCR-Unterstützung
-Bei Konfiguration mit Azure oder [Mistral OCR](https://docs.mistral.ai/ocr/):
+Wenn mit Azure oder [Mistral OCR](https://docs.mistral.ai/ocr/) konfiguriert:
 - **Verarbeitung gescannter Dokumente**: Text aus bildbasierten PDFs extrahieren
- **Umgang mit gemischten Inhalten**: Verarbeitung von PDFs mit Text und Bildern
+- **Verarbeitung gemischter Inhalte**: PDFs mit Text und Bildern verarbeiten
 - **Hohe Genauigkeit**: Fortschrittliche KI-Modelle gewährleisten präzise Textextraktion

-## Verwendung des Wissensblocks in Workflows
+## Verwendung des Knowledge-Blocks in Workflows

-Sobald Ihre Dokumente verarbeitet sind, können Sie sie in Ihren KI-Workflows über den Wissensblock nutzen. Dies ermöglicht Retrieval-Augmented Generation (RAG), wodurch Ihre KI-Agenten auf Ihre Dokumentinhalte zugreifen und darüber nachdenken können, um genauere, kontextbezogene Antworten zu liefern.
+Sobald Ihre Dokumente verarbeitet sind, können Sie sie in Ihren KI-Workflows über den Knowledge-Block verwenden. Dies ermöglicht Retrieval-Augmented Generation (RAG), wodurch Ihre KI-Agenten auf Ihre Dokumentinhalte zugreifen und darüber nachdenken können, um genauere, kontextbezogene Antworten zu liefern.

-<Image src="/static/knowledgebase/knowledgebase-2.png" alt="Verwendung des Wissensblocks in Workflows" width={800} height={500} />
+<Image src="/static/knowledgebase/knowledgebase-2.png" alt="Verwendung des Knowledge-Blocks in Workflows" width={800} height={500} />

-### Funktionen des Wissensblocks
- **Semantische Suche**: Relevante Inhalte mit natürlichsprachlichen Abfragen finden
- **Kontextintegration**: Automatisches Einbinden relevanter Chunks in Agenten-Prompts
- **Dynamischer Abruf**: Suche erfolgt in Echtzeit während der Workflow-Ausführung
- **Relevanzbewertung**: Ergebnisse nach semantischer Ähnlichkeit geordnet
+### Knowledge-Block-Funktionen
+- **Semantische Suche**: Relevante Inhalte mithilfe natürlichsprachlicher Abfragen finden
+- **Kontextintegration**: Relevante Chunks automatisch in Agenten-Prompts einbinden
+- **Dynamisches Abrufen**: Suche erfolgt in Echtzeit während der Workflow-Ausführung
+- **Relevanz-Bewertung**: Ergebnisse nach semantischer Ähnlichkeit sortiert

 ### Integrationsoptionen
- **System-Prompts**: Kontext für Ihre KI-Agenten bereitstellen
- **Dynamischer Kontext**: Suche und Einbindung relevanter Informationen während Gesprächen
- **Dokumentübergreifende Suche**: Abfrage über Ihre gesamte Wissensdatenbank
- **Gefilterte Suche**: Kombination mit Tags für präzisen Inhaltsabruf
+- **System-Prompts**: Stellen Sie Ihren KI-Agenten Kontext bereit
+- **Dynamischer Kontext**: Suchen und fügen Sie relevante Informationen während Konversationen hinzu
+- **Multi-Dokument-Suche**: Durchsuchen Sie Ihre gesamte Wissensdatenbank
+- **Gefilterte Suche**: Kombinieren Sie mit Tags für präzises Abrufen von Inhalten

-## Vektorsuchtechnologie
+## Vektor-Suchtechnologie

 Sim verwendet Vektorsuche, die von [pgvector](https://github.com/pgvector/pgvector) unterstützt wird, um die Bedeutung und den Kontext Ihrer Inhalte zu verstehen:

 ### Semantisches Verständnis
 - **Kontextuelle Suche**: Findet relevante Inhalte, auch wenn exakte Schlüsselwörter nicht übereinstimmen
- **Konzeptbasierte Abfrage**: Versteht Beziehungen zwischen Ideen
+- **Konzeptbasiertes Abrufen**: Versteht Beziehungen zwischen Ideen
 - **Mehrsprachige Unterstützung**: Funktioniert über verschiedene Sprachen hinweg
 - **Synonymerkennung**: Findet verwandte Begriffe und Konzepte

 ### Suchfunktionen
- **Natürlichsprachige Abfragen**: Stellen Sie Fragen in natürlicher Sprache
+- **Natürlichsprachige Abfragen**: Stellen Sie Fragen in einfachem Deutsch
 - **Ähnlichkeitssuche**: Finden Sie konzeptionell ähnliche Inhalte
- **Hybridsuche**: Kombiniert Vektor- und traditionelle Schlüsselwortsuche
- **Konfigurierbare Ergebnisse**: Steuern Sie die Anzahl und den Relevanz-Schwellenwert der Ergebnisse
+- **Hybride Suche**: Kombiniert Vektor- und traditionelle Schlüsselwortsuche
+- **Konfigurierbare Ergebnisse**: Steuern Sie die Anzahl und Relevanzschwelle der Ergebnisse

 ## Dokumentenverwaltung

 ### Organisationsfunktionen
- **Massenupload**: Laden Sie mehrere Dateien gleichzeitig über die asynchrone API hoch
- **Verarbeitungsstatus**: Echtzeit-Updates zum Dokumentenverarbeitungsprozess
- **Suchen und Filtern**: Finden Sie Dokumente schnell in großen Sammlungen
+- **Massen-Upload**: Laden Sie mehrere Dateien gleichzeitig über die asynchrone API hoch
+- **Verarbeitungsstatus**: Echtzeit-Updates zur Dokumentenverarbeitung
+- **Suchen und filtern**: Finden Sie Dokumente schnell in großen Sammlungen
 - **Metadaten-Tracking**: Automatische Erfassung von Dateiinformationen und Verarbeitungsdetails

 ### Sicherheit und Datenschutz
 - **Sichere Speicherung**: Dokumente werden mit Sicherheit auf Unternehmensniveau gespeichert
 - **Zugriffskontrolle**: Workspace-basierte Berechtigungen
- **Verarbeitungsisolierung**: Jeder Workspace hat eine isolierte Dokumentenverarbeitung
+- **Verarbeitungsisolierung**: Jeder Workspace hat isolierte Dokumentenverarbeitung
 - **Datenaufbewahrung**: Konfigurieren Sie Richtlinien zur Dokumentenaufbewahrung

 ## Erste Schritte

 1. **Navigieren Sie zu Ihrer Wissensdatenbank**: Zugriff über Ihre Workspace-Seitenleiste
-2. **Dokumente hochladen**: Drag & Drop oder wählen Sie Dateien zum Hochladen aus
-3. **Verarbeitung überwachen**: Beobachten Sie, wie Dokumente verarbeitet und in Chunks aufgeteilt werden
-4. **Chunks erkunden**: Sehen und bearbeiten Sie die verarbeiteten Inhalte
-5. **Zu Workflows hinzufügen**: Verwenden Sie den Wissensblock, um ihn in Ihre KI-Agenten zu integrieren
+2. **Dokumente hochladen**: Ziehen und ablegen oder Dateien zum Hochladen auswählen
+3. **Verarbeitung überwachen**: Beobachten Sie, wie Dokumente verarbeitet und in Abschnitte unterteilt werden
+4. **Abschnitte erkunden**: Zeigen Sie die verarbeiteten Inhalte an und bearbeiten Sie sie
+5. **Zu Workflows hinzufügen**: Verwenden Sie den Knowledge-Block, um mit Ihren KI-Agenten zu integrieren

-Die Wissensdatenbank verwandelt Ihre statischen Dokumente in eine intelligente, durchsuchbare Ressource, die Ihre KI-Workflows für fundiertere und kontextbezogenere Antworten nutzen können.
+Die Wissensdatenbank verwandelt Ihre statischen Dokumente in eine intelligente, durchsuchbare Ressource, die Ihre KI-Workflows für fundiertere und kontextbezogene Antworten nutzen können.
--- a/apps/docs/content/docs/de/mcp/deploy-workflows.mdx
+++ b/apps/docs/content/docs/de/mcp/deploy-workflows.mdx
@@ -0,0 +1,108 @@
+---
+title: Workflows als MCP bereitstellen
+description: Stellen Sie Ihre Workflows als MCP-Tools für externe KI-Assistenten
+  und Anwendungen bereit
+---
+
+import { Video } from '@/components/ui/video'
+import { Callout } from 'fumadocs-ui/components/callout'
+
+Stellen Sie Ihre Workflows als MCP-Tools bereit, um sie für externe KI-Assistenten wie Claude Desktop, Cursor und andere MCP-kompatible Clients zugänglich zu machen. Dies verwandelt Ihre Workflows in aufrufbare Tools, die von überall aus aufgerufen werden können.
+
+## MCP-Server erstellen und verwalten
+
+MCP-Server gruppieren Ihre Workflow-Tools zusammen. Erstellen und verwalten Sie sie in den Workspace-Einstellungen:
+
+<div className="mx-auto w-full overflow-hidden rounded-lg">
+  <Video src="mcp/mcp-server.mp4" width={700} height={450} />
+</div>
+
+1. Navigieren Sie zu **Einstellungen → MCP-Server**
+2. Klicken Sie auf **Server erstellen**
+3. Geben Sie einen Namen und eine optionale Beschreibung ein
+4. Kopieren Sie die Server-URL zur Verwendung in Ihren MCP-Clients
+5. Zeigen Sie alle zum Server hinzugefügten Tools an und verwalten Sie diese
+
+## Einen Workflow als Tool hinzufügen
+
+Sobald Ihr Workflow bereitgestellt ist, können Sie ihn als MCP-Tool verfügbar machen:
+
+<div className="mx-auto w-full overflow-hidden rounded-lg">
+  <Video src="mcp/mcp-deploy-tool.mp4" width={700} height={450} />
+</div>
+
+1. Öffnen Sie Ihren bereitgestellten Workflow
+2. Klicken Sie auf **Bereitstellen** und wechseln Sie zum Tab **MCP**
+3. Konfigurieren Sie den Tool-Namen und die Beschreibung
+4. Fügen Sie Beschreibungen für jeden Parameter hinzu (hilft der KI, Eingaben zu verstehen)
+5. Wählen Sie aus, zu welchen MCP-Servern es hinzugefügt werden soll
+
+<Callout type="info">
+Der Workflow muss bereitgestellt sein, bevor er als MCP-Tool hinzugefügt werden kann.
+</Callout>
+
+## Tool-Konfiguration
+
+### Tool-Name
+Verwenden Sie Kleinbuchstaben, Zahlen und Unterstriche. Der Name sollte beschreibend sein und den MCP-Namenskonventionen folgen (z. B. `search_documents`, `send_email`).
+
+### Beschreibung
+Schreiben Sie eine klare Beschreibung dessen, was das Tool tut. Dies hilft KI-Assistenten zu verstehen, wann das Tool verwendet werden soll.
+
+### Parameter
+Die Eingabeformatfelder deines Workflows werden zu Tool-Parametern. Füge jedem Parameter Beschreibungen hinzu, um KI-Assistenten zu helfen, korrekte Werte bereitzustellen.
+
+## MCP-Clients verbinden
+
+Verwende die Server-URL aus den Einstellungen, um externe Anwendungen zu verbinden:
+
+### Claude Desktop
+Füge dies zu deiner Claude Desktop-Konfiguration hinzu (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "my-sim-workflows": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "YOUR_SERVER_URL"]
+    }
+  }
+}
+```
+
+### Cursor
+Füge die Server-URL in den MCP-Einstellungen von Cursor mit demselben mcp-remote-Muster hinzu.
+
+<Callout type="warn">
+Füge deinen API-Key-Header (`X-API-Key`) für authentifizierten Zugriff hinzu, wenn du mcp-remote oder andere HTTP-basierte MCP-Transporte verwendest.
+</Callout>
+
+## Server-Verwaltung
+
+In der Server-Detailansicht unter **Einstellungen → MCP-Server** können Sie:
+
+- **Tools anzeigen**: Alle Workflows sehen, die einem Server hinzugefügt wurden
+- **URL kopieren**: Die Server-URL für MCP-Clients abrufen
+- **Workflows hinzufügen**: Weitere bereitgestellte Workflows als Tools hinzufügen
+- **Tools entfernen**: Workflows vom Server entfernen
+- **Server löschen**: Den gesamten Server und alle seine Tools entfernen
+
+## So funktioniert es
+
+Wenn ein MCP-Client dein Tool aufruft:
+
+1. Die Anfrage wird an deiner MCP-Server-URL empfangen
+2. Sim validiert die Anfrage und ordnet Parameter den Workflow-Eingaben zu
+3. Der bereitgestellte Workflow wird mit den angegebenen Eingaben ausgeführt
+4. Die Ergebnisse werden an den MCP-Client zurückgegeben
+
+Workflows werden mit derselben Bereitstellungsversion wie API-Aufrufe ausgeführt, was konsistentes Verhalten gewährleistet.
+
+## Berechtigungsanforderungen
+
+| Aktion | Erforderliche Berechtigung |
+|--------|-------------------|
+| MCP-Server erstellen | **Admin** |
+| Workflows zu Servern hinzufügen | **Write** oder **Admin** |
+| MCP-Server anzeigen | **Read**, **Write** oder **Admin** |
+| MCP-Server löschen | **Admin** |
--- a/apps/docs/content/docs/de/mcp/index.mdx
+++ b/apps/docs/content/docs/de/mcp/index.mdx
@@ -1,8 +1,10 @@
 ---
-title: MCP (Model Context Protocol)
+title: MCP-Tools verwenden
+description: Externe Tools und Dienste über das Model Context Protocol verbinden
 ---

 import { Image } from '@/components/ui/image'
+import { Video } from '@/components/ui/video'
 import { Callout } from 'fumadocs-ui/components/callout'

 Das Model Context Protocol ([MCP](https://modelcontextprotocol.com/)) ermöglicht es Ihnen, externe Tools und Dienste über ein standardisiertes Protokoll zu verbinden, wodurch Sie APIs und Dienste direkt in Ihre Workflows integrieren können. Mit MCP können Sie die Fähigkeiten von Sim erweitern, indem Sie benutzerdefinierte Integrationen hinzufügen, die nahtlos mit Ihren Agenten und Workflows zusammenarbeiten.
@@ -20,14 +22,8 @@ MCP ist ein offener Standard, der es KI-Assistenten ermöglicht, sich sicher mit

 MCP-Server stellen Sammlungen von Tools bereit, die Ihre Agenten nutzen können. Konfigurieren Sie diese in den Workspace-Einstellungen:

-<div className="flex justify-center">
-  <Image
-    src="/static/blocks/mcp-1.png"
-    alt="Konfiguration eines MCP-Servers in den Einstellungen"
-    width={700}
-    height={450}
-    className="my-6"
-  />
+<div className="mx-auto w-full overflow-hidden rounded-lg">
+  <Video src="mcp/settings-mcp-tools.mp4" width={700} height={450} />
 </div>

 1. Navigieren Sie zu Ihren Workspace-Einstellungen
@@ -40,14 +36,18 @@ MCP-Server stellen Sammlungen von Tools bereit, die Ihre Agenten nutzen können.
 Sie können MCP-Server auch direkt über die Symbolleiste in einem Agent-Block für eine schnelle Einrichtung konfigurieren.
 </Callout>

-## Verwendung von MCP-Tools in Agenten
+### Tools aktualisieren

-Sobald MCP-Server konfiguriert sind, werden ihre Tools innerhalb Ihrer Agent-Blöcke verfügbar:
+Klicken Sie bei einem Server auf **Aktualisieren**, um die neuesten Tool-Schemas abzurufen und alle Agent-Blöcke, die diese Tools verwenden, automatisch mit den neuen Parameterdefinitionen zu aktualisieren.
+
+## MCP-Tools in Agents verwenden
+
+Sobald MCP-Server konfiguriert sind, werden ihre Tools in Ihren Agent-Blöcken verfügbar:

 <div className="flex justify-center">
  <Image
    src="/static/blocks/mcp-2.png"
-    alt="Verwendung eines MCP-Tools im Agent-Block"
+    alt="Using MCP Tool in Agent Block"
    width={700}
    height={450}
    className="my-6"
@@ -55,25 +55,25 @@ Sobald MCP-Server konfiguriert sind, werden ihre Tools innerhalb Ihrer Agent-Bl
 </div>

 1. Öffnen Sie einen **Agent**-Block
-2. Im Abschnitt **Tools** sehen Sie die verfügbaren MCP-Tools
+2. Im Bereich **Tools** sehen Sie die verfügbaren MCP-Tools
 3. Wählen Sie die Tools aus, die der Agent verwenden soll
 4. Der Agent kann nun während der Ausführung auf diese Tools zugreifen

 ## Eigenständiger MCP-Tool-Block

-Für eine genauere Kontrolle können Sie den dedizierten MCP-Tool-Block verwenden, um bestimmte MCP-Tools auszuführen:
+Für eine präzisere Steuerung können Sie den dedizierten MCP-Tool-Block verwenden, um bestimmte MCP-Tools auszuführen:

 <div className="flex justify-center">
  <Image
    src="/static/blocks/mcp-3.png"
-    alt="Eigenständiger MCP-Tool-Block"
+    alt="Standalone MCP Tool Block"
    width={700}
    height={450}
    className="my-6"
  />
 </div>

-Der MCP-Tool-Block ermöglicht es Ihnen:
+Der MCP-Tool-Block ermöglicht Ihnen:
 - Jedes konfigurierte MCP-Tool direkt auszuführen
 - Spezifische Parameter an das Tool zu übergeben
 - Die Ausgabe des Tools in nachfolgenden Workflow-Schritten zu verwenden
@@ -81,9 +81,9 @@ Der MCP-Tool-Block ermöglicht es Ihnen:

 ### Wann MCP-Tool vs. Agent verwenden

-**Verwenden Sie einen Agenten mit MCP-Tools, wenn:**
- Sie möchten, dass die KI entscheidet, welche Tools zu verwenden sind
- Sie komplexe Überlegungen benötigen, wann und wie Tools eingesetzt werden sollen
+**Verwenden Sie Agent mit MCP-Tools, wenn:**
+- Sie möchten, dass die KI entscheidet, welche Tools verwendet werden
+- Sie komplexes Reasoning darüber benötigen, wann und wie Tools verwendet werden
 - Sie eine natürlichsprachliche Interaktion mit den Tools wünschen

 **Verwenden Sie den MCP-Tool-Block, wenn:**
@@ -93,7 +93,7 @@ Der MCP-Tool-Block ermöglicht es Ihnen:

 ## Berechtigungsanforderungen

-MCP-Funktionalität erfordert spezifische Workspace-Berechtigungen:
+Die MCP-Funktionalität erfordert spezifische Workspace-Berechtigungen:

 | Aktion | Erforderliche Berechtigung |
 |--------|-------------------|
@@ -105,7 +105,7 @@ MCP-Funktionalität erfordert spezifische Workspace-Berechtigungen:
 ## Häufige Anwendungsfälle

 ### Datenbankintegration
-Verbinden Sie sich mit Datenbanken, um Daten innerhalb Ihrer Workflows abzufragen, einzufügen oder zu aktualisieren.
+Verbinden Sie sich mit Datenbanken, um Daten in Ihren Workflows abzufragen, einzufügen oder zu aktualisieren.

 ### API-Integrationen
 Greifen Sie auf externe APIs und Webdienste zu, die keine integrierten Sim-Integrationen haben.
@@ -113,8 +113,8 @@ Greifen Sie auf externe APIs und Webdienste zu, die keine integrierten Sim-Integ
 ### Dateisystemzugriff
 Lesen, schreiben und bearbeiten Sie Dateien auf lokalen oder entfernten Dateisystemen.

-### Benutzerdefinierte Geschäftslogik
-Führen Sie benutzerdefinierte Skripte oder Tools aus, die auf die Bedürfnisse Ihrer Organisation zugeschnitten sind.
+### Individuelle Geschäftslogik
+Führen Sie benutzerdefinierte Skripte oder Tools aus, die spezifisch für die Anforderungen Ihrer Organisation sind.

 ### Echtzeit-Datenzugriff
 Rufen Sie Live-Daten von externen Systemen während der Workflow-Ausführung ab.
@@ -128,12 +128,12 @@ Rufen Sie Live-Daten von externen Systemen während der Workflow-Ausführung ab.

 ## Fehlerbehebung

-### MCP-Server erscheint nicht
+### MCP-Server wird nicht angezeigt
 - Überprüfen Sie, ob die Serverkonfiguration korrekt ist
- Prüfen Sie, ob Sie die erforderlichen Berechtigungen haben
- Stellen Sie sicher, dass der MCP-Server läuft und zugänglich ist
+- Prüfen Sie, ob Sie über die erforderlichen Berechtigungen verfügen
+- Stellen Sie sicher, dass der MCP-Server läuft und erreichbar ist

-### Fehler bei der Tool-Ausführung
+### Tool-Ausführungsfehler
 - Überprüfen Sie, ob die Tool-Parameter korrekt formatiert sind
 - Prüfen Sie die MCP-Server-Logs auf Fehlermeldungen
 - Stellen Sie sicher, dass die erforderliche Authentifizierung konfiguriert ist
@@ -141,4 +141,4 @@ Rufen Sie Live-Daten von externen Systemen während der Workflow-Ausführung ab.
 ### Berechtigungsfehler
 - Bestätigen Sie Ihre Workspace-Berechtigungsstufe
 - Prüfen Sie, ob der MCP-Server zusätzliche Authentifizierung erfordert
- Stellen Sie sicher, dass der Server für Ihren Workspace richtig konfiguriert ist
+- Überprüfen Sie, ob der Server ordnungsgemäß für Ihren Workspace konfiguriert ist
--- a/apps/docs/content/docs/de/meta.json
+++ b/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
+}
--- a/apps/docs/content/docs/de/quick-reference/index.mdx
+++ b/apps/docs/content/docs/de/quick-reference/index.mdx
@@ -0,0 +1,394 @@
+---
+title: Kurzreferenz
+description: Wesentliche Aktionen zum Navigieren und Verwenden des Sim-Workflow-Editors
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { ActionImage, ActionVideo } from '@/components/ui/action-media'
+
+Eine schnelle Übersicht für alltägliche Aktionen im Sim-Workflow-Editor. Für Tastaturkürzel siehe [Tastaturkürzel](/keyboard-shortcuts).
+
+<Callout type="info">
+  **Mod** bezieht sich auf `Cmd` unter macOS und `Ctrl` unter Windows/Linux.
+</Callout>
+
+## Arbeitsbereiche
+
+<table>
+  <thead>
+    <tr><th>Aktion</th><th>Wie</th><th>Vorschau</th></tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Arbeitsbereich erstellen</td>
+      <td>Arbeitsbereich-Dropdown anklicken → **Neuer Arbeitsbereich**</td>
+      <td><ActionVideo src="quick-reference/create-workspace.mp4" alt="Arbeitsbereich erstellen" /></td>
+    </tr>
+    <tr>
+      <td>Arbeitsbereiche wechseln</td>
+      <td>Arbeitsbereich-Dropdown anklicken → Arbeitsbereich auswählen</td>
+      <td><ActionVideo src="quick-reference/switch-workspace.mp4" alt="Arbeitsbereiche wechseln" /></td>
+    </tr>
+    <tr>
+      <td>Teammitglieder einladen</td>
+      <td>Seitenleiste → **Einladen**</td>
+      <td><ActionVideo src="quick-reference/invite.mp4" alt="Teammitglieder einladen" /></td>
+    </tr>
+    <tr>
+      <td>Arbeitsbereich umbenennen</td>
+      <td>Rechtsklick auf Arbeitsbereich → **Umbenennen**</td>
+      <td rowSpan={4}><ActionImage src="/static/quick-reference/workspace-context-menu.png" alt="Arbeitsbereich-Kontextmenü" /></td>
+    </tr>
+    <tr>
+      <td>Arbeitsbereich duplizieren</td>
+      <td>Rechtsklick auf Arbeitsbereich → **Duplizieren**</td>
+    </tr>
+    <tr>
+      <td>Arbeitsbereich exportieren</td>
+      <td>Rechtsklick auf Arbeitsbereich → **Exportieren**</td>
+    </tr>
+    <tr>
+      <td>Arbeitsbereich löschen</td>
+      <td>Rechtsklick auf Arbeitsbereich → **Löschen**</td>
+    </tr>
+  </tbody>
+</table>
+
+## Workflows
+
+<table>
+  <thead>
+    <tr><th>Aktion</th><th>Wie</th><th>Vorschau</th></tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Workflow erstellen</td>
+      <td>**+**-Schaltfläche in der Seitenleiste anklicken</td>
+      <td><ActionImage src="/static/quick-reference/create-workflow.png" alt="Workflow erstellen" /></td>
+    </tr>
+    <tr>
+      <td>Workflows neu anordnen / verschieben</td>
+      <td>Workflow nach oben/unten oder auf einen Ordner ziehen</td>
+      <td><ActionVideo src="quick-reference/reordering.mp4" alt="Workflows neu anordnen" /></td>
+    </tr>
+    <tr>
+      <td>Workflow importieren</td>
+      <td>Import-Schaltfläche in der Seitenleiste anklicken → Datei auswählen</td>
+      <td><ActionImage src="/static/quick-reference/import-workflow.png" alt="Workflow importieren" /></td>
+    </tr>
+    <tr>
+      <td>Mehrere Workflows auswählen</td>
+      <td>`Mod+Click` oder `Shift+Click` Workflows in der Seitenleiste</td>
+      <td><ActionVideo src="quick-reference/multiselect.mp4" alt="Mehrere Workflows auswählen" /></td>
+    </tr>
+    <tr>
+      <td>In neuem Tab öffnen</td>
+      <td>Rechtsklick auf Workflow → **In neuem Tab öffnen**</td>
+      <td rowSpan={6}><ActionImage src="/static/quick-reference/workflow-context-menu.png" alt="Workflow-Kontextmenü" /></td>
+    </tr>
+    <tr>
+      <td>Workflow umbenennen</td>
+      <td>Rechtsklick auf Workflow → **Umbenennen**</td>
+    </tr>
+    <tr>
+      <td>Workflow-Farbe zuweisen</td>
+      <td>Rechtsklick auf Workflow → **Farbe ändern**</td>
+    </tr>
+    <tr>
+      <td>Workflow duplizieren</td>
+      <td>Rechtsklick auf Workflow → **Duplizieren**</td>
+    </tr>
+    <tr>
+      <td>Workflow exportieren</td>
+      <td>Rechtsklick auf Workflow → **Exportieren**</td>
+    </tr>
+    <tr>
+      <td>Workflow löschen</td>
+      <td>Rechtsklick auf Workflow → **Löschen**</td>
+    </tr>
+    <tr>
+      <td>Ordner umbenennen</td>
+      <td>Rechtsklick auf Ordner → **Umbenennen**</td>
+      <td rowSpan={6}><ActionImage src="/static/quick-reference/folder-context-menu.png" alt="Ordner-Kontextmenü" /></td>
+    </tr>
+    <tr>
+      <td>Workflow in Ordner erstellen</td>
+      <td>Rechtsklick auf Ordner → **Workflow erstellen**</td>
+    </tr>
+    <tr>
+      <td>Ordner in Ordner erstellen</td>
+      <td>Rechtsklick auf Ordner → **Ordner erstellen**</td>
+    </tr>
+    <tr>
+      <td>Ordner duplizieren</td>
+      <td>Rechtsklick auf Ordner → **Duplizieren**</td>
+    </tr>
+    <tr>
+      <td>Ordner exportieren</td>
+      <td>Rechtsklick auf Ordner → **Exportieren**</td>
+    </tr>
+    <tr>
+      <td>Ordner löschen</td>
+      <td>Rechtsklick auf Ordner → **Löschen**</td>
+    </tr>
+  </tbody>
+</table>
+
+## Blöcke
+
+<table>
+  <thead>
+    <tr><th>Aktion</th><th>Wie</th><th>Vorschau</th></tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Block hinzufügen</td>
+      <td>Aus Toolbar-Panel ziehen oder Rechtsklick auf Canvas → **Block hinzufügen**</td>
+      <td><ActionVideo src="quick-reference/add-block.mp4" alt="Block hinzufügen" /></td>
+    </tr>
+    <tr>
+      <td>Mehrere Blöcke auswählen</td>
+      <td>`Mod+Click` zusätzliche Blöcke oder Shift-Ziehen für Auswahlrahmen</td>
+      <td><ActionVideo src="quick-reference/multiselect-blocks.mp4" alt="Mehrere Blöcke auswählen" /></td>
+    </tr>
+    <tr>
+      <td>Blöcke kopieren</td>
+      <td>`Mod+C` mit ausgewählten Blöcken</td>
+      <td rowSpan={2}><ActionVideo src="quick-reference/copy-paste.mp4" alt="Blöcke kopieren und einfügen" /></td>
+    </tr>
+    <tr>
+      <td>Blöcke einfügen</td>
+      <td>`Mod+V` zum Einfügen kopierter Blöcke</td>
+    </tr>
+    <tr>
+      <td>Blöcke duplizieren</td>
+      <td>Rechtsklick → **Duplizieren**</td>
+      <td><ActionVideo src="quick-reference/duplicate-block.mp4" alt="Blöcke duplizieren" /></td>
+    </tr>
+    <tr>
+      <td>Blöcke löschen</td>
+      <td>`Delete` oder `Backspace` Taste oder Rechtsklick → **Löschen**</td>
+      <td><ActionImage src="/static/quick-reference/delete-block.png" alt="Block löschen" /></td>
+    </tr>
+    <tr>
+      <td>Block umbenennen</td>
+      <td>Auf Blocknamen im Header klicken oder im Editor-Panel bearbeiten</td>
+      <td><ActionVideo src="quick-reference/rename-block.mp4" alt="Block umbenennen" /></td>
+    </tr>
+    <tr>
+      <td>Block aktivieren/deaktivieren</td>
+      <td>Rechtsklick → **Aktivieren/Deaktivieren**</td>
+      <td><ActionImage src="/static/quick-reference/disable-block.png" alt="Block deaktivieren" /></td>
+    </tr>
+    <tr>
+      <td>Block sperren/entsperren</td>
+      <td>Über Block hovern → Auf Schloss-Symbol klicken (nur Admin)</td>
+      <td><ActionImage src="/static/quick-reference/lock-block.png" alt="Block sperren" /></td>
+    </tr>
+    <tr>
+      <td>Handle-Ausrichtung umschalten</td>
+      <td>Rechtsklick → **Handles umschalten**</td>
+      <td><ActionVideo src="quick-reference/toggle-handles.mp4" alt="Handle-Ausrichtung umschalten" /></td>
+    </tr>
+    <tr>
+      <td>Block konfigurieren</td>
+      <td>Block auswählen → Editor-Panel rechts verwenden</td>
+      <td><ActionVideo src="quick-reference/configure-block.mp4" alt="Block konfigurieren" /></td>
+    </tr>
+  </tbody>
+</table>
+
+## Verbindungen
+
+<table>
+  <thead>
+    <tr><th>Aktion</th><th>Wie</th><th>Vorschau</th></tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Verbindung erstellen</td>
+      <td>Vom Ausgangs-Handle zum Eingangs-Handle ziehen</td>
+      <td><ActionVideo src="quick-reference/connect-blocks.mp4" alt="Blöcke verbinden" /></td>
+    </tr>
+    <tr>
+      <td>Verbindung löschen</td>
+      <td>Auf Kante klicken zum Auswählen → `Delete` Taste</td>
+      <td><ActionVideo src="quick-reference/delete-connection.mp4" alt="Verbindung löschen" /></td>
+    </tr>
+    <tr>
+      <td>Ausgabe in anderem Block verwenden</td>
+      <td>Verbindungs-Tag in Eingabefeld ziehen</td>
+      <td><ActionVideo src="quick-reference/connection-tag.mp4" alt="Verbindungs-Tag verwenden" /></td>
+    </tr>
+  </tbody>
+</table>
+
+## Panels und Ansichten
+
+<table>
+  <thead>
+    <tr><th>Aktion</th><th>Wie</th><th>Vorschau</th></tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Symbolleiste durchsuchen</td>
+      <td>`Mod+F`</td>
+      <td><ActionVideo src="quick-reference/search-toolbar.mp4" alt="Symbolleiste durchsuchen" /></td>
+    </tr>
+    <tr>
+      <td>Alles durchsuchen</td>
+      <td>`Mod+K`</td>
+      <td><ActionImage src="/static/quick-reference/search-everything.png" alt="Alles durchsuchen" /></td>
+    </tr>
+    <tr>
+      <td>Manuellen Modus umschalten</td>
+      <td>Klicken Sie auf die Umschalt-Schaltfläche, um zwischen manuell und Selektor zu wechseln</td>
+      <td><ActionImage src="/static/quick-reference/toggle-manual-mode.png" alt="Manuellen Modus umschalten" /></td>
+    </tr>
+    <tr>
+      <td>Seitenleiste ein-/ausklappen</td>
+      <td>Klicken Sie auf die Einklappen-Schaltfläche in der Seitenleiste</td>
+      <td><ActionVideo src="quick-reference/collapse-sidebar.mp4" alt="Seitenleiste einklappen" /></td>
+    </tr>
+  </tbody>
+</table>
+
+## Ausführen und Testen
+
+<table>
+  <thead>
+    <tr><th>Aktion</th><th>Wie</th><th>Vorschau</th></tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Workflow ausführen</td>
+      <td>Klicken Sie auf die Schaltfläche Workflow ausführen oder `Mod+Enter`</td>
+      <td><ActionImage src="/static/quick-reference/run-workflow.png" alt="Workflow ausführen" /></td>
+    </tr>
+    <tr>
+      <td>Workflow stoppen</td>
+      <td>Klicken Sie auf die Stopp-Schaltfläche oder `Mod+Enter` während der Ausführung</td>
+      <td><ActionImage src="/static/quick-reference/stop-workflow.png" alt="Workflow stoppen" /></td>
+    </tr>
+    <tr>
+      <td>Mit Chat testen</td>
+      <td>Verwenden Sie das Chat-Panel auf der rechten Seite</td>
+      <td><ActionImage src="/static/quick-reference/test-chat.png" alt="Mit Chat testen" /></td>
+    </tr>
+    <tr>
+      <td>Ausgabe zum Anzeigen auswählen</td>
+      <td>Klicken Sie auf das Dropdown-Menü im Chat-Panel → Wählen Sie Block-Ausgabe aus</td>
+      <td><ActionImage src="/static/quick-reference/output-select.png" alt="Ausgabe zum Anzeigen auswählen" /></td>
+    </tr>
+    <tr>
+      <td>Chat-Verlauf löschen</td>
+      <td>Klicken Sie auf die Löschen-Schaltfläche im Chat-Panel</td>
+      <td><ActionImage src="/static/quick-reference/clear-chat.png" alt="Chat-Verlauf löschen" /></td>
+    </tr>
+    <tr>
+      <td>Ab Block ausführen</td>
+      <td>Bewegen Sie den Mauszeiger über den Block → Klicken Sie auf die Wiedergabe-Schaltfläche oder Rechtsklick → **Ab Block ausführen**</td>
+      <td><ActionImage src="/static/quick-reference/run-from-block.png" alt="Ab Block ausführen" /></td>
+    </tr>
+    <tr>
+      <td>Bis Block ausführen</td>
+      <td>Rechtsklick auf Block → **Bis Block ausführen**</td>
+      <td><ActionImage src="/static/quick-reference/run-until-block.png" alt="Bis Block ausführen" /></td>
+    </tr>
+    <tr>
+      <td>Ausführungsprotokolle anzeigen</td>
+      <td>Öffnen Sie das Terminal-Panel unten oder `Mod+L`</td>
+      <td><ActionImage src="/static/quick-reference/terminal.png" alt="Terminal für Ausführungsprotokolle" /></td>
+    </tr>
+    <tr>
+      <td>Protokolle filtern</td>
+      <td>Klicken Sie auf das Filter-Symbol im Terminal → Filtern Sie nach Block oder Status</td>
+      <td><ActionImage src="/static/quick-reference/filter-block.png" alt="Protokolle nach Block filtern" /></td>
+    </tr>
+    <tr>
+      <td>Protokolle durchsuchen</td>
+      <td>Verwenden Sie das Suchfeld im Terminal oder Rechtsklick auf Protokolleintrag → **Suchen**</td>
+      <td><ActionImage src="/static/quick-reference/terminal-search.png" alt="Protokolle durchsuchen" /></td>
+    </tr>
+    <tr>
+      <td>Protokolleintrag kopieren</td>
+      <td>Zwischenablage-Symbol oder Rechtsklick auf Protokolleintrag → **Kopieren**</td>
+      <td><ActionImage src="/static/quick-reference/copy-log.png" alt="Protokolleintrag kopieren" /></td>
+    </tr>
+    <tr>
+      <td>Terminal leeren</td>
+      <td>Papierkorb-Symbol oder `Mod+D`</td>
+      <td><ActionImage src="/static/quick-reference/clear-terminal.png" alt="Terminal leeren" /></td>
+    </tr>
+  </tbody>
+</table>
+
+## Bereitstellung
+
+<table>
+  <thead>
+    <tr><th>Aktion</th><th>Wie</th><th>Vorschau</th></tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Workflow bereitstellen</td>
+      <td>Klicken Sie auf die Schaltfläche **Bereitstellen** im Panel</td>
+      <td><ActionImage src="/static/quick-reference/deploy.png" alt="Workflow bereitstellen" /></td>
+    </tr>
+    <tr>
+      <td>Bereitstellung aktualisieren</td>
+      <td>Klicken Sie auf **Aktualisieren**, wenn Änderungen erkannt werden</td>
+      <td><ActionImage src="/static/quick-reference/update-deployment.png" alt="Bereitstellung aktualisieren" /></td>
+    </tr>
+    <tr>
+      <td>Bereitstellungsstatus anzeigen</td>
+      <td>Überprüfen Sie die Statusanzeige (Live/Aktualisieren/Bereitstellen) im Tab „Bereitstellen"</td>
+      <td><ActionImage src="/static/quick-reference/view-deployment.png" alt="Bereitstellungsstatus anzeigen" /></td>
+    </tr>
+    <tr>
+      <td>Bereitstellung zurücksetzen</td>
+      <td>Greifen Sie auf frühere Versionen im Tab „Bereitstellen" zu → **Zu Live befördern**</td>
+      <td><ActionImage src="/static/quick-reference/promote-deployment.png" alt="Bereitstellung zu Live befördern" /></td>
+    </tr>
+    <tr>
+      <td>Versionsbeschreibung hinzufügen</td>
+      <td>Tab „Bereitstellen" → Klicken Sie auf das Beschreibungssymbol → Beschreibung hinzufügen oder generieren</td>
+      <td><ActionVideo src="quick-reference/deployment-description.mp4" alt="Versionsbeschreibung für Bereitstellung hinzufügen" /></td>
+    </tr>
+    <tr>
+      <td>API-Endpunkt kopieren</td>
+      <td>Tab „Bereitstellen" → API → API-cURL kopieren</td>
+      <td><ActionImage src="/static/quick-reference/copy-api.png" alt="API-Endpunkt kopieren" /></td>
+    </tr>
+  </tbody>
+</table>
+
+## Variablen
+
+<table>
+  <thead>
+    <tr><th>Aktion</th><th>Wie</th><th>Vorschau</th></tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Workflow-Variable hinzufügen / bearbeiten / löschen</td>
+      <td>Panel → Variablen → **Variable hinzufügen**, zum Bearbeiten klicken oder Löschsymbol verwenden</td>
+      <td><ActionImage src="/static/quick-reference/variables.png" alt="Variablen-Panel" /></td>
+    </tr>
+    <tr>
+      <td>Umgebungsvariable hinzufügen</td>
+      <td>Einstellungen → **Umgebungsvariablen** → **Hinzufügen**</td>
+      <td><ActionImage src="/static/quick-reference/add-env-variable.png" alt="Umgebungsvariable hinzufügen" /></td>
+    </tr>
+    <tr>
+      <td>Auf Workflow-Variable verweisen</td>
+      <td>Verwenden Sie die Syntax `<blockName.itemName>` in Block-Eingaben</td>
+      <td><ActionImage src="/static/quick-reference/variable-reference.png" alt="Auf Workflow-Variable verweisen" /></td>
+    </tr>
+    <tr>
+      <td>Auf Umgebungsvariable verweisen</td>
+      <td>Verwenden Sie die Syntax `{{ENV_VAR}}` in Block-Eingaben</td>
+      <td><ActionImage src="/static/quick-reference/env-variable-reference.png" alt="Auf Umgebungsvariable verweisen" /></td>
+    </tr>
+  </tbody>
+</table>
--- a/apps/docs/content/docs/de/sdks/python.mdx
+++ b/apps/docs/content/docs/de/sdks/python.mdx
@@ -7,10 +7,10 @@ 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 mithilfe des offiziellen Python SDKs auszuführen.
+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 asynchroner Ausführungsunterstützung, automatischer Ratenbegrenzung mit exponentiellem Backoff und Nutzungsverfolgung.
+  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
@@ -75,16 +75,16 @@ result = client.execute_workflow(
 - `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, die im `blockName.attribute`Format gestreamt werden sollen (z.B. `["agent1.content"]`)
+- `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ückgabe:** `WorkflowExecutionResult | AsyncExecutionResult`
+**Rückgabewert:** `WorkflowExecutionResult | AsyncExecutionResult`

-Wenn `async_execution=True`, wird sofort mit einer Task-ID zum Abfragen zurückgegeben. Andernfalls wird auf den Abschluss gewartet.
+Wenn `async_execution=True`, wird sofort mit einer Task-ID zum Polling zurückgegeben. Andernfalls wird auf die Fertigstellung gewartet.

 ##### get_workflow_status()

-Den Status eines Workflows abrufen (Bereitstellungsstatus usw.).
+Ruft den Status eines Workflows ab (Deployment-Status usw.).

 ```python
 status = client.get_workflow_status("workflow-id")
@@ -98,7 +98,7 @@ print("Is deployed:", status.is_deployed)

 ##### validate_workflow()

-Überprüfen, ob ein Workflow für die Ausführung bereit ist.
+Überprüft, ob ein Workflow zur Ausführung bereit ist.

 ```python
 is_ready = client.validate_workflow("workflow-id")
@@ -114,7 +114,7 @@ if is_ready:

 ##### get_job_status()

-Den Status einer asynchronen Job-Ausführung abrufen.
+Ruft den Status einer asynchronen Job-Ausführung ab.

 ```python
 status = client.get_job_status("task-id-from-async-execution")
@@ -131,7 +131,7 @@ if status["status"] == "completed":
 **Antwortfelder:**
 - `success` (bool): Ob die Anfrage erfolgreich war
 - `taskId` (str): Die Task-ID
- `status` (str): Einer der Werte `'queued'`, `'processing'`, `'completed'`, `'failed'`, `'cancelled'`
+- `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)
@@ -139,7 +139,7 @@ if status["status"] == "completed":

 ##### execute_with_retry()

-Einen Workflow mit automatischer Wiederholung bei Ratenbegrenzungsfehlern unter Verwendung von exponentiellem Backoff ausführen.
+Führt einen Workflow mit automatischer Wiederholung bei Rate-Limit-Fehlern unter Verwendung von exponentiellem Backoff aus.

 ```python
 result = client.execute_with_retry(
@@ -161,13 +161,13 @@ result = client.execute_with_retry(
 - `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): Anfängliche Verzögerung in Sekunden (Standard: 1.0)
+- `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ückgabewert:** `WorkflowExecutionResult | AsyncExecutionResult`
+**Rückgabe:** `WorkflowExecutionResult | AsyncExecutionResult`

-Die Wiederholungslogik verwendet exponentielles Backoff (1s → 2s → 4s → 8s...) mit ±25% Jitter, um den Thundering-Herd-Effekt zu vermeiden. Wenn die API einen `retry-after` Header bereitstellt, wird dieser stattdessen verwendet.
+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()

@@ -185,7 +185,7 @@ if rate_limit_info:

 ##### get_usage_limits()

-Ruft aktuelle Nutzungslimits und Kontingentinformationen für dein Konto ab.
+Ruft aktuelle Nutzungslimits und Kontingentinformationen für Ihr Konto ab.

 ```python
 limits = client.get_usage_limits()
@@ -320,9 +320,9 @@ class SimStudioError(Exception):

 **Häufige Fehlercodes:**
 - `UNAUTHORIZED`: Ungültiger API-Schlüssel
- `TIMEOUT`: Zeitüberschreitung bei der Anfrage
- `RATE_LIMIT_EXCEEDED`: Ratengrenze überschritten
- `USAGE_LIMIT_EXCEEDED`: Nutzungsgrenze überschritten
+- `TIMEOUT`: Zeitüberschreitung der Anfrage
+- `RATE_LIMIT_EXCEEDED`: Ratenlimit überschritten
+- `USAGE_LIMIT_EXCEEDED`: Nutzungslimit überschritten
 - `EXECUTION_ERROR`: Workflow-Ausführung fehlgeschlagen

 ## Beispiele
@@ -334,7 +334,7 @@ class SimStudioError(Exception):
    Richten Sie den SimStudioClient mit Ihrem API-Schlüssel ein.
  </Step>
  <Step title="Workflow validieren">
-    Prüfen Sie, ob der Workflow bereitgestellt und für die Ausführung bereit ist.
+    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.
@@ -386,7 +386,7 @@ Behandeln Sie verschiedene Fehlertypen, die während der Workflow-Ausführung au
 from simstudio import SimStudioClient, SimStudioError
 import os

-client = SimStudioClient(api_key=os.getenv("SIM_API_KEY"))   
+client = SimStudioClient(api_key=os.getenv("SIM_API_KEY"))

 def execute_with_error_handling():
    try:
@@ -409,11 +409,20 @@ def execute_with_error_handling():
        raise
 ```

-### Verwendung des Kontextmanagers
+### Verwendung des Context-Managers

-Verwenden Sie den Client als Kontextmanager, um die Ressourcenbereinigung automatisch zu handhaben:
+Verwenden Sie den Client als Context-Manager, um die Ressourcenbereinigung automatisch zu handhaben:

---CODE-PLACEHOLDER-ef99d3dd509e04865d5b6b0e0e03d3f8---
+```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

@@ -466,7 +475,7 @@ for result in results:

 ### Asynchrone Workflow-Ausführung

-Führen Sie Workflows asynchron für lang laufende Aufgaben aus:
+Führen Sie Workflows asynchron für langwierige Aufgaben aus:

 ```python
 import os
@@ -510,9 +519,9 @@ def execute_async():
 execute_async()
 ```

-### Rate-Limiting und Wiederholungsversuche
+### Ratenlimitierung und Wiederholung

-Behandle Rate-Limits automatisch mit exponentiellem Backoff:
+Behandeln Sie Ratenbegrenzungen automatisch mit exponentiellem Backoff:

 ```python
 import os
@@ -549,7 +558,7 @@ execute_with_retry_handling()

 ### Nutzungsüberwachung

-Überwache deine Kontonutzung und -limits:
+Überwachen Sie die Nutzung und Limits Ihres Kontos:

 ```python
 import os
@@ -593,13 +602,13 @@ check_usage()

 ### Streaming-Workflow-Ausführung

-Führe Workflows mit Echtzeit-Streaming-Antworten aus:
+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"))   
+client = SimStudioClient(api_key=os.getenv("SIM_API_KEY"))

 def execute_with_streaming():
    """Execute workflow with streaming enabled."""
@@ -619,7 +628,7 @@ def execute_with_streaming():
 execute_with_streaming()
 ```

-Die Streaming-Antwort folgt dem Server-Sent Events (SSE) Format:
+Die Streaming-Antwort folgt dem Server-Sent-Events- (SSE-) Format:

 ```
 data: {"blockId":"7b7735b9-19e5-4bd6-818b-46aae2596e9f","chunk":"One"}
@@ -688,9 +697,9 @@ if __name__ == '__main__':
    app.run(debug=True)
 ```

-### Umgebungskonfiguration
+### Umgebungskonfiguration

-Konfiguriere den Client mit Umgebungsvariablen:
+Konfigurieren Sie den Client mit Umgebungsvariablen:

 <Tabs items={['Development', 'Production']}>
  <Tab value="Development">
@@ -727,27 +736,27 @@ Konfiguriere den Client mit Umgebungsvariablen:
  </Tab>
 </Tabs>

-## API-Schlüssel erhalten
+## Ihren API-Schlüssel erhalten

 <Steps>
  <Step title="Bei Sim anmelden">
-    Navigiere zu [Sim](https://sim.ai) und melde dich bei deinem Konto an.
+    Navigieren Sie zu [Sim](https://sim.ai) und melden Sie sich in Ihrem Konto an.
  </Step>
-  <Step title="Öffne deinen Workflow">
-    Navigiere zu dem Workflow, den du programmatisch ausführen möchtest.
+  <Step title="Workflow öffnen">
+    Navigieren Sie zu dem Workflow, den Sie programmatisch ausführen möchten.
  </Step>
-  <Step title="Deploye deinen Workflow">
-    Klicke auf "Deploy", um deinen Workflow zu deployen, falls dies noch nicht geschehen ist.
+  <Step title="Workflow bereitstellen">
+    Klicken Sie auf "Bereitstellen", um Ihren Workflow bereitzustellen, falls dies noch nicht geschehen ist.
  </Step>
-  <Step title="Erstelle oder wähle einen API-Schlüssel">
-    Wähle während des Deployment-Prozesses einen API-Schlüssel aus oder erstelle einen neuen.
+  <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="Kopiere den API-Schlüssel">
-    Kopiere den API-Schlüssel zur Verwendung in deiner Python-Anwendung.
+  <Step title="API-Schlüssel kopieren">
+    Kopieren Sie den API-Schlüssel, um ihn in Ihrer Python-Anwendung zu verwenden.
  </Step>
 </Steps>

-## Anforderungen
+## Voraussetzungen

 - Python 3.8+
 - requests >= 2.25.0
--- a/Show More
+++ b/Show More