@vyuhlabs/dxkit 2.5.1 → 2.6.0

package/CHANGELOG.md

@@ -7,6 +7,324 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.6.0] - 2026-05-23
+
+The "per-finding suppression + public-repo-safe baselines" release.
+Adds the typed-category allowlist surface for false-positive /
+test-fixture / mitigated-externally / accepted-risk / deferred
+suppression with inline + file-level modes; retires license
+findings from the baseline (~73% size drop on real customer repos);
+introduces three baseline modes with visibility-aware defaults so
+public repos no longer leak file paths, package names, and
+advisory IDs through a committed baseline.
+
+### Added
+
+- **Per-finding allowlist** — `vyuh-dxkit allowlist add/list/show/audit/prune`.
+  Typed-category suppression (`false-positive`, `test-fixture`,
+  `mitigated-externally`, `accepted-risk`, `deferred`) with required
+  reason + (where relevant) expiry. Two surfaces: inline
+  `// dxkit-allow:<category> reason="..."` annotations and a
+  file-level `.dxkit/allowlist.json`. `accepted-risk` and `deferred`
+  require expiry (default 90 days). See
+  [docs/commands/allowlist.md](docs/commands/allowlist.md).
+- **Strict stale-annotation detection** — orphaned `dxkit-allow:`
+  annotations (where the underlying finding is now gone) emit a
+  new `stale-allow` baseline kind on the next scan. The
+  TypeScript `@ts-expect-error` pattern, applied to suppressions —
+  forces cleanup, prevents the annotation graveyard. Allowlisting
+  a `stale-allow` finding is forbidden; only remediation is to
+  remove the orphaned comment.
+- **Allowlist activity in PR comments** — the
+  `dxkit-guardrails.yml` workflow's sticky PR comment now includes
+  an "Allowlist activity" section listing every entry added (or
+  removed) on this branch versus the baseline commit. Reviewers
+  see new suppressions being introduced and can sanity-check
+  category + reason + expiry before approving.
+- **`vyuh-dxkit issue`** — pre-filled GitHub Issues for false
+  positives, missing findings, bugs, feature requests, and docs
+  gaps. Nothing submits automatically — the CLI opens the
+  customer's browser at a new-issue URL with env metadata
+  pre-populated, customer reviews + clicks "Submit." See
+  [docs/commands/issue.md](docs/commands/issue.md).
+- **`commentSyntax` on language packs** — each pack declares its
+  line-comment marker (`#` for python/ruby; `//` for
+  typescript/go/rust/csharp/kotlin/java). Drives the inline
+  allowlist-annotation generator across every language uniformly.
+  Recipe-enforced: scaffolder ships an empty placeholder so
+  unfilled packs fail the contract test until populated.
+- Three preemptive architecture rules in `scripts/check-architecture.sh`
+  lock down the allowlist canonical entry points: no `createHash`
+  inside `src/allowlist/`, no direct `allowlist.json` IO outside
+  the canonical loader, no language-comment fallback literals
+  (`?? '//'`) anywhere in the module.
+
+### Changed
+
+- **License findings retired from the baseline.** Per-package
+  license attributions no longer flow through the baseline
+  producer registry — they were informational, not regression
+  material, and dominated baselines on real customer repos
+  (~73% of entries). The canonical license inventory now lives
+  solely in `.dxkit/bom.json` (`vyuh-dxkit bom`), which already
+  carries richer per-package data (licenseType, licenseText,
+  sourceUrl, supplier, releaseDate). Lenient migration:
+  baselines written by older dxkit versions still load — the
+  reader silently filters retired `license` entries on the way
+  in (no file rewrite until the next `baseline create --force`).
+  Dependency vulnerability tracking is unchanged — `dep-vuln`
+  is a separate identity kind on a separate producer and still
+  blocks via the guardrail check.
+- **Sanitization machinery for baseline entries.** New pure
+  module `src/baseline/sanitize.ts` introduces a stripped
+  `SanitizedBaselineEntry` variant (`{ id, kind, sanitized: true }`)
+  carrying identity + kind only. The `sanitizeEntry` /
+  `sanitizeFile` pass collapses every rich field; cross-run
+  matching still works at full confidence via the fingerprint
+  multiset pass. Producers now emit the rich
+  `RichBaselineEntry` shape (a `BaselineEntry` excluding the
+  sanitized variant); sanitization is a write-time
+  transformation, never a producer concern. Consumers walking
+  a baseline narrow via the `isSanitized` type guard before
+  switching on `entry.kind`. Write-path wiring + visibility-
+  aware mode selection ship in a follow-up commit.
+
+### Added
+
+- **Three baseline modes with visibility-aware defaults.**
+  `committed-full` (today's behavior, rich entries), `committed-
+  sanitized` (stripped per-entry payload via the sanitization
+  pass), and `ref-based` (no committed file; guardrail check
+  recomputes the prior side from a git ref via `git worktree
+  add`). The mode is picked by a single resolver
+  (`src/baseline/modes.ts`) with precedence: CLI flag →
+  `.dxkit/policy.json:baseline.mode` → visibility-derived default
+  (public repos auto-pick `ref-based`; everything else picks
+  `committed-full`). `committed-sanitized` is never auto-picked
+  — it's the explicit opt-in for compliance-conscious private
+  repos.
+- `vyuh-dxkit baseline create [--mode <m>] [--ref <r>]` and
+  `vyuh-dxkit guardrail check [--mode <m>] [--ref <r>]` — flags
+  override `policy.json` for one-off runs.
+- `gh repo view --json visibility` probe + per-process cache
+  in `src/baseline/visibility.ts`. Every failure path returns
+  `'unknown'`; the resolver treats unknown as private to avoid
+  surprise sanitization when `gh auth` lapses.
+- Ref-based gather mechanics in `src/baseline/ref-baseline.ts` —
+  `withRefWorktree(opts, fn)` is the reusable primitive; tears
+  down the worktree on success + failure. Mirrors file-mode
+  `.dxkit/salt` into the worktree so secret-HMAC entries pair
+  across cwd + worktree.
+
+### Architectural notes
+
+- New CLAUDE.md rule 11: baseline mode resolution flows through
+  `resolveBaselineMode`. Two arch-check rules lock the contract:
+  no `gh repo view --json visibility` outside
+  `src/baseline/visibility.ts`; no `git worktree add` / `remove`
+  outside `src/baseline/ref-baseline.ts`.
+- `resolvePolicy` lifted from `check.ts` to `policy.ts` so
+  `createBaseline` and `runGuardrailCheck` share one canonical
+  loader.
+
+### Discovery surfaces
+
+- **PR-comment markdown** now shows the resolved baseline mode in
+  the sticky footer (`_Mode_: \`ref-based\` (ref: \`origin/main\`)`).
+  Reviewers see WHY a guardrail run picked a given posture.
+- **JSON renderer** carries `baseline.mode = { value, source,
+  explanation, ref? }` so agents + dashboards can read the audit
+  trail without re-deriving it.
+- **`vyuh-dxkit doctor`** has two new operational checks:
+  - "baseline mode: ref-based" / "baseline captured (mode: ...)" —
+    the existing baseline-captured check now understands ref-based
+    mode (where no on-disk file is expected) so the doctor stops
+    reporting a false-negative on public repos.
+  - "baseline mode aligned with repo visibility" — warns when an
+    explicit `committed-full` pin is in use on a public repo (the
+    posture leaks file paths + package names; the auto-picker
+    would have chosen ref-based).
+- **`dxkit-onboard` skill** — step 5 now ASKs about disclosure
+  posture before running `baseline create`, walks customers through
+  the three modes, and offers a one-shot `.dxkit/policy.json` snippet
+  for pinning the choice repo-wide.
+- **`dxkit-action` skill** — new section explains how to act on a
+  blocked finding when the baseline is sanitized / ref-based
+  (locator stripped at write time; re-run the analyzer for full
+  context or allowlist by fingerprint).
+- **README + getting-started.md** — call out the public-repo
+  posture explicitly so customers don't accidentally commit a
+  rich baseline to an open-source repo.
+
+### Architectural notes
+
+- Added `stale-allow` as a new `IdentityKind` (Rule 9 + Rule 10
+  compliant: identityFor case + producer + fixture row +
+  removed from `DEFERRED_KINDS` once the gather pass landed).
+- The hint formatter (block-time guidance for blocked findings)
+  consumes the canonical `BaselineEntry` discriminated union
+  directly — no invented intermediate "BlockingFinding" shape.
+  TypeScript exhaustiveness across 6+ switches guarantees new
+  finding kinds can't ship without matching cases.
+- `dxkit-action` skill extended with the typed-category +
+  surfaces description; SAST recipe redirects from semgrep's
+  `// nosemgrep:` to dxkit's `// dxkit-allow:` (single canonical
+  suppression surface across all scanners).
+
+## [2.5.2] - 2026-05-22
+
+The "scaffold UX + lifecycle skills + setup automation" release. Closes
+every defect surfaced during the 2026-05-21 guided Codespaces UX
+walkthrough (D145–D156) plus a vestigial-cleanup pass and adds three
+new CLI subcommands + three new lifecycle skills.
+
+Companion release: **`@vyuhlabs/create-dxkit@0.2.0`** ships alongside
+this version, picking up the create-dxkit shim improvements (quieter
+ERESOLVE handling, `--no-audit`, `.npmrc legacy-peer-deps` persistence).
+Tag: `create-dxkit@v0.2.0`. Run `npm init @vyuhlabs/dxkit` to get
+the new combined experience.
+
+Validated end-to-end with two cross-stack walkthroughs on 2026-05-22:
+`vyuhlabs-platform` (python + typescript) and `dpl-studio` (csharp).
+Both stacks: defect closures verified, per-pack devcontainer adapts
+correctly, doctor's new tier-3 surfaces operational gaps with
+actionable fix commands.
+
+### Added
+
+- Three new lifecycle skills under `.claude/skills/`, completing
+  the orthogonal customer-journey trio:
+  - **`dxkit-fix`** — reactive repair. Consumes
+    `vyuh-dxkit doctor --json` output and walks the customer
+    through each fixable check with per-step confirmation.
+  - **`dxkit-update`** — existing-install upgrade orchestrator.
+    Consumes `vyuh-dxkit upgrade --plan --json` and drives a
+    conversational upgrade with version-delta analysis, breaking-
+    change warnings, and per-step confirmation. Hands off to
+    `dxkit-fix` on post-upgrade doctor failures.
+  - **`dxkit-onboard`** — fresh-install orchestrator. Walks the
+    full first-time customer journey end-to-end (install → doctor
+    → fix gaps → baseline → hooks → branch protection → Codespaces
+    prebuild → final verify). Delegates to focused skills for
+    sub-decisions.
+- Three new CLI subcommands:
+  - **`vyuh-dxkit upgrade [--plan [--json] | --yes | --target=X.Y.Z |
+    --dry-run]`** — combined binary + scaffold refresh. `--plan`
+    mode emits structured `upgrade-plan.v1` JSON consumed by the
+    `dxkit-update` skill. Execution mode runs `npm install`
+    + `vyuh-dxkit update` + `vyuh-dxkit doctor` in sequence with
+    a devcontainer-rebuild reminder if applicable.
+  - **`vyuh-dxkit setup-branch-protection [--branch X]
+    [--require-reviews N] [--force]`** — wraps `gh api` to mark
+    `dxkit-guardrails` as a required status check on the default
+    branch. Idempotent merge with existing required-checks list.
+  - **`vyuh-dxkit setup-prebuild [--branch X] [--regions=R1,R2]
+    [--force]`** — wraps `gh api` to configure Codespaces
+    prebuilds. Fresh Codespaces start in ~30s instead of running
+    the full devcontainer build (~7 min after per-stack feature).
+- Doctor third tier — **Operational health**. Six runtime checks
+  (`git hooks active`, `baseline captured`, `vyuh-dxkit on PATH`,
+  `scanner toolchain healthy`, `.npmrc legacy-peer-deps
+  persistence`, `CI guardrails workflow`) each carrying structured
+  fix metadata (hint + command + skill). Plus a new `--json`
+  output mode emitting the `doctor.v1` schema for `dxkit-fix`
+  consumption.
+- `manifest.installFlags` — persists the customer's `init`
+  flag choices in `.vyuh-dxkit.json` so `vyuh-dxkit update`
+  knows exactly which surfaces to refresh. Self-migrates legacy
+  pre-2.5.2 manifests by stamping detected flags back on first
+  update run.
+- Per-pack `LanguageSupport.devcontainerExtensions?` field.
+  Each language pack contributes its VSCode editor extensions;
+  the installer unions across active packs only. Pure-Python
+  Codespaces no longer install Go / Rust / C# / Java / Kotlin /
+  Ruby editor extensions on every container start.
+- Architecture rule (`scripts/check-architecture.sh`) that catches
+  dead `IF_*` template conditions in `constants.ts`. The
+  type-correct compute-without-consumer class of dead code sat
+  for days before the rule landed; rule now blocks new
+  occurrences at pre-commit time.
+- Three new doc pages: `docs/commands/upgrade.md`,
+  `docs/commands/setup-branch-protection.md`,
+  `docs/commands/setup-prebuild.md`.
+
+### Changed
+
+- **`vyuh-dxkit update` actually refreshes everything now.**
+  Pre-this-release, update only re-ran the template generator and
+  silently passed `withDxkitAgents=false`. Customers on 2.5.1 had
+  no path to receive new dxkit-* skills, per-stack devcontainer
+  extensions, doctor pivot, or any other scaffold-side change.
+  `update` now detects which install surfaces the customer
+  originally landed (via `manifest.installFlags` or workspace
+  detection) and re-runs every relevant installer.
+- `vyuh-dxkit doctor` — three-tier framing (Reports + Agent DX +
+  Operational health, was two-tier). Tier 1 + 2 labels +
+  exit-code behavior preserved verbatim; tier 3 is additive.
+- All six existing dxkit-* skill prose files standardized on
+  `npx vyuh-dxkit X` invocations (was a mix of bare + npx forms).
+  Robust to customers whose shell PATH doesn't have dxkit
+  globally installed.
+- Python devcontainer feature switched from `installTools: true`
+  → `false`. The upstream feature's bundled installTools list
+  added ~3 min to every devcontainer build with no dxkit
+  consumer. Saves ~3 min per Codespaces rebuild on python-stack
+  projects.
+- `osv-scanner` install switched from `go install` to GitHub
+  releases binary fetch. Pre-this-release, customers on any
+  non-Go stack silently lost `osv-scanner` (the canonical
+  Tier-2 dep-vuln scanner) because the install command failed
+  without a Go toolchain.
+- `post-create.sh` always runs a global `npm install -g
+  @vyuhlabs/dxkit` in addition to whatever project-local install
+  happened. Without this, `vyuh-dxkit` wasn't on the customer's
+  shell PATH in Codespaces.
+- Init's closing summary surfaces `Next: run vyuh-dxkit
+  baseline create` as a prominent info-level call-to-action
+  immediately after `Done!`, instead of burying it in a dim
+  three-line footer.
+- `create-dxkit` shim: stderr from the first `npm install`
+  attempt is now captured (not streamed) so a peer-dep
+  `ERESOLVE` doesn't print a multi-line error wall before the
+  silent `--legacy-peer-deps` fallback succeeds. `--no-audit`
+  passed to both install attempts so the host project's
+  pre-existing vulnerability count doesn't surface mid-init.
+  Fallback choice persisted to `.npmrc` so the customer's next
+  `npm install <pkg>` doesn't re-hit the same ERESOLVE wall.
+- CI: `actions/cache@v4` on the scanner toolchain
+  (`~/.local/{pipx,bin,share/{detekt,pmd}}`). Saves ~2 min per
+  CI run.
+- Publish workflows (`publish.yml` + `publish-create-dxkit.yml`):
+  verify-shasum poll window 18s → 180s. First-publishes of
+  scoped packages commonly need 30–90s for CDN propagation;
+  the wider window prevents the "publish succeeded but workflow
+  reports failure" mode that bit both 2.5.1 publishes.
+- README, getting-started, docs/README, commands/init.md
+  refreshed to reflect: `npm init @vyuhlabs/dxkit` as canonical
+  first install, 9 lifecycle skills (was 6), postinstall
+  auto-activation of hooks, per-stack devcontainer.
+
+### Removed
+
+- Vestigial `DetectedStack.tools.{gcloud, pulumi, infisical,
+  ghCli}` field. Computed at every detect call since the 2026-
+  05-19 generator simplification removed the `.project.yaml`
+  consumers; nothing referenced them post-cleanup. Doctor's
+  pre-pivot tier-2 `gcloud` + `infisical` availability checks
+  removed alongside (no manifest field to gate on).
+- Six dead `IF_*` template conditions in `constants.ts`:
+  `IF_POSTGRES`, `IF_REDIS`, `IF_HAS_SERVICES`, `IF_DOCKER`,
+  `IF_CLAUDE_CODE`, `IF_COVERAGE_ENABLED`. Computed but no
+  template referenced them; same 2026-05-19 cleanup left them
+  behind. Arch-check rule (above) prevents new occurrences.
+
+### Fixed
+
+- Dispatcher deadline test (`test/dispatcher-deadline.test.ts`):
+  lower-bound assertion 40ms → 25ms. Test was occasionally
+  flaking on fast CI runners where `setTimeout`'s ~1-2ms
+  granularity could fire at 38-39ms.
+
 ## [2.5.1] - 2026-05-20
 
 ### Added

package/README.md

@@ -9,7 +9,7 @@ agent DX; one baseline turns on the guardrails.** Works across major
 language stacks, greenfield or brownfield.
 
 ```bash
-npx @vyuhlabs/dxkit@latest init --full
+npm init @vyuhlabs/dxkit
 ```
 
 <p>
@@ -45,28 +45,37 @@ the grading path.
 
 ---
 
-## What `init --full` creates
+## What `npm init @vyuhlabs/dxkit` creates
 
 ```bash
-npx @vyuhlabs/dxkit@latest init --full
+npm init @vyuhlabs/dxkit
 ```
 
-`init --full` lands a coordinated set of pieces:
+This collapses install + scaffold into a single command: it installs
+`@vyuhlabs/dxkit` as a devDep and runs `vyuh-dxkit init --full --yes`.
+The full install lands a coordinated set of pieces:
 
 ```text
-.devcontainer/        Reproducible environment — pinned language
-                      toolchains, dxkit's scanner toolchain auto-
-                      installed, install scripts for AI agent CLIs
-                      (auth stays user-owned).
-.githooks/            pre-push guardrail hook (pre-commit opt-in
-                      via --with-precommit-hook).
+.devcontainer/        Reproducible environment — per-stack pinned
+                      toolchains (only the languages your project
+                      uses), dxkit's scanner toolchain auto-installed,
+                      install scripts for AI agent CLIs (auth stays
+                      user-owned).
+.githooks/            pre-push guardrail hook (pre-commit opt-in via
+                      --with-precommit-hook). Postinstall auto-
+                      activates `core.hooksPath` so teammates who
+                      clone + `npm install` get hooks wired too.
 .github/workflows/    PR-gate workflow + post-merge baseline-refresh
                       workflow (refresh runs only after the PR-gate
                       passes — see "Safety + trust" below).
-agent scaffolding     Entry-point doc, project skills, slash commands,
-                      per-language conventions, and specialized
-                      subagents for the currently supported agent
-                      (broader agent coverage in 2.6).
+AGENTS.md             Open-standard project context file read by
+                      Claude Code, Codex, Cursor, Aider, and any
+                      AGENTS.md-compliant agent.
+CLAUDE.md             Claude Code shim that points at AGENTS.md.
+.claude/skills/       Nine dxkit-* skills covering the full lifecycle:
+                      learn / init / config / hooks / reports /
+                      action / fix / update / onboard. Claude Code
+                      auto-discovers via skill frontmatter.
 .dxkit/               reports, baselines, and (optional) policy.
 .vyuh-dxkit.json      install manifest.
 ```
@@ -74,7 +83,6 @@ agent scaffolding     Entry-point doc, project skills, slash commands,
 After install:
 
 ```bash
-git config core.hooksPath .githooks   # activate the hooks
 vyuh-dxkit baseline create            # capture today's state
 git add .dxkit/baselines/main.json .githooks .github/workflows/dxkit-*.yml
 git commit -m "chore: enable dxkit guardrails"
@@ -108,9 +116,9 @@ rm .githooks/pre-commit              # disable just pre-commit (keep pre-push)
 ## 60-second demo
 
 ```text
-$ npx @vyuhlabs/dxkit@latest init --full
-✓ Created: 73 files
-✓ Git hooks: installed 2 file(s)
+$ npm init @vyuhlabs/dxkit
+✓ Created: 11 files (AGENTS.md, CLAUDE.md, .claude/skills/dxkit-*, ...)
+✓ Git hooks: installed 1 file(s)
 ✓ Devcontainer: installed 3 file(s)
 ✓ CI guardrails workflow: installed 1 file(s)
 ✓ CI baseline-refresh workflow: installed 1 file(s)
@@ -119,8 +127,8 @@ $ vyuh-dxkit baseline create
 ✓ Wrote .dxkit/baselines/main.json — 89 findings (32s)
 ```
 
-Your AI agent has access to dxkit's reports and the bundled
-subagents that init scaffolded. A typical request to the agent:
+Your AI agent has access to dxkit's reports and the nine lifecycle
+skills that init scaffolded. A typical request to the agent:
 
 ```text
 Read the latest dxkit health report. Pick one safe quality
@@ -166,27 +174,38 @@ Summary
 ## Quickstart
 
 ```bash
-# One-shot, no install
-npx @vyuhlabs/dxkit@latest init --full
+# Canonical first install — collapses install + scaffold into one step
+npm init @vyuhlabs/dxkit
 
-# Or install + use repeatedly
+# Or install dxkit globally + scaffold manually
 npm install -g @vyuhlabs/dxkit
 vyuh-dxkit init --full
 vyuh-dxkit baseline create
 vyuh-dxkit guardrail check --changed-only
+
+# Upgrade an existing install later
+vyuh-dxkit upgrade           # plan + execute combined
 ```
 
 À la carte if you only want specific pieces:
 
 ```bash
-vyuh-dxkit init --with-hooks              # just the pre-push hook (default for hooks)
+vyuh-dxkit init --with-dxkit-agents       # just the nine dxkit-* skills + AGENTS.md
+vyuh-dxkit init --with-hooks              # just the pre-push hook
 vyuh-dxkit init --with-precommit-hook     # add the pre-commit hook (opt-in; slow on large repos)
-vyuh-dxkit init --with-devcontainer       # just the devcontainer
+vyuh-dxkit init --with-devcontainer       # just the per-stack devcontainer
 vyuh-dxkit init --with-ci                 # just the PR-gate workflow
 vyuh-dxkit init --with-baseline-refresh   # just the auto-refresh
 vyuh-dxkit init --with-pr-review          # AI PR-review workflow (opt-in, needs API key)
 ```
 
+Post-install, two more CLIs polish the safety surface:
+
+```bash
+vyuh-dxkit setup-branch-protection   # mark dxkit-guardrails as required check on default branch
+vyuh-dxkit setup-prebuild            # configure Codespaces prebuild (cold-start ~7 min → ~30s)
+```
+
 ---
 
 ## Baseline mode: greenfield to 10-year-old codebases
@@ -215,6 +234,86 @@ The classifier distinguishes:
 Customize via [`.dxkit/policy.json`](docs/configuration/policy.md) —
 auto-discovered when present, compiled-in defaults otherwise.
 
+### Baseline modes — public vs private repos
+
+The baseline file is committed to git. On public repos that
+disclosure surface matters: a `committed-full` baseline tells anyone
+reading the repo which file/line each finding lives on, which
+private packages you depend on, and which advisory IDs you're
+sitting on unpatched. dxkit ships three modes:
+
+| Mode                  | On-disk content                                          | Auto-default for |
+| --------------------- | -------------------------------------------------------- | ---------------- |
+| `committed-full`      | Rich entries (file/line/rule/package/advisory)           | private repos    |
+| `committed-sanitized` | Stripped to `{ id, kind }` per finding                   | opt-in           |
+| `ref-based`           | No file — guardrail recomputes prior side from a git ref | public repos     |
+
+`vyuh-dxkit baseline create` auto-picks via
+`gh repo view --json visibility`. Pin the choice repo-wide in
+`.dxkit/policy.json`:
+
+```json
+{ "baseline": { "mode": "ref-based", "ref": "origin/main" } }
+```
+
+The cross-run matching contract (fingerprint identity) is identical
+across all three modes — sanitization only strips human-readable
+locators, it doesn't change which findings pair across runs. See
+[docs/commands/baseline.md](docs/commands/baseline.md#modes) for the
+full trade-off discussion.
+
+---
+
+## Allowlist: per-finding suppression
+
+The baseline handles codebase-wide brownfield acceptance ("today's
+mess is grandfathered; tomorrow's must be net-new improvement").
+For per-finding decisions — false positives, intentional test
+fixtures, externally-mitigated risks, deliberately deferred work —
+use the [allowlist](docs/commands/allowlist.md).
+
+Five typed categories signal **why** a finding is suppressed:
+
+| Category               | Meaning                                           | Expiry                         |
+| ---------------------- | ------------------------------------------------- | ------------------------------ |
+| `false-positive`       | Scanner is wrong about this finding               | Optional                       |
+| `test-fixture`         | Intentional pattern in fixture / test code        | Optional                       |
+| `mitigated-externally` | Real risk neutralized at runtime (WAF, env, etc.) | Optional                       |
+| `accepted-risk`        | Real risk, team accepts, signed off               | **Required** (default 90 days) |
+| `deferred`             | Real, will fix later, tracked work                | **Required**                   |
+
+Two surfaces. Inline annotation for source-anchored findings:
+
+```python
+api_key = "sk_test_xxxx"  # dxkit-allow:test-fixture reason="placeholder in unit test"
+```
+
+File-level (`.dxkit/allowlist.json`) for cross-file findings or any
+suppression that needs an expiry. New entries appear in the PR-
+comment automation so reviewers see suppressions being introduced
+and can sanity-check the rationale before approving. `audit` /
+`prune` subcommands handle stale + soon-to-expire entries.
+
+**Strict cleanup**: orphaned `dxkit-allow:` annotations become
+`stale-allow` findings on the next scan. dxkit refuses to allowlist
+those — the only remediation is to remove the annotation. This is
+the TypeScript `@ts-expect-error` pattern: tools that surface their
+own stale suppressions force cleanup, preventing the annotation
+graveyard.
+
+```bash
+# The block message from `guardrail check` prints the exact command
+# to paste for any blocked finding — file:line for inline-compatible
+# kinds, --fingerprint for everything else.
+vyuh-dxkit allowlist add src/auth/oauth.ts:42 \
+    --category=test-fixture --reason="placeholder in unit test"
+
+vyuh-dxkit allowlist audit              # find stale + soon-to-expire entries
+```
+
+See [`vyuh-dxkit allowlist`](docs/commands/allowlist.md) for the
+full surface.
+
 ---
 
 ## Git-aware identity matching
@@ -420,8 +519,9 @@ dxkit is local-first.
 - [x] Git hooks (pre-push default; pre-commit opt-in)
 - [x] GitHub Actions PR-gate + gated baseline-refresh workflows
 - [x] Devcontainer with pinned toolchains
-- [ ] First-class scaffolding for every major coding agent —
-      per-agent skills + entry-point file conventions (2.6)
+- [x] Nine dxkit-\* skills + AGENTS.md (open-standard, read by every
+      AGENTS.md-compliant agent — Claude Code, Codex, Cursor, Aider)
+- [ ] First-class plugin packaging for the Claude Code marketplace + MCP server for cross-agent reach (2.6, decision-pending)
 - [ ] Scoped + incremental scanning — fast pre-commit on monorepos
       (2.6)
 - [ ] Symbol-level coverage gaps across all 8 packs (2.6)
@@ -439,6 +539,28 @@ dxkit is local-first.
 
 ---
 
+## Reporting issues
+
+If a scanner is too noisy, a finding is missing, dxkit itself is
+broken, or the docs are unclear, the fastest path to the dxkit team
+is the built-in issue subcommand:
+
+```bash
+vyuh-dxkit issue --type=false-positive \
+    --fingerprint=<id> \
+    --about="the scanner flags my intentional X as a Y"
+
+vyuh-dxkit issue --type=bug --about="vyuh-dxkit doctor crashes on macOS arm64"
+
+vyuh-dxkit issue --type=feature-request --about="add SARIF export"
+```
+
+It opens a pre-filled [GitHub issue](https://github.com/vyuh-labs/dxkit/issues)
+in your browser with dxkit version + platform info already populated.
+Nothing is submitted until you click "Submit" — you review the
+prefill first. See [`vyuh-dxkit issue`](docs/commands/issue.md) for
+the full reference.
+
 ## Contributing
 
 dxkit aims to be the standard agentic-development layer for any
@@ -466,7 +588,7 @@ MIT. See [LICENSE](LICENSE).
 ## Try it
 
 ```bash
-npx @vyuhlabs/dxkit@latest init --full
+npm init @vyuhlabs/dxkit
 ```
 
 If dxkit helps you ship AI-assisted changes more safely, star the