@unstable-dev/unmeshed-mcp 0.1.0

package/knowledge/assets/patterns.md

@@ -0,0 +1,637 @@
+# Unmeshed Workflow Patterns & Templates
+
+Use these as starting scaffolds. Replace all `<PLACEHOLDER>` values.
+
+---
+
+## Pattern A — Linear Data Pipeline
+
+**Use case:** Receive API input → transform → call integration → format output → store
+
+```json
+{
+  "orgId": 1,
+  "namespace": "default",
+  "name": "<workflow-name>",
+  "version": 1,
+  "type": "API_ORCHESTRATION",
+  "description": "<description>",
+  "configuration": null,
+  "steps": [
+    {
+      "orgId": 1, "namespace": "default",
+      "name": "map_input_fields", "type": "JAVASCRIPT", "ref": "map_input_fields",
+      "optional": false, "createdBy": "system", "updatedBy": "system",
+      "description": "Map and validate incoming API input", "label": null,
+      "created": 1700000000000, "updated": 1700000000000,
+      "configuration": { "errorPolicyName": null, "useCache": false, "cacheKey": null, "cacheTimeoutSeconds": 0, "stream": false, "streamAllStatuses": false, "preExecutionScript": null, "constructInputFromScript": false, "scriptLanguage": null, "jqTransformer": null, "rateLimitMaxRequests": 0, "rateLimitWindowSeconds": 0 },
+      "children": [],
+      "input": {
+        "script": "(steps, context) => {\n  const input = context.input || {};\n  return {\n    field1: input.field1 || '',\n    field2: input.field2 || ''\n  };\n}"
+      },
+      "output": null
+    },
+    {
+      "orgId": 1, "namespace": "default",
+      "name": "<integration_step>", "type": "INTEGRATION", "ref": "<integration_ref>_1",
+      "optional": false, "createdBy": "system", "updatedBy": "system",
+      "description": null, "label": null,
+      "created": 1700000000000, "updated": 1700000000000,
+      "configuration": { "errorPolicyName": null, "useCache": false, "cacheKey": null, "cacheTimeoutSeconds": 0, "stream": false, "streamAllStatuses": false, "preExecutionScript": null, "constructInputFromScript": false, "scriptLanguage": null, "jqTransformer": null, "rateLimitMaxRequests": 0, "rateLimitWindowSeconds": 0 },
+      "children": [],
+      "input": { /* see integrations.md */ },
+      "output": null
+    }
+  ],
+  "defaultInput": null, "defaultOutput": null, "outputMapping": null,
+  "signature": null, "metadata": null, "tags": null, "dependencies": null, "dependents": null
+}
+```
+
+---
+
+## Pattern B — LLM Classify → Decision Route
+
+**Use case:** Input → map fields → LLM classifies → DECISION_ENGINE routes
+
+Steps: `JAVASCRIPT (map)` → `INTEGRATION (llm-claude)` → `DECISION_ENGINE`
+
+Key wiring:
+- LLM output accessed as: `steps.llm_claude_1.output.results.<field>`
+- Decision context maps LLM output fields to decision table column names
+- Always defensively read LLM output: `(steps.llm_claude_1.output.results || steps.llm_claude_1.output.result || {})`
+
+JAVASCRIPT (map) input:
+```javascript
+(steps, context) => {
+  const input = context.input || {};
+  return {
+    text: input.text || '',
+    userId: input.userId || ''
+  };
+}
+```
+
+INTEGRATION (llm-claude) input:
+```json
+{
+  "type": "llm-claude",
+  "name": "unmeshed",
+  "publishProperties": { "allowedTokens": 300, "temperature": 0.0 },
+  "messageBody": {
+    "systemPrompt": "Classify the input. Return only valid JSON with fields: category, urgency.",
+    "userPrompt": "Text: {{steps.map_input_fields.output.result.text}}\n\nReturn: {\"category\": \"...\", \"urgency\": \"low|medium|high\"}"
+  }
+}
+```
+
+DECISION_ENGINE input:
+```json
+{
+  "decisionRuleStrategy": "FIRST_MATCH",
+  "decisionTable": "<your-table-name>",
+  "decisionContext": {
+    "Category": "{{steps.llm_claude_1.output.results.category}}",
+    "Urgency": "{{steps.llm_claude_1.output.results.urgency}}"
+  },
+  "decisionTableVersion": "",
+  "decisionOutputColumns": ["AssignTo", "Priority"]
+}
+```
+
+---
+
+## Pattern C — State-Gated Branch (Create or Reuse Resource)
+
+**Use case:** Check if resource exists in state → if yes use it, if no create it
+
+Steps:
+1. `PERSISTED_STATE` (READ) — check if resource ID is stored
+2. `SWITCH` — branch on `steps.persisted_state_1.output.result` being null or not
+    - Branch `new-resource` (LIST): create resource → store ID in PERSISTED_STATE (UPSERT)
+    - Branch `existing-resource` (LIST or NOOP): use stored ID directly
+
+SWITCH script pattern:
+```javascript
+(steps, context) => {
+  if (steps.persisted_state_1.output.result) {
+    return 'existing-resource';
+  }
+  return 'new-resource';
+}
+```
+
+SWITCH responseMapping:
+```json
+[
+  { "targetRef": "existing-resource", "value": "existing-resource" },
+  { "targetRef": "new-resource", "value": "new-resource" },
+  { "targetRef": "new-resource", "defaultBranch": true }
+]
+```
+
+PERSISTED_STATE (READ) input:
+```json
+{ "operation": "READ", "name": "my-spreadsheet-id", "path": "$" }
+```
+
+PERSISTED_STATE (UPSERT, inside LIST branch) input:
+```json
+{
+  "operation": "UPSERT",
+  "name": "my-spreadsheet-id",
+  "path": "$",
+  "value": "{{steps.google_sheets_1.output.spreadsheetId}}"
+}
+```
+
+---
+
+## Pattern D — Parallel Sub-Process Fan-out
+
+**Use case:** Gate check → run multiple workflows concurrently
+
+Steps:
+1. `PERSISTED_STATE` (READ) — read a flag
+2. `SWITCH` — if flag true: proceed, else EXIT
+    - Branch NOOP → continues to next top-level step
+    - Branch EXIT → terminates
+3. `PARALLEL` — children are all SUB_PROCESS steps
+
+PARALLEL input:
+```json
+{ "failIfAnyBranchFails": true }
+```
+
+PARALLEL children (SUB_PROCESS steps):
+```json
+[
+  {
+    "orgId": 1, "namespace": "default",
+    "name": "process-a", "type": "SUB_PROCESS", "ref": "process-a",
+    "optional": false, "createdBy": "system", "updatedBy": "system",
+    "description": null, "label": null,
+    "created": 1700000000000, "updated": 1700000000000,
+    "configuration": { "errorPolicyName": null, "useCache": false, "cacheKey": null, "cacheTimeoutSeconds": 0, "stream": false, "streamAllStatuses": false, "preExecutionScript": null, "constructInputFromScript": false, "scriptLanguage": null, "jqTransformer": null, "rateLimitMaxRequests": 0, "rateLimitWindowSeconds": 0 },
+    "children": [],
+    "input": { "processName": "process-a", "waitForCompletion": true },
+    "output": null
+  }
+]
+```
+
+---
+
+## Pattern E — Classify → Store All → Conditionally Notify
+
+**Use case:** Every record is stored (e.g. Google Sheets), but notifications (e.g. Slack) only fire for specific conditions (e.g. critical urgency).
+
+Steps:
+1. `JAVASCRIPT` — map/validate input fields
+2. `INTEGRATION` (llm-claude) — classify/analyse with LLM
+3. `DECISION_ENGINE` — route based on classification rules
+4. `JAVASCRIPT` — format output record + pre-build notification message string
+5. `INTEGRATION` (google-sheets APPEND_ROWS) — always write to sheet unconditionally
+6. `SWITCH` — check condition (e.g. `topic === 'technical_issue' && urgency === 'critical'`)
+    - Branch `notify` → `INTEGRATION` (slack-messaging) directly (no LIST wrapper needed)
+    - Branch `skip` → `NOOP` (do nothing)
+
+**Key insight:** The SWITCH comes **after** the unconditional storage step. This ensures every record is persisted regardless of whether a notification fires.
+
+SWITCH branch direct to INTEGRATION example:
+```json
+{
+  "type": "SWITCH",
+  "children": [
+    {
+      "orgId": 1, "namespace": "default",
+      "name": "slack_messaging", "type": "INTEGRATION", "ref": "slack_messaging_1",
+      "optional": false, "createdBy": "system", "updatedBy": "system",
+      "description": null, "label": null,
+      "created": 1700000000000, "updated": 1700000000000,
+      "configuration": { "errorPolicyName": null, "useCache": false, "cacheKey": null, "cacheTimeoutSeconds": 0, "stream": false, "streamAllStatuses": false, "preExecutionScript": null, "constructInputFromScript": false, "scriptLanguage": null, "jqTransformer": null, "rateLimitMaxRequests": 0, "rateLimitWindowSeconds": 0 },
+      "children": [],
+      "input": {
+        "type": "slack-messaging",
+        "name": "",
+        "messageBody": {
+          "type": "MESSAGE",
+          "message": "{{steps.format_step.output.result.slackMessage}}",
+          "messageBlocks": [{ "type": "section", "text": { "type": "mrkdwn", "text": "{{steps.format_step.output.result.slackMessage}}" } }]
+        },
+        "publishProperties": { "durationType": "MINUTES", "receiverType": "CHANNEL" }
+      },
+      "output": null
+    },
+    {
+      "orgId": 1, "namespace": "default",
+      "name": "no_notification", "type": "NOOP", "ref": "no-notification",
+      "optional": false, "createdBy": "system", "updatedBy": "system",
+      "description": null, "label": null,
+      "created": 1700000000000, "updated": 1700000000000,
+      "configuration": { "errorPolicyName": null, "useCache": false, "cacheKey": null, "cacheTimeoutSeconds": 0, "stream": false, "streamAllStatuses": false, "preExecutionScript": null, "constructInputFromScript": false, "scriptLanguage": null, "jqTransformer": null, "rateLimitMaxRequests": 0, "rateLimitWindowSeconds": 0 },
+      "children": [],
+      "input": {},
+      "output": null
+    }
+  ],
+  "input": {
+    "script": "(steps, context) => {\n  const topic = String(steps.format_step.output.result.topic || '').toLowerCase();\n  const urgency = String(steps.format_step.output.result.urgency || '').toLowerCase();\n  if (topic === 'technical_issue' && urgency === 'critical') return 'notify';\n  return 'skip';\n}",
+    "responseMapping": [
+      { "targetRef": "slack_messaging_1", "value": "notify" },
+      { "targetRef": "no-notification", "value": "skip" },
+      { "targetRef": "no-notification", "defaultBranch": true }
+    ]
+  }
+}
+```
+
+---
+
+## Pattern F — HTTP API Call → Normalize → Store
+
+**Use case:** Call external REST API, normalize the response, store to DB or sheet.
+
+Steps:
+1. `JAVASCRIPT` — build request payload from context input
+2. `HTTP` — call the external API
+3. `JAVASCRIPT` — normalize/extract fields from API response
+4. `INTEGRATION` (postgres or google-sheets) — store the data
+
+Key wiring for HTTP step:
+```json
+{
+  "type": "HTTP",
+  "ref": "http_1",
+  "input": {
+    "method": "POST",
+    "url": "https://api.example.com/data",
+    "headers": { "Content-Type": "application/json", "Authorization": "Bearer {{secrets.api_token}}" },
+    "params": {},
+    "body": {
+      "type": "json",
+      "content": {
+        "query": "{{steps.map_input_fields.output.result.query}}"
+      }
+    },
+    "repeatUntilEnabled": null,
+    "repeatUntilCondition": { "script": "(steps, context) => { return false; }" },
+    "repeatIntervalSeconds": null,
+    "maxRepeatCount": null,
+    "includeFullResponseString": false,
+    "noEncode": false,
+    "extraLongTimeouts": false
+  }
+}
+```
+
+Normalize JS after HTTP:
+```javascript
+(steps, context) => {
+  const response = steps.http_1.output.response || {};
+  return {
+    id: response.id || '',
+    name: response.name || '',
+    value: response.data?.value || 0
+  };
+}
+```
+
+---
+
+## Pattern G — Error-Aware Exit Branches
+
+**Use case:** Validate input → exit with FAILED if invalid, else continue processing.
+
+Steps:
+1. `JAVASCRIPT` — validate input fields, return `{ valid: true/false, reason: '...' }`
+2. `SWITCH` — branch on `valid`
+    - Branch `invalid` → `EXIT` (status: FAILED)
+    - Branch `valid` → `LIST` (continue with main logic)
+
+SWITCH script:
+```javascript
+(steps, context) => {
+  if (!steps.validate_input.output.result.valid) return 'invalid';
+  return 'valid';
+}
+```
+
+EXIT step inside invalid branch:
+```json
+{
+  "type": "EXIT",
+  "input": {
+    "message": "{{steps.validate_input.output.result.reason}}",
+    "status": "FAILED"
+  }
+}
+```
+
+---
+
+## Ref Naming Conventions
+
+| Step type | Ref pattern | Example |
+|---|---|---|
+| INTEGRATION | `<name>_<n>` | `google_sheets_1`, `llm_claude_1`, `http_1` |
+| JAVASCRIPT | same as `name` | `map_input_fields`, `format_output` |
+| PYTHON | same as `name` | `extract_content` |
+| NOOP | same as `name` | `job_config`, `settings` |
+| SWITCH | `switch_<n>` | `switch_1` |
+| PARALLEL | `parallel_<n>` | `parallel_1` |
+| PERSISTED_STATE | `persisted_state_<n>` | `persisted_state_1` |
+| LIST (branch) | descriptive kebab | `new-sheet`, `existing-sheet`, `invalid-input` |
+| EXIT | `exit_<n>` | `exit_1` |
+| SUB_PROCESS | same as `name` | `send-welcome-email` |
+
+---
+
+## Data Flow Cheatsheet
+
+```
+context.input.<field>                        ← workflow API input
+steps.<ref>.output.response.<field>          ← native HTTP response body
+steps.<ref>.output.statusCode                ← native HTTP status code
+steps.<ref>.output.result.<field>            ← JAVASCRIPT / PYTHON / most INTEGRATION output
+steps.<ref>.output.results.<field>           ← LLM Claude output (note: results plural)
+steps.<ref>.output.<field>                   ← NOOP output (no .result wrapper)
+steps.<ref>.output.spreadsheetId            ← Google Sheets CREATE output
+steps.<ref>.output.result.rows              ← PostgreSQL / MySQL SELECT output
+steps.<ref>.output.id                       ← Google Drive upload output (file ID)
+steps.<ref>.output.webViewLink              ← Google Drive upload output (share URL)
+steps.<ref>.output.status                   ← HTTP integration response status code
+steps.__self.id                              ← current step ID (inside scripts)
+context.id                                   ← workflow process/run ID
+```
+
+---
+
+## Pattern H — WAIT for Async Side Effect
+
+**Use case:** Trigger an async action (e.g. send email via sub-process), wait for it to arrive/propagate, then assert or read results.
+
+Steps:
+1. `SUB_PROCESS` — trigger the action (e.g. send email)
+2. `WAIT` — pause for delivery/propagation time
+3. `INTEGRATION` — read/verify the result (e.g. readEmail)
+4. `JAVASCRIPT` — assert on the result
+
+WAIT input:
+```javascript
+(steps, context) => {
+  return {
+    "waitUntil": steps.__self.startTime + (25 * 1000)  // 25 seconds
+  };
+}
+```
+
+**Key rule:** Always use `steps.__self.startTime` (not `Date.now()`) as the base — it's stable within a WAIT instance.
+
+---
+
+## Pattern I — FOREACH Loop
+
+**Use case:** Iterate over an array and run the same steps for each element.
+
+Structure:
+```
+FOREACH (inputArray, concurrency)
+  └── LIST
+        └── [step(s) for each iteration]
+JAVASCRIPT (collect results)
+JAVASCRIPT (assert on collected results)
+```
+
+FOREACH input:
+```json
+{
+  "inputArray": [1, 2, 3, 4, 5],
+  "concurrency": 1
+}
+```
+
+Collecting results after the loop:
+```javascript
+(steps, context) => {
+  const allOutputs = [];
+  for (let i = 0; i < 5; i++) {
+    allOutputs.push(steps[`http[${i}]`].output);
+  }
+  return allOutputs;
+}
+```
+
+Access individual iteration output: `steps["<ref>[0]"].output`, `steps["<ref>[1]"].output`, etc.
+
+---
+
+## Pattern J — PARALLEL with LIST Branches (not SUB_PROCESS)
+
+**Use case:** Run multiple independent test suites or processing tracks concurrently within the same workflow.
+
+Structure: `PARALLEL → [LIST branch_1, LIST branch_2, LIST branch_3, ...]`
+
+Each LIST branch has its own `ref` and independent `children` steps. Unlike Pattern D (SUB_PROCESS fan-out), the branches are inline within the same workflow JSON.
+
+```json
+{
+  "type": "PARALLEL",
+  "children": [
+    { "type": "LIST", "ref": "branch_1", "children": [...], "input": {} },
+    { "type": "LIST", "ref": "branch_2", "children": [...], "input": {} },
+    { "type": "LIST", "ref": "branch_3", "children": [...], "input": {} }
+  ],
+  "input": { "failIfAnyBranchFails": true }
+}
+```
+
+Use `"failIfAnyBranchFails": false` when branches are independent and partial failure is acceptable.
+
+---
+
+## Pattern K — Rate-Limit Aware Integration
+
+**Use case:** External API may return HTTP 429 (rate limit). Mark the step optional and use a SWITCH to gracefully skip when rate-limited.
+
+Steps:
+1. `INTEGRATION` (optional: true, errorPolicyName: "retry_ep") — call the external API
+2. `SWITCH` — check if the output contains a rate-limit error
+    - Branch `plan_expired` → `JAVASCRIPT` (return skip/pass message)
+    - Branch `plan_working` → `LIST` (continue with main logic)
+
+SWITCH script for rate-limit detection:
+```javascript
+(steps, context) => {
+  if (steps.get_all_tables.output.error &&
+      steps.get_all_tables.output.error.includes("HTTP 429 429 TOO_MANY_REQUESTS")) {
+    return "plan_expired";
+  }
+  return "plan_working";
+}
+```
+
+SWITCH responseMapping:
+```json
+[
+  { "targetRef": "plan_expired", "value": "plan_expired" },
+  { "targetRef": "plan_working", "defaultBranch": true }
+]
+```
+
+---
+
+## Ref Naming Conventions
+
+| Step type | Ref pattern | Example |
+|---|---|---|
+| INTEGRATION | `<name>_<n>` | `google_sheets_1`, `llm_claude_1`, `http_1` |
+| JAVASCRIPT | same as `name` | `map_input_fields`, `format_output`, `assert_1` |
+| PYTHON | same as `name` | `extract_content`, `delete_attachments` |
+| NOOP | same as `name` | `job_config`, `settings` |
+| SWITCH | `switch_<n>` | `switch_1` |
+| PARALLEL | `parallel_<n>` | `parallel_1` |
+| FOREACH | descriptive name | `foreachstep`, `foreach_users` |
+| WAIT | `wait_<n>` | `wait_1`, `wait_2` |
+| HTTP (native) | `http` or `http_<n>` | `http`, `http_1` |
+| PERSISTED_STATE | `persisted_state_<n>` | `persisted_state_1` |
+| LIST (branch) | descriptive kebab | `new-sheet`, `branch_1`, `plan_working` |
+| EXIT | `exit_<n>` | `exit_1` |
+| SUB_PROCESS | same as `name` | `send_sendgrid_mail` |
+
+---
+
+## Data Flow Cheatsheet
+
+```
+context.input.<field>                              ← workflow API input
+steps.<ref>.output.response.<field>                ← native HTTP response body
+steps.<ref>.output.statusCode                      ← native HTTP status code
+steps.<ref>.output.result.<field>                  ← JAVASCRIPT / PYTHON / most INTEGRATION output
+steps.<ref>.output.results.<field>                 ← LLM Claude, Redis, MongoDB output
+steps.<ref>.output.<field>                         ← NOOP output (no .result wrapper)
+steps.<ref>.output.spreadsheetId                   ← Google Sheets CREATE output
+steps.<ref>.output.result.rows                     ← PostgreSQL / MySQL SELECT output
+steps.<ref>.output.id                              ← Google Drive, Notion CREATE output
+steps.<ref>.output.webViewLink                     ← Google Drive upload share URL
+steps.<ref>.output.status                          ← HTTP integration response status code
+steps.<ref>.output.messages                        ← Outlook readEmail output (array)
+steps.<ref>.output.tables                          ← Airtable GET_TABLES output (array)
+steps.<ref>.output.records                         ← Airtable LIST/CREATE output (array)
+steps.<ref>.output.fields.<FieldName>              ← Airtable READ single record
+steps.<ref>.output.issues                          ← Jira SEARCH_ISSUES output (array)
+steps.<ref>.output.transitions                     ← Jira GET_TRANSITIONS output (array)
+steps.<ref>.output.comments                        ← Jira GET_COMMENTS output (array)
+steps.<ref>.output.results                         ← Notion QUERY/SEARCH/LIST_USERS/GET_BLOCK_CHILDREN
+steps.<ref>.output.results.result                  ← Redis GET (string), KEYS (array), EVAL result
+steps.<ref>.output.results.count                   ← MongoDB COUNT
+steps.<ref>.output.results.success                 ← MongoDB CREATE/DELETE_COLLECTION
+steps["<ref>[0]"].output                           ← FOREACH iteration output (index notation)
+steps.__self.id                                    ← current step ID (inside scripts)
+steps.__self.startTime                             ← WAIT step start time (milliseconds)
+context.id                                         ← workflow process/run ID
+```
+
+---
+
+## Pattern L — WHILE Loop with State Counter
+
+**Use case:** Repeat a block of steps a dynamic number of times, tracking progress in state.
+
+Structure:
+```
+WHILE (whileloop.iteration < N)
+  └── LIST
+        ├── WAIT (throttle)
+        └── JAVASCRIPT (__statePut to update state)
+```
+
+WHILE input:
+```javascript
+(steps, context) => {
+  return whileloop.iteration < 5;
+}
+```
+
+WAIT inside loop (use WHILE step's `.updated` as base):
+```javascript
+(steps, context) => {
+  return { "waitUntil": steps.my_while_step.updated + 1000 };
+}
+```
+
+State increment JAVASCRIPT:
+```javascript
+(steps, context) => {
+  return {
+    "__statePut": {
+      "count": (context.state.count || 0) + 1
+    }
+  };
+}
+```
+
+Read state anywhere: `context.state.count`
+
+---
+
+## Pattern M — Error Policy Retry Check
+
+**Use case:** A step is expected to fail on early attempts (error policy retries it), then succeed. Assert that it eventually passed after N retries.
+
+Mark the step `optional: true` and set `errorPolicyName` to a retry policy. In the assertion step, check `steps.__self.executionList.length` or verify the step eventually returned a valid output.
+
+```javascript
+// Inside the retrying step — fail until retry count >= 3
+(steps, context) => {
+  const index = steps.__self.executionList.length;
+  if (index < 3) {
+    throw Error("Failed the step because index < 3");
+  }
+  return { "index": index };
+}
+```
+
+Assert on failed optional step's error message:
+```javascript
+(steps, context) => {
+  const errorMessage = steps.fail_debug.output.error;
+  if (!errorMessage.includes("expected error text")) {
+    throw Error("Not returning expected error");
+  }
+  return { "allGood": true };
+}
+```
+
+---
+
+## Pattern N — Variables and Secrets in HTTP Steps
+
+Use `{{variables.*}}` for environment-specific config and `{{secrets.*}}` for credentials. Never hardcode URLs or tokens.
+
+```json
+{
+  "type": "HTTP",
+  "input": {
+    "method": "GET",
+    "url": "{{variables.dev_server}}/api/resource/{{steps.create.output.response.namespace}}/{{steps.create.output.response.name}}",
+    "headers": {
+      "Authorization": "Bearer {{secrets.unmeshed_test_token}}"
+    }
+  }
+}
+```
+
+Body with mixed template refs:
+```json
+{
+  "body": {
+    "type": "json",
+    "content": {
+      "name": "{{steps.create.output.response.name}}",
+      "namespace": "{{steps.create.output.response.namespace}}",
+      "config": "{{steps.create.output.response.config}}"
+    }
+  }
+}
+```

package/knowledge/execution/debugging-guide.md

@@ -0,0 +1,18 @@
+# Process Run Debugging Guide
+
+Use this sequence when a user asks why a process failed or produced the wrong output.
+
+1. Fetch the process run by id with step details.
+2. Identify process status and process-level output.
+3. Find the first failed step.
+4. Inspect that step's runtime input, output, and error.
+5. Inspect previous step outputs referenced by the failed step.
+6. Compare runtime output paths against the step output path contract.
+7. Explain the root cause in plain English.
+8. If the fix is clear, propose the exact workflow change.
+
+Common HTTP-to-JavaScript issue:
+- HTTP output lives at `steps.<http_ref>.output.response`.
+- JavaScript/Python output lives at `steps.<js_ref>.output.result`.
+- If a JavaScript/Python step after HTTP reads `steps.<http_ref>.output.result`, it will receive `undefined`.
+

package/knowledge/execution/process-run.schema.md

@@ -0,0 +1,24 @@
+# Process Run Schema
+
+Use this contract when explaining or debugging an executed process.
+
+Process run records can include:
+- Process id
+- Namespace
+- Process definition name
+- Version
+- Status
+- Trigger type
+- Correlation id
+- Request id
+- Created/updated timestamps
+- Input
+- Output
+- Step records when requested with full details
+
+Debugging rules:
+- Use the process id to fetch the run.
+- Use full step details when the user asks for complete JSON, step output, failed step, or troubleshooting.
+- Do not infer output from the process definition alone; inspect the executed run output.
+- If process-level output is `null`, inspect step records before claiming the workflow produced no useful data.
+