game-harness 1.0.0

package/docs/contributing.md

@@ -0,0 +1,21 @@
+---
+title: Contributing
+description: Development, validation, and pull-request expectations.
+---
+
+Game Harness uses pnpm and Node from `.nvmrc` (Node 22 or newer).
+
+```sh
+mise install # or: nvm use && corepack enable
+pnpm install --frozen-lockfile
+pnpm verify
+```
+
+Write a focused test, implement the change, and run `pnpm verify` before
+opening a pull request. Use a Conventional Commit (`fix:`, `feat:`, `docs:`,
+`refactor:`, `test:`, or `chore:`); release-please owns release versions and
+the changelog.
+
+Open a same-upstream branch and PR. Do not push directly to `main`, rebase a
+shared branch, or squash a completed PR: the repository preserves merge-commit
+history. See the repository's [full contribution guide](https://github.com/jbcom/game-harness/blob/main/CONTRIBUTING.md).

package/docs/entry-points.md

@@ -0,0 +1,41 @@
+---
+title: Entry points
+description: The full map of Game Harness subpath exports and their required peers.
+---
+
+Import only the entry point a game uses:
+
+- `game-harness/playwright` for Playwright projects and strict
+  preview-server configuration; install `@playwright/test`.
+- `game-harness/silent-qa` for a peer-free,
+  audio-engine-agnostic application-side runtime mute adapter.
+- `game-harness/production-runtime` for a fresh, silent
+  production-artifact or exact-live boot; install `@playwright/test`.
+- `game-harness/chromium` for peer-free Chromium renderer and
+  silence launch profiles.
+- `game-harness/vitest` for Vitest Browser Mode; install
+  `vitest` and `@vitest/browser-playwright`.
+- `game-harness`, `/lighthouse`, `/release-ladder`, and
+  `/visual-battery` for peer-free verification utilities.
+
+Framework peers are intentionally optional at install time and are never
+loaded by the package root.
+
+## Package boundaries
+
+| Entry point           | Responsibility                                                  | Required peer                          |
+| --------------------- | --------------------------------------------------------------- | -------------------------------------- |
+| package root          | Lighthouse policy, release ladder, visual battery               | None                                   |
+| `/chromium`           | Renderer and mandatory mute launch profile                      | None                                   |
+| `/silent-qa`          | Application-side runtime mute request and readiness marker      | None                                   |
+| `/playwright`         | Device tiers, isolated ports, preview server, silent navigation | `@playwright/test`                     |
+| `/production-runtime` | Fresh server/browser lifecycle and runtime evidence             | `@playwright/test`                     |
+| `/vitest`             | Vitest Browser Mode configuration                               | `vitest`, `@vitest/browser-playwright` |
+| `/lighthouse`         | Immutable Lighthouse CI presets                                 | None                                   |
+| `/release-ladder`     | Ordered sync/async verification steps                           | None                                   |
+| `/visual-battery`     | Deterministic screenshot baseline orchestration                 | None                                   |
+
+The production-runtime entry point depends on the Playwright entry point
+because it composes `openSilentGame()` into a fresh-browser lifecycle; no
+dependency points back toward the root. See the [Architecture reference](/game-harness/reference/architecture/)
+for the complete module map and runtime-verification sequence.

package/docs/getting-started.md

@@ -0,0 +1,42 @@
+---
+title: Getting started
+description: Install Game Harness and pick the entry points your game needs.
+---
+
+Node 22 or newer is required. Install the package plus only the peer family
+for the integration you use:
+
+```sh
+# Playwright config and production-runtime verification
+pnpm add -D game-harness @playwright/test
+pnpm exec playwright install chromium
+
+# Vitest Browser Mode instead
+pnpm add -D game-harness vitest @vitest/browser-playwright playwright
+pnpm exec playwright install chromium
+
+# Peer-free Lighthouse, release-ladder, or visual-battery utilities
+pnpm add -D game-harness
+```
+
+Framework peers are intentionally optional at install time and are never
+loaded by the package root. Each consumer installs only the peers required by
+the framework entry point it imports — a Playwright-only game installs
+`@playwright/test` but does not need Vitest or `@vitest/browser-playwright`.
+
+## Current release matrix
+
+`engines.node` declares `>=22`, the earliest Node LTS line still actively
+supported. CI pins the primary gate to the version in `.nvmrc` (currently
+24.19.0, the latest Node 24 LTS patch) and additionally runs the full test
+and build suite against Node 22 on Linux to prove the floor of that range,
+alongside macOS and Windows portability on the pinned version. The current
+conformance matrix is Playwright 1.62.1 and Vitest Browser 4.1.10.
+Package-boundary consumers run with a credential-free home directory and npm
+configuration, install only the peer family needed by each entry point, and
+exercise ESM, CommonJS, the CLI, silent runtime markers, and Chromium launch
+profiles. `publint` and `@arethetypeswrong/cli` independently validate package
+metadata and declarations.
+
+Continue to [Quick start](/game-harness/quick-start/) to wire up the silent
+runtime marker and your first Playwright config.

package/docs/guides/chromium-and-silent-qa.md

@@ -0,0 +1,72 @@
+---
+title: Chromium launch profile & Silent QA
+description: The peer-free primitives behind every silent browser launch.
+---
+
+```ts
+import { chromium } from '@playwright/test';
+import { createChromiumLaunchProfile } from 'game-harness/chromium';
+
+const { args, env } = createChromiumLaunchProfile({
+  gpuMode: process.platform === 'linux' && process.env.CI ? 'linux-hardware-vulkan' : 'auto',
+});
+const browser = await chromium.launch({ args, env, headless: false });
+```
+
+`createChromiumLaunchProfile()` is the peer-free primitive behind both
+`definePlaywrightConfig()` and `defineBrowserTestConfig()` — use it directly
+when driving Chromium yourself (a custom launch script, `production-runtime`'s
+own internals, or a non-Playwright automation layer). It resolves one of
+three renderer policies (`auto` leaves selection to Chromium; `software`
+opts into SwiftShader explicitly; `linux-hardware-vulkan` applies the
+reviewed Mesa/ANGLE flags plus `EGL_PLATFORM=surfaceless` for a runner
+exposing `/dev/dri/renderD128`) and always de-duplicates and appends
+`--mute-audio` last, so a caller-supplied arg list can never accidentally
+drop the silence guard.
+
+Every browser launched by `definePlaywrightConfig()` or
+`defineBrowserTestConfig()` receives Chromium's `--mute-audio` argument as a
+defense-in-depth guard, including projects with custom launch options. The
+application must also expose a non-persistent mute mode so tests fail closed
+before interacting with it:
+
+```ts
+import { activateSilentQa } from 'game-harness/silent-qa';
+import { Howler } from 'howler';
+
+// Evaluate before the rest of the application/audio graph.
+export const silentQaActive = activateSilentQa(() => Howler.mute(true));
+```
+
+`activateSilentQa()` detects `?muted` by presence, invokes the consumer-owned
+audio-engine callback, and only then publishes
+`<html data-audio-mode="muted-test">`. It never reads or writes saved audio
+preferences. Consumers use its boolean return value or `isSilentQaActive()`
+to prevent later preference restoration from overriding the page-lifetime
+mute. If the audio engine mutes asynchronously, await
+`activateSilentQaAsync()`; passing a promise-returning callback to the
+synchronous function throws instead of publishing a premature readiness
+marker.
+
+```ts
+import { openSilentGame } from 'game-harness/playwright';
+
+test('starts a game without audible QA', async ({ page }) => {
+  await openSilentGame(page, '/my-game/', { scenario: 'new-game' });
+  // The helper returns only after html[data-audio-mode="muted-test"] exists.
+});
+```
+
+`openSilentGame()` adds `?muted=1` (preserving other query parameters and the
+fragment), navigates, and requires the application to set
+`data-audio-mode="muted-test"` on `<html>`. The mute mode is runtime-only: it
+must mute audio before any sound objects can play and must never write the
+player's saved audio preference. Use `silentTestUrl()` when a test needs the
+URL without navigating. Custom marker/query names are supported for legacy
+adapters, but new games use these defaults. There is no audible-debug
+exception: verify audio behavior through programmatic state, mocks, or
+analyser assertions while agent-controlled playback remains muted.
+
+Keep `reuseExistingServer` false for release evidence and assert the game
+identity before exercising a journey. A process from another repository on a
+familiar port must never be accepted as proof.

package/docs/guides/lighthouse-and-release-ladder.md

@@ -0,0 +1,62 @@
+---
+title: Lighthouse presets & release ladder
+description: Immutable Lighthouse CI assertions and a thin ordered-step release orchestrator.
+---
+
+## Lighthouse CI presets
+
+```ts
+// lighthouserc.mjs
+import { lighthouseAssertions } from 'game-harness/lighthouse';
+
+const config = lighthouseAssertions('game-default', {
+  url: ['http://localhost/index.html', 'http://localhost/settings/index.html'],
+  assertions: { 'categories:performance': ['warn', { minScore: 0.5 }] },
+});
+
+console.log(JSON.stringify(config, null, 2));
+```
+
+`lighthouseAssertions()` returns a `lighthouserc.json`-shaped config object
+for a named preset, with `overrides` merged on top (assertion overrides are
+merged key-by-key on top of the preset's own; every other override field
+replaces it wholesale). The only shipped preset, `'game-default'`, is a
+production `lighthouserc.json` verbatim: performance/accessibility/best-practices
+assertions at warn level (a score dip surfaces in CI logs without
+hard-blocking a merge on Lighthouse's inherent run-to-run variance), with SEO
+and PWA assertions off since these are single-page game shells with no SEO
+surface and no installable-PWA requirement. To keep `lighthouserc.json` as
+static JSON instead of a `.mjs` config, run this once locally and paste the
+printed object — the factory has no runtime dependency on the consumer's
+environment beyond the `overrides` you pass.
+
+## Release ladder orchestrator
+
+```ts
+import { verifyReleaseLadder } from 'game-harness/release-ladder';
+import { execSync } from 'node:child_process';
+
+const result = await verifyReleaseLadder([
+  { name: 'lint', run: () => execSync('pnpm lint', { stdio: 'inherit' }) },
+  {
+    name: 'typecheck',
+    run: () => execSync('pnpm typecheck', { stdio: 'inherit' }),
+  },
+  { name: 'test', run: () => execSync('pnpm test', { stdio: 'inherit' }) },
+  { name: 'build', run: () => execSync('pnpm build', { stdio: 'inherit' }) },
+]);
+
+process.exit(result.ok ? 0 : 1);
+```
+
+`verifyReleaseLadder()` is a thin orchestrator for a `verify:*` release
+ladder — an ordered list of named steps, each a plain sync or async function,
+run in sequence and stopped at the first failure with a labeled summary. It
+generalizes the pattern of many discrete `node scripts/verify-X.mjs` files
+composed via a shell `&&` chain into one reusable primitive: a step can
+inline its logic or delegate to an existing script via `execSync`. It never
+throws — it returns a `ReleaseLadderResult` (`{ ok, ranSteps, failedStep?,
+error? }`) so the caller decides how to report or exit;
+`process.exit(result.ok ? 0 : 1)` is the CLI convention. Pass `{ log, error
+}` to redirect the default `console.log`/`console.error` output (both
+prefixed with `[verify]`).

package/docs/guides/playwright.md

@@ -0,0 +1,58 @@
+---
+title: Playwright
+description: Deterministic ports, strict-port preview servers, and silent Chromium launches.
+---
+
+```ts
+import { definePlaywrightConfig } from 'game-harness/playwright';
+
+export default definePlaywrightConfig({
+  port: 4391,
+  deviceTiers: ['desktop', 'mobile'],
+  gpuMode: process.platform === 'linux' && process.env.CI ? 'linux-hardware-vulkan' : 'auto',
+  webServerCommand: (port) =>
+    `pnpm build && pnpm exec vite preview --host 127.0.0.1 --port ${port} --strictPort`,
+});
+```
+
+The configured `port` is the stable local-development port. On GitHub or
+Gitea Actions, the factory derives a deterministic port from repository, run,
+and job identity so concurrent workflows cannot accidentally share the same
+preview. Every Playwright config reload in the parent and worker processes
+resolves the same value. `PLAYWRIGHT_PORT` or `PW_PORT` remains an exact
+override. A rare cross-process/hash collision still fails closed because the
+preview must use strict-port semantics; it never reuses a reachable process.
+
+Playwright 1.62 forces coloured output in its web-server and worker children.
+If the invoking shell exports `NO_COLOR`, Node warns that the variable is
+ignored once Playwright adds `FORCE_COLOR=1`. During config evaluation the
+factory therefore removes only the already-ignored `NO_COLOR` value from the
+Playwright process environment before those children are spawned. This does
+not modify the parent shell, and every other environment variable and
+warning remains intact.
+
+Use `webServerCommand(port)` when a consumer needs build or
+asset-preparation steps around its preview. The callback receives the
+already-resolved local or CI-isolated port. A literal
+`overrides.webServer.command` remains supported, but a command that
+hard-codes its own port bypasses isolation and is not valid release evidence.
+
+Chromium is headed by default locally and in CI. Linux CI must provide a
+display with `xvfb-run`; it should not change the browser to headless simply
+to make WebGL start. The default `auto` profile lets Chromium select the
+native renderer (including Metal on macOS). `software` is an explicit
+SwiftShader fallback. `linux-hardware-vulkan` applies the reviewed
+Mesa/ANGLE flags and `EGL_PLATFORM=surfaceless` for a runner that exposes
+`/dev/dri/renderD128`.
+
+A Gitea runner job using the hardware profile must install
+`mesa-vulkan-drivers` and `xvfb`, require the render device with
+`test -c /dev/dri/renderD128`, and run the browser command under
+`xvfb-run --auto-servernum`. Use `requireHardwareWebGL()` in the journey
+itself so a green test cannot silently fall back to SwiftShader or llvmpipe.
+The assertion also fails closed when the browser withholds its unmasked
+renderer.
+
+`deviceTiers` declares the available matrix, while the default fast gate runs
+only its first tier. Run `MULTIVIEW=1 pnpm exec playwright test` (or
+`VISUAL=1 ...`) to include every declared tier.

package/docs/guides/production-runtime.md

@@ -0,0 +1,61 @@
+---
+title: Production runtime verification
+description: Turn a successful build into runtime evidence with a fresh, silent, fail-closed browser session.
+---
+
+`verifyProductionRuntime()` turns a successful build into runtime evidence. It
+launches a fresh Chromium process with `--mute-audio` and uses headed mode by
+default,
+navigates through `openSilentGame()`, and fails on page errors, console
+errors, failed requests, HTTP errors, an inactive silent-QA marker, or a
+changed local-storage sentinel. The required `assertReady` callback pins game
+identity and the primary UI or canvas instead of accepting any app that
+happens to answer on the same port.
+
+```ts
+import {
+  findAvailableProductionPort,
+  requireHardwareWebGL,
+  verifyProductionRuntime,
+} from 'game-harness/production-runtime';
+
+const port = await findAvailableProductionPort();
+
+await verifyProductionRuntime({
+  url: `http://127.0.0.1:${port}/`,
+  gpuMode: process.platform === 'linux' && process.env.CI ? 'linux-hardware-vulkan' : 'auto',
+  server: {
+    command: process.execPath,
+    args: [
+      'node_modules/vite/bin/vite.js',
+      'preview',
+      '--host=127.0.0.1',
+      `--port=${port}`,
+      '--strictPort',
+    ],
+  },
+  localStorageSentinels: { 'settings::muted': 'false' },
+  assertReady: async (page) => {
+    await page.getByRole('heading', { name: 'My Game' }).waitFor();
+    await page.locator('canvas').waitFor({ state: 'visible' });
+    const { renderer } = await requireHardwareWebGL(page);
+    console.log(`WebGL renderer: ${renderer}`);
+  },
+});
+```
+
+Pass `browserLaunchOptions: { headless: true }` only for a deliberately
+constrained non-visual check. Release and final gameplay proof remain headed.
+
+When `server` is present, its readiness URL must be unreachable before
+launch; the verifier never reuses an arbitrary process. It owns that child
+process, waits for readiness, and terminates it after either success or
+failure. Omit `server` to apply the same strict gate to an already-deployed
+exact-live URL. Every reachable readiness probe cancels its response body
+after recording the status, including non-OK retry responses. A long polling
+loop must not retain response streams or connections while it waits for the
+owned server. Use `findAvailableProductionPort()` for CI or any shared runner
+instead of a hard-coded port. It delegates selection to `get-port`, reserves
+that selection against parallel calls in the current process, and still
+requires the owned server to bind with strict-port semantics so an external
+race fails closed.

package/docs/guides/visual-battery.md

@@ -0,0 +1,58 @@
+---
+title: Visual battery
+description: Deterministic, fail-closed screenshot baseline orchestration.
+---
+
+Run the default harness directory in update mode, or enforce committed
+baselines in CI:
+
+```sh
+pnpm exec game-harness-visual-battery tests/harness
+pnpm exec game-harness-visual-battery tests/harness --ci
+```
+
+`test-harness-visual-battery` remains as a compatibility alias. Programmatic
+callers can pass `testCommand: { command, args }`; the executable and
+discovered harness paths are invoked directly rather than interpolated
+through a shell.
+
+`runVisualBattery()` owns one canonical `__screenshots__` tree directly under
+the configured harness directory. Vitest screenshot paths are relative to the
+test file, so a harness must write `__screenshots__/name.png`, not a
+repository-relative path such as `tests/harness/__screenshots__/name.png`.
+The battery rejects any second `__screenshots__` directory nested elsewhere
+under the harness tree; otherwise an apparently green run could leave an
+important screenshot outside the Git diff gate.
+
+When two renderers cannot produce byte-identical PNGs, keep strict profiles
+instead of adding a pixel threshold. Pass `baselineProfile: 'linux'`; the
+battery compares `__screenshots__/linux/` and exposes the same value to Vite
+as `VITE_VISUAL_BASELINE_PROFILE`. Screenshot helpers should include that
+optional directory in their path:
+
+```ts
+const profile = import.meta.env.VITE_VISUAL_BASELINE_PROFILE?.trim();
+const path = profile ? `__screenshots__/${profile}/scene.png` : '__screenshots__/scene.png';
+```
+
+`baselinesDir` names the baseline root. When it is combined with
+`baselineProfile`, the profile is always appended below that root. For
+example, `{ baselinesDir: 'visual-baselines', baselineProfile: 'linux' }`
+owns and diffs `visual-baselines/linux/`.
+
+For WebGL scenes, capture the canvas locator instead of the full browser
+page:
+
+```ts
+await page.locator('canvas').screenshot({ path: '__screenshots__/scene.png' });
+```
+
+If a canvas baseline is stable alone but changes after other harnesses have
+run in the same long-lived Chromium process, isolate that file so it gets a
+fresh browser process while the remaining files stay in one fast batch:
+
+```ts
+runVisualBattery('tests/harness', {
+  isolatedHarnessFiles: ['scene.browser.test.tsx'],
+});
+```

package/docs/guides/vitest.md

@@ -0,0 +1,41 @@
+---
+title: Vitest Browser Mode
+description: A real-Chromium Vitest Browser Mode project, headed by default and silent at launch.
+---
+
+```ts
+import { defineConfig } from 'vitest/config';
+import { defineBrowserTestConfig } from 'game-harness/vitest';
+
+export default defineConfig({
+  test: {
+    projects: [
+      {
+        extends: true,
+        test: { name: 'unit', environment: 'node', include: ['tests/unit/**'] },
+      },
+      {
+        extends: true,
+        test: defineBrowserTestConfig({
+          optimizeDeps: ['three/examples/jsm/utils/SkeletonUtils.js'],
+        }),
+      },
+    ],
+  },
+});
+```
+
+`defineBrowserTestConfig()` builds the `test` fragment for a real-Chromium
+Vitest Browser Mode project: headed by default (both locally and in CI, same
+as `definePlaywrightConfig()`), silent at the Chromium launch boundary, and a
+fixed viewport with `deviceScaleFactor: 1` so a headed macOS run never
+recaptures visual baselines at the host's Retina scale. Pass `headless:
+'ci-only'` only for a hosted runner genuinely without a display; CI should
+normally keep the headed default and run under `xvfb-run`. Requires `vitest`
+and `@vitest/browser-playwright` installed as peers.
+
+`optimizeDeps` surfaces module specifiers (deep imports Vite's scanner won't
+discover on its own) that must also be merged into your top-level
+`vite.config.ts`'s `optimizeDeps.include` — read them off the returned
+fragment's `__optimizeDepsInclude` field, since Vitest's `test` block has no
+`optimizeDeps` field of its own.

package/docs/introduction.md

@@ -0,0 +1,29 @@
+---
+title: Game Harness
+description: Release-grade browser QA primitives for TypeScript games.
+---
+
+Game Harness turns a successful build into evidence: silent browser sessions,
+deterministic device tiers, byte-exact screenshots, production-runtime proof,
+and Lighthouse gates.
+
+It is intentionally a focused library rather than a test framework. Your game
+keeps its own journeys, assertions, art direction, and audio engine; Game
+Harness supplies the reusable safety and orchestration layer around Playwright
+and Vitest Browser Mode.
+
+## Why Game Harness
+
+- **Silent by construction.** Chromium launches with `--mute-audio`, and tests
+  wait for an application-owned runtime mute marker before interacting.
+- **No accidental server reuse.** CI ports are deterministic per job, preview
+  commands use strict-port semantics, and production verification refuses an
+  already-reachable readiness URL.
+- **Visual evidence that fails closed.** Screenshot baselines are scoped,
+  profile-aware, and checked through Git without fuzzy thresholds or shell
+  interpolation.
+- **Real package boundaries.** Framework peers stay optional and isolated to
+  subpath exports, with clean ESM, CommonJS, type, CLI, and install smoke tests.
+
+Start with [Getting started](getting-started/) to choose the integration your
+game needs.

package/docs/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "game-harness-docs",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "sourcey dev",
+    "build": "sourcey build",
+    "validate": "sourcey build"
+  },
+  "dependencies": {
+    "sourcey": "^3.6.0"
+  }
+}

package/docs/quick-start.md

@@ -0,0 +1,47 @@
+---
+title: Quick start
+description: Wire up the silent runtime marker and your first Playwright config.
+---
+
+Activate the runtime-only mute before the application restores saved audio
+preferences or creates anything that can play sound:
+
+```ts
+// src/silent-qa.ts
+import { activateSilentQa } from 'game-harness/silent-qa';
+import { Howler } from 'howler';
+
+export const silentQaActive = activateSilentQa(() => Howler.mute(true));
+```
+
+Then use the shared Playwright config and open the game through the
+fail-closed navigation helper:
+
+```ts
+// playwright.config.ts
+import { definePlaywrightConfig } from 'game-harness/playwright';
+
+export default definePlaywrightConfig({
+  port: 4391,
+  webServerCommand: (port) =>
+    `pnpm build && pnpm exec vite preview --host 127.0.0.1 --port ${port} --strictPort`,
+});
+```
+
+```ts
+// tests/e2e/boot.spec.ts
+import { expect, test } from '@playwright/test';
+import { openSilentGame } from 'game-harness/playwright';
+
+test('boots the intended game silently', async ({ page }) => {
+  await openSilentGame(page, '/my-game/', { scenario: 'new-game' });
+  await expect(page.getByRole('heading', { name: 'My Game' })).toBeVisible();
+  await expect(page.locator('canvas')).toBeVisible();
+});
+```
+
+The application marker is part of the contract: `openSilentGame()` does not
+return until `<html data-audio-mode="muted-test">` exists.
+
+Continue to [Entry points](/game-harness/entry-points/) for the full map of
+subpath exports, or jump straight to the [Playwright guide](/game-harness/guides/playwright/).

package/docs/reference/troubleshooting.md

@@ -0,0 +1,33 @@
+---
+title: Troubleshooting
+description: Common failure modes and their causes.
+---
+
+- **A headed browser cannot start on Linux CI:** install Chromium
+  dependencies and run the browser command with `xvfb-run --auto-servernum`;
+  do not silently switch release evidence to headless mode.
+- **`PLAYWRIGHT_PORT` or `PW_PORT` is rejected:** overrides must be integer
+  TCP ports from 1 through 65535. Invalid explicit values fail instead of
+  falling back to another port.
+- **The visual battery reports zero PNGs:** each harness must write into its
+  canonical `__screenshots__` directory. An existing but empty directory is
+  not release evidence.
+- **`test:package` reports an npm version too old:** the package-boundary test
+  requires npm 10 or newer (bundled with every Node version in the supported
+  `>=22` range); use the Node version from `.nvmrc` or any newer supported
+  LTS.
+- **A local Chrome channel is unavailable:** leave `PW_CHROMIUM_CHANNEL`
+  unset on CI to use Playwright's bundled Chromium, or set it explicitly to
+  an installed supported channel for a local branded-browser run.
+
+## Releases and support
+
+Conventional commits on `main` are collected into a release pull request by
+release-please. Merging that pull request creates the GitHub release and
+publishes the exact tag to npm with provenance after `pnpm verify` passes.
+Changes are recorded in the [CHANGELOG](https://github.com/jbcom/game-harness/blob/main/CHANGELOG.md).
+
+Report defects and feature requests through the
+[repository issue forms](https://github.com/jbcom/game-harness/issues).
+Report vulnerabilities privately as described in
+[SECURITY.md](https://github.com/jbcom/game-harness/blob/main/SECURITY.md).

package/docs/security.md

@@ -0,0 +1,15 @@
+---
+title: Security
+description: Report vulnerabilities privately and understand the project's security boundary.
+---
+
+Do not report security issues in a public issue. Use [GitHub private security
+advisories](https://github.com/jbcom/game-harness/security/advisories/new) so a
+fix can be prepared before disclosure. The latest minor release receives
+security fixes.
+
+For the complete reporting policy, see [SECURITY.md](https://github.com/jbcom/game-harness/blob/main/SECURITY.md).
+
+Every pull request must pass the dependency-review and repository-policy checks
+before it can merge. The repository-policy check treats changes from external
+forks as untrusted and rejects edits to the repository control plane.