Document git-submodule wiring into guix-dotfiles in MIGRATION.md

1 files changed, 43 insertions, 15 deletions

diff --git a/MIGRATION.md b/MIGRATION.md
index 0e3f7f4..92f6392 100644
--- a/MIGRATION.md
+++ b/MIGRATION.md
@@ -5,28 +5,56 @@ home-manager flake guix-dotfiles was already using) and pulls Linux desktop
 config that used to live in `guix-dotfiles/home-config/home-configuration.scm`
 into home-manager proper. It does **not** replace Guix itself: package
 management, the system config, and three specific home services stay in
-Guix (see "Stays in Guix" below). Nothing in `guix-dotfiles` has been edited
-by this migration - the changes below are for you to apply by hand.
+Guix (see "Stays in Guix" below).
 
-## 1. Point `home-manager` at this repo
+`nix-combined` is deliberately its own repo (own history, own remote) so
+that darwin machines never need to clone anything guix-related. It's wired
+into `guix-dotfiles` as a **git submodule** at
+`guix-dotfiles/home-config/nix-combined` - the rest of this section covers
+that wiring; everything after "Stays in Guix" is still a plan for you to
+apply by hand.
 
-In `guix-dotfiles/home-config/home-configuration.scm`, `%home-symlinks`
-currently has:
+## 1. Submodule wiring (already done in this working tree)
 
-```scheme
-(".config/guix/home-config/nix-home-manager" ".config/home-manager")
-```
+Already applied, not yet committed/pushed - review with `git status`/`git
+diff` in `guix-dotfiles` before committing:
 
-Change the target to wherever you clone `nix-combined`, e.g.:
+- `guix-dotfiles/.gitmodules` added, pointing `home-config/nix-combined` at
+  **the local filesystem path** to this checkout of `nix-combined`. That
+  only works on this machine. **Before pushing**, create the real remote
+  (recommend `https://git.rschanz.org/nix-combined`, matching the
+  `nix-dotfiles`/`guix-dotfiles` naming convention) and push `nix-combined`
+  there, then run, from `guix-dotfiles`:
+  ```
+  git submodule set-url home-config/nix-combined https://git.rschanz.org/nix-combined
+  git add .gitmodules
+  git commit
+  ```
+- `home-configuration.scm`'s `%home-symlinks` now points
+  `.config/guix/home-config/nix-combined` at `.config/home-manager`
+  (previously `.config/guix/home-config/nix-home-manager`).
+- `deploy.sh`'s fresh-install clone now uses `git clone --recurse-submodules`
+  so a from-scratch deploy pulls `nix-combined` in the same step.
 
-```scheme
-("/path/to/nix-combined" ".config/home-manager")
+**On existing machines**, after pulling this change:
+```
+git submodule update --init --recursive
+```
+(or `git clone --recurse-submodules` next time you clone `guix-dotfiles`
+fresh). Then switch with `home-manager switch --flake ~/.config/home-manager#ryan`
+(the `rebuild` zsh alias does this on Linux).
+
+**Updating `nix-combined` later**: since the submodule pins an exact commit,
+pulling new `nix-combined` changes needs a bump in `guix-dotfiles`:
+```
+cd home-config/nix-combined && git pull origin main && cd -
+git add home-config/nix-combined
+git commit -m "bump nix-combined"
 ```
 
-Then switch with `home-manager switch --flake ~/.config/home-manager#ryan`
-(the `rebuild` zsh alias does this on Linux). The old
-`guix-dotfiles/home-config/nix-home-manager` directory can be deleted once
-you've confirmed the new flake builds and switches cleanly.
+The old `guix-dotfiles/home-config/nix-home-manager` directory (the
+pre-submodule ad-hoc flake) can be deleted once you've confirmed the new
+one builds and switches cleanly.
 
 **Leave the `nix-config` symlink entry alone for the first switch.** It's
 what sets `experimental-features = nix-command flakes` for your user today,