feat(miner): audit DEPLOYMENT.md env vars, paths, and CLI subcommands against source

[e11734937-beep]

What

Mirrors the self-host docs-accuracy audit (apps/gittensory-ui/src/lib/selfhost-docs-audit.ts) for the miner package. A new packages/gittensory-miner/lib/deployment-docs-audit.js module parses packages/gittensory-miner/DEPLOYMENT.md and cross-checks every claim it makes against the live source tree:

• Env vars — every GITTENSORY_MINER_* / MINER_* name the doc references must still be read somewhere under packages/gittensory-miner/**.
• File paths — every repo-relative markdown link (Dockerfile, compose files, k8s/, systemd/…, docs) must still resolve on disk; external issue links are ignored.
• CLI subcommands — every documented gittensory-miner <subcommand> must still be registered in the CLI dispatch table (parsed from the bin entry), and the @jsonbored/gittensory-miner package spelling is not mistaken for a subcommand.

On any drift the audit fails with a message naming the exact stale claim (var / path / subcommand) rather than a generic failure.

Wiring

Runs as a vitest drift guard, test/unit/miner-deployment-docs-audit.test.ts, which is part of npm run test:ci (via test:coverage) — the same pattern as the existing self-host audit checklist test.

Tests

Full branch coverage on the new module: success and failure fixtures for each claim type, a renamed-env-var regression, an invariant that the audit never silently passes on drift, and a green pass against DEPLOYMENT.md's current, accurate state.

Closes #5180

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.45%. Comparing base (0d78f24) to head (b523704).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5414   +/-   ##
=======================================
  Coverage   94.45%   94.45%           
=======================================
  Files         552      553    +1     
  Lines       44310    44350   +40     
  Branches    14659    14659           
=======================================
+ Hits        41851    41891   +40     
  Misses       1784     1784           
  Partials      675      675           

Flag	Coverage Δ
shard-1	43.86% <0.00%> (-0.31%)	⬇️
shard-2	34.12% <0.00%> (-0.51%)	⬇️
shard-3	32.08% <0.00%> (+0.56%)	⬆️
shard-4	31.43% <100.00%> (-0.08%)	⬇️
shard-5	32.91% <0.00%> (-0.44%)	⬇️
shard-6	43.87% <0.00%> (+0.53%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...ages/gittensory-miner/lib/deployment-docs-audit.js	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-12 17:33:30 UTC}

4 files · 2 AI reviewers · no blockers · readiness 100/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This adds a docs-drift audit for packages/gittensory-miner/DEPLOYMENT.md, mirroring the existing self-host audit pattern: it parses env vars, file paths, and CLI subcommands claimed by the doc and cross-checks them against the live source tree via injected predicates, wired into vitest as part of test:ci. The implementation is pure/testable (predicates injected rather than doing I/O directly), the test file both unit-tests each extractor and runs a live pass against the actual DEPLOYMENT.md and bin/lib files, and the `build` script is updated to include the new file in `node --check`. This closes #5180 and follows the established self-host-docs-audit precedent closely.

Nits — 5 non-blocking

• deployment-docs-audit.js:65 auditDeploymentDocs nests three sequential for-loops each with an if — consider extracting a small `checkClaims(claims, predicate, formatFailure)` helper to flatten the repeated shape.
• The CLI_DISPATCH_PATTERN regex (lib/deployment-docs-audit.js:19) assumes the bin file uses `cliArgs[0] === "name"` guards; if the dispatch table is ever refactored to a switch/lookup object this silently stops finding commands — worth a one-line comment noting that coupling.
• SUBCOMMAND_PATTERN's negative lookbehind excludes `@​jsonbored/gittensory-miner` but would also fail to match if 'gittensory-miner' appears at the very start of a line preceded by nothing — verify this isn't overly permissive in edge cases, though the live-doc test passing suggests it's fine in practice.
• Consider hoisting the repeated for-loop/failure-push pattern in auditDeploymentDocs into a shared helper to reduce the flagged nesting depth and ease adding a fourth claim type later.
• Add a short JSDoc example showing what a `reality` object looks like in production wiring (vs. the test's buildLiveReality) since the .d.ts alone doesn't convey that this is meant to be filesystem-injected.

Signal	Result	Evidence
Code review	✅ No blockers	2 reviewers, synthesized
Linked issue	✅ Linked	#5180
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 63 registered-repo PR(s), 40 merged, 2 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	e11734937-beep; Gittensor profile; 63 PR(s), 2 issue(s).
Gate result	✅ Passing	No configured blocker found.
Improvement	✅ Minor	risk: clean · value: minor — Code changes are accompanied by test evidence. LLM value judgment: moderate — The change is a well-scoped, precedent-following addition (mirrors the self-host audit) that closes a named issue and adds a concrete CI guard against doc drift for a real, previously-unchecked surface.

Linked issue satisfaction

Addressed
The PR adds a deployment-docs-audit module mirroring selfhost-docs-audit.ts that parses DEPLOYMENT.md for GITTENSORY_MINER_*/MINER_* env vars, repo-relative file paths, and CLI subcommands, then cross-checks each against the live source tree with failure messages naming the specific stale claim, wired into test:ci via the new vitest test file with extensive success/failure/regression coverage.

Review context

• Author: e11734937-beep
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: not available
• Official Gittensor activity: 63 PR(s), 2 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

[BETA] Chat with Gittensory

Ask Gittensory a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @gittensory ask <question> answers contribution-quality Q&A with source citations and freshness.
• @gittensory chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @gittensory mention with a real question is routed to the closest matching read-only command automatically -- no exact syntax required.

Full command reference: https://gittensory.aethereal.dev/docs/gittensory-commands

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review

[loopover-orb]

Gittensory approves — the gate is satisfied and CI is green.