ci: publish to pages from a pre-push hook

Pushing main now rebuilds the site and force-pushes dist/ to pages.

.agents/scripts/publish-pages.sh does the work. It never checks pages
out: it writes a tree straight from dist/ with write-tree and
commit-tree, so the working tree is untouched and a failure halfway
through leaves nothing behind. The commit is parented on the current
pages tip, so the branch keeps its history and a rollback is one
force-push to an earlier commit -- which the script prints before it
pushes.

It refuses to publish when the working tree is dirty, when HEAD is not
main, when HEAD is not the commit being pushed, or when any of the ten
routes is missing or empty in dist/. A build can succeed and still emit a
stub; that is exactly how this site would go down.

The hook guards three ways. AF_PUBLISHING short-circuits it so the
publisher's own push does not re-enter it forever. AF_NO_PUBLISH=1 lets
you push main without publishing. And because git has no post-push hook,
the publish necessarily runs before main lands -- so it first checks that
the remote tip is an ancestor of what is being pushed, and skips
publishing when the push could still be rejected as a non-fast-forward.

Also rewrites the operations guide's rollback section, which still
described merging main into pages with --ff-only. That has not been true
since pages started carrying build output.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/operations-guide.md

@@ -53,11 +53,21 @@ migration task.
 flowchart LR
   E[Edit main] --> V[pnpm run gate]
   V --> C[Commit]
-  C --> P[Push main]
-  P --> G[Gitea Actions: gate]
-  G -.manual dispatch.-> B[Build + force-push dist to pages]
+  C --> P[git push main]
+  P --> H[pre-push hook: gate, then publish-pages.sh]
+  H --> B[Build + force-push dist to pages]
   B --> S[Gitea Pages Server]
   S --> L[Live URL]
+  P -.also.-> G[Gitea Actions: gate]
+  G -.manual dispatch.-> B
+```
+
+**A push of `main` republishes the live site.** The `pre-push` hook runs the
+gate and then `.agents/scripts/publish-pages.sh`. There is no staging step
+between your push and visitors. To push without publishing:
+
+```bash
+AF_NO_PUBLISH=1 git push
 ```
 
 ### 1. Start from current `main`
@@ -69,9 +79,7 @@ git pull --ff-only
 git status --short --branch
 ```
 
-Do not overwrite unrelated local changes. The untracked `scripts/inspect.py` and
-`scripts/__pycache__/` are local visual-test artifacts and are intentionally not
-part of the published site.
+Do not overwrite unrelated local changes.
 
 ### 2. Preview locally
 
@@ -518,23 +526,39 @@ together when the underlying interview workflow changes.
 
 ## Safe rollback
 
-Prefer a normal revert so history and the `pages` branch remain
-fast-forwardable:
+`pages` holds build output, not a copy of `main`, so it is not merged into or
+fast-forwarded from `main`. Rolling the _site_ back and rolling the _source_
+back are two separate actions.
+
+**Roll the live site back immediately**, without touching `main`. The publisher
+prints the rollback command every time it runs; `pages` keeps its history, so
+any previous tip works:
+
+```bash
+git fetch origin pages
+git log --oneline origin/pages | head        # pick the tip you want back
+git push --force origin <SHA>:refs/heads/pages
+```
+
+`pages-backup-2026-09-06` (`37a1e48`) is the last commit of the hand-written
+site, kept as a floor under every rollback.
+
+Confirm with a cache-buster — a stale cached 200 looks exactly like success:
+
+```bash
+curl -sS -o /dev/null -w '%{http_code}\n' \
+  "https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/?v=$(date +%s)"
+```
+
+**Then fix the source.** Revert on `main` and push; the pre-push hook rebuilds
+and republishes, which is what makes the site and the source agree again:
 
 ```bash
 git switch main
 git revert BAD_COMMIT
 git push origin main
-git worktree add /tmp/ai-for-dummies-pages pages
-git -C /tmp/ai-for-dummies-pages merge --ff-only origin/pages   # local pages is often stale
-git -C /tmp/ai-for-dummies-pages merge --no-edit main
-git -C /tmp/ai-for-dummies-pages push origin pages
-git worktree remove /tmp/ai-for-dummies-pages
 ```
 
-Verify the live URL after rollback. Do not use `reset --hard` or force-push for
-ordinary content recovery.
-
 ## Completion checklist
 
 - [ ] English content is complete without JavaScript.