rename approval to human in the loop

Author: waleed

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

@@ -0,0 +1,344 @@
+---
+title: Human in the Loop
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Step, Steps } from 'fumadocs-ui/components/steps'
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+import { Image } from '@/components/ui/image'
+
+The Human in the Loop block pauses workflow execution and waits for human intervention before continuing. Use it to add approval gates, collect feedback, enable manual review, or gather additional input at critical decision points in your workflow.
+
+<div className="flex justify-center">
+  <Image
+    src="/static/blocks/hitl-1.png"
+    alt="Human in the Loop Block Configuration"
+    width={500}
+    height={400}
+    className="my-6"
+  />
+</div>
+
+<Callout type="info">
+  When execution reaches this block, the workflow pauses and waits indefinitely until a human approver provides input or approval through one of the available interfaces.
+</Callout>
+
+## Overview
+
+The Human in the Loop block enables you to:
+
+<Steps>
+  <Step>
+    <strong>Pause Workflow Execution</strong>: Stop the workflow at a critical point and wait for human input
+  </Step>
+  <Step>
+    <strong>Display Context</strong>: Show relevant workflow data to the approver for informed decision-making
+  </Step>
+  <Step>
+    <strong>Collect Feedback</strong>: Gather approval decisions, comments, edits, or additional data from humans
+  </Step>
+  <Step>
+    <strong>Notify Stakeholders</strong>: Send alerts via Slack, Gmail, or other channels when approval is needed
+  </Step>
+  <Step>
+    <strong>Resume with Input</strong>: Continue workflow execution with the human-provided data
+  </Step>
+</Steps>
+
+## How It Works
+
+The Human in the Loop block creates a pause-and-resume flow:
+
+1. **Workflow Pauses** - Execution stops when it reaches the Human in the Loop block
+2. **Context Displayed** - Configured data is shown to the approver through the approval portal
+3. **Notifications Sent** - Alerts are dispatched via configured channels (Slack, email, etc.)
+4. **Human Reviews** - Approver examines the data and provides input or approval
+5. **Workflow Resumes** - Execution continues with the human-provided data available to downstream blocks
+
+<div className="flex justify-center">
+  <Image
+    src="/static/blocks/hitl-2.png"
+    alt="Human in the Loop Approval Portal"
+    width={700}
+    height={500}
+    className="my-6"
+  />
+</div>
+
+## Configuration Options
+
+### Paused Output
+
+The Paused Output defines what data is displayed to the approver when the workflow pauses. Think of this as the "context" you're providing to help them make an informed decision.
+
+**Use Cases:**
+- Display extracted data for verification: "Is this customer information correct?"
+- Show AI-generated content for approval: "Review this email draft before sending"
+- Present analysis results for validation: "Confirm these findings before proceeding"
+- Expose workflow variables for review: "Check these values before final processing"
+
+**Configuration:**
+Use the visual builder or JSON editor to define the structure of data shown to approvers. Reference workflow variables using `<blockName.output>` syntax.
+
+```json
+{
+  "customerName": "<agent1.content.name>",
+  "proposedAction": "<router1.selectedPath>",
+  "confidenceScore": "<evaluator1.score>",
+  "generatedEmail": "<agent2.content>"
+}
+```
+
+### Notification
+
+The Notification section configures how approvers are alerted when the workflow pauses and requires their attention.
+
+**Supported Channels:**
+- **Slack**: Send messages to channels or direct messages with approval links
+- **Gmail**: Email approvers with context and links to the approval portal
+- **Microsoft Teams**: Notify team members through Teams channels
+- **Custom Webhooks**: Trigger your own notification systems
+- **SMS**: Send text message alerts via Twilio
+
+**Configuration:**
+Add notification tools and configure them with the relevant details:
+- For Slack: Select channel and compose message with approval link
+- For Gmail: Specify recipients, subject, and email body
+- For Teams: Choose team and channel for notifications
+
+<Callout type="tip">
+  Include the approval URL (`<approval1.url>`) in your notification messages so approvers can quickly access the approval portal.
+</Callout>
+
+### Resume Input
+
+The Resume Input defines what fields the approver can fill in when reviewing the paused workflow. This is the data that will be collected from the human and made available to downstream blocks.
+
+**Use Cases:**
+- **Binary Approval**: Simple approved/rejected boolean field
+- **Feedback Collection**: Text field for comments or explanations
+- **Data Editing**: Fields for modifying AI-generated content
+- **Multi-field Forms**: Complex approval forms with multiple input types
+
+**Configuration:**
+Define input fields with names, types, and validation rules:
+
+```json
+{
+  "approved": {
+    "type": "boolean",
+    "description": "Approve or reject this request"
+  },
+  "comments": {
+    "type": "string",
+    "description": "Optional feedback or explanation"
+  },
+  "modifiedEmail": {
+    "type": "string",
+    "description": "Edit the email content if needed"
+  }
+}
+```
+
+**Accessing Resume Data:**
+After the workflow resumes, access the human-provided input using `<approval1.resumeInput.fieldName>` in downstream blocks.
+
+## Approval Methods
+
+The Human in the Loop block supports multiple ways for approvers to interact with paused workflows:
+
+<Tabs items={['Approval Portal', 'API', 'Webhook']}>
+  <Tab>
+    ### Approval Portal (Web UI)
+    
+    Every Human in the Loop block generates a unique approval portal URL accessible via the `url` output.
+    
+    **Features:**
+    - Visual interface showing all Paused Output data
+    - Form fields for Resume Input
+    - Mobile-responsive design
+    - Secure, time-limited access
+    
+    **Usage:**
+    ```
+    Access URL: <approval1.url>
+    ```
+    
+    Share this URL in notifications or embed it in your application for approvers to review and respond.
+  </Tab>
+  <Tab>
+    ### REST API
+    
+    Programmatically resume workflows by calling the approval API endpoint.
+    
+    **Endpoint:**
+    ```bash
+    POST /api/workflows/{workflowId}/executions/{executionId}/resume/{blockId}
+    Content-Type: application/json
+    
+    {
+      "approved": true,
+      "comments": "Looks good to proceed",
+      "modifiedEmail": "Updated email content..."
+    }
+    ```
+    
+    **Use Cases:**
+    - Build custom approval UIs
+    - Integrate with existing approval systems
+    - Automate approvals based on external logic
+  </Tab>
+  <Tab>
+    ### Webhook Listener
+    
+    Configure external systems to listen for approval requests via webhooks.
+    
+    **Setup:**
+    1. Add a webhook tool to the Notification section
+    2. Configure your webhook endpoint
+    3. Receive approval request payloads
+    4. Respond to resume the workflow
+    
+    **Use Cases:**
+    - Integrate with ticketing systems (Jira, ServiceNow)
+    - Connect to approval workflow platforms
+    - Build custom notification pipelines
+  </Tab>
+</Tabs>
+
+## Common Use Cases
+
+### Content Approval Workflow
+
+Pause before publishing AI-generated content:
+
+```
+Agent (Generate) → Human in the Loop (Review) → API (Publish)
+```
+
+**Paused Output:** Generated article, metadata, SEO analysis  
+**Resume Input:** approved (boolean), edits (text), publishDate (date)
+
+### Multi-Stage Approval Pipeline
+
+Require multiple approvals for high-stakes decisions:
+
+```
+Agent (Analyze) → Human in the Loop (Manager) → Human in the Loop (Director) → API (Execute)
+```
+
+**Use Case:** Financial transactions, contract approvals, policy changes
+
+### Data Validation Gate
+
+Verify extracted data before processing:
+
+```
+Agent (Extract) → Human in the Loop (Validate) → Function (Process) → Database (Store)
+```
+
+**Paused Output:** Extracted fields from documents  
+**Resume Input:** confirmed (boolean), corrections (object)
+
+### Quality Control Check
+
+Review AI outputs before sending to customers:
+
+```
+Agent (Generate Response) → Human in the Loop (QA) → Gmail (Send)
+```
+
+**Paused Output:** Generated email, customer context  
+**Resume Input:** approved (boolean), modifications (text)
+
+## Block Outputs
+
+The Human in the Loop block provides the following outputs:
+
+**`url`** (string)  
+The unique URL for the approval portal where humans can review and respond to the paused workflow.
+
+**`resumeInput.*`** (dynamic)  
+All fields defined in the Resume Input section become available as outputs after the workflow resumes. Access them using `<blockId.resumeInput.fieldName>`.
+
+## Best Practices
+
+<Steps>
+  <Step>
+    <strong>Provide Clear Context</strong>: Include all relevant data in Paused Output so approvers can make informed decisions
+  </Step>
+  <Step>
+    <strong>Use Multiple Notification Channels</strong>: Don't rely on a single notification method—add Slack and email for redundancy
+  </Step>
+  <Step>
+    <strong>Set Timeout Policies</strong>: Consider adding workflow-level timeouts to handle abandoned approvals
+  </Step>
+  <Step>
+    <strong>Include Instructions</strong>: Add description fields to Resume Input to guide approvers
+  </Step>
+  <Step>
+    <strong>Track Approval History</strong>: Log approval decisions and comments for audit trails
+  </Step>
+  <Step>
+    <strong>Test Portal Access</strong>: Verify that approvers can access the portal URL from their devices
+  </Step>
+</Steps>
+
+<Callout type="warning">
+  Paused workflows consume execution state resources. Implement timeout mechanisms or periodic cleanup for abandoned approvals to avoid accumulating paused executions.
+</Callout>
+
+## Example Configuration
+
+Here's a complete example of a Human in the Loop block configured for content approval:
+
+**Paused Output:**
+```json
+{
+  "title": "<agent1.content.title>",
+  "body": "<agent1.content.body>",
+  "targetAudience": "<router1.selectedPath>",
+  "qualityScore": "<evaluator1.score>",
+  "generatedAt": "<function1.output.timestamp>"
+}
+```
+
+**Notification:**
+- **Slack**: Channel: #content-review, Message: "New article ready for review: `<approval1.url>`"
+- **Gmail**: To: editors@company.com, Subject: "Article Approval Required"
+
+**Resume Input:**
+```json
+{
+  "decision": {
+    "type": "boolean",
+    "description": "Approve this article for publication?"
+  },
+  "feedback": {
+    "type": "string",
+    "description": "Provide feedback or request changes"
+  },
+  "publishDate": {
+    "type": "string",
+    "description": "Scheduled publish date (YYYY-MM-DD)"
+  }
+}
+```
+
+**Downstream Usage:**
+```javascript
+// In a Condition block:
+if (<approval1.resumeInput.decision> === true) {
+  // Proceed to publish
+} else {
+  // Route to revision workflow
+}
+```
+
+## Related Blocks
+
+- **[Response](/blocks/response)**: Return workflow results to API callers
+- **[Condition](/blocks/condition)**: Branch based on approval decisions
+- **[Variables](/blocks/variables)**: Store approval history and metadata
+- **[Wait](/blocks/wait)**: Add time delays before or after approvals
+

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

@@ -31,6 +31,7 @@ Sim provides essential block types that handle the core functions of AI workflow
 ### Control Flow Blocks
 - **[Variables](/blocks/variables)** - Set and manage workflow-scoped variables
 - **[Wait](/blocks/wait)** - Pause workflow execution for a specified time delay
+- **[Human in the Loop](/blocks/human-in-the-loop)** - Pause for human approval and feedback before continuing
 
 ### Output Blocks
 - **[Response](/blocks/response)** - Format and return final results from your workflow
@@ -127,6 +128,9 @@ Each block type has specific configuration options:
   <Card title="Condition Block" href="/blocks/condition">
     Create branching logic based on data evaluation
   </Card>
+  <Card title="Human in the Loop Block" href="/blocks/human-in-the-loop">
+    Pause for human approval and feedback before continuing
+  </Card>
   <Card title="Variables Block" href="/blocks/variables">
     Set and manage workflow-scoped variables
   </Card>

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

@@ -7,6 +7,7 @@
     "evaluator",
     "function",
     "guardrails",
+    "human-in-the-loop",
     "loop",
     "parallel",
     "response",