From 990c2a629586c1c307382ed560ea8b12e39a1664 Mon Sep 17 00:00:00 2001
From: pyao12 <patrick25yao@outlook.com>
Date: Sun, 24 May 2026 19:52:01 +0800
Subject: [PATCH] [chore] Create AGENTS.md

---
 AGENTS.md | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..c2bba8b
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,33 @@
+# Sylva OS — Agent Guide
+
+x86_64 UEFI hobby OS kernel. C17 boot → C++17 kernel, ELF64 → PE32+ via objcopy.
+
+## Build & Run
+
+| Command | What |
+|---------|------|
+| `make` | Build `build/BOOTX64.EFI` |
+| `make run` | QEMU + OVMF, serial → `serial.log`, paused for GDB (`-s -S`) |
+| `make clean` | **Always before commit** — gnu-efi produces untracked files |
+
+## Architecture
+
+- `boot.c` — UEFI entrypoint (`efi_main`), calls `kernel_main()`
+- `kernel/main.cpp` — `extern "C" kernel_main()`: init GOP → serial → PMM → heap → idle loop (`hlt`)
+- `kernel/serial.cpp` — UEFI serial protocol wrapper
+- `kernel/memory/pmm.cpp` — bitmap + free-list physical page allocator
+- `kernel/memory/heap.cpp` — kmalloc/kfree/kcalloc/krealloc (first-fit, coalescing)
+- `graphics/` — GOP framebuffer pixel drawing
+- `fonts/` — Hankaku 8×16 pixel font renderer
+- `gnu-efi/` — git submodule (https://github.com/ncroxon/gnu-efi.git)
+
+## Quirks
+
+- **`uefi_call_wrapper` required for all UEFI protocol calls or kernel page-faults**
+- `kernel_main` must be `extern "C"` (C→C++ linkage)
+- QEMU starts paused — connect GDB to :1234 to proceed
+- No tests, no CI, no lint/formatter config
+- C17 (`boot.c`), C++17 (`kernel/`)
+- Standards: `-ffreestanding -fno-stack-protector -fshort-wchar -mno-red-zone`
+- `#define ASM asm volatile` in `include/common.h`
+- `BUILD_INFOS.h` is a placeholder for CI