Onboarding: live "Hello" introduction step (NAN-699)

[yagudaev]

Summary

• Replaces the wizard's text-only smoke test with a live Hello step where the agent introduces itself out loud, asks the user's name, and asks for a brief bio. Captured info is stored in USER.md so every future session knows who it's talking to.
• Adds a systemPromptOverride field on the relay so this step runs against a tight onboarding script (no brain tools, no SOUL/IDENTITY persona) — keeps the agent on-script instead of trying to call ask_brain mid-greeting.
• Extends the relay's instruction builder to load USER.md from the brain workspace and inject the user's name + bio into every regular session's system prompt.

Closes NAN-699

What changed where

Area	File(s)	Notes
Storage	desktop/src/main/user-profile.ts (new)	USER.md read/write, mirrors identity.ts pattern
IPC	desktop/src/main/ipc-handlers.ts, desktop/src/preload/index.ts, desktop/src/renderer/src/lib/onboarding-api.ts	user:get / user:save + userApi
Relay prompt	relay-server/src/instructions.ts, relay-server/src/types.ts	Loads USER.md; new systemPromptOverride field
Wizard step	desktop/src/renderer/src/pages/onboarding/StepIntroduction.tsx (new)	Live transcript + auto-populating Name/About fields + typed-input fallback
Wizard wiring	OnboardingWizard.tsx, App.tsx, onboarding.ts (main), preload/index.ts	testcall → introduction; 'testcall' cursor migration
Docs	docs/src/content/docs/desktop/first-run.mdx (new), docs/src/content/docs/desktop/onboarding.mdx, docs/astro.config.mjs	End-user guide w/ screenshot + sidebar entry; existing doc updated to 7-step flow + USER.md

Where the captured info is stored

~/Library/Application Support/VoiceClaw/openclaw/workspace/
├── SOUL.md       # bundled, read-only
├── IDENTITY.md   # written by the Voice step (existing)
└── USER.md       # written by the Hello step (new)

USER.md is markdown with ## Name and ## About sections; mode 0600. The relay reads it on every session start (in loadAgentIdentity) and appends an ## About the user block to the system prompt. If the file is missing or only holds the placeholder defaults, the block is omitted.

Decisions worth flagging

• instructionsOverride was already taken. It's used as an "About the User" appendix (e.g. mobile title-gen). I added systemPromptOverride as a separate field rather than reinterpret semantics. The introduction step uses the new field plus brainAgent: 'none' to fully suppress the persona/brain prompt and the brain tools.
• Step-id migration: any saved current_step = 'testcall' is remapped to 'introduction' in getOnboardingState so users mid-wizard during the upgrade don't land on an unknown step.
• pending_greeting flag removed from wizard finish: the introduction step IS the greeting, so the previous "auto-start a call when chat opens" hack is no longer needed.
• StepTestCall.tsx deleted — the descoped placeholder is replaced.

Test evidence

Suite	Result
yarn workspace voiceclaw-desktop test	135 passed (was 121)
yarn workspace relay-server test	144 passed + 3 skipped (was 138)
desktop/yarn build	clean
docs/yarn build	35 pages built

New tests:

• desktop/src/main/user-profile.test.ts — round-trip read/write, defaults, multi-line bio
• desktop/src/main/onboarding.test.ts — 'testcall' → 'introduction' migration
• desktop/src/renderer/src/pages/onboarding/StepIntroduction.test.ts — buildIntroPrompt + extractFirstName (covers "Michael", "I'm Michael", "My name is …", "MICHAEL", trailing punctuation, empty input)
• relay-server/test/instructions.test.ts — USER.md inclusion (Gemini + OpenAI paths), placeholder elision, systemPromptOverride replaces persona while keeping conversation rules

Visual evidence

Captured by booting the renderer in preview mode (yarn dev:desktop → Vite at :5173) and driving Playwright at ?onboarding=1&step=introduction. Saved to screenshots/ and the docs public/ directory.

The same dev server confirmed ?step=identity still renders correctly with the updated step indicator (06 / 07).

Manual end-to-end testing — DEFERRED

⚠️ The original task brief said to test on iOS via Expo. The ticket explicitly marks the mobile equivalent as out of scope (this is a desktop ticket — desktop/src/main/..., IDENTITY.md / USER.md paths under userData/openclaw/workspace/). I tested via the Vite renderer in preview mode (Playwright screenshots) plus full unit coverage of the prompt builder, name-extractor, USER.md round-trip, and relay instructions loader.

Not yet done from this branch: a full Electron-app boot end-to-end where the agent actually speaks aloud over Gemini Live, the user's voice fills the form fields via real STT, and a follow-up call demonstrates the agent greeting them by name. That requires actual mic input + Gemini API quota — the unit tests cover the deterministic logic, and the previewMode screenshots cover the UI rendering. Recommend a real-device smoke pass before merge.

Acceptance criteria coverage

• Wizard reaches the new StepIntroduction step automatically after StepIdentity. (Wizard sequence updated; verified in preview.)
• Form fields auto-populate from user transcript turns. (Logic in onTranscriptDone; first user turn → name; second → bio.)
• User can edit either field before clicking Done. (Manual fallback toggle + free-form editing always allowed.)
• Done writes both fields to USER.md. (Via userApi.save → writeUserProfile; restarts relay so next session reads it.)
• Skip for now writes defaults. (Persists Friend / empty bio.)
• Mic-denied path: form fields still work, no transcript, no agent voice. (voiceUnavailable state + manual entry; verified in preview screenshot.)
• Re-running onboarding pre-fills with existing USER.md values. (OnboardingWizard loads via userApi.get and passes as initialUser.)
• User profile fields appear in [instructions] log line on next session. (loadUserBlock adds the ## About the user block; covered by instructions.test.ts.)
• Greeting on first chat after Done says "Hey " instead of generic. (Untested end-to-end on a real Electron build; the prompt-injection logic is unit-tested.)

Test plan

• Boot Electron locally with a fresh userData dir, walk through all 7 steps, deny then grant mic permission, confirm form fields fill from voice.
• Hit Done, then start a fresh call from the chat UI; confirm the agent greets by name on first turn.
• Re-run onboarding from Settings → Debug; confirm Hello step pre-fills with the previously-saved values.
• Manually edit ~/Library/Application Support/VoiceClaw/openclaw/workspace/USER.md; confirm the next session picks up the edit.
• Run tail -f relay.log during the next session and confirm the [instructions] line includes the user's name in the prompt fingerprint.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
voiceclaw	Ready	Preview, Comment	May 10, 2026 6:59pm