diff --git a/README.md b/README.md
index 7e5b90c..d91905b 100644
--- a/README.md
+++ b/README.md
@@ -6,16 +6,16 @@
- 
+ 
- 
+ 
-> 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).
diff --git a/guide/ai-ecosystem.md b/guide/ai-ecosystem.md
index 8104bb8..f96e666 100644
--- 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
diff --git a/guide/architecture.md b/guide/architecture.md
index 32a532a..6275954 100644
--- 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.
+
+
+
+*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)
```
┌─────────────────────────────────────────────────────────────┐
diff --git a/guide/images/mcp-architecture-diagram.svg b/guide/images/mcp-architecture-diagram.svg
new file mode 100644
index 0000000..4155972
--- /dev/null
+++ b/guide/images/mcp-architecture-diagram.svg
@@ -0,0 +1,174 @@
+
+
+
diff --git a/guide/observability.md b/guide/observability.md
index 2747fee..4690d15 100644
--- 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