@vyuhlabs/dxkit 2.5.0 → 2.5.2

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

@@ -0,0 +1,246 @@
+---
+name: dxkit-onboard
+description: Walk a customer through setting up dxkit on a repo from scratch — checks state, installs, scaffolds, configures hooks, runs doctor, fixes any gaps, captures the first baseline, sets up branch protection + Codespaces prebuild. Use when the user asks "set me up", "install dxkit on this repo", "I want to use dxkit", "walk me through dxkit setup", "help me get started with dxkit", or anything about onboarding a fresh repo. Asks for confirmation at each step with sensible defaults; hands off to dxkit-fix mid-flow when doctor surfaces gaps.
+---
+
+# dxkit-onboard
+
+This skill drives the FULL new-customer journey end-to-end. It's the "I have nothing — set me up" surface (complement to `dxkit-update` for existing-install upgrades and `dxkit-fix` for repairs).
+
+Unlike the other dxkit-* skills which are each scoped to a single domain (install / config / hooks / etc.), dxkit-onboard orchestrates across them. It dispatches into `dxkit-init` for flag choices, `dxkit-fix` for gap closure, `dxkit-hooks` for hook deep-dives — composing a single coherent customer conversation.
+
+## When to use this skill
+
+Use when:
+
+- "Set me up"
+- "Install dxkit on this repo"
+- "I want to use dxkit"
+- "Walk me through dxkit setup"
+- "Help me get started with dxkit"
+- "First time using dxkit"
+
+Don't use when:
+
+- Customer already has `.vyuh-dxkit.json` AND is asking about a specific task (use the focused skill — dxkit-reports, dxkit-action, etc.)
+- Customer wants to UPGRADE an existing install (use `dxkit-update`)
+- Something is broken (use `dxkit-fix`)
+
+## The onboarding journey
+
+```
+[1] State check       → is dxkit installed? scaffold present? baseline captured? hooks active?
+[2] Install if needed → npm init @vyuhlabs/dxkit OR npx vyuh-dxkit init --full --yes
+[3] Doctor            → npx vyuh-dxkit doctor (parse summary.fixable[])
+[4] Fix gaps          → dispatch through dxkit-fix for each fixable signal
+[5] Capture baseline  → npx vyuh-dxkit baseline create (with explicit secrets-warning)
+[6] Pre-commit ASK    → opt-in based on repo size (>500 files: default no)
+[7] Postinstall chain → opt-in to auto-activate hooks for teammates
+[8] Branch protection → ASK to run vyuh-dxkit setup-branch-protection
+[9] Codespaces prebuild → ASK to run vyuh-dxkit setup-prebuild (if customer uses Codespaces)
+[10] Final verify     → re-run doctor; show green; surface any remaining gaps
+```
+
+Each step ASKS the customer with a sensible default — never silent execution. The customer can decline any step; default behavior shouldn't surprise them.
+
+## Steps
+
+### 1. State check
+
+Before recommending anything, snapshot the customer's current state:
+
+```bash
+# Does the manifest exist?
+test -f .vyuh-dxkit.json && echo "has-manifest" || echo "fresh"
+
+# Is dxkit on PATH?
+command -v vyuh-dxkit && echo "binary-on-path" || echo "binary-missing"
+
+# Is the workspace a git repo?
+git rev-parse --is-inside-work-tree 2>/dev/null && echo "git-ok" || echo "not-a-repo"
+```
+
+Branch the conversation on the result:
+
+- **Fresh repo (no manifest)**: go to step 2 (install)
+- **Manifest exists**: this customer already onboarded. Pivot: "Looks like dxkit is already installed. Are you trying to upgrade (→ dxkit-update) or fix something (→ dxkit-fix)?"
+- **Not a git repo**: stop. "dxkit needs a git repo. Run `git init` first, then come back."
+
+### 2. Install if needed
+
+For a fresh install, the canonical command is:
+
+```bash
+npm init @vyuhlabs/dxkit
+```
+
+This runs `create-dxkit` which installs `@vyuhlabs/dxkit` as a devDep and then runs `npx vyuh-dxkit init --full --yes` (which scaffolds everything: skills, AGENTS.md, CLAUDE.md, devcontainer, hooks, CI workflows).
+
+Before running, ASK:
+
+- **"Full install (recommended)?"** — yes runs the above; no asks for flag choices and routes through `dxkit-init`'s decision tree.
+
+Optional flags worth surfacing if the customer pushes back on "full":
+
+- `--with-dxkit-agents` — just the 8 dxkit-* skills (no hooks, no CI)
+- `--with-hooks --with-dxkit-agents` — skills + pre-push hook
+- `--with-precommit-hook` — also pre-commit (slow on large repos)
+
+If the customer wants more granularity, hand off to `dxkit-init` for the full flag explanation.
+
+### 3. Doctor
+
+After install, run:
+
+```bash
+npx vyuh-dxkit doctor --json > /tmp/dxkit-onboard-doctor.json
+```
+
+Parse `summary.fixable[]`. Most fresh-install gaps will be operational (hooks not yet activated by postinstall trigger; baseline not captured yet; etc.) rather than scaffold-missing.
+
+### 4. Fix gaps
+
+For each fixable signal in doctor's output, dispatch through `dxkit-fix`'s recovery loop. Most common fresh-install gaps:
+
+- `git hooks active` not active → `npx vyuh-dxkit hooks activate`
+- `baseline captured` missing → defer to step 5 (we'll handle that explicitly with the secrets warning)
+- `vyuh-dxkit on PATH` missing → `npm install -g @vyuhlabs/dxkit`
+- `scanner toolchain` incomplete → `npx vyuh-dxkit tools install --yes`
+
+Don't auto-execute baseline capture here — step 5 has a values-laden warning that needs explicit customer confirmation.
+
+### 5. Capture baseline (carefully)
+
+This is the step with permanent consequences. The baseline records the fingerprint of every finding currently in the repo and tells future scans "these are pre-existing — don't block on them."
+
+Before running `baseline create` on a fresh customer:
+
+> **About to capture the first baseline.**
+>
+> This locks in ALL current findings as "pre-existing" — they won't block future PRs. If your repo has real secrets, vulnerable deps, or other defects you'd want to fix FIRST, tell me and I'll show you what's flagged so we can triage before baseline.
+>
+> Capture baseline now if: codebase is known-messy brownfield and you want guardrails on FUTURE regressions specifically.
+>
+> Skip baseline now if: you have secrets in the repo, or you'd rather fix-as-you-go than accept the current state.
+
+If they want to triage first, hand off to `dxkit-action` — that skill prioritizes findings before baseline lock-in. Come back to step 5 after triage.
+
+If they confirm baseline:
+
+```bash
+npx vyuh-dxkit baseline create
+git add .dxkit/baselines/
+git commit -m "chore: capture dxkit baseline"
+```
+
+### 6. Pre-commit ASK
+
+Pre-commit is opt-in even under `--full` because it re-runs every analyzer on every commit (~1-3 min on 500+ file repos). Most teams skip it.
+
+ASK:
+
+> **Add pre-commit hook?** Default no. Pre-commit catches regressions before commit (vs pre-push catching them before push). Tradeoff: ~1-3 min wall-clock on every commit for a 500+ file repo. Most teams accept the pre-push-only model.
+
+Default recommendation by repo size:
+- `find . -type f -name "*.ts" -o -name "*.py" -o -name "*.go" 2>/dev/null | wc -l` < 200 → default Yes
+- > 500 → default No
+- In between → ask without a strong default
+
+If yes, run `npx vyuh-dxkit init --with-precommit-hook --yes` to add the pre-commit hook.
+
+### 7. Postinstall chain
+
+If the customer's `package.json` already has a `postinstall` script (most non-trivial repos do — patch-package, husky, monorepo bootstrap), dxkit won't auto-chain its hook activation into it. Teammates who clone the repo and run `npm install` won't get hooks wired automatically.
+
+ASK:
+
+> **Chain dxkit-hooks-activate into your existing postinstall?** Default yes. Without this, teammates who clone won't get hooks wired automatically.
+>
+> Current postinstall: `<read from package.json>`
+> Proposed: `<current> && vyuh-dxkit hooks activate`
+
+If yes, hand off to `dxkit-hooks` for the actual edit (it knows the safe append pattern + how to deal with sidecar files).
+
+### 8. Branch protection ASK
+
+Local hooks are fast feedback; CI is the unbypassable enforcement. Branch protection wires CI as a required status check — without it, the dxkit-guardrails workflow is informational and PRs can merge even when it fails.
+
+ASK:
+
+> **Configure branch protection now?** Default yes. Adds `dxkit-guardrails` as a required status check on `<default branch>`. Requires admin permission on the GitHub repo. Without this, the CI workflow is informational — PRs can merge even on guardrail failures.
+
+If yes:
+
+```bash
+npx vyuh-dxkit setup-branch-protection
+```
+
+If the customer isn't a repo admin (HTTP 403), surface the manual UI path: Settings → Branches → Add rule → Require status checks → check `dxkit-guardrails`. Or ask their repo admin to run the command.
+
+### 9. Codespaces prebuild ASK
+
+Only relevant if the customer's team uses Codespaces. ASK:
+
+> **Does your team use GitHub Codespaces?** [Y/N]
+>
+> If yes: configuring a prebuild drops cold-start from ~7 min to ~30s. Trivial to set up; storage costs ~$3-5/month per region.
+
+If yes:
+
+```bash
+npx vyuh-dxkit setup-prebuild
+```
+
+Same admin-permission caveat as step 8.
+
+### 10. Final verify
+
+Re-run doctor:
+
+```bash
+npx vyuh-dxkit doctor
+```
+
+Report the results:
+
+- **All green** → "You're fully set up. dxkit will guard your next push. Run `vyuh-dxkit health` whenever you want to see scores."
+- **Remaining fixable gaps** → hand off to `dxkit-fix` for each one. Don't end with broken signals.
+
+## What dxkit-onboard can NOT do
+
+- **Auto-decide values-laden questions** — baseline lock-in (step 5), pre-commit opt-in (step 6), postinstall chaining (step 7), branch protection (step 8) all require explicit customer confirmation. Never silently execute these.
+- **Fix repos that aren't git repos** — surface the "git init first" step and stop.
+- **Triage code findings** — that's `dxkit-action`. Hand off when the customer wants to evaluate findings before baseline.
+- **Install on a non-Node project** — dxkit can still scan non-Node projects but `npm init @vyuhlabs/dxkit` needs Node + npm. Surface the requirement; offer global install path as a fallback.
+
+## Boundary with other lifecycle skills
+
+| Customer state | Reach for |
+|---|---|
+| "I have nothing" | **dxkit-onboard (this skill)** |
+| "I have working install, make it newer" | `dxkit-update` |
+| "Doctor says X is broken" | `dxkit-fix` |
+| "Run a report" | `dxkit-reports` |
+| "Fix code findings" | `dxkit-action` |
+| "Edit dxkit configuration" | `dxkit-config` |
+| "Set up / troubleshoot hooks" | `dxkit-hooks` |
+| "Explain dxkit concepts" | `dxkit-learn` |
+| "Choose init flags" | `dxkit-init` |
+
+When in doubt, dxkit-onboard handles the full first-install journey and delegates to focused skills for sub-decisions. After step 10, the customer should never need dxkit-onboard again — they'd reach for dxkit-update (newer dxkit), dxkit-fix (broken signal), or one of the work skills (reports/action/config/hooks).
+
+## Final report
+
+```
+✓ Fresh dxkit install complete:
+   • Binary: 2.5.X installed globally + project-local
+   • Scaffold: 8 dxkit-* skills, AGENTS.md, CLAUDE.md, devcontainer, hooks, CI workflows
+   • Doctor: 14/14 (Reports + Agent DX + Operational health)
+   • Baseline: N findings locked in (or "skipped — you're triaging first")
+   • Pre-commit: yes/no (your choice)
+   • Postinstall chain: yes/no (your choice)
+   • Branch protection: configured / declined / failed (admin permission)
+   • Codespaces prebuild: configured / declined / N/A
+```
+
+End with a one-line CTA: "Try it: edit a file, `git push`, and watch the hook fire. Or ask 'run health' to see your dxkit scores."

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

@@ -0,0 +1,111 @@
+---
+name: dxkit-reports
+description: Run dxkit reports and explain their output, including the consolidated dashboard view. Use when the user asks "run health", "check security", "show me the dashboard", "open the dashboard", "tour the dashboard", "explain the dashboard", "what does this score mean", or anything about generating / interpreting dxkit analyzer output. Always reach for this skill even when the user names a specific subcommand (health, vulnerabilities, dashboard, bom, etc.) — running the command is only half of the value; the skill wraps the output with the right framing. 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" | `npx vyuh-dxkit health` | 6-dimension score table + top actions per dimension |
+| "Check security" / "find vulns" | `npx vyuh-dxkit vulnerabilities` | Code-level SAST + dep-vuln + secret findings, grouped by severity |
+| "Test coverage gaps" | `npx vyuh-dxkit test-gaps` | Source files without matching tests, prioritized by architectural role |
+| "Code quality" | `npx vyuh-dxkit quality` | Lint findings + duplication + slop score |
+| "Who's been working on what" | `npx vyuh-dxkit dev-report` | Per-author activity, hot files, churn |
+| "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` |
+
+## 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
+npx vyuh-dxkit health
+```
+
+Re-uses cached scanner outputs where possible. ~5-15s on warm cache, ~30-60s cold.
+
+### Pre-merge audit (thorough)
+
+```bash
+npx vyuh-dxkit health --with-coverage   # Runs tests + materializes coverage before scoring
+npx vyuh-dxkit vulnerabilities          # Always re-runs the deep security scan
+npx 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
+npx 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
+npx vyuh-dxkit health --fail-on-score=70                 # Exit 1 if overall score < 70
+npx 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 `npx vyuh-dxkit tools list` to see status; `npx 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/.claude/skills/dxkit-update/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: dxkit-update
+description: Walk the customer through upgrading dxkit to a newer version safely. Use when the user asks "update dxkit", "upgrade to latest", "what's new in dxkit", "is there a new dxkit version", "should I upgrade dxkit", or anything about moving an existing dxkit install forward. Reads version delta + changelog + recommended steps; confirms each step. Hands off to dxkit-fix if post-upgrade doctor surfaces broken signals.
+---
+
+# dxkit-update
+
+This skill drives the dxkit upgrade flow conversationally. It's the "I have something working — make it newer" surface (complement to `dxkit-onboard` for fresh installs and `dxkit-fix` for repairs).
+
+## When to use this skill
+
+Use when:
+
+- "Is there a new dxkit version?"
+- "Update dxkit"
+- "Upgrade to latest"
+- "What changed in dxkit recently?"
+- "What's new in 2.5.5?" (or any other specific version)
+- "Should I upgrade?"
+
+Don't use when:
+
+- Customer has no `.vyuh-dxkit.json` (they need `dxkit-init`, not update)
+- Something is BROKEN — use `dxkit-fix` first; then maybe update after
+- Customer wants to roll back to an older version (downgrade — surface the risk + manual command, don't auto-execute)
+
+## How the upgrade works (two stages)
+
+dxkit ships in two layers and an upgrade touches both:
+
+1. **The binary** — `@vyuhlabs/dxkit` npm package. `npm update` or `npm install @vyuhlabs/dxkit@<version>` replaces the local binary.
+2. **The scaffold** — files in the customer's repo (`.devcontainer/`, `.githooks/`, `.claude/skills/dxkit-*/`, `AGENTS.md`, `CLAUDE.md`, `.github/workflows/dxkit-*.yml`). `npx vyuh-dxkit update` refreshes these to match the new binary's templates.
+
+Both run for any non-trivial upgrade. The CLI subcommand `vyuh-dxkit upgrade` orchestrates them; this skill drives the customer through the orchestration with explanations and confirmations.
+
+## The upgrade loop
+
+```
+[1] Read the plan        → npx vyuh-dxkit upgrade --plan --json
+[2] Explain the delta    → current vs target, classification, what's new
+[3] Surface warnings     → major bumps, breaking changes, scaffold drift
+[4] Confirm              → "proceed?" (default Y for low-risk; default N for major/downgrade)
+[5] Execute              → drive each step with per-step status
+[6] Verify               → run doctor + report operational health post-upgrade
+[7] Surface manual steps → devcontainer rebuild instructions if .devcontainer/ changed
+```
+
+## Steps
+
+### 1. Snapshot the plan
+
+```bash
+npx vyuh-dxkit upgrade --plan --json > /tmp/dxkit-upgrade-plan.json
+```
+
+The JSON has shape `{ schema: "upgrade-plan.v1", current: { binary, scaffold }, target, delta, steps: [...], warnings: [...], changelogNote }`. Capturing to a file (instead of piping inline) lets the customer re-read the plan if they pause mid-flow.
+
+### 2. Explain what's about to happen
+
+Translate the structured plan into customer-friendly prose:
+
+| Plan field | What to say |
+|---|---|
+| `current.binary` + `current.scaffold` | "You're on dxkit X (scaffold also X). Latest: Y." |
+| `delta: 'none'` | "Already up to date — nothing to do." Skip to End. |
+| `delta: 'patch'` | "N patch versions between you and latest. Low risk — bug fixes + small features only." |
+| `delta: 'minor'` | "Minor bump — new features + scaffold changes likely. Probably safe; CHANGELOG.md has details." |
+| `delta: 'major'` | "**Major bump** — read CHANGELOG.md for breaking changes BEFORE upgrading. Possible baseline/manifest schema migrations; possibly broken policy files; possibly removed CLI flags." |
+| `delta: 'downgrade'` | "Target is OLDER than installed. Downgrades aren't officially supported — baseline/manifest schemas may differ. Surface this and let the customer decide." |
+
+### 3. Surface every warning
+
+Iterate `plan.warnings` and present each as its own bullet. Don't bury them. If `warnings` is empty, mention "No warnings — proceed when ready."
+
+### 4. Confirm before execution
+
+Ask:
+
+> **Proceed with the upgrade?**
+
+Default Y for patch/minor; default N for major/downgrade. If they decline, end gracefully — leave the plan in their hands.
+
+### 5. Execute step-by-step
+
+For each step in `plan.steps`:
+
+- Skip `optional: true` steps from auto-execution (devcontainer rebuild is the only one today; surface it after)
+- Show: "[i/N] purpose"
+- Run: the command via Bash
+- Note: success/failure based on exit code
+
+If any step fails, **stop**. Don't continue with downstream steps. Surface:
+
+- Which step failed + its stderr
+- Suggested recovery: "Run `npx vyuh-dxkit doctor` to see current state, or invoke the `dxkit-fix` skill to walk through repair."
+
+### 6. Verify with doctor
+
+If all steps succeeded, run `npx vyuh-dxkit doctor` and report. If doctor surfaces operational issues post-upgrade (e.g. `summary.fixable[]` not empty), **hand off to dxkit-fix** — say "Upgrade complete, but doctor surfaced N gaps. Walking through dxkit-fix to close them."
+
+### 7. Surface manual follow-ups
+
+Iterate optional steps in the plan:
+
+```
+⚠ Your .devcontainer/ was refreshed. Rebuild your container to pick up:
+    VSCode:     Command Palette → "Dev Containers: Rebuild Container"
+    Codespaces: Command Palette → "Codespaces: Rebuild Container"
+    Local Docker: `docker compose down && docker compose up -d --build`
+```
+
+## What dxkit-update can NOT do
+
+- **Cross-major migrations** — major bumps may need MIGRATION.md guidance + manual policy edits. Surface the link; don't auto-execute.
+- **Customer code changes** — if the upgrade requires changes to the customer's scoring policy, baseline schema, or workflow file customizations, point at the CHANGELOG.md section and stop.
+- **Downgrades** — never auto-execute. Always confirm; warn about schema differences; suggest backing up `.dxkit/baselines/` first.
+- **Rollback** — if execution mid-step fails, dxkit-update can't undo the binary install. Customer needs to `npm install @vyuhlabs/dxkit@<previous-version>` themselves.
+
+## Boundary with other lifecycle skills
+
+| Customer state | Reach for |
+|---|---|
+| "I have nothing" | `dxkit-onboard` |
+| "I have working install, make it newer" | **dxkit-update (this skill)** |
+| "Doctor says X is broken" | `dxkit-fix` |
+| "I want to run a report" | `dxkit-reports` |
+| "Fix these findings" | `dxkit-action` |
+| "Configure dxkit" | `dxkit-config` |
+| "Set up hooks" | `dxkit-hooks` |
+| "Explain dxkit" | `dxkit-learn` |
+
+If the customer asks something that spans skills (e.g. "update dxkit and then fix the new issues"), chain: dxkit-update first, then auto-invoke dxkit-fix on the post-upgrade doctor output.
+
+## CHANGELOG hygiene (worth raising)
+
+The plan's `changelogNote` field points at the canonical CHANGELOG.md URL. Currently it's just a pointer — future versions of `vyuh-dxkit upgrade --plan` may parse the changelog and surface per-version highlights inline. For now, when the customer asks "what changed?", offer to fetch + summarize the CHANGELOG.md for the version range:
+
+```bash
+# Fetch the changelog locally (the installed package ships it)
+cat node_modules/@vyuhlabs/dxkit/CHANGELOG.md
+```
+
+Or for content between current and target (which isn't in the installed tarball until AFTER upgrade), suggest visiting the URL in `plan.changelogNote`.
+
+## Final report
+
+After the loop completes:
+
+```
+✓ Upgraded: dxkit X → Y
+✓ Scaffold refreshed: N files updated, M new (e.g. dxkit-fix skill if upgrading from <2.5.2)
+✓ Doctor: all green
+○ Manual: rebuild devcontainer to pick up changes
+```
+
+Or if something failed:
+
+```
+✗ Upgrade halted at step [i/N]: <purpose>
+   stderr: <captured>
+   → Recovery: `npx vyuh-dxkit doctor` to see current state; ask "fix dxkit" to walk through repair
+```
+
+End with a one-line CTA: "Anything else? Ask 'check dxkit health' to see current scores on the new version."

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,
@@ -50,23 +24,14 @@
   // registry pinned-versions advanced since last use.
   "postStartCommand": "command -v vyuh-dxkit >/dev/null 2>&1 && vyuh-dxkit tools list || true",
 
+  // Extensions list is generated by `vyuh-dxkit init` from the detected
+  // stack — only active packs' editor support gets installed. Always-on
+  // entries (anthropic.claude-code + GitHub Actions/PR) ship on every
+  // container regardless. Add or remove entries by hand to override the
+  // auto-detected set.
   "customizations": {
     "vscode": {
-      "extensions": [
-        "anthropic.claude-code",
-        "dbaeumer.vscode-eslint",
-        "esbenp.prettier-vscode",
-        "ms-python.python",
-        "ms-python.vscode-pylance",
-        "golang.go",
-        "rust-lang.rust-analyzer",
-        "ms-dotnettools.csharp",
-        "redhat.java",
-        "fwcd.kotlin",
-        "rebornix.ruby",
-        "github.vscode-github-actions",
-        "github.vscode-pull-request-github"
-      ],
+      "extensions": __DXKIT_DEVCONTAINER_EXTENSIONS__,
       "settings": {
         "editor.formatOnSave": true,
         "files.eol": "\n"

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

@@ -23,31 +23,60 @@ 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
 
-# Resolve dxkit. Prefer the project-local install if a `package.json`
-# pinned dxkit in devDependencies; otherwise install globally so the
-# binary is on PATH for the rest of the script and any subshell.
+# Resolve dxkit for THIS script. Prefer the project-local install if a
+# package.json pinned dxkit in devDependencies (so the script uses the
+# project's pinned version); otherwise install globally and use that.
 if [ -x ./node_modules/.bin/vyuh-dxkit ]; then
   DXKIT="./node_modules/.bin/vyuh-dxkit"
 elif command -v vyuh-dxkit >/dev/null 2>&1; then
   DXKIT="vyuh-dxkit"
 else
-  echo "==> Installing @vyuhlabs/dxkit globally..."
+  echo "==> Installing @vyuhlabs/dxkit globally (for script use)..."
   npm install -g @vyuhlabs/dxkit
   DXKIT="vyuh-dxkit"
 fi
+
+# Make sure `vyuh-dxkit` is on the CUSTOMER's interactive shell PATH
+# regardless of where the script-local resolution above ended up.
+# Project-local installs (./node_modules/.bin/) are NOT on PATH for
+# terminal sessions or for the dxkit-* agent skills' bash invocations
+# — only the global install puts the bare command on PATH. Without
+# this, the customer types `vyuh-dxkit doctor` and gets "command not
+# found" until they discover `npx vyuh-dxkit`. Soft-fail: if global
+# install fails (offline / registry hiccup), `npx vyuh-dxkit` still
+# works as a fallback.
+if ! command -v vyuh-dxkit >/dev/null 2>&1; then
+  echo "==> Installing @vyuhlabs/dxkit globally (for shell PATH)..."
+  npm install -g @vyuhlabs/dxkit || \
+    echo "WARN: global install failed — customer terminal will need 'npx vyuh-dxkit'." >&2
+fi
 echo "==> Using dxkit binary: ${DXKIT}"
 
 echo "==> Installing scanner toolchain via dxkit registry..."