From 1d3253b8b756d2c02f6d9c21a71798581659dd8c Mon Sep 17 00:00:00 2001
From: "thomas g. lopes" <thomasgl@pm.me>
Date: Wed, 11 Mar 2026 10:06:01 +0000
Subject: [PATCH] update agents.md with per-OS variants docs and sync note

---
 AGENTS.md | 30 ++++++++++++++++++++++++++++--
 1 file changed, 28 insertions(+), 2 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 7908522..6dc52e8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -7,12 +7,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)
 - `sigil apply --prune` — prune stale links without prompting
@@ -43,3 +61,11 @@ sigil unlink ~/.config/wezterm/wezterm.lua
 ## Development
 - When modifying this repo, rebuild and install the binary: `go build -o ~/.local/bin/sigil .`
 - Bump the version constant in `main.go` for every change (follow semver: bugfix = patch, feature = minor, breaking = major)
+
+## 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. This repo: `/home/thomasgl/programming/sigil/AGENTS.md`
+2. Dotfiles repo: `/home/thomasgl/.dotfiles/AGENTS.md`
+
+Keep them in sync so agents have correct instructions regardless of which directory they're working in.