Create an agent avatar

Use the toolkit's existing character brief, shared house style, generator, and profile publisher. Preserve durable identity separately from rendering so the roster can be restyled without redesigning every character.

Inspect the identity first

Read the agent's AGENTS.md, profile.json, and avatar.md. Read design-system.md when drafting or substantially revising the character. Use the real job and persona as evidence; do not design from the name alone.

Keep these layers separate:

• avatar.md owns role metaphor, silhouette, signature prop, wardrobe and palette intent, background hue, expression, posture, and one role-specific joke.
• packages/cli/src/avatar-house-style.txt owns composition, line, lighting, crop, and the rest of the shared rendering system.
• profile.json selects avatar.svg or avatar.png for publication.

Do not copy the house style into each brief. Do not reduce identity to hex colors or model-specific prompt syntax.

Design for recognition

Make the avatar pass all of these tests:

• The face, silhouette, signature prop, and joke read in a 32 px circular crop.
• Eyes remain open and visible; props route behind or beside the face.
• The expression and posture match the behavioral persona.
• The silhouette remains distinct in grayscale.
• A total art-style swap leaves the character recognizable.
• No text, logo, detailed scenery, or decorative frame is needed for recognition.

Prefer one strong prop and one visual joke over many small clues. Keep humor warm and tied to the work, not to protected traits or humiliation.

Generate new artwork

For a new guided agent, the integrated flow is the user's to run in their own terminal:

./bin/sageox-agent create --name <agent-name>

The guided flow generates three candidates and pauses for a human selection. Selecting between candidates needs a terminal, so more than one candidate is something you hand to the human to run — asking for several from a tool shell fails with multiple avatar candidates need an interactive terminal for selection.

Generate one candidate yourself:

./bin/sageox-agent create --name <agent-name> \
  --generate-avatar --avatar-candidates 1 --non-interactive

The CLI requests high-quality 1024×1024 PNG output, then resizes it to 512×512 and quantizes its palette (keeping alpha) before writing avatar.png and updating profile.json — chat-icon scale, small enough to commit alongside avatar.md. It does not crop the square portrait to a circle; that stays a chat client's job, deliberately (see prepareAvatarForUpload in register.ts for why — an image model draws a visibly different ring on every render, so that geometry belongs in code, not the prompt, the day this toolkit wants one). Use --starter-avatar for an offline SVG.

Generation needs OPENAI_API_KEY, and the key is the user's to supply. --non-interactive reads it only from the environment and fails with --generate-avatar needs OPENAI_API_KEY when it is unset. That error is the handoff: ask the user to export the key in the shell that runs the command, and rerun. Never ask for the value in chat, never pass it as an argument or an inline OPENAI_API_KEY=… ./bin/sageox-agent … prefix, and never write it to a file — the CLI deliberately uses it for the one request and does not save it.

Replace existing artwork

Edit the existing avatar.md, then deliberately regenerate:

./bin/sageox-agent create --name <agent-name> \
  --generate-avatar --avatar-candidates 1 --non-interactive --replace-avatar

When the user wants a choice instead, ask them to run --generate-avatar --avatar-candidates 3 --replace-avatar in their own terminal and pick from the prompt.

Do not pass new profile fields when changing only artwork. Do not use --replace-avatar unless the user authorized replacing the selected image. Preserve the existing image when all candidates fail review.

Review and publish

Read review-and-publish.md. Review every candidate at full size, at 32 px, and in a circular crop before selection. A single candidate skips the prompt and lands directly at <agents-home>/<agent-name>/avatar.png, so review that file and regenerate with --replace-avatar rather than publishing artwork you have not looked at. Fix the durable brief when the identity is wrong; fix the shared style only when the same rendering failure affects the roster.

Generation is local. Publish only when the user explicitly asks:

./bin/sageox-agent identity register buzz --agent <agent-name> --relay <wss-url>
./bin/sageox-agent identity register slack --agent <agent-name> --app-id <app-id>

Slack publication needs a one-time SLACK_CONFIG_TOKEN exported by the user; it is never saved and never yours to collect.

Verify the published profile on the destination surface. Report whether artwork was only generated, selected locally, or also uploaded.