docs: per-host overrides shipped — spec decisions, host-tier docs, task close-out

1 files changed, 7 insertions, 1 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
index b3c965d..03da278 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -35,13 +35,19 @@ make test-vm-base  # Create the base VM only
 Dotfile stow operations live in the dotfiles repo's own Makefile, not here.
 Run them from `~/.dotfiles`:
 ```
-cd ~/.dotfiles && make stow hyprland     # common + hyprland
+cd ~/.dotfiles && make stow hyprland     # common + hyprland + host tier
 cd ~/.dotfiles && make restow hyprland   # refresh links after git pull
 cd ~/.dotfiles && make reset hyprland    # fix conflicts, keep repo version
 cd ~/.dotfiles && make unstow hyprland   # remove symlinks
 cd ~/.dotfiles && make import common     # fzf select → import to common/
 cd ~/.dotfiles && make test              # run the dotfile-script unit suites
 ```
+Per-host overrides live in a stow tier named after the machine (`ratio/`,
+`velox/`), auto-included by every stow target when the directory exists
+(`HOST=<name>` overrides detection; hostname binary is absent — `uname -n`).
+The tier holds only files no shared package owns: hypr `conf.d/local.conf`
+(velox: HiDPI scale + XWayland toolkit env), `pypr/config.toml`, and foot's
+`host.ini` (the shared foot.ini sets no font — it's per-host via include).
 
 ## Dotfiles Repository