docs: define runtime manager global install contract

docs/adr/2026-03-03-global-installer-contract-and-manifest.md

@@ -0,0 +1,89 @@
+# ADR: Global Installer Contract and Canonical Manifest (`installer.v1`)
+
+- Date: 2026-03-03
+- Status: Accepted
+- Scope: `beadboard-05a.1.1` + `beadboard-05a.1.2`
+
+## Context
+
+The `beadboard-05a` epic requires one installer contract shared by all platform wrappers and launcher behavior.  
+Without a canonical schema, wrappers can drift and the driver skill can emit inconsistent remediation guidance.
+
+Constraints:
+
+- `bd` remains source of truth for work state.
+- Driver skill must remain detect/remediate only, with no install side effects.
+- Windows and POSIX wrappers must map to one shared semantic model.
+
+## Decision
+
+Adopt `installer.v1` as the canonical manifest contract and validate it centrally in code.
+
+Contract requirements:
+
+1. **Versioned schema**
+- `version` must be exactly `installer.v1`.
+
+2. **Distribution contract**
+- `distribution.packageName` declares the global package identity.
+- `distribution.shimNames` declares required command shims (`bb`, `beadboard`).
+
+3. **Wrapper contract**
+- `wrappers.windows.script` and `wrappers.posix.script` are required and explicit.
+
+4. **Runtime command contract**
+- `runtime.start`, `runtime.open`, and `runtime.status` are required.
+
+5. **Driver boundary contract**
+- `driver.remediationMode` must be `detect_only`.
+- `driver.installSideEffects` must be `false`.
+
+## Implementation
+
+Added canonical validator and type contract:
+
+- `src/lib/install-manifest.ts`
+- `tests/lib/install-manifest.test.ts`
+
+Exported artifacts:
+
+- `INSTALLER_SCHEMA_VERSION = "installer.v1"`
+- `validateInstallerManifest(input)`
+- `canonicalInstallerManifest` for shared reference in downstream wrapper and launcher tasks
+
+## Verification Evidence
+
+TDD red:
+
+- `node --import tsx --test tests/lib/install-manifest.test.ts`  
+  failed with `Cannot find module '../../src/lib/install-manifest'`
+
+TDD green:
+
+- `node --import tsx --test tests/lib/install-manifest.test.ts`  
+  passed (`4/4`)
+
+Suite registration:
+
+- `package.json` test script now explicitly includes `tests/lib/install-manifest.test.ts`
+
+## Consequences
+
+Positive:
+
+- Platform wrappers now have one schema target.
+- Launcher semantics are pre-declared before wrapper implementation.
+- Driver detection-only boundary is encoded in validator rules.
+
+Tradeoff:
+
+- Wrapper and CI tasks (`05a.2+`) must now conform to `installer.v1`; they cannot introduce ad hoc fields.
+
+## Runtime Manager Alignment
+
+This ADR is paired with `docs/adr/2026-03-03-runtime-manager-global-install.md`.
+
+- Canonical runtime home is `~/.beadboard/runtime/<version>`.
+- Global install (`npm i -g beadboard`) is the primary operator path.
+- Wrappers remain supported as fallback bootstraps.
+- Legacy repo-bound shim migration is mandatory for backward compatibility.

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

@@ -0,0 +1,49 @@
+# ADR: Runtime Manager for Global Install
+
+- Date: 2026-03-03
+- Status: Accepted
+- Scope: Global installer runtime execution model
+
+## Context
+
+The installer currently supports wrappers and launcher behavior, but runtime location and shim targets must be stable across updates and usable from any working directory.
+
+## Decision
+
+Adopt a runtime-manager layout rooted at `~/.beadboard/runtime/<version>` with stable command shims in `~/.beadboard/bin`.
+
+Primary install flow is npm global:
+
+- `npm i -g beadboard`
+
+Fallback install flow remains script bootstrap wrappers when npm-global is unavailable.
+
+All shims resolve a runtime target from runtime metadata first, then execute launcher logic from the selected runtime root.
+
+## Runtime Layout
+
+- Runtime root: `~/.beadboard/runtime/<version>`
+- Stable metadata: `~/.beadboard/runtime/current.json`
+- Stable shim directory: `~/.beadboard/bin`
+- Required shims: `bb`, `beadboard`
+
+## Update / Uninstall Model
+
+- Update writes a new versioned runtime directory and atomically switches `current.json`.
+- Uninstall removes runtime directories and shims after explicit confirmation.
+- Failed updates do not replace active metadata; previous runtime remains executable.
+
+## Compatibility and Migration
+
+Legacy repo-bound shim migration is required:
+
+- Detect legacy shims that hardcode repository-relative launcher paths.
+- Rewrite shims to runtime-managed targets atomically.
+- Preserve user-facing command names and shell compatibility.
+
+## 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.
+