From 4cc268683da1b943494cd40fa55e7d6af48a8129 Mon Sep 17 00:00:00 2001
From: Markus Maiwald <markus@maiwald.work>
Date: Tue, 30 Dec 2025 08:11:44 +0100
Subject: [PATCH] docs(rumpk): Add module READMEs per Panopticum doctrine

Added feature-colocated documentation for AI agent discoverability:
- core/README.md: L1 Nim logic overview
- hal/README.md: L0 Zig HAL overview, exported symbols
- boot/README.md: Linker scripts, memory layout

Panopticum Compliance: Each folder is now self-documenting.
---
 boot/README.md | 27 +++++++++++++++++++++++++++
 core/README.md | 38 ++++++++++++++++++++++++++++++++++++++
 hal/README.md  | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 111 insertions(+)
 create mode 100644 boot/README.md
 create mode 100644 core/README.md
 create mode 100644 hal/README.md

diff --git a/boot/README.md b/boot/README.md
new file mode 100644
index 0000000..da10e14
--- /dev/null
+++ b/boot/README.md
@@ -0,0 +1,27 @@
+# Rumpk Boot
+
+**Purpose:** Bootloader headers and linker scripts
+
+## Contents
+
+| File | Purpose |
+|------|---------|
+| `linker.ld` | Default linker script (ARM64 QEMU virt) |
+| `header.zig` | Multiboot2 header (future) |
+
+## Memory Layout (ARM64 QEMU virt)
+
+```
+0x40080000  _start (Entry Point)
+0x40080000  .text
+            .rodata
+            .data
+            .bss
+            Stack (16KB)
+```
+
+## Future
+
+- `linker-x86_64.ld` - x86_64 QEMU q35
+- `linker-riscv64.ld` - RISC-V QEMU virt
+- EFI stub for real hardware
diff --git a/core/README.md b/core/README.md
new file mode 100644
index 0000000..eb4b761
--- /dev/null
+++ b/core/README.md
@@ -0,0 +1,38 @@
+# Rumpk Core (L1)
+
+**Language:** Nim  
+**Purpose:** Architecture-agnostic kernel logic
+
+## Module Index
+
+| File | Purpose |
+|------|---------|
+| `kernel.nim` | Main entry point (`kmain`), fiber test |
+| `fiber.nim` | Cooperative fiber abstraction |
+| `ring.nim` | Lock-free Disruptor ring buffer |
+| `panicoverride.nim` | Nim panic handler for freestanding |
+
+## Architecture Independence
+
+This folder contains **no architecture-specific code**. All platform-specific
+details are handled by the HAL layer (`../hal/`).
+
+Compile-time architecture selection uses Nim's `when defined()`:
+```nim
+when defined(amd64):
+  const CONTEXT_SIZE = 56
+elif defined(arm64):
+  const CONTEXT_SIZE = 96
+elif defined(riscv64):
+  const CONTEXT_SIZE = 112
+```
+
+## Dependencies
+
+- Imports `console_write`, `rumpk_halt` from HAL (Zig L0)
+- Imports `cpu_switch_to` from arch-specific assembly
+- Uses `mm:arc` memory management (no GC)
+
+## Build
+
+Built via `../build.sh [aarch64|x86_64|riscv64]`
diff --git a/hal/README.md b/hal/README.md
new file mode 100644
index 0000000..c96c236
--- /dev/null
+++ b/hal/README.md
@@ -0,0 +1,46 @@
+# Rumpk HAL (L0)
+
+**Language:** Zig + Assembly  
+**Purpose:** Hardware Abstraction Layer
+
+## Module Index
+
+| File | Purpose |
+|------|---------|
+| `main.zig` | Entry point (`_start`), stack setup, calls Nim `kmain` |
+| `stubs.zig` | Freestanding libc (memcpy, malloc, printf, etc.) |
+| `uart.zig` | PL011 UART driver (QEMU virt) |
+| `abi.zig` | C ABI structs shared with Nim |
+
+## Architecture Directory (`arch/`)
+
+Contains per-architecture implementations:
+
+```
+arch/
+├── aarch64/        # ARM64 (VisionFive 2, RPi, AWS Graviton)
+│   ├── switch.S    # Context switch (96 bytes)
+│   └── constants.nim
+├── x86_64/         # System V ABI (servers, trading)
+│   ├── switch.S    # Context switch (56 bytes)
+│   └── constants.nim
+└── riscv64/        # RISC-V LP64 (satellites, drones)
+    ├── switch.S    # Context switch (112 bytes)
+    └── constants.nim
+```
+
+## Freestanding Doctrine
+
+This HAL provides ALL C ABI symbols. No glibc, no musl.
+
+**Exported Symbols:**
+- Memory: `memcpy`, `memset`, `memmove`, `memcmp`
+- Strings: `strlen`, `strcmp`, `strcpy`
+- Heap: `malloc`, `free`, `realloc`, `calloc`
+- I/O: `printf`, `puts`, `putchar`
+- Exit: `exit`, `abort`
+- Signals: `signal`, `raise` (no-op stubs)
+
+## Build
+
+Compiled via `zig build-obj -target <arch>-freestanding-none`