feat(filebrowser): add delete button to toolbar, fix FAT32 delete/rename with raw sector scanning

- Add SYM_TRASH toolbar button wired to fb_delete_cb (was missing entirely)
- Filter '.' and '..' entries in fb_collect_cb so they never appear
- Rewrite deleteFile/deleteDir/renameFile to use raw sector scanning
  instead of getDirEntries linked-list indices (fixes  gap mismatch)
- Handle root directory correctly (use bootRecord^.rootCluster instead
  of assuming entry 0 is '.')

Dockerfile

@@ -6,7 +6,7 @@ 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 \
-	python3 python3-pip && \
+	python3 python3-pip python3-pil && \
 	apt-get clean my room
 
 RUN pip3 install --no-cache-dir --break-system-packages "mkdocs>=1.6,<2" mkdocs-material

doc/compat/lmemorymanager.md

@@ -1 +1,94 @@
-# Placeholder
+# lmemorymanager
+
+Compatibility shim that re-exports the `memory.heap` API under the legacy unit name.
+
+## Overview
+
+The Wasuro WASM VM project references the old unit name `lmemorymanager` for heap memory operations. Because the Wasuro source tree cannot be modified, this shim unit re-exports every public symbol from `memory.heap` so that `uses lmemorymanager` continues to compile without changes. All functions are thin inline wrappers that delegate directly to their `memory.heap` counterparts.
+
+## Dependencies
+
+- `memory.heap` -- the canonical heap allocator implementation in the Asuro kernel.
+
+## Constants
+
+### ALLOC_UNIT
+Re-exported from `memory.heap.ALLOC_UNIT`. The base allocation unit size used by the heap allocator.
+
+### DATA_OFFSET
+Re-exported from `memory.heap.DATA_OFFSET`. Byte offset from a heap block header to the start of user data.
+
+### PAGE_SIZE_LMM
+Re-exported from `memory.heap.PAGE_SIZE_LMM`. Page size used by the lightweight memory manager.
+
+### TOTAL_UNITS
+Re-exported from `memory.heap.TOTAL_UNITS`. Total number of allocation units per heap page.
+
+### BITMAP_DWORDS
+Re-exported from `memory.heap.BITMAP_DWORDS`. Number of 32-bit words in the per-page allocation bitmap.
+
+### SIZE_PREFIX
+Re-exported from `memory.heap.SIZE_PREFIX`. Size of the prefix stored before each allocation to record its length.
+
+### LARGE_ALLOC_MAGIC
+Re-exported from `memory.heap.LARGE_ALLOC_MAGIC`. Magic value used to identify large (multi-page) allocations.
+
+## Types
+
+### PHeapPageHeader / THeapPageHeader
+Re-exported from `memory.heap`. Pointer and record types describing the header structure at the beginning of each heap page.
+
+## Functions and Procedures
+
+### init
+```pascal
+procedure init;
+```
+Initializes the heap memory manager by delegating to `memory.heap.init`.
+
+### kalloc
+```pascal
+function kalloc(size: uint32): void;
+```
+Allocates `size` bytes from the kernel heap and returns a pointer to the allocated memory.
+
+### klalloc
+```pascal
+function klalloc(size: uint32): void;
+```
+Performs a large kernel allocation of `size` bytes and returns a pointer to the allocated memory.
+
+### klfree
+```pascal
+procedure klfree(address: uint32);
+```
+Frees a large allocation previously obtained via `klalloc`.
+
+### kpalloc
+```pascal
+function kpalloc(address: uint32): void;
+```
+Allocates a heap page at the specified address and returns a pointer to it.
+
+### kfree
+```pascal
+procedure kfree(area: void);
+```
+Frees a standard allocation previously obtained via `kalloc`.
+
+### lmm_total_free
+```pascal
+function lmm_total_free: uint32;
+```
+Returns the total number of free bytes available across all heap pages.
+
+### lmm_page_count
+```pascal
+function lmm_page_count: uint32;
+```
+Returns the current number of heap pages managed by the allocator.
+
+## Notes
+
+- Every function and procedure in the implementation section is marked `inline`, so the compiler eliminates the wrapper overhead entirely.
+- This unit exists solely for backward compatibility with the Wasuro WASM VM build. New kernel code should use `memory.heap` directly.

doc/compat/types.md

@@ -1 +1,16 @@
-# Placeholder
+# types
+
+Empty compatibility shim that satisfies `uses types` references from the Wasuro WASM VM project.
+
+## Overview
+
+Some units in the Wasuro WASM VM source tree include `uses types` to pull in shared type definitions from the Asuro kernel. In the kernel proper, those types may be declared elsewhere or may no longer be needed in the WASM context. This stub unit provides an empty `types` compilation unit so that `uses types` resolves without error during the Wasuro build.
+
+## Dependencies
+
+None.
+
+## Notes
+
+- The unit declares no constants, types, variables, or routines. Its only purpose is to exist as a valid compilation unit.
+- If Wasuro code is ever updated to remove the `uses types` dependency, this shim can be deleted.

doc/lvglh/hack_14.md

@@ -1 +1,53 @@
-# Placeholder
+# hack_14.c
+
+LVGL bitmap font source for the Hack Regular typeface at 14 px.
+
+## Overview
+
+This file contains a pre-rendered bitmap font generated from the Hack Regular TrueType font (`Hack-Regular.ttf`) for use with LVGL. It provides a complete monospaced programmer font covering the full Basic Multilingual Plane (Unicode range 0x0000--0xFFFF). The font is intended for use in terminal emulators, code editors, or any UI element within Asuro that benefits from a fixed-width typeface.
+
+The file was generated by the LVGL font converter tool and is approximately 12,900 lines (~548 KB) of static bitmap and glyph descriptor data.
+
+## Configuration Options / Defines
+
+### HACK_14
+Value: `1` (default). Acts as a compile-time guard. Set to `0` to exclude this font from the build entirely.
+
+## Font Properties
+
+| Property | Value |
+|----------|-------|
+| Font family | Hack Regular |
+| Size | 14 px |
+| Bits per pixel | 4 (16-level anti-aliasing) |
+| Compression | None (`--no-compress`) |
+| Stride alignment | 1 byte |
+| Data alignment | 1 byte |
+| Line height | 19 px |
+| Baseline | 5 px from bottom |
+| Underline position | -2 |
+| Underline thickness | 1 |
+| Unicode range | 0x0000--0xFFFF |
+| Subpixel rendering | None |
+
+## Public Symbol
+
+```c
+const lv_font_t hack_14;
+```
+
+This is the font descriptor exposed for use in LVGL widget styles. Reference it as `&hack_14` when assigning fonts to labels, text areas, or other text-bearing widgets.
+
+## Generation Command
+
+```
+--bpp 4 --size 14 --no-compress --stride 1 --align 1 \
+--font Hack-Regular.ttf --range 0-65535 --format lvgl -o hack_14.c
+```
+
+## Notes
+
+- This is a machine-generated file. Do not edit by hand; regenerate using the LVGL font converter if changes are needed.
+- The full 0--65535 Unicode range makes this a large file. If binary size is a concern, the range could be narrowed to only the code points actually used.
+- The font includes version-conditional compilation guards for compatibility across LVGL 6.x through 9.x, though Asuro targets LVGL 9.2.2.
+- The `LV_ATTRIBUTE_LARGE_CONST` annotation on the glyph bitmap array allows the linker to place it in an appropriate read-only section.

doc/lvglh/lv_conf.md

@@ -1 +1,133 @@
-# Placeholder
+# lv_conf.h
+
+LVGL v9.2.2 configuration header tailored for the Asuro bare-metal kernel environment.
+
+## Overview
+
+This file configures the LVGL graphics library for use inside the Asuro kernel, where no standard C library, operating system, or GPU hardware is available. It selects a 32-bit XRGB8888 color depth to match the VESA framebuffer, routes all stdlib functionality through LVGL's built-in implementations, enables only the software renderer, and disables every hardware backend, filesystem driver, and image decoder. The result is a minimal but functional GUI stack that runs entirely in kernel space.
+
+## Configuration Options / Defines
+
+### Color Settings
+
+#### LV_COLOR_DEPTH
+Value: `32`. Matches the VESA XRGB8888 framebuffer used by Asuro.
+
+### Standard Library Wrappers
+
+#### LV_USE_STDLIB_MALLOC / LV_USE_STDLIB_STRING / LV_USE_STDLIB_SPRINTF
+Value: `LV_STDLIB_BUILTIN`. All three are set to use LVGL's own built-in implementations since no libc is available in the bare-metal environment.
+
+### Memory Pool
+
+#### LV_MEM_SIZE
+Value: `256 * 1024U` (256 KB). Size of LVGL's internal memory pool for widget allocations and draw buffers.
+
+#### LV_MEM_POOL_EXPAND_SIZE
+Value: `0`. Pool expansion is disabled; the 256 KB allocation is fixed.
+
+#### LV_MEM_ADR
+Value: `0`. LVGL allocates the pool itself rather than using a fixed address.
+
+### HAL Settings
+
+#### LV_DEF_REFR_PERIOD
+Value: `33` (milliseconds). Targets approximately 30 frames per second.
+
+#### LV_DPI_DEF
+Value: `96`. Standard screen DPI assumption.
+
+### Operating System
+
+#### LV_USE_OS
+Value: `LV_OS_NONE`. No OS abstraction layer; LVGL runs in a bare-metal cooperative model.
+
+### Rendering Configuration
+
+#### LV_USE_DRAW_SW
+Value: `1`. The software renderer is the sole rendering backend.
+
+Only the color formats actually used are enabled within the software renderer:
+
+| Define | Value | Description |
+|--------|-------|-------------|
+| `LV_DRAW_SW_SUPPORT_XRGB8888` | 1 | Primary framebuffer format |
+| `LV_DRAW_SW_SUPPORT_ARGB8888` | 1 | Alpha-blended surfaces |
+| `LV_DRAW_SW_SUPPORT_RGB888` | 1 | 24-bit fallback |
+| `LV_DRAW_SW_SUPPORT_RGB565` | 0 | Disabled |
+| All other formats | 0 | Disabled |
+
+#### LV_DRAW_SW_COMPLEX
+Value: `1`. Enables complex draw operations (shadows, rounded corners). Shadow cache is disabled (`LV_DRAW_SW_SHADOW_CACHE_SIZE = 0`); circle cache is set to 4 entries.
+
+#### LV_DRAW_LAYER_SIMPLE_BUF_SIZE
+Value: `24 * 1024` (24 KB). Buffer for simple layer rendering.
+
+#### GPU Backends
+All GPU-accelerated backends are disabled: VGLite, PXP, Dave2D, SDL, VG-Lite.
+
+### Logging
+
+#### LV_USE_LOG
+Value: `1`. Logging is enabled at `LV_LOG_LEVEL_WARN`. Printf-based logging, timestamps, and file/line info are all disabled to reduce overhead. All trace categories (memory, timer, indev, display refresh, events, object creation, layout, animation, cache) are disabled.
+
+### Assertions
+
+#### LV_USE_ASSERT_NULL / LV_USE_ASSERT_MALLOC
+Value: `1`. Null-pointer and malloc-failure assertions are active.
+
+#### LV_ASSERT_HANDLER
+Value: `{}` (no-op). The assert handler intentionally does nothing to avoid hanging the kernel on a failed assertion.
+
+### Fonts
+
+#### LV_FONT_MONTSERRAT_14
+Value: `1`. The only built-in Montserrat size enabled.
+
+#### LV_FONT_DEFAULT
+Value: `&lv_font_montserrat_14`. All other Montserrat sizes (8--48), compressed variants, and alternative font families (DejaVu, SimSun, UNSCII) are disabled.
+
+### Text Settings
+
+#### LV_TXT_ENC
+Value: `LV_TXT_ENC_UTF8`. UTF-8 text encoding. BiDi and Arabic/Persian character support are disabled.
+
+### Widgets
+
+Enabled widgets: AnimImg, Arc, Bar, Button, ButtonMatrix, Checkbox, Dropdown, Image, Keyboard, Label, Line, List, MsgBox, Roller, Slider, Spinner, Switch, TextArea, Table, TabView, Win.
+
+Disabled widgets: Calendar, Canvas, Chart, ImageButton, LED, Lottie, Menu, Scale, Span, SpinBox, TileView.
+
+### Themes
+
+#### LV_USE_THEME_DEFAULT
+Value: `1`. Dark mode enabled (`LV_THEME_DEFAULT_DARK = 1`) with 80 ms transition time.
+
+#### LV_USE_THEME_SIMPLE
+Value: `1`.
+
+#### LV_USE_THEME_MONO
+Value: `0`.
+
+### Layouts
+
+Both Flex and Grid layout engines are enabled.
+
+### Third-Party Libraries
+
+All filesystem drivers are disabled (stdio, POSIX, Win32, FatFS, MemFS, LittleFS). All image decoders are disabled (PNG, BMP, JPEG, GIF, RLE). FreeType, TinyTTF, Rlottie, vector graphics, LZ4, and FFmpeg are all disabled.
+
+### Device Drivers
+
+All platform-specific device drivers are disabled (SDL, X11, Wayland, Linux FBDEV, Linux DRM, NuttX, various SPI display controllers, Windows, OpenGLES, QNX). Display and input are handled by Asuro's own HAL layer.
+
+### Examples and Demos
+
+All built-in examples and demo applications are disabled.
+
+## Notes
+
+- The configuration is designed for minimal footprint. Features are enabled only when required by the Asuro desktop shell.
+- Since no libc is linked, all string, memory, and formatting operations fall through to LVGL's internal implementations.
+- The assert handler is a deliberate no-op to prevent the kernel from halting on non-critical UI assertion failures.
+- The 256 KB memory pool is fixed and cannot expand at runtime. UI complexity must stay within this budget.

doc/lvglh/lv_font_fa_solid_16.md

@@ -1 +1,55 @@
-# Placeholder
+# lv_font_fa_solid_16.c
+
+LVGL bitmap font source for Font Awesome 7 Free Solid at 16 px.
+
+## Overview
+
+This file contains a pre-rendered bitmap font generated from the Font Awesome 7 Free Solid TrueType font (`Font Awesome 7 Free-Solid-900.ttf`) for use with LVGL. It provides a library of solid-style vector icons rendered as bitmaps, suitable for toolbar buttons, status indicators, navigation elements, and general iconography in the Asuro GUI.
+
+The file was generated by the LVGL font converter tool and is approximately 35,800 lines (~1.6 MB) of static bitmap and glyph descriptor data.
+
+## Configuration Options / Defines
+
+### LV_FONT_FA_SOLID_16
+Value: `1` (default). Acts as a compile-time guard. Set to `0` to exclude this font from the build entirely.
+
+## Font Properties
+
+| Property | Value |
+|----------|-------|
+| Font family | Font Awesome 7 Free Solid 900 |
+| Size | 16 px |
+| Bits per pixel | 4 (16-level anti-aliasing) |
+| Compression | None (`--no-compress`) |
+| Stride alignment | 1 byte |
+| Data alignment | 1 byte |
+| Line height | 20 px |
+| Baseline | 4 px from bottom |
+| Underline position | 0 |
+| Underline thickness | 0 |
+| Unicode range | 0x0000--0xFFFF |
+| Subpixel rendering | None |
+
+## Public Symbol
+
+```c
+const lv_font_t lv_font_fa_solid_16;
+```
+
+This is the font descriptor exposed for use in LVGL widget styles. Reference it as `&lv_font_fa_solid_16` when assigning icon fonts to labels or buttons. Font Awesome icons are addressed by their Unicode code points (e.g., `LV_SYMBOL_*` constants or raw `\uXXXX` escape sequences).
+
+## Generation Command
+
+```
+--bpp 4 --size 16 --no-compress --stride 1 --align 1 \
+--font "Font Awesome 7 Free-Solid-900.ttf" --range 0-65535 --format lvgl \
+-o lv_font_fa_solid_16.c
+```
+
+## Notes
+
+- This is a machine-generated file. Do not edit by hand; regenerate using the LVGL font converter if changes are needed.
+- The full 0--65535 Unicode range includes all Font Awesome solid icons. Since most code points in this range are blank (Font Awesome only defines glyphs for its icon set), the actual rendered glyph count is much smaller than the range suggests, but the descriptor tables still consume significant space.
+- The file is the largest in the `lvglh/` directory at approximately 1.6 MB. If binary size becomes a constraint, the Unicode range should be narrowed to only the icon code points actually used by the Asuro shell.
+- The font includes version-conditional compilation guards for compatibility across LVGL 6.x through 9.x, though Asuro targets LVGL 9.2.2.
+- The `LV_ATTRIBUTE_LARGE_CONST` annotation on the glyph bitmap array allows the linker to place it in an appropriate read-only section.

doc/src/core/core.panic.md

@@ -4,7 +4,9 @@ Architecture-agnostic kernel panic (BSOD) engine.
 
 ## Overview
 
-`core.panic` implements a graphical and serial kernel panic handler for the Asuro kernel. When a fatal condition is detected anywhere in the kernel, `panic` is called with a fault identifier, a human-readable description, and an optional CPU register snapshot. The unit outputs the fault information to the serial syslog for headless debugging and, if LVGL has been initialised, displays a graphical Blue Screen of Death (BSOD).
+`core.panic` implements a graphical and serial kernel panic handler for the Asuro kernel. When a fatal condition is detected anywhere in the kernel, `panic` is called with a fault identifier, a human-readable description, and an optional CPU register snapshot. All diagnostic sections (Fault Info, CPU Registers, Process Info, System Info, Call Stack) are mirrored to the serial syslog for headless debugging. If LVGL has been initialised, a graphical Blue Screen of Death (BSOD) is displayed.
+
+If the panic occurs inside the `gfxd` graphics-rendering process, LVGL state may be corrupt. In this case the unit falls back to rendering the panic screen directly to the VESA framebuffer using `driver.video.DrawString`, `driver.video.DrawHex`, and `driver.video.DrawInt`, bypassing LVGL entirely.
 
 The BSOD screen and all its LVGL widgets are pre-allocated at `init` time so that no dynamic LVGL allocation is needed when a panic fires. At panic time only label text is updated via `lv_label_set_text`, the pre-built screen is loaded, and a single render pass is forced. Text formatting uses static heap buffers and avoids calling any string library routines that might themselves fault.
 
@@ -16,7 +18,7 @@ If `init` has not been called before a panic (early boot panic), the unit gracef
 
 - `io.syslog` — serial fault output
 - `debug.tracer` — call-stack capture and freeze
-- `driver.video` — frame buffer flush
+- `driver.video` — frame buffer flush and text drawing (DrawString, DrawHex, DrawInt) for VESA fallback
 - `memory.heap` — buffer allocation
 - `driver.video.lvgl` — LVGL widget creation and rendering
 - `core.version` — version constants for the system info panel
@@ -24,6 +26,8 @@ If `init` has not been called before a panic (early boot panic), the unit gracef
 - `proc.types` — process state enumeration
 - `core.fmt.targa` — teapot TGA image decoding
 - `core.gfx.texture` — pixel buffer type
+- `core.strings` — string comparison for gfxd process detection
+- `core.gfx.color` — TRGB32 colour type for direct pixel drawing
 
 ## Constants
 
@@ -71,7 +75,7 @@ Creates the hidden BSOD LVGL screen and pre-allocates all widget objects and tex
 ```pascal
 procedure panic(fault : pchar; info : pchar; regs : PRegisterSnapshot);
 ```
-Triggers a kernel panic. Freezes the call-stack tracer, dumps fault information to syslog, and (if the BSOD screen is ready) displays the graphical panic screen. Then calls the registered halt procedure. Re-entrant calls are detected by a guard flag; if `panic` is called while a panic is already in progress, the system halts immediately without further output.
+Triggers a kernel panic. Freezes the call-stack tracer, dumps all diagnostic sections (Fault Info, CPU Registers, Process Info, System Info, Call Stack) to syslog, and displays the graphical panic screen. If the crash occurred in the `gfxd` process, LVGL is bypassed and the screen is rendered directly to the VESA framebuffer. Otherwise, if the LVGL BSOD screen is ready, it is used. Then calls the registered halt procedure. Re-entrant calls are detected by a guard flag; if `panic` is called while a panic is already in progress, the system halts immediately without further output.
 
 Parameters:
 - `fault` — short fault identifier string, e.g. `'arch.x86.fault.gpf'`.
@@ -93,3 +97,17 @@ The teapot image is loaded from a TGA binary linked into the kernel image via an
 All text formatting in the panic path uses a set of internal buffer-writing helpers (`writeHexToBuffer`, `writeStrToBuffer`, `writeIntToBuffer`) that do not call the kernel string library, making the panic path robust against faults in those subsystems.
 
 A compile-time switch `BSOD_ENABLE` gates the display path; if disabled, `panic` only writes to syslog and halts.
+
+### gfxd Crash Detection
+
+When `panic` is triggered, it checks whether the currently executing process is `gfxd` (the graphics daemon). If so, LVGL’s internal state may be corrupt (since `gfxd` drives the LVGL render pipeline), so the unit falls back to `showVESAFallbackScreen`. This procedure fills the screen with the BSOD background colour and renders all diagnostic sections using `driver.video.DrawString`, `driver.video.DrawHex`, and `driver.video.DrawInt` (which draw 8×16 bitmap font glyphs via `DrawPixel`). The layout mirrors the LVGL BSOD but uses a simpler single-column text format.
+
+### Syslog Output
+
+All five diagnostic sections are written to syslog in every panic, regardless of the display path:
+
+1. **Fault Info** — fault identifier and human-readable description
+2. **CPU Registers** — name/value pairs from the register snapshot
+3. **Process Info** — name, PID, parent PID, state, and priority of the current process
+4. **System Info** — kernel version, build date, compiler, revision, heap status, process count, uptime
+5. **Call Stack** — frozen tracer output

doc/src/core/core.strings.md

@@ -106,6 +106,12 @@ function intToString(i : uint32) : pchar;
 ```
 Returns a heap-allocated decimal string representation of `i`.
 
+### int64ToString
+```pascal
+function int64ToString(i : int64) : pchar;
+```
+Returns a heap-allocated decimal string representation of the signed 64-bit integer `i`. Negative values are prefixed with `'-'`.
+
 ### hexStringToInt
 ```pascal
 function hexStringToInt(str : pchar) : uint32;
@@ -118,6 +124,12 @@ function boolToString(b : boolean; ext : boolean) : pchar;
 ```
 Returns a heap-allocated string for the boolean `b`. When `ext` is `true`, returns `'true'` or `'false'`; when `false`, returns `'1'` or `'0'`.
 
+### doubleToStr
+```pascal
+function doubleToStr(d : Double) : pchar;
+```
+Returns a heap-allocated decimal string representation of the 64-bit floating-point value `d`. Integer values are emitted without a decimal point (e.g. `42`). Fractional values include up to 15 significant digits with trailing zeros removed. Very large or very small values use scientific notation (e.g. `1.5e+20`).
+
 ### UnitTest
 ```pascal
 procedure UnitTest;

doc/src/driver/video/driver.video.md

@@ -13,6 +13,7 @@ This unit is the central video interface for the Asuro kernel. It holds a single
 - `driver.video.gpu`
 - `driver.video.vesa32` (and other BPP variants)
 - `core.hashmap`
+- `core.gfx.fonts` — 8×16 bitmap font data for text drawing
 - `syslog`
 
 ## Functions and Procedures
@@ -69,6 +70,34 @@ function backBuffer: PVideoBuffer;
 ```
 Returns a pointer to `VideoInterface.BackBuffer`.
 
+## Text Drawing
+
+These functions render text directly to the framebuffer using the 8×16 bitmap font from `core.gfx.fonts`. They are useful for panic screens or other contexts where LVGL is unavailable. Each function returns the X coordinate immediately after the last drawn pixel, allowing calls to be chained for inline formatting.
+
+### DrawChar
+```pascal
+function DrawChar(X, Y : uint32; C : char; Color : TRGB32) : uint32;
+```
+Draws a single 8×16 bitmap glyph at `(X, Y)` in the given colour. Returns `X + 8`.
+
+### DrawString
+```pascal
+function DrawString(X, Y : uint32; Str : pchar; Color : TRGB32) : uint32;
+```
+Draws a null-terminated string starting at `(X, Y)`. Each character advances X by 8 pixels. Returns the X coordinate after the last character.
+
+### DrawHex
+```pascal
+function DrawHex(X, Y : uint32; Value : uint32; Color : TRGB32) : uint32;
+```
+Draws a `uint32` as a `0xHHHHHHHH` hex string at `(X, Y)`. Returns the X coordinate after the string.
+
+### DrawInt
+```pascal
+function DrawInt(X, Y : uint32; Value : uint32; Color : TRGB32) : uint32;
+```
+Draws an unsigned integer in decimal at `(X, Y)`. Returns the X coordinate after the last digit.
+
 ## Notes
 
 - All drawing operations target the back buffer (`DefaultBuffer`) when double buffering is active. `Flush` transfers the result to the front (visible) buffer.

doc/toolchain/compile.md

@@ -1 +1,44 @@
-# Placeholder
+# compile.sh
+
+Top-level build orchestrator for the Asuro kernel.
+
+## Overview
+
+`compile.sh` is the main entry point for building the Asuro operating system. It sequentially invokes each stage of the build pipeline, halting on the first failure. After all stages complete (or a failure occurs), it calls `compile_finish.sh` to generate a build-status badge and set the exit code.
+
+## Prerequisites
+
+- All sub-scripts must be present in the same directory as `compile.sh`.
+- The Docker build container must provide: `bash`, `nasm`, `fpc`, `gcc`, `ld`, `grub-mkrescue`, `git`, `wget`, and standard POSIX utilities.
+
+## Inputs
+
+None directly. Each sub-script reads its own inputs from the source tree.
+
+## Outputs
+
+- All artifacts produced by the sub-scripts (object files, kernel binary, ISO image, version info, badges, documentation).
+- Final exit code: `0` on success, `1` on failure.
+
+## Behavior
+
+1. Clears the `lib/` directory to ensure a clean build.
+2. Defines a helper function `runOrFail` that runs a command and increments `ERRCOUNT` on failure.
+3. Resolves its own directory (`TOOLCHAIN_DIR`) so sub-scripts can be located by absolute path.
+4. Declares an ordered list of build steps (script name and error message pairs):
+   - `compile_stub.sh` -- Assemble boot stubs.
+   - `compile_vergen.sh` -- Generate version information.
+   - `compile_lvgl.sh` -- Compile the LVGL graphics library.
+   - `compile_wasuro.sh` -- Pull the Wasuro WASM runtime sources.
+   - `compile_sources.sh` -- Compile Free Pascal kernel sources.
+   - `compile_link.sh` -- Link all object files into `kernel.bin`.
+   - `compile_isogen.sh` -- Create the bootable ISO image.
+   - `compile_docs.sh` -- Generate project documentation.
+5. Iterates through the steps. If `ERRCOUNT` is non-zero, all remaining steps are skipped.
+6. Calls `compile_finish.sh` with either `"success"` or `"failed"` depending on whether any errors were recorded.
+7. Changes directory back up one level (`cd ..`).
+
+## Notes
+
+- `compile_finish.sh` is sourced (`. script`) rather than executed as a sub-process, so its `exit` call terminates the entire pipeline.
+- The build is fail-fast: the first failing step prevents all subsequent steps from running, but the finish step always runs to produce a status badge.

doc/toolchain/compile_checksum.md

@@ -1 +1,38 @@
-# Placeholder
+# compile_checksum.sh
+
+Generates MD5 checksums for all Pascal source files.
+
+## Overview
+
+`compile_checksum.sh` iterates over every `.pas` file under `src/` and appends its MD5 hash to `checksums.md5`. This file serves as a source-level fingerprint used by `compile_vergen.sh` to produce a build integrity checksum.
+
+## Prerequisites
+
+- `md5sum` and `find` must be available.
+- The `src/` directory must exist and contain `.pas` files.
+
+## Inputs
+
+All `*.pas` files found recursively under `src/`, up to 10 levels deep.
+
+## Outputs
+
+| File | Description |
+|------|-------------|
+| `checksums.md5` | A file containing one `md5sum`-format line per Pascal source file. |
+
+## Behavior
+
+1. Truncates (or creates) `checksums.md5` with an empty write (`echo >`).
+2. Finds all directories under `src/` (up to 10 levels deep).
+3. For each directory, iterates over `*.pas` files and computes their MD5 checksum.
+4. Skips files matching any of the following conditions:
+   - Path contains `.svn` (Subversion metadata).
+   - The glob matched no files (literal `*.pas` string).
+   - Path contains `include/asuro.pas`.
+5. Appends each valid checksum line to `checksums.md5`.
+
+## Notes
+
+- The resulting `checksums.md5` is consumed by `compile_vergen.sh`, which hashes the checksum file itself to produce a single build fingerprint constant embedded in the kernel.
+- The `.svn` exclusion is a legacy filter from when the project used Subversion for version control.

doc/toolchain/compile_docs.md

@@ -18,20 +18,6 @@ Builds the static documentation website from the Markdown files in the `doc/` di
 3. Runs `mkdocs build --strict` to generate the static site.
 4. Output is written to the `site/` directory at the project root.
 
-## Docker Usage
-
-The documentation site can also be built and served via Docker Compose:
-
-```bash
-# Live development server with hot-reload
-docker compose up docs
-
-# Static build only
-docker compose run docs build --strict
-```
-
-The development server listens on `http://localhost:8000`.
-
 ## Configuration
 
 The site is configured by `mkdocs.yml` in the project root. The navigation structure mirrors the `doc/` directory hierarchy.

doc/toolchain/compile_finish.md

@@ -1 +1,40 @@
-# Placeholder
+# compile_finish.sh
+
+Reports build status and generates the build result badge.
+
+## Overview
+
+`compile_finish.sh` is the final step in the Asuro build pipeline. It is sourced (not executed) by `compile.sh` and receives a single argument indicating whether the build succeeded or failed. It downloads the appropriate shields.io badge and exits with the corresponding exit code.
+
+## Prerequisites
+
+- `wget` must be available (though badge download failure is non-fatal).
+- The `release/` directory must exist.
+
+## Inputs
+
+| Input | Description |
+|-------|-------------|
+| `$1` | A string argument: `"failed"` or `"success"`. Passed by `compile.sh`. |
+
+## Outputs
+
+| File | Description |
+|------|-------------|
+| `release/build.svg` | A shields.io badge: red "build-failed" or green "build-succeeded". |
+
+## Behavior
+
+1. If `$1` is `"failed"`:
+   - Prints an error message directing the user to review the log.
+   - Downloads a red "build-failed" badge to `release/build.svg`.
+   - Exits with code 1.
+2. Otherwise:
+   - Prints a success message.
+   - Downloads a green "build-succeeded" badge to `release/build.svg`.
+   - Exits with code 0.
+
+## Notes
+
+- This script is sourced (`. compile_finish.sh`) by `compile.sh`, meaning its `exit` call terminates the parent shell. This is intentional -- it sets the final exit code for the entire build pipeline.
+- Badge download is silent and non-blocking; if `wget` fails (e.g., no network), the build still reports the correct exit code.

doc/toolchain/compile_isogen.md

@@ -1 +1,37 @@
-# Placeholder
+# compile_isogen.sh
+
+Creates a bootable GRUB ISO image containing the Asuro kernel.
+
+## Overview
+
+`compile_isogen.sh` copies the compiled kernel binary into the ISO directory structure and invokes `grub-mkrescue` to produce a bootable CD-ROM image. The resulting `Asuro.iso` can be booted in any x86 emulator (QEMU, VirtualBox, etc.) or written to physical media.
+
+## Prerequisites
+
+- `grub-mkrescue` (from GRUB utilities) and `xorriso` (its backend) must be available.
+- `bin/kernel.bin` must exist (produced by `compile_link.sh`).
+- The `iso/boot/` directory must exist and contain a GRUB configuration file (`iso/boot/grub/grub.cfg`).
+
+## Inputs
+
+| Source | Description |
+|--------|-------------|
+| `bin/kernel.bin` | The linked kernel binary. |
+| `iso/` | Pre-existing ISO directory tree with GRUB configuration. |
+
+## Outputs
+
+| File | Description |
+|------|-------------|
+| `Asuro.iso` | Bootable GRUB rescue ISO image. |
+| `iso/boot/asuro.bin` | Copy of the kernel binary placed into the ISO tree. |
+
+## Behavior
+
+1. Copies `bin/kernel.bin` to `iso/boot/asuro.bin`.
+2. Runs `grub-mkrescue -o Asuro.iso iso` to generate the bootable ISO from the `iso/` directory tree.
+
+## Notes
+
+- The GRUB configuration in `iso/boot/grub/grub.cfg` must reference `asuro.bin` as the kernel to load.
+- The ISO is generated in the project root directory.

doc/toolchain/compile_link.md

@@ -1 +1,47 @@
-# Placeholder
+# compile_link.sh
+
+Links all object files and libraries into the final kernel binary.
+
+## Overview
+
+`compile_link.sh` collects every `.o` object file in `lib/`, locates `libgcc` for i386, and invokes the GNU linker (`ld`) to produce `bin/kernel.bin`. The linker script `toolchain/linker.script` controls the memory layout of the resulting binary.
+
+## Prerequisites
+
+- `ld` (GNU linker) and `gcc` must be available.
+- All object files must have been produced by prior build steps (`compile_stub.sh`, `compile_sources.sh`).
+- `lib/liblvgl.a` must exist (produced by `compile_lvgl.sh`).
+- `toolchain/linker.script` must exist.
+- The `bin/` output directory must exist.
+
+## Inputs
+
+| Source | Description |
+|--------|-------------|
+| `lib/*.o` | All ELF object files (boot stub, Pascal units, splash screen, etc.). |
+| `lib/liblvgl.a` | Static LVGL library archive. |
+| `libgcc` (system) | GCC runtime support library for i386, located via `gcc -m32 -print-libgcc-file-name`. |
+| `toolchain/linker.script` | Linker script defining section layout and entry point. |
+
+## Outputs
+
+| File | Description |
+|------|-------------|
+| `bin/kernel.bin` | The final linked, stripped kernel binary. |
+
+## Behavior
+
+1. Collects all `.o` files from `lib/`, excluding `lib/stub.o` from the general list.
+2. Prepends `lib/stub.o` to the front of the object list so the boot entry point is linked first.
+3. Locates `libgcc` for the 32-bit target using `gcc -m32 -print-libgcc-file-name`.
+4. Invokes `ld` with the following flags:
+   - `-m elf_i386` -- Target i386 ELF format.
+   - `-s` -- Strip all symbol information.
+   - `--gc-sections` -- Remove unused sections (works with FPC's `-CX -XXs` smart-linking).
+   - `-T toolchain/linker.script` -- Use the project linker script.
+   - `--start-group` / `--end-group` -- Wraps `liblvgl.a` and `libgcc` to resolve circular references between them.
+
+## Notes
+
+- `stub.o` must be first in the link order because it contains the multiboot header and the initial entry point that GRUB transfers control to.
+- The `--start-group` / `--end-group` construct allows the linker to iterate over `liblvgl.a` and `libgcc` multiple times to resolve all symbols, which is necessary when C library objects have mutual dependencies.

doc/toolchain/compile_lvgl.md

@@ -1 +1,51 @@
-# Placeholder
+# compile_lvgl.sh
+
+Downloads and compiles LVGL v9.2 into a static library for the kernel.
+
+## Overview
+
+`compile_lvgl.sh` clones the LVGL graphics library source, cross-compiles every C source file to 32-bit freestanding ELF objects, and archives them into `lib/liblvgl.a`. It also compiles any custom Asuro-specific LVGL extension files found in `lvglh/`. A caching mechanism on the host-mounted `/code/lvgl/` directory allows subsequent builds to skip the entire compilation.
+
+## Prerequisites
+
+- `git`, `gcc`, `ar`, and standard POSIX utilities must be available.
+- The `lvglh/` directory must contain an `lv_conf.h` configuration header (and optionally custom `.c` files).
+- The `lib/` output directory must exist.
+
+## Inputs
+
+| Source | Description |
+|--------|-------------|
+| LVGL Git repository | Cloned from `https://github.com/lvgl/lvgl.git` at tag `v9.2.2`. |
+| `lvglh/` | Project-local directory containing `lv_conf.h` and optional custom C source files. |
+| `/code/lvgl/liblvgl.a` | Optional cached artifact from a previous build (host mount). |
+
+## Outputs
+
+| File | Description |
+|------|-------------|
+| `lib/liblvgl.a` | Static archive containing all compiled LVGL and custom extension objects. |
+| `/code/lvgl/` | Cached copy of the static library, LVGL source, and object files for future builds. |
+
+## Behavior
+
+1. **Cache check**: If `/code/lvgl/liblvgl.a` exists, copies it to `lib/` and exits immediately.
+2. **Clone**: Shallow-clones the LVGL repository at the specified version tag into `/tmp/lvgl`.
+3. **Discover sources**: Finds all `.c` files under the LVGL `src/` directory, excluding test files.
+4. **Compile**: Compiles each source file with GCC using the following key flags:
+   - `-m32 -march=i686` -- 32-bit i686 target.
+   - `-ffreestanding -fno-builtin -fno-stack-protector -fno-pic -fno-pie` -- Bare-metal environment.
+   - `-O2` -- Optimization level 2.
+   - `-DLV_CONF_INCLUDE_SIMPLE` -- Tells LVGL to include `lv_conf.h` via a simple path.
+   - Include paths for `lvglh/` and the LVGL source tree.
+5. **Archive**: Collects all `.o` files into `lib/liblvgl.a` using `ar rcs`.
+6. **Custom extensions**: If `lvglh/` contains `.c` files, compiles them with the same flags and appends the resulting objects to `liblvgl.a`.
+7. **Cache write**: Copies the static library, source, and objects to `/code/lvgl/` on the host mount for future builds.
+
+Progress is reported every 50 files. The script aborts with exit code 1 if any compilation errors occur.
+
+## Notes
+
+- All intermediate work (clone, object files) happens in `/tmp` for speed on container-local filesystems.
+- The cache lives on the host mount at `/code/lvgl/`. Deleting `lvgl/liblvgl.a` from the project root forces a full rebuild.
+- The static library is linked into the kernel by `compile_link.sh` using `--start-group` / `--end-group` alongside `libgcc`.