docs(selfhost): document a real backup/restore drill result

[JSONbored]

Summary

• Closes chore(selfhost): verify backup and restore posture #1821 ("verify backup and restore posture") asks for a restore drill that starts from a clean volume and proves recovered state, not just code review of the backup/restore scripts.
• The existing scripts/verify-backup.sh already had a well-guarded scratch-restore mode (VERIFY_RESTORE_SCRATCH=1 + a dedicated scratch DB URL, with an identity-fingerprint check via pg_control_system() that refuses to run if the scratch URL resolves to the same database as the live source) — this PR runs it for real and documents the result, rather than adding new tooling.
• Ran it against a real production Postgres backup on the live self-host instance: restored into a throwaway, network-isolated scratch Postgres container (new container, new credentials, never the live database), confirmed distinct by the script's own identity check before touching anything. The restore completed cleanly and repopulated all 84 application tables, with the largest operational tables' full row counts intact (hundreds of thousands of rows) — not just an empty schema.
• The scratch container was fully torn down afterward; the live Postgres/app containers were never restarted, reconfigured, or otherwise touched, and /ready was confirmed healthy on the live instance before and after.
• Documents explicitly why the drill stops at DB-level restore rather than booting a full app instance to /ready: that endpoint also gates on live Redis, Qdrant, the AI provider, Codex auth, and a real GitHub App key — reproducing those for a disposable scratch instance would mean copying real credentials into new throwaway infrastructure, which is a bigger risk than the drill is worth. An actual disaster recovery restores onto trusted infrastructure the operator already controls with their own real credentials.

Scope

• The PR title follows type(scope): short summary Conventional Commit format.
• This PR is focused and does not mix unrelated backend, UI, MCP, docs, dependency, and deploy changes — docs-only, one file.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked an issue (Advances #1821 — this documents a real, verified drill result but the issue's broader deliverables, e.g. a Litestream/SQLite-mode drill and a full backup-mode matrix, remain open).

Validation

• git diff --check
• npm run typecheck — not applicable; no src/** or TypeScript logic touched.
• npm run test:coverage — not applicable; docs-only, no Codecov obligation.
• npm run ui:lint
• npm run ui:typecheck
• npm run ui:build
• npm run docs:drift-check

If any required check was skipped, explain why:

• This PR only edits apps/gittensory-ui/src/routes/docs.self-hosting-backup-scaling.tsx. No backend code, schema, or config changed, so the typecheck/coverage/OpenAPI/migration checks have no surface to run against.

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed. The drill write-up names table counts only (no row content, no hostnames, no credentials).
• 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 — not applicable.
• API/OpenAPI/MCP behavior — not applicable.
• UI changes use live API data — not applicable; static docs prose.
• Visible UI changes include a UI Evidence section — this is a docs-content addition to an existing page's existing layout, not a new visual surface; no screenshot attached.
• Public docs/changelogs are updated where needed; changelog untouched (not a release-prep PR).

[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	7604c98	Commit Preview URL Branch Preview URL	Jul 04 2026, 11:03 PM

[loopover-orb]

Warning

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

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-04 23:01:05 UTC}

1 file · 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 update that records the July 4, 2026 database restore drill and clearly scopes what was and was not exercised. The most important part is correct: it does not overclaim full app readiness, and it explicitly distinguishes database-level restore proof from a full disaster-recovery rehearsal. I do not see a code or docs-contract defect in the changed file.

Nits — 7 non-blocking

• nit: apps/gittensory-ui/src/routes/docs.self-hosting-backup-scaling.tsx:162 includes a specific production backup filename; keep it only if you intentionally want that operational identifier in public docs, otherwise replace it with a date-only or sanitized drill ID.
• nit: apps/gittensory-ui/src/routes/docs.self-hosting-backup-scaling.tsx:159 the heading says `restore-tested` but the earlier checklist at apps/gittensory-ui/src/routes/docs.self-hosting-backup-scaling.tsx:114 still requires booting the app and checking `/ready`, so I would make the heading explicitly say `database restore drill` to reduce reader ambiguity.
• apps/gittensory-ui/src/routes/docs.self-hosting-backup-scaling.tsx:159 change the heading to `Database restore drill: what was verified` or similar, so the section does not read like it fully satisfies the broader restore checklist above.
• apps/gittensory-ui/src/routes/docs.self-hosting-backup-scaling.tsx:162 consider replacing `gittensory-20260704T090939Z.dump` with a sanitized drill identifier unless the exact backup name is intentionally part of the public audit trail.
• apps/gittensory-ui/src/routes/docs.self-hosting-backup-scaling.tsx:167 consider linking or summarizing a sanitized command transcript in the linked issue so future maintainers can audit the table-count claim without relying only on prose.
• 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	#1821
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 (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 56 registered-repo PR(s), 46 merged, 429 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 56 PR(s), 429 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: Python, TypeScript, JavaScript, Ruby, Go, Kotlin, MDX, Shell
• Official Gittensor activity: 56 PR(s), 429 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