docs: add start-here index and gateway lane-queue diagram

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]
+```
+