docs(miner): document opt-in Prometheus textfile-collector export

[JSONbored]

Summary

• Adds scripts/export-miner-prometheus-textfile.sh: runs the miner's four existing Prometheus-text-emitting commands (gittensory-miner metrics, queue metrics, ledger metrics, governor metrics) and atomically writes their concatenated output to a .prom file, following the standard node_exporter textfile collector pattern — mirrors scripts/export-ams-reporting-db.sh's fail-open-per-source philosophy: a broken/corrupt local store for one family never blocks the other three.
• Documents this as a new "Prometheus metrics (opt-in)" section in packages/gittensory-miner/docs/observability.md, alongside a table of all four commands/metric families and a sample crontab line.

Why

#4839 asks for "an optional metrics/tracing integration point, documented, off by default" so a self-hoster can opt in and see miner activity in their own Grafana/observability stack. The four gittensory-miner ... metrics commands already exist (the last two — queue metrics and governor metrics — shipped this session in #5603/#5604) but were never documented as a cohesive story, and nothing bridges a one-shot CLI command to something Prometheus can actually scrape. This closes that gap with the smallest correct mechanism: no new HTTP server, no new dependency, entirely opt-in (nothing in the miner package invokes this script itself — AMS's zero-infra "laptop mode" is unaffected if it's never run).

Closes #4839

Test plan

• sh -n scripts/export-miner-prometheus-textfile.sh (syntax check)
• npm run docs:drift-check
• git diff --check
• Ran the script live against a real (fresh, then populated) local miner config dir: confirmed atomic write (.tmp then mv), and confirmed the fail-open path directly — with one of the four subcommands unavailable, the script still wrote a valid file containing the other three families' metrics and exited 0, logging only the one failure to stderr

This PR touches scripts/** and packages/gittensory-miner/docs/** only — no src/**/packages/*/src/**/packages/gittensory-miner/lib/** changes, so Codecov's patch-coverage gate has nothing to measure here.

[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 95.00%. Comparing base (7e55ebc) to head (5ab5a4e).
⚠️ Report is 4 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5608   +/-   ##
=======================================
  Coverage   95.00%   95.00%           
=======================================
  Files         573      573           
  Lines       45629    45629           
  Branches    14661    14661           
=======================================
  Hits        43350    43350           
  Misses       1528     1528           
  Partials      751      751           

Flag	Coverage Δ
shard-1	44.04% <ø> (ø)
shard-2	35.69% <ø> (ø)
shard-3	32.18% <ø> (ø)
shard-4	32.68% <ø> (ø)
shard-5	31.79% <ø> (ø)
shard-6	44.12% <ø> (ø)

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 09:14:03 UTC}

2 files · 1 AI reviewer · no blockers · readiness 100/100 · CI green · clean

⏸️ Suggested Action - Manual Review

• Touches a guarded path — held for manual review: This PR changes guardrail-protected path(s): scripts/export-miner-prometheus-textfile.sh (matched scripts/**).

Review summary
Adds a shell script that concatenates output from four existing miner CLI subcommands into a Prometheus textfile-collector-compatible .prom file, with per-family fail-open error handling and atomic write via .tmp+mv, plus a documentation section explaining the opt-in wiring. This is a pure docs+ops-script addition with no changes to production code paths, and the mechanism (mirroring the existing export-ams-reporting-db.sh pattern) is sound: each export_family call is independently guarded by the if/else, so one failing subcommand doesn't abort the mkdir/write/mv sequence for the others. The `set -eu` combined with unguarded command substitution or unset var use elsewhere could be a concern, but the script correctly quotes all variable expansions and defaults them.

Nits — 8 non-blocking

• scripts/export-miner-prometheus-textfile.sh: `TMP_FILE` is not cleaned up on early failure (e.g. if `mkdir -p` fails under `set -eu` before any family runs), leaving stray `.tmp` files on repeated failed runs — consider a `trap` to remove it.
• scripts/export-miner-prometheus-textfile.sh: if ALL four `export_family` calls fail, the script still `mv`s an empty file over `OUT_FILE` and exits 0, silently replacing a previously-valid `.prom` file with an empty one — worth a comment or explicit check since this diverges slightly from the 'partial export is better than stale' framing when the export is fully empty.
• packages/gittensory-miner/docs/observability.md: the crontab example doesn't set `GITTENSORY_MINER_PROMETHEUS_TEXTFILE`, so it silently relies on the script's default `/var/lib/...` path being writable by the cron user, which may need root or a pre-created directory — worth calling out.
• Add a `trap 'rm -f "$TMP_FILE"' EXIT` in scripts/export-miner-prometheus-textfile.sh to avoid stray temp files on unexpected failures before the final `mv`.
• Consider having the script exit non-zero (while still writing the partial file) if all four families fail, so cron/systemd can surface a fully-broken export distinctly from a partially-degraded one.
• PR author also opened the linked issue — Link an issue that was opened by a different contributor, or provide a rationale for why this self-authored issue represents genuine discovery work.
• Diff looks like trivial or whitespace-only churn — Reduce whitespace-only or formatting-only churn and keep the diff focused on substantive changes.
• Touches a guarded path — held for manual review — A maintainer must review and merge this change.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#4839
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: 44 registered-repo PR(s), 36 merged, 347 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 44 PR(s), 347 issue(s).
Gate result	⚠️ Not blocking	Advisory; not blocking this PR.
Improvement	⚠️ ℹ️ Insufficient signal	risk: low · value: insufficient-signal — Nothing measurable for the structural-improvement analyzers on this PR (e.g. no code files changed).

Review context

• Author: JSONbored
• Role context: owner (maintainer lane)
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Python, TypeScript, Ruby, Go, JavaScript, MDX, Shell, Solidity
• Official Gittensor activity: 44 PR(s), 347 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Treat this as maintainer-lane context rather than normal contributor-lane activity.

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