docs(selfhost): close first-run onboarding gaps for admin access and GitHub App setup

[JSONbored]

Summary

Closes #2542.

Three first-run operator experience gaps, distinct from the broader image-first onboarding work tracked in #1938:

1. ADMIN_GITHUB_LOGINS (the env var that grants control-panel access) was undocumented anywhere. It fails closed by design (isAuthorizedGitHubSessionLogin in src/auth/security.ts returns false when the allowlist is empty) — a first-time operator signs into their own dashboard and gets silently zero privileges, which reads as a bug rather than the intended next step.
2. A working one-click GitHub App setup wizard already exists (GET /setup in src/selfhost/setup-wizard.ts, POSTs a manifest to GitHub's own App-creation flow) but wasn't mentioned in the docs at all. The manually-documented permission set had also drifted from what the manifest actually requests: docs said Contents: read, add write only if the self-host should merge; the manifest unconditionally requests contents: write (needed for update_branch, not just merge). An operator who created their App manually per the old docs could unknowingly break auto-merge with no error surfaced anywhere.
3. Five env vars the app genuinely reads at runtime (GITHUB_WEBHOOK_MAX_BODY_BYTES, BROWSER_WS_ENDPOINT, MCP_READ_REPO_ALLOWLIST, MCP_ACTUATION_REPO_ALLOWLIST, AI_DAILY_NEURON_BUDGET) were absent from .env.example, discoverable only by grepping source.

What changed

• .env.example: added ADMIN_GITHUB_LOGINS (with its fail-closed behavior spelled out) right after the setup-wizard vars, MCP_READ_REPO_ALLOWLIST/MCP_ACTUATION_REPO_ALLOWLIST alongside it, GITHUB_WEBHOOK_MAX_BODY_BYTES and BROWSER_WS_ENDPOINT in the self-host runtime section, and AI_DAILY_NEURON_BUDGET in the AI review backend section.
• docs.self-hosting-security.tsx: new "Control-panel access" section documenting ADMIN_GITHUB_LOGINS, framed explicitly as fail-closed-by-design (not a bug), right after the existing "put an auth layer in front of dashboards" bullet — the app already has its own built-in gate for this.
• docs.self-hosting-github-app.tsx: new "One-click App creation (recommended for a Direct App)" section documenting the /setup wizard as the primary path, with a note that manual creation is still fully supported. Corrected "Direct App permissions" to state Contents: write (matching buildManifest in setup-wizard.ts exactly) with an explanation of why read is insufficient, instead of the old, now-inaccurate "read, add write only if merging" guidance.

Verification

Ran both changed doc pages through the local dev server (vite dev) at both viewport sizes used elsewhere in this doc set, and caught + fixed one real visual bug in the process: my first draft of the new "One-click App creation" .env code block had a multi-line inline comment that overflowed the CodeBlock component's right edge instead of wrapping (overflow-x: visible on the underlying <code> element) — shortened both comments to one line each in a follow-up commit, confirmed the fix visually. I'm not able to attach the actual screenshot images to this PR body from this environment (no browser session to drag-drop into, and the preview tool doesn't expose a file path for the captured images) — happy to attach them via a follow-up comment if that's needed for review, or you're welcome to run npm --workspace @jsonbored/gittensory-ui run dev and load /docs/self-hosting-security and /docs/self-hosting-github-app directly.

Both changed pages are documentation prose (new headings/paragraphs/lists) plus CodeBlock/Callout usages that are pre-existing, unmodified, already-used-elsewhere-in-this-doc-set components — no new visual components, styling, or layout were introduced.

Validation

• npm run ui:typecheck
• npm run ui:lint (0 errors; only pre-existing, unrelated warnings)
• npm run ui:build
• npm run ui:test
• npm run test:ci (the full local gate, exit 0 — no src/** files changed, this PR is scoped to docs/env-example)
• git diff --check
• Duplicate-variable check across .env.example confirmed none of the 6 newly-added vars collide with an existing entry

Scope

• Change is narrow and limited to the stated problem
• No secrets, wallets, hotkeys, trust scores, or reward values added anywhere
• No edits to site/, CNAME, **/lovable/**, or CHANGELOG.md

Safety

• No auth/session/CORS surface touched — documentation only, no behavior change
• No secrets in .env.example — every new entry is a name + placeholder/description, consistent with the file's existing convention

[loopover-orb]

Tip

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

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-02 20:36:39 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
The diff is a focused documentation/onboarding change: it documents admin control-panel access, adds missing runtime env vars to `.env.example`, and brings the GitHub App permission docs in line with the setup wizard by adding a parity test. The visible implementation is safe enough to proceed because the new test exercises the real `buildManifest` source for permissions/events instead of duplicating an expected manifest by hand. The notable weak spot is that the test is intentionally prose-coupled and can miss wording drift outside the permission/event list, but that is a maintainability nit rather than a breaking defect.

Nits — 6 non-blocking

• nit: `test/unit/setup-wizard-docs-parity.test.ts:6` says the docs claim the list is “generated from the identical source,” but the changed docs now say it is “kept in sync ... and checked in CI,” so update the comment to match the actual contract being tested.
• nit: `test/unit/setup-wizard-docs-parity.test.ts:39` parses the first `Events: ...` sentence in the whole source file, which is fine today but brittle if the page later adds another events mention before the manual list.
• nit: `apps/gittensory-ui/src/routes/docs.self-hosting-github-app.tsx:65` states the wizard is disabled once an App is configured; confirm this remains tied to the same condition operators actually set during first run, because the docs are now making that security behavior explicit.
• In `test/unit/setup-wizard-docs-parity.test.ts`, scope the events regex to the Direct App permissions section or a nearby heading so future prose additions do not accidentally satisfy the parity test.
• In `test/unit/setup-wizard-docs-parity.test.ts`, revise the top comment to describe the actual CI parity check instead of claiming generation from a shared source.
• 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.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#2542
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: 64 registered-repo PR(s), 55 merged, 526 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 64 PR(s), 526 issue(s).
Gate result	✅ Passing	No configured 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: 64 PR(s), 526 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	37f66b2	Commit Preview URL Branch Preview URL	Jul 02 2026, 09:39 PM

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.05%. Comparing base (074b888) to head (37f66b2).
⚠️ Report is 5 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2625   +/-   ##
=======================================
  Coverage   96.05%   96.05%           
=======================================
  Files         234      234           
  Lines       26228    26228           
  Branches     9517     9517           
=======================================
  Hits        25192    25192           
  Misses        425      425           
  Partials      611      611           

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.