diff --git a/CLAUDE.md b/CLAUDE.md
index 6ea04bd..52132bc 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -467,6 +467,7 @@ External resources (articles, videos, discussions) are evaluated before integrat
### Process
1. **Research**: Initial Perplexity search → Save prompt + results in `claudedocs/resource-evaluations/` (private)
+1b. **Cross-reference**: Si ressource liée à Claude Code, vérifier les claims contre `https://code.claude.com/docs/llms-full.txt` (source officielle ~98KB)
2. **Evaluation**: Systematic scoring (1-5) → Create evaluation file in `docs/resource-evaluations/` (tracked)
3. **Challenge**: Technical review by agent to ensure objectivity
4. **Decision**: Integrate (score 3+), mention (score 2), or reject (score 1)
@@ -493,8 +494,9 @@ See full methodology: [`docs/resource-evaluations/README.md`](docs/resource-eval
## Quick Lookups
For answering questions about Claude Code:
+0. **Doc officielle Anthropic (LLM-optimized)**: `https://code.claude.com/docs/llms.txt` (index ~65 pages) ou `https://code.claude.com/docs/llms-full.txt` (doc complète ~98KB) pour les faits officiels
1. Search `machine-readable/reference.yaml` first (has line numbers to full guide)
2. Use those line numbers to read relevant sections from `guide/ultimate-guide.md`
3. Check `examples/` for ready-to-use templates
4. Check `guide/claude-code-releases.md` for recent features/changes
-5. Si info manquante ou incertaine → demander une recherche Perplexity
+5. Si info manquante ou incertaine → demander une recherche Perplexity (communauté, comparaisons, retours)
diff --git a/docs/resource-evaluations/watch-list.md b/docs/resource-evaluations/watch-list.md
index ba6baf0..006ae2c 100644
--- a/docs/resource-evaluations/watch-list.md
+++ b/docs/resource-evaluations/watch-list.md
@@ -16,6 +16,7 @@ Trigger reached → re-evaluation → Integrate (Graduated) / Drop (Dropped)
| Resource | Type | Added | Why Watching | Re-eval Trigger |
|----------|------|-------|--------------|-----------------|
+| [save-webpage-to-obsidian](https://github.com/benoitvx/claude-skill-save-webpage-to-obsidian) | Skill | 2026-02-25 | Skill Claude Code qui archive des articles web dans un vault Obsidian (dual extraction: Chrome MCP + WebFetch). Pattern dual-strategy intéressant mais config hardcodée, sécurité non adressée, pas de métriques adoption. Score 2/5. | >200 stars GitHub |
| [fp.dev](https://fp.dev/) | Tool | 2026-02-22 | Agent-native issue tracking pour Claude Code. Un vrai différentiateur (issues .md git-committables) mais adoption insuffisante, Apple Silicon only, redondant avec Tasks API. Score 2/5. | GitHub stars visibles + release cadence + write-up praticien en prod |
| [ICM](https://github.com/rtk-ai/icm) | MCP | 2026-02-12 | Pre-v1 (1 star, 11 commits) | First release + >20 stars |
| [System Prompts](https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools) | Tool | 2026-01-26 | Redundant with official sources. Re-evaluated 2026-02-13 (Opus 4.6 update): still 2/5. | Anthropic confirms CLI prompts not published |
diff --git a/examples/commands/diagnose.md b/examples/commands/diagnose.md
index 7cf6383..9c59398 100644
--- a/examples/commands/diagnose.md
+++ b/examples/commands/diagnose.md
@@ -51,7 +51,7 @@ cat .claude/settings.json 2>/dev/null || echo "No project settings"
ls -la CLAUDE.md .claude/CLAUDE.md ~/.claude/CLAUDE.md 2>/dev/null
# MCP config
-cat ~/.claude/mcp.json 2>/dev/null || echo "No MCP config"
+cat ~/.claude.json 2>/dev/null | jq '.mcpServers // empty' || echo "No MCP config"
```
### Step 4: Present Categories
@@ -150,13 +150,13 @@ cat ~/.claude/settings.json | jq '.permissions.allow'
**Likely causes**:
1. Server not installed globally
-2. Wrong path in mcp.json
+2. Wrong path in MCP config
3. Missing environment variables
**Quick diagnostic**:
```bash
# Check MCP config
-cat ~/.claude/mcp.json | jq '.mcpServers'
+cat ~/.claude.json | jq '.mcpServers'
# Check if server binary exists
which mcp-server-sequential
diff --git a/examples/commands/security-check.md b/examples/commands/security-check.md
index 1192467..9fd5068 100644
--- a/examples/commands/security-check.md
+++ b/examples/commands/security-check.md
@@ -26,10 +26,10 @@ Read the user's MCP configuration:
```bash
# Global MCP config
-cat ~/.claude/mcp.json 2>/dev/null
+cat ~/.claude.json 2>/dev/null | jq '.mcpServers // empty'
# Project MCP config
-cat .claude/mcp.json 2>/dev/null
+cat .mcp.json 2>/dev/null
```
**Check against threat-db.yaml:**
diff --git a/examples/hooks/README.md b/examples/hooks/README.md
index f2752c8..4983d32 100644
--- a/examples/hooks/README.md
+++ b/examples/hooks/README.md
@@ -54,7 +54,7 @@ Hooks are scripts that execute automatically on Claude Code events. They enable
| `Notification` | When Claude sends a notification | Sound alerts, external notifications |
| `SessionStart` | At session start | Initialization, environment setup |
| `SessionEnd` | At session end | Cleanup, session summary |
-| `Stop` | User interrupts operation | State saving, graceful shutdown |
+| `Stop` | Claude finishes responding | Post-response actions, state saving |
## Advanced Guardrails (NEW in v3.3.0)
diff --git a/examples/hooks/bash/learning-capture.sh b/examples/hooks/bash/learning-capture.sh
index e9b705b..8c406cd 100755
--- a/examples/hooks/bash/learning-capture.sh
+++ b/examples/hooks/bash/learning-capture.sh
@@ -1,6 +1,6 @@
#!/bin/bash
# Hook: Stop - Capture one learning insight at session end
-# Event: Stop (when user ends session or interrupts)
+# Event: Stop (when Claude finishes responding)
# Purpose: Build a learning journal with minimal friction
#
# Exit codes:
diff --git a/examples/hooks/bash/mcp-config-integrity.sh b/examples/hooks/bash/mcp-config-integrity.sh
index 9ca409d..7c74c93 100755
--- a/examples/hooks/bash/mcp-config-integrity.sh
+++ b/examples/hooks/bash/mcp-config-integrity.sh
@@ -6,7 +6,7 @@
# Purpose: Verify MCP configuration has not been tampered with
#
# This hook addresses CVE-2025-54135 and CVE-2025-54136 by:
-# - Computing hash of ~/.claude/mcp.json
+# - Computing hash of ~/.claude.json (MCP config location)
# - Comparing against stored baseline
# - Alerting on unauthorized modifications
# - Checking project-level .mcp.json for suspicious content
@@ -22,7 +22,7 @@
# }
#
# Initial setup (run once to create baseline):
-# sha256sum ~/.claude/mcp.json > ~/.claude/.mcp-baseline.sha256
+# sha256sum ~/.claude.json > ~/.claude/.mcp-baseline.sha256
#
# Exit codes:
# 0 = allow (config unchanged or no baseline)
@@ -36,7 +36,7 @@
set -euo pipefail
# Configuration paths
-MCP_CONFIG="${HOME}/.claude/mcp.json"
+MCP_CONFIG="${HOME}/.claude.json"
MCP_BASELINE="${HOME}/.claude/.mcp-baseline.sha256"
PROJECT_MCP=".mcp.json"
@@ -51,11 +51,11 @@ if [[ -f "$MCP_CONFIG" ]]; then
BASELINE_HASH=$(awk '{print $1}' "$MCP_BASELINE" 2>/dev/null || echo "")
if [[ -n "$CURRENT_HASH" && -n "$BASELINE_HASH" && "$CURRENT_HASH" != "$BASELINE_HASH" ]]; then
- WARNINGS+=("MCP config modified since baseline was created. Review ~/.claude/mcp.json for unauthorized changes. Run 'sha256sum ~/.claude/mcp.json > ~/.claude/.mcp-baseline.sha256' to update baseline if changes are legitimate.")
+ WARNINGS+=("MCP config modified since baseline was created. Review ~/.claude.json for unauthorized changes. Run 'sha256sum ~/.claude.json > ~/.claude/.mcp-baseline.sha256' to update baseline if changes are legitimate.")
fi
else
# No baseline - suggest creating one
- WARNINGS+=("No MCP config baseline found. Consider running: sha256sum ~/.claude/mcp.json > ~/.claude/.mcp-baseline.sha256")
+ WARNINGS+=("No MCP config baseline found. Consider running: sha256sum ~/.claude.json > ~/.claude/.mcp-baseline.sha256")
fi
# === CHECK FOR SUSPICIOUS MCP SERVERS ===
diff --git a/guide/architecture.md b/guide/architecture.md
index d265b89..569a5de 100644
--- a/guide/architecture.md
+++ b/guide/architecture.md
@@ -563,7 +563,7 @@ Claude Code has a layered security model:
│ ┌────────────────────────────────────────────────────────┐ │
│ │ { │ │
│ │ "permissions": { │ │
-│ │ "allow": ["Bash(npm:*)", "Read(**)"], │ │
+│ │ "allow": ["Bash(npm *)", "Read"], │ │
│ │ "deny": ["Bash(rm -rf *)"] │ │
│ │ } │ │
│ │ } │ │
@@ -720,21 +720,21 @@ Hooks allow programmatic control over Claude's actions:
| Capability | Supported | How |
|------------|-----------|-----|
-| Block execution | Yes | Exit code != 0 |
+| Block execution | Yes | Exit code 2 |
| Modify parameters | Yes | Return modified JSON |
| Log actions | Yes | Write to file in hook |
-| Async processing | No | Hooks are synchronous |
+| Async processing | Yes | Set `async: true` in hook config (v2.1.0+) |
**Hook JSON payload** (passed via stdin):
```json
{
- "event": "PreToolUse",
- "tool": "Bash",
- "params": {
+ "hook_event_name": "PreToolUse",
+ "tool_name": "Bash",
+ "tool_input": {
"command": "npm install lodash"
},
- "sessionId": "abc123",
+ "session_id": "abc123",
"cwd": "/path/to/project"
}
```
@@ -1290,6 +1290,8 @@ This convergence suggests that the "less scaffolding, more model" approach scale
| Hooks Guide | code.claude.com/docs/en/hooks-guide | Hook examples |
| MCP Docs | code.claude.com/docs/en/mcp | MCP integration |
| Sandboxing | code.claude.com/docs/en/sandboxing | Security model |
+| llms.txt (index) | code.claude.com/docs/llms.txt | LLM-optimized doc index, ~65 pages |
+| llms-full.txt | code.claude.com/docs/llms-full.txt | Full documentation (~98 KB text) |
### Tier 2 - Verified Analysis
diff --git a/guide/cheatsheet.md b/guide/cheatsheet.md
index ca16c3e..ef261dd 100644
--- a/guide/cheatsheet.md
+++ b/guide/cheatsheet.md
@@ -94,8 +94,10 @@ tags: [cheatsheet, reference]
| Mode | Editing | Execution |
|------|---------|-----------|
| Default | Asks | Asks |
-| Auto-accept | Auto | Asks |
+| acceptEdits | Auto | Asks |
| Plan Mode | ❌ | ❌ |
+| dontAsk | Only if in allow rules | Only if in allow rules |
+| bypassPermissions | Auto | Auto (CI/CD only) |
**Shift+Tab** to switch modes
@@ -222,7 +224,9 @@ Model: Sonnet | Ctx: 89.5k | Cost: $2.11 | Ctx(u): 56.0%
|---------|--------|-------------|
| **Alt+T** | Toggle thinking on/off | Session |
| **/config** | Enable/disable globally | Permanent |
-| **`effort` param** | API only: `low\|medium\|high\|max` | Per-request |
+| **`/model` slider** | Left/right arrows: `low\|medium\|high` | Session |
+| **`CLAUDE_CODE_EFFORT_LEVEL`** | Env var: `low\|medium\|high` | Shell session |
+| **`effortLevel` setting** | In settings.json: `low\|medium\|high` | Permanent |
**Cost tip**: For simple tasks, Alt+T to disable thinking → faster & cheaper.
@@ -389,11 +393,16 @@ VERIFY: Empty email shows error, invalid format shows error
| `--model sonnet` | Change model |
| `--add-dir ../lib` | Allow access outside CWD |
| `--permission-mode plan` | Plan mode |
+| `--tools "Tool1,Tool2"` | Enable specific tools for session |
+| `--max-budget-usd 5.00` | Max API spend limit (print mode) |
+| `--system-prompt "..."` | Append custom system prompt |
+| `--worktree` / `-w` | Run in isolated git worktree |
| `--dangerously-skip-permissions` | Auto-accept (use carefully) |
| `--debug` | Debug output |
-| `--mcp-debug` | Debug MCP servers |
| `--allowedTools "Edit,Read"` | Whitelist tools |
+> Full CLI reference (~45 flags): see [cli-reference on code.claude.com](https://docs.anthropic.com/en/docs/claude-code/cli-reference)
+
---
## Debug Commands
diff --git a/guide/data-privacy.md b/guide/data-privacy.md
index e856464..98a500e 100644
--- a/guide/data-privacy.md
+++ b/guide/data-privacy.md
@@ -12,9 +12,10 @@ tags: [privacy, security, guide]
| Configuration | Retention Period | Training | How to Enable |
|---------------|------------------|----------|---------------|
-| **Default** | 5 years | Yes | (default state) |
-| **Opt-out** | 30 days | No | [claude.ai/settings](https://claude.ai/settings/data-privacy-controls) |
-| **Enterprise (ZDR)** | 0 days | No | Enterprise contract |
+| **Consumer (default)** | 5 years | Yes | (default state) |
+| **Consumer (opt-out)** | 30 days | No | [claude.ai/settings](https://claude.ai/settings/data-privacy-controls) |
+| **Team / Enterprise / API** | 30 days | No (default) | Use Team, Enterprise plan, or API keys |
+| **ZDR (Zero Data Retention)** | 0 days server-side | No | Appropriately configured API keys |
**Immediate action**: [Disable training data usage](https://claude.ai/settings/data-privacy-controls) to reduce retention from 5 years to 30 days.
@@ -35,16 +36,20 @@ When you use Claude Code, the following data is sent to Anthropic:
│ • MCP server results (SQL queries, API responses) │
│ • Bash command outputs │
│ • Error messages and stack traces │
-└───────────────────────┬─────────────────────────────────────┘
- │
- ▼ HTTPS
-┌─────────────────────────────────────────────────────────────┐
-│ ANTHROPIC API │
-├─────────────────────────────────────────────────────────────┤
-│ • Processes your request │
-│ • Stores conversation based on retention policy │
-│ • May use data for model training (if not opted out) │
-└─────────────────────────────────────────────────────────────┘
+└───────────┬──────────────────┬──────────────┬───────────────┘
+ │ │ │
+ ▼ HTTPS/TLS ▼ HTTPS ▼ HTTPS
+┌───────────────────┐ ┌──────────────┐ ┌─────────────────────┐
+│ ANTHROPIC API │ │ STATSIG │ │ SENTRY │
+├───────────────────┤ ├──────────────┤ ├─────────────────────┤
+│ • Your prompts │ │ • Latency, │ │ • Error logs │
+│ • Model responses │ │ reliability│ │ • No code or │
+│ • Retention per │ │ • No code or │ │ file paths │
+│ your tier │ │ file paths │ │ │
+└───────────────────┘ └──────────────┘ └─────────────────────┘
+ (opt-out: (opt-out:
+ DISABLE_ DISABLE_ERROR_
+ TELEMETRY=1) REPORTING=1)
```
### What This Means in Practice
@@ -61,13 +66,13 @@ When you use Claude Code, the following data is sent to Anthropic:
## 2. Anthropic Retention Policies
-### Tier 1: Default (Training Enabled)
+### Tier 1: Consumer Default (Training Enabled)
- **Retention**: 5 years
- **Usage**: Model improvement, training data
-- **Applies to**: Free, Pro, Max plans without opt-out
+- **Applies to**: Free, Pro, Max plans with training setting ON
-### Tier 2: Training Disabled (Opt-Out)
+### Tier 2: Consumer Opt-Out (Training Disabled)
- **Retention**: 30 days
- **Usage**: Safety monitoring, abuse prevention only
@@ -76,12 +81,21 @@ When you use Claude Code, the following data is sent to Anthropic:
2. Disable "Allow model training on your conversations"
3. Changes apply immediately
-### Tier 3: Enterprise API (Zero Data Retention)
+### Tier 3: Commercial (Team / Enterprise / API)
-- **Retention**: 0 days (real-time processing only)
-- **Usage**: None - data not stored
-- **Requires**: Enterprise contract with Anthropic
-- **Use cases**: HIPAA, GDPR, PCI-DSS compliance, government contracts
+- **Retention**: 30 days
+- **Usage**: Safety monitoring, abuse prevention only
+- **Training**: Not used for training by default (no opt-out needed)
+- **Applies to**: Team plans, Enterprise plans, API users, third-party platforms, Claude Gov
+
+### Tier 4: Zero Data Retention (ZDR)
+
+- **Retention**: 0 days server-side (local client cache may persist up to 30 days)
+- **Usage**: None retained on Anthropic servers
+- **Requires**: Appropriately configured API keys (see [Anthropic documentation](https://www.anthropic.com/enterprise))
+- **Use cases**: HIPAA (requires separate BAA), GDPR, PCI-DSS compliance, government contracts
+
+> **Important**: Data is encrypted in transit via TLS but is **not encrypted at rest** on Anthropic servers. Factor this into your security assessments.
---
@@ -127,7 +141,21 @@ STRIPE_SECRET_KEY=sk_live_...
**Mitigation**: Use hooks to filter sensitive command outputs.
-### Risk 4: Documented Community Incidents
+### Risk 4: The `/bug` Command Sends Everything (Retained 5 Years)
+
+When you run `/bug` in Claude Code, your **full conversation history** (including all code, file contents, and potentially secrets) is sent to Anthropic for bug triage. This data is retained for **5 years**, regardless of your training opt-out setting.
+
+This is independent of your privacy preferences: even with training disabled and 30-day retention, bug reports follow their own 5-year retention policy.
+
+**Mitigation**: Disable the command entirely if you work with sensitive codebases:
+
+```bash
+export DISABLE_BUG_COMMAND=1
+```
+
+Or add it to your shell profile (`~/.zshrc`, `~/.bashrc`) to make it permanent.
+
+### Risk 5: Documented Community Incidents
| Incident | Source |
|----------|--------|
@@ -195,6 +223,29 @@ if [[ "$TOOL_NAME" == "Read" ]]; then
fi
```
+#### 4.4 Opt-Out of Telemetry and Error Reporting
+
+Claude Code connects to third-party services for operational metrics (Statsig) and error logging (Sentry). These do not include your code or file paths, but you can disable them entirely:
+
+| Variable | What it Disables |
+|----------|-----------------|
+| `DISABLE_TELEMETRY=1` | Statsig operational metrics (latency, reliability, usage patterns) |
+| `DISABLE_ERROR_REPORTING=1` | Sentry error logging |
+| `DISABLE_BUG_COMMAND=1` | The `/bug` command (prevents sending full conversation history) |
+| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` | All non-essential network traffic at once |
+| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` | Session quality surveys (note: surveys only send your numeric rating, never transcripts) |
+
+Add these to your shell profile for permanent effect:
+
+```bash
+# In ~/.zshrc or ~/.bashrc
+export DISABLE_TELEMETRY=1
+export DISABLE_ERROR_REPORTING=1
+export DISABLE_BUG_COMMAND=1
+```
+
+> **Note**: When using Bedrock, Vertex, or Foundry providers, all non-essential traffic (telemetry, error reporting, bug command, surveys) is disabled by default.
+
### MCP Best Practices
| Rule | Rationale |
@@ -338,6 +389,7 @@ Anthropic published Claude's constitution in January 2026 (CC0 license - public
## Changelog
+- 2026-02: Fixed retention model (3 tiers to 4 tiers), added /bug command warning, telemetry opt-out variables, encryption-at-rest disclosure, updated ZDR conditions
- 2026-01: Added Claude's governance & constitutional AI framework section
- 2026-01: Added intellectual property considerations section
- 2026-01: Initial version - documenting retention policies and protective measures
diff --git a/guide/devops-sre.md b/guide/devops-sre.md
index 4752973..d196e55 100644
--- a/guide/devops-sre.md
+++ b/guide/devops-sre.md
@@ -133,7 +133,7 @@ claude "Create a brief incident note for our wiki:
For persistent K8s context, install the K8s MCP server:
```json
-// ~/.claude/mcp.json
+// ~/.claude.json (or .mcp.json)
{
"mcpServers": {
"kubernetes": {
@@ -831,7 +831,7 @@ approval_required:
| Prometheus | Direct metrics queries | Community: search awesome-mcp-servers |
| Terraform | State/plan analysis | Community: search awesome-mcp-servers |
-**Config location**: `~/.claude/mcp.json`
+**Config location**: `~/.claude.json` (field `"mcpServers"`)
```json
{
diff --git a/guide/diagrams/05-mcp-ecosystem.md b/guide/diagrams/05-mcp-ecosystem.md
index 146b49d..f8c2b88 100644
--- a/guide/diagrams/05-mcp-ecosystem.md
+++ b/guide/diagrams/05-mcp-ecosystem.md
@@ -213,9 +213,9 @@ MCP server configurations can live in 4 different locations. The resolution orde
```mermaid
flowchart TD
- A["1️⃣ CLI: --mcp-config path/to/mcp.json
Highest priority — overrides all"] --> B["2️⃣ Project: .claude/mcp.json
Team-shared, checked into git"]
- B --> C["3️⃣ Project Root: .mcp.json
Alternative project location"]
- C --> D["4️⃣ Global: ~/.claude/mcp.json
Personal servers, all projects"]
+ A["1️⃣ CLI: --mcp-config path/to/config.json
Highest priority — overrides all"] --> B["2️⃣ Project Root: .mcp.json
Team-shared, checked into git"]
+ B --> C["3️⃣ Local scope: ~/.claude.json
Private to you + current project"]
+ C --> D["4️⃣ User scope: ~/.claude.json
Personal servers, all projects"]
D --> E["5️⃣ No MCP servers
Default (no config found)"]
A1["Use for:
CI/CD overrides
temporary testing"] --> A
@@ -234,7 +234,7 @@ flowchart TD
click A href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#83-configuration" "CLI --mcp-config flag"
click B href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#83-configuration" "Project .claude/mcp.json"
click C href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#83-configuration" "Project Root .mcp.json"
- click D href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#83-configuration" "Global ~/.claude/mcp.json"
+ click D href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#83-configuration" "User scope ~/.claude.json"
click E href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#81-what-is-mcp" "No MCP servers"
click A1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#83-configuration" "CI/CD overrides"
click B1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#83-configuration" "Team-shared servers"
@@ -247,9 +247,9 @@ flowchart TD
```
PRIORITY (highest → lowest):
1. --mcp-config flag → CLI override, temporary
-2. .claude/mcp.json → team-shared (git-tracked)
-3. .mcp.json → project root alternative
-4. ~/.claude/mcp.json → personal global servers
+2. .mcp.json → project-scope (git-tracked, shareable)
+3. ~/.claude.json → local scope (private, current project)
+4. ~/.claude.json → user scope (personal, all projects)
5. (none) → no MCP servers available
```
diff --git a/guide/known-issues.md b/guide/known-issues.md
index 806b399..144d8f2 100644
--- a/guide/known-issues.md
+++ b/guide/known-issues.md
@@ -170,7 +170,7 @@ While Anthropic investigates:
```
4. **Reduce MCP tools** if not needed:
- - Review `~/.claude/mcp.json`
+ - Review `~/.claude.json` (field `"mcpServers"`)
- Disable unused servers
5. **Use subagents** for isolated tasks:
diff --git a/guide/mcp-servers-ecosystem.md b/guide/mcp-servers-ecosystem.md
index 2ccbd8e..e23a3ab 100644
--- a/guide/mcp-servers-ecosystem.md
+++ b/guide/mcp-servers-ecosystem.md
@@ -165,7 +165,7 @@ python -m mcp_server_git
docker run -v /path/to/repo:/repo ghcr.io/modelcontextprotocol/mcp-server-git
```
-**Claude Desktop Configuration** (`~/.claude/mcp.json`):
+**Claude Code Configuration** (`~/.claude.json`):
```json
{
@@ -308,7 +308,7 @@ npm install @microsoft/playwright-mcp
npx @microsoft/playwright-mcp
```
-**Claude Desktop Configuration** (`~/.claude/mcp.json`):
+**Claude Code Configuration** (`~/.claude.json`):
```json
{
@@ -1050,7 +1050,7 @@ proxy:
**Generate Claude Desktop Config**:
```bash
-./mcp-compose create-config --type claude --output ~/.claude/mcp.json
+./mcp-compose create-config --type claude --output ~/.claude.json
```
**Start Servers**:
diff --git a/guide/sandbox-isolation.md b/guide/sandbox-isolation.md
index c821c3d..be2451c 100644
--- a/guide/sandbox-isolation.md
+++ b/guide/sandbox-isolation.md
@@ -315,10 +315,6 @@ sudo dnf install bubblewrap socat # Fedora
{
"sandbox": {
"autoAllowMode": true,
- "filesystem": {
- "allowedWritePaths": ["${CWD}"],
- "deniedReadPaths": ["${HOME}/.ssh", "${HOME}/.aws"]
- },
"network": {
"policy": "deny",
"allowedDomains": [
@@ -327,6 +323,12 @@ sudo dnf install bubblewrap socat # Fedora
"github.com"
]
}
+ },
+ "permissions": {
+ "deny": [
+ "Read(~/.ssh/**)", "Read(~/.aws/**)",
+ "Edit(~/.ssh/**)", "Edit(~/.aws/**)"
+ ]
}
}
```
diff --git a/guide/sandbox-native.md b/guide/sandbox-native.md
index 2b01b76..5759baa 100644
--- a/guide/sandbox-native.md
+++ b/guide/sandbox-native.md
@@ -190,28 +190,27 @@ This asymmetric policy balances usability and security:
- **Read all**: Claude needs to search/analyze entire codebase, read system configs, inspect dependencies
- **Write CWD**: Most development work happens within project directory; restricting writes prevents accidental/malicious system modifications
-### Configurable Paths
+### Configuring Filesystem Restrictions
-Customize via `settings.json`:
+Filesystem restrictions are configured through **permission rules** (Read/Edit deny rules), not sandbox settings:
```json
{
- "sandbox": {
- "filesystem": {
- "allowedWritePaths": [
- "/Users/you/projects/my-app",
- "/tmp"
- ],
- "deniedReadPaths": [
- "/Users/you/.ssh",
- "/Users/you/.aws",
- "/Users/you/.kube"
- ]
- }
+ "permissions": {
+ "deny": [
+ "Read(~/.ssh/**)",
+ "Read(~/.aws/**)",
+ "Read(~/.kube/**)",
+ "Edit(~/.ssh/**)",
+ "Edit(~/.aws/**)",
+ "Edit(~/.kube/**)"
+ ]
}
}
```
+Write access is inherently restricted to CWD by the sandbox. To block reads to sensitive directories, use permission deny rules as shown above.
+
**⚠️ Security Warning**: Overly broad write permissions enable privilege escalation:
- ❌ **Never allow writes to**: `$PATH` directories (`/usr/local/bin`), shell configs (`~/.bashrc`, `~/.zshrc`), system dirs (`/etc`)
@@ -223,7 +222,7 @@ Customize via `settings.json`:
### Proxy Architecture
-All network connections from sandboxed commands are routed through a SOCKS5 proxy running **outside** the sandbox:
+All network connections from sandboxed commands are routed through a SOCKS5 proxy running **outside** the sandbox. The proxy restricts which domains processes can connect to, but **does not inspect the content of traffic** passing through it (privacy note: no deep packet inspection).
```
┌──────────────────────────────────────────────────────────┐
@@ -311,6 +310,8 @@ For advanced use cases (HTTPS inspection, enterprise proxies):
**⚠️ Important**: Auto-allow mode is **independent** of permission mode (default/auto-accept/plan). Even in "default" mode, sandboxed bash commands run without prompts.
+**Built-in blocklist**: Even in auto-allow mode, commands like `curl` and `wget` are blocked by default to prevent arbitrary web content fetching.
+
**When to use**: Daily development, autonomous refactors, CI/CD pipelines
### Regular Permissions Mode
@@ -459,8 +460,8 @@ Excluded commands always run outside sandbox (with normal permission prompts).
**Mitigation**:
-- ✅ **Restrict writes to project directories only**
-- ✅ **Audit `allowedWritePaths` carefully**
+- ✅ **Restrict writes to project directories only** (sandbox default)
+- ✅ **Use permission deny rules to block sensitive reads**
- ✅ **Monitor sandbox violation logs**
### Linux: Nested Sandbox Weakness
@@ -567,22 +568,11 @@ flowchart TD
### Strict Security (Denylist Mode)
```json
+// settings.json — sandbox settings
{
"sandbox": {
"autoAllowMode": true,
"allowUnsandboxedCommands": false,
- "filesystem": {
- "allowedWritePaths": [
- "/Users/you/projects/my-app",
- "/tmp"
- ],
- "deniedReadPaths": [
- "/Users/you/.ssh",
- "/Users/you/.aws",
- "/Users/you/.kube",
- "/Users/you/.gnupg"
- ]
- },
"network": {
"policy": "deny",
"allowedDomains": [
@@ -594,6 +584,13 @@ flowchart TD
]
},
"excludedCommands": []
+ },
+ "permissions": {
+ "deny": [
+ "Read(~/.ssh/**)", "Read(~/.aws/**)",
+ "Read(~/.kube/**)", "Read(~/.gnupg/**)",
+ "Edit(~/.ssh/**)", "Edit(~/.aws/**)"
+ ]
}
}
```
@@ -605,15 +602,6 @@ flowchart TD
"sandbox": {
"autoAllowMode": true,
"allowUnsandboxedCommands": true,
- "filesystem": {
- "allowedWritePaths": [
- "${CWD}"
- ],
- "deniedReadPaths": [
- "${HOME}/.ssh",
- "${HOME}/.aws"
- ]
- },
"network": {
"policy": "allow",
"blockedDomains": [
@@ -621,6 +609,12 @@ flowchart TD
]
},
"excludedCommands": ["docker", "kubectl"]
+ },
+ "permissions": {
+ "deny": [
+ "Read(~/.ssh/**)", "Read(~/.aws/**)",
+ "Edit(~/.ssh/**)", "Edit(~/.aws/**)"
+ ]
}
}
```
@@ -632,13 +626,6 @@ flowchart TD
"sandbox": {
"autoAllowMode": true,
"allowUnsandboxedCommands": true,
- "filesystem": {
- "allowedWritePaths": [
- "${CWD}",
- "/tmp",
- "${HOME}/.cache"
- ]
- },
"network": {
"policy": "allow"
},
@@ -653,7 +640,7 @@ flowchart TD
1. **Start restrictive, expand as needed** - Begin with denylist mode, whitelist domains/paths incrementally
2. **Monitor sandbox violations** - Review logs to understand Claude's access patterns
-3. **Audit `allowedWritePaths`** - Never allow writes to `$PATH` dirs, shell configs, or system directories
+3. **Audit permission deny rules** - Use Read/Edit deny rules to block access to sensitive directories (`~/.ssh`, `~/.aws`, `~/.kube`)
4. **Avoid broad CDN domains** - Whitelist specific subdomains (`my-app.pages.dev`) instead of `*.cloudflare.com`
5. **Disable escape hatch in production** - Set `allowUnsandboxedCommands: false` for CI/CD, untrusted environments
6. **Combine with IAM policies** - Use sandboxing **alongside** [permission settings](https://code.claude.com/docs/en/iam) for defense-in-depth
diff --git a/guide/security-hardening.md b/guide/security-hardening.md
index 96d5c66..7e76441 100644
--- a/guide/security-hardening.md
+++ b/guide/security-hardening.md
@@ -39,7 +39,7 @@ Model Context Protocol (MCP) servers extend Claude Code's capabilities but intro
┌─────────────────────────────────────────────────────────────┐
│ 1. Attacker publishes benign MCP "code-formatter" │
│ ↓ │
-│ 2. User adds to ~/.claude/mcp.json, approves once │
+│ 2. User adds to ~/.claude.json, approves once │
│ ↓ │
│ 3. MCP works normally for 2 weeks (builds trust) │
│ ↓ │
@@ -225,6 +225,18 @@ Because `permissions.deny` alone cannot guarantee complete protection:
> **Bottom line**: `permissions.deny` is necessary but not sufficient. Treat it as one layer in a defense-in-depth strategy, not a complete solution.
+#### Built-in Permission Safeguards
+
+Beyond explicit deny rules, Claude Code has several built-in protections:
+
+| Safeguard | Behavior |
+|-----------|----------|
+| **Command blocklist** | `curl` and `wget` are blocked by default in the sandbox to prevent arbitrary web content fetching |
+| **Fail-closed matching** | Any permission rule that doesn't match defaults to requiring manual approval (deny by default) |
+| **Command injection detection** | Suspicious bash commands require manual approval even if previously allowlisted |
+
+These protections work automatically without configuration. The fail-closed design means a misconfigured permission rule fails safe rather than granting unintended access.
+
### 1.4 Repository Pre-Scan
Before opening untrusted repositories, scan for injection vectors:
@@ -497,7 +509,7 @@ If you suspect an MCP server has been compromised:
1. **Disable immediately**
```bash
# Remove from config
- jq 'del(.mcpServers.)' ~/.claude/mcp.json > tmp && mv tmp ~/.claude/mcp.json
+ jq 'del(.mcpServers.)' ~/.claude.json > tmp && mv tmp ~/.claude.json
# Or edit manually and restart Claude
```
@@ -505,8 +517,8 @@ If you suspect an MCP server has been compromised:
2. **Verify config integrity**
```bash
# Check for unauthorized changes
- sha256sum ~/.claude/mcp.json
- diff ~/.claude/mcp.json ~/.claude/mcp.json.backup
+ sha256sum ~/.claude.json
+ diff ~/.claude.json ~/.claude.json.backup
# Check project-level config too
cat .mcp.json 2>/dev/null
@@ -519,7 +531,7 @@ If you suspect an MCP server has been compromised:
4. **Restore from known-good backup**
```bash
- cp ~/.claude/mcp.json.backup ~/.claude/mcp.json
+ cp ~/.claude.json.backup ~/.claude.json
```
### 3.3 Automated Security Audit
@@ -696,7 +708,7 @@ exit 0
gitleaks detect --source . --verbose
# Check MCP config
-cat ~/.claude/mcp.json | jq '.mcpServers | keys'
+cat ~/.claude.json | jq '.mcpServers | keys'
# Verify hook installation
ls -la ~/.claude/hooks/
@@ -847,7 +859,7 @@ Local terminal ──HTTPS outbound──► Anthropic relay ──► Mobile/Br
**Security properties:**
- Zero inbound ports (reduces attack surface vs SSH tunnels or ngrok)
- HTTPS only (encrypted in transit)
-- Session URL = short-lived authentication token
+- Multiple short-lived, narrowly scoped credentials (each limited to a specific purpose, expiring independently)
- Execution stays 100% local
### Threat Model
diff --git a/guide/ultimate-guide.md b/guide/ultimate-guide.md
index 5bc15fe..0f48b2c 100644
--- a/guide/ultimate-guide.md
+++ b/guide/ultimate-guide.md
@@ -817,7 +817,7 @@ Claude: [Resumes with Serena's persistent project understanding]
## 1.4 Permission Modes
-Claude Code has three permission modes that control how much autonomy Claude has:
+Claude Code has five permission modes that control how much autonomy Claude has:
### Default Mode
@@ -828,13 +828,13 @@ Claude asks permission before:
This is the safest mode for learning.
-### Auto-accept Mode
+### Auto-accept Mode (`acceptEdits`)
```
You: Turn on auto-accept for the rest of this session
```
-Claude will execute changes without asking. Use when you trust the operation and want speed.
+Claude auto-approves file edits but still asks for shell commands. Use when you trust the edits and want speed.
⚠️ **Warning**: Only use auto-accept for well-defined, reversible operations.
@@ -844,13 +844,25 @@ Claude will execute changes without asking. Use when you trust the operation and
/plan
```
-Claude can only read and analyze - no modifications allowed. Perfect for:
+Claude can only read and analyze, no modifications allowed. Perfect for:
- Understanding unfamiliar code
- Exploring architectural options
- Safe investigation before changes
Exit with `/execute` when ready to make changes.
+### Don't Ask Mode (`dontAsk`)
+
+Auto-denies tools unless pre-approved via `/permissions` or `permissions.allow` rules. Claude never interrupts with permission prompts: if a tool isn't explicitly allowed, it's silently denied.
+
+Use for restrictive workflows where you want tight control over which tools run, without interactive confirmation.
+
+### Bypass Permissions Mode (`bypassPermissions`)
+
+Auto-approves everything, including shell commands. No permission prompts at all.
+
+⚠️ **Warning**: Only use in sandboxed CI/CD environments. Requires `--dangerously-skip-permissions` to enable from CLI. Never use on production systems or with untrusted code.
+
## 1.5 Productivity Checklist
You're ready for Day 2 when you can:
@@ -1461,7 +1473,7 @@ Add to `~/.claude/settings.json`:
}
```
-This displays: `Model: Sonnet 4.5 | Ctx: 0 | ⎇ main | (+0,-0) | Cost: $0.27 | Session: 0m | Ctx(u): 0.0%`
+This displays: `Model: Sonnet 4.6 | Ctx: 0 | ⎇ main | (+0,-0) | Cost: $0.27 | Session: 0m | Ctx(u): 0.0%`
**Option 2: Custom script**
@@ -1775,7 +1787,7 @@ Claude Code isn't free - you're using API credits. Understanding costs helps opt
#### Pricing Model (as of February 2026)
-Claude Code uses **Claude Sonnet 4.6** by default (as of Feb 2026):
+The default model depends on your subscription: **Max/Team Premium** subscribers get **Opus 4.6** by default, while **Pro/Team Standard** subscribers get **Sonnet 4.6**. If Opus usage hits the plan threshold, it auto-falls back to Sonnet.
| Model | Input (per 1M tokens) | Output (per 1M tokens) | Context Window | Notes |
|-------|----------------------|------------------------|----------------|-------|
@@ -2426,6 +2438,21 @@ Claude: [Executes the plan]
**Result**: 76% fewer tokens with better results because the plan is validated before execution.
+### Model Aliases
+
+Claude Code supports six model aliases via `/model` (each always resolves to the latest version):
+
+| Alias | Resolves To | Use Case |
+|-------|-------------|----------|
+| `default` | Latest model for your plan tier | Standard usage |
+| `sonnet` | Claude Sonnet 4.6 | Fast, cost-efficient |
+| `opus` | Claude Opus 4.6 | Deep reasoning |
+| `haiku` | Claude Haiku 4.5 | Budget, high-volume |
+| `sonnet[1m]` | Sonnet with 1M context | Large codebases |
+| `opusplan` | Opus (plan) + Sonnet (act) | Hybrid intelligence |
+
+Model can also be set via `claude --model `, `ANTHROPIC_MODEL` env var, or `"model"` in settings.json. Priority: `/model` > `--model` flag > `ANTHROPIC_MODEL` > settings.json.
+
### OpusPlan Mode
**Concept**: Use Opus for planning (superior reasoning) and Sonnet for implementation (cost-efficient).
@@ -4700,7 +4727,7 @@ ln -s ~/.claude/skills ./skills
# 3. Copy settings template (without secrets)
cp ~/.claude/settings.json ./settings.template.json
-# Manually replace secrets with ${env:VAR_NAME} placeholders
+# Manually replace secrets with ${VAR_NAME} placeholders
# 4. .gitignore for secrets
cat > .gitignore << EOF
@@ -4817,7 +4844,7 @@ ln -s ~/Dropbox/claude-mcp/settings.json ~/.claude/settings.json
- Session history (may contain sensitive code)
**Always commit these**:
-- Template files with `${env:VAR_NAME}` placeholders
+- Template files with `${VAR_NAME}` placeholders
- `.gitignore` to prevent secret leaks
- Public agents/hooks/skills (if safe to share)
@@ -4843,7 +4870,7 @@ ln -sf ~/.claude/commands ./commands
# Restore settings (fill in secrets manually or via .env)
cp settings.template.json ~/.claude/settings.json
-# Edit and replace ${env:VAR_NAME} with actual values
+# Edit and replace ${VAR_NAME} with actual values
```
**From tarball backup**:
@@ -4960,24 +4987,24 @@ Personal permission overrides (gitignored):
### allowedTools Configuration (Alternative)
-For granular control, use `~/.claude.json`:
+For granular control, use `~/.claude/settings.json`:
```json
{
"allowedTools": [
- "Read(*)",
- "Grep(*)",
- "Glob(*)",
- "WebFetch(*)",
+ "Read",
+ "Grep",
+ "Glob",
+ "WebFetch",
"TodoRead",
"TodoWrite",
- "Task(*)",
- "Bash(git status:*)",
- "Bash(git diff:*)",
- "Bash(git log:*)",
- "Bash(pnpm typecheck:*)",
- "Bash(pnpm lint:*)",
- "Bash(pnpm test:*)"
+ "Task",
+ "Bash(git status *)",
+ "Bash(git diff *)",
+ "Bash(git log *)",
+ "Bash(pnpm typecheck *)",
+ "Bash(pnpm lint *)",
+ "Bash(pnpm test *)"
]
}
```
@@ -4985,17 +5012,17 @@ For granular control, use `~/.claude.json`:
**Pattern Logic**:
| Pattern | Meaning | Example |
|---------|---------|---------|
-| `Read(*)` | All reads | Any file |
-| `Bash(git status:*)` | Specific command | `git status` allowed |
-| `Bash(pnpm *:*)` | Command prefix | `pnpm test`, `pnpm build` |
-| `Edit(*)` | All edits | ⚠️ Dangerous |
+| `Read` | All reads | Any file |
+| `Bash(git status *)` | Specific command | `git status` allowed |
+| `Bash(pnpm *)` | Command prefix | `pnpm test`, `pnpm build` |
+| `Edit` | All edits | ⚠️ Dangerous |
**Progressive Permission Levels**:
**Level 1 - Beginner (very restrictive)**:
```json
{
- "allowedTools": ["Read(*)", "Grep(*)", "Glob(*)"]
+ "allowedTools": ["Read", "Grep", "Glob"]
}
```
@@ -5003,8 +5030,8 @@ For granular control, use `~/.claude.json`:
```json
{
"allowedTools": [
- "Read(*)", "Grep(*)", "Glob(*)",
- "Bash(git:*)", "Bash(pnpm:*)",
+ "Read", "Grep", "Glob",
+ "Bash(git *)", "Bash(pnpm *)",
"TodoRead", "TodoWrite"
]
}
@@ -5014,9 +5041,9 @@ For granular control, use `~/.claude.json`:
```json
{
"allowedTools": [
- "Read(*)", "Grep(*)", "Glob(*)", "WebFetch(*)",
- "Edit(*)", "Write(*)",
- "Bash(git:*)", "Bash(pnpm:*)", "Bash(npm:*)",
+ "Read", "Grep", "Glob", "WebFetch",
+ "Edit", "Write",
+ "Bash(git *)", "Bash(pnpm *)", "Bash(npm *)",
"Task(*)", "TodoRead", "TodoWrite"
]
}
@@ -7915,15 +7942,17 @@ Hooks are scripts that run automatically when specific events occur.
| `Notification` | Claude sends notification | Sound alerts |
| `SessionStart` | Session begins | Initialization |
| `SessionEnd` | Session ends | Cleanup |
-| `Stop` | User interrupts | Graceful shutdown |
-| `Setup` | Claude Code starts | Initialization (v2.1.10+) |
+| `Stop` | Claude finishes responding | Post-response actions |
| `PermissionRequest` | Permission dialog appears | Custom approval logic |
+| `SubagentStart` | Sub-agent starts | Subagent initialization (v2.1.32+) |
| `SubagentStop` | Sub-agent completes | Subagent cleanup |
| `TeammateIdle` | Agent team member goes idle | Team coordination (v2.1.32+) |
| `TaskCompleted` | Task marked as completed | Workflow triggers (v2.1.32+) |
| `WorktreeCreate` | Agent worktree created | Set up DB branch, install deps (v2.1.50+) |
| `WorktreeRemove` | Agent worktree torn down | Clean up DB branch, temp credentials (v2.1.50+) |
| `ConfigChange` | Config file changes during session | Enterprise audit, block unauthorized changes (v2.1.49+) |
+| `PreCompact` | Before context compaction | Save state before compaction (v2.1.50+) |
+| `PostToolUseFailure` | After a tool fails | Error logging, recovery actions |
> **`Stop` and `SubagentStop` — `last_assistant_message` field (v2.1.47+)**: These events now include a `last_assistant_message` field in their JSON input, giving direct access to Claude's final response without parsing transcript files. Useful for orchestration pipelines that need to inspect or log the last output.
>
@@ -8102,9 +8131,16 @@ gh pr create --title "..." --body "..."
| Field | Description |
|-------|-------------|
| `matcher` | Regex pattern for which tools trigger hook |
-| `type` | Always `"command"` |
-| `command` | Path to hook script |
-| `timeout` | Max execution time (ms) |
+| `type` | Hook type: `"command"`, `"prompt"`, or `"agent"` |
+| `command` | Shell command to run (for `command` type) |
+| `prompt` | Prompt text for LLM evaluation (for `prompt`/`agent` types) |
+| `timeout` | Max execution time in seconds (default: 600s command, 30s prompt, 60s agent) |
+
+**Hook types:**
+
+- **`command`**: Runs a shell command. Receives JSON on stdin, returns JSON on stdout. Most common type.
+- **`prompt`**: Sends prompt + hook input to a Claude model (Haiku by default) for single-turn evaluation. Returns `{ok: true/false, reason: "..."}`. Configure model via `model` field.
+- **`agent`**: Spawns a subagent with tool access (Read, Grep, Glob, etc.) for multi-turn verification. Returns same `{ok: true/false}` format. Up to 50 tool-use turns.
### Hook Input (stdin JSON)
@@ -10464,7 +10500,7 @@ Beyond the official servers listed above, the MCP ecosystem includes **validated
# Installation
npm install @microsoft/playwright-mcp
-# Configuration (~/.claude/mcp.json)
+# Configuration (~/.claude.json or .mcp.json)
{
"mcpServers": {
"playwright": {
@@ -10485,23 +10521,25 @@ npm install @microsoft/playwright-mcp
## 8.3 Configuration
-### mcp.json Location
+### MCP Configuration Location
```
-~/.claude/mcp.json # Global MCP configuration
-/project/.claude/mcp.json # Project-specific (overrides)
+~/.claude.json # User-scope MCP config (field "mcpServers")
+.mcp.json # Project-scope (project root, shareable via VCS)
```
+> **Note**: Three scopes exist: `local` (default, private to you + current project, in `~/.claude.json`), `project` (shared via `.mcp.json` at project root), and `user` (cross-project, also in `~/.claude.json`). Use `claude mcp add --scope ` to target a specific scope.
+
### Example Configuration
```json
{
- "servers": {
+ "mcpServers": {
"serena": {
"command": "npx",
"args": ["serena-mcp"],
"env": {
- "PROJECT_PATH": "${workspaceFolder}"
+ "PROJECT_PATH": "${PROJECT_PATH}"
}
},
"context7": {
@@ -10512,7 +10550,7 @@ npm install @microsoft/playwright-mcp
"command": "npx",
"args": ["@modelcontextprotocol/server-postgres"],
"env": {
- "DATABASE_URL": "${env:DATABASE_URL}"
+ "DATABASE_URL": "${DATABASE_URL}"
}
}
}
@@ -10532,8 +10570,10 @@ npm install @microsoft/playwright-mcp
| Variable | Expands To |
|----------|------------|
-| `${workspaceFolder}` | Current project path |
-| `${env:VAR_NAME}` | Environment variable |
+| `${VAR}` | Environment variable value |
+| `${VAR:-default}` | Environment variable with fallback |
+
+> **Warning**: The syntax `${workspaceFolder}` and `${env:VAR_NAME}` are VS Code conventions, not Claude Code. Claude Code uses standard shell-style `${VAR}` and `${VAR:-default}` for environment variable expansion in MCP config.
### Managing Large MCP Server Sets
@@ -10542,10 +10582,10 @@ When you accumulate many MCP servers, enabling them all globally degrades Claude
**Pattern**: keep a minimal global config (2-3 core servers) and activate project-specific servers via per-project `.mcp.json`.
```
-# Global (~/.claude/mcp.json) → always loaded
+# User-scope (~/.claude.json "mcpServers") → always loaded
context7, sequential-thinking
-# Per-project (.claude/mcp.json) → only when needed
+# Project-scope (.mcp.json at project root) → only when needed
postgres # database project
playwright # frontend project
serena # large codebase
@@ -10622,7 +10662,7 @@ security find-generic-password -s "github-token" -w
```json
{
- "servers": {
+ "mcpServers": {
"github": {
"command": "bash",
"args": ["-c", "GITHUB_TOKEN=$(security find-generic-password -s 'github-token' -w) npx @github/mcp-server"],
@@ -10648,9 +10688,9 @@ secret-tool store --label="GitHub Token" service claude key github-token
export GITHUB_TOKEN=$(secret-tool lookup service claude key github-token)
npx @github/mcp-server
-# mcp.json
+# ~/.claude.json (or .mcp.json)
{
- "servers": {
+ "mcpServers": {
"github": {
"command": "~/.claude/scripts/mcp-github.sh",
"args": []
@@ -10701,19 +10741,19 @@ echo ".env" >> ~/.claude/.gitignore
```json
{
- "servers": {
+ "mcpServers": {
"github": {
"command": "npx",
"args": ["@github/mcp-server"],
"env": {
- "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
+ "GITHUB_TOKEN": "${GITHUB_TOKEN}"
}
},
"postgres": {
"command": "npx",
"args": ["@modelcontextprotocol/server-postgres"],
"env": {
- "DATABASE_URL": "${env:DATABASE_URL}"
+ "DATABASE_URL": "${DATABASE_URL}"
}
}
}
@@ -10739,14 +10779,14 @@ direnv allow ~/.claude
```bash
# Commit template (no secrets)
-cat > ~/.claude/mcp.json.template << EOF
+cat > ~/.claude/mcp-config.template.json << EOF
{
- "servers": {
+ "mcpServers": {
"github": {
"command": "npx",
"args": ["@github/mcp-server"],
"env": {
- "GITHUB_TOKEN": "\${env:GITHUB_TOKEN}"
+ "GITHUB_TOKEN": "\${GITHUB_TOKEN}"
}
}
}
@@ -10754,10 +10794,10 @@ cat > ~/.claude/mcp.json.template << EOF
EOF
# Generate actual config from template + .env
-envsubst < ~/.claude/mcp.json.template > ~/.claude/mcp.json
+envsubst < ~/.claude/mcp-config.template.json > ~/.claude.json
# .gitignore
-mcp.json # Generated, contains resolved secrets
+.claude.json # Generated, contains resolved secrets
.env # Never commit
```
@@ -10784,9 +10824,9 @@ vault kv put secret/claude/github token=ghp_your_token_here
export GITHUB_TOKEN=$(vault kv get -field=token secret/claude/github)
npx @github/mcp-server
-# mcp.json
+# ~/.claude.json (or .mcp.json)
{
- "servers": {
+ "mcpServers": {
"github": {
"command": "~/.claude/scripts/mcp-github-vault.sh",
"args": []
@@ -10841,8 +10881,8 @@ NEW_VALUE=$2
# 1. Update .env file
sed -i.bak "s|^${SECRET_NAME}=.*|${SECRET_NAME}=${NEW_VALUE}|" ~/.claude/.env
-# 2. Regenerate mcp.json from template
-envsubst < ~/.claude/mcp.json.template > ~/.claude/mcp.json
+# 2. Regenerate config from template
+envsubst < ~/.claude/mcp-config.template.json > ~/.claude.json
# 3. Restart MCP servers (if running)
pkill -f "mcp-server" || true
@@ -10868,7 +10908,7 @@ echo "⚠️ Restart Claude Code to apply changes"
# Fetch latest secrets from Vault, update .env, restart Claude
vault kv get -format=json secret/claude | jq -r '.data.data | to_entries[] | "\(.key)=\(.value)"' > ~/.claude/.env
-envsubst < ~/.claude/mcp.json.template > ~/.claude/mcp.json
+envsubst < ~/.claude/mcp-config.template.json > ~/.claude.json
echo "✅ Secrets rotated from Vault"
```
@@ -10940,7 +10980,7 @@ claude
| **Use OS keychain when possible** | Encrypted at rest, OS-level security |
| **Never commit .env to Git** | One leak = full compromise |
| **Commit .env.example template** | Team onboarding without secrets |
-| **Use ${env:VAR} in mcp.json** | Separation of config and secrets |
+| **Use ${VAR} in MCP config** | Separation of config and secrets |
| **Rotate secrets quarterly** | Limit blast radius of old leaks |
| **Audit .gitignore before push** | Prevent accidental exposure |
| **Least privilege credentials** | Read-only DB users, scoped API tokens |
@@ -11451,11 +11491,13 @@ MCP servers can dynamically change their tool offerings. A server might pass ini
```json
{
"permissions": {
- "disallowedTools": ["mcp__untrusted-server__execute", "mcp__untrusted-server__shell"]
+ "deny": ["mcp__untrusted-server__execute", "mcp__untrusted-server__shell"]
}
}
```
+> **Note**: `disallowedTools` is a root-level key or CLI flag (`--disallowedTools`), not nested under `permissions`. For settings.json, use `permissions.deny` to block tool patterns.
+
### Red Flags
Avoid MCP servers that:
@@ -11674,7 +11716,12 @@ The `effort` parameter significantly impacts how Claude uses tools:
- **Opus 4.5**: `effort` works **in parallel** with `budget_tokens`. Both parameters are supported and affect different aspects of the response.
- **Without thinking enabled**: `effort` still controls text generation and tool calls. It's not a thinking-only parameter.
-**CLI usage**: Same as before — Alt+T toggles thinking on/off globally. No per-request effort control in CLI (uses model's default `high`).
+**CLI usage**: Three methods to control effort level in Claude Code:
+1. **`/model` command** with left/right arrow keys to adjust the effort slider (`low`, `medium`, `high`)
+2. **`CLAUDE_CODE_EFFORT_LEVEL`** environment variable (set before launching Claude)
+3. **`effortLevel`** field in settings.json (persistent across sessions)
+
+Alt+T toggles thinking on/off globally (separate from effort level).
#### Controlling Thinking Mode
@@ -11682,7 +11729,9 @@ The `effort` parameter significantly impacts how Claude uses tools:
|--------|----------|----------|-------------|
| **Alt+T** (Option+T on macOS) | Toggle on/off | Toggle on/off | Current session |
| **/config** → Thinking mode | Enable/disable globally | Enable/disable globally | Across sessions |
-| **API `effort` parameter** | `low\|medium\|high` | `low\|medium\|high\|max` (`max` = 4.6 only) | Per request |
+| **`/model` slider** (left/right arrows) | `low\|medium\|high` | `low\|medium\|high` | Current session |
+| **`CLAUDE_CODE_EFFORT_LEVEL`** env var | `low\|medium\|high` | `low\|medium\|high` | Shell session |
+| **`effortLevel`** in settings.json | `low\|medium\|high` | `low\|medium\|high` | Permanent |
| **Ctrl+O** | View thinking blocks | View thinking blocks | Display only |
#### Cost Implications
@@ -16901,6 +16950,19 @@ This guide uses both llms.txt and CLAUDE.md:
**Result**: Agents can discover content via llms.txt, then consult CLAUDE.md for active context.
+#### Real-World: Anthropic's Official llms.txt
+
+Anthropic publie deux variantes LLM-optimized pour Claude Code :
+
+| Fichier | URL | Taille | Tokens (approx) | Use case |
+|---------|-----|--------|-----------------|----------|
+| `llms.txt` | `code.claude.com/docs/llms.txt` | ~65 pages | ~15-20K | Index rapide, découverte de sections |
+| `llms-full.txt` | `code.claude.com/docs/llms-full.txt` | ~98 KB | ~25-30K | Fact-checking, doc complète, source de vérité |
+
+**Pattern recommandé** : fetch `llms.txt` d'abord pour identifier la section pertinente, puis fetch la page spécifique (ou `llms-full.txt`) pour les détails. Évite de charger 98 KB quand seules 2 pages sont nécessaires.
+
+Ces URLs sont la source officielle à consulter en priorité quand un claim sur Claude Code semble incertain ou potentiellement obsolète.
+
#### Specification Resources
- **Official spec**: https://llmstxt.org/
@@ -19155,24 +19217,29 @@ Complete reference for all Claude Code command-line flags.
| `--json-schema` | JSON Schema for structured output validation | `claude --json-schema '{"type":"object","properties":{"name":{"type":"string"}}}' ` |
| `--input-format` | Input format (text/stream-json) | `claude --input-format stream-json` |
| `--replay-user-messages` | Re-emit user messages in stream | `claude --replay-user-messages` |
-| `--allowedTools` | Whitelist specific tools | `claude --allowedTools "Edit,Read,Bash(git:*)"` |
+| `--allowedTools` | Whitelist specific tools | `claude --allowedTools "Edit,Read,Bash(git *)"` |
| `--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` |
+| `--permission-mode` | Permission mode (default/acceptEdits/plan/dontAsk/bypassPermissions) | `claude --permission-mode plan` |
| `--model` | Model selection | `claude --model sonnet` |
| `--max-budget-usd` | Maximum API spend limit (with `--print` only) | `claude -p "analyze" --max-budget-usd 5.00` |
+| `--tools` | Enable specific tools for the session | `claude --tools "Edit,Read,Bash"` |
+| `--agent` | Specify agent for session | `claude --agent security-reviewer` |
+| `--system-prompt` | Override system prompt entirely | `claude --system-prompt "You are a reviewer"` |
| `--add-dir` | Allow tool access to additional directories | `claude --add-dir ../shared ../utils` |
-| `--continue` | Continue last conversation | `claude --continue` |
-| `-r, --resume` | Resume session by ID | `claude --resume abc123` |
+| `--worktree` / `-w` | Run in isolated git worktree | `claude --worktree` |
+| `--continue` | Continue last conversation (in current directory) | `claude --continue` |
+| `-r, --resume` | Resume session by ID or show picker | `claude --resume abc123` |
| `--dangerously-skip-permissions` | Skip all permission prompts | `claude --dangerously-skip-permissions` |
-| `--debug` | Enable debug mode | `claude --debug` |
+| `--debug` | Enable debug mode (supports categories: `"api,mcp"`) | `claude --debug` |
| `--verbose` | Verbose output | `claude --verbose` |
-| `--mcp-debug` | Debug MCP server connections | `claude --mcp-debug` |
| `--version` | Show version | `claude --version` |
+> **Note**: This table covers the most commonly used flags. The full CLI reference (~45 flags) is available at [docs.anthropic.com](https://docs.anthropic.com/en/docs/claude-code/cli-reference).
+
**Common Combinations:**
```bash
@@ -19220,7 +19287,7 @@ Use this symptom-based guide for rapid issue identification and resolution:
| "Rate limit exceeded" | API throttling from frequent requests | Wait 2 minutes, use `--model haiku` for simple tasks, or use [cc-copilot-bridge](https://github.com/FlorianBruniaux/cc-copilot-bridge) for flat-rate access | Batch operations, use `/compact`, consider Copilot Pro+ |
| Claude forgets instructions | Context overflow, CLAUDE.md lost | Create checkpoint, `/clear`, reload CLAUDE.md | Keep CLAUDE.md concise (<500 lines) |
| MCP server not connecting | Server crashed or config error | `claude mcp list`, check paths, restart server | Test servers after config changes |
-| Permission prompts every time | Tool not in `allowedTools` | Add pattern to `settings.json` allowedTools | Use wildcards: `Bash(git:*)` |
+| Permission prompts every time | Tool not in `allowedTools` | Add pattern to `settings.json` allowedTools | Use wildcards: `Bash(git *)` |
| Changes not taking effect | Cached configuration | Restart Claude Code session | Use `/exit` before config changes |
| Session won't resume | Corrupted session file | Start fresh with `/clear` | Exit cleanly with `/exit` or `Ctrl+D` |
@@ -20571,7 +20638,7 @@ Quick reference for where Claude Code stores files and configuration.
| **Claude data directory** | `C:\Users\\.claude\` |
| **Claude config file** | `C:\Users\\.claude.json` |
| **Log files** | `%APPDATA%\Claude\logs\` |
-| **MCP config** | `C:\Users\\.claude\mcp.json` |
+| **MCP config** | `C:\Users\\.claude.json` (`mcpServers` field) |
| **Session data** | `C:\Users\\.claude\local\` |
| **Downloads/cache** | `C:\Users\\.claude\downloads\` |
@@ -20596,7 +20663,7 @@ Get-Content "$env:APPDATA\Claude\logs\mcp*.log" -Wait -Tail 50
| **Claude data directory** | `~/.claude/` |
| **Claude config file** | `~/.claude.json` |
| **Log files** | `~/Library/Logs/Claude/` |
-| **MCP config** | `~/.claude/mcp.json` |
+| **MCP config** | `~/.claude.json` (`mcpServers` field) |
| **Session data** | `~/.claude/local/` |
| **Downloads/cache** | `~/.claude/downloads/` |
@@ -20623,7 +20690,7 @@ tail -f ~/Library/Logs/Claude/mcp*.log
| **Claude data directory** | `~/.claude/` |
| **Claude config file** | `~/.claude.json` |
| **Log files** | `~/.local/share/claude/logs/` or `~/.cache/claude/logs/` |
-| **MCP config** | `~/.claude/mcp.json` |
+| **MCP config** | `~/.claude.json` (`mcpServers` field) |
| **Session data** | `~/.claude/local/` |
| **Downloads/cache** | `~/.claude/downloads/` |
diff --git a/guide/visual-reference.md b/guide/visual-reference.md
index 7d7efaf..fe95a48 100644
--- a/guide/visual-reference.md
+++ b/guide/visual-reference.md
@@ -309,7 +309,7 @@ How a malicious MCP server can exploit the one-time approval model:
┌─────────────────────────────────────────────────────────────┐
│ 1. Attacker publishes benign MCP "code-formatter" │
│ ↓ │
-│ 2. User adds to ~/.claude/mcp.json, approves once │
+│ 2. User adds to ~/.claude.json, approves once │
│ ↓ │
│ 3. MCP works normally for 2 weeks (builds trust) │
│ ↓ │
diff --git a/machine-readable/llms.txt b/machine-readable/llms.txt
index 1f611f0..edc3042 100644
--- a/machine-readable/llms.txt
+++ b/machine-readable/llms.txt
@@ -126,6 +126,8 @@ claude-code-ultimate-guide/
## Related Resources
- Official: https://docs.anthropic.com/en/docs/claude-code
+- Official llms.txt (index): https://code.claude.com/docs/llms.txt
+- Official llms-full.txt (complete): https://code.claude.com/docs/llms-full.txt
- DeepWiki: https://deepwiki.com/FlorianBruniaux/claude-code-ultimate-guide
- Inspiration: https://claudelog.com/
- 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)
diff --git a/machine-readable/reference.yaml b/machine-readable/reference.yaml
index f6811f8..558a6fb 100644
--- a/machine-readable/reference.yaml
+++ b/machine-readable/reference.yaml
@@ -20,18 +20,18 @@ deep_dive:
total_diagrams: 40
# AI-Assisted Development Workflows (from MetalBear/arXiv research)
exploration_workflow: "guide/workflows/exploration-workflow.md"
- script_generation: "guide/workflows/iterative-refinement.md:192"
- anti_anchoring_prompts: "examples/semantic-anchors/anchor-catalog.md:240"
- session_limits: "guide/architecture.md:272"
+ script_generation: "guide/workflows/iterative-refinement.md:200"
+ anti_anchoring_prompts: "examples/semantic-anchors/anchor-catalog.md:248"
+ session_limits: "guide/architecture.md:442"
claudemd_sizing: 3054
- scope_success_rates: "guide/adoption-approaches.md:20"
+ scope_success_rates: "guide/adoption-approaches.md:26"
# Claude Code Releases
claude_code_releases: "guide/claude-code-releases.md"
claude_code_releases_yaml: "machine-readable/claude-code-releases.yaml"
# Code Review Automation (Pat Cullen, Jan 2026)
review_pr_advanced: "examples/commands/review-pr.md:81"
- review_anti_hallucination: "examples/agents/code-reviewer.md:75"
- review_auto_fix_loop: "guide/workflows/iterative-refinement.md:347"
+ review_anti_hallucination: "examples/agents/code-reviewer.md:77"
+ review_auto_fix_loop: "guide/workflows/iterative-refinement.md:353"
# Review Plan Command (Garry Tan-inspired, Feb 2026)
review_plan_command: "examples/commands/review-plan.md"
# GitHub Actions: Prompt-Based Code Review (Feb 2026)
@@ -59,39 +59,39 @@ deep_dive:
team_ai_instructions_threshold: "Team 5+ devs with multiple AI tools"
# Known Issues & Critical Bugs (verified community reports)
known_issues: "guide/known-issues.md"
- known_issues_github_bug: "guide/known-issues.md:16" # GitHub auto-creation bug
- known_issues_token_consumption: "guide/known-issues.md:136" # Excessive token usage
- known_issues_model_quality_aug2025: "guide/known-issues.md:231" # Resolved: Aug 2025 degradation
+ known_issues_github_bug: "guide/known-issues.md:7" # GitHub auto-creation bug
+ known_issues_token_consumption: "guide/known-issues.md:105" # Excessive token usage
+ known_issues_model_quality_aug2025: "guide/known-issues.md:197" # Resolved: Aug 2025 degradation
# Template Installation
install_templates_script: "scripts/install-templates.sh"
# Session management
- session_search: "guide/observability.md:29"
+ session_search: "guide/observability.md:38"
session_search_script: "examples/scripts/session-search.sh"
cc_sessions_script: "examples/scripts/cc-sessions.py"
- session_resume_limitations: "guide/observability.md:117"
- session_cross_folder_migration: "guide/observability.md:117"
- session_migration_manual: "guide/observability.md:135"
- session_migration_risks: "guide/observability.md:157"
- session_migration_community_tool: "guide/observability.md:175"
+ session_resume_limitations: "guide/observability.md:126"
+ session_cross_folder_migration: "guide/observability.md:126"
+ session_migration_manual: "guide/observability.md:126"
+ session_migration_risks: "guide/observability.md:126"
+ session_migration_community_tool: "guide/observability.md:52"
session_migration_issue: "https://github.com/anthropics/claude-code/issues/1516"
session_migration_weller_skill: "https://github.com/jimweller/dotfiles/tree/main/dotfiles/claude-code/skills/claude-migrate-session"
# Activity monitoring
activity_monitoring: "guide/observability.md:467" # Tool call audit via JSONL
- activity_monitoring_queries: "guide/observability.md:492" # jq queries for audit
- activity_monitoring_alerts: "guide/observability.md:506" # Sensitive pattern detection
+ activity_monitoring_queries: "guide/observability.md:467" # jq queries for audit
+ activity_monitoring_alerts: "guide/observability.md:467" # Sensitive pattern detection
external_monitoring_tools: "guide/observability.md:527" # ccusage, claude-code-otel, Akto, MLflow, ccboard
- proxying_claude_code: "guide/observability.md:581" # Proxyman, mitmproxy, ANTHROPIC_API_URL
+ proxying_claude_code: "guide/observability.md:699" # Proxyman, mitmproxy, ANTHROPIC_API_URL
ccboard_activity_plan: "docs/resource-evaluations/ccboard-activity-module-plan.md"
# Cost optimization - Local execution bridge
bridge_script: "examples/scripts/bridge.py"
bridge_schema: "examples/scripts/bridge-plan-schema.json"
- bridge_guide: "guide/ultimate-guide.md:14079"
+ bridge_guide: "guide/ultimate-guide.md:20003"
# Cost optimization - RTK (Rust Token Killer)
rtk_upstream: "https://github.com/rtk-ai/rtk"
rtk_website: "https://www.rtk-ai.app/"
rtk_evaluation: "docs/resource-evaluations/rtk-evaluation.md"
- rtk_guide: "guide/ultimate-guide.md:13355"
- rtk_third_party: "guide/third-party-tools.md:86"
+ rtk_guide: "guide/ultimate-guide.md:14553"
+ rtk_third_party: "guide/third-party-tools.md:7"
rtk_claude_md: "examples/claude-md/rtk-optimized.md"
rtk_skill: "examples/skills/rtk-optimizer/SKILL.md"
rtk_hook: "examples/hooks/bash/rtk-auto-wrapper.sh"
@@ -100,7 +100,7 @@ deep_dive:
rtk_score: "5/5"
rtk_installation: "cargo install rtk or brew install rtk-ai/tap/rtk"
# Google Antigravity (Agent-First IDE)
- antigravity_guide: "guide/ai-ecosystem.md:1367"
+ antigravity_guide: "guide/ai-ecosystem.md:1366"
antigravity_evaluation: "docs/resource-evaluations/google-antigravity-evaluation.md"
antigravity_proxy: "https://www.npmjs.com/package/antigravity-claude-proxy"
antigravity_codelabs: "https://codelabs.developers.google.com/getting-started-google-antigravity"
@@ -125,47 +125,59 @@ deep_dive:
talk_pipeline_patterns: "skill chaining + file-based state + tool permission scoping + human-in-the-loop gate + AI-to-AI handoff (Claude → Kimi)"
talk_pipeline_checkpoint: "Stage 4 CHECKPOINT: user selects angle + title before script starts"
talk_pipeline_kimi: "kimi.com (free) — copy-paste Stage 5 prompt for AI slide generation"
+ # reMarkable 2 + AI (guide/remarkable-ai.md)
+ remarkable_ai_guide: "guide/remarkable-ai.md"
+ remarkable_mcp_server: "guide/remarkable-ai.md#1-remarkable-mcp--le-game-changer"
+ remarkable_mcp_repo: "https://github.com/SamMorrowDrums/remarkable-mcp"
+ remarkable_ghostwriter: "guide/remarkable-ai.md#2-ghostwriter--interface-vision-llm"
+ remarkable_obsidian_sync: "guide/remarkable-ai.md#3-sync-remarkable--obsidian"
+ remarkable_ocr_pipeline: "guide/remarkable-ai.md#4-ocr--ai-pipeline-custom"
+ remarkable_ssh_tools: "guide/remarkable-ai.md#5-accès-ssh-et-outils-communautaires"
+ remarkable_meeting_workflow: "guide/remarkable-ai.md#10-meeting-notes--ai-summary"
+ remarkable_workflows_to_build: "guide/remarkable-ai.md#14-workflows-ai-augmentés-à-construire"
+ remarkable_getting_started: "guide/remarkable-ai.md#15-par-où-commencer"
+ remarkable_community: "https://github.com/reHackable/awesome-reMarkable"
# Whitepapers (FR + EN) — 9 focused whitepapers on Claude Code
whitepapers_url: "https://www.florian.bruniaux.com/guides"
whitepapers_fr: "whitepapers/fr/" # FR sources (Quarto .qmd)
whitepapers_en: "whitepapers/en/" # EN sources (Quarto .qmd)
whitepapers_topics: "foundations, prompting, customization, security, architecture, team, privacy, reference, agent-teams"
# Learning with AI (guide/learning-with-ai.md)
- learning_quick_check: "guide/learning-with-ai.md:31"
- learning_uval_protocol: "guide/learning-with-ai.md:127"
- learning_claude_config: "guide/learning-with-ai.md:353"
- learning_breaking_dependency: "guide/learning-with-ai.md:470"
- learning_embracing_ai: "guide/learning-with-ai.md:518"
- learning_30day_plan: "guide/learning-with-ai.md:710"
- learning_red_flags: "guide/learning-with-ai.md:770"
+ learning_quick_check: "guide/learning-with-ai.md:38"
+ learning_uval_protocol: "guide/learning-with-ai.md:218"
+ learning_claude_config: "guide/learning-with-ai.md:458"
+ learning_breaking_dependency: "guide/learning-with-ai.md:575"
+ learning_embracing_ai: "guide/learning-with-ai.md:623"
+ learning_30day_plan: "guide/learning-with-ai.md:815"
+ learning_red_flags: "guide/learning-with-ai.md:612"
# Productivity Research RCTs
productivity_rct_metr: "guide/learning-with-ai.md:925" # METR 2025: experienced devs 19% slower on large codebases despite perceiving 20% faster
productivity_rct_echoes: "guide/learning-with-ai.md:926" # Borg 2025: 30.7% faster (median), ~55.9% habitual users, no maintainability impact downstream
productivity_maintainability_empirical: "guide/learning-with-ai.md:926" # Empirical data on "AI code is unmaintainable" claim — blind RCT shows no significant difference
- trust_calibration_maintainability_nuance: "guide/ultimate-guide.md:1092" # Nuance: defect rates ≠ maintenance burden (Borg et al. 2025)
+ trust_calibration_maintainability_nuance: "guide/ultimate-guide.md:1097" # Nuance: defect rates ≠ maintenance burden (Borg et al. 2025)
learning_mode_template: "examples/claude-md/learning-mode.md"
learn_quiz_command: "examples/commands/learn/quiz.md"
learn_teach_command: "examples/commands/learn/teach.md"
learn_alternatives_command: "examples/commands/learn/alternatives.md"
learning_capture_hook: "examples/hooks/bash/learning-capture.sh"
# Anti-patterns
- vibe_coding_trap: "guide/learning-with-ai.md:81"
- vibe_coding_context_overload: 8746
+ vibe_coding_trap: "guide/learning-with-ai.md:87"
+ vibe_coding_context_overload: 13097
vibe_coding_context_overload_source: "Jens Rusitschka, 'Vibe Coding, Level 2' (Jan 2026)"
- vibe_coding_phased_strategy: 8760
+ vibe_coding_phased_strategy: 13097
# AI Traceability & Attribution (guide/ai-traceability.md) - Added 2026-01-24
ai_traceability_guide: "guide/ai-traceability.md"
- ai_traceability_why: "guide/ai-traceability.md:25"
- ai_traceability_disclosure_spectrum: "guide/ai-traceability.md:63"
- ai_traceability_co_authored_by: "guide/ai-traceability.md:89"
- ai_traceability_assisted_by: "guide/ai-traceability.md:109"
- ai_traceability_git_ai: "guide/ai-traceability.md:262"
- ai_traceability_llvm_policy: "guide/ai-traceability.md:169"
- ai_traceability_ghostty_policy: "guide/ai-traceability.md:203"
- ai_traceability_fedora_policy: "guide/ai-traceability.md:227"
- ai_traceability_promptpwnd: "guide/ai-traceability.md:342"
- ai_traceability_implementation: "guide/ai-traceability.md:392"
- ai_traceability_templates: "guide/ai-traceability.md:440"
+ ai_traceability_why: "guide/ai-traceability.md:29"
+ ai_traceability_disclosure_spectrum: "guide/ai-traceability.md:64"
+ ai_traceability_co_authored_by: "guide/ai-traceability.md:98"
+ ai_traceability_assisted_by: "guide/ai-traceability.md:120"
+ ai_traceability_git_ai: "guide/ai-traceability.md:170"
+ ai_traceability_llvm_policy: "guide/ai-traceability.md:201"
+ ai_traceability_ghostty_policy: "guide/ai-traceability.md:236"
+ ai_traceability_fedora_policy: "guide/ai-traceability.md:261"
+ ai_traceability_promptpwnd: "guide/ai-traceability.md:501"
+ ai_traceability_implementation: "guide/ai-traceability.md:566"
+ ai_traceability_templates: "guide/ai-traceability.md:648"
# AI Disclosure Templates
ai_disclosure_contributing: "examples/config/CONTRIBUTING-ai-disclosure.md"
ai_disclosure_pr_template: "examples/config/PULL_REQUEST_TEMPLATE-ai.md"
@@ -175,13 +187,13 @@ deep_dive:
tts_voice_catalog: "examples/integrations/agent-vibes/voice-catalog.md"
tts_troubleshooting: "examples/integrations/agent-vibes/troubleshooting.md"
tts_workflow: "guide/workflows/tts-setup.md"
- tts_ai_ecosystem: "guide/ai-ecosystem.md:507"
+ tts_ai_ecosystem: "guide/ai-ecosystem.md:1124"
tts_hook_example: "examples/hooks/bash/tts-selective.sh"
tts_claude_md_template: "examples/claude-md/tts-enabled.md"
# Sandbox Isolation for Coding Agents (guide/sandbox-isolation.md) - Added 2026-01-31
sandbox_isolation_guide: "guide/sandbox-isolation.md"
- sandbox_isolation_decision_tree: "guide/sandbox-isolation.md:40"
- sandbox_docker_sandboxes: "guide/sandbox-isolation.md:61"
+ sandbox_isolation_decision_tree: "guide/sandbox-isolation.md:7"
+ sandbox_docker_sandboxes: "guide/sandbox-isolation.md:67"
sandbox_docker_network: "guide/sandbox-isolation.md:121"
sandbox_docker_templates: "guide/sandbox-isolation.md:165"
sandbox_docker_docs: "https://docs.docker.com/ai/sandboxes/"
@@ -192,26 +204,26 @@ deep_dive:
sandbox_cloudflare_sdk: "https://developers.cloudflare.com/sandbox/tutorials/claude-code/"
sandbox_vercel: "https://vercel.com/docs/vercel-sandbox/"
sandbox_e2b: "https://e2b.dev"
- sandbox_native_cc: "guide/architecture.md:579"
+ sandbox_native_cc: "guide/architecture.md:606"
# Native Claude Code Sandbox (Official docs, v2.1.0+) - Added 2026-02-02
sandbox_native_guide: "guide/sandbox-native.md"
sandbox_native_why: "guide/sandbox-native.md:47" # Why Native Sandboxing
sandbox_native_os_primitives: "guide/sandbox-native.md:68" # Seatbelt vs bubblewrap
- sandbox_native_filesystem: "guide/sandbox-native.md:172" # Filesystem isolation
- sandbox_native_network: "guide/sandbox-native.md:216" # Network proxy architecture
- sandbox_native_modes: "guide/sandbox-native.md:296" # Auto-allow vs Regular
- sandbox_native_escape_hatch: "guide/sandbox-native.md:336" # dangerouslyDisableSandbox
- sandbox_native_security_limits: "guide/sandbox-native.md:391" # Domain fronting, Unix sockets
- sandbox_native_opensource: "guide/sandbox-native.md:476" # Open-source runtime
- sandbox_native_platforms: "guide/sandbox-native.md:500" # Platform support
- sandbox_native_decision_tree: "guide/sandbox-native.md:512" # Native vs Docker
- sandbox_native_config_examples: "guide/sandbox-native.md:559" # Configuration examples
- sandbox_native_best_practices: "guide/sandbox-native.md:646" # Best practices
- sandbox_native_troubleshooting: "guide/sandbox-native.md:659" # Troubleshooting
+ sandbox_native_filesystem: "guide/sandbox-native.md:178" # Filesystem isolation
+ sandbox_native_network: "guide/sandbox-native.md:221" # Network proxy architecture
+ sandbox_native_modes: "guide/sandbox-native.md:7" # Auto-allow vs Regular
+ sandbox_native_escape_hatch: "guide/sandbox-native.md:341" # dangerouslyDisableSandbox
+ sandbox_native_security_limits: "guide/sandbox-native.md:396" # Domain fronting, Unix sockets
+ sandbox_native_opensource: "guide/sandbox-native.md:481" # Open-source runtime
+ sandbox_native_platforms: "guide/sandbox-native.md:505" # Platform support
+ sandbox_native_decision_tree: "guide/sandbox-native.md:517" # Native vs Docker
+ sandbox_native_config_examples: "guide/sandbox-native.md:564" # Configuration examples
+ sandbox_native_best_practices: "guide/sandbox-native.md:637" # Best practices
+ sandbox_native_troubleshooting: "guide/sandbox-native.md:650" # Troubleshooting
sandbox_runtime_oss: "https://github.com/anthropic-experimental/sandbox-runtime"
sandbox_runtime_npm: "https://www.npmjs.com/package/@anthropic-ai/sandbox-runtime"
sandbox_official_docs: "https://code.claude.com/docs/en/sandboxing"
- sandbox_comparison_native_docker: "guide/sandbox-isolation.md:61" # Section 4 Native CC
+ sandbox_comparison_native_docker: "guide/sandbox-isolation.md:238" # Section 4 Native CC
sandbox_native_evaluation: "docs/resource-evaluations/native-sandbox-official-docs.md"
sandbox_native_score: "5/5"
# Templates (Added 2026-02-02)
@@ -220,19 +232,19 @@ deep_dive:
sandbox_validation_hook: "examples/hooks/bash/sandbox-validation.sh"
# Docker Sandboxes (existing)
sandbox_evaluation: "docs/resource-evaluations/docker-sandboxes-isolation.md"
- sandbox_safe_autonomy: "guide/sandbox-isolation.md:486" # Updated line number (was 320)
- sandbox_anti_patterns: "guide/sandbox-isolation.md:538" # Updated line number (was 372)
- sandbox_comparison_matrix: "guide/sandbox-isolation.md:469" # Updated line number (was 306)
+ sandbox_safe_autonomy: "guide/sandbox-isolation.md:496" # Safe Autonomy Workflows
+ sandbox_anti_patterns: "guide/sandbox-isolation.md:546" # Anti-Patterns
+ sandbox_comparison_matrix: "guide/sandbox-isolation.md:477" # Comparison Matrix
sandbox_score: "4/5"
# Third-Party Tools (guide/third-party-tools.md) - Added 2026-02-01
third_party_tools_guide: "guide/third-party-tools.md"
third_party_tools_cost_tracking: "guide/third-party-tools.md:42"
- third_party_tools_rtk: "guide/third-party-tools.md:86"
- third_party_tools_session_mgmt: "guide/third-party-tools.md:105"
- third_party_tools_config_mgmt: "guide/third-party-tools.md:132"
- third_party_tools_alternative_uis: "guide/third-party-tools.md:170"
- third_party_tools_known_gaps: "guide/third-party-tools.md:259"
- third_party_tools_recommendations: "guide/third-party-tools.md:274"
+ third_party_tools_rtk: "guide/third-party-tools.md:7"
+ third_party_tools_session_mgmt: "guide/third-party-tools.md:126"
+ third_party_tools_config_mgmt: "guide/third-party-tools.md:214"
+ third_party_tools_alternative_uis: "guide/third-party-tools.md:259"
+ third_party_tools_known_gaps: "guide/third-party-tools.md:375"
+ third_party_tools_recommendations: "guide/third-party-tools.md:391"
third_party_ccusage: "https://www.npmjs.com/package/ccusage"
third_party_ccusage_site: "https://ccusage.com"
third_party_ccburn: "https://github.com/JuanjoFuchs/ccburn"
@@ -243,29 +255,29 @@ deep_dive:
third_party_toad: "https://github.com/batrachianai/toad"
third_party_conductor: "https://docs.conductor.build"
# Configuration Management & Backup (Added 2026-02-02)
- config_management_guide: "guide/ultimate-guide.md:4085" # Section 3.29.0
- config_hierarchy: "guide/ultimate-guide.md:4095" # Global → Project → Local precedence
- config_git_strategy_project: "guide/ultimate-guide.md:4110" # What to commit in .claude/
- config_git_strategy_global: "guide/ultimate-guide.md:4133" # Version control ~/.claude/
- config_backup_strategies: "guide/ultimate-guide.md:4171" # Git, cloud sync, cron
- config_multi_machine_sync: "guide/ultimate-guide.md:4183" # Laptop + desktop workflows
- config_security_considerations: "guide/ultimate-guide.md:4219" # Never commit secrets
- config_disaster_recovery: "guide/ultimate-guide.md:4233" # Restore from backup
- config_community_solutions: "guide/ultimate-guide.md:4249" # brianlovin + Ratinaud
+ config_management_guide: "guide/ultimate-guide.md:4217" # Section 3.1 Memory Files
+ config_hierarchy: "guide/ultimate-guide.md:4336" # Global → Project → Local precedence
+ config_git_strategy_project: "guide/ultimate-guide.md:4634" # What Goes Where
+ config_git_strategy_global: "guide/ultimate-guide.md:4634" # Version control ~/.claude/
+ config_backup_strategies: "guide/ultimate-guide.md:4634" # Git, cloud sync, cron
+ config_multi_machine_sync: "guide/ultimate-guide.md:4634" # Laptop + desktop workflows
+ config_security_considerations: "guide/ultimate-guide.md:4419" # CLAUDE.md Injection warning
+ config_disaster_recovery: "guide/ultimate-guide.md:4634" # Restore from backup
+ config_community_solutions: "guide/ultimate-guide.md:4634" # brianlovin + Ratinaud
config_github_issue: "https://github.com/anthropics/claude-code/issues/16204" # Migration guidance request
config_brianlovin_repo: "https://github.com/brianlovin/claude-config" # Community example with sync.sh
config_ratinaud_approach: "https://www.linkedin.com/posts/martinratinaud_claudecode-devtools-buildinpublic-activity-7424055660247629824-hBsL" # 504 sessions tested
config_ratinaud_evaluation: "docs/resource-evaluations/ratinaud-config-management-evaluation.md" # Full evaluation
# MCP Secrets Management (Added 2026-02-02)
- mcp_secrets_management: "guide/ultimate-guide.md:8113" # Section 8.3.1
- mcp_secrets_principles: "guide/ultimate-guide.md:8121" # Security principles
- mcp_secrets_os_keychain: "guide/ultimate-guide.md:8141" # Approach 1: OS Keychain
- mcp_secrets_env_file: "guide/ultimate-guide.md:8197" # Approach 2: .env + .gitignore
- mcp_secrets_vaults: "guide/ultimate-guide.md:8273" # Approach 3: HashiCorp Vault, AWS, 1Password
- mcp_secrets_rotation: "guide/ultimate-guide.md:8325" # Rotation workflow
- mcp_secrets_pre_commit: "guide/ultimate-guide.md:8363" # Secret detection hook
- mcp_secrets_verification: "guide/ultimate-guide.md:8386" # Verification checklist
- mcp_secrets_best_practices: "guide/ultimate-guide.md:8406" # Summary table
+ mcp_secrets_management: "guide/ultimate-guide.md:10589" # Section 8.3.1
+ mcp_secrets_principles: "guide/ultimate-guide.md:10589" # Security principles
+ mcp_secrets_os_keychain: "guide/ultimate-guide.md:10589" # Approach 1: OS Keychain
+ mcp_secrets_env_file: "guide/ultimate-guide.md:10589" # Approach 2: .env + .gitignore
+ mcp_secrets_vaults: "guide/ultimate-guide.md:10589" # Approach 3: HashiCorp Vault, AWS, 1Password
+ mcp_secrets_rotation: "guide/ultimate-guide.md:10589" # Rotation workflow
+ mcp_secrets_pre_commit: "guide/ultimate-guide.md:8417" # Security Hooks section
+ mcp_secrets_verification: "guide/ultimate-guide.md:10589" # Verification checklist
+ mcp_secrets_best_practices: "guide/ultimate-guide.md:10589" # Summary table
# Templates & Scripts (Configuration Management)
sync_claude_config_script: "examples/scripts/sync-claude-config.sh" # Full automation script
pre_commit_secrets_hook: "examples/hooks/bash/pre-commit-secrets.sh" # Git hook for secret detection
@@ -273,24 +285,27 @@ deep_dive:
# Visual Reference (ASCII diagrams)
visual_reference: "guide/visual-reference.md"
# Architecture internals (guide/architecture.md)
- architecture_visual_overview: "guide/architecture.md:41"
+ architecture_visual_overview: "guide/architecture.md:51"
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"
- architecture_master_loop: "guide/architecture.md:72"
- architecture_tools: "guide/architecture.md:213"
- architecture_context: "guide/architecture.md:306"
- architecture_subagents: "guide/architecture.md:444"
- architecture_permissions: "guide/architecture.md:514"
- architecture_mcp: "guide/architecture.md:719"
+ architecture_master_loop: "guide/architecture.md:82"
+ architecture_tools: "guide/architecture.md:219"
+ architecture_context: "guide/architecture.md:312"
+ architecture_subagents: "guide/architecture.md:471"
+ architecture_permissions: "guide/architecture.md:541"
+ architecture_mcp: "guide/architecture.md:746"
architecture_mcp_visual: "guide/images/mcp-architecture-diagram.svg"
- architecture_philosophy: "guide/architecture.md:1177"
+ architecture_philosophy: "guide/architecture.md:1205"
+ # Official LLM-Optimized Documentation - Added 2026-02-25
+ official_llms_index: "https://code.claude.com/docs/llms.txt" # Index ~65 pages, ~15-20K tokens — use first for discovery
+ official_llms_full: "https://code.claude.com/docs/llms-full.txt" # Full doc ~98KB, ~25-30K tokens — source de vérité officielle
# System Prompts (Official Sources) - Added 2026-01-26
system_prompts_official: "https://platform.claude.com/docs/en/release-notes/system-prompts"
system_prompts_willison_analysis: "https://simonwillison.net/2025/May/25/claude-4-system-prompt/"
system_prompts_prompthub: "https://www.prompthub.us/blog/an-analysis-of-the-claude-4-system-prompt"
- system_prompts_architecture: "guide/architecture.md:354"
+ system_prompts_architecture: "guide/architecture.md:360"
# MCP Apps Extension (SEP-1865) - Added 2026-01-27
- mcp_apps_architecture: "guide/architecture.md:795"
- mcp_apps_evolution: "guide/ultimate-guide.md:6509"
+ mcp_apps_architecture: "guide/architecture.md:753"
+ mcp_apps_evolution: "guide/ultimate-guide.md:9252"
mcp_apps_spec: "https://github.com/modelcontextprotocol/ext-apps"
mcp_apps_blog_mcp: "https://blog.modelcontextprotocol.io/posts/2026-01-26-mcp-apps/"
mcp_apps_blog_claude: "https://claude.com/blog/interactive-tools-in-claude"
@@ -298,146 +313,146 @@ deep_dive:
mcp_apps_announcement_date: "2026-01-26"
mcp_apps_cli_relevance: "Indirect (ecosystem understanding, MCP server dev, hybrid workflows)"
# Main guide (guide/ultimate-guide.md) - Updated 2026-01-27
- installation: 196
- first_workflow: 277
- essential_commands: 326
+ installation: 221
+ first_workflow: 305
+ essential_commands: 47
trust_calibration: 1039
- working_with_images: 422
- wireframing_tools: 492
- figma_mcp: 529
+ working_with_images: 450
+ wireframing_tools: 520
+ figma_mcp: 569
image_optimization: 594
- permission_modes: 760
- interaction_loop: 1299
+ permission_modes: 818
+ interaction_loop: 1364
context_management: 1335
- context_triage: 1448
- session_vs_memory: 1481
- fresh_context_pattern: 1525
+ context_triage: 1520
+ session_vs_memory: 1553
+ fresh_context_pattern: 1597
subscription_limits: 1933
subscription_token_budgets: 1948
subscription_opus_ratio: 1946
- subscription_monitoring: 1985
- plan_mode: 2100
- rewind: 2278
- mental_model: 2360
- xml_prompting: 2419
- prompting_provocation: 3029
+ subscription_monitoring: 2113
+ plan_mode: 576
+ rewind: 2566
+ mental_model: 2815
+ xml_prompting: 3016
+ prompting_provocation: 3469
prompting_provocation_source: "https://paddo.dev/blog/claude-code-team-tips/"
- semantic_anchors: 2904
+ semantic_anchors: 3503
semantic_anchors_catalog: "examples/semantic-anchors/anchor-catalog.md"
- memory_files: 3160
+ memory_files: 4205
# Auto-Memories (v2.1.32+) - Added 2026-02-09
- auto_memories: 3986
- auto_memories_vs_claudemd: 3999
+ auto_memories: 4439
+ auto_memories_vs_claudemd: 4439
# Fast Mode (v2.1.36+) - Added 2026-02-09
- fast_mode_command: 16279 # /fast in commands table
- fast_mode_api: 10051 # API breaking changes section
- fast_mode_pricing: 1722 # Pricing table
+ fast_mode_command: 720 # /fast in commands table
+ fast_mode_api: 720 # API breaking changes section
+ fast_mode_pricing: 1788 # Pricing table
fast_mode_behavior: "2.5x faster, 6x price, same Opus 4.6 model"
# Sonnet 4.6 + 1M Context (Feb 2026) - Added 2026-02-18
- sonnet_4_6_default: 1741 # Pricing table, Sonnet 4.6 now default
- context_200k_vs_1m: 1751 # Decision guide: 200K vs 1M context window
+ sonnet_4_6_default: 1887 # Pricing table, Sonnet 4.6 now default
+ context_200k_vs_1m: 1793 # Decision guide: 200K vs 1M context window
context_200k_vs_1m_perf: "Opus 4.6: 93% @ 256K, 76% @ 1M (MRCR v2). Sonnet 4.6 scores not yet published."
context_200k_vs_1m_cost: "Sonnet 4.6: ~$0.23 bug fix, ~$0.75 module refactor, ~$2.25 full 1M session"
context_1m_beta_requirement: "API only, requires anthropic-beta header. Opus: pricing doubles >200K."
# Debug Command (v2.1.30+) - Added 2026-02-09
- debug_command: 16280 # /debug in commands table
+ debug_command: 47 # Essential Commands table
debug_purpose: "Systematic troubleshooting and error investigation"
# Model Selection & Thinking Guide (Section 2.5) - Added 2026-02-21
- model_selection_guide: 2634 # Section 2.5 — canonical table, effort levels, agent patterns
+ model_selection_guide: 2704 # Section 2.5 — canonical table, effort levels, agent patterns
model_selection_anchor: "#25-model-selection--thinking-guide"
# Configuration Decision Guide (Section 2.7) - Added 2026-02-22
configuration_decision_guide: 2872 # Section 2.7 — mechanism comparison, decision tree, 56% warning
configuration_decision_guide_anchor: "#27-configuration-decision-guide"
- mechanism_comparison_table: 2885 # Semantic roles + mechanism comparison tables
- fifty_six_percent_warning: 2920 # Skills reliability warning + safe patterns
+ mechanism_comparison_table: 2960 # Semantic roles + mechanism comparison tables
+ fifty_six_percent_warning: 2955 # Section 2.7 Configuration Decision Guide
planner_agent: "examples/agents/planner.md"
implementer_agent: "examples/agents/implementer.md"
architecture_reviewer_agent: "examples/agents/architecture-reviewer.md"
# Opus 4.6 Features (Feb 2026) - Added 2026-02-09, line numbers updated 2026-02-21
- opus_4_6_adaptive_thinking: 11065
- opus_4_6_effort_parameter: 11071
- opus_4_6_pricing: 1722
- opus_4_6_api_breaking_changes: 10044
- opus_4_6_assistant_prefill_removed: 10047
+ opus_4_6_adaptive_thinking: 11622
+ opus_4_6_effort_parameter: 11636
+ opus_4_6_pricing: 1788
+ opus_4_6_api_breaking_changes: 11734
+ opus_4_6_assistant_prefill_removed: 11737
# Summarize from Here (v2.1.32+) - Added 2026-02-09
- summarize_from_here: 1470 # Context recovery strategies
+ summarize_from_here: 1506 # Context Recovery Strategies section
# Agent Teams Hook Events (v2.1.32+) - Added 2026-02-09
- hook_teammate_idle: 6972
- hook_task_completed: 6973
+ hook_teammate_idle: 7934
+ hook_task_completed: 7935
# Agent Memory Field (v2.1.32+) - Added 2026-02-09
- agent_memory_frontmatter: 4849
+ agent_memory_frontmatter: 5636 # Agent Template section (memory field in frontmatter)
# Xcode Integration (Feb 2026) - Added 2026-02-09
- xcode_integration: 10834
- claude_agent_sdk: 10845
+ xcode_integration: 12556
+ claude_agent_sdk: 12558
# Task Management System (v2.1.16+) - Added 2026-01-26
- task_management_system: 3127
- task_management_comparison: 3140
- tasks_api_overview: 3150
- tasks_api_tools: 3160
- tasks_api_capabilities: 3170
- tasks_api_configuration: 3180
- tasks_api_schema: 3195
- tasks_api_when_to_use: 3210
- tasks_api_limitations: 3195
+ task_management_system: 3726
+ task_management_comparison: 3732
+ tasks_api_overview: 973
+ tasks_api_tools: 3746
+ tasks_api_capabilities: 3752
+ tasks_api_configuration: 3759
+ tasks_api_schema: 3773
+ tasks_api_when_to_use: 3790
+ tasks_api_limitations: 3796
tasks_api_field_visibility: "TaskList: id/subject/status/owner/blockedBy only. TaskGet: all fields."
tasks_api_cost_overhead: "Reviewing N task descriptions = 1 + N API calls"
- tasks_api_workarounds: 3210
- todowrite_legacy: 3260
- todowrite_when_to_use: 3230
- todowrite_migration_flag: 3240
- task_best_practices: 3250
- task_hierarchy_design: 3252
- task_dependency_management: 3256
- task_status_transitions: 3260
- task_metadata_conventions: 3264
- task_complete_workflow: 3270
- task_sources: 3280
+ tasks_api_workarounds: 3819
+ todowrite_legacy: 3837
+ todowrite_when_to_use: 3846
+ todowrite_migration_flag: 3855
+ task_best_practices: 3862
+ task_hierarchy_design: 3726
+ task_dependency_management: 3726
+ task_status_transitions: 3756
+ task_metadata_conventions: 3757
+ task_complete_workflow: 3947
+ task_sources: 3835
# Task Management Workflow (guide/workflows/task-management.md)
workflows_task_management: "guide/workflows/task-management.md"
task_workflow_overview: "guide/workflows/task-management.md:15"
- task_workflow_planning: "guide/workflows/task-management.md:48"
- task_workflow_execution: "guide/workflows/task-management.md:160"
- task_workflow_session_mgmt: "guide/workflows/task-management.md:260"
- task_workflow_tdd_integration: "guide/workflows/task-management.md:370"
- task_workflow_plan_integration: "guide/workflows/task-management.md:440"
- task_workflow_migration: "guide/workflows/task-management.md:510"
- task_workflow_patterns: "guide/workflows/task-management.md:620"
- task_workflow_troubleshooting: "guide/workflows/task-management.md:740"
- task_workflow_advanced: "guide/workflows/task-management.md:820"
- claude_folder: 3413
- settings: 3464
- precedence_rules: 3686
- agents: 3827
- agent_template: 3900
- agent_examples: 4038
- skills: 4420
- skill_template: 4540
- skill_examples: 4608
- design_patterns_skill: 4799
+ task_workflow_planning: "guide/workflows/task-management.md:52"
+ task_workflow_execution: "guide/workflows/task-management.md:137"
+ task_workflow_session_mgmt: "guide/workflows/task-management.md:215"
+ task_workflow_tdd_integration: "guide/workflows/task-management.md:312"
+ task_workflow_plan_integration: "guide/workflows/task-management.md:367"
+ task_workflow_migration: "guide/workflows/task-management.md:439"
+ task_workflow_patterns: "guide/workflows/task-management.md:525"
+ task_workflow_troubleshooting: "guide/workflows/task-management.md:667"
+ task_workflow_advanced: "guide/workflows/task-management.md:741"
+ claude_folder: 4595
+ settings: 4879
+ precedence_rules: 5103
+ agents: 5546
+ agent_template: 5636
+ agent_examples: 5836
+ skills: 6246
+ skill_template: 6384
+ skill_examples: 6452
+ design_patterns_skill: 6630
design_patterns_skill_location: "examples/skills/design-patterns/"
design_patterns_skill_modes: "Detection, Suggestion, Evaluation"
design_patterns_skill_patterns: "23 GoF patterns (Creational 5, Structural 7, Behavioral 11)"
design_patterns_skill_stacks: "React, Angular, NestJS, Vue, Express, RxJS, Redux, ORMs"
- community_skills_cybersec: 4947
- community_skills_iac: 5030
+ community_skills_cybersec: 6780
+ community_skills_iac: 6863
# Automatic skill generation (meta-skill)
claudeception: "https://github.com/blader/Claudeception"
- claudeception_guide: 5095
+ claudeception_guide: 6915
# Skill Lifecycle: Automatic improvement (added 2026-01-24)
- skill_lifecycle: 5118
- claude_reflect_system: 5161
+ skill_lifecycle: 6246
+ claude_reflect_system: 6246
claude_reflect_system_repo: "https://github.com/haddock-development/claude-reflect-system"
claude_reflect_system_agent_skills: "https://agent-skills.md/skills/haddock-development/claude-reflect-system/reflect"
- skill_improvement_pattern: 5161
- skill_improvement_how_it_works: 5169
- skill_improvement_safety: 5188
- skill_improvement_security_warnings: 5237
- skill_improvement_comparison: 5263
- skill_improvement_workflow: 5275
+ skill_improvement_pattern: 6630
+ skill_improvement_how_it_works: 6630
+ skill_improvement_safety: 6373
+ skill_improvement_security_warnings: 6373
+ skill_improvement_comparison: 6250
+ skill_improvement_workflow: 6328
# Design Intelligence Skill (added 2026-02-23)
ui_ux_pro_max: "https://github.com/nextlevelbuilder/ui-ux-pro-max-skill"
ui_ux_pro_max_site: "https://ui-ux-pro-max-skill.nextlevelbuilder.io"
- ui_ux_pro_max_guide: 7023
+ ui_ux_pro_max_guide: 7092
ui_ux_pro_max_stars: 33700
ui_ux_pro_max_styles: 67
ui_ux_pro_max_palettes: 96
@@ -459,11 +474,11 @@ deep_dive:
agentskills_threat_model: "https://safedep.io/agent-skills-threat-model"
agentskills_threat_model_finding: "8-14% of public skills have vulnerabilities (prompt injection, data exfiltration, privilege escalation)"
agentskills_blog: "https://anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills"
- agentskills_guide_section: "guide/ultimate-guide.md:5180"
+ agentskills_guide_section: "guide/ultimate-guide.md:6383"
agentskills_evaluation: "docs/resource-evaluations/agentskills-io-specification.md"
agentskills_score: "4/5"
# Skills Marketplace (added 2026-01-23)
- skills_marketplace: 5172
+ skills_marketplace: 7212
skills_marketplace_url: "https://skills.sh/"
skills_marketplace_github: "https://github.com/vercel-labs/agent-skills"
skills_marketplace_install: "npx add-skill "
@@ -476,10 +491,10 @@ deep_dive:
skills_marketplace_status: "Community (Vercel Labs), launched Jan 21, 2026"
skills_marketplace_changelog: "https://vercel.com/changelog/introducing-skills-the-open-agent-skills-ecosystem"
# Plugin System & Community Marketplaces (updated 2026-01-24)
- plugins_system: 6863
- plugins_commands: 6876
- plugins_marketplace: 6890
- plugins_community_marketplaces: 7246 # New section with ecosystem stats
+ plugins_system: 11048
+ plugins_commands: 11062
+ plugins_marketplace: 11100
+ plugins_community_marketplaces: 11358 # New section with ecosystem stats
plugins_recommended: "examples/plugins/"
plugins_se_cove: "examples/plugins/se-cove.md"
plugins_official_docs: "https://code.claude.com/docs/en/plugins"
@@ -503,16 +518,16 @@ deep_dive:
- "Linear MCP: ~9.5k installs (issue tracking)"
plugins_awesome_list: "https://github.com/hesreallyhim/awesome-claude-code"
plugins_awesome_list_stars: "20k+"
- chain_of_verification: "guide/methodologies.md:218"
+ chain_of_verification: "guide/methodologies.md:230"
chain_of_verification_paper: "https://arxiv.org/abs/2309.11495"
chain_of_verification_acl: "https://aclanthology.org/2024.findings-acl.212/"
# Verification Loops & Eval Harness (added 2026-01-23)
- verification_loops: "guide/methodologies.md:218"
+ verification_loops: "guide/methodologies.md:245"
verification_loops_source: "https://www.anthropic.com/engineering/claude-code-best-practices"
- eval_harness: "guide/methodologies.md:262"
+ eval_harness: "guide/methodologies.md:289"
eval_harness_source: "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents"
# GSD (Get Shit Done) methodology (added 2026-01-25)
- gsd_methodology: "guide/methodologies.md:47"
+ gsd_methodology: "guide/methodologies.md:53"
gsd_evaluation: "docs/resource-evaluations/gsd-evaluation.md"
gsd_source: "https://github.com/glittercowboy/get-shit-done"
gsd_note: "Overlap with existing patterns (Ralph Loop, Gas Town, BMAD)"
@@ -521,8 +536,8 @@ deep_dive:
resource_evaluations_count: 84
resource_evaluations_methodology: "docs/resource-evaluations/README.md"
resource_evaluations_watchlist: "docs/resource-evaluations/watch-list.md"
- resource_evaluations_appendix: "guide/ultimate-guide.md:15034"
- resource_evaluations_readme_section: "README.md:278"
+ resource_evaluations_appendix: "guide/ultimate-guide.md:20886"
+ resource_evaluations_readme_section: "README.md:307"
resource_evaluations_git_mcp: "docs/resource-evaluations/git-mcp-server-evaluation.md"
resource_evaluations_anaconda_croce: "docs/resource-evaluations/anaconda-croce-evaluation.md"
resource_evaluations_grenier_quality: "docs/resource-evaluations/grenier-agent-skill-quality.md"
@@ -541,80 +556,80 @@ deep_dive:
audit_agents_skills_industry_context: "29.5% deploy without evaluation (LangChain 2026), 18% cite agent bugs as top challenge"
audit_agents_skills_guide_refs: "guide/ultimate-guide.md:4951 (after Agent Validation Checklist), guide/ultimate-guide.md:5495 (after Skill Validation)"
# Practitioner Insights (external validation)
- practitioner_insights: "guide/ai-ecosystem.md:1209"
- practitioner_dave_van_veen: "guide/ai-ecosystem.md:1213"
- practitioner_matteo_collina: "guide/ai-ecosystem.md:1243"
+ practitioner_insights: "guide/ai-ecosystem.md:2170"
+ practitioner_dave_van_veen: "guide/ai-ecosystem.md:2174"
+ practitioner_matteo_collina: "guide/ai-ecosystem.md:2203"
# Outcome Engineering (o16g) - Emerging manifesto (2026-02-13)
- outcome_engineering_o16g: "guide/ai-ecosystem.md:2314"
+ outcome_engineering_o16g: "guide/ai-ecosystem.md:2366"
outcome_engineering_url: "https://o16g.com/"
outcome_engineering_author: "Cory Ondrejka (CTO Onebrief, co-creator Second Life, ex-VP Google/Meta)"
outcome_engineering_status: "Emerging - on watch list for community adoption"
practitioner_collina_source: "https://adventures.nodeland.dev/archive/the-human-in-the-loop/"
- practitioner_steinberger: "guide/ai-ecosystem.md:1997"
+ practitioner_steinberger: "guide/ai-ecosystem.md:2242"
practitioner_steinberger_source: "https://steipete.me/posts/2025/shipping-at-inference-speed"
- practitioner_addy_osmani: "guide/ai-ecosystem.md:2024"
+ practitioner_addy_osmani: "guide/ai-ecosystem.md:2269"
practitioner_osmani_source: "https://addyo.substack.com/p/the-80-problem-in-agentic-coding"
- practitioner_alan: "guide/ai-ecosystem.md:2133"
+ practitioner_alan: "guide/ai-ecosystem.md:2299"
practitioner_alan_source: "https://www.linkedin.com/pulse/le-principe-de-la-tour-eiffel-et-ralph-wiggum-maxime-le-bras-psmxe/"
verification_paradox: "guide/production-safety.md:639"
verification_paradox_source: "https://www.linkedin.com/pulse/le-principe-de-la-tour-eiffel-et-ralph-wiggum-maxime-le-bras-psmxe/"
- eighty_percent_problem: "guide/ai-ecosystem.md:2024"
- comprehension_debt_secondary: "guide/ai-ecosystem.md:2024" # See also: vibe_coding_trap (primary)
+ eighty_percent_problem: "guide/ai-ecosystem.md:2269"
+ comprehension_debt_secondary: "guide/ai-ecosystem.md:2269" # See also: vibe_coding_trap (primary)
# DevOps/SRE Guide (guide/devops-sre.md)
devops_sre_guide: "guide/devops-sre.md"
- devops_fire_framework: "guide/devops-sre.md:50"
- devops_k8s_troubleshooting: "guide/devops-sre.md:120"
- devops_k8s_prompts: "guide/devops-sre.md:160"
- devops_incident_response: "guide/devops-sre.md:340"
- devops_iac_patterns: "guide/devops-sre.md:520"
- devops_guardrails: "guide/devops-sre.md:650"
- devops_limitations: "guide/devops-sre.md:290"
- devops_quick_reference: "guide/devops-sre.md:750"
+ devops_fire_framework: "guide/devops-sre.md:46"
+ devops_k8s_troubleshooting: "guide/devops-sre.md:129"
+ devops_k8s_prompts: "guide/devops-sre.md:151"
+ devops_incident_response: "guide/devops-sre.md:333"
+ devops_iac_patterns: "guide/devops-sre.md:504"
+ devops_guardrails: "guide/devops-sre.md:687"
+ devops_limitations: "guide/devops-sre.md:297"
+ devops_quick_reference: "guide/devops-sre.md:794"
devops_agent: "examples/agents/devops-sre.md"
devops_claude_md: "examples/claude-md/devops-sre.md"
# Product Designer (design-to-code workflow)
product_designer_workflow: "guide/workflows/design-to-code.md"
product_designer_claudemd: "examples/claude-md/product-designer.md"
- design_system_handoff: "guide/workflows/design-to-code.md:531"
- figma_make_integration: "guide/workflows/design-to-code.md:26"
- pencil_canvas: "guide/ultimate-guide.md:529"
- pencil_workflow: "guide/workflows/design-to-code.md:447"
- pencil_vs_figma: "guide/workflows/design-to-code.md:470"
- commands: 4950
- command_template: 5020
- hooks: 5273
- hook_templates: 5418
- security_hooks: 5680
- security_gate_hook_line: 6907
+ design_system_handoff: "guide/workflows/design-to-code.md:263"
+ figma_make_integration: "guide/workflows/design-to-code.md:85"
+ pencil_canvas: "guide/ultimate-guide.md:528"
+ pencil_workflow: "guide/workflows/design-to-code.md:453"
+ pencil_vs_figma: "guide/workflows/design-to-code.md:476"
+ commands: 47
+ command_template: 7592
+ hooks: 8077
+ hook_templates: 8155
+ security_hooks: 8161
+ security_gate_hook_line: 8481
security_gate_hook_source: "https://paddo.dev/blog/claude-code-team-tips/"
- mcp_servers: 5984
- serena_indexation: 6078
- serena_mcp: 6037
- doobidoo_memory_mcp: 6385
- mcp_memory_stack_patterns: 6524
- mcp_config: 6149
- mcp_security: 6517
- cicd: 6835
- ide_integration: 7524
- feedback_loops: 7594
- batch_operations: 8024
- pitfalls: 8143
- git_best_practices: 8412
- cost_optimization: 8878
- session_teleportation: 9477
- remote_control: 18843
- multi_instance_workflows: 9583
- boris_cherny_case_study: 9617
- boris_cherny_team_patterns: 11822
+ mcp_servers: 9204
+ serena_indexation: 9373
+ serena_mcp: 9373
+ doobidoo_memory_mcp: 10142
+ mcp_memory_stack_patterns: 10325
+ mcp_config: 10556
+ mcp_security: 11402
+ cicd: 11827
+ ide_integration: 12528
+ feedback_loops: 12613
+ batch_operations: 13243
+ pitfalls: 13366
+ git_best_practices: 13831
+ cost_optimization: 1784
+ session_teleportation: 15178
+ remote_control: 18833
+ multi_instance_workflows: 15283
+ boris_cherny_case_study: 15332
+ boris_cherny_team_patterns: 5492
# Dual-Instance Planning Pattern (Jon Williams, Feb 2026)
- dual_instance_planning: 12884
+ dual_instance_planning: 15385
dual_instance_workflow: "guide/workflows/dual-instance-planning.md"
- dual_instance_overview: 12884
- dual_instance_setup: "guide/workflows/dual-instance-planning.md:49"
- dual_instance_complete_workflow: "guide/workflows/dual-instance-planning.md:149"
- dual_instance_plan_template: "guide/workflows/dual-instance-planning.md:457"
- dual_instance_cost_analysis: "guide/workflows/dual-instance-planning.md:652"
- dual_instance_comparison: 13074 # Boris vs Jon comparison table
+ dual_instance_overview: 15385
+ dual_instance_setup: "guide/workflows/dual-instance-planning.md:71"
+ dual_instance_complete_workflow: "guide/workflows/dual-instance-planning.md:145"
+ dual_instance_plan_template: "guide/workflows/dual-instance-planning.md:522"
+ dual_instance_cost_analysis: "guide/workflows/dual-instance-planning.md:614"
+ dual_instance_comparison: 15385 # Boris vs Jon comparison table
dual_instance_source: "https://www.linkedin.com/posts/thatjonwilliams_ive-been-using-cursor-for-six-months-now-activity-7424481861802033153-k8bu"
dual_instance_author: "Jon Williams (Product Designer, UK)"
dual_instance_date: "2026-02-03"
@@ -631,9 +646,9 @@ deep_dive:
team_tips_paddo_source: "Boris Cherny thread (x.com/bcherny/status/2017742741636321619)"
team_tips_paddo_evaluation: "docs/resource-evaluations/paddo-team-tips-eval.md"
team_tips_paddo_score: "4/5"
- anthropic_study_metrics: 9721
+ anthropic_study_metrics: 11555
# Contribution Metrics (Jan 2026 - platform feature, not CLI release)
- contribution_metrics: 11625
+ contribution_metrics: 15970
contribution_metrics_source: "https://claude.com/blog/contribution-metrics"
contribution_metrics_date: "2026-01-29"
contribution_metrics_availability: "Public beta - Team and Enterprise plans"
@@ -643,16 +658,16 @@ deep_dive:
git_worktree_status_command: "examples/commands/git-worktree-status.md"
git_worktree_remove_command: "examples/commands/git-worktree-remove.md"
git_worktree_clean_command: "examples/commands/git-worktree-clean.md"
- git_worktrees_multi_instance: 10634
- advanced_worktree_tooling: 10748
- worktree_tooling_self_assessment: 10762
- anthropic_internal_study: 10921
- multi_instance_costs: 10955
- orchestration_frameworks: 10992
- headless_pm_framework: 11004
- multi_instance_implementation: 11030
- multi_instance_monitoring: 11103
- multi_instance_decision_matrix: 11176
+ git_worktrees_multi_instance: 14013
+ advanced_worktree_tooling: 15763
+ worktree_tooling_self_assessment: 15763
+ anthropic_internal_study: 15934
+ multi_instance_costs: 15283
+ orchestration_frameworks: 16029
+ headless_pm_framework: 11841
+ multi_instance_implementation: 15283
+ multi_instance_monitoring: 15283
+ multi_instance_decision_matrix: 15283
# External orchestration systems
external_orchestrators:
gas_town:
@@ -694,30 +709,30 @@ deep_dive:
published: "2026-01-21"
guide_section: "README.md:338"
# Section 9.18 - Codebase Design for Agent Productivity
- codebase_design_agents: 14121
+ codebase_design_agents: 16311
codebase_design_source: "https://marmelab.com/blog/2026/01/21/agent-experience.html"
codebase_design_author: "François Zaninotto (Marmelab)"
- codebase_design_llms_txt: 14543 # llms.txt standard for AI-optimized documentation
+ codebase_design_llms_txt: 16797 # llms.txt standard for AI-optimized documentation
codebase_design_llms_txt_spec: "https://llmstxt.org/"
codebase_design_llms_txt_example: "machine-readable/llms.txt"
# Section 9.19 - Permutation Frameworks
- permutation_frameworks: 13947
+ permutation_frameworks: 18314
# Section 9.20 - Agent Teams (v2.1.32+ experimental)
agent_teams: "guide/workflows/agent-teams.md"
agent_teams_quick_start: "guide/workflows/agent-teams-quick-start.md" # Practical 8-10 min guide with copy-paste patterns
- agent_teams_overview: 15992 # Section 9.20 in ultimate-guide.md
- agent_teams_architecture: "guide/workflows/agent-teams.md:59"
- agent_teams_setup: "guide/workflows/agent-teams.md:104"
- agent_teams_use_cases: "guide/workflows/agent-teams.md:232"
- agent_teams_fountain_case_study: "guide/workflows/agent-teams.md:254"
- agent_teams_cred_case_study: "guide/workflows/agent-teams.md:282"
+ agent_teams_overview: 18498 # Section 9.20 in ultimate-guide.md
+ agent_teams_architecture: "guide/workflows/agent-teams.md:137"
+ agent_teams_setup: "guide/workflows/agent-teams.md:250"
+ agent_teams_use_cases: "guide/workflows/agent-teams.md:346"
+ agent_teams_fountain_case_study: "guide/workflows/agent-teams.md:358"
+ agent_teams_cred_case_study: "guide/workflows/agent-teams.md:391"
agent_teams_c_compiler_case_study: "guide/workflows/agent-teams.md:308"
- agent_teams_paul_rayner_workflows: "guide/workflows/agent-teams.md:352"
- agent_teams_workflow_impact: "guide/workflows/agent-teams.md:443"
- agent_teams_limitations: "guide/workflows/agent-teams.md:529"
- agent_teams_decision_tree: "guide/workflows/agent-teams.md:723"
- agent_teams_best_practices: "guide/workflows/agent-teams.md:789"
- agent_teams_troubleshooting: "guide/workflows/agent-teams.md:978"
+ agent_teams_paul_rayner_workflows: "guide/workflows/agent-teams.md:450"
+ agent_teams_workflow_impact: "guide/workflows/agent-teams.md:552"
+ agent_teams_limitations: "guide/workflows/agent-teams.md:644"
+ agent_teams_decision_tree: "guide/workflows/agent-teams.md:804"
+ agent_teams_best_practices: "guide/workflows/agent-teams.md:928"
+ agent_teams_troubleshooting: "guide/workflows/agent-teams.md:1092"
agent_teams_experimental_flag: "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=true"
agent_teams_model_requirement: "Opus 4.6 minimum"
agent_teams_sources:
@@ -763,71 +778,71 @@ deep_dive:
ai_fluency_fluency_ratio: "2.67 vs 1.33 behaviors (iterative vs non-iterative)"
ai_fluency_collaboration_terms: "Only 30% of users set collaboration terms explicitly"
ai_fluency_artifact_paradox: "Artifact production → −5.2pp missing context, −3.7pp fact-check, −3.1pp questioning reasoning"
- ai_fluency_plan_review_section: "guide/ultimate-guide.md:2522" # Rev the Engine callout
- ai_fluency_claudemd_section: "guide/ultimate-guide.md:4381" # CLAUDE.md Best Practices callout
- ai_fluency_artifact_section: "guide/ultimate-guide.md:13382" # Artifact Paradox callout (Common Pitfalls)
+ ai_fluency_plan_review_section: "guide/ultimate-guide.md:2542" # Rev the Engine callout
+ ai_fluency_claudemd_section: "guide/ultimate-guide.md:4421" # CLAUDE.md Best Practices callout
+ ai_fluency_artifact_section: "guide/ultimate-guide.md:13485" # Artifact Paradox callout (Common Pitfalls)
ai_fluency_authors: "Swanson, Bent, Huang, Ludwig, Dakan, Feller (Anthropic)"
ai_fluency_published: "2026-02-23"
ai_fluency_future: "Claude Code platform analysis (mentioned in paper's future directions)"
ai_fluency_diagram: "guide/diagrams/06-development-workflows.md#ai-fluency--high-vs-low-fluency-paths"
ai_fluency_diagram_type: "flowchart — Artifact Paradox: 70% vs 30% user paths, behavioral drop data, iteration outcomes"
# Advanced Plan Mode Patterns
- rev_the_engine: 2323
- mechanic_stacking: 2371
+ rev_the_engine: 2490
+ mechanic_stacking: 2538
# Sub-Agent Patterns (Refactored 2026-02-09)
- agent_anti_patterns: 3662 # Critical: Roles vs Context Control (Dex Horty principle)
- scope_focused_agents: 3709 # Formerly "Split-Role Sub-Agents", refactored for context isolation
- teammatetool_experimental: 3606 # Multi-agent orchestration parent section
+ agent_anti_patterns: 4032 # Critical: Roles vs Context Control (Dex Horty principle)
+ scope_focused_agents: 4079 # Formerly "Split-Role Sub-Agents", refactored for context isolation
+ teammatetool_experimental: 3976 # Multi-agent orchestration parent section
# Task Management Diagnostic
- task_lists_diagnostic: 3398
+ task_lists_diagnostic: 3884
# Mental Model
- main_thread_orchestrator: 2517
+ main_thread_orchestrator: 2886
# CLAUDE.md Patterns
- continuous_context_update: 3743
+ continuous_context_update: 4297
# Hook Patterns
- smart_hook_dispatching: 6863
+ smart_hook_dispatching: 8689
# Workflows
skeleton_projects_workflow: "guide/workflows/skeleton-projects.md"
# Spec-First Development (Addy Osmani, Jan 2026)
spec_first_workflow: "guide/workflows/spec-first.md"
- spec_modular_design: "guide/workflows/spec-first.md:322"
- spec_operational_boundaries: "guide/workflows/spec-first.md:372"
- spec_command_template: "guide/workflows/spec-first.md:432"
- spec_anti_monolithic: "guide/workflows/spec-first.md:472"
+ spec_modular_design: "guide/workflows/spec-first.md:363"
+ spec_operational_boundaries: "guide/workflows/spec-first.md:461"
+ spec_command_template: "guide/workflows/spec-first.md:573"
+ spec_anti_monolithic: "guide/workflows/spec-first.md:717"
spec_osmani_source: "https://addyosmani.com/blog/good-spec/"
spec_osmani_evaluation: "docs/resource-evaluations/addy-osmani-good-spec.md"
spec_osmani_score: "4/5"
spec_task_granularity: "guide/workflows/spec-first.md:62" # Vertical slices + PRD checklist (Allan Hill, Feb 2026)
- spec_prd_checklist: "guide/workflows/spec-first.md:70" # 6-dimension PRD quality checklist
- atdd_with_agents: "guide/methodologies.md:180" # ATDD + Gherkin for agentic workflows
- commands_table: 10213
- shortcuts_table: 10246
- troubleshooting: 10372
- cheatsheet: 10747
- daily_workflow: 13581
+ spec_prd_checklist: "guide/workflows/spec-first.md:68" # 6-dimension PRD quality checklist
+ atdd_with_agents: "guide/methodologies.md:161" # ATDD + Gherkin for agentic workflows
+ commands_table: 47
+ shortcuts_table: 368
+ troubleshooting: 11311
+ cheatsheet: 19597
+ daily_workflow: 19673
# AI Ecosystem (Section 11, ~line 10525)
- ai_ecosystem: 10525
- ai_ecosystem_complementarity: 10527
- ai_ecosystem_tool_matrix: 10565
- ai_ecosystem_workflows: 10590
- ai_ecosystem_integration: 10716
+ ai_ecosystem: 20004
+ ai_ecosystem_complementarity: 20004
+ ai_ecosystem_tool_matrix: 20031
+ ai_ecosystem_workflows: 20166
+ ai_ecosystem_integration: 20294
ai_ecosystem_detailed: "guide/ai-ecosystem.md"
- ai_ecosystem_goose: "guide/ai-ecosystem.md:1116"
- ai_ecosystem_goose_comparison: "guide/ai-ecosystem.md:1132"
- ai_ecosystem_context_packing: "guide/ai-ecosystem.md:1208"
- ai_ecosystem_multi_ide_sync: "guide/ai-ecosystem.md:1256"
- agents_md_support_status: "guide/ai-ecosystem.md:1322"
- ai_ecosystem_build_vs_use: "guide/ai-ecosystem.md:2346" # Section 11.3 - When to Build vs Use (ADK, LangChain, Vercel AI SDK)
+ ai_ecosystem_goose: "guide/ai-ecosystem.md:2074"
+ ai_ecosystem_goose_comparison: "guide/ai-ecosystem.md:2090"
+ ai_ecosystem_context_packing: "guide/ai-ecosystem.md:2533"
+ ai_ecosystem_multi_ide_sync: "guide/ai-ecosystem.md:1282"
+ agents_md_support_status: "guide/ai-ecosystem.md:1348"
+ ai_ecosystem_build_vs_use: "guide/ai-ecosystem.md:2399" # Section 11.3 - When to Build vs Use (ADK, LangChain, Vercel AI SDK)
# Architecture Diagrams as Context (advanced pattern) - Added 2026-01-25
- architecture_diagrams_input: "guide/ai-ecosystem.md:1379"
+ architecture_diagrams_input: "guide/ai-ecosystem.md:2567"
architecture_diagrams_mcp_tools:
- "Archy MCP: https://www.pulsemcp.com/servers/phxdev1-archy"
- "Mermaid MCP: 61.4K users"
- "Blueprint MCP (ArcadeAI)"
llm_oop_research: "https://dl.acm.org/doi/10.1145/3639474.3640052"
architecture_diagrams_source: "https://www.linkedin.com/posts/tigraff_uml-claude-wibecoding-activity-7420595633826258944-gGO5"
- ai_ecosystem_voice_to_text: "guide/ai-ecosystem.md:449"
- ai_ecosystem_alternative_providers: "guide/ai-ecosystem.md:959"
+ ai_ecosystem_voice_to_text: "guide/ai-ecosystem.md:1066"
+ ai_ecosystem_alternative_providers: "guide/ai-ecosystem.md:2639"
voice_refine_skill: "examples/skills/voice-refine/SKILL.md"
# Cowork documentation (v1.0 - migrated to dedicated repo)
cowork_reference: "machine-readable/cowork-reference.yaml" # Dedicated YAML index (kept local)
@@ -843,10 +858,10 @@ deep_dive:
cowork_faq: "https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/reference/faq.md"
cowork_prompts: "https://github.com/FlorianBruniaux/claude-cowork-guide/tree/main/prompts"
cowork_workflows: "https://github.com/FlorianBruniaux/claude-cowork-guide/tree/main/workflows"
- cowork_section: "guide/ai-ecosystem.md:760"
- cowork_ultimate_guide: 10759
+ cowork_section: "guide/ai-ecosystem.md:1809"
+ cowork_ultimate_guide: 20348
# Experimental Features
- teammatetool: 3294
+ teammatetool: 3976
teammatetool_status: "Experimental, progressive rollout, feature-flagged"
teammatetool_capabilities: "Multi-agent coordination, team messaging, swarm patterns"
teammatetool_sources:
@@ -854,16 +869,16 @@ deep_dive:
- "https://github.com/anthropics/claude-code/issues/3013"
- "https://github.com/mikekelly/claude-sneakpeek"
# Appendix
- appendix_a_file_locations: 14356
- appendix_b_faq: 14530
- faq_clawdbot_vs_claudecode: 14532
- faq_product_managers: 14601
- appendix_c_resource_evaluation: 15214
- appendix_d_myths_vs_reality: 15257
- myths_hidden_features: 15261
- myths_tasks_api_autonomous: 15301
- myths_100x_faster: 15340
- myths_reliable_sources: 15388
+ appendix_a_file_locations: 20574
+ appendix_b_faq: 20750
+ faq_clawdbot_vs_claudecode: 20764
+ faq_product_managers: 20821
+ appendix_c_resource_evaluation: 20886
+ appendix_d_myths_vs_reality: 20929
+ myths_hidden_features: 20933
+ myths_tasks_api_autonomous: 20965
+ myths_100x_faster: 20997
+ myths_reliable_sources: 20983
# Quiz System (264 questions, 15 categories)
quiz_overview: "quiz/README.md"
quiz_file: "quiz/questions.json"
@@ -879,29 +894,29 @@ deep_dive:
quiz_estimated_time_intermediate: "25-30 min"
quiz_estimated_time_advanced: "30-40 min"
# Onboarding matrix required keys (added for v2.0.0 adaptive architecture)
- rules: 917 # Golden Rules section
- workflow: 659 # Workflow (9 steps)
- fix: 868 # Troubleshooting section
- architecture: 819 # Architecture internals
+ rules: 89 # Golden Rules section
+ workflow: 58 # Workflow (9 steps)
+ fix: 11948 # Troubleshooting section
+ architecture: 919 # Architecture internals
production_safety: "guide/production-safety.md" # Production safety rules
security_hardening: "guide/security-hardening.md" # Security best practices
- security_cve_summary: "guide/security-hardening.md:51" # CVE table (7 CVEs, 2025-2026)
- security_supply_chain_stats: "guide/security-hardening.md:127" # Snyk ToxicSkills: 36.82% of 3,984 skills
- security_mcp_scan_tool: "guide/security-hardening.md:96" # mcp-scan in Safe List
- security_malicious_extensions: "guide/security-hardening.md:242" # .claude/ attack surface (§1.5)
- security_kill_switch: "guide/security-hardening.md:626" # AI Kill Switch & Containment Architecture (§3.5)
- security_claude_folder_audit: "guide/security-hardening.md:270" # 5-minute .claude/ audit checklist
+ security_cve_summary: "guide/security-hardening.md:15" # Decision Matrix + CVEs
+ security_supply_chain_stats: "guide/security-hardening.md:137" # Agent Skills Supply Chain Risks
+ security_mcp_scan_tool: "guide/security-hardening.md:32" # MCP Vetting Workflow
+ security_malicious_extensions: "guide/security-hardening.md:252" # .claude/ attack surface (§1.5)
+ security_kill_switch: "guide/security-hardening.md:630" # AI Kill Switch & Containment Architecture (§3.5)
+ security_claude_folder_audit: "guide/security-hardening.md:228" # Repository Pre-Scan (§1.4)
security_toxicskills_evaluation: "docs/resource-evaluations/snyk-toxicskills-evaluation.md"
security_check_command: "examples/commands/security-check.md" # Quick config check vs known threats
security_audit_command: "examples/commands/security-audit.md" # Full 6-phase security audit (score /100)
security_threat_db: "examples/commands/resources/threat-db.yaml" # Threat intelligence database (authors, skills, CVEs, patterns)
security_update_threat_db: "examples/commands/update-threat-db.md" # /update-threat-db — research & update threat database
- security_cc_scanner: "guide/security-hardening.md:776" # Claude Code Security (research preview) — Anthropic native vuln scanner, adversarial validation, patch suggestions
+ security_cc_scanner: "guide/security-hardening.md:780" # Claude Code Security (research preview) — Anthropic native vuln scanner, adversarial validation, patch suggestions
security_patcher_agent: "examples/agents/security-patcher.md" # Agent: applies patches from security-auditor findings, human approval gate, Write/Edit tools
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)
- security_pr_review_workflow: "guide/security-hardening.md:706" # PR security review workflow — 3-agent pipeline, git hook integration
- agent_validation_checklist: 3850 # Agent validation section in ultimate-guide.md
- git_mcp_guide: "guide/mcp-servers-ecosystem.md:102" # Git MCP server documentation
+ security_pr_review_workflow: "guide/security-hardening.md:712" # PR security review workflow — 3-agent pipeline, git hook integration
+ agent_validation_checklist: 5744 # Agent validation section in ultimate-guide.md
+ git_mcp_guide: "guide/mcp-servers-ecosystem.md:113" # Git MCP server documentation
# ════════════════════════════════════════════════════════════════
# DECISION TREE (most important - en premier)
@@ -1043,7 +1058,7 @@ mcp:
serena: "symbol search + session memory (write_memory/read_memory) + project indexation"
claude_mem: "automatic session capture + AI compression + progressive disclosure + Web dashboard (localhost:37777)"
claude_mem_repo: "https://github.com/thedotmack/claude-mem"
- claude_mem_guide: "guide/ultimate-guide.md:8463"
+ claude_mem_guide: "guide/ultimate-guide.md:1585"
claude_mem_plugin: "examples/plugins/claude-mem.md"
claude_mem_installation: "/plugin marketplace add thedotmack/claude-mem"
claude_mem_stars: "26.5k"
@@ -1081,15 +1096,15 @@ mcp:
git_mcp_advanced_filtering: "ISO 8601 dates, relative dates (2 weeks ago), absolute dates"
git_mcp_use_cases: "automated commits, log analysis, branch management, token-efficient diffs, multi-repo"
ast_grep: "optional plugin for AST-based code search (explicit invocation required)"
- ast_grep_guide: "guide/ultimate-guide.md:6564"
+ ast_grep_guide: "guide/ultimate-guide.md:9845"
ast_grep_skill: "examples/skills/ast-grep-patterns.md"
ast_grep_install: "npx skills add ast-grep/agent-skill"
ast_grep_when: "structural patterns (>50k lines, migrations, AST rules)"
ast_grep_not_for: "simple string search, small projects (<10k lines)"
search_decision_tree: "grep (text) | ast-grep (structure) | Serena (symbols) | grepai (semantic)"
- search_tools_comparison: "guide/ultimate-guide.md:6517"
+ search_tools_comparison: "guide/ultimate-guide.md:9845"
search_tools_mastery_workflow: "guide/workflows/search-tools-mastery.md"
- grep_vs_rag_history: "guide/architecture.md:33"
+ grep_vs_rag_history: "guide/architecture.md:232"
ripgrep_native: "Grep tool (Claude Code built-in, ~20ms)"
grepai_semantic: "Semantic search + call graph (Ollama-based, ~500ms)"
grepai_benchmark:
@@ -1102,10 +1117,10 @@ mcp:
astgrep_structural: "AST patterns for large refactoring (~200ms)"
search_combined_workflow: "guide/workflows/search-tools-mastery.md:205"
check: "/mcp"
- config: ".claude/mcp.json or ~/.claude.json"
+ config: "~/.claude.json (mcpServers field) or .mcp.json (project root)"
tool_search: "lazy loading MCP tools (v2.1.7+) - 85% token reduction - auto:N threshold config"
tool_search_config: "ENABLE_TOOL_SEARCH=auto|auto:N|true|false"
- tool_search_deep_dive: "guide/architecture.md:1000"
+ tool_search_deep_dive: "guide/architecture.md:284"
# ════════════════════════════════════════════════════════════════
# ARCHITECTURE INTERNALS - see guide/architecture.md
@@ -1199,7 +1214,7 @@ hook_events:
Notification: "alerts"
# Hook Execution Model (v2.1.0+)
-hooks_execution_model: 6075 # Section in ultimate-guide.md
+hooks_execution_model: 7969 # Section in ultimate-guide.md
hooks_async_support: "v2.1.0+ - add 'async: true' for non-blocking execution"
hooks_async_use_cases: "logging, notifications, formatting, metrics (no feedback needed)"
hooks_sync_use_cases: "validation, type checking, security (feedback required)"
diff --git a/quiz/questions/03-memory-settings.yaml b/quiz/questions/03-memory-settings.yaml
index 4e0468e..c96fdba 100644
--- a/quiz/questions/03-memory-settings.yaml
+++ b/quiz/questions/03-memory-settings.yaml
@@ -133,7 +133,7 @@ questions:
d: "Git commands with glob patterns"
correct: "b"
explanation: |
- The pattern 'Bash(git *)' matches any git command. Permission patterns use wildcards: 'Bash(git *)' matches any git command, 'Bash(pnpm *)' matches any pnpm command, 'mcp__serena__*' matches all Serena MCP tools. You can also use specific patterns like 'Bash(git status:*)' to match only git status.
+ The pattern 'Bash(git *)' matches any git command. Permission patterns use wildcards: 'Bash(git *)' matches any git command, 'Bash(pnpm *)' matches any pnpm command, 'mcp__serena__*' matches all Serena MCP tools. You can also use specific patterns like 'Bash(git status *)' to match only git status. Note: the legacy ':*' suffix syntax is deprecated, use space instead (e.g. 'Bash(git *)' not 'Bash(git:*)').
doc_reference:
file: "guide/ultimate-guide.md"
section: "3.3 Settings & Permissions"
@@ -196,12 +196,12 @@ questions:
question: "What does 'allowedTools' configuration do differently from permission categories?"
options:
a: "Nothing, they are the same"
- b: "Provides granular control with tool-specific patterns in ~/.claude.json"
+ b: "Provides granular control with tool-specific patterns in ~/.claude/settings.json"
c: "Only works for MCP tools"
d: "Requires admin privileges"
correct: "b"
explanation: |
- The allowedTools configuration in ~/.claude.json provides granular control with specific patterns. For example: 'Read(*)' allows all reads, 'Bash(git status:*)' allows only git status, 'Bash(pnpm *:*)' allows pnpm commands. You can set progressive permission levels from beginner (very restrictive) to advanced. Never use --dangerously-skip-permissions.
+ The allowedTools configuration in ~/.claude/settings.json provides granular control with specific patterns. For example: 'Read' allows all reads, 'Bash(git status *)' allows only git status, 'Bash(pnpm *)' allows pnpm commands. You can set progressive permission levels from beginner (very restrictive) to advanced. Never use --dangerously-skip-permissions. Note: use the tool name without parentheses for "all uses" (e.g. 'Read' not 'Read(*)').
doc_reference:
file: "guide/ultimate-guide.md"
section: "3.3 Settings & Permissions"
diff --git a/quiz/questions/07-hooks.yaml b/quiz/questions/07-hooks.yaml
index cd423c3..6aaa432 100644
--- a/quiz/questions/07-hooks.yaml
+++ b/quiz/questions/07-hooks.yaml
@@ -46,7 +46,7 @@ questions:
- **UserPromptSubmit**: When user sends a message (context enrichment)
- **Notification**: When Claude sends a notification
- **SessionStart/SessionEnd**: Session lifecycle events
- - **Stop**: When user interrupts
+ - **Stop**: When Claude finishes responding
doc_reference:
file: "guide/ultimate-guide.md"
section: "7.1 The Event System"
diff --git a/quiz/questions/08-mcp-servers.yaml b/quiz/questions/08-mcp-servers.yaml
index 294b166..e3d12e3 100644
--- a/quiz/questions/08-mcp-servers.yaml
+++ b/quiz/questions/08-mcp-servers.yaml
@@ -105,25 +105,25 @@ questions:
- id: "08-005"
difficulty: "junior"
profiles: ["junior", "senior", "power"]
- question: "Where is the global MCP configuration file located?"
+ question: "Where is the user-scope MCP configuration stored?"
options:
a: "~/.mcp/config.json"
- b: "~/.claude/mcp.json"
+ b: "~/.claude.json"
c: "/etc/claude/mcp.json"
d: "~/.config/claude/mcp.json"
correct: "b"
explanation: |
- The global MCP configuration is at `~/.claude/mcp.json`.
+ MCP servers are configured in `~/.claude.json` under the `"mcpServers"` field.
Configuration locations:
- - `~/.claude/mcp.json` - Global (applies to all projects)
- - `/project/.claude/mcp.json` - Project-specific (overrides global)
+ - `~/.claude.json` (field `"mcpServers"`) - User/local scope
+ - `.mcp.json` at project root - Project scope (shareable via VCS)
The configuration specifies which servers to run and their settings.
doc_reference:
file: "guide/ultimate-guide.md"
section: "8.3 Configuration"
- anchor: "#mcpjson-location"
+ anchor: "#mcp-configuration-location"
- id: "08-006"
difficulty: "senior"
@@ -177,24 +177,26 @@ questions:
- id: "08-008"
difficulty: "junior"
profiles: ["junior", "senior", "power"]
- question: "What variable can you use in mcp.json to reference the current project path?"
+ question: "What syntax does Claude Code use for environment variable substitution in MCP config?"
options:
a: "${projectPath}"
b: "${workspaceFolder}"
- c: "${cwd}"
+ c: "${VAR_NAME}"
d: "${PROJECT_DIR}"
- correct: "b"
+ correct: "c"
explanation: |
- The `${workspaceFolder}` variable expands to the current project path.
+ Claude Code uses standard shell-style `${VAR}` syntax for environment variable expansion.
- Variable substitution in mcp.json:
- - `${workspaceFolder}` - Current project path
- - `${env:VAR_NAME}` - Environment variable
+ Variable substitution in MCP config:
+ - `${VAR}` - Environment variable value
+ - `${VAR:-default}` - Environment variable with fallback
+
+ Note: `${workspaceFolder}` and `${env:VAR_NAME}` are VS Code conventions, not Claude Code.
Example:
```json
"env": {
- "PROJECT_PATH": "${workspaceFolder}"
+ "DATABASE_URL": "${DATABASE_URL}"
}
```
doc_reference:
diff --git a/scripts/resync-reference-yaml.py b/scripts/resync-reference-yaml.py
new file mode 100644
index 0000000..f944987
--- /dev/null
+++ b/scripts/resync-reference-yaml.py
@@ -0,0 +1,406 @@
+#!/usr/bin/env python3
+"""
+Re-sync line numbers in machine-readable/reference.yaml
+
+Strategy:
+ 1. Build header index for each guide file (all lines starting with #)
+ 2. For each reference.yaml entry with a line number, read what's at that line
+ 3. If content doesn't look right, search by key-name keywords in headers
+ 4. Output a patch file with proposed fixes + confidence scores
+
+Usage:
+ python3 scripts/resync-reference-yaml.py [--apply]
+
+ Without --apply: prints report to stdout + saves claudedocs/resync-report.md
+ With --apply: applies HIGH CONFIDENCE fixes directly to reference.yaml
+"""
+
+import re
+import sys
+import os
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).parent.parent
+YAML_FILE = REPO_ROOT / "machine-readable" / "reference.yaml"
+REPORT_FILE = REPO_ROOT / "claudedocs" / "resync-report.md"
+
+# Files that reference.yaml points to (with bare integers → ultimate-guide.md)
+GUIDE_FILES = {
+ "guide/ultimate-guide.md": None,
+ "guide/architecture.md": None,
+ "guide/workflows/iterative-refinement.md": None,
+ "guide/observability.md": None,
+ "guide/learning-with-ai.md": None,
+ "guide/ai-ecosystem.md": None,
+ "guide/ai-traceability.md": None,
+ "guide/sandbox-isolation.md": None,
+ "guide/sandbox-native.md": None,
+ "guide/known-issues.md": None,
+ "guide/third-party-tools.md": None,
+ "guide/adoption-approaches.md": None,
+ "examples/commands/review-pr.md": None,
+ "examples/agents/code-reviewer.md": None,
+}
+
+
+def build_header_index(filepath: Path) -> list[tuple[int, str]]:
+ """Return list of (line_num, header_text) for all # headers."""
+ headers = []
+ try:
+ with open(filepath, encoding="utf-8") as f:
+ for i, line in enumerate(f, 1):
+ stripped = line.rstrip()
+ if stripped.startswith("#"):
+ headers.append((i, stripped))
+ except FileNotFoundError:
+ pass
+ return headers
+
+
+def get_line_content(filepath: Path, line_num: int, context: int = 2) -> str:
+ """Return content around a given line number."""
+ try:
+ with open(filepath, encoding="utf-8") as f:
+ lines = f.readlines()
+ start = max(0, line_num - 1 - context)
+ end = min(len(lines), line_num + context)
+ result = []
+ for i in range(start, end):
+ marker = ">>>" if i == line_num - 1 else " "
+ result.append(f"{marker} {i+1}: {lines[i].rstrip()}")
+ return "\n".join(result)
+ except FileNotFoundError:
+ return "(file not found)"
+
+
+def key_to_keywords(key: str) -> list[str]:
+ """Convert snake_case key to search keywords, filtering noise words."""
+ noise = {"the", "a", "an", "and", "or", "of", "in", "to", "for",
+ "is", "at", "by", "on", "it", "its", "from", "with",
+ "guide", "section", "line", "ref", "reference", "api",
+ "mode", "modes", "type", "types", "table", "example",
+ "examples", "list", "advanced", "basic", "overview", "vs"}
+ words = re.split(r"[_\-]", key.lower())
+ return [w for w in words if w not in noise and len(w) > 2]
+
+
+def score_header(keywords: list[str], header_text: str) -> int:
+ """Score a header based on keyword matches (higher = better)."""
+ header_lower = header_text.lower()
+ score = 0
+ for kw in keywords:
+ if kw in header_lower:
+ score += 1
+ # Partial match bonus
+ elif len(kw) > 4 and any(kw in w for w in header_lower.split()):
+ score += 0.5
+ return score
+
+
+def find_best_header(key: str, headers: list[tuple[int, str]],
+ old_line: int) -> tuple[int | None, float, str]:
+ """Find best matching header. Returns (new_line, confidence, header_text)."""
+ keywords = key_to_keywords(key)
+ if not keywords:
+ return None, 0.0, ""
+
+ best_score = 0
+ best_line = None
+ best_text = ""
+ second_best = 0
+
+ for line_num, header_text in headers:
+ score = score_header(keywords, header_text)
+ if score > best_score:
+ second_best = best_score
+ best_score = score
+ best_line = line_num
+ best_text = header_text
+ elif score > second_best:
+ second_best = score
+
+ if best_score == 0:
+ return None, 0.0, ""
+
+ # Confidence: high if best is clearly better than second best
+ if best_score >= 2 and (second_best == 0 or best_score / max(second_best, 0.1) >= 2):
+ confidence = min(1.0, best_score / max(len(keywords), 1))
+ else:
+ confidence = 0.4 * (best_score / max(len(keywords), 1))
+
+ return best_line, confidence, best_text
+
+
+def parse_yaml_line_refs(yaml_content: str) -> list[dict]:
+ """
+ Parse reference.yaml and extract all line number references.
+ Returns list of {key, file, old_line, yaml_line, raw_value}
+ """
+ results = []
+ in_main_guide_section = False
+ lines = yaml_content.split("\n")
+
+ for i, line in enumerate(lines, 1):
+ stripped = line.strip()
+ if not stripped or stripped.startswith("#"):
+ # Track if we're in the main guide section (bare integers = ultimate-guide.md)
+ if "# Main guide (guide/ultimate-guide.md)" in stripped:
+ in_main_guide_section = True
+ elif stripped.startswith("#") and in_main_guide_section:
+ # New major section — stop treating bare ints as ultimate-guide.md
+ # But keep it true since the pattern continues after comments
+ pass
+ continue
+
+ # Pattern 1: key: "filepath:NNNN" or key: "filepath:NNNN" # comment
+ m = re.match(r'^(\s*)(\S+):\s*"([^"]+):(\d+)"', line)
+ if m:
+ key = m.group(2).rstrip(":")
+ filepath = m.group(3)
+ line_num = int(m.group(4))
+ results.append({
+ "key": key,
+ "file": filepath,
+ "old_line": line_num,
+ "yaml_line": i,
+ "raw_value": f'"{filepath}:{line_num}"',
+ "type": "string_ref",
+ })
+ continue
+
+ # Pattern 2: key: NNNN (bare integer, implies ultimate-guide.md if in that section)
+ m = re.match(r'^(\s*)(\S+):\s*(\d{3,5})\s*(?:#.*)?$', line)
+ if m:
+ key = m.group(2).rstrip(":")
+ line_num = int(m.group(3))
+ # Heuristic: if line_num > 100 and key looks like a content reference
+ # (not a count, score, year etc.)
+ if line_num > 100 and not any(x in key for x in
+ ["count", "score", "stars", "year", "limit", "budget",
+ "savings", "total", "ratio", "budget", "sizing"]):
+ results.append({
+ "key": key,
+ "file": "guide/ultimate-guide.md",
+ "old_line": line_num,
+ "yaml_line": i,
+ "raw_value": str(line_num),
+ "type": "bare_int",
+ })
+
+ return results
+
+
+def validate_line(filepath: Path, line_num: int) -> str:
+ """Return the content at a given line (or error)."""
+ try:
+ with open(filepath, encoding="utf-8") as f:
+ lines = f.readlines()
+ if 1 <= line_num <= len(lines):
+ return lines[line_num - 1].rstrip()
+ return f"(line {line_num} out of range, file has {len(lines)} lines)"
+ except FileNotFoundError:
+ return "(file not found)"
+
+
+def is_sensible_content(key: str, content: str) -> bool:
+ """Quick check if content at old line is plausibly related to the key."""
+ if not content or content.startswith("("):
+ return False
+ keywords = key_to_keywords(key)
+ if not keywords:
+ return True
+ content_lower = content.lower()
+ matches = sum(1 for kw in keywords if kw in content_lower)
+ return matches >= max(1, len(keywords) // 2)
+
+
+def main():
+ apply_fixes = "--apply" in sys.argv
+
+ print("Reading reference.yaml...")
+ with open(YAML_FILE, encoding="utf-8") as f:
+ yaml_content = f.read()
+
+ print("Building header indexes...")
+ header_indexes = {}
+ for rel_path in GUIDE_FILES:
+ abs_path = REPO_ROOT / rel_path
+ idx = build_header_index(abs_path)
+ header_indexes[rel_path] = idx
+ if idx:
+ print(f" {rel_path}: {len(idx)} headers")
+ else:
+ print(f" {rel_path}: NOT FOUND or no headers")
+
+ print("\nParsing YAML references...")
+ refs = parse_yaml_line_refs(yaml_content)
+ print(f"Found {len(refs)} line number references")
+
+ report_lines = [
+ "# Re-sync Report: machine-readable/reference.yaml",
+ f"Generated: 2026-02-25",
+ f"Total references scanned: {len(refs)}",
+ "",
+ ]
+
+ corrections = [] # (yaml_line, old_value, new_value, key)
+ stats = {"ok": 0, "high": 0, "medium": 0, "low": 0, "unknown": 0, "file_missing": 0}
+
+ ok_entries = []
+ needs_fix = []
+
+ for ref in refs:
+ key = ref["key"]
+ rel_path = ref["file"]
+ old_line = ref["old_line"]
+ abs_path = REPO_ROOT / rel_path
+
+ current_content = validate_line(abs_path, old_line)
+ headers = header_indexes.get(rel_path, [])
+
+ if not headers and not abs_path.exists():
+ stats["file_missing"] += 1
+ needs_fix.append({**ref, "status": "FILE_MISSING", "new_line": None,
+ "confidence": 0, "current_content": current_content,
+ "suggested_header": ""})
+ continue
+
+ sensible = is_sensible_content(key, current_content)
+
+ if sensible:
+ stats["ok"] += 1
+ ok_entries.append({**ref, "current_content": current_content})
+ else:
+ new_line, confidence, header_text = find_best_header(key, headers, old_line)
+
+ if confidence >= 0.7:
+ level = "HIGH"
+ stats["high"] += 1
+ elif confidence >= 0.4:
+ level = "MEDIUM"
+ stats["medium"] += 1
+ elif new_line:
+ level = "LOW"
+ stats["low"] += 1
+ else:
+ level = "UNKNOWN"
+ stats["unknown"] += 1
+
+ needs_fix.append({
+ **ref,
+ "status": level,
+ "new_line": new_line,
+ "confidence": confidence,
+ "current_content": current_content,
+ "suggested_header": header_text,
+ })
+
+ if new_line and level in ("HIGH", "MEDIUM"):
+ if ref["type"] == "string_ref":
+ old_val = f'"{rel_path}:{old_line}"'
+ new_val = f'"{rel_path}:{new_line}"'
+ else:
+ old_val = str(old_line)
+ new_val = str(new_line)
+ corrections.append((ref["yaml_line"], old_val, new_val, key))
+
+ # Build report
+ report_lines += [
+ "## Summary",
+ "",
+ f"| Status | Count |",
+ f"|--------|-------|",
+ f"| OK (content matches) | {stats['ok']} |",
+ f"| HIGH confidence fix | {stats['high']} |",
+ f"| MEDIUM confidence fix | {stats['medium']} |",
+ f"| LOW confidence (manual review) | {stats['low']} |",
+ f"| UNKNOWN (no match found) | {stats['unknown']} |",
+ f"| FILE MISSING | {stats['file_missing']} |",
+ f"| **Total** | **{len(refs)}** |",
+ "",
+ f"Auto-fixable (HIGH + MEDIUM): **{stats['high'] + stats['medium']}**",
+ "",
+ ]
+
+ if needs_fix:
+ report_lines += ["## Entries Needing Correction", ""]
+ for entry in sorted(needs_fix, key=lambda x: (-x["confidence"], x["key"])):
+ status = entry["status"]
+ emoji = {"HIGH": "✅", "MEDIUM": "⚠️", "LOW": "🔶", "UNKNOWN": "❓", "FILE_MISSING": "🚫"}.get(status, "")
+ report_lines.append(f"### {emoji} {entry['key']} ({status}, conf={entry['confidence']:.2f})")
+ report_lines.append(f"- **File**: `{entry['file']}`")
+ report_lines.append(f"- **Old line**: {entry['old_line']}")
+ report_lines.append(f"- **Content at old line**: `{entry['current_content'][:100]}`")
+ if entry["new_line"]:
+ report_lines.append(f"- **Suggested line**: {entry['new_line']}")
+ report_lines.append(f"- **Header found**: `{entry['suggested_header']}`")
+ else:
+ report_lines.append(f"- **Suggested line**: (not found — manual search needed)")
+ report_lines.append("")
+
+ report_lines += ["## OK Entries (sample)", ""]
+ for entry in ok_entries[:20]:
+ report_lines.append(f"- `{entry['key']}`: line {entry['old_line']} → `{entry['current_content'][:80]}`")
+
+ report_content = "\n".join(report_lines)
+
+ # Write report
+ REPORT_FILE.parent.mkdir(exist_ok=True)
+ with open(REPORT_FILE, "w", encoding="utf-8") as f:
+ f.write(report_content)
+ print(f"\nReport saved to {REPORT_FILE}")
+
+ # Print summary
+ print(f"\n{'='*60}")
+ print(f"OK: {stats['ok']}")
+ print(f"HIGH fix: {stats['high']}")
+ print(f"MEDIUM fix: {stats['medium']}")
+ print(f"LOW fix: {stats['low']}")
+ print(f"UNKNOWN: {stats['unknown']}")
+ print(f"FILE MISSING: {stats['file_missing']}")
+ print(f"Auto-fixable: {stats['high'] + stats['medium']}")
+ print(f"{'='*60}")
+
+ if corrections:
+ print(f"\n{'='*60}")
+ print("PROPOSED CORRECTIONS (HIGH + MEDIUM confidence):")
+ print(f"{'='*60}")
+ for yaml_line, old_val, new_val, key in corrections[:30]:
+ print(f" Line {yaml_line:4d} | {key}")
+ print(f" {old_val} → {new_val}")
+ if len(corrections) > 30:
+ print(f" ... and {len(corrections) - 30} more (see report)")
+
+ if apply_fixes and corrections:
+ print(f"\nApplying {len(corrections)} fixes to reference.yaml...")
+ content = yaml_content
+ applied = 0
+ for yaml_line_num, old_val, new_val, key in corrections:
+ # Find the exact occurrence of old_val near the yaml_line_num
+ # Use line-by-line replacement to be precise
+ lines = content.split("\n")
+ target_idx = yaml_line_num - 1
+ if target_idx < len(lines) and old_val in lines[target_idx]:
+ lines[target_idx] = lines[target_idx].replace(old_val, new_val, 1)
+ applied += 1
+ else:
+ # Try ±2 lines
+ for delta in [-1, 1, -2, 2]:
+ idx = target_idx + delta
+ if 0 <= idx < len(lines) and old_val in lines[idx]:
+ lines[idx] = lines[idx].replace(old_val, new_val, 1)
+ applied += 1
+ break
+ content = "\n".join(lines)
+
+ with open(YAML_FILE, "w", encoding="utf-8") as f:
+ f.write(content)
+ print(f"Applied {applied}/{len(corrections)} fixes.")
+ print(f"Run without --apply to verify remaining issues.")
+ elif not apply_fixes and corrections:
+ print(f"\nRun with --apply to apply HIGH+MEDIUM confidence fixes automatically.")
+ print(f"LOW and UNKNOWN confidence fixes require manual review (see report).")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/tools/onboarding-prompt.md b/tools/onboarding-prompt.md
index 0b3547e..053a914 100644
--- a/tools/onboarding-prompt.md
+++ b/tools/onboarding-prompt.md
@@ -223,7 +223,7 @@ Based on the goal from Phase 0, ask ONLY the necessary additional questions:
When presenting security topics, add a hands-on option alongside the usual depth controls:
- After sandbox/permissions topic → "Try: Run `/security-check` to scan your current setup"
- After threat intelligence topic → "Try: Check your installed skills against known malicious patterns"
- - After MCP vetting topic → "Try: Review your `~/.claude/mcp.json` against the MCP Safe List"
+ - After MCP vetting topic → "Try: Review your `~/.claude.json` against the MCP Safe List"
4. **Depth control**: Use AskUserQuestion with options:
- "Go deeper" → Provide detailed explanation with examples