Built heap allocation

docs/README.md

@@ -18,7 +18,7 @@ rather than restate it. Roughly in the order things happen at runtime:
    rather than leaking UEFI's memory descriptors across the boundary.
 5. **[frame-allocator.md](frame-allocator.md) — the physical frame allocator.** The
    bitmap allocator that hands out and reclaims 4 KiB physical frames from that
-   map — the primitive page tables and the heap will be built on.
+   map — the primitive page tables and the heap are built on.
 6. **[interrupts.md](interrupts.md) — interrupts and exceptions.** The GDT, IDT and
    TSS, the exception stubs, and the handler that reports a CPU fault in red instead
    of letting it triple-fault into a silent reset.
@@ -28,8 +28,11 @@ rather than restate it. Roughly in the order things happen at runtime:
 8. **[device-interrupts.md](device-interrupts.md) — device interrupts.** The Local
    APIC and its timer — the kernel's first interrupt that is *handled and returned
    from*, giving it a heartbeat.
-9. **[halting.md](halting.md) — halting.** Why a kernel can't just "exit", and
-   how `while (true) hlt` parks the CPU safely once there's nothing left to do.
+9. **[heap.md](heap.md) — the kernel heap.** A growable free-list allocator built on
+   the VMM, exposed as a `std.mem.Allocator` so std containers work — dynamic
+   allocation for the kernel.
+10. **[halting.md](halting.md) — halting.** Why a kernel can't just "exit", and
+    how `while (true) hlt` parks the CPU safely once there's nothing left to do.
 
 Cutting across all of these:
 
@@ -51,7 +54,8 @@ map** of physical RAM ([memory-map.md](memory-map.md)); the kernel turns that ma
 into a **frame allocator** ([frame-allocator.md](frame-allocator.md)), installs
 its **descriptor tables** so CPU faults are caught ([interrupts.md](interrupts.md)),
 builds its own **page tables** and switches onto them ([paging.md](paging.md)),
-starts the **timer** so it has a heartbeat ([device-interrupts.md](device-interrupts.md)),
+brings up the **heap** for dynamic allocation ([heap.md](heap.md)), starts the
+**timer** so it has a heartbeat ([device-interrupts.md](device-interrupts.md)),
 runs — its CPU-specific bits behind the [arch](arch.md) boundary — and when it has
 finished, or panics, it **halts** ([halting.md](halting.md)).
 
@@ -63,6 +67,7 @@ finished, or panics, it **halts** ([halting.md](halting.md)).
 | Kernel entry, panic, bring-up | `src/main.zig` |
 | Shared loader↔kernel contract (`BootInfo`, `Framebuffer`, `MemoryMap`, ABI) | `src/root.zig` |
 | Physical frame allocator | `src/pmm.zig` |
+| Kernel heap (`std.mem.Allocator`) | `src/heap.zig` |
 | Framebuffer text console (mirrors to serial) | `src/console.zig` |
 | In-kernel test cases | `src/tests.zig` |
 | Arch-specific kernel code (`halt`, GDT/IDT/TSS, exception + interrupt stubs, page tables, APIC/timer, serial, linker script) | `src/arch/x86_64/` |