docs: fill out compat, lvglh, and toolchain documentation

Replace placeholder content in doc/compat/, doc/lvglh/, and
doc/toolchain/ with comprehensive documentation derived from the
source files.

- compat: document Wasuro WASM VM compatibility shims
- lvglh: document LVGL v9.2.2 configuration, fonts, and patches
- toolchain: document all 13 build pipeline scripts

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

doc/toolchain/compile_sourcelist.md

@@ -1 +1,32 @@
-# Placeholder
+# compile_sourcelist.sh
+
+Generates a list of all Pascal source files in the project.
+
+## Overview
+
+`compile_sourcelist.sh` scans the parent directory for all `.pas` files and writes their paths to `sources.list`. This file can be used by other tools or scripts that need a manifest of Pascal source files.
+
+## Prerequisites
+
+- `find` must be available.
+- Must be run from a subdirectory of the project root (it searches `..`).
+
+## Inputs
+
+The entire project directory tree (searched recursively for `*.pas` files).
+
+## Outputs
+
+| File | Description |
+|------|-------------|
+| `sources.list` | A newline-delimited list of absolute paths to all `.pas` files found. |
+
+## Behavior
+
+1. Uses `find` to locate all files matching `*.pas` in the parent directory.
+2. Writes the results to `sources.list` in the current working directory.
+3. Exits with code 0.
+
+## Notes
+
+- This script is not currently listed in the `compile.sh` build pipeline steps. It may be used as a standalone utility or by external tooling.

doc/toolchain/compile_sources.md

@@ -1 +1,55 @@
-# Placeholder
+# compile_sources.sh
+
+Compiles the Asuro kernel Pascal sources with Free Pascal.
+
+## Overview
+
+`compile_sources.sh` invokes the Free Pascal Compiler (FPC) to compile the main kernel unit (`src/asuro.pas`) along with all dependent units. It dynamically discovers every subdirectory under `src/`, `wasuro/`, and `compat/` and passes them as unit search paths (`-Fu`) so that FPC can resolve all unit references.
+
+## Prerequisites
+
+- `fpc` (Free Pascal Compiler 3.2.2 or compatible) must be available.
+- `find` must be available.
+- The `src/`, `wasuro/`, and `compat/` directories must be populated with their respective Pascal sources.
+- The `lib/` output directory must exist.
+
+## Inputs
+
+| Source | Description |
+|--------|-------------|
+| `src/asuro.pas` | The top-level kernel program unit. |
+| `src/**/*.pas` | All kernel Pascal source units. |
+| `wasuro/**/*.pas` | Wasuro WASM runtime units (pulled by `compile_wasuro.sh`). |
+| `compat/**/*.pas` | Compatibility layer units. |
+
+## Outputs
+
+| File | Description |
+|------|-------------|
+| `lib/*.o` | ELF object files for each compiled unit. |
+| `lib/*.ppu` | FPC precompiled unit files. |
+
+## Behavior
+
+1. Discovers all subdirectories under `src/`, `wasuro/`, and `compat/` using `find`.
+2. Builds a `-Fu` flag string containing every discovered directory.
+3. Invokes `fpc` with the following key flags:
+   - `-Aelf` -- Output ELF-format assembly.
+   - `-gw -g -gl` -- Generate DWARF debug info and line info.
+   - `-n` -- Ignore `fpc.cfg`; do not load default configuration.
+   - `-v0e` -- Verbosity: errors only.
+   - `-O3` -- Aggressive optimization.
+   - `-OpPENTIUM3` -- Optimize for Pentium III instruction scheduling.
+   - `-Si -Sc -Sg` -- Enable inline, C-style operators, and goto support.
+   - `-Xd` -- Do not search default library path.
+   - `-CX -XXs` -- Create smartlinkable units and strip unused code.
+   - `-CfSSE -CfSSE2` -- Use SSE/SSE2 floating-point.
+   - `-Rintel` -- Use Intel assembler syntax.
+   - `-Pi386 -Tlinux` -- Target i386 Linux (ELF).
+   - `-FElib/` -- Output compiled files to `lib/`.
+
+## Notes
+
+- The `-n` flag is critical: it prevents FPC from loading any system-wide configuration that might introduce incompatible settings for the bare-metal target.
+- The `-Xd` flag ensures FPC does not try to link against system libraries, since the kernel is freestanding.
+- Object files produced here are later consumed by `compile_link.sh`.

doc/toolchain/compile_stub.md

@@ -1 +1,37 @@
-# Placeholder
+# compile_stub.sh
+
+Assembles the low-level boot stub and splash screen objects.
+
+## Overview
+
+`compile_stub.sh` uses NASM to assemble two assembly source files into ELF object files. These objects contain the initial boot entry point and an embedded splash-screen TGA image, both of which are linked into the final kernel binary.
+
+## Prerequisites
+
+- `nasm` must be available on the PATH.
+- The source files `src/arch/x86/boot/stub.asm` and `src/boot/splash_tga.asm` must exist.
+- The `lib/` output directory must exist (created by `compile.sh` which clears it beforehand).
+
+## Inputs
+
+| File | Description |
+|------|-------------|
+| `src/arch/x86/boot/stub.asm` | x86 boot stub -- the kernel entry point before Pascal code takes over. |
+| `src/boot/splash_tga.asm` | Embeds a TGA splash screen image as a binary blob. |
+
+## Outputs
+
+| File | Description |
+|------|-------------|
+| `lib/stub.o` | ELF object for the boot stub. |
+| `lib/splash_tga.o` | ELF object for the splash screen data. |
+
+## Behavior
+
+1. Assembles `stub.asm` into `lib/stub.o` using NASM with the ELF output format (`-f elf`).
+2. Assembles `splash_tga.asm` into `lib/splash_tga.o` using the same format.
+
+## Notes
+
+- Both files are assembled as 32-bit ELF objects, consistent with the i386 target architecture.
+- `stub.o` is treated specially during linking: `compile_link.sh` places it first in the link order so that the boot entry point appears at the expected address.

doc/toolchain/compile_sumgen.md

@@ -1 +1,35 @@
-# Placeholder
+# compile_sumgen.sh
+
+Generates an MD5 checksum badge for the final ISO image.
+
+## Overview
+
+`compile_sumgen.sh` computes the MD5 hash of `Asuro.iso` and downloads a shields.io SVG badge displaying the checksum. This badge is stored in the `release/` directory for use in project documentation and release pages.
+
+## Prerequisites
+
+- `md5sum`, `awk`, and `wget` must be available.
+- `Asuro.iso` must exist in the current directory (produced by `compile_isogen.sh`).
+- The `release/` directory must exist.
+
+## Inputs
+
+| Source | Description |
+|--------|-------------|
+| `Asuro.iso` | The final bootable ISO image. |
+
+## Outputs
+
+| File | Description |
+|------|-------------|
+| `release/checksum.svg` | Shields.io badge displaying the ISO's MD5 checksum. |
+
+## Behavior
+
+1. Computes the MD5 checksum of `Asuro.iso` using `md5sum`.
+2. Downloads a shields.io badge SVG with the checksum value and saves it to `release/checksum.svg`.
+
+## Notes
+
+- This script is not currently listed in the `compile.sh` pipeline. It may be invoked separately or have been superseded by badge generation in `compile_vergen.sh`.
+- The `wget` call is silenced (`-q`) and its stderr is redirected to `/dev/null`, so download failures are silent.

doc/toolchain/compile_vergen.md

@@ -1 +1,53 @@
-# Placeholder
+# compile_vergen.sh
+
+Generates compile-time version constants and release badges.
+
+## Overview
+
+`compile_vergen.sh` extracts version metadata from Git tags (using semantic versioning), gathers build statistics (line counts, file counts, tool versions), and writes them into a Pascal unit (`core.version.pas`). It also downloads shields.io SVG badges summarizing the release information.
+
+## Prerequisites
+
+- `git`, `wget`, `fpc`, `make`, `nasm`, `awk`, `find`, `md5sum`, and `date` must be available.
+- The repository must have at least one semver-compatible Git tag reachable from HEAD.
+- `compile_checksum.sh` must be present in the toolchain directory (called to generate `checksums.md5` first).
+- `loc.sh` must be present in the toolchain directory.
+- The `bin/`, `release/`, and `src/core/` directories must exist.
+
+## Inputs
+
+| Source | Description |
+|--------|-------------|
+| Git tags | Parsed via `git describe --tags` to extract semver components. |
+| `checksums.md5` | Generated by `compile_checksum.sh`; its own MD5 is used as a build fingerprint. |
+| Source tree (`src/`) | Scanned to count total files and driver files. |
+| Tool versions | Queried from `fpc -h`, `make -v`, and `nasm -v`. |
+
+## Outputs
+
+| File | Description |
+|------|-------------|
+| `src/core/core.version.pas` | Pascal unit exposing version constants to the kernel at compile time. |
+| `release/*.svg` | Shields.io badges for version, revision, release, line count, file count, driver count, tool versions, date, and fingerprint. |
+
+## Behavior
+
+1. Runs `compile_checksum.sh` to produce `checksums.md5`.
+2. Downloads the `semver` shell tool from GitHub into `bin/` and adds it to `PATH`.
+3. Extracts the following from `git describe --tags`:
+   - Major, minor, and patch version numbers.
+   - Pre-release label (if any).
+   - Build metadata.
+   - Short commit revision (8 characters).
+4. Counts total lines of Pascal source (via `loc.sh`), total source files, and driver-specific files.
+5. Queries the installed versions of FPC, Make, and NASM.
+6. Records the current date and time.
+7. Computes an MD5 fingerprint of `checksums.md5`.
+8. Writes all values into `src/core/core.version.pas` as Pascal `const` declarations.
+9. Downloads SVG badges from shields.io into `release/` for each metric. Badge download failures are non-fatal (`set +e`).
+
+## Notes
+
+- The `set -e` at the top causes the script to abort on any error during the critical version-extraction phase. It is relaxed (`set +e`) before badge downloads, since those are cosmetic and may fail in offline or branch builds.
+- If a pre-release label is present in the tag, it is appended to the version string (e.g., `1.0.0-alpha`).
+- The generated `core.version.pas` is compiled into the kernel by `compile_sources.sh`, making all version metadata available at runtime.

doc/toolchain/compile_wasuro.md

@@ -1 +1,38 @@
-# Placeholder
+# compile_wasuro.sh
+
+Pulls the Wasuro WASM runtime Pascal sources into the build tree.
+
+## Overview
+
+`compile_wasuro.sh` fetches the Wasuro WebAssembly runtime from its Git repository using a sparse checkout (only the `src/wasm` subtree) and copies the Pascal source files into the local `wasuro/` directory. This makes the Wasuro units available to the FPC compiler via `-Fu` include paths during `compile_sources.sh`.
+
+## Prerequisites
+
+- `git` must be available and able to reach `https://gitea.spexeah.com/Spexeah/Wasuro.git`.
+- The `find` and `cp` utilities must be available.
+
+## Inputs
+
+| Source | Description |
+|--------|-------------|
+| Wasuro Git repository | Cloned (sparse, depth 1) from the `develop` branch. |
+
+## Outputs
+
+| File | Description |
+|------|-------------|
+| `wasuro/*.pas` | Pascal source files for the WASM runtime, ready for inclusion in the FPC build. |
+
+## Behavior
+
+1. **Cache check**: If `.pas` files already exist in `wasuro/`, the script prints a message and exits immediately, skipping the network fetch.
+2. **Sparse clone**: Clones the Wasuro repository into `/tmp/wasuro` with `--depth 1`, `--filter=blob:none`, and `--sparse`, then sets the sparse-checkout to `src/wasm`.
+3. **Copy**: Copies the contents of the cloned `src/wasm/` directory into `wasuro/`.
+4. **Cleanup**: Removes the temporary clone from `/tmp`.
+5. Reports the number of Pascal files copied.
+
+## Notes
+
+- The sparse checkout minimizes download size by fetching only the `src/wasm` subtree.
+- Once `wasuro/` is populated, subsequent builds reuse the cached files without re-cloning. To force a fresh pull, delete the `wasuro/` directory.
+- The script uses `set -e`, so any failure (network error, git error) aborts the build.

doc/toolchain/loc.md

@@ -1 +1,30 @@
-# Placeholder
+# loc.sh
+
+Counts the total lines of Pascal source code in the project.
+
+## Overview
+
+`loc.sh` is a utility script that counts the total number of lines across all `.pas` files in the project. It is called by `compile_vergen.sh` to embed a line count into the kernel's version metadata.
+
+## Prerequisites
+
+- `find`, `xargs`, `wc`, and `awk` must be available.
+
+## Inputs
+
+All `*.pas` files found recursively from the current working directory.
+
+## Outputs
+
+Prints a single line to stdout containing the total line count (e.g., `42567`).
+
+## Behavior
+
+1. Uses `find` to locate all `.pas` files starting from the current directory.
+2. Pipes the file list to `xargs wc -l` to count lines in each file.
+3. Uses `awk` to extract the grand total from the last line of `wc` output.
+
+## Notes
+
+- The output is consumed by `compile_vergen.sh` via command substitution and piped through `awk` to extract just the numeric value.
+- This script produces no files; it only writes to stdout.