feat(boot,vfs,security): expand kernel boot contract, VFS snapshots, and ctx surfaces

- Kernel: strict capability contract merge, junit selftest, startup class, cold boot
  budget warning, boot txn schema v1, rc/kernel.ext resolution traces, richer
  bareOsPublishBootReady (steps/bootSteps, FSM sketch)
- Booter: warm reboot extra cycles, boot provenance on boot.json, step mirroring,
  corestore/swarm suspend-resume hooks, swarm connection manager sketch, event bus
  + optional NDJSON, security_posture proc schema v2, key handle TTL/scopes
- VFS: snapshot path class + BARE_OS_VFS_SNAPSHOTS checkout views, policy metrics,
  batch put + diff helpers, watch consistency hint, quotas vfsQuota fields
- Protocol: BARE_OS_PROTOMUX_CORK_HINT_VERSION via channel exports
- Initd: BARE_INITD_UNIT_STATES; shell: tokenizer module split
- Extensions: capability conflict detector in kernel-extension-resolver
- Docs/scripts: reference index map, observability event bus, dry-run vs rollback
  table, benchmark trend + integration-lab smoke, scripts README
- Tests: /proc listing + pseudo path caps for snapshots and security_posture

docs/reference/README.md

@@ -2,6 +2,18 @@
 
 This directory holds the split **file-by-file inventory** that used to live in the root [`DOCUMENTATION.md`](../../DOCUMENTATION.md) stub. Use it when you need paths, package roles, and environment variables without a narrative walkthrough.
 
+### Documentation map (single index)
+
+| Kind | Where to start |
+| --- | --- |
+| Project overview | [README](../../README.md) |
+| Operator narrative | [Handbook](../../handbook/README.md) |
+| Contributor / `ctx` / Pear | [Developer guide](../../developer-guide/README.md) |
+| Day-to-day use | [Users manual](../../users-manual/README.md) |
+| File-level inventory | This directory (`docs/reference/`) |
+| JSON Schemas | [`docs/schemas/`](../schemas/) |
+| CI / verifiers | [`scripts/README.md`](../../scripts/README.md) |
+
 ---
 
 ## On this page
@@ -29,6 +41,7 @@ This directory holds the split **file-by-file inventory** that used to live in t
 - **VFS path classes (policy sketch)** — [vfs-path-classes.md](vfs-path-classes.md)
 - **Observability contracts** — [observability-contracts.md](observability-contracts.md)
 - **Kernel extensions (short index)** — [kernel-extensions-capability-specs.md](kernel-extensions-capability-specs.md)
+- **Kernel extensions (generated TOC)** — [kernel-extensions-generated-toc.md](kernel-extensions-generated-toc.md)
 - **OTA channel sketch** — [ota-channels.md](ota-channels.md)
 - **POSIX conformance dashboard (sketch)** — [conformance-dashboard.md](conformance-dashboard.md)
 - **Machine-readable data stubs** — [../data/README.md](../data/README.md)

docs/reference/kernel-capabilities-index.md

@@ -33,7 +33,7 @@ Each row is one **bit index** in the first capability word. Columns list **env o
 | 4 `HOST_STATS`                   | —                                   | host bridge                                      | `bareOsHostStats`                                     |
 | 5 `CRYPTO_URANDOM`               | `BARE_OS_URANDOM_CRYPTO=0` disables | `/dev/urandom`                                   | —                                                     |
 | 6 `SANDBOX_SCRIPT`               | `BARE_OS_SANDBOX_SCRIPT=0`          | —                                                | `bareOsSandboxRunScript`                              |
-| 7 `BOOT_PHASE_HOOKS`             | —                                   | —                                                | `bareOsRegisterBootStepHook` (legacy `bareOsRegisterBootPhaseHook`) |
+| 7 `BOOT_STEP_HOOKS` (wire label `BOOT_PHASE_HOOKS`) | —                                   | —                                                | `bareOsRegisterBootStepHook` (legacy `bareOsRegisterBootPhaseHook`) |
 | 8 `IPC_DUPLEX`                   | —                                   | —                                                | `bareOsIpc.createDuplexBridge`                        |
 | 9 `VFS_UNION`                    | `BARE_OS_VFS_UNION_PREFIXES`        | `/proc/bare_os_union`                            | —                                                     |
 | 10 `PROC_SWARM`                  | —                                   | `/proc/bare_os_swarm`                            | —                                                     |

docs/reference/kernel-extensions-generated-toc.md

@@ -0,0 +1,14 @@
+<!-- Generated by scripts/gen-kernel-extensions-index.mjs — do not edit by hand. -->
+
+# Kernel extensions — generated TOC
+
+- Governance (feature bits doc v14)
+- Capability bitmask
+- Environment quick reference
+- Capability word 6 summary
+- Capability word 9 summary
+- Capability word 10 summary
+- Capability word 11 summary
+- POSIX utility notes
+- Cookbook snippets
+- Profiles

docs/reference/kernel-extensions.md

@@ -1,6 +1,6 @@
 # Kernel extensions and feature matrix (Bare OS)
 
-This document complements the [handbook](../../handbook/09-posix-utilities-shell-and-vfs.md) with a single map of optional **booter + stock kernel** features added for richer POSIX-like behavior, protocol alignment, and operations. For a short capability index with pointers to schemas, see **[kernel-extensions-capability-specs.md](./kernel-extensions-capability-specs.md)**.
+This document complements the [handbook](../../handbook/09-posix-utilities-shell-and-vfs.md) with a single map of optional **booter + stock kernel** features added for richer POSIX-like behavior, protocol alignment, and operations. For a short capability index with pointers to schemas, see **[kernel-extensions-capability-specs.md](./kernel-extensions-capability-specs.md)**. **Generated heading index:** [kernel-extensions-generated-toc.md](./kernel-extensions-generated-toc.md) (from `npm run pretest`).
 
 ## Governance (feature bits doc v14)
 

docs/reference/observability-contracts.md

@@ -6,5 +6,6 @@ Bare OS mirrors structured **boot** and **kernel** events to optional sinks:
 - **Telemetry NDJSON** — `BARE_OS_TELEMETRY_NDJSON` (guest path); schema **`telemetry-ndjson-record.schema.json`** (`telemetrySchemaVersion` / `lifecycleSchemaVersion`).
 - **OTel-style JSONL** — `BARE_OS_TELEMETRY_OTEL_JSONL`; schema **`otel-bare-os-jsonl.schema.json`**.
 - **Audit stream** — host/session policy; see kernel extensions reference for env keys.
+- **Event bus** — `ctx.bareOsEmitEventBus` / `ctx.bareOsSubscribeEventBus`; optional **`BARE_OS_EVENT_BUS_NDJSON=1`** mirrors one JSON line per event on session stdout (`eventBusSchema: 1`).
 
 **Contract tests** in root `pretest`: `validate-example-schemas.mjs`, `verify-kernel-capabilities-contract.mjs`, `verify-compat-matrix.mjs`, **`verify-banned-terminology.mjs`** (governance wording; skips vendored `kernel/lib/bare/`), and **`verify-naming-alias-matrix.mjs`**. When adding fields, bump schema versions and extend the example JSON under `kernel/etc/bare-os/`.

docs/reference/vfs-path-classes.md

@@ -9,5 +9,10 @@ Stock routing is implemented in `packages/bare-os-booter/lib/vfs.js` (`createVfs
 | `mount` | `/mnt`, `/media`, `/mount` | Optional union / HDMS mounts |
 | `personal` | `/home/…`, `/root…` | Personal Hyperdrive view |
 | `system` | `/boot`, `/bin`, `/lib`, `/etc`, `/usr`, `/var`, default | System image Hyperdrive |
+| `snapshot` | `/snapshots`, `/snapshots/system/…` | Read-only **system** checkout views when **`BARE_OS_VFS_SNAPSHOTS=1`** and `drive.checkout` exists |
+
+**Policy helper:** `evaluateBareOsVfsPathPolicy(path, rules)` returns **`verdict`**, **`matched`**, and **`metrics`** (`rulesEvaluated`, `matchCount`).
+
+**Batch / diff helpers:** `bareOsVfsBatchPut(drive, puts)` and `bareOsHyperdriveDiffCollect(drive, a, b, opts)` in the same module (used from **`ctx.bareOsVfsBatchWrite`** / **`ctx.bareOsHyperdriveDiffCollect`** in the booter).
 
 This is **advisory** today: enforcement remains in the VFS implementation and boot policy (`denyVfsPrefixes`, …).