feat(miner): publish operational files (DEPLOYMENT.md, docs, Dockerfile, schema) in the npm package (#4874)

[carlh7777]

Summary

The published @jsonbored/gittensory-miner package's files list was ["bin", "lib", "expected-engine.version"], so an npm install -g user — the README's own quickstart path — had no access to the package's operational material (DEPLOYMENT.md, the docs/ directory, the Dockerfile, or the schema/ directory) without separately visiting the GitHub repo.

This ships that material with the package:

• package.json — adds docs, schema, DEPLOYMENT.md, and Dockerfile to files.
• scripts/check-miner-package.mjs (the test:miner-pack gate, an allowlist over the packed file set) — extends ALLOWED to permit those paths (DEPLOYMENT.md, Dockerfile, docs/*.md, schema/*.json), adds DEPLOYMENT.md / Dockerfile / schema/miner-goal-spec.schema.json to REQUIRED, and adds a docs/*.md presence check — so the operational files are now a published guarantee, asserted on every pack, not just a one-time addition that could silently regress.
• Tests — a complete package (incl. the operational files) is accepted; each of DEPLOYMENT.md and a docs file being absent is rejected with a specific message; and the docs allowlist stays tight (a non-.md or nested docs file is still rejected).

Verified against the real npm pack --dry-run output: all four categories now appear in the packed set and pass the check. The allowlist is deliberately kept narrow (only docs/*.md and schema/*.json, not arbitrary nested paths), consistent with the existing lib/ flattening discipline.

Closes #4874

Scope

• The PR title follows type(scope): short summary Conventional Commit format.
• This PR is focused and does not mix unrelated backend, UI, MCP, docs, dependency, and deploy changes.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked a currently open issue this PR resolves (Closes Publish operational files with the npm package #4874).

Validation

• git diff --check
• npm run typecheck
• npm run test:miner-pack logic verified: the real npm pack --dry-run file list (205 files) fed through check-miner-package.mjs passes and includes DEPLOYMENT.md, Dockerfile, docs/*.md, and schema/miner-goal-spec.schema.json. Unit tests in check-miner-package.test.ts (fixed 1 order-affected case + 4 new operational-file cases) pass; the sole failing case (passes on the real workspace package) is a pre-existing Windows-only npm-spawn issue that fails identically on main and passes on CI/Linux.
• npm run test:workers · build:mcp · ui:* — N/A (miner package files + its pack-check script/tests only).

If any required check was skipped, explain why:

Change is confined to the miner package's files list, the test:miner-pack check script, and that script's unit tests. No worker src/**, workflow, MCP, OpenAPI, or UI surface is touched.

Safety

• No secrets, wallet details, hotkeys, coldkeys, PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed. The pack check's existing secret-content scan runs over every newly-published file; the operational files were confirmed free of secret-like patterns, and the scan now guards them on every pack.
• Public GitHub text stays sanitized and low-noise.
• Auth/CORS/session negative-path tests — N/A.
• API/OpenAPI/MCP behavior updated/tested — N/A.
• UI changes use real states — N/A (no UI).
• Visible UI changes include UI Evidence — N/A.
• Public docs/changelogs updated where needed — N/A (publishes existing docs; no changelog edit).

UI Evidence

N/A — packaging change, no UI.

Notes

• The operational files are added to REQUIRED (not just ALLOWED) so the pack check now fails if any of them is ever dropped from the package again — turning Publish operational files with the npm package #4874 into an enforced invariant rather than a one-off fix.
• README.md is already published (npm includes it by default); only the four categories the issue named were missing.

[superagent-security]

🚨 Contributor flagged. Click here for more info: Superagent Dashboard

[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.79%. Comparing base (05d1fb0) to head (545efa5).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5528   +/-   ##
=======================================
  Coverage   94.79%   94.79%           
=======================================
  Files         566      566           
  Lines       45065    45065           
  Branches    14675    14675           
=======================================
  Hits        42718    42718           
  Misses       1613     1613           
  Partials      734      734           

Flag	Coverage Δ
shard-1	44.20% <ø> (ø)
shard-2	35.47% <ø> (ø)
shard-3	31.94% <ø> (ø)
shard-4	31.93% <ø> (ø)
shard-5	32.87% <ø> (+<0.01%)	⬆️
shard-6	43.51% <ø> (ø)

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

🚀 New features to boost your workflow:

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

[loopover-orb]

Warning

🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-13 04:03:54 UTC}

3 files · 1 AI reviewer · no blockers · readiness 100/100 · CI green · unstable

⏸️ Suggested Action - Manual Review

• Touches a guarded path — held for manual review: This PR changes guardrail-protected path(s): scripts/check-miner-package.mjs (matched scripts/**).

Review summary
This PR closes #4874 by adding docs/, schema/, DEPLOYMENT.md, and Dockerfile to the miner package's published files list, and correctly hardens the test:miner-pack allowlist/REQUIRED/docs-presence checks so these files can't silently regress out of future packages. The regex allowlist additions are appropriately narrow (docs/*.md only, no nesting; schema/*.json only), consistent with the existing lib/ flattening discipline noted in the #3704 regression comment, and the new tests exercise both the happy path and each rejection branch (missing DEPLOYMENT.md, missing docs, non-md/nested docs file). The change is small, mechanical, and fully covered by its own tests.

Nits — 6 non-blocking

• The 'magic numbers' flagged in the external brief (scripts/check-miner-package.mjs:17-18,46) are regex/array literals, not numeric magic constants — not an actionable nit.
• README.md is still not in the miner package's `files` list even though it's allowlisted in check-miner-package.mjs's ALLOWED patterns; worth confirming that's intentional and unrelated to this PR's scope.
• Consider linking the DEPLOYMENT.md/docs pattern used here to any similar allowlist in the mcp package's release-candidate script (test/unit/mcp-release-candidate.test.ts) for consistency if that package ever ships similar operational files.
• nit: scripts/check-miner-package.mjs:14 uses a broad `schema/[a-z0-9.-]+.json` allowlist while only `schema/miner-goal-spec.schema.json` is required, so consider keeping the schema allowlist closer to the actual published contract unless future schema files are intentional.
• nit: test/unit/check-miner-package.test.ts:129 adds explicit missing-file coverage for `DEPLOYMENT.md` and docs, but not for `Dockerfile` or the required schema file; adding one table-driven test would make the new REQUIRED entries harder to regress independently.
• Touches a guarded path — held for manual review — A maintainer must review and merge this change.

Flagged checks (non-blocking)

• Contributor trust — Contributor flagged for review

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#4874
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: 190 registered-repo PR(s), 120 merged, 17 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	carlh7777; Gittensor profile; 190 PR(s), 17 issue(s).
Gate result	⚠️ Not blocking	Advisory; not blocking this PR.
Improvement	✅ Minor	risk: clean · value: minor — Code changes are accompanied by test evidence.

Review context

• Author: carlh7777
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Python, JavaScript, TypeScript, Cuda, HTML, MDX, Rust
• Official Gittensor activity: 190 PR(s), 17 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