@vyuhlabs/dxkit 2.7.1 → 2.9.0

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

@@ -0,0 +1,148 @@
+---
+name: dxkit-docs
+description: Generate the documentation a repo is missing — read the Documentation dimension's gaps, orient on the real code via the graph, then write a grounded README / docstrings / API + architecture docs that move the score without tripping the slop check. Use when the user says "write docs", "document this module", "improve the documentation score", "generate a README", "add docstrings", or after a health report flags Documentation.
+---
+
+# dxkit-docs
+
+This skill closes the gap `dxkit-action` doesn't: it **generates** missing
+documentation rather than fixing flagged findings. It's built around one
+hard constraint — dxkit's own quality scan flags AI-slop prose, so
+documentation that reads like generated filler *lowers* the Quality score
+while raising Documentation. The whole point of this skill is docs that
+are **grounded in the real code** and **survive the slop check**.
+
+## The docs loop
+
+```
+[1] Read the gap   → health Documentation deductions + top actions
+[2] Orient         → graph: what are the real entry points, modules, public API
+[3] Generate       → write the missing artifact, grounded in actual symbols/paths
+[4] De-slop        → write like a human; re-run quality so it doesn't trip slop
+[5] Verify         → re-run health; Documentation up, slop not down
+```
+
+Don't skip [2] or [4]. [2] is what keeps the docs true; [4] is what keeps
+them from costing you on another dimension.
+
+## [1] Read the gap — what's actually missing
+
+The Documentation dimension scores a fixed checklist. Read its deductions
+and ranked actions instead of guessing:
+
+```bash
+npx vyuh-dxkit health --detailed --json | jq '.dimensions.documentation'
+```
+
+The `deductions` array names each missing/substandard artifact; `topActions`
+ranks them by score uplift. The scored artifacts are:
+
+| Artifact | What moves the score |
+|---|---|
+| **README** | Present, and substantial (not a 5-line stub) |
+| **Doc-comment density** | Share of source files carrying docstrings / JSDoc / Rustdoc |
+| **API docs** | `docs/api/`, OpenAPI/Swagger spec |
+| **Architecture docs** | `ARCHITECTURE.md` or `docs/architecture/` |
+| **CONTRIBUTING** | `CONTRIBUTING.md` |
+| **CHANGELOG** | `CHANGELOG.md` |
+
+Work the `topActions` order — the README and doc-comment density weigh
+heaviest, CHANGELOG lightest.
+
+## [2] Orient — document the code that's actually there
+
+Docs that describe code which doesn't exist are worse than no docs. Before
+writing a word, learn the real shape from the graph (cheap, structural):
+
+```bash
+npx vyuh-dxkit explore entry-points      # what this repo does — the surfaces to lead a README with
+npx vyuh-dxkit explore communities       # the natural modules — the spine of an ARCHITECTURE.md
+npx vyuh-dxkit explore api-surface       # exported symbols — what API docs must cover
+npx vyuh-dxkit explore hot-files         # the foundational files — docstring these first
+npx vyuh-dxkit context <symbol>          # one area's structure before you docstring it
+```
+
+Then **read the actual code** you're about to document — the graph points
+you at it; it doesn't replace reading it. Also read any existing docs
+first and match their voice, structure, and terminology.
+
+## [3] Generate — grounded, specific, real
+
+Per artifact:
+
+- **README** — lead with what the repo *does* (from `entry-points`), then
+  real install + usage steps you've verified against the actual scripts /
+  entry points, not a generic template. Reference real commands, real file
+  paths, real module names.
+- **Doc-comments** — docstring the highest-value undocumented files first
+  (public API from `api-surface`, foundational files from `hot-files`).
+  Describe *why* and the contract (params, returns, invariants, gotchas) —
+  not a restatement of the signature.
+- **Architecture docs** — structure an `ARCHITECTURE.md` around the real
+  `communities` / `hot-files`: what each module owns, how they depend on
+  each other (the graph already knows the edges).
+- **API docs** — generate from the actual exported surface; prefer the
+  ecosystem's doc generator (`typedoc`, `sphinx`, `godoc`, `yard`, …) over
+  hand-rolled prose when one fits.
+- **CONTRIBUTING / CHANGELOG** — real build/test commands from the repo;
+  real recent changes from `git log` for a CHANGELOG seed.
+
+## [4] De-slop — the rule that makes this skill different
+
+dxkit's slop check flags AI-generated boilerplate. **Generated docs are
+the single biggest source of slop**, so this step is mandatory, not
+optional. Write to pass it:
+
+- **No filler openers.** Not "This module provides functionality for
+  handling…" — say what it does and why it exists.
+- **Be concrete.** Name real symbols, real paths, real commands. Specifics
+  don't read as slop; generic scaffolding does.
+- **No hedging padding** ("it's worth noting that", "in order to",
+  "leverage", "robust", "seamless", "comprehensive solution").
+- **Match the repo's register** — terse repos get terse docs.
+
+Then prove it:
+
+```bash
+npx vyuh-dxkit quality            # slop score must not drop
+```
+
+If a genuine false positive trips the slop check on prose you stand
+behind, annotate the line (`// slop-ok: <reason>`, or `# slop-ok` for
+hash-comment languages) — but fix first, suppress second.
+
+## [5] Verify — Documentation up, nothing else down
+
+```bash
+npx vyuh-dxkit health --detailed   # Documentation score moved in the right direction
+npx vyuh-dxkit quality             # slop / quality did NOT regress
+```
+
+The work is done when the Documentation deduction you targeted is gone
+**and** the Quality score held. A docs change that raises Documentation by
+moving slop into Quality is a net loss — re-do it more concretely.
+
+Then run the guardrail before pushing, same as any change:
+
+```bash
+npx vyuh-dxkit guardrail check
+```
+
+## Scope — what NOT to document
+
+- Don't docstring self-evident one-liners; density credit comes from
+  documenting the files that need it (public API, foundational modules),
+  not papering every getter.
+- Don't document auto-generated or vendored code.
+- Don't invent behavior to fill a section — if you're unsure what
+  something does, read it or ask, don't guess in prose.
+
+## Hand-offs
+
+- Running / interpreting the health report → `dxkit-reports`.
+- Documentation surfaced as one finding inside a broader fix pass →
+  `dxkit-action`.
+- Documenting a feature you're building → `dxkit-feature` (its build step
+  should leave the new surface documented).
+- Slop findings outside docs (AI-generated code prose, CHANGELOG slop) →
+  `dxkit-action`'s slop recipe.

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

@@ -0,0 +1,189 @@
+---
+name: dxkit-feature
+description: Develop a new feature with the code graph as your map — orient cheaply by querying structure instead of reading whole files, implement following the patterns already in the repo, then verify the change did not regress security, tests, or quality before you push. Use when the user says "add a feature", "implement X", "build the Y flow", "where should this live", or otherwise starts net-new development in a dxkit-scaffolded repo.
+---
+
+# dxkit-feature
+
+This skill drives forward development — building something new — the way
+`dxkit-action` drives the reverse (fixing what's flagged). Its two jobs:
+
+1. **Orient by graph, not by grep.** Use the code graph to find where the
+   feature plugs in, what patterns already exist, and what a change will
+   touch — at a fraction of the tokens that repeated whole-file reads cost.
+2. **Close the loop a plain coding agent skips.** After the edit, run the
+   dxkit analyzers on the change and the guardrail check, so the new feature
+   doesn't quietly ship a vuln, a test gap, or a quality regression.
+
+## The feature loop
+
+```
+[1] Clarify        → what's the feature + what does "done" mean
+[2] Orient         → query the graph: where it lives, patterns, blast radius
+[3] Plan           → ordered edits, reusing the patterns found in [2]
+[4] Build          → read only the files the graph named, then implement
+[5] Verify         → run the analyzers on the change; confirm nothing regressed
+[6] Decide baseline→ commit, or re-baseline if the change is deliberately accepted
+```
+
+Don't skip [2] or [5]. [2] is where the token saving lives; [5] is the whole
+reason to use dxkit for forward work instead of a generic agent.
+
+## [2] Orient — query structure before you read files
+
+This is the step that differentiates this skill. **Orientation (discovery)
+is where direct agents burn the most tokens** — grep, read a 2,000-line
+file, grep again, read another. The graph answers the same questions from a
+budget-bounded slice instead.
+
+Run `health` once first if there's no graph yet (it writes
+`.dxkit/reports/graph.json` as a side effect), then query:
+
+```bash
+# "Where is this feature area implemented?" — clusters of matching symbols
+npx vyuh-dxkit explore feature auth
+
+# Token-budgeted structural slice for an area you're about to extend:
+# anchor symbol, its callers/callees grouped by module, blast radius
+npx vyuh-dxkit context "checkout session"
+
+# Zoom into one symbol's exact neighborhood (curated AST chunk, not the
+# whole file) — read 500 focused lines instead of ingesting 15k
+npx vyuh-dxkit context src/payments/checkout.ts:142
+
+# One file's structural neighborhood — symbols, callers, callees, imports
+npx vyuh-dxkit explore file src/payments/checkout.ts
+
+# The repo's public API / dead surface — useful when adding an entry point
+npx vyuh-dxkit explore api-surface
+```
+
+Use the answers to decide three things before you write anything:
+
+- **Where the feature plugs in** — which module/cluster owns this area, so
+  the new code lands next to its neighbors rather than in a new island.
+- **Which pattern to copy** — read the anchor symbol the graph points at;
+  it's the highest-in-degree example of "how this repo already does X."
+  Match its shape (error handling, validation, naming) so the feature reads
+  like the surrounding code.
+- **The blast radius** — how many caller files a change to the touched
+  symbols reaches. That's your re-test list for step [5].
+
+### Honest scope of the graph win (don't oversell it)
+
+The reduction is a **navigation-phase win, not an end-to-end multiplier.**
+The graph cuts the cost of *finding and orienting*; the *edit* phase still
+reads the real files you change, and *verification* still runs the real
+analyzers. The win is largest in big, unfamiliar codebases (orientation-by-
+grep is expensive there) and near-zero in a small repo whose relevant files
+already fit in context. Lead with the graph for discovery; then read the
+actual code you're about to modify — `context` is a map, not a substitute
+for the territory.
+
+### Three hard rules for graph context (same as dxkit-action)
+
+1. **It's a hint, never ground truth.** Confirm the symbol and call sites by
+   opening the file before you act on them — the graph stores declaration
+   lines, not end lines, and same-name symbols can conflate.
+2. **A blank or `n/a` blast radius is NOT "safe to change".** Languages whose
+   call graph dxkit can't fully resolve (C# is the known case) report no
+   callers even for heavily-used files. Treat empty as *unknown* — fall back
+   to grep/read to find callers before a risky edit. Never read "no callers"
+   as "free to rewrite."
+3. **Fall open — the graph is an accelerator, never a dependency.** If
+   graphify hasn't built a graph yet, `context` / `explore` print
+   `No graph.json … Run vyuh-dxkit health or pass --refresh` and exit
+   non-zero (they never crash or hang). Two responses, in order:
+   - Build it once: `npx vyuh-dxkit health` writes `graph.json` as a side
+     effect, or add `--refresh` to any explore/context call. Do this if the
+     repo is large enough that the orientation saving is worth one scan.
+   - Or just orient the normal way — grep + read — and carry on. You lose
+     the token saving, not the ability to build the feature.
+
+### If graphify isn't installed at all
+
+The graph is built by **graphify** (a registry tool). If it isn't installed,
+`health` won't produce a `graph.json`, so step [2]'s graph queries are
+unavailable — fall back to grep + read as above, or install it to unlock the
+saving:
+
+```bash
+npx vyuh-dxkit tools install   # installs graphify + the other scanners
+```
+
+**Steps [5] and [6] do not need graphify.** The `vulnerabilities`,
+`test-gaps`, `quality`, and `guardrail check` commands run fully without a
+graph — only the `--graph-context` *enrichment* is suppressed (drop the flag
+and the reports are still complete). So verification never depends on the
+graph being present; only the orientation *speed-up* does.
+
+## [3] Plan
+
+Write an ordered list of edits. For each, name the file and the existing
+pattern it mirrors (from step [2]). Prefer extending an existing module over
+creating a new one unless the graph showed no natural home. Call out the
+caller files in the blast radius that will need updating or re-testing.
+
+## [4] Build
+
+Read only the files the orientation step named — that's the point of doing
+[2] first. Implement following the matched pattern. Keep the change tight:
+comment density, naming, and idioms should match the surrounding code, not a
+generic template.
+
+## [5] Verify — never skip
+
+A new feature can introduce exactly the things dxkit scans for: a SAST
+finding, a vulnerable dependency you just added, an untested new surface, a
+quality/slop regression. Run the analyzers on the changed area, with graph
+context attached so you see each finding's blast radius:
+
+```bash
+npx vyuh-dxkit vulnerabilities --detailed --graph-context   # new code + new deps
+npx vyuh-dxkit test-gaps --graph-context                    # is the new surface tested?
+npx vyuh-dxkit quality --graph-context                      # slop / duplication / complexity
+```
+
+Then gate the change the same way CI will:
+
+```bash
+npx vyuh-dxkit guardrail check
+```
+
+Exit 0 = the feature added no net-new regressions. Exit 1 = something new
+appeared — **a finding you introduced.** Address it before pushing:
+
+- A real finding in your new code → fix it now (hand off to `dxkit-action`
+  for the fix recipes — secret rotation, dep upgrade, writing the missing
+  test, etc.).
+- A genuine false positive / intentional pattern → allowlist with a typed
+  category + reason (see `dxkit-action`'s allowlisting section). Fix first;
+  allowlist second.
+
+The feature isn't done when it works — it's done when it works **and** the
+guardrail is green.
+
+## [6] Baseline decision
+
+| Scenario | Action |
+|---|---|
+| Feature is clean; guardrail green | Just commit the code. Baseline + allowlist unchanged. |
+| You fixed an introduced finding | Commit the code + fix together. Baseline unchanged. |
+| Introduced finding is a true false positive / intentional | `vyuh-dxkit allowlist add` with `category=false-positive` or `test-fixture`; commit the annotation. |
+| Feature deliberately accepts a known trade-off (documented) | `vyuh-dxkit allowlist add` with `category=accepted-risk` + `--expires`; never re-baseline silently. |
+
+Prefer the allowlist over re-baselining for per-finding calls — it carries a
+typed reason a future maintainer can read. Reserve "accept as baseline" for
+the deliberate codebase-wide line-in-the-sand, not for hiding a finding your
+own feature introduced.
+
+## Hand-offs
+
+- A finding the guardrail blocked needs fixing → `dxkit-action` (the fix-loop
+  recipes for secrets, dep-vulns, SAST, test gaps).
+- Re-running reports between iterations → `dxkit-reports`.
+- Ignore-file / config edits as part of the feature → `dxkit-config`.
+- Hook problems on the verify push → `dxkit-hooks`.
+- Deeper structural exploration than `context` gives (entry-points,
+  communities, hot-files) → run `npx vyuh-dxkit explore <subcommand>`
+  directly; see the `explore` command docs.

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

@@ -0,0 +1,99 @@
+---
+name: dxkit-ingest
+description: Bring an external interprocedural-SAST engine's findings (Snyk Code, CodeQL, or any SARIF) into dxkit so they're fingerprinted, baselined, guardrailed, graph-linked, and fixable. Use when the user says "ingest Snyk", "pull our Snyk Code findings", "import a SARIF file", "run CodeQL and bring it in", or asks why dxkit's SAST finds less than Snyk/CodeQL.
+---
+
+# dxkit-ingest
+
+dxkit's bundled SAST (community semgrep) is **intraprocedural** — it cannot follow tainted data across function boundaries. The findings that dominate a Snyk Code or CodeQL report (path traversal, information exposure, SSRF, injection) are **interprocedural** and live outside that engine. This skill brings those findings INTO dxkit so they become first-class: fingerprinted, deduped against native findings, written to the baseline, enforced by the guardrail, linked to the code graph, and fixable through `dxkit-action`.
+
+dxkit is not re-detecting — it's orchestrating. The detection engine stays whatever the customer can run; dxkit owns the governance + agentic-fix loop on top of it.
+
+## Pick the engine (license-aware)
+
+Run the resolver's logic before ingesting:
+
+| Situation | Engine | Why |
+|---|---|---|
+| Customer already runs **Snyk** (any tier, incl. free) | **Snyk Code via REST** | Reads stored findings — consumes **no** Snyk test quota. Their own license. |
+| **Open-source** repo | **CodeQL on-demand** | CodeQL's CLI is licensed for open source. |
+| **Private** repo with **GitHub Advanced Security** | **CodeQL on-demand** | GHAS covers private-repo CodeQL. Confirm consent first. |
+| Private repo, no GHAS, no Snyk | stay on community semgrep | No licensed interprocedural engine available. Don't run CodeQL on private code without GHAS. |
+
+**Never run CodeQL against a non-public repo without confirming the user has GitHub Advanced Security.** dxkit prompts for this; honor it.
+
+## Path A — ingest Snyk Code
+
+```bash
+# Token: a Snyk API token from Snyk → Account settings → API token.
+# dxkit reads it from the ENVIRONMENT — it does NOT auto-load a .env file.
+export SNYK_TOKEN=...        # in CI, add this once as a repo/org Actions secret
+# org/project resolve from the flag, then .vyuh-dxkit.json, then the
+# environment (SNYK_ORG_ID / SNYK_PROJECT_ID) — so an exported shell needs
+# no flags. The project id is the project page URL in the Snyk UI.
+npx vyuh-dxkit ingest --from-snyk --org <org-id> --project <project-id>
+```
+
+`--from-snyk` works on **every Snyk plan**, two ways:
+
+- **REST API (quota-free)** — reads stored findings without consuming the
+  org's Snyk Code test quota. But REST API access is a **Snyk Enterprise**
+  entitlement; on Free/Team plans the read returns 403.
+- **CLI fallback (free/team)** — on that 403 dxkit automatically falls back to
+  `snyk code test` (the Snyk Code *product* entitlement that free includes),
+  which writes SARIF dxkit ingests. This **does** cost one Snyk Code test from
+  the quota per run, and only needs the org (no project id). Pass `--snyk-cli`
+  to force this path and skip the REST attempt. dxkit installs the Snyk CLI on
+  demand if it's missing.
+
+So on a free-tier customer, `--from-snyk` "just works" — it tries REST, hits
+403, and runs the CLI test. Either way it writes `.dxkit/external/snyk-code.json`.
+**Commit it** — every developer and CI run then reads the findings WITHOUT a
+token; only whoever runs `ingest` (ideally one CI refresh job) needs it.
+
+If `SNYK_TOKEN` is unset, dxkit says so explicitly — `export` it (or set the CI
+secret); it will not read a `.env` file for you.
+
+## Path B — ingest a SARIF file (any engine)
+
+For CodeQL, a Snyk SARIF export, Semgrep Pro, Bearer, or anything that emits SARIF 2.1.0:
+
+```bash
+npx vyuh-dxkit ingest --sarif results.sarif      # engine auto-detected from the SARIF
+npx vyuh-dxkit ingest --sarif results.sarif --engine codeql   # or force the label
+```
+
+### Producing the SARIF with CodeQL (OSS / GHAS only)
+
+CodeQL is heavy (~database build + analysis; tens of minutes). Run it on demand / in CI, never on the pre-push hook.
+
+```bash
+codeql database create db --language=javascript-typescript --source-root=.
+codeql database analyze db \
+  codeql/javascript-queries:codeql-suites/javascript-security-extended.qls \
+  --format=sarifv2.1.0 --output=codeql.sarif
+npx vyuh-dxkit ingest --sarif codeql.sarif
+```
+
+Compiled languages (Java, C#, Kotlin, Go) need a working build for CodeQL extraction; JS/TS, Python, Ruby do not.
+
+## After ingesting — the loop
+
+```
+[1] Ingest        → .dxkit/external/<engine>.json (commit it)
+[2] See them      → npx vyuh-dxkit vulnerabilities --graph-context
+[3] Fix them      → hand off to dxkit-action (graph-linked: blast radius + callers)
+[4] Lock the line → baseline picks them up; guardrail blocks net-new regressions
+```
+
+Ingested findings flow through the same aggregate as native findings, so they appear in the vulnerability report (with the engine as the `tool`), get a stable fingerprint, dedupe against any overlapping semgrep finding, and — with `--graph-context` — carry the enclosing symbol + blast radius the agent needs to fix safely. That graph enrichment is the part the source engine's own autofix doesn't have.
+
+## Keeping it fresh (CI)
+
+Add a scheduled refresh (mirrors `dxkit-baseline-refresh`): a CI job with the `SNYK_TOKEN` secret runs `ingest --from-snyk` and commits the updated snapshot. The bundled `--with-deep-sast-refresh` workflow (`workflow_dispatch`) does exactly this; its `method` input picks `api` (Enterprise, quota-free) or `cli` (free/team, one test per run). The ingested findings are a point-in-time snapshot of the engine's last scan — re-ingest after the engine re-scans.
+
+## Hand-offs
+
+- To fix the ingested findings → `dxkit-action` (it reads them like any code finding).
+- For token / secret setup questions → `dxkit-config`.
+- For the broader read→act→verify loop → `dxkit-reports` then `dxkit-action`.

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

@@ -94,6 +94,16 @@ If any step fails, **stop**. Don't continue with downstream steps. Surface:
 - Which step failed + its stderr
 - Suggested recovery: "Run `npx vyuh-dxkit doctor` to see current state, or invoke the `dxkit-fix` skill to walk through repair."
 
+**Peer-dep ERESOLVE on the binary install.** The most common failure on a
+brownfield Node repo: `npm install @vyuhlabs/dxkit@<version>` aborts with
+`npm error code ERESOLVE` from a conflict in the project's *own* existing
+dependency tree (not dxkit's). It's a pre-existing conflict the upgrade
+merely surfaces. Recovery: retry the same command with `--legacy-peer-deps`
+(npm's own error message also suggests this), then persist the choice so
+future installs don't re-hit it: `echo "legacy-peer-deps=true" >> .npmrc`.
+After it succeeds, continue the loop. (`doctor` flags a missing `.npmrc`
+persistence as its own operational check.)
+
 ### 6. Verify with doctor
 
 If all steps succeeded, run `npx vyuh-dxkit doctor` and report. If doctor surfaces operational issues post-upgrade (e.g. `summary.fixable[]` not empty), **hand off to dxkit-fix** — say "Upgrade complete, but doctor surfaced N gaps. Walking through dxkit-fix to close them."

package/templates/.github/workflows/dxkit-deep-sast-refresh.yml

@@ -0,0 +1,104 @@
+name: dxkit deep-SAST refresh
+
+# Periodically re-ingest interprocedural SAST findings (Snyk Code) into
+# `.dxkit/external/` and commit the snapshot. The committed snapshot is
+# what the pre-push hook and the PR guardrail enforce against, so this
+# job is the ONE place the external engine's token is needed — every
+# developer and CI run reads the snapshot without it.
+#
+# Setup (one-time, by an admin):
+#   1. Add a repository (or organization) secret `SNYK_TOKEN`
+#      (Settings → Secrets and variables → Actions). The token is never
+#      committed — it lives only here.
+#   2. Set the org/project in `.vyuh-dxkit.json`:
+#        { "deepSast": { "snyk": { "orgId": "…", "projectId": "…" } } }
+#
+# Two read methods (pick via the `method` input when running on demand):
+#   - api (default): read stored findings over the Snyk REST API. Does NOT
+#     consume the org's Snyk Code test quota — but REST API access is an
+#     Enterprise-tier entitlement. On other plans the read 403s and dxkit
+#     auto-falls-back to the CLI method below.
+#   - cli: run `snyk code test` on the checkout (Snyk Code *product*
+#     entitlement, which free/team plans include). Costs one Snyk Code
+#     test from the quota per run. Needs only the org (no project id).
+#
+# The auto-commit carries `[skip ci]` so it doesn't re-trigger CI.
+#
+# This runs ON DEMAND only — trigger it from the Actions tab (Run
+# workflow). To also refresh on a schedule, uncomment the `schedule:`
+# block below; scheduled runs use the default method (`api`, which
+# auto-falls-back to the CLI on non-Enterprise plans).
+
+on:
+  workflow_dispatch:
+    inputs:
+      method:
+        description: 'Read method: api (quota-free, Enterprise) or cli (one test/run, free-tier)'
+        type: choice
+        default: api
+        options:
+          - api
+          - cli
+  # schedule:
+  #   - cron: '0 6 * * 1' # weekly, Monday 06:00 UTC
+
+permissions:
+  contents: write
+
+jobs:
+  refresh:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+
+      - name: Install dxkit
+        run: |
+          if [ -f package-lock.json ]; then
+            npm ci
+          elif [ -f package.json ]; then
+            npm install
+          else
+            npm install -g @vyuhlabs/dxkit
+          fi
+
+      - name: Ingest Snyk Code findings
+        env:
+          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
+          METHOD: ${{ github.event.inputs.method || 'api' }}
+        run: |
+          if [ -z "${SNYK_TOKEN}" ]; then
+            echo "SNYK_TOKEN secret is not set — skipping deep-SAST refresh."
+            echo "Add it under Settings → Secrets and variables → Actions to enable."
+            exit 0
+          fi
+          if [ -x ./node_modules/.bin/vyuh-dxkit ]; then
+            DXKIT=./node_modules/.bin/vyuh-dxkit
+          else
+            DXKIT=vyuh-dxkit
+          fi
+          # org/project come from .vyuh-dxkit.json:deepSast.snyk. The api
+          # method auto-falls-back to the CLI on plans without REST access;
+          # the cli method forces `snyk code test` (one test from quota).
+          if [ "${METHOD}" = "cli" ]; then
+            "${DXKIT}" ingest --from-snyk --snyk-cli
+          else
+            "${DXKIT}" ingest --from-snyk
+          fi
+
+      - name: Commit and push refreshed snapshot
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          if git diff --quiet -- .dxkit/external/; then
+            echo "Ingested snapshot unchanged — nothing to commit."
+            exit 0
+          fi
+          git add .dxkit/external/
+          git commit -m "chore(deep-sast): refresh ingested findings [skip ci]"
+          git push