@xmachines/docs 6.1.0 → 7.1.0

package/contributing/deployment.md

@@ -8,11 +8,11 @@ This document describes how `@xmachines/xmachines-js` packages are built, versio
 
 All `@xmachines/*` packages are published to the **public npm registry** (`registry.npmjs.org`). Every package uses `"publishConfig": { "access": "public" }` so scoped packages are accessible without an npm org subscription. See the [Published Packages](#published-packages) table for the full list.
 
-| Target          | Config File                                        | Purpose                                                |
-| --------------- | -------------------------------------------------- | ------------------------------------------------------ |
-| npm registry    | `scripts/publish-release.mjs`, on the tag pipeline | Publish all public packages                            |
-| GitLab Releases | `scripts/publish-release.mjs`, on the tag pipeline | Attach tarball artifacts to the GitLab release tag     |
-| GitLab CI       | `.gitlab-ci.yml`                                   | Trigger builds, tests, and releases on push / MR / tag |
+| Target          | Config File                                       | Purpose                                                |
+| --------------- | ------------------------------------------------- | ------------------------------------------------------ |
+| npm registry    | `publish-release`, on the tag pipeline of a train | Publish the public packages of the train               |
+| GitLab Releases | `publish-release`, on the tag pipeline of a train | Attach tarball artifacts to the GitLab release tag     |
+| GitLab CI       | `.gitlab-ci.yml`                                  | Trigger builds, tests, and releases on push / MR / tag |
 
 The root `package.json` is marked `"private": true` and is **never published** to npm.
 
@@ -20,32 +20,38 @@ The root `package.json` is marked `"private": true` and is **never published** t
 
 ## Published Packages
 
-The following packages are published on every release (derived from the workspace scan in `release.config.mjs` — every non-private package that is not a demo):
-
-| Package                                                                                           | Directory                             |
-| ------------------------------------------------------------------------------------------------- | ------------------------------------- |
-| [`@xmachines/shared`](../api/@xmachines/shared/README.md)                                         | `packages/shared`                     |
-| [`@xmachines/play`](../api/@xmachines/play/README.md)                                             | `packages/play`                       |
-| [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)                                 | `packages/play-actor`                 |
-| [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md)                                   | `packages/play-atom`                  |
-| [`@xmachines/play-router`](../api/@xmachines/play-router/README.md)                               | `packages/play-router`                |
-| [`@xmachines/play-dom`](../api/@xmachines/play-dom/README.md)                                     | `packages/play-dom`                   |
-| [`@xmachines/play-dom-router`](../api/@xmachines/play-dom-router/README.md)                       | `packages/play-dom-router`            |
-| [`@xmachines/play-react`](../api/@xmachines/play-react/README.md)                                 | `packages/play-react`                 |
-| [`@xmachines/play-react-router`](../api/@xmachines/play-react-router/README.md)                   | `packages/play-react-router`          |
-| [`@xmachines/play-solid`](../api/@xmachines/play-solid/README.md)                                 | `packages/play-solid`                 |
-| [`@xmachines/play-solid-router`](../api/@xmachines/play-solid-router/README.md)                   | `packages/play-solid-router`          |
-| [`@xmachines/play-svelte`](../api/@xmachines/play-svelte/README.md)                               | `packages/play-svelte`                |
-| [`@xmachines/play-sveltekit-router`](../api/@xmachines/play-sveltekit-router/README.md)           | `packages/play-sveltekit-router`      |
-| [`@xmachines/play-svelte-spa-router`](../api/@xmachines/play-svelte-spa-router/README.md)         | `packages/play-svelte-spa-router`     |
-| [`@xmachines/play-tanstack-react-router`](../api/@xmachines/play-tanstack-react-router/README.md) | `packages/play-tanstack-react-router` |
-| [`@xmachines/play-tanstack-solid-router`](../api/@xmachines/play-tanstack-solid-router/README.md) | `packages/play-tanstack-solid-router` |
-| [`@xmachines/play-vue`](../api/@xmachines/play-vue/README.md)                                     | `packages/play-vue`                   |
-| [`@xmachines/play-vue-router`](../api/@xmachines/play-vue-router/README.md)                       | `packages/play-vue-router`            |
-| [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md)                               | `packages/play-xstate`                |
-| [`@xmachines/docs`](../README.md)                                                                 | `packages/docs`                       |
-
-**Example demo packages** (under `packages/*/examples/demo`) are **not published** to npm (`"npmPublish": false`) but are still packed into release tarballs and attached as GitLab release assets for testing.
+The release is in **trains**, each released on its own: `core`, `play` and `docs`. A train publishes every package under its paths that is not private, at the version of the train's release (`release.config.mjs`, `trains`):
+
+| Package                                                                                           | Directory                             | Train  |
+| ------------------------------------------------------------------------------------------------- | ------------------------------------- | ------ |
+| [`@xmachines/core`](../api/@xmachines/core/README.md)                                             | `packages/core`                       | `core` |
+| [`@xmachines/play`](../api/@xmachines/play/README.md)                                             | `packages/play`                       | `play` |
+| [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)                                 | `packages/play-actor`                 | `play` |
+| [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md)                                   | `packages/play-atom`                  | `play` |
+| [`@xmachines/play-dom`](../api/@xmachines/play-dom/README.md)                                     | `packages/play-dom`                   | `play` |
+| [`@xmachines/play-dom-router`](../api/@xmachines/play-dom-router/README.md)                       | `packages/play-dom-router`            | `play` |
+| [`@xmachines/play-pattern`](../api/@xmachines/play-pattern/README.md)                             | `packages/play-pattern`               | `play` |
+| [`@xmachines/play-react`](../api/@xmachines/play-react/README.md)                                 | `packages/play-react`                 | `play` |
+| [`@xmachines/play-react-router`](../api/@xmachines/play-react-router/README.md)                   | `packages/play-react-router`          | `play` |
+| [`@xmachines/play-router`](../api/@xmachines/play-router/README.md)                               | `packages/play-router`                | `play` |
+| [`@xmachines/play-solid`](../api/@xmachines/play-solid/README.md)                                 | `packages/play-solid`                 | `play` |
+| [`@xmachines/play-solid-router`](../api/@xmachines/play-solid-router/README.md)                   | `packages/play-solid-router`          | `play` |
+| [`@xmachines/play-svelte`](../api/@xmachines/play-svelte/README.md)                               | `packages/play-svelte`                | `play` |
+| [`@xmachines/play-svelte-spa-router`](../api/@xmachines/play-svelte-spa-router/README.md)         | `packages/play-svelte-spa-router`     | `play` |
+| [`@xmachines/play-sveltekit-router`](../api/@xmachines/play-sveltekit-router/README.md)           | `packages/play-sveltekit-router`      | `play` |
+| [`@xmachines/play-tanstack-react-router`](../api/@xmachines/play-tanstack-react-router/README.md) | `packages/play-tanstack-react-router` | `play` |
+| [`@xmachines/play-tanstack-router`](../api/@xmachines/play-tanstack-router/README.md)             | `packages/play-tanstack-router`       | `play` |
+| [`@xmachines/play-tanstack-solid-router`](../api/@xmachines/play-tanstack-solid-router/README.md) | `packages/play-tanstack-solid-router` | `play` |
+| [`@xmachines/play-url`](../api/@xmachines/play-url/README.md)                                     | `packages/play-url`                   | `play` |
+| [`@xmachines/play-view`](../api/@xmachines/play-view/README.md)                                   | `packages/play-view`                  | `play` |
+| [`@xmachines/play-vue`](../api/@xmachines/play-vue/README.md)                                     | `packages/play-vue`                   | `play` |
+| [`@xmachines/play-vue-router`](../api/@xmachines/play-vue-router/README.md)                       | `packages/play-vue-router`            | `play` |
+| [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md)                               | `packages/play-xstate`                | `play` |
+| [`@xmachines/docs`](../README.md)                                                                 | `packages/docs`                       | `docs` |
+
+Every package of `packages/play-*` that is not private is on the `play` train. [`@xmachines/shared`](../api/@xmachines/shared/README.md) is private: it holds the configs every package is built with, and no train publishes it.
+
+**Example demo packages** (under `packages/*/examples/*`, every one but the `shared` packages) are private and **not published** to npm, but the `play` train packs them beside its packages and attaches them to its GitLab release as assets for testing. It also packs the shared package of the demos, `packages/play-actor/examples/shared`, because each demo depends on it and no registry holds it.
 
 Each published package includes only the directories listed in its `files` field: `dist`, `README.md`, and `LICENSE` (or equivalent for packages without a compilation step).
 
@@ -57,13 +63,14 @@ Each published package includes only the directories listed in its `files` field
 
 Pipeline runs are triggered by `.gitlab-ci.yml` under the following conditions:
 
-| Trigger                                          | Pipeline runs                                      |
-| ------------------------------------------------ | -------------------------------------------------- |
-| Push to `main` / `rc` / `beta` / `alpha` / `pre` | Full pipeline; the release job waits to be started |
-| Merge request                                    | Full pipeline, no release job                      |
-| Web / API / trigger / parent pipeline            | Full pipeline                                      |
+| Trigger                                                   | Pipeline runs                                      |
+| --------------------------------------------------------- | -------------------------------------------------- |
+| Push to `main` / `next` / `rc` / `beta` / `alpha` / `pre` | Full pipeline; the release jobs wait to be started |
+| Merge request                                             | Full pipeline, no release job                      |
+| Web / API / trigger / parent pipeline                     | Full pipeline                                      |
+| A release tag, `<train>-v<version>`                       | `publish-release` alone, which publishes the train |
 
-No rule admits a tag pipeline, so pushing a tag runs nothing.
+No rule admits another tag, so pushing one runs nothing.
 
 The pipeline includes two reusable CI components, both pinned in `.gitlab-ci.yml` — which is the version to trust, rather than a number repeated here:
 
@@ -76,15 +83,15 @@ The `node-build` job runs one command:
 pnpm run build           # vite build (JavaScript) && tsc --build (declarations)
 ```
 
-It runs no test. The `test` job owns the unit suite, so `node-build` skips its own with `NODE_TEST_ARGS`. It also builds no documentation: the `docs` job below does that.
+It runs no test. The `test:dist` job owns the unit suite, so `node-build` skips its own with `NODE_TEST_ARGS`. It also builds no documentation: the `docs` job below does that.
 
-Coverage comes from the `test` job, through the regex:
+Coverage comes from the `test:dist` job, through the regex:
 
 ```
 /All files[^|]*\|[^|]*\s+([\d\.]+)/
 ```
 
-That job publishes the JUnit results as `reports/test-results.xml` and the Cobertura coverage as `reports/cobertura-coverage.xml`. `vitest.config.ts` names both paths, and `COVERAGE_REPORTS_DIR` points them at `reports/`.
+That job runs the suites on the `dist/` of `node-build`, and it maps the coverage back to `src/` through the source maps. It publishes the JUnit results as `reports/test-results.xml` and the Cobertura coverage as `reports/cobertura-coverage.xml`. `vitest.config.ts` names both paths, and `COVERAGE_REPORTS_DIR` points them at `reports/`.
 
 ### Docs Job
 
@@ -112,42 +119,30 @@ To run the same check on your machine, run `pnpm run docs` and then `pnpm run te
 
 ### Release Job Detail
 
-The `semantic-release` CI job is configured with:
-
-```yaml
-semantic-release:
-    id_tokens:
-        NPM_ID_TOKEN:
-            aud: "npm:registry.npmjs.org"
-    artifacts:
-        when: always
-        expire_in: 1 week
-        paths:
-            - dist/releases/*.tgz
-```
+The `semantic-release` job is the job of the `to-be-continuous/semantic-release` component, with its own rules: manual on every release branch, and a `resource_group` that runs one release at a time. One click releases every train: the job runs semantic-release once for each train that the pipeline's input `release-trains` names, all three by default, in the order of the trains of `release.config.mjs`: `core`, then `play`, then `docs`, whatever order they were ticked in. A train with no commit that releases it releases nothing, and the next one runs. A run that fails stops the job; retry it, and each train it released already has nothing left to release. To release some trains alone, tick them in the multi-select `release-trains` of **Run pipeline**, or set `RELEASE_TRAINS` as you start the job, as `docs`: the input is the default of the global variable `RELEASE_TRAINS`, which a CI/CD variable overrides, as a to-be-continuous component maps its inputs. A name of no train fails the job.
+
+The component turns `release.config.mjs` into `.releaserc.json`, of `RELEASE_TRAIN=docs`, whose run names every plugin of the others' runs too, and installs semantic-release and each plugin that the config names, globally. The config is therefore literals: it imports no plugin, and holds no top-level await. The job then removes `.releaserc.json`, so each run reads `release.config.mjs` of its own train.
 
-The job uses a GitLab OIDC id token (`NPM_ID_TOKEN`) scoped to `npm:registry.npmjs.org` rather than a static `NPM_TOKEN`.
+The job releases from the tip of its branch: a release of an earlier pipeline may have pushed a release commit since, and semantic-release releases nothing of a branch behind its remote. The job checks the tip out when every commit past its pipeline's commit is a release commit, and fails otherwise, as a branch that moved on needs the pipeline of its tip. Each run of a train then starts at the release commit of the run before it.
 
 The `semantic-release` command is called with `--no-ci` to allow it to run inside CI without triggering its own CI-environment mode.
 
 ### Release Smoke Test Job
 
-The `release-pack-smoke` job is defined in `.gitlab-ci.yml` and runs on the same trigger rules as other CI jobs (automatically on `main` pushes and tags, manually on MRs):
+The `release-pack-smoke` job runs automatically on `main` and in a merge train, and manually on a merge request:
 
 ```bash
 pnpm run build
-node scripts/release-pack-smoke.mjs
+semantic-release-trains-smoke
 ```
 
-`scripts/release-pack-smoke.mjs`:
+`semantic-release-trains-smoke`, of `@wtf/semantic-release-trains-publish`, reads the trains of `release.config.mjs` and:
 
-1. Asks `scripts/lib/release-packages.mjs` which packages a release publishes. `publish-release.mjs` and `release.config.mjs` ask the same module, so the three cannot disagree.
-2. For each publishable package: runs `npm pack --json` in the package directory.
-3. Creates a temporary directory, runs `npm init -y`, and installs the local tarball with `--ignore-scripts`.
-4. Asserts the install succeeds — any missing files, broken exports, or pack-time errors surface here.
-5. Cleans up temp directories and tarballs after each check.
+1. Packs every package of every train, and each private package of its `pack` globs, as the release packs it: each `workspace:` range resolved, the `source` export condition stripped. The globs name the demos, and the shared package of the demos, which each demo depends on and which no registry holds.
+2. Checks each tarball: every entry of its `files` present, no `source` condition left, and no file a `forbid` glob names, as a typecheck build.
+3. Installs each tarball in a temporary project, with every other package that it packed in place of the registry's, and imports each of its exports.
 
-This smoke test runs **before** the actual publish so packaging problems are caught in CI rather than on npm.
+The publish plugin runs the same check on the tag, of the tarballs it is about to publish, before the first publish.
 
 ---
 
@@ -155,117 +150,111 @@ This smoke test runs **before** the actual publish so packaging problems are cau
 
 ### Branch Model
 
-Releases are driven by commit history on the release branches:
+Releases are driven by the commit history of each train on the release branches:
 
-| Branch  | Channel          | Tag format       | Behaviour                     |
-| ------- | ---------------- | ---------------- | ----------------------------- |
-| `main`  | stable (default) | `v1.2.3`         | Full production release       |
-| `rc`    | `rc`             | `v1.2.3-rc.N`    | Release candidate pre-release |
-| `beta`  | `beta`           | `v1.2.3-beta.N`  | Beta pre-release              |
-| `alpha` | `alpha`          | `v1.2.3-alpha.N` | Alpha pre-release             |
-| `pre`   | `pre`            | `v1.2.3-pre.N`   | Pre-release                   |
+| Branch  | Channel          | Tag format (of `play`) | Behaviour                     |
+| ------- | ---------------- | ---------------------- | ----------------------------- |
+| `main`  | stable (default) | `play-v1.2.3`          | Full production release       |
+| `next`  | `next`           | `play-v1.2.3-next.N`   | The line on XState 6          |
+| `rc`    | `rc`             | `play-v1.2.3-rc.N`     | Release candidate pre-release |
+| `beta`  | `beta`           | `play-v1.2.3-beta.N`   | Beta pre-release              |
+| `alpha` | `alpha`          | `play-v1.2.3-alpha.N`  | Alpha pre-release             |
+| `pre`   | `pre`            | `play-v1.2.3-pre.N`    | Pre-release                   |
 
 The channel becomes the npm dist-tag verbatim, which is why none of them contains a slash: npm reads a slash in a version selector as a GitHub shorthand, so such a tag cannot be installed.
 
-Tag format is `v${version}` (e.g., `v1.0.0-beta.46`).
+The tag format of a train is `<train>-v${version}`. Every train continued from 7.0.0, the last release of one version for everything: `core-v7.0.0`, `play-v7.0.0` and `docs-v7.0.0` name its commit.
 
-### Prepare Phase
+#### `next` after a release of `main`
 
-Before any package is published, semantic-release runs a sequence of `@semantic-release/exec` prepare steps defined in `release.config.mjs`:
+`main` stays on XState 5 and merges into `next`. **After each release on `main`, merge `main` into `next`**, by a merge request from `main` to `next`, kept unsquashed, that keeps `main` (its source branch is never deleted).
 
-```bash
-corepack enable
-pnpm install --frozen-lockfile
-node scripts/set-workspace-versions.mjs ${nextRelease.version}
-pnpm run build
-pnpm --filter @xmachines/docs run typedoc --gitRevision v${nextRelease.version}
-pnpm --filter @xmachines/docs run format
-git add -A packages/docs/api packages/docs/examples/@xmachines packages/docs/examples/README.md
-```
+A prerelease of `next` builds on the last release of its train that `next` reaches: from `play-v7.0.0`, a breaking change on `next` releases `play` `8.0.0-next.1`, then `8.0.0-next.2`, and so on. That claims 8.0.0 for the line of XState 6. When `main` takes that major first, by a breaking release of the same train, `play` 8.0.0 is something else, and `next` would go on with `8.0.0-next.N`, which sorts below 8.0.0 and does not hold it. The merge of `main` corrects it: `play-v8.0.0` is then reachable from `next`, the breaking change of `next` is not in it, and the next prerelease is `9.0.0-next.1`. A user of `@next` sees the major move from 8 to 9, as semver allows. The same holds for `core` and `docs`, each by its own version.
 
-Step by step:
+### Which Commits Release a Train
 
-1. **Enable corepack** — activates the pinned pnpm version.
-2. **Install** — `pnpm install --frozen-lockfile` installs the exact dependency versions recorded in the lockfile.
-3. **Sync versions** — `scripts/set-workspace-versions.mjs` sets the same release version across every `package.json` in the workspace (root + all packages), including cross-package workspace dependency ranges.
-4. **Build** — runs `vite build && tsc --build` to produce compiled `dist/` output — JavaScript then declarations — in all packages.
-5. **Generate API docs** — runs TypeDoc to regenerate `packages/docs/api/` and `packages/docs/examples/@xmachines/` at the release git revision. TypeDoc also rewrites the demo lists of `packages/docs/examples/README.md`.
-6. **Format docs** — runs `oxfmt` on the docs package to ensure consistent formatting.
-7. **Stage the generated docs** — `git add -A packages/docs/api packages/docs/examples/@xmachines packages/docs/examples/README.md`. The git plugin stages what `git ls-files -m -o` reports, and that never reports a DELETION. A page that TypeDoc removed, because an export was renamed or deleted, therefore stayed in git forever while the docs tarball packed from the working tree was correct. `git add -A` stages the removals, and the git plugin commits the index.
+A commit counts for a train when it changes a file under the train's paths, or one of its `shared` files. A breaking change of `core` therefore makes a major release of `core` alone.
 
-### Publish Phase
+- `core`: `packages/core`.
+- `play`: `packages/play` and `packages/play-*`, the demos too.
+- `docs`: `packages/docs`, and every file of `core` and of `play`: the reference documents them, so a release of either is a release of `docs`. Release `docs` last.
 
-semantic-release publishes nothing. It stops at the tag, and `scripts/publish-release.mjs` publishes from a pipeline that runs ON that tag:
+The files every package is built with count for every train: the root `package.json`, `pnpm-lock.yaml`, `pnpm-workspace.yaml`, `tsconfig.json`, `vite.config.ts`, and `packages/shared`.
 
-```bash
-node scripts/publish-release.mjs
-```
+Release the trains in order: `core`, then `play`, then `docs`. `play` depends on `core`, and `dependencies: "fail"` of the config fails a run of `play` while `core` has commits that would release and are not released: its publish would pin `core`'s last release, without what those commits changed. The job runs them in that order; one of the input `play` alone fails so. `docs` depends on both by the `dependsOn` of its train, as its package depends on neither, and fails so too: its reference would show their old version badges until its next release.
 
-The tag pipeline is what makes the provenance attestation meaningful. npm records the commit of the pipeline in the attestation. On a tag pipeline that commit IS the commit that the tag names, and it is the commit whose manifests declare this version. A publish from the branch pipeline attests the PARENT of the release commit instead: a revision that the tag does not name, and whose manifests still carry the previous version.
+### Branch Phase
 
-The script pins the internal dependencies, strips the `source` export condition, packs every workspace package into `dist/releases/`, publishes each publishable tarball with `--provenance` under the dist-tag of the version, and verifies that every one reached the registry. It then creates the GitLab release with the tarballs attached, and it restores the working tree.
+The job of a train runs these plugins, in this order:
 
-The script is idempotent. It skips every package that the registry already serves at this version, so one retry of the job finishes a run that died partway — which is how the publish of 1.1.0 recovered from a credential that expired mid-run. Nothing to untag, nothing to force-push.
+1. **The analyzer and the notes generator**, each wrapped by an entry of `@wtf/semantic-release-trains` (`wrap`), which gives it the train's commits alone. Each entry of the trains plugin also checks the trains: no file on two of them, and the trains the train depends on released. `type!:` is a breaking change, by `parserOpts` at the root of the config.
+2. **`@semantic-release/changelog`** writes the train's changelog, the `CHANGELOG.md` of its first path: `packages/core/CHANGELOG.md`, `packages/play/CHANGELOG.md`, `packages/docs/CHANGELOG.md`. The root `CHANGELOG.md` holds the history up to 7.0.0.
+3. **`@wtf/semantic-release-replace`** writes the version into the badge of each README of the train, by the `badge` template at the root of the config: a RegExp of the badge of shields.io, its version written as `shields` escapes it. `tests/readme-badges.test.ts` holds the template to every badge of the READMEs.
+4. **Of `docs` alone**, the reference: `corepack enable`, `pnpm install --frozen-lockfile`, `pnpm run build`, TypeDoc at the revision `docs-v${nextRelease.version}`, and `oxfmt` of the docs package, each a `@semantic-release/exec` step. Then an entry of `@wtf/semantic-release-trains` of `generated: true` stages the trees TypeDoc writes, deletions too: the git plugin stages what `git ls-files -m -o` reports, which never reports a deletion, so a page of an export that was renamed or removed would stay in git for ever.
+5. **`@semantic-release/git`** commits the changelog, the READMEs of the train, and of `docs` the reference (`packages/docs/api/**`, `packages/docs/examples/@xmachines/**` and the demo lists of `packages/docs/examples/README.md`), as:
 
-### Post-Release Phase
+    ```
+    chore(release): <train> <version>
+    ```
 
-This phase runs on the branch, BEFORE the tag pipeline publishes.
+    The release notes are NOT interpolated into the message. `@semantic-release/git` runs `git commit -m <message>`, and the notes of a long release overflow the argument limit of the OS. The notes land in the changelog, which the same commit carries.
 
-1. **`@semantic-release/git`** commits updated files back to the repository:
-    - `CHANGELOG.md`
-    - `package.json`, `pnpm-lock.yaml` and `pnpm-workspace.yaml` (root)
-    - The `package.json` of every scanned package, and the `README.md` of every one — the release stamps the version badge of a README at the same moment as the manifest
-    - `packages/docs/api/**` (generated API documentation)
-    - `packages/docs/examples/@xmachines/**` (generated demo documentation)
-    - `packages/docs/examples/README.md` (TypeDoc rewrites its demo lists)
+    The message carries no `[skip ci]`. The release commit needs no pipeline of its own, but the TAG that points at it does: that pipeline is where the publish happens. A `workflow:` rule skips the branch pipeline of the commit instead.
 
-    The manifest list and the README list both come from the workspace scan, and not from a glob written by hand, so a package that a new `pnpm-workspace` pattern adds cannot be published while its manifest stays behind in git. A test asserts that every scanned package appears in both lists.
+6. semantic-release pushes the tag `<train>-v<version>`. It publishes nothing.
 
-    Commit message format:
+### Publish Phase
 
-    ```
-    chore(release): <version>
-    ```
+The tag's pipeline builds the tagged commit, and its `publish-release` job runs `semantic-release-trains-tag`, of `@wtf/semantic-release-trains`. It runs semantic-release's own config, plugins and branches for the tag, with its version and its channel, and the plugins of the tag's run of `release.config.mjs`:
 
-    The release notes are NOT interpolated into the message. `@semantic-release/git` runs `git commit -m <message>`, and the notes of the first stable release aggregate about 1600 commits — an `-m` value of several megabytes overflows the argument limit of the OS. The notes land in `CHANGELOG.md`, which the same commit carries.
+1. **The notes generator**, on the train, writes the notes again of the same commits.
+2. **`@wtf/semantic-release-trains-publish`** packs each package of the train into `dist/releases/`, the demos too, with each `workspace:` range resolved (a package of the same train to the release's version, one of another train to that train's last release) and the `source` export condition stripped; runs the smoke test of the tarballs; and publishes each package that is not private, in the order of their dependencies, under the dist-tag of the channel, with provenance. `NPM_DIST_TAG` overrides the dist-tag for a one-off.
+3. **`@semantic-release/gitlab`** creates the GitLab release of the tag, its notes those of the release, its assets every tarball of `dist/releases/` — after the publish succeeded, so a release entry never advertises a tarball that npm refused.
 
-    The message carries no `[skip ci]`. The release commit needs no pipeline of its own, but the TAG that points at it does: that pipeline is where the publish happens.
+The tag pipeline is what makes the provenance attestation meaningful. npm records the commit of the pipeline in the attestation. On a tag pipeline that commit IS the commit that the tag names. A publish from the branch pipeline attests the PARENT of the release commit instead: a revision that the tag does not name.
 
-2. **The git plugin pushes the commit and the tag.** semantic-release stops there. The GitLab release entry, with every `dist/releases/*.tgz` attached, is created later by `scripts/publish-release.mjs` on the tag pipeline — after the publish succeeded, so a release entry never advertises a tarball that npm refused.
+The job is idempotent. It skips every package that the registry already serves at this version, so one retry of the job finishes a run that died partway. Nothing to untag, nothing to force-push. A version below the one its dist-tag points at publishes nothing, so a retry of an older release's job moves no dist-tag back.
 
 ---
 
-## Version Synchronisation
+## Versions
 
-All packages in the monorepo share a **single version** at all times. This is enforced during release by `scripts/set-workspace-versions.mjs`, which:
+No version is written into git. Every `package.json` holds `0.0.0-development`, and each `@xmachines/*` dependency of the workspace is `workspace:*` within a train, `workspace:^` across trains. The tag is the version of a train, and the publish writes it into the manifests it packs, each `workspace:*` resolved to an exact version, so a package always depends on the exact version of a sibling of its train that was released with it. A dependency on a package of another train resolves to the range of that train's last release, by its tags, as `^7.0.0`: an exact pin would hold back each release of that train alone, a peer of it failing the install of the new version, and a dependency of it installing a second copy.
 
-- Sets `version` in every workspace `package.json` (including the root) to the new release version.
-- Rewrites `dependencies`, `devDependencies`, `peerDependencies`, and `optionalDependencies` ranges for any `@xmachines/*` workspace package to the exact new version (no `^` or `~` prefix — a strict pinned version is written).
+Why the versions stay out of git:
 
-This means packages always depend on the exact same version of sibling packages that was released together.
+- **`main` merges into `next`.** With versions in git, `main` holds 7.x and `next` holds 8.0.0-next.N in the same `package.json` files, and each merge of `main` conflicts in the version of every package that either line released since the last merge.
+- **The trains stay apart.** The release commit of a train touches its changelog and its READMEs alone: no two trains write the same file, and the release commit of one train never counts as a change of another.
+- **One source of truth.** The tag and npm hold the version, and nothing in git has to agree with them, so no release can stop between writing versions and tagging.
+
+What it costs:
+
+- A checkout says `0.0.0-development`: a package built from git, or packed by hand, carries no real version. Only the publish of the tag's pipeline writes one. No source reads its own version from its `package.json`; keep it so.
+- The README badges carry the version, by the release commit of the train, and the manifests do not.
+- `npm version`, and any tool that bumps a `package.json`, has nothing to do here.
 
 ---
 
 ## Credentials and Protected Variables
 
-| Variable                    | Source                                  | Purpose                                                                                                        |
-| --------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `NPM_ID_TOKEN`              | GitLab CI OIDC (auto-generated per job) | Authenticates `semantic-release` to npm registry via OIDC token exchange                                       |
-| `GL_TOKEN` / `GITLAB_TOKEN` | GitLab CI group variable (unprotected)  | Authenticates the git push back of semantic-release, and the GitLab release that `publish-release.mjs` creates |
-| `CI_JOB_TOKEN`              | GitLab CI built-in                      | Used by the `to-be-continuous` components for GitLab API calls                                                 |
+| Variable                    | Source                                  | Purpose                                                                                                    |
+| --------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `NPM_ID_TOKEN`              | GitLab CI OIDC (auto-generated per job) | Authenticates the publish of `publish-release` to npm registry via OIDC token exchange                     |
+| `GL_TOKEN` / `GITLAB_TOKEN` | GitLab CI group variable (protected)    | Authenticates the git push back of semantic-release, and the GitLab release that `publish-release` creates |
+| `CI_JOB_TOKEN`              | GitLab CI built-in                      | Used by the `to-be-continuous` components for GitLab API calls                                             |
 
 **No static npm token is committed to the repository.** The `NPM_ID_TOKEN` is a short-lived OIDC token generated for each CI job with audience `npm:registry.npmjs.org`.
 
 To publish packages, a maintainer must:
 
-1. Have push access to a release-eligible branch (`main`, `rc`, `beta`, `alpha`, `pre`). Only `main` is protected; see the branch model above for what changes if `GITLAB_TOKEN` is ever made a protected variable.
+1. Have push access to a release-eligible branch (`main`, `next`, `rc`, `beta`, `alpha`, `pre`). `GITLAB_TOKEN` is a protected variable, so each of these branches is protected, and a new release branch must be too. The tags of the trains (`core-v*`, `play-v*`, `docs-v*`) are protected, so the tag's pipeline gets the token for the GitLab release.
 2. Ensure the GitLab project CI/CD variables include the required tokens.
 
 ---
 
 ## Artifacts
 
-Release tarballs are stored as GitLab CI artifacts for **1 week** after each pipeline:
+Release tarballs are stored as artifacts of the `publish-release` job, with no expiry:
 
 ```
 dist/releases/*.tgz
@@ -273,7 +262,7 @@ dist/releases/*.tgz
 
 The same tarballs are attached to the GitLab Release entry as permanent downloadable assets. Tarballs are **not committed** to git (the `dist/` directory is gitignored).
 
-The post-release git commit **commits** the generated documentation (`packages/docs/api/` and `packages/docs/examples/@xmachines/`) to git. The same commit holds the demo lists that TypeDoc writes into the hand-written `packages/docs/examples/README.md`. It also holds `CHANGELOG.md`, which `@semantic-release/changelog` writes.
+The release commit of `docs` **commits** the generated documentation (`packages/docs/api/` and `packages/docs/examples/@xmachines/`) to git, with the demo lists that TypeDoc writes into the hand-written `packages/docs/examples/README.md`. The release commit of each train holds its changelog and its stamped READMEs.
 
 ---
 
@@ -295,7 +284,7 @@ There is no automated rollback mechanism. To revert a release:
     npm unpublish @xmachines/play@<bad-version>
     ```
 
-3. **Patch release** — push a `fix:` commit to `main` (or the relevant branch) to trigger a patch version release via semantic-release. This is the preferred long-term approach for production issues.
+3. **Patch release** — push a `fix:` commit to `main` (or the relevant branch) and release its train, a patch release by semantic-release. This is the preferred long-term approach for production issues.
 
 4. **GitLab Release** — delete or edit the GitLab Release entry via the GitLab UI or API to remove broken tarballs. This does not affect what is on npm.
 
@@ -368,50 +357,31 @@ Then, for EACH package:
 
 ## Recovering a Failed Release
 
-If the job dies partway (e.g. one package's trusted publisher isn't set up), some packages are published, the git tag is created, and the rest are missing. To finish the release:
-
-1. **Delete the release tag.** semantic-release creates the tag _before_ publishing, so a re-run while it exists is a no-op ([semantic-release#3178](https://github.com/semantic-release/semantic-release/issues/3178)):
-    ```bash
-    glab api --method DELETE "projects/xmachin-es%2Fxmachines-js/repository/tags/vX.Y.Z"
-    ```
-2. **Re-run the `semantic-release` job.**
-
-The config detects a staged-but-untagged version (a recovery re-run) and automatically demotes any package already on npm at that version to pack-only — re-packing it for the release assets but **not** re-publishing it — so the re-run publishes only what's missing, with no manual input. `SEMREL_SKIP_STEPS` (a regex matched against release step IDs) remains available as a manual override to force-skip specific steps.
+**A publish that failed** (e.g. one package's trusted publisher isn't set up) has pushed the tag, published some packages and left the rest missing. Fix the cause, then retry the `publish-release` job of the tag: every package npm already has is skipped, and the GitLab release is created once every package is published.
 
-> First fix the underlying cause before re-running — e.g. configure the missing trusted publisher — otherwise the same packages fail again.
+**A branch job that failed** before `@semantic-release/git` pushed the release commit is retried as it is. One that failed after, as of the push of the tag, cannot be: the retry runs behind the release commit, where semantic-release releases nothing. Push the missing tag by hand, at the release commit, with semantic-release's note of its channel (`refs/notes/semantic-release-<tag>`, `{"channels":[<channel>]}`, `null` of `main`'s) added to the tag's commit; its pipeline publishes it.
 
 ---
 
 ## Local Release Dry-Run (Manual)
 
-To preview what semantic-release would do without publishing:
+To preview what the release of a train would do, without a tag and without a publish:
 
 ```bash
-# Install dependencies first
-pnpm install --frozen-lockfile
-
-# Run semantic-release in dry-run mode
-pnpm exec semantic-release --dry-run --no-ci
+npm install --global semantic-release@25 @semantic-release/changelog @semantic-release/exec \
+  @semantic-release/git @semantic-release/gitlab @wtf/semantic-release-trains \
+  @wtf/semantic-release-replace @wtf/semantic-release-trains-publish
+RELEASE_TRAIN=play semantic-release --dry-run --no-ci
 ```
 
-To test package packaging locally (the same check run by `release-pack-smoke` in CI):
+To test the packaging locally (the same check run by `release-pack-smoke` in CI):
 
 ```bash
 pnpm run build
-node scripts/release-pack-smoke.mjs
-```
-
-This packs every publishable package, installs each tarball in a temporary project, and verifies the install succeeds.
-
-To manually version and pack a single package for local inspection:
-
-```bash
-# From the repo root
-pnpm --filter @xmachines/play run build
-pnpm --filter @xmachines/play pack
+semantic-release-trains-smoke
 ```
 
-**Do not run `npm publish` manually.** All publishing must go through semantic-release in CI to keep `CHANGELOG.md`, git tags, and npm versions in sync. [Bootstrapping a New Package](#bootstrapping-a-new-package) is the ONE exception, and it publishes a version that holds no code.
+**Do not run `npm publish` manually.** All publishing must go through the release in CI to keep the changelogs, git tags, and npm versions in sync. [Bootstrapping a New Package](#bootstrapping-a-new-package) is the ONE exception, and it publishes a version that holds no code.
 
 ---
 
@@ -422,6 +392,6 @@ The project does not include application runtime monitoring (no Sentry, Datadog,
 Post-release health checks:
 
 - **npm package availability** — verify new versions appear on `https://www.npmjs.com/package/@xmachines/<pkg>` after the pipeline completes.
-- **GitLab pipeline status** — monitor the `semantic-release` job in the GitLab CI UI for the release commit.
+- **GitLab pipeline status** — monitor the `semantic-release` job of the train, then the `publish-release` job of its tag.
 - **GitLab Releases page** — confirm the release tag and tarball assets appear at `https://gitlab.com/xmachin-es/xmachines-js/-/releases`.
-- **`packages/docs/api/` commit** — confirm the post-release git commit updated API docs on the target branch.
+- **`packages/docs/api/` commit** — confirm the release commit of `docs` updated the API docs on the target branch.

package/contributing/development.md

@@ -12,6 +12,7 @@ This guide covers everything you need to set up a local development environment,
 - [Code Style](#code-style)
 - [Writing Style](#writing-style-asd-ste100)
 - [Link a Package That You Name](#link-a-package-that-you-name)
+- [Code Examples in Documents](#code-examples-in-documents)
 - [Branch Conventions](#branch-conventions)
 - [PR Process](#pr-process)
 
@@ -88,7 +89,7 @@ packages/
 ├── play-pattern/                # The route pattern language: one parse, and the path it builds back
 ├── play-url/                    # The URL layer: the URLPattern API, a base path, framework params
 ├── play-actor/                  # The actor contract (PlayActor). It names no engine
-├── play-view/                   # The shared view half (Viewable, PlaySpec, the view store lifecycle)
+├── play-view/                   # The shared view half (Viewable, PlaySpec, the view session)
 ├── play-xstate/                 # XState v5 adapter (definePlayer, PlayerActor)
 ├── play-router/                 # Route extraction and RouterBridgeBase
 ├── play-dom/                    # Vanilla DOM renderer
@@ -142,6 +143,7 @@ All commands are run from the **repository root** unless otherwise noted.
 | `pnpm run test:browser:dist`               | Run Playwright browser tests on the build output                          |
 | `pnpm run test:coverage`                   | Run tests with V8 coverage reporting                                      |
 | `pnpm run test:browser:coverage`           | Run browser tests with coverage reporting                                 |
+| `pnpm run test:docs:examples`              | Compile and run the code examples of the documentation                    |
 | `pnpm run test:build`                      | Complete type-check of every package and its tests (`tsconfig.test.json`) |
 | `pnpm run lint`                            | Lint all packages with oxlint                                             |
 | `pnpm run lint:fix`                        | Auto-fix lint issues                                                      |
@@ -197,7 +199,7 @@ React 18 and vue-router 4 are supported by intent — nothing known depends on 1
 
 [`@xmachines/play`](../api/@xmachines/play/README.md) holds `PlayError`, and the documentation sends a consumer to `err instanceof PlayError`. That check answers `false` for an error of the second copy. [`@xmachines/core`](../api/@xmachines/core/README.md) holds `BaseError`, the base of `PlayError`, and `err instanceof BaseError` fails in the same way.
 
-A dependency invites that second copy. `scripts/lib/workspace-deps.mjs` pins a `workspace:*` range to an EXACT version, so two packages of two releases name two versions, and an installer resolves both. A peer moves the choice to the consumer, who brings one copy. The `@xmachines/json-render-*` packages carry the same rule for the same reason.
+A dependency invites that second copy. The publish resolves a `workspace:*` range to an EXACT version, so two packages of two releases name two versions, and an installer resolves both. A peer moves the choice to the consumer, who brings one copy. The `@xmachines/json-render-*` packages carry the same rule for the same reason.
 
 Each of the three needs a `devDependency` beside the peer, because the workspace installs no peer. Without that entry a package resolves the specifier through the hoisting of another package, and it compiles until that other package stops declaring it.
 
@@ -429,7 +431,7 @@ Use `unknown` with type guards instead of `any`. Prefix unused locals/parameters
 
 1. Always use `.js` extensions in imports, even for TypeScript source files:
 
-    ```typescript
+    ```typescript fragment
     // ✅ Correct
     import { PlayError } from "./errors.js";
 
@@ -439,7 +441,7 @@ Use `unknown` with type guards instead of `any`. Prefix unused locals/parameters
 
 2. Use `import type` for type-only imports (required by `verbatimModuleSyntax`):
 
-    ```typescript
+    ```typescript fragment
     import type { RouteNode, RouteTree } from "../src/types.js";
     ```
 
@@ -495,6 +497,29 @@ Three places keep a plain code span:
 
 ---
 
+## Code Examples in Documents
+
+A reader copies a code example and expects it to work. Two tests therefore read every `ts`, `typescript` and `tsx` block of the hand-written markdown:
+
+- `tests/doc-examples/compile.test.ts` compiles each block against the source of the workspace. It writes the block into the package that can resolve its imports, and it uses the `tsconfig.json` of that package.
+- `tests/doc-examples/run.test.ts` runs each complete block in jsdom. A block is complete when it declares no value that the reader supplies, holds no JSX, and loads no package that needs a compiler of Solid, Vue or Svelte, the runtime of SvelteKit, or a test runner such as `vitest`. A type import loads nothing, so it does not count. A run fails on each `console.error` and `console.warn`, unless the block logs on purpose. The page holds the elements `#app`, `#root`, `#loading` and `#crashed`.
+
+Give an example of a call its imports, so that it compiles. Use `declare const` only for a value that the reader supplies, such as their machine or a DOM element. Two words after the language change what the tests do:
+
+| Fence              | Use it for                                                                     | Compiled | Run |
+| ------------------ | ------------------------------------------------------------------------------ | -------- | --- |
+| ` ```ts `          | An example that a reader can copy                                              | yes      | yes |
+| ` ```ts norun `    | An example that compiles, but runs only in a test or in a component            | yes      | no  |
+| ` ```ts fragment ` | A part of a larger file, such as one state of a machine, or a ✅/❌ comparison | no       | no  |
+
+GitHub, GitLab and TypeDoc read the first word of a fence alone, so the second word changes nothing on a rendered page.
+
+An example for a reader imports published packages alone. A private workspace package, such as a demo or [`@xmachines/shared`](../api/@xmachines/shared/README.md), fails the check, because a reader cannot install it. The contributor guides and the README of a private package can import one.
+
+Check one document with `DOC_EXAMPLES=<part of its path> pnpm vitest run tests/doc-examples/compile.test.ts`, and run its examples with `DOC_EXAMPLES=<part of its path> pnpm vitest run tests/doc-examples/run.test.ts`. `pnpm run test:docs:examples` runs both, for every document. The dist run leaves them out, and CI runs them in the `test:docs:examples` job.
+
+---
+
 ## Branch Conventions
 
 Use a `<type>/` prefix that matches the conventional commit type for the work being done:
@@ -517,7 +542,7 @@ Release branches are managed by the project maintainers:
 | `alpha` | Pre-release alpha channel |
 | `pre`   | Pre-release channel       |
 
-**Do not** manually version packages or create release branches — semantic-release owns the version, and a release is cut by starting its manual CI job.
+**Do not** manually version packages or create release branches — semantic-release owns the version of each train (`core`, `play`, `docs`), and a release is cut by starting the manual CI job of the train.
 
 ---
 
@@ -551,13 +576,13 @@ This project uses **Conventional Commits** — changelogs and version bumps are
 Breaking changes: append `!` after the type (`feat!:`) AND write a `BREAKING CHANGE:`
 footer. The two do different work, and neither one replaces the other:
 
-- The `!` decides the BUMP. `release.config.mjs` gives both semantic-release plugins a
-  `breakingHeaderPattern`, because the angular preset reads `!` not at all: without that
+- The `!` decides the BUMP. `release.config.mjs` gives every semantic-release plugin a
+  `breakingHeaderPattern`, at the root of the config, because the angular preset reads `!` not at all: without that
   pattern, `feat!: …` parses with no type, and a release made of nothing but such commits
   is no release.
 - The footer writes the NOTE. The changelog lists a breaking change from the footer alone,
   so a `!` commit with no footer bumps the major and tells a reader nothing about what
-  broke. Seven commits shipped that way once, and none of them appears in `CHANGELOG.md`.
+  broke. Seven commits shipped that way once, and none of them appears in the changelog.
 
 Write the footer as one paragraph that names the old form and the new one: