diff --git a/README.md b/README.md
index 67c9809..faddb7d 100644
--- a/README.md
+++ b/README.md
@@ -210,6 +210,34 @@ MCP tools execute client-side (on whatever machine runs Claude Code or Roo Code)
 
 To route additional models, add entries to the `MODEL_ROUTES` object in `proxy.mjs`. The proxy matches exact model names first, then tries prefix matching, then falls back to the default route (Z.ai / GLM-4.7).
 
+## AI Context Files
+
+This repo includes context files for AI coding agents (Claude Code CLI and Roo Code). There are three levels:
+
+| File | Scope | Loaded when... |
+|---|---|---|
+| `CLAUDE.md` | Project-level | AI agent is working inside this repo |
+| `CONTEXT.md` | Project-level | Referenced from CLAUDE.md; agent reads on demand |
+| `global-claude-md/CLAUDE.md` | User-level | Every AI session, regardless of project |
+
+**`global-claude-md/CLAUDE.md`** is the source of truth for the global file. It gets copied to `~/.claude/CLAUDE.md` on each machine. To update it:
+
+```bash
+# 1. Edit the source in this repo
+vim global-claude-md/CLAUDE.md
+
+# 2. Commit and push
+git add -A && git commit -m "Update global CLAUDE.md" && git push
+
+# 3. Copy to work laptop
+cp global-claude-md/CLAUDE.md ~/.claude/CLAUDE.md
+
+# 4. Copy to mini-server
+scp global-claude-md/CLAUDE.md mini-server:~/.claude/CLAUDE.md
+```
+
+The project-level files (`CLAUDE.md` and `CONTEXT.md`) are picked up automatically when an AI agent opens this repo — no copying needed.
+
 ## Files
 
 | File | Description |