docs(onboarding): add bootstrapping page (#9767)

docs/docs.json

@@ -745,7 +745,7 @@
                   "start/getting-started",
                   {
                     "group": "Onboarding",
-                    "pages": ["start/wizard", "start/onboarding"]
+                    "pages": ["start/wizard", "start/onboarding", "start/bootstrapping"]
                   },
                   "start/pairing"
                 ]

docs/start/bootstrapping.md

@@ -0,0 +1,41 @@
+---
+summary: "Agent bootstrapping ritual that seeds the workspace and identity files"
+read_when:
+  - Understanding what happens on the first agent run
+  - Explaining where bootstrapping files live
+  - Debugging onboarding identity setup
+title: "Agent Bootstrapping"
+sidebarTitle: "Bootstrapping"
+---
+
+# Agent Bootstrapping
+
+Bootstrapping is the **first‑run** ritual that prepares an agent workspace and
+collects identity details. It happens after onboarding, when the agent starts
+for the first time.
+
+## What bootstrapping does
+
+On the first agent run, OpenClaw bootstraps the workspace (default
+`~/.openclaw/workspace`):
+
+- Seeds `AGENTS.md`, `BOOTSTRAP.md`, `IDENTITY.md`, `USER.md`.
+- Runs a short Q&A ritual (one question at a time).
+- Writes identity + preferences to `IDENTITY.md`, `USER.md`, `SOUL.md`.
+- Removes `BOOTSTRAP.md` when finished so it only runs once.
+
+## Where it runs
+
+Bootstrapping always runs on the **gateway host**. If the macOS app connects to
+a remote Gateway, the workspace and bootstrapping files live on that remote
+machine.
+
+<Note>
+When the Gateway runs on another machine, edit workspace files on the gateway
+host (for example, `user@gateway-host:~/.openclaw/workspace`).
+</Note>
+
+## Related docs
+
+- macOS app onboarding: [Onboarding](/start/onboarding)
+- Workspace layout: [Agent workspace](/concepts/agent-workspace)

docs/start/onboarding.md

@@ -13,99 +13,67 @@ This doc describes the **current** first‑run onboarding flow. The goal is a
 smooth “day 0” experience: pick where the Gateway runs, connect auth, run the
 wizard, and let the agent bootstrap itself.
 
-## Page order (current)
+<Steps>
-
+<Step title="Approve macOS warning">
-1. Welcome + security notice
+<Frame>
-2. **Gateway selection** (Local / Remote / Configure later)
+<img src="/assets/macos-onboarding/01-macos-warning.jpeg" alt=""></img>
-3. **Auth (Anthropic OAuth)** — local only
+</Frame>
-4. **Setup Wizard** (Gateway‑driven)
+</Step>
-5. **Permissions** (TCC prompts)
+<Step title="Approve find local networks">
-6. **CLI** (optional)
+<Frame>
-7. **Onboarding chat** (dedicated session)
+<img src="/assets/macos-onboarding/02-local-networks.jpeg" alt=""></img>
-8. Ready
+</Frame>
-
+</Step>
-## 1) Welcome + security notice
+<Step title="Welcome and security notice">
-
+<Frame caption="Read the security notice displayed and decide accordingly">
-Read the security notice displayed and decide accordingly.
+<img src="/assets/macos-onboarding/03-security-notice.png" alt=""></img>
-
+</Frame>
-## 2) Local vs Remote
+</Step>
+<Step title="Local vs Remote">
+<Frame>
+<img src="/assets/macos-onboarding/04-choose-gateway.png" alt=""></img>
+</Frame>
 
 Where does the **Gateway** run?
 
-- **Local (this Mac):** onboarding can run OAuth flows and write credentials
+- **This Mac (Local only):** onboarding can run OAuth flows and write credentials
   locally.
 - **Remote (over SSH/Tailnet):** onboarding does **not** run OAuth locally;
   credentials must exist on the gateway host.
 - **Configure later:** skip setup and leave the app unconfigured.
 
-Gateway auth tip:
+<Tip>
-
+**Gateway auth tip:**
 - The wizard now generates a **token** even for loopback, so local WS clients must authenticate.
 - If you disable auth, any local process can connect; use that only on fully trusted machines.
 - Use a **token** for multi‑machine access or non‑loopback binds.
-
+</Tip>
-## 3) Local-only auth (Anthropic OAuth)
+</Step>
-
+<Step title="Permissions">
-The macOS app supports Anthropic OAuth (Claude Pro/Max). The flow:
+<Frame caption="Choose what permissions do you want to give OpenClaw">
-
+<img src="/assets/macos-onboarding/05-permissions.png" alt=""></img>
-- Opens the browser for OAuth (PKCE)
+</Frame>
-- Asks the user to paste the `code#state` value
-- Writes credentials to `~/.openclaw/credentials/oauth.json`
-
-Other providers (OpenAI, custom APIs) are configured via environment variables
-or config files for now.
-
-## 4) Setup Wizard (Gateway‑driven)
-
-The app can run the same setup wizard as the CLI. This keeps onboarding in sync
-with Gateway‑side behavior and avoids duplicating logic in SwiftUI.
-
-## 5) Permissions
 
 Onboarding requests TCC permissions needed for:
 
+- Automation (AppleScript)
 - Notifications
 - Accessibility
 - Screen Recording
-- Microphone / Speech Recognition
+- Microphone
-- Automation (AppleScript)
+- Speech Recognition
-
+- Camera
-## 6) CLI (optional)
+- Location
-
+  </Step>
-The app can install the global `openclaw` CLI via npm/pnpm so terminal
+  <Step title="CLI">
-workflows and launchd tasks work out of the box.
+  <Info>This step is optional</Info>
-
+  The app can install the global `openclaw` CLI via npm/pnpm so terminal
-## 7) Onboarding chat (dedicated session)
+  workflows and launchd tasks work out of the box.
-
+  </Step>
-After setup, the app opens a dedicated onboarding chat session so the agent can
+  <Step title="Onboarding Chat (dedicated session)">
-introduce itself and guide next steps. This keeps first‑run guidance separate
+  After setup, the app opens a dedicated onboarding chat session so the agent can
-from your normal conversation.
+  introduce itself and guide next steps. This keeps first‑run guidance separate
-
+  from your normal conversation. See [Bootstrapping](/start/bootstrapping) for
-## Agent bootstrap ritual
+  what happens on the gateway host during the first agent run.
-
+  </Step>
-On the first agent run, OpenClaw bootstraps a workspace (default `~/.openclaw/workspace`):
+  </Steps>
-
-- Seeds `AGENTS.md`, `BOOTSTRAP.md`, `IDENTITY.md`, `USER.md`
-- Runs a short Q&A ritual (one question at a time)
-- Writes identity + preferences to `IDENTITY.md`, `USER.md`, `SOUL.md`
-- Removes `BOOTSTRAP.md` when finished so it only runs once
-
-## Optional: Gmail hooks (manual)
-
-Gmail Pub/Sub setup is currently a manual step. Use:
-
-```bash
-openclaw webhooks gmail setup --account you@gmail.com
-```
-
-See [/automation/gmail-pubsub](/automation/gmail-pubsub) for details.
-
-## Remote mode notes
-
-When the Gateway runs on another machine, credentials and workspace files live
-**on that host**. If you need OAuth in remote mode, create:
-
-- `~/.openclaw/credentials/oauth.json`
-- `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
-
-on the gateway host.