@crvouga/atlas 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog: @crvouga/atlas
 
+## 0.9.0 (2026-10-15)
+
+### Features
+
+- accept transition metadata ([6668573](https://github.com/crvouga/atlas/commit/666857395a702b7fc3319d7a31e90caaa060e8e9))
+
+## 0.8.0 (2026-10-15)
+
+### Features
+
+- add anonymous Atlas server image (#12) ([269d62d](https://github.com/crvouga/atlas/commit/269d62d74e08efd2ba473dd3629bddfd13670265))
+
 ## 0.7.0 (2026-10-15)
 
 ### Features

package/README.md

@@ -68,6 +68,48 @@ live step logs and a Running status filter. Producers send heartbeats every
 configure `ATLAS_RUN_TIMEOUT_SECONDS` and `ATLAS_RUN_STALL_SECONDS` (0 disables the progress timeout),
 or edit these settings in the client. An interruption never turns missing outcomes into passes.
 
+## Deploy to Railway without code
+
+Copy this image URI into **Railway → New service → Docker image**:
+
+```text
+ghcr.io/crvouga/atlas:latest
+```
+
+The image includes the Atlas server and viewer; hosting it needs no repository, Dockerfile, build command
+or package installation. [`latest` on GHCR](https://github.com/users/crvouga/packages/container/atlas) follows
+the newest checked `main` image, independently of npm releases.
+
+1. Leave the start command unset. Add a long random secret as `ATLAS_TOKEN` (at least 12 characters;
+   use 48 or more) and set `RAILWAY_RUN_UID=0` for [Railway volume permissions](https://docs.railway.com/volumes#permissions).
+2. Attach a persistent volume at `/data` and keep one replica so reports and server settings survive updates.
+3. Set the healthcheck path to `/readyz` and generate a public domain. Railway supplies `PORT`;
+   leave `ATLAS_PORT` unset. Open the domain and sign in with the token as the password (any username).
+4. Enable **Settings → Source → Configure Auto Updates → Anytime** to follow `latest`.
+   [Railway checks for image updates periodically](https://docs.railway.com/deployments/image-auto-updates);
+   detection can take a few hours.
+
+For the exact image from a run, open **[CI](https://github.com/crvouga/atlas/actions/workflows/ci.yml) →
+run → Summary → Atlas CI**. The summary includes a copyable full commit tag, the immutable registry digest,
+whether that run updated `latest`, all job results, npm release details and artifact links. Use the commit
+tag to pin or roll back a deployment. The [deployment guide](docs/deploying.md#run-it) covers optional reader
+and publisher tokens, bucket storage and sending results from your projects.
+
+### Deploy without authentication
+
+For anonymous access, use this image in Railway instead:
+
+```text
+ghcr.io/crvouga/atlas-insecure:latest
+```
+
+It contains the same server and viewer, with anonymous reading, uploads and administration enabled.
+Follow the Railway steps above, leaving `ATLAS_TOKEN`, `ATLAS_PUBLISH_TOKEN`, `ATLAS_READ_TOKEN` and
+configuration-file auth tokens unset. Open the generated domain directly; no sign-in is required.
+Anyone who discovers the URL can read reports, upload results and change settings. An unlisted URL
+is not access control. See the [anonymous deployment guide](docs/deploying.md#deploy-without-authentication)
+for a token-free project configuration and verification commands.
+
 ## For AI agents
 
 Atlas is built to be integrated and operated by agents, with nothing to click and nothing to guess.
@@ -187,9 +229,8 @@ unless you choose a bucket. `atlas dev` runs the same server with the client's d
 development is one host too. See [the server](docs/server.md) and
 [running Atlas for a project](docs/deploying.md).
 
-On Railway, deploy the image `ghcr.io/crvouga/atlas:latest` directly, with no project checkout or
-custom Dockerfile. Every green merge to `main` publishes it; enable Railway's image auto updates to follow it.
-The [deployment guide](docs/deploying.md#run-it) covers the token, persistent volume and healthcheck.
+Deploy the server using the [Railway setup above](#deploy-to-railway-without-code), or follow the
+[deployment guide](docs/deploying.md#run-it) for other hosts.
 
 ```sh
 atlas serve                                          # the project's server, at :8080 (ATLAS_TOKEN says who may upload)

package/dist/core/src/lint.js

@@ -2,6 +2,7 @@ import { ChartGraph } from './graph.js';
 import { composeCharts } from './spec/compose.js';
 import { invokesOf, walkStates } from './spec/types.js';
 const STATE_KEYS = new Set(['id', 'initial', 'type', 'meta', 'states', 'on', 'invoke', 'description']);
+const TRANSITION_KEYS = new Set(['target', 'meta']);
 const INVOKE_KEYS = new Set(['src', 'id', 'onDone']);
 const REQUIRED_META = ['description'];
 const FORBIDDEN = ['entry', 'exit', 'actions', 'assign', 'after', 'always', 'context', 'guard', 'cond', 'delay', 'output', 'onError'];
@@ -26,7 +27,7 @@ function checkShape(node, name, requiredMeta, out) {
             continue;
         }
         for (const key of Object.keys(t)) {
-            if (key !== 'target')
+            if (!TRANSITION_KEYS.has(key))
                 out.push({ rule: 'pure', message: `${name} --${event}-->: "${key}" is not allowed (no guards, no actions)` });
         }
     }
@@ -47,7 +48,10 @@ function sanitized(bundle) {
             if (STATE_KEYS.has(key))
                 out[key] = value;
         if (node.on) {
-            out['on'] = Object.fromEntries(Object.entries(node.on).map(([event, t]) => [event, typeof t === 'string' ? t : { target: t.target }]));
+            out['on'] = Object.fromEntries(Object.entries(node.on).map(([event, t]) => [
+                event,
+                typeof t === 'string' ? t : { target: t.target, ...('meta' in t ? { meta: t.meta } : {}) }
+            ]));
         }
         if (node.states)
             out['states'] = Object.fromEntries(Object.entries(node.states).map(([k, v]) => [k, clean(v)]));

package/dist/core/src/spec/types.d.ts

@@ -18,7 +18,10 @@
  */
 /** The object form of a transition. `target` is a state name, optionally prefixed with `#` (a reference by name across the composed product). */
 export type TransitionConfig = {
+    /** The destination state, optionally prefixed with `#`. */
     target: string;
+    /** Declarative provenance or business metadata; ignored while executing the chart. */
+    meta?: Record<string, unknown>;
 };
 /** An `invoke` that runs another chart inside a state. It is never executed: `composeCharts` inlines the child chart statically. */
 export type InvokeConfig = {
@@ -84,7 +87,7 @@ export type StateConfig = {
     type?: 'parallel' | 'final';
     meta?: StateMeta;
     states?: Record<string, StateConfig>;
-    /** Event name (exact business wording) to its transition: a target string or `{ target }`. */
+    /** Event name (exact business wording) to its transition: a target string or `{ target, meta? }`. */
     on?: Record<string, TransitionConfig | string>;
     /** Child chart(s) that run inside this state. */
     invoke?: InvokeConfig | InvokeConfig[];

package/dist/schema/src/spec.d.ts

@@ -144,9 +144,10 @@ export declare const StateMetaSchema: z.ZodObject<{
 }, z.core.$strip>;
 /** A parsed `StateMetaSchema` value. */
 export type StateMeta = z.infer<typeof StateMetaSchema>;
-/** The target of an event transition: a state name (or `#id`) written as a string, or an object with `target`. */
+/** The target of an event transition: a state name (or `#id`) written as a string, or an object with `target` and optional declarative `meta`. */
 export declare const TransitionTargetSchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
     target: z.ZodString;
+    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>]>;
 /** Kinds of state in the composed map: `atomic`, `compound`, `parallel`, `final`. */
 export declare const STATE_TYPES: readonly ["atomic", "compound", "parallel", "final"];

package/dist/schema/src/spec.js

@@ -73,10 +73,13 @@ export const StateMetaShape = {
 };
 /** `StateMetaShape` with every field optional: the `meta` of a state or of a whole chart. */
 export const StateMetaSchema = z.object(StateMetaShape).partial();
-/** The target of an event transition: a state name (or `#id`) written as a string, or an object with `target`. */
+/** The target of an event transition: a state name (or `#id`) written as a string, or an object with `target` and optional declarative `meta`. */
 export const TransitionTargetSchema = z.union([
     z.string().min(1),
-    z.object({ target: z.string().min(1) })
+    z.object({
+        target: z.string().min(1),
+        meta: z.record(z.string(), z.unknown()).optional()
+    })
 ]);
 /** Kinds of state in the composed map: `atomic`, `compound`, `parallel`, `final`. */
 export const STATE_TYPES = ['atomic', 'compound', 'parallel', 'final'];

package/docs/deploying.md

@@ -214,7 +214,15 @@ use a named `--store project=s3://… --write project` to put uploads in a share
 ### Run it
 
 **Railway (deploy an image, no repository or code changes).** Create a service from the Docker image
-`ghcr.io/crvouga/atlas:latest`.
+`ghcr.io/crvouga/atlas:latest`. Copy the URI below into Railway's image field:
+
+```text
+ghcr.io/crvouga/atlas:latest
+```
+
+For a specific revision, open a [CI run](https://github.com/crvouga/atlas/actions/workflows/ci.yml)'s
+**Summary → Atlas CI**: it includes the published commit image URI, immutable digest and whether that run
+updated `latest`. Pull request builds and failed publications are labelled accordingly.
 
 1. In Railway choose **New service → Docker image** and enter `ghcr.io/crvouga/atlas:latest`.
    Leave the start command unset: the image includes the server and the prebuilt viewer.
@@ -239,7 +247,56 @@ 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.
 
-**Docker.** The same published image works anywhere Docker runs. It already contains the client (the same
+### Deploy without authentication
+
+Use `ghcr.io/crvouga/atlas-insecure:latest` for a server that requires no sign-in or API token. It is built
+from the same commit, server and viewer as `ghcr.io/crvouga/atlas:latest`, with `ATLAS_INSECURE=true`
+to allow listening on the network without tokens. Anonymous callers have full read, publish and admin access.
+Anyone who discovers an unlisted URL can read reports, upload results and change settings; the URL is
+not access control.
+
+In Railway, create a **Docker image** service with:
+
+```text
+ghcr.io/crvouga/atlas-insecure:latest
+```
+
+Leave the start command unset. Attach a persistent volume at `/data`, set `RAILWAY_RUN_UID=0`, 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`
+for settings (leave the token field blank and choose **Load settings**).
+
+Verify anonymous reads and uploads without an Authorization header:
+
+```sh
+curl --fail https://YOUR-DOMAIN/readyz
+curl --fail https://YOUR-DOMAIN/api/server
+curl --fail 'https://YOUR-DOMAIN/api/checks?project=my-project' \
+  -H 'content-type: application/json' \
+  -d '{"producer":"smoke","checks":[{"id":"deployed","title":"Deployed","status":"passed"}]}'
+```
+
+Readiness returns HTTP 200, `/api/server` reports `"open":true` and `"role":"admin"`, and the upload returns
+HTTP 201. Configure a project with `ATLAS_STORE=https://YOUR-DOMAIN` and `ATLAS_PROJECT=my-project`;
+leave its `ATLAS_TOKEN` unset. Use the same publishing commands described in
+[sending results](#3-send-results-from-ci-and-from-laptops), omitting credentials.
+
+For local Docker:
+
+```sh
+docker run --pull always -p 8080:8080 -v atlas-data:/data ghcr.io/crvouga/atlas-insecure:latest
+```
+
+Both images publish full commit tags for pinning or rollback. A new GHCR package must be made Public
+once before Railway can pull without registry credentials; see
+[image publication](https://github.com/crvouga/atlas/blob/main/docs/releasing.md#server-image).
+
+### 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`:
 
 ```sh

package/docs/reference/core.md

@@ -2241,7 +2241,12 @@ See docs/statecharts.md
 #### `TransitionConfig`
 
 ```ts
-export type TransitionConfig = { target: string };
+export type TransitionConfig = {
+  /** The destination state, optionally prefixed with `#`. */
+  target: string;
+  /** Declarative provenance or business metadata; ignored while executing the chart. */
+  meta?: Record<string, unknown>;
+};
 ```
 
 The object form of a transition. `target` is a state name, optionally prefixed with `#` (a reference by name across the composed product).
@@ -2308,7 +2313,7 @@ export type StateConfig = {
   type?: 'parallel' | 'final';
   meta?: StateMeta;
   states?: Record<string, StateConfig>;
-  /** Event name (exact business wording) to its transition: a target string or `{ target }`. */
+  /** Event name (exact business wording) to its transition: a target string or `{ target, meta? }`. */
   on?: Record<string, TransitionConfig | string>;
   /** Child chart(s) that run inside this state. */
   invoke?: InvokeConfig | InvokeConfig[];

package/docs/reference/schema.md

@@ -1613,7 +1613,7 @@ A parsed `StateMetaSchema` value.
 export const TransitionTargetSchema = …
 ```
 
-The target of an event transition: a state name (or `#id`) written as a string, or an object with `target`.
+The target of an event transition: a state name (or `#id`) written as a string, or an object with `target` and optional declarative `meta`.
 
 #### `STATE_TYPES`
 

package/docs/server.md

@@ -56,6 +56,8 @@ ATLAS_STORE=http://127.0.0.1:5180 bunx atlas report publish --producer unit --ju
 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.
+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).
 
 ## Configuration
 

package/docs/statecharts.md

@@ -119,7 +119,8 @@ Atlas walks charts without running any code, so it executes only the parts of a
 are pure structure:
 
 - states, nesting (`initial`), `parallel` regions and `final` states;
-- event transitions, written as a target (`Opens: Open` or `{ target: '#Open' }`);
+- event transitions, written as a target (`Opens: Open` or `{ target: '#Open' }`), with
+  optional declarative metadata (`{ target: '#Open', meta: { source: ['specs/door.feature'] } }`);
 - `invoke` that names another chart (`src`, `id`, `onDone`), composed statically;
 - `meta`.
 

package/llms-full.txt

@@ -1008,6 +1008,8 @@ ATLAS_STORE=http://127.0.0.1:5180 bunx atlas report publish --producer unit --ju
 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.
+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).
 
 ## Configuration
 
@@ -1586,7 +1588,15 @@ use a named `--store project=s3://… --write project` to put uploads in a share
 ### Run it
 
 **Railway (deploy an image, no repository or code changes).** Create a service from the Docker image
-`ghcr.io/crvouga/atlas:latest`.
+`ghcr.io/crvouga/atlas:latest`. Copy the URI below into Railway's image field:
+
+```text
+ghcr.io/crvouga/atlas:latest
+```
+
+For a specific revision, open a [CI run](https://github.com/crvouga/atlas/actions/workflows/ci.yml)'s
+**Summary → Atlas CI**: it includes the published commit image URI, immutable digest and whether that run
+updated `latest`. Pull request builds and failed publications are labelled accordingly.
 
 1. In Railway choose **New service → Docker image** and enter `ghcr.io/crvouga/atlas:latest`.
    Leave the start command unset: the image includes the server and the prebuilt viewer.
@@ -1611,7 +1621,56 @@ 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.
 
-**Docker.** The same published image works anywhere Docker runs. It already contains the client (the same
+### Deploy without authentication
+
+Use `ghcr.io/crvouga/atlas-insecure:latest` for a server that requires no sign-in or API token. It is built
+from the same commit, server and viewer as `ghcr.io/crvouga/atlas:latest`, with `ATLAS_INSECURE=true`
+to allow listening on the network without tokens. Anonymous callers have full read, publish and admin access.
+Anyone who discovers an unlisted URL can read reports, upload results and change settings; the URL is
+not access control.
+
+In Railway, create a **Docker image** service with:
+
+```text
+ghcr.io/crvouga/atlas-insecure:latest
+```
+
+Leave the start command unset. Attach a persistent volume at `/data`, set `RAILWAY_RUN_UID=0`, 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`
+for settings (leave the token field blank and choose **Load settings**).
+
+Verify anonymous reads and uploads without an Authorization header:
+
+```sh
+curl --fail https://YOUR-DOMAIN/readyz
+curl --fail https://YOUR-DOMAIN/api/server
+curl --fail 'https://YOUR-DOMAIN/api/checks?project=my-project' \
+  -H 'content-type: application/json' \
+  -d '{"producer":"smoke","checks":[{"id":"deployed","title":"Deployed","status":"passed"}]}'
+```
+
+Readiness returns HTTP 200, `/api/server` reports `"open":true` and `"role":"admin"`, and the upload returns
+HTTP 201. Configure a project with `ATLAS_STORE=https://YOUR-DOMAIN` and `ATLAS_PROJECT=my-project`;
+leave its `ATLAS_TOKEN` unset. Use the same publishing commands described in
+[sending results](#3-send-results-from-ci-and-from-laptops), omitting credentials.
+
+For local Docker:
+
+```sh
+docker run --pull always -p 8080:8080 -v atlas-data:/data ghcr.io/crvouga/atlas-insecure:latest
+```
+
+Both images publish full commit tags for pinning or rollback. A new GHCR package must be made Public
+once before Railway can pull without registry credentials; see
+[image publication](https://github.com/crvouga/atlas/blob/main/docs/releasing.md#server-image).
+
+### 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`:
 
 ```sh
@@ -2668,7 +2727,8 @@ Atlas walks charts without running any code, so it executes only the parts of a
 are pure structure:
 
 - states, nesting (`initial`), `parallel` regions and `final` states;
-- event transitions, written as a target (`Opens: Open` or `{ target: '#Open' }`);
+- event transitions, written as a target (`Opens: Open` or `{ target: '#Open' }`), with
+  optional declarative metadata (`{ target: '#Open', meta: { source: ['specs/door.feature'] } }`);
 - `invoke` that names another chart (`src`, `id`, `onDone`), composed statically;
 - `meta`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crvouga/atlas",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Atlas: specs of any kind, reported as layered evidence. Publish checks from any runner (JUnit, CTRF, a script), combine them across nodes, branches, environments and backends, gate CI on the result, and run statecharts against the real app.",
   "license": "MIT",
   "type": "module",

package/packages/schema/schemas/state-node.schema.json

@@ -225,6 +225,13 @@
               "target": {
                 "type": "string",
                 "minLength": 1
+              },
+              "meta": {
+                "type": "object",
+                "propertyNames": {
+                  "type": "string"
+                },
+                "additionalProperties": {}
               }
             },
             "required": [