Support multi-game betas with automatic server selection

docs/guides/beta-test-plans.md

@@ -1,9 +1,42 @@
 # Beta test plans
 
-Create a plan in Betas, choose its servers, and deploy. The server's game script
+Create a plan in Betas, choose how many instances per game must pass, and deploy. The server's game script
 reports gameplay to Electric Cherry. The same reports update Fleet and any active
 beta on that server.
 
+## Files and automatic server selection
+
+A beta can bundle files for different games, including T5 and T6 together. Each
+file installs only on participants matching its game or map scope; an unscoped
+file applies to all participants. Every file needs at least one matching test
+participant. For example, a T5 script and a T6 script can share one beta without
+either script being installed on the other game's servers.
+
+Setup defaults to automatic selection with one instance per applicable game.
+Choose the number that must pass for each game. Every automatically selected
+instance must pass every requirement in the plan. Set a game's count to zero to
+omit it only when every selected file still has a matching participant.
+
+When you choose **Start beta**, Electric Cherry chooses compatible servers with
+the fewest current players, while ensuring that every file is tested. Counts
+are exact: requesting two T5 and three T6 instances selects five participants,
+and all five must pass. Server choices are made at launch, so review shows the
+requested counts rather than a provisional list of server names.
+
+Automatic selection requires fresh player observations and available running
+servers. Servers held by another active beta or with pending deployment work
+are excluded, as are instances on unavailable, draining, or disabled hosts.
+Unknown or stale player counts are not treated as empty. If the
+requested counts cannot be met, including coverage of every selected map-scoped
+file, the beta does not start. Deployment and restarts still wait for confirmed
+empty lobbies and restart capacity.
+
+Open **Advanced options → Choose specific servers** for manual selection. The
+picker includes servers matching any file in the bundle; each file must have a
+matching selected server. Manual selection retains the configurable coverage
+rules below. Drafts preserve the selection mode and counts, and older drafts
+with explicit server choices resume in manual mode.
+
 ## Game reporter protocol
 
 Set `EC_TELEMETRY_TOKEN` on the Electric Cherry controller to a dedicated random
@@ -209,9 +242,11 @@ Health intervals spanning more than 60 seconds earn no healthy time.
 
 ## Coverage, waves and outcomes
 
-Coverage can require all selected servers, a quorum, one per selected map,
+Automatic selection requires all requested instances to pass. With manual server
+selection, coverage can require all selected servers, a quorum, one per selected map,
 one per selected game, or one per selected game/map combination. Coverage
-metadata is pinned when the beta opens.
+metadata is pinned when the beta opens. Every bundled file also needs at least
+one passing server that received it; a quorum cannot skip testing a game's file.
 
 Set wave size to 1 for a canary, a larger number for batches, or 0 for all
 selected servers. Later waves receive files after the previous waves pass.
@@ -288,7 +323,13 @@ changing the policy still requires a new beta.
 
 ## API and storage
 
-`POST /api/betas` accepts `testPlan`.
+`POST /api/betas` accepts `scripts`, `testPlan`, and either
+`instancesPerGame` (for example, `{ "t5": 2, "t6": 3 }`) for automatic selection
+or `servers` with explicit registered server names for manual selection. Submit
+only positive integer counts in `instancesPerGame`; omit games set to zero in
+the UI. Automatic selection sets the plan's coverage `scope` to `all`.
+Do not send both selection forms. File scopes determine which bundle files each
+participant receives in both modes.
 `GET /api/betas/:id` includes the plan, outcome, per-server progress, and
 recent evidence under `test`.