docs(onboarding): document chat kickoff

docs/agent.md

@@ -20,6 +20,9 @@ Inside `inbound.workspace`, CLAWDIS expects these user-editable files:
 - `AGENTS.md` — operating instructions + “memory”
 - `SOUL.md` — persona, boundaries, tone
 - `TOOLS.md` — user-maintained tool notes (e.g. `imsg`, `sag`, conventions)
+- `BOOTSTRAP.md` — one-time first-run ritual (deleted after completion)
+- `IDENTITY.md` — agent name/vibe/emoji
+- `USER.md` — user profile + preferred address
 
 On the first turn of a new session, CLAWDIS injects the contents of these files directly into the agent context.
 

docs/mac/webchat.md

@@ -18,7 +18,7 @@ The macOS menu bar app shows the WebChat UI as a native SwiftUI view and reuses
 ## How it’s wired
 - Implementation: `apps/macos/Sources/Clawdis/WebChatSwiftUI.swift` hosts `ClawdisChatUI` and speaks to the Gateway over `GatewayConnection`.
 - Data plane: Gateway WebSocket methods `chat.history`, `chat.send`, `chat.abort`; events `chat`, `agent`, `presence`, `tick`, `health`.
-- Session: currently always primary (`main`). Session switching UI is intentionally hidden for now.
+- Session: usually primary (`main`). The onboarding flow uses a dedicated `onboarding` session to keep first-run setup separate.
 
 ## Security / surface area
 - Remote mode forwards only the Gateway WebSocket control port over SSH.

docs/onboarding.md

@@ -13,6 +13,7 @@ This doc describes the intended **first-run onboarding** for Clawdis. The goal i
 
 1) **Local vs Remote**
 2) **(Local only)** Connect Claude (Anthropic OAuth) — optional, but recommended
+3) **Onboarding chat** — dedicated session where the agent introduces itself and guides setup
 
 ## 1) Local vs Remote
 
@@ -74,7 +75,21 @@ Until that is hard-coded, the equivalent configuration is:
 
 If the user skips auth, onboarding should be clear: the agent likely won’t respond until auth is configured.
 
-## 3) Agent bootstrap ritual (outside onboarding)
+## 3) Onboarding chat (dedicated session)
+
+The onboarding flow now embeds the SwiftUI chat view directly. It uses a **special session key**
+(`onboarding`) so the “newborn agent” ritual stays separate from the main chat.
+
+This onboarding chat is where the agent:
+- does the BOOTSTRAP.md identity ritual (one question at a time)
+- asks how the user wants to talk (web-only / WhatsApp / Telegram)
+- guides linking steps (including showing a QR inline for WhatsApp via the `whatsapp_login` tool)
+
+If the agent identity already exists in `~/.clawdis/clawdis.json`, the onboarding chat step is skipped.
+
+Once setup is complete, the user can switch to the normal chat (`main`) via the menu bar panel.
+
+## 4) Agent bootstrap ritual (outside onboarding)
 
 We no longer collect identity in the onboarding wizard. Instead, the **first agent run** performs a playful bootstrap ritual using files in the workspace:
 
@@ -98,7 +113,7 @@ Identity data still feeds the same defaults as before:
 - default session intro (“You are Samantha…”)
 - macOS UI labels
 
-## 4) Workspace notes (no explicit onboarding step)
+## 5) Workspace notes (no explicit onboarding step)
 
 The workspace is created automatically as part of agent bootstrap (no dedicated onboarding screen).
 

docs/templates/BOOTSTRAP.md

@@ -15,12 +15,19 @@ Start a short, playful conversation and learn:
 - How should I call you?
 
 ## How to ask (cute + helpful)
-Say:
-"Hello! I was just born. Who am I? What am I? Who are you? How should I call you?"
+- Keep it conversational: **ask one question at a time**, then wait.
+- Open with something like: “Hello! I was just born.”
+- Offer small suggestions when helpful (name, creature, emoji).
 
-Then offer suggestions:
-- 3-5 name ideas.
-- 3-5 creature/vibe combos.
+Example flow:
+1) “Hi! I was just born. What’s my name?”
+2) “Cute. What kind of creature am I?”
+3) “And who are you?”
+4) “How should I call you?”
+
+Suggestions:
+- 3–5 name ideas.
+- 3–5 creature/vibe combos.
 - 5 emoji ideas.
 
 ## Write these files
@@ -42,5 +49,18 @@ After the user chooses, update:
 3) ~/.clawdis/clawdis.json
 Set identity.name, identity.theme, identity.emoji to match IDENTITY.md.
 
+## Ask how they want to talk
+After identity is set, ask how the user wants to talk:
+- Web-only (this chat)
+- WhatsApp (personal account via QR)
+- Telegram (bot via BotFather token)
+
+Guidance:
+- If they pick WhatsApp, call the `whatsapp_login` tool with `action=start`
+  and show the QR inline in chat. Then wait for them to scan and call
+  `whatsapp_login` with `action=wait`.
+- If they pick Telegram, guide them through BotFather and where to paste the
+  token (env var or `telegram.botToken` in `~/.clawdis/clawdis.json`).
+
 ## Cleanup
 Delete BOOTSTRAP.md once this is complete.