diff --git a/apps/docs/content/docs/en/blocks/function.mdx b/apps/docs/content/docs/en/blocks/function.mdx
index 05510aa3d22..bfad3468b1f 100644
--- a/apps/docs/content/docs/en/blocks/function.mdx
+++ b/apps/docs/content/docs/en/blocks/function.mdx
@@ -2,10 +2,12 @@
 title: Function
 ---
 
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
 import { Image } from '@/components/ui/image'
 import { FAQ } from '@/components/ui/faq'
 
-The Function block executes custom JavaScript or TypeScript code in your workflows. Transform data, perform calculations, or implement custom logic.
+The Function block executes custom JavaScript, TypeScript, or Python code in your workflows. Transform data, perform calculations, or implement custom logic.
 
 <div className="flex justify-center">
   <Image
@@ -41,6 +43,8 @@ Input → Function (Validate & Sanitize) → API (Save to Database)
 
 ### Example: Loyalty Score Calculator
 
+<Tabs items={['JavaScript', 'Python']}>
+  <Tab value="JavaScript">
 ```javascript title="loyalty-calculator.js"
 // Process customer data and calculate loyalty score
 const { purchaseHistory, accountAge, supportTickets } = <agent>;
@@ -64,6 +68,112 @@ return {
   metrics: { spendScore, frequencyScore, supportScore }
 };
 ```
+  </Tab>
+  <Tab value="Python">
+```python title="loyalty-calculator.py"
+import json
+
+# Reference outputs from other blocks using angle bracket syntax
+data = json.loads('<agent>')
+purchase_history = data["purchaseHistory"]
+account_age = data["accountAge"]
+support_tickets = data["supportTickets"]
+
+# Calculate metrics
+total_spent = sum(p["amount"] for p in purchase_history)
+purchase_frequency = len(purchase_history) / (account_age / 365)
+ticket_ratio = support_tickets["resolved"] / support_tickets["total"]
+
+# Calculate loyalty score (0-100)
+spend_score = min(total_spent / 1000 * 30, 30)
+frequency_score = min(purchase_frequency * 20, 40)
+support_score = ticket_ratio * 30
+
+loyalty_score = round(spend_score + frequency_score + support_score)
+
+tier = "Platinum" if loyalty_score >= 80 else "Gold" if loyalty_score >= 60 else "Silver"
+
+result = {
+    "customer": data["name"],
+    "loyaltyScore": loyalty_score,
+    "loyaltyTier": tier,
+    "metrics": {
+        "spendScore": spend_score,
+        "frequencyScore": frequency_score,
+        "supportScore": support_score
+    }
+}
+print(json.dumps(result))
+```
+  </Tab>
+</Tabs>
+
+## Python Support
+
+The Function block supports Python as an alternative to JavaScript. Python code runs in a secure [E2B](https://e2b.dev) cloud sandbox.
+
+{/* TODO: Screenshot of the Function block with Python language selected */}
+
+### Enabling Python
+
+Select **Python** from the language dropdown in the Function block. Python execution requires E2B to be enabled on your Sim instance.
+
+<Callout type="warn">
+If you don't see Python as an option in the language dropdown, E2B is not enabled. This only applies to self-hosted instances — E2B is enabled by default on sim.ai.
+</Callout>
+
+<Callout type="info">
+Python code always runs in the E2B sandbox, even for simple scripts without imports. This ensures a secure, isolated execution environment.
+</Callout>
+
+### Returning Results
+
+In Python, print your result as JSON to stdout. The Function block captures stdout and makes it available via `<function.result>`:
+
+```python title="example.py"
+import json
+
+data = {"status": "processed", "count": 42}
+print(json.dumps(data))
+```
+
+### Available Libraries
+
+The E2B sandbox includes the Python standard library (`json`, `re`, `datetime`, `math`, `os`, `collections`, etc.) and common packages like `matplotlib` for visualization. Charts generated with matplotlib are captured as images automatically.
+
+<Callout type="info">
+  The exact set of pre-installed packages depends on the E2B sandbox configuration. If a package you need isn't available, consider calling an external API from your code instead.
+</Callout>
+
+### Matplotlib Charts
+
+When your Python code generates matplotlib figures, they are automatically captured and returned as base64-encoded PNG images in the output:
+
+```python title="chart.py"
+import matplotlib.pyplot as plt
+import json
+
+data = json.loads('<api.data>')
+
+plt.figure(figsize=(10, 6))
+plt.bar(data["labels"], data["values"])
+plt.title("Monthly Revenue")
+plt.xlabel("Month")
+plt.ylabel("Revenue ($)")
+plt.savefig("chart.png")
+plt.show()
+```
+
+{/* TODO: Screenshot of Python code execution output in the logs panel */}
+
+### JavaScript vs. Python
+
+| | JavaScript | Python |
+|--|-----------|--------|
+| **Execution** | Local VM (fast) or E2B sandbox (with imports) | Always E2B sandbox |
+| **Returning results** | `return { ... }` | `print(json.dumps({ ... }))` |
+| **HTTP requests** | `fetch()` built-in | `requests` or `httpx` |
+| **Best for** | Quick transforms, JSON manipulation | Data science, charting, complex math |
 
 ## Best Practices
 
diff --git a/apps/docs/content/docs/en/execution/api-deployment.mdx b/apps/docs/content/docs/en/execution/api-deployment.mdx
new file mode 100644
index 00000000000..43ec5cea3e4
--- /dev/null
+++ b/apps/docs/content/docs/en/execution/api-deployment.mdx
@@ -0,0 +1,262 @@
+---
+title: API Deployment
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+import { FAQ } from '@/components/ui/faq'
+
+Deploy your workflow as a REST API endpoint that applications can call directly. Supports synchronous, streaming, and asynchronous execution modes.
+
+## Deploying a Workflow
+
+1. Open your workflow and click **Deploy**
+2. The **General** tab shows deployment status — click **Deploy** to publish
+3. Switch to the **API** tab to see your endpoint URL and code examples
+
+{/* TODO: Screenshot of the API tab in the deploy modal showing code examples */}
+
+Once deployed, your workflow is available at:
+
+```
+POST https://sim.ai/api/workflows/{workflow-id}/execute
+```
+
+<Callout type="info">
+  API executions run against the active deployment snapshot. After making canvas changes, click **Update** in the Deploy modal to publish a new version.
+</Callout>
+
+## Authentication
+
+By default, API endpoints require an API key in the `x-api-key` header. You can generate keys in **Settings → Sim Keys**.
+
+```bash
+curl -X POST https://sim.ai/api/workflows/{workflow-id}/execute \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: $SIM_API_KEY" \
+  -d '{ "input": "Hello" }'
+```
+
+### Public APIs
+
+You can make an API endpoint public so it doesn't require authentication. This is useful for public-facing integrations or webhooks from external services.
+
+{/* TODO: Screenshot of the public/private API toggle */}
+
+<Callout type="warn">
+  Public endpoints can be called by anyone with the URL. Only use this for workflows that don't expose sensitive data or perform sensitive actions.
+</Callout>
+
+## Execution Modes
+
+The API tab in the Deploy modal shows code examples for each mode in **cURL**, **Python**, **JavaScript**, and **TypeScript**.
+
+### Synchronous
+
+The default mode. Send a request and wait for the complete response:
+
+<Tabs items={['cURL', 'Python']}>
+  <Tab value="cURL">
+```bash
+curl -X POST https://sim.ai/api/workflows/{workflow-id}/execute \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: $SIM_API_KEY" \
+  -d '{ "input": "Summarize this article" }'
+```
+  </Tab>
+  <Tab value="Python">
+```python
+import requests
+import os
+
+response = requests.post(
+    "https://sim.ai/api/workflows/{workflow-id}/execute",
+    headers={
+        "Content-Type": "application/json",
+        "x-api-key": os.environ.get("SIM_API_KEY")
+    },
+    json={"input": "Summarize this article"}
+)
+
+print(response.json())
+```
+  </Tab>
+</Tabs>
+
+### Streaming
+
+Stream the response as it's generated. Choose which block outputs to stream using the output selector in the API tab.
+
+{/* TODO: Screenshot of the streaming output selector dropdown */}
+
+<Tabs items={['cURL', 'Python']}>
+  <Tab value="cURL">
+```bash
+curl -X POST https://sim.ai/api/workflows/{workflow-id}/execute \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: $SIM_API_KEY" \
+  -d '{
+    "input": "Write a long essay",
+    "stream": true,
+    "selectedOutputs": ["agent_1.content"]
+  }'
+```
+  </Tab>
+  <Tab value="Python">
+```python
+import requests
+import os
+
+response = requests.post(
+    "https://sim.ai/api/workflows/{workflow-id}/execute",
+    headers={
+        "Content-Type": "application/json",
+        "x-api-key": os.environ.get("SIM_API_KEY")
+    },
+    json={
+        "input": "Write a long essay",
+        "stream": True,
+        "selectedOutputs": ["agent_1.content"]
+    },
+    stream=True
+)
+
+for line in response.iter_lines():
+    if line:
+        print(line.decode())
+```
+  </Tab>
+</Tabs>
+
+### Asynchronous
+
+For long-running workflows, use async mode to start a job and poll for results. Set the `X-Execution-Mode: async` header to submit the workflow and receive a job ID immediately without waiting for completion.
+
+<Tabs items={['Start Job', 'Check Status']}>
+  <Tab value="Start Job">
+```bash
+curl -X POST https://sim.ai/api/workflows/{workflow-id}/execute \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: $SIM_API_KEY" \
+  -H "X-Execution-Mode: async" \
+  -d '{ "input": "Process this large dataset" }'
+```
+
+**Response** (HTTP 202):
+```json
+{
+  "success": true,
+  "async": true,
+  "jobId": "run_abc123",
+  "executionId": "exec_xyz",
+  "message": "Workflow execution queued",
+  "statusUrl": "https://sim.ai/api/jobs/run_abc123"
+}
+```
+  </Tab>
+  <Tab value="Check Status">
+```bash
+curl https://sim.ai/api/jobs/{jobId} \
+  -H "x-api-key: $SIM_API_KEY"
+```
+
+**Response** (while processing):
+```json
+{
+  "success": true,
+  "taskId": "run_abc123",
+  "status": "processing",
+  "metadata": {
+    "createdAt": "2025-09-10T12:00:00.000Z",
+    "startedAt": "2025-09-10T12:00:01.000Z"
+  },
+  "estimatedDuration": 300000
+}
+```
+
+**Response** (when completed):
+```json
+{
+  "success": true,
+  "taskId": "run_abc123",
+  "status": "completed",
+  "metadata": {
+    "createdAt": "2025-09-10T12:00:00.000Z",
+    "startedAt": "2025-09-10T12:00:01.000Z",
+    "completedAt": "2025-09-10T12:00:05.000Z",
+    "duration": 4000
+  },
+  "output": { "result": "..." }
+}
+```
+  </Tab>
+</Tabs>
+
+#### Job Status Values
+
+| Status | Description |
+|--------|-------------|
+| `queued` | Job is waiting to be picked up |
+| `processing` | Workflow is actively executing |
+| `completed` | Finished successfully — `output` field contains the result |
+| `failed` | Execution failed — `error` field contains the message |
+
+Poll the `statusUrl` returned in the initial response until the status is `completed` or `failed`.
+
+#### Execution Time Limits
+
+Async jobs can run significantly longer than synchronous requests:
+
+| Plan | Sync Limit | Async Limit |
+|------|-----------|-------------|
+| **Community** | 5 minutes | 90 minutes |
+| **Pro / Max / Team / Enterprise** | 50 minutes | 90 minutes |
+
+If a job exceeds its time limit, it is automatically marked as `failed`.
+
+#### Job Retention
+
+Completed and failed job results are retained for **24 hours**. After that, the job data is cleaned up and the status endpoint returns `404`. If you need results longer, retrieve and store them on your end after completion.
+
+#### Capacity Limits
+
+If the execution queue is full, the API returns a `503` response with a `Retry-After` header:
+
+```json
+{
+  "error": "Service temporarily at capacity",
+  "retryAfterSeconds": 10
+}
+```
+
+Wait the indicated number of seconds before retrying.
+
+<Callout type="info">
+  Async mode always runs against the deployed version. It does not support draft state, block overrides, or partial execution options like `runFromBlock` or `stopAfterBlockId`.
+</Callout>
+
+## API Key Management
+
+Generate and manage API keys in **Settings → Sim Keys**:
+
+- **Create** new keys for different applications or environments
+- **Revoke** keys that are no longer needed
+- Keys are scoped to your workspace
+
+<Callout type="info">
+  The API tab in the Deploy modal shows a masked version of your key in the code examples. Copy the examples directly — they include the correct authentication header.
+</Callout>
+
+## Rate Limits
+
+API calls are subject to rate limits based on your plan. Rate limit details are returned in response headers (`X-RateLimit-*`) and in the response body. Use async mode for high-volume or long-running workloads.
+
+For detailed rate limit information and the logs/webhooks API, see [External API](/execution/api).
+
+<FAQ items={[
+  { question: "What's the difference between the API tab and the External API docs?", answer: "The API tab in the Deploy modal is for deploying your workflow as a callable endpoint. The External API documentation covers the logs query API and webhook notifications for monitoring executions." },
+  { question: "Can I deploy the same workflow as both an API and a chat?", answer: "Yes. A workflow can be deployed as an API, chat, MCP tool, and more simultaneously. Each deployment type runs against the same active snapshot." },
+  { question: "How do I choose between sync, streaming, and async?", answer: "Use sync for quick workflows (under a few seconds). Use streaming when you want to show progressive output to users. Use async for long-running workflows where you don't want to hold a connection open." },
+  { question: "How long are async job results available?", answer: "Completed and failed job results are retained for 24 hours. After that, the status endpoint returns 404. Retrieve and store results on your end if you need them longer." },
+  { question: "What happens if my API key is compromised?", answer: "Revoke the key immediately in Settings → Sim Keys and create a new one. Revoked keys stop working instantly." },
+]} />
diff --git a/apps/docs/content/docs/en/execution/chat.mdx b/apps/docs/content/docs/en/execution/chat.mdx
new file mode 100644
index 00000000000..c8915010f7b
--- /dev/null
+++ b/apps/docs/content/docs/en/execution/chat.mdx
@@ -0,0 +1,175 @@
+---
+title: Chat Deployment
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+import { FAQ } from '@/components/ui/faq'
+
+Deploy your workflow as a conversational chat interface that users can interact with via a shareable link or embedded widget. Chat supports multi-turn conversations, file uploads, and voice input.
+
+## Overview
+
+Chat deployment wraps your workflow in a real-time conversational UI with:
+- Multi-turn conversations with streaming responses
+- File uploads (up to 15 files per message, 10 MB each)
+- Voice input and text-to-speech output
+- Customizable branding (title, welcome message, logo)
+- Access control (public, password, email, or SSO)
+
+{/* TODO: Screenshot of a deployed chat interface (end-user view) */}
+
+<Callout type="info">
+Chat executions run against your workflow's active deployment snapshot. Publish a new deployment after making canvas changes so the chat uses the updated version.
+</Callout>
+
+## Creating a Chat
+
+1. Open your workflow and click **Deploy**
+2. Select the **Chat** tab
+3. Configure:
+   - **Identifier**: URL slug for the chat (e.g., `support-bot` becomes `sim.ai/chat/support-bot`). Lowercase letters, numbers, and hyphens only.
+   - **Title**: Display name shown in the chat header
+   - **Output Blocks**: Select which block outputs are returned to the user (at least one required)
+   - **Welcome Message**: Greeting shown when the chat loads (default: "Hi there! How can I help you today?")
+   - **Access Control**: Who can access the chat (see below)
+4. Click **Launch**
+
+{/* TODO: Screenshot of the chat deployment configuration panel in the deploy modal */}
+
+## Access Control
+
+| Mode | Description |
+|------|-------------|
+| **Public** | Anyone with the link can chat |
+| **Password** | Users must enter a password before chatting |
+| **Email** | Only verified emails/domains can access. Users receive a 6-digit OTP code via email |
+| **SSO** | OIDC-based single sign-on (enterprise) |
+
+{/* TODO: Screenshot of access control settings (public/password/email whitelist) */}
+
+For email and SSO:
+- Exact email: `user@example.com`
+- Domain pattern: `@example.com` (allows any email from that domain)
+
+## Sharing
+
+### Direct Link
+
+```
+https://sim.ai/chat/your-identifier
+```
+
+### Iframe
+
+```html
+<iframe
+  src="https://sim.ai/chat/your-identifier"
+  width="100%"
+  height="600"
+  frameborder="0"
+  title="Chat"
+></iframe>
+```
+
+## API Submission
+
+Send messages to a chat programmatically. The response is streamed using server-sent events (SSE).
+
+<Tabs items={['cURL', 'TypeScript']}>
+  <Tab value="cURL">
+```bash
+curl -X POST https://sim.ai/api/chat/your-identifier \
+  -H "Content-Type: application/json" \
+  -d '{
+    "input": "Hello, I need help with my order",
+    "conversationId": "optional-conversation-id"
+  }'
+```
+  </Tab>
+  <Tab value="TypeScript">
+```typescript
+const response = await fetch('https://sim.ai/api/chat/your-identifier', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    input: 'Hello, I need help with my order',
+    conversationId: 'optional-conversation-id'
+  })
+});
+
+// Response is an SSE stream
+const reader = response.body?.getReader();
+const decoder = new TextDecoder();
+
+while (true) {
+  const { done, value } = await reader!.read();
+  if (done) break;
+  console.log(decoder.decode(value));
+}
+```
+  </Tab>
+</Tabs>
+
+### With File Uploads
+
+```bash
+curl -X POST https://sim.ai/api/chat/your-identifier \
+  -H "Content-Type: application/json" \
+  -d '{
+    "input": "What does this document say?",
+    "files": [{
+      "name": "report.pdf",
+      "type": "application/pdf",
+      "size": 1048576,
+      "data": "data:application/pdf;base64,..."
+    }]
+  }'
+```
+
+### Protected Chats
+
+For password-protected chats:
+```bash
+curl -X POST https://sim.ai/api/chat/your-identifier \
+  -H "Content-Type: application/json" \
+  -d '{ "password": "secret", "input": "Hello" }'
+```
+
+For email-protected chats, authenticate first with OTP:
+```bash
+# Step 1: Request OTP
+curl -X POST https://sim.ai/api/chat/your-identifier/otp \
+  -H "Content-Type: application/json" \
+  -d '{ "email": "allowed@example.com" }'
+
+# Step 2: Verify OTP (save the Set-Cookie header to a cookie jar)
+curl -X PUT https://sim.ai/api/chat/your-identifier/otp \
+  -H "Content-Type: application/json" \
+  -c cookies.txt \
+  -d '{ "email": "allowed@example.com", "otp": "123456" }'
+
+# Step 3: Send messages (replay the auth cookie from step 2)
+curl -X POST https://sim.ai/api/chat/your-identifier \
+  -H "Content-Type: application/json" \
+  -b cookies.txt \
+  -d '{ "input": "Hello" }'
+```
+
+## Troubleshooting
+
+**Chat returns 403** - The deployment is inactive. Re-deploy the workflow.
+
+**"At least one output block is required"** - Select at least one block output in the Output Blocks configuration.
+
+**OTP email not arriving** - Check the email address is correct and check spam folders. OTP codes expire and can be resent after a 30-second cooldown.
+
+**Chat not loading in iframe** - Check your site's Content Security Policy allows iframes from `sim.ai`.
+
+<FAQ items={[
+  { question: "How is chat different from form deployment?", answer: "Forms collect structured input in a single submission and trigger one workflow execution. Chats support multi-turn conversations with streaming responses, file uploads, and voice input. Each message in a chat triggers a new workflow execution with the conversation context." },
+  { question: "Can I customize the chat appearance?", answer: "Yes. You can set a custom title, welcome message, and logo image. The chat inherits your brand color for the primary accent." },
+  { question: "Is there a message length limit?", answer: "There is no hard limit on message length. However, very long messages may impact response time depending on your workflow's AI model context window." },
+  { question: "Can I use chat with any workflow?", answer: "Yes, any workflow can be deployed as a chat. The chat sends the user's message as input and returns the selected block outputs as the response. Workflows with Agent blocks work particularly well since they're designed for conversational interaction." },
+  { question: "What happens if I update my workflow after deploying?", answer: "Chat executions run against the active deployment snapshot. To use updated workflow logic, you need to publish a new deployment from the Deploy modal." },
+]} />
diff --git a/apps/docs/content/docs/en/execution/costs.mdx b/apps/docs/content/docs/en/execution/costs.mdx
index a069c541415..944814817ce 100644
--- a/apps/docs/content/docs/en/execution/costs.mdx
+++ b/apps/docs/content/docs/en/execution/costs.mdx
@@ -452,6 +452,21 @@ curl -X GET -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" htt
 - `limit` is derived from individual limits (Free/Pro/Max) or pooled organization limits (Team/Enterprise)
 - `plan` is the highest-priority active plan associated with your user
 
+## Purchasing Additional Credits
+
+Pro and Team plan users can buy additional credits at any time in **Settings → Subscription → Credit Balance**:
+
+- **Range**: $10 to $1,000 per purchase
+- **Conversion**: 1 credit = $0.005 (a $10 purchase adds 2,000 credits)
+- **Availability**: Credits are added immediately after payment
+- **Expiration**: Purchased credits do not expire
+- **Refunds**: Purchases are non-refundable
+- **Team plans**: Only organization owners and admins can purchase credits. Purchased credits are added to the team's shared pool.
+
+<Callout type="info">
+  Enterprise users should contact support for credit adjustments.
+</Callout>
+
 ## Cost Optimization Strategies
 
 - **Model Selection**: Choose models based on task complexity. Simple tasks can use GPT-4.1-nano while complex reasoning might need o1 or Claude Opus.
diff --git a/apps/docs/content/docs/en/execution/index.mdx b/apps/docs/content/docs/en/execution/index.mdx
index cc80425ecfb..c6f07931afa 100644
--- a/apps/docs/content/docs/en/execution/index.mdx
+++ b/apps/docs/content/docs/en/execution/index.mdx
@@ -32,6 +32,15 @@ Sim's execution engine brings your workflows to life by processing blocks in the
   <Card title="External API" href="/execution/api">
     Access execution logs and set up webhooks programmatically via REST API
   </Card>
+
+  <Card title="API Deployment" href="/execution/api-deployment">
+    Deploy your workflow as a REST API endpoint with sync, streaming, and async modes
+  </Card>
+
+  <Card title="Chat Deployment" href="/execution/chat">
+    Deploy your workflow as a conversational chat interface with streaming, file uploads, and voice
+  </Card>
+
 </Cards>
 
 ## Key Concepts
@@ -56,19 +65,37 @@ Each workflow maintains a rich context during execution containing:
 
 ## Deployment Snapshots
 
-API, Chat, Schedule, and Webhook executions run against the workflow’s active deployment snapshot. Manual runs from the editor execute the current draft canvas state, letting you test changes before deploying. Publish a new deployment whenever you change the canvas so every trigger uses the updated version.
+API, Chat, Schedule, and Webhook executions run against the workflow's active deployment snapshot. Manual runs from the editor execute the current draft canvas state, letting you test changes before deploying. Publish a new deployment whenever you change the canvas so every trigger uses the updated version.
 
-<div className='flex justify-center my-6'>
+<div className="flex justify-center my-6">
   <Image
-    src='/static/execution/deployment-versions.png'
-    alt='Deployment versions table'
+    src="/static/execution/deployment-versions.png"
+    alt="Deployment versions table"
     width={500}
     height={280}
-    className='rounded-xl border border-border shadow-sm'
+    className="rounded-xl border border-border shadow-sm"
   />
 </div>
 
-The Deploy modal keeps a full version history—inspect any snapshot, compare it against your draft, and promote or roll back with one click when you need to restore a prior release.
+### Version History
+
+The **General** tab in the Deploy modal shows a version history table for every deployment. Each row shows the version name, who deployed it, and when.
+
+{/* TODO: Screenshot of the version history table with multiple versions */}
+
+From the version table you can:
+
+- **Rename** a version to give it a meaningful label (e.g., "v2 — added error handling")
+- **Add a description** with notes about what changed in that deployment
+- **Promote to live** to roll back to an older version — this makes the selected version the active deployment without changing your draft canvas
+- **Load into editor** to restore a previous version's workflow into the canvas for editing and redeploying
+- **Preview a version** by selecting a row, then toggle between viewing the live deployment and the selected version in the canvas
+
+{/* TODO: Screenshot of the version preview toggle (live vs selected) */}
+
+<Callout type="info">
+  Promoting an old version takes effect immediately — all API, Chat, Schedule, and Webhook executions will use the promoted version. Your draft canvas is not affected.
+</Callout>
 
 ## Programmatic Execution
 
diff --git a/apps/docs/content/docs/en/execution/meta.json b/apps/docs/content/docs/en/execution/meta.json
index fd2124b9dd4..9092f40f161 100644
--- a/apps/docs/content/docs/en/execution/meta.json
+++ b/apps/docs/content/docs/en/execution/meta.json
@@ -1,3 +1,3 @@
 {
-  "pages": ["index", "basics", "files", "api", "logging", "costs"]
+  "pages": ["index", "basics", "files", "api", "api-deployment", "chat", "logging", "costs"]
 }
diff --git a/apps/docs/content/docs/en/knowledgebase/connectors.mdx b/apps/docs/content/docs/en/knowledgebase/connectors.mdx
index c6573ed5505..b4f0953338d 100644
--- a/apps/docs/content/docs/en/knowledgebase/connectors.mdx
+++ b/apps/docs/content/docs/en/knowledgebase/connectors.mdx
@@ -43,7 +43,13 @@ Open a knowledge base and click **Add Connector**. You'll see the full list of a
 
 Most connectors use **OAuth** — select an existing credential from the dropdown, or click **Connect new account** to authorize through the service's login flow. Tokens are refreshed automatically, so you won't need to re-authenticate unless you revoke access.
 
-A few connectors (Evernote, Obsidian, Fireflies) use **API keys** instead. Paste your key or developer token directly, and it will be stored securely.
+A few connectors use **API keys** instead of OAuth. Paste your key or developer token directly, and it will be stored securely.
+
+| Connector | Credential | Where to find it |
+|-----------|-----------|-----------------|
+| **Evernote** | Developer Token (starts with `S=`) | [Evernote Developer Tokens](https://dev.evernote.com/doc/articles/dev_tokens.php) — request a developer token from your account settings |
+| **Obsidian** | API Key | Install the [Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api) community plugin in Obsidian, then copy the API key from the plugin settings |
+| **Fireflies** | API Key | Generate an API key from the Integrations page in your Fireflies account settings |
 
 <Callout type="info">
   If you rotate an API key in the external service, you'll need to update it in Sim as well. OAuth tokens are refreshed automatically, but API keys are not.
@@ -59,7 +65,8 @@ Each connector has its own configuration fields that control what gets synced. S
 - **Notion**: Choose between syncing an entire workspace, a specific database, or a single page tree
 - **GitHub**: Specify a repository, branch, and optional file extension filter
 - **Confluence**: Enter your Atlassian domain and optionally filter by space key or content type
-- **Obsidian**: Provide your vault URL and optionally restrict to a folder path
+- **Obsidian**: Provide your vault URL (default: `https://127.0.0.1:27124`) and optionally restrict to a folder path
+- **Fireflies**: Optionally filter by host email or limit the number of transcripts synced
 
 All configuration is validated when you save — if a repository doesn't exist or a domain is unreachable, you'll get an immediate error.
 
@@ -137,6 +144,37 @@ You can add multiple connectors to a single knowledge base. For example, you mig
 
 Each connector manages its own documents independently. Metadata tag slots are shared across the knowledge base, so keep an eye on slot usage if you're combining several connectors that each populate tags.
 
+## PDF Processing and OCR
+
+When connectors sync PDF files, Sim can use OCR (Optical Character Recognition) to extract text from scanned documents, images within PDFs, and complex layouts that standard text extraction would miss.
+
+### OCR Providers
+
+Sim supports two OCR providers. If neither is configured, PDFs fall back to a basic text parser.
+
+| Provider | Setup | Notes |
+|----------|-------|-------|
+| **Mistral OCR** | Set `MISTRAL_API_KEY` environment variable, or add a Mistral key via workspace BYOK settings | Splits large PDFs (1,000+ pages) into chunks and processes them concurrently |
+| **Azure Mistral OCR** | Set `OCR_AZURE_ENDPOINT`, `OCR_AZURE_API_KEY`, and `OCR_AZURE_MODEL_NAME` environment variables | Same 1,000-page chunking behavior as Mistral OCR |
+
+<Callout type="info">
+  OCR is automatic — if the environment variables are configured, PDF processing uses OCR. No per-connector toggle is needed.
+</Callout>
+
+### Self-Hosted OCR Setup
+
+If you're self-hosting Sim, add the relevant environment variables to your `.env` file:
+
+```bash
+# Option 1: Mistral OCR
+MISTRAL_API_KEY=your-mistral-api-key
+
+# Option 2: Azure Mistral OCR
+OCR_AZURE_ENDPOINT=https://your-azure-endpoint.openai.azure.com
+OCR_AZURE_API_KEY=your-azure-api-key
+OCR_AZURE_MODEL_NAME=your-model-name
+```
+
 ## Common Use Cases
 
 - **Internal knowledge base**: Sync your team's Notion workspace and Confluence spaces so AI agents can answer questions about internal processes, policies, and documentation
diff --git a/apps/docs/content/docs/en/knowledgebase/tags.mdx b/apps/docs/content/docs/en/knowledgebase/tags.mdx
index 47b64b58b19..cd4ecfad1fe 100644
--- a/apps/docs/content/docs/en/knowledgebase/tags.mdx
+++ b/apps/docs/content/docs/en/knowledgebase/tags.mdx
@@ -2,6 +2,7 @@
 title: Tags and Filtering
 ---
 
+import { Callout } from 'fumadocs-ui/components/callout'
 import { Video } from '@/components/ui/video'
 import { FAQ } from '@/components/ui/faq'
 
@@ -15,15 +16,37 @@ You can add custom tags to any document in your knowledgebase to organize and ca
   <Video src="knowledgebase-tag.mp4" width={700} height={450} />
 </div>
 
-### Tag Management
-- **Custom tags**: Create your own tag system that fits your workflow
-- **Multiple tags per document**: Apply as many tags as needed to each document. Each knowledgebase has 17 tag slots total: 7 text, 5 number, 2 date, and 3 boolean slots, shared by all documents in the knowledgebase
-- **Tag organization**: Group related documents with consistent tagging
+### Tag Slots and Field Types
+
+Each knowledge base has **17 tag slots** shared across all documents. Slots are organized by field type:
+
+| Field Type | Slots | Accepted Values | Example |
+|-----------|-------|----------------|---------|
+| **Text** | 7 slots | Any string (case-insensitive matching) | `category: "engineering"` |
+| **Number** | 5 slots | Any valid number | `priority: 3` |
+| **Date** | 2 slots | `YYYY-MM-DD` format | `published: 2025-06-15` |
+| **Boolean** | 3 slots | `true` or `false` | `reviewed: true` |
+
+<Callout type="info">
+  Tag slots are shared across all documents and connectors in a knowledge base. If a connector auto-populates 3 text tags, you have 4 text slots remaining for manual tags or other connectors.
+</Callout>
+
+### Creating Tags
+
+Tags are defined at the knowledge base level — you create a tag definition (e.g., "Department" of type text), and then set values on individual documents. To create a tag:
+
+1. Open a knowledge base and select a document
+2. Click **Add Tag** in the document detail panel
+3. Choose a field type and enter a display name
+4. Set the tag value for that document
+
+Once a tag definition exists, you can set its value on any document in the knowledge base. Connectors can also auto-populate tags with metadata from the source (see [Connectors](/knowledgebase/connectors)).
 
 ### Tag Best Practices
 - **Consistent naming**: Use standardized tag names across your documents
 - **Descriptive tags**: Use clear, meaningful tag names
-- **Regular cleanup**: Remove unused or outdated tags periodically
+- **Plan for connectors**: If you use connectors that auto-populate tags, leave enough slots for manual tags
+- **Regular cleanup**: Remove unused or outdated tags periodically — unused tag definitions can be cleaned up to free slots
 
 ## Using Tags in Knowledge Blocks
 
@@ -66,10 +89,17 @@ When you **provide both tags and a search query**:
 ### Search Configuration
 
 #### Tag Filtering
-- **Multiple tags**: Use multiple tags with AND or OR logic to control whether documents must match all or any of the specified tags
-- **Tag combinations**: Mix different tag types for precise filtering
-- **Case sensitivity**: Tag matching is case-insensitive
-- **Partial matching**: Text fields support partial matching operators such as contains, starts_with, and ends_with in addition to exact matching
+
+Configure tag filters in the Knowledge block to narrow results before vector search runs:
+
+- **AND / OR logic**: Control whether documents must match all tags (AND) or any tag (OR)
+- **Case-insensitive**: Tag matching ignores capitalization
+- **Text operators**: `equals`, `not equals`, `contains`, `does not contain`, `starts with`, `ends with`
+- **Number operators**: `equals`, `not equals`, `greater than`, `greater than or equal`, `less than`, `less than or equal`, `between`
+- **Date operators**: `equals`, `after`, `on or after`, `before`, `on or before`, `between`
+- **Boolean operators**: `is` / `is not`
+
+Mix different field types freely — for example, filter by `department = "engineering"` AND `priority >= 3` AND `reviewed = true`.
 
 #### Vector Search Parameters
 - **Query complexity**: Natural language questions work best
diff --git a/apps/docs/content/docs/en/mcp/deploy-workflows.mdx b/apps/docs/content/docs/en/mcp/deploy-workflows.mdx
index 1c031197ebb..2f2a78420bc 100644
--- a/apps/docs/content/docs/en/mcp/deploy-workflows.mdx
+++ b/apps/docs/content/docs/en/mcp/deploy-workflows.mdx
@@ -17,11 +17,14 @@ MCP servers group your workflow tools together. Create and manage them in worksp
   <Video src="mcp/mcp-server.mp4" width={700} height={450} />
 </div>
 
-1. Navigate to **Settings → MCP Servers**
+1. Navigate to **Settings → Workflow MCP Servers**
 2. Click **Create Server**
 3. Enter a name and optional description
-4. Copy the server URL for use in your MCP clients
-5. View and manage all tools added to the server
+4. Choose access: **API Key** (private, requires `X-API-Key` header) or **Public** (no authentication)
+5. Optionally select deployed workflows to add as tools immediately
+6. Copy the server URL for use in your MCP clients
+
+{/* TODO: Screenshot of the Workflow MCP Servers settings page */}
 
 ## Adding a Workflow as a Tool
 
@@ -54,9 +57,35 @@ Your workflow's input format fields become tool parameters. Add descriptions to
 
 ## Connecting MCP Clients
 
-Use the server URL from settings to connect external applications:
+The server detail page generates ready-to-use configuration snippets for each supported client. Select your client to see the exact config.
+
+### Cursor
+
+Cursor supports direct URL configuration. Add to your Cursor MCP settings (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "my-sim-workflows": {
+      "url": "YOUR_SERVER_URL",
+      "headers": { "X-API-Key": "$SIM_API_KEY" }
+    }
+  }
+}
+```
+
+Cursor also provides a one-click install button in the server detail view.
+
+### Claude Code
+
+Run this command in your terminal:
+
+```bash
+claude mcp add "my-sim-workflows" --url "YOUR_SERVER_URL" --header "X-API-Key:$SIM_API_KEY"
+```
 
 ### Claude Desktop
+
 Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
 
 ```json
@@ -64,22 +93,38 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
   "mcpServers": {
     "my-sim-workflows": {
       "command": "npx",
-      "args": ["-y", "mcp-remote", "YOUR_SERVER_URL"]
+      "args": ["-y", "mcp-remote", "YOUR_SERVER_URL", "--header", "X-API-Key:$SIM_API_KEY"]
     }
   }
 }
 ```
 
-### Cursor
-Add the server URL in Cursor's MCP settings using the same mcp-remote pattern.
+### VS Code
+
+Add to your VS Code MCP settings (`.vscode/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "my-sim-workflows": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "YOUR_SERVER_URL", "--header", "X-API-Key:$SIM_API_KEY"]
+    }
+  }
+}
+```
+
+<Callout type="info">
+  For public servers, omit the `X-API-Key` header and `--header` arguments. Public servers don't require authentication.
+</Callout>
 
 <Callout type="warn">
-Include your API key header (`X-API-Key`) for authenticated access when using mcp-remote or other HTTP-based MCP transports.
+  `$SIM_API_KEY` is a placeholder. For Claude Desktop and VS Code configs, replace it with your actual API key since these clients don't expand environment variables in JSON config files. Claude Code and Cursor handle variable expansion natively.
 </Callout>
 
 ## Server Management
 
-From the server detail view in **Settings → MCP Servers**, you can:
+From the server detail view in **Settings → Workflow MCP Servers**, you can:
 
 - **View tools**: See all workflows added to a server
 - **Copy URL**: Get the server URL for MCP clients
diff --git a/apps/docs/content/docs/en/mcp/index.mdx b/apps/docs/content/docs/en/mcp/index.mdx
index 4e966165dc5..15a37887c0b 100644
--- a/apps/docs/content/docs/en/mcp/index.mdx
+++ b/apps/docs/content/docs/en/mcp/index.mdx
@@ -26,19 +26,49 @@ MCP servers provide collections of tools that your agents can use. Configure the
   <Video src="mcp/settings-mcp-tools.mp4" width={700} height={450} />
 </div>
 
-1. Navigate to your workspace settings
-2. Go to the **MCP Servers** section
-3. Click **Add MCP Server**
-4. Enter the server configuration details
-5. Save the configuration
+1. Navigate to **Settings → MCP Servers**
+2. Click **Add MCP Server**
+3. Enter the server name and URL
+4. Add any required headers (e.g., authentication tokens)
+5. Click **Test Connection** to verify the server is reachable
+6. Save the configuration
 
 <Callout type="info">
 You can also configure MCP servers directly from the toolbar in an Agent block for quick setup.
 </Callout>
 
-### Refresh Tools
+### Server Configuration Options
 
-Click **Refresh** on a server to fetch the latest tool schemas and automatically update any agent blocks using those tools with the new parameter definitions.
+| Field | Description |
+|-------|-------------|
+| **Name** | Display name for the server |
+| **URL** | The MCP server endpoint |
+| **Transport** | Currently supports `streamable-http` |
+| **Headers** | Key-value pairs for authentication or custom headers |
+| **Timeout** | Connection timeout in milliseconds (default: 30,000) |
+
+### Environment Variables in Configuration
+
+Server URLs and headers support environment variable substitution using `{{VAR_NAME}}` syntax. This keeps sensitive values like API keys out of the server configuration.
+
+```
+URL: https://api.example.com/mcp
+Authorization: Bearer {{MCP_API_TOKEN}}
+```
+
+When you type `{{` in the URL or header fields, a dropdown appears showing available workspace environment variables.
+
+### Testing and Validation
+
+Click **Test Connection** before saving to verify the server is reachable and discover available tools. The test response shows the number of tools found and the protocol version.
+
+After saving, each server displays its available tools with parameter names, types, and required flags. If a server's tools change (e.g., after a server update), click **Refresh** to fetch the latest schemas. This automatically updates any agent blocks using those tools.
+
+Tool validation badges appear on servers with issues — for example, if a tool was removed from the server but is still referenced in a workflow. Click the badge to see which workflows are affected.
+
+### Domain Allowlisting
+
+Self-hosted deployments can restrict which MCP server domains are allowed by setting the `ALLOWED_MCP_DOMAINS` environment variable (comma-separated list). When set, only servers on approved domains can be added. When unset, all domains are allowed.
 
 ## Using MCP Tools in Agents
 
diff --git a/apps/docs/content/docs/en/tools/custom-tools.mdx b/apps/docs/content/docs/en/tools/custom-tools.mdx
new file mode 100644
index 00000000000..6261af27a80
--- /dev/null
+++ b/apps/docs/content/docs/en/tools/custom-tools.mdx
@@ -0,0 +1,162 @@
+---
+title: Custom Tools
+description: Create your own tools with JavaScript code and use them in Agent blocks
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Step, Steps } from 'fumadocs-ui/components/steps'
+import { FAQ } from '@/components/ui/faq'
+
+Custom tools let you write your own JavaScript functions and make them available as callable tools in Agent blocks. This is useful when you need functionality that isn't covered by Sim's built-in integrations — for example, calling an internal API, performing a custom calculation, or transforming data in a specific way.
+
+## How Custom Tools Work
+
+A custom tool has two parts:
+
+1. **Schema** — A JSON definition describing the tool's name, description, and parameters (using the OpenAI function-calling format). This tells the AI agent what the tool does and what inputs it expects.
+2. **Code** — A JavaScript function body that runs when the agent calls the tool. Parameters defined in the schema are available as variables in your code.
+
+When an Agent block has access to a custom tool, the AI model decides when to call it based on the schema description and the conversation context — just like built-in tools.
+
+## Creating a Custom Tool
+
+<Steps>
+<Step>
+
+### Open Custom Tools settings
+
+Navigate to **Settings → Custom Tools** in your workspace and click **Add**.
+
+</Step>
+<Step>
+
+### Define the schema
+
+In the **Schema** tab, define your tool using JSON in the OpenAI function-calling format:
+
+```json
+{
+  "type": "function",
+  "function": {
+    "name": "get_weather",
+    "description": "Get the current weather for a city",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "city": {
+          "type": "string",
+          "description": "The city name"
+        },
+        "units": {
+          "type": "string",
+          "enum": ["celsius", "fahrenheit"],
+          "description": "Temperature units"
+        }
+      },
+      "required": ["city"]
+    }
+  }
+}
+```
+
+<Callout type="info">
+  You can use the AI wand button to generate a schema from a natural language description of what the tool should do.
+</Callout>
+
+</Step>
+<Step>
+
+### Write the code
+
+Switch to the **Code** tab and write the JavaScript function body. Parameters from your schema are available directly as variables:
+
+```javascript
+const response = await fetch(
+  `https://api.openweathermap.org/data/2.5/weather?q=${city}&units=${units === 'celsius' ? 'metric' : 'imperial'}&appid={{OPENWEATHER_API_KEY}}`
+);
+
+const data = await response.json();
+
+return {
+  temperature: data.main.temp,
+  description: data.weather[0].description,
+  humidity: data.main.humidity
+};
+```
+
+<Callout type="info">
+  You can also use the AI wand to generate code from a description. Environment variables are referenced with `&#123;&#123;KEY&#125;&#125;` syntax.
+</Callout>
+
+</Step>
+<Step>
+
+### Save
+
+Click **Save** to create the tool. It's now available to use in any Agent block across your workspace.
+
+</Step>
+</Steps>
+
+## Using Custom Tools in Workflows
+
+Once created, custom tools appear alongside built-in tools when configuring an Agent block:
+
+1. Open an Agent block
+2. Click **Add Tools**
+3. Find your custom tool in the tool list
+4. The agent will call the tool when it determines it's relevant to the task
+
+## Code Environment
+
+### Available Features
+
+- **Async/await** — Your code runs in an async context, so you can use `await` directly
+- **fetch()** — Make HTTP requests to external APIs
+- **Node.js built-ins** — Access to `crypto`, `Buffer`, and other standard modules
+- **Environment variables** — Use `{{KEY}}` syntax to inject secrets
+
+### Limitations
+
+- **No npm packages** — External libraries like `axios` or `lodash` are not available. Use built-in APIs instead
+- **Parameters by name** — Schema parameters are available directly as variables (e.g., `city`), not via a `params` object
+
+### Returning Results
+
+Return a value from your code to send it back to the agent:
+
+```javascript
+const result = await fetch(`https://api.example.com/data?q=${query}`);
+const data = await result.json();
+return data;
+```
+
+The returned value becomes the tool output that the agent sees and can use in its response.
+
+## Managing Custom Tools
+
+From **Settings → Custom Tools** you can:
+
+- **Search** tools by name, function name, or description
+- **Edit** any tool's schema or code
+- **Delete** tools that are no longer needed
+
+<Callout type="warn">
+  Deleting a custom tool removes it from all Agent blocks that reference it. Make sure no active workflows depend on the tool before deleting.
+</Callout>
+
+## Permissions
+
+| Action | Required Permission |
+|--------|-------------------|
+| View custom tools | **Read**, **Write**, or **Admin** |
+| Create or edit tools | **Write** or **Admin** |
+| Delete tools | **Write** or **Admin** |
+
+<FAQ items={[
+  { question: "Can I use custom tools in standalone blocks (not agents)?", answer: "No. Custom tools are designed for use within Agent blocks, where the AI model decides when to call them. For deterministic tool execution, use the Function block instead." },
+  { question: "How do I pass API keys to my custom tool code?", answer: "Use environment variables with double curly brace syntax: {{MY_API_KEY}}. Create the environment variable in Settings → Secrets, and it will be injected at execution time without appearing in logs." },
+  { question: "Can I use external npm packages?", answer: "No. Custom tool code runs in a sandboxed environment with access to built-in Node.js modules and fetch(), but not external packages. For complex dependencies, consider calling an external API that wraps the functionality you need." },
+  { question: "What's the difference between custom tools and the Function block?", answer: "Custom tools are called by AI agents when they decide the tool is relevant — the agent chooses when to use it. Function blocks run deterministically at a fixed point in the workflow. Use custom tools for agent-driven actions and Function blocks for predictable data transformations." },
+  { question: "Are custom tools shared across the workspace?", answer: "Yes. Custom tools are workspace-scoped, so all workspace members can use them in their workflows." },
+]} />
diff --git a/apps/docs/content/docs/en/tools/meta.json b/apps/docs/content/docs/en/tools/meta.json
index 2a8e6ba0c89..c19088bce08 100644
--- a/apps/docs/content/docs/en/tools/meta.json
+++ b/apps/docs/content/docs/en/tools/meta.json
@@ -1,6 +1,7 @@
 {
   "pages": [
     "index",
+    "custom-tools",
     "a2a",
     "agentmail",
     "ahrefs",
diff --git a/apps/docs/content/docs/en/variables/index.mdx b/apps/docs/content/docs/en/variables/index.mdx
new file mode 100644
index 00000000000..0596e08a75c
--- /dev/null
+++ b/apps/docs/content/docs/en/variables/index.mdx
@@ -0,0 +1,90 @@
+---
+title: Variables
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Card, Cards } from 'fumadocs-ui/components/card'
+import { FAQ } from '@/components/ui/faq'
+
+Sim has two systems for injecting dynamic values into your workflows: **workflow variables** for in-run state and **environment variables** for secrets and configuration.
+
+## Variable Syntax at a Glance
+
+| Syntax | What it references | Example |
+|--------|-------------------|---------|
+| `<variable.name>` | Workflow variable | `<variable.counter>` |
+| `<variable.obj.prop>` | Nested property | `<variable.config.retryCount>` |
+| `<blockname.field>` | Block output | `<agent.content>` |
+| `<loop.index>` | Loop iteration (inside loop) | `<loop.currentItem>` |
+| `<parallel.index>` | Parallel instance (inside parallel) | `<parallel.currentItem>` |
+| `{{KEY}}` | Environment variable | `{{OPENAI_API_KEY}}` |
+
+Type `<` in any block text field to open the variable picker and browse available references.
+
+## Workflow Variables
+
+Workflow variables are a global store that any block can read or update during execution. They're defined in the **Variables** panel in the sidebar and support text, numbers, booleans, objects, and arrays.
+
+Key behaviors:
+- **Global scope**: Accessible from any block in the workflow
+- **Run-scoped persistence**: Changes during a run are visible to subsequent blocks, but each new execution resets variables to their initial values
+- **Nested access**: Use dot notation for object properties (`<variable.config.timeout>`)
+- **Updated via the Variables block**: Use the [Variables block](/blocks/variables) to modify variable values mid-workflow
+
+<Card title="Workflow Variables" href="/variables/workflow-variables">
+  Full guide on creating, accessing, and updating workflow variables
+</Card>
+
+## Environment Variables
+
+Environment variables store sensitive values like API keys, tokens, and configuration that should never appear in logs or be visible in the workflow canvas.
+
+### Creating Environment Variables
+
+1. Go to **Settings** in your workspace
+2. Open the **Secrets** tab
+3. Click **Add** and enter a key-value pair
+
+### Personal vs. Workspace
+
+| Scope | Visibility | Use case |
+|-------|-----------|----------|
+| **Workspace** | All workspace members | Shared API keys, team configuration |
+| **Personal** | Only you | Your personal tokens, dev credentials |
+
+When both a workspace and personal variable share the same key, the workspace value takes precedence.
+
+### Using Environment Variables
+
+Reference them with double curly braces in any block field:
+
+```
+{{API_KEY}}
+```
+
+<Callout type="info">
+  Environment variable names must start with a letter or underscore and contain only letters, numbers, and underscores (e.g., `MY_API_KEY`).
+</Callout>
+
+### Environment Variables vs. Credentials
+
+| | Environment Variables | Credentials |
+|--|----------------------|-------------|
+| **Format** | Key-value string pairs | OAuth tokens, API keys with provider context |
+| **Syntax** | `{{KEY}}` | Selected via dropdown in block config |
+| **Best for** | Custom API keys, configuration values, feature flags | OAuth services (Slack, GitHub, Google), managed connections |
+| **Management** | Settings → Secrets | Settings → Credentials |
+
+Use environment variables when you have a raw API key or config value. Use [credentials](/credentials) when connecting to a service that needs OAuth or managed token refresh.
+
+## Name Conflicts
+
+If a workflow variable and a block output share the same name, Sim resolves the reference in a fixed priority order: loop and parallel context first, then workflow variables, then environment variables, then block outputs. To avoid confusion, use distinct names for your variables and blocks.
+
+<FAQ items={[
+  { question: "What's the difference between workflow variables and environment variables?", answer: "Workflow variables store runtime data (text, numbers, objects, arrays) that blocks can read and modify during execution. They use <variable.name> syntax. Environment variables store sensitive configuration like API keys using {{KEY}} syntax. They never appear in logs and are managed at the workspace or personal level." },
+  { question: "Can I use environment variables in the Function block?", answer: "Yes. Use the double curly brace syntax {{KEY}} directly in your code. The value is substituted before execution, so the actual secret never appears in logs or outputs." },
+  { question: "How do I share an API key with my team?", answer: "Create a workspace-scoped environment variable in Settings → Secrets. All workspace members will be able to use it in their workflows via {{KEY}} syntax." },
+  { question: "What happens if a variable name has spaces or mixed case?", answer: "Variable resolution is case-insensitive and ignores spaces. A variable named 'My Counter' can be referenced as <variable.mycounter> or <variable.My Counter>. However, using consistent naming (like camelCase) is recommended." },
+  { question: "Can I reference environment variables in the Agent system prompt?", answer: "Yes. You can use {{KEY}} syntax in any text field, including system prompts, to inject environment variable values." },
+]} />
diff --git a/apps/docs/content/docs/en/variables/meta.json b/apps/docs/content/docs/en/variables/meta.json
new file mode 100644
index 00000000000..00b2a1dc9e0
--- /dev/null
+++ b/apps/docs/content/docs/en/variables/meta.json
@@ -0,0 +1,5 @@
+{
+  "title": "Variables",
+  "pages": ["index", "workflow-variables"],
+  "defaultOpen": false
+}