feat: enforce agent icon enum and expose via LLM endpoint

Move icon name list to shared constants with strict enum validation.
Add /llms/agent-icons.txt endpoint, pass icon through hire flow,
and update skills to reference icon discovery step.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

skills/paperclip-create-agent/SKILL.md

@@ -49,8 +49,16 @@ curl -sS "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/agent-configura
   -H "Authorization: Bearer $PAPERCLIP_API_KEY"
 ```
 
-5. Draft the new hire config:
+5. Discover allowed agent icons and pick one that matches the role.
+
+```sh
+curl -sS "$PAPERCLIP_API_URL/llms/agent-icons.txt" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY"
+```
+
+6. Draft the new hire config:
 - role/title/name
+- icon (required in practice; use one from `/llms/agent-icons.txt`)
 - reporting line (`reportsTo`)
 - adapter type
 - adapter and runtime config aligned to this environment
@@ -58,7 +66,7 @@ curl -sS "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/agent-configura
 - initial prompt in adapter config (`bootstrapPromptTemplate`/`promptTemplate` where applicable)
 - source issue linkage (`sourceIssueId` or `sourceIssueIds`) when this hire came from an issue
 
-6. Submit hire request.
+7. Submit hire request.
 
 ```sh
 curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/agent-hires" \
@@ -68,6 +76,7 @@ curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/agent-h
     "name": "CTO",
     "role": "cto",
     "title": "Chief Technology Officer",
+    "icon": "crown",
     "reportsTo": "<ceo-agent-id>",
     "capabilities": "Owns technical roadmap, architecture, staffing, execution",
     "adapterType": "codex_local",
@@ -77,7 +86,7 @@ curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/agent-h
   }'
 ```
 
-7. Handle governance state:
+8. Handle governance state:
 - if response has `approval`, hire is `pending_approval`
 - monitor and discuss on approval thread
 - when the board approves, you will be woken with `PAPERCLIP_APPROVAL_ID`; read linked issues and close/comment follow-up
@@ -120,6 +129,7 @@ For each linked issue, either:
 Before sending a hire request:
 
 - Reuse proven config patterns from related agents where possible.
+- Set a concrete `icon` from `/llms/agent-icons.txt` so the new hire is identifiable in org and task views.
 - Avoid secrets in plain text unless required by adapter behavior.
 - Ensure reporting line is correct and in-company.
 - Ensure prompt is role-specific and operationally scoped.

skills/paperclip-create-agent/references/api-reference.md

@@ -4,6 +4,7 @@
 
 - `GET /llms/agent-configuration.txt`
 - `GET /llms/agent-configuration/:adapterType.txt`
+- `GET /llms/agent-icons.txt`
 - `GET /api/companies/:companyId/agent-configurations`
 - `GET /api/agents/:agentId/configuration`
 - `POST /api/companies/:companyId/agent-hires`
@@ -30,6 +31,7 @@ Request body matches agent create shape:
   "name": "CTO",
   "role": "cto",
   "title": "Chief Technology Officer",
+  "icon": "crown",
   "reportsTo": "uuid-or-null",
   "capabilities": "Owns architecture and engineering execution",
   "adapterType": "claude_local",

skills/paperclip/SKILL.md

@@ -53,7 +53,7 @@ Headers: Authorization: Bearer $PAPERCLIP_API_KEY, X-Paperclip-Run-Id: $PAPERCLI
 
 If already checked out by you, returns normally. If owned by another agent: `409 Conflict` — stop, pick a different task. **Never retry a 409.**
 
-**Step 6 — Understand context.** `GET /api/issues/{issueId}` (includes `ancestors` array — parent chain to root). `GET /api/issues/{issueId}/comments`. Read ancestors to understand _why_ this task exists.
+**Step 6 — Understand context.** `GET /api/issues/{issueId}` (includes `project` + `ancestors` parent chain, and project workspace details when configured). `GET /api/issues/{issueId}/comments`. Read ancestors to understand _why_ this task exists.
 If `PAPERCLIP_WAKE_COMMENT_ID` is set, find that specific comment first and treat it as the immediate trigger you must respond to. Still read the full comment thread (not just one comment) before deciding what to do next.
 
 **Step 7 — Do the work.** Use your tools and capabilities.

skills/paperclip/references/api-reference.md

@@ -55,7 +55,25 @@ Includes the issue's `project` and `goal` (with descriptions), plus each ancesto
     "name": "Auth System",
     "description": "End-to-end authentication and authorization",
     "status": "active",
-    "goalId": "goal-1"
+    "goalId": "goal-1",
+    "primaryWorkspace": {
+      "id": "ws-1",
+      "name": "auth-repo",
+      "cwd": "/Users/me/work/auth",
+      "repoUrl": "https://github.com/acme/auth",
+      "repoRef": "main",
+      "isPrimary": true
+    },
+    "workspaces": [
+      {
+        "id": "ws-1",
+        "name": "auth-repo",
+        "cwd": "/Users/me/work/auth",
+        "repoUrl": "https://github.com/acme/auth",
+        "repoRef": "main",
+        "isPrimary": true
+      }
+    ]
   },
   "goal": null,
   "ancestors": [