From cb81ce73474ec484ab9ac52535341ac53ea461b4 Mon Sep 17 00:00:00 2001
From: Bryan Ramos <bryan@ramos.codes>
Date: Wed, 1 Apr 2026 16:56:54 -0400
Subject: [PATCH] docs: document symlink fragility in maintenance section

---
 README.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/README.md b/README.md
index 5dc86d7..ef5f2fc 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,10 @@ cd ~/Documents/Personal/projects/agent-team
 
 The script symlinks `agents/`, `skills/`, `CLAUDE.md`, and `settings.json` into `~/.claude/`. Works on Linux, macOS, and Windows (Git Bash).
 
+## Maintenance
+
+**Symlink fragility:** `~/.claude/CLAUDE.md` and `~/.claude/settings.json` are installed as symlinks by `install.sh`. Some tools (including Claude Code itself when writing settings) resolve symlinks to regular files on write, silently breaking the link. If edits to the repo are no longer reflected in `~/.claude/`, re-run `./install.sh` to restore the symlinks.
+
 ## Agents
 
 | Agent | Model | Role |