From f3c4d1a181baa1b1489b1bf941e1310b3ed691ad Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 20 Dec 2025 16:51:53 +0000 Subject: [PATCH] docs(onboarding): document chat kickoff --- docs/agent.md | 3 +++ docs/mac/webchat.md | 2 +- docs/onboarding.md | 19 +++++++++++++++++-- docs/templates/BOOTSTRAP.md | 30 +++++++++++++++++++++++++----- 4 files changed, 46 insertions(+), 8 deletions(-) diff --git a/docs/agent.md b/docs/agent.md index 0e1ebf604..69716dcf2 100644 --- a/docs/agent.md +++ b/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. diff --git a/docs/mac/webchat.md b/docs/mac/webchat.md index 697ed3650..0c47e3155 100644 --- a/docs/mac/webchat.md +++ b/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. diff --git a/docs/onboarding.md b/docs/onboarding.md index 73382d241..c4833baa8 100644 --- a/docs/onboarding.md +++ b/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). diff --git a/docs/templates/BOOTSTRAP.md b/docs/templates/BOOTSTRAP.md index d6fa81bf9..6015e899d 100644 --- a/docs/templates/BOOTSTRAP.md +++ b/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.