hail-hydra-cc 2.0.4 → 2.1.1

package/files/SKILL.md

@@ -178,6 +178,54 @@ The index is stale if:
 - The user switches to a different project/directory
 When stale, rebuild the index on the next scout dispatch.
 
+## Codebase Map — Orchestrator Protocol
+
+Hydra maintains a codebase map at `.claude/hydra/codebase-map.json`. This map
+is built and maintained by hydra-scout. It contains file dependencies, blast
+radius data, risk scores, env var references, and test coverage.
+
+### Session Start — Map Check
+
+At the start of EVERY session, before any work:
+
+1. Check if `.claude/hydra/codebase-map.json` exists.
+2. If yes: read the `_meta` section. Check if `git_hash` matches current HEAD.
+   - If current: map is ready. Note this internally.
+   - If stale: dispatch hydra-scout to do an incremental update before proceeding.
+3. If no: dispatch hydra-scout to build the map on the first exploration task.
+   Don't block the session — but prioritize building the map early.
+
+### Risk-Based Sentinel Triggering
+
+Use the map's risk scores to decide sentinel behavior:
+
+| Modified File Risk | Sentinel Behavior |
+|-------------------|-------------------|
+| `critical` (7+ dependents) | ALWAYS run sentinel-scan, ALWAYS escalate to deep |
+| `high` (4-6 dependents) | ALWAYS run sentinel-scan, escalate if issues found |
+| `medium` (2-3 dependents) | Run sentinel-scan, escalate only if P0 issues found |
+| `low` (0-1 dependents) | Run sentinel-scan, but auto-accept if clean |
+
+This replaces the previous "always run sentinel-scan the same way" approach
+with risk-proportional verification.
+
+### When Dispatching Sentinel-Scan
+
+Include the map's relevant data in the task description:
+- The blast radius for the changed files (from the map)
+- The risk score of each changed file
+- The test coverage status of each changed file
+- Any env vars referenced by the changed files
+
+This gives sentinel-scan a head start — it doesn't need to compute the
+blast radius itself, the map already has it.
+
+### Map Staleness
+
+If you notice the map's git_hash doesn't match HEAD and hydra-scout hasn't
+been dispatched yet, dispatch scout to update the map BEFORE running sentinel.
+A stale map is worse than no map — it could have incorrect dependency data.
+
 ## Blocking vs Non-Blocking Dispatch
 
 Not all agents need to finish before the next wave starts. Classify each dispatch as
@@ -782,6 +830,7 @@ the command's instructions:
 | `/hydra:update` | Trigger an update via npx |
 | `/hydra:config` | Show current configuration |
 | `/hydra:guard [files]` | Manually invoke the security scan on specified files |
+| `/hydra:map [file]` | View, rebuild, or query the codebase dependency map |
 | `/hydra:quiet` | Suppress dispatch logs for this session |
 | `/hydra:verbose` | Enable detailed dispatch logs with timing |
 
@@ -921,12 +970,13 @@ If the user types any of these exact phrases, respond with the corresponding act
 | `hydra quiet` | Suppress dispatch logs for the rest of the session (equivalent to stealth mode) |
 | `hydra verbose` | Enable verbose dispatch logs with per-agent detail for the rest of the session |
 | `hydra reset` | Clear session index, treat next turn as Turn 1 (rebuild from fresh scout) |
+| `hydra map` | Show codebase map summary, or query a specific file's blast radius |
 
 ## The Nine Heads
 
 | Head | Model | Role | Tools |
 |------|-------|------|-------|
-| `hydra-scout` | 🟢 Haiku 4.5 | Codebase exploration, file search, reading | Read, Grep, Glob |
+| `hydra-scout` | 🟢 Haiku 4.5 | Codebase exploration, file search, reading, map building | Read, Grep, Glob, Bash, Write |
 | `hydra-runner` | 🟢 Haiku 4.5 | Test execution, builds, linting, validation | Read, Bash, Glob, Grep |
 | `hydra-scribe` | 🟢 Haiku 4.5 | Documentation, READMEs, comments, changelogs | Read, Write, Edit, Glob, Grep |
 | `hydra-guard` | 🟢 Haiku 4.5 | Security/quality gate after code changes | Read, Grep, Glob, Bash |

package/files/agents/hydra-scout.md

@@ -1,14 +1,15 @@
 ---
 name: hydra-scout
 description: >
-  🟢 Hydra's fastest head — ultra-fast codebase exploration and information retrieval.
-  Use PROACTIVELY whenever Claude needs to search files, read code, find patterns, grep for
-  strings, list directories, understand project structure, or answer "where is X?" questions.
+  🟢 Hydra's fastest head — ultra-fast codebase exploration, information retrieval,
+  and codebase map building/maintenance. Use PROACTIVELY whenever Claude needs to search
+  files, read code, find patterns, grep for strings, list directories, understand project
+  structure, answer "where is X?" questions, or build/update the codebase dependency map.
   This is the first head to reach for when gathering information before making changes.
   Runs on Haiku 4.5 for near-instant responses.
   May run in parallel with other Hydra agents — produces self-contained, clearly structured
   output so the orchestrator can merge results from multiple simultaneous agents.
-tools: Read, Grep, Glob
+tools: Read, Grep, Glob, Bash, Write
 model: haiku
 color: "#10B981"
 memory: project
@@ -27,6 +28,7 @@ directory organization patterns. Keep notes concise — 1-2 lines per finding.
 - Reading and summarizing code structure
 - Finding patterns, imports, usages, and dependencies
 - Mapping directory structures and project organization
+- Building and maintaining the codebase dependency map (imports, risk scores, test coverage)
 - Answering "where is X?" and "what does Y look like?" questions
 
 ## How to Work
@@ -53,11 +55,135 @@ directory organization patterns. Keep notes concise — 1-2 lines per finding.
 
 ## Boundaries
 
-- Never modify files
-- Never run commands
+- Never modify source files (the codebase map is generated output, not source code)
 - Never make architectural decisions
 - Never guess when you can search — always verify
 
+## Codebase Map — Building & Maintenance
+
+You are responsible for building and maintaining the codebase map at
+`.claude/hydra/codebase-map.json`. This map is used by sentinel, the
+orchestrator, and other agents to understand file dependencies without
+scanning the entire codebase.
+
+### When to Build
+
+At the START of every task where you're dispatched for exploration:
+
+1. Check if `.claude/hydra/codebase-map.json` exists
+2. If it exists, check `_meta.git_hash` against current `git rev-parse HEAD`
+   - If they match: map is current. Skip rebuild. Use the existing map.
+   - If they differ: do an INCREMENTAL update (see below).
+3. If it doesn't exist: do a FULL build.
+
+### Full Build
+
+Run these steps to build the complete map:
+
+1. Find all source files (exclude node_modules, .git, dist, build, vendor,
+   __pycache__, .next, .nuxt, coverage, .claude):
+   ```bash
+   find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \
+     -o -name "*.py" -o -name "*.go" -o -name "*.java" -o -name "*.kt" \
+     -o -name "*.rb" -o -name "*.rs" -o -name "*.vue" -o -name "*.svelte" \) \
+     ! -path "*/node_modules/*" ! -path "*/.git/*" ! -path "*/dist/*" \
+     ! -path "*/build/*" ! -path "*/vendor/*" ! -path "*/__pycache__/*" \
+     ! -path "*/.next/*" ! -path "*/.nuxt/*" ! -path "*/coverage/*" \
+     ! -path "*/.claude/*" | sort
+   ```
+
+2. For each file, extract import statements using grep/regex:
+   - **JS/TS**: `import ... from '...'`, `require('...')`, `import('...')`, `export ... from '...'`
+   - **Python**: `import module`, `from module import ...`
+   - **Go**: `import "package/path"`, `import ( "package/path" )`
+   - **Java/Kotlin**: `import package.name.ClassName`
+   - **Ruby**: `require '...'`, `require_relative '...'`
+
+3. Resolve relative imports to project-relative paths:
+   - `import { x } from './auth'` in `src/api/users.ts` → `src/services/auth.ts`
+   - Try extensions: `.ts`, `.tsx`, `.js`, `.jsx`, `/index.ts`, `/index.js`
+   - `from ..models.user import User` in `src/services/auth.py` → `src/models/user.py`
+   - **Ignore**: node_modules imports (third-party), standard library imports, anything
+     that doesn't resolve to a file in the project
+
+4. Build the `imported_by` reverse index:
+   - For every file A that imports file B, add A to B's `imported_by` array.
+
+5. Calculate risk scores based on `dependents_count` (length of `imported_by`):
+   - `"low"` — 0-1 dependents
+   - `"medium"` — 2-3 dependents
+   - `"high"` — 4-6 dependents
+   - `"critical"` — 7+ dependents
+
+6. Detect test coverage for each file:
+   - `"covered"` — at least one file in `tests/` or `__tests__/` imports it,
+     OR a file named `*.test.*` or `*.spec.*` imports it
+   - `"partial"` — the file is in a directory where >50% of sibling files have
+     tests but this one doesn't
+   - `"untested"` — no test file imports it and it's not in a well-tested directory
+
+7. Detect environment variable references across all source files:
+   - **JS/TS**: `process.env.VARIABLE_NAME`, `process.env['VARIABLE_NAME']`, `process.env["VARIABLE_NAME"]`
+   - **Python**: `os.environ["VARIABLE_NAME"]`, `os.environ.get("VARIABLE_NAME")`, `os.getenv("VARIABLE_NAME")`
+   - **Go**: `os.Getenv("VARIABLE_NAME")`
+   - **Ruby**: `ENV["VARIABLE_NAME"]`, `ENV.fetch("VARIABLE_NAME")`
+   - **General**: `.env` file parsing (`KEY=VALUE` lines)
+
+8. Write the complete map to `.claude/hydra/codebase-map.json` with this schema:
+   ```json
+   {
+     "_meta": {
+       "built_at": "2026-03-26T10:00:00Z",
+       "git_hash": "a1b2c3d4e5f6",
+       "file_count": 487,
+       "builder": "hydra-scout",
+       "version": "1.0"
+     },
+     "files": {
+       "src/services/auth.ts": {
+         "imports": ["src/models/user.ts", "src/config/env.ts"],
+         "imported_by": ["src/api/users.ts", "src/api/admin.ts"],
+         "risk": "medium",
+         "dependents_count": 2,
+         "tested_by": ["tests/auth.test.ts"],
+         "test_coverage": "covered"
+       }
+     },
+     "env_vars": {
+       "DATABASE_URL": ["src/db/connection.ts", "src/config/index.ts"],
+       "JWT_SECRET": ["src/services/auth.ts"]
+     }
+   }
+   ```
+
+9. Add `.claude/hydra/codebase-map.json` to `.gitignore` if not already there
+   (the map is machine-generated and project-specific).
+
+### Incremental Update
+
+When the git hash has changed since the last build:
+
+1. Run `git diff --name-only <old_hash> HEAD` to find changed files.
+2. For each changed file:
+   - Re-extract its imports
+   - Update its entry in the map
+   - Recalculate its test coverage
+   - Re-check its env var references
+3. Rebuild the `imported_by` reverse index (since dependencies may have changed).
+4. Recalculate risk scores for affected files.
+5. Update `_meta.git_hash` and `_meta.built_at`.
+
+Incremental updates should be MUCH faster than full builds — for 5 changed
+files in a 500-file project, you re-process 5 files instead of 500.
+
+### After Building — Update Your Memory
+
+Note in your memory:
+- When the map was last built
+- How many files are in the project
+- Which directories are the most interconnected
+- Any files that failed to parse (unusual import syntax)
+
 ## Collaboration Protocol
 
 You may be running in parallel with other Hydra agents. Your output must be:

package/files/agents/hydra-sentinel-scan.md

@@ -7,7 +7,7 @@ description: >
   If issues are found, the orchestrator escalates to hydra-sentinel for
   deep analysis. If clean — done, zero additional cost.
 model: haiku
-tools: Read, Grep, Glob
+tools: Read, Grep, Glob, Bash
 memory: project
 ---
 
@@ -40,7 +40,61 @@ You receive a summary of what changed:
 - What functions/classes/exports changed
 - The git diff (if available)
 
-## Scan Checklist (run ALL of these)
+## Codebase Map Integration
+
+Before scanning, check if `.claude/hydra/codebase-map.json` exists.
+
+### If the map EXISTS (preferred path):
+
+Use the map for all dependency checks. This is MUCH faster and more accurate
+than grepping.
+
+#### P0 — Import/Export Chain Integrity
+1. For every file that was modified, read its entry from the map.
+2. Check `imported_by` — these are the files that depend on it.
+3. For each dependent file, verify the imports are still valid:
+   - Was anything renamed or removed that the dependent file uses?
+   - Read ONLY the dependent files (not the whole codebase).
+
+#### P0 — Blast Radius Assessment
+1. For every modified file, compute the blast radius:
+   - First degree: files in `imported_by` (direct dependents)
+   - Second degree: for each first-degree file, check ITS `imported_by`
+   - Stop at second degree (deeper is diminishing returns)
+2. Report the total blast radius count in your output.
+
+#### P0 — Function Signature Changes
+1. Read the modified file and its first-degree dependents (from the map).
+2. Check if function signatures changed and callers still match.
+
+#### P1 — Environment Variable Check
+1. Read the `env_vars` section of the map.
+2. For every new `process.env.X` (or equivalent) in the changed files:
+   - Check if X exists in the `env_vars` index already.
+   - If not: grep `.env`, `.env.example`, and config files for X.
+   - Flag if X is not defined anywhere.
+
+#### P1 — Risk-Based Severity
+1. Read the `risk` field for each modified file.
+2. If a `critical` or `high` risk file was modified:
+   - ALWAYS escalate to sentinel deep analysis, even if no obvious issues found.
+   - The blast radius is too large to trust a fast scan alone.
+3. If a `low` risk file was modified and no issues found:
+   - Report clean with high confidence.
+
+#### P2 — Test Coverage Warning
+1. Read the `test_coverage` field for each modified file.
+2. If a modified file has `"test_coverage": "untested"`:
+   - Add an INFO-level note: "This file has no test coverage. Consider adding tests."
+   - If sentinel also finds integration issues in this file, escalate severity.
+
+### If the map DOES NOT EXIST (fallback):
+
+Fall back to the existing grep-based scanning (the Scan Checklist below).
+This ensures sentinel-scan works even if the map hasn't been built yet.
+Recommend that the user/orchestrator run hydra-scout to build the map.
+
+## Scan Checklist — Grep Fallback (run ALL when map unavailable)
 
 ### P0 — Import/Export Chain Integrity
 1. For every function, class, variable, or type that was RENAMED or DELETED:
@@ -89,9 +143,13 @@ Return a JSON object:
 ```json
 {
   "status": "clean",
+  "map_used": true,
   "files_scanned": 12,
+  "blast_radius": 3,
+  "blast_radius_files": ["src/api/users.ts", "src/middleware/auth.ts", "src/routes/index.ts"],
   "checks_passed": 6,
-  "summary": "No integration issues found."
+  "untested_files_modified": [],
+  "summary": "No integration issues found. Blast radius: 3 files."
 }
 ```
 
@@ -99,7 +157,10 @@ Return a JSON object:
 ```json
 {
   "status": "issues_found",
+  "map_used": true,
   "files_scanned": 12,
+  "blast_radius": 12,
+  "blast_radius_files": ["src/api/users.ts", "src/middleware/auth.ts", "..."],
   "checks_passed": 4,
   "checks_failed": 2,
   "issues": [
@@ -120,10 +181,15 @@ Return a JSON object:
       "suggestion": "Add REDIS_URL to .env and .env.example"
     }
   ],
-  "summary": "2 integration issues found. Escalating to deep analysis."
+  "untested_files_modified": ["src/services/cache.ts"],
+  "summary": "2 integration issues found. Blast radius: 12 files. Escalating."
 }
 ```
 
+> **Note:** When the map is not available, set `"map_used": false` and omit
+> `blast_radius`, `blast_radius_files`, and `untested_files_modified` fields.
+> The output otherwise follows the same format.
+
 ## IMPORTANT
 
 - Do NOT attempt to fix anything. Report only.
@@ -139,3 +205,19 @@ You may be running in parallel with other Hydra agents. Your output must be:
 - **Clearly structured** — use the JSON format above so the orchestrator can parse it
 - **Focused on YOUR task only** — integration integrity, nothing else
 - **Actionable** — every issue includes file:line and a specific suggestion
+
+## Cleanup: Clear Sentinel Pending Flag
+
+After completing your scan (whether clean or issues found), clear the
+sentinel pending flag by deleting the flag file:
+```bash
+rm -f /tmp/hydra-sentinel/${session_id}-pending.json
+```
+
+Use the session_id from your context. This clears the "⚠ Sentinel pending"
+warning from the status bar.
+
+If you can't determine the session_id, run:
+```bash
+rm -f /tmp/hydra-sentinel/*-pending.json
+```

package/files/agents/hydra-sentinel.md

@@ -43,6 +43,33 @@ After analysis, update your memory with:
 2. The sentinel-scan report (JSON with flagged issues)
 3. Context from the orchestrator about what task was being performed
 
+## Codebase Map Integration
+
+Before analyzing, read `.claude/hydra/codebase-map.json` if it exists.
+
+### How to Use the Map
+
+1. **Understand the blast radius before reading files.**
+   The map tells you which files depend on the changed files. Read the
+   blast radius files FIRST — these are the most likely to have issues.
+
+2. **Check env_vars section for missing variables.**
+   The map's env_vars index tells you every env var reference in the project.
+   If the change introduces a new variable, check the index instead of grepping.
+
+3. **Use risk scores to prioritize.**
+   Focus your deepest analysis on `critical` and `high` risk files. For `low`
+   risk files, a quick check is sufficient.
+
+4. **Flag untested files.**
+   If a file with integration issues also has `"test_coverage": "untested"`,
+   escalate the severity and explicitly recommend adding tests.
+
+5. **Cross-reference test coverage.**
+   The map's `tested_by` field tells you which test files cover each source file.
+   If you confirm a real issue, you can tell the user exactly which tests to run
+   to verify the fix: "Run tests/auth.test.ts to verify this fix."
+
 ## Deep Analysis Checklist
 
 ### For EVERY issue flagged by sentinel-scan:

package/files/commands/hydra/help.md

@@ -16,6 +16,7 @@ COMMANDS
   /hydra:config    Show current configuration
   /hydra:guard     Run security scan on files (usage: /hydra:guard src/auth.py)
   /hydra:quiet     Suppress dispatch logs for this session
+  /hydra:map       View, rebuild, or query the codebase map
   /hydra:verbose   Enable verbose dispatch logs with timing
   /hydra:report    Report a bug, request a feature, or share feedback
 

package/files/commands/hydra/map.md

@@ -0,0 +1,100 @@
+---
+description: View, rebuild, or query the codebase dependency map
+allowed-tools: Bash, Read
+---
+
+# Hydra Map
+
+Manage the codebase dependency map.
+
+## If no arguments provided: Show Summary
+
+Read `.claude/hydra/codebase-map.json` and display a summary:
+
+```
+🐉 Hydra Codebase Map
+══════════════════════════════════
+Status:     ✅ Current (matches HEAD)
+Files:      487 mapped
+Built:      2026-03-26 10:00:00
+Git hash:   a1b2c3d
+
+Risk Distribution:
+  🔴 Critical (7+ deps):   8 files
+  🟠 High (4-6 deps):     23 files
+  🟡 Medium (2-3 deps):   89 files
+  🟢 Low (0-1 deps):     367 files
+
+Test Coverage:
+  ✅ Covered:    234 files (48%)
+  🟡 Partial:    78 files (16%)
+  ❌ Untested:  175 files (36%)
+
+Environment Variables: 12 tracked across 28 files
+
+Top 5 Highest-Risk Files:
+  src/services/auth.ts      (12 dependents) 🔴
+  src/utils/helpers.ts      (9 dependents)  🔴
+  src/config/index.ts       (8 dependents)  🔴
+  src/models/user.ts        (7 dependents)  🔴
+  src/middleware/cors.ts     (6 dependents)  🟠
+```
+
+If the map file doesn't exist, display:
+```
+🐉 Hydra Codebase Map
+══════════════════════════════════
+Status:     ❌ Not built
+
+No codebase map found. Run /hydra:map rebuild to build one,
+or it will be built automatically on the next hydra-scout dispatch.
+```
+
+If the map exists but `_meta.git_hash` doesn't match current `git rev-parse HEAD`:
+```
+Status:     ⚠️ Stale (map: a1b2c3d, HEAD: e4f5g6h)
+```
+
+## If argument is "rebuild": Force Rebuild
+
+Dispatch hydra-scout to do a complete rebuild of the map, regardless of
+staleness. Show progress and report when done.
+
+## If argument is a file path: Show Blast Radius
+
+Read the map entry for that file and display:
+
+```
+🐉 Blast Radius: src/services/auth.ts
+══════════════════════════════════════
+Risk: 🔴 CRITICAL (12 dependents)
+Test Coverage: ✅ Covered (tests/auth.test.ts, tests/integration/login.test.ts)
+
+Imports (this file depends on):
+  → src/models/user.ts
+  → src/config/env.ts
+
+Imported By (depends on this file):
+  1st degree (direct):
+    ← src/api/users.ts
+    ← src/api/admin.ts
+    ← src/middleware/auth.ts
+  2nd degree (indirect):
+    ← src/routes/index.ts (via api/users.ts)
+    ← src/app.ts (via middleware/auth.ts)
+
+Total Blast Radius: 5 files
+
+Environment Variables Referenced:
+  JWT_SECRET (also used in: src/middleware/auth.ts)
+  AUTH_TIMEOUT (also used in: src/config/index.ts)
+
+⚠ Changing this file could impact 5 other files.
+  Run sentinel after any modifications.
+```
+
+If the file is not found in the map, display:
+```
+File not found in codebase map: <file_path>
+The map may be stale. Run /hydra:map rebuild to refresh.
+```

package/files/commands/hydra/status.md

@@ -43,6 +43,16 @@ cat .claude/skills/hydra/config/hydra.config.md 2>/dev/null || \
 echo "No config file found (using defaults)"
 ```
 
+## 6. Codebase Map
+```bash
+if [ -f ".claude/hydra/codebase-map.json" ]; then
+  echo "Map: ✅ Exists"
+  node -e "const m=JSON.parse(require('fs').readFileSync('.claude/hydra/codebase-map.json','utf8'));console.log('Files:',m._meta.file_count);console.log('Built:',m._meta.built_at);console.log('Hash:',m._meta.git_hash);"
+else
+  echo "Map: ❌ Not built yet (run /hydra:map rebuild)"
+fi
+```
+
 ## Display Format
 
 Present results as a clean status card:
@@ -60,8 +70,9 @@ Agents (7):
   🟢 hydra-git      (Haiku 4.5)   ✅
   🔵 hydra-coder    (Sonnet 4.6)  ✅
   🔵 hydra-analyst  (Sonnet 4.6)  ✅
-Commands (7): update, status, help, config, guard, quiet, verbose
-Hooks (3):    check-update ✅, statusline ✅, auto-guard ✅
+Commands (9): update, status, help, config, guard, quiet, verbose, report, map
+Hooks (4):    check-update ✅, statusline ✅, auto-guard ✅, notify ✅
+Map:          ✅ Current (487 files, built 2026-03-26)
 Config:       balanced mode, dispatch log on, auto-guard on
 ──────────────────────────────
 ```

package/files/references/model-capabilities.md

@@ -32,9 +32,21 @@ Haiku outputs qualify for auto-accept when they are raw, factual, and unambiguou
 - **hydra-scribe**: Internal docstrings, inline comments, changelog entries
 - **Requires verify**: Any analysis, interpretation, or user-facing documentation
 
-### hydra-sentinel-scan (Haiku 4.5)
+### hydra-scout (Haiku 4.5) — Updated in v2.1.0
+- **Strengths**: Codebase exploration, file search, reading, AND codebase
+  map building/maintenance
+- **New capability**: Builds and incrementally updates the codebase dependency
+  map using grep-based import extraction. No external parsers required.
+- **Memory focus**: Codebase structure, key file locations, module boundaries,
+  map build history, files that failed to parse
+
+### hydra-sentinel-scan (Haiku 4.5) — Updated in v2.1.0
 - **Strengths**: Pattern matching, grep-level analysis, import tracing,
-  fast structural checks
+  fast structural checks, AND map-based instant blast-radius lookups
+- **New capability**: Reads codebase map for instant dependency lookups
+  instead of grepping. Falls back to grep if map doesn't exist.
+- **Map-aware checks**: Risk-based severity, test coverage warnings,
+  env var index lookups, blast radius reporting
 - **Limitations**: Cannot understand semantic meaning of data shapes,
   may produce false positives on complex contract changes
 - **Memory focus**: Codebase dependency graph, coupling patterns,

package/files/references/routing-guide.md

@@ -156,6 +156,34 @@ These are tasks that look like one tier but are actually another:
 
 ---
 
+## Map-Aware Routing Examples
+
+These examples show how the codebase map changes routing decisions by providing
+risk scores and blast radius data upfront.
+
+### "Fix the bug in auth.ts"
+1. Check map: auth.ts has risk=critical, 12 dependents
+2. hydra-scout → verify map is current (incremental update if needed)
+3. hydra-analyst → diagnose the bug
+4. hydra-coder → implement the fix
+5. hydra-sentinel-scan → map shows blast radius of 12 files, check all 12
+   (without map, would have to grep the entire codebase)
+6. hydra-sentinel → deep analysis (auto-escalated because risk=critical)
+
+### "Add a new utility function"
+1. Check map: new file, risk=low (zero dependents initially)
+2. hydra-coder → write the function
+3. hydra-sentinel-scan → low risk, quick scan, auto-accept if clean
+   (without map, would run the same expensive scan as a critical file)
+
+### "Refactor the database connection module"
+1. Check map: src/db/connection.ts has risk=critical, 15 dependents
+2. Plan execution with full blast radius awareness
+3. Dispatch parallel hydra-coders for each affected file
+4. Sentinel deep analysis is MANDATORY (critical risk)
+
+---
+
 ## Quick Decision Flowchart
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hail-hydra-cc",
-  "version": "2.0.4",
+  "version": "2.1.1",
   "description": "Multi-headed speculative execution framework for Claude Code",
   "bin": {
     "hail-hydra-cc": "bin/cli.js"

package/src/display.js

@@ -42,7 +42,7 @@ function showInstallComplete(statusLineConfigured = true) {
   console.log(chalk.cyan.bold('  \uD83D\uDC09 Hail Hydra! Framework deployed and ready.'));
   console.log(chalk.gray('  ' + '\u2500'.repeat(45)));
   console.log(chalk.green(`    \u2714 9 agents installed`));
-  console.log(chalk.green(`    \u2714 8 slash commands installed`));
+  console.log(chalk.green(`    \u2714 9 slash commands installed`));
   console.log(chalk.green(`    \u2714 4 hooks registered`));
   if (statusLineConfigured) {
     console.log(chalk.green(`    \u2714 StatusLine configured`));
@@ -50,9 +50,11 @@ function showInstallComplete(statusLineConfigured = true) {
     console.log(chalk.yellow(`    \u26a0 StatusLine skipped (existing config preserved)`));
   }
   console.log(chalk.green(`    \u2714 Sentinel pipeline active`));
+  console.log(chalk.green(`    \u2714 Codebase map ready (run /hydra:map rebuild)`));
   console.log(chalk.green(`    \u2714 Version tracked (${VERSION})`));
   console.log();
   console.log(chalk.gray('  Quick start:  /hydra:help'));
+  console.log(chalk.gray('  Build map:    /hydra:map rebuild'));
   console.log(chalk.gray('  Check status: /hydra:status'));
   console.log(chalk.gray('  GitHub: https://github.com/AR6420/Hail_Hydra'));
   console.log();

package/src/files.js

@@ -81,6 +81,7 @@ const commands = {
   'quiet':    readBundled('commands/hydra/quiet.md'),
   'verbose':  readBundled('commands/hydra/verbose.md'),
   'report':   readBundled('commands/hydra/report.md'),
+  'map':      readBundled('commands/hydra/map.md'),
 };
 
 const hooks = {