@vyuhlabs/dxkit 2.5.1 → 2.6.0

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

@@ -1,6 +1,6 @@
 ---
 name: dxkit-config
-description: Edit dxkit configuration — add/remove paths in .dxkit-ignore, tune .vyuh-dxkit.json, adjust .dxkit/policy.json guardrail severity. Use when the user wants to exclude a directory from scanning, change scoring thresholds, or modify what blocks a PR.
+description: Edit dxkit configuration — add/remove paths in .dxkit-ignore, tune .npx vyuh-dxkit.json, adjust .dxkit/policy.json guardrail severity. Use when the user wants to exclude a directory from scanning, change scoring thresholds, or modify what blocks a PR.
 ---
 
 # dxkit-config
@@ -12,7 +12,7 @@ This skill modifies the three configuration files dxkit reads. Reach for it when
 | File | Purpose | When to edit |
 |---|---|---|
 | `.dxkit-ignore` | Extra paths dxkit's analyzers should skip (gitignore-style format) | Vendored code, generated code, test fixtures, large data files |
-| `.vyuh-dxkit.json` | Manifest of detected stack + custom settings (regenerated by `init` / `update`) | Rare — usually let `dxkit update` regenerate. Override version pins or framework detection here. |
+| `.npx vyuh-dxkit.json` | Manifest of detected stack + custom settings (regenerated by `init` / `update`) | Rare — usually let `dxkit update` regenerate. Override version pins or framework detection here. |
 | `.dxkit/policy.json` | Severity policy for guardrail check | Customize what blocks a PR (e.g., demote `medium` to warning) |
 
 ## Adding a path to `.dxkit-ignore`
@@ -62,7 +62,7 @@ build/
 target/
 ```
 
-## Tuning `.vyuh-dxkit.json`
+## Tuning `.npx vyuh-dxkit.json`
 
 This file is mostly auto-generated. Common manual edits:
 
@@ -80,7 +80,7 @@ This file is mostly auto-generated. Common manual edits:
 }
 ```
 
-When you edit this file, run `vyuh-dxkit update` to propagate changes through the rest of the scaffold (per-language rules, devcontainer features, etc.). Use `--force` only if you've also edited evolving files — otherwise `update` preserves customer changes.
+When you edit this file, run `npx vyuh-dxkit update` to propagate changes through the rest of the scaffold (per-language rules, devcontainer features, etc.). Use `--force` only if you've also edited evolving files — otherwise `update` preserves customer changes.
 
 ## Customizing `.dxkit/policy.json`
 
@@ -106,15 +106,15 @@ Each finding-kind has `block` (exit 1) and `warn` (log only) lists. Adjust to yo
 { "secret": { "block": ["critical", "high"] } }
 ```
 
-Run `vyuh-dxkit guardrail check --policy=.dxkit/policy.json` to test the new policy. If no `policy.json` exists, dxkit uses the built-in defaults.
+Run `npx vyuh-dxkit guardrail check --policy=.dxkit/policy.json` to test the new policy. If no `policy.json` exists, dxkit uses the built-in defaults.
 
 ## Workflow
 
 When the user asks for a config change:
 
-1. Identify which file owns the concern (path exclusion → `.dxkit-ignore`; severity routing → `.dxkit/policy.json`; detection override → `.vyuh-dxkit.json`).
+1. Identify which file owns the concern (path exclusion → `.dxkit-ignore`; severity routing → `.dxkit/policy.json`; detection override → `.npx vyuh-dxkit.json`).
 2. Open the file, propose the edit, confirm.
-3. After writing, run `vyuh-dxkit baseline create --force` if exclusions changed (so the baseline doesn't carry stale findings from the now-excluded paths).
+3. After writing, run `npx vyuh-dxkit baseline create --force` if exclusions changed (so the baseline doesn't carry stale findings from the now-excluded paths).
 4. Commit both: the config file + the regenerated baseline.
 
 ## What NOT to do

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

@@ -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,274 @@
+---
+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, ASK about disclosure posture (the baseline file is committed to git):
+
+> **About to capture the first baseline. One quick choice first — which posture fits this repo?**
+>
+> The baseline file lives at `.dxkit/baselines/main.json`. Three modes trade disclosure for diagnostic richness:
+>
+> - **`committed-full`** (default for private repos) — Rich entries with file paths, package names, advisory IDs. Best diagnostic quality. Fine when only your team reads the repo.
+> - **`committed-sanitized`** (compliance-conscious private) — Stripped to fingerprint + kind only. Hides location detail; matching still works. Good when many people have repo read access.
+> - **`ref-based`** (default for public repos) — No baseline file at all. Each guardrail check recomputes the prior side from a git ref (e.g. `origin/main`). Zero disclosure.
+>
+> Auto-pick: run `vyuh-dxkit baseline create` and dxkit picks the right default by probing `gh repo view`. Or pin explicitly via `--mode=<X>` or `.dxkit/policy.json`.
+
+Then the standard "lock-in" warning:
+
+> **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 (and they're happy with auto-picked mode):
+
+```bash
+npx vyuh-dxkit baseline create
+git add .dxkit/baselines/   # only if mode wrote a file (committed-*)
+git commit -m "chore: capture dxkit baseline"
+```
+
+If they want to PIN the mode explicitly (so every developer + CI run agrees), write `.dxkit/policy.json`:
+
+```bash
+mkdir -p .dxkit
+cat > .dxkit/policy.json <<'JSON'
+{
+  "baseline": {
+    "mode": "ref-based",
+    "ref": "origin/main"
+  }
+}
+JSON
+git add .dxkit/policy.json
+git commit -m "chore: pin baseline mode in policy.json"
+```
+
+### 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."