docs(ci): finalize global install runtime docs and smoke coverage

.github/workflows/installer-smoke.yml

@@ -0,0 +1,49 @@
+name: Installer Smoke
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - master
+
+jobs:
+  installer-smoke-ubuntu:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - run: npm link
+      - run: bash ./install/install.sh
+      - run: beadboard doctor --json
+      - run: node --import tsx --test tests/scripts/beadboard-launcher.test.ts
+      - run: node --import tsx --test tests/scripts/install-wrappers-contract.test.ts
+      - run: node --import tsx --test tests/scripts/install-sh-smoke.test.ts
+      - run: node --import tsx --test tests/skills/beadboard-driver/resolve-bb.test.ts
+
+  installer-smoke-windows:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - run: npm link
+      - name: Run PowerShell installer wrapper
+        shell: pwsh
+        run: .\install\install.ps1
+      - name: Run installer doctor
+        shell: pwsh
+        run: beadboard doctor --json
+      - name: Verify installed shims
+        shell: pwsh
+        run: |
+          $shimDir = Join-Path $HOME ".beadboard\bin"
+          if (!(Test-Path (Join-Path $shimDir "bb.cmd"))) { throw "Missing bb.cmd shim" }
+          if (!(Test-Path (Join-Path $shimDir "beadboard.cmd"))) { throw "Missing beadboard.cmd shim" }

README.md

@@ -95,6 +95,38 @@ cd beadboard
 npm install
 ```
 
+### Global CLI Install (Optional)
+Primary install path:
+
+```bash
+npm i -g beadboard
+```
+
+Fallback wrappers from repo root:
+
+POSIX (Linux/macOS):
+```bash
+bash ./install/install.sh
+```
+
+Windows (PowerShell):
+```powershell
+powershell -ExecutionPolicy Bypass -File .\install\install.ps1
+```
+
+Both wrappers install shims at:
+- `~/.beadboard/bin/bb`
+- `~/.beadboard/bin/beadboard`
+
+Runtime home:
+- `~/.beadboard/runtime/<version>`
+- `~/.beadboard/runtime/current.json`
+
+Launcher commands:
+- `beadboard start`
+- `beadboard open`
+- `beadboard status`
+
 ---
 
 ## Quick Start

docs/adr/2026-03-03-runtime-manager-global-install.md

@@ -41,9 +41,14 @@ Legacy repo-bound shim migration is required:
 - Rewrite shims to runtime-managed targets atomically.
 - Preserve user-facing command names and shell compatibility.
 
+## Supported Platforms
+
+- Linux: npm-global primary, POSIX wrapper fallback.
+- macOS: npm-global primary, POSIX wrapper fallback.
+- Windows: npm-global primary, PowerShell wrapper fallback.
+
 ## Failure Modes and Rollback
 
 - Missing runtime metadata: launcher reports actionable remediation and install mode.
 - Corrupt runtime target: launcher falls back to previous known-good metadata when present.
 - Partial install: installer leaves active runtime unchanged and exits non-zero.
-

docs/ops/global-install-rollout.md

@@ -0,0 +1,31 @@
+# Global Install Rollout: Runtime Manager
+
+## Objective
+Roll out npm-global-first install behavior with runtime metadata and backward-compatible shim migration.
+
+## Operator Install Paths
+1. Primary: `npm i -g beadboard`
+2. Fallback (POSIX): `bash ./install/install.sh`
+3. Fallback (Windows): `powershell -ExecutionPolicy Bypass -File .\\install\\install.ps1`
+
+## Runtime Layout
+- Shim directory: `~/.beadboard/bin`
+- Runtime versions: `~/.beadboard/runtime/<version>`
+- Active runtime metadata: `~/.beadboard/runtime/current.json`
+
+## Migration
+When existing repo-bound shims are found, installers rewrite them to runtime-aware shims that resolve runtime root from `current.json` first.
+
+## Recovery Playbook
+1. Run `beadboard doctor --json`.
+2. If metadata missing/corrupt, rerun installer fallback for your platform.
+3. If PATH missing, add `~/.beadboard/bin` to PATH.
+4. If repo-bound shim remains, rerun installer to force shim rewrite.
+
+## Platform Matrix
+- Linux: Supported
+- macOS: Supported
+- Windows: Supported
+
+## CI Validation
+Installer smoke workflow validates wrapper execution and `beadboard doctor --json` in Ubuntu and Windows jobs.

tests/docs/installer-quickstart-contract.test.ts

@@ -0,0 +1,21 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const readmePath = path.resolve('README.md');
+
+test('README documents installer one-liners for windows and posix', async () => {
+  const raw = await fs.readFile(readmePath, 'utf8');
+  assert.match(raw, /npm i -g beadboard/i);
+  assert.match(raw, /install\/install\.sh/i);
+  assert.match(raw, /install[\\/]+install\.ps1/i);
+  assert.match(raw, /~\/\.beadboard\/runtime/i);
+});
+
+test('README documents beadboard launcher commands', async () => {
+  const raw = await fs.readFile(readmePath, 'utf8');
+  assert.match(raw, /\bbeadboard start\b/i);
+  assert.match(raw, /\bbeadboard open\b/i);
+  assert.match(raw, /\bbeadboard status\b/i);
+});

tests/scripts/installer-ci-contract.test.ts

@@ -0,0 +1,18 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const workflowPath = path.resolve('.github/workflows/installer-smoke.yml');
+
+test('installer smoke CI workflow exists', async () => {
+  const raw = await fs.readFile(workflowPath, 'utf8');
+  assert.match(raw, /name:\s*Installer Smoke/i);
+});
+
+test('installer smoke CI includes ubuntu and windows jobs', async () => {
+  const raw = await fs.readFile(workflowPath, 'utf8');
+  assert.match(raw, /ubuntu-latest/i);
+  assert.match(raw, /windows-latest/i);
+  assert.match(raw, /beadboard doctor --json/i);
+});