feat(kernel): wave 2 guest OS surface and operator parity

- Extend capability model (featureBits2) and align ADR, protocol, /proc, verify scripts
- Add seed RPC + /proc mirrors for replication queue, MBR failover hints, optional attestation
- Pear bridge: IPC request/response, mirror-drive / HDMS pairing hints, dev diagnostics
- Initd: IdleSec for socket units, units.d drop-ins, richer readiness (e.g. exec:)
- Cron: @reboot and JitterSec-style scheduling
- VFS: Linux-shaped /proc stubs (cgroups, tcp), bounded vfs.watch on safe pseudo paths
- Shell: gated parameter expansion v2; /bin/env -S and --env-file (staged script without ESM export)
- Schemas under docs/schemas; expand contract tests; kernel.ext.d → /proc extensions registry
- Refresh handbook, developer-guide, reference index, package READMEs; keep seeder kernel tree in sync

docs/reference/README.md

@@ -17,5 +17,6 @@ This directory holds the split **file-by-file inventory** that used to live in t
 | *(roadmap)* | [Feature roadmap status](feature-roadmap.md) |
 | §§15–16 | [Out of scope and tooling](out-of-scope-and-tooling.md) |
 | *(HTTP clients)* | [curl and wget (delegation, fetch stack, policy)](http-curl-and-wget.md) |
+| *(JSON Schemas)* | [Published schemas: boot policy, telemetry, boot trace](../schemas/) |
 
 **Narrative docs:** [Handbook](../../handbook/README.md) (why / architecture), [Developer guide](../../developer-guide/README.md) (how to extend `run` / `start`, `ctx`).

docs/reference/environment-and-posix-appendix.md

@@ -18,7 +18,7 @@ Former **DOCUMENTATION.md** §14, §14a. [Reference index →](README.md)
 | `MANWIDTH`                | `/bin/man`               | Wrap width for manual text (default `72`; minimum `40`)                                                                                                                                                                  |
 | `NO_COLOR`                | `/bin/man`               | If set, disable ANSI bold for section headings on a TTY                                                                                                                                                                  |
 
-**Host → session passthrough** (booter copies into **`shellEnv`** when the host sets a non-empty value): `BARE_OS_PIPELINE_MAX_STAGES`, `BARE_OS_PIPELINE_MAX_BYTES`, `BARE_OS_PIPELINE_MAX_LINES`, `BARE_OS_SHELL_STREAMING`, `BARE_OS_SHELL_STREAMING_MULT`, `BARE_OS_SHELL_CMDSUBST`, `BARE_OS_SHELL_CMDSUBST_MAX_BYTES`, `BARE_OS_SHELL_PARAM_EXPANSION`, `BARE_OS_BOOT_PROFILE`, `BARE_OS_ONBOOT`, `BARE_OS_BOOT_STRICT`, `BARE_OS_RC_D_SKIP`, `BARE_OS_BOOT_MINIMAL`, `BARE_OS_BOOT_SKIP`, `BARE_OS_BOOT_TRACE`, `BARE_OS_KERNEL_SELFTEST`, `BARE_OS_SELFTEST_FORMAT`, `BARE_OS_AUDIT`, `BARE_OS_AUDIT_JSON`, `BARE_OS_AUDIT_REDACT`, `BARE_OS_IMAGE_DIGEST`, `BARE_OS_EXEC_MAX_DEPTH`, `BARE_OS_EXEC_LINE_BUDGET_MS`, `BARE_OS_IPC_MAX_BYTES`, `BARE_OS_IPC_CHANNEL_MAX_BYTES`, `BARE_OS_IPC_RPC_TOKEN`, `BARE_OS_IPC_FANOUT`, `BARE_OS_IPC_JSON_MAX_BYTES`, `BARE_OS_IPC_NAMESPACE`, `BARE_OS_VFS_WATCH`, `BARE_OS_VFS_UNION_PREFIXES`, `BARE_OS_VFS_UNION_WRITE_DENY`, `BARE_OS_VFS_BIN_CACHE`, `BARE_OS_BOOT_ALLOWLIST`, `BARE_OS_BOOT_MANIFEST`, `BARE_OS_BOOT_MANIFEST_SIGN`, `BARE_OS_BOOT_MANIFEST_PUBKEY_HEX`, `BARE_OS_BOOT_POLICY`, `BARE_OS_BOOT_POLICY_STRICT`, `BARE_OS_LAZY_PERSONAL_DRIVE`, `BARE_OS_SYSTEM_REVISION_ID`, `BARE_OS_SYSTEM_REVISION_PENDING`, `BARE_OS_SYSTEM_SLOT`, `BARE_OS_DELEGATE_ALLOW`, `BARE_OS_DELEGATE_MAX_PER_MIN`, `BARE_OS_DELEGATE_GIT_MAX_PER_MIN`, `BARE_OS_DELEGATE_CURL_MAX_PER_MIN`, `BARE_OS_DELEGATE_WGET_MAX_PER_MIN`, `BARE_OS_DELEGATE_SYSTEMCTL_MAX_PER_MIN`, `BARE_OS_DELEGATE_AUDIT_ONLY`, `BARE_OS_DNS_ALLOWLIST`, `BARE_OS_KERNEL_HOT_RELOAD`, `BARE_OS_SANDBOX_SCRIPT`, `BARE_OS_SANDBOX_WORKER`, `BARE_OS_INITD_MAX_PARALLEL`, `BARE_OS_INITD_JOURNAL_MAX_LINES`, `BARE_OS_URANDOM_CRYPTO`, `BARE_OS_TELEMETRY_NDJSON`, `BARE_OS_TELEMETRY_OTEL_JSONL`, `BARE_OS_PROC_POLL_MS`, `BARE_OS_SEED_RPC_HANDSHAKE`, `BARE_OS_SEED_CAP_STRICT`, `BARE_OS_SEED_CAP_FAIL`, `BARE_OS_HTTP_ALLOWLIST`, `BARE_OS_HTTP_DENYLIST`, `BARE_OS_TLS_PIN_SHA256`, `BARE_OS_BARE_MODULES`, `BARE_OS_BARE_DRIVE_BUNDLES`, `BARE_OS_PEAR_CHANNEL`, `BARE_OS_PEAR_RELEASE`, `PEAR_CHANNEL`, `BARE_OS_FIND_EXEC_MAX`, `BARE_OS_YES_MAX_LINES`, `BARE_OS_SHUF_MAX_LINES`, `BARE_OS_SPLIT_MAX_FILES`, `BARE_OS_NPROC`, `BARE_OS_BLIND_BOOTSTRAP_URL`, `BARE_OS_BLIND_BOOTSTRAP_JSON`, `BARE_OS_MIRROR_READ_KEY`, **`TERM`**, **`COLORTERM`**.
+**Host → session passthrough** (booter copies into **`shellEnv`** when the host sets a non-empty value): `BARE_OS_PIPELINE_MAX_STAGES`, `BARE_OS_PIPELINE_MAX_BYTES`, `BARE_OS_PIPELINE_MAX_LINES`, `BARE_OS_SHELL_STREAMING`, `BARE_OS_SHELL_STREAMING_MULT`, `BARE_OS_SHELL_CMDSUBST`, `BARE_OS_SHELL_CMDSUBST_MAX_BYTES`, `BARE_OS_SHELL_PARAM_EXPANSION`, `BARE_OS_SHELL_PARAM_EXPANSION_V2`, `BARE_OS_ENV_DASH_S`, `BARE_OS_VFS_WATCH_PSEUDO`, `BARE_OS_DIAGNOSTICS_SUBSCRIBE`, `BARE_OS_AUTOPASS_INVITE_URL`, `BARE_OS_BIN_WORKER_OFFLOAD`, `BARE_OS_BIN_WORKER_ALLOW`, `BARE_OS_BOOT_PROFILE`, `BARE_OS_ONBOOT`, `BARE_OS_BOOT_STRICT`, `BARE_OS_RC_D_SKIP`, `BARE_OS_BOOT_MINIMAL`, `BARE_OS_BOOT_SKIP`, `BARE_OS_BOOT_TRACE`, `BARE_OS_KERNEL_SELFTEST`, `BARE_OS_SELFTEST_FORMAT`, `BARE_OS_AUDIT`, `BARE_OS_AUDIT_JSON`, `BARE_OS_AUDIT_REDACT`, `BARE_OS_IMAGE_DIGEST`, `BARE_OS_EXEC_MAX_DEPTH`, `BARE_OS_EXEC_LINE_BUDGET_MS`, `BARE_OS_IPC_MAX_BYTES`, `BARE_OS_IPC_CHANNEL_MAX_BYTES`, `BARE_OS_IPC_RPC_TOKEN`, `BARE_OS_IPC_FANOUT`, `BARE_OS_IPC_JSON_MAX_BYTES`, `BARE_OS_IPC_NAMESPACE`, `BARE_OS_VFS_WATCH`, `BARE_OS_VFS_UNION_PREFIXES`, `BARE_OS_VFS_UNION_WRITE_DENY`, `BARE_OS_VFS_BIN_CACHE`, `BARE_OS_BOOT_ALLOWLIST`, `BARE_OS_BOOT_MANIFEST`, `BARE_OS_BOOT_MANIFEST_SIGN`, `BARE_OS_BOOT_MANIFEST_PUBKEY_HEX`, `BARE_OS_BOOT_POLICY`, `BARE_OS_BOOT_POLICY_STRICT`, `BARE_OS_LAZY_PERSONAL_DRIVE`, `BARE_OS_SYSTEM_REVISION_ID`, `BARE_OS_SYSTEM_REVISION_PENDING`, `BARE_OS_SYSTEM_SLOT`, `BARE_OS_DELEGATE_ALLOW`, `BARE_OS_DELEGATE_MAX_PER_MIN`, `BARE_OS_DELEGATE_GIT_MAX_PER_MIN`, `BARE_OS_DELEGATE_CURL_MAX_PER_MIN`, `BARE_OS_DELEGATE_WGET_MAX_PER_MIN`, `BARE_OS_DELEGATE_SYSTEMCTL_MAX_PER_MIN`, `BARE_OS_DELEGATE_AUDIT_ONLY`, `BARE_OS_DNS_ALLOWLIST`, `BARE_OS_KERNEL_HOT_RELOAD`, `BARE_OS_SANDBOX_SCRIPT`, `BARE_OS_SANDBOX_WORKER`, `BARE_OS_INITD_MAX_PARALLEL`, `BARE_OS_INITD_JOURNAL_MAX_LINES`, `BARE_OS_URANDOM_CRYPTO`, `BARE_OS_TELEMETRY_NDJSON`, `BARE_OS_TELEMETRY_OTEL_JSONL`, `BARE_OS_PROC_POLL_MS`, `BARE_OS_SEED_RPC_HANDSHAKE`, `BARE_OS_SEED_CAP_STRICT`, `BARE_OS_SEED_CAP_FAIL`, `BARE_OS_HTTP_ALLOWLIST`, `BARE_OS_HTTP_DENYLIST`, `BARE_OS_TLS_PIN_SHA256`, `BARE_OS_BARE_MODULES`, `BARE_OS_BARE_DRIVE_BUNDLES`, `BARE_OS_PEAR_CHANNEL`, `BARE_OS_PEAR_RELEASE`, `PEAR_CHANNEL`, `BARE_OS_FIND_EXEC_MAX`, `BARE_OS_YES_MAX_LINES`, `BARE_OS_SHUF_MAX_LINES`, `BARE_OS_SPLIT_MAX_FILES`, `BARE_OS_NPROC`, `BARE_OS_BLIND_BOOTSTRAP_URL`, `BARE_OS_BLIND_BOOTSTRAP_JSON`, `BARE_OS_MIRROR_READ_KEY`, **`TERM`**, **`COLORTERM`**.
 
 | Variable | Used by | Meaning |
 | -------- | ------- | ------- |
@@ -45,12 +45,18 @@ Former **DOCUMENTATION.md** §14, §14a. [Reference index →](README.md)
 | `BARE_OS_TELEMETRY_OTEL_JSONL` | Booter / var-log | Guest VFS path for OTLP-inspired JSON lines (var-log mirrors). |
 | `BARE_OS_PROC_POLL_MS` | VFS | Coalescing interval for **`/proc/bare_os/metrics_live.json`** (250–60000). |
 | `BARE_OS_SHELL_PARAM_EXPANSION` | Shell | When **`1`**, enable **`${VAR:-word}`** and **`${VAR#prefix}`** in **`expandWord`**. |
+| `BARE_OS_SHELL_PARAM_EXPANSION_V2` | Shell | With param expansion on, enable **`${VAR:=word}`**, **`${VAR##*/}`** / **`${VAR#*/}`**, **`${VAR%%suffix}`** / **`${VAR%suffix}`** (bounded patterns). |
+| `BARE_OS_ENV_DASH_S` | `/bin/env` | When **`1`**, enable **`-S` / `--split-string`** and **`--env-file`** (bounded). |
+| `BARE_OS_VFS_WATCH_PSEUDO` | VFS | When **`1`**, allow **`vfs.watch`** on coalesced **`/proc/bare_os/metrics_live.json`**. |
+| `BARE_OS_DIAGNOSTICS_SUBSCRIBE` | Booter | When **`1`**, **`ctx.bareOsDiagnosticsSubscribe`** receives structured booter events. |
+| `BARE_OS_AUTOPASS_INVITE_URL` | `/proc/bare_os/hdms_hints.json` | Optional operator invite URL hint (guest does not fetch it). |
+| `BARE_OS_BIN_WORKER_OFFLOAD` | Reserved | With **`BARE_OS_BIN_WORKER_ALLOW`** (comma list), gates future bare-thread **`/bin`** offload; stock booter still runs in-process. |
 | `BARE_OS_EXEC_LINE_BUDGET_MS` | Booter | Reject top-level **`execLine`** when cumulative wall time exceeds budget. |
 | `BARE_OS_DELEGATE_MAX_PER_MIN` | Host delegates | Global per-minute cap (sliding window) on delegate invocations. |
 | `BARE_OS_DELEGATE_*_MAX_PER_MIN` | Host delegates | Per-kind override (**`GIT`**, **`CURL`**, **`WGET`**, **`SYSTEMCTL`**). |
 | `BARE_OS_DELEGATE_AUDIT_ONLY` | Host delegates | With **`BARE_OS_AUDIT`**, log delegate calls and skip execution (**exit 0**). |
 | `BARE_OS_SEED_RPC_HANDSHAKE` | Booter | Set **`0`** / **`false`** to skip the pre-MBR **`bare_os.capabilities`** RPC against the first peer. |
-| `BARE_OS_SEED_CAP_STRICT` | Booter | When **`1`** / **`true`**, require seeder feature **`bits`** to cover **`BARE_OS_KERNEL_FEATURES_STOCK_V1`** or throw. |
+| `BARE_OS_SEED_CAP_STRICT` | Booter | When **`1`** / **`true`**, require seeder feature **`bits`** / **`bits2`** to cover stock booter **`BARE_OS_KERNEL_FEATURES_STOCK_V1`** / **`STOCK_V2`** or throw. |
 | `BARE_OS_SEED_CAP_FAIL` | Booter | When **`1`** / **`true`**, rethrow after a failed handshake instead of recording the error and continuing. |
 | `BARE_OS_URANDOM_CRYPTO` | VFS **`/dev/urandom`** | Set **`0`** to use non-crypto PRNG for synthetic urandom (default prefers crypto where available). |
 | `BARE_OS_BLIND_BOOTSTRAP_URL` | `/proc/bare_os_bootstrap` | Non-empty URL string echoed into the proc JSON for host/operator wiring (guest does not fetch it). |

docs/reference/kernel-capabilities-index.md

@@ -1,6 +1,6 @@
 # Kernel capabilities index (bits, env, `/proc`, `ctx`)
 
-Single map from optional **feature bits** ([`packages/bare-os-protocol/lib/kernel-feature-bits.js`](../../packages/bare-os-protocol/lib/kernel-feature-bits.js)) to operator env vars, guest **`/proc`** paths, and **`ctx`** fields. Stock booter advertises `BARE_OS_KERNEL_FEATURES_STOCK_V1`. Governance: [`developer-guide/adr/001-kernel-feature-bits-governance.md`](../../developer-guide/adr/001-kernel-feature-bits-governance.md).
+Single map from optional **feature bits** ([`packages/bare-os-protocol/lib/kernel-feature-bits.js`](../../packages/bare-os-protocol/lib/kernel-feature-bits.js)) to operator env vars, guest **`/proc`** paths, and **`ctx`** fields. Stock booter advertises **`BARE_OS_KERNEL_FEATURES_STOCK_V1`** (word 1) and **`BARE_OS_KERNEL_FEATURES_STOCK_V2`** (word 2, `bits2` on the wire). Governance: [`developer-guide/adr/001-kernel-feature-bits-governance.md`](../../developer-guide/adr/001-kernel-feature-bits-governance.md).
 
 | Bit (export) | Env / behavior | `/proc` or RPC | `ctx` / notes |
 |--------------|----------------|----------------|---------------|
@@ -36,6 +36,30 @@ Single map from optional **feature bits** ([`packages/bare-os-protocol/lib/kerne
 | 29 `LIFECYCLE_TELEMETRY_V3` | telemetry NDJSON | — | `lifecycleSchemaVersion: 3` |
 | 30 `BOOT_POLICY_V2` | extended `boot.policy.json` | — | `maxExecLineDepth`, `denyEnvKeys`, `requireProcNodes` |
 
+### Word 2 (`bits2`, wave 2)
+
+| Bit (export) | Env / behavior | `/proc` or RPC | `ctx` / notes |
+|--------------|----------------|----------------|---------------|
+| 0 `FEATURE2_SEED_REPLICATION_QUEUE_RPC` | — | seed RPC `replication_queue`; replication JSON | queue / backpressure hints |
+| 1 `FEATURE2_SEED_CAPABILITY_ATTESTATION_RPC` | `BARE_OS_SEED_CAPABILITY_ATTESTATION_JSON` (seeder) | RPC `capability_attestation` | optional distro attestation JSON |
+| 2 `FEATURE2_SEED_MBR_LAYOUT_RPC` | — | RPC `mbr_layout`; replication JSON `mbrKeysHex` | MBR failover key hints |
+| 3 `FEATURE2_PEAR_IPC_REQUEST` | — | — | `bareOsPearIpcRequest` |
+| 4 `FEATURE2_MIRROR_DRIVE_CTX` | — | — | `bareOsEmitMirrorDriveHint` |
+| 5 `FEATURE2_AUTOPASS_HDMS_HINTS` | `BARE_OS_AUTOPASS_INVITE_URL` | `/proc/bare_os/hdms_hints.json` | operational pairing hint only |
+| 6 `FEATURE2_BIN_WORKER_OFFLOAD` | `BARE_OS_BIN_WORKER_OFFLOAD`, `BARE_OS_BIN_WORKER_ALLOW` | — | reserved / gated heavy `/bin` (stock remains in-process) |
+| 7 `FEATURE2_DIAGNOSTICS_CHANNEL` | `BARE_OS_DIAGNOSTICS_SUBSCRIBE=1` | — | `bareOsDiagnosticsSubscribe` / `Emit` |
+| 8 `FEATURE2_INITD_IDLE_STOP` | initd `IdleSec=` | — | socket-activated idle stop |
+| 9 `FEATURE2_INITD_UNITS_D` | — | — | `~/.config/bare-os/units.d/<unit>/*.conf` |
+| 10 `FEATURE2_CRON_REBOOT_JITTER` | — | — | `@reboot`, `JitterSec=`, timer `JitterSec=` |
+| 11 `FEATURE2_INITD_BOOT_READY_UNITS` | — | `/run/bare-os/boot.json` | `subsystems.initdActiveUnits` |
+| 12 `FEATURE2_PROC_CGROUPS_TCP` | — | `/proc/self/cgroups`, `/proc/net/tcp` | Linux-shaped stubs |
+| 13 `FEATURE2_VFS_WATCH_PSEUDO` | `BARE_OS_VFS_WATCH_PSEUDO=1` | metrics pseudo | bounded `vfs.watch` on metrics |
+| 14 `FEATURE2_SHELL_PARAM_EXPAND_V2` | `BARE_OS_SHELL_PARAM_EXPANSION_V2=1` (+ param expansion on) | — | `##`, `%%`, `:=`, `*/` basename |
+| 15 `FEATURE2_ENV_DASH_S` | `BARE_OS_ENV_DASH_S=1` | — | `/bin/env` `-S`, `--env-file` |
+| 16 `FEATURE2_JSON_SCHEMAS_REPO` | — | [`docs/schemas/`](../../docs/schemas/) | published JSON Schemas |
+| 17 `FEATURE2_CONTRACT_TESTS_WAVE2` | — | — | expanded contract tests |
+| 18 `FEATURE2_KERNEL_EXT_PROC` | — | `/proc/bare_os/extensions.json` | `bareOsRegisterKernelExtensionRecord` |
+
 **Related `ctx` (1.11.0+):** `bareOsReadProcMetricsLive()` — parsed coalesced metrics (same as `/proc/bare_os/metrics_live.json`); Pear IPC channel names in [`bare-os-pear-ipc-registry.js`](../../packages/bare-os-booter/lib/bare-os-pear-ipc-registry.js).
 
 **Handbook:** [handbook/09-posix-utilities-shell-and-vfs.md](../../handbook/09-posix-utilities-shell-and-vfs.md), [handbook/04-the-booter-runtime.md](../../handbook/04-the-booter-runtime.md).

docs/reference/kernel-extensions.md

@@ -2,17 +2,19 @@
 
 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.
 
-## Governance (feature bits doc v3)
+## Governance (feature bits doc v4)
 
-New capability bits are governed by [ADR 001 — Kernel feature bit governance](../../developer-guide/adr/001-kernel-feature-bits-governance.md). **`BARE_OS_KERNEL_FEATURE_BITS_DOC`** must bump when semantics change. Bits **28–30** are assigned (see ADR); avoid `1 << 31` in JS without `>>> 0` discipline.
+New capability bits are governed by [ADR 001 — Kernel feature bit governance](../../developer-guide/adr/001-kernel-feature-bits-governance.md). **`BARE_OS_KERNEL_FEATURE_BITS_DOC`** must bump when semantics change. Bits **28–30** on word 1 are assigned (see ADR). **Word 2 (`bits2`)** carries wave-2 features; always mask with **`>>> 0`**. Avoid `1 << 31` on word 1 in JS without `>>> 0` discipline.
 
 **Capability index:** [kernel-capabilities-index.md](./kernel-capabilities-index.md) (bits → env → `/proc` → `ctx`).
 
 ## Capability bitmask
 
-Runtime bits are defined in `bare-os-protocol` (`kernel-feature-bits.js`) and surfaced under `/proc/bare_os_features` and the **`/proc/bare_os/`** tree. The stock booter advertises `BARE_OS_KERNEL_FEATURES_STOCK_V1`.
+Runtime bits are defined in `bare-os-protocol` (`kernel-feature-bits.js`) and surfaced under `/proc/bare_os_features` and the **`/proc/bare_os/`** tree. The stock booter advertises **`BARE_OS_KERNEL_FEATURES_STOCK_V1`** and **`bits2`** from **`BARE_OS_KERNEL_FEATURES_STOCK_V2`**.
 
-Seed RPC **`bare_os.capabilities`** includes **`protocolPackageVersion`**, **`featureBitsDoc`**, **`doc`**, **`bits`**, **`role`**, **`protocol`**. **`bare_os.replication_status`** returns seeder-side replication hints (manifest path count, local RAM block count). **`bare_os.manifest_hints`** returns a sample of manifest paths; **`bare_os.peer_health`** returns seeder health counters; **`bare_os.staging_slot`** returns optional A/B slot hints (seeder env `BARE_OS_SEED_STAGING_SLOT`, `BARE_OS_SEED_STAGING_PENDING`). Booter mirrors hints under **`/proc/bare_os/manifest_hints`**, **`peer_health`**, **`staging_slot`** and embeds them in **`/proc/bare_os_replication`** JSON.
+Seed RPC **`bare_os.capabilities`** includes **`protocolPackageVersion`**, **`featureBitsDoc`**, **`doc`**, **`bits`**, **`bits2`**, **`role`**, **`protocol`**. **`bare_os.replication_status`** returns seeder-side replication hints (manifest path count, local RAM block count). **`bare_os.replication_queue`**, **`bare_os.capability_attestation`**, and **`bare_os.mbr_layout`** are optional wave-2 RPCs. **`bare_os.manifest_hints`** returns a sample of manifest paths; **`bare_os.peer_health`** returns seeder health counters; **`bare_os.staging_slot`** returns optional A/B slot hints (seeder env `BARE_OS_SEED_STAGING_SLOT`, `BARE_OS_SEED_STAGING_PENDING`). Booter mirrors hints under **`/proc/bare_os/manifest_hints`**, **`peer_health`**, **`staging_slot`**, **`extensions.json`**, **`hdms_hints.json`** and embeds them in **`/proc/bare_os_replication`** JSON.
+
+**JSON Schemas** (policy, telemetry, boot trace): [`docs/schemas/`](../schemas/) (see also [reference README](./README.md)).
 
 ## Environment quick reference
 
@@ -30,6 +32,12 @@ Seed RPC **`bare_os.capabilities`** includes **`protocolPackageVersion`**, **`fe
 | Telemetry OTel | `BARE_OS_TELEMETRY_OTEL_JSONL` | Logical path; append OTLP-inspired JSON lines for var-log mirrors |
 | Proc poll | `BARE_OS_PROC_POLL_MS` | Min interval 250ms, max 60s, for coalesced **`/proc/bare_os/metrics_live.json`** |
 | Shell `${…}` | `BARE_OS_SHELL_PARAM_EXPANSION=1` | Enable `${VAR:-default}` and `${VAR#prefix}` (bounded prefix length) |
+| Shell `${…}` v2 | `BARE_OS_SHELL_PARAM_EXPANSION_V2=1` | With param expansion on: `${VAR:=x}`, `${VAR##*/}` / `${VAR#*/}`, `${VAR%%pat}` / `${VAR%pat}` (bounded; see handbook ch.9) |
+| Env GNU-like | `BARE_OS_ENV_DASH_S=1` | `/bin/env` supports `-S` / `--split-string` and `--env-file` (bounded) |
+| VFS pseudo watch | `BARE_OS_VFS_WATCH_PSEUDO=1` | `vfs.watch` on coalesced **`/proc/bare_os/metrics_live.json`** |
+| Diagnostics | `BARE_OS_DIAGNOSTICS_SUBSCRIBE=1` | `ctx.bareOsDiagnosticsSubscribe` for structured dev events |
+| HDMS / autopass hint | `BARE_OS_AUTOPASS_INVITE_URL` | Surfaced in **`/proc/bare_os/hdms_hints.json`** (guest does not open URLs) |
+| Bin worker (reserved) | `BARE_OS_BIN_WORKER_OFFLOAD=1`, `BARE_OS_BIN_WORKER_ALLOW` | Gate for future bare-thread offload; stock path remains in-process |
 | Exec budget | `BARE_OS_EXEC_LINE_BUDGET_MS` | Reject top-level `execLine` when session wall time exceeds budget |
 | Delegates | `BARE_OS_DELEGATE_MAX_PER_MIN`, `BARE_OS_DELEGATE_CURL_MAX_PER_MIN`, … | Per-minute caps on host delegates (sliding minute window) |
 | Delegates | `BARE_OS_DELEGATE_AUDIT_ONLY=1` | With `BARE_OS_AUDIT=1`, log delegate invocations and skip host run (exit 0) |
@@ -56,7 +64,7 @@ Seed RPC **`bare_os.capabilities`** includes **`protocolPackageVersion`**, **`fe
 1. **Boot phases** — Use `ctx.bareOsRegisterBootPhaseHook` (see stock `kernel/init.js` header).
 2. **Virtual files** — `ctx.bareOsRegisterVirtualFile(name, reader, { etag, mime, ttlMs })`; list via `/proc/bare_os_virtual_registry`.
 3. **IPC** — Named FIFOs under `/run/bare-os/ipc/`; optional `BARE_OS_IPC_NAMESPACE`; JSON-RPC and fan-out documented in the booter package README.
-4. **Initd drop-ins** — `After=` / `Before=` / `Wants=` / `Requires=`; `RestartMaxAttempts=` in `~/.config/bare-os/units/<name>.unit` (1–32). **Timers** — `~/.config/bare-os/timers/*.timer`: `[Timer]` with `OnCalendar=` + `ExecLine=`, or `EveryMs=` (1000–86400000) + `ExecLine=` for fixed-interval jobs (max 8 files).
+4. **Initd drop-ins** — `After=` / `Before=` / `Wants=` / `Requires=`; `RestartMaxAttempts=` in `~/.config/bare-os/units/<name>.unit` (1–32). **Fragments** — `~/.config/bare-os/units.d/<name>/*.conf` merged before `bare-init` overrides. **`IdleSec=`** with **`SocketActivationIpc=`** stops the unit after idle IPC (requires **`stop`**). **`ReadinessPath=`** may be **`exec:<line>`** for an **`execLine`** gate. **Timers** — `~/.config/bare-os/timers/*.timer`: `[Timer]` with `OnCalendar=` + `ExecLine=`, optional **`JitterSec=`**, or `EveryMs=` (1000–86400000) + `ExecLine=` for fixed-interval jobs (max 8 files).
 5. **`/proc/bare_os/`** — Stable aliases (`features`, `replication`, `provenance`, `metrics_live.json`, `initd_dag.json`, `pear_ipc.json`, `manifest_hints`, …) mirroring flat `/proc/bare_os_*` files.
 6. **`ctx.bareOsReadProcMetricsLive()`** — Same JSON as **`/proc/bare_os/metrics_live.json`** without a VFS read.
 7. **Initd** — `bareOsRegisterSuspendHook` / `ResumeHook` stop and restart units with `stop` handlers around Bare mobile suspend (see **`bare-initd`**).

docs/schemas/boot-trace-line.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://bare-os.dev/schemas/boot-trace-line.schema.json",
+  "title": "Bare OS kernel boot trace JSON line (stderr, BARE_OS_BOOT_TRACE=json)",
+  "type": "object",
+  "required": ["phase"],
+  "additionalProperties": true,
+  "properties": {
+    "phase": { "type": "string" },
+    "ok": { "type": "boolean" },
+    "ms": { "type": "number" },
+    "error": { "type": "string" }
+  }
+}

docs/schemas/boot.policy.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://bare-os.dev/schemas/boot.policy.schema.json",
+  "title": "Bare OS boot.policy.json (subset)",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "skipPhases": { "type": "array", "items": { "type": "string" } },
+    "denyBootPhases": { "type": "array", "items": { "type": "string" } },
+    "minKernelFeatureMask": { "type": "integer", "minimum": 0 },
+    "requireSeedCaps": { "type": "integer", "minimum": 0 },
+    "maxExecLineDepth": { "type": "integer", "minimum": 1 },
+    "denyEnvKeys": { "type": "array", "items": { "type": "string" } },
+    "requireProcNodes": { "type": "array", "items": { "type": "string" } },
+    "allowedUnionPrefixes": { "type": "array", "items": { "type": "string" } }
+  }
+}

docs/schemas/telemetry-ndjson-record.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://bare-os.dev/schemas/telemetry-ndjson-record.schema.json",
+  "title": "Bare OS telemetry NDJSON line (v3 lifecycle)",
+  "type": "object",
+  "required": ["type", "ts"],
+  "additionalProperties": true,
+  "properties": {
+    "telemetrySchemaVersion": { "type": "integer" },
+    "lifecycleSchemaVersion": { "type": "integer" },
+    "type": { "type": "string" },
+    "ts": { "type": "integer", "minimum": 0 },
+    "sessionId": { "type": "string" },
+    "phase": { "type": "string" },
+    "ms": { "type": "number" }
+  }
+}