@vyuhlabs/dxkit 2.5.1 → 2.5.2

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

@@ -13,7 +13,7 @@ This skill handles the git-hook surface dxkit ships. Use it to install hooks, de
 
 `.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.
+Both run `npx vyuh-dxkit guardrail check`. The check exits 1 (blocking) on net-new findings vs. the baseline.
 
 ## Installation
 
@@ -36,21 +36,21 @@ Hooks activate by setting `core.hooksPath = .githooks` in the local git config.
 
 ```bash
 # Either of these works
-vyuh-dxkit hooks activate
+npx 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.
+`npx 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).
+2. **hooksPath is wired**: `git config --local --get core.hooksPath` should print `.githooks`. If empty or pointing elsewhere, run `npx vyuh-dxkit hooks activate`.
+3. **dxkit binary is on PATH**: from the repo root, `which npx 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 `npx vyuh-dxkit baseline create`.
+5. **Run the check by hand**: `npx 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.
 
@@ -81,7 +81,7 @@ This skips ALL git hooks (not just dxkit's). After the emergency:
 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
+   npx vyuh-dxkit baseline create --force
    git add .dxkit/baselines/main.json
    git commit -m "chore(baseline): accept regression from <ref>"
    ```

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

@@ -66,7 +66,7 @@ Ask the user what they want, then pick the right invocation:
 
 ## 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`.
+- **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 && npx 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.
@@ -77,7 +77,7 @@ A complete install lays down ~15-20 files (down from the 2.5.0 ~73-file scaffold
 
 - `.dxkit/baselines/main.json` (after `baseline create`)
 - `.dxkit-ignore` (starter template)
-- `.vyuh-dxkit.json` (manifest)
+- `.npx vyuh-dxkit.json` (manifest)
 - `.githooks/pre-push`
 - `.github/workflows/dxkit-guardrails.yml`
 - `.github/workflows/dxkit-baseline-refresh.yml`
@@ -89,5 +89,5 @@ A complete install lays down ~15-20 files (down from the 2.5.0 ~73-file scaffold
 - `.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`)
+- `package.json` (postinstall = `npx vyuh-dxkit hooks activate`)
 - `.gitignore` (additive: `.dxkit/reports/`, `.dxkit/cache/`, `graphify-out/`)

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

@@ -30,11 +30,11 @@ Each dimension is a 0-100 score with letter grade (A≥80, B≥60, C≥40, D≥2
 | **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.
+Run `npx 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:
+dxkit doesn't write parsers — it orchestrates established tools and computes scores. The full list is in `TOOL_DEFS` (or run `npx 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)
@@ -59,10 +59,10 @@ That's why "fix a critical, leave the medium" works — the medium's fingerprint
 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
+npx vyuh-dxkit baseline create               # Capture current state into .dxkit/baselines/main.json
+npx vyuh-dxkit baseline show                 # Summarize what's recorded
+npx vyuh-dxkit baseline show --kind secret   # Drill into a specific finding kind
+npx vyuh-dxkit guardrail check               # Diff current scan vs baseline; exit 1 on net-new
 ```
 
 ## Hooks
@@ -76,9 +76,9 @@ Activation is wired via `npm postinstall` so `npm install` after `git clone` set
 
 ## How to learn more
 
-- `vyuh-dxkit <subcommand> --help` — flag reference
-- `vyuh-dxkit baseline show` — what your repo already has recorded
+- `npx vyuh-dxkit <subcommand> --help` — flag reference
+- `npx 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
+- `npx 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-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

@@ -1,6 +1,6 @@
 ---
 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.
+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
@@ -11,15 +11,15 @@ This skill runs dxkit analyzers and reads their output back to the user. It's th
 
 | 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` |
+| "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
 
@@ -56,7 +56,7 @@ Score → rating: A ≥ 80, B ≥ 60, C ≥ 40, D ≥ 20, E < 20. **Cap tiers**
 ### Quick health check (warm cache)
 
 ```bash
-vyuh-dxkit health
+npx vyuh-dxkit health
 ```
 
 Re-uses cached scanner outputs where possible. ~5-15s on warm cache, ~30-60s cold.
@@ -64,9 +64,9 @@ Re-uses cached scanner outputs where possible. ~5-15s on warm cache, ~30-60s col
 ### 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
+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.
@@ -74,7 +74,7 @@ vyuh-dxkit dashboard                 # Renders the latest reports into one HTML
 ### Per-PR scope
 
 ```bash
-vyuh-dxkit guardrail check
+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).
@@ -82,8 +82,8 @@ Diffs the current scan vs the baseline. Exit 1 on net-new findings (the same log
 ### 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
+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.
@@ -105,7 +105,7 @@ Hand off to the `dxkit-action` skill — that's the workflow for prioritizing +
 
 ## Troubleshooting
 
-- **"Scanner X unavailable"** → run `vyuh-dxkit tools list` to see status; `vyuh-dxkit tools install` to install missing ones.
+- **"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

@@ -24,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"