feature: add mkdocs-material documentation site with CI deployment

Generate comprehensive documentation for all 173 source units and
integrate mkdocs-material into the build toolchain. Documentation
covers kernel core, x86 architecture, drivers, applications, and
all subsystems with a tabbed navigation structure.

- Add mkdocs.yml with material theme, mermaid support, and tabbed nav
- Add doc/index.md landing page
- Generate doc/src/ markdown for every Pascal unit in src/
- Reorganize planning docs into doc/planning/
- Add compat, lvglh, and toolchain doc sections
- Update Dockerfile to install python3 and mkdocs-material (pinned <2)
- Replace pasdoc-based compile_docs.sh with mkdocs build --strict
- Add compile_docs.sh to the main build pipeline in compile.sh
- Add deploy-docs step in .drone.yml with host volume mount to nginx
- Add site/.gitkeep for build output directory

doc/src/app/app.base64.md

@@ -0,0 +1,40 @@
+# app.base64
+
+Terminal command for Base64 encoding and decoding of text.
+
+## Overview
+
+`app.base64` registers the `BASE64` shell command, which allows the user to encode an arbitrary text string to Base64 or decode a Base64 string back to plain text. Multiple words passed after `encode` are joined with spaces before encoding.
+
+## Dependencies
+
+- `io.stdio`
+- `core.util`, `arch.x86.util`
+- `core.strings`
+- `debug.tracer`
+- `core.enc.base64`
+- `memory.heap`
+
+## Functions and Procedures
+
+### init
+
+```pascal
+procedure init();
+```
+
+Registers the `BASE64` command with `io.stdio`. Must be called once at startup, typically from `app.mgr.init`.
+
+### run (internal)
+
+```pascal
+procedure run(Params: PParamList; stdin_buf, stdout_buf, stderr_buf: POutBuf);
+```
+
+Command entry point. The first parameter selects the operation (`encode` or `decode`). For encoding, all subsequent parameters are concatenated with spaces into a single string before being passed to `b64_encode_str`. The resulting string is written to `stdout_buf` and then freed. For decoding, the second parameter is passed directly to `b64_decode_str`.
+
+Usage: `BASE64 encode <text...>` or `BASE64 decode <base64string>`
+
+## Notes
+
+The encoded or decoded result is heap-allocated by the `core.enc.base64` routines and freed by this unit after writing to the output buffer. Passing an invalid operation string (anything other than `encode` or `decode`) prints usage information to `stderr_buf`.

doc/src/app/app.dhclient.md

@@ -0,0 +1,37 @@
+# app.dhclient
+
+Terminal command for initiating DHCP network configuration.
+
+## Overview
+
+`app.dhclient` registers the `DHClient` shell command, which triggers a DHCP discovery process to automatically configure the system's network interface. It is a thin wrapper around the `driver.net.proto.dhcp.DHCPDiscover` function.
+
+## Dependencies
+
+- `io.stdio`
+- `core.util`, `arch.x86.util`
+- `core.strings`
+- `debug.tracer`
+- `driver.net.proto.dhcp`
+
+## Functions and Procedures
+
+### init
+
+```pascal
+procedure init();
+```
+
+Registers the `DHClient` command with `io.stdio`. Must be called once at startup from `app.mgr.init`.
+
+### run (internal)
+
+```pascal
+procedure run(Params: PParamList; stdin_buf, stdout_buf, stderr_buf: POutBuf);
+```
+
+Command entry point. Calls `DHCPDiscover()` unconditionally. No parameters are required or examined. All output (lease acknowledgements, errors) is handled within the DHCP driver itself.
+
+## Notes
+
+This is a minimal command stub. Network interface selection and lease management are delegated entirely to `driver.net.proto.dhcp`.

doc/src/app/app.diskcmd.md

@@ -0,0 +1,49 @@
+# app.diskcmd
+
+Command-line tool for inspecting and wiping physical storage devices.
+
+## Overview
+
+`app.diskcmd` registers the `DISK` shell command, which provides three subcommands for working with raw storage devices registered with the storage manager. It queries `driver.storage.mgr` for device information and `driver.storage.vol.mgr` for free-space accounting.
+
+## Dependencies
+
+- `core.ds.lists`, `memory.heap`
+- `driver.storage.mgr`, `driver.storage.types`
+- `core.strings`, `io.stdio`, `debug.tracer`
+- `core.util`, `arch.x86.util`
+- `driver.storage.vol.mgr`
+
+## Functions and Procedures
+
+### init
+
+```pascal
+procedure init();
+```
+
+Registers the `DISK` command with `io.stdio`.
+
+### command_disk (internal)
+
+```pascal
+procedure command_disk(params: PParamList; stdin_buf, stdout_buf, stderr_buf: POutBuf);
+```
+
+Main command dispatcher. Reads the first parameter and routes to `cmd_list`, `cmd_info`, or `cmd_wipe`.
+
+### cmd_list (internal)
+
+Prints a table of all registered storage devices showing index, controller type, writable status, total size, and partition count.
+
+### cmd_info (internal)
+
+Prints detailed information for a single device by index: device ID, controller, controller ID, sector size, total sectors, total size, start sector, free space, and partition count.
+
+### cmd_wipe (internal)
+
+Zeros the entire contents of a writable device. Removes all volumes from the device first via `driver.storage.vol.mgr.init_disk`, then writes zeroed 64-sector batches across all sectors. Requires the device to have write support.
+
+## Notes
+
+Size values are printed in human-readable form (B, KB, MB, or GB). The `wipe` subcommand is destructive and non-reversible; no confirmation prompt is shown. The device must have a `dispatchWrite` function pointer set to be eligible for wiping.

doc/src/app/app.diskutil.md

@@ -0,0 +1,54 @@
+# app.diskutil
+
+Graphical disk utility application for inspecting and managing storage devices.
+
+## Overview
+
+`app.diskutil` provides a windowed GUI application (launched from the desktop) that presents a two-pane interface for working with storage. The left sidebar lists all registered physical devices and their volumes. Selecting an item populates the right-hand detail panel with device or volume information. From the detail panel the user can add or remove partitions and format volumes with any registered filesystem.
+
+The application runs as a registered desktop program and creates an associated process entry so it appears in the process list.
+
+## Dependencies
+
+- `driver.video.desktop`, `driver.video.lvgl`, `driver.video`, `driver.video.windows`
+- `driver.storage.fs.mgr`, `driver.storage.mgr`, `driver.storage.types`
+- `driver.storage.vol.mbr`, `driver.storage.vol.mgr`
+- `memory.heap`, `core.strings`, `io.syslog`, `debug.tracer`
+- `proc.mgr`, `proc.types`
+
+## Constants
+
+### WIN_W / WIN_H
+`740` / `480` — Window dimensions in pixels.
+
+### SIDEBAR_W
+`210` — Width of the device/volume sidebar in pixels.
+
+### SEL_NONE / SEL_DEVICE / SEL_VOLUME
+`0` / `1` / `2` — Selection mode values tracking whether nothing, a device, or a volume is currently selected.
+
+## Functions and Procedures
+
+### init
+
+```pascal
+procedure init();
+```
+
+Registers the application with `driver.video.desktop` under the name `DiskUtil`. The window is created when the user launches it from the desktop environment.
+
+### launch (internal)
+
+Creates the LVGL window, populates the sidebar with all storage devices and their volumes, and spawns a process so the application appears in `PS`.
+
+### refreshSidebar (internal)
+
+Rebuilds the sidebar button list to reflect the current state of registered devices and volumes.
+
+### showDeviceDetail / showVolumeDetail (internal)
+
+Populates the detail panel with properties for the selected device or volume respectively, including action buttons for partition management and formatting.
+
+## Notes
+
+Only one instance of the disk utility window may be open at a time. Destructive operations (partition deletion, formatting) present a confirmation message box before proceeding. The format dropdown is populated from all filesystems registered with `driver.storage.fs.mgr` at the time the detail panel is shown.

doc/src/app/app.edit.md

@@ -0,0 +1,67 @@
+# app.edit
+
+Simple terminal-mode text editor with VFS file load and save support.
+
+## Overview
+
+`app.edit` registers the `EDIT` shell command, which opens a lightweight keyboard-driven text editor. The editor operates on an in-memory line buffer (up to 256 lines of 120 characters each) and can load and save files through the VFS layer. It renders into a terminal window using character-cell drawing primitives.
+
+## Dependencies
+
+- `io.syslog`, `io.stdio`, `debug.tracer`
+- `driver.hid.keyboard`
+- `memory.heap`
+- `driver.storage.types`, `driver.storage.vfs`
+- `core.strings`
+- `core.util`, `arch.x86.util`
+
+## Constants
+
+### ED_WIDTH / ED_HEIGHT
+`60` / `20` — Dimensions of the editor viewport in character columns and rows.
+
+### MAX_LINES
+`256` — Maximum number of lines that can be held in the editor buffer.
+
+### MAX_COLS
+`120` — Maximum number of characters per line.
+
+### TEXT_ROWS
+`19` — Number of rows available for text (one row is reserved for the status bar).
+
+### TAB_SIZE
+`4` — Number of spaces inserted per Tab keypress.
+
+## Functions and Procedures
+
+### init
+
+```pascal
+procedure init();
+```
+
+Registers the `EDIT` command with `io.stdio` and initializes the colour attribute values for normal text, cursor highlight, and the status bar.
+
+### Run (internal)
+
+```pascal
+procedure Run(Params: PParamList; stdin_buf, stdout_buf, stderr_buf: POutBuf);
+```
+
+Command entry point. Accepts an optional file path parameter. If a path is provided it is resolved to an absolute path via `driver.storage.vfs.MakeAbsolutePath`, the buffer is reset, and the file is loaded. The editor window is then opened and the active flag set.
+
+### SaveFile (internal)
+
+Serializes the line buffer to a single contiguous byte array with LF newlines and writes it to the VFS. Tries `omReadWrite / wmRewrite` first for existing files, then `omWriteOnly / wmNew` for new files.
+
+### LoadFile (internal)
+
+Reads up to 32 KB from the VFS into a temporary buffer, then parses it into the line array splitting on LF (CR bytes are skipped).
+
+### OnKeyPressed (internal)
+
+Keyboard event handler. Handles Ctrl+S (save), Escape (close), Tab (insert spaces), Backspace (delete character or merge lines), Enter (split line), arrow keys (cursor movement with scroll adjustment), and printable characters (ASCII 32-126).
+
+## Notes
+
+The window creation and event handler registration stubs are marked `TODO` in the source. The editor is currently single-instance; attempting to open a second instance while one is active logs an error and returns. The draw routine contains stub comments in place of the actual window-drawing calls, meaning rendering is not fully connected in the current codebase state.

doc/src/app/app.filepicker.md

@@ -0,0 +1,60 @@
+# app.filepicker
+
+Reusable LVGL file picker dialog for open and save operations.
+
+## Overview
+
+`app.filepicker` provides a modal file picker widget that can be embedded by any application needing VFS file selection. It presents a two-pane layout with a bookmarks sidebar and a scrollable file list. Directories and files are displayed separately, both sorted alphabetically. The caller supplies a callback that receives the selected path as a heap-allocated string (which the caller must `kfree`) or `nil` on cancellation.
+
+The picker is built on a full-screen semi-transparent backdrop that blocks interaction with the application behind it. Destroying the backdrop tears down the entire picker tree in one LVGL call.
+
+## Dependencies
+
+- `core.ds.hashmap`, `memory.heap`
+- `driver.video.lvgl`
+- `driver.storage.types`, `driver.storage.vfs`
+- `core.strings`, `io.syslog`, `debug.tracer`
+- `core.util`, `arch.x86.util`
+
+## Constants
+
+### FP_FILTER_ALL
+`nil` — Pass as the `filter` parameter to show all file types.
+
+## Types
+
+### TPickerCallback
+
+```pascal
+TPickerCallback = procedure(path: pchar; userdata: pointer); cdecl;
+```
+
+Callback invoked when the user confirms a selection or cancels. `path` is a `kalloc`'d absolute path string that the caller must `kfree`, or `nil` if the user cancelled.
+
+### TPicker / PPicker (internal)
+
+State record holding all LVGL widget references, current directory, navigation history (up to 16 entries), callback pointer, and picker mode flags.
+
+## Functions and Procedures
+
+### show_open
+
+```pascal
+procedure show_open(title: pchar; start_dir: pchar; filter: pchar;
+                    cb: TPickerCallback; userdata: pointer);
+```
+
+Creates and displays an open-mode file picker. `title` is shown in the dialog header. `start_dir` is the initial directory. `filter` restricts visible files to a specific extension (e.g. `'.txt'`), or pass `FP_FILTER_ALL` for no restriction. `cb` is called with the chosen path on confirm or `nil` on cancel. `userdata` is passed through to the callback unchanged.
+
+### show_save
+
+```pascal
+procedure show_save(title: pchar; start_dir: pchar; initial_name: pchar;
+                    filter: pchar; cb: TPickerCallback; userdata: pointer);
+```
+
+Creates and displays a save-mode file picker. In addition to the open-mode features, a filename entry bar is shown below the file list. If the user selects an existing file a two-click overwrite confirmation is required before the callback is invoked. `initial_name` pre-fills the filename bar.
+
+## Notes
+
+Navigation history is capped at 16 entries. Entry names stored in LVGL widget `user_data` are `stringCopy`'d and freed by `free_list_items` before any list repopulation or picker close. Bookmark button paths are similarly managed by `free_bkmk_items`. The picker uses a deferred-refresh timer to avoid re-entering LVGL event handlers during directory population.

doc/src/app/app.inio.md

@@ -0,0 +1,45 @@
+# app.inio
+
+Inline file I/O command for reading and writing VFS files from the terminal.
+
+## Overview
+
+`app.inio` registers the `INIO` shell command, which provides simple redirection-style file access directly from the terminal prompt. It supports two operations: reading a file's contents to the system log (`<`) and writing text to a file (`>`). Path arguments are resolved relative to the current working directory.
+
+## Dependencies
+
+- `io.syslog`, `io.stdio`, `debug.tracer`
+- `memory.heap`
+- `driver.storage.types`, `driver.storage.vfs`
+- `core.strings`
+- `core.util`, `arch.x86.util`
+
+## Functions and Procedures
+
+### init
+
+```pascal
+procedure init();
+```
+
+Registers the `INIO` command with `io.stdio`.
+
+### Run (internal)
+
+```pascal
+procedure Run(Params: PParamList; stdin_buf, stdout_buf, stderr_buf: POutBuf);
+```
+
+Command entry point. Expects at least two parameters: a file path and an operator (`<` or `>`).
+
+**Read mode (`<`):** Opens the file read-only, reads up to 32 KB, and writes the content to `io.syslog`. The read buffer is zeroed and freed after use.
+
+**Write mode (`>`):** Joins all parameters from index 2 onward with spaces to form the content string, then opens the file for writing (attempting read-write rewrite first, then write-only new), writes the content, and closes the file.
+
+The file path is resolved to an absolute path via `driver.storage.vfs.MakeAbsolutePath` before any VFS call.
+
+Usage: `INIO <file> <` or `INIO <file> > text...`
+
+## Notes
+
+The read buffer is fixed at 32 KB. Files larger than this limit are silently truncated. Write operations overwrite the entire file contents.

doc/src/app/app.md5sum.md

@@ -0,0 +1,37 @@
+# app.md5sum
+
+Terminal command for computing the MD5 checksum of a string.
+
+## Overview
+
+`app.md5sum` registers the `MD5SUM` shell command, which computes and prints the MD5 digest of the first command-line argument. The 16-byte digest is printed as 32 uppercase hexadecimal characters.
+
+## Dependencies
+
+- `io.stdio`
+- `core.util`, `arch.x86.util`
+- `core.strings`
+- `debug.tracer`
+- `core.enc.md5`
+
+## Functions and Procedures
+
+### init
+
+```pascal
+procedure init();
+```
+
+Registers the `MD5SUM` command with `io.stdio`.
+
+### run (internal)
+
+```pascal
+procedure run(Params: PParamList; stdin_buf, stdout_buf, stderr_buf: POutBuf);
+```
+
+Command entry point. Takes the first parameter as the input string, computes its MD5 digest using `core.enc.md5.MD5Buffer`, and writes the 16 digest bytes to `stdout_buf` as hex pairs using `bufWriteHexPair`. A trailing space and newline are appended.
+
+## Notes
+
+Only the first parameter is hashed. Multi-word input must be quoted or joined before passing. The `PMD5Digest` pointer returned by `MD5Buffer` is used directly; the caller does not free it (it is assumed to be a static or stack-local result from the MD5 implementation).

doc/src/app/app.meminfo.md

@@ -0,0 +1,41 @@
+# app.meminfo
+
+Terminal command for displaying physical and heap memory statistics.
+
+## Overview
+
+`app.meminfo` registers the `MEMINFO` shell command, which prints a summary of the system's memory state in three sections: Multiboot-reported memory ranges, Physical Memory Manager (PMM) block statistics, and Logical Memory Manager (LMM) heap statistics.
+
+## Dependencies
+
+- `io.stdio`
+- `arch.x86.multiboot`
+- `arch.x86.memory.physical`
+- `memory.heap`
+- `debug.tracer`
+
+## Functions and Procedures
+
+### init
+
+```pascal
+procedure init();
+```
+
+Registers the `MEMINFO` command with `io.stdio`.
+
+### run (internal)
+
+```pascal
+procedure run(Params: PParamList; stdin_buf, stdout_buf, stderr_buf: POutBuf);
+```
+
+Command entry point. Outputs three labelled sections:
+
+**Multiboot:** Reads `multibootinfo^.mem_lower` and `mem_upper` to report lower memory, upper memory, and total memory in KB/MB.
+
+**PMM (4 MB blocks):** Reads `arch.x86.memory.physical.pmm_total_blocks`, `pmm_free_blocks`, and derives used blocks. Reports free physical memory in MB.
+
+**LMM (Heap):** Reads `memory.heap.lmm_page_count` and `lmm_total_free`. Reports heap size in MB and free heap in KB.
+
+All output is written to `stdout_buf`.

doc/src/app/app.mgr.md

@@ -0,0 +1,50 @@
+# app.mgr
+
+Central initialization manager for all baked-in terminal programs and kernel-level command providers.
+
+## Overview
+
+`app.mgr` is the single entry point that registers all built-in shell commands and initializes every bundled application module at boot time. It is called once from `kmain` during the application initialization phase. The unit separates command registration (wiring handler function pointers directly into `io.stdio`) from application-level initialization (which may allocate state, register with the desktop, or set up WASM integration).
+
+## Dependencies
+
+- `debug.tracer`, `io.stdio`, `proc.mgr`
+- `app.base64`, `app.md5sum`, `app.dhclient`, `app.vbeinfo`, `app.testcmd`, `app.ping`, `app.meminfo`, `app.setres`
+- `driver.storage.ctl.ram`, `driver.mgr`
+- `driver.net.proto.ipv4`, `driver.net.proto.arp`, `driver.net.proto.tcp`
+- `driver.storage.filedispatch`
+- `app.wasm.runner`
+- `core.version`, `arch.x86.cpu`
+- `app.diskcmd`, `driver.bus.usb.core`, `app.diskutil`, `app.notepad`, `app.partcmd`, `app.volcmd`
+
+## Functions and Procedures
+
+### init
+
+```pascal
+procedure init();
+```
+
+Registers all kernel-level terminal commands and calls `init()` on every bundled application unit. Commands registered directly from driver and subsystem modules:
+
+| Command | Description |
+|---|---|
+| `CPU` | CPU information |
+| `DEV` | Driver management interface |
+| `PS` | List running processes |
+| `KILL` | Force-kill a process by PID |
+| `TERMINATE` | Gracefully terminate a process by PID |
+| `ARP` | Get ARP table |
+| `IFCONFIG` | Configure network settings |
+| `TCPCONNECT` | Connect to a TCP host and send a test message |
+| `TCPLISTEN` | Listen on a TCP port and log received data |
+| `TCPHTTP` | Send HTTP GET to a host IP |
+| `USB` | USB subsystem information |
+
+Application modules initialized (each registers its own command internally): `app.diskcmd`, `app.partcmd`, `app.volcmd`, `app.diskutil`, `app.notepad`, `app.md5sum`, `app.base64`, `app.dhclient`, `app.vbeinfo`, `app.testcmd`, `app.ping`, `app.meminfo`.
+
+Finally initializes the RAM storage controller, file dispatch subsystem, WASM runner, and display resolution command.
+
+## Notes
+
+Initialization order is significant: `driver.storage.ctl.ram.init()` and `driver.storage.filedispatch.init()` must precede `app.wasm.runner.init()` because the WASM runner registers a file-type handler with the dispatch subsystem.

doc/src/app/app.notepad.md

@@ -0,0 +1,96 @@
+# app.notepad
+
+Graphical text editor application with full file management and text selection.
+
+## Overview
+
+`app.notepad` provides a windowed GUI text editor built on LVGL. It is registered with the desktop environment and launched from the application launcher. The editor supports opening, saving, and creating new documents via an integrated file picker dialog. Text selection is implemented manually on top of LVGL's textarea widget using a selection anchor and direct label selection API calls.
+
+The application runs as a desktop program and creates an associated process entry visible in `PS`.
+
+## Dependencies
+
+- `driver.video.desktop`, `driver.video.lvgl`, `driver.video`, `driver.video.windows`
+- `app.filepicker`
+- `driver.hid.keyboard`
+- `memory.heap`
+- `driver.storage.types`, `driver.storage.vfs`
+- `core.strings`, `io.syslog`, `debug.tracer`
+- `core.util`, `arch.x86.util`
+- `proc.mgr`, `proc.types`
+
+## Constants
+
+### WIN_W / WIN_H
+`700` / `500` — Window dimensions in pixels.
+
+### TOOLBAR_H / STATUSBAR_H
+`40` / `24` — Heights of the toolbar and status bar in pixels.
+
+### FILE_BUF_SIZE
+`65536` — Maximum file read/write buffer size (64 KB).
+
+### LV_NO_SEL
+`$FFFF` — Sentinel returned by LVGL when no text selection is active.
+
+### LV_EVT_STOP_OFF / LV_EVT_STOP_BIT
+`24` / `2` — Byte offset and bitmask used to set the `stop_processing` flag in an `lv_event_t` struct, preventing LVGL's default textarea key handler from also processing a key event.
+
+## Types
+
+### TNotepadState / PNotepadState
+
+Per-instance state record allocated on the heap.
+
+| Field | Type | Description |
+|---|---|---|
+| `win_id` | `uint32` | LVGL window identifier |
+| `pid` | `uint32` | Process ID of the associated notepad process |
+| `ta` | `Plv_obj` | LVGL textarea widget |
+| `status_label` | `Plv_obj` | Status bar label showing line, column, and filename |
+| `dirty_label` | `Plv_obj` | Dirty-flag indicator label |
+| `currentPath` | `pchar` | Heap-allocated path of the open file, or `nil` for untitled |
+| `isDirty` | `boolean` | Whether the document has unsaved changes |
+| `sel_anchor` | `sint32` | Byte offset of the selection anchor; `-1` means no selection |
+
+## Functions and Procedures
+
+### init
+
+```pascal
+procedure init();
+```
+
+Registers the application with `driver.video.desktop` under the name `Notepad`.
+
+### launch (internal)
+
+Creates the LVGL window, toolbar (New, Open, Save, Save As buttons), main textarea, and status bar. Registers keyboard event callbacks and spawns the notepad process.
+
+### saveFile (internal)
+
+Writes the textarea content to `currentPath` via VFS. Opens for read-write rewrite first; falls back to write-only new for new files. Shows an error message box on failure.
+
+### loadFile (internal)
+
+Reads a file from VFS into the textarea. Resets dirty state and selection anchor after loading.
+
+### performNew (internal)
+
+Clears the textarea, resets `currentPath` to `nil`, and updates the status bar.
+
+### updateStatusBar (internal)
+
+Computes the 1-based line and column from the current cursor byte offset and updates the status label text.
+
+### buildSplicedString (internal)
+
+Returns a new heap-allocated string with a range `[from_idx, to_idx)` replaced by an optional insertion string. Used for selection deletion and text replacement.
+
+### applyIndent (internal)
+
+Applies or removes 4-space indentation from every line overlapping a selection range. Returns a new heap-allocated string.
+
+## Notes
+
+Only one Notepad window may be open at a time. Closing with unsaved changes shows a discard confirmation dialog. The Shift+Arrow selection mechanism uses `lv_label_set_text_selection_start/end` directly rather than LVGL's built-in selection, because user key callbacks fire before the default widget handler, allowing `stopEvent` to suppress unwanted default behaviour.

doc/src/app/app.partcmd.md

@@ -0,0 +1,61 @@
+# app.partcmd
+
+Command-line tool for MBR partition table management.
+
+## Overview
+
+`app.partcmd` registers the `PART` shell command, which provides four subcommands for managing the MBR partition table of a storage device. It supports listing, adding, removing, and formatting partitions. Partition sizes can be specified with unit suffixes (B, KB, MB, GB). Auto-initialization of a missing MBR is performed transparently when adding the first partition.
+
+## Dependencies
+
+- `driver.storage.fs.mgr`
+- `core.ds.lists`, `memory.heap`
+- `driver.storage.vol.mbr`, `driver.storage.vol.mgr`
+- `io.stdio`, `driver.storage.mgr`, `driver.storage.types`
+- `core.strings`, `debug.tracer`
+
+## Functions and Procedures
+
+### init
+
+```pascal
+procedure init();
+```
+
+Registers the `PART` command with `io.stdio`.
+
+### command_part (internal)
+
+```pascal
+procedure command_part(params: PParamList; stdin_buf, stdout_buf, stderr_buf: POutBuf);
+```
+
+Main dispatcher routing to one of four subcommand procedures.
+
+### cmd_list (internal)
+
+Reads the MBR from the specified disk and prints the four partition slots showing system ID, LBA start, size, and boot flag. Warns if the boot marker is not `$AA55`.
+
+### cmd_add (internal)
+
+Adds a new partition to the first available slot. If no valid MBR exists the disk is auto-initialized. An optional size argument is parsed by `parsesize`; if omitted all remaining free sectors are used. The new partition receives system ID `0` (unformatted).
+
+### cmd_rm (internal)
+
+Clears a partition slot (0-3) on the specified disk, updating the on-disk MBR.
+
+### cmd_format (internal)
+
+Formats the volume corresponding to a partition slot using a named filesystem. Looks up the filesystem by name via `driver.storage.fs.mgr.find_filesystem_by_name`, creates a volume record if one does not already exist, calls the filesystem's `createCallback`, and re-probes the volume to confirm the new signature.
+
+### parsesize (internal)
+
+```pascal
+function parsesize(s: pchar; sectorSize: uint32): uint32;
+```
+
+Converts a human-readable size string (e.g. `500MB`, `2GB`, `1024KB`, `4096B`, or plain integer treated as bytes) into a sector count. Returns `0` on invalid input.
+
+## Notes
+
+The MBR supports exactly four primary partition slots (slots 0-3). Logical/extended partitions are not supported. The `format` subcommand overwrites any existing filesystem on the target slot without a separate confirmation prompt.

doc/src/app/app.ping.md

@@ -0,0 +1,73 @@
+# app.ping
+
+ICMP ping command that sends echo requests and reports round-trip times.
+
+## Overview
+
+`app.ping` registers the `PING` shell command. Given an IPv4 address, it sends 10 ICMP echo requests with a 1-second delay between each, printing the round-trip time or an error reason for each attempt. A 5-second timeout is enforced per ping. Per-invocation state is heap-allocated so multiple terminal instances can ping concurrently without interfering with each other.
+
+## Dependencies
+
+- `io.stdio`, `debug.tracer`
+- `arch.x86.bda`
+- `driver.net.types`, `driver.net.proto.icmp`, `driver.net.util`
+- `core.strings`
+- `proc.mgr`
+- `core.util`, `arch.x86.util`
+- `memory.heap`
+
+## Constants
+
+### PING_TIMEOUT_MS
+`5000` — Per-ping timeout in milliseconds.
+
+## Types
+
+### TPingResult
+
+```pascal
+TPingResult = (prWaiting, prGotReply, prGotError);
+```
+
+State of a single in-flight ping.
+
+### TPingState / PPingState
+
+Per-invocation state record allocated on the heap.
+
+| Field | Type | Description |
+|---|---|---|
+| `Result` | `TPingResult` | Current result state |
+| `ReplyTimeMS` | `uint64` | Round-trip time in timer ticks |
+| `ErrorReason` | `TARPErrorCode` | Error code if `prGotError` |
+| `SendTime` | `uint64` | BIOS tick counter value at send time |
+
+## Functions and Procedures
+
+### init
+
+```pascal
+procedure init();
+```
+
+Registers the `PING` command with `io.stdio`.
+
+### run (internal)
+
+```pascal
+procedure run(Params: PParamList; stdin_buf, stdout_buf, stderr_buf: POutBuf);
+```
+
+Command entry point. Parses the first parameter as an IPv4 address string using `stringToIPv4`. Allocates a `TPingState` record and sends 10 ICMP requests in a loop. Between each request it spin-yields via `proc.mgr.proc_yield` until the reply or error callback fires, or until the timeout expires. Sleeps 1 second between pings using `proc.mgr.proc_sleep_ms`. Frees the state record and IP buffer on completion.
+
+### on_reply (internal)
+
+ICMP callback: records the elapsed time and sets `Result` to `prGotReply`.
+
+### on_error (internal)
+
+ICMP callback: records the error reason and sets `Result` to `prGotError`.
+
+## Notes
+
+Round-trip time is reported in BIOS timer ticks (the counter runs at approximately 1024 Hz), not milliseconds. Error reasons include: `aecFailedToResolveHost`, `aecNoRouteToHost`, `aecTimeout`, and `aecTTLExpired`.

doc/src/app/app.setres.md

@@ -0,0 +1,39 @@
+# app.setres
+
+Terminal command for changing the display resolution at runtime.
+
+## Overview
+
+`app.setres` registers the `SETRES` shell command, which switches the display to a specified width and height at 32 bits per pixel. It delegates to the GPU driver framework (`driver.video.gpu.setMode`), which attempts a BGA (Bochs Graphics Adapter) mode switch first and falls back to VBE/VESA if BGA is unavailable.
+
+## Dependencies
+
+- `io.stdio`, `io.syslog`
+- `driver.video.gpu`
+- `core.util`, `arch.x86.util`
+- `core.strings`
+- `debug.tracer`
+
+## Functions and Procedures
+
+### init
+
+```pascal
+procedure init();
+```
+
+Registers the `SETRES` command with `io.stdio`.
+
+### run (internal)
+
+```pascal
+procedure run(Params: PParamList; stdin_buf, stdout_buf, stderr_buf: POutBuf);
+```
+
+Command entry point. Parses two numeric parameters (width and height). Validates that neither is zero. Calls `driver.video.gpu.setMode(w, h, 32, info)` and reports the active driver name on success, or an error message on failure.
+
+Usage: `SETRES <width> <height>` (e.g. `SETRES 1024 768`)
+
+## Notes
+
+The bit depth is always fixed at 32. The `TGPUModeInfo` struct populated by `setMode` is not currently inspected by this command. A failed mode switch does not restore any previous state; behaviour depends on the underlying GPU driver.

doc/src/app/app.testcmd.md

@@ -0,0 +1,35 @@
+# app.testcmd
+
+Simple test command that demonstrates incremental output with timed delays.
+
+## Overview
+
+`app.testcmd` registers the `TEST` shell command, which prints five numbered lines to stdout with a 1-second pause between each. Its primary purpose is to demonstrate that long-running commands execute as preemptive processes, with output appearing incrementally in the terminal without blocking the rest of the system.
+
+## Dependencies
+
+- `io.stdio`
+- `proc.mgr`
+- `debug.tracer`
+
+## Functions and Procedures
+
+### init
+
+```pascal
+procedure init();
+```
+
+Registers the `TEST` command with `io.stdio`.
+
+### run (internal)
+
+```pascal
+procedure run(Params: PParamList; stdin_buf, stdout_buf, stderr_buf: POutBuf);
+```
+
+Prints the lines `Test output 1 of 5` through `Test output 5 of 5` to `stdout_buf`, calling `proc.mgr.proc_sleep_ms(1000)` between each line (except after the last).
+
+## Notes
+
+This unit is a development and diagnostic aid. The command accepts no parameters.

doc/src/app/app.uidebug.md

@@ -0,0 +1,62 @@
+# app.uidebug
+
+Toggleable real-time diagnostic overlay for the LVGL desktop.
+
+## Overview
+
+`app.uidebug` provides a semi-transparent diagnostic panel that floats over all other UI content. When visible it displays live system metrics updated every frame: FPS, open window count, screen widget count, mouse position, LVGL tick counter, total memory, and screen resolution. A rolling FPS history chart with auto-scaling Y axis is rendered below the text rows.
+
+The overlay is toggled by calling `toggle` (typically wired to F12 in the keyboard handler). It does not register a terminal command; it is controlled programmatically.
+
+## Dependencies
+
+- `driver.video.lvgl`
+- `driver.video.windows`
+- `driver.hid.mouse`
+- `driver.video`
+- `arch.x86.multiboot`
+- `debug.tracer`
+
+## Constants
+
+### PANEL_W / PANEL_H
+`220` / `280` — Default panel dimensions (auto-sized to content in practice).
+
+### FPS_INTERVAL
+`1000` — Milliseconds between FPS recalculations.
+
+### GRAPH_SAMPLES
+`60` — Number of FPS history data points in the ring buffer.
+
+### GRAPH_MAX_FPS
+`120` — Maximum Y-axis value for the FPS graph (used as a fallback; the graph auto-scales to actual min/max).
+
+## Functions and Procedures
+
+### update
+
+```pascal
+procedure update;
+```
+
+Must be called once per frame from the main render loop (before `lvgl_handler`). If the overlay is visible, refreshes all label text and updates the FPS graph. Uses a static 64-byte scratch buffer for label strings to avoid heap allocation per frame.
+
+### toggle
+
+```pascal
+procedure toggle;
+```
+
+Shows the overlay if it is currently hidden, or destroys it if it is visible. Resets FPS tracking state on show.
+
+### isVisible
+
+```pascal
+function isVisible: boolean;
+```
+
+Returns `true` if the overlay is currently displayed.
+
+## Notes
+
+The overlay is always moved to the foreground on each `update` call via `lv_obj_move_foreground`. Label updates use a module-level static character buffer (`buf`) to avoid per-frame heap allocations. The widget count displayed is only the direct child count of the active screen, not a full recursive widget tree count.

doc/src/app/app.vbeinfo.md

@@ -0,0 +1,39 @@
+# app.vbeinfo
+
+Terminal command for displaying current display mode parameters.
+
+## Overview
+
+`app.vbeinfo` registers the `VBEINFO` shell command, which prints the current framebuffer width, height, and bits-per-pixel as reported by `driver.video`. Despite the name it works with any registered video driver, not exclusively VESA/VBE.
+
+## Dependencies
+
+- `io.stdio`
+- `driver.video`
+- `core.util`, `arch.x86.util`
+- `core.strings`
+- `debug.tracer`
+
+## Functions and Procedures
+
+### init
+
+```pascal
+procedure init();
+```
+
+Registers the `VBEINFO` command with `io.stdio`.
+
+### run (internal)
+
+```pascal
+procedure run(Params: PParamList; stdin_buf, stdout_buf, stderr_buf: POutBuf);
+```
+
+Command entry point. Writes three lines to `stdout_buf`:
+
+- `Pixel Width: <value>`
+- `Pixel Height: <value>`
+- `Bits Per Pixel: <value>`
+
+Values are read from `driver.video.frontBufferWidth`, `frontBufferHeight`, and `frontBufferBpp`.

doc/src/app/app.volcmd.md

@@ -0,0 +1,44 @@
+# app.volcmd
+
+Command-line tool for inspecting registered storage volumes.
+
+## Overview
+
+`app.volcmd` registers the `VOL` shell command, which provides two subcommands for viewing the logical volumes known to `driver.storage.vol.mgr`. It shows the relationship between volumes and their underlying physical devices, filesystem assignments, and space usage.
+
+## Dependencies
+
+- `core.ds.lists`, `memory.heap`
+- `driver.storage.mgr`, `driver.storage.types`
+- `core.strings`, `io.stdio`, `debug.tracer`
+- `driver.storage.vol.mgr`
+
+## Functions and Procedures
+
+### init
+
+```pascal
+procedure init();
+```
+
+Registers the `VOL` command with `io.stdio`.
+
+### command_vol (internal)
+
+```pascal
+procedure command_vol(params: PParamList; stdin_buf, stdout_buf, stderr_buf: POutBuf);
+```
+
+Main dispatcher routing to `cmd_list` or `cmd_info`.
+
+### cmd_list (internal)
+
+Prints a summary table of all registered volumes: index, device ID and controller type, total size, and assigned filesystem name (or `none`).
+
+### cmd_info (internal)
+
+Prints detailed information for a single volume by index: sector start, sector count, sector size, total size, free size, boot drive flag, filesystem name, and parent device ID and controller type.
+
+## Notes
+
+Volume indices are assigned by the volume manager at registration time and may not correspond to partition slot numbers. Free space reported in `cmd_info` reflects the `freeSectors` field of the volume record, which must be updated by the filesystem driver to remain accurate.

doc/src/app/app.vterminal.md

@@ -0,0 +1,97 @@
+# app.vterminal
+
+LVGL-based multi-instance visual terminal emulator.
+
+## Overview
+
+`app.vterminal` implements a full graphical terminal window that runs inside the Asuro desktop environment. Each instance is fully independent: it maintains its own scrollback buffer, input line, command history, working directory, directory stack, foreground process, and background job list. All per-instance state is stored in a heap-allocated `TVTermState` record referenced through LVGL widget `user_data`.
+
+Commands are parsed and dispatched as preemptive processes via `proc.mgr.runCommand`. A per-instance LVGL timer polls the foreground process's stdout and stderr buffers at 100 ms intervals and appends new output to the scrollback. Background jobs (launched with a trailing `&`) are tracked separately and reaped when they finish.
+
+## Dependencies
+
+- `driver.video.lvgl`, `driver.video`, `driver.video.windows`, `driver.video.desktop`
+- `driver.hid.keyboard`
+- `debug.tracer`
+- `core.strings`, `core.util`, `arch.x86.util`
+- `memory.heap`, `core.version`
+- `io.stdio`, `driver.storage.vfs`
+- `proc.mgr`, `proc.types`
+- `core.ds.lists`, `core.ds.hashmap`
+- `driver.storage.filedispatch`
+
+## Constants
+
+### TERM_W / TERM_H
+`640` / `400` — Terminal window dimensions in pixels.
+
+### MAX_TEXT
+`4096` — Maximum scrollback buffer length in characters. When full, the oldest half is discarded.
+
+### MAX_LINE
+`1024` — Maximum input line length.
+
+### HIST_SIZE
+`10` — Number of command history entries.
+
+### DRAIN_PERIOD
+`100` — Milliseconds between output-drain timer polls.
+
+## Types
+
+### TVTermState / PVTermState
+
+Per-instance state record allocated on the heap.
+
+| Field | Description |
+|---|---|
+| `win_id` | LVGL window identifier |
+| `text_label` | LVGL label widget holding the scrollback text |
+| `drain_timer` | Per-instance LVGL timer for polling foreground process output |
+| `text_buf` | Scrollback character buffer |
+| `line_buf` | Current input line being typed |
+| `hist` | Ring buffer of recent commands |
+| `ForegroundPID` | PID of the currently running foreground process, or 0 |
+| `fg_stdout/stderr/stdin` | I/O buffers for the foreground process |
+| `TerminalPID` | PID of the terminal's own idle process |
+| `cwd` | Per-terminal working directory string |
+| `dir_stack` | Stack of saved working directories for `pushd`/`popd` |
+| `bg_jobs` | Dynamic list of background job records |
+
+### TBackgroundJob / PBackgroundJob
+
+Record tracking a background process: PID, job number, command name, stdout/stderr buffers, and drain watermarks.
+
+## Functions and Procedures
+
+### init
+
+```pascal
+procedure init;
+```
+
+Registers the terminal application with `driver.video.desktop` under the name `Terminal`. Multiple independent instances can be launched from the desktop.
+
+### launch (internal)
+
+Allocates a new `TVTermState`, creates the LVGL window with a black background and green-on-black text label, registers event callbacks, creates the drain timer, spawns the terminal process, and displays the welcome prompt.
+
+### processCommand (internal)
+
+Parses the input line into a parameter list and dispatches to a built-in handler or `io.stdio.findCommand`. Supports background launch via trailing `&`. Falls through to `driver.storage.filedispatch` for file-based executables if no registered command matches.
+
+## Built-in Commands
+
+| Command | Description |
+|---|---|
+| `CLEAR` | Clears the scrollback buffer |
+| `CD` | Changes the per-terminal working directory |
+| `LS` | Lists the contents of the current directory |
+| `PUSHD` | Pushes the current directory onto the stack |
+| `POPD` | Pops and changes to the top directory on the stack |
+| `JOBS` | Lists active background jobs |
+| `FG` | Brings the first background job to the foreground |
+
+## Notes
+
+Ctrl+C terminates the foreground process, drains remaining output, and returns to the prompt. History navigation uses Up/Down arrow keys and wraps correctly on ring buffer boundaries. The scrollback buffer uses a half-discard strategy when full to avoid blocking I/O.

doc/src/app/wasm/app.wasm.cleanup.md

@@ -0,0 +1,39 @@
+# app.wasm.cleanup
+
+Teardown handler for WASURO VM allocations when a WASM process exits or is killed.
+
+## Overview
+
+`app.wasm.cleanup` provides a single public procedure, `wasm_resource_cleanup`, whose signature matches the `TResourceCleanup` callback type used by `proc.mgr.bindResource`. When a WASM process terminates (normally or via kill), the process manager invokes this callback with the shim pointer, which then walks the entire `PWASMProcessContext` and frees every heap allocation made during parsing and VM setup.
+
+Because the WASURO VM library is treated as read-only, teardown is performed entirely on the Asuro side by mirroring the known allocation patterns from the WASM parser and VM initializer.
+
+## Dependencies
+
+- `memory.heap`
+- `wasm.types.builtin`, `wasm.types.context`, `wasm.types.sections`
+- `wasm.types.heap`, `wasm.types.values`
+- `app.wasm.shim`
+
+## Functions and Procedures
+
+### wasm_resource_cleanup
+
+```pascal
+procedure wasm_resource_cleanup(handle: void);
+```
+
+Top-level cleanup entry point. Casts `handle` to `PProcessWASMShim` and frees all nested WASM structures in order:
+
+1. Execution state: heap memory pages, operand and control stacks, globals, tables, data segments, element segments, flat code buffer.
+2. Section data: type section (per-type parameter and return type arrays), import section (module and field name strings), function section, export section (entry name strings), code section (per-entry code buffers and local variable arrays), memory section.
+3. Resolved imports array and host function registry entries array.
+4. The `PWASMProcessContext` record itself.
+5. Shim-owned allocations: `FileBuffer` and `ArgBuf`.
+6. The `PProcessWASMShim` record itself.
+
+Each sub-free procedure guards against `nil` pointers before dereferencing.
+
+## Notes
+
+Import section `ModuleName` and `FieldName` pointers in the resolved imports array alias the strings already freed by `freeImportSection`, so they must not be freed a second time. Similarly, `ModuleName` and `FieldName` in the host function registry entries are compile-time string constants and must not be freed. The `ExecutionState.Locals` pointer aliases an entry inside `CodeSection` and has no independent free.