Document git-checkout deploy workflow (replaces rsync)

CLAUDE.md

@@ -20,7 +20,8 @@ A FastAPI webhook server. One Mastodon admin webhook delivers `account.created`,
 | Where | What |
 |---|---|
 | Workstation | Source of truth: `~/yttrx-welcomebot/` (this repo) |
-| `admin.yttrx.com` | Deploy target: `/root/yttrx-welcomebot/`, Docker container `yttrx-welcomebot` on `127.0.0.1:8087`, nginx site `hooks` → `hooks.yttrx.com`. `ssh admin.yttrx.com` logs in as **root**. Compose is **`docker-compose` v1.29.2** (hyphenated, not `docker compose`). |
+| `git.blairhaus.net/yttrx-welcomebot.git` | `origin` remote (HTTP Basic Auth, `GIT_AUTH_USER`/`GIT_AUTH_PASS` in `~/docker/.env` on admin — same shared cred as every other git.blairhaus.net repo, embedded in the remote URL). No CI (`.ci/run.sh`) configured — deploy is a manual `git pull` on admin.yttrx.com, not push-triggered. |
+| `admin.yttrx.com` | Deploy target: `/root/yttrx-welcomebot/` is a **git checkout** of the above (converted from an rsync-deployed tree 2026-07-02), Docker container `yttrx-welcomebot` on `127.0.0.1:8087`, nginx site `hooks` → `hooks.yttrx.com`. `ssh admin.yttrx.com` logs in as **root**. Compose is **`docker-compose` v1.29.2** (hyphenated, not `docker compose`). |
 | `mammut` (`ssh mammut`) | The Mastodon instance. `tootctl`/Rails run inside the `live-web-1` container. Bot accounts + tokens live here. |
 
 Full ops history is in secondbrain `yttrx-documentation/changelog.md`; the
@@ -29,14 +30,20 @@ user-memory note `project_welcomebot` has the current state.
 ## HARD RULES
 
 - **Never overwrite the `.env` on `admin.yttrx.com`.** It holds the live
-  `WEBHOOK_SECRET`, `BOT_ACCESS_TOKEN`, and `ABUSE_BOT_TOKEN`. The local `.env`
+  `WEBHOOK_SECRET`, `BOT_ACCESS_TOKEN`, and `ABUSE_BOT_TOKEN`. It is untracked
-  has these blank. **Always rsync code only (`--exclude='.env'`)** and edit the
+  (gitignored) in the deploy checkout — `git pull`/`git reset` never touch it.
-  box's `.env` in place for new vars.
+  Edit it in place for new vars.
 - **Never commit secrets.** `.env` is git- and docker-ignored. Tokens/passwords
   must not land in this repo, the changelog, or CLAUDE.md.
 - The bot **silences** (reversible), it does not suspend by default
   (`ABUSE_ACTION=silence`). It applies the action **without** `report_id` so the
   report stays open for human review.
+- **`git` commands on admin.yttrx.com run as root** against a repo whose files
+  are `chown`ed to `waffles` (see below) — root's global config there already
+  has `safe.directory /root/yttrx-welcomebot` set to avoid the "dubious
+  ownership" error; don't need to re-add it, but if the repo is ever
+  reconstructed at that path from scratch, re-run
+  `git config --global --add safe.directory /root/yttrx-welcomebot`.
 
 ## Deploy procedure (workstation → admin.yttrx.com)
 
@@ -46,27 +53,32 @@ cd ~/yttrx-welcomebot
 python3 -m venv .venv && . .venv/bin/activate && pip install -q -r requirements.txt
 WEBHOOK_SECRET=testsecret BOT_ACCESS_TOKEN=x python test_local.py   # -> ALL TESTS PASSED
 
-# 2. Back up the live code + env on the box (date-stamp)
+# 2. Commit + push to origin (git.blairhaus.net)
-ssh admin.yttrx.com 'cd /root/yttrx-welcomebot && \
+git add -A && git commit -m "..."
-  cp app/main.py app/main.py.bak-$(date +%Y%m%d) && cp .env .env.bak-$(date +%Y%m%d)'
+git push origin main
 
-# 3. Rsync CODE ONLY (never the .env)
+# 3. Pull on admin.yttrx.com (.env is gitignored — untouched by pull/reset)
-rsync -az --exclude='.env' --exclude='.venv' --exclude='__pycache__' \
+ssh admin.yttrx.com 'cd /root/yttrx-welcomebot && git pull origin main'
-  --exclude='*.pyc' --exclude='*.db' --exclude='*.bak*' --exclude='.git' \
-  ~/yttrx-welcomebot/ admin.yttrx.com:/root/yttrx-welcomebot/
 
-# 4. Normalise ownership; keep .env root:root 600
+# 4. Re-normalise ownership if new files were added (chown is not tracked by git)
 ssh admin.yttrx.com 'cd /root/yttrx-welcomebot && chown -R waffles:waffles . && \
-  chown root:root .env .env.bak-* 2>/dev/null; chmod 600 .env .env.bak-* 2>/dev/null'
+  chown root:root .env; chmod 600 .env'
 
 # 5. If new env vars were added this release, set them IN PLACE on the box, e.g.
 ssh admin.yttrx.com 'cd /root/yttrx-welcomebot && \
   grep -q "^NEW_VAR=" .env || echo "NEW_VAR=value" >> .env'
 
-# 6. Rebuild + restart (named volume welcomebot-data persists the dedup db)
+# 6. Rebuild + restart (named volume welcomebot-data persists the dedup db;
+#    the volume name is derived from the directory basename, which is
+#    unchanged, so it survived the rsync -> git-checkout conversion)
 ssh admin.yttrx.com 'cd /root/yttrx-welcomebot && docker-compose up -d --build'
 ```
 
+Rollback is now `git checkout <previous-sha> -- .` (or `git revert`) instead of
+restoring `.bak` files — though `.env.bak-*`/`main.py.bak-*` from the
+pre-git-conversion deploys, and the full pre-conversion tree at
+`/root/yttrx-welcomebot.pre-git-*/`, are still on the box as a fallback.
+
 ### Verify
 
 ```bash