@vyuhlabs/dxkit 2.5.0 → 2.5.1

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

@@ -0,0 +1,124 @@
+---
+name: dxkit-config
+description: Edit dxkit configuration — add/remove paths in .dxkit-ignore, tune .vyuh-dxkit.json, adjust .dxkit/policy.json guardrail severity. Use when the user wants to exclude a directory from scanning, change scoring thresholds, or modify what blocks a PR.
+---
+
+# dxkit-config
+
+This skill modifies the three configuration files dxkit reads. Reach for it when the user asks to "ignore this vendored directory," "stop flagging X," "make the guardrail stricter/laxer," or "what controls Y."
+
+## The three config files
+
+| File | Purpose | When to edit |
+|---|---|---|
+| `.dxkit-ignore` | Extra paths dxkit's analyzers should skip (gitignore-style format) | Vendored code, generated code, test fixtures, large data files |
+| `.vyuh-dxkit.json` | Manifest of detected stack + custom settings (regenerated by `init` / `update`) | Rare — usually let `dxkit update` regenerate. Override version pins or framework detection here. |
+| `.dxkit/policy.json` | Severity policy for guardrail check | Customize what blocks a PR (e.g., demote `medium` to warning) |
+
+## Adding a path to `.dxkit-ignore`
+
+Format mirrors `.gitignore`: directory/, file-glob, multi-segment paths.
+
+```bash
+# Append a vendored directory
+echo 'vendor/' >> .dxkit-ignore
+
+# Append a generated-code dir
+echo 'src/generated/' >> .dxkit-ignore
+
+# Append a glob (auto-generated TypeScript types)
+echo '*.generated.ts' >> .dxkit-ignore
+```
+
+Or use Edit to add multiple entries cleanly. The file accepts comments (`#`).
+
+After editing, the **next** `baseline create` picks up the change. Existing baselines stay valid (the file's content hash is recorded in the baseline envelope, so a mismatch surfaces as a "baseline regenerated against newer .dxkit-ignore" note rather than an error).
+
+### Common exclusions
+
+```gitignore
+# Vendored third-party code committed to git
+vendor/
+third_party/
+
+# Generated code
+generated/
+*.generated.ts
+*.designer.cs
+*.pb.go
+src/proto-types/
+
+# Legacy code you don't want to track findings against
+legacy/
+deprecated/
+
+# Test fixtures that inflate metrics
+fixtures/large/
+test/fixtures/
+
+# Build artifacts (most are gitignored already, but defensive)
+dist/
+build/
+target/
+```
+
+## Tuning `.vyuh-dxkit.json`
+
+This file is mostly auto-generated. Common manual edits:
+
+```json
+{
+  "framework": "express",          // Override if auto-detection picked wrong
+  "languages": {
+    "typescript": true,
+    "python": false
+  },
+  "testRunner": {
+    "framework": "vitest",         // Override auto-detected test runner
+    "command": "npm test"
+  }
+}
+```
+
+When you edit this file, run `vyuh-dxkit update` to propagate changes through the rest of the scaffold (per-language rules, devcontainer features, etc.). Use `--force` only if you've also edited evolving files — otherwise `update` preserves customer changes.
+
+## Customizing `.dxkit/policy.json`
+
+The policy file controls what severity counts as "blocking" for the guardrail. Default:
+
+```json
+{
+  "code": { "block": ["critical", "high"], "warn": ["medium"] },
+  "dependency": { "block": ["critical", "high"], "warn": ["medium"] },
+  "secret": { "block": ["critical", "high", "medium", "low"] },
+  "test-gap": { "block": ["critical"], "warn": ["high"] },
+  "duplicate": { "warn": ["all"] }
+}
+```
+
+Each finding-kind has `block` (exit 1) and `warn` (log only) lists. Adjust to your team's tolerance:
+
+```json
+// Stricter — block medium SAST findings too
+{ "code": { "block": ["critical", "high", "medium"] } }
+
+// Laxer — make secret medium/low non-blocking (don't recommend)
+{ "secret": { "block": ["critical", "high"] } }
+```
+
+Run `vyuh-dxkit guardrail check --policy=.dxkit/policy.json` to test the new policy. If no `policy.json` exists, dxkit uses the built-in defaults.
+
+## Workflow
+
+When the user asks for a config change:
+
+1. Identify which file owns the concern (path exclusion → `.dxkit-ignore`; severity routing → `.dxkit/policy.json`; detection override → `.vyuh-dxkit.json`).
+2. Open the file, propose the edit, confirm.
+3. After writing, run `vyuh-dxkit baseline create --force` if exclusions changed (so the baseline doesn't carry stale findings from the now-excluded paths).
+4. Commit both: the config file + the regenerated baseline.
+
+## What NOT to do
+
+- Don't edit `.dxkit/cache/` or `.dxkit/reports/` — they're regenerated on every run (gitignored).
+- Don't manually mutate `.dxkit/baselines/main.json` — use `baseline create --force` to regenerate.
+- Don't add `.dxkit/` to `.dxkit-ignore` — dxkit itself doesn't scan its own outputs.

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

@@ -0,0 +1,109 @@
+---
+name: dxkit-hooks
+description: Install, configure, troubleshoot, or remove dxkit git hooks. Use when the user asks "set up hooks", "pre-push isn't firing", "how do I chain with husky", "bypass the hook", or anything about pre-commit/pre-push behavior in a dxkit-managed repo.
+---
+
+# dxkit-hooks
+
+This skill handles the git-hook surface dxkit ships. Use it to install hooks, debug "the hook didn't fire," chain dxkit with an existing hook system, or guide a bypass.
+
+## What dxkit ships
+
+`.githooks/pre-push` (default-on under `--full`) — runs the guardrail check before code leaves the developer's machine. Fast on warm scanner caches (~10-30s).
+
+`.githooks/pre-commit` (opt-in via `--with-precommit-hook`) — same guardrail check but on every commit. Slower on large repos (~1-3 min on 500+ file repos). Not in `--full` by default because the wall-clock cost gates adoption.
+
+Both run `vyuh-dxkit guardrail check`. The check exits 1 (blocking) on net-new findings vs. the baseline.
+
+## Installation
+
+```bash
+# Pre-push only (recommended for most teams)
+npx vyuh-dxkit init --with-hooks --yes
+
+# Both pre-commit + pre-push
+npx vyuh-dxkit init --with-hooks --with-precommit-hook --yes
+
+# Add to an existing dxkit install (idempotent)
+npx vyuh-dxkit init --with-precommit-hook --yes
+```
+
+Existing hooks at `.githooks/<name>` or `.husky/<name>` trigger sidecar-write mode: dxkit puts its hook at `.githooks/<name>.dxkit` and emits a chain note instead of clobbering.
+
+## Activation
+
+Hooks activate by setting `core.hooksPath = .githooks` in the local git config. Dxkit wires this via `npm postinstall` so every clone + `npm install` runs it automatically. Manual:
+
+```bash
+# Either of these works
+vyuh-dxkit hooks activate
+git config core.hooksPath .githooks
+```
+
+`vyuh-dxkit hooks activate` is idempotent — refuses to clobber a custom hooksPath (husky's `.husky`, lefthook's `.lefthook`, etc.). Run it to confirm the current state.
+
+## Troubleshooting "hook didn't fire"
+
+Walk this checklist:
+
+1. **Hook file exists**: `ls -la .githooks/pre-push` — should be executable.
+2. **hooksPath is wired**: `git config --local --get core.hooksPath` should print `.githooks`. If empty or pointing elsewhere, run `vyuh-dxkit hooks activate`.
+3. **dxkit binary is on PATH**: from the repo root, `which vyuh-dxkit` should resolve (either project-local `./node_modules/.bin/vyuh-dxkit` or global). The hook delegates to whichever it finds.
+4. **Baseline exists**: `test -f .dxkit/baselines/main.json` — without a baseline the guardrail has nothing to compare against. Run `vyuh-dxkit baseline create`.
+5. **Run the check by hand**: `vyuh-dxkit guardrail check` from the repo root. Expected: exits 1 on net-new findings (red), 0 on clean diff (green).
+
+If all five pass and the hook still doesn't fire, the most common cause is a competing hook system. `git config --global --get core.hooksPath` could be set globally to something else.
+
+## Chaining with husky / lefthook / other hook managers
+
+When dxkit detects an existing hook (`.husky/pre-commit` or `.githooks/pre-commit`), it writes `.githooks/pre-commit.dxkit` instead and prints a chain note. To wire them together, add a line at the end of the existing hook:
+
+```bash
+# .husky/pre-commit (after husky's own logic)
+sh .githooks/pre-commit.dxkit
+```
+
+Order matters: run the fast lint/format hooks first, then dxkit's guardrail last (so dxkit sees the actual final diff).
+
+For pre-push, same pattern with `.githooks/pre-push.dxkit`.
+
+## Bypass (emergency)
+
+When a hook blocks a push and the fix needs to land NOW (incident response, hotfix):
+
+```bash
+git push --no-verify
+```
+
+This skips ALL git hooks (not just dxkit's). After the emergency:
+
+1. Open the .dxkit/reports/ from the blocked push to understand what got bypassed.
+2. Either fix the regression in a follow-up commit OR
+3. Re-baseline if the regression is intentional and accepted:
+   ```bash
+   vyuh-dxkit baseline create --force
+   git add .dxkit/baselines/main.json
+   git commit -m "chore(baseline): accept regression from <ref>"
+   ```
+
+Re-baselining is a deliberate action — it grants future scans permission to keep the regression. Don't do it casually; use the policy file to suppress noisy finding kinds instead.
+
+## Disabling pre-commit (keeping pre-push)
+
+If pre-commit becomes a wall-clock blocker:
+
+```bash
+rm .githooks/pre-commit
+```
+
+`git config core.hooksPath` stays pointed at `.githooks/` (don't unset it). Future `init` calls won't re-add pre-commit unless `--with-precommit-hook` is passed.
+
+## Removing dxkit hooks entirely
+
+```bash
+git config --local --unset core.hooksPath
+rm -rf .githooks
+# Also remove the postinstall line from package.json if you want a clean uninstall
+```
+
+The CI workflows in `.github/workflows/dxkit-*.yml` continue to enforce the guardrail at PR-time, so removing local hooks doesn't disable the safety guarantees — just shifts them to CI-only.

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

@@ -0,0 +1,93 @@
+---
+name: dxkit-init
+description: Walk the user through installing and configuring dxkit on a fresh repo. Use when the user asks "how do I install dxkit?", "set up dxkit on this repo", "what flags should I use?", or wants to scaffold the guardrail surface. Defers to dxkit-config / dxkit-hooks for post-install tuning.
+---
+
+# dxkit-init
+
+This skill scaffolds dxkit on a repo: chooses flags, runs `init`, captures a baseline, and points at the next steps.
+
+## Decision tree
+
+Ask the user what they want, then pick the right invocation:
+
+1. **"Just give me everything"** → `npm init @vyuhlabs/dxkit` (collapses install + init), or if dxkit is already a devDep: `npx vyuh-dxkit init --full --yes`
+2. **"I only want the agent context, no guardrails yet"** → `npx vyuh-dxkit init --with-dxkit-agents --yes`
+3. **"I want guardrails but no CI"** → `npx vyuh-dxkit init --with-hooks --with-dxkit-agents --yes`
+4. **"I want the full setup but no pre-commit"** → `--full --yes` already does this (pre-commit is opt-in via `--with-precommit-hook` because it's slow on large repos)
+5. **"Interactive — talk me through it"** → `npx vyuh-dxkit init` (no `--yes`) and let it prompt
+
+## Flag reference
+
+| Flag | What it ships | Default under `--full`? |
+|---|---|---|
+| `--with-dxkit-agents` | The 6 dxkit-* skills + AGENTS.md + CLAUDE.md shim | Yes |
+| `--with-hooks` | `.githooks/pre-push` + postinstall activation wire-up | Yes |
+| `--with-precommit-hook` | Adds `.githooks/pre-commit` (slow on large repos) | No (still opt-in) |
+| `--with-devcontainer` | `.devcontainer/devcontainer.json` (per-stack features) + post-create.sh | Yes |
+| `--with-ci` | `.github/workflows/dxkit-guardrails.yml` (PR gate) | Yes |
+| `--with-baseline-refresh` | `.github/workflows/dxkit-baseline-refresh.yml` (post-merge regen) | Yes |
+| `--with-pr-review` | `.github/workflows/pr-review.yml` (AI PR review; needs `ANTHROPIC_API_KEY`) | No (still opt-in) |
+
+`--yes` accepts all prompts; `--force` overwrites existing files instead of writing `.dxkit` sidecars on conflict.
+
+## Steps
+
+1. **Detect the stack** before installing — let the user confirm:
+   ```bash
+   npx vyuh-dxkit init --detect
+   ```
+   This auto-detects and previews what `init --full` would do without writing anything.
+
+2. **Run init**:
+   ```bash
+   # Most common case — full setup, no prompts
+   npx vyuh-dxkit init --full --yes
+   ```
+
+3. **Capture the brownfield baseline** — must do this before hooks/CI become useful:
+   ```bash
+   npx vyuh-dxkit baseline create
+   git add .dxkit/baselines/
+   git commit -m "chore: capture dxkit baseline"
+   ```
+
+4. **Verify the install**:
+   ```bash
+   npx vyuh-dxkit doctor
+   ```
+   This checks: hooks active, baseline present, workflows installed, scanner toolchain available.
+
+5. **Hand off**:
+   - For policy / exclusions / scoring thresholds → `dxkit-config` skill
+   - For hook troubleshooting → `dxkit-hooks` skill
+   - For running reports → `dxkit-reports` skill
+   - For branch protection (manual today, automated in next release): GitHub repo settings → Branches → require `dxkit guardrails` check + require PR review
+
+## Common pitfalls
+
+- **No package.json**: `npm init @vyuhlabs/dxkit` seeds a minimal one. For Python-only / Go-only repos, install dxkit globally instead: `npm install -g @vyuhlabs/dxkit && vyuh-dxkit init --full --yes`.
+- **Existing .claude/ from 2.5.0**: dxkit init is additive — your existing `.claude/` files are preserved. To switch to the new dxkit-specific shape, delete the old `.claude/` dir first, then re-init.
+- **Peer-dep ERESOLVE during `npm install`**: `npm init @vyuhlabs/dxkit` automatically retries with `--legacy-peer-deps`. Manual installs may need that flag.
+- **Brownfield repo with thousands of existing findings**: that's normal — the baseline records them all once. Guardrail only blocks net-new findings.
+
+## What `init --full` writes
+
+A complete install lays down ~15-20 files (down from the 2.5.0 ~73-file scaffold). Per-repo:
+
+- `.dxkit/baselines/main.json` (after `baseline create`)
+- `.dxkit-ignore` (starter template)
+- `.vyuh-dxkit.json` (manifest)
+- `.githooks/pre-push`
+- `.github/workflows/dxkit-guardrails.yml`
+- `.github/workflows/dxkit-baseline-refresh.yml`
+- `.devcontainer/devcontainer.json` (per-stack features)
+- `.devcontainer/post-create.sh`
+- `.devcontainer/install-agent-clis.sh`
+- `.claude/skills/dxkit-{learn,init,config,hooks,reports,action}/SKILL.md`
+- `.claude/rules/<lang>.md` (per active language pack)
+- `.claude/settings.json` (narrowed: dxkit-binary permissions only)
+- `AGENTS.md` (project prose context for any agent — Claude, Codex, Cursor, Aider)
+- `CLAUDE.md` (shim pointing at AGENTS.md)
+- `package.json` (postinstall = `vyuh-dxkit hooks activate`)
+- `.gitignore` (additive: `.dxkit/reports/`, `.dxkit/cache/`, `graphify-out/`)

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

@@ -0,0 +1,84 @@
+---
+name: dxkit-learn
+description: Answer questions about dxkit — what each scanner does, what a baseline is, what the 6 health dimensions score, how guardrails work. Use when the user asks "what does dxkit X do?", "what's a baseline?", "what's the slop score?", "how do hooks fit in?", or anything else about dxkit concepts.
+---
+
+# dxkit-learn
+
+This skill explains how dxkit works. Reach for it when the user asks about dxkit concepts before they take an action.
+
+## Mental model
+
+dxkit measures a codebase along **6 dimensions** (Security, Code Quality, Tests, Documentation, Maintainability, Developer Experience) using deterministic scanners (gitleaks, semgrep, cloc, jscpd, graphify, ruff, eslint, …). Findings are anchored to a **baseline** (`.dxkit/baselines/main.json`) so today's pre-existing issues don't block tomorrow's PR. A **guardrail check** diffs current state against the baseline and blocks net-new regressions. Hooks + CI wire the guardrail into the developer's workflow.
+
+The three contracts to remember:
+
+1. **Baseline = the brownfield anchor**. Pre-existing findings are recorded once; future scans only block on *additions*.
+2. **Hooks fire fast (pre-push); CI fires thorough**. Both use the same guardrail logic.
+3. **Reports are deterministic** — same code + same baseline = same findings. The salt mode (`deterministic` vs `random`) controls per-finding identity stability across runs.
+
+## The 6 dimensions
+
+Each dimension is a 0-100 score with letter grade (A≥80, B≥60, C≥40, D≥20, E<20):
+
+| Dimension | What scores it down |
+|---|---|
+| **Security** | Secret leaks (gitleaks), SAST findings (semgrep), dependency vulns (osv-scanner / npm-audit / pip-audit / etc.), TLS-bypass patterns |
+| **Code Quality** | Lint findings (eslint / ruff / golangci-lint / clippy / detekt / rubocop / dotnet-format), high duplication (jscpd), code-pattern slop |
+| **Tests** | Missing test coverage on primary-architecture files; missing test runner config; below-threshold line coverage |
+| **Documentation** | Missing/empty README; missing doc-comments on public APIs (XML-doc/JSDoc/TSDoc/godoc/etc.); below-threshold comment ratio |
+| **Maintainability** | Function/file size outliers, deep cyclomatic complexity, god-objects, high orphan-module count, dead imports |
+| **Developer Experience** | Missing `.gitignore` / `.editorconfig` / `package.json` engines pin / devcontainer / hooks / CI workflow |
+
+Run `vyuh-dxkit health` to see all six at once. Each dimension report has a "top actions" list — the changes that would lift the score the most.
+
+## The scanner toolchain
+
+dxkit doesn't write parsers — it orchestrates established tools and computes scores. The full list is in `TOOL_DEFS` (or run `vyuh-dxkit tools list`). Key ones:
+
+- **gitleaks** — secret scanning (API keys, AWS credentials, GitHub tokens)
+- **semgrep** — multi-language SAST (auto config picks rulesets per active language pack)
+- **cloc** — language-aware line counting (excludes comments + blanks)
+- **jscpd** — copy-paste detection
+- **graphify** — AST-based metrics (functions, classes, cohesion, god-nodes, dead imports)
+- **osv-scanner** — dependency vulnerabilities (npm/pip/cargo/go/gem/maven via OSV.dev)
+- Per-language linters: eslint (TS), ruff (Python), golangci-lint (Go), clippy (Rust), dotnet-format (C#), detekt (Kotlin), pmd (Java), rubocop (Ruby)
+
+If a tool isn't installed, dxkit degrades gracefully (the affected dimension reports a partial score with a "missing tool" note instead of crashing).
+
+## Baselines explained
+
+A baseline is the per-finding identity snapshot of a scan. Every finding has a **fingerprint** (SHA-1[0:16] of file+rule+line-window+content). The baseline stores those fingerprints. The guardrail diffs today's scan against the baseline:
+
+- Fingerprint in scan + in baseline → **existing** (ignored)
+- Fingerprint in scan + NOT in baseline → **added** (blocks)
+- Fingerprint in baseline + NOT in scan → **removed** (silently good)
+
+That's why "fix a critical, leave the medium" works — the medium's fingerprint stays in the baseline; only net-new findings count.
+
+Commands:
+
+```bash
+vyuh-dxkit baseline create               # Capture current state into .dxkit/baselines/main.json
+vyuh-dxkit baseline show                 # Summarize what's recorded
+vyuh-dxkit baseline show --kind secret   # Drill into a specific finding kind
+vyuh-dxkit guardrail check               # Diff current scan vs baseline; exit 1 on net-new
+```
+
+## Hooks
+
+Two hooks ship under `.githooks/`:
+
+- **pre-push** (always-on under `--full`): runs the guardrail check before code leaves the developer's machine. Fast on warm scanner caches (~10-30s).
+- **pre-commit** (opt-in via `--with-precommit-hook`): same logic, fires on every commit. Slower on large repos until incremental scanning lands.
+
+Activation is wired via `npm postinstall` so `npm install` after `git clone` sets `core.hooksPath = .githooks` automatically.
+
+## How to learn more
+
+- `vyuh-dxkit <subcommand> --help` — flag reference
+- `vyuh-dxkit baseline show` — what your repo already has recorded
+- `.dxkit/reports/` — every analyzer's markdown + JSON output from the last run
+- `vyuh-dxkit dashboard` — single HTML view of every report
+
+When the user asks specifically about a scanner or a finding type, point them at the relevant report or run the relevant analyzer command directly.

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

@@ -0,0 +1,111 @@
+---
+name: dxkit-reports
+description: Run dxkit reports and explain their output. Use when the user asks "run health", "check security", "show me the dashboard", "what does this score mean", or anything about generating / reading dxkit analyzer output. Hands off to dxkit-action for fixing findings.
+---
+
+# dxkit-reports
+
+This skill runs dxkit analyzers and reads their output back to the user. It's the "tell me how my codebase is doing" surface.
+
+## Command map
+
+| User asks | Command | Output |
+|---|---|---|
+| "Overall health" / "give me the score" | `vyuh-dxkit health` | 6-dimension score table + top actions per dimension |
+| "Check security" / "find vulns" | `vyuh-dxkit vulnerabilities` | Code-level SAST + dep-vuln + secret findings, grouped by severity |
+| "Test coverage gaps" | `vyuh-dxkit test-gaps` | Source files without matching tests, prioritized by architectural role |
+| "Code quality" | `vyuh-dxkit quality` | Lint findings + duplication + slop score |
+| "Who's been working on what" | `vyuh-dxkit dev-report` | Per-author activity, hot files, churn |
+| "License inventory" | `vyuh-dxkit licenses` | Every dependency's declared license |
+| "Bill of materials" | `vyuh-dxkit bom` | Licenses + dep vulnerabilities joined (15-col XLSX-ready output) |
+| "Run everything" | `vyuh-dxkit report` | Every analyzer in one shot, ~3-5 min |
+| "Show me the dashboard" | `vyuh-dxkit dashboard` | Single HTML view of all reports — opens at `.dxkit/reports/dashboard.html` |
+
+## Where output lands
+
+Every analyzer writes to `.dxkit/reports/` with a date-stamped filename:
+
+```
+.dxkit/reports/
+  health-2026-05-19.md
+  health-2026-05-19.json
+  vulnerability-scan-2026-05-19.md
+  vulnerability-scan-2026-05-19-detailed.json
+  ...
+  dashboard.html
+```
+
+The `.md` files are human-readable; the `.json` files are machine-readable (for CI consumption or custom tooling). Reports are gitignored by default — they regenerate on every run.
+
+## Reading the health report
+
+The 6 dimensions each get an A-E grade. Below each grade the "top actions" list shows what would lift the score the most (sorted by potential uplift). Example:
+
+```
+Security: B (72)
+  Top actions:
+    1. Pin @types/node to ≥18.19.0 (closes 2 dep-vuln entries)
+    2. Add gitleaks pre-commit hook (closes 1 secret-scan finding)
+    3. Replace `Math.random()` in src/auth/token.ts (closes 1 SAST finding)
+```
+
+Score → rating: A ≥ 80, B ≥ 60, C ≥ 40, D ≥ 20, E < 20. **Cap tiers** can pin a score below its arithmetic value when trust is broken (e.g., uncommitted state caps at 79). The report explains the cap if one fires.
+
+## Common patterns
+
+### Quick health check (warm cache)
+
+```bash
+vyuh-dxkit health
+```
+
+Re-uses cached scanner outputs where possible. ~5-15s on warm cache, ~30-60s cold.
+
+### Pre-merge audit (thorough)
+
+```bash
+vyuh-dxkit health --with-coverage   # Runs tests + materializes coverage before scoring
+vyuh-dxkit vulnerabilities          # Always re-runs the deep security scan
+vyuh-dxkit dashboard                 # Renders the latest reports into one HTML view
+```
+
+`--with-coverage` is slow (runs your test suite) but switches the Tests dimension from heuristic ("files match a test pattern") to real ("line coverage from your reporter"). Worth it for pre-merge audits.
+
+### Per-PR scope
+
+```bash
+vyuh-dxkit guardrail check
+```
+
+Diffs the current scan vs the baseline. Exit 1 on net-new findings (the same logic the pre-push hook uses).
+
+### Failing CI on a threshold
+
+```bash
+vyuh-dxkit health --fail-on-score=70                 # Exit 1 if overall score < 70
+vyuh-dxkit vulnerabilities --fail-on-severity=high   # Exit 1 if any high-severity finding
+```
+
+Use these in CI for hard floors.
+
+## Reading dependency findings
+
+`vulnerabilities` (and `bom`) carry severity + CVSS where available. The severity column is computed via OSV.dev's enrichment — when OSV reports no severity, dxkit assigns one via CVSS v4.0 base-score math (see `src/analyzers/tools/cvss-v4.ts`).
+
+When the user asks "is this CVE worth fixing today" the answer depends on:
+1. **Reachability** — does the codebase actually call the vulnerable function? (Today: heuristic via graphify call-graph; reachability tiers are a roadmap item.)
+2. **Exploitability** — public PoC? Authentication required? Network exposure?
+3. **Patch availability** — is there a fixed version?
+
+Surface those three when summarizing a dep-vuln finding. The detailed JSON has the OSV/GHSA reference URL — link to it.
+
+## When the user wants to ACT on findings
+
+Hand off to the `dxkit-action` skill — that's the workflow for prioritizing + fixing + re-baselining. This skill stops at "here's what's wrong."
+
+## Troubleshooting
+
+- **"Scanner X unavailable"** → run `vyuh-dxkit tools list` to see status; `vyuh-dxkit tools install` to install missing ones.
+- **"N/A for this stack"** → applicability-guard fired (e.g., vitest-coverage on a mocha repo). Not a problem; the scanner doesn't apply here.
+- **Report looks stale** → `.dxkit/reports/` is keyed by date. Re-run the analyzer to get a fresh date-stamped file.
+- **Numbers don't match between two reports** → check whether `--with-coverage` was used. Without it, Tests dimension uses heuristic; with it, real coverage. They legitimately differ.

package/templates/.devcontainer/devcontainer.json

@@ -1,41 +1,15 @@
 {
   "name": "dxkit dev environment",
 
-  // Universal base + composable features. Each language pack dxkit
-  // supports has a corresponding feature here so the same image works
-  // for monorepos that span multiple ecosystems. Tune by removing
-  // features your project does not need — smaller image, faster
-  // Codespaces prebuild.
+  // Universal base + per-stack composable features. The features
+  // block below is generated by `vyuh-dxkit init` from the detected
+  // stack — only toolchains your project actually uses get installed.
+  // Always-on: Node (dxkit's own runtime) + GitHub CLI. Add or
+  // remove entries by hand if you want to over- or under-ride the
+  // auto-detected set.
   "image": "mcr.microsoft.com/devcontainers/base:ubuntu-22.04",
 
-  "features": {
-    "ghcr.io/devcontainers/features/node:1": {
-      "version": "22",
-      "nvmVersion": "latest"
-    },
-    "ghcr.io/devcontainers/features/python:1": {
-      "version": "3.12",
-      "installTools": true
-    },
-    "ghcr.io/devcontainers/features/go:1": {
-      "version": "1.21"
-    },
-    "ghcr.io/devcontainers/features/dotnet:2": {
-      "version": "8.0"
-    },
-    "ghcr.io/devcontainers/features/ruby:1": {
-      "version": "3.3"
-    },
-    "ghcr.io/devcontainers/features/java:1": {
-      "version": "17",
-      "installGradle": true
-    },
-    "ghcr.io/devcontainers/features/rust:1": {
-      "version": "stable",
-      "profile": "default"
-    },
-    "ghcr.io/devcontainers/features/github-cli:1": {}
-  },
+  "features": __DXKIT_DEVCONTAINER_FEATURES__,
 
   // Reproducibility note: language toolchains are pinned in the
   // features block above. Scanner tools (gitleaks, semgrep, cloc,

package/templates/.devcontainer/post-create.sh

@@ -23,15 +23,29 @@ echo "==> dxkit post-create starting in $(pwd)"
 # annoying but shouldn't take down the rest of the post-create. The
 # user can re-run `npm install` after authenticating or fixing the
 # lockfile.
+#
+# The fallback chain layers three install strategies before giving up:
+#
+#   1. `npm ci` (lockfile path only) — strict, fast, uses the lockfile
+#      verbatim. Happy path on a healthy tree.
+#   2. `npm install` — looser; rebuilds lockfile entries if the
+#      lockfile drifted (lockfile vs package.json mismatch after a
+#      merge, for example).
+#   3. `npm install --legacy-peer-deps` — last resort. npm v7+ defaults
+#      to strict peer-dep resolution; brownfield monorepos almost
+#      always carry unresolved peers (eslint 8↔10, react cross-pkg
+#      peer mismatches, etc.) which fail both prior steps with
+#      multi-line ERESOLVE dumps. Legacy mode skips the peer-dep
+#      check and gets a working node_modules/.
 if [ -f package.json ]; then
   echo "==> Installing project dependencies..."
   if [ -f package-lock.json ]; then
-    npm ci || npm install || {
-      echo "WARN: project dependency install failed — re-run 'npm install' manually if needed." >&2
+    npm ci || npm install || npm install --legacy-peer-deps || {
+      echo "WARN: project dependency install failed even with --legacy-peer-deps — re-run 'npm install --legacy-peer-deps' manually after fixing the cause." >&2
     }
   else
-    npm install || {
-      echo "WARN: project dependency install failed — re-run 'npm install' manually if needed." >&2
+    npm install || npm install --legacy-peer-deps || {
+      echo "WARN: project dependency install failed even with --legacy-peer-deps — re-run 'npm install --legacy-peer-deps' manually after fixing the cause." >&2
     }
   fi
 fi