@xmachines/docs 7.0.0 → 8.0.0-next.1

package/api/@xmachines/shared/vite-aliases/functions/xmBuildOutputFile.md

@@ -6,7 +6,7 @@
 function xmBuildOutputFile(packageDir, sourceFile): string;
 ```
 
-Defined in: [vite-aliases.ts:359](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/shared/config/vite-aliases.ts#L359)
+Defined in: [vite-aliases.ts:359](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v8.0.0-next.1/packages/shared/config/vite-aliases.ts#L359)
 
 The file in `dist/` that the build writes for one source file of a package.
 

package/api/@xmachines/shared/vite-aliases/functions/xmCacheDir.md

@@ -6,7 +6,7 @@
 function xmCacheDir(importMetaUrl, name): string;
 ```
 
-Defined in: [vite-aliases.ts:495](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/shared/config/vite-aliases.ts#L495)
+Defined in: [vite-aliases.ts:495](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v8.0.0-next.1/packages/shared/config/vite-aliases.ts#L495)
 
 Returns the shared Vite `cacheDir` for this workspace package.
 

package/api/@xmachines/shared/vite-aliases/functions/xmOptimizeDeps.md

@@ -6,7 +6,7 @@
 function xmOptimizeDeps(include?): DepOptimizationOptions;
 ```
 
-Defined in: [vite-aliases.ts:448](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/shared/config/vite-aliases.ts#L448)
+Defined in: [vite-aliases.ts:448](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v8.0.0-next.1/packages/shared/config/vite-aliases.ts#L448)
 
 Returns the standard Vite `optimizeDeps` config for browser test projects.
 

package/api/@xmachines/shared/vite-aliases/functions/xmResolve.md

@@ -6,7 +6,7 @@
 function xmResolve(importMetaUrl, extra?): ResolveOptions & object;
 ```
 
-Defined in: [vite-aliases.ts:333](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/shared/config/vite-aliases.ts#L333)
+Defined in: [vite-aliases.ts:333](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v8.0.0-next.1/packages/shared/config/vite-aliases.ts#L333)
 
 Full Vite `resolve` config for @xmachines/* workspace packages.
 

package/api/@xmachines/shared/vite-aliases/functions/xmSvelteRunes.md

@@ -6,7 +6,7 @@
 function xmSvelteRunes(): object;
 ```
 
-Defined in: [vite-aliases.ts:474](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/shared/config/vite-aliases.ts#L474)
+Defined in: [vite-aliases.ts:474](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v8.0.0-next.1/packages/shared/config/vite-aliases.ts#L474)
 
 Svelte plugin options that enforce runes mode for workspace sources only.
 
@@ -33,6 +33,6 @@ one and change the other.
 
 `object`
 
-| Name                      | Type                                                    | Defined in                                                                                                                  |
-| ------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `dynamicCompileOptions()` | (`data`) => \| \{ `runes`: `boolean`; \} \| `undefined` | [vite-aliases.ts:475](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/shared/config/vite-aliases.ts#L475) |
+| Name                      | Type                                                    | Defined in                                                                                                                              |
+| ------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `dynamicCompileOptions()` | (`data`) => \| \{ `runes`: `boolean`; \} \| `undefined` | [vite-aliases.ts:475](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v8.0.0-next.1/packages/shared/config/vite-aliases.ts#L475) |

package/api/@xmachines/shared/vite-aliases/functions/xmTestTarget.md

@@ -6,7 +6,7 @@
 function xmTestTarget(env?): XmTestTarget;
 ```
 
-Defined in: [vite-aliases.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/shared/config/vite-aliases.ts#L25)
+Defined in: [vite-aliases.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v8.0.0-next.1/packages/shared/config/vite-aliases.ts#L25)
 
 Reads the test target from the `XM_TEST_TARGET` environment variable.
 

package/api/@xmachines/shared/vite-aliases/type-aliases/XmTestTarget.md

@@ -6,7 +6,7 @@
 type XmTestTarget = "source" | "dist";
 ```
 
-Defined in: [vite-aliases.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/shared/config/vite-aliases.ts#L13)
+Defined in: [vite-aliases.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v8.0.0-next.1/packages/shared/config/vite-aliases.ts#L13)
 
 The code that a test run loads for each published `@xmachines/*` package.
 

package/api/@xmachines/shared/vitest/functions/defineXmBrowserConfig.md

@@ -6,7 +6,7 @@
 function defineXmBrowserConfig(importMetaUrl, overrides, options?): UserConfig;
 ```
 
-Defined in: [vitest.ts:224](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/shared/config/vitest.ts#L224)
+Defined in: [vitest.ts:224](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v8.0.0-next.1/packages/shared/config/vitest.ts#L224)
 
 Create a Vitest browser-mode config with XMachines workspace defaults.
 

package/api/@xmachines/shared/vitest/functions/defineXmVitestConfig.md

@@ -6,7 +6,7 @@
 function defineXmVitestConfig(importMetaUrl, overrides): UserConfig;
 ```
 
-Defined in: [vitest.ts:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/shared/config/vitest.ts#L76)
+Defined in: [vitest.ts:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v8.0.0-next.1/packages/shared/config/vitest.ts#L76)
 
 Create a Vitest config with XMachines workspace defaults.
 

package/api/@xmachines/shared/vitest/interfaces/XmBrowserConfigOptions.md

@@ -2,15 +2,15 @@
 
 # Interface: XmBrowserConfigOptions
 
-Defined in: [vitest.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/shared/config/vitest.ts#L174)
+Defined in: [vitest.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v8.0.0-next.1/packages/shared/config/vitest.ts#L174)
 
 Options for [defineXmBrowserConfig](../functions/defineXmBrowserConfig.md) that live outside the plain
 Vitest config overrides.
 
 ## Properties
 
-| Property                                           | Type                                     | Description                                                                                                                                                                                                                                                                                                                 | Defined in                                                                                                      |
-| -------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| <a id="property-base"></a> `base?`                 | `UserConfig`                             | Base Vite config to layer the browser test config on top of (typically a demo's `vite.config.ts`). When set, the base is expected to provide its own `resolve`/`plugins`, so the `cacheDir` and `resolve` defaults are not applied — mirroring the previous `mergeConfig(viteConfig, ...)` pattern in demo browser configs. | [vitest.ts:182](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/shared/config/vitest.ts#L182) |
-| <a id="property-optimizedeps"></a> `optimizeDeps?` | `string`[]                               | Extra package specifiers to pre-bundle via `xmOptimizeDeps` (e.g. `["@xmachines/json-render-vue", "@xmachines/json-render-vue/schema"]`). Ignored when `overrides.optimizeDeps` is set, which then replaces the default `xmOptimizeDeps()` wholesale.                                                                       | [vitest.ts:189](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/shared/config/vitest.ts#L189) |
-| <a id="property-resolve"></a> `resolve?`           | `Partial`\<`ResolveOptions` & `object`\> | Extra resolve options forwarded to `xmResolve` (e.g. `conditions` or additional `alias` entries). Not applied when `base` is set — the base config owns `resolve` in that layout.                                                                                                                                           | [vitest.ts:195](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/shared/config/vitest.ts#L195) |
+| Property                                           | Type                                     | Description                                                                                                                                                                                                                                                                                                                 | Defined in                                                                                                                  |
+| -------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-base"></a> `base?`                 | `UserConfig`                             | Base Vite config to layer the browser test config on top of (typically a demo's `vite.config.ts`). When set, the base is expected to provide its own `resolve`/`plugins`, so the `cacheDir` and `resolve` defaults are not applied — mirroring the previous `mergeConfig(viteConfig, ...)` pattern in demo browser configs. | [vitest.ts:182](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v8.0.0-next.1/packages/shared/config/vitest.ts#L182) |
+| <a id="property-optimizedeps"></a> `optimizeDeps?` | `string`[]                               | Extra package specifiers to pre-bundle via `xmOptimizeDeps` (e.g. `["@xmachines/json-render-vue", "@xmachines/json-render-vue/schema"]`). Ignored when `overrides.optimizeDeps` is set, which then replaces the default `xmOptimizeDeps()` wholesale.                                                                       | [vitest.ts:189](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v8.0.0-next.1/packages/shared/config/vitest.ts#L189) |
+| <a id="property-resolve"></a> `resolve?`           | `Partial`\<`ResolveOptions` & `object`\> | Extra resolve options forwarded to `xmResolve` (e.g. `conditions` or additional `alias` entries). Not applied when `base` is set — the base config owns `resolve` in that layout.                                                                                                                                           | [vitest.ts:195](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v8.0.0-next.1/packages/shared/config/vitest.ts#L195) |

package/contributing/architecture.md

@@ -4,7 +4,7 @@ XMachines Play implements the **Universal Player Architecture** — a layered, a
 
 ## System Overview
 
-XMachines JS is the JavaScript/TypeScript reference implementation of the **Universal Player Architecture** ([Play RFC](../rfc/play.md)). It is a monorepo of modular packages that strictly separates **business logic (the Actor)** from **infrastructure (router adapters and view renderers)**. An XState v5 state machine is the single source of truth; it owns all state, guards, and route validity. Infrastructure is passive: it observes atoms emitted by the Actor and proposes state changes via typed events. The Actor's guards make every navigation and transition decision. Communication across the boundary is exclusively through atoms — never subscriptions, callbacks, or direct state mutation. Five architectural invariants (documented in the [Play RFC](../rfc/play.md)) enforce this contract across the entire package graph.
+XMachines JS is the JavaScript/TypeScript reference implementation of the **Universal Player Architecture** ([Play RFC](../rfc/play.md)). It is a monorepo of modular packages that strictly separates **business logic (the Actor)** from **infrastructure (router adapters and view renderers)**. An XState v6 state machine is the single source of truth; it owns all state, guards, and route validity. Infrastructure is passive: it observes atoms emitted by the Actor and proposes state changes via typed events. The Actor's guards make every navigation and transition decision. Communication across the boundary is exclusively through atoms — never subscriptions, callbacks, or direct state mutation. Five architectural invariants (documented in the [Play RFC](../rfc/play.md)) enforce this contract across the entire package graph.
 
 ## Architectural Invariants
 
@@ -86,7 +86,7 @@ The diagram groups the packages by role. The build order is a separate view: eac
 | [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md)                                   | The atom primitives, isolated in one package            | `packages/play-atom/src/index.ts`                                   |
 | [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)                                 | `PlayActor`, and nothing else                           | `packages/play-actor/src/play-actor.ts`                             |
 | [`@xmachines/play-view`](../api/@xmachines/play-view/README.md)                                   | `Viewable`, `PlaySpec`, the shared view half            | `packages/play-view/src/view-types.ts`                              |
-| [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md)                               | XState v5 adapter: `definePlayer`, `PlayerActor`        | `packages/play-xstate/src/player-actor.ts`                          |
+| [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md)                               | XState v6 adapter: `definePlayer`, `PlayerActor`        | `packages/play-xstate/src/player-actor.ts`                          |
 | [`@xmachines/play-pattern`](../api/@xmachines/play-pattern/README.md)                             | The route pattern language: one parse, and `buildPath`  | `packages/play-pattern/src/pattern-grammar.ts`                      |
 | [`@xmachines/play-url`](../api/@xmachines/play-url/README.md)                                     | The URLPattern API, a base path, framework params       | `packages/play-url/src/url-pattern-utils.ts`                        |
 | [`@xmachines/play-router`](../api/@xmachines/play-router/README.md)                               | `RouteMap`, `RouterBridgeBase`, the provider lifecycle  | `packages/play-router/src/router-bridge-base.ts`                    |
@@ -202,7 +202,7 @@ flowchart TD
     C --> D --> E --> F
 ```
 
-The composition keeps each element of the outer view by reference, except an element that receives a child view. It prefixes each key of a child view with the id of its state. play-xstate keeps one result of `composeViews` for each tree of views of each machine. A context assign therefore emits the same `elements` and `viewParts` references, and the emit gate of `withView` compares the top-level fields alone. One walk derives every view: a machine without `outlets` is its simple case, in which the deepest view wins. When the `viewKey` stays and the `viewParts` value changes, `createViewStoreLifecycle` writes the authored keys that the store does not hold. play-dom then gives the new spec to `setSpec` of the incremental renderer, which keeps each node whose element did not change.
+The composition keeps each element of the outer view by reference, except an element that receives a child view. It prefixes each key of a child view with the id of its state. play-xstate keeps one result of `composeViews` for each tree of views of each machine. A change of the context therefore emits the same `elements` and `viewParts` references, and the emit gate of `withView` compares the top-level fields alone. One walk derives every view: a machine without `outlets` is its simple case, in which the deepest view wins. When the `viewKey` stays and the `viewParts` value changes, `createViewStoreLifecycle` writes the authored keys that the store does not hold. play-dom then gives the new spec to `setSpec` of the incremental renderer, which keeps each node whose element did not change.
 
 Each provider reads the view through `createViewSession` of play-view. The session resolves the store when the actor emits, when the host hands over a new actor or controlled store, and for a retry — never in a render. A provider binds the snapshot of the session to its framework: `useState` and a layout effect in play-react, a `shallowRef` in play-vue, a signal in play-solid, `$state.raw` in play-svelte, and a listener in play-dom. The subtree of the view is keyed on the `generation` of the store, and the error boundary resets on a new snapshot.
 
@@ -259,7 +259,7 @@ Extends `@xmachines/json-render-core` `Spec`. `deriveCurrentView` projects the m
 
 ### [`PlayerActor<TMachine>`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md)
 
-Concrete XState v5 actor. It extends XState's own `Actor` directly, and it implements [`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md). It receives the machine in its constructor, so an instance IS the actor rather than a wrapper around one. Bridges its own subscription to atoms. Exposes: `state`, `send()`, `start()`, `stop()`, `can()`.
+Concrete XState v6 actor. It extends XState's own `Actor` directly, and it implements [`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md). It receives the machine in its constructor, so an instance IS the actor rather than a wrapper around one. Bridges its own subscription to atoms. Exposes: `state`, `send()`, `start()`, `stop()`, `can()`.
 
 [`Routable`](../api/@xmachines/play-router/index/interfaces/Routable.md) and [`Viewable`](../api/@xmachines/play-view/index/interfaces/Viewable.md) are OPTIONAL capabilities, and the class implements neither. Each one is a mixin behind its own entry point — [`@xmachines/play-xstate/routing`](../api/@xmachines/play-xstate/README.md) and [`@xmachines/play-xstate/view`](../api/@xmachines/play-xstate/README.md) — and `compose` builds the class that an application needs:
 
@@ -340,7 +340,7 @@ Subscribe to a single atom with microtask coalescing and memory-safe cleanup. It
 
 ### [`formatPlayRouteTransitions(machineConfig)`](../api/@xmachines/play-xstate/with-routing/functions/formatPlayRouteTransitions.md)
 
-Crawls machine state configs looking for states with `meta.route` and auto-generates `play.route` transition handlers at the root machine level. Each generated transition targets the matching state, guards on `event.to === "#stateId"`, and assigns `event.params` and `event.query` to context. Returns the same config type `T` — directly usable by `setup().createMachine()`.
+Crawls machine state configs looking for states with `meta.route` and auto-generates `play.route` transition handlers at the root machine level. Each generated transition is a config object: it targets the matching state, it selects the event with `matches: { to: "#stateId" }`, and its `context` mapper returns a patch with `event.params` and `event.query`. The `play.route` entry is a list, with the generated transitions first and a transition of the machine last. Returns the same config type `T` — directly usable by `setup().createMachine()`.
 
 ## View Renderer Pattern
 
@@ -407,7 +407,7 @@ packages/
 ├── play-url/                   # Layer 2: the URL layer — the URLPattern API, a base path, framework params
 ├── play-view/                  # Layer 2: Viewable, PlaySpec, the view session, the context projection
 │
-├── play-xstate/                # Layer 4: Concrete XState v5 actor: definePlayer, PlayerActor
+├── play-xstate/                # Layer 4: Concrete XState v6 actor: definePlayer, PlayerActor
 │   └── src/
 │       ├── player-actor.ts              # PlayerActor — concrete actor
 │       ├── define-player.ts             # definePlayer factory
@@ -482,7 +482,7 @@ The **protocol layer** is `play`, `play-atom` and `play-actor`. `play` reads `co
 | URL layer (`play-url`)                | Protocol layer, `play-pattern`, `urlpattern-polyfill`   | Any other `@xmachines/*` package |
 | View half (`play-view`)               | Protocol layer, `@xmachines/json-render-core`           | Router adapters, framework code  |
 | Actor logic (`play-xstate`)           | Protocol layer, `play-pattern`, `xstate`                | View renderers, router adapters  |
-| Router infrastructure (`play-router`) | Protocol layer, `play-url`, `@statelyai/graph`          | View renderers                   |
+| Router infrastructure (`play-router`) | Protocol layer, `play-url`, `xstate`                    | View renderers                   |
 | Router adapters (`play-*-router`)     | `play-router`, protocol layer, framework router lib     | View renderers                   |
 | View renderers (`play-*`)             | Protocol layer, `play-view`, `@xmachines/json-render-*` | Router adapters                  |
 
@@ -541,13 +541,14 @@ import { InvalidEventError } from "@xmachines/play-xstate/errors";
 
 ```tsx
 import { createRootRoute, createRouter } from "@tanstack/react-router";
-import { setup } from "xstate";
+import { setup, types } from "xstate";
 import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
 import { formatPlayRouteTransitions, withRouting } from "@xmachines/play-xstate/routing";
 import { withView } from "@xmachines/play-xstate/view";
 import { extractMachineRoutes } from "@xmachines/play-router/xstate";
 import { createRouteMapFromTree, PlayRouterProvider } from "@xmachines/play-tanstack-react-router";
 import { PlayUIProvider, PlayRenderer, type PlayUIProviderProps } from "@xmachines/play-react";
+import type { ViewMeta } from "@xmachines/play-view";
 
 // 1. Define machine — meta.route declares virtual routes; meta.view declares UI specs
 const machineConfig = formatPlayRouteTransitions({
@@ -584,7 +585,10 @@ const machineConfig = formatPlayRouteTransitions({
 	},
 });
 
-const machine = setup({}).createMachine(machineConfig);
+// XState 6 types the `meta` of each state from `schemas.meta`
+const machine = setup({
+	schemas: { meta: types<{ route?: string; view?: ViewMeta }>() },
+}).createMachine(machineConfig);
 
 // 2. Build route map from machine definition (done once at startup)
 const routeTree = extractMachineRoutes(machine);

package/contributing/configuration.md

@@ -20,33 +20,6 @@ The dev container currently defines no workspace-specific environment variables;
 
 **Defined in:** the `test:dist` and `test:browser:dist` scripts of the root `package.json`. **Read by:** `xmTestTarget` of [`@xmachines/shared/vite-aliases`](../api/@xmachines/shared/README.md), which every config helper of that package calls. Do not set it by hand: run `pnpm run test:dist`. See [testing.md](testing.md#tests-on-the-build-output).
 
-### CI / Release Pipeline Variable
-
-| Variable            | Required | Default                      | Description                                                                                                                                                                         |
-| ------------------- | -------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `SEMREL_SKIP_STEPS` | Optional | `""` (empty — run all steps) | A single RegExp string matched against every semantic-release plugin step ID. Use `\|` for alternation to skip multiple steps. Set via the GitLab "Run pipeline" UI or API trigger. |
-
-**Defined in:** `.gitlab-ci.yml`, consumed by `release.config.mjs`.
-
-**Examples:**
-
-A step ID is the name of the plugin, and a name that the entry declares extends it: `@semantic-release/exec:build`.
-
-```bash
-# Skip one prepare step
-SEMREL_SKIP_STEPS="@semantic-release/exec:build$"
-
-# Skip every prepare step
-SEMREL_SKIP_STEPS="@semantic-release/exec"
-
-# Leave CHANGELOG.md alone
-SEMREL_SKIP_STEPS="@semantic-release/changelog"
-```
-
-A pattern that removes `@semantic-release/git` throws instead of running: semantic-release would still tag and push, and the tag would then name a commit that carries no version bump.
-
-The variable reaches the publish never. `scripts/publish-release.mjs` runs on the tag pipeline, outside semantic-release — see [deployment.md](deployment.md).
-
 ---
 
 ## Configuration Files
@@ -420,40 +393,42 @@ Provides the helpers used in all `vitest.config.ts` and `vite.config.ts` files:
 **Location:** `/release.config.mjs`
 **Tool:** [semantic-release](https://semantic-release.gitbook.io/) via `@semantic-release/*` plugins
 
-Defines the release branches and plugin chain used by the GitLab CI semantic-release job.
+Defines the trains, the release branches, and the plugins of each run: the run of a branch, of the `semantic-release` job of a train, and the run of a tag, of the `publish-release` job. The `to-be-continuous` semantic-release component turns it into `.releaserc.json` and installs each plugin it names, so it is literals: no import of a plugin, no top-level await.
 
 **Release branches:**
 
 | Branch  | Channel   | Pre-release |
 | ------- | --------- | ----------- |
 | `main`  | (default) | No          |
+| `next`  | `next`    | `next`      |
 | `rc`    | `rc`      | `rc`        |
 | `beta`  | `beta`    | `true`      |
 | `alpha` | `alpha`   | `alpha`     |
 | `pre`   | `pre`     | `pre`       |
 
-Only `main` is a protected branch today. That works because `GITLAB_TOKEN` — which the release needs, since `CI_JOB_TOKEN` can push neither the release commit nor the tag — is an _unprotected_ group variable and so reaches every one of these refs. If it is ever made protected, each of these branches has to be protected too, or the release fails in verify-conditions with `EGITNOPERMISSION` rather than at the registry.
+`GITLAB_TOKEN`, which the release needs (`CI_JOB_TOKEN` can push neither the release commit nor the tag, and creates no GitLab release), is a _protected_ group variable: it reaches only protected branches and protected tags. Every release branch is protected, `main` and the prerelease branches alike, and so are the tags of the trains, `core-v*`, `play-v*` and `docs-v*`. A release branch added to this table has to be protected too, or its release fails in verify-conditions with `EGITNOPERMISSION`.
+
+**Trains:** `core` (`packages/core`), `play` (`packages/play`, `packages/play-*`) and `docs` (`packages/docs`, with every file of `core` and `play` counting for it too). The build files of the root and `packages/shared` count for every train.
 
-**Tag format:** `v${version}`
+**Tag format:** `<train>-v${version}`, as `play-v7.1.0`.
 
-**Plugin order:**
+**Plugin order of a branch's run:**
 
-1. `@semantic-release/commit-analyzer` — determines version bump from conventional commits
-2. `@semantic-release/release-notes-generator` — builds release notes
-3. `@semantic-release/changelog` — writes `CHANGELOG.md`
-4. `@semantic-release/exec` steps (in order):
+1. `@semantic-release/commit-analyzer` and `@semantic-release/release-notes-generator`, each wrapped by an entry of `@wtf/semantic-release-trains` (`wrap`) — the version bump and the notes, of the train's commits alone; each entry of the trains plugin also checks the trains
+2. `@semantic-release/changelog` — writes the `CHANGELOG.md` of the train's first path
+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
+4. Of `docs` alone, `@semantic-release/exec` steps (in order):
     - `corepack` — `corepack enable`
     - `install` — `pnpm install --frozen-lockfile`
-    - `set-workspace-versions` — updates all `package.json` files to the new version
     - `build` — `pnpm run build`
-    - `typedoc` — `pnpm --filter @xmachines/docs run typedoc`
+    - `typedoc` — `pnpm --filter @xmachines/docs run typedoc --gitRevision docs-v${nextRelease.version}`
     - `format-docs` — `pnpm --filter @xmachines/docs run format`
-    - `stage-generated-docs` — `git add -A packages/docs/api packages/docs/examples/@xmachines packages/docs/examples/README.md`, so a page that TypeDoc deleted leaves git too
-5. `@semantic-release/git` — commits the changelog, the manifests, the READMEs and the generated docs (`api/`, `examples/@xmachines/` and the demo lists of `examples/README.md`), then pushes the commit and the tag
 
-The list ends there. semantic-release publishes nothing and creates no GitLab release: `scripts/publish-release.mjs` does both, on the pipeline of the tag. [deployment.md](deployment.md) states the whole sequence and the reason.
+    then an entry of `@wtf/semantic-release-trains` of `generated: true`, which stages the trees that TypeDoc writes, so a page that TypeDoc deleted leaves git too
+
+5. `@semantic-release/git` — commits the changelog, the READMEs of the train, and of `docs` the generated docs (`api/`, `examples/@xmachines/` and the demo lists of `examples/README.md`), then pushes the commit and the tag
 
-Any step above can be skipped with the `SEMREL_SKIP_STEPS` CI variable, which the CI / Release Pipeline Variable section at the top of this page states.
+**Plugin order of a tag's run:** the notes generator on the train; `@wtf/semantic-release-trains-publish`, which packs, smoke-tests and publishes the train's packages and packs its demos; `@semantic-release/gitlab`, the GitLab release with the tarballs. [deployment.md](deployment.md) states the whole sequence and the reason.
 
 ---
 
@@ -487,15 +462,14 @@ The only environment-specific distinction is between **local development** (dev
 
 ## Required vs Optional Settings Summary
 
-| Config                                                                     | Required to Work                        | Optional / Has Default        |
-| -------------------------------------------------------------------------- | --------------------------------------- | ----------------------------- |
-| `SEMREL_SKIP_STEPS`                                                        | No                                      | Default: `""` (run all steps) |
-| Root `tsconfig.json` `references`                                          | Yes — the whole build order             | —                             |
-| Per-package `references`                                                   | No — TypeScript drops them on `extends` | —                             |
-| Per-package `composite: true`                                              | Yes — required for project references   | —                             |
-| [`@xmachines/shared/tsconfig`](../api/@xmachines/shared/README.md) extends | Yes — all packages must extend it       | —                             |
-| [`@xmachines/shared/oxlint`](../api/@xmachines/shared/README.md) extends   | Yes — all packages must extend it       | —                             |
-| [`@xmachines/shared/oxfmt`](../api/@xmachines/shared/README.md) extends    | Yes — all packages must extend it       | —                             |
+| Config                                                                     | Required to Work                        | Optional / Has Default |
+| -------------------------------------------------------------------------- | --------------------------------------- | ---------------------- |
+| Root `tsconfig.json` `references`                                          | Yes — the whole build order             | —                      |
+| Per-package `references`                                                   | No — TypeScript drops them on `extends` | —                      |
+| Per-package `composite: true`                                              | Yes — required for project references   | —                      |
+| [`@xmachines/shared/tsconfig`](../api/@xmachines/shared/README.md) extends | Yes — all packages must extend it       | —                      |
+| [`@xmachines/shared/oxlint`](../api/@xmachines/shared/README.md) extends   | Yes — all packages must extend it       | —                      |
+| [`@xmachines/shared/oxfmt`](../api/@xmachines/shared/README.md) extends    | Yes — all packages must extend it       | —                      |
 
 ---