docs(self-hosting): document backpressure, orb, and config-as-code gaps

[JSONbored]

Summary

• Fills a self-hosting documentation audit's confirmed gaps in docs.self-hosting-configuration.tsx and docs.tuning.tsx, plus the pages those gaps point at (docs.self-hosting-github-app.tsx, docs.self-hosting-ai-providers.tsx, docs.self-hosting-rag.tsx, docs.self-hosting-operations.tsx).
• Adds prose for ~25 previously-undocumented operator-relevant env vars: the maintenance-admission and per-installation-concurrency backpressure cluster (tied to a real past production incident — un-jittered cron enqueue), FOREGROUND_LIVENESS_*, OTEL_*, MIGRATIONS_DIR/REVIEW_AUDIT_DIR/CODEX_HOME, PORT, ORB_ANONYMIZE/ORB_COLLECTOR_URL/ORB_COLLECTOR_TOKEN/ORB_APP_ID, per-provider AI base-URL siblings (OPENAI_AI_*, OLLAMA_AI_*, ANTHROPIC_AI_BASE_URL, AI_EMBED_API_KEY), PGVECTOR_ENABLED, SENTRY_SERVER_NAME, and the per-PR DISCORD_WEBHOOK_URL/DISCORD_REPO_WEBHOOKS/SLACK_WEBHOOK_URL notification webhooks (explicitly distinguished from the existing Alertmanager infra-alert Discord/Slack wiring).
• Documents .gittensory.yml blocks that had zero website coverage anywhere: gate.checkMode, the gate.cla sub-object, gate.expectedCiContexts, gate.premergeContentRecheck, gate.requireFreshRebaseWindow, gate.dryRun, gate.firstTimeContributorGrace, settings.closeOwnerAuthors, top-level blockedPaths, the ~20-field anti-abuse settings cluster, the features: 3-state (true/false/omitted) fallback semantics, and the entire contentLane: block.
• Adds explicit config precedence (.gittensory.yml > per-repo DB settings > built-in defaults, with the gate: alias overriding settings: for the same fields) and a link to .gittensory.yml.example as the authoritative reference, plus two-way cross-links between docs.self-hosting-configuration.tsx and docs.tuning.tsx (previously zero links existed between them despite docs.tuning.tsx holding the best gate:/settings: field explanations).
• Fixes the one confirmed accuracy defect: the "Instance-wide write switches" section described three modes but never named the env var controlling them. Now names SELFHOST_DEPLOYMENT_MODE explicitly (verified live at src/github/client.ts:613-631, src/env.d.ts:148).
• Every fact was cross-checked against the source that actually reads the variable (not just the .env.example comment) — for example ORB_APP_ID had zero prior mention anywhere; reading src/selfhost/orb-collector.ts:59 shows it overrides the seed used to derive a brokered instance's stable anonymous instance_id, which is what's documented here.

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 an issue, or this is small enough that the summary explains why an issue is not needed. — Advances roadmap(selfhost): production hardening and first release readiness #1819 (self-host production-readiness roadmap); this is documentation-depth work, not a single tracked issue, so it's a non-closing reference.

Validation

• git diff --check
• npm run actionlint — not applicable, no workflow changes.
• npm run typecheck — n/a to src/** (no backend changes); ran npm run ui:typecheck instead (clean).
• npm run test:coverage — not applicable: docs-only change under apps/gittensory-ui/**, which Codecov does not measure (no src/** touched).
• npm run test:workers — not applicable, no backend/worker code changed.
• npm run build:mcp / npm run test:mcp-pack — not applicable, no MCP package changes.
• npm run ui:openapi:check — not applicable, no API/schema changes.
• npm run ui:lint (clean; ran npm --workspace @jsonbored/gittensory-ui run format first to fix prose line-wrap formatting)
• npm run ui:typecheck
• npm run ui:build
• npm run docs:drift-check
• npm audit --audit-level=moderate — not run standalone; no dependency changes in this PR.
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries — not applicable, no src/** behavior changed.

If any required check was skipped, explain why:

• This is a docs-only change confined to apps/gittensory-ui/src/routes/docs.*.tsx. No src/**, workflow, MCP, OpenAPI, or dependency files changed, so the Codecov/coverage/worker/MCP/audit checks above don't apply. Ran the docs-specific gate instead: ui:lint, ui:typecheck, ui:build, docs:drift-check, all green.

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. — not applicable, no code changed.
• API/OpenAPI/MCP behavior is updated and tested where needed. — not applicable.
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks. — not applicable, static prose only.
• Visible UI changes include a UI Evidence section below — see note below.
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs (not touched here).

UI Evidence

This is prose-only content added inside existing, already-styled doc pages, using only components already in use throughout those same pages (Callout, CodeBlock, FeatureRow, Link) — no new visual components, layout, or styling. The local preview tooling in this environment resolved to a different worktree's unmodified files, so rather than capture a screenshot of the wrong content, verification was done directly against this branch's production build output:

npm run ui:build
grep -o "SELFHOST_DEPLOYMENT_MODE\|Precedence\|contentLane\|checkMode" \
  apps/gittensory-ui/dist/client/assets/docs.self-hosting-configuration-*.js
# => Precedence / SELFHOST_DEPLOYMENT_MODE / checkMode / contentLane all present

The same check was repeated for all six touched pages, confirming every new string (ORB_ANONYMIZE, ORB_APP_ID, OLLAMA_AI_BASE_URL, PGVECTOR_ENABLED, SENTRY_SERVER_NAME, DISCORD_REPO_WEBHOOKS, etc.) compiles into the correct route's client bundle.

Notes

• Scope was intentionally limited to docs.self-hosting-configuration.tsx and docs.tuning.tsx per the audit, plus the specific named cross-links into docs.self-hosting-github-app.tsx, docs.self-hosting-ai-providers.tsx, docs.self-hosting-rag.tsx, and docs.self-hosting-operations.tsx where the audit called out exact existing sections to extend.
• Intentionally skipped per the audit's own carve-out: OBSERVABILITY_SMOKE_POLL_MS, OBSERVABILITY_SMOKE_TIMEOUT_MS, SELFHOST_SERVICE (smoke-test-script-only), SELFHOST_BUNDLE_ALL, and HOME — none are real operator configuration surfaces.

[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	87d12e2	Commit Preview URL Branch Preview URL	Jul 05 2026, 01:06 AM

[superagent-security]

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

[loopover-orb]

Warning

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

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-05 01:09:45 UTC}

6 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 PR is documentation-only and coherently fills self-hosting/operator gaps across configuration, tuning, AI provider, RAG, Orb, and operations pages. The added imports and JSX usage are consistent with the existing docs patterns, and CI already verified the UI build on this commit. I do not see a reachable code defect in the visible diff, but a few operator-facing examples would benefit from tighter wording so they do not age poorly or overstate defaults.

Nits — 6 non-blocking

• nit: apps/gittensory-ui/src/routes/docs.self-hosting-ai-providers.tsx:85 uses `OPENAI_AI_MODEL=gpt-5.5` as the documented default, which is likely to age quickly and should either point at the actual env default from the provider code or use a placeholder like `<model>` unless this exact model is pinned by the runtime.
• nit: apps/gittensory-ui/src/routes/docs.self-hosting-configuration.tsx:381 says `.gittensory.yml.example` is the authoritative reference while also saying some fields are documented only in comments there; consider making this page name which fields are intentionally deferred to the example so the docs contract is less split.
• nit: apps/gittensory-ui/src/routes/docs.self-hosting-github-app.tsx:196 says `ORB_COLLECTOR_TOKEN` is for a private collector, but does not say whether it is ignored or still sent when `ORB_COLLECTOR_URL` points at the hosted collector; clarify that behavior to avoid accidental credential exposure assumptions.
• apps/gittensory-ui/src/routes/docs.self-hosting-ai-providers.tsx:85: replace the concrete OpenAI model example with the runtime default pulled from the provider config, or use `OPENAI_AI_MODEL=<model>` and say the default is defined by the release.
• apps/gittensory-ui/src/routes/docs.self-hosting-configuration.tsx:149: add a one-line pointer from `MIGRATIONS_DIR` to the shipped migration directory layout if custom image builders are expected to override it.
• 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: 56 registered-repo PR(s), 46 merged, 423 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 56 PR(s), 423 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: 56 PR(s), 423 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