AethelOS: Instructions file for Claude Code

CLAUDE.md - AI Assistant Guide to AethelOS Development

Quick Reference: This document is designed for AI assistants (Claude, GPT, etc.) working on AethelOS. It provides build commands, design philosophy, coding standards, and pointers to architectural documentation.

---

Table of Contents

1. Quick Start
2. Design Philosophy
3. Architecture Overview
4. Coding Standards & Quality Controls
5. Documentation Index
6. Current Status & Roadmap
7. Common Tasks

---

Build Commands

From project root:

# 1. Build the kernel and ISO

cd /f/OS/user_programs/hello && cargo build --release --target x86_64-unknown-none 2>&1 | grep -E "(Compiling|Finished|error)"
cd /f/OS && cargo build 2>&1 | grep -E "(Compiling heartwood|Finished|error)" && wsl bash -c "cp target/x86_64-aethelos/debug/heartwood isodir/boot/aethelos/heartwood.bin && grub-mkrescue -o aethelos.iso isodir 2>&1 | grep -E '(success|Writing)'"


# 2. Run in QEMU
Do not attempt to run in QEMU yourself. Pass the turn to the human after a build and alert them to run it for you and inform you of the results.



### Prerequisites

- **Rust:** Nightly toolchain (configured in `rust-toolchain.toml`)
  - Components: `rust-src`, `llvm-tools-preview`
- **GRUB:** `grub-mkrescue` (via WSL on Windows, native on Linux)
- **QEMU:** `qemu-system-x86_64` for testing

---

## Design Philosophy

### Core Principle: Symbiotic Computing

> *"The code does not command the silicon. The silicon does not serve the code. They dance together, and in that dance, life emerges."*

AethelOS is **not** a clone of Unix, Linux, or Windows. It is a ground-up rethinking of operating system design based on these principles:

### 1. **Harmony Over Force**

- **NOT:** Preemptive scheduling that interrupts processes arbitrarily
- **BUT:** Cooperative negotiation where processes yield willingly
- **METAPHOR:** The Loom of Fate weaves threads together harmoniously

**Implementation:**
- Threads have harmony scores based on CPU usage, yield frequency, and cooperation
- "Parasitic" threads are throttled (slowed), not killed
- System-wide harmony metrics guide scheduling decisions

### 2. **Memory Over Forgetting**

- **NOT:** Files that are overwritten and lost
- **BUT:** Git-like versioning built into the filesystem
- **METAPHOR:** The World-Tree remembers all versions like tree rings

**Implementation:**
- Content-addressable storage (SHA-256)
- Global commit graph tracking all changes
- Query-based file discovery: `seek scrolls where essence is "Scroll" and creator is "Elara"`
- Intelligent pruning prevents unbounded growth

### 3. **Beauty as Necessity**

- **NOT:** Aesthetics as afterthought
- **BUT:** Visual design reveals system state intuitively
- **METAPHOR:** The system's appearance is its truth

**Implementation:**
- Poetic naming (Loom of Fate, Mana Pool, World-Tree)
- Unicode symbols (◈ for emphasis, tree metaphors)
- VGA graphics mode planned for vector-based GUI
- Color-coded thread states, visual harmony indicators

### 4. **Security Through Nature**

- **NOT:** Access control lists and permissions bits
- **BUT:** Unforgeable capability tokens
- **METAPHOR:** Natural boundaries, not artificial walls

**Implementation:**
- Capability-based security (no raw pointers in userspace)
- Capabilities grant specific rights (read, write, execute, delegate)
- Capabilities can be attenuated (reduced permissions) but never amplified
- Hardware MMU enforces capability boundaries
- Borrowing ideas from known good kernel hardening efforts, grsec/PaX etc.
---

## Architecture Overview

### High-Level Structure

┌─────────────────────────────────────────────────────────┐ │ User Space │ │ ┌─────────────┐ ┌──────────────┐ ┌───────────────┐ │ │ │ Eldarin │ │ User Apps │ │ System Utils │ │ │ │ Shell │ │ (Future) │ │ │ │ │ └─────────────┘ └──────────────┘ └───────────────┘ │ └─────────────────────────────────────────────────────────┘ ↕ (Capability-based syscalls) ┌─────────────────────────────────────────────────────────┐ │ Groves (Services) │ │ ┌──────────────┐ ┌──────────────┐ ┌────────────────┐ │ │ │ World-Tree │ │ The Weave │ │ Network Sprite │ │ │ │ (Filesystem) │ │ (Compositor) │ │ (Networking) │ │ │ └──────────────┘ └──────────────┘ └────────────────┘ │ └─────────────────────────────────────────────────────────┘ ↕ (IPC via Nexus) ┌─────────────────────────────────────────────────────────┐ │ Heartwood (Kernel) │ │ ┌──────────────┐ ┌──────────────┐ ┌────────────────┐ │ │ │ Loom of Fate │ │ Mana Pool │ │ Attunement │ │ │ │ (Scheduler) │ │ (Memory) │ │ (Hardware) │ │ │ └──────────────┘ └──────────────┘ └────────────────┘ │ │ ┌──────────────┐ ┌──────────────┐ │ │ │ Nexus │ │ VGA Buffer │ │ │ │ (IPC) │ │ (Display) │ │ │ └──────────────┘ └──────────────┘ │ └─────────────────────────────────────────────────────────┘ ↕ ┌─────────────────────────────────────────────────────────┐ │ Hardware │ │ CPU (x86-64) | Memory | VGA | Keyboard | Timer | etc. │ └─────────────────────────────────────────────────────────┘

### Heartwood (Kernel) Components

| Module | Purpose | Status | Location |
|--------|---------|--------|----------|
| **Loom of Fate** | Cooperative thread scheduler with harmony metrics | ✅ Complete | `heartwood/src/loom_of_fate/` |
| **Mana Pool** | Memory allocator (currently buddy allocator) | ✅ Complete | `heartwood/src/mana_pool/` |
| **Attunement** | Hardware abstraction (IDT, PIC, keyboard, timer) | ✅ Complete | `heartwood/src/attunement/` |
| **VGA Buffer** | Text mode display driver | ✅ Complete | `heartwood/src/vga_buffer.rs` |
| **Eldarin** | Interactive shell | ✅ Complete | `heartwood/src/eldarin.rs` |
| **Nexus** | Inter-process communication | ⚪ Planned | Not started |

### Groves (Service Layer)

| Service | Purpose | Status | Location |
|---------|---------|--------|----------|
| **World-Tree** | Query-based filesystem with versioning | 🟡 Designed | `groves/world-tree_grove/` |
| **The Weave** | Vector scene graph compositor | 🟡 Designed | `groves/the-weave_grove/` |
| **Lanthir** | Window manager | 🟡 Designed | `groves/lanthir_grove/` |
| **Network Sprite** | Network stack | 🟡 Designed | `groves/network_sprite/` |

### Ancient Runes (Standard Library)

| Library | Purpose | Status | Location |
|---------|---------|--------|----------|
| **Corelib** | Collections, math, error types | 🟡 Skeletal | `ancient-runes/corelib/` |
| **Weaving** | Widget toolkit (buttons, labels, containers) | 🟡 Skeletal | `ancient-runes/weaving/` |
| **Script** | Shell scripting API for Glimmer-Weave | 🟡 Skeletal | `ancient-runes/script/` |

**Status Legend:**
- ✅ **Complete:** Working and integrated
- 🟡 **Designed:** Architecture documented, skeleton code exists
- ⚪ **Planned:** Design phase

---

## Coding Standards & Quality Controls

### 🔴 CRITICAL RULES - MUST FOLLOW

#### 1. **No Unsafe Without Justification**

```rust
// ❌ WRONG - Unjustified unsafe
unsafe {
    core::ptr::write_volatile(addr, value);
}