diff --git a/README.md b/README.md
new file mode 100644
index 0000000..43ebb81
--- /dev/null
+++ b/README.md
@@ -0,0 +1,239 @@
+
+# 🚀 MNMIVM
+
+### *Fire-and-Forget Virtual Machines*
+
+![MNMIVM Hero](./assets/tuxrockets.jpg)
+
+**MNMIVM** is a minimal, single-binary VM launcher built on **QEMU + KVM + cloud-init**.
+It is designed for *fast iteration*, *ephemeral usage*, and *zero ceremony*.
+
+If Docker feels too constrained, and OpenStack / Proxmox feel like overkill — MNMIVM sits comfortably in the middle.
+
+> Spin it up.
+> Get a random port.
+> SSH in.
+> Done.
+
+---
+
+## ✨ What MNMIVM Is
+
+* A **fire-and-forget VM launcher**
+* A **CLI-first** virtualization tool
+* A **thin orchestration layer**, not a platform
+* A way to spin up *real Linux VMs* without running a control plane
+
+MNMIVM intentionally avoids:
+
+* Long-lived port bindings
+* Static network assumptions
+* Cluster state
+* Databases
+* APIs
+* Daemons
+
+It launches a VM, hands you SSH + VNC, and gets out of the way.
+
+---
+
+## 🧠 Design Philosophy
+
+MNMIVM is built around a few hard rules:
+
+* **No background services**
+* **No required config files**
+* **No global state beyond `/var/lib/microvm`**
+* **Every VM is self-contained**
+* **Cloud-init is the source of truth**
+* **Root-only, explicit control**
+
+This makes MNMIVM ideal for:
+
+* Homelabs
+* CI runners
+* Testing OS images
+* Disposable dev environments
+* Learning QEMU/KVM internals
+* “I just need a VM *right now*”
+
+---
+
+## 🆚 How It Compares (At a Glance)
+
+| Feature                | MNMIVM      | Docker  | LXC/LXD | Proxmox | OpenStack |
+| ---------------------- | ----------- | ------- | ------- | ------- | --------- |
+| Real VMs               | ✅           | ❌       | ⚠️      | ✅       | ✅         |
+| Cloud-init             | ✅           | ❌       | ⚠️      | ✅       | ✅         |
+| Requires Daemons       | ❌           | ✅       | ✅       | ✅       | ✅         |
+| Random Ports           | ✅           | ❌       | ❌       | ❌       | ❌         |
+| Cluster-aware          | ❌           | ❌       | ⚠️      | ✅       | ✅         |
+| Stateful Control Plane | ❌           | ❌       | ⚠️      | ✅       | ✅         |
+| Setup Time             | **Seconds** | Minutes | Minutes | Hours   | Days      |
+
+> MNMIVM behaves more like **`docker run` for VMs**, not like a cloud.
+
+---
+
+## 🧱 Architecture Overview
+
+* **QEMU + KVM** for virtualization
+* **User-mode networking** (no bridges required)
+* **Cloud-init seed ISO** (`cidata`) for provisioning
+* **QCOW2 backing images**
+* **Ephemeral SSH + VNC ports**
+* **State stored on disk only**
+
+```
+/var/lib/microvm/
+├── images/        # Base cloud images
+└── vms/
+    └── vm1/
+        ├── disk.qcow2
+        ├── seed.iso
+        ├── pubkey.pub
+        ├── os.name
+        ├── ssh.port
+        ├── vnc.port
+        └── vm.pid
+```
+
+No database.
+No API.
+No daemon.
+
+---
+
+## 📦 Supported Operating Systems
+
+| OS     | Version     | Boot Mode |
+| ------ | ----------- | --------- |
+| Ubuntu | 24.04 LTS   | BIOS      |
+| Debian | 13 (Trixie) | BIOS      |
+| Fedora | 43 Cloud    | BIOS      |
+| Alpine | 3.22        | BIOS      |
+
+> UEFI images are intentionally avoided for simplicity and reliability.
+
+---
+
+## 🔑 SSH & Identity Management
+
+* SSH keys are injected via **cloud-init**
+* Keys are **fully replaced**, not appended
+* Old keys are **revoked**
+* `update-cloud` regenerates the seed ISO
+* Changes apply on **next boot**
+
+This gives you **real identity revocation**, not just key sprawl.
+
+---
+
+## 📀 Disk Behavior
+
+* Base disk size is **12GB** (configurable constant)
+* Uses **QCOW2 backing images**
+* Root filesystem auto-expands on first boot
+* Predictable, uniform VM sizing
+
+This keeps resource usage balanced and intentional.
+
+---
+
+## 🧰 CLI Usage
+
+### Create a VM
+
+```bash
+sudo mnmivm create vm1 --os debian --pubkey-path ~/.ssh/id_ed25519.pub
+```
+
+### Start a VM
+
+```bash
+sudo mnmivm start vm1
+```
+
+### Stop a VM
+
+```bash
+sudo mnmivm stop vm1
+```
+
+### Update SSH key (cloud-init)
+
+```bash
+sudo mnmivm update-cloud vm1 --pubkey-path newkey.pub
+```
+
+### List VMs
+
+```bash
+sudo mnmivm list
+```
+
+### Delete a VM
+
+```bash
+sudo mnmivm delete vm1
+# Requires typing YES in all caps
+```
+
+---
+
+## 📊 VM List Output
+
+MNMIVM renders a clean Unicode table showing:
+
+* Name
+* Running state
+* OS
+* SSH endpoint
+* VNC endpoint
+* SSH public key path
+
+This makes it usable *without* scripting.
+
+---
+
+## ⚠️ What MNMIVM Is Not
+
+* ❌ A cloud platform
+* ❌ A hypervisor manager
+* ❌ A replacement for Proxmox
+* ❌ A Kubernetes node orchestrator
+* ❌ A long-lived VM manager
+
+If you want **policy, HA, scheduling, quotas, tenants** — use Proxmox or OpenStack.
+
+If you want **a VM right now**, MNMIVM wins.
+
+---
+
+## 🧪 Project Status
+
+* ✅ Actively working
+* ✅ Under ~600 lines of Go
+* ✅ No external Go dependencies
+* ⚠️ API not stabilized yet
+* ⚠️ CLI flags may evolve
+
+This project is intentionally **hackable** and **readable**.
+
+---
+
+## 🐧 Why MNMIVM Exists
+
+Sometimes you don’t want:
+
+* A cluster
+* A UI
+* A dashboard
+* A service mesh
+
+You just want to:
+
+> “Launch a VM and throw it into orbit.”
+
+That’s MNMIVM.
+
diff --git a/assets/tuxrockets.jpg b/assets/tuxrockets.jpg
new file mode 100644
index 0000000..2461528
Binary files /dev/null and b/assets/tuxrockets.jpg differ