diff --git a/AGENTS.md b/AGENTS.md
index 9736bc0..826530d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -84,6 +84,30 @@ graph LR
     E --> F[health check]
 ```
 
+## Pi Model Config (`~/.pi/agent/models.json`)
+
+The Pi agent reaches the fleet through `/home/dank/.pi/agent/models.json`.
+This file lives outside the repository. Each provider is one host endpoint.
+Each model `id` is the served alias. The two aliases are
+`frank-default-small` (dankserver `:7770`) and `frank-default-large`
+(dankclaw `:52625`).
+
+The model `id` values are stable. The file
+`/home/dank/.pi/agent/settings.json` references them. Two resolution rules
+apply (verified in `@earendil-works/pi-coding-agent` `model-resolver.js`):
+
+- The default model resolves as a `defaultProvider` + `defaultModel` pair.
+  The `defaultProvider` must name the provider that serves the `defaultModel`.
+- A subagent override uses a bare model `id`. A bare `id` resolves only when
+  it is unique across all providers.
+
+When you rename a service or move a model to a new host, update
+`models.json`. Update the provider key, the model `id`, `contextWindow`, and
+`input`. If the default model moved hosts, also update `defaultProvider` in
+`settings.json`. Set `contextWindow` to the per-slot context (dankserver
+`175104`, dankclaw `262144`). The full schema is in the agent knowledge base
+page `~/.pi/agent/docs/pi/models.md`.
+
 ## Runtime & Troubleshooting
 
 ### FastMTP patched llama.cpp (retired, 2026-08-18)