From c7184ea5da96033816a69f81a7013c92822c51cc Mon Sep 17 00:00:00 2001
From: Florian BRUNIAUX <florian@bruniaux.com>
Date: Sun, 11 Jan 2026 14:15:14 +0100
Subject: [PATCH] feat(docs): add comprehensive Plugin System documentation
 (v2.6.0)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add Section 8.5 Plugin System with complete coverage of Claude Code's
plugin marketplace and extensibility features. Resolve keyboard shortcut
documentation inconsistency.

**Added:**
- Section 8.5 Plugin System (~245 lines)
  - Plugin commands: install, enable, disable, uninstall, update
  - Marketplace management (add, list, update, remove)
  - Custom plugin creation guide with manifest structure
  - Plugin vs MCP Server comparison
  - Security considerations and best practices
  - Real-world use cases (team standards, security audit, a11y)
  - Troubleshooting guide
- Esc×2 double-tap shortcut in keyboard shortcuts table
- /plugin command in commands reference
- --plugin-dir flag in CLI flags reference

**Changed:**
- Updated Table of Contents with Plugin System entry
- Enhanced Section 8 navigation with plugin link
- Added Plugins to Power Features in TL;DR
- Version bumped: 2.5 → 2.6 (README + guide)

**Stats:**
- Guide: 8,545 → 8,787 lines (+242 lines, +2.8%)
- Focus: Extensibility and community-driven functionality

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 CHANGELOG.md                          |  62 +++
 IMPROVEMENT_RECOMMENDATIONS.md        | 572 --------------------------
 README.md                             |   5 +-
 english-ultimate-claude-code-guide.md | 248 ++++++++++-
 4 files changed, 310 insertions(+), 577 deletions(-)
 delete mode 100644 IMPROVEMENT_RECOMMENDATIONS.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 67c96a5..ce23c6a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,68 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
+## [2.6.0] - 2026-01-11
+
+### Added
+- **Section 8.5: Plugin System** (~245 lines, comprehensive documentation)
+  - **Plugin System fundamentals** (lines 4836-5073)
+    - What are plugins: packaged agents, skills, commands, domain-specific tooling
+    - Plugin commands table: install, enable, disable, uninstall, update, validate
+    - Marketplace management: add, list, update, remove marketplaces
+    - Using plugins workflow from marketplace to session usage
+    - Plugin session loading with `--plugin-dir` flag for testing
+  - **When to Use Plugins** decision matrix
+    - Team workflows: Share standardized agents/skills via private marketplace
+    - Domain expertise: Pre-built security, accessibility, performance plugins
+    - Repeating patterns: Package custom workflows for reuse
+    - Community solutions: Leverage community expertise
+  - **Creating Custom Plugins** guide
+    - Directory structure with manifest (plugin.json)
+    - Example security-audit plugin manifest
+    - Validation command: `claude plugin validate ./my-plugin`
+  - **Plugin vs. MCP Server** comparison table
+    - Plugin = "How Claude thinks" (workflows, specialized agents)
+    - MCP Server = "What Claude can do" (tools, external systems)
+    - Clear guidance on when to use which
+  - **Security Considerations** section
+    - Before installing: trust source, review manifest, test in isolation
+    - Red flags: network access without reason, obfuscated code, no documentation
+  - **Example Use Cases** with real workflows
+    - Team Code Standards Plugin (private marketplace)
+    - Security Audit Suite (community plugin)
+    - Accessibility Testing (a11y plugin with WCAG compliance)
+  - **Troubleshooting** guide
+    - Plugin not found after install
+    - Plugin conflicts resolution
+    - Plugin not loading in session
+- **Keyboard Shortcut: `Esc×2` double-tap** (line 7487)
+  - Added to Section 10.2 Keyboard Shortcuts table
+  - Clarifies double-tap pattern: Rewind to previous checkpoint (same as `/rewind`)
+  - Resolves inconsistency between TL;DR mention and shortcuts table
+- **Plugin command** in Section 10.1 Commands Table (line 7696)
+  - `/plugin` command: Manage Claude Code plugins (Config category)
+- **Plugin flag** in Section 10.3 CLI Flags Reference (line 7782)
+  - `--plugin-dir`: Load plugins from directory (repeatable flag)
+
+### Changed
+- **Table of Contents updated** (line 147)
+  - Added [8.5 Plugin System](#85-plugin-system) entry
+- **Section 8 Quick Jump navigation enhanced** (line 4530)
+  - Added Plugin System link to quick navigation bar
+- **TL;DR Power Features table** (line 80)
+  - Added "Plugins: Community-created extension packages" row
+- **Version alignment** across documentation
+  - english-ultimate-claude-code-guide.md: Version 2.5 → 2.6
+  - README.md: Version 2.5 → 2.6
+
+### Stats
+- Guide expanded from 8,545 to 8,787 lines (+242 lines, +2.8%)
+- Plugin System section: ~245 lines of comprehensive documentation
+- 1 keyboard shortcut clarified (Esc×2)
+- 2 command/flag additions (/plugin, --plugin-dir)
+- Focus on extensibility and community-driven functionality
+- Zero loss of existing functionality
+
 ## [2.5.0] - 2026-01-11
 
 ### Removed
diff --git a/IMPROVEMENT_RECOMMENDATIONS.md b/IMPROVEMENT_RECOMMENDATIONS.md
deleted file mode 100644
index 632f41b..0000000
--- a/IMPROVEMENT_RECOMMENDATIONS.md
+++ /dev/null
@@ -1,572 +0,0 @@
-# Guide Improvement Recommendations
-
-Based on comprehensive analysis of zebbern/claude-code-guide, here are prioritized recommendations to enhance our Claude Code Ultimate Guide.
-
-## Priority 1: High-Impact Quick Wins ⚡
-
-### 1.1 Add Status Overview Table (5 min)
-
-**What:** Add a visual status table at the top showing section completeness.
-
-**Where:** Right after the main title, before TOC.
-
-**Implementation:**
-```markdown
-<div align="center">
-
-| Section | Status | Coverage |
-|---------|--------|----------|
-| Installation & Setup | ✅ Complete | 100% |
-| Core Concepts | ✅ Complete | 100% |
-| Agents & Skills | ✅ Complete | 100% |
-| MCP Integration | 🔄 Updating | 95% |
-| Advanced Patterns | ✅ Complete | 100% |
-| Troubleshooting | ✅ Complete | 100% |
-
-</div>
-```
-
-**Benefit:** Users immediately see what's covered and maturity level.
-
----
-
-### 1.2 Create One-Page Cheat Sheet (30 min)
-
-**What:** Ultra-condensed reference for daily use.
-
-**File:** `cheatsheet-en.md` (already exists but could be enhanced)
-
-**Format:** Single page with these sections:
-```markdown
-## Quick Reference Card
-
-### Essential Commands
-claude                     # Start REPL
-claude -p "query"          # Print mode
-claude --model sonnet      # Model selection
-claude --think             # Extended reasoning
-
-### Config Management
-claude config get <key>
-claude config set <key> <val>
-claude config add <key> <vals>  # For arrays
-
-### MCP Quick Setup
-claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents
-
-### Debugging
-claude doctor
-claude --debug
-claude --verbose
-
-### Permission Control
---allowedTools "Edit,Read,Bash(git:*)"
---disallowedTools "WebFetch"
-```
-
-**Benefit:** Printable, scannable, perfect for new team members.
-
----
-
-### 1.3 Complete Command Line Flags Table (20 min)
-
-**What:** Comprehensive reference for all CLI flags.
-
-**Where:** Section 6 or new appendix.
-
-**Content:** Based on zebbern's table:
-| Flag | Description | Example |
-|------|-------------|---------|
-| `-p, --print` | Print response and exit | `claude -p "query"` |
-| `--output-format` | Output format (text/json/stream-json) | `--output-format json` |
-| `--input-format` | Input format (text/stream-json) | `--input-format stream-json` |
-| `--replay-user-messages` | Re-emit user messages in stream | `--replay-user-messages` |
-| `--allowedTools` | Whitelist tools | `--allowedTools "Edit,Read"` |
-| `--disallowedTools` | Blacklist tools | `--disallowedTools "WebFetch"` |
-| `--mcp-config` | Load MCP from JSON | `--mcp-config ./mcp.json` |
-| `--strict-mcp-config` | Only use specified MCP | `--strict-mcp-config` |
-| `--append-system-prompt` | Add to system prompt | `--append-system-prompt "..."` |
-| `--permission-mode` | Permission mode | `--permission-mode plan` |
-| `--model` | Model selection | `--model sonnet` |
-| `--add-dir` | Additional directories | `--add-dir ../apps ../lib` |
-| `--continue` | Continue last conversation | `--continue` |
-| `-r, --resume` | Resume session by ID | `--resume abc123` |
-| `--dangerously-skip-permissions` | Skip all permissions | `--dangerously-skip-permissions` |
-
-**Benefit:** Complete reference for power users and automation.
-
----
-
-## Priority 2: Enhanced Troubleshooting 🔧
-
-### 2.1 MCP Troubleshooting Section Enhancement (45 min)
-
-**What:** Add common MCP errors and solutions.
-
-**Where:** Expand section 10.4 "MCP Issues"
-
-**New subsections:**
-
-#### Common MCP Errors
-
-**Error 1: Tool Name Validation Failed**
-```
-API Error 400: "tools.11.custom.name: String should match pattern '^[a-zA-Z0-9_-]{1,64}'"
-```
-**Solution:**
-- Server name: only letters, numbers, underscores, hyphens
-- Max 64 characters
-- No special characters or spaces
-
-**Error 2: MCP Server Not Found**
-```
-MCP server 'my-server' not found
-```
-**Solution:**
-1. Check scope settings (local/user/project)
-2. Run `claude mcp list` to verify
-3. Ensure correct directory for local scope
-4. Restart Claude Code
-
-**Error 3: Windows Path Issues**
-```
-Error: Cannot find module 'C:UsersusernameDocuments'
-```
-**Solution:**
-```bash
-# Wrong
-claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:\Users\username\Documents
-
-# Correct
-claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:/Users/username/Documents
-# or
-claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem "C:\\Users\\username\\Documents"
-```
-
-#### MCP Debugging Techniques
-
-**Enable Debug Mode:**
-```bash
-claude --mcp-debug
-```
-
-**View MCP Status:**
-```bash
-/mcp  # Inside Claude Code
-```
-
-**View Log Files:**
-```bash
-# macOS/Linux
-tail -f ~/Library/Logs/Claude/mcp*.log
-
-# Windows
-type "%APPDATA%\Claude\logs\mcp*.log"
-```
-
-**Manual Server Test:**
-```bash
-# Test if server works standalone
-npx -y @modelcontextprotocol/server-filesystem ~/Documents
-```
-
----
-
-### 2.2 One-Shot Health Check Scripts (15 min)
-
-**What:** Copy-paste diagnostic scripts.
-
-**Where:** Section 10 "Help & Troubleshooting"
-
-**Windows (PowerShell):**
-```powershell
-Write-Host "`n=== Node & npm ==="; node --version; npm --version
-Write-Host "`n=== Where is claude? ==="; where claude
-Write-Host "`n=== Try doctor ==="; try { claude doctor } catch { Write-Host "claude not on PATH" }
-Write-Host "`n=== API key set? ==="; if ($env:ANTHROPIC_API_KEY) { "Yes" } else { "No" }
-Write-Host "`n=== MCP Status ==="; claude mcp list
-```
-
-**macOS/Linux (bash/zsh):**
-```bash
-echo "=== Node & npm ==="; node --version; npm --version
-echo "=== Where is claude? ==="; which claude || echo "claude not on PATH"
-echo "=== Try doctor ==="; claude doctor || true
-echo "=== API key set? ==="; [ -n "$ANTHROPIC_API_KEY" ] && echo Yes || echo No
-echo "=== MCP Status ==="; claude mcp list
-```
-
-**Benefit:** Instant diagnosis for users reporting issues.
-
----
-
-### 2.3 Full Clean Reinstall Procedures (20 min)
-
-**What:** Nuclear option for corrupted installations.
-
-**Where:** Section 10 troubleshooting
-
-**Windows PowerShell Script:**
-```powershell
-# 1. Uninstall
-npm uninstall -g @anthropic-ai/claude-code
-
-# 2. Remove shims
-Remove-Item -LiteralPath "$env:USERPROFILE\AppData\Roaming\npm\claude*" -Force -ErrorAction SilentlyContinue
-Remove-Item -LiteralPath "$env:USERPROFILE\AppData\Roaming\npm\node_modules\@anthropic-ai\claude-code" -Recurse -Force -ErrorAction SilentlyContinue
-
-# 3. Delete cache
-Remove-Item -LiteralPath "$env:USERPROFILE\.claude\downloads\*" -Recurse -Force -ErrorAction SilentlyContinue
-Remove-Item -LiteralPath "$env:USERPROFILE\.claude\local" -Recurse -Force -ErrorAction SilentlyContinue
-
-# 4. Remove config (optional - backs up first)
-Copy-Item "$env:USERPROFILE\.claude.json" "$env:USERPROFILE\.claude.json.backup" -ErrorAction SilentlyContinue
-Remove-Item -LiteralPath "$env:USERPROFILE\.claude.json" -Force -ErrorAction SilentlyContinue
-
-# 5. Reinstall
-npm install -g @anthropic-ai/claude-code
-```
-
-**macOS/Linux Script:**
-```bash
-#!/bin/bash
-# 1. Uninstall
-npm uninstall -g @anthropic-ai/claude-code
-
-# 2. Remove global bin files
-rm -f "$(npm config get prefix)/bin/claude"
-rm -rf "$(npm config get prefix)/lib/node_modules/@anthropic-ai/claude-code"
-
-# 3. Delete cache
-rm -rf ~/.claude/downloads/*
-rm -rf ~/.claude/local
-
-# 4. Backup and remove config (optional)
-cp ~/.claude.json ~/.claude.json.backup 2>/dev/null || true
-rm -f ~/.claude.json
-
-# 5. Reinstall
-npm install -g @anthropic-ai/claude-code
-```
-
-**Benefit:** Last resort fix for mysterious issues.
-
----
-
-## Priority 3: Format Enhancements 📝
-
-### 3.1 Add Visual Badges (10 min)
-
-**What:** Status badges at top of README.
-
-**Implementation:**
-```markdown
-![Claude Code Version](https://img.shields.io/badge/Claude%20Code-1.0+-blue)
-![Status](https://img.shields.io/badge/Status-Active-brightgreen)
-![License](https://img.shields.io/badge/License-MIT-orange)
-![Last Updated](https://img.shields.io/badge/Updated-January%202026-blue)
-```
-
----
-
-### 3.2 Collapsible Tables for Dense Content (30 min)
-
-**What:** Use `<details>` tags or tables for long sections.
-
-**Where:** Troubleshooting, environment variables, MCP server list.
-
-**Example:**
-```markdown
-<details>
-<summary><b>Environment Variables Reference (click to expand)</b></summary>
-
-| Variable | Purpose | Example |
-|----------|---------|---------|
-| `ANTHROPIC_API_KEY` | API authentication | `sk-ant-...` |
-| `ANTHROPIC_MODEL` | Default model | `claude-sonnet-4-20250514` |
-| `BASH_DEFAULT_TIMEOUT_MS` | Bash timeout | `60000` |
-...
-
-</details>
-```
-
-**Benefit:** Reduces visual clutter while keeping info accessible.
-
----
-
-### 3.3 "C-Style Comment" Format for Multi-Variant Commands (15 min)
-
-**What:** Visual organization for OS-specific commands.
-
-**Example:**
-```C
-# Quick Start Installation
-/*──────────────────────────────────────────────────────────────*/
-/* Universal Method       */ npm install -g @anthropic-ai/claude-code
-/*──────────────────────────────────────────────────────────────*/
-/* Windows (CMD)          */ npm install -g @anthropic-ai/claude-code
-/* Windows (PowerShell)   */ irm https://claude.ai/install.ps1 | iex
-/*──────────────────────────────────────────────────────────────*/
-/* macOS                  */ brew install node && npm install -g @anthropic-ai/claude-code
-/*──────────────────────────────────────────────────────────────*/
-/* Linux (Debian/Ubuntu)  */ sudo apt update && sudo apt install -y nodejs npm
-/*                        */ npm install -g @anthropic-ai/claude-code
-```
-
-**Benefit:** Extremely scannable, looks professional.
-
----
-
-## Priority 4: Content Additions 📚
-
-### 4.1 Security Best Practices - Do/Don't Format (30 min)
-
-**What:** Clear visual Do/Don't examples.
-
-**Where:** Section 8 Security
-
-**Format:**
-```markdown
-### Security Pitfalls
-
-**❌ Don't:**
-- Use `--dangerously-skip-permissions` on production systems
-- Hard-code secrets in commands/config files
-- Grant overly broad permissions (`Bash(*)`)
-- Run with elevated privileges unnecessarily
-
-**✅ Do:**
-- Store secrets in environment variables
-- Start from minimal permissions and expand gradually
-- Audit regularly with `claude config list`
-- Isolate risky operations in containers/VMs
-```
-
----
-
-### 4.2 Performance Pitfalls Section (20 min)
-
-**What:** Common performance mistakes.
-
-**Format:**
-```markdown
-### Performance Pitfalls
-
-**❌ Don't:**
-- Load entire monorepo when you only need one package
-- Max out thinking/turn budgets for simple tasks
-- Ignore session cleanup (old sessions accumulate)
-- Use `--ultrathink` for trivial edits
-
-**✅ Do:**
-- Use `--add-dir` for focused context
-- Right-size with `--max-turns` and `MAX_THINKING_TOKENS`
-- Set `cleanupPeriodDays` to prune old sessions
-- Match thinking level to task complexity
-```
-
----
-
-### 4.3 Workflow Pitfalls Section (20 min)
-
-**What:** Common workflow mistakes.
-
-**Format:**
-```markdown
-### Workflow Pitfalls
-
-**❌ Don't:**
-- Skip project context (`CLAUDE.md`)
-- Use vague prompts ("fix this", "check my code")
-- Ignore errors in logs
-- Automate workflows without testing first
-
-**✅ Do:**
-- Maintain and update `CLAUDE.md` regularly
-- Be specific and goal-oriented in prompts
-- Monitor via logs/OpenTelemetry as appropriate
-- Test automation in safe environments first
-- Review agent outputs before committing
-```
-
----
-
-### 4.4 DeepSeek Integration (15 min)
-
-**What:** Alternative LLM provider integration.
-
-**Where:** Section 11 "Third-Party Integrations"
-
-**Content:**
-```markdown
-## 11.1 DeepSeek Integration
-
-Use DeepSeek's Claude-compatible API as a cost-effective alternative.
-
-### Setup
-
-1. **Prerequisites:**
-   - Claude Code installed: `npm install -g @anthropic-ai/claude-code`
-   - DeepSeek API key from [platform.deepseek.com](https://platform.deepseek.com)
-
-2. **Configure Environment:**
-   ```bash
-   export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
-   export ANTHROPIC_AUTH_TOKEN=${YOUR_DEEPSEEK_API_KEY}
-   export ANTHROPIC_MODEL=deepseek-chat
-   export ANTHROPIC_SMALL_FAST_MODEL=deepseek-chat
-   ```
-
-3. **Launch Claude:**
-   ```bash
-   claude
-   ```
-
-### Cost Comparison
-
-| Provider | Model | Cost per 1M tokens |
-|----------|-------|-------------------|
-| Anthropic | Sonnet 4 | ~$3.00 |
-| DeepSeek | deepseek-chat | ~$0.14 |
-
-**Savings: ~95% reduction**
-
-### Limitations
-
-- DeepSeek models have different capabilities than Claude
-- Some advanced features may not work identically
-- Performance/quality trade-offs exist
-
-### Resources
-
-- [DeepSeek API Documentation](https://api-docs.deepseek.com/guides/anthropic_api)
-- [DeepSeek Platform](https://platform.deepseek.com)
-```
-
----
-
-## Priority 5: Documentation Structure 🏗️
-
-### 5.1 Add Quick Navigation Links (10 min)
-
-**What:** Jump links at top of major sections.
-
-**Example:**
-```markdown
-## Section 6: Commands & Usage
-
-_Quick jump:_ [Slash Commands](#slash-commands) · [CLI Flags](#cli-flags) · [Cheat Sheet](#cheat-sheet) · [Environment Variables](#environment-variables)
-
----
-
-### 6.1 Slash Commands
-...
-```
-
----
-
-### 5.2 Appendix: Useful Paths (10 min)
-
-**What:** Reference for file locations.
-
-**Content:**
-```markdown
-## Appendix A: File Locations Reference
-
-### Windows
-- **npm global bin:** `C:\Users\<you>\AppData\Roaming\npm`
-- **Node.js:** `C:\Program Files\nodejs`
-- **Claude data:** `C:\Users\<you>\.claude\`
-- **Claude config:** `C:\Users\<you>\.claude.json`
-- **Logs:** `%APPDATA%\Claude\logs\`
-
-### macOS/Linux
-- **npm global bin:** `$(npm config get prefix)/bin` (often `/usr/local/bin`)
-- **Claude data:** `~/.claude/`
-- **Claude config:** `~/.claude.json`
-- **Logs (macOS):** `~/Library/Logs/Claude/`
-- **Logs (Linux):** `~/.local/share/claude/logs/`
-```
-
----
-
-## Implementation Roadmap
-
-### Phase 1: Quick Wins (2-3 hours)
-1. ✅ Add thinking keywords inline syntax
-2. ✅ Create GitHub Actions examples directory
-3. Add status overview table
-4. Create/enhance cheat sheet
-5. Add CLI flags table
-6. Add visual badges
-
-### Phase 2: Troubleshooting (3-4 hours)
-1. MCP troubleshooting enhancement
-2. One-shot health check scripts
-3. Full clean reinstall procedures
-4. Appendix: useful paths
-
-### Phase 3: Content Enrichment (4-5 hours)
-1. Security pitfalls Do/Don't
-2. Performance pitfalls
-3. Workflow pitfalls
-4. DeepSeek integration
-5. Collapsible tables for dense content
-
-### Phase 4: Format Polish (2-3 hours)
-1. C-style comment format for commands
-2. Quick navigation links
-3. Consistent emoji hierarchy
-4. Table of contents update
-
----
-
-## Metrics for Success
-
-### User Experience
-- **Time to first success:** < 15 minutes (installation → first task)
-- **Time to find answer:** < 2 minutes (via cheat sheet or quick links)
-- **Support ticket reduction:** Target 30% reduction via better troubleshooting
-
-### Content Quality
-- **Coverage:** 100% of official features documented
-- **Accuracy:** < 1% error rate in commands/examples
-- **Freshness:** Updated within 7 days of new Claude Code releases
-
-### Community Engagement
-- **GitHub Stars:** Track growth trend
-- **Issues/PRs:** Measure community contributions
-- **Fork activity:** Indicates usage/adaptation
-
----
-
-## What NOT to Change
-
-**Keep these strengths from our guide:**
-
-1. **Learning Path Structure** - Junior → Senior → Power User progression
-2. **Trinity Pattern** - Unique advanced workflow
-3. **OpusPlan Mode** - Cost optimization strategy
-4. **Context Management Zones** - Clear guidance on usage levels
-5. **Maturity Model** - 5-level progression framework
-6. **Agent-Based Task Delegation** - Advanced orchestration
-7. **Skill Inheritance Model** - Reusable expertise
-8. **Git Archaeology Pattern** - Unique debugging approach
-9. **Narrative Style** - Pedagogical, not just reference
-10. **Real-world Examples** - Production scenarios, not toy examples
-
----
-
-## Conclusion
-
-These recommendations balance:
-- **Immediate impact** (quick wins) with **long-term value** (structural improvements)
-- **Reference utility** (cheat sheets, tables) with **learning journey** (narrative)
-- **Completeness** (troubleshooting) with **scannability** (collapsible sections)
-
-**Core Philosophy:**
-> zebbern's guide = comprehensive reference
-> our guide = mastery journey
-> **enhanced guide = both**
-
-By selectively adopting zebbern's strengths while preserving our unique pedagogical approach, we create the definitive Claude Code resource.
diff --git a/README.md b/README.md
index 38eedac..e00edb3 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,7 @@
 
 [![License: CC BY-SA 4.0](https://img.shields.io/badge/License-CC%20BY--SA%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by-sa/4.0/)
 [![GitHub stars](https://img.shields.io/github/stars/FlorianBruniaux/claude-code-ultimate-guide?style=social)](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/stargazers)
+[![zread](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)](https://zread.ai/FlorianBruniaux/claude-code-ultimate-guide)
 
 **Author**: [Florian BRUNIAUX](https://github.com/FlorianBruniaux) | Founding Engineer [@Méthode Aristote](https://methode-aristote.fr)
 
@@ -288,7 +289,7 @@ Want to know if your Claude Code setup follows best practices?
 - [DeepTo Claude Code Guide](https://cc.deeptoai.com/docs/en/best-practices/claude-code-comprehensive-guide) — Comprehensive best practices covering XML-structured prompts, session continuation, image processing, Unix piping workflows, and cost tracking (ccusage tool)
 
 ### Community Curated Lists
-- [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) — Commands, workflows, IDE integrations
+- [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) — Extensive reference library (19.9k stars) covering commands, workflows, hooks, IDE integrations, and monitoring tools. **Note**: This is a curated collection for discovering solutions, not an architectural guide—it lists tools without guidance on how to combine them intelligently or which to choose based on specific needs
 - [awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills) — Custom skills collection
 - [awesome-claude-code-subagents](https://github.com/VoltAgent/awesome-claude-code-subagents) — Full-stack & DevOps subagents
 - [awesome-claude](https://github.com/alvinunreal/awesome-claude) — General Claude resources (SDKs, tools)
@@ -320,4 +321,4 @@ You are free to share and adapt this material, provided you give appropriate cre
 
 ---
 
-*Last updated: January 2026 | Version 2.5*
\ No newline at end of file
+*Last updated: January 2026 | Version 2.6*
\ No newline at end of file
diff --git a/english-ultimate-claude-code-guide.md b/english-ultimate-claude-code-guide.md
index 5fd51f7..85d656a 100644
--- a/english-ultimate-claude-code-guide.md
+++ b/english-ultimate-claude-code-guide.md
@@ -10,7 +10,7 @@
 
 **Last updated**: January 2026
 
-**Version**: 2.5
+**Version**: 2.6
 
 ---
 
@@ -77,6 +77,7 @@ Describe → Claude Analyzes → Review Diff → Accept/Reject → Verify
 | **Skills** | Reusable knowledge modules |
 | **Hooks** | Automation scripts triggered by events |
 | **MCP Servers** | External tools (Serena, Context7, Playwright...) |
+| **Plugins** | Community-created extension packages |
 
 ### The Golden Rules
 1. **Always review diffs** before accepting changes
@@ -144,6 +145,7 @@ Context full → /compact or /clear
   - [8.2 Available Servers](#82-available-servers)
   - [8.3 Configuration](#83-configuration)
   - [8.4 Server Selection Guide](#84-server-selection-guide)
+  - [8.5 Plugin System](#85-plugin-system)
 - [9. Advanced Patterns](#9-advanced-patterns)
   - [9.1 The Trinity](#91-the-trinity)
   - [9.2 Composition Patterns](#92-composition-patterns)
@@ -4526,7 +4528,7 @@ exit 0
 
 # 8. MCP Servers
 
-_Quick jump:_ [What is MCP](#81-what-is-mcp) · [Available Servers](#82-available-servers) · [Configuration](#83-configuration) · [Server Selection Guide](#84-server-selection-guide)
+_Quick jump:_ [What is MCP](#81-what-is-mcp) · [Available Servers](#82-available-servers) · [Configuration](#83-configuration) · [Server Selection Guide](#84-server-selection-guide) · [Plugin System](#85-plugin-system)
 
 ---
 
@@ -4833,6 +4835,243 @@ Servers can work together:
 4. Playwright → Test the implementation
 ```
 
+## 8.5 Plugin System
+
+Claude Code includes a comprehensive **plugin system** that allows you to extend functionality through community-created or custom plugins and marketplaces.
+
+### What Are Plugins?
+
+Plugins are packaged extensions that can add:
+- Custom agents with specialized behavior
+- New skills for reusable workflows
+- Pre-configured commands
+- Domain-specific tooling
+
+Think of plugins as **distributable packages** that bundle agents, skills, and configuration into installable modules.
+
+### Plugin Commands
+
+| Command | Purpose | Example |
+|---------|---------|---------|
+| `claude plugin` | List installed plugins | Shows all plugins with status |
+| `claude plugin install <name>` | Install plugin from marketplace | `claude plugin install security-audit` |
+| `claude plugin install <name>@<marketplace>` | Install from specific marketplace | `claude plugin install linter@company` |
+| `claude plugin enable <name>` | Enable installed plugin | `claude plugin enable security-audit` |
+| `claude plugin disable <name>` | Disable plugin without removing | `claude plugin disable linter` |
+| `claude plugin uninstall <name>` | Remove plugin completely | `claude plugin uninstall security-audit` |
+| `claude plugin update [name]` | Update plugin to latest version | `claude plugin update security-audit` |
+| `claude plugin validate <path>` | Validate plugin manifest | `claude plugin validate ./my-plugin` |
+
+### Marketplace Management
+
+Marketplaces are repositories of plugins you can install from.
+
+**Marketplace commands:**
+
+```bash
+# Add a marketplace
+claude plugin marketplace add <url-or-path>
+
+# Examples:
+claude plugin marketplace add https://github.com/claudecode/plugins
+claude plugin marketplace add /Users/yourname/company-plugins
+claude plugin marketplace add gh:myorg/claude-plugins  # GitHub shorthand
+
+# List configured marketplaces
+claude plugin marketplace list
+
+# Update marketplace catalog
+claude plugin marketplace update [name]
+
+# Remove a marketplace
+claude plugin marketplace remove <name>
+```
+
+### Using Plugins
+
+**Typical workflow:**
+
+```bash
+# 1. Add a marketplace (one-time setup)
+claude plugin marketplace add https://github.com/awesome-claude/plugins
+
+# 2. Install a plugin
+claude plugin install code-reviewer
+
+# 3. Enable it for your project
+claude plugin enable code-reviewer
+
+# 4. Use it in Claude Code session
+claude
+You: /review-pr
+# Plugin command is now available
+```
+
+### Plugin Session Loading
+
+Load plugins temporarily for a single session:
+
+```bash
+# Load plugin directory for this session only
+claude --plugin-dir ~/.claude/custom-plugins
+
+# Load multiple plugin directories
+claude --plugin-dir ~/work/plugins --plugin-dir ~/personal/plugins
+```
+
+This is useful for testing plugins before permanent installation.
+
+### When to Use Plugins
+
+| Scenario | Use Plugins |
+|----------|-------------|
+| **Team workflows** | ✅ Share standardized agents/skills across team via private marketplace |
+| **Domain expertise** | ✅ Install pre-built plugins for security, accessibility, performance analysis |
+| **Repeating patterns** | ✅ Package your custom workflows for reuse across projects |
+| **Community solutions** | ✅ Leverage community expertise instead of rebuilding from scratch |
+| **Quick experiments** | ❌ Use custom agents/skills directly in `.claude/` folder |
+| **Project-specific** | ❌ Keep as project CLAUDE.md instructions instead |
+
+### Creating Custom Plugins
+
+Plugins are structured directories with a manifest:
+
+```
+my-plugin/
+├── plugin.json           # Plugin manifest
+├── agents/
+│   └── my-agent.md       # Custom agents
+├── skills/
+│   └── my-skill.md       # Custom skills
+├── commands/
+│   └── my-cmd.sh         # Custom commands
+└── README.md             # Documentation
+```
+
+**Example `plugin.json`:**
+
+```json
+{
+  "name": "security-audit",
+  "version": "1.0.0",
+  "description": "Security audit tools for Claude Code",
+  "author": "Your Name",
+  "agents": ["agents/security-scanner.md"],
+  "skills": ["skills/owasp-check.md"],
+  "commands": ["commands/scan.sh"]
+}
+```
+
+**Validate before distribution:**
+
+```bash
+claude plugin validate ./my-plugin
+```
+
+### Plugin vs. MCP Server
+
+Understanding when to use which:
+
+| Feature | Plugin | MCP Server |
+|---------|--------|------------|
+| **Purpose** | Bundle Claude-specific workflows (agents, skills) | Add external tool capabilities (databases, APIs) |
+| **Complexity** | Simpler - just files + manifest | More complex - requires server implementation |
+| **Scope** | Claude Code instructions and patterns | External system integrations |
+| **Installation** | `claude plugin install` | Add to `settings.json` MCP config |
+| **Use case** | Security auditor agent, code review workflows | PostgreSQL access, Playwright browser automation |
+
+**Rule of thumb:**
+- **Plugin** = "How Claude thinks" (new workflows, specialized agents)
+- **MCP Server** = "What Claude can do" (new tools, external systems)
+
+### Security Considerations
+
+**Before installing plugins:**
+
+1. **Trust the source** - Only install from verified marketplaces
+2. **Review manifest** - Check what the plugin includes with `validate`
+3. **Test in isolation** - Use `--plugin-dir` for testing before permanent install
+4. **Company policies** - Check if your organization has approved plugin sources
+
+**Red flags:**
+
+- Plugins requesting network access without clear reason
+- Unclear or obfuscated code in agents/skills
+- Plugins without documentation or proper manifest
+
+### Example Use Cases
+
+**1. Team Code Standards Plugin**
+
+```bash
+# Company creates private marketplace
+git clone git@github.com:yourcompany/claude-plugins.git ~/company-plugins
+
+# Add marketplace
+claude plugin marketplace add ~/company-plugins
+
+# Install company standards
+claude plugin install code-standards@company
+
+# Now all team members use same linting, review patterns
+```
+
+**2. Security Audit Suite**
+
+```bash
+# Install community security plugin
+claude plugin install owasp-scanner
+
+# Use in session
+claude
+You: /security-scan
+# Runs OWASP Top 10 checks, dependency audit, secret scanning
+```
+
+**3. Accessibility Testing**
+
+```bash
+# Install a11y plugin
+claude plugin install wcag-checker
+
+# Enable for project
+claude plugin enable wcag-checker
+
+# Adds accessibility-focused agents
+You: Review this component for WCAG 2.1 compliance
+```
+
+### Troubleshooting
+
+**Plugin not found after install:**
+
+```bash
+# Refresh marketplace catalogs
+claude plugin marketplace update
+
+# Verify plugin is installed
+claude plugin
+
+# Check if disabled
+claude plugin enable <name>
+```
+
+**Plugin conflicts:**
+
+```bash
+# Disable conflicting plugin
+claude plugin disable <conflicting-plugin>
+
+# Or uninstall completely
+claude plugin uninstall <conflicting-plugin>
+```
+
+**Plugin not loading in session:**
+
+- Plugins are loaded at session start
+- Restart Claude Code after enabling/disabling
+- Check `~/.claude/plugins/` for installation
+
 ---
 
 # 9. Advanced Patterns
@@ -7454,6 +7693,7 @@ _Quick jump:_ [Commands Table](#101-commands-table) · [Keyboard Shortcuts](#102
 | `/stats` | View usage statistics with activity graphs | Info |
 | `/chrome` | Toggle native browser integration | Mode |
 | `/mcp` | Manage Model Context Protocol servers | Config |
+| `/plugin` | Manage Claude Code plugins | Config |
 | `/plan` | Enter Plan Mode | Mode |
 | `/execute` | Exit Plan Mode | Mode |
 | `/rewind` | Undo recent changes | Edit |
@@ -7484,6 +7724,7 @@ _Quick jump:_ [Commands Table](#101-commands-table) · [Keyboard Shortcuts](#102
 | `Ctrl+L` | Clear screen (keeps context) |
 | `Ctrl+B` | Run command in background |
 | `Esc` | Dismiss current suggestion |
+| `Esc×2` (double-tap) | Rewind to previous checkpoint (same as `/rewind`) |
 
 ### Input & Navigation
 
@@ -7538,6 +7779,7 @@ Complete reference for all Claude Code command-line flags.
 | `--disallowedTools` | Blacklist specific tools | `claude --disallowedTools "WebFetch"` |
 | `--mcp-config` | Load MCP servers from JSON file | `claude --mcp-config ./mcp.json` |
 | `--strict-mcp-config` | Only use MCP servers from config | `claude --strict-mcp-config` |
+| `--plugin-dir` | Load plugins from directory (repeatable) | `claude --plugin-dir ~/.claude/plugins` |
 | `--append-system-prompt` | Add to system prompt | `claude --append-system-prompt "Use TypeScript"` |
 | `--permission-mode` | Permission mode (default/auto/plan) | `claude --permission-mode plan` |
 | `--model` | Model selection | `claude --model sonnet` |
@@ -8542,4 +8784,4 @@ Thumbs.db
 
 **Contributions**: Issues and PRs welcome.
 
-**Last updated**: January 2026 | **Version**: 2.5
+**Last updated**: January 2026 | **Version**: 2.6