feat: add agent identity avatars (#1329) (thanks @dlauer)

docs/cli/agents.md

@@ -21,3 +21,51 @@ clawdbot agents set-identity --workspace ~/clawd --from-identity
 clawdbot agents set-identity --agent main --avatar avatars/clawd.png
 clawdbot agents delete work
 ```
+
+## Identity files
+
+Each agent workspace can include an `IDENTITY.md` at the workspace root:
+- Example path: `~/clawd/IDENTITY.md`
+- `set-identity --from-identity` reads from the workspace root (or an explicit `--identity-file`)
+
+Avatar paths resolve relative to the workspace root.
+
+## Set identity
+
+`set-identity` writes fields into `agents.list[].identity`:
+- `name`
+- `theme`
+- `emoji`
+- `avatar` (workspace-relative path, http(s) URL, or data URI)
+
+Load from `IDENTITY.md`:
+
+```bash
+clawdbot agents set-identity --workspace ~/clawd --from-identity
+```
+
+Override fields explicitly:
+
+```bash
+clawdbot agents set-identity --agent main --name "Clawd" --emoji "🦞" --avatar avatars/clawd.png
+```
+
+Config sample:
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "main",
+        identity: {
+          name: "Clawd",
+          theme: "space lobster",
+          emoji: "🦞",
+          avatar: "avatars/clawd.png"
+        }
+      }
+    ]
+  }
+}
+```

docs/gateway/configuration.md

@@ -402,13 +402,23 @@ If set, Clawdbot derives defaults (only when you haven’t set them explicitly):
 - `agents.list[].groupChat.mentionPatterns` from the agent’s `identity.name`/`identity.emoji` (so “@Samantha” works in groups across Telegram/Slack/Discord/iMessage/WhatsApp)
 - `identity.avatar` accepts a workspace-relative image path or a remote URL/data URL. Local files must live inside the agent workspace.
 
+`identity.avatar` accepts:
+- Workspace-relative path (must stay within the agent workspace)
+- `http(s)` URL
+- `data:` URI
+
 ```json5
 {
   agents: {
     list: [
       {
         id: "main",
-        identity: { name: "Samantha", theme: "helpful sloth", emoji: "🦥", avatar: "avatars/sam.png" }
+        identity: {
+          name: "Samantha",
+          theme: "helpful sloth",
+          emoji: "🦥",
+          avatar: "avatars/samantha.png"
+        }
       }
     ]
   }

docs/reference/templates/IDENTITY.md

@@ -11,8 +11,12 @@ read_when:
 - **Creature:** *(AI? robot? familiar? ghost in the machine? something weirder?)*
 - **Vibe:** *(how do you come across? sharp? warm? chaotic? calm?)*
 - **Emoji:** *(your signature — pick one that feels right)*
-- **Avatar:** *(workspace-relative path, or a URL/data URL)*
+- **Avatar:** *(workspace-relative path, http(s) URL, or data URI)*
 
 ---
 
 This isn't just metadata. It's the start of figuring out who you are.
+
+Notes:
+- Save this file at the workspace root as `IDENTITY.md`.
+- For avatars, use a workspace-relative path like `avatars/clawd.png`.