bug(onboarding): seeded default agents have no images on a fresh install — avatar generation needs a Gemini key nobody has yet

[vybe]

Summary

On a fresh install with no keys configured, every seeded default agent renders without an image. Shipped templates declare avatar_prompt and avatars are produced at runtime by the Gemini-backed image generation service, which short-circuits with not_configured when GEMINI_API_KEY is absent — which is the state of every new instance. The default fleet is the first thing a new operator sees, and it arrives blank.

Context

First-run seeding provisions a starter fleet from bundled local: templates, so a fresh install comes up with agents already running. Those templates carry an avatar_prompt (e.g. config/agent-templates/scout/template.yaml) rather than an image, and src/backend/services/image_generation_service.py returns not_configured without a Gemini key — so the generation path that would fill it in never runs.

The result is that the out-of-the-box experience, including on a marketplace install where the operator has configured nothing at all, is a dashboard of identity-less agents.

Acceptance Criteria

• Seeded default agents show an image on a fresh install with no keys configured and no outbound API call at boot
• The approach is a deliberate choice, not a fallback bolted on: either a static image bundled with each shipped template (preferred — deterministic and offline) or a distinctive per-agent placeholder
• avatar_prompt remains the regeneration path once a Gemini key exists; a bundled image must not block an operator from generating a new one
• Covers every agent in the bundled first-run manifest, not only the templates that happen to have prompts today
• Nothing about the default fleet's appearance depends on an external API being reachable

Technical Notes

• Templates: config/agent-templates/*/template.yaml (avatar_prompt)
• Generation service and its not_configured short-circuit: src/backend/services/image_generation_service.py
• Avatar storage: src/backend/db/agent_settings/avatar.py
• First-run seeding: src/backend/services/system_seed_service.py

[obasilakis]

One decision needed before this can be built: where do the bundled images come from?

@vybe — AC2 asks for a deliberate choice ("a static image bundled with each shipped template (preferred) or a distinctive per-agent placeholder"), and that choice determines the whole shape of the fix. Findings from tracing the current path, then the three options.

What happens today

• Agent create seeds the template's avatar_prompt into the DB and marks the agent as having a default avatar (services/agent_service/crud.py:2138 → db.set_default_avatar). It stores the prompt and never generates an image — so a seeded agent has avatar_updated_at set, is_default_avatar=1, and no file. The UI falls back to initials (AgentAvatar.vue).
• There is already a manual catch-up path: Settings → General → Generate Default Avatars (POST /api/agents/avatars/generate-defaults, routers/avatar.py:142, admin-only). It selects every agent with no avatar or a default one, reuses the seeded prompt where there is one, otherwise pulls avatar_prompt/description from the running agent's template.yaml, otherwise falls back to a name-derived robot style.
• Nothing triggers it automatically. Saving a Gemini key fires no regeneration, and on dev the key is read from the environment at import, so it needs a backend restart. (trinity-enterprise#582 resolves the key at call time, so post-feat(onboarding): browser admin claim, one first-run overlay, credentials without a terminal (trinity-enterprise#580, #581, #582) #2715 the button works immediately after the first-run key step.)

So "generate once the operator adds a key" is already possible by hand — but it cannot satisfy AC1 and AC5, which require an image on a fresh install with no keys and no outbound call. It can only be a complement to the fix, never the fix.

What the first-run fleet actually is

config/manifests/default-system.yaml seeds scout, sage and scribe; cornelius is seeded separately from github:Abilityai/cornelius. Only scout and sage declare an avatar_prompt today — which is exactly the gap AC4 names ("every agent in the bundled first-run manifest, not only the templates that happen to have prompts").

The options

1. Generated portraits, committed per template (the ticket's stated preference). Produce the four images once from each template's avatar_prompt, commit avatar.webp next to template.yaml, install it at create time as is_default_avatar=1 so Generate Default Avatars can still overwrite it (AC3 holds). Best-looking and consistent with what an operator gets later from their own key. Cost: it needs a Gemini key to produce them once — there is none in the local .env — and scribe and cornelius need prompts written first.
2. Hand-drawn SVG per agent, reusing the technical-schematic vocabulary approved in trinity-enterprise#581. Offline, themeable, a few KB, no key needed, one visual family with the first-run overlay. Cost: deliberately different in character from the generated portraits an operator sees afterwards.
3. Deterministic per-agent placeholder generated in code (gradient plus glyph derived from the name). Smallest diff, no assets at all, covers any future seeded agent for free. Cost: least distinctive — closest to the initials we have now.

My read: option 1 is what the ticket asks for and is the best result, and it only needs a key once, at authoring time — nothing ships a runtime dependency. Option 2 is the better answer if we would rather not hand-curate four images that a template author will later want to change.

Blocked on this decision; happy to build whichever.

[obasilakis]

Decision taken, no input needed: bundled static image per template (the preferred mechanism), drawn as hand-made schematic glyphs since no Gemini key was available to render the prompts. Installed as a default avatar, so Generate Default Avatars still replaces it. cornelius (seeded from GitHub, not the manifest) is out of scope. PR: #2776