From 6e3f1fdd3f63ef7efff7ee2ca1bb3b9c1d47ff51 Mon Sep 17 00:00:00 2001
From: William Valentin <william.valentin.info@gmail.com>
Date: Sun, 15 Feb 2026 11:20:32 -0800
Subject: [PATCH] docs: add start-here index and gateway lane-queue diagram

---
 docs/README.md        | 40 +++++++++++++++++++++++++++++++++++++++
 docs/api/PROTOCOL.md  | 44 +++++++++++++++++++++++++++++++++++++++++++
 docs/plans/state.json |  5 +++++
 3 files changed, 89 insertions(+)
 create mode 100644 docs/README.md

diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..bef70e2
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,40 @@
+# Flynn Documentation (Start Here)
+
+This documentation is written to be useful to both humans and AI agents. If you want a fast mental model, read the architecture diagram first.
+
+## Reading Order
+
+1. Architecture overview (agent-oriented)
+   - `docs/architecture/AGENT_DIAGRAM.md`
+   - `docs/architecture/TYPESCRIPT_MAP.md`
+   - `docs/architecture/SYMBOL_INDEX.md`
+   - `docs/architecture/CONTRIBUTOR_MAP.md`
+2. Security boundary (safe-by-default personal agent)
+   - `docs/security/SAFE_PERSONAL_AGENT.md`
+3. Gateway API (WebSocket JSON-RPC)
+   - `docs/api/PROTOCOL.md`
+4. Tool contracts and policy/execution details
+   - `docs/api/TOOLS.md`
+5. Production and performance
+   - `docs/deployment/PRODUCTION.md`
+   - `docs/performance/TUNING.md`
+
+## Quick Map (One Diagram)
+
+```mermaid
+flowchart TD
+  U[User on chat surface] --> CA[ChannelAdapter]
+  U --> GW[Gateway WS/HTTP + Web UI]
+
+  CA --> RT[Routing + Sessions]
+  GW --> RT
+
+  RT --> OR[AgentOrchestrator]
+  OR --> NA[NativeAgent tool loop]
+  NA --> MR[ModelRouter]
+  MR --> MC[ModelClient -> provider]
+
+  NA --> TP[ToolPolicy + ToolRegistry]
+  TP --> TE[ToolExecutor\nhooks + enforcement + audit]
+```
+
diff --git a/docs/api/PROTOCOL.md b/docs/api/PROTOCOL.md
index 9f3c24b..48a664b 100644
--- a/docs/api/PROTOCOL.md
+++ b/docs/api/PROTOCOL.md
@@ -22,6 +22,50 @@ The gateway provides:
 - **Streaming Events**: Real-time updates during agent processing
 - **HTTP Server**: Serves static dashboard and handles webhook endpoints
 
+### Execution Model (Sessions + Per-Session Queue)
+
+Two concepts matter for correct clients:
+
+- **connectionId**: a single WebSocket connection identity (assigned on connect)
+- **sessionId**: the conversation/session the connection is attached to (defaults to a per-connection session, but can be switched to resume an old session)
+
+The gateway serialises agent work **per session**, not per WebSocket connection:
+
+- Requests that target the same `sessionId` run one-at-a-time (FIFO) in a per-session lane.
+- Requests for different sessions can run in parallel.
+
+This is implemented via a per-lane queue (`LaneQueue`) in the gateway server, and used by `agent.send` and `agent.cancel`.
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant C as Client
+  participant G as Gateway (WS JSON-RPC)
+  participant LQ as LaneQueue (per-session)
+  participant SB as SessionBridge
+  participant A as AgentOrchestrator
+
+  C->>G: agent.send {connectionId, message}
+  G->>SB: resolve sessionId for connectionId
+  SB-->>G: sessionId (laneId)
+  G->>LQ: enqueue(laneId, work)
+
+  alt lane idle
+    LQ-->>G: starts work immediately
+  else lane busy
+    Note over LQ: work queued (FIFO) for this lane
+  end
+
+  G->>A: process(message) in that session
+  A-->>G: streaming events (content/tool_start/tool_end)
+  G-->>C: events + final done
+
+  C->>G: agent.cancel {connectionId}
+  G->>LQ: cancel(laneId) (queued items rejected)
+  G->>SB: cancel active op (best-effort)
+  G-->>C: result.cancelled=true/false
+```
+
 ### Base URL
 
 - WebSocket: `ws://localhost:18800` (or `wss://` if using TLS)
diff --git a/docs/plans/state.json b/docs/plans/state.json
index b64335b..47d11f1 100644
--- a/docs/plans/state.json
+++ b/docs/plans/state.json
@@ -4,6 +4,11 @@
   "description": "Tracks the status of all Flynn plans and implementation phases",
 
   "plans": {
+    "docs-agent-oriented-diagrams-pass": {
+      "status": "completed",
+      "date": "2026-02-15",
+      "summary": "Docs gap pass: added docs/README.md as a start-here index and expanded docs/api/PROTOCOL.md with a precise Mermaid diagram explaining per-session lane queueing and cancellation semantics for agent.send/agent.cancel."
+    },
     "openclaw-gap-roadmap": {
       "file": "2026-02-15-openclaw-gap-roadmap.md",
       "status": "planned",