docs(selfhost): recommend pull vs. push relay mode, add pull-mode smoke scenario

[JSONbored]

Summary

Completes #1825's remaining deliverables that PR #3193's code-level audit explicitly left open (its own "What's not done" section): a written stable-ingress-vs-pull-mode recommendation, a reproducible pull-mode smoke-test scenario, and troubleshooting guidance for a failed relay registration in each mode.

Grounded entirely in the current code (src/orb/broker-client.ts, src/orb/relay.ts, src/server.ts, src/selfhost/monitored-work.ts) and the existing docs, not invented — see file:line detail below.

What changed

• docs.self-hosting-github-app.tsx: new "Choosing a relay mode: pull vs. push" section. Makes explicit what the code already implies but never stated for operators: pull mode (ORB_RELAY_MODE=pull) needs no inbound endpoint at all and is the right fit for NAT/tailnet deployments with no stable public ingress; push mode (the default) requires PUBLIC_API_ORIGIN to be a real, internet-reachable, TLS-terminated URL that the broker SSRF-validates at registration time. Also expands the "Brokered Orb env" code block to show ORB_RELAY_MODE.
• docs.self-hosting-release-checklist.tsx: the existing "2. Brokered mode" smoke scenario only exercised push mode. Added a pull-mode variant alongside it (no PUBLIC_API_ORIGIN needed) since the two modes exercise genuinely different code paths, not just different env vars.
• docs.self-hosting-troubleshooting.tsx: expanded "Orb export or relay problems" with specific guidance for selfhost_orb_relay_register_failed — what it means and what to check, broken out by relay mode (release-blocking + check PUBLIC_API_ORIGIN for push; non-fatal + check ORB_ENROLLMENT_SECRET for pull).

Why

Issue #1825 asked for exactly this ("Clear recommendation for stable ingress versus pull-mode default for NAT/tailnet deployments" + "Reproducible smoke checklist for both pull-mode and push-mode relay"), but PR #3193 (the code audit) only covered push mode in the smoke checklist and left the ingress recommendation as an implicit code default rather than written operator guidance. #1825 itself is already closed (auto-closed on #3193's merge), so this references it for traceability without attempting to close it again.

Validation

• npm run ui:typecheck
• npm run ui:lint (0 errors; pre-existing react-refresh/only-export-components warnings unrelated to this change)
• npm run ui:test (64/64 passing)
• npm run ui:build
• npm run ui:version-audit
• npm run docs:drift-check
• No src/** changes — Codecov's patch-coverage gate does not apply

Scope

• Change is narrowly scoped to docs/UI route files
• No changes to site/, CNAME, or **/lovable/**
• No changelog edits
• No secrets, wallets, hotkeys, trust scores, or reward values added anywhere

Safety

• No secrets/wallets/hotkeys/trust-score/reward terms anywhere
• Docs-only change; no behavior change to the running self-host stack

[superagent-security]

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

[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	5f28d82	Commit Preview URL Branch Preview URL	Jul 04 2026, 08:56 PM

[loopover-orb]

Warning

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

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-04 20:55:51 UTC}

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

⏸️ 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 is a docs-only change that correctly separates brokered pull and push relay guidance and ties the release checklist/troubleshooting language to the current relay code paths. The most notable risk is consistency: the new smoke example now says push mode requires a real reachable public origin while still showing a placeholder `.example` URL, which can lead operators to run a scenario that cannot pass unchanged. No blocking code defect is introduced in the provided diff.

Nits — 5 non-blocking

• nit: apps/gittensory-ui/src/routes/docs.self-hosting-release-checklist.tsx:84 says push mode requires a real, internet-reachable `PUBLIC_API_ORIGIN`, but the example immediately below still uses `https:​//selfhost-smoke.example`, so I would change that placeholder to an explicitly operator-owned hostname or add a short inline note that it must be replaced before running the smoke.
• nit: apps/gittensory-ui/src/routes/docs.self-hosting-release-checklist.tsx:82 says pull mode tolerates `selfhost_orb_relay_register_failed`, while the pull smoke at line 100 forbids that event; that can be defensible for an RC smoke, but I would spell out that the smoke is stricter than beta operations.
• apps/gittensory-ui/src/routes/docs.self-hosting-release-checklist.tsx:88: replace `https:​//selfhost-smoke.example` with a clearly substituted value like `https:​//<your-public-selfhost-origin>` so the command does not look copy-paste runnable with an invalid origin.
• apps/gittensory-ui/src/routes/docs.self-hosting-release-checklist.tsx:100: add a one-line comment before the pull-mode `SELFHOST_SMOKE_FORBID_EVENTS` explaining that release smoke requires clean registration even though transient pull-mode failures are operationally non-fatal.
• 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	✅ No-issue rationale	PR body explains why no issue is linked.
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 (no linked issue context).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 60 registered-repo PR(s), 50 merged, 438 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 60 PR(s), 438 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: 60 PR(s), 438 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Treat this as maintainer-lane context rather than normal contributor-lane activity.
• No action.
• Link the issue being solved, or explicitly explain why this is a no-issue PR.

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