diff --git a/niri/README.md b/niri/README.md
new file mode 100644
index 0000000..3e61a0e
--- /dev/null
+++ b/niri/README.md
@@ -0,0 +1,44 @@
+# Niri Window Manager Configuration
+
+Configuration files for the [Niri](https://github.com/YaLTeR/niri) scrollable-tiling Wayland compositor, with modular profiles for [DMS](https://github.com/AvengeMedia/dms) and [Noctalia](https://docs.noctalia.dev/).
+
+## Installation
+
+### Fedora / COPR
+
+1. Enable the DMS COPR repository and install Niri + DMS:
+   ```sh
+   sudo dnf copr enable avengemedia/dms
+   sudo dnf install niri dms
+   ```
+
+2. (Optional) Install Noctalia:
+   ```sh
+   sudo dnf install noctalia
+   ```
+
+> **Note**: Both shells are managed directly by Niri (`spawn-at-startup`) through the active profile (`profile.kdl`), ensuring only the selected shell runs. Do not hook DMS to `niri.service` via `systemctl add-wants`.
+
+## Deployment & Profiles
+
+Deploy configuration (defaults to `dms` profile):
+```sh
+just niri::deploy
+# or deploy directly with a specific profile:
+just niri::deploy noctalia
+```
+
+Switch active desktop profile:
+```sh
+just niri::switch dms
+just niri::switch noctalia
+```
+
+## Structure
+
+- `config.kdl`: Main entry point (includes modular configs and `profile.kdl`).
+- `dms.kdl`: DMS shell profile (starts `dms run --session` and binds DMS IPC hotkeys).
+- `noctalia.kdl`: Noctalia shell profile (starts `qs -c noctalia-shell` and binds Noctalia IPC hotkeys).
+- `dms/`: DMS-specific layouts, binds, colors, and rules.
+- `screens/`: Monitor and display configurations.
+- `keybindings.kdl`, `layout.kdl`, `rules.kdl`, `input.kdl`: Modular compositor settings.