@xmachines/docs 1.0.0-beta.9 → 1.0.0

package/contributing/configuration.md

@@ -0,0 +1,368 @@
+<!-- generated-by: gsd-doc-writer -->
+
+# Configuration
+
+This document describes every configuration file, environment variable, and per-package override used by the `xmachines-js` monorepo.
+
+---
+
+## Environment Variables
+
+The monorepo itself has no application runtime that reads environment variables. The only variables are for the **dev container** tooling and the **CI/CD release pipeline**.
+
+### Dev Container Variables
+
+The dev container currently defines no workspace-specific environment variables; `.devcontainer/.env` (loaded via `env_file` in `.devcontainer/compose.yaml`) is available for local overrides if a future tool needs one. Copy `.devcontainer/.env.sample` to `.devcontainer/.env` to get started.
+
+### 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:**
+
+```bash
+# Skip one package publish
+SEMREL_SKIP_STEPS="@semantic-release/npm:packages/play-xstate"
+
+# Skip all demo publish steps
+SEMREL_SKIP_STEPS="examples/demo"
+
+# Skip all exec steps (build, typedoc, etc.)
+SEMREL_SKIP_STEPS="@semantic-release/exec"
+
+# Publish-only retry (skip build + demos)
+SEMREL_SKIP_STEPS="@semantic-release/exec|examples/demo"
+
+# Skip git commit and GitLab release
+SEMREL_SKIP_STEPS="@semantic-release/git|@semantic-release/gitlab"
+```
+
+---
+
+## Configuration Files
+
+### TypeScript — `tsconfig.json` (root)
+
+**Location:** `/tsconfig.json`
+
+The root TypeScript config is a **build coordinator only** — it compiles nothing itself. It lists every package and example via `references` so that `tsc --build` can determine the correct build order automatically.
+
+```json
+{
+	"files": [],
+	"references": [
+		// Layer 0 — no internal deps
+		{ "path": "./packages/play-signals" },
+		{ "path": "./packages/play" },
+		{ "path": "./packages/docs" },
+		// Layer 1 — depends on Layer 0
+		{ "path": "./packages/play-actor" },
+		// Layer 2 — depends on Layer 0 + 1
+		{ "path": "./packages/play-router" },
+		{ "path": "./packages/play-xstate" }
+		// ...etc.
+	]
+}
+```
+
+Every package must be listed here and must have `composite: true` in its own `tsconfig.json`.
+
+**Test build coordinator:** `/tsconfig.test.json` — identical structure but references each package's `tsconfig.test.json` for type-checking tests without emitting output.
+
+### TypeScript — Shared Base Config (`@xmachines/shared/tsconfig`)
+
+**Location:** `packages/shared/config/tsconfig.json`
+**Exported as:** `@xmachines/shared/tsconfig`
+
+All packages extend this base. Key compiler settings:
+
+| Setting                      | Value        | Notes                                                    |
+| ---------------------------- | ------------ | -------------------------------------------------------- |
+| `target`                     | `ESNext`     | Latest ECMAScript output                                 |
+| `module`                     | `NodeNext`   | ESM with `.js` extension imports required                |
+| `moduleResolution`           | `NodeNext`   | Matches `module` setting                                 |
+| `customConditions`           | `["source"]` | Resolves `@xmachines/*` to TypeScript source in dev/test |
+| `strict`                     | `true`       | Full strict mode                                         |
+| `noUnusedLocals`             | `true`       | Error on unused variables                                |
+| `noUnusedParameters`         | `true`       | Error on unused parameters                               |
+| `noFallthroughCasesInSwitch` | `true`       |                                                          |
+| `noImplicitReturns`          | `true`       |                                                          |
+| `noImplicitOverride`         | `true`       |                                                          |
+| `exactOptionalPropertyTypes` | `true`       |                                                          |
+| `declaration`                | `true`       | Emits `.d.ts` files                                      |
+| `declarationMap`             | `true`       | Emits `.d.ts.map` for IDE go-to-source                   |
+| `sourceMap`                  | `true`       |                                                          |
+| `verbatimModuleSyntax`       | `true`       | Preserves `import type`                                  |
+| `isolatedModules`            | `true`       |                                                          |
+| `removeComments`             | `false`      | Preserves JSDoc in output                                |
+
+**Per-package `tsconfig.json` pattern:**
+
+```json
+{
+	"extends": "@xmachines/shared/tsconfig",
+	"compilerOptions": {
+		"composite": true,
+		"rootDir": "./src",
+		"outDir": "./dist"
+	},
+	"references": [{ "path": "../dependency-package" }]
+}
+```
+
+**Test tsconfig (`@xmachines/shared/tsconfig-test`):**
+
+**Location:** `packages/shared/config/tsconfig.test.json`
+
+Test builds add `noEmit: true`, `allowImportingTsExtensions: true`, and `vitest/globals` types. Used by `pnpm run test:build` to type-check test files without emitting output.
+
+### Linting — `oxlint.config.ts` (root)
+
+**Location:** `/oxlint.config.ts`
+**Tool:** [oxlint](https://oxc.rs/docs/guide/usage/linter) `^1.62.0`
+**Run:** `pnpm run lint` / `pnpm run lint:fix`
+
+The root config extends the shared base (`@xmachines/shared/oxlint`) and adds workspace-level ignore patterns:
+
+```typescript
+// /oxlint.config.ts
+export default defineConfig({
+	extends: [sharedConfig],
+	ignorePatterns: [
+		".planning",
+		".opencode",
+		"node_modules",
+		"dist",
+		"build",
+		"coverage",
+		"docs/api/_media",
+		"*.min.js",
+		"CHANGELOG.md",
+	],
+});
+```
+
+**Shared base rules** (`packages/shared/config/oxlint.config.ts`):
+
+| Plugin                       | Category      | Severity                             |
+| ---------------------------- | ------------- | ------------------------------------ |
+| `typescript`                 | `correctness` | `error`                              |
+| `unicorn`                    | `suspicious`  | `warn`                               |
+| `import`                     | `perf`        | `warn`                               |
+| `import/no-cycle`            | —             | `error`                              |
+| `typescript/no-explicit-any` | —             | `error`                              |
+| `typescript/no-unused-vars`  | —             | `error` (ignores `_` prefixed names) |
+| `unicorn/filename-case`      | —             | `off`                                |
+
+**Per-package override pattern:**
+
+```typescript
+// packages/<name>/oxlint.config.ts
+import sharedConfig from "@xmachines/shared/oxlint";
+import { defineConfig } from "oxlint";
+
+export default defineConfig({
+	extends: [sharedConfig],
+	// add package-specific rules here
+});
+```
+
+### Formatting — `oxfmt.config.ts` (root)
+
+**Location:** `/oxfmt.config.ts`
+**Tool:** [oxfmt](https://oxc.rs/docs/guide/usage/formatter) `^0.47.0`
+**Run:** `pnpm run format` / `pnpm run format:check`
+
+The root config extends the shared base and adds workspace-level ignore patterns:
+
+```typescript
+// /oxfmt.config.ts
+export default defineConfig({
+	...sharedConfig,
+	ignorePatterns: [
+		...(sharedConfig.ignorePatterns ?? []),
+		".planning",
+		".opencode",
+		".agents",
+		".githuman",
+		".devcontainer",
+		"CHANGELOG.md",
+		"Thumbs.db",
+	],
+});
+```
+
+**Shared base format settings** (`packages/shared/config/oxfmt.config.ts`):
+
+| Setting              | Value   |
+| -------------------- | ------- |
+| `printWidth`         | `100`   |
+| `tabWidth`           | `4`     |
+| `useTabs`            | `true`  |
+| `semi`               | `true`  |
+| `singleQuote`        | `false` |
+| `trailingComma`      | `"all"` |
+| `insertFinalNewline` | `true`  |
+
+**JSON / YAML override** (applied via `overrides`):
+
+| Setting    | Value   |
+| ---------- | ------- |
+| `useTabs`  | `false` |
+| `tabWidth` | `2`     |
+
+### Editor — `.editorconfig`
+
+**Location:** `/.editorconfig`
+
+| Setting                    | `[*]`   | `[*.{json,yml,yaml}]` | `[*.md]` |
+| -------------------------- | ------- | --------------------- | -------- |
+| `indent_style`             | `tab`   | `space`               | —        |
+| `indent_size`              | `4`     | `2`                   | —        |
+| `end_of_line`              | `lf`    | —                     | —        |
+| `charset`                  | `utf-8` | —                     | —        |
+| `trim_trailing_whitespace` | `true`  | —                     | `false`  |
+| `insert_final_newline`     | `true`  | —                     | —        |
+
+### Testing — `vitest.config.ts` (root)
+
+**Location:** `/vitest.config.ts`
+**Tool:** [Vitest](https://vitest.dev/) `^4.1.5`
+**Run:** `pnpm test` / `pnpm run test:coverage`
+
+Root Vitest config is a **workspace coordinator** that lists all per-package configs under `test.projects`. It sets conservative monorepo-wide defaults:
+
+| Setting           | Value      | Notes                                                  |
+| ----------------- | ---------- | ------------------------------------------------------ |
+| `pool`            | `"forks"`  | Process-isolated workers                               |
+| `maxWorkers`      | `4`        | Root default; per-project configs may override         |
+| `isolate`         | `true`     |                                                        |
+| `fileParallelism` | `false`    | Conservative default; safe packages opt in with `true` |
+| `teardownTimeout` | `30000` ms |                                                        |
+| `hookTimeout`     | `30000` ms |                                                        |
+| `testTimeout`     | `10000` ms |                                                        |
+
+**Coverage thresholds** (monorepo aggregate — `vitest run --coverage`):
+
+| Type       | Threshold |
+| ---------- | --------- |
+| Lines      | 80%       |
+| Functions  | 80%       |
+| Branches   | 75%       |
+| Statements | 80%       |
+
+Coverage provider: `v8`. Individual packages may declare higher per-package thresholds in their own `vitest.config.ts`.
+
+**Browser test config:** `/vitest.browser.config.ts`
+Run with `pnpm run test:browser`. Uses Playwright Chromium via Vitest browser mode. `testTimeout` is `20000` ms; `maxWorkers` is `2` (default; demo integration projects override with `pool: "threads"` + `maxWorkers: 2`).
+
+### Per-Package Vitest Config — `@xmachines/shared/vitest`
+
+**Location:** `packages/shared/config/vitest.ts`
+**Exported as:** `@xmachines/shared/vitest`
+
+Packages use `defineXmVitestConfig(import.meta.url, overrides)` to create their config. It automatically injects:
+
+- `resolve.alias` via `xmAliases()` so `@xmachines/*` imports resolve to TypeScript source without a prior build.
+- `vitest.node.setup.ts` for non-browser projects (if not already present).
+- `vitest.setup.ts` for all projects (if not already present).
+
+**Typical per-package usage:**
+
+```typescript
+// packages/<name>/vitest.config.ts
+import { defineXmVitestConfig } from "@xmachines/shared/vitest";
+
+export default defineXmVitestConfig(import.meta.url, {
+	test: {
+		name: "play-example",
+		include: ["test/**/*.test.ts"],
+	},
+});
+```
+
+### Vite Source Aliases — `@xmachines/shared/vite-aliases`
+
+**Location:** `packages/shared/config/vite-aliases.ts`
+**Exported as:** `@xmachines/shared/vite-aliases`
+
+Provides two helpers used in all `vitest.config.ts` and `vite.config.ts` files:
+
+- **`xmAliases(import.meta.url)`** — returns a `Record<string, string>` mapping every `@xmachines/*` package to its TypeScript source entry. Enables tests and dev servers to run without a prior `pnpm run build`.
+- **`xmResolve(import.meta.url)`** — returns a full Vite `resolve` config with `xmAliases` plus `preserveSymlinks: true` and `conditions: ["source"]`.
+- **`xmCacheDir(import.meta.url, name)`** — returns a shared Vite cache path under `node_modules/.vite/<name>` to prevent redundant dep optimizer runs across projects.
+- **`xmOptimizeDeps(extra?)`** — returns a standard `optimizeDeps.include` list; pass framework-specific extras to pre-bundle them at startup.
+
+### Release — `release.config.mjs`
+
+**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.
+
+**Release branches:**
+
+| Branch   | Channel   | Pre-release |
+| -------- | --------- | ----------- |
+| `main`   | (default) | No          |
+| `pre/rc` | `pre/rc`  | `rc`        |
+| `beta`   | `beta`    | `true`      |
+
+**Tag format:** `v${version}`
+
+**Plugin order:**
+
+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):
+    - `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`
+    - `format-docs` — `pnpm --filter @xmachines/docs run format`
+5. `@semantic-release/npm` — one entry per published package (20 packages) + pack-only for demo apps
+6. `@semantic-release/git` — commits `CHANGELOG.md`, updated `package.json` files, and generated API docs
+7. `@semantic-release/gitlab` — creates a GitLab release with tarball assets
+
+Any step can be skipped via the `SEMREL_SKIP_STEPS` CI variable (see [Environment Variables](#environment-variables)).
+
+---
+
+## Per-Environment Overrides
+
+This monorepo has no application-level config with per-environment overrides (no `.env.development` / `.env.production` files). All configuration is tool-level (TypeScript, linter, formatter, test runner) and is environment-agnostic.
+
+The only environment-specific distinction is between **local development** (dev container with `.devcontainer/.env`) and **CI** (GitLab CI with pipeline variables), described in the sections above.
+
+---
+
+## 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 — must list all packages          | —                             |
+| Per-package `composite: true`        | Yes — required for project references | —                             |
+| `@xmachines/shared/tsconfig` extends | Yes — all packages must extend it     | —                             |
+| `@xmachines/shared/oxlint` extends   | Yes — all packages must extend it     | —                             |
+| `@xmachines/shared/oxfmt` extends    | Yes — all packages must extend it     | —                             |
+
+---
+
+## Adding a New Package
+
+When adding a new package, update these configuration files:
+
+1. **`/tsconfig.json`** — add a `{ "path": "./packages/<name>" }` entry in the correct dependency layer.
+2. **`/tsconfig.test.json`** — add a `{ "path": "./packages/<name>/tsconfig.test.json" }` entry.
+3. **`/vitest.config.ts`** — add `"packages/<name>/vitest.config.ts"` to `test.projects`.
+4. **`/vitest.browser.config.ts`** (if the package has browser tests) — add the browser config path to `test.projects`.
+5. **`/release.config.mjs`** — add an entry to `NPM_PACKAGES` array with the package's `pkgRoot`.
+
+See [AGENTS.md](https://gitlab.com/xmachin-es/xmachines-js/-/blob/main/AGENTS.md) for the full new-package checklist.

package/contributing/deployment.md

@@ -0,0 +1,312 @@
+<!-- generated-by: gsd-doc-writer -->
+
+# Deployment
+
+This document describes how `@xmachines/xmachines-js` packages are built, versioned, and published to npm. All releases are automated through [semantic-release](https://semantic-release.gitbook.io/) running inside a GitLab CI pipeline. No manual `npm publish` commands are required for normal releases.
+
+---
+
+## Deployment Targets
+
+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    | `.releaserc.json` (per-package `@semantic-release/npm` plugin entries) | Publish all public packages                            |
+| GitLab Releases | `.releaserc.json` (`@semantic-release/gitlab` plugin)                  | 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.
+
+---
+
+## Published Packages
+
+The following packages are published on every release (derived from `.releaserc.json`):
+
+| 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-signals`](../api/@xmachines/play-signals/README.md)                             | `packages/play-signals`               |
+| [`@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.
+
+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).
+
+---
+
+## Build Pipeline
+
+### CI Pipeline Stages
+
+Pipeline runs are triggered by `.gitlab-ci.yml` under the following conditions:
+
+| Trigger                                       | Pipeline runs                                 |
+| --------------------------------------------- | --------------------------------------------- |
+| Push to `main` / `master` / `beta` / `pre/rc` | Full pipeline including release               |
+| Merge request                                 | Full pipeline (release job skipped or manual) |
+| Tag push (`$CI_COMMIT_TAG`)                   | Full pipeline                                 |
+
+The pipeline includes two reusable CI components:
+
+- **`to-be-continuous/node/gitlab-ci-node@5.1.2`** — handles install, lint, build, test, and audit
+- **`to-be-continuous/semantic-release/gitlab-ci-semrel@4.1.0`** — runs `semantic-release` on eligible branches
+
+The `node-build` job runs with:
+
+```bash
+pnpm run build           # tsc --build (TypeScript composite build)
+pnpm run test:coverage   # vitest run --coverage (with JUnit + Cobertura reporters)
+```
+
+Coverage is extracted from the `node-build` job via the regex:
+
+```
+/All files[^|]*\|[^|]*\s+([\d\.]+)/
+```
+
+JUnit results are published as `reports/junit.xml` and Cobertura coverage as `reports/coverage/cobertura-coverage.xml`.
+
+### 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 job uses a GitLab OIDC id token (`NPM_ID_TOKEN`) scoped to `npm:registry.npmjs.org` rather than a static `NPM_TOKEN`.
+
+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):
+
+```bash
+pnpm run build
+node scripts/release-pack-smoke.mjs
+```
+
+`scripts/release-pack-smoke.mjs`:
+
+1. Reads `.releaserc.json` to find all `@semantic-release/npm` plugin entries where `npmPublish` is not `false`.
+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.
+
+This smoke test runs **before** the actual publish so packaging problems are caught in CI rather than on npm.
+
+---
+
+## Semantic Release Process
+
+### Branch Model
+
+Releases are driven by commit history on protected branches:
+
+| Branch   | Channel          | Tag format      | Behaviour                     |
+| -------- | ---------------- | --------------- | ----------------------------- |
+| `main`   | stable (default) | `v1.2.3`        | Full production release       |
+| `beta`   | `beta`           | `v1.2.3-beta.N` | Beta pre-release              |
+| `pre/rc` | `pre/rc`         | `v1.2.3-rc.N`   | Release candidate pre-release |
+
+Tag format is `v${version}` (e.g., `v1.0.0-beta.46`).
+
+### Prepare Phase
+
+Before any package is published, semantic-release runs a sequence of `@semantic-release/exec` prepare steps defined in `release.config.mjs`:
+
+```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
+```
+
+Step by step:
+
+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 `tsc --build` to produce compiled `dist/` output in all packages.
+5. **Generate API docs** — runs TypeDoc to regenerate `packages/docs/api/` at the release git revision.
+6. **Format docs** — runs `oxfmt` on the docs package to ensure consistent formatting.
+
+### Publish Phase
+
+Each publishable package is published in sequence via individual `@semantic-release/npm` plugin entries. Each entry specifies:
+
+- `pkgRoot` — the package directory relative to the workspace root
+- `tarballDir` — `dist/releases/` where the packed `.tgz` is saved
+
+Example (from `.releaserc.json`):
+
+```json
+["@semantic-release/npm", { "pkgRoot": "packages/play", "tarballDir": "dist/releases" }]
+```
+
+### Post-Release Phase
+
+After all packages are published:
+
+1. **`@semantic-release/git`** commits updated files back to the repository:
+    - `CHANGELOG.md`
+    - `package.json` and `package-lock.json` (root)
+    - `packages/*/{package.json,examples/*/package.json}` (all workspace packages)
+    - `packages/docs/api/**` (generated API documentation)
+
+    Commit message format:
+
+    ```
+    chore(release): <version>
+
+    <release notes>
+
+    [skip ci]
+    ```
+
+2. **`@semantic-release/gitlab`** creates a GitLab Release entry attached to the version tag, with all `dist/releases/*.tgz` tarballs as downloadable assets labelled "Release tarballs".
+
+3. **`@semantic-release/changelog`** updates `CHANGELOG.md` with generated release notes.
+
+---
+
+## Version Synchronisation
+
+All packages in the monorepo share a **single version** at all times. This is enforced during release by `scripts/set-workspace-versions.mjs`, which:
+
+- 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).
+
+This means packages always depend on the exact same version of sibling packages that was released together.
+
+---
+
+## 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 protected variable            | Authenticates `@semantic-release/gitlab` for release creation and git push back |
+| `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`, `beta`, `pre/rc`).
+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:
+
+```
+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 API documentation (`packages/docs/api/`) **is committed** to git by the post-release git commit and is the only generated artifact tracked in version control.
+
+---
+
+## Rollback Procedure
+
+There is no automated rollback mechanism. To revert a release:
+
+1. **npm deprecate** (preferred) — deprecate the bad version on npm so it is hidden from installs:
+
+    ```bash
+    npm deprecate @xmachines/play@<bad-version> "Deprecated: use <good-version>"
+    ```
+
+    Repeat for each affected package.
+
+2. **npm unpublish** — unpublish the bad version if it was published within 72 hours and no dependents exist:
+
+    ```bash
+    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.
+
+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.
+
+---
+
+## Local Release Dry-Run (Manual)
+
+To preview what semantic-release would do without publishing:
+
+```bash
+# Install dependencies first
+pnpm install --frozen-lockfile
+
+# Run semantic-release in dry-run mode
+pnpm exec semantic-release --dry-run --no-ci
+```
+
+To test package 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
+```
+
+**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.
+
+---
+
+## Monitoring
+
+The project does not include application runtime monitoring (no Sentry, Datadog, or OpenTelemetry) — it is a library monorepo, not a deployed service.
+
+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 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.