Add a start flag, and let --check survive a first deploy

-e start=false (mode sync in CI) lands the payload and starts nothing, for
migrations. A check run on a never-deployed stack now skips Compose with a note
instead of failing on the missing directory.

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

docs/architecture.md

@@ -76,6 +76,22 @@ Two properties follow, and both are load-bearing:
 - **An update run must be safe to repeat.** It is not transactional. Something
   will fail halfway through, and the fix is to run it again.
 
+## Starting is a flag too
+
+`start` is the same idea pointed at a different question. `pull` asks *which
+images*; `start` asks *whether to run Compose at all*. `-e start=false` lands the
+payload, creates the directories and the networks, and stops.
+
+The alternative — a one-off playbook that syncs and does not start, or a
+commented-out `roles:` block during a migration — is a copy of the real playbook
+that exists only while somebody is mid-task, which is exactly when a copy is most
+likely to be deployed by accident. A flag leaves one playbook, and leaves it
+honest.
+
+The role gates the Compose task itself rather than the `up.yml` include, because
+a two-phase playbook calls `tasks_from: up` directly and would otherwise slip
+past the flag.
+
 ## The `SSH_KEY_PATH` seam
 
 Ansible knows one thing about credentials: a path to a private key. One script

docs/ci-gitea.md

@@ -117,7 +117,7 @@ Actions → **deploy** → Run workflow. Three fields:
 | Field | Values | Meaning |
 | --- | --- | --- |
 | `stack` | the dropdown | Which playbook to run. `site` is all of them. |
-| `mode` | `check`, `deploy` | `check` runs `--check --diff` and touches nothing |
+| `mode` | `check`, `sync`, `deploy` | `check` runs `--check --diff` and touches nothing; `sync` copies the files for real but starts no container (`-e start=false`) |
 | `pull` | `policy`, `always`, `missing`, `never` | `always` fetches newer images **and** enables per-stack update work |
 
 Work up from harmless to real the first time:

docs/ci-github-actions.md

@@ -67,7 +67,7 @@ Actions → **deploy** → Run workflow. Three fields:
 | Field | Values | Meaning |
 | --- | --- | --- |
 | `stack` | the dropdown | Which playbook to run. `site` is all of them. |
-| `mode` | `check`, `deploy` | `check` runs `--check --diff` and touches nothing |
+| `mode` | `check`, `sync`, `deploy` | `check` runs `--check --diff` and touches nothing; `sync` copies the files for real but starts no container (`-e start=false`) |
 | `pull` | `policy`, `always`, `missing`, `never` | `always` fetches newer images **and** enables per-stack update work |
 
 Work up from harmless to real the first time:

docs/ci-gitlab.md

@@ -54,6 +54,10 @@ Pipelines → Run pipeline, add a variable) and press the same deploy button. Th
 also enables the work gated behind an update run — `webapp`'s backup and
 migration.
 
+To copy the files and start nothing — the `sync` mode of the other two
+platforms — run it with `START=false` instead. `true`, `false` and empty are the
+only values accepted.
+
 `ansible:ping` is the right first thing to run after setting the variables up. It
 should print `SUCCESS => {"ping": "pong"}` for every host, and changes nothing.