docs(selfhost): define safe update and rollback flow

[andriypolanski]

Summary

• Expand the Updating and rolling back section on the Operations docs page with explicit preflight/post-update checklists, an operator-owned files callout, and guidance on app-only restarts vs recreating profile services.
• Add scripts/selfhost-post-update-check.sh — a read-only helper that verifies /ready, container health, .env release metadata, and the running image after an update.
• Add a drift-guard unit test tying docs to the deploy and post-update scripts.

Closes #1823

Scope

• Docs-only + one small operator script (no src/** changes — Codecov patch N/A)
• Preserves .env, gittensory-config/, data volumes, auth material, Grafana state, and docker-compose.override.yml — documented explicitly; scripts unchanged except new read-only helper
• Image-tag path (deploy-selfhost-image.sh) and source-checkout path (git pull + deploy-selfhost-prebuilt.sh) documented with copy/paste commands
• Migration/rollback limits (forward-only migrations, image rollback vs schema rollback) retained and cross-linked

Changed files

File	Change
apps/gittensory-ui/src/routes/docs.self-hosting-operations.tsx	Preflight/post-update checklists, operator-owned callout, app vs profile restart guidance
apps/gittensory-ui/src/routes/docs.maintainer-self-hosting.tsx	Operations blurb mentions update/rollback
scripts/selfhost-post-update-check.sh	New post-update verification helper
test/unit/docs-selfhost-update-rollback.test.ts	Doc/script drift guard

Validation

git diff --check
npx vitest run test/unit/docs-selfhost-update-rollback.test.ts test/unit/selfhost-image-deploy.test.ts
npm run docs:drift-check
npm --workspace @jsonbored/gittensory-ui run lint
npm --workspace @jsonbored/gittensory-ui run typecheck
npm run test:ci
npm audit --audit-level=moderate

Optional manual smoke on a disposable stack:

./scripts/deploy-selfhost-image.sh
./scripts/selfhost-post-update-check.sh

Safety

• Post-update script is read-only — no writes to .env, volumes, or compose state
• No secrets or private policy in docs changes

[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-06 05:40:07 UTC}

6 files · 1 AI reviewer · no blockers · readiness 80/100 · CI green · clean

⏸️ Suggested Action - Manual Review

Review summary
This is a docs-only restructuring of the self-host update/rollback flow: it replaces prose with explicit preflight/post-update checklists, adds an operator-owned-files callout, and ships a new read-only script (selfhost-post-update-check.sh) that probes /ready, container health, .env release metadata, and the running image. The new script relies on scripts/lib/selfhost-deploy-common.sh for require_cmd/compose_file_args, which isn't shown in this diff but is presumably the same shared helper already used by deploy-selfhost-image.sh and deploy-selfhost-prebuilt.sh (those two only get a 2-line comment addition here, implying no change to their existing sourcing). The drift-guard test ties doc content to literal strings in the deploy scripts and the new helper, which is a reasonable coverage approach for a docs+script PR with no src/** changes.

Nits — 5 non-blocking

• apps/gittensory-ui/src/routes/docs.self-hosting-operations.tsx has grown to roughly 795 lines per the size-smell report (threshold 400) — worth splitting into smaller sub-components if this page keeps accreting sections.
• scripts/selfhost-post-update-check.sh only warns to stderr and continues when .env is missing (the `else` branch around line ~48), but the doc's post-update checklist frames confirming the release id as a required step — consider exiting non-zero there for consistency with the other hard failures in the script.
• Confirm scripts/lib/selfhost-deploy-common.sh actually exports require_cmd and compose_file_args as used by the new script — it isn't part of this diff so it can't be verified here, but the new script's correctness depends entirely on it.
• test/unit/docs-selfhost-update-rollback.test.ts asserts exact substrings like 'up -d --no-build --no-deps "$SERVICE"' in the deploy scripts, which is a brittle drift guard that will false-fail on any unrelated formatting change to that line.
• Add a short note in selfhost-post-update-check.sh's header comment (or the docs) about its dependency on scripts/lib/selfhost-deploy-common.sh so future edits to that shared lib know this script also depends on it.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#1823
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	❌ 5/25	Preflight is holding this PR: the review lane is unavailable, so it is not ready for automated review.
Contributor workload	✅ 10/10	Author activity: 126 registered-repo PR(s), 76 merged, 5 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	andriypolanski; Gittensor profile; 126 PR(s), 5 issue(s).
Gate result	✅ Passing	No configured blocker found.

Review context

• Author: andriypolanski
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository registration is not available in the local Gittensory cache.
• Public profile languages: TypeScript, JavaScript, Python, Rust, Cuda, Kotlin, MDX, Scala
• Official Gittensor activity: 126 PR(s), 5 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Await review-lane availability.
• Refresh registry data or choose a registered active repo.

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.28%. Comparing base (a151d8a) to head (289ffdb).
⚠️ Report is 40 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3713   +/-   ##
=======================================
  Coverage   93.28%   93.28%           
=======================================
  Files         314      314           
  Lines       32054    32054           
  Branches    11747    11747           
=======================================
  Hits        29903    29903           
  Misses       1517     1517           
  Partials      634      634           

🚀 New features to boost your workflow:

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

[loopover-orb]

Gittensory approves — the gate is satisfied and CI is green.