diff --git a/README.md b/README.md
new file mode 100644
index 0000000..40aca4b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,114 @@
+# moss
+
+![Architecture](https://img.shields.io/badge/arch-aarch64-blue)
+![Language](https://img.shields.io/badge/language-Rust-orange)
+![License](https://img.shields.io/badge/license-MIT-yellow)
+
+![Moss Boot Demo](etc/moss_demo.gif)
+
+**moss** is a Unix-like, Linux-compatible kernel written in Rust and Aarch64
+assembly.
+
+It features a modern, asynchronous core, a modular architecture abstraction
+layer, and binary compatibility with Linux userspace applications (currently
+capable of running most BusyBox commands).
+
+## Features
+
+### Architecture & Memory
+* Full support for aarch64.
+* A well-defined HAL allowing for easy porting to other architectures (e.g.,
+  x86_64, RISC-V).
+* Memory Management:
+    * Full MMU enablement and page table management.
+    * Copy-on-Write (CoW) pages.
+    * Safe copy to/from userspace async functions.
+    * Kernel and userspace page fault management.
+    * Buddy allocator for physical addresses and `smalloc` for boot allocations
+      and tracking memory reservations.
+
+### Async Core
+One of the defining features of `moss` is its usage of Rust's `async/await`
+model within the kernel context:
+* All non-trivial system calls are written as `async` functions, sleep-able
+  functions are prefixed with `.await`.
+* The compiler enforces that spinlocks cannot be held over sleep points,
+  eliminating a common class of kernel deadlocks.
+
+###  Process Management
+* Full task management including scheduling and task migration via IPIs.
+* Currently implements 49 Linux syscalls; sufficient to execute most BusyBox
+  commands.
+* Advanced forking capabilities via `clone()`.
+* Process and thread signal delivery and raising support.
+
+### VFS & Filesystems
+* Virtual File System with full async abstractions.
+* Drivers:
+    * Ramdisk block device implementation.
+    * FAT32 filesystem driver (ro).
+    * `devtmpfs` driver for kernel character device access.
+
+## `libkernel` & Testing
+`moss` is built on top of `libkernel`, a utility library designed to be
+architecture-agnostic. This allows logic to be tested on a host machine (e.g.,
+x86) before running on bare metal.
+
+* Address Types: Strong typing for `VA` (Virtual), `PA` (Physical), and `UA`
+  (User) addresses.
+* Containers: `VMA` management, generic page-based ring buffer (`kbuf`), and
+  waker sets.
+* Sync Primitives: `spinlock`, `mutex`, `condvar`, `per_cpu`.
+* Test Suite: A comprehensive suite of 230+ tests ensuring functionality across
+  architectures (e.g., validating Aarch64 page table parsing logic on an x86
+  host).
+
+## Building and Running
+
+### Prerequisites
+You will need a nightly Rust toolchain and QEMU for aarch64 emulation.
+
+```bash
+# Install Rust Nightly
+rustup toolchain install nightly
+rustup component add rust-src llvm-tools-preview
+
+# Install QEMU (Ubuntu/Debian)
+sudo apt install qemu-system-aarch64
+```
+
+### Running via QEMU
+
+To build the kernel and launch it in QEMU: 
+
+``` bash
+cargo run --release
+```
+
+
+### Running the Test Suite
+Because `libkernel` is architecturally decoupled, you can run the logic tests on
+your host machine: code Bash
+
+``` bash
+cargo test -p libkernel --target x86_64-unknown-linux-gnu
+```
+
+
+### Roadmap & Status
+
+moss is under active development. Current focus areas include:
+
+* Basic Linux Syscall Compatibility (Testing through BusyBox).
+* Networking Stack: TCP/IP implementation.
+* Scheduler Improvements: Task load balancing.
+* A fully read/write capable filesystem driver (e.g., ext2/4).
+* Expanding coverage beyond the current 49 calls.
+
+## Contributing
+
+Contributions are welcome! Whether you are interested in writing a driver,
+porting to x86, or adding syscalls.
+
+## License
+Distributed under the MIT License. See LICENSE for more information.
diff --git a/etc/moss_demo.gif b/etc/moss_demo.gif
new file mode 100644
index 0000000..86d3468
Binary files /dev/null and b/etc/moss_demo.gif differ