---
name: dxkit-config
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

This skill modifies the three configuration files dxkit reads. Reach for it when the user asks to "ignore this vendored directory," "stop flagging X," "make the guardrail stricter/laxer," or "what controls Y."

## The three config files

| 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 |
| `.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) |
| `.dxkit/tools.json` | Where dxkit looks for / installs scanner binaries | Tools live in a non-standard or corp-managed directory, or PATH detection misses them (common on Windows / locked-down machines) |

## Adding a path to `.dxkit-ignore`

Format mirrors `.gitignore`: directory/, file-glob, multi-segment paths.

```bash
# Append a vendored directory
echo 'vendor/' >> .dxkit-ignore

# Append a generated-code dir
echo 'src/generated/' >> .dxkit-ignore

# Append a glob (auto-generated TypeScript types)
echo '*.generated.ts' >> .dxkit-ignore
```

Or use Edit to add multiple entries cleanly. The file accepts comments (`#`).

After editing, the **next** `baseline create` picks up the change. Existing baselines stay valid (the file's content hash is recorded in the baseline envelope, so a mismatch surfaces as a "baseline regenerated against newer .dxkit-ignore" note rather than an error).

### Common exclusions

```gitignore
# Vendored third-party code committed to git
vendor/
third_party/

# Generated code
generated/
*.generated.ts
*.designer.cs
*.pb.go
src/proto-types/

# Legacy code you don't want to track findings against
legacy/
deprecated/

# Test fixtures that inflate metrics
fixtures/large/
test/fixtures/

# Build artifacts (most are gitignored already, but defensive)
dist/
build/
target/
```

## Tuning `.npx vyuh-dxkit.json`

This file is mostly auto-generated. Common manual edits:

```json
{
  "framework": "express",          // Override if auto-detection picked wrong
  "languages": {
    "typescript": true,
    "python": false
  },
  "testRunner": {
    "framework": "vitest",         // Override auto-detected test runner
    "command": "npm test"
  }
}
```

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`

The policy file controls what severity counts as "blocking" for the guardrail. Default:

```json
{
  "code": { "block": ["critical", "high"], "warn": ["medium"] },
  "dependency": { "block": ["critical", "high"], "warn": ["medium"] },
  "secret": { "block": ["critical", "high", "medium", "low"] },
  "test-gap": { "block": ["critical"], "warn": ["high"] },
  "duplicate": { "warn": ["all"] }
}
```

Each finding-kind has `block` (exit 1) and `warn` (log only) lists. Adjust to your team's tolerance:

```json
// Stricter — block medium SAST findings too
{ "code": { "block": ["critical", "high", "medium"] } }

// Laxer — make secret medium/low non-blocking (don't recommend)
{ "secret": { "block": ["critical", "high"] } }
```

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.

## Pointing dxkit at a custom tool directory (`.dxkit/tools.json`)

By default dxkit finds scanner binaries (gitleaks, semgrep, jscpd, osv-scanner, cloc, …) on `PATH` and in the usual per-ecosystem locations (npm global, pipx `~/.local/bin`, cargo, go, brew). When tools live somewhere else — a corp-managed directory, a project-local toolbox, or a locked-down Windows box where you can't write to the default locations — declare it here:

```json
{
  "probePaths": ["D:\\devtools\\bin", "/opt/team/bin"],
  "installDir": "D:\\devtools\\bin"
}
```

- **`probePaths`** — extra directories dxkit searches for each tool (Windows-aware: matches `tool.exe` / `tool.cmd`). This is the primary mechanism — if a tool is already installed somewhere, list its directory here and `npx vyuh-dxkit tools list` will find it.
- **`installDir`** — where `npx vyuh-dxkit tools install` drops new binaries. dxkit injects this into each package manager (pipx, npm-g, cargo, go) and automatically probes both `installDir` and `installDir/bin`, so a freshly installed tool is discoverable without extra config.

Both fields are optional; an absent or malformed file is ignored (detection just falls back to the defaults — it never errors).

### When to use it

A `npx vyuh-dxkit doctor` or `tools list` showing tools as missing **when they are actually installed** is the signal. Confirm where the binary lives (`where gitleaks` on Windows, `which gitleaks` on POSIX), then:

1. Create / edit `.dxkit/tools.json` and add that directory to `probePaths`.
2. Re-run `npx vyuh-dxkit tools list` — the tool should now show as available.
3. If the user wants dxkit to *install* tools into a specific dir, set `installDir`, then `npx vyuh-dxkit tools install`.
4. Regenerate the baseline so it reflects the now-available scanners: `npx vyuh-dxkit baseline create --force`.

## 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 → `.npx vyuh-dxkit.json`).
2. Open the file, propose the edit, confirm.
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

- Don't edit `.dxkit/cache/` or `.dxkit/reports/` — they're regenerated on every run (gitignored).
- Don't manually mutate `.dxkit/baselines/main.json` — use `baseline create --force` to regenerate.
- Don't add `.dxkit/` to `.dxkit-ignore` — dxkit itself doesn't scan its own outputs.
