@xmachines/docs 1.0.0-beta.51 → 1.0.0-beta.52

package/contributing/development.md

@@ -1,62 +1,56 @@
 <!-- generated-by: gsd-doc-writer -->
 
-# Development Guide
+# Development
 
-This guide covers everything you need to contribute to the XMachines JS monorepo — from setting up your environment through the full build, test, lint, and release lifecycle.
+This guide covers everything you need to set up a local development environment, understand the build system, and contribute code to the XMachines JS monorepo.
 
----
-
-## Prerequisites
+## Table of Contents
 
-| Requirement | Version              | Notes                                                    |
-| ----------- | -------------------- | -------------------------------------------------------- |
-| Node.js     | `>= 22.0.0`          | Specified in all `package.json` `engines` fields         |
-| npm         | Bundled with Node 22 | Workspaces support required                              |
-| TypeScript  | `^5.7+`              | Installed as a dev dependency — no global install needed |
-| Git         | Any recent version   | Commit message format enforced by CI                     |
-
-No global tool installs are required beyond Node.js. All build, lint, and format tooling is installed locally via `npm ci`.
+- [Local Setup](#local-setup)
+- [Monorepo Structure](#monorepo-structure)
+- [Build Commands](#build-commands)
+- [TypeScript Composite Build System](#typescript-composite-build-system)
+- [Code Style](#code-style)
+- [Branch Conventions](#branch-conventions)
+- [PR Process](#pr-process)
 
 ---
 
 ## Local Setup
 
-### 1. Clone the repository
+### Prerequisites
 
-```bash
-git clone git@gitlab.com:xmachin-es/xmachines-js.git
-cd xmachines-js
-```
+- **Node.js** `>= 22.0.0`
+- **npm** (bundled with Node.js — the project uses npm workspaces)
+- **Git**
 
-### 2. Install dependencies
+No global tool installs are required beyond Node.js. All build, lint, and format tooling is installed locally via `npm ci`.
 
-Always use `npm ci` (not `npm install`) so the lockfile is respected:
+### Clone and Install
 
 ```bash
+git clone git@gitlab.com:xmachin-es/xmachines-js.git
+cd xmachines-js
 npm ci
 ```
 
-`postinstall` automatically runs `patch-package` to apply the patches in `patches/` — this is expected and required.
+> **Use `npm ci`, not `npm install`.** `npm ci` installs exact locked versions and triggers the `postinstall` hook that runs `patch-package` to apply any repository patches.
 
-### 3. Build all packages
+### Build
 
 ```bash
 npm run build
 ```
 
-The build uses TypeScript project references (`tsc --build`) and compiles all packages in dependency order. Build outputs go to each package's `dist/` directory. The `dist/` directories are gitignored.
+The root-level `tsc --build` command uses TypeScript project references to build all packages in the correct dependency order automatically. You never need to sequence builds manually.
 
-### 4. Verify
+To build a single package (and its upstream dependencies):
 
 ```bash
-npm test
+npm run build -w @xmachines/<package-name>
 ```
 
-All tests should pass on a clean install. If any fail, check the [Common Setup Issues](#common-setup-issues) section.
-
----
-
-## Dev Container (Optional)
+### Dev Container (Optional)
 
 A fully configured dev container is provided at `.devcontainer/`. It includes Docker-outside-of-Docker, Claude Code, and OpenCode.
 
@@ -66,6 +60,16 @@ npm run devcontainer:up
 
 Or open the repository in VS Code and choose **Reopen in Container** when prompted.
 
+### Verify Your Setup
+
+```bash
+npm test              # Run the full test suite
+npm run lint          # Check for lint errors
+npm run format:check  # Check formatting without modifying files
+```
+
+All three should pass without errors on a freshly cloned repository.
+
 ---
 
 ## Monorepo Structure
@@ -98,220 +102,229 @@ packages/
 
 Many packages also contain an `examples/` subdirectory with runnable demo apps.
 
-### Package naming convention
-
-All packages use the `@xmachines/` npm scope. The package directory name matches the npm name without the scope:
-
-- `packages/play` → [`@xmachines/play`](../api/@xmachines/play/README.md)
-- `packages/play-actor` → [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)
-
-### Standard package layout
+### Standard Package Layout
 
 ```
 packages/<name>/
-├── src/              # TypeScript source files
-├── dist/             # Build output (gitignored)
-├── test/             # Test files (*.spec.ts or *.test.ts)
-├── examples/         # Runnable demo apps (optional)
-├── package.json      # Must have "type": "module"
-├── tsconfig.json     # Extends shared base config
+├── src/               # TypeScript source files
+├── dist/              # Build output (gitignored)
+├── test/              # Test files (*.spec.ts or *.test.ts)
+├── examples/          # Runnable demo apps (optional)
+├── package.json       # Must have "type": "module"
+├── tsconfig.json      # Composite build config (extends tsconfig.base.json)
 ├── tsconfig.base.json # Local base (extends @xmachines/shared/tsconfig)
-├── vitest.config.ts  # Package test config
+├── vitest.config.ts   # Package test config
 └── README.md
 ```
 
 ---
 
-## Build System
-
-### Build commands
-
-| Command                            | Description                                                |
-| ---------------------------------- | ---------------------------------------------------------- |
-| `npm run build`                    | Build all packages in dependency order (incremental)       |
-| `npm run build -w packages/<name>` | Build a specific package (and its deps)                    |
-| `npm run test:build`               | Type-check the full test TypeScript graph without emitting |
-| `npm run clean`                    | Remove all build outputs and caches across all packages    |
-
-### TypeScript composite build
-
-This monorepo uses **TypeScript project references** (`composite: true`) for build-order management.
-
-- **`tsconfig.json`** at the root coordinates all packages via its `references` array — it does not compile anything itself
-- Each package's `tsconfig.json` sets `composite: true`, `rootDir: "./src"`, and `outDir: "./dist"`
-- TypeScript understands the full dependency graph and builds packages in the correct order automatically
-- Incremental builds: only changed packages are rebuilt
-- `declarationMap: true` is set in the base config — **Go to Definition** in your IDE jumps to source `.ts` files, not compiled `.d.ts`
-
-**Dependency layers** (from `tsconfig.json`):
-
-| Layer   | Packages                                                              |
-| ------- | --------------------------------------------------------------------- |
-| Layer 0 | `play-signals`, `play`, `docs` — no internal dependencies             |
-| Layer 1 | `play-actor` — depends on Layer 0                                     |
-| Layer 2 | `play-router`, `play-xstate`, all view renderers, all router adapters |
-| Layer 3 | Example applications                                                  |
+## Build Commands
+
+All commands are run from the **repository root** unless otherwise noted.
+
+| Command                             | Description                                                           |
+| ----------------------------------- | --------------------------------------------------------------------- |
+| `npm run build`                     | TypeScript composite build — all packages in dependency order         |
+| `npm run build -w @xmachines/<pkg>` | Build a single package (and its deps)                                 |
+| `npm run clean`                     | Remove coverage, Vite caches, and all `dist/` directories in packages |
+| `npm test`                          | Run all unit/integration tests once                                   |
+| `npm run test:watch`                | Re-run tests on file changes (interactive)                            |
+| `npm run test:browser`              | Run Playwright browser tests                                          |
+| `npm run test:coverage`             | Run tests with V8 coverage reporting                                  |
+| `npm run coverage:report`           | Run tests and write an HTML coverage report                           |
+| `npm run coverage:summary`          | Run tests and write a JSON summary report                             |
+| `npm run test:build`                | Type-check test files without running them (`tsconfig.test.json`)     |
+| `npm run lint`                      | Lint all packages with oxlint                                         |
+| `npm run lint:fix`                  | Auto-fix lint issues                                                  |
+| `npm run format`                    | Format all files with oxfmt                                           |
+| `npm run format:check`              | Check formatting (CI mode — no writes)                                |
+| `npm run docs`                      | Build packages, generate TypeDoc API docs, then format                |
 
 ---
 
-## Adding a New Package
-
-Follow these steps when creating a new package:
-
-### 1. Create the package directory
+## TypeScript Composite Build System
+
+The monorepo uses **TypeScript project references** for correct build-order management. No manual sequencing or separate build scripts are needed.
+
+### How It Works
+
+- The **root `tsconfig.json`** coordinates all packages via a `references` array — it compiles nothing itself
+- Each package has `composite: true` in its own `tsconfig.json`, enabling incremental and referenced builds
+- Packages declare `references` to their `@xmachines/*` dependencies so `tsc --build` resolves order automatically
+- With `declarationMap: true` in the base config, **Go to Definition** in your IDE navigates to `.ts` source files rather than compiled `.d.ts` files
+
+### Build Layers
+
+Packages are grouped into dependency layers as defined in the root `tsconfig.json`:
+
+| Layer | Packages                                                                                                                                                                                                                                                                  | Depends on         |
+| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
+| 0     | `play-signals`, `play`, `docs`                                                                                                                                                                                                                                            | External libs only |
+| 1     | `play-actor`                                                                                                                                                                                                                                                              | Layer 0            |
+| 2     | `play-router`, `play-dom-router`, `play-sveltekit-router`, `play-xstate`, `play-react`, `play-vue`, `play-solid`, `play-svelte`, `play-dom`, `play-tanstack-react-router`, `play-vue-router`, `play-solid-router`, `play-svelte-spa-router`, `play-tanstack-solid-router` | Layers 0–1         |
+| 3     | `play-react-router`, example demo apps                                                                                                                                                                                                                                    | Layer 2            |
+
+#### Mermaid Diagram
+
+```mermaid
+flowchart LR
+    subgraph L0["Layer 0 — no internal deps"]
+        play-signals
+        play
+        docs
+    end
+
+    subgraph L1["Layer 1"]
+        play-actor
+    end
+
+    subgraph L2["Layer 2 — view renderers & router adapters"]
+        play-router
+        play-dom-router
+        play-sveltekit-router
+        play-xstate
+        play-react
+        play-vue
+        play-solid
+        play-svelte
+        play-dom
+        play-tanstack-react-router
+        play-vue-router
+        play-solid-router
+        play-svelte-spa-router
+        play-tanstack-solid-router
+    end
+
+    subgraph L3["Layer 3 — application layer"]
+        play-react-router
+        examples["example demo apps"]
+    end
+
+    L0 --> L1
+    L1 --> L2
+    L2 --> L3
+```
+
+### Adding a New Package
+
+1. **Create the package directory** following the standard structure:
+
+    ```
+    packages/<your-package>/
+    ├── src/
+    │   └── index.ts
+    ├── test/
+    ├── package.json      # must have "type": "module"
+    ├── tsconfig.json
+    ├── tsconfig.base.json
+    ├── vitest.config.ts
+    └── README.md
+    ```
+
+2. **`tsconfig.base.json`** — extend the shared config:
+
+    ```json
+    {
+    	"$schema": "https://json.schemastore.org/tsconfig",
+    	"extends": "@xmachines/shared/tsconfig",
+    	"compilerOptions": {
+    		"skipLibCheck": true
+    	}
+    }
+    ```
+
+    If the package depends on other monorepo packages, add `references`:
+
+    ```json
+    {
+    	"extends": "@xmachines/shared/tsconfig",
+    	"compilerOptions": { "skipLibCheck": true },
+    	"references": [{ "path": "../play" }, { "path": "../play-actor" }]
+    }
+    ```
+
+3. **`tsconfig.json`** — enable composite build:
+
+    ```json
+    {
+    	"$schema": "https://json.schemastore.org/tsconfig",
+    	"extends": "./tsconfig.base.json",
+    	"compilerOptions": {
+    		"composite": true,
+    		"rootDir": "./src",
+    		"outDir": "./dist"
+    	},
+    	"include": ["src/**/*"]
+    }
+    ```
+
+4. **Register in root `tsconfig.json`** — add a reference in the correct layer:
+
+    ```json
+    {
+    	"references": [{ "path": "./packages/your-package" }]
+    }
+    ```
+
+5. **Register in root `tsconfig.test.json`** and **root `vitest.config.ts`** (`projects` array).
 
-```bash
-mkdir packages/my-new-package
-```
-
-### 2. Create `package.json`
-
-Must include `"type": "module"` and follow the standard scripts pattern:
-
-```json
-{
-	"name": "@xmachines/my-new-package",
-	"version": "1.0.0-beta.46",
-	"type": "module",
-	"exports": {
-		".": {
-			"source": "./src/index.ts",
-			"types": "./dist/index.d.ts",
-			"import": "./dist/index.js"
-		}
-	},
-	"scripts": {
-		"build": "tsc --build",
-		"clean": "rm -rf dist *.tsbuildinfo coverage",
-		"test": "vitest",
-		"lint": "oxlint .",
-		"lint:fix": "oxlint --fix .",
-		"format": "oxfmt .",
-		"format:check": "oxfmt --check .",
-		"prepublishOnly": "npm run build"
-	},
-	"devDependencies": {
-		"@xmachines/shared": "1.0.0-beta.46",
-		"oxfmt": "^0.45.0",
-		"oxlint": "^1.60.0",
-		"vitest": "^4.1.4"
-	},
-	"engines": {
-		"node": ">=22.0.0"
-	}
-}
-```
+---
 
-### 3. Create `tsconfig.json`
-
-```json
-{
-	"$schema": "https://json.schemastore.org/tsconfig",
-	"extends": "./tsconfig.base.json",
-	"compilerOptions": {
-		"composite": true,
-		"rootDir": "./src",
-		"outDir": "./dist"
-	},
-	"include": ["src/**/*"]
-}
-```
+## Code Style
 
-### 4. Create `tsconfig.base.json`
+All style rules are **mandatory** — CI enforces them on every merge request.
 
-```json
-{
-	"$schema": "https://json.schemastore.org/tsconfig",
-	"extends": "@xmachines/shared/tsconfig",
-	"compilerOptions": {
-		"skipLibCheck": true
-	}
-}
-```
+### Formatter — oxfmt
 
-If the package depends on other packages in this monorepo, add `references`:
+oxfmt (Biome-based) is configured via `oxfmt.config.ts` at the root (extends `@xmachines/shared/oxfmt`).
 
-```json
-{
-	"extends": "@xmachines/shared/tsconfig",
-	"compilerOptions": { "skipLibCheck": true },
-	"references": [{ "path": "../play" }, { "path": "../play-actor" }]
-}
+```bash
+npm run format          # Format all files
+npm run format:check    # Check without writing (CI mode)
 ```
 
-### 5. Register in root `tsconfig.json`
+Key settings (from `packages/shared/config/oxfmt.config.ts`):
 
-Add an entry to the `references` array in the appropriate layer:
+| Setting         | Value                                 |
+| --------------- | ------------------------------------- |
+| Print width     | 100 characters                        |
+| Indentation     | Tabs (`useTabs: true`, `tabWidth: 4`) |
+| Semicolons      | Always (`semi: true`)                 |
+| Quotes          | Double (`singleQuote: false`)         |
+| Trailing commas | All                                   |
+| JSON / YAML     | 2-space indent (override)             |
 
-```json
-{
-	"references": [{ "path": "./packages/my-new-package" }]
-}
-```
-
-### 6. Register in root `tsconfig.test.json`
+### Linter — oxlint
 
-```json
-{
-	"references": [{ "path": "./packages/my-new-package/tsconfig.test.json" }]
-}
-```
+oxlint is configured via `oxlint.config.ts` at the root (extends `@xmachines/shared/oxlint`).
 
-### 7. Create `vitest.config.ts`
-
-```typescript
-import { defineXmVitestConfig } from "@xmachines/shared/vitest";
-
-export default defineXmVitestConfig(import.meta.url, {
-	test: {
-		environment: "node",
-		include: ["test/**/*.spec.ts", "test/**/*.test.ts"],
-		coverage: {
-			provider: "v8",
-			include: ["src/**/*.ts"],
-			thresholds: {
-				lines: 80,
-				functions: 80,
-				branches: 75,
-				statements: 80,
-			},
-		},
-	},
-});
+```bash
+npm run lint        # Lint all packages
+npm run lint:fix    # Auto-fix lint issues
 ```
 
-### 8. Register in root `vitest.config.ts`
+Active plugins: `typescript`, `unicorn`, `import`. Key rules:
 
-Add the package's `vitest.config.ts` to the `projects` array in the root `vitest.config.ts`.
+| Rule                         | Severity                       |
+| ---------------------------- | ------------------------------ |
+| `typescript/no-explicit-any` | error                          |
+| `import/no-cycle`            | error                          |
+| `typescript/no-unused-vars`  | error (prefix unused with `_`) |
+| `correctness` category       | error                          |
+| `suspicious` category        | warn                           |
 
----
-
-## Code Style
-
-### Rules enforced
-
-**All rules below are mandatory and enforced in CI.**
+### Editor Config
 
-#### 1. `.js` extensions on all imports
-
-Even in TypeScript source files, imports must use `.js` extensions. This is required by Node.js ESM resolution:
-
-```typescript
-// ✅ Correct
-import { foo } from "./bar.js";
-import { PlayEvent } from "@xmachines/play";
-
-// ❌ Wrong — will fail at runtime
-import { foo } from "./bar";
-```
+`.editorconfig` is present at the root and enforces:
 
-#### 2. ESM only — no CommonJS
+- Tabs for indentation in all source files
+- 2-space indent for JSON/YAML
+- LF line endings, UTF-8, insert final newline
 
-Every package has `"type": "module"` in its `package.json`. Do not use `require()`, `module.exports`, or `.cjs` files.
+### TypeScript Strict Mode
 
-#### 3. Strict TypeScript
-
-The base `tsconfig.json` enables the full strict suite plus additional checks:
+All packages extend `@xmachines/shared/tsconfig` which enables full strict mode. Mandatory constraints:
 
 | Option                       | Value  |
 | ---------------------------- | ------ |
@@ -324,161 +337,80 @@ The base `tsconfig.json` enables the full strict suite plus additional checks:
 | `verbatimModuleSyntax`       | `true` |
 | `isolatedModules`            | `true` |
 
-Use `import type` for type-only imports (required by `verbatimModuleSyntax`).
-
-#### 4. No `any`
-
-`typescript/no-explicit-any` is set to `"error"` in the shared oxlint config. Use `unknown` or appropriate generic types instead.
+Use `unknown` with type guards instead of `any`. Prefix unused locals/parameters with `_` to suppress errors.
 
-### Linting (oxlint)
+### Import Rules
 
-The project uses **oxlint** — a Rust-based linter with TypeScript, unicorn, and import plugins.
+1. Always use `.js` extensions in imports, even for TypeScript source files:
 
-```bash
-npm run lint          # Lint all packages
-npm run lint:fix      # Auto-fix lint issues across all packages
-```
+    ```typescript
+    // ✅ Correct
+    import { PlayError } from "./errors.js";
 
-Root config: `oxlint.config.ts`  
-Shared base: `packages/shared/config/oxlint.config.ts`
+    // ❌ Wrong — will not resolve at runtime with NodeNext module resolution
+    import { PlayError } from "./errors";
+    ```
 
-Enabled categories: `correctness: error`, `suspicious: warn`, `perf: warn`. Import cycle detection (`import/no-cycle`) is set to `"error"`.
+2. Use `import type` for type-only imports (required by `verbatimModuleSyntax`):
 
-### Formatting (oxfmt)
-
-The project uses **oxfmt** — an opinionated formatter.
-
-```bash
-npm run format         # Format all files in place
-npm run format:check   # Check formatting without writing (CI mode)
-```
+    ```typescript
+    import type { RouteNode, RouteTree } from "../src/types.js";
+    ```
 
-Root config: `oxfmt.config.ts`  
-Shared base: `packages/shared/config/oxfmt.config.ts`
-
-Key settings (from shared config):
-
-| Setting         | Value                     |
-| --------------- | ------------------------- |
-| Print width     | 100                       |
-| Indentation     | Tabs (width 4)            |
-| Semicolons      | `true`                    |
-| Quotes          | Double                    |
-| Trailing commas | All                       |
-| JSON/YAML files | 2-space indent (override) |
-
-### EditorConfig
-
-An `.editorconfig` at the project root ensures consistent whitespace in editors:
-
-- All files: tabs (4-wide), LF line endings, insert final newline
-- JSON/YAML: spaces (2-wide)
-- Markdown: trailing whitespace preserved
+3. Import order: Node.js built-ins (`node:` prefix) → external packages → internal `@xmachines/*` packages → relative imports
 
 ---
 
-## Testing
-
-### Test framework
-
-All packages use **Vitest 4.x** with **v8 coverage**.
-
-### Running tests
+## Branch Conventions
 
-| Command                    | Description                                      |
-| -------------------------- | ------------------------------------------------ |
-| `npm test`                 | Run all tests (node environment)                 |
-| `npm run test:watch`       | Interactive watch mode                           |
-| `npm run test:ui`          | Vitest browser UI for visual debugging           |
-| `npm run test:browser`     | Run browser-mode tests (Playwright/Chromium)     |
-| `npm run test:coverage`    | Run with coverage, output text/HTML/JSON-summary |
-| `npm run coverage:report`  | Coverage with HTML report                        |
-| `npm run coverage:summary` | Coverage with JSON summary                       |
-| `npm run test:build`       | Type-check all test files (no emit)              |
+Use a `<type>/` prefix that matches the conventional commit type for the work being done:
 
-To run tests for a single package in isolation:
-
-```bash
-npm test -w packages/play-actor
 ```
-
-### Test file conventions
-
-- Place test files in `test/` within each package
-- Use `.spec.ts` or `.test.ts` extensions
-- Both are supported; `.spec.ts` is the conventional choice for unit tests
-
-### Coverage thresholds
-
-Root-level (regression gate for the full monorepo):
-
-| Type       | Threshold |
-| ---------- | --------- |
-| Lines      | 80%       |
-| Functions  | 80%       |
-| Branches   | 75%       |
-| Statements | 80%       |
-
-Core packages enforce higher per-package thresholds in their own `vitest.config.ts`. For example, `play-actor` requires 90% lines/functions/statements and 85% branches.
-
-### Browser tests
-
-Browser tests use Vitest's Playwright integration (Chromium). They run separately from node tests:
-
-```bash
-npm run test:browser
+feat/vue-router-adapter
+fix/signal-watcher-cleanup
+docs/play-actor-jsdoc
+chore/update-vitest-4
+refactor/route-map-extraction
 ```
 
-Browser test configs are named `vitest.browser.config.ts` inside each package. Not all packages have browser tests — add them only when the code has meaningful browser-specific behavior.
-
-### Shared test setup
-
-The [`@xmachines/shared/vitest`](../api/@xmachines/shared/vitest/README.md) helper ([`defineXmVitestConfig`](../api/@xmachines/shared/vitest/functions/defineXmVitestConfig.md)) automatically:
+Release branches are managed by the project maintainers:
 
-- Configures `@xmachines/*` path aliases so tests resolve to source files
-- Injects the shared setup file (`vitest.setup.ts`) for global test utilities
-- Injects the node setup file (`vitest.node.setup.ts`) for non-browser packages
+| Branch   | Purpose                   |
+| -------- | ------------------------- |
+| `main`   | Stable releases           |
+| `beta`   | Pre-release beta channel  |
+| `pre/rc` | Release candidate channel |
 
-Use [`defineXmVitestConfig`](../api/@xmachines/shared/vitest/functions/defineXmVitestConfig.md) in every package's `vitest.config.ts` instead of bare `defineConfig`.
+**Do not** manually version packages or create release branches — releases are automated via semantic-release triggered by CI.
 
 ---
 
-## Commit Conventions
+## PR Process
 
-This project uses [Conventional Commits](https://www.conventionalcommits.org/). Commit messages are parsed by `semantic-release` to determine version bumps and changelog entries.
+### Commit Messages
 
-### Format
+This project uses **Conventional Commits** — changelogs and version bumps are generated automatically from commit history.
 
 ```
-<type>(<scope>): <description>
+<type>[(<scope>)][!]: <short description>
 
 [optional body]
 
 [optional footer]
 ```
 
-### Types
+| Type       | Triggers version bump     | When to use                              |
+| ---------- | ------------------------- | ---------------------------------------- |
+| `feat`     | Minor                     | New user-facing feature                  |
+| `fix`      | Patch                     | Bug fix                                  |
+| `docs`     | No bump                   | Documentation only                       |
+| `refactor` | No bump                   | Code restructure without behavior change |
+| `test`     | No bump                   | Adding or updating tests                 |
+| `chore`    | No bump                   | Build, tooling, or dependency changes    |
+| `perf`     | No bump (unless breaking) | Performance improvements                 |
+| `ci`       | No bump                   | CI/CD pipeline changes                   |
 
-| Type       | Triggers                  | When to use                                |
-| ---------- | ------------------------- | ------------------------------------------ |
-| `feat`     | Minor bump                | New user-facing feature                    |
-| `fix`      | Patch bump                | Bug fix                                    |
-| `docs`     | No bump                   | Documentation only                         |
-| `chore`    | No bump                   | Build scripts, tooling, dependencies       |
-| `refactor` | No bump                   | Code restructuring without behavior change |
-| `test`     | No bump                   | Adding or updating tests                   |
-| `perf`     | No bump (unless breaking) | Performance improvement                    |
-| `ci`       | No bump                   | CI configuration changes                   |
-
-A `BREAKING CHANGE:` footer or `!` after the type triggers a major version bump:
-
-```
-feat!: drop Node 20 support
-
-BREAKING CHANGE: Minimum Node version is now 22.
-```
-
-### Scope (optional)
+Breaking changes: append `!` after the type (`feat!:`) or add `BREAKING CHANGE:` in the footer.
 
 Use the package short-name as scope when the change is isolated to one package:
 
@@ -487,131 +419,46 @@ fix(play-actor): correct signal cleanup on dispose
 feat(play-react): add PlayRenderer suspense boundary
 ```
 
----
+### Before Submitting
 
-## Documentation
+1. **Read the relevant RFC** in [`packages/docs/rfc/`](../packages/docs/rfc/) — ensure your change conforms to the spec
+2. **Run the full check suite** from the repo root:
 
-API documentation is generated from TypeScript source using **TypeDoc**.
+    ```bash
+    npm run build
+    npm test
+    npm run lint
+    npm run format:check
+    ```
 
-```bash
-npm run docs
-```
+3. **Write tests** — new code must meet coverage thresholds (80% lines/functions/statements and 75% branches at the monorepo level; core packages enforce higher per-package thresholds)
+4. **Add JSDoc** — all new public exports require JSDoc with `@param`, `@returns`, and `@see` RFC links
+5. **Never edit `packages/docs/api/`** — API docs are auto-generated; edit source JSDoc and regenerate with `npm run docs`
 
-This runs the full build, generates API docs into `packages/docs/api/`, then formats the output.
+### Merge Request Checklist
 
-**Important:** `packages/docs/api/` is auto-generated and committed to git. **Never edit files inside it directly.** Always regenerate via `npm run docs`.
+- [ ] Branch is up to date with `main`
+- [ ] All tests pass (`npm test`)
+- [ ] Lint passes (`npm run lint`)
+- [ ] Formatting is correct (`npm run format:check`)
+- [ ] Build succeeds (`npm run build`)
+- [ ] New code has tests at or above coverage thresholds
+- [ ] All new public exports have JSDoc
+- [ ] Conventional commit format used on all commits
+- [ ] RFC read and implementation conforms to spec
 
-### RFC links in JSDoc
+### CI Pipeline
 
-RFC files live at `packages/docs/rfc/`. Use relative links in `@see` tags:
+The GitLab CI pipeline runs automatically on merge requests, pushes to `main`, and git tags.
 
-```typescript
-/**
- * @see `Play RFC`
- */
-```
-
-TypeDoc's custom plugin (`typedoc.config.mjs`) handles rewriting these links in the generated output.
+| Job                | Command                               | Artifacts                              |
+| ------------------ | ------------------------------------- | -------------------------------------- |
+| Build              | `npm run build`                       | —                                      |
+| Test with coverage | `vitest run --coverage`               | JUnit XML, Cobertura coverage report   |
+| Lint               | `oxlint .`                            | —                                      |
+| Audit              | `npm audit --audit-level=high`        | —                                      |
+| Semantic release   | (automated on `main`/`beta`/`pre/rc`) | CHANGELOG, npm publish, GitLab release |
 
 ---
 
-## Patches
-
-The `patches/` directory contains `patch-package` patches applied automatically during `npm ci` and `npm install` (via the `postinstall` script).
-
-Current patches are for `@json-render` packages. Do not remove or manually modify patch files — they are required for the build to succeed.
-
-To create a new patch after modifying a file in `node_modules/`:
-
-```bash
-npx patch-package <package-name>
-```
-
----
-
-## Release Process
-
-Releases are fully automated via **semantic-release** running in GitLab CI. No manual version bumping or tagging is required.
-
-### How releases work
-
-1. Commits merged to `main` are analyzed by `@semantic-release/commit-analyzer`
-2. If releasable commits are present, semantic-release:
-    - Determines the next version from commit types
-    - Updates all workspace `package.json` versions via `scripts/set-workspace-versions.mjs`
-    - Builds all packages and regenerates API docs
-    - Publishes all publishable packages to npm
-    - Creates a GitLab release with tarball artifacts
-    - Commits `CHANGELOG.md`, updated `package.json` files, and generated docs back to the branch
-
-### Release branches
-
-| Branch   | Channel | Pre-release tag |
-| -------- | ------- | --------------- |
-| `main`   | stable  | —               |
-| `beta`   | beta    | `beta`          |
-| `pre/rc` | pre/rc  | `rc`            |
-
-### Smoke testing before release
-
-The `release-pack-smoke` CI job validates that packed tarballs install correctly:
-
-```bash
-npm run build
-node scripts/release-pack-smoke.mjs
-```
-
-This job runs automatically on `main` pushes and tags but can be triggered manually on other branches.
-
-### Published packages
-
-All packages listed in `.releaserc.json` with `npmPublish: true` (the default) are published to npm under the `@xmachines/` scope. Example packages (`examples/demo`) are packed for the GitLab release but not published to npm.
-
----
-
-## CI Pipeline
-
-The GitLab CI pipeline (`.gitlab-ci.yml`) runs on:
-
-- Every push to `main`
-- Every merge request
-- Every git tag
-
-### Pipeline stages
-
-| Job                  | Description                                                                   |
-| -------------------- | ----------------------------------------------------------------------------- |
-| `node-build`         | Lints, builds, and runs `test:coverage`; reports JUnit and Cobertura coverage |
-| `semantic-release`   | Automated release on `main`, `beta`, and `pre/rc` branches                    |
-| `release-pack-smoke` | Validates packed tarballs install correctly                                   |
-
-The pipeline uses the `to-be-continuous/node` component and `to-be-continuous/semantic-release` component from the GitLab CI component catalog.
-
-**Coverage gate:** The CI reports coverage in Cobertura format. The regex `/All files[^|]*\|[^|]*\s+([\d\.]+)/` extracts the aggregate coverage percentage.
-
----
-
-## Common Setup Issues
-
-**Tests fail with `Cannot find module` errors**
-: Run `npm run build` before running tests. Some packages need their `dist/` present even in development. Alternatively, ensure [`@xmachines/shared/vite-aliases`](../api/@xmachines/shared/vite-aliases/README.md) aliases are configured in your `vitest.config.ts` — use [`defineXmVitestConfig`](../api/@xmachines/shared/vitest/functions/defineXmVitestConfig.md) from [`@xmachines/shared/vitest`](../api/@xmachines/shared/vitest/README.md) to get them automatically.
-
-**TypeScript errors about missing types after adding a dependency**
-: Run `npm ci` to ensure all types are installed. If adding a workspace-local dependency, also add the correct `references` entry to the package's `tsconfig.base.json`.
-
-**`patch-package` errors during install**
-: The patches in `patches/` are version-specific. If you update a `@json-render` package, the patches may need to be regenerated with `npx patch-package <pkg>`.
-
-**Lint errors on import extensions**
-: All imports must end with `.js`. This applies to relative imports even for `.ts` source files. Your editor's auto-import may omit the extension — fix it manually or configure your editor to add it automatically.
-
-**Build is slow after a `git clean`**
-: TypeScript incremental builds use `.tsbuildinfo` files. After a full clean these are gone and the initial build will be slower. This is expected.
-
----
-
-## Related Documentation
-
-- [Architecture](../guides/architecture.md) — System design, component diagram, data flow
-- [Configuration](configuration.md) — Environment variables and config files
-- [RFC docs](../rfc/) — Canonical specifications for each protocol
+_See [ARCHITECTURE.md](ARCHITECTURE.md) for the package layering and data flow details, and [CONFIGURATION.md](CONFIGURATION.md) for tooling configuration reference._