Add deployment preflight and fix helium Syncthing root

deploy/production/README.md

@@ -48,13 +48,21 @@ the folder's normalized API-visible **path** as the override key (for example,
 Syncthing `~/Downloads/Sync` becomes `/var/syncthing/Downloads/Sync`); do not
 use the folder ID.
 
-Before starting a stack, validate it with:
+Before starting a stack, validate its config and then run the generic host
+preflight with that machine's own paths and container names:
 
 ```sh
 docker compose config
 docker compose run --rm archive-client --check-config
+python3 scripts/preflight-deployment.py --help
 ```
 
 The check is fail-fast and performs local permission, filesystem, sparse-file,
 hard-link, and reflink probes. Normal startup additionally probes the local
 qBittorrent and Syncthing APIs before registration.
+
+`scripts/preflight-deployment.py` is deliberately topology-agnostic: pass the
+host's `client.toml` and its client, qBittorrent, and Syncthing container names.
+It resolves Docker mounts rather than assuming project names or host paths. It
+also catches a common fatal error: a Syncthing `api_root` that names its config
+volume rather than the mounted shared-data tree.

deploy/production/helium/README.md

@@ -16,3 +16,19 @@ placements can hardlink rather than make a full copy.
 `/media/Data2/Downloading` already contains unrelated files. The fresh qB
 instance must not import or manage them; only Archive Control-created torrents
 are managed.
+
+Before the first client start, run the repository preflight on the target host
+(replace container names if that host uses different compose project names):
+
+```sh
+python3 scripts/preflight-deployment.py \
+  --client-config ~/Repositories/compose/ArchiveControl-archive/client.toml \
+  --client-container archive-control-helium-archive-client-1 \
+  --syncthing-container helium-syncthing-syncthing-1 \
+  --qbittorrent-container helium-qbittorrent-qbittorrent-1
+```
+
+It is read-only: it checks the configured API roots resolve to the same host
+paths as the client roots, that both data roots share one client bind mount for
+hardlinks, secret-file permissions, filesystem capabilities, and the local qB
+and Syncthing APIs. It does not send the control token or modify any container.

deploy/production/helium/client.toml

@@ -37,6 +37,6 @@ local_root = "/data/storage/Downloading"
 [syncthing]
 endpoint = "http://127.0.0.1:8384"
 api_key_file = "/run/secrets/syncthing_api_key"
-api_root = "/var/syncthing"
+api_root = "/var/syncthing/Sync"
 local_root = "/data/storage/Sync"
 advertised_addresses = ["dynamic"]