Automate host preparation and speed up game file downloads

docs/native-hosts.md

@@ -18,23 +18,39 @@ the agent owns local execution and its durable operation journal.
    installation, verifies the downloaded agent and updater SHA-256 over HTTPS,
    enrolls it and enables `electric-cherry-agent.service` and its automatic update
    timer. It needs no Git, Node.js or local build.
-4. In **Hosts**, prepare a Plutainer runtime image. In **Game Files**, select T5 or
-   T6 and upload your local game folder. Name the library and version and publish
+4. In **Game Files**, select T5 or T6 and upload your local game folder. Name the
+   library and version and publish
    it after the upload finishes. Include the DLC files in that folder; there is
    no separate DLC declaration. Uploading also works before enrolling any host.
-5. Cache the published version on each destination host. Wait for verification.
-   Hosts report connection and readiness separately; deployment also checks the
-   particular library, image, capacity and ports you selected. A connected host
-   missing content shows **Needs runtime** or **Needs game files**; these require
-   setup rather than waiting for an automatic preparation step. **Ready** means
-   it has both a runtime image and a verified library available.
+5. Hosts automatically prepare the configured Plutainer runtime and the latest
+   published version of every game library. **Automatic host setup** reports
+   progress and errors. Wait for verification before launching. Hosts report
+   connection and readiness separately; deployment also checks the particular
+   library, image, capacity and ports you selected.
 6. Launch a server or collection. Select the host, immutable game-file version(s)
-   and runtime image. EC selects lobby IDs and reserves UDP/TCP ports atomically.
+   and use the automatically selected default runtime, or an advanced override.
+   EC selects lobby IDs and reserves UDP/TCP ports atomically.
    Saved Plutonium server keys remain associated with their exact server names.
 
 A fresh destination host downloads centrally stored game files without manual
 copying or per-container setup. EC does not supply the game content itself.
 
+The controller reconciles automatic setup on agent heartbeats and operation
+polls. It first pulls `PLUTAINER_IMAGE` (default
+`ghcr.io/ayymoss/plutainer:latest`), then prepares the newest published version of
+each library, one setup operation at a time. Publishing more files or enrolling
+another host needs no manual propagation. Setup waits for an active, connected,
+healthy host with sufficient storage. Failed operations retry automatically with
+backoff from one minute to fifteen minutes; their errors remain visible in the
+host's setup panel and operation history. Disconnected hosts resume when they
+reconnect. Draining and disabled hosts do not receive new automatic setup work.
+
+Verified older versions remain cached and running servers keep their selected
+files and runtime. Automatic setup ensures that the configured image is present;
+it does not refresh an already cached mutable image tag. Advanced controls on the
+host and game-file pages can explicitly pull a custom runtime, prepare an older
+library version or retry preparation immediately.
+
 The default host root is `/var/lib/electric-cherry`; installer `--data-dir` changes
 it. Use a dedicated, root-owned directory. For a separate disk, use a child of its
 mount point (for example `/mnt/games/electric-cherry`), with no nested mounts, so
@@ -247,8 +263,12 @@ the page open while transferring. Once publication starts, the controller hashes
 every complete file and publishes the directory atomically; closing the browser
 does not stop that verification. An interrupted controller can retry publication.
 Published versions cannot be updated;
-changing files requires a new version. Hosts download with HTTP Range resumption,
-report progress, verify all checksums and atomically promote the complete cache.
+changing files requires a new version. Hosts download up to four files
+concurrently with HTTP Range resumption, report progress, verify all checksums
+and atomically promote the complete cache. Checksums are calculated while bytes
+arrive, avoiding another complete read of newly downloaded files. Resumed files
+include their saved prefix in verification. Progress reports are rate-limited so
+controller round trips do not stall every transferred chunk.
 Corrupt or incomplete content never becomes Ready. Cache inventory is reconciled
 on heartbeats, including vanished caches. Older immutable versions remain usable
 when their exact manifest is verified.