@xmachines/docs 3.0.0 → 5.0.0

package/contributing/configuration.md

@@ -22,23 +22,23 @@ The dev container currently defines no workspace-specific environment variables;
 
 **Examples:**
 
-```bash
-# Skip one package publish
-SEMREL_SKIP_STEPS="@semantic-release/npm:packages/play-xstate"
+A step ID is the name of the plugin, and a name that the entry declares extends it: `@semantic-release/exec:build`.
 
-# Skip all demo publish steps
-SEMREL_SKIP_STEPS="examples/demo"
+```bash
+# Skip one prepare step
+SEMREL_SKIP_STEPS="@semantic-release/exec:build$"
 
-# Skip all exec steps (build, typedoc, etc.)
+# Skip every prepare step
 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"
+# 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
@@ -58,7 +58,7 @@ The root TypeScript config is a **build coordinator only** — it compiles nothi
 		{ "path": "./packages/play" },
 		{ "path": "./packages/shared" },
 		// Layer 1 — depends on Layer 0
-		{ "path": "./packages/play-signals" },
+		{ "path": "./packages/play-atom" },
 		// Layer 2
 		{ "path": "./packages/play-actor" },
 		// Layer 3
@@ -75,7 +75,7 @@ Every package must be listed here and must have `composite: true` in its own `ts
 ### TypeScript — Shared Base Config (`@xmachines/shared/tsconfig`)
 
 **Location:** `packages/shared/config/tsconfig.json`
-**Exported as:** `@xmachines/shared/tsconfig`
+**Exported as:** [`@xmachines/shared/tsconfig`](../api/@xmachines/shared/README.md)
 
 All packages extend this base. Key compiler settings:
 
@@ -139,7 +139,7 @@ declared floor is the floor the bundle runs on.
 
 A package declares no `references`. Its dependencies live in `package.json`, and the root array orders the build.
 
-**Test tsconfig (`@xmachines/shared/tsconfig-test`):**
+**Test tsconfig ([`@xmachines/shared/tsconfig-test`](../api/@xmachines/shared/README.md)):**
 
 **Location:** `packages/shared/config/tsconfig.test.json`
 
@@ -151,7 +151,7 @@ Test builds add `noEmit: true`, `allowImportingTsExtensions: true`, and `vitest/
 **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:
+The root config extends the shared base ([`@xmachines/shared/oxlint`](../api/@xmachines/shared/README.md)) and adds workspace-level ignore patterns:
 
 ```typescript
 // /oxlint.config.ts
@@ -185,8 +185,8 @@ export default defineConfig({
 | `no-underscore-dangle`       | —             | `off`                                |
 
 `unicorn/no-array-sort` is an error and not the warning of its category. The workspace
-targets ESNext, and Node 22 — the lowest runtime a published package supports — has
-`toSorted()`, so the method is always available. As a warning the rule kept
+targets ESNext, and Node 24 — the floor of every package — has `toSorted()`, so the
+method is always available. As a warning the rule kept
 the lint job green while the Code Quality report showed the degradation, and `sort()` stayed
 behind a suppression for a ceiling that had already gone.
 
@@ -252,6 +252,64 @@ export default defineConfig({
 | `useTabs`  | `false` |
 | `tabWidth` | `2`     |
 
+### Developer Tools — Vite DevTools
+
+**Tool:** [Vite DevTools](https://devtools.vite.dev/guide/) `^0.7.1`
+**Run:** `Shift+Alt+D` in any demo dev server
+
+`@vitejs/devtools` hosts four integrations, and each one reads a tool this repository already
+uses:
+
+| Integration                                                        | Panel                                                            |
+| ------------------------------------------------------------------ | ---------------------------------------------------------------- |
+| [`@vitejs/devtools-oxc`](https://devtools.vite.dev/oxc/)           | oxlint diagnostics, the resolved rules, and the oxfmt version    |
+| [`@vitejs/devtools-vite`](https://devtools.vite.dev/vite/)         | the plugin pipeline of the dev server, and each module transform |
+| [`@vitejs/devtools-rolldown`](https://devtools.vite.dev/rolldown/) | the rolldown build that Vite 8 runs, and the modules it bundles  |
+| [`@vitejs/devtools-vitest`](https://devtools.vite.dev/vitest/)     | the Vitest UI, inside the dock                                   |
+
+`defineXmDemoConfig` adds the dock to every demo dev server, therefore the four panels need no
+script and no separate command:
+
+```bash
+pnpm --filter @xmachines/play-vue-router-demo run dev
+# then press Shift+Alt+D in the browser
+```
+
+The dock starts hidden (`embeddedVisibility: "passive"`), and the browser remembers the choice
+after the first `Shift+Alt+D`. The demos are the subjects of the browser suites and of the
+screenshots of the documentation, and a panel above them helps neither.
+
+The root manifest declares `@vitest/ui`, because the Vitest panel embeds it. Without it the panel
+shows an "Install @vitest/ui & start" button, and that button writes the dependency into the root
+manifest and installs it while the dev server runs. It installs the newest version, which is 5.x,
+and `vitest` names `@vitest/ui` as a peer at its own exact version. The declared `^4.1.11` keeps
+the whole vitest family on one range, which `tests/vitest-version-lockstep.test.ts` holds true.
+
+Only the 13 demo apps declare the five packages, because only they run a dev server. The Oxc panel
+reads the same shared configuration from any of them: all 23 per-package `oxlint.config.ts`
+files hold `extends: [sharedConfig]` and add nothing, and the packages under `examples/` hold no
+config of their own. To read the configuration of a package that has no demo, run the inspector
+without installing it:
+
+```bash
+pnpm --filter @xmachines/docs exec npx @vitejs/devtools-oxc
+```
+
+`defineXmDemoConfig` hands `DevTools()` the demo directory as `cwd`. Without it the lookup starts
+at `process.cwd()`, and the set of panels then depends on the directory a person typed the command
+in.
+
+Every DevTools plugin carries `apply: "serve"`. A demo is a release asset, therefore
+`pnpm --filter <demo> run build` emits the same files as before the dock existed, and no devtools
+code reaches a published demo.
+
+A Vitest run gets no dock. `apply: "serve"` does not cover that case, because Vitest browser mode
+serves the app and therefore counts as `serve`. `defineXmDemoConfig` reads the `VITEST` variable
+that the Vitest CLI sets, and it adds no plugin when that variable is present. This gate is a
+guard, and it is not a fix for a failure that reproduces: the browser suite also passes and exits
+with the gate removed. A dock belongs to a dev server that a person opened, therefore the gate
+stays.
+
 ### Editor — `.editorconfig`
 
 **Location:** `/.editorconfig`
@@ -273,15 +331,15 @@ export default defineConfig({
 
 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 |                                                        |
+| Setting           | Value      | Notes                                                                                |
+| ----------------- | ---------- | ------------------------------------------------------------------------------------ |
+| `pool`            | `"forks"`  | Process-isolated workers; `defineXmVitestConfig` gives a jsdom project `"vmThreads"` |
+| `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`):
 
@@ -300,7 +358,7 @@ Run with `pnpm run test:browser`. Uses Playwright Chromium via Vitest browser mo
 ### Per-Package Vitest Config — `@xmachines/shared/vitest`
 
 **Location:** `packages/shared/config/vitest.ts`
-**Exported as:** `@xmachines/shared/vitest`
+**Exported as:** [`@xmachines/shared/vitest`](../api/@xmachines/shared/README.md)
 
 Packages use `defineXmVitestConfig(import.meta.url, overrides)` to create their config. It automatically injects:
 
@@ -325,7 +383,7 @@ export default defineXmVitestConfig(import.meta.url, {
 ### Vite Source Aliases — `@xmachines/shared/vite-aliases`
 
 **Location:** `packages/shared/config/vite-aliases.ts`
-**Exported as:** `@xmachines/shared/vite-aliases`
+**Exported as:** [`@xmachines/shared/vite-aliases`](../api/@xmachines/shared/README.md)
 
 Provides two helpers used in all `vitest.config.ts` and `vite.config.ts` files:
 
@@ -367,11 +425,12 @@ Only `main` is a protected branch today. That works because `GITLAB_TOKEN` — w
     - `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
+    - `stage-generated-docs` — `git add -A packages/docs/api`, so a page that TypeDoc deleted leaves git too
+5. `@semantic-release/git` — commits the changelog, the manifests, the READMEs and the generated API docs, 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.
 
-Any step can be skipped via the `SEMREL_SKIP_STEPS` CI variable (see [Environment Variables](#environment-variables)).
+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.
 
 ---
 
@@ -385,15 +444,15 @@ 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` 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       | —                             |
+| 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       | —                             |
 
 ---
 

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    | `release.config.mjs` (npm plugin entries derived from the workspace scan) | Publish all public packages                            |
-| GitLab Releases | `release.config.mjs` (`@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 |
+| 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 |
 
 The root `package.json` is marked `"private": true` and is **never published** to npm.
 
@@ -27,7 +27,7 @@ The following packages are published on every release (derived from the workspac
 | [`@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-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`            |
@@ -70,20 +70,31 @@ The pipeline includes two reusable CI components, both pinned in `.gitlab-ci.yml
 - **`to-be-continuous/node/gitlab-ci-node`** — handles install, lint, build, test, and audit
 - **`to-be-continuous/semantic-release/gitlab-ci-semrel`** — runs `semantic-release` on eligible branches
 
-The `node-build` job runs with:
+The `node-build` job runs one command:
 
 ```bash
 pnpm run build           # vite build (JavaScript) && tsc --build (declarations)
-pnpm run test:coverage   # vitest run --coverage (with JUnit + Cobertura reporters)
 ```
 
-Coverage is extracted from the `node-build` job via the regex:
+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.
+
+Coverage comes from the `test` job, through the regex:
 
 ```
 /All files[^|]*\|[^|]*\s+([\d\.]+)/
 ```
 
-JUnit results are published as `reports/junit.xml` and Cobertura coverage as `reports/coverage/cobertura-coverage.xml`.
+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/`.
+
+### Docs Job
+
+The `docs` job runs `pnpm run docs` — the full build, then TypeDoc, then the formatter. It runs automatically on `main` and it waits for a click on a merge request. It declares `needs: []`, because it compiles what it documents.
+
+TypeDoc treats a warning as an error. This job is therefore the gate that reports a `@see` or a `{@link}` that names a symbol a rename removed. Before it existed, `node-build` regenerated the reference on every push, which put a second pass over every package on a branch that is pushed to many times.
+
+The click is a gate, not an option. The job is manual with `allow_failure: false`, so a pipeline that nobody starts it from stays BLOCKED, and the merge check "Pipelines must succeed" holds the merge request. The `release-pack-smoke` job below uses the same rules for the same reason.
+
+The job declares `stage: test`. A blocking manual job holds every later stage until it runs, so `build` would keep the unit suite, the browser suite and `release-pack-smoke` waiting for a click. Jobs in the same stage are not affected.
 
 ### Release Job Detail
 
@@ -116,7 +127,7 @@ node scripts/release-pack-smoke.mjs
 
 `scripts/release-pack-smoke.mjs`:
 
-1. Reads `release.config.mjs` to find all `@semantic-release/npm` plugin entries where `npmPublish` is not `false`.
+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.
@@ -155,6 +166,7 @@ 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
 ```
 
 Step by step:
@@ -165,44 +177,45 @@ Step by step:
 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/` at the release git revision.
 6. **Format docs** — runs `oxfmt` on the docs package to ensure consistent formatting.
+7. **Stage the generated docs** — `git add -A packages/docs/api`. 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.
 
 ### Publish Phase
 
-Each publishable package is published in sequence via individual `@semantic-release/npm` plugin entries. Each entry specifies:
+semantic-release publishes nothing. It stops at the tag, and `scripts/publish-release.mjs` publishes from a pipeline that runs ON that tag:
 
-- `pkgRoot` — the package directory relative to the workspace root
-- `tarballDir` — `dist/releases/` where the packed `.tgz` is saved
+```bash
+node scripts/publish-release.mjs
+```
 
-Example (from `release.config.mjs`, where these entries are generated rather than
-hand-written):
+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.
 
-```js
-["@semantic-release/npm", { pkgRoot: "packages/play", tarballDir: "dist/releases" }];
-```
+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 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.
 
 ### Post-Release Phase
 
-After all packages are published:
+This phase runs on the branch, BEFORE the tag pipeline publishes.
 
 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)
+    - `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)
 
+    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.
+
     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".
+    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.
 
-3. **`@semantic-release/changelog`** updates `CHANGELOG.md` with generated release notes.
+    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.
+
+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.
 
 ---
 
@@ -219,11 +232,11 @@ This means packages always depend on the exact same version of sibling packages
 
 ## 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 `@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                  |
+| 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                                                 |
 
 **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`.
 
@@ -272,6 +285,71 @@ There is no automated rollback mechanism. To revert a release:
 
 ---
 
+## Bootstrapping a New Package
+
+A package that this workspace publishes for the FIRST time needs one manual publish before
+the release, and it is the one publish that a human runs.
+
+The release authenticates to npm through OIDC and carries no static token. npm configures
+a trusted publisher on a package that EXISTS already, and a package exists after its first
+version. A name that npm has never seen therefore takes no publisher, and the release fails
+on that package alone: it publishes the rest, it creates the tag, and it leaves the new
+package missing — the state that [Recovering a Failed Release](#recovering-a-failed-release)
+describes.
+
+Run this from the repository root, when the release is NEAR:
+
+```bash
+# Rehearse it first. It writes a tarball and publishes nothing.
+node scripts/bootstrap-npm-package.mjs --dry-run play-pattern play-atom
+
+node scripts/bootstrap-npm-package.mjs play-pattern play-atom
+```
+
+The script reads the real manifest of each package and publishes ONE version,
+`0.0.0-bootstrap.0`, that holds the name, the metadata that npm shows, and a README that
+says why the version carries no code. The version carries a prerelease identifier, so a
+RANGE of a consumer selects it never. npm asks the maintainer for a one-time password, and
+the script gives npm the terminal to ask on. Pass a code without a terminal through the
+environment: `npm_config_otp=<code> node scripts/bootstrap-npm-package.mjs <package>`.
+
+> **The bootstrap version takes the `latest` dist-tag.** A package takes its `latest` from
+> its FIRST version, whatever `--tag` says, because npm keeps no package without one. The
+> script asks for the `bootstrap` tag and npm sets both, so `npm install @xmachines/<name>`
+> gives the empty version until the real release replaces the tag. This is the second
+> reason to bootstrap a name when the release is NEAR.
+
+The registry also answers for the new package about three minutes after the publish, so a
+read that says "Not found" right after a publish that reported success is that delay.
+
+Then, for EACH package:
+
+1. Open `https://www.npmjs.com/package/<name>/access` and add a trusted publisher:
+
+    | Field         | Value            |
+    | ------------- | ---------------- |
+    | Namespace     | `xmachin-es`     |
+    | Project       | `xmachines-js`   |
+    | Pipeline file | `.gitlab-ci.yml` |
+    | Environment   | none             |
+
+    The publish job declares no environment, so leaving that field set refuses the token.
+
+2. Cut the release, which publishes the real version through OIDC.
+
+3. Unpublish the bootstrap version:
+
+    ```bash
+    npm unpublish @xmachines/<name>@0.0.0-bootstrap.0
+    ```
+
+> **npm accepts an unpublish for 72 HOURS after the publish.** Bootstrap a name when the
+> release is near, and not weeks before it, or the empty version stays on the registry for
+> ever. [`@xmachines/play-url`](../api/@xmachines/play-url/README.md) and [`@xmachines/play-view`](../api/@xmachines/play-view/README.md) were bootstrapped this way for
+> 4.0.0, and each one carries the release version alone today.
+
+---
+
 ## 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:
@@ -317,7 +395,7 @@ 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.
+**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.
 
 ---