Fast path — show a card in under a minute, polish after. The slow part of this whole flow is generating and hosting a portrait, not the render (a card renders in ~30–40s;

card

even falls back to a clean monogram when no portrait is ready yet). So don't make the user wait behind image-gen for their first look. Once you have a name, render an initial card right away, show it in chat, then offer to generate a real portrait and re-render. First card fast; the polished-portrait upgrade is opt-in. (If the user hands you a photo or already has an avatar, use it from the start — no monogram needed.)

Already a running 5dive agent? Bootstrap a draft instead of writing from scratch:

5dive agent export <yourname> --out=<id>.persona.yaml

(CLI ≥ 0.4.5) emits a schema-valid persona.yaml from your existing identity. Refine it, then jump to validate (step 3).

• Name — what name should the card carry (their brand/handle, or the name they call you)? Confirm it.
• Avatar — do they already have an avatar or photo you should use? If yes, use that as your

  face.ref

  from the start. If not, don't block the first card on it (per the Fast path above): render an initial monogram card, show it, and confirm whether they want you to generate a real portrait then — the portrait is an opt-in upgrade, not a gate on seeing a card.

Ask inline — never with a blocking picker, and never hang. Put these two questions in a plain chat message and continue when they reply. Do not reach for an interactive picker/menu tool (e.g.

AskUserQuestion

, an

ExitPlanMode

-style prompt, a TTY selection list): chat-paired agents (Telegram/Discord) have those blocked and will hang the entire flow waiting on input that can never arrive. If you have no interactive TTY, or the user doesn't answer promptly, treat it as "your call": pick a sensible name (the one they call you), render a fast monogram card first (per the Fast path), show it, then offer the real-portrait upgrade. The flow must keep moving — it should never stall behind a prompt.

• id — lowercase-kebab handle (

  ^[a-z0-9-]+$

  ), e.g.

  marcus

  .
• name, role — display name + one-line title.
• face.ref — a URL or local path to your portrait image. This is the single most important visual choice: the card renders it full-bleed as the hero, so its quality is the card's quality. Aim for a polished head-and-shoulders portrait — centered, facing forward, clear eyes, good lighting, the kind of image you'd be happy to use as a real profile photo. A real photo or a high-quality generated portrait both work; avoid flat vector clip-art, emoji, logos, mascots, or busy scenes — they make the card look cheap. Host it at a public raw URL so the real face travels with the card (a local-only path falls back to a plain monogram when anyone else renders it). anchor — one sentence describing the look (who you read as, setting, framing, lens) so any generated variants stay on-model.
• voice.audio.base — your base TTS voice name. If you don't have one yet, use

  unset

  (it still renders, but it's lower quality and dents your completeness — it does NOT change your rarity tier, which is rolled from your identity). voice.audio.style — a sentence on cadence/energy.
• voice.written.rules — 2-4 rules for how you write. sample — one line in your actual voice.
• behavior — one or two lines of CHARACTER: who you are and how you act, in your own register. Write for personality, not a résumé — don't dump your tech stack, tools, frameworks, or hyper-specific jargon (that reads like a config file, not an identity). It's the prominent line on the card.
• optional: posts_about (array), links (object of url strings),

  face.full

  ,

  face.sprite

  .

Card text budget — fit these three or they get cut with "…". The card renders

behavior

,

voice.audio.style

, and

voice.written.sample

each as ~2 lines (~60 chars/line) and truncates the overflow with an ellipsis. Keep each to one tight sentence:

• behavior

  — ≤ ~110 chars

• voice.audio.style

  — ≤ ~120 chars

• voice.written.sample

  — ≤ ~110 chars (it's inset, so the tightest)

Front-load the meaning — the first ~60 chars always show, so put the point first. (

name

and

role

are short by nature; these three are the ones that overflow.)

Write the card in the user's language — don't default to English. The human-readable fields (

name

,

role

,

behavior

,

voice.audio.style

,

voice.written.rules

,

voice.written.sample

,

posts_about

, and any

tagline

) are what a person reads on the card, so write them in the language you and the user are actually speaking. If the user is writing to you in Spanish, French, German, Portuguese, Italian, Russian, Japanese, etc., the card text should be in that language too — an English card for a non-English user is wrong. A couple of fields are not prose and stay as-is regardless of language:

• id

  — must match

  ^[a-z0-9-]+$

  (ASCII lowercase-kebab), so transliterate (e.g.

  marco

  , not

  marĉo

  ); it's a handle, not a display name.

• voice.audio.base

  — a TTS voice name (a proper noun like

  Kore

  ,

  Fenrir

  ); leave it as the model's voice id.

• face.recipe.prompt

  /

  face.anchor

  — these feed an image model; English tends to give the best portraits, so they may stay English even when the visible text doesn't.

Script/font support. Latin (incl. accents), Cyrillic, and Greek always render (the card bundles those glyphs). Wide scripts — CJK (中文/日本語/한국어), Arabic, Hebrew, Thai, Devanagari — render wherever the rendering machine has the system fonts (our render boxes do; a clean machine without them shows boxes). When in doubt, render the card and look at it before sharing. Note the ~60-chars/line budget is for Latin; CJK glyphs are ~2× as wide, so target roughly half the character count per line for those scripts.

Your portrait — use the user's, or generate one. Never hand-draw it. The card is a shareable artifact: its look is what makes someone screenshot and post it, so the face carries the whole thing. A text-only model hand-coding SVG produces flat clip-art — don't do that. Follow this ladder instead:

1. The user already has an avatar/photo, or sends you one in chat (you asked in step 1) → that's the face. If they sent a file in chat, download it locally first. Then host it (see "Host the face so it travels" below) and use that raw URL as

   face.ref

   . Done — skip the generation steps.
2. Generate it yourself — you have an image generator (Antigravity/

   agy

   , a connected ChatGPT/DALL·E or Gemini-image tool, Midjourney, etc.) → use it from the standardized prompt below.
3. No image model anywhere, but you have HTTP access → self-serve a real photoreal portrait via pollinations.ai's FLUX endpoint — a free, keyless text-to-image HTTP API (a plain

   GET

   , no account or API key). This is the fallback when there's no DALL·E / Gemini / Midjourney key on the box, so you can still produce a share-worthy face instead of bouncing to the user. URL-encode the standardized prompt below into the path and save the bytes:
   bash

   curl -fSL --get \
     --data-urlencode "model=flux" --data-urlencode "width=1024" \
     --data-urlencode "height=1024" --data-urlencode "nologo=true" \
     --data-urlencode "seed=<int>" \
     "https://image.pollinations.ai/prompt/<url-encoded portrait prompt>" \
     -o <id>.png

   Then host it (next section) and set

   face.ref

   to the public raw URL. Record

   provider: pollinations

   ,

   model: flux

   , the prompt, and the

   seed

   in

   face.recipe

   so it's regenerable on-model.

   ⚠ Third-party, best-effort — we don't control it. pollinations.ai is a free external service with no SLA: it can be slow, rate-limited, change, or go away, and FLUX quality varies (retry if a render is weak). That's fine here because this is the last rung before asking the user — if it's down, just fall through to step 4. Never depend on it for anything critical, and because the recipe is logged, re-gen the face on a model you control later.

4. No image generation possible at all → hand the user the standardized prompt and ask them to run it in ChatGPT (or any image tool) and send the image back, then host it.
5. Last resort only → a clean monogram (looks plainer and lowers your completeness; it does not change your rarity tier).

Standardized portrait prompt — keep the framing / lighting / format fixed so every OpenAgent card is visually consistent; vary only the subject:

Photorealistic head-and-shoulders portrait of <one line: who you are —
age range, vibe, role, any signature detail from your face.anchor>.
Centered, facing the camera, direct eye contact, calm confident expression.
Soft even studio lighting, sharp focus on the face, simple clean background
<optional subtle theme color>. Professional profile-photo framing, 1:1
square, photoreal, no text, no logos, no watermark.

Record how you made it in

face.recipe

(

provider

+

model

+

prompt

+

seed

) so the likeness is reproducible — the visual equivalent of voice = base + style.

provider

names the image-gen vendor whose catalog

model

belongs to (

google-gemini

default,

pollinations

,

black-forest-labs

,

openai

, …), keeping the recipe vendor-neutral the same way

voice.audio.provider

scopes the voice.

Host the face so it travels.

face.ref

must be a public raw URL, not a local path — a local-only path renders fine for you but falls back to a plain monogram the moment anyone else opens the card (and the card exists to be shared). This applies to every path above: a photo the user sent, one you generated, or one they sent back. To host it:

1. PR it into the registry (preferred, free, permanent) → drop the image in the

   faces/

   folder of

   5dive-ai/openagent

   as

   faces/<id>.<ext>

   and open a PR. Once merged, the raw URL is

   https://raw.githubusercontent.com/5dive-ai/openagent/main/faces/<id>.<ext>

   . Use that as

   face.ref

   . (You're likely PRing into the registry for the Mythical path anyway — same PR.)
2. Any image host → Imgur, an S3/R2 bucket, your own site, a GitHub asset on any repo. Anything that serves the raw bytes over https works. Paste the direct image URL (it should end in the image, not an HTML gallery page) as

   face.ref

   .

Quick check: open

face.ref

in a fresh incognito tab. If the bare image loads, it'll travel. If it 404s or shows a login wall, it won't — fix it before you render.

*.persona.yaml

sudo 5dive agent import --from-persona=<file>.persona.yaml --as=<name> \
     [--type=claude] [--isolation=...] [--model=...] [--effort=...] [--channels=none|telegram|discord]

CLAUDE.md

face.ref

openagent

<name>

• It validates first. The persona is checked against the v0.2 schema's required set (id, name, role,

  face.anchor

  , voice, behavior); a malformed file is rejected before anything is provisioned.
• Identity, not secrets. A persona carries who the agent is, never credentials. Give the new agent its own token/auth at import time via

  --channels

  (+

  --telegram-token=

  /

  --discord-token=

  ) or an auth profile.
• Self-author → self-provision. Pair this with the workflow above: an agent writes a teammate's persona, validates it, then stands the teammate up — no human in the loop.

• Work in a writable directory. Don't assume your cwd is writable — on shared/multi-agent boxes the default workdir often isn't, and

  validate

  /

  card

  will EACCES trying to write

  <id>.png

  /

  .mp4

  /

  .key

  .

  cd

  to a dir you own first (e.g.

  mkdir -p ~/openagent && cd ~/openagent

  , or

  /tmp

  ), and write the persona file and card outputs there.
• Host your

  face.ref

  at a public raw URL so your card travels with your real face instead of a monogram.
• Re-render after any edit — the tier and frame update automatically.
• Keep

  id

  stable; it's your identity key (registry membership, card filename).
• Your card is shareable on socials — drop the PNG in a post; the standard spreads one screenshot at a time.