diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6967a1a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,37 @@
+# Dotfiles
+
+Modular personal dotfiles managed with [just](https://github.com/casey/just).
+
+## Philosophy
+
+- **Isolation**: Each tool/service has its own self-contained directory with its configuration and local `Justfile`.
+- **Modularity**: The root `Justfile` imports each component as a `just` module.
+- **Simplicity**: Declarative deployment recipes using symbolic links or build steps.
+
+## Usage
+
+List all available modules and commands:
+```sh
+just
+```
+
+Deploy a specific configuration:
+```sh
+just <service>::deploy    # e.g., just niri::deploy, just xxh::deploy
+```
+
+Deploy everything:
+```sh
+just all
+```
+
+## Adding a New Configuration
+
+1. Create a dedicated directory: `<service>/`
+2. Place the configuration files inside it.
+3. Create `<service>/Justfile` with a `deploy` recipe.
+4. Register the module in the root `Justfile`:
+   ```just
+   mod <service>
+   ```
+5. Add `just <service>::deploy` under `@all` in the root `Justfile`.