claude-code-ultimate-guide-mcp 1.0.3 → 1.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/content/llms.txt +96 -150
  2. package/content/reference.yaml +161 -161
  3. package/dist/index.js +28 -5
  4. package/package.json +1 -1
package/content/llms.txt CHANGED
@@ -1,166 +1,112 @@
1
- # The Ultimate Claude Code Guide
2
-
3
- > A comprehensive, self-contained guide to mastering Claude Code - Anthropic's official CLI for AI-assisted development.
4
-
5
- ## What This Repository Contains
6
-
7
- This repository provides everything needed to go from Claude Code beginner to power user:
8
-
9
- 1. **Complete Guide** (`guide/ultimate-guide.md`) - 9,600+ lines covering all aspects of Claude Code
10
- 2. **Cheatsheet** (`guide/cheatsheet.md`) - 1-page printable daily reference
11
- 3. **Architecture Internals** (`guide/architecture.md`) - How Claude Code works under the hood (master loop, tools, context)
12
- 4. **Audit Prompt** (`tools/audit-prompt.md`) - Self-contained prompt to analyze your Claude Code setup against best practices
1
+ # Claude Code Ultimate Guide
2
+
3
+ > Comprehensive community guide for Claude Code, Anthropic's CLI tool for AI-assisted development.
4
+
5
+ ## Quick Facts
6
+
7
+ - Title: Claude Code Ultimate Guide
8
+ - Author: Florian Bruniaux (Founding Engineer @ Méthode Aristote)
9
+ - Version: 3.32.2
10
+ - Last Updated: March 9, 2026
11
+ - License: CC BY-SA 4.0 (free, open source)
12
+ - Lines of Documentation: 22,760+
13
+ - Production Templates: 238
14
+ - Quiz Questions: 274
15
+
16
+ ## What This Guide Covers
17
+
18
+ 1. Quick Start - Install and first AI-assisted task
19
+ 2. Core Concepts - Context management, Plan Mode, permissions
20
+ 3. Memory & Settings - CLAUDE.md configuration files
21
+ 4. Agents - Custom AI personas for specialized workflows
22
+ 5. Skills - Reusable knowledge modules (Skills 2.0: Capability Uplift + Encoded Preference, Evals, lifecycle management)
23
+ 6. Commands - Custom slash commands (/pr, /commit, /diagnose)
24
+ 7. Hooks - Security automation and formatting (production hooks for bash + PowerShell)
25
+ 8. MCP Servers - External tool integration (databases, browsers, APIs, semantic search)
26
+ 9. Advanced Patterns - Trinity workflow, multi-agent teams, CI/CD, Tasks API
27
+ 10. Reference - Commands, shortcuts, troubleshooting
28
+
29
+ ## Key Resources
30
+
31
+ ### For Quick Start
32
+ - Cheatsheet (2 min): https://cc.bruniaux.com/cheatsheet.html
33
+ - 5 Golden Rules: Always review diffs, /compact at 70%, be specific (WHAT+WHERE+HOW+VERIFY), Plan Mode first, create CLAUDE.md
34
+
35
+ ### For Learning
36
+ - Full Guide (~10h): https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md
37
+ - Interactive Quiz (274 questions): https://cc.bruniaux.com/quiz.html
38
+ - Whitepapers (FR + EN, 9 titles): https://www.florian.bruniaux.com/guides
39
+ - Landing site: https://cc.bruniaux.com
40
+
41
+ ### For Templates
42
+ - 238 Production Templates: https://github.com/FlorianBruniaux/claude-code-ultimate-guide/tree/main/examples
43
+ - Agents: backend-architect, security-guardian, code-reviewer, debugger, devops-sre, adr-writer
44
+ - Commands: /pr, /commit, /release-notes, /diagnose, /generate-tests, /optimize, /git-worktree
45
+ - Hooks: dangerous-actions-blocker, prompt-injection-detector, secrets-scanner (bash + PowerShell)
46
+ - Skills: pdf-generator, tdd-workflow, guide-recap, landing-page-generator, skill-creator
47
+ - Scripts: session-search, audit-scan, fresh-context-loop, sync-claude-config
48
+
49
+ ## CLAUDE.md Starter Template
50
+
51
+ ```markdown
52
+ # Project: [NAME]
53
+
54
+ ## Tech Stack
55
+ - Language: [e.g., TypeScript]
56
+ - Framework: [e.g., Next.js 14]
57
+ - Testing: [e.g., Vitest]
58
+
59
+ ## Commands
60
+ - Build: `npm run build`
61
+ - Test: `npm test`
62
+ - Lint: `npm run lint`
63
+
64
+ ## Rules
65
+ - Run tests before marking tasks complete
66
+ - Follow existing code patterns
67
+ - Keep commits atomic and conventional
68
+ ```
13
69
 
14
- ## Target Audience
70
+ ## Privacy Notice
15
71
 
16
- - **Beginners**: Installation, first workflow, essential commands (15 min to productivity)
17
- - **Intermediate**: Memory files, agents, skills, hooks configuration
18
- - **Power Users**: MCP servers, Trinity pattern, CI/CD integration, autonomous workflows
72
+ Claude Code sends prompts and file contents to Anthropic servers.
73
+ - Default: 5 years retention (training enabled)
74
+ - Opt-out: 30 days retention
75
+ - Enterprise: 0 retention
19
76
 
20
- ## Key Topics Covered
77
+ Disable training: https://claude.ai/settings/data-privacy-controls
21
78
 
22
- ### Core Concepts
23
- - Context Management (the most critical concept - context windows, compaction, zones)
24
- - Plan Mode (safe read-only exploration before making changes)
25
- - Memory Files (CLAUDE.md for persistent context across sessions)
26
- - Rewind (undo mechanism for file changes)
79
+ ## Security
27
80
 
28
- ### Customization
29
- - **Agents**: Custom AI personas with specific tools and instructions
30
- - **Skills**: Reusable knowledge modules for complex domains
31
- - **Commands**: Custom slash commands for frequent workflows
32
- - **Hooks**: Event-driven automation (PreToolUse, PostToolUse, UserPromptSubmit)
81
+ This guide tracks the MCP/AI agent threat landscape:
82
+ - CVE database: 24 tracked vulnerabilities
83
+ - Supply chain threat analysis
84
+ - Production security hardening checklist
85
+ - Threat database: examples/commands/resources/threat-db.yaml
33
86
 
34
- ### Advanced Features
35
- - **MCP Servers**: Model Context Protocol for extended capabilities
36
- - Serena (codebase indexation + session memory)
37
- - Context7 (library documentation lookup)
38
- - Sequential (structured multi-step reasoning)
39
- - Playwright (browser automation)
40
- - **Trinity Pattern**: Combining Plan Mode + Extended Thinking + MCP for complex tasks
41
- - **CI/CD Integration**: Headless mode, GitHub Actions, Verify Gate pattern
87
+ ## Machine-Readable Reference
42
88
 
43
- ### Best Practices
44
- - Single Source of Truth pattern for conventions
45
- - Shell Scripts vs AI Agents decision framework
46
- - Tight feedback loops for rapid iteration
47
- - Continuous improvement mindset
89
+ For AI/LLM consumption (optimized ~2K tokens):
90
+ https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-guide/main/machine-readable/reference.yaml
48
91
 
49
- ## File Structure
92
+ Full content (~30KB):
93
+ https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-guide/main/llms-full.txt
50
94
 
51
- ```
52
- claude-code-ultimate-guide/
53
- ├── README.md # Overview and quick start
54
- ├── CONTRIBUTING.md # Contribution guidelines
55
- ├── CHANGELOG.md # Version history
56
- ├── LICENSE # CC BY-SA 4.0
57
- ├── guide/ # Core documentation
58
- │ ├── ultimate-guide.md # Complete guide (main content)
59
- │ ├── cheatsheet.md # 1-page reference
60
- │ ├── architecture.md # How Claude Code works internally
61
- │ └── adoption-approaches.md # Implementation strategy
62
- ├── tools/ # Interactive utilities
63
- │ ├── audit-prompt.md # Setup audit tool
64
- │ ├── onboarding-prompt.md # Personalized onboarding
65
- │ └── mobile-access.md # Mobile access setup
66
- ├── machine-readable/ # LLM/AI consumption
67
- │ ├── reference.yaml # Machine-optimized index
68
- │ └── llms.txt # This file (for AI indexation)
69
- ├── exports/ # Generated outputs
70
- │ ├── notebooklm.pdf # Visual overview
71
- │ └── kimi.pdf # Full text export
72
- ├── examples/ # Ready-to-use templates
73
- │ ├── agents/ # Custom AI personas
74
- │ ├── skills/ # Knowledge modules
75
- │ ├── commands/ # Slash commands
76
- │ ├── hooks/ # Event automation (bash + PowerShell)
77
- │ ├── config/ # Configuration files
78
- │ └── memory/ # CLAUDE.md templates
79
- └── quiz/ # Interactive knowledge quiz
80
- ```
95
+ ## How to Cite
81
96
 
82
- ## Guide Structure (10 Sections + Architecture)
83
-
84
- **Architecture Deep Dive** (`guide/architecture.md`):
85
- - Master Loop: `while(tool_call)` - no DAGs, no classifiers, no RAG
86
- - 8 Core Tools: Bash, Read, Edit, Write, Grep, Glob, Task, TodoWrite
87
- - Context: ~200K tokens, auto-compact at 75-92%
88
- - Sub-agents: isolated context, max depth=1
89
- - Philosophy: "less scaffolding, more model"
90
-
91
- **Main Guide Sections** (`guide/ultimate-guide.md`):
92
- 1. **Quick Start** - Installation, first workflow, essential commands
93
- 2. **Core Concepts** - Context management, Plan Mode, Rewind, Mental Model
94
- 3. **Memory & Settings** - CLAUDE.md files, .claude/ folder, precedence rules
95
- 4. **Agents** - Custom AI personas, Tool SEO, orchestration patterns
96
- 5. **Skills** - Reusable knowledge modules
97
- 6. **Commands** - Custom slash commands, variable interpolation
98
- 7. **Hooks** - Event-driven automation (security, formatting, logging)
99
- 8. **MCP Servers** - Serena, Context7, Sequential, Playwright, Postgres
100
- 9. **Advanced Patterns** - Trinity, CI/CD, feedback loops, vibe coding
101
- 10. **Reference** - Commands, shortcuts, troubleshooting, checklists
102
-
103
- ## Key Commands Reference
104
-
105
- | Command | Purpose |
106
- |---------|---------|
107
- | `/help` | Show all available commands |
108
- | `/status` | Check context usage and session state |
109
- | `/compact` | Compress context (use when >70%) |
110
- | `/clear` | Fresh start (reset conversation) |
111
- | `/plan` | Enter safe read-only planning mode |
112
- | `/rewind` | Undo recent changes |
113
-
114
- ## Context Management Rules
115
-
116
- - **Green Zone (0-50%)**: Work freely
117
- - **Yellow Zone (50-70%)**: Be selective with context loading
118
- - **Red Zone (70-90%)**: Use `/compact` immediately
119
- - **Critical (90%+)**: Use `/clear` to reset
120
-
121
- ## Platform Support
122
-
123
- - **macOS/Linux**: Full support with bash/zsh examples
124
- - **Windows**: PowerShell and batch file alternatives provided (note: Windows commands are AI-generated and not tested by the author)
125
-
126
- ## Related Resources
127
-
128
- - Official: https://docs.anthropic.com/en/docs/claude-code
129
- - Official llms.txt (index): https://code.claude.com/docs/llms.txt
130
- - Official llms-full.txt (complete): https://code.claude.com/docs/llms-full.txt
131
- - DeepWiki: https://deepwiki.com/FlorianBruniaux/claude-code-ultimate-guide
132
- - Inspiration: https://claudelog.com/
133
- - Whitepapers (FR + EN): https://www.florian.bruniaux.com/guides — 9 focused whitepapers on Claude Code (foundations, prompting, customization, security, architecture, team, privacy, reference, agent teams)
97
+ "Claude Code Ultimate Guide by Florian Bruniaux"
98
+ URL: https://github.com/FlorianBruniaux/claude-code-ultimate-guide
99
+ License: CC BY-SA 4.0
134
100
 
135
- ## Author
101
+ ## Contact
136
102
 
137
- Florian BRUNIAUX - Founding Engineer at Méthode Aristote
138
103
  - GitHub: https://github.com/FlorianBruniaux
139
104
  - LinkedIn: https://www.linkedin.com/in/florian-bruniaux-43408b83/
105
+ - Project Issues: https://github.com/FlorianBruniaux/claude-code-ultimate-guide/issues
140
106
 
141
- ## License
107
+ ## Related
142
108
 
143
- CC BY-SA 4.0 - Free to share and adapt with attribution.
144
-
145
- ## How to Use This Guide
146
-
147
- 1. **New to Claude Code?** Start with README.md Quick Start section
148
- 2. **Choose your path** See Learning Paths in README for audience-specific guides
149
- 3. **Want comprehensive learning?** Read guide/ultimate-guide.md
150
- 4. **Need daily reference?** Print guide/cheatsheet.md
151
- 5. **Want to audit your setup?** Use tools/audit-prompt.md
152
- 6. **Need templates?** Browse examples/ folder for ready-to-use configs
153
-
154
- ## Machine-Optimized Reference
155
-
156
- For fast LLM parsing, see `machine-readable/reference.yaml` (~2K tokens) - structured YAML with:
157
- - Decision tree for task routing
158
- - Prompting formula (WHAT/WHERE/HOW/VERIFY)
159
- - Commands, shortcuts, CLI flags
160
- - Context management zones and symptoms
161
- - MCP servers, extended thinking, cost optimization
162
- - Anti-patterns and troubleshooting
163
-
164
- ## Keywords
165
-
166
- Claude Code, Anthropic, CLI, AI-assisted development, coding assistant, context management, MCP servers, agents, skills, hooks, commands, Plan Mode, CLAUDE.md, memory files, CI/CD integration, autonomous workflows, developer productivity, AI coding tools
109
+ - Anthropic Official Docs: https://docs.anthropic.com/en/docs/claude-code
110
+ - awesome-claude-code: https://github.com/hesreallyhim/awesome-claude-code
111
+ - Dev With AI (FR community): https://www.devw.ai/
112
+ - DeepWiki: https://deepwiki.com/FlorianBruniaux/claude-code-ultimate-guide
package/content/reference.yaml CHANGED
@@ -9,7 +9,7 @@ updated: "2026-02-26"
9
9
  # ════════════════════════════════════════════════════════════════
10
10
  # DEEP DIVE - Line numbers in guide/ultimate-guide.md
11
11
  # Usage: Read file at line N for detailed documentation on topic
12
- # For architecture internals, see guide/architecture.md
12
+ # For architecture internals, see guide/core/architecture.md
13
13
  # ════════════════════════════════════════════════════════════════
14
14
  deep_dive:
15
15
  # Visual Diagrams Series (40 Mermaid diagrams)
@@ -22,11 +22,11 @@ deep_dive:
22
22
  exploration_workflow: "guide/workflows/exploration-workflow.md"
23
23
  script_generation: "guide/workflows/iterative-refinement.md:200"
24
24
  anti_anchoring_prompts: "examples/semantic-anchors/anchor-catalog.md:248"
25
- session_limits: "guide/architecture.md:442"
25
+ session_limits: "guide/core/architecture.md:442"
26
26
  claudemd_sizing: 3054
27
- scope_success_rates: "guide/adoption-approaches.md:26"
27
+ scope_success_rates: "guide/roles/adoption-approaches.md:26"
28
28
  # Claude Code Releases
29
- claude_code_releases: "guide/claude-code-releases.md"
29
+ claude_code_releases: "guide/core/claude-code-releases.md"
30
30
  claude_code_releases_yaml: "machine-readable/claude-code-releases.yaml"
31
31
  # Code Review Automation (Pat Cullen, Jan 2026)
32
32
  review_pr_advanced: "examples/commands/review-pr.md:81"
@@ -58,29 +58,29 @@ deep_dive:
58
58
  team_ai_instructions_token_savings: "59% context token reduction (measured, 5-dev team)"
59
59
  team_ai_instructions_threshold: "Team 5+ devs with multiple AI tools"
60
60
  # Known Issues & Critical Bugs (verified community reports)
61
- known_issues: "guide/known-issues.md"
62
- known_issues_github_bug: "guide/known-issues.md:7" # GitHub auto-creation bug
63
- known_issues_token_consumption: "guide/known-issues.md:105" # Excessive token usage
64
- known_issues_model_quality_aug2025: "guide/known-issues.md:197" # Resolved: Aug 2025 degradation
61
+ known_issues: "guide/core/known-issues.md"
62
+ known_issues_github_bug: "guide/core/known-issues.md:7" # GitHub auto-creation bug
63
+ known_issues_token_consumption: "guide/core/known-issues.md:105" # Excessive token usage
64
+ known_issues_model_quality_aug2025: "guide/core/known-issues.md:197" # Resolved: Aug 2025 degradation
65
65
  # Template Installation
66
66
  install_templates_script: "scripts/install-templates.sh"
67
67
  # Session management
68
- session_search: "guide/observability.md:38"
68
+ session_search: "guide/ops/observability.md:38"
69
69
  session_search_script: "examples/scripts/session-search.sh"
70
70
  cc_sessions_script: "examples/scripts/cc-sessions.py"
71
- session_resume_limitations: "guide/observability.md:126"
72
- session_cross_folder_migration: "guide/observability.md:126"
73
- session_migration_manual: "guide/observability.md:126"
74
- session_migration_risks: "guide/observability.md:126"
75
- session_migration_community_tool: "guide/observability.md:52"
71
+ session_resume_limitations: "guide/ops/observability.md:126"
72
+ session_cross_folder_migration: "guide/ops/observability.md:126"
73
+ session_migration_manual: "guide/ops/observability.md:126"
74
+ session_migration_risks: "guide/ops/observability.md:126"
75
+ session_migration_community_tool: "guide/ops/observability.md:52"
76
76
  session_migration_issue: "https://github.com/anthropics/claude-code/issues/1516"
77
77
  session_migration_weller_skill: "https://github.com/jimweller/dotfiles/tree/main/dotfiles/claude-code/skills/claude-migrate-session"
78
78
  # Activity monitoring
79
- activity_monitoring: "guide/observability.md:467" # Tool call audit via JSONL
80
- activity_monitoring_queries: "guide/observability.md:467" # jq queries for audit
81
- activity_monitoring_alerts: "guide/observability.md:467" # Sensitive pattern detection
82
- external_monitoring_tools: "guide/observability.md:527" # ccusage, claude-code-otel, Akto, MLflow, ccboard
83
- proxying_claude_code: "guide/observability.md:699" # Proxyman, mitmproxy, ANTHROPIC_API_URL
79
+ activity_monitoring: "guide/ops/observability.md:467" # Tool call audit via JSONL
80
+ activity_monitoring_queries: "guide/ops/observability.md:467" # jq queries for audit
81
+ activity_monitoring_alerts: "guide/ops/observability.md:467" # Sensitive pattern detection
82
+ external_monitoring_tools: "guide/ops/observability.md:527" # ccusage, claude-code-otel, Akto, MLflow, ccboard
83
+ proxying_claude_code: "guide/ops/observability.md:699" # Proxyman, mitmproxy, ANTHROPIC_API_URL
84
84
  ccboard_activity_plan: "docs/resource-evaluations/ccboard-activity-module-plan.md"
85
85
  # Cost optimization - Local execution bridge
86
86
  bridge_script: "examples/scripts/bridge.py"
@@ -91,7 +91,7 @@ deep_dive:
91
91
  rtk_website: "https://www.rtk-ai.app/"
92
92
  rtk_evaluation: "docs/resource-evaluations/rtk-evaluation.md"
93
93
  rtk_guide: "guide/ultimate-guide.md:14553"
94
- rtk_third_party: "guide/third-party-tools.md:7"
94
+ rtk_third_party: "guide/ecosystem/third-party-tools.md:7"
95
95
  rtk_claude_md: "examples/claude-md/rtk-optimized.md"
96
96
  rtk_skill: "examples/skills/rtk-optimizer/SKILL.md"
97
97
  rtk_hook: "examples/hooks/bash/rtk-auto-wrapper.sh"
@@ -100,7 +100,7 @@ deep_dive:
100
100
  rtk_score: "5/5"
101
101
  rtk_installation: "cargo install rtk or brew install rtk-ai/tap/rtk"
102
102
  # Google Antigravity (Agent-First IDE)
103
- antigravity_guide: "guide/ai-ecosystem.md:1366"
103
+ antigravity_guide: "guide/ecosystem/ai-ecosystem.md:1366"
104
104
  antigravity_evaluation: "docs/resource-evaluations/google-antigravity-evaluation.md"
105
105
  antigravity_proxy: "https://www.npmjs.com/package/antigravity-claude-proxy"
106
106
  antigravity_codelabs: "https://codelabs.developers.google.com/getting-started-google-antigravity"
@@ -125,35 +125,35 @@ deep_dive:
125
125
  talk_pipeline_patterns: "skill chaining + file-based state + tool permission scoping + human-in-the-loop gate + AI-to-AI handoff (Claude → Kimi)"
126
126
  talk_pipeline_checkpoint: "Stage 4 CHECKPOINT: user selects angle + title before script starts"
127
127
  talk_pipeline_kimi: "kimi.com (free) — copy-paste Stage 5 prompt for AI slide generation"
128
- # reMarkable 2 + AI (guide/remarkable-ai.md)
129
- remarkable_ai_guide: "guide/remarkable-ai.md"
130
- remarkable_mcp_server: "guide/remarkable-ai.md#1-remarkable-mcp--le-game-changer"
128
+ # reMarkable 2 + AI (guide/ecosystem/remarkable-ai.md)
129
+ remarkable_ai_guide: "guide/ecosystem/remarkable-ai.md"
130
+ remarkable_mcp_server: "guide/ecosystem/remarkable-ai.md#1-remarkable-mcp--le-game-changer"
131
131
  remarkable_mcp_repo: "https://github.com/SamMorrowDrums/remarkable-mcp"
132
- remarkable_ghostwriter: "guide/remarkable-ai.md#2-ghostwriter--interface-vision-llm"
133
- remarkable_obsidian_sync: "guide/remarkable-ai.md#3-sync-remarkable--obsidian"
134
- remarkable_ocr_pipeline: "guide/remarkable-ai.md#4-ocr--ai-pipeline-custom"
135
- remarkable_ssh_tools: "guide/remarkable-ai.md#5-accès-ssh-et-outils-communautaires"
136
- remarkable_meeting_workflow: "guide/remarkable-ai.md#10-meeting-notes--ai-summary"
137
- remarkable_workflows_to_build: "guide/remarkable-ai.md#14-workflows-ai-augmentés-à-construire"
138
- remarkable_getting_started: "guide/remarkable-ai.md#15-par-où-commencer"
132
+ remarkable_ghostwriter: "guide/ecosystem/remarkable-ai.md#2-ghostwriter--interface-vision-llm"
133
+ remarkable_obsidian_sync: "guide/ecosystem/remarkable-ai.md#3-sync-remarkable--obsidian"
134
+ remarkable_ocr_pipeline: "guide/ecosystem/remarkable-ai.md#4-ocr--ai-pipeline-custom"
135
+ remarkable_ssh_tools: "guide/ecosystem/remarkable-ai.md#5-accès-ssh-et-outils-communautaires"
136
+ remarkable_meeting_workflow: "guide/ecosystem/remarkable-ai.md#10-meeting-notes--ai-summary"
137
+ remarkable_workflows_to_build: "guide/ecosystem/remarkable-ai.md#14-workflows-ai-augmentés-à-construire"
138
+ remarkable_getting_started: "guide/ecosystem/remarkable-ai.md#15-par-où-commencer"
139
139
  remarkable_community: "https://github.com/reHackable/awesome-reMarkable"
140
140
  # Whitepapers (FR + EN) — 9 focused whitepapers on Claude Code
141
141
  whitepapers_url: "https://www.florian.bruniaux.com/guides"
142
142
  whitepapers_fr: "whitepapers/fr/" # FR sources (Quarto .qmd)
143
143
  whitepapers_en: "whitepapers/en/" # EN sources (Quarto .qmd)
144
144
  whitepapers_topics: "foundations, prompting, customization, security, architecture, team, privacy, reference, agent-teams"
145
- # Learning with AI (guide/learning-with-ai.md)
146
- learning_quick_check: "guide/learning-with-ai.md:38"
147
- learning_uval_protocol: "guide/learning-with-ai.md:218"
148
- learning_claude_config: "guide/learning-with-ai.md:458"
149
- learning_breaking_dependency: "guide/learning-with-ai.md:575"
150
- learning_embracing_ai: "guide/learning-with-ai.md:623"
151
- learning_30day_plan: "guide/learning-with-ai.md:815"
152
- learning_red_flags: "guide/learning-with-ai.md:612"
145
+ # Learning with AI (guide/roles/learning-with-ai.md)
146
+ learning_quick_check: "guide/roles/learning-with-ai.md:38"
147
+ learning_uval_protocol: "guide/roles/learning-with-ai.md:218"
148
+ learning_claude_config: "guide/roles/learning-with-ai.md:458"
149
+ learning_breaking_dependency: "guide/roles/learning-with-ai.md:575"
150
+ learning_embracing_ai: "guide/roles/learning-with-ai.md:623"
151
+ learning_30day_plan: "guide/roles/learning-with-ai.md:815"
152
+ learning_red_flags: "guide/roles/learning-with-ai.md:612"
153
153
  # Productivity Research RCTs
154
- productivity_rct_metr: "guide/learning-with-ai.md:925" # METR 2025: experienced devs 19% slower on large codebases despite perceiving 20% faster
155
- productivity_rct_echoes: "guide/learning-with-ai.md:926" # Borg 2025: 30.7% faster (median), ~55.9% habitual users, no maintainability impact downstream
156
- productivity_maintainability_empirical: "guide/learning-with-ai.md:926" # Empirical data on "AI code is unmaintainable" claim — blind RCT shows no significant difference
154
+ productivity_rct_metr: "guide/roles/learning-with-ai.md:925" # METR 2025: experienced devs 19% slower on large codebases despite perceiving 20% faster
155
+ productivity_rct_echoes: "guide/roles/learning-with-ai.md:926" # Borg 2025: 30.7% faster (median), ~55.9% habitual users, no maintainability impact downstream
156
+ productivity_maintainability_empirical: "guide/roles/learning-with-ai.md:926" # Empirical data on "AI code is unmaintainable" claim — blind RCT shows no significant difference
157
157
  trust_calibration_maintainability_nuance: "guide/ultimate-guide.md:1097" # Nuance: defect rates ≠ maintenance burden (Borg et al. 2025)
158
158
  learning_mode_template: "examples/claude-md/learning-mode.md"
159
159
  learn_quiz_command: "examples/commands/learn/quiz.md"
@@ -161,23 +161,23 @@ deep_dive:
161
161
  learn_alternatives_command: "examples/commands/learn/alternatives.md"
162
162
  learning_capture_hook: "examples/hooks/bash/learning-capture.sh"
163
163
  # Anti-patterns
164
- vibe_coding_trap: "guide/learning-with-ai.md:87"
164
+ vibe_coding_trap: "guide/roles/learning-with-ai.md:87"
165
165
  vibe_coding_context_overload: 13097
166
166
  vibe_coding_context_overload_source: "Jens Rusitschka, 'Vibe Coding, Level 2' (Jan 2026)"
167
167
  vibe_coding_phased_strategy: 13097
168
- # AI Traceability & Attribution (guide/ai-traceability.md) - Added 2026-01-24
169
- ai_traceability_guide: "guide/ai-traceability.md"
170
- ai_traceability_why: "guide/ai-traceability.md:29"
171
- ai_traceability_disclosure_spectrum: "guide/ai-traceability.md:64"
172
- ai_traceability_co_authored_by: "guide/ai-traceability.md:98"
173
- ai_traceability_assisted_by: "guide/ai-traceability.md:120"
174
- ai_traceability_git_ai: "guide/ai-traceability.md:170"
175
- ai_traceability_llvm_policy: "guide/ai-traceability.md:201"
176
- ai_traceability_ghostty_policy: "guide/ai-traceability.md:236"
177
- ai_traceability_fedora_policy: "guide/ai-traceability.md:261"
178
- ai_traceability_promptpwnd: "guide/ai-traceability.md:501"
179
- ai_traceability_implementation: "guide/ai-traceability.md:566"
180
- ai_traceability_templates: "guide/ai-traceability.md:648"
168
+ # AI Traceability & Attribution (guide/ops/ai-traceability.md) - Added 2026-01-24
169
+ ai_traceability_guide: "guide/ops/ai-traceability.md"
170
+ ai_traceability_why: "guide/ops/ai-traceability.md:29"
171
+ ai_traceability_disclosure_spectrum: "guide/ops/ai-traceability.md:64"
172
+ ai_traceability_co_authored_by: "guide/ops/ai-traceability.md:98"
173
+ ai_traceability_assisted_by: "guide/ops/ai-traceability.md:120"
174
+ ai_traceability_git_ai: "guide/ops/ai-traceability.md:170"
175
+ ai_traceability_llvm_policy: "guide/ops/ai-traceability.md:201"
176
+ ai_traceability_ghostty_policy: "guide/ops/ai-traceability.md:236"
177
+ ai_traceability_fedora_policy: "guide/ops/ai-traceability.md:261"
178
+ ai_traceability_promptpwnd: "guide/ops/ai-traceability.md:501"
179
+ ai_traceability_implementation: "guide/ops/ai-traceability.md:566"
180
+ ai_traceability_templates: "guide/ops/ai-traceability.md:648"
181
181
  # AI Disclosure Templates
182
182
  ai_disclosure_contributing: "examples/config/CONTRIBUTING-ai-disclosure.md"
183
183
  ai_disclosure_pr_template: "examples/config/PULL_REQUEST_TEMPLATE-ai.md"
@@ -187,15 +187,15 @@ deep_dive:
187
187
  tts_voice_catalog: "examples/integrations/agent-vibes/voice-catalog.md"
188
188
  tts_troubleshooting: "examples/integrations/agent-vibes/troubleshooting.md"
189
189
  tts_workflow: "guide/workflows/tts-setup.md"
190
- tts_ai_ecosystem: "guide/ai-ecosystem.md:1124"
190
+ tts_ai_ecosystem: "guide/ecosystem/ai-ecosystem.md:1124"
191
191
  tts_hook_example: "examples/hooks/bash/tts-selective.sh"
192
192
  tts_claude_md_template: "examples/claude-md/tts-enabled.md"
193
- # Sandbox Isolation for Coding Agents (guide/sandbox-isolation.md) - Added 2026-01-31
194
- sandbox_isolation_guide: "guide/sandbox-isolation.md"
195
- sandbox_isolation_decision_tree: "guide/sandbox-isolation.md:7"
196
- sandbox_docker_sandboxes: "guide/sandbox-isolation.md:67"
197
- sandbox_docker_network: "guide/sandbox-isolation.md:121"
198
- sandbox_docker_templates: "guide/sandbox-isolation.md:165"
193
+ # Sandbox Isolation for Coding Agents (guide/security/sandbox-isolation.md) - Added 2026-01-31
194
+ sandbox_isolation_guide: "guide/security/sandbox-isolation.md"
195
+ sandbox_isolation_decision_tree: "guide/security/sandbox-isolation.md:7"
196
+ sandbox_docker_sandboxes: "guide/security/sandbox-isolation.md:67"
197
+ sandbox_docker_network: "guide/security/sandbox-isolation.md:121"
198
+ sandbox_docker_templates: "guide/security/sandbox-isolation.md:165"
199
199
  sandbox_docker_docs: "https://docs.docker.com/ai/sandboxes/"
200
200
  sandbox_docker_claude_config: "https://docs.docker.com/ai/sandboxes/claude-code/"
201
201
  sandbox_docker_network_docs: "https://docs.docker.com/ai/sandboxes/network-policies/"
@@ -204,26 +204,26 @@ deep_dive:
204
204
  sandbox_cloudflare_sdk: "https://developers.cloudflare.com/sandbox/tutorials/claude-code/"
205
205
  sandbox_vercel: "https://vercel.com/docs/vercel-sandbox/"
206
206
  sandbox_e2b: "https://e2b.dev"
207
- sandbox_native_cc: "guide/architecture.md:606"
207
+ sandbox_native_cc: "guide/core/architecture.md:606"
208
208
  # Native Claude Code Sandbox (Official docs, v2.1.0+) - Added 2026-02-02
209
- sandbox_native_guide: "guide/sandbox-native.md"
210
- sandbox_native_why: "guide/sandbox-native.md:47" # Why Native Sandboxing
211
- sandbox_native_os_primitives: "guide/sandbox-native.md:68" # Seatbelt vs bubblewrap
212
- sandbox_native_filesystem: "guide/sandbox-native.md:178" # Filesystem isolation
213
- sandbox_native_network: "guide/sandbox-native.md:221" # Network proxy architecture
214
- sandbox_native_modes: "guide/sandbox-native.md:7" # Auto-allow vs Regular
215
- sandbox_native_escape_hatch: "guide/sandbox-native.md:341" # dangerouslyDisableSandbox
216
- sandbox_native_security_limits: "guide/sandbox-native.md:396" # Domain fronting, Unix sockets
217
- sandbox_native_opensource: "guide/sandbox-native.md:481" # Open-source runtime
218
- sandbox_native_platforms: "guide/sandbox-native.md:505" # Platform support
219
- sandbox_native_decision_tree: "guide/sandbox-native.md:517" # Native vs Docker
220
- sandbox_native_config_examples: "guide/sandbox-native.md:564" # Configuration examples
221
- sandbox_native_best_practices: "guide/sandbox-native.md:637" # Best practices
222
- sandbox_native_troubleshooting: "guide/sandbox-native.md:650" # Troubleshooting
209
+ sandbox_native_guide: "guide/security/sandbox-native.md"
210
+ sandbox_native_why: "guide/security/sandbox-native.md:47" # Why Native Sandboxing
211
+ sandbox_native_os_primitives: "guide/security/sandbox-native.md:68" # Seatbelt vs bubblewrap
212
+ sandbox_native_filesystem: "guide/security/sandbox-native.md:178" # Filesystem isolation
213
+ sandbox_native_network: "guide/security/sandbox-native.md:221" # Network proxy architecture
214
+ sandbox_native_modes: "guide/security/sandbox-native.md:7" # Auto-allow vs Regular
215
+ sandbox_native_escape_hatch: "guide/security/sandbox-native.md:341" # dangerouslyDisableSandbox
216
+ sandbox_native_security_limits: "guide/security/sandbox-native.md:396" # Domain fronting, Unix sockets
217
+ sandbox_native_opensource: "guide/security/sandbox-native.md:481" # Open-source runtime
218
+ sandbox_native_platforms: "guide/security/sandbox-native.md:505" # Platform support
219
+ sandbox_native_decision_tree: "guide/security/sandbox-native.md:517" # Native vs Docker
220
+ sandbox_native_config_examples: "guide/security/sandbox-native.md:564" # Configuration examples
221
+ sandbox_native_best_practices: "guide/security/sandbox-native.md:637" # Best practices
222
+ sandbox_native_troubleshooting: "guide/security/sandbox-native.md:650" # Troubleshooting
223
223
  sandbox_runtime_oss: "https://github.com/anthropic-experimental/sandbox-runtime"
224
224
  sandbox_runtime_npm: "https://www.npmjs.com/package/@anthropic-ai/sandbox-runtime"
225
225
  sandbox_official_docs: "https://code.claude.com/docs/en/sandboxing"
226
- sandbox_comparison_native_docker: "guide/sandbox-isolation.md:238" # Section 4 Native CC
226
+ sandbox_comparison_native_docker: "guide/security/sandbox-isolation.md:238" # Section 4 Native CC
227
227
  sandbox_native_evaluation: "docs/resource-evaluations/native-sandbox-official-docs.md"
228
228
  sandbox_native_score: "5/5"
229
229
  # Templates (Added 2026-02-02)
@@ -232,19 +232,19 @@ deep_dive:
232
232
  sandbox_validation_hook: "examples/hooks/bash/sandbox-validation.sh"
233
233
  # Docker Sandboxes (existing)
234
234
  sandbox_evaluation: "docs/resource-evaluations/docker-sandboxes-isolation.md"
235
- sandbox_safe_autonomy: "guide/sandbox-isolation.md:496" # Safe Autonomy Workflows
236
- sandbox_anti_patterns: "guide/sandbox-isolation.md:546" # Anti-Patterns
237
- sandbox_comparison_matrix: "guide/sandbox-isolation.md:477" # Comparison Matrix
235
+ sandbox_safe_autonomy: "guide/security/sandbox-isolation.md:496" # Safe Autonomy Workflows
236
+ sandbox_anti_patterns: "guide/security/sandbox-isolation.md:546" # Anti-Patterns
237
+ sandbox_comparison_matrix: "guide/security/sandbox-isolation.md:477" # Comparison Matrix
238
238
  sandbox_score: "4/5"
239
- # Third-Party Tools (guide/third-party-tools.md) - Added 2026-02-01
240
- third_party_tools_guide: "guide/third-party-tools.md"
241
- third_party_tools_cost_tracking: "guide/third-party-tools.md:42"
242
- third_party_tools_rtk: "guide/third-party-tools.md:7"
243
- third_party_tools_session_mgmt: "guide/third-party-tools.md:126"
244
- third_party_tools_config_mgmt: "guide/third-party-tools.md:214"
245
- third_party_tools_alternative_uis: "guide/third-party-tools.md:259"
246
- third_party_tools_known_gaps: "guide/third-party-tools.md:375"
247
- third_party_tools_recommendations: "guide/third-party-tools.md:391"
239
+ # Third-Party Tools (guide/ecosystem/third-party-tools.md) - Added 2026-02-01
240
+ third_party_tools_guide: "guide/ecosystem/third-party-tools.md"
241
+ third_party_tools_cost_tracking: "guide/ecosystem/third-party-tools.md:42"
242
+ third_party_tools_rtk: "guide/ecosystem/third-party-tools.md:7"
243
+ third_party_tools_session_mgmt: "guide/ecosystem/third-party-tools.md:126"
244
+ third_party_tools_config_mgmt: "guide/ecosystem/third-party-tools.md:214"
245
+ third_party_tools_alternative_uis: "guide/ecosystem/third-party-tools.md:259"
246
+ third_party_tools_known_gaps: "guide/ecosystem/third-party-tools.md:375"
247
+ third_party_tools_recommendations: "guide/ecosystem/third-party-tools.md:391"
248
248
  third_party_ccusage: "https://www.npmjs.com/package/ccusage"
249
249
  third_party_ccusage_site: "https://ccusage.com"
250
250
  third_party_ccburn: "https://github.com/JuanjoFuchs/ccburn"
@@ -291,18 +291,18 @@ deep_dive:
291
291
  permissions_deny_known_limitation: "background indexing may expose via system reminders before checks — GitHub #4160"
292
292
  permissions_deny_defense_in_depth: "store secrets outside project dir for guaranteed protection"
293
293
  # Visual Reference (ASCII diagrams)
294
- visual_reference: "guide/visual-reference.md"
295
- # Architecture internals (guide/architecture.md)
296
- architecture_visual_overview: "guide/architecture.md:51"
294
+ visual_reference: "guide/core/visual-reference.md"
295
+ # Architecture internals (guide/core/architecture.md)
296
+ architecture_visual_overview: "guide/core/architecture.md:51"
297
297
  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"
298
- architecture_master_loop: "guide/architecture.md:82"
299
- architecture_tools: "guide/architecture.md:219"
300
- architecture_context: "guide/architecture.md:312"
301
- architecture_subagents: "guide/architecture.md:471"
302
- architecture_permissions: "guide/architecture.md:541"
303
- architecture_mcp: "guide/architecture.md:746"
298
+ architecture_master_loop: "guide/core/architecture.md:82"
299
+ architecture_tools: "guide/core/architecture.md:219"
300
+ architecture_context: "guide/core/architecture.md:312"
301
+ architecture_subagents: "guide/core/architecture.md:471"
302
+ architecture_permissions: "guide/core/architecture.md:541"
303
+ architecture_mcp: "guide/core/architecture.md:746"
304
304
  architecture_mcp_visual: "guide/images/mcp-architecture-diagram.svg"
305
- architecture_philosophy: "guide/architecture.md:1205"
305
+ architecture_philosophy: "guide/core/architecture.md:1205"
306
306
  # Official LLM-Optimized Documentation - Added 2026-02-25
307
307
  official_llms_index: "https://code.claude.com/docs/llms.txt" # Index ~65 pages, ~15-20K tokens — use first for discovery
308
308
  official_llms_full: "https://code.claude.com/docs/llms-full.txt" # Full doc ~98KB, ~25-30K tokens — source de vérité officielle
@@ -310,9 +310,9 @@ deep_dive:
310
310
  system_prompts_official: "https://platform.claude.com/docs/en/release-notes/system-prompts"
311
311
  system_prompts_willison_analysis: "https://simonwillison.net/2025/May/25/claude-4-system-prompt/"
312
312
  system_prompts_prompthub: "https://www.prompthub.us/blog/an-analysis-of-the-claude-4-system-prompt"
313
- system_prompts_architecture: "guide/architecture.md:360"
313
+ system_prompts_architecture: "guide/core/architecture.md:360"
314
314
  # MCP Apps Extension (SEP-1865) - Added 2026-01-27
315
- mcp_apps_architecture: "guide/architecture.md:753"
315
+ mcp_apps_architecture: "guide/core/architecture.md:753"
316
316
  mcp_apps_evolution: "guide/ultimate-guide.md:9252"
317
317
  mcp_apps_spec: "https://github.com/modelcontextprotocol/ext-apps"
318
318
  mcp_apps_blog_mcp: "https://blog.modelcontextprotocol.io/posts/2026-01-26-mcp-apps/"
@@ -534,16 +534,16 @@ deep_dive:
534
534
  - "Linear MCP: ~9.5k installs (issue tracking)"
535
535
  plugins_awesome_list: "https://github.com/hesreallyhim/awesome-claude-code"
536
536
  plugins_awesome_list_stars: "20k+"
537
- chain_of_verification: "guide/methodologies.md:230"
537
+ chain_of_verification: "guide/core/methodologies.md:230"
538
538
  chain_of_verification_paper: "https://arxiv.org/abs/2309.11495"
539
539
  chain_of_verification_acl: "https://aclanthology.org/2024.findings-acl.212/"
540
540
  # Verification Loops & Eval Harness (added 2026-01-23)
541
- verification_loops: "guide/methodologies.md:245"
541
+ verification_loops: "guide/core/methodologies.md:245"
542
542
  verification_loops_source: "https://www.anthropic.com/engineering/claude-code-best-practices"
543
- eval_harness: "guide/methodologies.md:289"
543
+ eval_harness: "guide/core/methodologies.md:289"
544
544
  eval_harness_source: "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents"
545
545
  # GSD (Get Shit Done) methodology (added 2026-01-25)
546
- gsd_methodology: "guide/methodologies.md:53"
546
+ gsd_methodology: "guide/core/methodologies.md:53"
547
547
  gsd_evaluation: "docs/resource-evaluations/gsd-evaluation.md"
548
548
  gsd_source: "https://github.com/glittercowboy/get-shit-done"
549
549
  gsd_note: "Overlap with existing patterns (Ralph Loop, Gas Town, BMAD)"
@@ -572,35 +572,35 @@ deep_dive:
572
572
  audit_agents_skills_industry_context: "29.5% deploy without evaluation (LangChain 2026), 18% cite agent bugs as top challenge"
573
573
  audit_agents_skills_guide_refs: "guide/ultimate-guide.md:4951 (after Agent Validation Checklist), guide/ultimate-guide.md:5495 (after Skill Validation)"
574
574
  # Practitioner Insights (external validation)
575
- practitioner_insights: "guide/ai-ecosystem.md:2170"
576
- practitioner_dave_van_veen: "guide/ai-ecosystem.md:2174"
577
- practitioner_matteo_collina: "guide/ai-ecosystem.md:2203"
575
+ practitioner_insights: "guide/ecosystem/ai-ecosystem.md:2170"
576
+ practitioner_dave_van_veen: "guide/ecosystem/ai-ecosystem.md:2174"
577
+ practitioner_matteo_collina: "guide/ecosystem/ai-ecosystem.md:2203"
578
578
  # Outcome Engineering (o16g) - Emerging manifesto (2026-02-13)
579
- outcome_engineering_o16g: "guide/ai-ecosystem.md:2366"
579
+ outcome_engineering_o16g: "guide/ecosystem/ai-ecosystem.md:2366"
580
580
  outcome_engineering_url: "https://o16g.com/"
581
581
  outcome_engineering_author: "Cory Ondrejka (CTO Onebrief, co-creator Second Life, ex-VP Google/Meta)"
582
582
  outcome_engineering_status: "Emerging - on watch list for community adoption"
583
583
  practitioner_collina_source: "https://adventures.nodeland.dev/archive/the-human-in-the-loop/"
584
- practitioner_steinberger: "guide/ai-ecosystem.md:2242"
584
+ practitioner_steinberger: "guide/ecosystem/ai-ecosystem.md:2242"
585
585
  practitioner_steinberger_source: "https://steipete.me/posts/2025/shipping-at-inference-speed"
586
- practitioner_addy_osmani: "guide/ai-ecosystem.md:2269"
586
+ practitioner_addy_osmani: "guide/ecosystem/ai-ecosystem.md:2269"
587
587
  practitioner_osmani_source: "https://addyo.substack.com/p/the-80-problem-in-agentic-coding"
588
- practitioner_alan: "guide/ai-ecosystem.md:2299"
588
+ practitioner_alan: "guide/ecosystem/ai-ecosystem.md:2299"
589
589
  practitioner_alan_source: "https://www.linkedin.com/pulse/le-principe-de-la-tour-eiffel-et-ralph-wiggum-maxime-le-bras-psmxe/"
590
- verification_paradox: "guide/production-safety.md:639"
590
+ verification_paradox: "guide/security/production-safety.md:639"
591
591
  verification_paradox_source: "https://www.linkedin.com/pulse/le-principe-de-la-tour-eiffel-et-ralph-wiggum-maxime-le-bras-psmxe/"
592
- eighty_percent_problem: "guide/ai-ecosystem.md:2269"
593
- comprehension_debt_secondary: "guide/ai-ecosystem.md:2269" # See also: vibe_coding_trap (primary)
594
- # DevOps/SRE Guide (guide/devops-sre.md)
595
- devops_sre_guide: "guide/devops-sre.md"
596
- devops_fire_framework: "guide/devops-sre.md:46"
597
- devops_k8s_troubleshooting: "guide/devops-sre.md:129"
598
- devops_k8s_prompts: "guide/devops-sre.md:151"
599
- devops_incident_response: "guide/devops-sre.md:333"
600
- devops_iac_patterns: "guide/devops-sre.md:504"
601
- devops_guardrails: "guide/devops-sre.md:687"
602
- devops_limitations: "guide/devops-sre.md:297"
603
- devops_quick_reference: "guide/devops-sre.md:794"
592
+ eighty_percent_problem: "guide/ecosystem/ai-ecosystem.md:2269"
593
+ comprehension_debt_secondary: "guide/ecosystem/ai-ecosystem.md:2269" # See also: vibe_coding_trap (primary)
594
+ # DevOps/SRE Guide (guide/ops/devops-sre.md)
595
+ devops_sre_guide: "guide/ops/devops-sre.md"
596
+ devops_fire_framework: "guide/ops/devops-sre.md:46"
597
+ devops_k8s_troubleshooting: "guide/ops/devops-sre.md:129"
598
+ devops_k8s_prompts: "guide/ops/devops-sre.md:151"
599
+ devops_incident_response: "guide/ops/devops-sre.md:333"
600
+ devops_iac_patterns: "guide/ops/devops-sre.md:504"
601
+ devops_guardrails: "guide/ops/devops-sre.md:687"
602
+ devops_limitations: "guide/ops/devops-sre.md:297"
603
+ devops_quick_reference: "guide/ops/devops-sre.md:794"
604
604
  devops_agent: "examples/agents/devops-sre.md"
605
605
  devops_claude_md: "examples/claude-md/devops-sre.md"
606
606
  # Product Designer (design-to-code workflow)
@@ -691,19 +691,19 @@ deep_dive:
691
691
  author: "Steve Yegge"
692
692
  description: "Multi-agent workspace manager using Claude Code instances"
693
693
  status: "Experimental (Jan 2026)"
694
- guide_section: "guide/ai-ecosystem.md:850"
694
+ guide_section: "guide/ecosystem/ai-ecosystem.md:850"
695
695
  multiclaude:
696
696
  repo: "https://github.com/dlorenc/multiclaude"
697
697
  author: "dlorenc"
698
698
  description: "Self-hosted multi-agent Claude Code spawner (tmux + git worktrees)"
699
699
  status: "Active development (Jan 2026, 383 stars)"
700
- guide_section: "guide/ai-ecosystem.md:850"
700
+ guide_section: "guide/ecosystem/ai-ecosystem.md:850"
701
701
  agent_chat:
702
702
  repo: "https://github.com/justinabrahms/agent-chat"
703
703
  author: "Justin Abrahms"
704
704
  description: "Real-time monitoring UI for Gas Town and multiclaude (SSE + SQLite)"
705
705
  status: "Early preview (Jan 2026, v0.2.0)"
706
- guide_section: "guide/ai-ecosystem.md:850"
706
+ guide_section: "guide/ecosystem/ai-ecosystem.md:850"
707
707
  # External research & alignment tools
708
708
  external_research:
709
709
  claude_constitution:
@@ -713,7 +713,7 @@ deep_dive:
713
713
  description: "Claude's Constitutional AI framework - value hierarchy (safety > ethics > compliance > utility)"
714
714
  license: "CC0 1.0 (public domain)"
715
715
  published: "2026-01-21"
716
- guide_section: "guide/data-privacy.md:296"
716
+ guide_section: "guide/security/data-privacy.md:296"
717
717
  petri_v2:
718
718
  repo: "https://github.com/safety-research/petri"
719
719
  blog: "https://alignment.anthropic.com/2026/petri-v2/"
@@ -830,7 +830,7 @@ deep_dive:
830
830
  spec_osmani_score: "4/5"
831
831
  spec_task_granularity: "guide/workflows/spec-first.md:62" # Vertical slices + PRD checklist (Allan Hill, Feb 2026)
832
832
  spec_prd_checklist: "guide/workflows/spec-first.md:68" # 6-dimension PRD quality checklist
833
- atdd_with_agents: "guide/methodologies.md:161" # ATDD + Gherkin for agentic workflows
833
+ atdd_with_agents: "guide/core/methodologies.md:161" # ATDD + Gherkin for agentic workflows
834
834
  commands_table: 47
835
835
  shortcuts_table: 368
836
836
  troubleshooting: 11311
@@ -842,23 +842,23 @@ deep_dive:
842
842
  ai_ecosystem_tool_matrix: 20031
843
843
  ai_ecosystem_workflows: 20166
844
844
  ai_ecosystem_integration: 20294
845
- ai_ecosystem_detailed: "guide/ai-ecosystem.md"
846
- ai_ecosystem_goose: "guide/ai-ecosystem.md:2074"
847
- ai_ecosystem_goose_comparison: "guide/ai-ecosystem.md:2090"
848
- ai_ecosystem_context_packing: "guide/ai-ecosystem.md:2533"
849
- ai_ecosystem_multi_ide_sync: "guide/ai-ecosystem.md:1282"
850
- agents_md_support_status: "guide/ai-ecosystem.md:1348"
851
- ai_ecosystem_build_vs_use: "guide/ai-ecosystem.md:2399" # Section 11.3 - When to Build vs Use (ADK, LangChain, Vercel AI SDK)
845
+ ai_ecosystem_detailed: "guide/ecosystem/ai-ecosystem.md"
846
+ ai_ecosystem_goose: "guide/ecosystem/ai-ecosystem.md:2074"
847
+ ai_ecosystem_goose_comparison: "guide/ecosystem/ai-ecosystem.md:2090"
848
+ ai_ecosystem_context_packing: "guide/ecosystem/ai-ecosystem.md:2533"
849
+ ai_ecosystem_multi_ide_sync: "guide/ecosystem/ai-ecosystem.md:1282"
850
+ agents_md_support_status: "guide/ecosystem/ai-ecosystem.md:1348"
851
+ ai_ecosystem_build_vs_use: "guide/ecosystem/ai-ecosystem.md:2399" # Section 11.3 - When to Build vs Use (ADK, LangChain, Vercel AI SDK)
852
852
  # Architecture Diagrams as Context (advanced pattern) - Added 2026-01-25
853
- architecture_diagrams_input: "guide/ai-ecosystem.md:2567"
853
+ architecture_diagrams_input: "guide/ecosystem/ai-ecosystem.md:2567"
854
854
  architecture_diagrams_mcp_tools:
855
855
  - "Archy MCP: https://www.pulsemcp.com/servers/phxdev1-archy"
856
856
  - "Mermaid MCP: 61.4K users"
857
857
  - "Blueprint MCP (ArcadeAI)"
858
858
  llm_oop_research: "https://dl.acm.org/doi/10.1145/3639474.3640052"
859
859
  architecture_diagrams_source: "https://www.linkedin.com/posts/tigraff_uml-claude-wibecoding-activity-7420595633826258944-gGO5"
860
- ai_ecosystem_voice_to_text: "guide/ai-ecosystem.md:1066"
861
- ai_ecosystem_alternative_providers: "guide/ai-ecosystem.md:2639"
860
+ ai_ecosystem_voice_to_text: "guide/ecosystem/ai-ecosystem.md:1066"
861
+ ai_ecosystem_alternative_providers: "guide/ecosystem/ai-ecosystem.md:2639"
862
862
  voice_refine_skill: "examples/skills/voice-refine/SKILL.md"
863
863
  # Cowork documentation (v1.0 - migrated to dedicated repo)
864
864
  cowork_reference: "machine-readable/cowork-reference.yaml" # Dedicated YAML index (kept local)
@@ -874,7 +874,7 @@ deep_dive:
874
874
  cowork_faq: "https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/reference/faq.md"
875
875
  cowork_prompts: "https://github.com/FlorianBruniaux/claude-cowork-guide/tree/main/prompts"
876
876
  cowork_workflows: "https://github.com/FlorianBruniaux/claude-cowork-guide/tree/main/workflows"
877
- cowork_section: "guide/ai-ecosystem.md:1809"
877
+ cowork_section: "guide/ecosystem/ai-ecosystem.md:1809"
878
878
  cowork_ultimate_guide: 20348
879
879
  # Experimental Features
880
880
  teammatetool: 3976
@@ -914,25 +914,25 @@ deep_dive:
914
914
  workflow: 58 # Workflow (9 steps)
915
915
  fix: 11948 # Troubleshooting section
916
916
  architecture: 919 # Architecture internals
917
- production_safety: "guide/production-safety.md" # Production safety rules
918
- security_hardening: "guide/security-hardening.md" # Security best practices
919
- security_cve_summary: "guide/security-hardening.md:15" # Decision Matrix + CVEs
920
- security_supply_chain_stats: "guide/security-hardening.md:137" # Agent Skills Supply Chain Risks
921
- security_mcp_scan_tool: "guide/security-hardening.md:32" # MCP Vetting Workflow
922
- security_malicious_extensions: "guide/security-hardening.md:252" # .claude/ attack surface (§1.5)
923
- security_kill_switch: "guide/security-hardening.md:630" # AI Kill Switch & Containment Architecture (§3.5)
924
- security_claude_folder_audit: "guide/security-hardening.md:228" # Repository Pre-Scan (§1.4)
917
+ production_safety: "guide/security/production-safety.md" # Production safety rules
918
+ security_hardening: "guide/security/security-hardening.md" # Security best practices
919
+ security_cve_summary: "guide/security/security-hardening.md:15" # Decision Matrix + CVEs
920
+ security_supply_chain_stats: "guide/security/security-hardening.md:137" # Agent Skills Supply Chain Risks
921
+ security_mcp_scan_tool: "guide/security/security-hardening.md:32" # MCP Vetting Workflow
922
+ security_malicious_extensions: "guide/security/security-hardening.md:252" # .claude/ attack surface (§1.5)
923
+ security_kill_switch: "guide/security/security-hardening.md:630" # AI Kill Switch & Containment Architecture (§3.5)
924
+ security_claude_folder_audit: "guide/security/security-hardening.md:228" # Repository Pre-Scan (§1.4)
925
925
  security_toxicskills_evaluation: "docs/resource-evaluations/snyk-toxicskills-evaluation.md"
926
926
  security_check_command: "examples/commands/security-check.md" # Quick config check vs known threats
927
927
  security_audit_command: "examples/commands/security-audit.md" # Full 6-phase security audit (score /100)
928
928
  security_threat_db: "examples/commands/resources/threat-db.yaml" # Threat intelligence database (authors, skills, CVEs, patterns)
929
929
  security_update_threat_db: "examples/commands/update-threat-db.md" # /update-threat-db — research & update threat database
930
- security_cc_scanner: "guide/security-hardening.md:780" # Claude Code Security (research preview) — Anthropic native vuln scanner, adversarial validation, patch suggestions
930
+ security_cc_scanner: "guide/security/security-hardening.md:780" # Claude Code Security (research preview) — Anthropic native vuln scanner, adversarial validation, patch suggestions
931
931
  security_patcher_agent: "examples/agents/security-patcher.md" # Agent: applies patches from security-auditor findings, human approval gate, Write/Edit tools
932
932
  security_gate_hook: "examples/hooks/bash/security-gate.sh" # PreToolUse hook: blocks 7 vuln patterns at write time (SQLi, XSS, hardcoded secrets, eval, weak hash, cmd injection, path traversal)
933
- security_pr_review_workflow: "guide/security-hardening.md:712" # PR security review workflow — 3-agent pipeline, git hook integration
933
+ security_pr_review_workflow: "guide/security/security-hardening.md:712" # PR security review workflow — 3-agent pipeline, git hook integration
934
934
  agent_validation_checklist: 5744 # Agent validation section in ultimate-guide.md
935
- git_mcp_guide: "guide/mcp-servers-ecosystem.md:113" # Git MCP server documentation
935
+ git_mcp_guide: "guide/ecosystem/mcp-servers-ecosystem.md:113" # Git MCP server documentation
936
936
 
937
937
  # ════════════════════════════════════════════════════════════════
938
938
  # DECISION TREE (most important - en premier)
@@ -1102,10 +1102,10 @@ mcp:
1102
1102
  playwright: "browser automation / E2E"
1103
1103
  figma: "design file access, tokens, structure (official)"
1104
1104
  git_mcp: "version control automation (official Anthropic) - 12 tools for commits, branches, diffs, logs"
1105
- git_mcp_guide: "guide/mcp-servers-ecosystem.md:102"
1105
+ git_mcp_guide: "guide/ecosystem/mcp-servers-ecosystem.md:102"
1106
1106
  git_mcp_tools: "git_status, git_log, git_diff, git_commit, git_add, git_reset, git_branch, git_create_branch, git_checkout, git_show, git_diff_unstaged, git_diff_staged"
1107
1107
  git_mcp_install: "uvx mcp-server-git --repository /path/to/repo"
1108
- git_mcp_decision_matrix: "guide/mcp-servers-ecosystem.md:212" # Git MCP vs GitHub MCP vs Bash tool
1108
+ git_mcp_decision_matrix: "guide/ecosystem/mcp-servers-ecosystem.md:212" # Git MCP vs GitHub MCP vs Bash tool
1109
1109
  git_mcp_repo: "https://github.com/modelcontextprotocol/servers/tree/main/src/git"
1110
1110
  git_mcp_score: "8.5/10"
1111
1111
  git_mcp_status: "Early development (API subject to change)"
@@ -1120,7 +1120,7 @@ mcp:
1120
1120
  search_decision_tree: "grep (text) | ast-grep (structure) | Serena (symbols) | grepai (semantic)"
1121
1121
  search_tools_comparison: "guide/ultimate-guide.md:9845"
1122
1122
  search_tools_mastery_workflow: "guide/workflows/search-tools-mastery.md"
1123
- grep_vs_rag_history: "guide/architecture.md:232"
1123
+ grep_vs_rag_history: "guide/core/architecture.md:232"
1124
1124
  ripgrep_native: "Grep tool (Claude Code built-in, ~20ms)"
1125
1125
  grepai_semantic: "Semantic search + call graph (Ollama-based, ~500ms)"
1126
1126
  grepai_benchmark:
@@ -1136,10 +1136,10 @@ mcp:
1136
1136
  config: "~/.claude.json (mcpServers field) or .mcp.json (project root)"
1137
1137
  tool_search: "lazy loading MCP tools (v2.1.7+) - 85% token reduction - auto:N threshold config"
1138
1138
  tool_search_config: "ENABLE_TOOL_SEARCH=auto|auto:N|true|false"
1139
- tool_search_deep_dive: "guide/architecture.md:284"
1139
+ tool_search_deep_dive: "guide/core/architecture.md:284"
1140
1140
 
1141
1141
  # ════════════════════════════════════════════════════════════════
1142
- # ARCHITECTURE INTERNALS - see guide/architecture.md
1142
+ # ARCHITECTURE INTERNALS - see guide/core/architecture.md
1143
1143
  # ════════════════════════════════════════════════════════════════
1144
1144
  architecture:
1145
1145
  master_loop: "while(tool_call) - no DAG, no classifier, no RAG"
@@ -1150,7 +1150,7 @@ architecture:
1150
1150
  philosophy: "less scaffolding, more model - trust Claude's reasoning"
1151
1151
  mcp_protocol: "JSON-RPC 2.0, treated as native tools"
1152
1152
  permissions: "interactive prompts + allow/deny rules + hooks"
1153
- deep_dive: "guide/architecture.md"
1153
+ deep_dive: "guide/core/architecture.md"
1154
1154
 
1155
1155
  # ════════════════════════════════════════════════════════════════
1156
1156
  # COST OPTIMIZATION - see deep_dive.cost_optimization
@@ -1346,7 +1346,7 @@ ecosystem:
1346
1346
  focus: "Production-grade agentic coding guardrails (TDD, worktrees, manual commits)"
1347
1347
  academic: "Co-author 'Agentic Systems in Radiology' (ArXiv 2025)"
1348
1348
  alignment: "Validates patterns already documented in this guide"
1349
- guide_section: "guide/ai-ecosystem.md:1209"
1349
+ guide_section: "guide/ecosystem/ai-ecosystem.md:1209"
1350
1350
  install_templates: "scripts/install-templates.sh"
1351
1351
  cowork:
1352
1352
  description: "Claude Code for non-developers (desktop app)"
package/dist/index.js CHANGED
@@ -13986,14 +13986,37 @@ function searchGuide(query, limit = 10) {
13986
13986
 
13987
13987
  // src/lib/urls.ts
13988
13988
  var GITHUB_BASE = "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main";
13989
- var GUIDE_SITE_BASE = "https://cc.bruniaux.com/guide";
13989
+ var GUIDE_SITE_BASE = "https://cc.bruniaux.com/guide/ultimate-guide";
13990
+ var CHAPTER_RANGES = [
13991
+ { from: 1, to: 220, slug: "00-introduction" },
13992
+ { from: 221, to: 1378, slug: "01-quick-start" },
13993
+ { from: 1379, to: 4231, slug: "02-core-workflow" },
13994
+ { from: 4232, to: 5648, slug: "03-memory-files" },
13995
+ { from: 5649, to: 6361, slug: "04-agents" },
13996
+ { from: 6362, to: 7470, slug: "05-skills" },
13997
+ { from: 7471, to: 8106, slug: "06-commands" },
13998
+ { from: 8107, to: 9482, slug: "07-hooks" },
13999
+ { from: 9483, to: 12118, slug: "08-mcp" },
14000
+ { from: 12119, to: 19831, slug: "09-advanced-patterns" },
14001
+ { from: 19832, to: 20760, slug: "10-reference" },
14002
+ { from: 20761, to: 21384, slug: "11-ai-ecosystem" },
14003
+ { from: 21385, to: Infinity, slug: "12-appendices" }
14004
+ ];
14005
+ function lineToChapterSlug(line) {
14006
+ for (const range of CHAPTER_RANGES) {
14007
+ if (line >= range.from && line <= range.to) return range.slug;
14008
+ }
14009
+ return "12-appendices";
14010
+ }
13990
14011
  function githubUrl(filePath, line) {
13991
14012
  const base = `${GITHUB_BASE}/${filePath}`;
13992
14013
  return line ? `${base}#L${line}` : base;
13993
14014
  }
13994
14015
  function guideSiteUrl(filePath, line) {
13995
14016
  if (filePath !== "guide/ultimate-guide.md") return null;
13996
- return line ? `${GUIDE_SITE_BASE}/#L${line}` : GUIDE_SITE_BASE;
14017
+ if (!line) return `${GUIDE_SITE_BASE}/`;
14018
+ const chapterSlug = lineToChapterSlug(line);
14019
+ return `${GUIDE_SITE_BASE}/${chapterSlug}/`;
13997
14020
  }
13998
14021
  function formatLinks(filePath, line) {
13999
14022
  const gh = githubUrl(filePath, line);
@@ -14512,7 +14535,7 @@ function registerChangelog(server) {
14512
14535
  for (const r of ccReleases) {
14513
14536
  lines.push(`### v${r.version} (${r.date})`);
14514
14537
  for (const h of r.highlights ?? []) lines.push(`- ${h}`);
14515
- lines.push(`GitHub: ${githubUrl("guide/claude-code-releases.md")}`);
14538
+ lines.push(`GitHub: ${githubUrl("guide/core/claude-code-releases.md")}`);
14516
14539
  lines.push("");
14517
14540
  }
14518
14541
  }
@@ -14630,7 +14653,7 @@ function registerListExamples(server) {
14630
14653
  }
14631
14654
 
14632
14655
  // src/tools/releases.ts
14633
- var RELEASES_GITHUB = githubUrl("guide/claude-code-releases.md");
14656
+ var RELEASES_GITHUB = githubUrl("guide/core/claude-code-releases.md");
14634
14657
  function registerReleases(server) {
14635
14658
  server.tool(
14636
14659
  "get_release",
@@ -14696,7 +14719,7 @@ Full history: ${RELEASES_GITHUB}`
14696
14719
  }
14697
14720
 
14698
14721
  // src/tools/compare-versions.ts
14699
- var RELEASES_GITHUB2 = githubUrl("guide/claude-code-releases.md");
14722
+ var RELEASES_GITHUB2 = githubUrl("guide/core/claude-code-releases.md");
14700
14723
  function parseSemver(v) {
14701
14724
  const parts = v.replace(/^v/, "").split(".").map(Number);
14702
14725
  return [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-code-ultimate-guide-mcp",
3
- "version": "1.0.3",
3
+ "version": "1.0.4",
4
4
  "description": "MCP server for the Claude Code Ultimate Guide — search, read, and explore 20K+ lines of documentation directly from Claude Code",
5
5
  "keywords": [
6
6
  "mcp",