Fix sidecar: advance refs/heads/main after each commit

post-receive uses `git checkout -f <SHA>` which detaches HEAD in the bare
repo. Without this fix, sidecar commits advance the detached HEAD but not
refs/heads/main and are orphaned on the next push.

Also commits CLAUDE.md docs update and the retry-loop sync-vps.sh.

scripts/sync-vps.sh

@@ -1,5 +1,8 @@
 #!/usr/bin/env bash
 # Pull web-edit commits from VPS, then push everything back.
+# Retries the container push (up to 3x) if a VPS web-edit landed between
+# our pull and push — receive.denyNonFastForwards is enabled on the bare repo
+# so those races are rejected rather than silently dropped.
 # Usage: bash scripts/sync-vps.sh
 set -e
 cd "$(dirname "$0")/.."
@@ -11,6 +14,16 @@ echo "==> Pushing site submodule to VPS..."
 (cd site && git push vps main)
 
 echo "==> Pushing container repo to VPS..."
-git push vps main
+for attempt in 1 2 3; do
+    if git push vps main; then
+        break
+    elif [ $attempt -lt 3 ]; then
+        echo "    Push rejected — VPS has new commits, pulling and retrying (attempt $attempt)..."
+        git pull --rebase --autostash vps main
+    else
+        echo "    Push failed after 3 attempts — run sync-vps.sh again manually."
+        exit 1
+    fi
+done
 
 echo "==> Done."