Docs Update

users-manual/04-shell-path-and-scripts.md

@@ -23,6 +23,17 @@ The shell and utilities are part of the **guest** runtime built by the booter. T
 
 For POSIX coverage and deliberate gaps, see [Handbook — Chapter 9](../handbook/09-posix-utilities-shell-and-vfs.md).
 
+```mermaid
+flowchart LR
+  line[User types line]
+  shell[Shell parse expand]
+  bin["/bin or builtin"]
+  vfs[VFS read/write]
+  line --> shell --> bin --> vfs
+```
+
+![Shell pipeline diagram](../docs/images/shell-pipeline.png)
+
 ---
 
 ## How a command runs (conceptually)
@@ -66,7 +77,7 @@ Pipelines and redirects behave like a small Unix (**`ls | wc -c`**, **`echo hell
 
 ## Builtins, `/bin`, and `/proc`
 
-The shell implements **builtins** ( **`cd`**, **`export`**, control flow, …) in **`packages/bare-os-booter/lib/shell.js`**. Everything else normally resolves to **`/bin/<name>`** via **`PATH`**. Synthetic trees such as **`/proc/bare_os_features`** expose JSON or text summaries of capabilities and runtime state; they are documented in the [kernel extensions reference](../docs/reference/kernel-extensions.md) and handbook chapters on the booter. If a name does not resolve, verify you are not shadowing a shell builtin and that **`PATH`** includes **`/bin`** (try **`command -v <name>`** when the shell supports it, or **`which <name>`** if installed).
+The shell implements **builtins** (**`cd`**, **`export`**, control flow, …) in **`packages/bare-os-booter/lib/shell.js`**. Everything else normally resolves to **`/bin/<name>`** via **`PATH`**. Synthetic trees such as **`/proc/bare_os_features`** expose JSON or text summaries of capabilities and runtime state; they are documented in the [kernel extensions reference](../docs/reference/kernel-extensions.md) and handbook chapters on the booter. If a name does not resolve, verify you are not shadowing a shell builtin and that **`PATH`** includes **`/bin`** (try **`command -v <name>`** when the shell supports it, or **`which <name>`** if installed).
 
 ---