docs(selfhost): make beta onboarding image-first

[JSONbored]

Closes #1938

Summary

• The documented self-host path was source-build-first (docker compose up --build) even though a published-image deploy script (scripts/deploy-selfhost-image.sh) already existed and was never surfaced in the docs. The sample env also mixed Cloudflare Worker vars with self-host-only vars, with no focused starter file, no AI-provider quick-pick, and no enabled/opt-in defaults table.
• Quickstart now leads with ./scripts/deploy-selfhost-image.sh (pull the published image, no local build/Node toolchain) as the recommended boot path, with docker compose up --build demoted to an explicit "building from source" alternative for contributors.
• New .env.selfhost.example: the short path — required secrets plus the existing conservative first-boot config, with nothing about the Worker deploy. .env.example remains the exhaustive reference for every optional service.
• New "Choose your AI provider" step with three separately copyable Claude-Code-only / Codex-only / both blocks (kept as one uncommented block in an earlier revision, which the gate caught: pasting all three together set AI_PROVIDER three times), plus the existing Codex fail-closed safety callout surfaced up front instead of only in the env file comments.
• New "Defaults at a glance" section (moved to the end, after the numbered steps, per gate feedback that it interrupted the sequential flow): what's on by default vs. what needs an explicit --profile or AI_PROVIDER, plus the Orb telemetry always-on notice.
• Quickstart's log-events step now explains which first-boot log noise is expected (migrations burst, brief Redis retry) vs. worth investigating.
• docker-compose.yml's header comment documents both boot paths instead of only the build-from-source one.

No dedicated tests

Docs/config content changes (compose header comment, docs page copy, a new sample env file) — no src/** logic changed, not measured by Codecov. Verified manually: docker compose config -q (compose still valid), a running dev server render of the new Quickstart flow, and the full local gate.

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
• docker compose config -q — compose file still valid after the header comment update
• Manually verified in a running dev server: Quickstart renders the new steps in order (env → AI provider → boot the stack → GitHub App → first review → defaults table), each AI-provider choice is a separately copyable block, Configuration page links back to the focused env file

[loopover-orb]

Warning

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

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-03 00:41:39 UTC}

5 files · 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 PR reorients the self-host quickstart around the published-image deploy path, adds a focused tracked `.env.selfhost.example`, and points the broader configuration docs back to that short path. The visible React docs changes are structurally coherent and the `.gitignore` negation correctly keeps the new env example tracked despite `.env.*`. I found no code-breaking defect in the provided diff; the remaining issues are documentation precision around first-boot prerequisites and copy/paste safety.

Nits — 7 non-blocking

• nit: `.env.selfhost.example:18` defaults to `GITHUB_APP_PRIVATE_KEY_FILE=/run/secrets/github-app-private-key.pem`, but the quickstart does not show how that file gets created or mounted, so add a short pointer to the existing secret-file setup or show the inline `GITHUB_APP_PRIVATE_KEY` fallback more explicitly.
• nit: `.env.selfhost.example:72` repeats the Codex provider block in the combined-provider example without repeating the `/data/codex` auth-volume requirement, which is easy to miss when users copy only that block.
• nit: `apps/gittensory-ui/src/routes/docs.self-hosting-quickstart.tsx:88` shows the Codex-only block with the opt-in flag but not the required auth volume in the same copyable example, so the example is not self-contained for a first-time operator.
• nit: `.env.selfhost.example:20` uses `https:​//example.invalid/registry.json` for a required runtime URL; consider either documenting that this placeholder must be replaced or using the canonical public registry URL if one exists.
• Add a quickstart line after `cp .env.selfhost.example .env` that tells users exactly where to put the GitHub App private-key file for the compose stack, or to switch to `GITHUB_APP_PRIVATE_KEY` inline for the trial path.
• 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	#1938
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:L; 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	273f8bb	Commit Preview URL Branch Preview URL	Jul 03 2026, 12:27 AM