From 59ba1ae174e243df6e71b0e52a1edc78bbe7d2a2 Mon Sep 17 00:00:00 2001
From: Florian BRUNIAUX <florian@bruniaux.com>
Date: Sat, 31 Jan 2026 23:14:41 +0100
Subject: [PATCH] release: v3.20.5 - 4 new ASCII diagrams (visual-reference.md)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add visual-reference.md with 20 ASCII diagrams (16 existing + 4 new)
  - #17 TDD Red-Green-Refactor Cycle
  - #18 UVAL Protocol Flow
  - #19 Security 3-Layer Defense
  - #20 Secret Exposure Timeline
- Add Visual Reference to README Core Documentation table
- Version sync: 3.20.4 → 3.20.5

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 CHANGELOG.md                    |  11 +
 README.md                       |   3 +-
 VERSION                         |   2 +-
 guide/cheatsheet.md             |   4 +-
 guide/ultimate-guide.md         |   4 +-
 guide/visual-reference.md       | 762 ++++++++++++++++++++++++++++++++
 machine-readable/reference.yaml |   8 +-
 7 files changed, 785 insertions(+), 9 deletions(-)
 create mode 100644 guide/visual-reference.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 09a4657..f9a3b8f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
+## [3.20.5] - 2026-01-31
+
+### Added
+
+- **Visual Reference**: 4 new high-value ASCII diagrams (16 → 20 total)
+  - **#17 TDD Red-Green-Refactor Cycle** — Cyclic loop showing the iterative nature of TDD
+  - **#18 UVAL Protocol Flow** — 4-step learning framework (Understand → Verify → Apply → Learn) with failure backtrack paths
+  - **#19 Security 3-Layer Defense** — Prevention/Detection/Response overview with adoption path by team size
+  - **#20 Secret Exposure Timeline** — Emergency response actions by time window (15min/1h/24h) with severity guide
+- **README.md**: Added Visual Reference to Core Documentation table
+
 ## [3.20.4] - 2026-01-31
 
 ### Added
diff --git a/README.md b/README.md
index 05a1b9e..4f5bf2b 100644
--- a/README.md
+++ b/README.md
@@ -369,6 +369,7 @@ Claude Code sends your prompts, file contents, and MCP results to Anthropic serv
 |------|---------|------|
 | **[Ultimate Guide](./guide/ultimate-guide.md)** | Complete reference (~16K lines), 10 sections | ~4 hours |
 | **[Cheat Sheet](./guide/cheatsheet.md)** | 1-page printable reference | 5 min |
+| **[Visual Reference](./guide/visual-reference.md)** | 20 ASCII diagrams for key concepts | 5 min |
 | **[Architecture](./guide/architecture.md)** | How Claude Code works internally | 25 min |
 | **[Methodologies](./guide/methodologies.md)** | TDD, SDD, BDD reference | 20 min |
 | **[Workflows](./guide/workflows/)** | Practical guides (TDD, Plan-Driven, Task Management) | 30 min |
@@ -483,7 +484,7 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
 
 ---
 
-*Version 3.20.4 | January 2026 | Crafted with Claude*
+*Version 3.20.5 | January 2026 | Crafted with Claude*
 
 <!-- SEO Keywords -->
 <!-- claude code, claude code tutorial, anthropic cli, ai coding assistant, claude code mcp,
diff --git a/VERSION b/VERSION
index c253e50..2505f2e 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-3.20.4
+3.20.5
diff --git a/guide/cheatsheet.md b/guide/cheatsheet.md
index 59f4daa..89a8522 100644
--- a/guide/cheatsheet.md
+++ b/guide/cheatsheet.md
@@ -6,7 +6,7 @@
 
 **Written with**: Claude (Anthropic)
 
-**Version**: 3.20.4 | **Last Updated**: January 2026
+**Version**: 3.20.5 | **Last Updated**: January 2026
 
 ---
 
@@ -484,4 +484,4 @@ where.exe claude; claude doctor; claude mcp list
 
 **Author**: Florian BRUNIAUX | [@Méthode Aristote](https://methode-aristote.fr) | Written with Claude
 
-*Last updated: January 2026 | Version 3.20.4*
+*Last updated: January 2026 | Version 3.20.5*
diff --git a/guide/ultimate-guide.md b/guide/ultimate-guide.md
index 998e621..b92ba00 100644
--- a/guide/ultimate-guide.md
+++ b/guide/ultimate-guide.md
@@ -10,7 +10,7 @@
 
 **Last updated**: January 2026
 
-**Version**: 3.20.4
+**Version**: 3.20.5
 
 ---
 
@@ -16290,4 +16290,4 @@ We'll evaluate and add it to this section if it meets quality criteria.
 
 **Contributions**: Issues and PRs welcome.
 
-**Last updated**: January 2026 | **Version**: 3.20.4
+**Last updated**: January 2026 | **Version**: 3.20.5
diff --git a/guide/visual-reference.md b/guide/visual-reference.md
new file mode 100644
index 0000000..ccfda56
--- /dev/null
+++ b/guide/visual-reference.md
@@ -0,0 +1,762 @@
+# Claude Code — Visual Reference
+
+All diagrams in one place. Quick visual overview of Claude Code's key concepts.
+For detailed docs → [Ultimate Guide](./ultimate-guide.md) | [Cheatsheet](./cheatsheet.md)
+
+> **20 diagrams**: 8 new (this file) + 12 from existing guides, all consolidated here.
+
+---
+
+## Table of Contents
+
+**New diagrams:**
+1. [Context Management Zones](#1-context-management-zones)
+2. [Permission Modes Cycle](#2-permission-modes-cycle)
+3. [Workflow Pipeline (9 Steps)](#3-workflow-pipeline-9-steps)
+4. [Quick Decision Tree](#4-quick-decision-tree)
+
+**Architecture & Internals:**
+5. [Master Loop](#5-master-loop)
+6. [Hook Event Flow](#6-hook-event-flow)
+7. [Data Privacy Flow](#7-data-privacy-flow)
+
+**Security:**
+8. [MCP Rug Pull Attack](#8-mcp-rug-pull-attack)
+9. [Docker Sandbox Architecture](#9-docker-sandbox-architecture)
+
+**Decision Trees:**
+10. [Search Tool Selection](#10-search-tool-selection)
+11. [Trust Calibration Flow](#11-trust-calibration-flow)
+12. [Adoption Decision Tree](#12-adoption-decision-tree)
+13. [Methodology Selection](#13-methodology-selection)
+
+**Workflows:**
+14. [Research → Spec → Code](#14-research--spec--code)
+15. [Review Auto-Correction Loop](#15-review-auto-correction-loop)
+16. [PDF Pipeline Stack](#16-pdf-pipeline-stack)
+
+**Development & Learning:**
+17. [TDD Red-Green-Refactor Cycle](#17-tdd-red-green-refactor-cycle)
+18. [UVAL Protocol Flow](#18-uval-protocol-flow)
+
+**Security (extended):**
+19. [Security 3-Layer Defense](#19-security-3-layer-defense)
+20. [Secret Exposure Timeline](#20-secret-exposure-timeline)
+
+---
+
+## 1. Context Management Zones
+
+How to react based on context window usage (check with `/status`):
+
+```
+Context Usage
+0%          50%         70%         90%       100%
+├───────────┼───────────┼───────────┼──────────┤
+│   GREEN   │  YELLOW   │  ORANGE   │   RED    │
+│  work     │ selective │ /compact  │  /clear  │
+│  freely   │ with care │   NOW     │ required │
+└───────────┴───────────┴───────────┴──────────┘
+              ▲                       ▲
+              │                       │
+         Be selective            Risk: forgetting
+         about reads             instructions,
+         and tool use            hallucinations
+```
+
+**Actions by zone:**
+- **Green (0-50%)** — Full speed. Read files, explore freely.
+- **Yellow (50-70%)** — Be selective. Avoid unnecessary file reads.
+- **Orange (70-90%)** — Run `/compact` immediately. Context is degrading.
+- **Red (90%+)** — Run `/clear` and restart. Responses are unreliable.
+
+→ Source: [ultimate-guide.md:1335](./ultimate-guide.md)
+
+---
+
+## 2. Permission Modes Cycle
+
+Cycle through modes with `Shift+Tab`:
+
+```
+                 Shift+Tab              Shift+Tab
+  ┌──────────┐ ────────────→ ┌───────────────┐ ────────────→ ┌───────────┐
+  │ DEFAULT  │               │  AUTO-ACCEPT   │               │ PLAN MODE │
+  │          │               │                │               │           │
+  │ edit=ask │               │ edit=auto      │               │ edit=no   │
+  │ exec=ask │               │ exec=ask       │               │ exec=no   │
+  └──────────┘ ←──────────── └───────────────┘ ←──────────── └───────────┘
+                 Shift+Tab              Shift+Tab
+```
+
+**When to use each mode:**
+
+| Mode | Use when... | Risk level |
+|------|-------------|------------|
+| **Default** | Normal development — review each change | Low |
+| **Auto-accept** | Trusted tasks (formatting, refactoring) | Medium |
+| **Plan mode** | Complex/risky operations — explore safely first | None |
+
+**Shortcuts:**
+- `Shift+Tab` — Cycle to next mode
+- `Shift+Tab × 2` — Jump to plan mode from default
+- `/plan` — Enter plan mode directly
+- `/execute` — Exit plan mode
+
+→ Source: [ultimate-guide.md:760](./ultimate-guide.md)
+
+---
+
+## 3. Workflow Pipeline (9 Steps)
+
+The recommended workflow for every task:
+
+```
+  ┌─────────┐    ┌──────────┐    ┌────────────┐    ┌─────────────┐
+  │ 1.START │───→│ 2./status│───→│ 3. plan?   │───→│ 4. describe │
+  │ claude  │    │ check ctx│    │ Shift+Tab×2│    │ WHAT/WHERE  │
+  └─────────┘    └──────────┘    │ (if risky) │    │ HOW/VERIFY  │
+                                 └────────────┘    └──────┬──────┘
+                                                          │
+      ┌───────────────────────────────────────────────────┘
+      │
+      ▼
+  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
+  │ 5.review │───→│ 6. y/n   │───→│ 7. test  │───→│ 8.commit │───→│9./compact│
+  │   diff   │    │ accept?  │    │   run    │    │ when done│    │ when >70%│
+  └──────────┘    └──────────┘    └──────────┘    └──────────┘    └──────────┘
+```
+
+**Key principles:**
+- **Step 2**: Always check context before starting. If >70%, `/compact` first.
+- **Step 3**: Use plan mode for anything risky, complex, or multi-file.
+- **Step 4**: Be specific — vague prompts produce vague results.
+- **Step 5**: Read every diff. Never blindly accept.
+- **Step 9**: Compact after each task to stay in the green zone.
+
+→ Source: [ultimate-guide.md:277](./ultimate-guide.md)
+
+---
+
+## 4. Quick Decision Tree
+
+What to do based on your situation:
+
+```
+What do you need?
+│
+├─ Simple task ─────────────────→ Just ask Claude
+│
+├─ Complex task
+│  ├─ Single session ───────────→ /plan + Tasks API
+│  └─ Multi-session ────────────→ Tasks API + CLAUDE_CODE_TASK_LIST_ID
+│
+├─ Repeating task ──────────────→ Create agent or command
+│
+├─ Context >70% ────────────────→ /compact
+│
+├─ Context >90% ────────────────→ /clear (restart conversation)
+│
+├─ Need library docs ───────────→ Context7 MCP
+│
+├─ Deep debugging ──────────────→ Opus model + Alt+T (thinking)
+│
+├─ UI from design ──────────────→ Figma MCP or screenshot input
+│
+└─ Team rollout ────────────────→ Read adoption-approaches.md
+```
+
+→ Source: [reference.yaml](../machine-readable/reference.yaml) (decide section)
+
+---
+
+## 5. Master Loop
+
+The entire architecture is a simple `while` loop — no DAG, no classifier, no RAG.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    CLAUDE CODE MASTER LOOP                  │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│   ┌──────────────┐                                          │
+│   │  Your Prompt │                                          │
+│   └──────┬───────┘                                          │
+│          │                                                  │
+│          ▼                                                  │
+│   ┌──────────────────────────────────────────────────────┐  │
+│   │                                                      │  │
+│   │                  CLAUDE REASONS                      │  │
+│   │        (No classifier, no routing layer)             │  │
+│   │                                                      │  │
+│   └────────────────────────┬─────────────────────────────┘  │
+│                            │                                │
+│                            ▼                                │
+│                   ┌────────────────┐                        │
+│                   │  Tool Call?    │                        │
+│                   └───────┬────────┘                        │
+│                           │                                 │
+│              YES          │           NO                    │
+│         ┌─────────────────┴─────────────────┐               │
+│         │                                   │               │
+│         ▼                                   ▼               │
+│  ┌────────────┐                      ┌────────────┐         │
+│  │  Execute   │                      │   Text     │         │
+│  │   Tool     │                      │  Response  │         │
+│  │            │                      │   (DONE)   │         │
+│  └─────┬──────┘                      └────────────┘         │
+│        │                                                    │
+│        ▼                                                    │
+│  ┌─────────────┐                                            │
+│  │ Feed Result │                                            │
+│  │  to Claude  │──────────────────┐                         │
+│  └─────────────┘                  │                         │
+│                                   │                         │
+│                                   ▼                         │
+│                          ┌────────────────┐                 │
+│                          │   LOOP BACK    │                 │
+│                          │  (Next turn)   │                 │
+│                          └────────────────┘                 │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+→ Source: [architecture.md:84](./architecture.md)
+
+---
+
+## 6. Hook Event Flow
+
+How hooks intercept Claude Code's execution pipeline:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                      EVENT FLOW                         │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│   User types message                                    │
+│        │                                                │
+│        ▼                                                │
+│   ┌────────────────────┐                                │
+│   │ UserPromptSubmit   │  ← Add context (git status)    │
+│   └────────────────────┘                                │
+│        │                                                │
+│        ▼                                                │
+│   Claude decides to run tool (e.g., Edit)               │
+│        │                                                │
+│        ▼                                                │
+│   ┌────────────────────┐                                │
+│   │ PreToolUse         │  ← Security check              │
+│   └────────────────────┘                                │
+│        │                                                │
+│        ▼ (if allowed)                                   │
+│   Tool executes                                         │
+│        │                                                │
+│        ▼                                                │
+│   ┌────────────────────┐                                │
+│   │ PostToolUse        │  ← Auto-format                 │
+│   └────────────────────┘                                │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+→ Source: [ultimate-guide.md:6327](./ultimate-guide.md)
+
+---
+
+## 7. Data Privacy Flow
+
+What data leaves your machine when using Claude Code:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    YOUR LOCAL MACHINE                       │
+├─────────────────────────────────────────────────────────────┤
+│  • Prompts you type                                         │
+│  • Files Claude reads (including .env if not excluded!)     │
+│  • MCP server results (SQL queries, API responses)          │
+│  • Bash command outputs                                     │
+│  • Error messages and stack traces                          │
+└───────────────────────┬─────────────────────────────────────┘
+                        │
+                        ▼ HTTPS
+┌─────────────────────────────────────────────────────────────┐
+│                    ANTHROPIC API                            │
+├─────────────────────────────────────────────────────────────┤
+│  • Processes your request                                   │
+│  • Stores conversation based on retention policy            │
+│  • May use data for model training (if not opted out)       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+→ Source: [data-privacy.md:24](./data-privacy.md)
+
+---
+
+## 8. MCP Rug Pull Attack
+
+How a malicious MCP server can exploit the one-time approval model:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  1. Attacker publishes benign MCP "code-formatter"          │
+│                         ↓                                    │
+│  2. User adds to ~/.claude/mcp.json, approves once          │
+│                         ↓                                    │
+│  3. MCP works normally for 2 weeks (builds trust)           │
+│                         ↓                                    │
+│  4. Attacker pushes malicious update (no re-approval!)      │
+│                         ↓                                    │
+│  5. MCP exfiltrates ~/.ssh/*, .env, credentials             │
+└─────────────────────────────────────────────────────────────┘
+MITIGATION: Version pinning + hash verification + monitoring
+```
+
+→ Source: [security-hardening.md:33](./security-hardening.md)
+
+---
+
+## 9. Docker Sandbox Architecture
+
+Full isolation for autonomous Claude Code sessions:
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                     HOST MACHINE                          │
+│                                                          │
+│  ┌────────────────────────────────────────────────────┐  │
+│  │              DOCKER SANDBOX (microVM)               │  │
+│  │                                                    │  │
+│  │  ┌──────────────┐  ┌───────────────────────────┐  │  │
+│  │  │ Claude Code   │  │ Private Docker daemon     │  │  │
+│  │  │ (--dsp mode)  │  │ (isolated from host)      │  │  │
+│  │  └──────────────┘  └───────────────────────────┘  │  │
+│  │                                                    │  │
+│  │  ┌──────────────────────────────────────────────┐  │  │
+│  │  │ Workspace: ~/my-project (synced with host)   │  │  │
+│  │  │ Same absolute path as host                   │  │  │
+│  │  └──────────────────────────────────────────────┘  │  │
+│  │                                                    │  │
+│  │  Base: Ubuntu, Node.js, Python 3, Go, Git,        │  │
+│  │        Docker CLI, GitHub CLI, ripgrep, jq         │  │
+│  │  User: non-root 'agent' with sudo                 │  │
+│  └────────────────────────────────────────────────────┘  │
+│                                                          │
+│  Host Docker daemon: NOT accessible from sandbox          │
+│  Host filesystem: NOT accessible (except workspace)       │
+└──────────────────────────────────────────────────────────┘
+```
+
+→ Source: [sandbox-isolation.md:87](./sandbox-isolation.md)
+
+---
+
+## 10. Search Tool Selection
+
+3-level decision tree for choosing the right search tool:
+
+**Level 1: What Do You Know?**
+
+```
+Do you know the EXACT text/pattern?
+│
+├─ YES → Use rg (ripgrep)
+│  ├─ Known function name: rg "createSession"
+│  ├─ Known import: rg "import.*React"
+│  └─ Known pattern: rg "async function"
+│
+└─ NO → Go to Level 2
+```
+
+**Level 2: What Are You Looking For?**
+
+```
+What's your search intent?
+│
+├─ "Find by MEANING/CONCEPT"
+│  → Use grepai
+│  └─ Example: grepai search "payment validation logic"
+│
+├─ "Find FUNCTION/CLASS definition"
+│  → Use Serena
+│  └─ Example: serena find_symbol --name "UserController"
+│
+├─ "Find by CODE STRUCTURE"
+│  → Use ast-grep
+│  └─ Example: async without error handling
+│
+└─ "Understand DEPENDENCIES"
+   → Use grepai trace
+   └─ Example: grepai trace callers "validatePayment"
+```
+
+**Level 3: Optimization**
+
+```
+Found too many results?
+│
+├─ rg → Add --type filter or narrow path
+├─ grepai → Add --path filter or use trace
+├─ Serena → Filter by symbol type (function/class)
+└─ ast-grep → Add constraints to pattern
+```
+
+→ Source: [search-tools-mastery.md:75](./workflows/search-tools-mastery.md)
+
+---
+
+## 11. Trust Calibration Flow
+
+How much to review AI-generated code based on risk level:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                 TRUST CALIBRATION FLOW                  │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│  AI generates code                                      │
+│         │                                               │
+│         ▼                                               │
+│  ┌──────────────┐                                       │
+│  │ What type?   │                                       │
+│  └──────────────┘                                       │
+│    │    │    │                                          │
+│    ▼    ▼    ▼                                          │
+│  Boiler Business Security                               │
+│  -plate  logic   critical                               │
+│    │      │        │                                    │
+│    ▼      ▼        ▼                                    │
+│  Skim   Test +   Full review                            │
+│  only   review   + tools                                │
+│    │      │        │                                    │
+│    └──────┴────────┘                                    │
+│            │                                            │
+│            ▼                                            │
+│    Tests pass? ──No──► Debug & fix                      │
+│            │                                            │
+│           Yes                                           │
+│            │                                            │
+│            ▼                                            │
+│        Ship it                                          │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+→ Source: [ultimate-guide.md:1182](./ultimate-guide.md)
+
+---
+
+## 12. Adoption Decision Tree
+
+How to choose your Claude Code adoption strategy:
+
+```
+Starting Claude Code?
+│
+├─ Need to ship today?
+│   └─ YES → Turnkey Quickstart
+│   └─ NO ↓
+│
+├─ Team needs shared conventions?
+│   └─ YES → Turnkey + document what matters to you
+│   └─ NO ↓
+│
+├─ Want to understand before configuring?
+│   └─ YES → Autonomous Learning Path
+│   └─ NO → Turnkey, adjust as you go
+```
+
+→ Source: [adoption-approaches.md:51](./adoption-approaches.md)
+
+---
+
+## 13. Methodology Selection
+
+Which development methodology to use:
+
+```
+┌─ "I want quality code" ────────────→ workflows/tdd-with-claude.md
+│
+├─ "I want to spec before code" ─────→ workflows/spec-first.md
+│
+├─ "I need to plan architecture" ────→ workflows/plan-driven.md
+│
+├─ "I'm iterating on something" ─────→ workflows/iterative-refinement.md
+│
+└─ "I need methodology theory" ──────→ methodologies.md
+```
+
+→ Source: [methodologies.md:24](./methodologies.md)
+
+---
+
+## 14. Research → Spec → Code
+
+Using Perplexity for research, then Claude Code for implementation:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ 1. PERPLEXITY (Deep Research)                           │
+│    "Research best practices for JWT refresh tokens      │
+│     in Next.js 15. Include security considerations,     │
+│     common pitfalls, and library recommendations."      │
+│                                                         │
+│    → Output: 2000-word spec with sources               │
+└───────────────────────────┬─────────────────────────────┘
+                            ↓ Export as spec.md
+┌─────────────────────────────────────────────────────────┐
+│ 2. CLAUDE CODE                                          │
+│    > claude                                             │
+│    "Implement JWT refresh tokens following spec.md.     │
+│     Use the jose library as recommended."               │
+│                                                         │
+│    → Output: Working implementation with tests         │
+└─────────────────────────────────────────────────────────┘
+```
+
+→ Source: [ai-ecosystem.md:155](./ai-ecosystem.md)
+
+---
+
+## 15. Review Auto-Correction Loop
+
+Iterative code review pattern where Claude reviews, fixes, and re-reviews:
+
+```
+┌─────────────────────────────────────────┐
+│   Review Auto-Correction Loop           │
+│                                          │
+│   Review (identify issues)               │
+│        ↓                                 │
+│   Fix (apply corrections)                │
+│        ↓                                 │
+│   Re-Review (verify fixes)               │
+│        ↓                                 │
+│   Converge (minimal changes) → Done      │
+│        ↑                                 │
+│        └──── Repeat (max iterations)     │
+└─────────────────────────────────────────┘
+```
+
+→ Source: [iterative-refinement.md:354](./workflows/iterative-refinement.md)
+
+---
+
+## 16. PDF Pipeline Stack
+
+Quarto + Typst stack for generating professional PDFs:
+
+```
+┌─────────────────────────────────────────────────┐
+│                  Your .qmd File                 │
+│         (Markdown + YAML frontmatter)           │
+└─────────────────────────────────────────────────┘
+                        │
+                        ▼
+┌─────────────────────────────────────────────────┐
+│                    Quarto                       │
+│           (Document rendering engine)           │
+│         • Processes YAML metadata               │
+│         • Handles extensions                    │
+│         • Manages output formats                │
+└─────────────────────────────────────────────────┘
+                        │
+          ┌─────────────┴─────────────┐
+          ▼                           ▼
+┌─────────────────────┐    ┌─────────────────────┐
+│       Pandoc        │    │       Typst         │
+│   (MD → AST → ?)    │    │  (Typography/PDF)   │
+│  • Markdown parser  │    │  • Modern engine    │
+│  • AST transforms   │    │  • Fast compilation │
+│  • Format bridges   │    │  • No LaTeX needed  │
+└─────────────────────┘    └─────────────────────┘
+                        │
+                        ▼
+┌─────────────────────────────────────────────────┐
+│                  document.pdf                   │
+│        (Professional typography output)         │
+└─────────────────────────────────────────────────┘
+```
+
+→ Source: [pdf-generation.md:58](./workflows/pdf-generation.md)
+
+---
+
+## 17. TDD Red-Green-Refactor Cycle
+
+The iterative loop at the heart of Test-Driven Development:
+
+```
+                    ┌──────────────────────────┐
+                    │                          │
+                    ▼                          │
+            ┌──────────────┐                   │
+            │   🔴 RED      │                   │
+            │              │                   │
+            │  Write a     │                   │
+            │  failing     │                   │
+            │  test        │                   │
+            └──────┬───────┘                   │
+                   │                           │
+                   │ Tests FAIL                │
+                   │ (expected)                │
+                   ▼                           │
+            ┌──────────────┐                   │
+            │   🟢 GREEN   │                   │
+            │              │                   │
+            │  Write       │                   │
+            │  minimal     │                   │
+            │  code to     │                   │
+            │  pass        │                   │
+            └──────┬───────┘                   │
+                   │                           │
+                   │ Tests PASS                │
+                   │ (minimal)                 │
+                   ▼                           │
+            ┌──────────────┐                   │
+            │   🔵 REFACTOR│                   │
+            │              │                   │
+            │  Clean up    │                   │
+            │  while tests │                   │
+            │  stay green  │                   │
+            └──────┬───────┘                   │
+                   │                           │
+                   │ Next feature              │
+                   └───────────────────────────┘
+
+Key rules:
+  RED    → Test must FAIL before writing implementation
+  GREEN  → Write ONLY enough code to pass (no more)
+  REFACTOR → Improve structure, tests must stay green
+  REPEAT → One feature at a time, always in this order
+```
+
+> Source: [workflows/tdd-with-claude.md:78](./workflows/tdd-with-claude.md)
+
+---
+
+## 18. UVAL Protocol Flow
+
+Systematic framework for learning with AI without losing your edge:
+
+```
+  ┌────────────────────────────────────────────────────────────┐
+  │                    UVAL PROTOCOL                           │
+  │         (Use AI without losing your edge)                  │
+  └────────────────────────────────────────────────────────────┘
+
+  ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
+  │    U     │     │    V     │     │    A     │     │    L     │
+  │UNDERSTAND│────→│  VERIFY  │────→│  APPLY   │────→│  LEARN   │
+  │          │     │          │     │          │     │          │
+  │ 15-min   │     │ Can you  │     │ Modify   │     │ Capture  │
+  │ rule:    │     │ explain  │     │ the code │     │ insights │
+  │          │     │ it back? │     │ yourself │     │ for long │
+  │ 1.State  │     │          │     │          │     │ term     │
+  │   problem│     │ Test:    │     │ Tasks:   │     │          │
+  │ 2.Brain- │     │ explain  │     │ • Extend │     │ Methods: │
+  │   storm  │     │ to a     │     │ • Modify │     │ • Notes  │
+  │ 3.Find   │     │ colleague│     │ • Debug  │     │ • Teach  │
+  │   gaps   │     │ without  │     │ • Adapt  │     │ • Blog   │
+  │ 4.Ask    │     │ looking  │     │   to new │     │ • Review │
+  │   smart  │     │ at code  │     │   context│     │   later  │
+  └──────────┘     └──────────┘     └──────────┘     └──────────┘
+       │                                                   │
+       │              ◄── Repeat per concept ──►           │
+       └───────────────────────────────────────────────────┘
+
+  If VERIFY fails → go back to UNDERSTAND (you copied, didn't learn)
+  If APPLY fails  → go back to VERIFY (you memorized, didn't understand)
+```
+
+> Source: [learning-with-ai.md:208](./learning-with-ai.md)
+
+---
+
+## 19. Security 3-Layer Defense
+
+The full security document (security-hardening.md) organized as 3 defense layers:
+
+```
+  ┌─────────────────────────────────────────────────────────────┐
+  │                  SECURITY 3-LAYER DEFENSE                   │
+  ├─────────────────────────────────────────────────────────────┤
+  │                                                             │
+  │  TIME ──────────────────────────────────────────────────►   │
+  │         Before              During             After        │
+  │                                                             │
+  │  ┌─────────────────┐ ┌─────────────────┐ ┌───────────────┐ │
+  │  │ LAYER 1         │ │ LAYER 2         │ │ LAYER 3       │ │
+  │  │ PREVENTION      │ │ DETECTION       │ │ RESPONSE      │ │
+  │  │                 │ │                 │ │               │ │
+  │  │ • MCP vetting   │ │ • Prompt inject │ │ • Secret      │ │
+  │  │   workflow      │ │   detection     │ │   rotation    │ │
+  │  │ • Version       │ │ • Output        │ │ • MCP         │ │
+  │  │   pinning       │ │   scanning      │ │   isolation   │ │
+  │  │ • .claudeignore │ │ • Anomaly       │ │ • History     │ │
+  │  │ • Input hooks   │ │   monitoring    │ │   rewriting   │ │
+  │  │ • Safe MCP list │ │ • Secret leak   │ │ • Incident    │ │
+  │  │ • Permissions   │ │   detection     │ │   reporting   │ │
+  │  │ • Integrity     │ │ • Unicode/ANSI  │ │ • Post-mortem │ │
+  │  │   scanning      │ │   filtering     │ │   & rotation  │ │
+  │  │                 │ │                 │ │               │ │
+  │  │  GOAL: Block    │ │  GOAL: Catch    │ │  GOAL: Limit  │ │
+  │  │  threats at     │ │  attacks in     │ │  damage and   │ │
+  │  │  entry points   │ │  real-time      │ │  recover fast │ │
+  │  └─────────────────┘ └─────────────────┘ └───────────────┘ │
+  │                                                             │
+  │  Adoption path:                                             │
+  │  Solo dev    → Layer 1 basics (output scanner)              │
+  │  Team        → Layer 1 + 2 (+ injection hooks)              │
+  │  Enterprise  → All 3 layers (+ ZDR + verification)          │
+  │                                                             │
+  └─────────────────────────────────────────────────────────────┘
+```
+
+> Source: [security-hardening.md:24/205/345](./security-hardening.md)
+
+---
+
+## 20. Secret Exposure Timeline
+
+Emergency response when a secret (API key, token, password) is exposed:
+
+```
+  SECRET EXPOSED — Emergency Response Timeline
+  ═══════════════════════════════════════════════════════════
+
+  0 min                15 min              1 hour             24 hours
+  │                    │                   │                  │
+  ▼                    ▼                   ▼                  ▼
+  ┌──────────────────┐ ┌─────────────────┐ ┌────────────────┐
+  │ ⏱️ FIRST 15 MIN   │ │ ⏱️ FIRST HOUR    │ │ ⏱️ FIRST 24H    │
+  │ Stop the         │ │ Assess damage   │ │ Remediate      │
+  │ bleeding         │ │                 │ │                │
+  │                  │ │ 3. Audit git    │ │ 6. Rotate ALL  │
+  │ 1. REVOKE key    │ │    history      │ │    related     │
+  │    immediately   │ │    (rewrite if  │ │    credentials │
+  │    (AWS/GH/      │ │     pushed)     │ │                │
+  │     Stripe)      │ │                 │ │ 7. Notify team │
+  │                  │ │ 4. Scan deps    │ │    /compliance │
+  │ 2. Confirm       │ │    for leaked   │ │    (GDPR/SOC2) │
+  │    exposure      │ │    keys         │ │                │
+  │    scope         │ │                 │ │ 8. Document    │
+  │    (local or     │ │ 5. Check CI/CD  │ │    incident    │
+  │     pushed?)     │ │    logs         │ │    timeline    │
+  │                  │ │                 │ │                │
+  └──────────────────┘ └─────────────────┘ └────────────────┘
+
+  SEVERITY GUIDE:
+  ┌─────────────────────────────────────────────────────────┐
+  │ Local only (not pushed)  → Revoke + rotate (steps 1-2) │
+  │ Pushed to remote         → Full timeline (steps 1-8)   │
+  │ Public repo exposure     → Assume compromised, rotate  │
+  │                            EVERYTHING, check for abuse  │
+  └─────────────────────────────────────────────────────────┘
+```
+
+> Source: [security-hardening.md:347](./security-hardening.md)
+
+---
+
+*Back to [Guide README](./README.md) | [Cheatsheet](./cheatsheet.md) | [Main README](../README.md)*
diff --git a/machine-readable/reference.yaml b/machine-readable/reference.yaml
index ff55d1f..17a1b75 100644
--- a/machine-readable/reference.yaml
+++ b/machine-readable/reference.yaml
@@ -1,9 +1,9 @@
 # claude-code-reference.yaml
-# Quick lookup for Claude Code - ~2K tokens target
+# Quick lookup for Claude Code - comprehensive index
 # Source: guide/ultimate-guide.md
 # Purpose: Condensed index for LLMs to quickly answer user questions about Claude Code
 
-version: "3.20.4"
+version: "3.20.5"
 updated: "2026-01-31"
 
 # ════════════════════════════════════════════════════════════════
@@ -119,6 +119,8 @@ deep_dive:
   sandbox_anti_patterns: "guide/sandbox-isolation.md:372"
   sandbox_comparison_matrix: "guide/sandbox-isolation.md:306"
   sandbox_score: "4/5"
+  # Visual Reference (ASCII diagrams)
+  visual_reference: "guide/visual-reference.md"
   # Architecture internals (guide/architecture.md)
   architecture_visual_overview: "guide/architecture.md:41"
   architecture_visual_source: "https://www.linkedin.com/posts/mohamed-ali-ben-salem-2b777b9a_en-ce-moment-je-vois-passer-des-posts-du-activity-7420592149110362112-eY5a"
@@ -869,7 +871,7 @@ ecosystem:
       - "Cross-links modified → Update all 4 repos"
     history:
       - date: "2026-01-20"
-        event: "Code Landing sync v3.20.4, 66 templates, cross-links"
+        event: "Code Landing sync v3.20.5, 66 templates, cross-links"
         commit: "5b5ce62"
       - date: "2026-01-20"
         event: "Cowork Landing fix (paths, README, UI badges)"