Mesh OS operates on an event-driven microkernel architecture where completely
decoupled daemons communicate exclusively via asynchronous JSON intents over a
universal bus.

By migrating from the monolithic `bash_lexer.js` to the modular `parser.js`
and `core_utils.js`, you are transitioning from a hardcoded switch-statement
script to a true, POSIX-style distributed operating system environment.

Here is the comprehensive developer documentation mapping out the big picture,
the flow of intents, and the exact steps to migrate your terminal
environments.

## 1. Core Architecture: The Universal Bus

At the heart of the system is the microkernel (`kernel_v3.js`). It has no
logic for commands, routing, or files; it simply allocates memory (`Registry`)
and manages the pub/sub event loops (`MeshOS.emit`, `MeshOS.subscribe`).

Every background script (daemon) and visual app (window) is entirely isolated.
They interact by throwing "Intents" (actions and payloads) onto this global
bus.

**The Boot Sequence Pipeline:**

1. `kernel_v3.js` mounts the OPFS filesystem and generates the cryptographic
identity.


2. It blind-launches headless daemons (e.g., `parser.js`, `vfs_mutator.js`,
`mesh_bridge_v3.js`) into memory.


3. It allocates the `Registry` (Workspaces and Windows) and hands control to
the DOM driver (`WindowManager`).


4. It reads `/system/autoexec.sh` and fires the initial intents to launch
user-space apps (like the RAM engine and IPC bridge).



## 2. The Great Migration: V1 Monolith vs. V2 Modularity

The old terminal architecture relied on `bash_lexer.js` acting as a monolithic
god-object. The new architecture distributes this workload safely.

### The Legacy Pipeline (V1)

* **The UI:** `terminal.js` listens to keystrokes and broadcasts
`CMD_RAW_INPUT`.
* **The Monolith:** `bash_lexer.js` catches `CMD_RAW_INPUT`. It parses
arguments, manages the VFS Crypto logic, processes aliases, manages redirects,
natively executes binaries, and contains massive `if/else if` blocks for core
OS commands (`cat`, `tree`, `launch`, `obj`, `coop`).


* **The Flaw:** If one regex interceptor fails or a loop hangs, the entire OS
command pipeline crashes. Adding new native commands requires modifying the
kernel-level lexer.

### The Modular Pipeline (V2)

The new architecture splits responsibilities into three distinct, decoupled
layers:

1. **The Input Node (`terminal2.js`):** A lightweight UI that simply captures
keystrokes and broadcasts `CMD_EXEC_V2` to the bus, attaching its specific
return address (`stream_term_out_{windowId}`).


2. **The Orchestrator (`parser.js`):** Catches `CMD_EXEC_V2`. It acts as a
strict AST parser. It handles semicolons to split commands, resolves aliases,
manages `|` pipes, and handles `>` redirects. It does **not** hardcode
commands.


3. **The Execution Layer:** For every parsed step, `parser.js` first checks if
the command exists in the standard library (`MeshCoreUtils`). If it does not,
it safely traverses `/vfs/bin/` to load and run the executable binary
natively.


4. **The Standard Library (`core_utils.js`):** A pure Javascript object
(`window.MeshCoreUtils`) that holds modular system commands like `tree`,
`cat`, and `alias`.



## 3. Peripheral Daemon Capabilities

Because everything runs on intents, expanding the OS simply means launching
new daemons that listen to specific bus channels:

* **`vfs_mutator.js`:** Listens for `SYSTEM_VFS_MUTATE`. It compiles safe
regex anchors from incoming intents, atomically patches OPFS files, and
broadcasts `VFS_UPDATED` upon success.


* **`data_router.js`:** Listens for `DATA_QUERY`. It acts as a DNS lookup,
translating a user request for `crm_customers` into a raw SQLite string and
bouncing an `ADAPTER_EXECUTE_SQLITE_WASM` intent to the underlying database
engine.


* **`pipeline_manager.js`:** Listens for `CMD_PARSED`. Rather than freezing
the UI thread, it offloads heavy execution graphs (data processing) into a
detached WebWorker.


* **`mesh_bridge_v3.js`:** Listens for `SYSTEM_VFS_READ_REQUEST` and
`SYSTEM_VFS_WRITE_REQUEST`. It intercepts internal intents and safely relays
them over an encrypted WebSocket to remote edge nodes.



## 4. How to Complete the V2 Migration