diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5e9c1e9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,46 @@
+# spectral
+
+KVM hypervisor introspector. Reads vCPU state and guest physical memory from the host by injecting ioctls into QEMU via ptrace — no agent, no kernel module inside the guest.
+
+Currently targets Windows 11 guests. Enumerates processes by walking the EPROCESS list and cross-references against PspCidTable to find DKOM-hidden ones.
+
+---
+
+## how it works
+
+ptraces the QEMU process, injects `KVM_GET_SREGS`/`KVM_GET_REGS` ioctls to pull vCPU state, then reads guest physical memory through `/proc/<pid>/mem`. From there it's kernel structure walking — CR3 → page tables → EPROCESS → ActiveProcessLinks.
+
+The ioctl injection uses a small shellcode gadget built by `build.rs` that gets written into QEMU's address space and executed under ptrace.
+
+## usage
+
+```
+sudo ./target/debug/KVM-hypervisor-introspector
+```
+
+Needs `CAP_SYS_PTRACE`. Rust nightly for inline asm. (i wrote this like after i changed some stuff up so you might not)
+
+## caveats
+
+- Kernel offsets in `windows.rs` are hardcoded for a specific Win11 build. Check [vergiliusproject.com](https://vergiliusproject.com) if targeting a different one.
+- Don't run this against anything you care about staying stable. Ptrace + live QEMU is racy.
+
+## structure
+
+```
+src/
+  main.rs           cli, top-level flow
+  kvm.rs            ioctl injection, vCPU state reads
+  mem.rs            guest physical memory primitives
+  ptrace_inject.rs  ptrace scaffolding + gadget execution
+  windows.rs        EPROCESS walker, PspCidTable diff
+build.rs            gadget assembly
+```
+
+## refs
+
+- [libvmi](https://github.com/libvmi/libvmi)
+- [hvpp](https://github.com/wbenny/hvpp)
+- [vergiliusproject](https://vergiliusproject.com)
+- Intel SDM Vol 3C ch. 23-33
+- There were alot more I will compile a better list soon 👀