fix: missing index.md from doc folder

The Drone runner environment does not have `pip` or `mkdocs` on PATH
even when installed via the Docker image. Use `pip3` explicitly and
invoke mkdocs as `python3 -m mkdocs` to ensure reliable execution.
Also add --break-system-packages to the fallback install.

.drone.yml

@@ -25,6 +25,30 @@ steps:
       - chmod +x /drone/src/toolchain/*.sh
       - /drone/src/toolchain/compile.sh
       
+  - name: deploy-docs
+    image: alpine:latest
+    depends_on:
+      - compile
+    when:
+      branch:
+        - master
+        - develop
+        - feature/mkdocs
+    volumes:
+      - name: docs-htdocs
+        path: /htdocs
+    commands:
+      - apk add --no-cache rsync
+      - |
+        if [ "${DRONE_BRANCH}" = "master" ]; then
+          DEST="/htdocs/master"
+        else
+          DEST="/htdocs/develop"
+        fi
+      - mkdir -p "$DEST"
+      - rsync -a --delete site/ "$DEST/"
+      - echo "Documentation deployed to ${DRONE_BRANCH}"
+
   - name: upload-iso-artifact
     image: alpine/git
     depends_on:
@@ -64,3 +88,9 @@ steps:
       webhook_token:
         from_secret: discord_webhook_secret
       message: "**Asuro Build**\n\n{{#success build.status}}✅ Build successful!\n\n{{else}}❌ Build failed!\n\n{{/success}}Repository: `{{repo.namespace}}/{{repo.name}}`\nBranch: `{{commit.branch}}`\nCommit: `{{commit.sha}}`\nAuthor: `{{commit.author}} <{{commit.email}}>`\n\nGitea Diff: [Link](<{{commit.link}}>)\nDrone Build: [Link](<{{build.link}}>)\n\nMessage: {{commit.message}}"
+
+volumes:
+  - name: docs-htdocs
+    host:
+      path: /mnt/user/htdocs/asuro_docs
+

.gitignore

@@ -16,6 +16,7 @@ dockerout.txt
 AGENTS.md
 lessons_learnt.md
 *.log
-/doc/*.md
 wasuro
 src/core/core.version.pas
+site/*
+!site/.gitkeep

Dockerfile

@@ -5,9 +5,12 @@ VOLUME ["/code"]
 ENV DEBIAN_FRONTEND=noninteractive
 RUN dpkg --add-architecture i386
 RUN apt-get update && apt-get install -y \
-	curl dos2unix wget git make nasm binutils xorriso grub-pc-bin gcc gcc-multilib && \
+	curl dos2unix wget git make nasm binutils xorriso grub-pc-bin gcc gcc-multilib \
+	python3 python3-pip && \
 	apt-get clean my room
 
+RUN pip3 install --no-cache-dir --break-system-packages "mkdocs>=1.6,<2" mkdocs-material
+
 SHELL ["/bin/bash", "-c"]
 ARG FPC_VERSION=3.2.2
 RUN curl -sL https://sourceforge.net/projects/freepascal/files/Linux/$FPC_VERSION/fpc-$FPC_VERSION.i386-linux.tar/download | tar -xf - && \

doc/compat/lmemorymanager.md

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

doc/compat/types.md

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

doc/index.md

@@ -0,0 +1,32 @@
+# Asuro OS
+
+Asuro is a 32-bit x86 operating system kernel written in Free Pascal and x86 assembly.
+
+## Documentation Structure
+
+- **Kernel Entry** -- The `asuro.pas` main unit and boot sequence.
+- **Architecture (x86)** -- CPU initialization, descriptor tables, interrupt handling, fault handlers, memory management, and process scheduling for the i386 target.
+- **Boot** -- Splash screen and early boot visuals.
+- **Core** -- Foundational libraries including data structures, encoding algorithms, string handling, graphics primitives, and the kernel panic subsystem.
+- **Memory** -- Heap allocator (`kalloc`/`kfree`) and page-level allocation.
+- **Processes** -- Process lifecycle, round-robin scheduling, and inter-process messaging.
+- **I/O** -- Standard I/O (shell command dispatch) and the system log fan-out.
+- **Debug** -- Execution tracer with ring-buffer call stack recording.
+- **Drivers** -- Hardware abstraction covering PCI/USB buses, HID devices, networking (E1000, TCP/IP stack), storage (IDE, AHCI, VFS, file systems), video (VESA, LVGL, double-buffering), serial I/O, and timers.
+- **Services** -- Background daemons for graphics rendering and USB hotplug.
+- **Applications** -- Userland commands and utilities: terminal, text editor, disk tools, network tools, and a WebAssembly runtime.
+- **Compatibility** -- Shim layers for legacy code.
+- **LVGL Headers** -- Configuration and patches for the LVGL v9.2.2 GUI library.
+- **Planning** -- Design documents and architectural notes for subsystems under development.
+- **Toolchain** -- Build pipeline documentation covering compilation, linking, and ISO generation.
+
+## Building
+
+The kernel is built inside Docker using a containerized FreePascal 3.2.2 toolchain:
+
+```bash
+docker compose build builder
+docker compose run builder
+```
+
+The documentation site will be available at `http://docs.asuro.xyz`.

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`.