Docs Update

docs/architecture/KERNEL_CONTRACT.md

@@ -18,6 +18,40 @@ This document is the **single overview** of how the Bare OS “kernel” is spli
 
 Canonical identifiers: `BARE_OS_BOOTER_BOOT_STEPS` in [`packages/bare-os-booter/lib/bare-os-boot-phases.js`](../../packages/bare-os-booter/lib/bare-os-boot-phases.js). Emitted in order: **`vfs`** → **`ctx`** → **`repl`** → **`initd`** → **`kernel_invoke`**.
 
+These milestones are recorded for observability (for example under **`booterPhases`** in **`/run/bare-os/boot.json`**) alongside guest/kernel phase traces when enabled.
+
+## End-to-end boot sequence (host → shell)
+
+Conceptual ordering from a cold **host** start through an interactive **guest** prompt. Sub-steps inside each box are described in the handbook and booter source; this diagram is a **contract-level** checklist.
+
+```mermaid
+sequenceDiagram
+  participant Host as Host process
+  participant Seed as bare-os-seeder
+  participant Swarm as Hyperswarm
+  participant Boot as bare-os-booter
+  participant Sys as System Hyperdrive
+  participant Pers as Personal Hyperdrive
+  participant Init as /boot/init.js
+  participant Sh as Shell REPL
+
+  Host->>Seed: start seeder (optional separate process)
+  Seed->>Sys: stage kernel MBR in RAM map
+  Seed->>Swarm: join topic + discovery
+  Host->>Boot: start booter
+  Boot->>Swarm: join topic find peers
+  Boot->>Seed: Protomux bare-os-v1 read block 0
+  Boot->>Sys: open replicate until /boot/init.js
+  Boot->>Pers: create or open personal drive
+  Note over Boot: booterPhases vfs then ctx then repl then initd
+  Boot->>Boot: createVfs buildBareCtxObjectFromHost
+  Boot->>Boot: bare-initd start
+  Boot->>Init: runKernelFromSource start ctx
+  Init->>Sh: rc snippets then readLine loop
+```
+
+![Full boot flow export](../images/boot-flow.png)
+
 ## Context API
 
 - Version: **`BARE_OS_CTX_API_VERSION`** in [`packages/bare-os-booter/lib/bare-os-ctx-api.js`](../../packages/bare-os-booter/lib/bare-os-ctx-api.js).
@@ -29,7 +63,10 @@ Shared error classes (stable `code` field): [`packages/bare-os-booter/lib/bare-o
 
 ## Related docs
 
+- [Architecture: end-to-end data flow](../reference/architecture-data-flow.md)
+- [Documentation home](../README.md)
 - [Handbook — protocol and disk](../../handbook/03-protocol-and-disk.md)
 - [Handbook — booter runtime](../../handbook/04-the-booter-runtime.md)
+- [Developer guide — Kernel boot](../../developer-guide/03-kernel-boot-init.md)
 - [Compatibility matrix](../reference/compatibility-matrix.md)
 - [Placeholder baseline (audit)](../audit/PLACEHOLDER_BASELINE.md)

docs/architecture/kernel-subsystems.md

@@ -23,6 +23,7 @@ This document is the **boundary map** for the Bare operating system runtime: whi
 
 ## Related
 
+- [Documentation home](../README.md) · [Glossary](../glossary.md)
 - [KERNEL_CONTRACT.md](KERNEL_CONTRACT.md) — trust and replication contract.
 - [POSIX conformance matrix](../reference/conformance-matrix.md) — Issue 7 tracking.
 - [Environment and POSIX appendix](../reference/environment-and-posix-appendix.md) — env vars and userland gaps.