docs(diagrams): audit, fix and expand Mermaid diagram suite (7 files → 9)

Phase 1-2 — fixes on existing diagrams: - 01-foundations: add Plan Mode + dontAsk subgraphs (3→5 permission modes) - 04-architecture-internals: add Control Flow Tools category (5→6 tool categories) - 05-mcp-ecosystem: clarify local+user scopes both live in ~/.claude.json - 07-multi-agent-patterns: fix disconnected B2 node (now proper third branch) - 09-cost-and-optimization: replace hardcoded prices with relative ratios + disclaimer Phase 3 — new diagram files: - 11-context-engineering.md: 4 diagrams (3-layer system, budget/adherence, monolithic vs modular, rule placement decision tree) - 12-enterprise-governance.md: 3 diagrams (governance risk tiers, MCP approval workflow, data classification) README.md updated: 41→48 diagrams, navigation table extended, 2 new use-case sections Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-12 16:47:36 +01:00 · 2026-03-12 16:47:36 +01:00 · a4a6c49cb5
commit a4a6c49cb5
parent f9ae40d6a7
8 changed files with 589 additions and 25 deletions
--- a/guide/diagrams/01-foundations.md
+++ b/guide/diagrams/01-foundations.md
@ -1,6 +1,6 @@
 ---
 title: "Claude Code — Foundations Diagrams"
-description: "Core concepts: 4-layer model, workflow pipeline, decision tree, permission modes"
+description: "Core concepts: 4-layer model, workflow pipeline, decision tree, 5 permission modes"
 tags: [foundations, architecture, getting-started]
 ---

@ -208,7 +208,7 @@ Task involves codebase?

 ### Permission Modes Comparison

-Claude Code has 3 permission modes that control what it can do automatically vs. what requires your approval. Choosing the wrong mode is the #1 safety mistake.
+Claude Code has 5 permission modes that control what it can do automatically vs. what requires your approval. Choosing the wrong mode is the #1 safety mistake.

 ```mermaid
 flowchart TD
@ -231,6 +231,18 @@ flowchart TD
        B3["Use only in:<br/>CI/CD, sandboxed<br/>environments"] --> B2
    end

+    subgraph PLAN["🔍 Plan Mode (Read-Only)"]
+        PL1(File reads) --> PL2([Auto-approved])
+        PL3(File writes) --> PL4([Blocked])
+        PL5(Shell commands) --> PL6([Blocked])
+        PL7["Exit with /execute<br/>or Shift+Tab"] --> PL2
+    end
+
+    subgraph DONTASK["🚫 dontAsk Mode"]
+        DA1(ALL operations) --> DA2([Auto-denied])
+        DA3["Unless pre-approved<br/>via /permissions add"] --> DA2
+    end
+
    style D2 fill:#7BC47F,color:#333
    style D4 fill:#E87E2F,color:#fff
    style D6 fill:#E87E2F,color:#fff
@ -241,6 +253,11 @@ flowchart TD
    style A8 fill:#E87E2F,color:#fff
    style B2 fill:#E85D5D,color:#fff
    style B3 fill:#F5E6D3,color:#333
+    style PL2 fill:#7BC47F,color:#333
+    style PL4 fill:#E85D5D,color:#fff
+    style PL6 fill:#E85D5D,color:#fff
+    style DA2 fill:#E85D5D,color:#fff
+    style DA3 fill:#F5E6D3,color:#333

    click D1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#14-permission-modes" "Default Mode — Permission Modes"
    click D2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#14-permission-modes" "Auto-approved"
@ -261,6 +278,16 @@ flowchart TD
    click B1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#14-permission-modes" "bypassPermissions Mode"
    click B2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#14-permission-modes" "Auto-approved (all)"
    click B3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#14-permission-modes" "CI/CD, sandboxed only"
+    click PL1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#14-permission-modes" "Plan Mode — File reads"
+    click PL2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#14-permission-modes" "Auto-approved"
+    click PL3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#14-permission-modes" "Plan Mode — File writes blocked"
+    click PL4 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#14-permission-modes" "Blocked"
+    click PL5 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#14-permission-modes" "Plan Mode — Shell commands blocked"
+    click PL6 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#14-permission-modes" "Blocked"
+    click PL7 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#14-permission-modes" "Exit Plan Mode"
+    click DA1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#14-permission-modes" "dontAsk Mode — All operations"
+    click DA2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#14-permission-modes" "Auto-denied"
+    click DA3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#14-permission-modes" "Pre-approve via /permissions add"
 ```

 <details>
@ -273,6 +300,13 @@ File reads    → AUTO ✓       File reads    → AUTO ✓    ALL ops → AUTO
 File writes   → PROMPT       File writes   → AUTO ✓
 Shell cmds    → PROMPT       Shell cmds    → PROMPT    Use: CI/CD only,
 Risky ops     → PROMPT       Risky ops     → PROMPT    sandboxed env
+
+Plan Mode (Read-Only)        dontAsk Mode
+─────────────────────        ────────────
+File reads    → AUTO ✓       ALL ops → AUTO DENIED ✗
+File writes   → BLOCKED ✗    Unless pre-approved via
+Shell cmds    → BLOCKED ✗    /permissions add
+Exit: /execute or Shift+Tab
 ```

 </details>
--- a/guide/diagrams/04-architecture-internals.md
+++ b/guide/diagrams/04-architecture-internals.md
@ -76,7 +76,7 @@ Tool calls?                          │

 ### Tool Categories & Selection

-Claude Code has 5 tool categories, each optimized for different operations. Understanding which tool Claude chooses (and why) helps you write instructions that guide better tool selection.
+Claude Code has 6 tool categories, each optimized for different operations. Understanding which tool Claude chooses (and why) helps you write instructions that guide better tool selection.

 ```mermaid
 flowchart TD
@ -85,6 +85,7 @@ flowchart TD
    ROOT --> EXECUTE
    ROOT --> WEB
    ROOT --> WORKFLOW
+    ROOT --> CONTROL

    subgraph READ["📖 Read Tools"]
        R1[Glob<br/>Find files by pattern]
@ -114,6 +115,12 @@ flowchart TD
        WF2[NotebookEdit<br/>Jupyter notebooks]
    end

+    subgraph CONTROL["🎛️ Control Flow Tools"]
+        CF1[EnterPlanMode / ExitPlanMode<br/>Toggle plan mode]
+        CF2[EnterWorktree / ExitWorktree<br/>Worktree navigation]
+        CF3[AskUserQuestion<br/>Request human input]
+    end
+
    style ROOT fill:#E87E2F,color:#fff
    style R1 fill:#6DB3F2,color:#fff
    style R2 fill:#6DB3F2,color:#fff
@ -128,6 +135,9 @@ flowchart TD
    style WB2 fill:#7BC47F,color:#333
    style WF1 fill:#B8B8B8,color:#333
    style WF2 fill:#B8B8B8,color:#333
+    style CF1 fill:#B8B8B8,color:#333
+    style CF2 fill:#B8B8B8,color:#333
+    style CF3 fill:#B8B8B8,color:#333

    click ROOT href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "Claude Code Tools"
    click R1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "Glob — Find files by pattern"
@ -143,6 +153,10 @@ flowchart TD
    click WB2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "WebFetch"
    click WF1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "TodoWrite — Task list"
    click WF2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "NotebookEdit — Jupyter"
+    click CONTROL href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "Control Flow Tools"
+    click CF1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "EnterPlanMode / ExitPlanMode"
+    click CF2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "EnterWorktree / ExitWorktree"
+    click CF3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "AskUserQuestion"
 ```

 <details>
@ -154,12 +168,15 @@ WRITE:    Write (create), Edit (modify), MultiEdit (batch)
 EXECUTE:  Bash (shell), Task (sub-agent)  ← most powerful/risky
 WEB:      WebSearch, WebFetch
 WORKFLOW: TodoWrite, NotebookEdit
+CONTROL:  EnterPlanMode/ExitPlanMode, EnterWorktree/ExitWorktree, AskUserQuestion
 ```

 </details>

 > **Source**: [Architecture: Tools](../core/architecture.md#tools) — Line ~213

+> *Simplified — additional tools available. See [Architecture: Tool Arsenal](../core/architecture.md#tools) for the full list.*
+
 ---

 ### System Prompt Assembly
--- a/guide/diagrams/05-mcp-ecosystem.md
+++ b/guide/diagrams/05-mcp-ecosystem.md
@ -215,7 +215,7 @@ DEFENSE: Read MCP source before installing. Especially check tool descriptions.

 ### MCP Config Hierarchy

-MCP server configurations can live in 4 different locations. The resolution order determines which servers are available and who can override what.
+MCP server configurations can live in 4 priority levels (3 actual files). The resolution order determines which servers are available and who can override what.

 ```mermaid
 flowchart TD
@ -228,6 +228,9 @@ flowchart TD
    B1["Use for:<br/>Team-shared servers<br/>(playwright, github)"] --> B
    D1["Use for:<br/>Personal tools<br/>(context7, grepai)"] --> D

+    NOTE2["⚠️ local + user scopes<br/>both stored in ~/.claude.json<br/>(separate configuration keys)"] -.-> C
+    NOTE2 -.-> D
+
    style A fill:#E87E2F,color:#fff
    style B fill:#6DB3F2,color:#fff
    style C fill:#6DB3F2,color:#fff
@ -236,6 +239,7 @@ flowchart TD
    style A1 fill:#B8B8B8,color:#333
    style B1 fill:#B8B8B8,color:#333
    style D1 fill:#B8B8B8,color:#333
+    style NOTE2 fill:#F5E6D3,color:#333

    click A href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#83-configuration" "CLI --mcp-config flag"
    click B href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#83-configuration" "Project .claude/mcp.json"
@ -257,6 +261,7 @@ PRIORITY (highest → lowest):
 3. ~/.claude.json      → local scope (private, current project)
 4. ~/.claude.json      → user scope (personal, all projects)
 5. (none)             → no MCP servers available
+* local + user both in ~/.claude.json (different keys)
 ```

 </details>
--- a/guide/diagrams/07-multi-agent-patterns.md
+++ b/guide/diagrams/07-multi-agent-patterns.md
@ -279,6 +279,7 @@ flowchart TD
    A([Task to complete]) --> B{Need multiple<br/>Claude instances?}
    B -->|No| C([Single session<br/>Standard usage])
    B -->|Yes| D{How many<br/>instances?}
+    B -->|"Planning separation?"| B2{Need planning<br/>separation?}

    D -->|2-3| E{Need branch<br/>isolation?}
    E -->|Yes| F([Git worktrees<br/>Separate branches])
@ -289,7 +290,7 @@ flowchart TD
    H -->|Sequential pipeline| J([Agent pipeline<br/>A → B → C])
    H -->|Mixed expertise| K([Specialist router<br/>Route by task type])

-    B2{Need planning<br/>separation?} --> L([Dual-instance<br/>Planner + Executor])
+    B2 --> L([Dual-instance<br/>Planner + Executor])

    style A fill:#F5E6D3,color:#333
    style B fill:#E87E2F,color:#fff
@ -326,16 +327,15 @@ flowchart TD
 ```
 Need multiple instances?
 ├─ No → Single session
-└─ Yes → How many?
-         ├─ 2-3 → Need branch isolation?
-         │        ├─ Yes → Git worktrees
-         │        └─ No  → Multiple terminals
-         └─ 4+  → Task structure?
-                  ├─ Independent → Task tool (parallel sub-agents)
-                  ├─ Sequential  → Agent pipeline A→B→C
-                  └─ Mixed       → Specialist router
-
-Special case: Need planning separation? → Dual-instance (Planner + Executor)
+├─ Yes → How many?
+│        ├─ 2-3 → Need branch isolation?
+│        │        ├─ Yes → Git worktrees
+│        │        └─ No  → Multiple terminals
+│        └─ 4+  → Task structure?
+│                 ├─ Independent → Task tool (parallel sub-agents)
+│                 ├─ Sequential  → Agent pipeline A→B→C
+│                 └─ Mixed       → Specialist router
+└─ Planning separation? → Dual-instance (Planner + Executor)
 ```

 </details>
--- a/guide/diagrams/09-cost-and-optimization.md
+++ b/guide/diagrams/09-cost-and-optimization.md
@ -21,14 +21,14 @@ flowchart TD
    A([Task to complete]) --> B{Task complexity?}

    B -->|Simple| C["Simple tasks:<br/>typo fixes, renames,<br/>formatting, translations"]
-    C --> D([Haiku 4.5<br/>💰 Cheapest, fastest<br/>~$0.80/MTok input])
+    C --> D([Haiku 4.5<br/>💰 Cheapest, fastest<br/>~5x cheaper than Sonnet])

    B -->|Standard| E["Standard tasks:<br/>feature implementation,<br/>bug fixes, refactoring"]
-    E --> F([Sonnet 4.5/4.6<br/>💰💰 Balanced<br/>~$3/MTok input])
+    E --> F([Sonnet 4.5/4.6<br/>💰💰 Balanced<br/>Best price/quality ratio])

    B -->|Complex| G{Needs deep<br/>reasoning?}
    G -->|Yes| H["Complex tasks:<br/>architecture decisions,<br/>security review,<br/>multi-file analysis"]
-    H --> I([Opus 4.6 / Sonnet + --think-hard<br/>💰💰💰 Most capable<br/>~$15/MTok input])
+    H --> I([Opus 4.6 / Sonnet + --think-hard<br/>💰💰💰 Most capable<br/>~5x more than Sonnet])

    G -->|No: just large| J["Large but clear tasks:<br/>big refactors,<br/>doc generation"]
    J --> F
@ -56,6 +56,8 @@ flowchart TD
    click J href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#25-model-selection--thinking-guide" "Large but clear tasks"
 ```

+> **Pricing**: Relative costs shown — check current rates at [anthropic.com/pricing](https://www.anthropic.com/pricing).
+
 **Budget modifier** — On constrained plans, downgrade one tier per phase:

 | Plan | Planning phase | Implementation phase |
@ -71,11 +73,11 @@ flowchart TD

 ```
 Task complexity?
-├─ Simple (typos, format, rename) → Haiku 4.5    ($  — ~5x cheaper)
-├─ Standard (features, bugs)      → Sonnet 4.5/4.6 ($$ — balanced)
+├─ Simple (typos, format, rename) → Haiku 4.5       ($  — ~5x cheaper than Sonnet)
+├─ Standard (features, bugs)      → Sonnet 4.5/4.6  ($$ — best price/quality ratio)
 └─ Complex (architecture, sec.)
-   ├─ Needs deep reasoning?        → Opus 4.6      ($$$ — most capable)
-   └─ Just large/clear?            → Sonnet 4.6    ($$ — handles it)
+   ├─ Needs deep reasoning?        → Opus 4.6        ($$$ — ~5x more than Sonnet)
+   └─ Just large/clear?            → Sonnet 4.6      ($$ — handles it)

 Budget modifier (downgrade one tier on constrained plans):
  Max/API    → Opus plan, Sonnet impl
--- a/guide/diagrams/11-context-engineering.md
+++ b/guide/diagrams/11-context-engineering.md
@ -0,0 +1,285 @@
+---
+title: "Claude Code — Context Engineering Diagrams"
+description: "3-layer context system, adherence degradation, modular architecture, rule placement decision tree"
+tags: [context-engineering, configuration, architecture, modular, adherence]
+---
+
+# Context Engineering
+
+How to fill Claude's context window with the right information at the right time — and how architectural choices determine whether Claude consistently follows your conventions.
+
+> "Context engineering is the art of filling the context window with the right information at the right time." — Andrej Karpathy
+
+---
+
+### The 3-Layer Context System
+
+Context engineering operates across 3 distinct layers with different scopes and persistence. Understanding which layer to use prevents the most common mistake: cramming everything into one file.
+
+```mermaid
+flowchart TD
+    subgraph GLOBAL["🌍 Layer 1: Global — ~/.claude/CLAUDE.md"]
+        G1["Identity & tone preferences"]
+        G2["Universal tool preferences"]
+        G3["Cross-project coding conventions"]
+        G4["Target: under 200 lines"]
+    end
+
+    subgraph PROJECT["📁 Layer 2: Project — ./CLAUDE.md + path modules"]
+        P1["Stack & architecture decisions"]
+        P2["Team conventions + deployment rules"]
+        P3["Path-scoped @imports for subsystems"]
+        P4["Target: under 150 lines (root) + modules"]
+    end
+
+    subgraph SESSION["⚡ Layer 3: Session — inline instructions, /add, flags"]
+        S1["One-off task constraints"]
+        S2["Temporary overrides"]
+        S3["Ephemeral — not persisted after session"]
+    end
+
+    GLOBAL --> PROJECT --> SESSION
+
+    OVR["Override order: Session > Project > Global<br/>More specific beats less specific<br/>Later-declared beats earlier at same level"] -.-> SESSION
+
+    style G1 fill:#E87E2F,color:#fff
+    style G2 fill:#E87E2F,color:#fff
+    style G3 fill:#E87E2F,color:#fff
+    style G4 fill:#B8B8B8,color:#333
+    style P1 fill:#6DB3F2,color:#fff
+    style P2 fill:#6DB3F2,color:#fff
+    style P3 fill:#6DB3F2,color:#fff
+    style P4 fill:#B8B8B8,color:#333
+    style S1 fill:#F5E6D3,color:#333
+    style S2 fill:#F5E6D3,color:#333
+    style S3 fill:#B8B8B8,color:#333
+    style OVR fill:#7BC47F,color:#333
+
+    click G1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "Identity & tone"
+    click G2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "Universal tools"
+    click G3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "Cross-project conventions"
+    click G4 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "Target: under 200 lines"
+    click P1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "Stack & architecture"
+    click P2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "Team conventions"
+    click P3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "Path-scoped imports"
+    click P4 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#4-modular-architecture" "Target: under 150 lines"
+    click S1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "One-off constraints"
+    click S2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "Temporary overrides"
+    click S3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "Ephemeral"
+    click OVR href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "Override semantics"
+```
+
+<details>
+<summary>ASCII version</summary>
+
+```
+GLOBAL ~/.claude/CLAUDE.md     → Identity, universal tools, cross-project conventions (<200 lines)
+    │ overridden by ↓
+PROJECT ./CLAUDE.md + modules  → Stack, architecture, team rules, path-scoped @imports (<150 lines root)
+    │ overridden by ↓
+SESSION inline / /add / flags  → One-off constraints, temporary overrides (ephemeral)
+
+Override order: Session > Project > Global
+More specific beats less specific at the same level
+```
+
+</details>
+
+> **Source**: [Context Engineering — Configuration Hierarchy](../core/context-engineering.md#3-configuration-hierarchy)
+
+---
+
+### Context Budget & Adherence Degradation
+
+Adherence to CLAUDE.md rules degrades predictably as file size grows. Beyond ~150 rules, models begin selectively ignoring instructions. Path-scoping is the primary fix — it reduces always-on context by 40-50% without losing coverage.
+
+```mermaid
+flowchart LR
+    subgraph ZONES["Adherence by CLAUDE.md lines"]
+        Z1["1–100 lines<br/>~95% adherence ✓"]
+        Z2["100–200 lines<br/>~88% adherence"]
+        Z3["200–400 lines<br/>~75% adherence ⚠️"]
+        Z4["400–600 lines<br/>~60% adherence"]
+        Z5["600+ lines<br/>~45% and falling ✗"]
+    end
+
+    Z1 --> Z2 --> Z3 --> Z4 --> Z5
+
+    FIX["✅ Path-scoping fix:<br/>Root CLAUDE.md: shared rules only (~2K tokens)<br/>Per subsystem: module loaded on demand<br/>Result: 40–50% always-on reduction<br/>Adherence stays in green zone"] -.-> Z1
+
+    SIGNALS["🔴 Signs of context overload:<br/>Rule silencing (80% followed, some ignored)<br/>Contradictory behavior across files<br/>Generic outputs instead of project-specific<br/>Slow first responses"] -.-> Z5
+
+    style Z1 fill:#7BC47F,color:#333
+    style Z2 fill:#7BC47F,color:#333
+    style Z3 fill:#E87E2F,color:#fff
+    style Z4 fill:#E85D5D,color:#fff
+    style Z5 fill:#E85D5D,color:#fff
+    style FIX fill:#7BC47F,color:#333
+    style SIGNALS fill:#E85D5D,color:#fff
+
+    click Z1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#2-the-context-budget" "1-100 lines: ~95%"
+    click Z2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#2-the-context-budget" "100-200 lines: ~88%"
+    click Z3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#2-the-context-budget" "200-400 lines: ~75%"
+    click Z4 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#2-the-context-budget" "400-600 lines: ~60%"
+    click Z5 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#2-the-context-budget" "600+ lines: ~45%"
+    click FIX href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#2-the-context-budget" "Path-scoping fix"
+    click SIGNALS href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#2-the-context-budget" "Signs of overload"
+```
+
+<details>
+<summary>ASCII version</summary>
+
+```
+Lines in CLAUDE.md    Adherence    Status
+──────────────────    ─────────    ──────
+1 – 100               ~95%         ✓ Green zone
+100 – 200             ~88%         ✓ Acceptable
+200 – 400             ~75%         ⚠️ Caution
+400 – 600             ~60%         ✗ Degraded
+600+                  ~45% ↓       ✗ Critical
+
+Fix: path-scope by subsystem → root CLAUDE.md stays <150 lines
+Result: 40-50% always-on context reduction, adherence back in green zone
+```
+
+</details>
+
+> **Source**: [Context Budget](../core/context-engineering.md#2-the-context-budget) — Adherence data: HumanLayer production data (15-25% improvement with structured context)
+
+---
+
+### Monolithic vs. Modular Architecture
+
+The monolithic CLAUDE.md is the most common failure mode in team contexts. Path-scoped modules fix it by loading only what's relevant for the current task.
+
+```mermaid
+flowchart TD
+    subgraph BAD["❌ Anti-Pattern: Monolithic CLAUDE.md"]
+        B1(["CLAUDE.md (600 lines)<br/>API rules + DB rules + UI rules<br/>+ Deploy rules — all mixed together"])
+        B2("All 600 lines loaded<br/>for every session, every file")
+        B3("Rules 1–20 get ~95% attention<br/>Rules 500+ get ~30% attention")
+        B4(["Adherence degrades continuously"])
+        B1 --> B2 --> B3 --> B4
+        style B1 fill:#E85D5D,color:#fff
+        style B2 fill:#E85D5D,color:#fff
+        style B3 fill:#E87E2F,color:#fff
+        style B4 fill:#E85D5D,color:#fff
+    end
+
+    subgraph GOOD["✅ Best Practice: Path-Scoped Modules"]
+        G1(["CLAUDE.md root (~100 lines)<br/>Shared rules only + @import declarations"])
+        G2["src/api/CLAUDE-api.md<br/>Loaded ONLY when in src/api/"]
+        G3["src/components/CLAUDE-components.md<br/>Loaded ONLY when in src/components/"]
+        G4["prisma/CLAUDE-db.md<br/>Loaded ONLY when in prisma/"]
+        G5(["Each module: full coverage<br/>Always-on: 40–50% smaller"])
+        G1 --> G2
+        G1 --> G3
+        G1 --> G4
+        G2 & G3 & G4 --> G5
+        style G1 fill:#7BC47F,color:#333
+        style G2 fill:#6DB3F2,color:#fff
+        style G3 fill:#6DB3F2,color:#fff
+        style G4 fill:#6DB3F2,color:#fff
+        style G5 fill:#7BC47F,color:#333
+    end
+
+    click B1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#4-modular-architecture" "Anti-pattern: monolith"
+    click B4 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#2-the-context-budget" "Adherence degradation"
+    click G1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#4-modular-architecture" "Root CLAUDE.md"
+    click G2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#4-modular-architecture" "API module"
+    click G3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#4-modular-architecture" "Components module"
+    click G4 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#4-modular-architecture" "DB module"
+    click G5 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#4-modular-architecture" "Result: coverage with less bloat"
+```
+
+<details>
+<summary>ASCII version</summary>
+
+```
+BAD: CLAUDE.md (600 lines, everything mixed)
+  → All 600 lines loaded every session
+  → Rules 500+ get ~30% attention weight
+  → Adherence degrades continuously
+
+GOOD: Root CLAUDE.md (~100 lines, shared only)
+  + src/api/CLAUDE-api.md      ← loaded only when editing API files
+  + src/components/CLAUDE-*.md ← loaded only when editing components
+  + prisma/CLAUDE-db.md        ← loaded only when editing DB files
+
+Result: 40-50% reduction in always-on tokens, full coverage per subsystem
+```
+
+</details>
+
+> **Source**: [Modular Architecture](../core/context-engineering.md#4-modular-architecture) — Path-scoping pattern
+
+---
+
+### Rule Placement Decision Tree
+
+Every new instruction or convention needs to land in the right layer. Wrong placement wastes tokens (too global) or loses coverage (too scoped). This tree makes the decision explicit.
+
+```mermaid
+flowchart TD
+    A([New rule or instruction to place]) --> B{Relevant to\nevery project\nyou work on?}
+    B -->|Yes| C([Global CLAUDE.md<br/>~/.claude/CLAUDE.md])
+
+    B -->|No| D{Specific to\ncertain files\nor subsystems?}
+    D -->|Yes| E([Path-scoped module<br/>e.g. src/api/CLAUDE-api.md])
+
+    D -->|No| F{Procedural<br/>step-by-step\nworkflow?}
+    F -->|Yes: how to do something| G([Skill file<br/>.claude/skills/task-name.md<br/>Loaded on demand, not always-on])
+
+    F -->|No: constraint or standard| H{Applies to<br/>whole project?}
+    H -->|Yes| I([Project CLAUDE.md root<br/>./CLAUDE.md])
+    H -->|No: one task only| J([Session inline instruction<br/>Tell Claude directly this session])
+
+    RULE["Rule of thumb:<br/>If you write it more than once<br/>it belongs in a permanent layer"] -.-> J
+
+    style A fill:#F5E6D3,color:#333
+    style B fill:#E87E2F,color:#fff
+    style D fill:#E87E2F,color:#fff
+    style F fill:#E87E2F,color:#fff
+    style H fill:#E87E2F,color:#fff
+    style C fill:#E87E2F,color:#fff
+    style E fill:#6DB3F2,color:#fff
+    style G fill:#6DB3F2,color:#fff
+    style I fill:#6DB3F2,color:#fff
+    style J fill:#F5E6D3,color:#333
+    style RULE fill:#7BC47F,color:#333
+
+    click A href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "New rule to place"
+    click B href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "Relevant to every project?"
+    click C href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#31-memory-files-claudemd" "Global CLAUDE.md"
+    click D href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#4-modular-architecture" "Specific to certain files?"
+    click E href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#4-modular-architecture" "Path-scoped module"
+    click F href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#4-modular-architecture" "Procedural workflow?"
+    click G href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#51-understanding-skills" "Skill file"
+    click H href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "Whole project?"
+    click I href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#31-memory-files-claudemd" "Project CLAUDE.md root"
+    click J href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "Session inline"
+    click RULE href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "Rule of thumb"
+```
+
+<details>
+<summary>ASCII version</summary>
+
+```
+New rule to place
+│
+Relevant to every project? ──Yes──► Global CLAUDE.md (~/.claude/CLAUDE.md)
+│ No
+Specific to certain files/subsystems? ──Yes──► Path-scoped module (src/area/CLAUDE-area.md)
+│ No
+Procedural step-by-step? ──Yes──► Skill file (.claude/skills/) [loaded on demand]
+│ No
+Applies to whole project? ──Yes──► Project CLAUDE.md root (./CLAUDE.md)
+│ No
+└──► Session inline instruction (ephemeral)
+
+Rule of thumb: if you say it more than once, promote it to a permanent layer.
+```
+
+</details>
+
+> **Source**: [Rule Placement](../core/context-engineering.md#3-configuration-hierarchy) — Decision tree from §3
--- a/guide/diagrams/12-enterprise-governance.md
+++ b/guide/diagrams/12-enterprise-governance.md
@ -0,0 +1,208 @@
+---
+title: "Claude Code — Enterprise Governance Diagrams"
+description: "Governance risk tiers, MCP approval workflow, guardrail tier selection"
+tags: [security, enterprise, governance, compliance, mcp]
+---
+
+# Enterprise Governance
+
+Org-level patterns for teams deploying Claude Code at scale — usage tiers, MCP approval workflows, and guardrail configurations.
+
+> **Audience**: Tech leads, engineering managers, security officers. For individual dev security see [Security & Production](./08-security-and-production.md).
+
+---
+
+### Governance Risk Tiers — What to Control and When
+
+Not everything needs heavy governance. This decision tree routes your context to the right control level based on actual risk — from personal dev workflow (minimal) to regulated environments (full compliance stack).
+
+```mermaid
+flowchart TD
+    A([What are you governing?]) --> B{Usage context?}
+
+    B --> P["Personal dev workflow<br/>Local, throwaway code<br/>One developer only"]
+    B --> T["Team codebase<br/>Shared repo, not production<br/>5–20 developers"]
+    B --> PR["Production system<br/>Customer-facing, real data<br/>Any team size"]
+    B --> REG["Regulated environment<br/>HIPAA, SOC2, PCI, finance<br/>Legal/compliance obligations"]
+
+    P --> TIER1(["Tier 1: Starter<br/>CLAUDE.md guidelines<br/>+ dangerous-actions-blocker hook<br/>10 min setup"])
+    T --> TIER2(["Tier 2: Standard<br/>Shared settings.json + MCP registry<br/>+ PR gates + audit log<br/>~2 hours setup"])
+    PR --> TIER3(["Tier 3: Strict<br/>Full permission deny list<br/>+ approval workflow<br/>+ session audit trail"])
+    REG --> TIER4(["Tier 4: Regulated<br/>All of above<br/>+ compliance audit trail<br/>+ SOC2/ISO27001 controls"])
+
+    NOTE["You CAN control: MCP servers, tool permissions,<br/>CLAUDE.md content, hooks, CI/CD gates<br/>You CANNOT control: personal ~/.claude settings,<br/>models on personal API keys, personal projects"] -.-> B
+
+    style A fill:#F5E6D3,color:#333
+    style B fill:#E87E2F,color:#fff
+    style P fill:#B8B8B8,color:#333
+    style T fill:#6DB3F2,color:#fff
+    style PR fill:#E87E2F,color:#fff
+    style REG fill:#E85D5D,color:#fff
+    style TIER1 fill:#7BC47F,color:#333
+    style TIER2 fill:#7BC47F,color:#333
+    style TIER3 fill:#E87E2F,color:#fff
+    style TIER4 fill:#E85D5D,color:#fff
+    style NOTE fill:#F5E6D3,color:#333
+
+    click A href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#1-local-vs-shared-the-governance-split" "What are you governing?"
+    click B href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#1-local-vs-shared-the-governance-split" "Usage context?"
+    click P href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#4-guardrail-tiers" "Personal dev workflow"
+    click T href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#4-guardrail-tiers" "Team codebase"
+    click PR href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#4-guardrail-tiers" "Production system"
+    click REG href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#4-guardrail-tiers" "Regulated environment"
+    click TIER1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#4-guardrail-tiers" "Tier 1: Starter"
+    click TIER2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#4-guardrail-tiers" "Tier 2: Standard"
+    click TIER3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#4-guardrail-tiers" "Tier 3: Strict"
+    click TIER4 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#4-guardrail-tiers" "Tier 4: Regulated"
+    click NOTE href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#12-what-you-can-and-cant-control" "What you can/cannot control"
+```
+
+<details>
+<summary>ASCII version</summary>
+
+```
+Usage context?
+├─ Personal dev workflow      → Tier 1: Starter     (CLAUDE.md + basic hooks, 10 min)
+├─ Team codebase              → Tier 2: Standard    (shared settings.json + MCP registry + PR gates)
+├─ Production system          → Tier 3: Strict      (full deny list + approval + audit trail)
+└─ Regulated (HIPAA/SOC2/PCI) → Tier 4: Regulated  (all above + compliance audit trail)
+
+You CAN control: settings.json in repo, CLAUDE.md, hooks, CI/CD gates, MCP registry
+You CANNOT control: personal ~/.claude, personal API key model choice, personal projects
+```
+
+</details>
+
+> **Source**: [Enterprise Governance](../security/enterprise-governance.md) — §1 Governance Split, §4 Guardrail Tiers
+
+---
+
+### MCP Governance Workflow
+
+Individual MCP vetting takes 5 minutes. Organizational MCP governance is the 5-step pipeline that ensures approved servers stay approved, versions are pinned, and risk is classified before deployment.
+
+```mermaid
+sequenceDiagram
+    participant DEV as Developer
+    participant TL as Tech Lead + Security
+    participant REG as MCP Registry<br/>.claude/mcp-registry.yaml
+    participant REPO as Shared Config Repo<br/>settings.json
+
+    DEV->>TL: Submit MCP request<br/>Name, source URL, use case, data scope
+
+    TL->>TL: 5-min security audit<br/>Stars >50? Recent commits?<br/>CVEs? Dangerous flags?
+    TL->>TL: Classify risk: LOW / MEDIUM / HIGH
+
+    alt LOW risk
+        TL->>REG: Approve — add to registry<br/>Pin version, set 6-month expiry
+    else MEDIUM or HIGH risk
+        TL->>TL: 2-week sandbox trial<br/>+ Security team sign-off
+        TL->>REG: Approve with restrictions<br/>Shorter expiry (3 months)
+    else HIGH risk (unacceptable)
+        TL->>DEV: Denied — document reason in registry
+    end
+
+    REG->>REPO: Deploy via committed settings.json<br/>No local overrides for approved MCPs
+    Note over REPO: Version-pinned, team-wide, auditable
+
+    REPO->>TL: Monitor every 30 days<br/>Patch bumps: auto re-approve<br/>Minor+ bumps: manual re-review<br/>Quarterly: full registry audit
+```
+
+<details>
+<summary>ASCII version</summary>
+
+```
+Developer submits MCP request (name, source, use case, data scope)
+    │
+Tech Lead: 5-min security audit (stars, commits, CVEs, flags)
+    │
+Classify risk: LOW / MEDIUM / HIGH
+    │
+┌───┴────────────────────────────┐
+LOW                             MED/HIGH
+Approve immediately             2-week sandbox trial
+                                + Security team sign-off
+    │
+Add to registry (.claude/mcp-registry.yaml)
+  - Pin exact version
+  - Set expiry (6 months for LOW, 3 months for MED)
+  - Document approved scope
+    │
+Deploy via committed settings.json (no local overrides)
+    │
+Monitor every 30 days:
+  - Check security advisories
+  - Patch bumps: auto | Minor+ bumps: manual re-review
+  - Quarterly: full registry audit
+```
+
+</details>
+
+> **Source**: [MCP Governance Workflow](../security/enterprise-governance.md#3-mcp-governance-workflow) — §3.1 Approval Workflow
+
+---
+
+### Data Classification & Claude Code Access Rules
+
+Data classification determines what Claude Code is allowed to read and process. Getting this wrong is the highest-impact governance failure. Four levels, clear rules, no exceptions for RESTRICTED.
+
+```mermaid
+flowchart LR
+    subgraph PUBLIC["🟢 PUBLIC"]
+        PU1["Open source code<br/>Public documentation<br/>Shared blog content"]
+        PU2(["Allowed — no restrictions"])
+    end
+
+    subgraph INTERNAL["🔵 INTERNAL"]
+        IN1["Internal tools<br/>Non-sensitive code<br/>Team documentation"]
+        IN2(["Allowed — standard config"])
+    end
+
+    subgraph CONFIDENTIAL["🟠 CONFIDENTIAL"]
+        CO1["Internal business secrets<br/>Non-regulated IP<br/>Architecture docs"]
+        CO2(["Enterprise plan only<br/>Zero Data Retention required"])
+    end
+
+    subgraph RESTRICTED["🔴 RESTRICTED"]
+        RE1["Customer PII<br/>PCI card data / PHI<br/>Credentials & API keys"]
+        RE2(["NEVER in AI context<br/>Block via permissions.deny<br/>No exceptions"])
+    end
+
+    PU1 --> PU2
+    IN1 --> IN2
+    CO1 --> CO2
+    RE1 --> RE2
+
+    style PU2 fill:#7BC47F,color:#333
+    style IN2 fill:#6DB3F2,color:#fff
+    style CO2 fill:#E87E2F,color:#fff
+    style RE2 fill:#E85D5D,color:#fff
+    style RE1 fill:#E85D5D,color:#fff
+
+    click PU1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#2-ai-usage-charter" "PUBLIC data"
+    click IN1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#2-ai-usage-charter" "INTERNAL data"
+    click CO1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#2-ai-usage-charter" "CONFIDENTIAL data"
+    click RE1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#2-ai-usage-charter" "RESTRICTED data"
+    click PU2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#2-ai-usage-charter" "PUBLIC: allowed"
+    click IN2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#2-ai-usage-charter" "INTERNAL: standard config"
+    click CO2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#2-ai-usage-charter" "CONFIDENTIAL: Enterprise only"
+    click RE2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#2-ai-usage-charter" "RESTRICTED: never in AI context"
+```
+
+<details>
+<summary>ASCII version</summary>
+
+```
+PUBLIC       → Allowed, no restrictions
+INTERNAL     → Allowed, standard config
+CONFIDENTIAL → Enterprise plan only (Zero Data Retention required)
+RESTRICTED   → NEVER in AI context (PII, PCI, PHI, credentials)
+               Block via: permissions.deny Read(.env, *.key, *.pem, secrets/**)
+
+Hard rule: RESTRICTED data never enters a context window.
+Not in prompts, not in files Claude reads, not as examples.
+```
+
+</details>
+
+> **Source**: [AI Usage Charter](../security/enterprise-governance.md#2-ai-usage-charter) — §2.1 Data Classification
--- a/guide/diagrams/README.md
+++ b/guide/diagrams/README.md
@ -1,12 +1,12 @@
 ---
 title: "Claude Code — Visual Diagrams"
-description: "41 Mermaid interactive diagrams covering all major Claude Code concepts"
+description: "48 Mermaid interactive diagrams covering all major Claude Code concepts"
 tags: [reference, architecture, diagrams, mermaid]
 ---

 # Claude Code — Visual Diagrams

-41 interactive Mermaid diagrams organized in 10 thematic files. Each diagram includes a Mermaid version (rendered natively on GitHub) and an ASCII fallback.
+48 interactive Mermaid diagrams organized in 10 thematic files. Each diagram includes a Mermaid version (rendered natively on GitHub) and an ASCII fallback.

 > For ASCII-only diagrams and a printable visual reference → [visual-reference.md](../core/visual-reference.md)

@ -52,7 +52,9 @@ All diagrams use the consistent Bold Guy palette:
 | [08-security-and-production.md](./08-security-and-production.md) | 4 | 3-layer defense, sandbox decision, verification paradox, CI/CD pipeline |
 | [09-cost-and-optimization.md](./09-cost-and-optimization.md) | 4 | Model selection, cost optimization, subscription tiers, token reduction |
 | [10-adoption-and-learning.md](./10-adoption-and-learning.md) | 3 | Onboarding paths, UVAL protocol, trust calibration |
-| **Total** | **41** | |
+| [11-context-engineering.md](./11-context-engineering.md) | 4 | 3-layer context system, adherence degradation, modular architecture, rule placement |
+| [12-enterprise-governance.md](./12-enterprise-governance.md) | 3 | Governance risk tiers, MCP approval workflow, data classification |
+| **Total** | **48** | |

 ---

@ -93,6 +95,17 @@ All diagrams use the consistent Bold Guy palette:
 2. [MCP Architecture](./05-mcp-ecosystem.md#mcp-architecture-client-server) — How it works
 3. [MCP Config Hierarchy](./05-mcp-ecosystem.md#mcp-config-hierarchy) — Where configs live

+### "I want to govern Claude Code across my team"
+1. [Governance Risk Tiers](./12-enterprise-governance.md#governance-risk-tiers) — Which control level fits your context?
+2. [MCP Governance Workflow](./12-enterprise-governance.md#mcp-governance-workflow) — Approval pipeline for MCP servers
+3. [Data Classification Rules](./12-enterprise-governance.md#data-classification--claude-code-access-rules) — What Claude can and cannot access
+
+### "I want to improve Claude's context adherence"
+1. [Rule Placement Decision Tree](./11-context-engineering.md#rule-placement-decision-tree) — Where does this rule go?
+2. [3-Layer Context System](./11-context-engineering.md#the-3-layer-context-system) — Global / Project / Session
+3. [Context Budget & Adherence](./11-context-engineering.md#context-budget--adherence-degradation) — Why rules stop being followed
+4. [Modular Architecture](./11-context-engineering.md#monolithic-vs-modular-architecture) — Path-scoping as the fix
+
 ---

 *Back to [guide/README.md](../README.md) | ASCII diagrams → [visual-reference.md](../core/visual-reference.md)*