From d663f1eeb5603c7f35e654311331b3c45ceca5d7 Mon Sep 17 00:00:00 2001
From: Torres <torres@mackwnox.ca>
Date: Thu, 12 Nov 2026 09:59:45 -0400
Subject: [PATCH] =?UTF-8?q?deploy:=20P4=20runbook=20=E2=80=94=20deploy/rol?=
 =?UTF-8?q?lback/logs/import=20gating/backup-restore=20drill/phone=20check?=
 =?UTF-8?q?list=20+=20one-time=20sidecar=20key=20step?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/DESIGN.md | 27 +++++++++++++++++++++++++--
 1 file changed, 25 insertions(+), 2 deletions(-)

diff --git a/docs/DESIGN.md b/docs/DESIGN.md
index 6ec034a..752bb74 100644
--- a/docs/DESIGN.md
+++ b/docs/DESIGN.md
@@ -116,6 +116,29 @@ data/           runtime state (gitignored)
 docs/           this design set
 ```
 
-## Runbook (completed at Phase 4)
+## Runbook (Phase 4)
 
-Deploy / update / rollback steps, log locations, import troubleshooting (gates), backup-restore drill, phone verification checklist.
+**Stack home:** `/var/mnt/DATA/podman-stacks/bike-tinder/` — a checkout of the `release` branch, plus stack-local `data/` (DB + image mirror + backups), `.env` (secrets, never committed) and `tailscale-state/` (node identity). Unit: `podman-stack-bike-tinder.service` (installed from `deploy/`).
+
+**Deploy / update a cut:**
+
+```sh
+# from the repo: merge dev -> main, then fast-forward release
+git -C /var/mnt/DATA/podman-stacks/bike-tinder pull --ff-only
+podman-compose -f deploy/docker-compose.yml --env-file .env build
+systemctl --user restart podman-stack-bike-tinder.service
+```
+
+Docs-only cuts stop after the `pull`. The unit is `oneshot` + `RemainAfterExit` with `Delegate=yes`, so the stack survives `hermes gateway restart` and reboots. The historical dev service (`bike-tinder-dev.service`) is retired at deploy; rollback happens through the stack, not that unit.
+
+**Rollback:** check out the previous release SHA in the stack dir, rebuild, restart. The DB is never touched by code rollbacks (migrations are guarded and idempotent); if a migration ever needs unwinding, restore the last backup (below).
+
+**Logs:** `podman logs bike-tinder-app`, `podman logs bike-tinder-ts`, `journalctl --user -u podman-stack-bike-tinder.service`.
+
+**Import troubleshooting:** `POST /api/import` refuses when the hunt state is older than 26 h or missing — check `~/.hermes/scripts/motorcycle-hunt.d/*.json`. The nightly chain is the Hermes cron job `bike-tinder-import` (08:30 Atlantic: import → agent read → DB backup); it is silent on success by design — inspect its last run in the cron list if a morning looks stale. The container also runs an on-boot catch-up import when the last run is >26 h old.
+
+**Backups:** nightly `data/backup/bike-tinder-YYYYMMDD-HHMM.sqlite3`, last 14 kept. Restore drill: stop the unit → remove `data/bike-tinder.sqlite3-wal`/`-shm` → copy the chosen backup over `data/bike-tinder.sqlite3` → start the unit → check `GET /api/stats`.
+
+**Phone checklist:** open `https://biketinder.tailf35a34.ts.net` from a tailnet device → expect the deck; Add to Home Screen (PWA installs via the manifest); swipe once and confirm the decision shows in List. If the URL fails: check the sidecar (`podman logs bike-tinder-ts`), confirm `TS_AUTHKEY` in `.env`, and re-run `podman-compose -f deploy/docker-compose.yml --env-file .env up -d`.
+
+**First-run sidecar (one-time):** mint a Tailscale auth key (admin console → Settings → Keys), put `TS_AUTHKEY=<key>` into the stack `.env`, then `podman-compose -f deploy/docker-compose.yml --env-file .env up -d tailscale`.