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

package/contributing/configuration.md

@@ -1,352 +1,290 @@
 <!-- generated-by: gsd-doc-writer -->
 
-# Configuration Reference
+# Configuration
 
-This document describes every configuration file used by the `@xmachines/xmachines-js` monorepo — TypeScript build settings, linting, formatting, testing, and CI/CD. All configuration is file-based; the project uses no environment variables for build or test execution.
+This document describes every configuration file, environment variable, and per-package override used by the `xmachines-js` monorepo.
 
 ---
 
 ## Environment Variables
 
-This project does **not** require environment variables to build, test, or develop. All configuration is expressed through config files checked into the repository.
+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**.
 
-The only environment variable that affects runtime behaviour is `NODE_ENV`, which is managed automatically by Vitest and the CI pipeline.
+### Dev Container Variables
 
-> The `.env` file pattern is in `.gitignore` but no `.env.example` exists — no user-facing environment variables are consumed by this project.
+These variables are consumed by the Docker Compose workspace defined in `.devcontainer/docker-compose.yaml`. Copy `.devcontainer/.env.sample` to `.devcontainer/.env` to override defaults locally.
 
----
-
-## TypeScript Configuration
+| Variable                      | Required | Default | Description                                                                                           |
+| ----------------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------- |
+| `OPENCODE_EXPERIMENTAL_OXFMT` | Optional | `false` | Enables experimental oxfmt integration inside the opencode AI assistant running in the dev container. |
+| `OPENCODE_PORT_MAPPING`       | Optional | `4096`  | Docker port mapping for the opencode web interface (`host_port:container_port` or just `host_port`).  |
 
-The monorepo uses a **TypeScript composite build system** with project references. A single root `tsconfig.json` coordinates all packages; each package extends a shared base config from [`@xmachines/shared`](../api/@xmachines/shared/README.md).
+**Sample file:** `.devcontainer/.env.sample`
 
-### Shared Base Config (`@xmachines/shared/tsconfig`)
+```bash
+# .devcontainer/.env.sample
+# OPENCODE_EXPERIMENTAL_OXFMT=true
+# OPENCODE_PORT_MAPPING=4096:4096
+```
 
-**Source:** `packages/shared/config/tsconfig.json`  
-**Exported as:** `@xmachines/shared/tsconfig`
+### CI / Release Pipeline Variable
 
-This is the authoritative base config inherited by every package. Key settings:
-
-| Category      | Option                       | Value        | Purpose                                                      |
-| ------------- | ---------------------------- | ------------ | ------------------------------------------------------------ |
-| Language      | `target`                     | `ESNext`     | Compile to modern JavaScript                                 |
-| Language      | `lib`                        | `["ESNext"]` | ESNext globals only (no DOM)                                 |
-| Language      | `types`                      | `["node"]`   | Node.js type declarations                                    |
-| Modules       | `module`                     | `NodeNext`   | Native ESM, respects `exports` field                         |
-| Modules       | `moduleResolution`           | `NodeNext`   | Node12+ resolution algorithm                                 |
-| Modules       | `customConditions`           | `["source"]` | Resolves `@xmachines/*` to TypeScript source during dev/test |
-| Type checking | `strict`                     | `true`       | Full strict mode                                             |
-| Type checking | `noUnusedLocals`             | `true`       | Error on unused local variables                              |
-| Type checking | `noUnusedParameters`         | `true`       | Error on unused function parameters                          |
-| Type checking | `noFallthroughCasesInSwitch` | `true`       | Error on switch fallthrough                                  |
-| Type checking | `noImplicitReturns`          | `true`       | All code paths must return                                   |
-| Type checking | `noImplicitOverride`         | `true`       | `override` keyword required                                  |
-| Type checking | `exactOptionalPropertyTypes` | `true`       | Optional props cannot be `undefined` unless explicitly typed |
-| Emit          | `declaration`                | `true`       | Generate `.d.ts` files                                       |
-| Emit          | `declarationMap`             | `true`       | Generate `.d.ts.map` for IDE "go to definition"              |
-| Emit          | `sourceMap`                  | `true`       | Generate `.js.map` files                                     |
-| Emit          | `removeComments`             | `false`      | Preserve JSDoc in output                                     |
-| Interop       | `verbatimModuleSyntax`       | `true`       | Enforce `import type` for type-only imports                  |
-| Interop       | `isolatedModules`            | `true`       | Each file compilable independently                           |
-
-**Include/exclude defaults:**
+| 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. |
 
-```json
-{
-	"include": ["src/**/*"],
-	"exclude": ["dist", "node_modules", "**/*.spec.ts", "**/*.test.ts"]
-}
-```
+**Defined in:** `.gitlab-ci.yml`, consumed by `release.config.mjs`.
 
-### Root Workspace Coordinator (`tsconfig.json`)
+**Examples:**
 
-**Source:** `tsconfig.json`
+```bash
+# Skip one package publish
+SEMREL_SKIP_STEPS="@semantic-release/npm:packages/play-xstate"
 
-The root config does **not compile anything itself**. It contains only `references` to all packages, listed in dependency order (leaves first, dependents last). TypeScript uses this to build the full graph in the correct sequence.
+# Skip all demo publish steps
+SEMREL_SKIP_STEPS="examples/demo"
 
-```
-Layer 0 (no internal deps): play-signals, play, docs
-Layer 1 (depends on Layer 0): play-actor
-Layer 2 (depends on Layers 0–1): 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
-Layer 3 (top-level / examples): play-react-router, all examples/demo packages
-```
+# Skip all exec steps (build, typedoc, etc.)
+SEMREL_SKIP_STEPS="@semantic-release/exec"
 
-Run the full build with:
+# Publish-only retry (skip build + demos)
+SEMREL_SKIP_STEPS="@semantic-release/exec|examples/demo"
 
-```bash
-npm run build          # tsc --build (incremental, correct order)
-npm run build -w <pkg> # Build one package and its dependencies
+# Skip git commit and GitLab release
+SEMREL_SKIP_STEPS="@semantic-release/git|@semantic-release/gitlab"
 ```
 
-### Per-Package Config Pattern
+---
 
-Every package uses two `tsconfig` files:
+## Configuration Files
 
-**`packages/<name>/tsconfig.base.json`** — points to the shared base:
+### TypeScript — `tsconfig.json` (root)
 
-```json
-{
-	"$schema": "https://json.schemastore.org/tsconfig",
-	"extends": "@xmachines/shared/tsconfig"
-}
-```
+**Location:** `/tsconfig.json`
 
-**`packages/<name>/tsconfig.json`** — the build config with composite enabled:
+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
 {
-	"$schema": "https://json.schemastore.org/tsconfig",
-	"extends": "./tsconfig.base.json",
-	"compilerOptions": {
-		"composite": true,
-		"rootDir": "./src",
-		"outDir": "./dist"
-	},
-	"include": ["src/**/*"]
+	"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.
+	]
 }
 ```
 
-Packages that depend on other `@xmachines/*` packages also declare `references` (see [`@xmachines/shared`](../api/@xmachines/shared/README.md) for the base config):
+Every package must be listed here and must have `composite: true` in its own `tsconfig.json`.
 
-```json
-{
-	"references": [{ "path": "../play" }]
-}
-```
+**Test build coordinator:** `/tsconfig.test.json` — identical structure but references each package's `tsconfig.test.json` for type-checking tests without emitting output.
 
-### Test TypeScript Config
+### TypeScript — Shared Base Config (`@xmachines/shared/tsconfig`)
 
-**Source:** `packages/shared/config/tsconfig.test.json`  
-**Exported as:** `@xmachines/shared/tsconfig-test`
+**Location:** `packages/shared/config/tsconfig.json`
+**Exported as:** `@xmachines/shared/tsconfig`
 
-Per-package test configs extend both the package base and this shared test config:
+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": ["./tsconfig.base.json", "@xmachines/shared/tsconfig-test"],
-	"include": ["src/**/*", "test/**/*"]
+	"extends": "@xmachines/shared/tsconfig",
+	"compilerOptions": {
+		"composite": true,
+		"rootDir": "./src",
+		"outDir": "./dist"
+	},
+	"references": [{ "path": "../dependency-package" }]
 }
 ```
 
-Key test-specific settings:
-
-| Option                       | Value                        | Purpose                                               |
-| ---------------------------- | ---------------------------- | ----------------------------------------------------- |
-| `noEmit`                     | `true`                       | Type-check only; Vitest transpiles at runtime         |
-| `allowImportingTsExtensions` | `true`                       | Import `.ts` files directly in test code              |
-| `customConditions`           | `["source"]`                 | Resolves packages to source, not dist                 |
-| `types`                      | `["node", "vitest/globals"]` | Adds Vitest global types (`describe`, `it`, `expect`) |
-
-The root `tsconfig.test.json` coordinates all per-package test configs (used by `npm run test:build`).
-
----
-
-## Linting Configuration (oxlint)
-
-The project uses **oxlint** (`^1.60.0`) — a fast Rust-based linter with ESLint-compatible rules.
-
-### Shared Linting Rules (`@xmachines/shared/oxlint`)
-
-**Source:** `packages/shared/config/oxlint.config.ts`  
-**Exported as:** `@xmachines/shared/oxlint`
-
-| Setting       | Value                             |
-| ------------- | --------------------------------- |
-| Plugins       | `typescript`, `unicorn`, `import` |
-| `correctness` | `"error"`                         |
-| `suspicious`  | `"warn"`                          |
-| `pedantic`    | `"off"`                           |
-| `perf`        | `"warn"`                          |
-| `style`       | `"off"`                           |
-
-Custom rule overrides:
-
-| Rule                         | Level     | Reason                                      |
-| ---------------------------- | --------- | ------------------------------------------- |
-| `unicorn/filename-case`      | `"off"`   | Not enforced project-wide                   |
-| `import/no-cycle`            | `"error"` | Circular imports are forbidden              |
-| `typescript/no-explicit-any` | `"error"` | `any` is prohibited                         |
-| `typescript/no-unused-vars`  | `"error"` | Unused vars are errors; `_` prefix exempted |
-
-### Root Linting Config (`oxlint.config.ts`)
+**Test tsconfig (`@xmachines/shared/tsconfig-test`):**
 
-**Source:** `oxlint.config.ts`
+**Location:** `packages/shared/config/tsconfig.test.json`
 
-Extends the shared config and adds monorepo-level ignore patterns:
+Test builds add `noEmit: true`, `allowImportingTsExtensions: true`, and `vitest/globals` types. Used by `npm run test:build` to type-check test files without emitting output.
 
-| Ignored Path      | Reason                       |
-| ----------------- | ---------------------------- |
-| `.planning`       | Auto-generated planning docs |
-| `.opencode`       | AI tooling cache             |
-| `node_modules`    | Third-party dependencies     |
-| `dist`            | Build output                 |
-| `build`           | Build output                 |
-| `coverage`        | Test coverage output         |
-| `docs/api/_media` | Auto-generated TypeDoc media |
-| `*.min.js`        | Minified files               |
-| `CHANGELOG.md`    | Managed by semantic-release  |
+### Linting — `oxlint.config.ts` (root)
 
-**Run commands:**
+**Location:** `/oxlint.config.ts`
+**Tool:** [oxlint](https://oxc.rs/docs/guide/usage/linter) `^1.62.0`
+**Run:** `npm run lint` / `npm run lint:fix`
 
-```bash
-npm run lint        # oxlint .
-npm run lint:fix    # oxlint --fix .
-```
-
-Per-package linting can be run with:
+The root config extends the shared base (`@xmachines/shared/oxlint`) and adds workspace-level ignore patterns:
 
-```bash
-npm run lint -w packages/<name>
+```typescript
+// /oxlint.config.ts
+export default defineConfig({
+	extends: [sharedConfig],
+	ignorePatterns: [
+		".planning",
+		".opencode",
+		"node_modules",
+		"dist",
+		"build",
+		"coverage",
+		"docs/api/_media",
+		"*.min.js",
+		"CHANGELOG.md",
+	],
+});
 ```
 
----
-
-## Formatting Configuration (oxfmt)
+**Shared base rules** (`packages/shared/config/oxlint.config.ts`):
 
-The project uses **oxfmt** (`^0.45.0`) — an opinionated formatter compatible with Prettier's output.
+| 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`                                |
 
-### Shared Formatting Rules (`@xmachines/shared/oxfmt`)
+**Per-package override pattern:**
 
-**Source:** `packages/shared/config/oxfmt.config.ts`  
-**Exported as:** `@xmachines/shared/oxfmt`
-
-| Option               | Value                         |
-| -------------------- | ----------------------------- |
-| `printWidth`         | `100`                         |
-| `tabWidth`           | `4`                           |
-| `useTabs`            | `true` (tabs for indentation) |
-| `semi`               | `true`                        |
-| `singleQuote`        | `false` (double quotes)       |
-| `trailingComma`      | `"all"`                       |
-| `insertFinalNewline` | `true`                        |
-
-**JSON and YAML override** (via `overrides`):
-
-| Option     | Value            |
-| ---------- | ---------------- |
-| `useTabs`  | `false` (spaces) |
-| `tabWidth` | `2`              |
-
-Default ignored paths include: `**/node_modules`, `**/dist`, `**/build`, `**/coverage`, `**/*.tsbuildinfo`, `**/*.log`, `**/*.min.js`, `**/.git`, `**/.svelte-kit`, `**/.nyc_output`, IDE directories, and test artifact directories.
-
-### Root Formatting Config (`oxfmt.config.ts`)
-
-**Source:** `oxfmt.config.ts`
-
-Extends the shared config and adds additional monorepo-level ignore patterns:
-
-| Ignored Path    |
-| --------------- |
-| `.planning`     |
-| `.opencode`     |
-| `.agents`       |
-| `.githuman`     |
-| `.devcontainer` |
-| `CHANGELOG.md`  |
-| `Thumbs.db`     |
-
-**Run commands:**
+```typescript
+// packages/<name>/oxlint.config.ts
+import sharedConfig from "@xmachines/shared/oxlint";
+import { defineConfig } from "oxlint";
 
-```bash
-npm run format        # oxfmt .   (format in place)
-npm run format:check  # oxfmt --check .   (CI mode, no writes)
+export default defineConfig({
+	extends: [sharedConfig],
+	// add package-specific rules here
+});
 ```
 
----
-
-## Editor Configuration (`.editorconfig`)
-
-**Source:** `.editorconfig`
-
-Enforces consistent whitespace across all editors:
-
-| File Pattern        | `indent_style` | `indent_size` | Notes                                                             |
-| ------------------- | -------------- | ------------- | ----------------------------------------------------------------- |
-| `*` (default)       | `tab`          | `4`           | UTF-8, LF line endings, trim trailing whitespace, final newline   |
-| `*.{json,yml,yaml}` | `space`        | `2`           | Matches oxfmt JSON/YAML override                                  |
-| `*.md`              | (inherited)    | (inherited)   | Trailing whitespace **not** trimmed (allows Markdown line breaks) |
+### Formatting — `oxfmt.config.ts` (root)
 
----
-
-## Vitest Configuration
+**Location:** `/oxfmt.config.ts`
+**Tool:** [oxfmt](https://oxc.rs/docs/guide/usage/formatter) `^0.47.0`
+**Run:** `npm run format` / `npm run format:check`
 
-The project uses **Vitest** (`^4.1.4`) with two distinct test modes — Node.js (unit/integration) and Browser (Playwright Chromium).
+The root config extends the shared base and adds workspace-level ignore patterns:
 
-### Root Node Test Config (`vitest.config.ts`)
+```typescript
+// /oxfmt.config.ts
+export default defineConfig({
+	...sharedConfig,
+	ignorePatterns: [
+		...(sharedConfig.ignorePatterns ?? []),
+		".planning",
+		".opencode",
+		".agents",
+		".githuman",
+		".devcontainer",
+		"CHANGELOG.md",
+		"Thumbs.db",
+	],
+});
+```
 
-**Source:** `vitest.config.ts`
+**Shared base format settings** (`packages/shared/config/oxfmt.config.ts`):
 
-| Option            | Value                                                                            | Notes                                     |
-| ----------------- | -------------------------------------------------------------------------------- | ----------------------------------------- |
-| `pool`            | `"forks"`                                                                        | Isolated Node.js process per file         |
-| `maxWorkers`      | `4`                                                                              | Parallel worker cap                       |
-| `isolate`         | `true`                                                                           | Full module isolation between tests       |
-| `fileParallelism` | `false`                                                                          | Files run sequentially within each worker |
-| `testTimeout`     | `10000` ms                                                                       | Per-test timeout                          |
-| `hookTimeout`     | `30000` ms                                                                       | `beforeAll`/`afterAll` timeout            |
-| `teardownTimeout` | `30000` ms                                                                       | Teardown timeout                          |
-| `resolve.alias`   | [`xmAliases(...)`](../api/@xmachines/shared/vite-aliases/functions/xmAliases.md) | `@xmachines/*` → TypeScript source        |
+| Setting              | Value   |
+| -------------------- | ------- |
+| `printWidth`         | `100`   |
+| `tabWidth`           | `4`     |
+| `useTabs`            | `true`  |
+| `semi`               | `true`  |
+| `singleQuote`        | `false` |
+| `trailingComma`      | `"all"` |
+| `insertFinalNewline` | `true`  |
 
-The config enumerates all per-package `vitest.config.ts` files explicitly via the `projects` array. 29 project configs are currently registered.
+**JSON / YAML override** (applied via `overrides`):
 
-**Run commands:**
+| Setting    | Value   |
+| ---------- | ------- |
+| `useTabs`  | `false` |
+| `tabWidth` | `2`     |
 
-```bash
-npm test                    # vitest run (all packages, node mode)
-npm run test:watch          # vitest (watch mode)
-npm run test:coverage       # vitest run --coverage
-npm run coverage:report     # vitest run --coverage --coverage.reporter=html
-npm run coverage:summary    # vitest run --coverage --coverage.reporter=json-summary
-```
+### Editor — `.editorconfig`
 
-### Root Browser Test Config (`vitest.browser.config.ts`)
+**Location:** `/.editorconfig`
 
-**Source:** `vitest.browser.config.ts`
+| 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`  | —                     | —        |
 
-Browser tests run via **Playwright Chromium** in headless mode.
+### Testing — `vitest.config.ts` (root)
 
-| Option            | Value                            | Notes                                              |
-| ----------------- | -------------------------------- | -------------------------------------------------- |
-| `pool`            | `"forks"`                        | Isolated process per browser project               |
-| `maxWorkers`      | `2`                              | Capped lower than Node tests (Playwright overhead) |
-| `isolate`         | `true`                           | Full isolation                                     |
-| `fileParallelism` | `false`                          | Sequential file execution                          |
-| `testTimeout`     | `20000` ms                       | Higher than Node (UI rendering overhead)           |
-| `hookTimeout`     | `30000` ms                       | Same as Node                                       |
-| `teardownTimeout` | `30000` ms                       | Same as Node                                       |
-| `globalSetup`     | `vitest.browser.global-setup.ts` | Raises `process.setMaxListeners` to `32`           |
-| `resolve`         | `xmResolve(...)`                 | Source aliases + `conditions: ["source"]`          |
+**Location:** `/vitest.config.ts`
+**Tool:** [Vitest](https://vitest.dev/) `^4.1.5`
+**Run:** `npm test` / `npm run test:coverage`
 
-The `projects` array lists 24 browser test configs (package-level unit browser tests and demo app integration flows).
+Root Vitest config is a **workspace coordinator** that lists all per-package configs under `test.projects`. It sets conservative monorepo-wide defaults:
 
-**Run command:**
+| 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 |                                                        |
 
-```bash
-npm run test:browser    # vitest run --config vitest.browser.config.ts
-```
+**Coverage thresholds** (monorepo aggregate — `vitest run --coverage`):
 
-### Shared Vitest Helper ([`@xmachines/shared/vitest`](../api/@xmachines/shared/vitest/README.md))
+| Type       | Threshold |
+| ---------- | --------- |
+| Lines      | 80%       |
+| Functions  | 80%       |
+| Branches   | 75%       |
+| Statements | 80%       |
 
-**Source:** `packages/shared/config/vitest.ts`  
-**Exported as:** [`@xmachines/shared/vitest`](../api/@xmachines/shared/vitest/README.md)
+Coverage provider: `v8`. Individual packages may declare higher per-package thresholds in their own `vitest.config.ts`.
 
-All packages call [`defineXmVitestConfig(import.meta.url, overrides)`](../api/@xmachines/shared/vitest/functions/defineXmVitestConfig.md) instead of `defineConfig` directly. This helper automatically:
+**Browser test config:** `/vitest.browser.config.ts`
+Run with `npm 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`).
 
-1. Injects `resolve.alias: xmAliases(import.meta.url)` so `@xmachines/*` packages resolve to TypeScript source.
-2. Prepends `vitest.node.setup.ts` for non-browser projects (enforces Node.js >= 22.0.0 at runtime).
-3. Prepends `vitest.setup.ts` (extends matchers with `@testing-library/jest-dom`).
+### Per-Package Vitest Config — `@xmachines/shared/vitest`
 
-Setup injection is additive — caller-provided `setupFiles` are appended after the shared ones.
+**Location:** `packages/shared/config/vitest.ts`
+**Exported as:** `@xmachines/shared/vitest`
 
-### Per-Package Vitest Config Pattern
+Packages use `defineXmVitestConfig(import.meta.url, overrides)` to create their config. It automatically injects:
 
-Packages use one of two environment patterns:
+- `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).
 
-**Node environment (core packages):**
+**Typical per-package usage:**
 
 ```typescript
 // packages/<name>/vitest.config.ts
@@ -354,187 +292,92 @@ import { defineXmVitestConfig } from "@xmachines/shared/vitest";
 
 export default defineXmVitestConfig(import.meta.url, {
 	test: {
-		environment: "node",
-		include: ["test/**/*.spec.ts", "test/**/*.test.ts"],
-		exclude: ["node_modules/**"],
-		coverage: {
-			/* package-specific thresholds */
-		},
-	},
-});
-```
-
-**Browser environment (packages with DOM interaction):**
-
-```typescript
-// packages/<name>/vitest.browser.config.ts
-import { defineConfig } from "vitest/config";
-import { playwright } from "@vitest/browser-playwright";
-import { xmResolve, xmCacheDir, xmOptimizeDeps } from "@xmachines/shared/vite-aliases";
-
-export default defineConfig({
-	cacheDir: xmCacheDir(import.meta.url, "<project-name>"),
-	resolve: xmResolve(import.meta.url),
-	optimizeDeps: xmOptimizeDeps([
-		/* framework packages */
-	]),
-	test: {
-		name: "<project-name>",
-		browser: {
-			enabled: true,
-			provider: playwright(),
-			headless: true,
-			instances: [{ browser: "chromium" }],
-		},
-		include: ["test/browser/**/*.browser.test.ts"],
+		name: "play-example",
+		include: ["test/**/*.test.ts"],
 	},
 });
 ```
 
-### Coverage Thresholds
-
-Coverage is enforced by `@vitest/coverage-v8`. Thresholds apply at two levels:
-
-**Root (regression gate) — `vitest.config.ts`:**
+### Vite Source Aliases — `@xmachines/shared/vite-aliases`
 
-| Type       | Threshold |
-| ---------- | --------- |
-| Lines      | 80%       |
-| Functions  | 80%       |
-| Branches   | 75%       |
-| Statements | 80%       |
-
-**Core packages** (`play`, `play-actor`, `play-signals` and others with highest standards):
+**Location:** `packages/shared/config/vite-aliases.ts`
+**Exported as:** `@xmachines/shared/vite-aliases`
 
-| Type       | Threshold |
-| ---------- | --------- |
-| Lines      | 90%       |
-| Functions  | 90%       |
-| Branches   | 85%       |
-| Statements | 90%       |
+Provides two helpers used in all `vitest.config.ts` and `vite.config.ts` files:
 
-**Integration/renderer packages** (e.g., `play-react`, `play-vue`, `play-solid`):
+- **`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 `npm 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.
 
-| Type       | Threshold |
-| ---------- | --------- |
-| Lines      | 80%       |
-| Functions  | 80%       |
-| Branches   | 80%       |
-| Statements | 80%       |
+### Release — `release.config.mjs`
 
-Coverage reports are produced in `text`, `html`, and `json-summary` formats, written to `coverage/` (gitignored).
+**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 Configuration (`.releaserc.json`)
+**Release branches:**
 
-**Source:** `.releaserc.json`  
-**Tool:** `semantic-release`
+| Branch   | Channel   | Pre-release |
+| -------- | --------- | ----------- |
+| `main`   | (default) | No          |
+| `pre/rc` | `pre/rc`  | `rc`        |
+| `beta`   | `beta`    | `true`      |
 
-| Setting            | Value                                                  |
-| ------------------ | ------------------------------------------------------ |
-| Tag format         | `v${version}`                                          |
-| Stable branch      | `main`                                                 |
-| Pre-release branch | `beta` (channel: `beta`, prerelease: auto-incremented) |
-| RC branch          | `pre/rc` (channel: `pre/rc`, prerelease: `rc`)         |
+**Tag format:** `v${version}`
 
-**Release plugins in order:**
+**Plugin order:**
 
 1. `@semantic-release/commit-analyzer` — determines version bump from conventional commits
-2. `@semantic-release/release-notes-generator` — generates changelog entries
+2. `@semantic-release/release-notes-generator` — builds release notes
 3. `@semantic-release/changelog` — writes `CHANGELOG.md`
-4. `@semantic-release/exec` — runs `set-workspace-versions.mjs`, builds all packages, regenerates TypeDoc API docs
-5. `@semantic-release/npm` — publishes each public package to npm (18 packages total)
-6. `@semantic-release/git` — commits updated `CHANGELOG.md`, `package.json`, `package-lock.json`, all per-package `package.json` files, and generated API docs
+4. `@semantic-release/exec` steps (in order):
+    - `install` — `npm ci`
+    - `apply-patches` — `npm run apply-patches`
+    - `set-workspace-versions` — updates all `package.json` files to the new version
+    - `build` — `npm run build`
+    - `typedoc` — `npm run typedoc -w @xmachines/docs`
+    - `format-docs` — `npm run format -w @xmachines/docs`
+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
 
-Packages with `npmPublish: false` (all `examples/demo` packages) are packed as tarballs but not published to npm.
-
-The `NPM_ID_TOKEN` GitLab CI token is used for authenticated npm publishing via OIDC. <!-- VERIFY: NPM_OIDC_token configuration details are managed in GitLab CI/CD secrets -->
+Any step can be skipped via the `SEMREL_SKIP_STEPS` CI variable (see [Environment Variables](#environment-variables)).
 
 ---
 
-## CI/CD Configuration (`.gitlab-ci.yml`)
-
-**Source:** `.gitlab-ci.yml`
-
-**Pipeline trigger conditions:**
-
-| Condition                                 | Trigger                       |
-| ----------------------------------------- | ----------------------------- |
-| `$CI_COMMIT_TAG`                          | Tag push                      |
-| `$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH` | Push to default branch (main) |
-| `$CI_MERGE_REQUEST_IID`                   | Merge request                 |
-
-**Included components:**
-
-| Component                                            | Version | Purpose                                   |
-| ---------------------------------------------------- | ------- | ----------------------------------------- |
-| `to-be-continuous/node/gitlab-ci-node`               | `5.1.2` | Node.js build, test, lint, and audit jobs |
-| `to-be-continuous/semantic-release/gitlab-ci-semrel` | `4.1.0` | Automated versioning and release          |
-
-**node-build job** (the primary test job):
-
-| Setting             | Value                                                        |
-| ------------------- | ------------------------------------------------------------ |
-| Test command        | See below                                                    |
-| Coverage extraction | Regex — see below                                            |
-| JUnit report        | `reports/junit.xml`                                          |
-| Coverage report     | `reports/coverage/cobertura-coverage.xml` (Cobertura format) |
-| Audit level         | `--audit-level=high`                                         |
-
-Test command:
-
-```
-npm run test:coverage -- --coverage.reporter=text --coverage.reporter=cobertura --coverage.reportsDirectory=reports/coverage --reporter=default --reporter=junit --outputFile.junit=reports/junit.xml
-```
-
-Coverage extraction regex:
-
-```
-/All files[^|]*\|[^|]*\s+([\d\.]+)/
-```
-
-**semantic-release job:**
+## Per-Environment Overrides
 
-| Setting            | Value                    |
-| ------------------ | ------------------------ |
-| Release branches   | `main`, `beta`, `pre/rc` |
-| Artifact path      | `dist/releases/*.tgz`    |
-| Artifact retention | 1 week                   |
+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.
 
-Jobs tagged as `rules: *auto-or-manual` run automatically on tag/main-branch pushes and are available as manual triggers on MRs.
+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.
 
 ---
 
-## npm Overrides and Patches
-
-**Source:** `package.json` `overrides` section and `patches/` directory
-
-The root `package.json` declares two npm overrides to pin transitive dependency versions:
-
-| Package           | Override                    | Reason                              |
-| ----------------- | --------------------------- | ----------------------------------- |
-| `glob`            | `^13.0.6`                   | Pin to compatible major             |
-| `whatwg-encoding` | `npm:@exodus/bytes@^1.15.0` | Replace with compatible alternative |
+## Required vs Optional Settings Summary
 
-Patches are applied automatically on `npm install` via the `postinstall` script:
-
-```bash
-# Applied via postinstall → patch-package
-npm ci   # patches applied automatically after install
-```
-
-To re-apply patches manually:
-
-```bash
-npm run apply-patches    # runs patch-package
-```
+| Config                               | Required to Work                      | Optional / Has Default        |
+| ------------------------------------ | ------------------------------------- | ----------------------------- |
+| `OPENCODE_EXPERIMENTAL_OXFMT`        | No                                    | Default: `false`              |
+| `OPENCODE_PORT_MAPPING`              | No                                    | Default: `4096`               |
+| `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     | —                             |
 
 ---
 
-## Per-Environment Overrides
+## Adding a New Package
+
+When adding a new package, update these configuration files:
 
-This project does not use `.env.development`, `.env.production`, or `.env.test` files. There are no per-environment configuration overrides — the same config files apply in all contexts.
+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`.
 
-The one environment-aware distinction is in Vitest: the `source` custom condition in `tsconfig` / Vite resolve config causes `@xmachines/*` imports to resolve to TypeScript source during development and testing, while production builds use the compiled `dist/` output via the standard `exports` field in each package's `package.json`.
+See [AGENTS.md](../AGENTS.md) for the full new-package checklist.