diff --git a/API.md b/API.md
index 80e894e..3b04a8c 100644
--- a/API.md
+++ b/API.md
@@ -1028,17 +1028,131 @@ User drops 3 new nodes on canvas
     ↓
 Workflow calls CanvasReasonerActivity
     ↓
-LLM analyzes: Clone → Analyze → Report
+LLM analyzes schemas: Clone (out: path,commit) → Analyze (in: path) → Report (in: metrics)
     ↓
-Returns edges + reasoning
+Compatibility checker validates edges
     ↓
-Frontend updates canvas with suggested connections
+Returns:
+  - Suggested edges (Clone → Analyze → Report)
+  - Incompatible edges (Report → Approve [terminal sink])
+  - Disconnected nodes (if any isolated nodes)
+  - User alerts explaining issues
     ↓
-User approves/rejects suggestions
+Frontend shows:
+  ✅ Green edges (compatible)
+  ❌ Red warnings (incompatible)
+  🔌 Yellow badges (disconnected)
+    ↓
+User approves compatible edges, fixes/removes incompatible ones
 ```
 
 ---
 
+### Handling Incompatible Connections
+
+When two activities **cannot** be connected, the response includes detailed incompatibility data:
+
+**Example: Terminal Activity Blocking Connection**
+```json
+{
+  "suggested_edges": [
+    {"source": "clone-1", "target": "analyze-1"}
+  ],
+  "incompatible_edges": [
+    {
+      "source": "security-scan-1",
+      "target": "approve-1",
+      "reason": "ApproveWorkflowActivity accepts no inputs (terminal sink activity)",
+      "source_needs": "to output: issues, metrics, severity",
+      "target_needs": "none (approval only blocks workflow)",
+      "suggestion": "ApproveWorkflowActivity must be the final step. Place it after Report generates summary."
+    }
+  ],
+  "user_alerts": [
+    "⚠️  security-scan-1 → approve-1: ApproveWorkflowActivity is terminal (no inputs). Place it at the end of the workflow."
+  ]
+}
+```
+
+**Example: Type Mismatch**
+```json
+{
+  "incompatible_edges": [
+    {
+      "source": "llm-inference-1",
+      "target": "deployment-check-1",
+      "reason": "Output type mismatch: string ≠ object",
+      "source_needs": "outputs: response (string)",
+      "target_needs": "inputs: deployment_plan (object)",
+      "suggestion": "Insert LLM transformer node to convert string response → deployment_plan object"
+    }
+  ],
+  "user_alerts": [
+    "⚠️  llm-inference-1 → deployment-check-1: Type mismatch (string ≠ object). Use LLM transformation node to map outputs."
+  ]
+}
+```
+
+**Example: Disconnected Nodes**
+```json
+{
+  "disconnected_nodes": ["security-scan-1", "notify-1"],
+  "user_alerts": [
+    "🔌 Node 'SecurityScan' has no connections. Connect it or remove from canvas.",
+    "🔌 Node 'Notify' has no incoming edges. Check if it should receive data."
+  ]
+}
+```
+
+### Incompatibility Warning Schema
+
+```json
+{
+  "source": "string - source node ID",
+  "target": "string - target node ID",
+  "reason": "string - why connection fails",
+  "source_needs": "string - what source outputs",
+  "target_needs": "string - what target requires",
+  "suggestion": "string - how to fix it"
+}
+```
+
+### Common Incompatibility Reasons
+
+| Reason | Example | Solution |
+|--------|---------|----------|
+| **Terminal Activity** | Notify → CloneRepo | Can't output from sink (terminal) |
+| **Type Mismatch** | string → object | Use LLM transformer node |
+| **No Outputs** | Notification has no outputs | Terminal activities can't be sources |
+| **No Inputs** | Approval has no inputs | Terminal activities can't accept data |
+| **Semantic Mismatch** | Approval → Analysis | Doesn't make logical sense |
+
+### Frontend Alert Display
+
+**Sidebar UI:**
+```
+🚨 Connection Issues (3)
+
+⚠️  CloneRepo-1 → Approve-1
+   Terminal sink can't receive inputs
+   [Fix] [Ignore] [Remove Node]
+
+⚠️  LLMInference-1 → DeploymentCheck-1
+   Type mismatch: string → object
+   [Add Transformer] [Manual Map]
+
+🔌 SecurityScan-1 (isolated)
+   No connections detected
+   [Connect] [Remove]
+```
+
+**Canvas Visual Feedback:**
+- ❌ Incompatible suggested edges appear as **red dashed lines** (don't auto-add)
+- ⚠️ Disconnected nodes show **yellow border** with icon
+- ✅ Compatible edges appear as **green solid lines** (safe to accept)
+
+---
+
 ### Error Handling
 
 If LLM inference fails: