diff --git a/README.md b/README.md
index 241e0a6..a122f2e 100644
--- a/README.md
+++ b/README.md
@@ -84,8 +84,10 @@ Per-agent settings live in each agent's `agent.nix` and are synced to
 the container as environment variables. Common options:
 
 - **`hyperhive.model`** — Claude model for this agent (default: `"haiku"`).
-  Sets `HIVE_DEFAULT_MODEL` in the container; the operator can override
-  at runtime via the per-agent web UI (persisted to state dir).
+  Sets `HIVE_DEFAULT_MODEL` in the container; the harness applies it at
+  boot and it takes priority over any persisted runtime override. The
+  operator can still switch the model at runtime via the per-agent web UI,
+  but that choice is reset by any rebuild that changes this option.
 - **`hyperhive.allowedRecipients`** — List of agent names this agent can
   message (via `send`). If unset, all agents are allowed. Useful to
   restrict an agent to talking only to the manager.