Add README file in docs

docs/README.md

@@ -0,0 +1,34 @@
+# danos documentation
+
+Notes on how danos boots and draws, written to explain the *why* behind the code
+rather than restate it. Roughly in the order things happen at runtime:
+
+1. **[efi.md](efi.md) — EFI / the boot process.** How UEFI firmware finds and
+   runs the bootloader, what the loader gathers before `ExitBootServices`, how it
+   loads the kernel ELF, and the ABI contract for the jump into the kernel. Start
+   here.
+2. **[gop.md](gop.md) — the Graphics Output Protocol.** How UEFI exposes graphics
+   modes (unlike fixed VGA modes), how we detect the monitor's native resolution
+   from EDID and switch to it, and the pixel formats we accept or reject.
+3. **[framebuffer.md](framebuffer.md) — the framebuffer.** What the linear
+   framebuffer the loader hands over actually is, and what **pitch** (stride)
+   means versus width — the detail you have to get right to avoid a skewed image.
+4. **[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.
+
+## How the pieces relate
+
+The boot flow ties them together: UEFI runs the loader ([efi.md](efi.md)), which
+queries the **GOP** to pick a graphics mode ([gop.md](gop.md)) and hands the
+kernel a **framebuffer** to draw into ([framebuffer.md](framebuffer.md)); when the
+kernel has finished — or panics — it **halts** ([halting.md](halting.md)).
+
+## Source map
+
+| Area | Code |
+|------|------|
+| Bootloader (UEFI app) | `src/efi.zig` → `BOOTX64.efi` |
+| Kernel entry, panic, halt | `src/main.zig` |
+| Shared loader↔kernel contract (`BootInfo`, `Framebuffer`, ABI) | `src/root.zig` |
+| Framebuffer text console | `src/console.zig` |
+| Build + `run-efi` (QEMU/OVMF) | `build.zig` |