From 20269873bd5d0594888ecdf7e64420537d7dbc46 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Fri, 5 Jun 2026 18:14:38 +0200
Subject: [PATCH] docs(turn-loop): also document hyperhive.icon option
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

SVG path for per-agent visual identity — used in the page header,
favicon, Forgejo profile avatar (forge-avatar-sync), and Matrix
profile avatar (matrix-avatar-sync).
---
 docs/turn-loop.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

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