diff --git a/README.md b/README.md
index 9d32f98..6b6d12c 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,81 @@
 # fedora-niri-dms
 
-Installer script that turns a minimal Fedora install into a niri + DankMaterialShell desktop
\ No newline at end of file
+An installer script that turns a minimal, terminal-only Fedora install into a complete
+[niri](https://github.com/niri-wm/niri) + [DankMaterialShell](https://danklinux.com) desktop,
+with the DMS login screen.
+
+## Quick start
+
+1. Install Fedora from the **Everything** netinstall ISO and choose
+   **Fedora Custom Operating System** under Software Selection. Create a user with
+   administrative privileges.
+2. Boot to the text login, sign in, and run:
+
+```bash
+curl -fsSL https://<your-gitea-host>/jschantli/fedora-niri-dms/raw/branch/main/fedora-niri-dms-setup.sh -o setup.sh
+bash setup.sh
+```
+
+Run it as your **normal user**, not root. It uses `sudo` when it needs to.
+
+3. Answer the optional questions at the start. The rest runs unattended.
+4. Reboot, pick the **niri** session at the login screen, and sign in.
+
+Press **Super+Shift+/** after logging in to see every keybind.
+
+## What it installs
+
+| Area | Packages / changes |
+| --- | --- |
+| dnf | Parallel downloads, `dnf5-plugins`, full system update |
+| Repos | RPM Fusion (free + non-free), Cisco OpenH264, `avengemedia/dms` COPR |
+| Graphics | Mesa + Vulkan, plus VA-API drivers for AMD, Intel or NVIDIA (auto-detected) |
+| Codecs | Full `ffmpeg` and the multimedia group |
+| Audio | PipeWire, WirePlumber, SOF firmware |
+| Hardware | Bluetooth, `tuned-ppd` power profiles, `fwupd` firmware updates |
+| Desktop | niri, DankMaterialShell, `xwayland-satellite` |
+| Login screen | DMS greeter (greetd), graphical boot target |
+| Essentials | Alacritty, Nautilus, Firefox, desktop portals, GNOME Keyring, Noto fonts, Flatpak + Flathub |
+
+### Optional (asked at the start)
+
+- Steam and gamescope
+- NetworkManager OpenVPN support (for PIA or other `.ovpn` configs)
+- Fingerprint reader setup (Framework laptops)
+- EasyEffects (for Framework's speaker profile)
+
+## Requirements
+
+- Fedora 43 or newer, installed as **Fedora Custom Operating System**
+- An internet connection
+- A GPU with working acceleration
+
+### Testing in a VM
+
+niri needs 3D acceleration, or you'll get a black screen after reboot. Turn it on before
+rebooting:
+
+- **Proxmox:** Display → VirGL GPU (host needs `apt install libgl1 libegl1`)
+- **virt-manager / GNOME Boxes:** Virtio video with 3D acceleration, Spice with OpenGL
+- **VirtualBox:** VMSVGA with Enable 3D Acceleration
+- **VMware:** Accelerate 3D graphics
+
+## Troubleshooting
+
+| Problem | Fix |
+| --- | --- |
+| Black screen after reboot | Ctrl+Alt+F2, log in, then run `niri-session` or `dms greeter status` |
+| DMS bar doesn't appear | Run `dms run` to see the error; check `systemctl --user status dms` |
+| No sound | `systemctl --user status pipewire wireplumber`, then `wpctl status` |
+| Screen sharing shows nothing | Check `xdg-desktop-portal-gnome` is installed, then log out and back in |
+| Keyring asks for a password every login | `sudo authselect enable-feature with-pam-gnome-keyring` and reboot |
+
+## Notes
+
+- The script is safe to re-run; each step checks before changing anything.
+- No HDR yet: niri doesn't support it. HDR gaming needs a separate gamescope session.
+- DMS comes from the stable `avengemedia/dms` COPR, not the faster-moving `dms-git`.
+
+## License
+
+MIT
\ No newline at end of file