auto: docs sync 2026-06-29T00:00:11+00:00

Files changed: .claude/settings.local.json engine/lint-report.md vault/.obsidian/workspace.json vault/runbooks/central-deploy-cutover.md

.claude/settings.local.json

@@ -27,7 +27,29 @@
       "Bash(gh pr create --title 'eonet: bypass bbox filter for global disaster feed' --body ' *)",
       "Read(//tmp/central-clone/**)",
       "Bash(gh pr create --title 'supervisor: shrink sat dedup window + WAL cursors.db to cut CPU/IO' --body ' *)",
-      "Bash(shellcheck --version)"
+      "Bash(shellcheck --version)",
-    ]
+      "Read(//tmp/central-deploy-work/**)",
+      "Read(//tmp/central-deploy-work/scripts/**)",
+      "Bash(chmod +x /tmp/central-deploy-work/scripts/deploy.sh)",
+      "Bash(bash -n /tmp/central-deploy-work/scripts/deploy.sh)",
+      "Bash(gh pr create --title 'scripts/deploy.sh: one-command tag-based deploy with pre-flight backup + verify' --body ' *)",
+      "Skill(update-config)",
+      "Edit",
+      "Write",
+      "Read",
+      "Glob",
+      "Grep",
+      "Bash(sudo *)",
+      "Bash(psql *)",
+      "Bash(systemctl *)",
+      "Bash(journalctl *)",
+      "Bash(curl *)",
+      "Bash(uv *)",
+      "Bash(pg_dump *)",
+      "Bash(python3 *)",
+      "Bash(scp *)",
+      "Bash(gh *)"
+    ],
+    "defaultMode": "bypassPermissions"
   }
 }

engine/lint-report.md

@@ -1,6 +1,6 @@
 # Vault Lint Report
 
-Generated: 2026-06-28T12:00:07Z  |  Docs scanned: 96  |  Elapsed: 0.0s
+Generated: 2026-06-28T18:00:07Z  |  Docs scanned: 96  |  Elapsed: 0.0s
 
 ## Summary
 

vault/.obsidian/workspace.json

@@ -199,6 +199,10 @@
   },
   "active": "17bd4a6166f789d0",
   "lastOpenFiles": [
+    "runbooks/central-deploy-cutover.md.tmp.3603785.4e7865cbcf79",
+    "runbooks/central-deploy-cutover.md.tmp.3603785.af9622a37ece",
+    "runbooks/central-deploy-cutover.md.tmp.3603785.45f414c68859",
+    "runbooks/central-deploy-cutover.md.tmp.3603785.ae5558fd7b31",
     "runbooks/central-deploy-cutover.md",
     "runbooks/central-deploy-cutover.md.tmp.2734058.9aafbee53297",
     "docs/software/navi.md.tmp.5281.13900bd73182",
@@ -207,9 +211,6 @@
     "runbooks/fleet-magicdns-resolved-migration.md.tmp.5281.0b86b5de4a11",
     "runbooks/fleet-magicdns-resolved-migration.md.tmp.5281.f94befc79ce2",
     "runbooks/fleet-magicdns-resolved-migration.md.tmp.5281.e8ec4cd814f7",
-    "runbooks/fleet-magicdns-resolved-migration.md.tmp.5281.fad0ae6cac23",
-    "runbooks/fleet-magicdns-resolved-migration.md.tmp.5281.70c8d22f0a1d",
-    "runbooks/fleet-magicdns-resolved-migration.md.tmp.5281.3a384be4f42c",
     "runbooks/fleet-magicdns-resolved-migration.md",
     "projects/fleet-platform-baseline.md",
     "runbooks/toc-cortex-pve9.2-update.md",
@@ -235,7 +236,6 @@
     "INDEX.md",
     "glossary.md",
     "concepts/youtube.md",
-    "concepts/tailscale-ssh.md",
     "assets/echo6yellow_logo_422x422_square.png",
     "assets/echo6yellow_logo_422x81.png",
     "assets/echo6_logo.png",

vault/runbooks/central-deploy-cutover.md

@@ -43,11 +43,13 @@ systemctl is-active central-supervisor central-archive central-gui
 **2. Confirm migration state is clean:**
 
 ```bash
-sudo -u central /opt/central/.venv/bin/central-migrate --check
+sudo -u central bash -c 'cd /opt/central && set -a && . /etc/central/central.env && set +a && /opt/central/.venv/bin/central-migrate --check'
 ```
 
 Exits 1 on drift. Resolve before proceeding.
 
+> **`central-migrate` env gotcha:** a bare `sudo -u central central-migrate` reads `.env` from the caller's cwd and the DB DSN is missing — it fails with `PermissionError: '.env'`. The systemd units supply it via `WorkingDirectory=/opt/central` + `EnvironmentFile=/etc/central/central.env`; manual calls must reproduce that with `cd /opt/central && set -a && . /etc/central/central.env && set +a && …` (the `central` user can read the env file). This wrapper is applied to every `central-migrate` invocation below.
+
 **3. Manual DB backup — REQUIRED before migrations (no automated backup exists):**
 
 ```bash
@@ -60,6 +62,12 @@ sudo -u central pg_dump -Fc central > /tmp/central-pre-<tag>.pgdump
 
 ## A. General deploy procedure
 
+> **Scripted path (preferred):** once `v0.14.6`+ is deployed, the repo ships `scripts/deploy.sh`, which automates everything below (pre-flight `pg_dump` to `/var/backups/central`, drift gate, fetch/checkout, `uv sync`, migrate, restart, verify, ERR-trap rollback guidance). Run:
+> ```bash
+> sudo /opt/central/scripts/deploy.sh v<NEW_TAG>      # add -y to skip the confirm prompt
+> ```
+> **Bootstrap caveat:** the script ships *inside* the repo, so the `v0.14.6` cutover that first introduces it must be done with the manual steps below; every deploy after that can use the script. The manual procedure remains the source of truth and the fallback.
+
 Run on CT 104 as `zvx`. Substitute `<NEW_TAG>` throughout.
 
 ```bash
@@ -72,16 +80,16 @@ sudo -u central git -C /opt/central checkout v<NEW_TAG>
 # 3. Sync venv from uv.lock (handles dep changes; editable install picks up code automatically)
 sudo -u central bash -c 'cd /opt/central && uv sync'
 
-# 4. Preview then apply migrations
+# 4. Preview then apply migrations (cd+env wrapper — see the env gotcha note above)
-sudo -u central /opt/central/.venv/bin/central-migrate --dry-run
+sudo -u central bash -c 'cd /opt/central && set -a && . /etc/central/central.env && set +a && /opt/central/.venv/bin/central-migrate --dry-run'
-sudo -u central /opt/central/.venv/bin/central-migrate
+sudo -u central bash -c 'cd /opt/central && set -a && . /etc/central/central.env && set +a && /opt/central/.venv/bin/central-migrate'
 
 # 5. Restart (nats/postgres assumed already up)
 sudo systemctl restart central-supervisor central-archive central-gui
 
 # 6. Verify
 systemctl is-active central-supervisor central-archive central-gui
-sudo -u central /opt/central/.venv/bin/central-migrate --check   # should be clean
+sudo -u central bash -c 'cd /opt/central && set -a && . /etc/central/central.env && set +a && /opt/central/.venv/bin/central-migrate --check'   # should be clean
 journalctl -u central-supervisor --since "2 min ago" --no-pager | tail -30
 curl -sS -o /dev/null -w '%{http_code}\n' http://localhost:8000/health   # expect 200
 ```
@@ -101,8 +109,9 @@ curl -sS -o /dev/null -w '%{http_code}\n' http://localhost:8000/health   # expec
 | #112 | Migration 036, version bump to 0.14.6, README | Only PR touching `pyproject.toml` — no collisions |
 | #113 | EONET `bypass_bbox_filter` flag + archive mirror | Code-only prerequisite for go-global |
 | #114 | Supervisor CPU: sat dedup + WAL `cursors.db` | Independent CPU fix |
+| #115 | `scripts/deploy.sh` + `scripts/README.md` | Deploy automation; no runtime effect |
 
-Review and merge all three into main.
+Review and merge all four into main.
 
 ### Step 2 — Cut and push the tag