docs: update template count badge (82 → 83)

Co-Authored-By: Claude <noreply@anthropic.com>
2026-01-25 13:30:40 +01:00 · 2026-01-25 13:30:40 +01:00 · 29f778daf7
commit 29f778daf7
parent a858dceda0
5 changed files with 335 additions and 5 deletions
--- a/README.md
+++ b/README.md
@ -6,16 +6,16 @@

 <p align="center">
  <a href="https://github.com/FlorianBruniaux/claude-code-ultimate-guide/stargazers"><img src="https://img.shields.io/github/stars/FlorianBruniaux/claude-code-ultimate-guide?style=for-the-badge" alt="Stars"/></a>
-  <a href="./examples/"><img src="https://img.shields.io/badge/Templates-82-green?style=for-the-badge" alt="Templates"/></a>
+  <a href="./examples/"><img src="https://img.shields.io/badge/Templates-83-green?style=for-the-badge" alt="Templates"/></a>
  <a href="./quiz/"><img src="https://img.shields.io/badge/Quiz-227_questions-orange?style=for-the-badge" alt="Quiz"/></a>
 </p>

 <p align="center">
  <a href="https://creativecommons.org/licenses/by-sa/4.0/"><img src="https://img.shields.io/badge/License-CC%20BY--SA%204.0-blue.svg" alt="License: CC BY-SA 4.0"/></a>
-  <a href="https://zread.ai/FlorianBruniaux/claude-code-ultimate-guide"><img src="https://img.shields.io/badge/Ask_Zread-_.svg?style=flat&color=00b0aa&labelColor=000000&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTQuOTYxNTYgMS42MDAxSDIuMjQxNTZDMS44ODgxIDEuNjAwMSAxLjYwMTU2IDEuODg2NjQgMS42MDE1NiAyLjI0MDFWNC45NjAxQzEuNjAxNTYgNS4zMTM1NiAxLjg4ODEgNS42MDAxIDIuMjQxNTYgNS42MDAxSDQuOTYxNTZDNS4zMTUwMiA1LjYwMDEgNS42MDE1NiA1LjMxMzU2IDUuNjAxNTYgNC45NjAxVjIuMjQwMUM1LjYwMTU2IDEuODg2NjQgNS4zMTUwMiAxLjYwMDEgNC45NjE1NiAxLjYwMDFaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00Ljk2MTU2IDEwLjM5OTlIMi4yNDE1NkMxLjg4ODEgMTAuMzk5OSAxLjYwMTU2IDEwLjY4NjQgMS42MDE1NiAxMS4wMzk5VjEzLjc1OTlDMS42MDE1NiAxNC4xMTM0IDEuODg4MSAxNC4zOTk5IDIuMjQxNTYgMTQuMzk5OUg0Ljk2MTU2QzUuMzE1MDIgMTQuMzk5OSA1LjYwMTU2IDE0LjExMzQgNS42MDE1NiAxMy43NTk5VjExLjAzOTlDNS42MDE1NiAxMC42ODY0IDUuMzE1MDIgMTAuMzk5OSA0Ljk2MTU2IDEwLjM5OTlaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik0xMy43NTg0IDEuNjAwMUgxMS4wMzg0QzEwLjY4NSAxLjYwMDEgMTAuMzk4NCAxLjg4NjY0IDEwLjM5ODQgMi4yNDAxVjQuOTYwMUMxMC4zOTg0IDUuMzEzNTYgMTAuNjg1IDUuNjAwMSAxMS4wMzg0IDUuNjAwMUgxMy43NTg0QzE0LjExMTkgNS42MDAxIDE0LjM5ODQgNS4zMTM1NiAxNC4zOTg0IDQuOTYwMVYyLjI0MDFDMTQuMzk4NCAxLjg4NjY0IDE0LjExMTkgMS42MDAxIDEzLjc1ODQgMS42MDAxWiIgZmlsbD0iI2ZmZiIvPgo8cGF0aCBkPSJNNCAxMkwxMiA0TDQgMTJaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00IDEyTDEyIDQiIHN0cm9rZT0iI2ZmZiIgc3Ryb2tlLXdpZHRoPSIxLjUiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIvPgo8L3N2Zz4K&logoColor=ffffff" alt="Ask Zread"/></a>
+  <a href="https://zread.ai/FlorianBruniaux/claude-code-ultimate-guide"><img src="https://img.shields.io/badge/Ask_Zread-_.svg?style=flat&color=00b0aa&labelColor=000000&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTQuOTYxNTYgMS42MDAxSDIuMjQxNTZDMS44ODgxIDEuNjAwMSAxLjYwMTU2IDEuODg2NjQgMS42MDE1NiAyLjI0MDFWNC45NjAxQzEuNjAxNTYgNS4zMTM1NiAxLjg4ODEgNS42MDAxIDIuMjQxNTYgNS42MDAxSDQuOTYxNTZDNS4zMTUwMiA1LjYwMDEgNS42MDE1NiA1LjMxMzU2IDUuNjAxNTYgNC45NjAxVjIuMjQwMUM1LjYwMTU2IDEuODg2NjQgNS4zMTUwMiAxLjYwMDEgNC45NjxNTYgMS42MDAxWiIgZmlsbD0iI2ZmZiIvPgo8cGF0aCBkPSJNNC45NjE1NiAxMC4zOTk5SDIuMjQxNTZDMS44ODgxIDEwLjM5OTkgMS42MDE1NiAxMC42ODY0IDEuNjAxNTYgMTEuMDM5OVYxMy43NTk5QzEuNjAxNTYgMTQuMTEzNCAxLjg4ODEgMTQuMzk5OSAyLjI0MTU2IDE0LjM5OTlINC45NjE1NkM1LjMxNTAyIDE0LjM5OTkgNS42MDE1NiAxNC4xMTM0IDUuNjAxNTYgMTMuNzU5OVYxMS4wMzk5QzUuNjAxNTYgMTAuNjg2NCA1LjMxNTAyIDEwLjM5OTkgNC45NjE1NiAxMC4zOTk5WiIgZmlsbD0iI2ZmZiIvPgo8cGF0aCBkPSJNMTMuNzU4NCAxLjYwMDFIMTEuMDM4NEMxMC42ODUgMS42MDAxIDEwLjM5ODQgMS44ODY2NCAxMC4zOTg0IDIuMjQwMVY0Ljk2MDFDMTAuMzk4NCA1LjMxMzU2IDEwLjY4NSA1LjYwMDEgMTEuMDM4NCA1LjYwMDFIMTMuNzU4NEMxNC4xMTE5IDUuNjAwMSAxNC4zOTg0IDUuMzEzNTYgMTQuMzk4NCA0Ljk2MDFWMi4yNDAxQzE0LjM5ODQgMS44ODY2NCAxNC4xMTE5IDEuNjAwMSAxMy43NTg0IDEuNjAwMVoiIGZpbGw9IiNmZmYiLz4KPHBhdGggZD0iTTQgMTJMMTIgNEw0IDEyWiIgZmlsbD0iI2ZmZiIvPgo8cGF0aCBkPSJNNCAxMkwxMiA0IiBzdHJva2U9IiNmZmYiIHN0cm9rZS13aWR0aD0iMS41IiBzdHJva2UtbGluZWNhcD0icm91bmQiLz4KPC9zdmc%2BCg%3D%3D&logoColor=ffffff" alt="Ask Zread"/></a>
 </p>

-> Complete guide to Claude Code with 82 production-ready templates
+> Complete guide to Claude Code with 83 production-ready templates

 ---

@ -155,7 +155,9 @@ cco   # Offline mode (Ollama, 100% local)
 2. [Golden Rules](#-golden-rules) — Key principles
 3. [Data Privacy](./guide/data-privacy.md) — Retention & compliance
 4. [Adoption Approaches](./guide/adoption-approaches.md) — Team strategies
-5. [Context Management](./guide/ultimate-guide.md#22-context-management) — Why it matters
+5. [PM FAQ](./guide/ultimate-guide.md#can-product-managers-use-claude-code) — Code-adjacent vs non-coding PMs
+
+**Note**: Non-coding PMs should consider [Claude Cowork Guide](https://github.com/FlorianBruniaux/claude-cowork-guide) instead (visual interface, no CLI).

 </details>

--- a/guide/ai-ecosystem.md
+++ b/guide/ai-ecosystem.md
@ -805,6 +805,117 @@ claude

 ---

+### 8.1 Multi-Agent Orchestration Systems
+
+When scaling beyond single Claude Code sessions, external orchestration systems coordinate multiple concurrent agents.
+
+#### Overview
+
+| System | Purpose | Backend | Maturity | Monitoring |
+|--------|---------|---------|----------|------------|
+| **Gas Town** | Multi-agent workspace manager | Claude Code instances | Experimental | agent-chat (SSE + SQLite) |
+| **multiclaude** | Self-hosted agent spawner | Claude Code agents | Active dev (383⭐) | agent-chat (JSON logs) |
+| **agent-chat** | Real-time monitoring UI | N/A (reads logs) | Early (v0.2.0) | Dashboard |
+
+#### Gas Town (Steve Yegge)
+
+**What it is**: Orchestrator managing dozens of Claude Code instances with Mad Max-inspired roles:
+- **Mayor**: Central coordinator, generates work, delegates tasks
+- **Polecats**: Ephemeral worker jobs performing coding tasks
+- **Witness**: Supervises workers, helps when stuck
+- **Refinery**: Manages merge queue, resolves conflicts
+
+**Key points**:
+- ✅ Unlocks multi-agent orchestration for Claude Code
+- ⚠️ Extremely expensive (creator needed 2nd Anthropic account for spending limits)
+- ❌ Experimental, not production-grade
+- 🔗 [GitHub repo](https://github.com/steveyegge/gastown)
+
+**When to use**: Complex, high-level tasks requiring parallel agent work (not granular tasks)
+
+#### multiclaude (dlorenc)
+
+**What it is**: Self-hosted system spawning autonomous Claude Code agents:
+- Each agent: separate tmux window + git worktree + branch
+- Auto-creates PRs, CI = ratchet (passing PRs auto-merge)
+- Agent types: worker, supervisor, merge-queue, PR shepherd, reviewer
+
+**Key points**:
+- ✅ Self-hosting since day one (multiclaude builds itself)
+- ✅ Extensible via Markdown agent definitions
+- ✅ Public Go packages: pkg/tmux, pkg/claude
+- 🔗 [GitHub repo](https://github.com/dlorenc/multiclaude)
+
+**When to use**: Teams wanting full control over agent orchestration, on-prem/airgap environments
+
+#### agent-chat (Justin Abrahms)
+
+**What it is**: Real-time monitoring UI (Slack-like) for agent communications:
+- Reads Gas Town's `beads.db` (SQLite) and multiclaude's JSON message files
+- SSE for live updates, workspace channels, unread indicators
+- Zero-config defaults, dark theme
+
+**Key points**:
+- ✅ Unified view across multiple orchestration systems
+- ⚠️ Very new (48h old, v0.2.0)
+- ⚠️ Not compatible with standalone Claude Code (needs Gas Town/multiclaude)
+- 🔗 [GitHub repo](https://github.com/justinabrahms/agent-chat)
+
+**Architecture pattern (transposable to Claude Code)**:
+```
+1. Hook logs Task agent spawns → SQLite
+2. Parent/child relationships tracked
+3. SSE endpoint streams updates
+4. Dashboard UI consumes stream
+```
+
+See: `guide/observability.md` for native Claude Code session monitoring
+
+#### Security & Cost Warnings
+
+**Before using external orchestrators**:
+
+| Risk | Mitigation |
+|------|------------|
+| **Cost explosion** | Set Anthropic spending limits, use Haiku for workers |
+| **Lost work** | "Vibe coding" accepts work loss for throughput - have rollback plan |
+| **Experimental status** | Not for production critical paths, test in staging first |
+| **Context leakage** | Logs may contain sensitive data - review before enabling monitoring UI |
+
+#### Integration with Native Claude Code
+
+If you're not using Gas Town/multiclaude, you can still:
+
+1. **Log multi-instance sessions** via hooks (see `examples/hooks/session-logger.sh`)
+2. **Track `--delegate` operations** with custom hook logging Task agent spawns
+3. **Build lightweight dashboard** using SSE pattern from agent-chat
+
+**Conceptual architecture**:
+```bash
+# Hook: .claude/hooks/multi-agent-logger.sh
+# Triggered on PostToolUse when tool="Task"
+# Logs: timestamp, parent_session_id, child_agent_id, task_description
+
+# Dashboard: Simple Go HTTP server streaming logs via SSE
+# UI: React/HTML consuming SSE stream
+```
+
+#### When NOT to Use Orchestrators
+
+**Use single Claude Code session when**:
+- Task is <3 steps or affects <5 files
+- You need full control/oversight of every change
+- Budget constraints prevent multi-agent costs
+- Codebase is simple enough for sequential work
+
+**Use orchestrators when**:
+- Task naturally parallelizes (multiple independent features)
+- You have budget for parallel agents (multiply costs by N agents)
+- Experimentation tolerance is high (work may be lost/redone)
+- Team has SRE capacity to monitor/intervene
+
+---
+
 ## 9. Cost & Subscription Strategy

 ### Monthly Cost Comparison
--- a/guide/architecture.md
+++ b/guide/architecture.md
@ -510,7 +510,20 @@ Hooks allow programmatic control over Claude's actions:

 MCP (Model Context Protocol) servers extend Claude Code with additional tools.

-### How MCP Works
+### MCP Architecture Overview
+
+> **💡 Visual Guide**: The following diagram illustrates how MCP creates a secure control layer between LLMs and real systems. The LLM layer has **no direct data access** - the MCP Server enforces security policies before tools can interact with databases, APIs, or files.
+
+![MCP Architecture - 7-Layer Security Model](./images/mcp-architecture-diagram.svg)
+
+*Figure 1: MCP Architecture showing separation between thinking (LLM), control (MCP Server), and execution (Tools). Design inspired by [Dinesh Kumar's LinkedIn visualization](https://www.linkedin.com/posts/dinesh-kumar-6b0528b4_model-context-protocol-mcp-why-it-came-activity-7419969525795782656-VoFh), recreated under Apache-2.0 license.*
+
+**Key security boundaries**:
+- **Yellow layer (LLM)**: Reasoning only - **No Data Access**
+- **Orange layer (MCP Server)**: Security control point (policies, validation, logs)
+- **Grey layer (Real Systems)**: Protected data - **Hidden From AI**
+
+### How MCP Works (Technical Details)

 ```
 ┌─────────────────────────────────────────────────────────────┐
--- a/guide/images/mcp-architecture-diagram.svg
+++ b/guide/images/mcp-architecture-diagram.svg
@ -0,0 +1,174 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!--
+  MCP Architecture Diagram - 7-Layer Security Model
+
+  Version: 1.0.0
+  Created: 2026-01-25
+  License: Apache-2.0
+
+  Design inspired by Dinesh Kumar's LinkedIn visualization
+  (https://www.linkedin.com/posts/dinesh-kumar-6b0528b4_model-context-protocol-mcp-why-it-came-activity-7419969525795782656-VoFh)
+  Recreated as original work for Claude Code Ultimate Guide
+
+  Structure:
+  - 7 vertical layers (USER → AI APP → LLM → MCP CLIENT → MCP SERVER → TOOLS → REAL SYSTEMS)
+  - Bottom workflow (5 steps with icons)
+  - Golden rule banner
+
+  Maintenance notes:
+  - Colors are defined in CSS for easy theme changes
+  - Each layer has semantic <g id="layer-N-name"> for targeting
+  - Text sizes: titles 18px, subtitles 14px, body 12px
+-->
+<svg width="900" height="1200" viewBox="0 0 900 1200" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc">
+  <title id="title">MCP Architecture - 7-Layer Security Model</title>
+  <desc id="desc">Diagram showing the Model Context Protocol architecture with 7 layers: User, AI Application, LLM (no data access), MCP Client, MCP Server (control and security), Tools, and Real Systems (hidden from AI). The diagram illustrates how MCP creates a secure control layer between language models and real systems.</desc>
+
+  <defs>
+    <style>
+      /* Layer colors */
+      .layer-user { fill: #2E5266; }
+      .layer-ai-app { fill: #4A7C59; }
+      .layer-llm { fill: #F4C542; }
+      .layer-mcp-client { fill: #5DA5DA; }
+      .layer-mcp-server { fill: #F07B3F; }
+      .layer-tools { fill: #8B5FBF; }
+      .layer-real-systems { fill: #3E3E3E; }
+      .workflow-bg { fill: #F5F5F5; }
+      .golden-rule-bg { fill: #FFD700; }
+      .highlight-box { fill: none; stroke: #000; stroke-width: 2; stroke-dasharray: 5,5; }
+
+      /* Typography */
+      .title { font-family: Arial, Helvetica, sans-serif; font-size: 18px; font-weight: bold; fill: white; }
+      .subtitle { font-family: Arial, Helvetica, sans-serif; font-size: 14px; font-weight: 500; fill: white; opacity: 0.9; }
+      .body { font-family: Arial, Helvetica, sans-serif; font-size: 12px; fill: white; }
+      .highlight { font-family: Arial, Helvetica, sans-serif; font-size: 14px; font-weight: bold; fill: #000; }
+      .workflow-text { font-family: Arial, Helvetica, sans-serif; font-size: 12px; fill: #333; }
+      .golden-text { font-family: Arial, Helvetica, sans-serif; font-size: 16px; font-weight: bold; fill: #000; }
+
+      /* Common styles */
+      .layer-rect { rx: 12; }
+      .shadow { filter: drop-shadow(0 2px 4px rgba(0,0,0,0.1)); }
+    </style>
+  </defs>
+
+  <!-- LAYER 1: USER -->
+  <g id="layer-1-user">
+    <rect class="layer-user layer-rect shadow" x="50" y="50" width="800" height="100"/>
+    <!-- User icon (simple silhouette) -->
+    <circle cx="120" cy="100" r="20" fill="white" opacity="0.9"/>
+    <path d="M 100 135 Q 100 115 120 115 Q 140 115 140 135 Z" fill="white" opacity="0.9"/>
+    <text class="title" x="160" y="95">USER</text>
+    <text class="body" x="160" y="115">Human Asks a Question</text>
+  </g>
+
+  <!-- LAYER 2: AI APPLICATION -->
+  <g id="layer-2-ai-app">
+    <rect class="layer-ai-app layer-rect shadow" x="50" y="180" width="800" height="100"/>
+    <text class="title" x="80" y="215">AI APPLICATION</text>
+    <text class="subtitle" x="80" y="235">Chat UI / Agent / SaaS</text>
+    <text class="body" x="80" y="260">Takes Input, Shows Answer</text>
+  </g>
+
+  <!-- LAYER 3: LLM (with NO DATA ACCESS highlight) -->
+  <g id="layer-3-llm">
+    <rect class="layer-llm layer-rect shadow" x="50" y="310" width="800" height="120"/>
+    <text class="title" x="80" y="350" fill="#000">LLM</text>
+    <text class="body" x="80" y="375" fill="#000">Thinks &amp; Decides</text>
+    <!-- Highlight box -->
+    <rect class="highlight-box" x="400" y="335" width="400" height="60"/>
+    <text class="highlight" x="420" y="358">NO DATA ACCESS</text>
+    <text class="body" x="420" y="378" fill="#000">Reasoning Only - Isolated Layer</text>
+  </g>
+
+  <!-- LAYER 4: MCP CLIENT -->
+  <g id="layer-4-mcp-client">
+    <rect class="layer-mcp-client layer-rect shadow" x="50" y="460" width="800" height="100"/>
+    <text class="title" x="80" y="495">MCP CLIENT</text>
+    <text class="subtitle" x="80" y="515">Library Inside Host</text>
+    <text class="body" x="80" y="540">Sends Structured Request</text>
+  </g>
+
+  <!-- LAYER 5: MCP SERVER (with 3 bullets) -->
+  <g id="layer-5-mcp-server">
+    <rect class="layer-mcp-server layer-rect shadow" x="50" y="590" width="800" height="140"/>
+    <text class="title" x="80" y="625">MCP SERVER</text>
+    <text class="subtitle" x="80" y="645">Control &amp; Security</text>
+    <!-- 3 bullet points -->
+    <text class="body" x="80" y="675">• Tool Registry</text>
+    <text class="body" x="80" y="695">• Policies &amp; Permissions</text>
+    <text class="body" x="80" y="715">• Validation &amp; Logs</text>
+  </g>
+
+  <!-- LAYER 6: TOOLS -->
+  <g id="layer-6-tools">
+    <rect class="layer-tools layer-rect shadow" x="50" y="760" width="800" height="100"/>
+    <text class="title" x="80" y="795">TOOLS</text>
+    <text class="subtitle" x="80" y="815">Safe Backend Logic</text>
+    <text class="body" x="80" y="840">Read DBs, Call APIs, Perform Actions</text>
+  </g>
+
+  <!-- LAYER 7: REAL SYSTEMS (with lock icon and highlight) -->
+  <g id="layer-7-real-systems">
+    <rect class="layer-real-systems layer-rect shadow" x="50" y="890" width="800" height="120"/>
+    <!-- Lock icon (simple padlock) -->
+    <rect x="100" y="930" width="30" height="35" rx="3" fill="white" opacity="0.9"/>
+    <circle cx="115" cy="930" r="12" fill="none" stroke="white" stroke-width="3" opacity="0.9"/>
+    <text class="title" x="150" y="945">REAL SYSTEMS</text>
+    <text class="body" x="150" y="970">Databases, APIs, Files</text>
+    <!-- Highlight box -->
+    <rect class="highlight-box" x="450" y="925" width="350" height="50" stroke="white"/>
+    <text class="highlight" x="470" y="948" fill="white">HIDDEN FROM AI</text>
+    <text class="body" x="470" y="968">Protected Data Layer</text>
+  </g>
+
+  <!-- BOTTOM WORKFLOW (5 steps with icons) -->
+  <g id="workflow">
+    <rect class="workflow-bg" x="50" y="1040" width="800" height="80" rx="8"/>
+
+    <!-- Step 1: User Asks -->
+    <text class="workflow-text" x="80" y="1070" font-size="20">👤</text>
+    <text class="workflow-text" x="70" y="1090">User Asks</text>
+
+    <!-- Arrow -->
+    <path d="M 160 1075 L 190 1075" stroke="#666" stroke-width="2" fill="none" marker-end="url(#arrowhead)"/>
+
+    <!-- Step 2: LLM Thinks -->
+    <text class="workflow-text" x="210" y="1070" font-size="20">🧠</text>
+    <text class="workflow-text" x="195" y="1090">LLM Thinks</text>
+
+    <!-- Arrow -->
+    <path d="M 295 1075 L 325 1075" stroke="#666" stroke-width="2" fill="none" marker-end="url(#arrowhead)"/>
+
+    <!-- Step 3: MCP Controls -->
+    <text class="workflow-text" x="345" y="1070" font-size="20">🛡️</text>
+    <text class="workflow-text" x="320" y="1090">MCP Controls</text>
+
+    <!-- Arrow -->
+    <path d="M 435 1075 L 465 1075" stroke="#666" stroke-width="2" fill="none" marker-end="url(#arrowhead)"/>
+
+    <!-- Step 4: Tools Execute -->
+    <text class="workflow-text" x="485" y="1070" font-size="20">⚙️</text>
+    <text class="workflow-text" x="460" y="1090">Tools Execute</text>
+
+    <!-- Arrow -->
+    <path d="M 565 1075 L 595 1075" stroke="#666" stroke-width="2" fill="none" marker-end="url(#arrowhead)"/>
+
+    <!-- Step 5: Safe Result -->
+    <text class="workflow-text" x="615" y="1070" font-size="20">✅</text>
+    <text class="workflow-text" x="595" y="1090">Safe Result</text>
+  </g>
+
+  <!-- Arrow marker definition -->
+  <defs>
+    <marker id="arrowhead" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <polygon points="0 0, 10 3, 0 6" fill="#666"/>
+    </marker>
+  </defs>
+
+  <!-- GOLDEN RULE BANNER -->
+  <g id="golden-rule">
+    <rect class="golden-rule-bg shadow" x="50" y="1145" width="800" height="45" rx="8"/>
+    <text class="golden-text" x="450" y="1172" text-anchor="middle">LLM Thinks → MCP Controls → Tools Execute → Data Locked</text>
+  </g>
+</svg>
--- a/guide/observability.md
+++ b/guide/observability.md
@ -114,6 +114,36 @@ See [session-search.sh](../examples/scripts/session-search.sh) for the complete

 ---

+### Multi-Agent Orchestration Monitoring
+
+For monitoring multiple concurrent Claude Code instances via external orchestrators (Gas Town, multiclaude), see:
+
+- **agent-chat** (https://github.com/justinabrahms/agent-chat): Real-time Slack-like UI for agent communications
+- **Architecture guide**: `guide/ai-ecosystem.md` Section 8.1 - Multi-Agent Orchestration Systems
+
+**Architecture pattern** (for custom implementations):
+1. Hook logs Task agent spawns: `.claude/hooks/multi-agent-logger.sh`
+2. Store in SQLite: `~/.claude/logs/agents.db` (parent_id, child_id, timestamp, task)
+3. Stream via SSE: Simple Go/Node HTTP server
+4. Dashboard: React/HTML consuming SSE stream
+
+**Native Claude Code monitoring** (this guide):
+- Session search: `session-search.sh` (see [Session Search & Resume](#session-search--resume))
+- Activity logs: `session-logger.sh` hook (see [Setting Up Session Logging](#setting-up-session-logging))
+- Stats analysis: `session-stats.sh` (see [Analyzing Session Data](#analyzing-session-data))
+
+**When to use external orchestrator monitoring**:
+- Running Gas Town or multiclaude with 5+ concurrent agents
+- Need real-time visibility into agent coordination
+- Debugging orchestration failures (agent conflicts, merge issues)
+
+**When native monitoring suffices**:
+- Single Claude Code session or `--delegate` with <3 subagents
+- Post-hoc analysis (logs, stats) is enough
+- Budget/complexity constraints
+
+---
+
 ## Setting Up Session Logging

 ### 1. Install the Logger Hook