feat(docs): added connections + execution docs

docs/content/docs/connections/accessing-data.mdx

@@ -0,0 +1,191 @@
+---
+title: Accessing Connected Data
+description: Techniques for accessing and manipulating data from connected blocks
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Files, Folder, File } from 'fumadocs-ui/components/files'
+
+## Accessing Connected Data
+
+Once blocks are connected, you can access data from source blocks in destination blocks using connection tags and various data access techniques.
+
+## Basic Data Access
+
+The simplest way to access data is through direct references using connection tags:
+
+<Files>
+  <File name="Simple Property" annotation="<block.content>" />
+  <File name="Nested Property" annotation="<block.tokens.total>" />
+  <File name="Array Element" annotation="<block.items[0].name>" />
+  <File name="Complex Path" annotation="<block.data.users[2].profile.email>" />
+</Files>
+
+## Advanced Data Access Techniques
+
+### Array Access
+
+You can access array elements using square bracket notation:
+
+```javascript
+// Access the first item in an array
+<block.items[0]>
+
+// Access a specific property of an array item
+<block.items[2].name>
+
+// Access the last item in an array (in Function blocks)
+const items = input.block.items;
+const lastItem = items[items.length - 1];
+```
+
+### Object Property Access
+
+Access object properties using dot notation:
+
+```javascript
+// Access a simple property
+<block.content>
+
+// Access a nested property
+<block.data.user.profile.name>
+
+// Access a property with special characters (in Function blocks)
+const data = input.block.data;
+const specialProp = data['property-with-dashes'];
+```
+
+### Dynamic References
+
+Connection references are evaluated at runtime, allowing for dynamic data flow through your workflow:
+
+```javascript
+// In a Function block, you can access connected data
+const userName = input.userBlock.name;
+const orderTotal = input.apiBlock.body.order.total;
+
+// Process the data
+const discount = orderTotal > 100 ? 0.1 : 0;
+const finalPrice = orderTotal * (1 - discount);
+
+// Return the result
+return {
+  userName,
+  originalTotal: orderTotal,
+  discount: discount * 100 + '%',
+  finalPrice
+};
+```
+
+## Data Transformation
+
+### Using Function Blocks
+
+Function blocks are the most powerful way to transform data between connections:
+
+```javascript
+// Example: Transform API response data
+const apiResponse = input.apiBlock.data;
+const transformedData = {
+  users: apiResponse.results.map(user => ({
+    id: user.id,
+    fullName: `${user.firstName} ${user.lastName}`,
+    email: user.email.toLowerCase(),
+    isActive: user.status === 'active'
+  })),
+  totalCount: apiResponse.count,
+  timestamp: new Date().toISOString()
+};
+
+return transformedData;
+```
+
+### String Interpolation
+
+You can combine connection tags with static text:
+
+```
+Hello, <userBlock.name>! Your order #<orderBlock.id> has been processed.
+```
+
+### Conditional Content
+
+In Function blocks, you can create conditional content based on connected data:
+
+```javascript
+const user = input.userBlock;
+const orderTotal = input.orderBlock.total;
+
+let message = `Thank you for your order, ${user.name}!`;
+
+if (orderTotal > 100) {
+  message += " You've qualified for free shipping!";
+} else {
+  message += ` Add $${(100 - orderTotal).toFixed(2)} more to qualify for free shipping.`;
+}
+
+return { message };
+```
+
+## Handling Missing Data
+
+It's important to handle cases where connected data might be missing or null:
+
+<Callout type="warning">
+  Always validate connected data before using it, especially when accessing nested properties or array elements.
+</Callout>
+
+### Default Values
+
+In Function blocks, you can provide default values for missing data:
+
+```javascript
+const userName = input.userBlock?.name || 'Guest';
+const items = input.orderBlock?.items || [];
+const total = input.orderBlock?.total ?? 0;
+```
+
+### Conditional Checks
+
+Check if data exists before accessing nested properties:
+
+```javascript
+let userEmail = 'No email provided';
+if (input.userBlock && input.userBlock.contact && input.userBlock.contact.email) {
+  userEmail = input.userBlock.contact.email;
+}
+```
+
+### Optional Chaining
+
+In Function blocks, use optional chaining to safely access nested properties:
+
+```javascript
+const userCity = input.userBlock?.address?.city;
+const firstItemName = input.orderBlock?.items?.[0]?.name;
+```
+
+## Debugging Connection Data
+
+When troubleshooting connection issues, these techniques can help:
+
+1. **Log Data**: In Function blocks, use `console.log()` to inspect connected data
+2. **Return Full Objects**: Return the full input object to see all available data
+3. **Check Types**: Verify the data types of connected values
+4. **Validate Paths**: Ensure you're using the correct path to access nested data
+
+```javascript
+// Example debugging function
+function debugConnections() {
+  console.log('All inputs:', input);
+  console.log('User data type:', typeof input.userBlock);
+  console.log('Order items:', input.orderBlock?.items);
+  
+  return {
+    debug: true,
+    allInputs: input,
+    userExists: !!input.userBlock,
+    orderItemCount: input.orderBlock?.items?.length || 0
+  };
+}
+``` 

docs/content/docs/connections/basics.mdx

@@ -0,0 +1,73 @@
+---
+title: Connection Basics
+description: Learn how connections work in Sim Studio
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Steps, Step } from 'fumadocs-ui/components/steps'
+
+## How Connections Work
+
+Connections are the pathways that allow data to flow between blocks in your workflow. When you connect two blocks in Sim Studio, you're establishing a data flow relationship that defines how information passes from one block to another.
+
+<Callout type="info">
+  Each connection represents a directed relationship where data flows from a source block's output to a destination block's input.
+</Callout>
+
+### Creating Connections
+
+<Steps>
+  <Step>
+    <strong>Select Source Block</strong>: Click on the output port of the block you want to connect from
+  </Step>
+  <Step>
+    <strong>Draw Connection</strong>: Drag to the input port of the destination block
+  </Step>
+  <Step>
+    <strong>Confirm Connection</strong>: Release to create the connection
+  </Step>
+  <Step>
+    <strong>Configure (Optional)</strong>: Some connections may require additional configuration
+  </Step>
+</Steps>
+
+### Connection Flow
+
+The flow of data through connections follows these principles:
+
+1. **Directional Flow**: Data always flows from outputs to inputs
+2. **Execution Order**: Blocks execute in order based on their connections
+3. **Data Transformation**: Data may be transformed as it passes between blocks
+4. **Conditional Paths**: Some blocks (like Router and Condition) can direct flow to different paths
+
+### Connection Visualization
+
+Connections are visually represented in the workflow editor:
+
+- **Solid Lines**: Active connections that will pass data
+- **Animated Flow**: During execution, data flow is visualized along connections
+- **Color Coding**: Different connection types may have different colors
+- **Connection Tags**: Visual indicators showing what data is available
+
+### Managing Connections
+
+You can manage your connections in several ways:
+
+- **Delete**: Click on a connection and press Delete or use the context menu
+- **Reroute**: Drag a connection to change its path
+- **Inspect**: Click on a connection to see details about the data being passed
+- **Disable**: Temporarily disable a connection without deleting it
+
+<Callout type="warning">
+  Deleting a connection will immediately stop data flow between the blocks. Make sure this is intended before removing connections.
+</Callout>
+
+## Connection Compatibility
+
+Not all blocks can be connected to each other. Compatibility depends on:
+
+1. **Data Type Compatibility**: The output type must be compatible with the input type
+2. **Block Restrictions**: Some blocks may have restrictions on what they can connect to
+3. **Workflow Logic**: Connections must make logical sense in the context of your workflow
+
+The editor will indicate when connections are invalid or incompatible. 

docs/content/docs/connections/best-practices.mdx

@@ -0,0 +1,207 @@
+---
+title: Connection Best Practices
+description: Recommended patterns for effective connection management
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Steps, Step } from 'fumadocs-ui/components/steps'
+
+## Connection Best Practices
+
+Following these best practices will help you create more maintainable, efficient, and reliable workflows with connections.
+
+## Workflow Organization
+
+### Organize Your Connections
+
+Keep your workflow clean and understandable by organizing connections logically:
+
+- **Minimize crossing connections** when possible to reduce visual complexity
+- **Group related blocks together** to make data flow more intuitive
+- **Use consistent flow direction** (typically left-to-right or top-to-bottom)
+- **Label complex connections** with descriptive names
+
+<Callout type="info">
+  A well-organized workflow is easier to understand, debug, and maintain. Take time to arrange your blocks and connections in a logical manner.
+</Callout>
+
+### Connection Naming Conventions
+
+When working with multiple connections, consistent naming helps maintain clarity:
+
+<Steps>
+  <Step>
+    <strong>Use descriptive block names</strong>: Name blocks based on their function (e.g., "UserDataFetcher", "ResponseGenerator")
+  </Step>
+  <Step>
+    <strong>Be specific with connection references</strong>: Use clear variable names when referencing connections in code
+  </Step>
+  <Step>
+    <strong>Document complex connections</strong>: Add comments explaining non-obvious data transformations
+  </Step>
+</Steps>
+
+## Data Validation
+
+### Validate Data Flow
+
+Ensure that the data being passed between blocks is compatible:
+
+- **Check that required fields are available** in the source block
+- **Verify data types match expectations** before using them
+- **Use Function blocks to transform data** when necessary
+- **Handle missing or null values** with default values or conditional logic
+
+```javascript
+// Example: Validating and transforming data in a Function block
+function processUserData() {
+  // Validate required fields
+  if (!input.userBlock || !input.userBlock.id) {
+    return { error: "Missing user data", valid: false };
+  }
+  
+  // Transform and validate data types
+  const userId = String(input.userBlock.id);
+  const userName = input.userBlock.name || "Unknown User";
+  const userScore = Number(input.userBlock.score) || 0;
+  
+  return {
+    valid: true,
+    user: {
+      id: userId,
+      name: userName,
+      score: userScore,
+      isHighScore: userScore > 100
+    }
+  };
+}
+```
+
+## Documentation
+
+### Document Connection Purpose
+
+Add comments or descriptions to clarify the purpose of connections, especially in complex workflows:
+
+- **What data is being passed**: Document the key fields and their purpose
+- **Why this connection exists**: Explain the relationship between blocks
+- **Any transformations or conditions applied**: Note any data processing that occurs
+
+```javascript
+// Example: Documenting connection purpose in a Function block
+/*
+ * This function processes user data from the UserFetcher block
+ * and order history from the OrderHistory block to generate
+ * personalized product recommendations.
+ * 
+ * Input:
+ * - userBlock: User profile data (id, preferences, history)
+ * - orderBlock: Recent order history (items, dates, amounts)
+ * 
+ * Output:
+ * - recommendations: Array of recommended product IDs
+ * - userSegment: Calculated user segment for marketing
+ * - conversionProbability: Estimated likelihood of purchase
+ */
+function generateRecommendations() {
+  // Implementation...
+}
+```
+
+## Testing and Debugging
+
+### Test Connection References
+
+Verify that connection references work as expected:
+
+- **Test with different input values** to ensure robustness
+- **Check edge cases** (empty values, large datasets, special characters)
+- **Ensure error handling for missing or invalid data**
+- **Use console logging in Function blocks** to debug connection issues
+
+```javascript
+// Example: Testing connection references with edge cases
+function testConnections() {
+  console.log("Testing connections...");
+  
+  // Log all inputs for debugging
+  console.log("All inputs:", JSON.stringify(input, null, 2));
+  
+  // Test for missing data
+  const hasUserData = !!input.userBlock;
+  console.log("Has user data:", hasUserData);
+  
+  // Test edge cases
+  const items = input.orderBlock?.items || [];
+  console.log("Item count:", items.length);
+  console.log("Empty items test:", items.length === 0 ? "Passed" : "Failed");
+  
+  // Return test results
+  return {
+    tests: {
+      hasUserData,
+      hasItems: items.length > 0,
+      hasLargeOrder: items.length > 10
+    }
+  };
+}
+```
+
+## Performance Considerations
+
+### Optimize Data Flow
+
+Keep your workflows efficient by optimizing how data flows through connections:
+
+- **Pass only necessary data** between blocks to reduce memory usage
+- **Use Function blocks to filter large datasets** before passing them on
+- **Consider caching results** for expensive operations
+- **Break complex workflows into smaller, reusable components**
+
+```javascript
+// Example: Optimizing data flow by filtering
+function optimizeUserData() {
+  const userData = input.userBlock;
+  
+  // Only pass necessary fields to downstream blocks
+  return {
+    id: userData.id,
+    name: userData.name,
+    email: userData.email,
+    // Filter out unnecessary profile data, history, etc.
+  };
+}
+```
+
+## Security Best Practices
+
+### Secure Sensitive Data
+
+Protect sensitive information when using connections:
+
+- **Never expose API keys or credentials** in connection data
+- **Sanitize user input** before processing it
+- **Redact sensitive information** when logging connection data
+- **Use secure connections** for external API calls
+
+<Callout type="warning">
+  Be careful when logging connection data that might contain sensitive information. Always redact or mask sensitive fields like passwords, API keys, or personal information.
+</Callout>
+
+## Advanced Patterns
+
+### Conditional Connections
+
+Use Condition blocks to create dynamic workflows:
+
+- **Route data based on content** to different processing paths
+- **Implement fallback paths** for error handling
+- **Create decision trees** for complex business logic
+
+### Feedback Loops
+
+Create more sophisticated workflows with feedback connections:
+
+- **Implement iterative processing** by connecting later blocks back to earlier ones
+- **Use Memory blocks** to store state between iterations
+- **Set termination conditions** to prevent infinite loops 

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

@@ -0,0 +1,181 @@
+---
+title: Connection Data Structure
+description: Understanding the data structure of different block outputs
+---
+
+import { Tabs, Tab } from 'fumadocs-ui/components/tabs'
+import { Callout } from 'fumadocs-ui/components/callout'
+
+## Connection Data Structure
+
+When you connect blocks, the output data structure from the source block determines what values are available in the destination block. Each block type produces a specific output structure that you can reference in downstream blocks.
+
+<Callout type="info">
+  Understanding these data structures is essential for effectively using connection tags and accessing the right data in your workflows.
+</Callout>
+
+## Block Output Structures
+
+Different block types produce different output structures. Here's what you can expect from each block type:
+
+<Tabs items={['Agent Output', 'API Output', 'Function Output', 'Evaluator Output', 'Condition Output', 'Router Output']}>
+  <Tab>
+    ```json
+    {
+      "content": "The generated text response",
+      "model": "gpt-4o",
+      "tokens": {
+        "prompt": 120,
+        "completion": 85,
+        "total": 205
+      },
+      "toolCalls": [...]
+    }
+    ```
+
+    ### Agent Block Output Fields
+
+    - **content**: The main text response generated by the agent
+    - **model**: The AI model used (e.g., "gpt-4o", "claude-3-opus")
+    - **tokens**: Token usage statistics
+      - **prompt**: Number of tokens in the prompt
+      - **completion**: Number of tokens in the completion
+      - **total**: Total tokens used
+    - **toolCalls**: Array of tool calls made by the agent (if any)
+  </Tab>
+  <Tab>
+    ```json
+    {
+      "data": "Response data",
+      "status": 200,
+      "headers": {
+        "content-type": "application/json",
+        "cache-control": "no-cache"
+      }
+    }
+    ```
+
+    ### API Block Output Fields
+
+    - **data**: The response data from the API (can be any type)
+    - **status**: HTTP status code of the response
+    - **headers**: HTTP headers returned by the API
+  </Tab>
+  <Tab>
+    ```json
+    {
+      "result": "Function return value",
+      "stdout": "Console output",
+      "executionTime": 45
+    }
+    ```
+
+    ### Function Block Output Fields
+
+    - **result**: The return value of the function (can be any type)
+    - **stdout**: Console output captured during function execution
+    - **executionTime**: Time taken to execute the function (in milliseconds)
+  </Tab>
+  <Tab>
+    ```json
+    {
+      "content": "Evaluation summary",
+      "model": "gpt-4o",
+      "tokens": {
+        "prompt": 120,
+        "completion": 85,
+        "total": 205
+      },
+      "metric1": 8.5,
+      "metric2": 7.2,
+      "metric3": 9.0
+    }
+    ```
+
+    ### Evaluator Block Output Fields
+
+    - **content**: Summary of the evaluation
+    - **model**: The AI model used for evaluation
+    - **tokens**: Token usage statistics
+    - **[metricName]**: Score for each metric defined in the evaluator (dynamic fields)
+  </Tab>
+  <Tab>
+    ```json
+    {
+      "content": "Original content passed through",
+      "conditionResult": true,
+      "selectedPath": {
+        "blockId": "2acd9007-27e8-4510-a487-73d3b825e7c1",
+        "blockType": "agent",
+        "blockTitle": "Follow-up Agent"
+      },
+      "selectedConditionId": "condition-1"
+    }
+    ```
+
+    ### Condition Block Output Fields
+
+    - **content**: The original content passed through
+    - **conditionResult**: Boolean result of the condition evaluation
+    - **selectedPath**: Information about the selected path
+      - **blockId**: ID of the next block in the selected path
+      - **blockType**: Type of the next block
+      - **blockTitle**: Title of the next block
+    - **selectedConditionId**: ID of the selected condition
+  </Tab>
+  <Tab>
+    ```json
+    {
+      "content": "Routing decision",
+      "model": "gpt-4o",
+      "tokens": {
+        "prompt": 120,
+        "completion": 85,
+        "total": 205
+      },
+      "selectedPath": {
+        "blockId": "2acd9007-27e8-4510-a487-73d3b825e7c1",
+        "blockType": "agent",
+        "blockTitle": "Customer Service Agent"
+      }
+    }
+    ```
+
+    ### Router Block Output Fields
+
+    - **content**: The routing decision text
+    - **model**: The AI model used for routing
+    - **tokens**: Token usage statistics
+    - **selectedPath**: Information about the selected path
+      - **blockId**: ID of the selected destination block
+      - **blockType**: Type of the selected block
+      - **blockTitle**: Title of the selected block
+  </Tab>
+</Tabs>
+
+## Custom Output Structures
+
+Some blocks may produce custom output structures based on their configuration:
+
+1. **Agent Blocks with Response Format**: When using a response format in an Agent block, the output structure will match the defined schema instead of the standard structure.
+
+2. **Function Blocks**: The `result` field can contain any data structure returned by your function code.
+
+3. **API Blocks**: The `data` field will contain whatever the API returns, which could be any valid JSON structure.
+
+<Callout type="warning">
+  Always check the actual output structure of your blocks during development to ensure you're referencing the correct fields in your connections.
+</Callout>
+
+## Nested Data Structures
+
+Many block outputs contain nested data structures. You can access these using dot notation in connection tags:
+
+```
+<blockId.path.to.nested.data>
+```
+
+For example:
+- `<agent1.tokens.total>` - Access the total tokens from an Agent block
+- `<api1.data.results[0].id>` - Access the ID of the first result from an API response
+- `<function1.result.calculations.total>` - Access a nested field in a Function block's result 

docs/content/docs/connections/index.mdx

@@ -3,10 +3,8 @@ title: Connections
 description: Connect your blocks to one another.
 ---
 
+import { Card, Cards } from 'fumadocs-ui/components/card'
 import { Callout } from 'fumadocs-ui/components/callout'
-import { Tabs, Tab } from 'fumadocs-ui/components/tabs'
-import { Steps, Step } from 'fumadocs-ui/components/steps'
-import { Files, Folder, File } from 'fumadocs-ui/components/files'
 import { ConnectIcon } from '@/components/icons'
 
 Connections are the pathways that allow data to flow between blocks in your workflow. They define how information is passed from one block to another, enabling you to create sophisticated, multi-step processes.
@@ -15,180 +13,37 @@ Connections are the pathways that allow data to flow between blocks in your work
   Properly configured connections are essential for creating effective workflows. They determine how data moves through your system and how blocks interact with each other.
 </Callout>
 
-## How Connections Work
-
-When you connect two blocks in Sim Studio, you're establishing a data flow relationship:
-
-<Steps>
-  <Step>
-    <strong>Create Connection</strong>: Draw a connection line between an output port of one block and an input port of another block
-  </Step>
-  <Step>
-    <strong>Connection Tag</strong>: A connection tag appears, representing the data that can flow between the blocks
-  </Step>
-  <Step>
-    <strong>Use Connection Data</strong>: Reference data from the source block in the destination block using connection tags
-  </Step>
-  <Step>
-    <strong>Data Transformation</strong>: Optionally transform or filter the data as it passes between blocks
-  </Step>
-</Steps>
-
-![Connections in action](public/connections.gif)
-
-## Connection Tags
-
-Connection tags are visual representations of the data available from connected blocks. They provide an easy way to reference outputs from previous blocks in your workflow.
-
-### Using Connection Tags
-
-<div className="grid grid-cols-1 md:grid-cols-2 gap-4 my-6">
-  <div className="border border-gray-200 dark:border-gray-800 rounded-lg p-4">
-    <h3 className="font-medium text-lg mb-2">Drag and Drop</h3>
-    <p className="text-sm text-gray-600 dark:text-gray-400">
-      Click on a connection tag and drag it into input fields of destination blocks. A dropdown will appear showing available values.
-    </p>
-  </div>
-  
-  <div className="border border-gray-200 dark:border-gray-800 rounded-lg p-4">
-    <h3 className="font-medium text-lg mb-2">Angle Bracket Syntax</h3>
-    <p className="text-sm text-gray-600 dark:text-gray-400">
-      Type <code>&lt;&gt;</code> in input fields to see a dropdown of available connection values from previous blocks.
-    </p>
-  </div>
+<div>
+  <video 
+    autoPlay 
+    loop 
+    muted 
+    playsInline
+    className="w-full"
+    src="/connections.mp4"
+  >
+  </video>
 </div>
 
-## Connection Data Structure
-
-When you connect blocks, the output data structure from the source block determines what values are available in the destination block:
-
-<Tabs items={['Agent Block Output', 'API Block Output', 'Function Block Output']}>
-  <Tab>
-    ```json
-    {
-      "content": "The generated text response",
-      "model": "gpt-4",
-      "tokens": {
-        "prompt": 120,
-        "completion": 85,
-        "total": 205
-      },
-      "toolCalls": [...]
-    }
-    ```
-  </Tab>
-  <Tab>
-    ```json
-    {
-      "status": 200,
-      "body": { ... },
-      "headers": { ... },
-      "error": null
-    }
-    ```
-  </Tab>
-  <Tab>
-    ```json
-    {
-      "result": "Function return value",
-      "stdout": "Console output",
-      "executionTime": 45
-    }
-    ```
-  </Tab>
-</Tabs>
-
-## Accessing Nested Data
-
-You can access nested properties from connected blocks using dot notation:
-
-<Files>
-  <File name="Simple Property" annotation="<block.content>" />
-  <File name="Nested Property" annotation="<block.tokens.total>" />
-  <File name="Array Element" annotation="<block.items[0].name>" />
-  <File name="Complex Path" annotation="<block.data.users[2].profile.email>" />
-</Files>
-
-## Dynamic References
-
-Connection references are evaluated at runtime, allowing for dynamic data flow through your workflow:
-
-```javascript
-// In a Function block, you can access connected data
-const userName = input.userBlock.name;
-const orderTotal = input.apiBlock.body.order.total;
-
-// Process the data
-const discount = orderTotal > 100 ? 0.1 : 0;
-const finalPrice = orderTotal * (1 - discount);
-
-// Return the result
-return {
-  userName,
-  originalTotal: orderTotal,
-  discount: discount * 100 + '%',
-  finalPrice
-};
-```
-
 ## Connection Types
 
-Sim Studio supports different types of connections based on the blocks being connected:
+Sim Studio supports different types of connections that enable various workflow patterns:
 
-<div className="grid grid-cols-1 md:grid-cols-3 gap-4 my-6">
-  <div className="border border-gray-200 dark:border-gray-800 rounded-lg p-4">
-    <h3 className="font-medium text-lg mb-2">Data Connections</h3>
-    <p className="text-sm text-gray-600 dark:text-gray-400">
-      Pass data between blocks for processing or transformation
-    </p>
-  </div>
-  
-  <div className="border border-gray-200 dark:border-gray-800 rounded-lg p-4">
-    <h3 className="font-medium text-lg mb-2">Control Connections</h3>
-    <p className="text-sm text-gray-600 dark:text-gray-400">
-      Determine execution flow based on conditions or routing decisions
-    </p>
-  </div>
-  
-  <div className="border border-gray-200 dark:border-gray-800 rounded-lg p-4">
-    <h3 className="font-medium text-lg mb-2">Feedback Connections</h3>
-    <p className="text-sm text-gray-600 dark:text-gray-400">
-      Create loops by connecting later blocks back to earlier ones
-    </p>
-  </div>
-</div>
-
-## Best Practices
-
-### Organize Your Connections
-
-Keep your workflow clean and understandable by organizing connections logically:
-
-- Minimize crossing connections when possible
-- Group related blocks together
-- Use consistent flow direction (typically left-to-right or top-to-bottom)
-
-### Validate Data Flow
-
-Ensure that the data being passed between blocks is compatible:
-
-- Check that required fields are available in the source block
-- Verify data types match expectations
-- Use Function blocks to transform data when necessary
-
-### Document Connection Purpose
-
-Add comments or descriptions to clarify the purpose of connections, especially in complex workflows:
-
-- What data is being passed
-- Why this connection exists
-- Any transformations or conditions applied to the data
-
-### Test Connection References
-
-Verify that connection references work as expected:
-
-- Test with different input values
-- Check edge cases (empty values, large datasets)
-- Ensure error handling for missing or invalid data
+<Cards>
+  <Card title="Connection Basics" href="/docs/connections/basics">
+    Learn how connections work and how to create them in your workflows
+  </Card>
+  <Card title="Connection Tags" href="/docs/connections/tags">
+    Understand how to use connection tags to reference data between blocks
+  </Card>
+  <Card title="Data Structure" href="/docs/connections/data-structure">
+    Explore the output data structures of different block types
+  </Card>
+  <Card title="Accessing Data" href="/docs/connections/accessing-data">
+    Learn techniques for accessing and manipulating connected data
+  </Card>
+  <Card title="Best Practices" href="/docs/connections/best-practices">
+    Follow recommended patterns for effective connection management
+  </Card>
+</Cards>
 

docs/content/docs/connections/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Connections",
+  "pages": ["basics", "tags", "data-structure", "accessing-data", "best-practices"]
+} 

docs/content/docs/connections/tags.mdx

@@ -0,0 +1,111 @@
+---
+title: Connection Tags
+description: Using connection tags to reference data between blocks
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+
+## Connection Tags
+
+Connection tags are visual representations of the data available from connected blocks. They provide an easy way to reference outputs from previous blocks in your workflow.
+
+<div>
+  <video 
+    autoPlay 
+    loop 
+    muted 
+    playsInline
+    className="w-full"
+    src="/connections.mp4"
+  >
+  </video>
+</div>
+
+### What Are Connection Tags?
+
+Connection tags are interactive elements that appear when blocks are connected. They represent the data that can flow from one block to another and allow you to:
+
+- Visualize available data from source blocks
+- Reference specific data fields in destination blocks
+- Create dynamic data flows between blocks
+
+<Callout type="info">
+  Connection tags make it easy to see what data is available from previous blocks and use it in your current block without having to remember complex data structures.
+</Callout>
+
+## Using Connection Tags
+
+There are two primary ways to use connection tags in your workflows:
+
+<div className="grid grid-cols-1 md:grid-cols-2 gap-4 my-6">
+  <div className="border border-gray-200 dark:border-gray-800 rounded-lg p-4">
+    <h3 className="font-medium text-lg mb-2">Drag and Drop</h3>
+    <p className="text-sm text-gray-600 dark:text-gray-400">
+      Click on a connection tag and drag it into input fields of destination blocks. A dropdown will appear showing available values.
+    </p>
+    <ol className="mt-2 text-sm text-gray-600 dark:text-gray-400 list-decimal pl-5">
+      <li>Hover over a connection tag to see available data</li>
+      <li>Click and drag the tag to an input field</li>
+      <li>Select the specific data field from the dropdown</li>
+      <li>The reference is inserted automatically</li>
+    </ol>
+  </div>
+  
+  <div className="border border-gray-200 dark:border-gray-800 rounded-lg p-4">
+    <h3 className="font-medium text-lg mb-2">Angle Bracket Syntax</h3>
+    <p className="text-sm text-gray-600 dark:text-gray-400">
+      Type <code>&lt;&gt;</code> in input fields to see a dropdown of available connection values from previous blocks.
+    </p>
+    <ol className="mt-2 text-sm text-gray-600 dark:text-gray-400 list-decimal pl-5">
+      <li>Click in any input field where you want to use connected data</li>
+      <li>Type <code>&lt;&gt;</code> to trigger the connection dropdown</li>
+      <li>Browse and select the data you want to reference</li>
+      <li>Continue typing or select from the dropdown to complete the reference</li>
+    </ol>
+  </div>
+</div>
+
+## Tag Syntax
+
+Connection tags use a simple syntax to reference data:
+
+```
+<blockId.path.to.data>
+```
+
+Where:
+- `blockId` is the identifier of the source block
+- `path.to.data` is the path to the specific data field
+
+For example:
+- `<agent1.content>` - References the content field from a block with ID "agent1"
+- `<api2.data.users[0].name>` - References the name of the first user in the users array from the data field of a block with ID "api2"
+
+## Dynamic Tag References
+
+Connection tags are evaluated at runtime, which means:
+
+1. They always reference the most current data
+2. They can be used in expressions and combined with static text
+3. They can be nested within other data structures
+
+### Examples
+
+```javascript
+// Reference in text
+"The user's name is <userBlock.name>"
+
+// Reference in JSON
+{
+  "userName": "<userBlock.name>",
+  "orderTotal": <apiBlock.data.total>
+}
+
+// Reference in code
+const greeting = "Hello, <userBlock.name>!";
+const total = <apiBlock.data.total> * 1.1; // Add 10% tax
+```
+
+<Callout type="warning">
+  When using connection tags in numeric contexts, make sure the referenced data is actually a number to avoid type conversion issues.
+</Callout> 

docs/content/docs/execution/advanced.mdx

@@ -0,0 +1,289 @@
+---
+title: Advanced Execution Features
+description: Master advanced execution capabilities in Sim Studio
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Tabs, Tab } from 'fumadocs-ui/components/tabs'
+import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'
+
+# Advanced Execution Features
+
+Sim Studio provides several advanced features that give you more control over workflow execution, error handling, and performance optimization.
+
+## Error Handling
+
+The execution engine includes built-in error handling mechanisms to make your workflows more robust:
+
+### Block-Level Error Handling
+
+Errors in one block don't necessarily stop the entire workflow execution:
+
+```javascript
+// Example of error handling in a Function block
+try {
+  // Potentially risky operation
+  const result = JSON.parse(input.apiBlock.data);
+  return { success: true, data: result };
+} catch (error) {
+  // Handle the error gracefully
+  console.error("Failed to parse JSON:", error.message);
+  return { 
+    success: false, 
+    error: error.message,
+    fallbackData: { status: "error", message: "Could not process data" }
+  };
+}
+```
+
+### Error Logging
+
+Comprehensive error information is captured in the execution logs:
+
+- **Error Messages**: Clear descriptions of what went wrong
+- **Stack Traces**: Detailed information about where errors occurred
+- **Context Data**: The inputs that led to the error
+- **Timestamps**: When the error occurred
+
+<Callout type="info">
+  Error logs are invaluable for debugging workflows. Always check the logs first when troubleshooting execution issues.
+</Callout>
+
+### Fallback Mechanisms
+
+For certain operations, the system provides automatic fallbacks:
+
+- **Function Execution**: WebContainer execution first, then VM execution if needed
+- **API Requests**: Automatic retries for transient network errors
+- **Model Calls**: Fallback to alternative models if primary model is unavailable
+
+### Recovery Options
+
+Configure blocks to handle failures gracefully:
+
+- **Retry Logic**: Automatically retry failed operations
+- **Default Values**: Provide fallback values when operations fail
+- **Alternative Paths**: Use conditional blocks to create error handling paths
+- **Graceful Degradation**: Continue execution with partial results
+
+## Environment Variables
+
+Environment variables provide a secure way to store and access configuration values:
+
+### Types of Environment Variables
+
+<Tabs items={['API Keys', 'Configuration Values', 'Secrets']}>
+  <Tab>
+    Store API credentials securely:
+    
+    ```
+    OPENAI_API_KEY=sk-...
+    ANTHROPIC_API_KEY=sk-...
+    GOOGLE_API_KEY=AIza...
+    ```
+    
+    These are automatically available to blocks that need them, without hardcoding sensitive values in your workflow.
+  </Tab>
+  
+  <Tab>
+    Manage environment-specific configuration:
+    
+    ```
+    MAX_RETRIES=3
+    DEFAULT_MODEL=gpt-4o
+    LOG_LEVEL=info
+    BASE_URL=https://api.example.com
+    ```
+    
+    These values can be referenced in blocks to control behavior without modifying the workflow itself.
+  </Tab>
+  
+  <Tab>
+    Store sensitive information securely:
+    
+    ```
+    DATABASE_PASSWORD=...
+    JWT_SECRET=...
+    ENCRYPTION_KEY=...
+    ```
+    
+    These values are encrypted at rest and only decrypted during execution, providing an extra layer of security.
+  </Tab>
+</Tabs>
+
+### Using Environment Variables
+
+Environment variables can be accessed in different ways depending on the block type:
+
+```javascript
+// In Function blocks
+const apiKey = process.env.MY_API_KEY;
+const maxRetries = parseInt(process.env.MAX_RETRIES || "3");
+
+// In API blocks (via connection tags)
+// URL: https://api.example.com?key=<env.MY_API_KEY>
+
+// In Agent blocks (via connection tags)
+// System prompt: Use the model <env.DEFAULT_MODEL> for this task.
+```
+
+<Callout type="warning">
+  Never hardcode sensitive information like API keys directly in your workflows. Always use environment variables instead.
+</Callout>
+
+## Real-Time Monitoring
+
+Sim Studio provides powerful real-time monitoring capabilities:
+
+<Accordions>
+  <Accordion title="Active Block Indicator">
+    The currently executing block is highlighted in the workflow editor, making it easy to follow the execution flow in real-time. This visual indicator helps you understand exactly where in your workflow the execution is currently happening.
+  </Accordion>
+  
+  <Accordion title="Live Logs Panel">
+    Execution logs appear in real-time in the logs panel on the right side. These logs include detailed information about each block's execution, including inputs, outputs, execution time, and any errors that occur. You can use these logs to debug your workflow and understand how data flows between blocks.
+  </Accordion>
+  
+  <Accordion title="Block States">
+    Each block's state (pending, executing, completed, or error) is visually indicated in the workflow editor. This helps you quickly identify which blocks have executed successfully and which may have encountered issues.
+  </Accordion>
+  
+  <Accordion title="Performance Metrics">
+    Detailed timing information shows how long each block takes to execute, helping you identify performance bottlenecks in your workflow. The execution engine tracks start time, end time, and total duration for both individual blocks and the entire workflow.
+  </Accordion>
+</Accordions>
+
+## Performance Optimization
+
+Optimize your workflows for better performance:
+
+### Block Optimization
+
+- **Break Down Complex Blocks**: Split complex operations into multiple simpler blocks
+- **Minimize External Calls**: Batch API requests where possible
+- **Cache Results**: Use Memory blocks to store and reuse results
+- **Optimize Function Code**: Write efficient JavaScript/TypeScript code
+
+### Data Flow Optimization
+
+- **Filter Data Early**: Process only the data you need as early as possible
+- **Minimize Data Transfer**: Pass only necessary fields between blocks
+- **Use Appropriate Data Structures**: Choose efficient data structures for your use case
+- **Avoid Redundant Computations**: Don't recalculate values that haven't changed
+
+### Execution Configuration
+
+- **Set Appropriate Timeouts**: Configure timeouts based on expected execution time
+- **Limit Parallel Executions**: Control how many workflows can run simultaneously
+- **Schedule During Off-Peak Hours**: Run resource-intensive workflows when system load is lower
+- **Monitor Resource Usage**: Keep an eye on memory and CPU usage
+
+<Callout type="info">
+  Performance optimization is especially important for workflows that run frequently or process large amounts of data.
+</Callout>
+
+## Advanced Execution Context
+
+The execution context maintains detailed information about the workflow execution:
+
+```javascript
+// Example of execution context structure (simplified)
+{
+  // Block states indexed by block ID
+  blockStates: {
+    "block-1": { output: { content: "..." }, status: "completed" },
+    "block-2": { output: { data: { ... } }, status: "completed" },
+    "block-3": { status: "pending" }
+  },
+  
+  // Active execution path
+  activeExecutionPath: Set(["block-1", "block-2", "block-5"]),
+  
+  // Routing decisions
+  decisions: {
+    router: Map(["router-1" => "block-5"]),
+    condition: Map(["condition-1" => "condition-true"])
+  },
+  
+  // Loop iterations
+  loopIterations: Map(["loop-1" => 2]),
+  
+  // Environment variables
+  env: { "API_KEY": "...", "MAX_RETRIES": "3" },
+  
+  // Execution logs
+  logs: [
+    { blockId: "block-1", timestamp: "...", status: "completed", duration: 120 },
+    { blockId: "block-2", timestamp: "...", status: "completed", duration: 85 }
+  ]
+}
+```
+
+This context is used internally by the execution engine but understanding its structure can help you debug complex workflows.
+
+## Debugging Techniques
+
+Advanced techniques for debugging workflow execution:
+
+### Console Logging
+
+Add strategic console.log statements in Function blocks:
+
+```javascript
+console.log("Input to processData:", JSON.stringify(input, null, 2));
+console.log("Processing step 1 complete:", intermediateResult);
+console.log("Final result:", finalResult);
+```
+
+### State Inspection
+
+Use Function blocks to inspect the current state:
+
+```javascript
+function debugState() {
+  // Log all inputs
+  console.log("All inputs:", input);
+  
+  // Return a debug object with relevant information
+  return {
+    debug: true,
+    inputSummary: {
+      hasUserData: !!input.userBlock,
+      apiStatus: input.apiBlock?.status,
+      itemCount: input.dataBlock?.items?.length || 0
+    },
+    timestamp: new Date().toISOString()
+  };
+}
+```
+
+### Execution Tracing
+
+Enable detailed execution tracing for complex workflows:
+
+1. Add a Memory block to accumulate trace information
+2. Add trace logging in key Function blocks
+3. Review the trace after execution to understand the flow
+
+### Performance Profiling
+
+Identify performance bottlenecks:
+
+```javascript
+function profileOperation() {
+  const start = performance.now();
+  
+  // Perform the operation
+  const result = performExpensiveOperation();
+  
+  const end = performance.now();
+  console.log(`Operation took ${end - start}ms`);
+  
+  return {
+    result,
+    executionTime: end - start
+  };
+}
+```
+
+By mastering these advanced execution features, you can create more robust, efficient, and sophisticated workflows in Sim Studio. 

docs/content/docs/execution/basics.mdx

@@ -0,0 +1,173 @@
+---
+title: Execution Basics
+description: Understanding the fundamental execution flow in Sim Studio
+---
+
+import { Step, Steps } from 'fumadocs-ui/components/steps'
+import { Tabs, Tab } from 'fumadocs-ui/components/tabs'
+import { Files, Folder, File } from 'fumadocs-ui/components/files'
+import { Callout } from 'fumadocs-ui/components/callout'
+import { AgentIcon, ApiIcon, ConditionalIcon, CodeIcon, ChartBarIcon, ConnectIcon } from '@/components/icons'
+
+# Execution Basics
+
+When you run a workflow in Sim Studio, the execution engine follows a systematic process to ensure blocks are executed in the correct order and data flows properly between them.
+
+## Execution Flow
+
+The execution of a workflow follows these key steps:
+
+<Steps>
+  <Step>
+    ### Validation
+    Before execution begins, the workflow is validated to ensure it has:
+    - An enabled starter block with no incoming connections
+    - Properly connected blocks with valid configurations
+    - No circular dependencies (except in intentional loops)
+    - Valid input and output types between connected blocks
+  </Step>
+  
+  <Step>
+    ### Initialization
+    The execution context is created, which includes:
+    - Environment variables for the workflow
+    - Input values from the starter block
+    - Initial state for all blocks
+    - Execution path tracking
+    - Loop iteration counters
+  </Step>
+  
+  <Step>
+    ### Block Execution
+    Blocks are executed in topological order (based on dependencies):
+    - The system identifies which blocks can be executed next
+    - Inputs for each block are resolved from previous block outputs
+    - Each block is executed by its specialized handler
+    - Outputs are stored in the execution context
+  </Step>
+  
+  <Step>
+    ### Path Determination
+    As execution progresses, the system determines which paths to follow:
+    - Router and conditional blocks make decisions about execution paths
+    - Only blocks on active paths are executed
+    - The path tracker maintains the current execution state
+  </Step>
+  
+  <Step>
+    ### Result Collection
+    After all blocks have executed:
+    - Final outputs are collected
+    - Execution logs are compiled
+    - Performance metrics are calculated
+    - Results are presented in the UI
+  </Step>
+</Steps>
+
+## Block Types and Execution
+
+Different block types have different execution behaviors:
+
+<Tabs items={['Orchestration Blocks', 'Processing Blocks', 'Integration Blocks']}>
+  <Tab>
+    <Card>
+      Orchestration blocks control the flow of execution through your workflow.
+      
+      <Files>
+        <File name="Starter Block" icon={<ConnectIcon className="w-4 h-4" />} annotation="Initiates workflow execution and provides initial input values. Every workflow must have exactly one starter block." />
+        <File name="Router Block" icon={<ConnectIcon className="w-4 h-4" />} annotation="Directs execution along specific paths based on dynamic decisions. Uses an AI model to select one of multiple possible paths." />
+        <File name="Condition Block" icon={<ConditionalIcon className="w-4 h-4" />} annotation="Executes different paths based on conditional logic. Evaluates JavaScript expressions to determine which path to follow." />
+      </Files>
+    </Card>
+  </Tab>
+  
+  <Tab>
+    <Card>
+      Processing blocks transform data and generate new outputs.
+      
+      <Files>
+        <File name="Agent Block" icon={<AgentIcon className="w-4 h-4" />} annotation="Interacts with AI models to generate content. Executes prompts against various LLM providers." />
+        <File name="Function Block" icon={<CodeIcon className="w-4 h-4" />} annotation="Executes custom JavaScript/TypeScript code. Runs in a secure sandbox environment with access to connected block outputs." />
+        <File name="Evaluator Block" icon={<ChartBarIcon className="w-4 h-4" />} annotation="Assesses outputs against defined criteria. Uses AI to evaluate content based on custom metrics." />
+      </Files>
+    </Card>
+  </Tab>
+  
+  <Tab>
+    <Card>
+      Integration blocks connect with external systems.
+      
+      <Files>
+        <File name="API Block" icon={<ApiIcon className="w-4 h-4" />} annotation="Makes HTTP requests to external services. Configurable with headers, body, and authentication." />
+        <File name="Tool Blocks" icon={<CodeIcon className="w-4 h-4" />} annotation="Specialized blocks for specific services (Gmail, Slack, GitHub, etc.). Each has its own execution logic for the specific service." />
+      </Files>
+    </Card>
+  </Tab>
+</Tabs>
+
+## Execution Methods
+
+Sim Studio offers multiple ways to trigger workflow execution:
+
+### Manual Execution
+
+Run workflows on-demand through the Sim Studio interface by clicking the "Run" button. This is perfect for:
+- Testing during development
+- One-off tasks
+- Workflows that need human supervision
+
+### Scheduled Execution
+
+Configure workflows to run automatically on a specified schedule:
+- Set up recurring executions using cron expressions
+- Define start times and frequency
+- Configure timezone settings
+- Set minimum and maximum execution intervals
+
+### API Endpoints
+
+Each workflow can be exposed as an API endpoint:
+- Get a unique URL for your workflow
+- Configure authentication requirements
+- Send custom inputs via POST requests
+- Receive execution results as JSON responses
+
+### Webhooks
+
+Configure workflows to execute in response to external events:
+- Set up webhook triggers from third-party services
+- Process incoming webhook data as workflow input
+- Configure webhook security settings
+- Support for specialized webhooks (GitHub, Stripe, etc.)
+
+<Callout type="info">
+  The execution method you choose depends on your workflow's purpose. Manual execution is great for development, while scheduled execution, API endpoints, and webhooks are better for production use cases.
+</Callout>
+
+## Execution Context
+
+Each workflow execution maintains a detailed context that includes:
+
+- **Block States**: Outputs and execution status of each block
+- **Execution Path**: The active path through the workflow
+- **Routing Decisions**: Records of which paths were selected
+- **Environment Variables**: Configuration values for the workflow
+- **Execution Logs**: Detailed records of each step in the execution
+
+This context is maintained throughout the execution and is used to:
+- Resolve inputs for blocks
+- Determine which blocks to execute next
+- Track the progress of execution
+- Provide debugging information
+- Store intermediate results
+
+## Real-Time Execution Monitoring
+
+As your workflow executes, you can monitor its progress in real-time:
+
+- **Active Block Highlighting**: The currently executing block is highlighted
+- **Live Logs**: Execution logs appear in real-time in the logs panel
+- **Block States**: Visual indicators show each block's execution state
+- **Performance Metrics**: Timing information for each block's execution
+
+These monitoring features help you understand how your workflow is executing and identify any issues that arise. 

docs/content/docs/execution/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: Execution
-description: Sim Studio provides a powerful execution engine that brings your workflows to life. Understanding how execution works will help you design more effective workflows and troubleshoot any issues that arise..
+description: Understand how workflows are executed in Sim Studio
 ---
 
 import { Card, Cards } from 'fumadocs-ui/components/card'
@@ -9,6 +9,53 @@ import { Step, Steps } from 'fumadocs-ui/components/steps'
 import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
 import { AgentIcon, ApiIcon, ConditionalIcon, CodeIcon, ChartBarIcon, ConnectIcon, GmailIcon, PerplexityIcon, NotionIcon, ExaAIIcon, FirecrawlIcon, SlackIcon } from '@/components/icons'
+import { Callout } from 'fumadocs-ui/components/callout'
+
+# Workflow Execution
+
+Sim Studio provides a powerful execution engine that brings your workflows to life. Understanding how execution works will help you design more effective workflows and troubleshoot any issues that arise.
+
+<div>
+  <video 
+    autoPlay 
+    loop 
+    muted 
+    playsInline
+    className="w-full"
+    src="/loops.mp4"
+  >
+  </video>
+</div>
+
+<Callout type="info">
+  The execution engine handles everything from block execution order to data flow, error handling, and loop management. It ensures your workflows run efficiently and predictably.
+</Callout>
+
+## Execution Documentation
+
+<Cards>
+  <Card title="Execution Basics" href="/docs/execution/basics">
+    Learn about the fundamental execution flow, block types, and how data flows through your workflow
+  </Card>
+  
+  <Card title="Loops" href="/docs/execution/loops">
+    Master the powerful loop functionality to create iterative processes and feedback mechanisms
+  </Card>
+  
+  <Card title="Advanced Features" href="/docs/execution/advanced">
+    Discover advanced capabilities like error handling, environment variables, and performance optimization
+  </Card>
+</Cards>
+
+## Key Execution Concepts
+
+- **Topological Execution** - Blocks are executed in dependency order, ensuring data flows correctly
+- **Path Tracking** - The system tracks active execution paths based on routing decisions
+- **Loop Management** - Sophisticated loop handling allows for iterative processing with safeguards
+- **Real-time Monitoring** - Watch your workflow execute with detailed logs and visual indicators
+- **Error Handling** - Robust error management keeps your workflows resilient
+
+Whether you're building simple automations or complex AI workflows, understanding execution is key to creating effective solutions in Sim Studio.
 
 ## Execution Flow
 

docs/content/docs/execution/loops.mdx

@@ -0,0 +1,219 @@
+---
+title: Loops
+description: Creating iterative processes with loops in Sim Studio
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Steps, Step } from 'fumadocs-ui/components/steps'
+import { Tabs, Tab } from 'fumadocs-ui/components/tabs'
+
+# Loops
+
+Loops are a powerful feature in Sim Studio that allow you to create iterative processes, implement feedback mechanisms, and build more sophisticated workflows.
+
+<div>
+  <video 
+    autoPlay 
+    loop 
+    muted 
+    playsInline
+    className="w-full"
+    src="/loops.mp4"
+  >
+  </video>
+</div>
+
+## What Are Loops?
+
+Loops in Sim Studio allow a group of blocks to execute repeatedly, with each iteration building on the results of the previous one. This enables:
+
+- **Iterative Refinement**: Progressively improve outputs through multiple passes
+- **Batch Processing**: Process collections of items one at a time
+- **Feedback Mechanisms**: Create systems that learn from their own outputs
+- **Conditional Processing**: Continue execution until specific criteria are met
+
+<Callout type="info">
+  Loops are particularly powerful for AI workflows, allowing you to implement techniques like chain-of-thought reasoning, recursive refinement, and multi-step problem solving.
+</Callout>
+
+## Creating Loops
+
+To create a loop in your workflow:
+
+<Steps>
+  <Step>
+    <strong>Select Blocks</strong>: Choose the blocks you want to include in the loop
+  </Step>
+  <Step>
+    <strong>Create Loop</strong>: Use the "Create Loop" option in the editor
+  </Step>
+  <Step>
+    <strong>Configure Loop Settings</strong>: Set iteration limits and conditions
+  </Step>
+  <Step>
+    <strong>Create Feedback Connections</strong>: Connect outputs from later blocks back to earlier blocks
+  </Step>
+</Steps>
+
+## Loop Configuration
+
+When configuring a loop, you can set several important parameters:
+
+### Iteration Limits
+
+- **Maximum Iterations**: The maximum number of times the loop can execute (default: 5)
+- **Minimum Iterations**: The minimum number of times the loop must execute before checking conditions
+
+<Callout type="warning">
+  Always set a reasonable maximum iteration limit to prevent infinite loops. The default limit of 5 iterations is a good starting point for most workflows.
+</Callout>
+
+### Loop Conditions
+
+Loops can continue based on different types of conditions:
+
+<Tabs items={['Conditional Block', 'Function Block', 'Fixed Iterations']}>
+  <Tab>
+    Use a Condition block to determine whether the loop should continue:
+    
+    ```javascript
+    // Example condition in a Condition block
+    function shouldContinueLoop() {
+      // Get the current score from an evaluator block
+      const score = input.evaluatorBlock.score;
+      
+      // Continue looping if score is below threshold
+      return score < 0.8;
+    }
+    ```
+    
+    The loop will continue executing as long as the condition returns true and the maximum iteration limit hasn't been reached.
+  </Tab>
+  
+  <Tab>
+    Use a Function block to implement complex loop conditions:
+    
+    ```javascript
+    // Example condition in a Function block
+    function processAndCheckContinuation() {
+      // Process data from previous blocks
+      const currentResult = input.agentBlock.content;
+      const previousResults = input.memoryBlock.results || [];
+      
+      // Store results for comparison
+      const allResults = [...previousResults, currentResult];
+      
+      // Check if we've converged (results not changing significantly)
+      const shouldContinue = previousResults.length === 0 || 
+        currentResult !== previousResults[previousResults.length - 1];
+      
+      return {
+        results: allResults,
+        shouldContinue: shouldContinue
+      };
+    }
+    ```
+    
+    Connect this Function block's output to a Condition block to control the loop.
+  </Tab>
+  
+  <Tab>
+    Execute the loop for a fixed number of iterations:
+    
+    ```
+    // Set in loop configuration
+    Minimum Iterations: 3
+    Maximum Iterations: 3
+    ```
+    
+    This will run the loop exactly 3 times, regardless of any conditions.
+  </Tab>
+</Tabs>
+
+## Loop Execution
+
+When a workflow with loops executes, the loop manager handles the iteration process:
+
+1. **First Pass**: All blocks in the loop execute normally
+2. **Iteration Check**: The system checks if another iteration should occur
+3. **State Reset**: If continuing, block states within the loop are reset
+4. **Next Iteration**: The loop blocks execute again with updated inputs
+5. **Termination**: The loop stops when either:
+   - The maximum iteration count is reached
+   - A loop condition evaluates to false (after minimum iterations)
+
+## Loop Use Cases
+
+Loops enable powerful workflow patterns:
+
+### Iterative Refinement
+
+<div className="p-4 border rounded-md mb-4">
+  <h4 className="font-medium">Example: Content Refinement</h4>
+  <p className="text-sm text-gray-600 dark:text-gray-400 mb-2">
+    Create a loop where an Agent block generates content, an Evaluator block assesses it, and a Function block decides whether to continue refining.
+  </p>
+  <ol className="text-sm list-decimal pl-5">
+    <li>Agent generates initial content</li>
+    <li>Evaluator scores the content</li>
+    <li>Function analyzes score and provides feedback</li>
+    <li>Loop back to Agent with feedback for improvement</li>
+    <li>Continue until quality threshold is reached</li>
+  </ol>
+</div>
+
+### Batch Processing
+
+<div className="p-4 border rounded-md mb-4">
+  <h4 className="font-medium">Example: Data Processing Pipeline</h4>
+  <p className="text-sm text-gray-600 dark:text-gray-400 mb-2">
+    Process a collection of items one at a time through a series of blocks.
+  </p>
+  <ol className="text-sm list-decimal pl-5">
+    <li>Function block extracts the next item from a collection</li>
+    <li>Processing blocks operate on the single item</li>
+    <li>Results are accumulated in a Memory block</li>
+    <li>Loop continues until all items are processed</li>
+  </ol>
+</div>
+
+### Recursive Problem Solving
+
+<div className="p-4 border rounded-md mb-4">
+  <h4 className="font-medium">Example: Multi-step Reasoning</h4>
+  <p className="text-sm text-gray-600 dark:text-gray-400 mb-2">
+    Implement a recursive approach to complex problem solving.
+  </p>
+  <ol className="text-sm list-decimal pl-5">
+    <li>Agent analyzes the current problem state</li>
+    <li>Function block implements a step in the solution</li>
+    <li>Condition block checks if the problem is solved</li>
+    <li>Loop continues until solution is found or maximum steps reached</li>
+  </ol>
+</div>
+
+## Best Practices for Loops
+
+To use loops effectively in your workflows:
+
+- **Set Appropriate Limits**: Always configure reasonable iteration limits
+- **Use Memory Blocks**: Store state between iterations with Memory blocks
+- **Include Exit Conditions**: Define clear conditions for when loops should terminate
+- **Monitor Performance**: Watch for performance impacts with many iterations
+- **Test Thoroughly**: Verify that loops terminate as expected in all scenarios
+
+<Callout type="warning">
+  Loops with many blocks or complex operations can impact performance. Consider optimizing individual blocks if your loops need many iterations.
+</Callout>
+
+## Loop Debugging
+
+When debugging loops in your workflows:
+
+- **Check Iteration Counts**: Verify the loop is executing the expected number of times
+- **Inspect Block Inputs/Outputs**: Look at how data changes between iterations
+- **Review Loop Conditions**: Ensure conditions are evaluating as expected
+- **Use Console Logging**: Add console.log statements in Function blocks to track loop progress
+- **Monitor Memory Usage**: Watch for growing data structures that might cause performance issues
+
+By mastering loops, you can create much more sophisticated and powerful workflows in Sim Studio. 

docs/content/docs/execution/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Execution",
+  "pages": ["basics", "loops", "advanced"]
+}