docs(aws): document capacity routing

CHANGELOG.md

@@ -27,6 +27,7 @@
 
 ### Changed
 
+- Changed AWS capacity fallback to route configured `CRABBOX_CAPACITY_REGIONS` across both brokered and direct AWS launches, with the deployed coordinator defaulting to a wider multi-region pool for better headroom.
 - Changed the portal lease table to merge external Blacksmith Testbox runners into the main grid as muted, disabled rows instead of rendering a separate external-runners table.
 - Refactored built-in provider backend implementations into `internal/providers/<name>` packages while keeping command orchestration and rendering core-owned.
 

docs/features/aws.md

@@ -36,6 +36,17 @@ AWS Linux defaults to Spot. Use `--market on-demand` for one lease when Spot is
 blocked or when an account only has On-Demand quota. `capacity.fallback` can
 fall back to On-Demand after Spot capacity/quota failures when configured.
 
+Set `CRABBOX_CAPACITY_REGIONS` or `capacity.regions` to give AWS more regional
+headroom. Brokered and direct AWS launches try the primary region first, then
+the configured capacity regions in order. The public coordinator defaults to:
+
+```sh
+CRABBOX_CAPACITY_REGIONS=eu-west-1,eu-west-2,eu-central-1,us-east-1,us-west-2
+```
+
+Prefer `standard` or `fast` during capacity incidents. `beast` starts at
+48xlarge candidates and can consume 192 vCPUs per request before fallback.
+
 Crabbox tries ordered instance candidates for the requested class. Explicit
 `--type` is exact: if EC2 rejects it, Crabbox fails clearly instead of silently
 choosing another type.
@@ -91,6 +102,8 @@ CRABBOX_AWS_INSTANCE_PROFILE
 CRABBOX_AWS_ROOT_GB
 CRABBOX_AWS_SSH_CIDRS
 CRABBOX_AWS_MAC_HOST_ID
+CRABBOX_CAPACITY_REGIONS
+CRABBOX_CAPACITY_AVAILABILITY_ZONES
 ```
 
 ## Security And Networking

docs/performance.md

@@ -86,7 +86,7 @@ Typical choices:
 - `large`: broad test shards or heavy builds.
 - `beast`: high-core changed-test runs.
 
-Hetzner dedicated classes can hit account quota. AWS Spot classes can hit regional capacity or account policy limits. For AWS, class requests try the configured high-core candidates first and can fall back to a small burstable type when the account rejects those candidates. `CRABBOX_CAPACITY_STRATEGY=most-available` and multiple `CRABBOX_CAPACITY_REGIONS` give the coordinator more room to find capacity.
+Hetzner dedicated classes can hit account quota. AWS Spot classes can hit regional capacity or account policy limits. For AWS, class requests try the configured high-core candidates first and can fall back to a small burstable type when the account rejects those candidates. Multiple `CRABBOX_CAPACITY_REGIONS` let brokered and direct AWS launches move to another region before giving up.
 
 ## Measure The Loop
 

docs/providers/aws.md

@@ -26,8 +26,8 @@ already exists.
 ## Commands
 
 ```sh
-crabbox warmup --provider aws --class beast
-crabbox run --provider aws --class beast -- pnpm test
+crabbox warmup --provider aws --class standard
+crabbox run --provider aws --class fast -- pnpm test
 crabbox run --provider aws --market on-demand -- pnpm check
 crabbox warmup --provider aws --target windows --desktop
 crabbox warmup --provider aws --target windows --windows-mode wsl2
@@ -69,6 +69,8 @@ CRABBOX_AWS_INSTANCE_PROFILE
 CRABBOX_AWS_ROOT_GB
 CRABBOX_AWS_SSH_CIDRS
 CRABBOX_AWS_MAC_HOST_ID
+CRABBOX_CAPACITY_REGIONS
+CRABBOX_CAPACITY_AVAILABILITY_ZONES
 ```
 
 Brokered AWS credentials belong in the Worker, not on developer machines.
@@ -109,6 +111,9 @@ provider labels and `crabbox cleanup`.
 
 - Spot capacity and quota errors are normal. Prefer classes over exact `--type`
   when you want fallback.
+- During capacity pressure, prefer `standard` or `fast` plus multiple
+  `CRABBOX_CAPACITY_REGIONS`; `beast` starts at 48xlarge candidates and can
+  consume 192 vCPUs per request.
 - Windows WSL2 needs nested virtualization instance families.
 - EC2 Mac needs an explicit Dedicated Host id.
 - VNC stays behind SSH tunnels; do not expose VNC ports directly.

docs/troubleshooting.md

@@ -108,7 +108,8 @@ Fixes:
 
 - choose a smaller class;
 - use `--market on-demand` or `--market spot` for a one-off AWS capacity-market override;
-- set `CRABBOX_CAPACITY_REGIONS` for AWS Spot placement-score selection;
+- set `CRABBOX_CAPACITY_REGIONS` so brokered and direct AWS launches can try multiple regions;
+- set `CRABBOX_CAPACITY_AVAILABILITY_ZONES` only when you intentionally want a specific zone in those regions;
 - set `CRABBOX_CAPACITY_STRATEGY=most-available`;
 - raise the AWS `Running On-Demand Standard (A, C, D, H, I, M, R, T, Z) instances` quota for C/M/R/T/Z families, or the matching Spot quota when using Spot;
 - raise Hetzner dedicated-core quota when dedicated classes are required;

internal/cli/app.go

@@ -223,7 +223,7 @@ Environment:
   CRABBOX_AWS_SSH_CIDRS        Comma-separated AWS SSH source CIDRs
   CRABBOX_SSH_FALLBACK_PORTS   Comma-separated SSH fallback ports, or none
   CRABBOX_CAPACITY_MARKET      spot or on-demand
-  CRABBOX_CAPACITY_REGIONS     Comma-separated AWS Spot placement candidates
+  CRABBOX_CAPACITY_REGIONS     Comma-separated AWS region fallback candidates
   HCLOUD_TOKEN/HETZNER_TOKEN   Direct Hetzner mode
 
 Aliases: