Docs Update

users-manual/03-running-seeder-and-booter.md

@@ -24,6 +24,16 @@ The **booter** owns the **consumer** side: it looks up peers on the same topic,
 
 You almost always run them as **two separate processes** (two terminal tabs or windows). The booter needs a live seeder (or an already-replicated drive) to make progress within its boot timeout.
 
+```mermaid
+flowchart LR
+  Seeder[bare-os-seeder]
+  Topic[Swarm topic bare-os-v1]
+  Booter[bare-os-booter]
+  Seeder -->|publish MBR + blocks| Topic
+  Booter -->|discover replicate| Topic
+  Booter --> Init["/boot/init.js"]
+```
+
 ---
 
 ## Run with Node (quick path)
@@ -60,7 +70,8 @@ npm run os:booter
 
 These scripts run **`scripts/ensure-pear-node-modules.mjs`** first so Pear sees **hoisted** workspace dependencies the same way **`npm ci`** does at the repo root. Without that step, **`pear run`** from inside a package directory can miss modules that live at the root **`node_modules`**.
 
-**Do not** type `pear run os:seeder` — **`os:seeder`** is an **npm script name**, not a Pear application name.
+> **Important**  
+> **`os:seeder`** is an **npm script name**, not a Pear app name. Do not type `pear run os:seeder`.
 
 ---
 
@@ -84,6 +95,8 @@ Concrete channel names, keys, versioned links, and host-side environment variabl
 
 Once the booter has replicated enough of the **system** drive, it mounts the **personal** drive (creating one if needed), wires the merged VFS, and executes **`/boot/init.js`**. The stock kernel prints **`/etc/os-release`**, optional **`motd`**, runs **`/etc/bare-os/rc`** and sorted snippets under **`rc.d`**, then enters the interactive shell unless **`BARE_OS_SKIP_REPL`** or **`onboot`** lines consume the session. You do not need to memorize every phase to operate the system; when something fails **during** boot, enable **`BARE_OS_BOOT_TRACE`** (see [environment appendix](../docs/reference/environment-and-posix-appendix.md)) and read the phase lines on stderr.
 
+Canonical **booter boot steps** (**`vfs`** → **`ctx`** → **`repl`** → **`initd`** → **`kernel_invoke`**) are summarized in [KERNEL_CONTRACT](../docs/architecture/KERNEL_CONTRACT.md).
+
 ---
 
 ## Choosing Node versus Pear
@@ -92,4 +105,11 @@ Once the booter has replicated enough of the **system** drive, it mounts the **p
 
 ---
 
+## Related reading
+
+- [docs/troubleshooting.md](../docs/troubleshooting.md)
+- [Handbook — Protocol and disk](../handbook/03-protocol-and-disk.md)
+
+---
+
 _Previous: [Chapter 2](02-install-and-repository-layout.md)_ · _Next: [Chapter 4 — Shell, PATH, and scripts](04-shell-path-and-scripts.md)_