Add deployment blueprints and reviewed launch recipes

docs/deployment-blueprints.md

@@ -0,0 +1,104 @@
+# 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.
+
+## Create and review a launch
+
+1. Choose **Create a 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.
+4. Enter the Plutonium key for the displayed server ID, or reuse its saved key.
+5. Choose **Launch server** and follow the operation to verified health.
+
+A preview lasts 30 minutes. It neither reserves capacity nor saves a key. If
+another launch takes the lobby or port, submission stops before saving the key;
+refresh the preview and review the newly assigned ID. Refreshing a preview clears
+the typed key so it cannot accidentally be saved against a different lobby.
+
+Komodo connection settings, target host, RCON configuration, config filename,
+lobby availability, and port availability are checked locally. These checks do
+not probe the host or verify game/DLC files, images, Docker volumes, firewall
+rules, or credentials. Container and RCON verification happen after provisioning.
+T6 variants retain their exact catalog slug and launch ruleset; RCON health checks
+verify the engine map, not the variant's start location.
+
+## Save and reuse a blueprint
+
+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
+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.
+
+Use **Preview launch** on a blueprint card to assign fresh capacity. Remove a
+blueprint from the library when it is no longer needed; its existing servers,
+reviewed previews, and deployment history remain intact.
+
+On a creation detail page, **Launch again** opens its original recipe with the
+next available lobby and port. This reproduces the original managed launch files,
+not the server's later live state. The preview also lets you save that historical
+recipe as a blueprint. Older deployments without a recipe retain their history
+but cannot offer this action.
+
+## What is frozen
+
+The exact managed file bytes, file hashes, version metadata, composed config,
+selected map, and image reference are stored in SQLite. Promotion or deletion of
+an artifact after preview cannot change those bytes. A submitted preview is bound
+to one deployment: retrying the same submission returns the original operation,
+including after an application restart or a lost HTTP response.
+
+Existing API clients that omit a preview still work. Their recipes are captured
+when queued, before provisioning begins. Queued jobs from before this update use
+the promoted setup at provisioning time because they have no recorded recipe.
+
+This is a launch snapshot, not a permanent version lock. Subsequent campaigns,
+betas, and drift reconciliation continue to follow the server's game/map scopes.
+Container tags can resolve to newer images; use a digest for a fixed image.
+Without a promoted baseline, Plutainer seeds its own defaults on first boot,
+which are not captured. Host, network, game-file volumes, destination directories,
+and RCON/Plutonium credentials use the environment and key store at launch time.
+A changed main config filename blocks reuse rather than silently loading the
+wrong configuration.
+
+Recipes do not include the separately stored Plutonium or integration credentials.
+Managed files can themselves contain sensitive configuration, so protect database
+backups as you would the existing artifact library and saved-key database. Public
+recipe responses contain file metadata and hashes, not file contents.
+
+## Progress and interrupted operations
+
+Creation verifies container health, then RCON, then the selected engine map.
+The detail page explains the current condition, displays elapsed time, and keeps
+its activity history. A completed container start is not reported as a completed
+server launch until the health checks pass.
+
+For failed or interrupted creations, **Resume health verification** appears only
+when the original server is still registered on its assigned port and no later
+lifecycle operation has targeted that ID. It resumes observation only; it never
+recreates or restarts a container. Missing servers and later destruction attempts
+require inspection rather than replaying provisioning automatically.
+
+## API
+
+- `GET /api/blueprints`: list summaries.
+- `POST /api/blueprints`: save `{ name, description?, previewId }` or
+  `{ name, description?, deploymentId }`.
+- `DELETE /api/blueprints/:id`: remove a library entry.
+- `POST /api/deployments/preview`: preview `{ game, mapSlug }`, `{ blueprintId }`,
+  or `{ deploymentId }`. 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.
+- `GET /api/deployments/:id`: includes `recipe`, `blueprintName`, and
+  `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.