dddimcha · dddimcha · Jan 29, 2026 · Jan 29, 2026 · Jan 29, 2026 · Jan 29, 2026
diff --git a/README.md b/README.md
@@ -1,202 +1,192 @@
 # EMBODIOS - Bare-Metal AI Operating System
 
-[![Status](https://img.shields.io/badge/Status-95%25%20Complete-brightgreen)](https://github.com/dddimcha/embodiOS/wiki/Current-State-Analysis)
-[![AI Runtime](https://img.shields.io/badge/AI%20Runtime-100%25-brightgreen)](https://github.com/dddimcha/embodiOS/wiki/Pillar-1:-Ollama-GGUF-Integration)
-[![Drivers](https://img.shields.io/badge/Drivers-85%25-green)](https://github.com/dddimcha/embodiOS/wiki/Pillar-2:-Linux-Driver-Compatibility)
-[![License](https://img.shields.io/badge/License-MIT-blue)](LICENSE)
-[![Model Compatibility](https://img.shields.io/badge/Model%20Compatibility-CI-brightgreen)](https://github.com/dddimcha/embodiOS/actions/workflows/model-compatibility-ci.yml)
-
-> **The world's first bare-metal AI operating system** - where the AI model runs directly on hardware as the OS kernel itself. No userspace. No OS overhead. Just transformers and hardware.
-
-## What's New (January 2026)
-
-- **Interactive Chat Mode:** `talk` command for dedicated conversation sessions with performance tracking
-- **Performance Stats:** Separate `perf` command to view timing metrics without cluttering chat
-- **Console UX:** Polished help system with categories, status display, command suggestions
-- **Production ISO Builder:** One-click bootable ISO with GRUB menu
-- **Stability Testing Suite:** Automated long-running tests (1h-72h) for memory leak detection
-- **Secure Boot:** UEFI Secure Boot support with signed kernel validation
-- **Streaming Inference:** Memory-efficient inference engine with parallel workers
-- **Industrial Protocols:** Modbus TCP and EtherCAT support for real-time automation
-
-## Current Status
-
-| Component | Status | Completion |
-|-----------|--------|------------|
-| **Kernel Foundation** | Memory, boot, interrupts, DMA, scheduler | 95% ✅ |
-| **AI Runtime** | GGUF, BPE, streaming inference, quantization | 100% ✅ |
-| **Drivers** | NVMe, VirtIO, e1000e, PCI, TCP/IP, Industrial | 85% ✅ |
-| **Performance** | SIMD, parallel inference, benchmarks | 90% ✅ |
-| **Documentation** | Wiki, README, Contributing guide | 100% ✅ |
-| **Overall** | **v1.0 Ready** - hardware testing only | **95%** |
+Run LLMs directly on hardware without any OS overhead. No Linux. No userspace. Just transformers and bare metal.
 
 ## Quick Start
 
-### Clone with Documentation
+### Prerequisites
 
+**macOS:**
 ```bash
-# Clone with wiki submodule
-git clone --recurse-submodules https://github.com/dddimcha/embodiOS.git
-cd embodiOS
+brew install x86_64-elf-gcc x86_64-elf-binutils x86_64-elf-grub xorriso qemu
+```
+
+**Ubuntu/Debian:**
+```bash
+sudo apt install gcc-x86-64-linux-gnu binutils-x86-64-linux-gnu grub-pc-bin xorriso qemu-system-x86
+```
 
-# Or initialize submodule after clone
-git submodule update --init
+**Arch Linux:**
+```bash
+sudo pacman -S x86_64-elf-gcc x86_64-elf-binutils grub xorriso qemu
 ```
 
 ### Build and Run
 
 ```bash
-# Build the kernel (requires Linux or Docker)
-cd kernel
-make
+git clone https://github.com/dddimcha/embodiOS.git
+cd embodiOS
+
+./embodi build
+./embodi run
+```
 
-# Run in QEMU
-qemu-system-x86_64 -kernel embodios.elf -m 256M -serial stdio
+## CLI Reference
+
+```
+Usage: embodi <command> [options]
+
+Commands:
+  build             Build the kernel
+  iso               Create bootable ISO
+  run               Run in QEMU
+  clean             Clean build artifacts
+  test              Run kernel tests
+  help              Show help
 ```
 
-### Chat with AI
+### Build Kernel
 
 ```bash
-> talk                   # Enter interactive chat mode (recommended!)
-You> Hello, how are you?
-AI>  Hello! I'm doing well. How can I help you today?
-You> perf                # Check performance inline
- [Session: 1 msgs, 15 tokens, 127 tok/s avg]
-You> exit                # Leave chat mode
+./embodi build              # Standard build
+./embodi build --debug      # Debug build with symbols
+```
 
-> chat Hello world       # Single message (for scripting)
-> perf                   # View detailed performance stats
-> status                 # Check AI readiness
+### Create Bootable ISO
+
+```bash
+./embodi iso                              # Without model
+./embodi iso --model models/smollm.gguf   # With embedded model
+./embodi iso --model models/smollm.gguf --arch x86_64
 ```
 
-### System Commands
+### Run in QEMU
 
 ```bash
-> help                   # Show available commands
-> help ai                # AI-specific commands  
-> help all               # All commands
-> benchmark              # Full inference benchmark
-> mem                    # Show memory stats
-> lspci                  # List PCI devices
+./embodi run                    # Run kernel directly
+./embodi run --memory 2G        # With more RAM
+./embodi run --iso              # Boot from ISO
 ```
 
-See the **[Console Commands Reference](https://github.com/dddimcha/embodiOS/wiki/Console-Commands)** for all commands.
+### Download Models
+
+```bash
+mkdir -p models
+
+# SmolLM-135M (469MB, fast)
+curl -L -o models/smollm-135m.gguf \
+  "https://huggingface.co/HuggingFaceTB/SmolLM-135M-Instruct-GGUF/resolve/main/smollm-135m-instruct-q6_k.gguf"
 
-## Key Features
+# TinyLlama-1.1B (638MB, better quality)
+curl -L -o models/tinyllama-1.1b.gguf \
+  "https://huggingface.co/TheBloke/TinyLlama-1.1B-Chat-v1.0-GGUF/resolve/main/tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf"
+```
 
-| Feature | Description |
+## Run on Real Hardware
+
+### Write to USB
+
+```bash
+# Build ISO with model
+./embodi iso --model models/smollm-135m.gguf
+
+# Write to USB (replace /dev/sdX with your device)
+sudo dd if=build/embodios.iso of=/dev/sdX bs=4M status=progress conv=fsync
+```
+
+### Boot
+
+1. Insert USB into target machine
+2. Enter BIOS boot menu (F12, F2, or Del)
+3. Select USB device
+4. EMBODIOS boots to AI shell
+
+## Shell Commands
+
+Once booted:
+
+| Command | Description |
 |---------|-------------|
-| **GGUF Model Support** | Load models from Ollama ecosystem directly |
-| **BPE Tokenization** | SentencePiece-compatible tokenizer from GGUF |
-| **Multi-Model** | Hot-swap between up to 8 loaded models |
-| **Integer-Only Math** | No FPU required - runs on any x86_64 |
-| **SIMD Acceleration** | SSE2/AVX2 for matrix operations |
-| **Zero-Copy DMA** | Identity-mapped memory for direct hardware access |
-| **UEFI Secure Boot** | Signed kernel validation for trusted boot chain |
-| **<1s Boot Time** | From power-on to AI inference ready |
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────┐
-│                    User Input                        │
-└─────────────────────┬───────────────────────────────┘
-                      ▼
-┌─────────────────────────────────────────────────────┐
-│              BPE Tokenizer (from GGUF)              │
-│         SentencePiece-compatible encoding           │
-└─────────────────────┬───────────────────────────────┘
-                      ▼
-┌─────────────────────────────────────────────────────┐
-│            Transformer Engine (Integer)             │
-│    Q4_K/Q5_K/Q6_K/Q8_0 quantized weights           │
-│         SIMD-accelerated matrix ops                 │
-└─────────────────────┬───────────────────────────────┘
-                      ▼
-┌─────────────────────────────────────────────────────┐
-│              Hardware Abstraction                   │
-│         PCI • DMA • Memory-Mapped I/O               │
-└─────────────────────────────────────────────────────┘
+| `talk` | Start interactive AI chat |
+| `chat <msg>` | Single message to AI |
+| `status` | System and AI status |
+| `help` | Show all commands |
+| `benchmark` | Run inference benchmark |
+| `mem` | Memory usage |
+| `perf` | Chat performance stats |
+
+### Example Session
+
+```
+embodios> talk
+You> Hello!
+AI>  Hello! How can I help you today?
+You> exit
+
+embodios> status
+  AI: Ready (SmolLM-135M)
+  Memory: 120MB / 512MB
 ```
 
-## Documentation
+## Supported Models
 
-Full documentation available on the [EMBODIOS Wiki](https://github.com/dddimcha/embodiOS/wiki).
-
-### Project Status
-- [Home](https://github.com/dddimcha/embodiOS/wiki) - Wiki home page
-- [Current State Analysis](https://github.com/dddimcha/embodiOS/wiki/Current-State-Analysis) - Project progress (75% complete)
-- [Three Strategic Pillars](https://github.com/dddimcha/embodiOS/wiki/Three-Strategic-Pillars) - Implementation roadmap
-- [Pillar 1: Ollama GGUF Integration](https://github.com/dddimcha/embodiOS/wiki/Pillar-1:-Ollama-GGUF-Integration) - AI runtime (90% complete)
-
-### Quick Start Guides
-- [Getting Started](https://github.com/dddimcha/embodiOS/wiki/Getting-Started) - Installation and first steps
-- [Console Commands](https://github.com/dddimcha/embodiOS/wiki/Console-Commands) - **Complete command reference**
-- [Modelfile Reference](https://github.com/dddimcha/embodiOS/wiki/Modelfile-Reference) - Model configuration
-- [Hardware Requirements](https://github.com/dddimcha/embodiOS/wiki/Hardware-Requirements) - Supported hardware
-- [API Reference](https://github.com/dddimcha/embodiOS/wiki/API-Reference) - API documentation
-- [Contributing](https://github.com/dddimcha/embodiOS/wiki/Contributing) - How to contribute
-
-### Technical Deep Dives
-- [Architecture Overview](https://github.com/dddimcha/embodiOS/wiki/Architecture-Overview) - System architecture
-- [Quantized Integer Inference](https://github.com/dddimcha/embodiOS/wiki/Quantized-Integer-Inference) - How integer-only AI works
-- [Performance Benchmarks](https://github.com/dddimcha/embodiOS/wiki/Performance-Benchmarks) - Benchmark results
-- [Bare Metal Deployment](https://github.com/dddimcha/embodiOS/wiki/Bare-Metal-Deployment) - Real hardware deployment
-- [Stability Testing](docs/stability_testing.md) - Long-running stability test suite
-
-## Performance Targets
-
-| Metric | llama.cpp | EMBODIOS v1.0 | Advantage |
-|--------|-----------|---------------|-----------|
-| **Speed** | 83-86 tok/s | 100-120 tok/s | **20-40% faster** |
-| **Memory** | 160 MB | 120 MB | **25% less** |
-| **Latency Jitter** | ±5-10ms | ±0.5ms | **10-20x better** |
-| **Boot Time** | N/A | <1 sec | **Instant on** |
-| **First Token** | ~50ms | <20ms | **2.5x faster** |
-| **Context Switch** | ~1-5μs | 0 | **Zero overhead** |
-
-## Verified Models
-
-| Model | Size | Quantization | Status |
-|-------|------|--------------|--------|
-| TinyLlama-1.1B | 638 MB | Q4_K_M | Tested |
-| Phi-2 | 1.7 GB | Q4_K_M | Tested |
-| Mistral-7B | 4.2 GB | Q4_K_M | Tested |
-
-## Why Bare-Metal AI?
-
-**Kernel-space AI enables:**
-- **Ultra-low latency:** 10x better consistency for real-time applications
-- **Minimal footprint:** 25% less memory for edge/embedded devices
-- **Direct hardware access:** No syscall overhead, zero-copy DMA
-- **Deterministic timing:** Critical for robotics, industrial control
+| Model | Size | Quantization |
+|-------|------|--------------|
+| SmolLM-135M | 469 MB | Q6_K |
+| TinyLlama-1.1B | 638 MB | Q4_K_M |
+| Phi-2-2.7B | 1.7 GB | Q4_K_M |
+| Mistral-7B | 4.2 GB | Q4_K_M |
 
-## Contributing
+Any GGUF model from Ollama/HuggingFace should work.
 
-```bash
-# Clone the repository
-git clone --recurse-submodules https://github.com/dddimcha/embodiOS.git
+## Project Structure
 
-# Build and test
-cd kernel && make
-make test
+```
+embodiOS/
+├── embodi              # CLI tool
+├── kernel/             # Kernel source
+│   ├── ai/             # AI runtime
+│   ├── core/           # Kernel core
+│   ├── drivers/        # Hardware drivers
+│   └── Makefile
+├── models/             # GGUF models
+├── scripts/            # Build scripts
+└── build/              # Output (ISO, etc.)
 ```
 
-**Choose Your Pillar:**
-- **Kernel hacker?** → [Pillar 2: Linux Driver Compatibility](https://github.com/dddimcha/embodiOS/wiki/Pillar-2:-Linux-Driver-Compatibility)
-- **AI researcher?** → [Pillar 1: Ollama GGUF Integration](https://github.com/dddimcha/embodiOS/wiki/Pillar-1:-Ollama-GGUF-Integration)
-- **Performance engineer?** → [Pillar 3: Performance Optimization](https://github.com/dddimcha/embodiOS/wiki/Pillar-3:-Performance-Optimization)
+## Performance
 
-## Community
+| Metric | EMBODIOS | llama.cpp |
+|--------|----------|-----------|
+| Memory | 120 MB | 160 MB |
+| Latency jitter | ±0.5ms | ±5-10ms |
+| Boot time | <1 sec | N/A |
+| First token | <20ms | ~50ms |
 
-- [Discord Server](https://discord.gg/xRsYfcdP)
-- [GitHub Wiki](https://github.com/dddimcha/embodiOS/wiki)
-- [Issues](https://github.com/dddimcha/embodiOS/issues)
+## Documentation
+
+- [Wiki](https://github.com/dddimcha/embodiOS/wiki)
+- [Getting Started](https://github.com/dddimcha/embodiOS/wiki/Getting-Started)
+- [Console Commands](https://github.com/dddimcha/embodiOS/wiki/Console-Commands)
+- [Architecture](https://github.com/dddimcha/embodiOS/wiki/Architecture-Overview)
+
+## Contributing
+
+```bash
+git clone https://github.com/YOUR_USERNAME/embodiOS.git
+cd embodiOS
+git checkout -b feature/my-feature
+./embodi build
+./embodi test
+# Submit PR
+```
 
 ## License
 
-EMBODIOS is open source software licensed under the [MIT License](LICENSE).
+MIT License - see [LICENSE](LICENSE)
 
----
+## Links
 
-**EMBODIOS** - Bare-metal AI where transformers meet hardware directly.
+- [Discord](https://discord.gg/xRsYfcdP)
+- [Issues](https://github.com/dddimcha/embodiOS/issues)
+- [Wiki](https://github.com/dddimcha/embodiOS/wiki)