@crvouga/atlas 0.17.0 → 1.0.0

package/docs/report-backends.md

@@ -1,144 +0,0 @@
-# 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.

package/docs/report-contract.md

@@ -211,7 +211,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. |
 

package/docs/runners.md

@@ -64,6 +64,6 @@ 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).

package/docs/server.md

@@ -9,22 +9,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)
 
@@ -33,7 +35,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 -->
@@ -49,21 +52,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`).
@@ -73,9 +173,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" },
@@ -91,11 +188,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 |
@@ -117,22 +219,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:
+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.
 
-  ```sh
-  ATLAS_STORE=project=s3://my-bucket/atlas/my-project ATLAS_WRITE=project atlas serve
-  ```
-
-- **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
 
@@ -321,6 +420,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. |
@@ -449,11 +551,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
@@ -463,7 +565,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.
 
@@ -475,13 +580,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.
 

package/docs/statecharts.md

@@ -80,7 +80,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

package/docs/ui.md

@@ -125,7 +125,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:

package/docs/workspaces.md

@@ -59,8 +59,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.