docs(claude): document the external dotfiles repo and migration

Phase 2 moved the dotfiles into their own repo at git.cjennings.net/dotfiles.git, so a fresh install clones DOTFILES_REPO to ~/.dotfiles and stows per DESKTOP_ENV. I documented that, the DOTFILES_REPO/BRANCH/DIR config keys, the DOTFILES= Makefile override, the post-install pull-and-restow flow, and the steps to migrate an existing machine off the in-repo dotfiles/.

The migration note calls out quitting Hyprland first: unstowing while it runs makes it write a stub hyprland.conf into the gap, which blocks the restow. The in-repo dotfiles/ stays until ratio and velox migrate, then it gets removed.

1 files changed, 41 insertions, 3 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
index 06c6d4a..ab6ef02 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -11,9 +11,9 @@ init                   Bootstrap script for live ISO
 Makefile               GNU Stow operations for dotfile management
 todo.org               Active task list
 
-dotfiles/common/       Shared dotfiles for all desktop environments (stowed to ~)
-dotfiles/dwm/          DWM/X11-specific dotfiles
-dotfiles/hyprland/     Hyprland-specific dotfiles
+dotfiles/              In-repo dotfiles (common/, dwm/, hyprland/), being migrated
+                       to a standalone repo — see "Dotfiles Repository" below.
+                       Retained until ratio + velox move to ~/.dotfiles, then removed.
 
 scripts/               Utility scripts (wireguard, post-install, wipedisk, etc.)
 assets/                Reference documents and archived files
@@ -39,6 +39,44 @@ make import common     # fzf select → import to common/
 make import dwm        # fzf select → import to dwm/
 make import hyprland   # fzf select → import to hyprland/
 ```
+Override the stow source with `DOTFILES=`, e.g. `make stow hyprland DOTFILES=~/.dotfiles`
+to stow from the standalone dotfiles repo instead of the in-repo `dotfiles/`.
+
+## Dotfiles Repository
+
+Dotfiles live in their own repo at `git.cjennings.net/dotfiles.git`
+(read: `https://git.cjennings.net/dotfiles.git`, push: `git@cjennings.net:dotfiles.git`).
+A fresh `archsetup` install clones it to `~/.dotfiles` and stows per `DESKTOP_ENV`:
+
+```
+dwm       → common/ + dwm/
+hyprland  → common/ + hyprland/
+none      → minimal/   (standalone headless tree, not common/)
+```
+
+Config keys (in `archsetup.conf`, all optional — defaults shown):
+```
+DOTFILES_REPO=https://git.cjennings.net/dotfiles.git
+DOTFILES_BRANCH=main
+DOTFILES_DIR=   # defaults to the target user's ~/.dotfiles
+```
+
+Pull dotfile changes after install:
+```
+cd ~/.dotfiles && git pull
+cd ~/code/archsetup && make restow hyprland DOTFILES=~/.dotfiles
+```
+
+Migrating an existing machine off the in-repo `dotfiles/`:
+```
+git clone https://git.cjennings.net/dotfiles.git ~/.dotfiles
+cd ~/code/archsetup
+make unstow hyprland                       # remove old symlinks (→ archsetup/dotfiles)
+make stow hyprland DOTFILES=~/.dotfiles    # recreate them (→ ~/.dotfiles)
+```
+**Quit Hyprland first.** Unstowing while Hyprland runs makes it write a stub
+`hyprland.conf` into the gap, which then blocks the restow. Migrate from a TTY,
+or with the session stopped.
 
 ## Dotfile Script Counts
 ```