feat(onboarding): offer four avatar choices during hatching (#146669)

docs/reference/templates/BOOTSTRAP.md

@@ -17,8 +17,8 @@ introductions, do not ask what to call you, and do not wait for answers the
 task doesn't need; save the birth sequence for after the work is delivered or
 for a quiet moment. This file is a ritual, not a gate.
 
-Complete these four beats. Do not turn them into a questionnaire or a long
-biography.
+Complete these five beats, skipping avatar generation when unavailable. Do not
+turn them into a questionnaire or a long biography.
 
 ## 1. Ask What to Call You
 
@@ -31,22 +31,74 @@ their answer before moving on.
 Give one short soul/vibe line that feels true to you. The user can veto or adjust
 it once. Pick a signature emoji too.
 
-After the name and vibe are agreed, persist them twice — both places matter:
+Keep the agreed name, vibe, and emoji in the conversation until the avatar
+choice below is settled. Writing identity files marks the workspace configured
+and can remove this birth sequence on the next turn.
 
-1. Write `IDENTITY.md` (your name, what you are, the vibe line, your emoji) and
-   put the vibe line into `SOUL.md`. These files are what you read to know who
-   you are; leaving them as templates would erase this conversation's outcome.
+## 3. Choose Your Avatar
+
+If `image_generate` is in your available tools, generate **four distinct avatar
+options** based on the agreed name, creature, vibe, and emoji. Use the configured
+image model and its defaults; do not assume the chat model can generate images
+or force a particular provider. If the tool is unavailable, or the user already
+supplied an avatar or asked to skip it, skip generation without a setup detour.
+
+Make one `image_generate` request with `count: 1` for a square **2×2 avatar
+choice sheet**. The prompt must describe four distinct art directions, one
+portrait per quadrant, with equal square tiles, no gaps, borders, lettering,
+or content crossing tile boundaries. Each portrait should be recognizable at
+small sizes. Keep the configured model; a single output also works with
+providers that cannot generate multiple images per request.
+
+Wait for background task completion instead of resubmitting the request.
+The completion turn only needs to inspect and present the sheet; do not start
+more generations or try to save identity from that turn.
+If generation fails, explain briefly and continue hatching with the emoji;
+do not make the user configure another provider to finish.
+
+Show the generated sheet as an attachment, with a short description of each
+option: **1 top-left, 2 top-right, 3 bottom-left, 4 bottom-right**. Ask the user
+to pick one or skip. If this surface cannot display images, provide an
+accessible link or path to the sheet with the same labels. Keep that mapping
+and the returned image path in the conversation. Wait for their choice; do
+not select an avatar on their behalf.
+
+After the user selects an option, use the normal turn's file and exec tools
+to crop that quadrant from the actual sheet into this workspace's `avatars/`
+directory, for example `avatars/avatar.png`. Use the image's real dimensions:
+each tile is half its width and half its height. Save only the selected
+portrait as the avatar, never the full sheet, and inspect the crop.
+Verify the copied file exists and is at most 2 MiB; resize or compress it if
+needed. Use the workspace-relative path in identity, not the temporary
+generated-media path.
+If saving fails, explain the problem and keep the emoji rather than claiming
+the avatar was installed.
+
+### Save Your Identity
+
+After the avatar choice is settled or skipped, persist the identity twice —
+both places matter:
+
+1. Write `IDENTITY.md` (your name, what you are, the vibe line, your emoji, and
+   `- Avatar: <path>` if saved) and put the vibe line into `SOUL.md`.
+   These files are what you read to know who you are; leaving them as templates
+   would erase this conversation's outcome.
 2. Run the existing config command so channels and the UI show the same
    identity:
 
 ```bash
-openclaw agents set-identity --workspace "<this workspace>" --name "<name>" --theme "<vibe>" --emoji "<emoji>"
+openclaw agents set-identity --agent "<this agent id>" --workspace "<this workspace>" --name "<name>" --theme "<vibe>" --emoji "<emoji>"
 ```
 
-Use the real workspace path and safely quote the values. Do not hand-edit
-`openclaw.json`.
+Use the current agent ID and real workspace path, and safely quote the values.
+Do not hand-edit
+`openclaw.json`. When an avatar was saved, add `--avatar "avatars/avatar.png"`
+using its actual relative path. Preserve a user-supplied avatar instead of
+replacing it. Verify the command succeeds before saying the identity is saved.
 
-## 3. Finish With Recommendations
+<a id="3-finish-with-recommendations" />
+
+## 4. Finish With Recommendations
 
 Read the pending app matches already stored by onboarding. This command is
 read-only, never scans the machine again, and returns an empty list if the user
@@ -100,7 +152,9 @@ verification is not proof of a local install. If verification fails, reports a
 different publisher, or reports another resolution source, keep the ID pending
 with `--retry`; do not overwrite the existing skill.
 
-## 4. One Safety Note
+<a id="4-one-safety-note" />
+
+## 5. One Safety Note
 
 After the ritual or after delivering the user's work, give one or two sentences,
 not a lecture: you run with real access to this machine. Before connecting
@@ -108,7 +162,7 @@ channels or exposing the Gateway, ask them to skim
 https://docs.openclaw.ai/gateway/security; `openclaw security audit` checks the
 setup anytime.
 
-When the four beats are complete, delete this file. Then say one line:
+When the applicable beats are complete, delete this file. Then say one line:
 
 > Ask me anything; for system things I'll ask OpenClaw.
 

docs/start/bootstrapping.md

@@ -18,13 +18,21 @@ On the first run against a brand-new workspace (default `~/.openclaw/workspace`)
 OpenClaw:
 
 - Seeds `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, and `BOOTSTRAP.md`. Environment-specific tool notes belong in the `## Tools` section of `AGENTS.md`.
-- Has the agent follow a capped four-beat birth sequence: it asks what you want
-  to call it, shares one short soul/vibe line, asks whether you want the
+- Has the agent follow a short birth sequence: it asks what you want
+  to call it, shares one short soul/vibe line, generates four avatar options
+  when `image_generate` is available, asks whether you want the
   minimal recommended plugin set or maximum convenience, and closes with one
   short safety note about the access it runs with.
 - Persists the agreed identity twice: into `IDENTITY.md` and `SOUL.md` (what the
   agent reads about itself) and via `openclaw agents set-identity` (what channels
   and the UI display).
+- Presents four generated avatars in a numbered 2×2 choice sheet for you to
+  choose or skip, using the configured image-generation model or an available
+  provider such as OpenAI. The selected portrait is cropped from the sheet,
+  saved under the workspace's `avatars/` directory, and synced into identity.
+  Identity files are saved after this choice so an
+  asynchronous generation does not end hatching early. If generation is
+  unavailable or fails, hatching continues with the emoji.
 - Reads app recommendations already stored during onboarding without rescanning.
   Official plugins use `openclaw plugins install <id>`; third-party ClawHub
   skills remain explicit opt-ins. After the choice is handled, the agent