docs: reliability core subsystem guide (v1.4.0)

README.md

@@ -111,6 +111,44 @@ terminal I/O, and reboot persistence.
 
 ## Stability notes (Pager 24.10.1)
 
+### Reliability Core (v1.4.0)
+
+The factory `/etc/config/pineapd` ships every crash source below enabled, so
+guards that only live inside Mark VIII revert on every reset/upgrade. v1.4.0
+makes the fixes structural (payload-only — no firmware changes):
+
+- **Boot guard** (`mk8-guard`, START=49): enforces the known-good UCI set
+  before the S50 pineapple stack starts; idempotent, diff-only commits,
+  logged to `/tmp/mk8-guard.log` and the event journal.
+- **Profiles + rollback watchdogs**: every risky operation (AP deploy,
+  client-mode change, profile restore) first snapshots UCI under
+  `/mmc/mk8/profiles/`, then spawns a detached watchdog probing *local*
+  liveness (`127.0.0.1:8080` + monitor presence). Sustained failure →
+  automatic snapshot restore + `wifi reload`; recovery → promotes
+  `lastknown-good`. Watchdogs self-exit after 120 quiet ticks.
+- **RF plan**: phy0 is always 2.4GHz ops; phy1 role-switches
+  uplink/attack/idle (`POST /api/rfplan/role`). The uplink STA lives on
+  radio1, so client-mode no longer blinds 2.4GHz recon. Hop governance
+  belongs to the role manager, not the boot guard.
+- **Supervisor**: passive sampler (pidof/iw//proc only — never pineapd's
+  socket), bounded JSONL journal at `/mmc/mk8/events.log`, boot-marker
+  unexpected-reboot detection, memory watermark alerts. Dashboard shows
+  events feed + reliability counters + guard sync chip.
+- **Atomic deploys**: `scripts/deploy.sh` stamps `VERSION` into build
+  copies only, sha256-verifies the upload, swaps `/mmc/mk8/releases/<ts>`
+  with a `current` symlink, polls local health, and auto-rolls back to the
+  previous release on failure.
+- **Smoke suite**: `scripts/smoke.sh` on-device (read-only checks always;
+  `--write` adds reconcile/watchdog drills; `SMOKE_UPLINK_SSID=...` enables
+  the RF-role drill). All checks verified against live hardware including
+  reboot persistence.
+
+Persistent state lives in `/mmc/mk8/` and survives reboots *and* firmware
+upgrades (overlay wipes). A pre-reliability config backup is captured at
+first deploy.
+
+### pineapd crash sources found and fixed on this firmware
+
 pineapd crash sources found and fixed on this firmware (verified on-device,
 zero crashes over sustained watches):