Update Docs

handbook/03-protocol-and-disk.md

@@ -57,7 +57,20 @@ sequenceDiagram
   B->>S: hyperdrive replicate
 ```
 
-![Hyperswarm and Protomux handshake](../docs/images/hyperswarm-protomux.png)
+**Stack view (discovery → channel → replication):**
+
+```mermaid
+flowchart TB
+  hs[Hyperswarm join topic and discoveryKey]
+  enc[Encrypted peer stream]
+  pm[Protomux multiplexer]
+  chOS["Channel bare-os-v1"]
+  chApp["Optional bare-os-app-v1"]
+  repl[Hyperdrive replicate on mux]
+  hs --> enc --> pm
+  pm --> chOS --> repl
+  pm -.-> chApp
+```
 
 > **Note**  
 > Offsets, magic bytes, and message IDs are specified in [package-bare-os-protocol](../docs/reference/package-bare-os-protocol.md); this sequence is the behavioral summary.

handbook/09-posix-utilities-shell-and-vfs.md

@@ -119,8 +119,6 @@ flowchart LR
   lists --> pipes --> param --> globs --> subst --> stage --> cap
 ```
 
-![Shell evaluation pipeline](../docs/images/shell-pipeline.png)
-
 **Top-level syntax:** the line is split on **`;`** into separate lists (semicolons **inside** compound blocks do not end the outer statement). **`if`** **`then`** **[** **`else`** **]** **`fi`** uses the same **`&&`** / **`||`** / pipeline rules inside the condition and each branch; the condition is true when the last evaluated command in that **`&&`/`||`** list exits **0**. **`while`** **`list;`** **`do`** **`list;`** **`done`** and **`for`** **`name`** **`in`** **words** **`;`** **`do`** **`list;`** **`done`** repeat the body while respecting **`BARE_OS_SHELL_LOOP_MAX`**. **`case`** **`word`** **`in`** **`pattern)`** **`list`** **`;;`** … **`esac`** matches the first pattern (token-safe); patterns support **`|`** alternation and fnmatch-style **`*`**, **`?`**, and **`[…]`** (excluding **`|`** branches handled separately). Branch count is capped by **`BARE_OS_SHELL_CASE_MAX_BRANCHES`**. Each list is an **AND-OR** chain: **pipelines** separated by **`&&`** or **`||`**, evaluated left-to-right with POSIX-style short-circuiting (**`ctx.exitCode`** — treat missing as **0**). Within a pipeline, **`|`** connects stages as before (simulated stdin between utilities).
 
 **Background / jobs (subset vs SUSv4):** a trailing **`&`** on a top-level list runs that list asynchronously (microtask). **`jobs`** lists recent jobs (including **Stopped** when **`suspend-job`** was used); **`fg`** awaits the selected (or latest) job; **`wait`** awaits one job by id (or **`%id`**) or all background jobs; with **`BARE_OS_SHELL_POSIX_MODE=1`**, **`wait -n`** waits for **any** pending job (**`Promise.race`**) and exits **0** when none remain. **`bg`** clears **Stopped** and re-queues the job (logical resume within the single-session runtime). **`trap -l`** / **`trap -p`** / **`trap CMD SIG`** use **`ctx.shellTrapHandlers`** (delivery still maps through **`ctx.bareOsSendSignal`** for synthetic PIDs). This is **not** IEEE Std 1003.1 job control: there is no **`set -m`** monitor mode, no real process groups or **`SIGTSTP`** from the host kernel, and background jobs use **`jobControlModel: 'logical_no_fork'`** (see **`/proc/bare_os/process_table.json`** **`jobControlSemantics`**). Unsupported operations fail with explicit stderr messages (**`fg: no such job`**, **`wait: no such job`**, **`bg: no stopped jobs`**, …) rather than silent no-ops.