Clean up README and organize documentation

docs/guides/settings.md

@@ -0,0 +1,137 @@
+# Fleet settings
+
+Administration → Settings has independent **Concurrency** and **Retention**
+sections. Settings persist in SQLite, apply without restarting the controller,
+and are writable only by administrators. Saving one section preserves the other
+section's saved values. Upgrades preserve existing values and add new defaults.
+
+## Concurrency
+
+The existing fleet restart, startup and destruction limits default to 1. Additional
+limits default to 0 (no additional cap):
+
+- Restarts per host, including starts and rebuild recovery.
+- Startups per host, including creation and rebuilds.
+- Destructions per host, including migration source removal.
+- Combined lifecycle work across create/start/stop/restart/rebuild/destroy.
+- Rebuilds across the fleet, including host drain migrations.
+- Hosts downloading or verifying game files simultaneously, including manual imports.
+
+Limits are checked again before command submission after asynchronous preflight.
+Launch-file preparation reserves capacity. A lifecycle workflow counts once in the
+combined pool; unresolved commands and recovery keep capacity occupied. Migrations
+keep rebuild capacity through source removal and destination creation. Lower limits
+do not cancel admitted work. Game-file preparation slots are assigned on agent
+command delivery and survive interrupted transfers. Runtime pulls, the four file
+transfers per host and the two health probes per host remain unchanged.
+
+## Retention
+
+For age settings, 0 means no expiry. An explicit version-count policy can still
+expire unused artifact versions when their age policy is disabled. Game-file grace
+is a delay: 0 adds no delay. A positive age and version count together preserve the
+minimum count as well as versions younger than the age threshold.
+
+| History or storage | Default |
+| --- | --- |
+| Campaigns | 7 days |
+| Successful routine operations | 1 day |
+| Provisioning workflows | Indefinite |
+| Agent actions | Indefinite |
+| Explicitly resolved failures | Indefinite |
+| Non-update maintenance jobs | 30 days |
+| Resolved recovery incidents | Indefinite |
+| Host resource history | 7 days |
+| Instance resource samples | 1 day |
+| Fleet occupancy metrics | 31 days |
+| Telemetry diagnostics | 7 days; 200 per server; 10,000 overall |
+| Completed/interrupted matches | Indefinite |
+| Closed betas and test evidence | Indefinite |
+| Campaign file bodies and closed beta snapshots | 30 days |
+| Completed launch and command file bodies | 30 days |
+| Unused artifact versions | No automatic expiry; no minimum count |
+| Unused game files | No grace period; keep latest 1 version per game |
+| Incomplete browser uploads | Indefinite |
+| Authentication audit events | Indefinite |
+| Minimum history count | 0 additional records |
+
+Telemetry age and count policies are independent; 0 disables each individual cap.
+Diagnostic responses remain bounded to 10,000 rows when the per-server retention
+cap is disabled. Metric and capacity chart time ranges are unchanged; increasing
+storage retention does not automatically add new chart ranges. Capacity learning
+continues to use its 24-hour window independently of longer sample retention.
+
+### Cleanup and dependencies
+
+Background cleanup runs in bounded batches. New age policies for previously
+permanent history default to indefinite. Pending work, unresolved failures,
+recovery dependencies and explicitly protected records are never removed merely
+because they are old. Referenced artifact versions are retained, including versions
+referenced by historical campaigns and betas. Collection workflows with unfinished
+members, cancellation links and recovery slots can keep provisioning history longer
+than its configured age.
+
+Update attempts and dismissed watchdog incidents remain durable suppression evidence.
+Host setup, credential/decommission operations and referenced agent commands are
+protected. Expired unreferenced action history drops payloads, results and events
+but keeps compact terminal receipts and request fingerprints. Reusing an idempotency
+key cannot execute an expired command again. Agent mutation journals remain intact;
+this policy controls controller history, not the agent's execution recovery journal.
+
+### File bodies and match history
+
+Expiring campaign file bodies preserves file paths, hashes and summary records but
+makes file comparisons and rollback unavailable. The detail page identifies this
+state and rollback requests fail explicitly. Active beta rollback images stay
+protected. Expiring matches removes their player participation rows and changes
+leaderboard/player totals; lifetime aggregates are not retained separately.
+
+Completed launch recipes and command receipts also retain their metadata when
+their file bodies expire. Unfinished workflows, unreconciled commands, unresolved
+failures and explicit holds preserve the bytes they need. Shared file bytes are
+deleted only after their final reference expires; library versions can keep a file
+available longer. Previously saved retention choices are preserved on upgrade.
+
+### Database cleanup
+
+The database upgrade normalizes retention clocks to UTC and enables incremental
+vacuum. An existing database without a vacuum page map is rebuilt once at startup;
+allow time for this rebuild and free disk space up to twice the database size.
+The rebuild uses disk-backed temporary storage and a 16 MiB page cache instead
+of holding a temporary copy of the database in RAM. Container scratch files use
+`/data/.sqlite-tmp`; `[database]` startup logs identify the current migration.
+Normal cleanup releases unused file blobs in bounded batches and incrementally
+returns free pages to disk after larger prunes.
+
+### Game files and incomplete uploads
+
+Game-file minimums apply per game. Grace starts when a version is superseded.
+Live, stopped, rebuilding and provisioning instances pin their files; unresolved
+operations and offline host copies also prevent controller deletion. Controller
+cleanup still waits for every host to report its copy absent. Incomplete browser
+uploads expire based on their last activity, including resume checks; active chunk
+writes and publication hold locks against cleanup. Metadata remains after files
+expire. Raising retention cannot restore previously deleted bytes.
+
+### Preview and record protection
+
+Expand **Cleanup preview and protected records** to preview the values currently
+entered without saving them. Preview lists eligible records and known payload
+sizes; SQLite file space may be reused rather than immediately returned to the OS.
+Policies can overlap, so payload sizes should not be added together. Unknown row,
+index, upload and agent-disk overhead is not included.
+
+Use a record's ID from its detail URL or the preview to protect it. Protection can
+be removed in the same panel. Protecting a campaign or beta also protects its file
+bodies; protecting those bodies prevents deletion of their parent history.
+Game-file and incomplete-upload protections apply to storage cleanup.
+
+The minimum history count preserves recent records per history category. It does
+not apply to telemetry caps, metric/resource samples or game-file storage, which
+have their own policies. Explicit holds protect individual history/storage records,
+not individual resource samples or telemetry diagnostics.
+
+Failed campaigns, provisioning workflows and agent commands require explicit
+resolution before the resolved-failure period applies. Resolution does not bypass
+recovery/dependency checks. Resolving a failed campaign stops automatic campaign
+retry requests; it does not cancel commands already submitted.