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/compat/lmemorymanager.md

@@ -0,0 +1 @@
+# Placeholder

doc/compat/types.md

@@ -0,0 +1 @@
+# Placeholder

doc/lvglh/hack_14.md

@@ -0,0 +1 @@
+# Placeholder

doc/lvglh/lv_conf.md

@@ -0,0 +1 @@
+# Placeholder

doc/lvglh/lv_font_fa_solid_16.md

@@ -0,0 +1 @@
+# Placeholder

doc/planning/tracer.md

@@ -0,0 +1,95 @@
+# Tracer Refactor Design
+
+## Goal
+Refactor tracer.pas to eliminate all copy operations and use an O(1) ring buffer of PChar pointers. Maximize efficiency, minimize overhead, and guard against interrupt-driven corruption.
+
+## Agreed Design Decisions
+
+### 1. No String Copies — Store PChar Directly
+- **Decision**: Trust callers. Store the `PChar` pointer directly in the ring buffer — no `StringCopy`, no `kalloc`, no `kfree`.
+- **Contract**: `push_trace` MUST only be called with pointers to static/persistent data (e.g. string literals). Passing a heap-allocated or stack-allocated PChar that may later be freed is undefined behavior.
+- **Rationale**: All current callers pass string literals baked into the binary. This eliminates all heap allocation from the hot path.
+
+### 2. Ring Buffer (O(1) push)
+- **Structure**: `Traces: Array[0..MAX_TRACE-1] of PChar` (static, 40 slots).
+- **Index**: Single `head: uint32` variable.
+- **head semantics**: `head` always points to the **most recently written** slot.
+- **Push operation**:
+  ```pascal
+  head := (head + 1) mod MAX_TRACE;
+  Traces[head] := t_name;
+  ```
+- **Read operations**:
+  - `get_last_trace` → `Traces[head]`
+  - `get_trace_N(idx)` → `Traces[(head - idx + MAX_TRACE) mod MAX_TRACE]`
+    - idx=0 is the most recent trace, idx=39 is the oldest.
+- **No shifting loop**. Current O(n) shift of 40 entries on every push is eliminated.
+
+### 3. Initialization
+- All 40 slots set to `nil`.
+- `head` initialized to `MAX_TRACE - 1` (39).
+- `push_trace('kmain')` is called, which advances `head` to 0 and writes `'kmain'` to `Traces[0]`.
+- After init: head = 0, Traces[0] = 'kmain', all other slots = nil.
+
+### 4. Interrupt Safety — Locked Boolean (Skip on Contention)
+- **Mechanism**: A `Locked: Boolean` reentrancy guard around `push_trace` only.
+- **Behavior**: If `push_trace` is already executing (e.g., main code is mid-push) and an ISR calls `push_trace`, the ISR sees `Locked = true` and **silently drops** its trace.
+- **Readers are NOT locked**: `get_last_trace` and `get_trace_N` always proceed without checking `Locked`. Since `head` is advanced AFTER the pointer is written, readers always see a consistent state.
+- **Race window analysis**: There is a tiny window between checking `if not Locked` and setting `Locked := true` where an interrupt could cause both main code and ISR to enter the critical section. With the ring buffer design, the worst case is one trace being overwritten in the same slot — acceptable for a debug tracing tool.
+
+### 5. pop_trace — No-Op Stub
+- `pop_trace` remains in the interface as an empty procedure (no-op).
+- This preserves ABI compatibility with all existing callers (`vmemorymanager`, `vterminal`, `kernel`, etc.) without requiring changes across the codebase.
+- Traces are never removed from the ring buffer.
+
+### 6. get_trace_count — Always Returns MAX_TRACE (40)
+- No tracking of actual push count.
+- Callers already handle `nil` entries from unfilled slots.
+- This keeps the implementation simpler (one less variable to maintain atomically).
+
+### 7. TRACER_ENABLE Compile-Time Guard — Kept
+- All function bodies remain wrapped in `if TRACER_ENABLE then`.
+- When `TRACER_ENABLE = false`, the compiler dead-code eliminates all tracer logic for zero runtime cost.
+- `t_ready` provides orthogonal runtime enable/disable.
+
+### 8. Dead Code Removal
+The following unused code will be removed:
+- `PTracerEntry` / `TTracerEntry` record types (linked list — never used)
+- `head` / `tail` : `PTracerEntry` variables (shadow the new `head: uint32`)
+- `c_lock: Boolean` (declared, never set to true, unreachable guard)
+- Old `Locked: Boolean` replaced by new `Locked: Boolean` with same semantics but cleaner usage
+
+### 9. Uses Clause Cleanup
+- Remove `lmemorymanager` (no more kalloc/kfree).
+- Remove `serial` (not used).
+- Keep `util`, `strings`, `stdio` (used by terminal command).
+
+## Resulting push_trace (Pseudocode)
+```pascal
+procedure push_trace(t_name: PChar);
+begin
+  if TRACER_ENABLE then begin
+    if t_ready then begin
+      if not Locked then begin
+        Locked := true;
+        head := (head + 1) mod MAX_TRACE;
+        Traces[head] := t_name;
+        Locked := false;
+      end;
+    end;
+  end;
+end;
+```
+
+## Performance Summary
+| Operation     | Before             | After         |
+|---------------|--------------------|---------------|
+| push_trace    | O(n) shift + alloc | O(1) 2 stores |
+| pop_trace     | No-op              | No-op         |
+| get_last_trace| O(1)               | O(1)          |
+| get_trace_N   | O(1)               | O(1)          |
+| Memory alloc  | kalloc per push    | Zero          |
+| Memory free   | kfree on overflow  | Zero          |
+
+## Files Changed
+- `src/tracer.pas` — Full rewrite of internals, interface unchanged.

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.