diff --git a/AGENTS.md b/AGENTS.md
index f340c1f..1f69544 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,7 +2,7 @@
 
 ## Deployed config
 
-`config-example.toml` in the repo root is the canonical config file. It is symlinked into `$XDG_CONFIG_HOME/agent-sandbox/config.toml` on the host. When editing it, remember that changes take effect immediately for all sandbox invocations.
+The live config on the host is deployed by hephaestus from `ansible/roles/agents/templates/agent-sandbox/config.toml.j2`; edit it there. `config-example.toml` in the repo root is only an example for other users.
 
 The config file may set `extra-config = "<absolute path>"` to layer a second file on top using the same merge rules (scalars replace, vecs append, profiles merge by name). A missing extra file is silently skipped; nesting is not supported (the extra file cannot itself set `extra-config`).
 
diff --git a/config-example.toml b/config-example.toml
index 29c50a9..f68f2d0 100644
--- a/config-example.toml
+++ b/config-example.toml
@@ -53,6 +53,11 @@ env = [
 
 profile = ["claude", "audio"]
 
+# The agent profiles expect CLAUDE_CONFIG_DIR, CODEX_HOME and
+# PI_CODING_AGENT_DIR to point inside their rw dirs. Claude Code writes
+# .claude.json beside CLAUDE_CONFIG_DIR, so set it one level deeper, e.g.
+# ~/.config/claude/claude.
+
 [profiles.claude]
 ro = ["~/.local/share/claude-code"]
 rw = ["~/.config/claude"]