docs site: add push-to-main polling deployer (agent host)

The agent host's cloud firewall only admits inbound SSH, so the registered
Gitea webhook cannot reach the receiver. docs-deploy-poll.service polls
Gitea every 60s over outbound HTTPS and deploys whenever main moves; the
webhook stays wired for the moment a port is opened in the Infomaniak panel.
Both serialise on the same deploy lock.

publishing/README.md

@@ -16,6 +16,8 @@ repository root.
 | `logo.svg` | Co-op logo (shared with the website repo) |
 | `build.sh` | Stage the Markdown into `.site-src/`, render to `.site-build/` |
 | `deploy.sh` | Push the build into the Surfer app container |
+| `poll-watcher.sh` | Polls Gitea main every 60s; deploys on change (agent host) |
+| `docs-deploy-poll.service` | systemd unit for the poller |
 | `webhook-receiver.py` | Gitea webhook → pull → build → deploy (agent host) |
 | `webhook-receiver.service` | systemd unit for the receiver |
 | `requirements.txt` | Pinned Python build toolchain |
@@ -48,21 +50,31 @@ canonical one.
 
 ## Automatic rebuilds (push to main)
 
-A push to `main` on `co-op/docs` fires a Gitea webhook (repo settings →
-webhooks) to the receiver on the agent host, which pulls, rebuilds and
-redeploys. On the agent host:
+Two mechanisms keep the site in step with `main`; both run on the agent host
+and neither adds a Cloudron app.
+
+**Polling (running now).** `docs-deploy-poll.service` polls Gitea every 60
+seconds and deploys whenever `main` moves. A push appears on the site within
+about a minute, with no human action. The Gitea webhook alone was not enough
+because the agent host's cloud firewall only admits inbound SSH — a webhook
+POST is silently dropped — while outbound access to Gitea works.
+
+**Webhook (wired, waiting on one port).** A Gitea webhook is registered on
+`co-op/docs` (push events, branch `main`) pointing at the receiver below. The
+moment the Infomaniak panel allows inbound TCP to the agent host — port 8787
+from the Cloudron box 179.237.86.116 is enough — start the receiver and pushes
+deploy instantly instead of within a minute:
 
 ```sh
-sudo cp publishing/webhook-receiver.service /etc/systemd/system/docs-deploy-webhook.service
-sudo systemctl daemon-reload && sudo systemctl enable --now docs-deploy-webhook
-tail -f /home/ubuntu/docs-deploy.log        # what the receiver is doing
+sudo systemctl enable --now docs-deploy-webhook
+tail -f /home/ubuntu/docs-deploy.log        # what both mechanisms are doing
 ```
 
 The receiver authenticates webhooks with an HMAC-SHA256 shared secret
 (`DEPLOY_WEBHOOK_SECRET` in the agent host's env file) and only accepts pushes
 to `main` of `co-op/docs` from the Cloudron box. Woodpecker CI (Cloudron
 catalog) could do the same job inside Cloudron, at the cost of running another
-app; the receiver was chosen because it adds no new Cloudron app.
+app; the agent-host mechanisms were chosen because they add no new Cloudron app.
 
 Each deploy writes `meta.json` into the site with the commit it was built
 from, so a deploy can be verified from the served site itself: