diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6e064e8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,179 @@
+# Debian Bootc Simple
+
+This is a less complex way to create bootc images than the deb-bootc-compose method that mirrors how Fedora does it.
+
+## Prerequisites
+
+- Debian-based system (tested on Debian 13 Trixie)
+- `podman` or `docker` for container operations
+- `qemu-utils` for image format conversion
+- `grub-pc-bin` for bootloader installation
+- `kpartx` for partition management
+- `just` command runner (install with `cargo install just`)
+
+## Quick Start
+
+### 1. Build a QCOW2 Image
+
+```bash
+# Create QCOW2 image from container (default)
+just qcow2
+
+# Create QCOW2 image from chroot
+just qcow2-chroot
+```
+
+### 2. Build Different Formats
+
+```bash
+# ISO image
+just iso
+
+# Raw disk image
+just img
+
+# VMware format
+just vmdk
+
+# VirtualBox format
+just vdi
+
+# All formats at once
+just all
+```
+
+### 3. Customize Image Size
+
+```bash
+# Create 20GB QCOW2 image
+just custom 20 qcow2
+
+# Create 15GB ISO from chroot
+just custom-chroot 15 iso
+```
+
+### 4. Choose Debian Release
+
+```bash
+# Use Debian 14 (Forky)
+just qcow2-chroot-release forky
+
+# Use Debian Sid
+just qcow2-chroot-release sid
+
+# Use environment variable
+DEBIAN_RELEASE=sid just qcow2-chroot
+```
+
+## Build Types
+
+### Container Method (Default)
+Extracts filesystem from a container image:
+```bash
+just qcow2
+```
+
+### Chroot Method
+Builds from a chroot environment:
+```bash
+just qcow2-chroot
+```
+
+## Output Formats
+
+- **QCOW2**: QEMU Copy-On-Write (default)
+- **ISO**: Bootable ISO image
+- **IMG**: Raw disk image
+- **VMDK**: VMware disk format
+- **VDI**: VirtualBox disk format
+
+## Debian Releases
+
+- **trixie**: Debian 13 (Testing) - Default
+- **forky**: Debian 14 (Unstable)
+- **sid**: Debian Sid (Always Unstable)
+
+## VM Testing
+
+Create and boot a VM with the generated image:
+```bash
+just vm
+```
+
+## Configuration
+
+View current configuration:
+```bash
+just config
+```
+
+Check available options:
+```bash
+./create-bootc-image.sh --help
+```
+
+## Cleanup
+
+```bash
+# Clean output files
+just clean
+
+# Clean work directories
+just clean-work
+
+# Clean everything
+just clean-all
+```
+
+## Advanced Usage
+
+### Build Container Only
+```bash
+just build
+```
+
+### Setup apt-cacher-ng for faster builds
+```bash
+just setup-cache
+```
+
+### Test container functionality
+```bash
+just test
+```
+
+## File Structure
+
+- `create-bootc-image.sh` - Main orchestration script
+- `modules/` - Modular components for different build stages
+- `config/defaults.sh` - Configuration defaults
+- `justfile` - Command shortcuts and examples
+- `debian_bootc_dockerfile.txt` - Container definition
+- `debian-bootc-vm.xml` - VM configuration template
+
+## Troubleshooting
+
+If you encounter issues:
+
+1. Check disk space: `df -h`
+2. Clean work directories: `just clean-work`
+3. Verify prerequisites: `which podman qemu-img grub-install`
+4. Check logs in the output directory
+
+## Examples
+
+```bash
+# Basic workflow
+just qcow2
+just vm
+
+# Chroot workflow with custom size
+just custom-chroot 25 qcow2
+just vm
+
+# Multiple formats from chroot
+just all-chroot
+
+# Debian 14 with custom size
+just custom-chroot-release 30 iso forky
+```