@vyuhlabs/dxkit 2.5.1 → 2.5.2

package/dist/upgrade.js

@@ -0,0 +1,324 @@
+"use strict";
+/**
+ * `vyuh-dxkit upgrade` — combined CLI for the dxkit upgrade flow.
+ *
+ * Two modes, one subcommand:
+ *
+ *   `--plan [--json]` — preview only. Emits UpgradePlan JSON
+ *   (consumed by dxkit-update skill) or text-prose summary. No
+ *   mutations. Used to inspect what an upgrade would do before
+ *   committing.
+ *
+ *   (no flag, or `--yes`) — execute. Runs the three-step upgrade:
+ *     1. `npm install @vyuhlabs/dxkit@<target>`     (binary)
+ *     2. `npx vyuh-dxkit update`                    (scaffold refresh)
+ *     3. `npx vyuh-dxkit doctor`                    (verify)
+ *   Then prints devcontainer-rebuild instructions if .devcontainer/
+ *   was refreshed.
+ *
+ * Architectural mirror of the doctor → dxkit-fix pattern: structured
+ * CLI output (--plan --json) for skill consumption, execution mode
+ * for direct human use. Same shape, different content.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyDelta = classifyDelta;
+exports.buildUpgradePlan = buildUpgradePlan;
+exports.runUpgrade = runUpgrade;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const logger = __importStar(require("./logger"));
+// ────────────────────────────────────────────────────────────────────
+// Version helpers
+// ────────────────────────────────────────────────────────────────────
+function readScaffoldVersion(cwd) {
+    const manifestPath = path.join(cwd, '.vyuh-dxkit.json');
+    if (!fs.existsSync(manifestPath))
+        return null;
+    try {
+        const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+        return manifest.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function readBinaryVersion(cwd) {
+    try {
+        const out = (0, child_process_1.execSync)('npx --no-install vyuh-dxkit --version 2>/dev/null', {
+            cwd,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf-8',
+        });
+        return out.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+function readLatestPublished() {
+    try {
+        const out = (0, child_process_1.execSync)('npm view @vyuhlabs/dxkit version 2>/dev/null', {
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf-8',
+            timeout: 15000,
+        });
+        return out.trim();
+    }
+    catch {
+        // npm registry unreachable — return empty so caller can decide
+        return '';
+    }
+}
+/**
+ * Classify the delta between two semver-shaped strings. Returns
+ * `'none'` if equal, `'downgrade'` if target < current.
+ */
+function classifyDelta(current, target) {
+    if (!current || !target)
+        return 'none';
+    const [c1, c2, c3] = current.split('.').map((n) => parseInt(n, 10));
+    const [t1, t2, t3] = target.split('.').map((n) => parseInt(n, 10));
+    if (Number.isNaN(c1) || Number.isNaN(t1))
+        return 'none';
+    if (t1 > c1)
+        return 'major';
+    if (t1 < c1)
+        return 'downgrade';
+    if (t2 > c2)
+        return 'minor';
+    if (t2 < c2)
+        return 'downgrade';
+    if (t3 > c3)
+        return 'patch';
+    if (t3 < c3)
+        return 'downgrade';
+    return 'none';
+}
+// ────────────────────────────────────────────────────────────────────
+// Plan construction
+// ────────────────────────────────────────────────────────────────────
+function buildUpgradePlan(cwd, opts = {}) {
+    const scaffold = readScaffoldVersion(cwd);
+    const binary = (opts._readBinary ?? readBinaryVersion)(cwd);
+    const latest = opts.target ?? (opts._readLatest ?? readLatestPublished)();
+    // Use binary version as the "current" anchor for delta classification —
+    // it's what npm install will replace. Scaffold version informs whether
+    // vyuh-dxkit update is needed even when binary is already up to date.
+    const delta = classifyDelta(binary, latest);
+    const steps = [];
+    const warnings = [];
+    if (!latest) {
+        warnings.push('Could not query npm for the latest version (registry unreachable or rate-limited). ' +
+            'Pass --target=X.Y.Z to upgrade to a specific version.');
+    }
+    // Step 1: binary upgrade. Always included unless delta is none AND
+    // scaffold already matches.
+    if (delta !== 'none' || (scaffold && binary && scaffold !== binary)) {
+        if (latest) {
+            steps.push({
+                command: `npm install @vyuhlabs/dxkit@${latest}`,
+                purpose: `Install dxkit binary ${binary ?? '(missing)'} → ${latest}`,
+            });
+        }
+    }
+    // Step 2: scaffold refresh. Always run when scaffold ≠ binary OR after
+    // a binary upgrade (scaffold may need updating to match the new binary).
+    if (latest) {
+        steps.push({
+            command: 'npx vyuh-dxkit update',
+            purpose: 'Refresh scaffold (.devcontainer, .githooks, .claude/skills, CI workflows)',
+        });
+    }
+    // Step 3: verify with doctor.
+    if (latest) {
+        steps.push({
+            command: 'npx vyuh-dxkit doctor',
+            purpose: 'Verify operational health post-upgrade',
+        });
+    }
+    // Optional: devcontainer rebuild reminder. We mark this optional so
+    // dxkit-update can surface it as a "you also need to do this manually"
+    // step rather than something the CLI can execute.
+    const hasDevcontainer = fs.existsSync(path.join(cwd, '.devcontainer', 'devcontainer.json'));
+    if (hasDevcontainer && delta !== 'none') {
+        steps.push({
+            command: '# Rebuild devcontainer: VSCode Command Palette → "Dev Containers: Rebuild Container"',
+            purpose: 'Pick up devcontainer.json changes (if any) — manual step',
+            optional: true,
+        });
+    }
+    // Warnings.
+    if (delta === 'major') {
+        warnings.push(`Major version jump (${binary} → ${latest}). Read CHANGELOG.md for breaking changes ` +
+            'before running the upgrade.');
+    }
+    if (delta === 'downgrade') {
+        warnings.push(`Target version ${latest} is OLDER than installed ${binary}. ` +
+            'Downgrades are not officially supported; baseline + manifest schemas may differ.');
+    }
+    if (scaffold && binary && scaffold !== binary) {
+        warnings.push(`Scaffold version (${scaffold}) doesn't match binary (${binary}). ` +
+            'Step 2 (vyuh-dxkit update) will reconcile.');
+    }
+    return {
+        schema: 'upgrade-plan.v1',
+        generatedAt: new Date().toISOString(),
+        cwd,
+        current: { binary, scaffold },
+        target: latest,
+        delta,
+        steps,
+        warnings,
+        changelogNote: latest
+            ? `For per-version details: https://github.com/vyuh-labs/dxkit/blob/main/CHANGELOG.md`
+            : '',
+    };
+}
+// ────────────────────────────────────────────────────────────────────
+// Renderers
+// ────────────────────────────────────────────────────────────────────
+function renderPlanProse(plan) {
+    logger.header('vyuh-dxkit upgrade --plan');
+    logger.info(`Current: scaffold ${plan.current.scaffold ?? '(none)'} + binary ${plan.current.binary ?? '(none)'}`);
+    logger.info(`Target:  ${plan.target || '(latest unavailable)'}`);
+    logger.info(`Delta:   ${plan.delta}`);
+    if (plan.warnings.length) {
+        console.log(''); // slop-ok
+        for (const w of plan.warnings)
+            logger.warn(w);
+    }
+    if (plan.steps.length) {
+        console.log(''); // slop-ok
+        logger.info('Plan:');
+        plan.steps.forEach((s, i) => {
+            const marker = s.optional ? '○' : '●';
+            logger.dim(`  ${marker} [${i + 1}/${plan.steps.length}] ${s.purpose}`);
+            logger.dim(`     ${s.command}`);
+        });
+    }
+    if (plan.changelogNote) {
+        console.log(''); // slop-ok
+        logger.dim(plan.changelogNote);
+    }
+}
+// ────────────────────────────────────────────────────────────────────
+// Execution
+// ────────────────────────────────────────────────────────────────────
+function runStep(step, cwd, dryRun) {
+    if (step.optional) {
+        // Optional steps are never auto-executed — surfaced for the
+        // customer to do manually.
+        return true;
+    }
+    logger.info(`→ ${step.purpose}`);
+    logger.dim(`  ${step.command}`);
+    if (dryRun) {
+        logger.dim('  (dry-run; skipping)');
+        return true;
+    }
+    // Shell out to a real shell so npx/npm work the same way as the
+    // customer's terminal would. We DON'T use spawnSync's shell:true
+    // bash escaping concerns because the commands here are all dxkit-
+    // controlled — no customer input flows into them.
+    const result = (0, child_process_1.spawnSync)('bash', ['-c', step.command], {
+        cwd,
+        stdio: 'inherit',
+    });
+    return result.status === 0;
+}
+async function runUpgradeExecution(cwd, plan, opts) {
+    // Print the plan so the customer sees what's about to happen.
+    renderPlanProse(plan);
+    if (plan.steps.length === 0) {
+        console.log(''); // slop-ok
+        logger.success('Already up to date — nothing to do.');
+        return;
+    }
+    if (!opts.yes && !opts.dryRun) {
+        // We don't bundle a real prompt library here — the upgrade is
+        // intended either non-interactive (--yes) or driven by the
+        // dxkit-update skill (which handles confirmation). Surface the
+        // hint so a direct human invocation knows to add --yes.
+        console.log(''); // slop-ok
+        logger.warn('Interactive confirmation is not implemented for this command. ' +
+            'Re-run with --yes to execute, --dry-run to print without executing, ' +
+            'or use the dxkit-update skill for a guided upgrade.');
+        return;
+    }
+    console.log(''); // slop-ok
+    logger.header('Executing upgrade');
+    const optionalAfter = [];
+    for (const step of plan.steps) {
+        if (step.optional) {
+            optionalAfter.push(step);
+            continue;
+        }
+        const ok = runStep(step, cwd, !!opts.dryRun);
+        if (!ok) {
+            logger.fail(`Step failed: ${step.purpose}`);
+            logger.dim('  Upgrade aborted. Re-run `vyuh-dxkit doctor` to see current state.');
+            process.exitCode = 1;
+            return;
+        }
+    }
+    console.log(''); // slop-ok
+    logger.success(`Upgraded to ${plan.target}.`);
+    if (optionalAfter.length) {
+        console.log(''); // slop-ok
+        logger.info('Manual steps still required:');
+        for (const s of optionalAfter)
+            logger.dim(`  • ${s.purpose}\n    ${s.command}`);
+    }
+}
+// ────────────────────────────────────────────────────────────────────
+// Entry point
+// ────────────────────────────────────────────────────────────────────
+async function runUpgrade(cwd, opts = {}) {
+    const plan = buildUpgradePlan(cwd, opts);
+    if (opts.planOnly) {
+        if (opts.json) {
+            // Logger already routes to stderr in --json mode (cli.ts sets it).
+            console.log(JSON.stringify(plan, null, 2)); // slop-ok
+        }
+        else {
+            renderPlanProse(plan);
+        }
+        return;
+    }
+    await runUpgradeExecution(cwd, plan, opts);
+}
+//# sourceMappingURL=upgrade.js.map

package/dist/upgrade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade.js","sourceRoot":"","sources":["../src/upgrade.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vyuhlabs/dxkit",
-  "version": "2.5.1",
+  "version": "2.5.2",
   "description": "AI-native developer experience toolkit for any codebase",
   "license": "MIT",
   "author": "Vyuh Labs",

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

@@ -42,7 +42,7 @@ Skip items where reachability is "no" (graphify can't find a call path) UNLESS t
 # 2. Remove the secret from the file
 # 3. If the secret was committed: `git filter-repo` or BFG to scrub history
 # 4. Re-scan to confirm gitleaks no longer reports it
-vyuh-dxkit vulnerabilities --json | jq '.summary.findings'
+npx vyuh-dxkit vulnerabilities --json | jq '.summary.findings'
 ```
 
 Don't try to redact the secret in place — the git history still has it. Rotation is the only true fix.
@@ -63,7 +63,7 @@ Suppression is `// nosemgrep: <rule-id>` on the offending line. Use sparingly
 # Find the patched version (osv-scanner / npm-audit / etc. report it)
 npm install <pkg>@<patched-version>
 # Re-run the scan
-vyuh-dxkit vulnerabilities
+npx vyuh-dxkit vulnerabilities
 ```
 
 For peer-dep conflicts: `npm install <pkg>@<patched-version> --legacy-peer-deps` (matches the post-create.sh fallback chain).
@@ -78,7 +78,7 @@ For Python: `pip install --upgrade <pkg>=<patched>` then re-pip-freeze. For Go:
 # 3. Run the test runner to confirm it passes
 npm test  # or pytest, go test, cargo test, etc.
 # 4. Re-run test-gaps to confirm the file dropped off the list
-vyuh-dxkit test-gaps
+npx vyuh-dxkit test-gaps
 ```
 
 Don't write tests that just import the module — write tests that exercise behavior. Useless tests inflate the count but don't move the dimension.
@@ -99,7 +99,7 @@ After each fix:
 
 ```bash
 # Re-run the SPECIFIC analyzer that flagged the finding
-vyuh-dxkit vulnerabilities  # or quality / test-gaps / health
+npx vyuh-dxkit vulnerabilities  # or quality / test-gaps / health
 ```
 
 The fix is verified when:
@@ -116,7 +116,7 @@ Once a finding is fixed AND verified gone, the workflow depends on what changed:
 | Scenario | Action |
 |---|---|
 | Fix landed via a code change | Commit the code. Baseline is unchanged. Future scans confirm the fix held. |
-| Fix landed via a config change (e.g., new entry in `.dxkit-ignore`) | Re-baseline: `vyuh-dxkit baseline create --force`. Commit both `.dxkit-ignore` and the new baseline. |
+| Fix landed via a config change (e.g., new entry in `.dxkit-ignore`) | Re-baseline: `npx vyuh-dxkit baseline create --force`. Commit both `.dxkit-ignore` and the new baseline. |
 | Finding accepted as known + not blocking | Re-baseline with explicit reason in the commit message. Future scans treat it as pre-existing, not net-new. |
 | Finding is genuinely a false positive | First try suppression on the offending line. If you can't suppress, re-baseline. |
 
@@ -127,7 +127,7 @@ Once a finding is fixed AND verified gone, the workflow depends on what changed:
 After fixing N findings, run the guardrail check before pushing:
 
 ```bash
-vyuh-dxkit guardrail check
+npx vyuh-dxkit guardrail check
 ```
 
 Exit 0 = your fixes didn't introduce any net-new regressions (you only removed/fixed things). Exit 1 = something new appeared; address that before pushing.

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."