[chore] Update AGENTS.md

AGENTS.md

@@ -50,9 +50,26 @@ All `string_utils.h` helpers are `static inline` — header-only, no link issues
 
 ## Conventions
 
-- **Commits:** `[type] message` — types: `feat`, `fix`, `chore`, `docs`, `refactor` (see `git log`).
+- **Commits:** `[type] message` — types: `feat`, `fix`, `chore`, `docs`, `refactor`, `optm` (see `git log`).
 - **Languages:** C17 (`boot.c`), C++17 (`kernel/`) — `-ffreestanding -fno-stack-protector -fshort-wchar -mno-red-zone -fcf-protection=none`. Kernel adds `-DGNU_EFI_USE_MS_ABI -fno-pic`.
 - **`kernel_main` must be `extern "C"`** — `boot.c` (C) calls into C++ (`kernel/entry.cpp:6`).
 - **All UEFI protocol calls must use `uefi_call_wrapper`** — calling the member fn directly page-faults in long mode. See `kernel/main.cpp:23-24` and throughout.
 - **Kernel linked at `0x100000`** (`kernel/kernel.ld`); `.bss` start/end symbols exposed as `__bss_start` / `__bss_end`.
 - **No tests, no CI, no lint config** — `make` is the only verification step. Boot by hand in QEMU to confirm kernel output in `serial.log`.
+
+## Global state
+
+| Symbol | File | Type |
+|--------|------|------|
+| `ST` | `kernel/entry.cpp` | `EFI_SYSTEM_TABLE*` — saved from UEFI boot |
+| `g_gfx` | `include/graphics/context.h` | `gfx_context` — GOP framebuffer info |
+| `g_draw_target` | `include/graphics/context.h` | `draw_target` — current draw surface |
+| `g_pmm` | `include/memory/pmm.h` | `pmm_t` — physical page allocator state |
+| `g_serial` | `kernel/serial.cpp` | `serial_context` — serial protocol handle |
+
+## Gotchas
+
+- **No paging** — kernel runs in physical memory, identity-mapped.
+- **No libc** — all string/memory ops go through `string_utils.h` (header-only, `static inline`).
+- **Window switching** uses Shift+F10 (hardcoded PS/2 scan codes in `kernel/graphics/layer.cpp`).
+- **`third_party/`** is empty — no external deps beyond bundled gnu-efi in `efi/`.