1 files changed, 27 insertions, 12 deletions

diff --git a/CONTEXT.md b/CONTEXT.md
index 68d2368..1c73656 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -4,11 +4,12 @@
 
 Custom x86_64 kernel for the RNG ecosystem.  Toy project — self-contained,
 no strict userspace separation, TempleOS-inspired design philosophy.
-Built in Rust, compiled for the `x86_64-unknown-uefi` target (nightly).
+Built in Rust, compiled for the `x86_64-unknown-uefi` target (stable).
 
 ## Boot interface
 
-The kernel is a **PE32+ EFI application** loaded via UEFI `LoadImage`/`StartImage`.
+The kernel is a **PE32+ EFI application** loaded via UEFI
+`LoadImage`/`StartImage`.
 The existing bootloader (rsbl) loads us from `\bzImage` and passes the UEFI
 system table.  No bootloader changes needed.
 
@@ -56,9 +57,10 @@ same RAM.  Contiguous runs with power-of-two alignment are supported
 
 ## Input strategy
 
-**PS/2 keyboard polling.** Port I/O to `0x60`/`0x64`.  Scancode set 1
-(US QWERTY layout in the initial build).  No interrupts — polling loop
-inside the shell.
+**PS/2 keyboard, interrupt-driven.**  IRQ1 pushes scancodes into a ring
+buffer (`interrupts::KEYBUF`); the shell polls it via `read_scancode()`.
+Port I/O to `0x60`/`0x64`.  Scancode set 1 (US QWERTY layout in the
+initial build).
 
 ## Display strategy
 
@@ -86,7 +88,14 @@ image as `\bzImage` (matching rsbl's expected path).
 
 ## Project layout
 
-Single Rust crate (`x86_64-unknown-uefi` target).  Module breakdown:
+Workspace of four crates, all built for the `x86_64-unknown-uefi` target:
+
+- `rsnix` — the kernel library (module breakdown below)
+- `shell` — command loop and built-ins
+- `rsdos` — EFI entry point (`efi_main`) and boot orchestration
+- `rsdosedit` — kernel-native terminal editor
+
+`rsnix` module breakdown:
 
 - `main.rs` — entry point, panic handler, top-level init
 - `uefi.rs` — UEFI protocol type definitions
@@ -97,14 +106,17 @@ Single Rust crate (`x86_64-unknown-uefi` target).  Module breakdown:
 - `paging.rs` — identity page-table helpers (map/unmap/query, large-page split)
 - `power.rs` — `ResetSystem`-based shutdown, hlt loop fallback
 - `rtc.rs` — CMOS/RTC clock (ports 0x70/0x71), BCD/12h normalization
-- `pci.rs` — legacy PCI config space (0xCF8/0xCFC), full enumeration; `config_write`
+- `pci.rs` — legacy PCI config space (0xCF8/0xCFC), full
+  enumeration; `config_write`
   - 64-bit BAR reader for the AHCI driver
 - `ahci.rs` — SATA AHCI host driver (polling, DMA, no interrupts): scans PCI for
   class 1/subclass 6/prog-if 1, maps ABAR, starts port 0 (FRE/ST/DMAE), runs
   IDENTIFY + READ/WRITE DMA EXT through a 4 KiB DMA buffer
-- `fat.rs` — FAT32: BPB parse, whole-FAT cache in RAM with write-back to both FAT
+- `fat.rs` — FAT32: BPB parse, whole-FAT cache in RAM with
+  write-back to both FAT
   copies, cluster chains, directory scan with checksum-validated LFN
-  reassembly, LFN + 8.3 writing, FSInfo free-count maintenance, mkdir/rm/read/write
+  reassembly, LFN + 8.3 writing, FSInfo free-count maintenance,
+  mkdir/rm/read/write
 - `fs.rs` — VFS: dirs, ramfs files, char devices (`/dev/mem`, `rtc`, `pci`,
   `version`, `meminfo`, `null`, `zero`, `console`, `serial`; `/tmp` ramfs;
   `/etc/motd`); `/disk` mount node + 24-slot ephemeral node pool so shell
@@ -130,14 +142,17 @@ Single Rust crate (`x86_64-unknown-uefi` target).  Module breakdown:
 
 ## Milestone status (v0.1)
 
-✅ **Booting** — kernel loads via rsbl, prints banner via UEFI console (verified on real hardware)
+✅ **Booting** — kernel loads via rsbl, prints banner via UEFI
+  console (verified on real hardware)
 ✅ **ExitBootServices** — memory map captured via static `.bss` buffer
   (see `docs/adr/0001-static-buffer-for-memory-map.md`)
 ✅ **Serial** — UART 16550 at COM1, 115200 8N1
 ✅ **Framebuffer** — GOP located, 8×16 bitmap font renders text
 ✅ **Keyboard** — PS/2 polling, scancode set 1, US QWERTY
-✅ **Shell** — commands: `help`, `echo`, `clear`, `hello`, `info`, `mem`, `halt`, `poweroff`
-✅ **Heap allocator** — first-fit free-list with splitting + coalescing, `alloc`/`free`
+✅ **Shell** — commands: `help`, `echo`, `clear`, `hello`, `info`,
+  `mem`, `halt`, `poweroff`
+✅ **Heap allocator** — first-fit free-list with splitting +
+  coalescing, `alloc`/`free`
   (boot-time self-test verifies alignment, reuse, and full coalescing)
 ✅ **Physical pages** — bitmap allocator over conventional regions, contiguous
   runs, heap reservation, page-0 trap guard (boot-time self-test included)