From d9fb5254cd3de24bb1130ec7dd5d019a5e310908 Mon Sep 17 00:00:00 2001
From: S <islam.ahmad@outlook.com>
Date: Mon, 2 Mar 2026 20:25:29 -0600
Subject: [PATCH] feat: add post-migration check section to usage guide for
 infrastructure validation

---
 USAGE_GUIDE.md | 50 +++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 49 insertions(+), 1 deletion(-)

diff --git a/USAGE_GUIDE.md b/USAGE_GUIDE.md
index 3fd0570..3d67fb8 100644
--- a/USAGE_GUIDE.md
+++ b/USAGE_GUIDE.md
@@ -162,7 +162,17 @@ If you prefer to run each phase individually and inspect results:
 
 ### What to verify when it's done
 
-After the full migration completes:
+After the full migration completes, run the post-migration check:
+
+```bash
+./post-migration-check.sh
+# or equivalently:
+./run_all.sh --dry-run
+```
+
+This probes all live infrastructure and reports the state of every phase — what's done, what's pending, and any errors. See [Post-Migration Check](#post-migration-check) below for details.
+
+You can also verify manually:
 
 1. **HTTPS access**: Open `https://YOUR_DOMAIN` in a browser — you should see the Gitea login page with a valid SSL certificate.
 2. **Repository content**: Log in as admin, navigate to your org, confirm all repos have commits, branches, and (if enabled) issues/labels.
@@ -215,6 +225,44 @@ When resuming from a later phase, Gitea is already running on ports 3000. Use:
 
 ---
 
+## Post-Migration Check
+
+A standalone read-only script that probes live infrastructure and reports the state of every migration phase. No mutations — safe to run at any time, before, during, or after migration.
+
+```bash
+./post-migration-check.sh
+# or:
+./run_all.sh --dry-run
+```
+
+### What it checks
+
+- **Connectivity**: SSH to Unraid/Fedora, Docker daemons, GitHub API token validity
+- **Phase 1-2**: Docker networks, compose files, app.ini, container health, admin auth, API tokens, organization
+- **Phase 3**: runners.conf, registration token, per-runner online/offline status
+- **Phase 4**: GitHub source repos accessible, Gitea repos migrated, Fedora mirrors active
+- **Phase 5**: Workflow directories present in Gitea repos
+- **Phase 6**: Push mirrors configured, GitHub Actions disabled
+- **Phase 7**: Branch protection rules with approval counts
+- **Phase 8**: DNS resolution, Caddy container, HTTPS end-to-end, TLS cert, GitHub `[MIRROR]` marking
+- **Phase 9**: Security scan workflows deployed
+
+### Output format
+
+Three states:
+
+| State | Meaning |
+|-------|---------|
+| `[DONE]` | Already exists/running — phase would skip this step |
+| `[TODO]` | Not done yet — phase would execute this step |
+| `[ERROR]` | Something is broken — needs attention |
+
+`[TODO]` is normal for phases you haven't run yet. Only `[ERROR]` indicates a problem.
+
+The script exits 0 if no errors, 1 if any `[ERROR]` found. A summary at the end shows per-phase counts.
+
+---
+
 ## Edge Cases
 
 ### GitHub API rate limit hit during migration