diff --git a/README.md b/README.md
index b984b00..009c78e 100644
--- a/README.md
+++ b/README.md
@@ -23,12 +23,18 @@ dot_config/
   kitty/                        kitty terminal + gruvbox themes
   nvim/                         LazyVim + custom plugins
   paru/                         (arch-only) paru config
+  sway/                         sway + wofi + foot configs (desktops only)
+  foot/                         foot terminal config
+  wofi/                         wofi launcher configs + CSS
+  waybar/                       waybar status bar
+  mako/                         (arch-only) mako notification daemon
 
 run_once_00-install-bootstrap-tools.sh.tmpl
 run_once_05-install-hosts.sh.tmpl             merge LAN host entries into /etc/hosts
 run_once_10-add-chaotic-aur.sh.tmpl            (arch-only)
 run_once_20-install-user-packages.sh.tmpl
 run_onchange_30-ensure-cargo.sh.tmpl
+run_once_40-install-sway.sh.tmpl               (desktops only) sway + wofi + foot
 ```
 
 ## Onboarding a new box
@@ -80,6 +86,35 @@ chezmoi apply
 ```
 
 If you skip this step, the omp config files will still land (they're not encrypted), but `zai.key` and `.env` will be missing and omp won't be able to authenticate against providers.
+
+## Sway / Wayland desktop stack
+
+Sway + wofi + foot + waybar + swaybg/lock/idle + grim/slurp + wl-clipboard is opt-in per host. Pis don't get it (headless); x86_64 desktops do automatically.
+
+**Default behavior** (set in `.chezmoi.yaml.tmpl`):
+- `data.sway: true` on hostnames matching `miche`, `byte`, `kaiser` (and any suffix like `byte-arch`)
+- `data.sway: false` on every other host
+
+**Manual override** (per box, takes precedence over hostname rule):
+```bash
+# Force ON (e.g. you set up a new Pi with a screen):
+touch ~/.config/chezmoi/features/sway
+chezmoi apply
+
+# Force OFF (e.g. running a desktop headless as a server):
+touch ~/.config/chezmoi/features/no-sway
+rm -f ~/.config/chezmoi/features/sway
+chezmoi apply
+```
+
+The `run_once_40-install-sway.sh` script:
+- exits 0 with no side effects on non-sway boxes
+- installs `sway wofi foot swaybg swaylock swayidle grim slurp waybar wl-clipboard` via `pacman` (arch) or `apt` (debian)
+- adds `dunst` instead of `mako` on debian (mako isn't packaged for debian)
+- creates the `~/.config/chezmoi/features/sway` marker so subsequent applies know it's enabled
+
+The configs in `dot_config/{sway,foot,wofi,waybar,mako}/` are placed unconditionally — they're harmless on Pis (no tools to read them).
+
 ## Editing dotfiles
 
 ```bash