@vyuhlabs/dxkit 2.5.0 → 2.5.2

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

@@ -0,0 +1,165 @@
+---
+name: dxkit-fix
+description: Repair a broken dxkit install — read doctor's structured output and walk the customer through each fix. Use when the user asks "fix dxkit", "fix my dxkit install", "doctor says X but Y is broken", "the pre-push hook isn't firing", "vyuh-dxkit command not found", or anything else that points at a broken-install state. Hands off to dxkit-init for fresh installs and dxkit-hooks for hook-specific deep dives.
+---
+
+# dxkit-fix
+
+This skill repairs broken dxkit installs. It does NOT install dxkit from scratch (that's `dxkit-init`) and it does NOT triage code findings (that's `dxkit-action`). Use it when something about the install itself is wrong — hooks not firing, vyuh-dxkit not on PATH, scanner toolchain missing pieces, baseline absent, etc.
+
+## How dxkit-fix works
+
+The skill consumes `npx vyuh-dxkit doctor --json` output. Doctor returns a structured `DoctorReport` with a `summary.fixable[]` array — every failing check carries:
+
+- `label` — the problem in one line
+- `fix.hint` — the human-readable explanation
+- `fix.command` — the shell command that repairs it (optional)
+- `fix.skill` — a more specific dxkit-* skill that can deep-dive (optional)
+
+The skill iterates `summary.fixable[]`, asks the customer for confirmation on each fix (with the command shown), runs it, then re-runs doctor at the end to verify everything closed.
+
+## The repair loop
+
+```
+[1] Run doctor in JSON mode    → npx vyuh-dxkit doctor --json
+[2] Read summary.fixable[]     → enumerate broken signals + fix commands
+[3] For each fixable:
+      [3a] Show the customer: label + hint + command
+      [3b] Confirm (default Y)
+      [3c] Run the command in their shell
+      [3d] Note success/failure
+[4] Re-run doctor              → verify the previously-fixable list is now empty
+[5] Report what remains        → any non-fixable failures + which dxkit-* skill handles them
+```
+
+## Steps
+
+### 1. Snapshot the broken state
+
+```bash
+npx vyuh-dxkit doctor --json > /tmp/dxkit-doctor.json
+```
+
+Capturing to a file (instead of piping inline) lets the customer re-read what was broken if a fix takes multiple iterations.
+
+### 2. Read the fixable list
+
+The JSON has shape `{ schema: "doctor.v1", checks: [...], summary: { fixable: [...] } }`. Iterate `summary.fixable` only — each entry has `ok: false` AND a `fix` block. Failing checks WITHOUT a fix block are informational (e.g. a missing optional toolchain) and shouldn't be touched here.
+
+### 3. Walk the customer through each fix
+
+For every fixable entry, present:
+
+| Field | What to show |
+|---|---|
+| `label` | Section heading ("git hooks active — not activated") |
+| `fix.hint` | One-line "what this means" explanation |
+| `fix.command` | The exact shell command, in a code block |
+| `fix.skill` (if present and ≠ dxkit-fix) | "For a deeper walkthrough, ask Claude Code: 'set up hooks'" (or whatever the skill's trigger is) |
+
+Then ASK the customer: "Run this fix? [Y/n]". Default Y. If they decline, skip and move on.
+
+When they confirm, run the command. Stream output. Note the exit code.
+
+### 4. Idempotency check
+
+Every fix command in the doctor output is designed to be idempotent — re-running it on a working install is a no-op (or a refresh). So even if a customer answers Y twice by accident, nothing breaks.
+
+### 5. Verify with a second doctor run
+
+After all fixes are applied (or declined), run `npx vyuh-dxkit doctor --json` again. The new `summary.fixable[]` should be a strict subset of the first run's. If something didn't close, surface it with the original `fix.hint` and offer to retry or escalate to the more specific skill.
+
+## What dxkit-fix can repair
+
+Driven by doctor's tier 3 (operational health) — these are the canonical repairables today:
+
+| Symptom (doctor label) | Fix command | Notes |
+|---|---|---|
+| `git hooks active` not active | `npx vyuh-dxkit hooks activate` | Sets `core.hooksPath = .githooks`. Refuses to clobber husky/lefthook configs. |
+| `baseline captured` missing | `npx vyuh-dxkit baseline create` | First-run: locks in today's findings as "pre-existing." Warn customer this is value-laden — see "Capturing the FIRST baseline" below. |
+| `vyuh-dxkit on PATH` not found | `npm install -g @vyuhlabs/dxkit` | Global install ensures the bare CLI works in any shell session. |
+| `scanner toolchain` missing pieces | `npx vyuh-dxkit tools install --yes` | Reinstalls any ✗ tools per TOOL_DEFS. Idempotent on already-installed tools. |
+| `.npmrc legacy-peer-deps persistence` missing | `echo "legacy-peer-deps=true" >> .npmrc` | Locks in the peer-dep resolution mode for future `npm install` calls. |
+| `CI guardrails workflow` missing | `npx vyuh-dxkit init --with-ci --yes` | Adds the dxkit-guardrails.yml workflow. Idempotent. |
+| Agent DX tier failures (manifest missing, AGENTS.md missing, .claude/* missing) | `npx vyuh-dxkit init --full --yes` or `npx vyuh-dxkit update` | Init for fresh installs; update for refreshes. |
+
+## Capturing the FIRST baseline — be deliberate
+
+Of all the fixes, `baseline create` is the only one 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."
+
+If the customer's repo has uncaptured findings that are real security issues (hardcoded secrets, leaked API keys, etc.), creating a baseline NOW locks those in as accepted. They won't trip the guardrail check.
+
+Before running `baseline create` on a customer who has NEVER captured one, surface this tradeoff:
+
+> Capturing a baseline locks in **N** current findings as "pre-existing." If any of those are real defects you'd want to fix first (secrets to rotate, vulnerable deps to upgrade), tell me and I'll show you what's flagged so we can triage before baseline.
+>
+> Skip baseline now if: you have secrets in the repo, or you'd rather fix-as-you-go than accept the current state.
+> Capture baseline now if: the codebase is a known-messy brownfield and you want guardrails on future regressions specifically.
+
+If they say "show me what's flagged first," hand off to `dxkit-action` — that skill triages findings before baseline lock-in.
+
+## What dxkit-fix can NOT repair
+
+These need a different skill or human action:
+
+- **Code findings** (hardcoded secrets, lint errors, duplicates, missing tests) — `dxkit-action` handles triage + fixing. Doctor only flags that the install is working; the analyzer results are a separate surface.
+- **Branch protection on the GitHub repo** — needs `gh api` credentials + repo-admin rights. The `setup-branch-protection` CLI (when available) wraps this. If doctor flags the workflow as missing but the customer's CI is healthy on PRs, this is a documentation gap, not an install gap.
+- **Real secret rotation** — even after dxkit detects a hardcoded API key, the credential needs to be rotated in its issuing provider's UI by a human.
+- **External tool toolchains** (e.g. a Go compiler for stacks that don't have Go) — dxkit's TOOL_DEFS install most scanner tools; toolchains for the customer's project itself are out of scope.
+
+## When to delegate to a more specific dxkit-* skill
+
+Doctor's `fix.skill` field signals "this is more nuanced than a single command — walk through it via that skill." Cases:
+
+| `fix.skill` | When to delegate |
+|---|---|
+| `dxkit-init` | Customer doesn't have a manifest at all — they need the full first-install flow, not a repair. |
+| `dxkit-hooks` | Hook-related repair where the customer also wants chaining advice (husky/lefthook integration, bypass workflow, removal). |
+| `dxkit-config` | Customer wants to tune what dxkit flags (e.g. exclude a vendored dir, adjust severity policy) rather than fix a broken state. |
+| (no skill, command only) | Plain repair — apply the command and move on. |
+
+If `fix.skill === "dxkit-fix"`, that's the default path — handle it here.
+
+## Idempotency + safety
+
+Every repair this skill drives is idempotent and reversible:
+
+- `hooks activate` is no-op if hooks already pointed at .githooks
+- `baseline create` refuses to overwrite an existing baseline without `--force` — so accidentally running it twice can't corrupt state
+- `tools install --yes` skips already-installed tools (per TOOL_DEFS check command)
+- `npm install -g @vyuhlabs/dxkit` upgrades or installs as needed; no data loss
+- `.npmrc` append is line-deduplicated
+
+So a customer who declines a fix, then runs into it again later, can re-invoke the skill with no penalty.
+
+## Failure modes
+
+If a fix command fails (non-zero exit):
+
+1. **Capture the stderr** so the customer can see why
+2. **Don't auto-retry** — the customer's environment may have a problem the fix can't solve (no network, permission denied, registry hiccup)
+3. **Suggest a manual workaround** if there's an obvious one (e.g. for global install failures, suggest `sudo npm install -g` on systems where the npm prefix isn't user-writable)
+4. **Continue with the remaining fixes** — one failure shouldn't block the rest
+
+Surface failures in the final summary alongside what DID get fixed.
+
+## Final summary
+
+After the loop completes, structure the report:
+
+```
+✓ Repaired:
+   • git hooks active
+   • vyuh-dxkit on PATH
+
+✗ Failed:
+   • baseline captured — `vyuh-dxkit baseline create` exit 1 (no .dxkit/ write permission?)
+
+→ Skipped:
+   • .npmrc legacy-peer-deps persistence (you declined)
+
+Remaining issues (not auto-fixable):
+   • CI guardrails workflow missing → ask 'set up dxkit init' to walk through init --with-ci
+```
+
+End with a one-line CTA: "Run `npx vyuh-dxkit doctor` to confirm the final state, or ask 'fix dxkit' again if anything new comes up."

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 `npx 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
+npx vyuh-dxkit hooks activate
+git config core.hooksPath .githooks
+```
+
+`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 `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.
+
+## 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
+   npx 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 && 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.
+
+## 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)
+- `.npx 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 = `npx 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 `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 `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)
+- **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
+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
+
+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
+
+- `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
+- `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.