Add multi-server blueprint collections and atomic launches

docs/deployment-blueprints.md

@@ -1,12 +1,49 @@
 # Deployment blueprints
 
-The Deployments page is the starting point for reusable server launches. This
-release adds saved blueprints, launch previews, immutable managed-file recipes,
-launching again from history, and clearer progress and recovery.
+The Deployments page is the starting point for reusable server collections. A
+blueprint describes a whole lineup: for example, two Kino lobbies, one Moon lobby,
+and two Town lobbies, launched together from one preview.
+
+## Build and launch a collection
+
+1. Choose **Create blueprint** on Deployments and name the lineup.
+2. Add maps from Black Ops I or II and set the number of lobbies for each.
+3. Choose **Save & preview** to review every new server ID and game port.
+4. Enter each lobby's Plutonium key, or leave its field blank to reuse the key
+   saved for that exact server ID.
+5. Choose **Launch all N servers** and follow the collection progress page.
+
+Blueprints support up to 40 distinct game/map selections, 1–20 lobbies per map,
+and 100 servers total. The host's configured port range and existing fleet may
+allow fewer. A blueprint can be saved even when there is insufficient capacity
+to launch it. Each map captures its promoted managed files when added.
+
+Use **Edit** on a blueprint card to change its name, description, maps, or lobby
+counts. Existing map recipes are retained when their counts change; newly added
+maps capture their current promoted setup. Already reviewed launches keep their
+original lineup and file contents, including after blueprint edits or removal.
+Blueprints saved by the earlier single-server release load as one-server lineups
+and can be expanded directly.
+
+A collection preview does not reserve capacity. At submission, all lobby IDs,
+ports, and keys are validated again. The entire collection is then queued in one
+database transaction. If any server lacks a valid key or capacity has changed,
+no jobs, reservations, or key changes from that submission are committed. Refreshing
+the preview clears typed keys so they cannot be applied to changed server IDs.
+
+Submitting the same preview again returns the same collection, including after
+a lost response or an application restart. Reusing the blueprint with a new
+preview deliberately creates another collection with fresh available capacity.
+
+The worker provisions servers sequentially; health verification and failures are
+recorded separately for each. One failure does not undo servers already created
+or prevent the rest of the queued collection from being attempted. The collection
+page summarizes verified, active, and failed operations and links to every
+server's timeline and recovery options. Each child links back to its collection.
 
 ## Create and review a launch
 
-1. Choose **Create a server** on Deployments (or the deploy action on the fleet).
+1. Choose **Single server** on Deployments (or the deploy action on the fleet).
 2. Choose the current promoted setup and select a game/map, or select a blueprint.
 3. Choose **Preview launch**. Review the image reference, configuration sources,
    managed files and versions, selected map, lobby, port, and prerequisite checks.
@@ -31,12 +68,11 @@ Expand **Make this a reusable blueprint** in a launch preview and give it a name
 and optional description. You can save a recipe even when host configuration or
 available capacity blocks launching. Names are unique without regard to case.
 
-Blueprints retain the game, map variant, image reference, composed configuration
+Each map in a blueprint retains the game, map variant, image reference, composed configuration
 when available, generated map configuration, and matching promoted script/plugin
-bytes. Each blueprint is a saved recipe: saving another variation requires a new
-name. Credentials, lobby IDs, and ports are not copied from the source server.
+bytes. Credentials, lobby IDs, and ports are not copied from the source server.
 
-Use **Preview launch** on a blueprint card to assign fresh capacity. Remove a
+Use **Launch N servers** on a blueprint card to review fresh capacity. Remove a
 blueprint from the library when it is no longer needed; its existing servers,
 reviewed previews, and deployment history remain intact.
 
@@ -89,10 +125,20 @@ require inspection rather than replaying provisioning automatically.
 
 - `GET /api/blueprints`: list summaries.
 - `POST /api/blueprints`: save `{ name, description?, previewId }` or
-  `{ name, description?, deploymentId }`.
+  `{ name, description?, deploymentId }` for a single-server recipe, or
+  `{ name, description?, entries: [{ game, mapSlug, count }] }` for a collection.
+- `PUT /api/blueprints/:id`: edit `{ name, description?, entries }`. Unchanged
+  game/map selections keep their saved recipes.
 - `DELETE /api/blueprints/:id`: remove a library entry.
+- `POST /api/deployment-collections/preview`: preview `{ blueprintId }`.
+- `POST /api/deployment-collections`: atomically queue `{ previewId, keys? }`,
+  where `keys` maps exact preview server IDs to optional replacement keys.
+- `GET /api/deployment-collections`: list collection progress summaries.
+- `GET /api/deployment-collections/:id`: collection and per-server progress.
 - `POST /api/deployments/preview`: preview `{ game, mapSlug }`, `{ blueprintId }`,
-  or `{ deploymentId }`. Returns an ID, expiry, recipe summary, capacity, key
+  or `{ deploymentId }` for a single-server recipe. Multi-server blueprints must
+  use the collection endpoint; they cannot silently launch only one entry.
+  Returns an ID, expiry, recipe summary, capacity, key
   availability (never its value), and prerequisite checks.
 - `POST /api/servers`: existing request plus optional `previewId`; the game and
   map must match that preview. `expectedName` remains supported.
@@ -100,5 +146,5 @@ require inspection rather than replaying provisioning automatically.
   `canResumeVerification` for lifecycle operations.
 - `POST /api/deployments/:id/resume`: resume eligible creation health checks.
 
-Bulk collections, scheduled game nights, and beta-gated expansion are future
-layers; they are not activated by saving or launching a blueprint.
+Scheduled game nights and beta-gated expansion remain future layers. Collection
+launches begin processing immediately after all requests are queued.