docs(orb): separate telemetry from token brokerage

[JSONbored]

Closes #1939

Summary

The GitHub App and Orb doc presented direct App and brokered Orb as symmetric, co-equal options with no risk framing, no explicit "private/managed-beta only" label on brokered mode, and no explanation that telemetry export is a completely separate concern from token brokerage — exactly the conflation this issue asks to resolve.

• Direct App is now explicitly labeled the recommended default; brokered Orb is explicitly labeled private/managed-beta only, with a callout on why (every brokered install draws on gittensory's own GitHub API quota, not just the operator's).
• New "Telemetry is separate from token brokerage" section: telemetry export is always-on in EITHER connection mode (it's what feeds the homepage counters and cross-fleet gate calibration), while brokerage is the optional, restricted piece. Documents exactly what is/isn't exported and the ORB_AIR_GAP opt-out.
• New "Brokered mode operational risks" callout: rate-limit blast radius, quota management, support burden, abuse/misconfiguration risk.
• New "Minimum broker safeguards before a public rollout" maintainer checklist: enrollment quota, per-install concurrency, per-install rate budget, revocation path, metrics broken out by enrollment.

Test plan

• npm run ui:typecheck, npm run ui:lint — clean
• npm run test:ci (full local gate, unsharded) — green
• npm audit --audit-level=moderate — 0 vulnerabilities
• Manually verified in a running dev server: page renders all 8 sections in order including the two new ones

[loopover-orb]

Warning

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

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-03 01:47:00 UTC}

1 file · 1 AI reviewer · 1 blocker · readiness 100/100 · CI green · blocked

⏸️ Suggested Action - Manual Review

• Maintainer test expectations unmet — Add or update tests, or attach passing validation output that satisfies the maintainer's test expectations.

Review summary
This docs-only change clearly separates the recommended direct GitHub App path from private/managed-beta brokered Orb enrollment and adds the missing risk framing around shared infrastructure and quota. The TSX is coherent, the new links/imports are valid in the provided file, and the added sections fit the existing DocsPage/FeatureRow/Callout structure without introducing a visible runtime or type contract break. The main remaining concern is verification of the newly documented telemetry contract, not a code blocker in this diff.

Nits — 6 non-blocking

• nit: apps/gittensory-ui/src/routes/docs.self-hosting-github-app.tsx:113 documents telemetry as enabled by default with ORB_AIR_GAP as the only opt-out, but this PR does not include a doc/contract test or cited source tying that wording to the implementation.
• nit: apps/gittensory-ui/src/routes/docs.self-hosting-github-app.tsx:153 uses a long numbered inline paragraph inside the Callout; splitting those risks into a short list would make the operational checklist easier to scan and maintain.
• Add or point to an existing test/fixture that locks the ORB_AIR_GAP telemetry contract against this docs page so the new guarantee does not drift from behavior.
• Consider converting the brokered-mode operational risks callout at apps/gittensory-ui/src/routes/docs.self-hosting-github-app.tsx:153 into a bullet list matching the safeguard checklist below it.
• 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.
• Code changes lack test evidence — Add focused regression tests or explain why existing coverage is sufficient.

Concerns raised — review before merging

• Maintainer test expectations unmet — Add or update tests, or attach passing validation output that satisfies the maintainer's test expectations.

Signal	Result	Evidence
Code review	❌ 1 blocker	1 reviewer
Linked issue	✅ Linked	#1939
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 (size label size:M; 1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 61 registered-repo PR(s), 52 merged, 506 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 61 PR(s), 506 issue(s).
Gate result	❌ Blocking	Repo-configured hard blocker found.

Review context

• Author: JSONbored
• Role context: owner (maintainer lane)
• Public audience mode: oss maintainer
• Lane context: Repository registration is not available in the local Gittensory cache.
• Public profile languages: not available
• Official Gittensor activity: 61 PR(s), 506 issue(s).
• PR-specific overlap: none found.

Contributor next steps

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

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

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	gittensory-ui	fe57e17	Commit Preview URL Branch Preview URL	Jul 03 2026, 01:48 AM