docs: fix multi-server fanout review findings

Documentation fixes from the final branch review, plus small curl/jq
hardening in the gitea-action script:

- tag was documented as cosmetic ("for logging") but is load-bearing in
  swarm mode: handlers.go folds it into the requested image, compose
  discovery strips it via NormaliseImage, but SwarmExecutor assigns it
  directly to ContainerSpec.Image. Omitting it deploys :latest, silently
  diverging from what CI just built. Fixed in action.yml, gitea-action's
  README, and added to CLAUDE.md's Gotchas since it's invisible from
  either mode's code alone.
- gitea-action/README.md's opening line and root README.md's intro/trigger
  flow described compose-only behavior even though both docs' bodies now
  cover swarm mode too.
- README.md's defense-in-depth section described a two-factor gate; compose
  mode is actually three factors (token, label, STACKS_ROOT prefix), and
  swarm mode is genuinely two (no local compose file to path-check against).
- action.yml: curl now has --connect-timeout 10 --max-time 900 so a host
  that accepts TCP but never answers can't block the fan-out loop forever;
  the jq payload build now fails loudly instead of silently sending an
  empty payload to every endpoint.
- CLAUDE.md References section now lists this branch's spec and plan.

Claude-Session: https://claude.ai/code/session_01S3aqJ4tvaPezQhsGNCybut

gitea-action/README.md

@@ -1,6 +1,6 @@
 # Deploy via package-updater (composite action)
 
-Notifies `package-updater` to `docker compose pull` + `up -d` for the matching service(s) after a CI build.
+Notifies one or more `package-updater` instances to update the matching service(s) after a CI build. Each instance does whatever its own `MODE` dictates — `docker compose pull` + `up -d`, or `docker service update` for swarm.
 
 ## Usage
 
@@ -34,7 +34,7 @@ input is sent to every endpoint.
 |---|---|---|---|
 | `endpoint` | yes | — | Full URL to `/update`. Several may be given, one per line, to update a fleet. |
 | `image` | yes | — | Image reference without tag |
-| `tag` | no | `""` | Tag that was just pushed (logged for audit) |
+| `tag` | no | `""` | Tag that was just pushed. Compose mode ignores it (the compose file pins the reference); **swarm mode sets the service image to it**, so omitting it deploys `:latest`. Always pass it. |
 | `token` | yes | — | Bearer token configured in package-updater |
 
 ## Failure modes
@@ -46,3 +46,7 @@ which hosts actually succeeded.
 The step exits non-zero if any endpoint returned 4xx/5xx or was unreachable. The
 log lists each endpoint with its HTTP status and response body, so a partial
 deploy is visible at a glance.
+
+Endpoints are contacted sequentially, so worst-case wall time is the number of endpoints times
+how long one update takes. Each request allows 10s to connect and 15 minutes to complete —
+`/update` is synchronous and waits for the deploy to finish.

gitea-action/action.yml

@@ -8,7 +8,7 @@ inputs:
     description: "Image reference without tag (e.g. registry.example.com/myapp)"
     required: true
   tag:
-    description: "Tag that was just pushed (for logging)"
+    description: "Tag that was just pushed. Required in practice for swarm instances — it becomes the image the service is set to. Omit it and swarm deploys :latest."
     required: false
     default: ""
   token:
@@ -31,7 +31,7 @@ runs:
         set -uo pipefail
 
         payload=$(jq -nc --arg image "$IMAGE" --arg tag "$TAG" \
-          '{image: $image, tag: $tag}')
+          '{image: $image, tag: $tag}') || { echo "jq is required but failed"; exit 1; }
 
         attempted=0
         failed=0
@@ -46,6 +46,7 @@ runs:
           echo "--- $endpoint"
 
           if ! response=$(curl -sS -w "\n%{http_code}" \
+            --connect-timeout 10 --max-time 900 \
             -X POST "$endpoint" \
             -H "Authorization: Bearer $TOKEN" \
             -H "Content-Type: application/json" \