diff --git a/docs/turn-loop.md b/docs/turn-loop.md
index 2661d308..48348b4a 100644
--- a/docs/turn-loop.md
+++ b/docs/turn-loop.md
@@ -291,6 +291,23 @@ write_settings, write_system_prompt, run_turn, drive_turn,
 emit_turn_end, wait_for_login, compact_session}` so the two binaries
 can't drift.
 
+### Agent icon
+
+```nix
+hyperhive.icon = ./icon.svg;  # default: null (falls back to shared hyperhive logo)
+```
+
+Path to an SVG file used as this agent's visual identity — shown in
+the per-agent page header, as the page favicon, and uploaded to the
+agent's Forgejo profile avatar (via the `forge-avatar-sync` boot
+unit) and Matrix profile avatar (via `matrix-avatar-sync`). Commit
+the SVG next to `agent.nix` in the config repo and reference it as a
+relative path.
+
+When `null` (the default), the agent falls back to the shared
+hyperhive branding mark. The harness serves whichever icon is active
+at `GET /icon` on the per-agent web port.
+
 ### `user.passwordlessSudo`
 
 ```nix