docs(miner): add hosted discovery-plane operator guide (#4309)

[andriypolanski]

Summary

• Add packages/gittensory-miner/docs/discovery-plane-operator-guide.md — operator guide for the optional Phase 6 hosted discovery-index plane (#4250).
• Document opt-in default OFF posture and contrast explicitly with Orb's opt-out-only export (src/selfhost/orb-collector.ts, ORB_AIR_GAP).
• Provisional env-var table (GITTENSORY_MINER_DISCOVERY_PLANE, index URL, telemetry flag) marked TBD until #4300 / #4301 ship.
• Add DEPLOYMENT.md-style Invariants and a never included inventory (sourced from #4301 / Orb anonymization posture).
• Link from DEPLOYMENT.md and README.md.

Closes #4309.

Scope

• The PR title follows type(scope): short summary Conventional Commit format, for example fix(api): restore profile access checks.
• 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 (e.g. Closes #123) — a linked open issue is required for every contributor PR.

Validation

• git diff --check
• npm run actionlint
• npm run typecheck
• npm run test:coverage locally; codecov/patch requires ≥99% coverage of the lines AND branches you changed
• npm run test:workers
• npm run build:mcp
• npm run test:mcp-pack
• npm run ui:openapi:check
• npm run ui:lint
• npm run ui:typecheck
• npm run ui:build
• npm audit --audit-level=moderate
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries

If any required check was skipped, explain why:

• Docs-only change under packages/gittensory-miner/** — no src/** diff, no runtime behavior, no new branches to instrument. codecov/patch not applicable.

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed.
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests.
• API/OpenAPI/MCP behavior is updated and tested where needed.
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks.
• Visible UI changes include a UI Evidence section below with JPG/JPEG or PNG screenshots arranged as organized, captioned, clickable thumbnails.
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs.

UI Evidence

n/a — miner-package markdown docs only; no apps/gittensory-ui/** or visible frontend change.

Notes

• Placeholder-scoped by design per docs(miner-discovery-plane): write the hosted-plane opt-in/opt-out operator guide #4309: env var names and wire formats will be updated when #4300, #4301, and #4302 land.
• Server-side operating doc remains #4250 (maintainer-only).

## Changed files

| File | Change |
|------|--------|
| `packages/gittensory-miner/docs/discovery-plane-operator-guide.md` | New operator guide (opt-in, invariants, never-included list, sibling issue links) |
| `packages/gittensory-miner/DEPLOYMENT.md` | Short pointer to optional hosted plane section |
| `packages/gittensory-miner/README.md` | Link to new guide |

[superagent-security]

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

[loopover-orb]

Tip

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

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-09 17:55:17 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This is a pure documentation PR adding an operator guide for the optional, opt-in Phase 6 hosted discovery-index plane, plus two-line cross-links from DEPLOYMENT.md and README.md. It closes the linked open issue #4309, explicitly marks all env-var names and telemetry schema as provisional pending #4300/#4301, and correctly contrasts the new opt-in-default-OFF posture against Orb's opt-out-only export in src/selfhost/orb-collector.ts. No source, schema, or migration changes are involved, so the usual wiring/coverage risks for this repo don't apply here.

Nits — 6 non-blocking

• packages/gittensory-miner/docs/discovery-plane-operator-guide.md:45 uses 'Master opt-in' — swap for 'main' or 'primary' opt-in per the repo's non-inclusive-terminology convention.
• The doc states env vars are provisional/TBD in one breath but then gives a concrete 'Operator checklist' with exact `export GITTENSORY_MINER_DISCOVERY_PLANE=true` style steps — consider adding a one-line caveat at the checklist itself (not just the header) so operators don't copy these as if final.
• The `/^(1|true|yes|on)$/i` truthy-string convention is asserted as 'matching other GITTENSORY_* flags in this repo' — worth a footnote pointing at one concrete existing flag (e.g. ORB_AIR_GAP's parsing) so the claim is checkable rather than asserted.
• Since feat(miner-discovery-plane): define the public-data-only discovery-index API contract #4300/feat(miner-discovery-plane): add anonymized telemetry event schema for the optional hosted plane #4301/feat(miner-discovery-plane): add client-side soft-claim coordination request builder #4302 are all still open, consider a short 'Status: no code yet — env vars are aspirational' banner at the very top of the guide (not just in the placeholder-scope callout) to reduce risk of an operator treating this as shippable config today.
• Cross-check the 'Never included' inventory against the eventual feat(miner-discovery-plane): add anonymized telemetry event schema for the optional hosted plane #4301 schema once it lands, since this guide will otherwise silently drift from the real payload shape.
• Diff looks like trivial or whitespace-only churn — Reduce whitespace-only or formatting-only churn and keep the diff focused on substantive changes.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#4309
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: 141 registered-repo PR(s), 84 merged, 25 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	andriypolanski; Gittensor profile; 141 PR(s), 25 issue(s).
Gate result	✅ Passing	No configured blocker found.

Linked issue satisfaction

Addressed
The PR adds the operator guide at the specified path, explicitly documents opt-in-default-OFF and contrasts it with Orb's opt-out-only posture using the same wording/citations the issue calls for, includes a DEPLOYMENT.md-style Invariants section with a 'never included' inventory, and clearly marks the doc as placeholder-scoped with links back to the sibling contract/telemetry/soft-claim issues (#

Review context

• Author: andriypolanski
• 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: 141 PR(s), 25 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.

_{🟩 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