@crvouga/atlas 0.17.0 → 1.0.0

package/llms-full.txt

@@ -153,7 +153,7 @@ workspace selection and test scripts. An existing `atlas.yml` not generated by A
 workflows may still need manual integration. Non-JavaScript suites need their language/tool setup in CI.
 
 Without a server, start with [local verification](quickstart.md). To run a server later, `atlas serve`
-starts one (`http://127.0.0.1:8080`, data in `./atlas-data`); [the server guide](server.md) covers configuration
+starts one (`http://127.0.0.1:8080`; it needs S3-compatible storage configured with the `ATLAS_S3_*` variables, see `.env.example`); [the server guide](server.md) covers configuration
 and authentication. Keep synthetic failure checks in a scratch store rather than a shared production report.
 
 ## What an agent can rely on
@@ -979,7 +979,7 @@ Playwright, Vitest, Bun, WebDriver/Appium and Detox already have Atlas statechar
 
 ## Operate the singleton
 
-Run `atlas server` once for the projects the node hosts; point local and CI publishers at that URL and set each project's `ATLAS_PROJECT`. Configure backends using environment variables or open **Settings** in the client (`/admin`). Authentication and listening addresses remain deployment configuration. Settings changes are validated and saved atomically for the next server restart. Environment variables and flags override saved values. A backend change does not migrate historical data: retain the old backend as a read source when switching the upload destination.
+Run `atlas server` once for the projects the node hosts; point local and CI publishers at that URL and set each project's `ATLAS_PROJECT`. The node keeps everything in the S3 bucket named by the required `ATLAS_S3_*` variables ([required S3 storage](server.md#required-s3-storage)); open **Settings** in the client (`/admin`) to define the garbage collection policy and report settings, which are saved as JSON in that bucket. Authentication, listening addresses and storage remain deployment configuration. Settings changes are validated and saved for the next server restart. Environment variables and flags override saved values.
 
 Native reporters send a heartbeat every 5 seconds. The server interrupts invocations after 30 seconds of silence, or after the configurable progress-stall timeout. It preserves finished results and never marks missing tests as passed. See [live test runs](server.md#live-test-runs-and-heartbeats).
 </doc>
@@ -1254,22 +1254,24 @@ development and in production.
   CI job ──────┼── PUT /api/store/…  POST /api/checks ─▶│
   device lab ──┘   atlas report publish | stream        │   atlas report status  (the gate: asks /api/status)
                                                         │
-                       backends: ./atlas-data (default), S3, other folders, another Atlas server
+                       one S3-compatible bucket: ALL reports and ALL user state (required)
 ```
 
 - **Clients upload directly to it.** `atlas report publish`, `atlas report stream`, `createReporter` and a plain
   `curl` all end up as layers on the server. Nothing else needs deploying: no bucket access for CI, no artifact
   merging, no static site to rebuild.
-- **Its default backend is its own filesystem** (`./atlas-data`). That folder is the whole state: back it up,
-  mount it on a volume, or put the state in a bucket instead ([backends](#backends)). Several backends are one
-  report, as ever.
+- **Its only storage is an S3-compatible bucket.** All reports and all user state (the garbage collection policy,
+  saved settings) live there and nowhere else: not on its disk, in memory, in a database or in the browser. The
+  storage settings are required and the server refuses to start without them
+  ([required S3 storage](#required-s3-storage)).
 - **The report is live.** Every client holds one server-sent-events connection; when results arrive the server
   says so and each client reads only what changed ([streaming](#streaming)).
 - **Layered, never partitioned**, as everywhere in Atlas: the server only stores immutable, content-addressed
   layers and works out the report from them. Replace it, restore it, or run a second one on a copy of the data:
   the same layers give the same report ([the contract](report-contract.md)).
 
-- [Run it](#run-it) · [Configuration](#configuration) · [Backends](#backends) · [Tokens and roles](#tokens-and-roles)
+- [Run it](#run-it) · [Required S3 storage](#required-s3-storage) · [User state and garbage collection](#user-state-and-garbage-collection)
+- [Configuration](#configuration) · [Storage](#storage) · [Tokens and roles](#tokens-and-roles)
 - [Sending results](#sending-results) · [Streaming](#streaming) · [API reference](#api-reference)
 - [What the server refuses](#what-the-server-refuses) · [Performance](#performance) · [Operating it](#operating-it)
 
@@ -1278,7 +1280,8 @@ development and in production.
 ```sh
 bun add -d @crvouga/atlas
 export ATLAS_TOKEN=$(openssl rand -hex 24)   # admin token; see "Tokens and roles"
-bunx atlas serve                             # http://127.0.0.1:8080, data in ./atlas-data
+cp .env.example .env                         # then fill in the ATLAS_S3_* variables: storage is required
+bunx atlas serve                             # http://127.0.0.1:8080, everything kept in your S3 bucket
 ```
 
 <!-- generated:runtime-requirements -->
@@ -1294,21 +1297,118 @@ server in front of it. Vite proxies `/api` (server-sent events included) to the
 uploaders and the client all use **one host**, exactly as in production, and a change to the client shows at once.
 
 ```sh
-bunx atlas dev --data .atlas-data            # http://127.0.0.1:5180
+bunx atlas dev                               # http://127.0.0.1:5180 (same ATLAS_S3_* variables)
 ATLAS_STORE=http://127.0.0.1:5180 bunx atlas report publish --producer unit --junit out.xml
 ```
 
 For Railway, deploy `ghcr.io/crvouga/atlas:latest` directly: the image contains the server and
 viewer, and every green `main` push updates it. See [running Atlas for a project](deploying.md#run-it) for
-Railway's volume, tokens, healthcheck and image auto updates, or for Docker, Kubernetes and CI.
+Railway's variables, tokens, healthcheck and image auto updates, or for Docker, Kubernetes and CI.
 For anonymous reading, uploads and administration, use `ghcr.io/crvouga/atlas-insecure:latest` with no tokens
 configured; see [deploying without authentication](deploying.md#deploy-without-authentication).
 
+## Required S3 storage
+
+The server keeps **all reports and all user state in S3-compatible object storage, and nowhere else**. There is no
+local-disk, in-memory or database fallback and no flag to choose another place, so the storage settings are
+**required environment variables with no defaults** (they hold secrets, so they are never read from a file or a flag):
+
+| Variable | Required | Meaning |
+| --- | --- | --- |
+| `ATLAS_S3_ENDPOINT` | yes | S3 API endpoint, e.g. `https://s3.eu-west-1.amazonaws.com`, `https://<account>.r2.cloudflarestorage.com`, `http://minio:9000` |
+| `ATLAS_S3_BUCKET` | yes | Bucket for reports and user state. It must already exist |
+| `ATLAS_S3_REGION` | yes | Bucket region (`auto` for Cloudflare R2, `us-east-1` for most self-hosted servers) |
+| `ATLAS_S3_ACCESS_KEY_ID` | yes | Access key of an account that may list, read, write and delete in the bucket and prefix |
+| `ATLAS_S3_SECRET_ACCESS_KEY` | yes | Its secret key |
+| `ATLAS_S3_PREFIX` | no | A folder inside the bucket for everything Atlas writes. Default: the bucket root |
+| `ATLAS_S3_PATH_STYLE` | no | `1` (default) for `endpoint/bucket/key`, `0` for virtual-hosted `bucket.endpoint/key` |
+| `ATLAS_S3_SESSION_TOKEN` | no | Only for temporary credentials |
+
+[`.env.example`](https://github.com/crvouga/atlas/blob/main/.env.example) lists them with explanations. The server does not look for
+ambient AWS credentials (`AWS_*`, profiles, instance roles) and the old `ATLAS_STORE`, `ATLAS_WRITE`, `ATLAS_DATA`,
+`--store`, `--write`, `--data` and the `data`, `backends` and `write` keys of `atlas.server.json` are gone; a
+configuration file that still has one of the keys is refused with a message that says so.
+
+**It fails fast and loud.** Before anything listens, the server checks every variable, then proves the bucket is
+usable (lists it, writes and deletes a scratch object) and reads the user state. If any step fails it prints a banner
+that lists **every** variable with `[MISSING]`, `[INVALID]`, `[ok]` or `[not set]`, says why storage is required (and
+what S3 answered, when S3 was reached), never prints a secret, and exits with status **2**:
+
+```text
+==============================================================================
+  ATLAS CANNOT START: S3 STORAGE IS NOT USABLE
+==============================================================================
+  Why:    the S3 configuration is missing or invalid.
+  Reason: Atlas stores ALL reports and ALL user state (the garbage collection policy and saved
+          settings) in S3-compatible object storage, and nowhere else. There is no local-disk,
+          in-memory or database fallback, so the server refuses to start without working S3.
+
+  Required environment variables:
+  [MISSING] ATLAS_S3_ENDPOINT           S3 API endpoint of the object storage service
+  [ok]      ATLAS_S3_BUCKET             Bucket that holds reports and user state; it must already exist
+  [INVALID] ATLAS_S3_REGION             must be lowercase letters, digits and hyphens, like eu-west-1
+  …
+  Fix these 2: ATLAS_S3_ENDPOINT, ATLAS_S3_REGION
+```
+
+Credentials that S3 rejects, a bucket that does not exist and a user state object that cannot be read stop the
+server in the same way, with the answer from S3 in the banner. `atlas dev` behaves the same.
+
+## User state and garbage collection
+
+Everything a person using Atlas has chosen is **user state**: one JSON document, `server/state.json` under
+`ATLAS_S3_PREFIX`, in the same bucket as the reports. It is never kept on the server's disk or in the browser.
+
+```json
+{
+  "schemaVersion": 1,
+  "gc": { "enabled": true, "maxAgeDays": 90, "keepLatest": 20, "intervalHours": 24 },
+  "settings": { "refreshSeconds": 30 }
+}
+```
+
+(published as [`user-state.schema.json`](https://github.com/crvouga/atlas/blob/main/packages/schema/schemas/user-state.schema.json))
+
+- **`gc` is the garbage collection policy**, defined in the Atlas UI (**Settings**, `/admin`, *Garbage collection*) and
+  read by the server **from S3 every time it collects**, so a saved policy applies at the next pass without a restart.
+- **`settings`** are the report and live-run settings saved from the same page. They apply at the next start, below
+  `atlas.server.json`, the environment and the flags in precedence.
+- A document that does not exist is an empty state; one that exists but cannot be parsed stops the server and is
+  never overwritten.
+
+**No policy saved yet.** Atlas is deletion-free until someone says otherwise: with no `gc` in the document,
+garbage collection is **off and nothing is ever deleted**. The server says so at start, the API answers
+`saved: false, policy: null`, the page shows a "No policy has been saved yet" notice with suggested values that take
+effect only after you turn collection on and save, and `POST /api/settings/gc/run` answers 409. There is no
+fallback to a file, an environment variable or built-in numbers.
+
+**What a policy deletes.** With `enabled: true`, every `intervalHours` (and shortly after start) the server applies the
+policy to every project. It deletes a report layer only when all of these hold:
+
+1. the server has read it and every check it carries has been replaced by a newer layer, so it no longer decides any
+   result (deleting it cannot change the report);
+2. it was recorded more than `maxAgeDays` days ago;
+3. it is not one of the newest `keepLatest` layers of its project.
+
+The layer's catalog entry goes first (so nothing visible points at a missing manifest), then its manifest, then the
+captured files (screenshots, logs, …) that no remaining layer refers to; if any remaining layer cannot be read, no
+file is deleted. Specs, runs and commit inventories are never touched, and a layer that failed to load, that
+`include` hides, or that still decides a result is never a candidate. Because a deleted layer is also removed from the
+test history, history older than the policy allows is gone after the next start. One narrow race remains: a publisher
+that reuses a stored file at the very moment the last layer that used it is deleted can end up with a layer that
+points at a missing file; keep `maxAgeDays` well above the time uploads take.
+
+**Editing it.** `GET /api/settings/gc` and `PUT /api/settings/gc` (admin, with `If-Match` the revision that was read,
+same-origin in browsers) read and save the policy; `POST /api/settings/gc/run` applies it now, and
+`POST /api/settings/gc/run?dryRun=1` only counts what would go. A save that races another is refused with 409. The
+revision is the SHA-256 of the stored document, so saving the policy and saving settings invalidate each other's
+revision: reload, then save. An object store has no conditional writes, so run one server per bucket.
+
 ## Configuration
 
-Everything has a default, so no configuration is a working server for this machine. Settings come from
+Everything but the [S3 storage](#required-s3-storage) has a default. Settings come from the settings saved in S3 (the lowest layer), then
 `atlas.server.json` (or `--config <file>` / `ATLAS_CONFIG`), then environment variables, then flags; a later one
-wins. A mistake (an unknown key, a short token, two write targets, listening beyond this machine without tokens)
+wins. A mistake (an unknown key, a short token, listening beyond this machine without tokens)
 is said in words and the server does not start. The file has a published
 [JSON Schema](https://github.com/crvouga/atlas/blob/main/packages/schema/schemas/server-config.schema.json)
 (`@crvouga/atlas/schemas/server-config.schema.json`).
@@ -1318,9 +1418,6 @@ is said in words and the server does not start. The file has a published
   "$schema": "./node_modules/@crvouga/atlas/packages/schema/schemas/server-config.schema.json",
   "host": "0.0.0.0",
   "port": 8080,
-  "data": "./atlas-data",
-  "backends": [{ "id": "archive", "url": "s3://my-bucket/atlas/my-project?region=us-east-1", "label": "Archive" }],
-  "write": "data",
   "auth": {
     "tokens": [
       { "name": "ci", "role": "publish", "tokenEnv": "ATLAS_CI_TOKEN" },
@@ -1336,11 +1433,16 @@ is said in words and the server does not start. The file has a published
 <!-- generated:server-settings -->
 | Setting | File key | Flag | Environment | Default |
 | --- | --- | --- | --- | --- |
+| S3 endpoint URL (**required**) | `storage.s3.endpoint` |  | `ATLAS_S3_ENDPOINT` | **none: the server refuses to start** |
+| Bucket for all reports and user state (**required**) | `storage.s3.bucket` |  | `ATLAS_S3_BUCKET` | **none: the server refuses to start** |
+| Bucket region (**required**) | `storage.s3.region` |  | `ATLAS_S3_REGION` | **none: the server refuses to start** |
+| Access key id (**required**) | `storage.s3.accessKeyId` |  | `ATLAS_S3_ACCESS_KEY_ID` | **none: the server refuses to start** |
+| Secret access key (**required**) | `storage.s3.secretAccessKey` |  | `ATLAS_S3_SECRET_ACCESS_KEY` | **none: the server refuses to start** |
+| Folder in the bucket for everything Atlas writes (optional) | `storage.s3.prefix` |  | `ATLAS_S3_PREFIX` | the bucket root |
+| Path-style bucket addressing (`0` for virtual-hosted) (optional) | `storage.s3.pathStyle` |  | `ATLAS_S3_PATH_STYLE` | yes |
+| Session token for temporary credentials (optional) | `storage.s3.sessionToken` |  | `ATLAS_S3_SESSION_TOKEN` | none |
 | Address to listen on | `host` | `--host <address>` | `ATLAS_HOST`, `HOST` | `127.0.0.1` |
 | Port (`0` picks a free one) | `port` | `--port <n>` | `ATLAS_PORT`, `PORT` | `8080` |
-| The server's own folder: the default backend and write target | `data` | `--data <dir>` | `ATLAS_DATA` | `./atlas-data` |
-| More backends, read together with the data folder | `backends` | `--store <[id=]url>` (repeatable) | `ATLAS_STORE` | none |
-| The backend uploads go to | `write` | `--write <id>` | `ATLAS_WRITE` | `data` |
 | The built client | `site` | `--site <dir>` | `ATLAS_SITE` | `./atlas-site`, else built once |
 | Whose specs the report is laid over | `outlineBranch` | `--outline-branch <branch>` | `ATLAS_OUTLINE_BRANCH` | `main`, then `master`, then the newest |
 | Only layers recorded on these branches take part | `include.branches` | `--branch <name>` (repeatable) | `ATLAS_ONLY_BRANCH` | all |
@@ -1362,22 +1464,19 @@ is said in words and the server does not start. The file has a published
 `ATLAS_HOST` and `ATLAS_PORT` win over `HOST` and `PORT`, which other tools on a machine often set for their own
 purposes.
 
-## Backends
-
-A backend is anything that implements `ObjectStore`: a folder, an S3-compatible bucket (`s3://`, `r2://`,
-`gs://`), or **another Atlas server** (`https://…`, with `ATLAS_TOKEN` for it). The server reads every backend
-and shows one report; one that is down is named in the client and skipped, and the server recovers by itself.
+## Storage
 
-- **Uploads go to one backend**: the `data` folder, or the one named by `write` / `ATLAS_WRITE`. Name a bucket
-  to make it the system of record, so the server holds nothing a replacement would lose:
-
-  ```sh
-  ATLAS_STORE=project=s3://my-bucket/atlas/my-project ATLAS_WRITE=project atlas serve
-  ```
+The server has one backend, the S3 bucket named by the [required variables](#required-s3-storage); it reads every
+layer in it and shows one report. If the bucket becomes unreachable the server keeps serving what it has, names the
+backend in the client and `/readyz`, and recovers by itself.
 
-- **Layers written to a backend by something else** (CI with bucket access, `atlas report merge`) are found at
-  the next refresh. Layers uploaded through the server are in the report at once.
-- **A server can be a backend of another**: a local server reading the project's shared one shows both.
+- **Uploads go to the bucket** and are in the report at once. Layers written to the bucket by something else (CI
+  with bucket access, `atlas report merge`) are found at the next refresh.
+- **Projects** are folders in the bucket (`projects/<slug>/`), as [below](#multiple-projects-on-one-node).
+- **Clients are different.** `atlas report publish --store …` on a laptop or CI job may name any store (a folder,
+  a bucket, this server's URL); this page is about the server.
+- **Library use.** `createAtlasServer({ backends, write })` accepts any `ObjectStore` so an application embedding the
+  server, or a test, can bring its own; `atlas serve` and `atlas dev` always use S3.
 
 ## Tokens and roles
 
@@ -1566,6 +1665,9 @@ curl "$ATLAS_SERVER_URL/api/projects/$ATLAS_PROJECT/reports/tests?format=markdow
 | `GET /admin` | read | Server settings page. |
 | `GET /api/settings` | admin | Read server settings. |
 | `PUT /api/settings` | admin | Save settings for the next restart. |
+| `GET /api/settings/gc` | admin | Read the garbage collection policy. |
+| `PUT /api/settings/gc` | admin | Save the garbage collection policy. |
+| `POST /api/settings/gc/run` | admin | Collect garbage now, or preview it. |
 | `GET /healthz` | none | Is the process up. |
 | `GET /readyz` | none | Has the server read its backends. |
 | `GET /api/openapi.json` | none | This document. |
@@ -1694,11 +1796,11 @@ What makes it so, none of it at the cost of the contract:
 - **One node for multiple projects.** Local environments and CI select their project slug and talk to the same node, which tells
   every client at once. Two servers on one backend both work and show the same report, but a client hears about
   an upload only from the server that took it and about the other's at the next refresh, so give a team one.
-- **State is the write backend.** Back up `./atlas-data` (or the bucket). Restoring it, or starting a new server
-  on it, shows the same report.
+- **State is the bucket.** Reports and user state are all in it. Back it up, replicate or version it as any data;
+  starting a new server on a restored copy shows the same report and applies the same garbage collection policy.
 - **Stopping.** `SIGTERM` stops accepting, lets requests in flight finish, ends the event streams and exits 0.
 - **Logs.** One JSON line per request (method, path, status, ms) to stdout, none for the probes. The first lines
-  say what it reads and which backend takes uploads, and warn when there are no tokens.
+  say which bucket it uses, what the garbage collection policy in S3 is (or that none is saved), and warn when there are no tokens.
 - **A backend goes down.** The server keeps serving what it has, names the backend in the client and in
   `/readyz`, and recovers by itself. The gate fails closed: unknown is not a pass.
 - **Upgrades.** The layer format is a stable, versioned contract; upgrade the server before the clients that
@@ -1708,7 +1810,10 @@ What makes it so, none of it at the cost of the contract:
 
 Open **Settings** (`/admin`) and enter an admin token. The token stays in page memory. Read and publish tokens cannot edit settings; the browser sign-in box only grants reading. The API uses `Authorization: Bearer` and refuses cross-origin browser writes.
 
-Use the Storage, Live updates, and Report rules forms to edit saved settings. Advanced includes request limits, logging, a JSON editor, and a read-only view of the active configuration. Save changes and restart Atlas to apply them. Atlas validates the configuration and atomically replaces `atlas.server.json`, preserving authentication and deployment settings. Changes apply at the next restart; environment variables and flags retain precedence. Concurrent edits require reloading the current revision. Data is never moved or removed by changing settings. Keep an old backend as a read source when moving future uploads to a new one. Embedded servers can provide their own settings persistence or manage configuration outside this API.
+The page has a Storage notice (the bucket is set by the `ATLAS_S3_*` variables and cannot be changed here), the **Garbage collection** form, and the Live updates and Report rules forms. Advanced includes request limits, logging, a JSON editor, and a read-only view of the active configuration.
+
+- **Garbage collection** edits the policy: enabled, delete layers older than N days, always keep the newest N layers, run every N hours. *Save garbage collection policy* writes it to S3 at once (it applies at the next pass, no restart). *Preview deletions* counts what a pass would delete, per project, and deletes nothing. See [user state and garbage collection](#user-state-and-garbage-collection).
+- **Settings** forms save to the same JSON document in S3 and apply after a restart. Atlas validates them against the whole deployment first, and the configuration file, environment variables and flags retain precedence. Concurrent edits require reloading the current revision. Data is never moved or removed by changing settings. Embedded servers can provide their own persistence or manage settings outside this API.
 
 Native test reporters for CodeceptJS, Mocha, Jest and Node upload directly to this server; see [runner setup](runners.md). Every publisher uses the same server address and only a publish token. Storage credentials belong in the server environment.
 
@@ -1720,13 +1825,13 @@ Start with `POST /api/live/<uuid>`, send ordered check deltas with `PATCH /api/l
 
 The server uses its own receipt clock. By default it interrupts a run after 30 seconds without a heartbeat (`ATLAS_RUN_TIMEOUT_SECONDS`). Heartbeats do not reset progress: after 15 minutes with no changed tests/steps, a separate stall timeout interrupts it (`ATLAS_RUN_STALL_SECONDS`, 0 disables). Both settings are editable in the admin UI. Healthy long tests continue renewing heartbeats; increase or disable the progress timeout for tests that legitimately make no observable progress for longer.
 
-Interrupted runs retain completed results and show why the remaining work stopped. Missing outcomes never become passes. The server persists bounded summaries under `server/live/` in its write backend (an HTTP relay keeps operational leases in its own data folder; the remote server only accepts immutable report objects) and restores outstanding leases as interrupted after a server restart. S3 server credentials need GetObject/PutObject for that prefix; generate the updated `atlas report policy --role both` policy. Producers still receive no backend credentials. Live `run` events carry bounded snapshots directly into test rows, including step logs and interruption reasons. The legacy `atlas:change` announcement remains available for older clients; its optional `liveRunId` identifies lease updates. Reconnecting viewers re-fetch progress, reports, and specifications. With SSE connected, live progress uses a 60-second safety refresh; without SSE it polls every two seconds. Returning to the tab or coming back online also revalidates reports and progress.
+Interrupted runs retain completed results and show why the remaining work stopped. Missing outcomes never become passes. The server persists bounded summaries under `server/live/` in its bucket and restores outstanding leases as interrupted after a server restart. S3 server credentials need GetObject/PutObject for that prefix; generate the updated `atlas report policy --role both` policy. Producers still receive no backend credentials. Live `run` events carry bounded snapshots directly into test rows, including step logs and interruption reasons. The legacy `atlas:change` announcement remains available for older clients; its optional `liveRunId` identifies lease updates. Reconnecting viewers re-fetch progress, reports, and specifications. With SSE connected, live progress uses a 60-second safety refresh; without SSE it polls every two seconds. Returning to the tab or coming back online also revalidates reports and progress.
 
 In this repository, use `bun atlas` and `bun example:run` in two terminals. Every example Gherkin scenario executes, including sharing and renaming; `@unrecorded` no longer excludes tests.
 
 ## Multiple projects on one node
 
-Start the node with `atlas server` (or `bun atlas` in this repository). The server builds or finds the Atlas client and serves it with the API from one process. It never imports a consumer or an example. In this repository the node uses port 5180 and `./atlas-data`; `bun example:run` publishes the Todo app to project `todo-app`.
+Start the node with `atlas server` (or `bun atlas` in this repository). The server builds or finds the Atlas client and serves it with the API from one process. It never imports a consumer or an example. In this repository the node uses port 5180 and the bucket named by your `.env`; `bun example:run` publishes the Todo app to project `todo-app`.
 
 Set `ATLAS_PROJECT=todo-app` alongside `ATLAS_SERVER_URL` for native reporters and statechart runs. Report CLI commands accept `--project todo-app` (or `ATLAS_PROJECT`) with an HTTP store. Programmatic HTTP stores, live reporters and native reporter options accept `project: 'todo-app'`. Keep the same slug for the invocation's live progress, final results, spec sets and recordings. Slugs use 1–64 lowercase letters, digits or hyphens, starting and ending with a letter or digit.
 
@@ -1744,14 +1849,14 @@ Project indexes are opened lazily; at most 64 are active in memory. An index wit
 
 This is the production setup. A project runs **one Atlas server**. Developers' machines and every CI job send
 their results to it, as they finish or when they are done, and it shows everyone, developers and the business
-alike, the whole project at once, live. It keeps results on its own disk by default, or in an object-store bucket
-if you prefer; either way nothing is partitioned by run, branch or person: results are layered. The server's API,
+alike, the whole project at once, live. It keeps results (and all its user state) in an S3-compatible bucket and
+nowhere else; nothing is partitioned by run, branch or person: results are layered. The server's API,
 configuration and protocol are in **[the Atlas server](server.md)**; this page is the path to production.
 
 ```
   a developer's worktree ─┐                                       ┌─▶ developers   (browser, live)
-  a CI job, any branch ───┼─ atlas report publish|stream ─▶ SERVER ◀┤   atlas serve: keeps layers in ./atlas-data
-  a device lab, nightly ──┘   (immutable layers, over HTTP)  or S3  ├─▶ business      or in a bucket (--write)
+  a CI job, any branch ───┼─ atlas report publish|stream ─▶ SERVER ◀┤   atlas serve: keeps layers in S3
+  a device lab, nightly ──┘   (immutable layers, over HTTP)  ──▶ S3  ├─▶ business      (required, nothing else)
                                                                     └─▶ CI gate     atlas report status
 ```
 
@@ -1760,7 +1865,7 @@ Why this holds together:
 - **Publishing never conflicts.** A layer is one immutable file named by its content. Two machines that
   publish at once write different files; a retry writes the same one. There is no lock, no index to
   corrupt, nothing to merge.
-- **The server is replaceable.** What it knows is its write backend (a folder, or a bucket). Replace it, restore it
+- **The server is replaceable.** What it knows is in its bucket. Replace it, restore it
   from a backup, or run a copy on a laptop: they show the same report, because a report is a function of the
   layers ([the contract](report-contract.md)).
 - **One view.** The newest completed result of every check, in every environment, from anyone. A
@@ -1778,13 +1883,15 @@ Why this holds together:
 
 ## 1. Where results are kept
 
-**By default, on the server's own disk** (`./atlas-data`, or the volume you mount at `ATLAS_DATA`). Nothing else
-needs to exist: skip to [section 3](#3-send-results-from-ci-and-from-laptops). Back that folder up like any data
-directory; starting a new server on a restored copy shows the same report.
+**The server keeps everything in one S3-compatible bucket** (reports and user state, such as the garbage collection
+policy), set by the required `ATLAS_S3_ENDPOINT`, `ATLAS_S3_BUCKET`, `ATLAS_S3_REGION`, `ATLAS_S3_ACCESS_KEY_ID` and
+`ATLAS_S3_SECRET_ACCESS_KEY` variables ([details](server.md#required-s3-storage), template in
+[`.env.example`](https://github.com/crvouga/atlas/blob/main/.env.example)). Without them it refuses to start, listing
+every variable and what is wrong. There is no disk or database to fall back to, so the server is replaceable:
+a new one started on the same bucket shows the same report.
 
-**To keep results in a bucket instead** (so a replaced server loses nothing, or CI already has bucket access),
-name it and make it the place uploads go: `ATLAS_STORE=project=s3://my-bucket/atlas/my-project ATLAS_WRITE=project`.
-The rest of this section is that setup. A store is named by a URL. Keys never go in it.
+**Clients and CI** name stores by URL, and a client may publish straight to a bucket or folder as well as to the
+server. A store is named by a URL. Keys never go in it.
 
 | Store | URL |
 | --- | --- |
@@ -1932,18 +2039,16 @@ A run is uploaded only when its privacy scan passed: the same rule the static cl
 ## 4. The server
 
 ```sh
-atlas serve                    # ATLAS_STORE says where; listens on :8080
+atlas serve                    # ATLAS_S3_* says where; listens on :8080
 ```
 
-It serves the client, the report and the project's specs and runs from all configured backends. It also
-accepts uploads and announces new results on its event stream. Uploads go to `--data` by default;
-use a named `--store project=s3://… --write project` to put uploads in a shared bucket, with publisher permissions.
+It serves the client, the report and the project's specs and runs from its bucket. It also
+accepts uploads and announces new results on its event stream. The bucket's credentials need list, read, write and delete
+permissions (`atlas report policy` prints a least-privilege policy; delete is for the garbage collection you define in the UI).
 
 | Flag | Environment | Meaning |
 | --- | --- | --- |
-| `--store <url>` (repeatable) | `ATLAS_STORE` | Where layers are. Several stores are one report: repeat the flag, or separate them in the variable with commas or new lines. |
-| `--data <dir>` | `ATLAS_DATA` | Local upload backend. Default `./atlas-data`. |
-| `--write <id>` | `ATLAS_WRITE` | Backend that accepts uploads. Default `data`. |
+| | `ATLAS_S3_ENDPOINT`, `ATLAS_S3_BUCKET`, `ATLAS_S3_REGION`, `ATLAS_S3_ACCESS_KEY_ID`, `ATLAS_S3_SECRET_ACCESS_KEY` | **Required.** The S3-compatible bucket that holds all reports and user state. Optional: `ATLAS_S3_PREFIX`, `ATLAS_S3_PATH_STYLE`, `ATLAS_S3_SESSION_TOKEN`. |
 | `--port <n>` | `ATLAS_PORT` or `PORT` | Default 8080. `0` picks a free one. |
 | `--host <h>` | `ATLAS_HOST` or `HOST` | Default `127.0.0.1`. Listening beyond this machine requires tokens or `--insecure`. |
 | `--site <dir>` | `ATLAS_SITE` | The built client. Default: `./atlas-site`, else built once into `~/.cache/atlas/site`. |
@@ -1970,9 +2075,10 @@ updated `latest`. Pull request builds and failed publications are labelled accor
    Leave the start command unset: the image includes the server and the prebuilt viewer.
 2. Add `ATLAS_TOKEN` with a long random value (generate one with `openssl rand -hex 24`). It grants admin
    access; optionally add separate `ATLAS_PUBLISH_TOKEN` and `ATLAS_READ_TOKEN` for publishers and readers.
-3. Attach a volume at `/data` and set `RAILWAY_RUN_UID=0`: Railway mounts volumes as root, while the image
-   normally runs as `bun` ([Railway volume permissions](https://docs.railway.com/volumes#permissions)).
-   Keep one replica. The volume retains reports and server settings when the image is replaced.
+3. Add the five required storage variables (`ATLAS_S3_ENDPOINT`, `ATLAS_S3_BUCKET`, `ATLAS_S3_REGION`,
+   `ATLAS_S3_ACCESS_KEY_ID`, `ATLAS_S3_SECRET_ACCESS_KEY`) for a bucket you own. The service keeps nothing on its own
+   disk, so no volume is needed and a replaced image loses nothing; without the variables it exits and lists each one.
+   Keep one replica.
 4. Set the healthcheck path to `/readyz` and generate a public domain. The image listens on `0.0.0.0` and
    honors Railway's `PORT`; leave `ATLAS_PORT` unset. Open the domain and sign in with your token as the
    password (any username), or use the viewer's token sign-in.
@@ -1986,8 +2092,7 @@ Projects publish to that domain with `ATLAS_STORE=https://YOUR-DOMAIN` and their
 [sending results](#3-send-results-from-ci-and-from-laptops). Hosting Atlas needs no project checkout; publishing
 your project's test results still needs the integration described there.
 
-For bucket storage instead, set `ATLAS_STORE=project=s3://my-bucket/atlas/my-project`, `ATLAS_WRITE=project`,
-and the bucket credentials. Keep the `/data` volume for server settings and local state.
+Then open `/admin` to define the garbage collection policy; until you save one, nothing is deleted.
 
 ### Deploy without authentication
 
@@ -2003,12 +2108,11 @@ In Railway, create a **Docker image** service with:
 ghcr.io/crvouga/atlas-insecure:latest
 ```
 
-Leave the start command unset. Attach a persistent volume at `/data`, set `RAILWAY_RUN_UID=0`, keep one
+Leave the start command unset. Add the required `ATLAS_S3_*` storage variables, keep one
 replica, set the healthcheck to `/readyz` and generate a public domain. Leave `ATLAS_PORT` unset so Railway's
 `PORT` is used. Enable **Settings → Source → Configure Auto Updates → Anytime** to follow `latest`.
 Do not set `ATLAS_TOKEN`, `ATLAS_PUBLISH_TOKEN` or `ATLAS_READ_TOKEN`, or add `auth.tokens` to
-`/data/atlas.server.json`: configured tokens still enable authentication. When reusing a volume from an
-authenticated deployment, remove its saved auth tokens first. Open the domain directly, including `/admin`
+a configuration file: configured tokens still enable authentication. Open the domain directly, including `/admin`
 for settings (leave the token field blank and choose **Load settings**).
 
 Verify anonymous reads and uploads without an Authorization header:
@@ -2029,7 +2133,7 @@ leave its `ATLAS_TOKEN` unset. Use the same publishing commands described in
 For local Docker:
 
 ```sh
-docker run --pull always -p 8080:8080 -v atlas-data:/data ghcr.io/crvouga/atlas-insecure:latest
+docker run --pull always -p 8080:8080 --env-file .env ghcr.io/crvouga/atlas-insecure:latest
 ```
 
 Both images publish full commit tags for pinning or rollback. A new GHCR package must be made Public
@@ -2039,10 +2143,11 @@ once before Railway can pull without registry credentials; see
 ### Docker
 
 The same published image works anywhere Docker runs. It already contains the client (the same
-for every project: the server tells the page where its data is), and keeps results on the volume at `/data`:
+for every project: the server tells the page where its data is), and keeps nothing on its own disk: it needs the
+`ATLAS_S3_*` variables (copy `.env.example` to `.env` and fill it in):
 
 ```sh
-docker run --pull always -p 8080:8080 -v atlas-data:/data \
+docker run --pull always -p 8080:8080 --env-file .env \
   -e ATLAS_TOKEN=$(openssl rand -hex 24) ghcr.io/crvouga/atlas:latest
 ```
 
@@ -2051,17 +2156,15 @@ back, replace `latest` with the full commit SHA. To build from this repository,
 [`examples/deploy/Dockerfile`](https://github.com/crvouga/atlas/blob/main/examples/deploy/Dockerfile) is the
 alternative for building from an npm version or a local package tarball.
 
-For a bucket as the system of record add `-e ATLAS_STORE=project=s3://my-bucket/atlas/my-project -e ATLAS_WRITE=project -e AWS_REGION=us-east-1`.
-On ECS, EKS or EC2, attach the combined **both** policy (including `server/live/*` for producer leases) to the task, service account or
-instance and set no keys.
+The bucket's account needs the combined **both** policy (including `server/live/*` for producer leases and `server/state.json`
+for user state) plus `s3:DeleteObject` for garbage collection. The server does not use ambient AWS roles: pass the keys.
 
 **Try it on one machine.** [`examples/deploy/compose.yaml`](https://github.com/crvouga/atlas/blob/main/examples/deploy/compose.yaml)
-starts the published image on a volume; `compose.s3.yaml` starts it with an S3 server and a bucket as its storage.
+starts the published image with an S3 server (SeaweedFS) and a bucket as its storage; `compose.s3.yaml` is the same stack without tokens.
 Publish to `http://localhost:8080` from your project and open it.
 
 **Kubernetes.** [`examples/deploy/kubernetes.yaml`](https://github.com/crvouga/atlas/blob/main/examples/deploy/kubernetes.yaml):
-one copy (the server is a singleton for the project), results in the bucket, readiness on `/readyz`, an IRSA
-service account.
+one copy (the server is a singleton for the project), results in the bucket (keys from a Secret), readiness on `/readyz`.
 
 **Without a container.** `bun add -d @crvouga/atlas`, then `bunx atlas client build --no-data --out
 atlas-site` and `bunx atlas serve`. Everything it can be told is in
@@ -2134,12 +2237,13 @@ Narrow it by choice, per consumer, never by moving data:
   listing (one request per thousand layers) runs at the start and every 30 refreshes (five minutes by
   default), which is also how a layer recorded with an old timestamp is found. One small `GET` per new
   layer, once.
-- **Retention.** Atlas deletes nothing. `atlas report doctor` shows what the bucket holds.
-- **Disaster recovery.** The write backend (the data folder, or the bucket) is the only state. Back it up, replicate or version it as you
+- **Retention.** Atlas deletes nothing until you define a garbage collection policy in the UI (`/admin`); it is kept in the bucket as JSON and
+  then removes only superseded layers older than you allow ([details](server.md#user-state-and-garbage-collection)). `atlas report doctor` shows what the bucket holds.
+- **Disaster recovery.** The bucket is the only state (reports and user state). Back it up, replicate or version it as you
   do any data; a server is rebuilt from nothing in the time it takes to read the layers (below). It listens at once
   and answers `/readyz` 503 until it has, so a liveness probe never kills one that is still reading.
-- **A second bucket.** Another team's layers, a device lab, an archive: pass several `--store`s. They are one
-  report, attributed to the store they came from.
+- **A second bucket.** The server reads one bucket. To combine another team's layers or an archive into the
+  report, copy them in with `atlas report merge --into <store>`; clients and `atlas report status` may read several stores.
 
 ## 7. Performance
 
@@ -2392,7 +2496,7 @@ are part of the contract:
 | **Partition independence** | Splitting the same layers across any number of backends, machines or branches, with any overlap, gives the same report. This is what makes partial runs on separate nodes safe. |
 | **Idempotence** | A layer present twice, in one backend or several, counts once. Publishing the same checks again writes the same layer. |
 | **Monotonic** | A layer changes only the slots it fills. Adding a layer never changes a result it did not record. |
-| **Deletion-free** | Nothing in the contract removes or rewrites a layer. Retention is the operator's choice. |
+| **Deletion-free** | Nothing in the contract removes or rewrites a layer. Retention is the operator's choice: Atlas deletes only under a garbage collection policy an operator saved in the UI, and then only layers that no longer decide any result ([the server](server.md#user-state-and-garbage-collection)). |
 | **Unknown is not a pass** | A layer that cannot be read, a backend that is down, and a check that is `running` or `not-run` never count as passing. The gate fails closed. |
 | **Aggregation by copying** | Layers are immutable and never share a key with different bytes, so combining stores is copying files (`atlas report merge`, `cp -R`, `rsync`, a CI artifact download). Copying is idempotent and commutative. |
 
@@ -2834,150 +2938,7 @@ unaffected.
 </doc>
 
 <doc path="docs/report-backends.md">
-# Report backends and live snapshots
-
-> [!NOTE]
-> Atlas has two kinds of backend, and this page is about the first.
->
-> - **Run sources** (this page): where the client finds *statechart runs* (`manifest.json` per run)
->   and live snapshots of a run in progress: a directory, HTTP files, or an HTTP API.
-> - **Layer stores**: where *layers of evidence for any kind of spec* are kept, an `ObjectStore`
->   such as a directory or a bucket. Any number of them are one report. See
->   [the report contract](report-contract.md#backends) and [integrating Atlas](integrating.md).
->
-> Publish a run as a layer (`atlas report publish --manifest`) to have it combine with other suites,
-> environments and branches.
-
-Atlas maps the product's areas, screens, events and journeys from a spec, then overlays evidence
-of what the product did. Specs and reports are independent. Local development, CI, device labs
-and hosted runners can supply reports to the same product atlas simultaneously. The client works
-before the first report exists.
-
-## Connect sources
-
-The default source is the directory passed to `--runs`. Add sources with a JSON file:
-
-```json
-{
-  "schemaVersion": 1,
-  "sources": [
-    { "id": "mobile", "label": "Mobile runs", "type": "directory", "runs": "./mobile-runs" },
-    { "id": "ci", "label": "CI reports", "type": "http", "baseUrl": "https://reports.example.com/atlas-data/" },
-    { "id": "runner", "label": "Hosted runner", "type": "api", "baseUrl": "https://runner.example.com/atlas/", "eventsUrl": "events", "pollMs": 10000 }
-  ]
-}
-```
-
-```sh
-atlas client dev --specs ./specs --runs ./atlas-runs --sources ./atlas.sources.json
-atlas client build --specs ./specs --runs ./atlas-runs --sources ./atlas.sources.json --out ./atlas-site
-atlas client publish-data --specs ./specs --runs ./atlas-runs --sources ./atlas.sources.json --out ./atlas-data
-```
-
-Directory paths resolve against the configuration file. Source ids are unique, stable names
-containing letters, numbers, underscores or hyphens. `workspace` is reserved for `--runs`.
-`ATLAS_SOURCES_FILE` is the environment equivalent. Restart dev after changing the file.
-Credentials must not appear in this file or URLs: descriptors are sent to the browser and
-included in static output.
-
-Remote services must allow requests
-from the client's origin. For private services, use an authenticated same-origin gateway. Atlas
-does not download private GitHub artifacts or sign object-storage requests itself: expose their
-published data over HTTP or implement a gateway using the contract below.
-
-## Transport contracts
-
-| Backend | Index | Snapshot | Media and other reports | Updates |
-| --- | --- | --- | --- | --- |
-| Directory | Generated from run directories | `<run>/manifest.json` | Files beside the manifest | File watcher and polling fallback |
-| HTTP files | `runs/index.json` | `runs/<id>/manifest.json` | `runs/<id>/<path>` | Polling; optional server events |
-| HTTP API | `runs` | `runs/<id>/manifest` | `runs/<id>/files/<path>` | Polling; optional server events |
 
-Locations are relative to `baseUrl`. The index follows the Atlas runs-index contract:
-
-```json
-{
-  "runs": [{
-    "id": "build-123",
-    "startedAt": "2026-10-09T11:59:00Z",
-    "progress": "running",
-    "hasManifest": true,
-    "execution": {
-      "totalPaths": 8,
-      "completedPaths": 2,
-      "activePaths": ["journey-3"],
-      "updatedAt": "2026-10-09T12:00:00Z"
-    }
-  }]
-}
-```
-
-Each manifest is a full snapshot of everything received so far, rather than a patch or unfinished
-JSON document. Records can be absent; malformed records are reported individually. Set
-`run.finishedAt` to `null` while running, then a timestamp when complete. Its absence preserves
-the meaning of older completed reports. Optional `run.progress` has the same shape as `execution`
-above. Paths can declare `progress: queued | running | complete`.
-
-Unvisited `not-reached` records appear pending during an active run. Passed and failed records
-appear immediately. A PNG can arrive before its optional WebP thumbnail. Promised media can
-declare `screenshotState: processing` or `clip.state: processing` until ready.
-
-The runner publishes an initial snapshot, each reached screen and completed step, each completed
-path and run completion. File replacements are atomic. Active outcomes stay out of
-`outcomes.json`, so merging and rerunning reuse only completed paths. Results retain deterministic
-plan order across workers.
-
-## Server events
-
-An optional `eventsUrl`, relative to `baseUrl`, serves `text/event-stream`. Send ordinary messages
-or named `atlas:change` events:
-
-```text
-event: atlas:change
-id: 124
-data: {"scope":"runs","runIds":["build-123"]}
-
-```
-
-These invalidate the source's index and named snapshots. Empty `runIds` refreshes cached snapshots
-for this source. Reconnection does the same to recover missed updates. Malformed notices are
-ignored. Polling remains available if a stream disconnects or EventSource is unavailable.
-
-Configured source indexes poll every ten seconds by default (`pollMs` overrides this); selected
-running snapshots poll every two seconds. `VITE_ATLAS_POLL_MS` controls spec polling. Pause live
-updates to keep a snapshot steady; manual Refresh still works. Resuming refreshes immediately.
-
-## Identity, failures and publishing
-
-Client identities combine source ids and native run ids. Cache keys include the backend location
-and transport. Matching run names cannot mix results or media. Shared links retain the qualified
-identity; old links containing only a run id still resolve to workspace reports.
-
-One unavailable source leaves other sources and the spec usable. Failed refreshes retain the
-last valid index and snapshot, with the failure recorded in data issues. A missing first snapshot
-is a waiting state for a running report. Latest follows the newest report, including active runs;
-choosing a particular report keeps it selected as newer reports arrive.
-
-Publishing includes privacy-checked running snapshots and finished runs. Extra directory sources
-are copied under `data/backends/<id>/`; `sources.json` uses relative URLs. Remote descriptors stay
-remote. Missing or failed privacy checks exclude the run, and temporary files and work directories
-are excluded. `--keep` applies per directory source. Publish updated data to the same host while
-a run is active for static viewers to receive its snapshots through polling.
-
-`VITE_ATLAS_BASE_URL` sets the primary spec/data location; `VITE_ATLAS_SOURCES_URL` can point to a
-descriptor file hosted elsewhere. Published descriptors translate directory sources into HTTP
-URLs and never expose the directory paths.
-
-## Another transport
-
-`src/data/adapters/report-backend.ts` defines `ReportBackend`: stable identity and cache key,
-report listing, snapshot loading, media resolution and optional change subscription. The query
-layer consumes this separately from the spec adapter. An embedded client can supply a backend
-through `ReportSourcesContext`; a new built-in transport can add a factory alongside
-`createReportBackend`. Screens, maps and journeys require no transport-specific code.
-
-The generated JSON Schemas include `report-sources`, `atlas-change`, `run-info` and `run-summary`
-alongside the existing manifest and record schemas.
 </doc>
 
 <doc path="docs/statecharts.md">
@@ -3063,7 +3024,7 @@ In another terminal run `bun run example:run`: statecharts, Gherkin scenarios an
 to project `todo-app` on that server while testing. Producers renew a heartbeat every 5 seconds; 30 seconds of silence
 marks an invocation interrupted. Final specs and recordings upload when their privacy scan completes.
 Tests show inline running indicators and logs without waiting for the whole suite to finish. Report history
-is retained in `atlas-data/projects/todo-app`; local run artifacts remain in `atlas-runs` and
+is retained in the server's bucket under `projects/todo-app/`; local run artifacts remain in `atlas-runs` and
 `atlas-reports`. To upload a completed run again without rerunning tests,
 use `bun run example:publish`. Set `ATLAS_SERVER_URL` for a different upload destination (and
 `ATLAS_PUBLISH_TOKEN` when it requires one). Restart `bun atlas` when switching from the older
@@ -3689,8 +3650,11 @@ bun run workspace:status
 ```
 
 Everything binds to `127.0.0.1`. For remote workspaces, use the IDE's port forwarding. Reports and server
-settings stay in this checkout's `.atlas-data/`; live runtime leases stay in `.atlas-workspace/`.
-Keep both directories private to each worktree. Do not share `node_modules`, `.atlas-data/`,
+settings are kept in S3 only, never in the checkout: `workspace:run` needs the required `ATLAS_S3_*` variables
+(copy `.env.example` to `.env`, which Bun loads, or export them) and exits at once, listing every missing one,
+without them. Give each checkout its own bucket or `ATLAS_S3_PREFIX` if their reports must not mix
+(`workspace:setup` and `workspace:preview` need no credentials). Live runtime leases stay in `.atlas-workspace/`.
+Keep that directory private to each worktree. Do not share `node_modules`,
 `.atlas-workspace/` or caches across checkouts with different dependencies. Frozen installs use Bun's
 download cache without linking one worktree's dependency tree to another.
 
@@ -3888,7 +3852,7 @@ The narrowly scoped exceptions are:
 | Evidence | Steps, retries, annotations, facts, unknown extensions, safe downloads and previews | List, Badge, Accordion, Code, Image, native media |
 | Recordings | Pictures/video/timeline, actor selection, moments, failure jumps, timing, model-state differences | Tabs, Slider, Button, ScrollArea, Table, Progress |
 | Search/help | Ranked and semantic search, shortcut help, recording shortcuts | Spotlight, Modal, Kbd |
-| Administration | Token access, storage backends/write destination, live timeouts, report rules, limits, raw JSON, conflicts | Same provider/theme, Fieldset, Mantine inputs, Accordion, Alert |
+| Administration | Token access, S3 storage notice, garbage collection policy (saved in S3), live timeouts, report rules, limits, raw JSON, conflicts | Same provider/theme, Fieldset, Mantine inputs, Accordion, Alert |
 
 The hash routes (`/`, `/chart/$chartId`, `/specs/$kind`), query contracts, project scoping, streaming,
 report APIs and data adapters remain the migration boundary. `/admin` still serves an independent document:
@@ -4269,7 +4233,7 @@ atlas — executable statecharts
                [--no-retry] [--output <dir>]
   atlas merge  [--config atlas.config.ts] [--output <dir>] <run-dir> <run-dir>...
   atlas export --specs <dir> --format scxml|mermaid|markdown|json [--out <file>]
-  atlas server [--data <dir>] [--port 8080] [--store <url>]...   one Atlas node: API, projects and client
+  atlas server [--port 8080]                                     one Atlas node: API, projects and client; needs ATLAS_S3_* (atlas serve --help)
   atlas client build [--no-data] [--out <dir>]                    build the project-agnostic Atlas client
   atlas dev    [--port 5180]                                     develop the Atlas server and client on one host
   atlas init   [--server <url>] [--write]                         integrate this project: detect its suites, print the plan (atlas init --help)
@@ -4306,14 +4270,18 @@ atlas init — integrate a project with an Atlas server
 ```text
 atlas serve: the Atlas server
 
-  atlas serve [--config atlas.server.json] [--data <dir>] [--port 8080] [--host 127.0.0.1]
-              [--store <url|id=url>]... [--write <id>] [--site <dir>]
+  atlas serve [--config atlas.server.json] [--port 8080] [--host 127.0.0.1] [--site <dir>]
               [--outline-branch <b>] [--branch <name>]... [--ignore-modified] [--refresh <seconds>]
               [--anonymous-read] [--insecure] [--no-log]
 
   One process serves the client and the API. Test results are uploaded to it from anywhere (laptops, CI) and it
-  shows everyone the combined report, live. It keeps its data in --data (default ./atlas-data) and can read more
-  backends (--store): S3, other servers, folders. Uploads go to the data folder unless --write names another.
+  shows everyone the combined report, live.
+
+  Storage is required. ALL reports and ALL user state (the garbage collection policy, saved settings) are kept in
+  S3-compatible object storage and nowhere else; there is no local-disk, in-memory or database fallback. Without
+  these environment variables the server prints every one of them with what is wrong, and exits with status 2:
+    ATLAS_S3_ENDPOINT  ATLAS_S3_BUCKET  ATLAS_S3_REGION  ATLAS_S3_ACCESS_KEY_ID  ATLAS_S3_SECRET_ACCESS_KEY
+  Optional: ATLAS_S3_PREFIX, ATLAS_S3_PATH_STYLE, ATLAS_S3_SESSION_TOKEN. See .env.example.
 
   Tokens (ATLAS_TOKEN admin, ATLAS_PUBLISH_TOKEN, ATLAS_READ_TOKEN, or "auth.tokens" in the config) are required
   to listen beyond this machine unless --insecure. Every option has an environment variable (docs/deploying.md).
@@ -4324,11 +4292,12 @@ atlas serve: the Atlas server
 ```text
 atlas dev: the Atlas server and the client, for working on either
 
-  atlas dev [--port 5180] [--host 127.0.0.1] [--data <dir>] [--store <url|id=url>]... [--config atlas.server.json]
+  atlas dev [--port 5180] [--host 127.0.0.1] [--config atlas.server.json]
 
   Starts the server (API only, on a port of its own) and the client's dev server, which proxies /api to it, so the
   browser talks to one host and a change to the client shows at once. In production `atlas serve` does both from
-  one process.
+  one process. Storage is the same as for `atlas serve`: the required ATLAS_S3_* environment variables name the S3
+  bucket that holds all reports and user state; without them it exits with status 2 and lists every variable.
 ```
 
 ## atlas report
@@ -4532,7 +4501,7 @@ Responses: `200` Settings editor.; `401` No token, or an unknown one. Send `Auth
 
 `GET /api/settings` · role: admin
 
-Returns editable persisted storage/report settings, active settings, a revision, and configuration precedence. Authentication settings are excluded. Requires an admin Bearer token. Embedded applications may manage settings outside this API.
+Returns the editable report and live-run settings saved in the user state in S3, active settings, a revision, and configuration precedence. Storage and authentication settings are excluded. Requires an admin Bearer token. Embedded applications may manage settings outside this API.
 
 Responses: `200` Settings and revision.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `503` Configuration is managed by the embedding application.
 
@@ -4540,12 +4509,40 @@ Responses: `200` Settings and revision.; `401` No token, or an unknown one. Send
 
 `PUT /api/settings` · role: admin
 
-Replaces editable storage/report settings, preserving authentication and other file fields. Atomically persists a validated configuration; no report data is moved. Environment variables and flags override these values after restart. Requires an admin Bearer token, same-origin requests in browsers, and a current revision.
+Replaces the editable report and live-run settings in the user state in S3 (`server/state.json`), preserving the garbage collection policy and other fields. Persists a validated configuration; no report data is moved. Environment variables and flags override these values after restart. Requires an admin Bearer token, same-origin requests in browsers, and a current revision.
 
 - `If-Match` (header, required): The quoted revision returned by GET /api/settings.
 
 Responses: `200` Saved settings and new revision. Restart required.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `409` Settings changed; reload before saving.; `413` Settings exceed the body limit.; `422` Invalid configuration.; `428` A quoted settings revision is required.; `503` Configuration is managed by the embedding application.
 
+### Read the garbage collection policy
+
+`GET /api/settings/gc` · role: admin
+
+Returns the policy kept in the user state in S3 (`server/state.json`), or `policy: null, saved: false` when none has been saved yet, in which case garbage collection is off and nothing is deleted. Also returns the revision to send back when saving and the last pass over each project. Requires an admin Bearer token. If the stored user state is unreadable the answer is 503 and the stored object is left untouched.
+
+Responses: `200` The policy, its revision and the last passes.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `503` The user state in S3 cannot be read, or settings are managed by the embedding application.
+
+### Save the garbage collection policy
+
+`PUT /api/settings/gc` · role: admin
+
+Replaces the policy in the user state in S3 and leaves the rest of that document alone. The server reads the policy from S3 each time it collects, so the new policy applies at the next pass, without a restart. Requires an admin Bearer token, same-origin requests in browsers, and the current revision.
+
+- `If-Match` (header, required): The quoted revision returned by GET /api/settings/gc.
+
+Responses: `200` The saved policy and the new revision.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `409` The state changed; reload before saving.; `413` The body exceeds the limit.; `422` Invalid policy.; `428` A quoted revision is required.; `503` The user state in S3 cannot be read, or settings are managed by the embedding application.
+
+### Collect garbage now, or preview it
+
+`POST /api/settings/gc/run` · role: admin
+
+Applies the policy saved in S3 to every project now, instead of waiting for the schedule. Only report layers that were read and no longer decide any result, older than the policy allows and beyond its `keepLatest`, are deleted, with the captured files only they used. With `dryRun=1` nothing is deleted and each run reports what it would delete (a disabled policy is previewed as if enabled). Answers 409 when no policy has been saved, and, without `dryRun`, when the saved policy is disabled. Requires an admin Bearer token and a same-origin request in browsers.
+
+- `dryRun` (query): `1` or `true` to only count what would be deleted.
+
+Responses: `200` One run per project.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` The token is known but its role may not do this.; `409` No policy has been saved, or it is disabled.
+
 ### Is the process up
 
 `GET /healthz` · role: none