@vyuhlabs/dxkit 2.6.0 → 2.7.0

package/templates/.claude/skills/dxkit-action/SKILL.md

@@ -11,7 +11,7 @@ This skill takes a dxkit report and drives the fix loop with the user. Reach for
 
 ```
 [1] Read the report          → understand what's flagged
-[2] Prioritize               → severity + reachability + cost
+[2] Prioritize               → severity + reachability + blast radius + cost
 [3] Plan                     → ordered list of edits
 [4] Execute                  → fix one finding at a time
 [5] Verify                   → re-run the analyzer, confirm score moved
@@ -20,6 +20,14 @@ This skill takes a dxkit report and drives the fix loop with the user. Reach for
 
 Don't skip [5]. Re-running the analyzer is the only way to confirm the fix landed correctly.
 
+For the richest input, read the **detailed** report with graph context attached:
+
+```bash
+npx vyuh-dxkit vulnerabilities --detailed --graph-context   # or test-gaps / quality
+```
+
+`--graph-context` adds a "Graph context" column (the module a finding lives in + its blast radius — how many files call into it) so you can plan the fix without separately discovering structure. It's a structural HINT, not ground truth — read "Graph context" below for how to use it safely.
+
 ## Priority order
 
 Walk findings in this order (highest to lowest):
@@ -33,6 +41,18 @@ Walk findings in this order (highest to lowest):
 
 Skip items where reachability is "no" (graphify can't find a call path) UNLESS the finding is a secret leak (those don't depend on reachability).
 
+## Graph context (structural blast radius)
+
+When the report was generated with `--graph-context`, each finding carries a "Graph context" cell: the module/role it belongs to and its **blast radius** (`role · N caller files`) — how many other files call into the finding's file. Use it to sharpen prioritization and planning, under three hard rules.
+
+**1. Additive only — it never overrides severity or reachability.** Blast radius is a tie-breaker between findings of similar severity, not a re-ranking of the priority list above. Among two HIGH findings, fix the one with the larger blast radius first (more depends on it). A LOW finding never jumps a HIGH one because its blast radius is bigger.
+
+**2. A blank or zero blast radius is NOT "safe to change".** The cell reads `blast radius n/a (call graph)` for languages whose call graph the analyzer can't resolve (C# is the known case — cross-assembly references aren't followed, so heavily-used files look like they have zero callers). Treat n/a — and even a literal `0 caller files` — as **unknown**, never as evidence the file is safe to edit freely. When blast radius is n/a, fall back to the module/role label (that part is reliable) and verify callers the normal way (grep / read) before a risky edit. Do **not** deprioritize a real finding just because its blast radius is empty.
+
+**3. Confirm the symbol before you act on it.** The context may name an enclosing symbol (the function the finding sits in). It's a best-effort guess (the graph stores declaration lines, not end lines), so open the file and confirm the finding is actually inside that symbol before editing or writing a test against it.
+
+Used within those rules, the win is concrete: a high blast radius tells you which caller files to re-check and re-test in step [5] after the fix, and the module label orients you fast. Same-name symbols can inflate the count — a suspiciously huge number is usually conflation, not reality.
+
 ## Common fix recipes
 
 ### Secret in code

package/templates/.claude/skills/dxkit-reports/SKILL.md

@@ -19,7 +19,9 @@ This skill runs dxkit analyzers and reads their output back to the user. It's th
 | "License inventory" | `npx vyuh-dxkit licenses` | Every dependency's declared license |
 | "Bill of materials" | `npx vyuh-dxkit bom` | Licenses + dep vulnerabilities joined (15-col XLSX-ready output) |
 | "Run everything" | `npx vyuh-dxkit report` | Every analyzer in one shot, ~3-5 min |
-| "Show me the dashboard" | `npx vyuh-dxkit dashboard` | Single HTML view of all reports — opens at `.dxkit/reports/dashboard.html` |
+| "Show me the dashboard" | `npx vyuh-dxkit dashboard` | Single HTML view of all reports — opens at `.dxkit/reports/dashboard.html`, incl. an interactive **Graph** tab (code structure) |
+| "What does this repo do / where is X" | `npx vyuh-dxkit explore <sub>` | Query the code graph: entry-points / hot-files / communities / file / feature / api-surface |
+| "Token-efficient context for a query" | `npx vyuh-dxkit context <query>` | Slim structural slice for an LLM (also a fix-time hint via `--graph-context`) |
 
 ## Where output lands
 

package/templates/AGENTS.md.template

@@ -114,12 +114,19 @@ Reach for the relevant skill when working in this repo. They wrap the `vyuh-dxki
 | Test coverage gaps | `npx vyuh-dxkit test-gaps` |
 | Code quality + slop | `npx vyuh-dxkit quality` |
 | Bill of materials | `npx vyuh-dxkit bom` |
-| Dashboard (HTML) | `npx vyuh-dxkit dashboard` |
+| Dashboard (HTML, incl. interactive Graph tab) | `npx vyuh-dxkit dashboard` |
+| What does this repo do / where does X live | `npx vyuh-dxkit explore <sub>` |
+| Token-efficient structural context for a query | `npx vyuh-dxkit context <query>` |
 | Guardrail check (baseline diff) | `npx vyuh-dxkit guardrail check` |
 | Doctor (verify setup) | `npx vyuh-dxkit doctor` |
 
 The pre-push hook runs `guardrail check` automatically — blocks net-new regressions before they leave your machine.
 
+When fixing findings, run the detailed report with `--graph-context`
+(e.g. `npx vyuh-dxkit vulnerabilities --detailed --graph-context`) — it
+attaches each finding's module + blast radius so you can navigate by the
+code graph instead of repeated whole-file reads.
+
 ## Security rules — never violate
 
 1. **Never output, log, or commit secrets** — no API keys, tokens, passwords, or credentials in code, commits, or files Claude writes