diff --git a/README.md b/README.md
new file mode 100644
index 0000000..62f5107
--- /dev/null
+++ b/README.md
@@ -0,0 +1,77 @@
+# dotfiles
+
+Chezmoi source tree for a Linux desktop — Hyprland (with a Niri alternative),
+Quickshell/Waybar, Neovim, and a Zsh/Nushell shell, themed end-to-end with the
+custom **apex-neon** (dark) / **apex-aeon** (light) palettes.
+
+> This README is `.chezmoiignore`d — it documents the repo for humans and is
+> never applied to `$HOME`.
+
+## Quick start
+
+```bash
+chezmoi diff          # preview pending changes
+chezmoi apply         # render templates and apply to $HOME
+chezmoi status        # show managed file status
+```
+
+After applying, reload the affected tool — `hyprctl reload`, restart Waybar /
+Quickshell, re-source Zsh, etc.
+
+## File naming (chezmoi)
+
+| Prefix / suffix | Meaning |
+|---|---|
+| `dot_` | leading `.` (e.g. `dot_config/` → `~/.config/`) |
+| `executable_` | sets the executable bit |
+| `private_` | restricts permissions (600/700) |
+| `symlink_` | creates a symlink |
+| `.tmpl` | Go template rendered at apply time |
+| `##hostname.<name>` | host-specific variant |
+
+## Template data model (`~/.config/chezmoi/chezmoi.toml`, per-machine, untracked)
+
+Machine traits are split from structured config:
+
+- **`tags`** — booleans only: `laptop`, `touchscreen`, `pipewire`, `dev`,
+  `bluetooth`. There is no `desktop` tag — the desktop case is `not laptop`.
+- **`compositor`** — `"hyprland"` or `"niri"`.
+- **`apps`** — optional programs present on the machine, e.g.
+  `["steam", "spotify", "jellyfin"]`. Gated with `has "steam" .apps`.
+- **`data.monitors`** — array; each has `name`, optional `primary`, and a
+  `role` (`"primary"`/`"left"`/`"right"`) plus its `workspaces`.
+- **`data.placement`** — app-home workspaces (`id`, `name`, monitor `role`,
+  `apps` = window classes routed there, `silent`, optional
+  `layout`/`layoutopts`/`on_created_empty`/`requires`). A `role` resolves to the
+  monitor that carries it and **falls back to the primary monitor** when that
+  role is absent, so single-monitor machines work with no edits. `requires`
+  drops an entry unless that program is in `apps`.
+- **`data.microphones`** — array, meaningful only when `pipewire = true`.
+
+Window placement (which app opens on which workspace/monitor) is therefore
+data-driven: edit `data.placement`, never hardcode monitor names in templates.
+See `dot_config/hypr/hyprland.d.lua/{workspaces,rules}.lua.tmpl`.
+
+## Layout
+
+- **`dot_config/hypr/`** — Hyprland (v0.55 Lua config). Entry: `hyprland.lua.tmpl`; modular includes in `hyprland.d.lua/`.
+- **`dot_config/niri/`** — Niri compositor (alternative to Hyprland).
+- **`dot_config/quickshell/`** — Quickshell bar/popouts (QML). See its `CLAUDE.md`.
+- **`dot_config/waybar/`** — Waybar config/styles (used under either compositor).
+- **`dot_config/nvim/`** — Neovim (Lua + lazy.nvim).
+- **`dot_config/zsh/`**, Nushell — shells and aliases.
+- **`dot_local/bin/`** — user scripts (`executable_` prefixed).
+- **`.chezmoiscripts/`** — `run_onchange_*` hooks run on `chezmoi apply`.
+
+## Theming — apex
+
+`apex-aeon` (dark) and `apex-neon` (neon) span nvim, zsh, waybar, quickshell,
+alacritty, kitty, ghostty, btop, fuzzel, gtk4, spicetify, swaync, wezterm,
+zathura, zed. Theme files are **not edited by hand** — they're synced from
+`~/Dev/Themes/apex/dist` via `refresh-apex-themes`.
+
+## Agent docs
+
+`CLAUDE.md` / `AGENTS.md` / `GEMINI.md` (root and per-tool) carry conventions and
+the full data-model reference for AI coding agents. They are also
+`.chezmoiignore`d.