diff --git a/AGENTS.md b/AGENTS.md
index 52984b1..d0570ec 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -16,12 +16,30 @@ This repo is managed by **Sigil**, a minimal symlink-based dotfile tool.
 ~/.dotfiles/
   <package>/
     config.lua
-    files/
-      ...
+    files/              # common files (all OSes)
+    files.linux/        # Linux-specific overrides
+    files.macos/        # macOS-specific overrides
+    files.windows/      # Windows-specific overrides
 ```
 
 Each package has a `config.lua` that defines its target path per OS.
 
+### Per-OS file variants
+
+Create `files.<os>/` directories alongside `files/` for OS-specific overlays:
+
+```
+pi-agent/
+  files/
+    settings.json       # shared config
+  files.linux/
+    agent.json          # Linux-specific
+  files.macos/
+    agent.json          # macOS-specific
+```
+
+On Linux, `agent.json` links to `files.linux/agent.json`. On macOS, it links to `files.macos/agent.json`. Files in `files/` are applied first, then OS-specific variants overlay on top.
+
 ## Common commands
 
 - `sigil apply` — apply symlinks (prompts for stale links)
@@ -58,6 +76,14 @@ sigil unlink ~/.config/wezterm/wezterm.lua
 
 When editing dotfiles, it is preferred to add/edit the files in this project directly, instead of going to the source. this way we can then use sigil apply --prune, and everything will be synced, even when there are new files.
 
+## IMPORTANT: Update AGENTS.md files when Sigil changes
+
+Whenever Sigil is modified (new features, behavior changes, new commands), you MUST update the AGENTS.md documentation in BOTH locations:
+1. Sigil repo: `/home/thomasgl/programming/sigil/AGENTS.md`
+2. This dotfiles repo: `/home/thomasgl/.dotfiles/AGENTS.md`
+
+Keep them in sync so agents have correct instructions regardless of which directory they're working in.
+
 # pi extensions
 
 Extensions live in `pi/files/agent/extensions/`.