From f1030aae822876d0e1317e9559d2228526bda220 Mon Sep 17 00:00:00 2001
From: Admin Bot <admin@riotpiao.com>
Date: Sat, 5 Sep 2026 00:54:30 -0700
Subject: [PATCH] docs: add CanvasReasonerActivity for auto-inferring workflow
 connections

---
 API.md | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)

diff --git a/API.md b/API.md
index b7ba923..80e894e 100644
--- a/API.md
+++ b/API.md
@@ -965,6 +965,80 @@ Response returned
 
 ---
 
+### CanvasReasonerActivity
+
+Auto-suggest workflow connections using LLM reasoning. When you drop new activities onto the canvas, this activity analyzes them and suggests logical connections based on input/output compatibility and workflow patterns.
+
+**Workflow Definition:**
+```json
+{
+  "id": "canvas-reason-1",
+  "type": "canvas-reasoner",
+  "label": "Auto-Connect Activities",
+  "data": {
+    "nodes": "{{ workflow.nodes }}",
+    "edges": "{{ workflow.edges }}",
+    "preserve_existing": true,
+    "auth_token": "{{ user.jwt_token }}"
+  }
+}
+```
+
+**Use Cases:**
+- New nodes added to canvas → automatically suggest connections
+- Validate workflow design → LLM reasoning explains connections
+- Redesign workflow → suggest optimal activity sequence
+- Data flow analysis → ensure proper input/output matching
+
+**How It Works:**
+1. Analyzes all node types and their configurations
+2. Reviews existing edges (if preserving)
+3. Uses reasoning model to infer logical connections
+4. Returns suggested edges with confidence score
+5. Includes reasoning explanation
+
+**Output Example:**
+```json
+{
+  "suggested_edges": [
+    {"source": "clone-1", "target": "analyze-1"},
+    {"source": "analyze-1", "target": "security-scan-1"},
+    {"source": "security-scan-1", "target": "report-1"}
+  ],
+  "reasoning": "Clone repository first, analyze code, perform security scan, generate report. Standard code review workflow.",
+  "confidence": 0.92
+}
+```
+
+**Fields:**
+- `nodes` (required): Canvas nodes to analyze
+- `edges` (required): Current edges
+- `preserve_existing` (optional, default true): Keep existing edges and only suggest new ones
+- `auth_token` (optional): JWT for LLM reasoning calls
+
+**Confidence Scores:**
+- 0.9-1.0: High confidence (common patterns)
+- 0.7-0.9: Medium confidence (reasonable connections)
+- 0.5-0.7: Low confidence (multiple valid approaches)
+- <0.5: Unsure (manual review recommended)
+
+**Integration Example:**
+```
+User drops 3 new nodes on canvas
+    ↓
+Workflow calls CanvasReasonerActivity
+    ↓
+LLM analyzes: Clone → Analyze → Report
+    ↓
+Returns edges + reasoning
+    ↓
+Frontend updates canvas with suggested connections
+    ↓
+User approves/rejects suggestions
+```
+
+---
+
 ### Error Handling
 
 If LLM inference fails: