added CLAUDE.md

1 files changed, 80 insertions, 0 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..d931abe
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,80 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**Strix OS** is a bare-metal x86-64 operating system kernel written in Rust, aiming for Linux application compatibility. Currently in Phase 0-1 (foundational infrastructure).
+
+## Build Commands
+
+All commands run from `/StrixKernel/`:
+
+```bash
+# Build the kernel
+cargo build
+
+# Build and run in QEMU
+cargo run
+
+# Run all tests (unit + integration)
+cargo test
+
+# Run a specific integration test
+cargo test --test basic_boot
+cargo test --test stack_overflow
+
+# Clean build artifacts
+cargo clean
+```
+
+**Requirements**: Rust nightly toolchain (specified in `rust-toolchain`), QEMU for running/testing.
+
+## Architecture
+
+### Boot Flow
+1. Bootloader (bootloader crate 0.9) loads kernel and provides `BootInfo` with memory map and physical memory offset
+2. `kernel_main()` in `main.rs` receives control
+3. `strix_os::init()` initializes GDT → IDT → PICs
+4. Kernel enters `hlt_loop()` waiting for interrupts
+
+### Core Modules (`StrixKernel/src/`)
+
+| Module | Purpose |
+|--------|---------|
+| `gdt.rs` | Global Descriptor Table + Task State Segment (double-fault stack) |
+| `interrupts.rs` | IDT setup, exception handlers, hardware interrupts (timer/keyboard via PIC 8259) |
+| `memory.rs` | Page table access (`OffsetPageTable`), `BootInfoFrameAllocator` for physical frames |
+| `vga_buffer.rs` | VGA text mode (80x25), `print!`/`println!` macros |
+| `serial.rs` | UART 16550 serial output, `serial_print!`/`serial_println!` for debugging |
+
+### Memory Model
+- Uses bootloader's `map_physical_memory` feature: all physical memory mapped at a fixed offset
+- `OffsetPageTable` translates virtual ↔ physical addresses
+- `BootInfoFrameAllocator` provides frames from bootloader's memory map
+
+### Test Framework
+- Custom `#[test_case]` attribute with `Testable` trait
+- Tests output to serial port (QEMU `-serial stdio`)
+- QEMU exit codes: `0x10` = success, `0x11` = failure
+- Integration tests in `tests/` run as separate kernel instances
+
+## Key Patterns
+
+- **Lazy statics with spinlocks**: `lazy_static!` + `spin::Mutex` for global mutable state (no std)
+- **Volatile writes**: VGA buffer uses `volatile` crate to prevent optimization
+- **x86_64 crate**: Provides CPU structures (GDT, IDT, page tables) and port I/O
+
+## Target Specification
+
+`x86_64-strix_os.json` defines the custom target:
+- No OS, no standard library
+- Disables red zone, uses soft floats
+- Panic strategy: abort
+
+## Roadmap
+
+See `roadmap.md` for the 6-phase development plan. Next priorities:
+1. Heap allocator (GlobalAlloc implementation)
+2. User space (Ring 3 transition, syscall interface)
+3. Process management (fork, exec, scheduler)