@mudlab/create-workflow 1.0.0

package/template/CLAUDE.md

@@ -0,0 +1,947 @@
+You operate within a 3-layer architecture that separates concerns to maximize reliability. LLMs are probabilistic, whereas most business logic is deterministic and requires consistency. This system fixes that mismatch.
+
+## The 3-Layer Architecture
+
+**Layer 1: Directive (What to do)**
+- SOPs written in Markdown, live in `directives/`
+- Define the goals, inputs, tools/scripts to use, outputs, and edge cases
+- Natural language instructions, like you'd give a mid-level employee
+
+**Layer 2: Orchestration (Decision making)**
+- This is you. Your job: intelligent routing.
+- Read directives, call execution tools in the right order, handle errors, ask for clarification, update directives with learnings
+- You're the glue between intent and execution
+
+**Layer 3: Execution (Doing the work)**
+- Deterministic Node.js scripts in `execution/`
+- Environment variables, API tokens, etc. stored in `.env`
+- Handle API calls, data processing, file operations
+- Reliable, testable, fast. Use scripts instead of manual work.
+
+**Why this works:** if you do everything yourself, errors compound. 90% accuracy per step = 59% success over 5 steps. Push complexity into deterministic code so you can focus on decision-making.
+
+## Operating Principles
+
+**1. Check directives first, then tools**
+Before doing ANYTHING manually, check `directives/` for an SOP that covers the request. The directive tells you which tools to run and in what order.
+
+- User asks to "add a lead"? Check `directives/new_lead.md` for the workflow steps.
+- User asks to send an email? Check if there's a directive, then find the tool.
+- User asks about capabilities? Check what directives and tools exist.
+
+**Execution flow:**
+1. Find the relevant directive (SOP) in `directives/`
+2. Read the ENTIRE directive — identify ALL steps and ALL required inputs
+3. Before executing anything, check if you have all required inputs for ALL steps
+4. If any required input is missing, ask the user for it upfront
+5. Execute ALL steps in order, running each tool locally with Node.js from `execution/tools/`
+6. If no directive exists, check `execution/tools/` for a standalone tool
+7. Only use manual approaches (curl, direct API calls) if no tool exists
+
+**Critical:** Never execute a partial workflow. If a directive has 3 steps, you must complete all 3. If you can't complete a step due to missing information, ask before starting — don't do half the job and stop.
+
+**Important:** Do NOT read `execution/workflows/*.json` files when executing tasks. Workflow JSON files are **only** for creating and pushing workflows to Mudlab. For local execution, you only need:
+- `directives/` — to understand what to do
+- `execution/tools/` — to run the actual code
+
+**2. Self-anneal when things break**
+- Read error message and stack trace
+- Fix the script and test it again (unless it uses paid tokens/credits—check w/ user first)
+- Update the directive with what you learned (API limits, timing, edge cases)
+
+**3. Update directives as you learn**
+Directives are living documents. When you discover API constraints, better approaches, common errors—update the directive. But don't create or overwrite directives without asking unless explicitly told to.
+
+## Self-annealing Loop
+
+Errors are learning opportunities. When something breaks:
+1. Fix it
+2. Update the tool
+3. Test tool, make sure it works
+4. Validate output compliance (see checklist below)
+5. Update directive to include new flow
+6. **If it's a structural change (new patterns, schema changes, conventions), update CLAUDE.md**
+7. System is now stronger
+
+**Update Checklist — ALWAYS update ALL connected files:**
+
+When you change ANY part of a workflow, you MUST update ALL of these:
+
+| If you change... | Also update... |
+|------------------|----------------|
+| Tool code (`execution/tools/*.js`) | Tool directive, workflow JSON (outputs), workflow directive |
+| Tool inputs/outputs | Workflow JSON (inputs, outputs, config), workflow directive (Inputs table, Example) |
+| Workflow step config | Workflow directive (Trigger, Inputs, Example sections) |
+| Workflow JSON | Workflow directive (must match exactly) |
+
+**Connected files for each workflow:**
+1. `execution/tools/<tool>.js` — the actual code
+2. `execution/tools_directives/<tool>.md` — AI usage instructions for the tool
+3. `execution/workflows/<workflow>.json` — workflow package (inputs, steps, config)
+4. `directives/<workflow>.md` — user-facing documentation (Trigger, Inputs, Example)
+
+**Critical rule:** The workflow directive's Trigger/Inputs/Example sections must EXACTLY match what the workflow JSON expects. If they don't match, the frontend will break.
+
+**Tool Output Validation Checklist:**
+When testing tools, verify each one follows the output object rules:
+- [ ] Tool definition has `running_message` - shown during execution (e.g., `"Sending email to $input.to..."`)
+- [ ] Returns an object (not primitive like `true`, `"success"`, `null`)
+- [ ] Includes action taken (e.g., `action: "sent"`, `action: "inserted"`)
+- [ ] Includes `message` - human-readable success message for logging (e.g., `"Sent email to john@example.com"`)
+- [ ] Includes relevant identifiers (IDs, timestamps, message IDs)
+- [ ] Summarizes what was affected (records, fields, recipients)
+- [ ] Errors include context about what failed and why
+
+**When to update CLAUDE.md:**
+- New structural patterns emerge (directive sections, tool conventions)
+- Schema changes (input types, workflow fields)
+- New integrations or API endpoints
+- Process improvements discovered through use
+
+## File Organization
+
+**Directory structure:**
+- `.tmp/` - Intermediate files (temp data, exports). Never commit, always regenerated.
+- `execution/` - Node.js scripts (the deterministic tools)
+  - `execution/tools/` - Individual tool functions for Mudlab
+  - `execution/tools_directives/` - Markdown files with AI usage instructions for tools
+  - `execution/workflows/` - Workflow package definitions (JSON)
+- `directives/` - Markdown files: SOPs (for orchestrator) and workflow directives (pushed to Mudlab UI)
+- `.env` - Environment variables and API keys
+- `assets/` - Static assets (logos, templates)
+
+**Key principle:** Local files are for processing. Deliverables live in cloud services or your Mudlab application.
+
+## Directive Structure
+
+Every workflow directive (`directives/*.md`) should include these sections:
+
+```markdown
+# Workflow Name
+
+Brief description of what the workflow does.
+
+## Prerequisites
+
+Step-by-step setup instructions to complete BEFORE pushing/testing the workflow:
+- API key acquisition (with links to where to get them)
+- External service configuration (database setup, integration permissions, etc.)
+- Environment variables to add to Mudlab
+
+This section ensures the user has everything ready before testing.
+
+## Trigger
+
+How to call this workflow via webhook:
+
+\`\`\`
+POST https://mudlab.io/api/webhooks/{webhook_id}
+Content-Type: application/json
+
+{
+  "field1": "value1",
+  "field2": "value2"
+}
+\`\`\`
+
+## Inputs
+
+| Field | Type | Label | Source | Default | Description |
+|-------|------|-------|--------|---------|-------------|
+| `field1` | string | Field 1 | input | - | Description |
+
+## Workflow Steps
+
+| Step | Tool | Required Inputs | Description |
+|------|------|-----------------|-------------|
+| 1. Step Name | `tool_name` | field1, field2 | What this step does |
+| 2. Step Name | `other_tool` | field3, (step1.output) | What this step does |
+
+**Note:** Steps are executed in order. If a step uses output from a previous step, indicate it with `(stepN.output)`.
+
+## Outputs
+
+| Field | Description |
+|-------|-------------|
+| `step1.action` | Action taken |
+| `step1.result` | The result data |
+
+## Example
+
+**Request:**
+\`\`\`
+POST https://mudlab.io/api/webhooks/wh_abc123
+Content-Type: application/json
+
+{ ... }
+\`\`\`
+
+**Response:**
+\`\`\`json
+{ ... }
+\`\`\`
+```
+
+**Required sections:**
+- **Workflow Scope** - Clear boundaries defining what this workflow is and is NOT for (see below)
+- **Prerequisites** - Step-by-step setup: API keys, external service config, env vars (complete BEFORE testing)
+- **Trigger** - Show the webhook URL pattern and expected request body
+- **Inputs** - Table of all input fields with types and sources
+- **Workflow Steps** - Table listing each step, its tool, required inputs, and description
+- **Outputs** - Table of output fields returned by the workflow
+- **Example** - Full request/response example
+
+## Workflow Scope (Required Section)
+
+Every workflow directive MUST include a **Workflow Scope** section immediately after the description. This section prevents workflow scope creep and ensures the AI uses workflows only for their intended purpose.
+
+**Why this matters:** AI can creatively reinterpret workflow purposes. A "New Lead" workflow might get used for bug reports, feedback, or test data if boundaries aren't explicit. Each workflow has ONE business function — enforce it.
+
+### Required Subsections
+
+```markdown
+## Workflow Scope
+
+### What This Workflow Is For
+
+This workflow is **exclusively** for [SPECIFIC PURPOSE]:
+
+- [Specific use case 1]
+- [Specific use case 2]
+- [Specific use case 3]
+
+[Brief explanation of what qualifies as valid input for this workflow]
+
+### What This Workflow Is NOT For
+
+**Do NOT use this workflow for:**
+
+| Invalid Use Case | Why It's Wrong | What To Use Instead |
+|------------------|----------------|---------------------|
+| [Invalid use 1] | [Explanation] | [Alternative workflow] |
+| [Invalid use 2] | [Explanation] | [Alternative workflow] |
+
+### Consequences of Misuse
+
+If you route invalid data through this workflow:
+- [Consequence 1 - e.g., database pollution]
+- [Consequence 2 - e.g., wasted team effort]
+- [Consequence 3 - e.g., broken metrics]
+
+### Proper vs Improper Usage
+
+**CORRECT** — Use this workflow when:
+\`\`\`json
+// [Description of valid input]
+{ "field": "valid_value" }
+\`\`\`
+
+**INCORRECT** — Do NOT use this workflow when:
+\`\`\`json
+// [Description of invalid input] (use [alternative] instead)
+{ "field": "invalid_value" }
+\`\`\`
+
+**AI Instruction:** [Clear directive for AI behavior when encountering edge cases]
+```
+
+### Key Principles
+
+1. **Be explicit about purpose** — Don't just say "captures leads." Say "captures SALES leads — potential customers who might buy from you."
+
+2. **List what it's NOT for** — The table format forces you to think through common misuse cases and provide alternatives.
+
+3. **Show consequences** — Explain what goes wrong when the workflow is misused (database pollution, wasted effort, broken metrics).
+
+4. **Provide examples** — Concrete JSON examples of valid vs invalid inputs remove ambiguity.
+
+5. **Include AI instructions** — Tell the AI explicitly what to do when it encounters edge cases: "If the data doesn't represent a genuine sales prospect, reject the request and suggest the appropriate workflow."
+
+### Example: New Lead Workflow Scope
+
+```markdown
+## Workflow Scope
+
+### What This Workflow Is For
+
+This workflow is **exclusively** for capturing **sales leads** — potential customers who have expressed interest in your product:
+
+- Contact forms on landing pages
+- "Request a demo" submissions
+- Newsletter signups from prospects
+
+A sales lead is someone who **might buy from you**.
+
+### What This Workflow Is NOT For
+
+| Invalid Use Case | Why It's Wrong | What To Use Instead |
+|------------------|----------------|---------------------|
+| Bug reports | Not a sales lead | Bug tracking workflow |
+| Customer support | Existing customers, not prospects | Support ticket workflow |
+| Test data | Pollutes leads database | Use sandbox environment |
+
+### Consequences of Misuse
+
+- Leads database polluted with non-sales entries
+- Sales team wastes time on irrelevant items
+- Conversion metrics become meaningless
+
+### Proper vs Improper Usage
+
+**CORRECT:**
+\`\`\`json
+{ "name": "Jane Smith", "email": "jane@acme.com", "phone": "+1-555-1234" }
+\`\`\`
+
+**INCORRECT:**
+\`\`\`json
+{ "name": "Bug Report", "email": "user@example.com", "phone": "Login broken" }
+\`\`\`
+
+**AI Instruction:** If the data doesn't represent a sales prospect, reject and suggest the correct workflow.
+```
+
+## Running Tools Locally
+
+When the user asks you to perform an action, **run tools directly with Node.js**—do NOT call the Mudlab API.
+
+```javascript
+node -e "
+const { run } = require('./execution/tools/tool_name.js');
+run({
+  input: { /* tool inputs + env vars from .env */ },
+  env: {},
+  context: {}
+}).then(r => console.log(JSON.stringify(r, null, 2)))
+  .catch(e => console.error('Error:', e.message));
+"
+```
+
+- Load credentials from `.env` and pass them in the `input` object (tools expect env vars in `input`, not `env`)
+- Follow the directive's workflow steps, running each tool in sequence
+- This is how you test and execute workflows locally
+
+## Mudlab Integration
+
+Mudlab is for **pushing only**—you push tools and workflows so they can run in production via webhooks. Do NOT call the Mudlab API to execute workflows locally.
+
+**When to use Mudlab API:** Only when the user explicitly says "push this workflow to Mudlab"
+
+### Tool Structure
+
+Tools are Node.js functions that follow this signature:
+
+```javascript
+async function run({ input, env, context }) {
+  // input   = data from previous steps or trigger
+  // env     = decrypted environment variables
+  // context = { user_id, client_id, workflow_id, step_id }
+
+  return {
+    // named output fields
+  };
+}
+
+module.exports = { run };
+```
+
+### Accessing Environment Variables in Tools
+
+When a tool input has `source: "env"`, Mudlab resolves the user's selected env var and passes it into the `input` object (not just `env`). Tools must access env vars from `input` first, with a fallback to `env` for backwards compatibility.
+
+**Pattern:**
+```javascript
+async function run({ input, env, context }) {
+  // Destructure env vars from input alongside regular inputs
+  const { name, email, MY_API_KEY, MY_SECRET } = input;
+
+  // Fall back to raw env object for backwards compatibility
+  const apiKey = MY_API_KEY || env.MY_API_KEY;
+  const secret = MY_SECRET || env.MY_SECRET;
+
+  if (!apiKey) {
+    throw new Error("Missing MY_API_KEY - ensure it is selected in the tool's env var dropdown");
+  }
+  // ...
+}
+```
+
+**Why this matters:**
+- Inputs with `source: "env"` are resolved by Mudlab before execution
+- The resolved value is placed in `input`, not `env`
+- Accessing only `env.VAR_NAME` will fail because the UI dropdown selection isn't reflected there
+- Error messages should guide users to check the env var dropdown in the UI
+
+**Workflow JSON must define env var inputs:**
+```json
+{
+  "inputs": [
+    {
+      "name": "MY_API_KEY",
+      "type": "string",
+      "label": "API Key",
+      "source": "env",
+      "required": true
+    }
+  ]
+}
+```
+
+### Tool Output Requirements
+
+Every tool MUST return structured data for the execution terminal display. The terminal shows Input, Output, and Error for each tool execution in real-time.
+
+**Rules:**
+- Always return an output object - even for side-effect tools (sending email, posting to Slack, writing to database)
+- Output should be informative - include details that confirm the action succeeded and what was affected
+- Errors must be descriptive - include context about what failed and why
+
+**Output Format Guidelines:**
+- Return objects, not primitives (no bare `true`, `"success"`, etc.)
+- Include `message` - a human-readable success message for logging (required)
+- Include identifiers (IDs, timestamps, message IDs)
+- Summarize what was done (action taken, records affected)
+- For fetches/reads, return the relevant data
+- Keep outputs concise but complete
+
+**The `message` field:**
+Every tool output MUST include a `message` field with a human-readable success message. This is used for logging and helps users understand what the tool accomplished.
+
+- Use present tense, active voice (e.g., "Sent email to..." not "Email was sent to...")
+- Include key identifiers from the operation (names, emails, IDs)
+- Keep it concise but informative (one sentence)
+
+Examples:
+- `"Added lead 'John Doe' to Notion database"`
+- `"Sent email to john@example.com"`
+- `"Generated random number 42 between 1 and 100"`
+
+**Examples:**
+
+Bad (email tool):
+```javascript
+await sendEmail(to, subject, body)
+// Returns nothing
+```
+
+Good (email tool):
+```javascript
+await sendEmail(to, subject, body)
+return {
+  action: "sent",
+  message: `Sent email to ${to}`,
+  sent_to: to,
+  subject: subject,
+  timestamp: new Date().toISOString(),
+  message_id: response.id
+}
+```
+
+Bad (database write):
+```javascript
+await db.insert(record)
+// No return
+```
+
+Good (database write):
+```javascript
+const result = await db.insert(record)
+return {
+  action: "inserted",
+  message: `Inserted record ${result.id} into users table`,
+  table: "users",
+  id: result.id,
+  fields_updated: Object.keys(record)
+}
+```
+
+### Workflow Package
+
+A workflow package bundles tools + workflow definition. Every workflow **must** have an associated directive file that explains what the workflow does (shown in Mudlab UI).
+
+```json
+{
+  "id": null,
+  "name": "My Workflow",
+  "description": "What it does",
+  "running_message": "Processing '$trigger.input.name'...",
+  "success_message": "Completed action for '$trigger.input.name'",
+  "directive_file": "directives/my_workflow.md",
+  "tools": [
+    {
+      "id": null,
+      "tool_id": "my_tool",
+      "name": "My Tool",
+      "description": "What the tool does",
+      "directive_file": "execution/tools_directives/my_tool.md",
+      "running_message": "Updating records for '$input.field1'...",
+      "success_message": "Updated records for '$input.field1'",
+      "code_file": "execution/tools/my_tool.js",
+      "inputs": [
+        {
+          "name": "field1",
+          "type": "string",
+          "label": "Field 1",
+          "placeholder": "Enter value",
+          "description": "What this field does",
+          "source": "input",
+          "required": true
+        }
+      ],
+      "outputs": ["result", "message"]
+    }
+  ],
+  "steps": [
+    {
+      "step_id": "step1",
+      "tool_id": "my_tool",
+      "depends_on": [],
+      "config": { "field1": "$trigger.input.data" }
+    }
+  ]
+}
+```
+
+**ID Fields:**
+- `id` (workflow and each tool) starts as `null`
+- After first push, the API returns UUIDs which are written back to the JSON
+- On subsequent pushes, existing `id` values trigger updates instead of creates
+- `tool_id` is a human-readable unique identifier (e.g., `"random_number"`) - different from the UUID `id`
+
+**Running Message (Workflow):**
+Every workflow MUST have a `running_message` field - displayed while the workflow is executing. This field supports template variables using `$trigger.input.field`:
+
+Examples:
+- `"Creating lead '$trigger.input.name'..."`
+- `"Generating random number..."`
+- `"Processing order $trigger.input.order_id..."`
+
+**Running Message (Tool):**
+Every tool definition MUST have a `running_message` field - displayed while the tool is executing. This field supports template variables using `$input.field` (referencing the tool's inputs):
+
+Examples:
+- `"Adding lead '$input.name' to Notion..."`
+- `"Sending email to $input.to..."`
+- `"Generating number between $input.min and $input.max..."`
+
+**Directive (Tool):**
+Tools have an optional `directive_file` field that points to a Markdown file containing usage instructions for the AI orchestrator. This is separate from `description` (which explains what the tool does) — the directive explains **how to use it properly**.
+
+| Field | Purpose | Example |
+|-------|---------|---------|
+| `description` | Brief explanation of what the tool does | "Sends an email via Resend API" |
+| `directive_file` | Path to Markdown file with usage instructions | `"execution/tools_directives/send_email_resend.md"` |
+
+Tool directives live in `execution/tools_directives/` and follow the same pattern as workflow directives — the push script reads the file and sends the content to the API.
+
+**When to add a directive:**
+**Always create a tool directive when creating or updating a workflow.** Every tool should have a corresponding directive file in `execution/tools_directives/`. Include:
+- **Input constraints** — validation rules, required formats, value ranges
+- **Output details** — what gets returned and when
+- **Formatting requirements** — plain text vs HTML vs markdown (for content tools)
+- **Best practices** — tone, structure, common mistakes to avoid
+- **Edge cases** — what to do when certain inputs are missing
+- **Common use cases** — help the AI understand when to use this tool
+
+**Example directive file (`execution/tools_directives/send_email_resend.md`):**
+
+```markdown
+## Formatting
+- Body supports HTML but not Markdown syntax
+- Do not use emojis unless the user explicitly requests them
+- Write in flowing prose, not bullet points (unless the user asks for bullets)
+
+## Subject Lines
+- Keep under 60 characters
+- Be specific and actionable
+
+## Common Mistakes
+- Don't use **bold** or *italic* markdown — these render as literal asterisks in plain text
+- If using HTML, use proper tags like <strong> and <em>
+```
+
+**How it works:**
+When the workflow is pushed, the push script reads each tool's `directive_file` and includes the content in the API payload. The directive is stored in the database and injected into the AI's system prompt under a "Tool Usage Guidelines" section.
+
+**Success Message (Workflow):**
+Every workflow MUST have a `success_message` field - a human-readable message logged when the workflow completes successfully. This field supports template variables:
+
+| Pattern | Description |
+|---------|-------------|
+| `$trigger.input.field` | Input from workflow trigger |
+| `$step_id.output.field` | Output from a completed step |
+
+Examples:
+- `"Created lead '$trigger.input.name' and sent notification"`
+- `"Generated random number $generate.output.number"`
+- `"Processed order $trigger.input.order_id for $trigger.input.customer_name"`
+
+**Success Message (Tool):**
+Every tool definition MUST have a `success_message` field - a human-readable message logged when the tool completes successfully. This field supports template variables using `$input.field` (referencing the tool's inputs):
+
+Examples:
+- `"Added lead '$input.name' to Notion"`
+- `"Sent email to $input.to"`
+- `"Generated random number between $input.min and $input.max"`
+
+Additionally, every tool output MUST include a `message` field in the return object (see Tool Output Requirements above). The `success_message` template is used for consistent logging, while the returned `message` provides runtime-specific details.
+
+### Pushing Workflows
+
+```bash
+# Single workflow
+node execution/push_workflow.js execution/workflows/my_workflow.json
+
+# Multiple workflows (bulk mode - single API call)
+node execution/push_workflow.js execution/workflows/workflow_a.json execution/workflows/workflow_b.json
+
+# All workflows via glob
+node execution/push_workflow.js execution/workflows/*.json
+```
+
+This will:
+1. Read each tool's code from `code_file`
+2. Read directive markdown from `directive_file`
+3. For each tool: check if `id` exists → update or create
+4. For workflow: check if `id` exists → update or create
+5. Write returned UUIDs back to the JSON file(s)
+6. Log results to `.tmp/pushed_workflows.json`
+
+**Single vs Bulk:**
+- Single file: sends object payload, returns `{ success, workflow, tools }`
+- Multiple files: sends array payload, returns bulk response format (see below)
+- Bulk mode uses a single API call with parallel processing (Promise.allSettled)
+
+**Bulk Response Format:**
+```json
+{
+  "success": false,
+  "results": [
+    { "success": true, "workflow": { "id": "...", "name": "Workflow A" }, "tools": [...] },
+    { "success": false, "workflow_name": "Workflow B", "error": "Tool missing code", "details": "..." }
+  ],
+  "summary": { "total": 2, "succeeded": 1, "failed": 1 },
+  "workflows": [ /* only successes - convenience array */ ],
+  "errors": [ /* only failures with workflow_name, error, details */ ]
+}
+```
+
+**HTTP Status Codes (bulk):**
+- `200` - All workflows succeeded
+- `207 Multi-Status` - Partial success (some failed, some succeeded)
+- `400/500` - Request or server error
+
+**Behavior:**
+- All workflows processed in parallel (independent - one failure doesn't affect others)
+- `errors` array makes it easy to see what failed and why
+
+**First push** (all `id` fields are `null`):
+- Creates new tools and workflow in the database
+- Writes UUIDs back to your JSON file
+
+**Subsequent pushes** (with `id` values):
+- Updates existing tools and workflow
+- Increments version numbers automatically
+
+### API Endpoints
+
+| Action | Endpoint | Description |
+|--------|----------|-------------|
+| Push Workflow | `POST /api/push-workflow` | Bulk create/update tools + workflow (preferred) |
+| Get Tool | `GET /api/tools/:id` | Check if tool exists by UUID |
+| Create Tool | `POST /api/tools` | Create a single tool |
+| Update Tool | `PUT /api/tools/:id` | Update existing tool (auto-versions) |
+| Get Workflow | `GET /api/workflows/:id` | Check if workflow exists by UUID |
+| Create Workflow | `POST /api/workflows` | Create workflow from steps |
+| Update Workflow | `PUT /api/workflows/:id` | Update existing workflow |
+| Run Workflow | `POST /api/run` | Execute a workflow |
+
+### Input Schema
+
+Tool inputs use structured objects so the frontend can auto-generate forms:
+
+```json
+{
+  "name": "string",        // Variable name used in code (snake_case)
+  "type": "string",        // "string" | "number" | "boolean" | "object" | "array"
+  "label": "string",       // User-readable label for UI (e.g., "Stripe API Key")
+  "placeholder"?: "string", // Input placeholder hint (e.g., "sk_live_xxxx...")
+  "description"?: "string", // Help text explaining what this input is for
+  "source": "input" | "env", // Where the value comes from:
+                            // - "input": User provides value directly (default)
+                            // - "env": Value comes from environment variable dropdown
+  "required": "boolean",   // Whether this input must be provided (always specify)
+  "default"?: "any"        // Default value if not provided (only when required: false)
+}
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Variable name used in code (snake_case) |
+| `type` | Yes | `string`, `number`, `boolean`, `object`, `array` |
+| `label` | Yes | User-readable label for UI |
+| `source` | Yes | `input` (user provides) or `env` (environment variable dropdown) |
+| `required` | Yes | Always set explicitly - UI fields start empty, so this controls validation |
+| `placeholder` | No | Input hint text (e.g., "sk_live_...") |
+| `description` | No | Help text shown in UI |
+| `default` | No | Default value - only use when `required: false` |
+
+**Required vs Default:**
+- If `required: true` → user must provide a value, no default needed
+- If `required: false` → consider adding a `default` so the tool has a fallback
+- Never use both `required: true` and `default` together - they're mutually exclusive
+
+**Source Rules:**
+- Use `"source": "env"` for sensitive values (API keys, secrets, tokens)
+- Use `"source": "input"` for regular parameters (amounts, names, options)
+
+**Example - Stripe charge tool:**
+
+```json
+{
+  "tool_id": "stripe_charge",
+  "name": "Stripe Charge",
+  "inputs": [
+    {
+      "name": "stripe_api_key",
+      "type": "string",
+      "label": "Stripe API Key",
+      "placeholder": "sk_live_...",
+      "description": "Your Stripe secret key from the dashboard",
+      "source": "env",
+      "required": true
+    },
+    {
+      "name": "amount",
+      "type": "number",
+      "label": "Amount",
+      "placeholder": "1000",
+      "description": "Amount in cents (e.g., 1000 = $10.00)",
+      "source": "input",
+      "required": true
+    },
+    {
+      "name": "currency",
+      "type": "string",
+      "label": "Currency",
+      "placeholder": "usd",
+      "description": "Three-letter ISO currency code",
+      "source": "input",
+      "required": false,
+      "default": "usd"
+    }
+  ]
+}
+```
+
+This schema enables the UI to:
+- Show text inputs for `source: "input"`
+- Show env var dropdowns for `source: "env"`
+- Display the `label` as the field name
+- Show `placeholder` as hint text
+- Show `description` as help text
+
+### Config Mapping
+
+Reference data from previous steps:
+
+| Pattern | Description |
+|---------|-------------|
+| `$trigger.input.field` | Input from workflow trigger |
+| `$step_id.output.field` | Output from a previous step |
+
+### Template Variables
+
+When configuring workflow steps that generate content (emails, PDFs, documents, messages), use template variables for dynamic content. These variables are automatically substituted at runtime.
+
+**Syntax:** Always use double curly braces: `{{variable}}`
+
+**Available Variables:**
+
+Variables come from two sources:
+
+1. **Workflow inputs** - Values passed when the workflow is triggered
+   - `{{name}}`, `{{email}}`, `{{phone}}`, etc.
+
+2. **Previous step outputs** - Values returned by earlier steps
+   - `{{page_url}}`, `{{record_id}}`, `{{file_path}}`, etc.
+
+**Variable Name Mappings:**
+
+The system recognizes common variations:
+
+| Variation | Maps to |
+|-----------|---------|
+| `{{lead_name}}` | `{{name}}` |
+| `{{lead_email}}` | `{{email}}` |
+| `{{lead_phone}}` | `{{phone}}` |
+| `{{notion_url}}` | `{{page_url}}` |
+
+**Best Practice:** Use simple variable names that match workflow input names directly.
+
+**Example step config:**
+
+```json
+{
+  "step_id": "notify",
+  "tool_id": "send_email_resend",
+  "config": {
+    "to": "$trigger.input.notification_email",
+    "subject": "New Lead: {{name}}",
+    "body": "<h2>New Lead</h2><p>Name: {{name}}</p><p>Email: {{email}}</p><p><a href=\"{{page_url}}\">View in Notion</a></p>"
+  }
+}
+```
+
+### Workflow Context System
+
+Workflows have two layers of configuration:
+
+1. **Directive (workflows.directive)** — The base workflow definition. This is **immutable from AI chat**. It defines what the workflow CAN do.
+
+2. **Context (workflow_contexts table)** — Per-user customizations. The AI chat CAN update this to customize workflow behavior within the boundaries defined by the directive.
+
+**Key principle:** The directive defines capabilities. Context customizes within those boundaries. If a user requests something the workflow doesn't support, acknowledge it and suggest an alternative workflow if one exists.
+
+#### workflow_contexts Schema
+
+```sql
+workflow_contexts (
+  id uuid,
+  workflow_id uuid,        -- Links to workflows table
+  context text,            -- The customization content (MUST be Markdown)
+  context_for uuid,        -- The user this context applies to
+  context_key text,        -- Identifies what aspect is being customized (e.g., "email_template", "notification_preferences")
+  created_at timestamp,
+  updated_at timestamp
+)
+```
+
+**Unique constraint:** `(workflow_id, context_for, context_key)` — One context entry per workflow, per user, per key.
+
+#### Context Format: Markdown Only
+
+The `context` field **MUST always be written in Markdown**. Never use:
+- Raw HTML (use Markdown syntax instead)
+- Plain text without formatting
+- JSON (unless embedded in a Markdown code block for reference)
+
+**Why Markdown:**
+- Consistent parsing across the system
+- Human-readable in database and logs
+- Easily rendered in UI
+- Supports structured content (headers, lists, code blocks)
+
+**Examples:**
+
+**CORRECT** — Markdown format:
+```markdown
+# Email Template
+
+## Subject
+New Lead: {{name}}
+
+## Body
+Hello team,
+
+A new lead just came in:
+
+- **Name:** {{name}}
+- **Email:** {{email}}
+- **Phone:** {{phone}}
+
+[View in Notion]({{page_url}})
+```
+
+**INCORRECT** — Raw HTML:
+```html
+<h1>Email Template</h1>
+<p>Hello team, A new lead: <strong>{{name}}</strong></p>
+```
+
+**INCORRECT** — Plain text:
+```
+Email Template
+Subject: New Lead
+Body: Hello team, a new lead came in.
+```
+
+For email bodies that need HTML rendering, write the content structure in Markdown and let the system convert it, or use a Markdown code block to document the desired HTML output:
+
+```markdown
+# Email Body
+
+The email should render as:
+
+\`\`\`html
+<h2>New Lead</h2>
+<p>Name: {{name}}</p>
+\`\`\`
+```
+
+#### What Can Be Customized via Context
+
+| Context Key | What It Customizes | Example |
+|-------------|-------------------|---------|
+| `email_template` | Email body/subject for notifications | Custom HTML template with branding |
+| `notification_preferences` | Who receives notifications, when | Different email for high-priority leads |
+| `field_mappings` | How input fields map to outputs | Custom field names for CRM sync |
+| `tone_preferences` | AI-generated content style | "Professional and formal" vs "Friendly" |
+
+#### What CANNOT Be Customized
+
+These are defined by the directive and are immutable:
+
+- **Workflow purpose** — A lead capture workflow cannot become a support ticket workflow
+- **Core tools/steps** — The sequence of tools that execute
+- **Required inputs** — What data the workflow needs to run
+- **Database targets** — Which Notion databases are written to
+- **API integrations** — Which services are called
+
+#### AI Chat Behavior
+
+When a user requests a change via AI chat:
+
+1. **If customizable** — Update workflow_contexts with the new preference
+   ```
+   User: "Change my lead notification email to include our company logo"
+   AI: Updates context_key="email_template" with new HTML template
+   ```
+
+2. **If not supported by this workflow** — Acknowledge and suggest alternatives
+   ```
+   User: "Can you also create a support ticket when a lead comes in?"
+   AI: "The New Lead workflow is specifically for sales leads. Creating support tickets
+        is a different workflow. Would you like me to help you set up a Support Ticket
+        workflow that could be triggered separately?"
+   ```
+
+3. **If no workflow exists** — Offer to create one
+   ```
+   User: "I want to track bug reports too"
+   AI: "There isn't a bug tracking workflow yet. Would you like me to create one?
+        It would be separate from lead capture to keep your data clean."
+   ```
+
+**Never** try to repurpose a workflow beyond its defined scope. Acknowledge the limitation, then help the user find or create the right solution.
+
+#### Context Priority
+
+At runtime, the system checks for context in this order:
+1. User-specific context (workflow_contexts where context_for = current_user)
+2. Step config defaults (from workflow JSON)
+3. Tool defaults (from tool definition)
+
+Content fields in step configs serve as defaults. User context takes priority when present.
+
+### Environment Variables
+
+Required in `.env`:
+- `MUDLAB_API_URL` - Base URL for Mudlab API
+- `MUDLAB_API_KEY` - API key for authentication (X-API-Key header)
+
+## Summary
+
+You sit between human intent (directives) and deterministic execution (Node.js scripts pushed to Mudlab). Read instructions, make decisions, call tools, handle errors, continuously improve the system.
+
+Be pragmatic. Be reliable. Self-anneal.