# LetsBe Biz — Onboarding Flow Spec

> **Version:** 1.1
> **Date:** February 26, 2026
> **Owner:** Matt Ciaccio (matt@letsbe.solutions)
> **Companion docs:** Technical Architecture v1.2, Founding Member Program v1.0, Email Templates v1.0, Brand Guidelines v1.0

---

## 1. Overview

### Goal

Get a new customer from payment to their first AI-completed task in under 30 minutes. The aha moment is: **the AI completes a real task using their actual business data.** Everything in the onboarding flow builds toward that moment.

### Design Principles

- **Non-technical first.** Every step should work for someone who's never self-hosted anything. Technical users can skip ahead.
- **Real, not demo.** The AI doesn't show a canned demo — it works with the customer's actual business info from the profile they provide.
- **Progressive, not overwhelming.** Start with 6-8 core tools. Let them discover and activate the rest at their own pace.
- **Skippable but guided.** Every step can be skipped, but the default path leads to value fast.

### Structure

The onboarding is a **hybrid** approach:
1. **Setup Wizard** (Steps 1-4) — Linear, guided, gets them to the aha moment
2. **Getting Started Checklist** — Persistent dashboard widget with remaining tasks, flexible order

---

## 2. Pre-Onboarding: Payment to Provisioning

### What Happens

1. Customer selects a plan on the pricing/founding member page
2. Enters payment details (Stripe or similar)
3. **Payment confirmed** → triggers server provisioning via a single Ansible run
4. Customer sees a "Your server is being set up" page with:
   - Progress indicator (e.g., animated server icon building)
   - Estimated time: "Usually 10-25 minutes"
   - "We'll email you when it's ready — you can close this page"
   - Fun loading states (rotating tips about what they can do with LetsBe)
5. **Server provisioned** → email sent (see Email Template O2)
6. Customer clicks login link in email → lands on the Setup Wizard

### What Provisioning Does (Behind the Scenes)

A single Ansible run deploys everything at once to the fresh VPS. No staged provisioning — all components install in one pass. Key steps:

1. **Base system** — Docker, Nginx reverse proxy, SSL certificates
2. **Tool containers** — All 25+ containerized tools deployed with isolated Docker networks and fixed port assignments (`127.0.0.1:30XX`)
3. **Credential generation** — `env_setup.sh` generates 50+ tool-specific credentials, API keys, and admin passwords, stored at `/opt/letsbe/env/credentials.env`
4. **OpenClaw** — AI agent runtime installed and configured with agent personas (Dispatcher, IT Admin, Marketing, Secretary, Sales)
5. **Safety Wrapper extension** — Installed at `~/.openclaw/extensions/letsbe-safety-wrapper/`, configured with Hub connectivity and tool access rules
6. **Tool registry** — `tool-registry.json` generated from provisioned tools and credentials, describing every tool's API endpoint, auth type, and credential references
7. **Skills & cheat sheets** — Master tool skill and per-tool reference documents deployed to agent workspaces
8. **Health checks** — Verify all containers are running, OpenClaw gateway responds, Safety Wrapper hooks are active, Hub connectivity confirmed

Total time: 10-25 minutes depending on VPS provider and network speed. OpenClaw itself adds minimal overhead (~45-75 seconds with pre-baked base image).

### Data Collected at Checkout

| Field | Required | Used For |
|-------|----------|---------|
| Full name | Yes | Account, billing, AI personalization |
| Email address | Yes | Account, login, email hosting setup |
| Business name | Yes | Instance branding, AI context |
| Country | Yes | Billing, GDPR compliance |
| Payment method | Yes | Billing |

Everything else is collected in the Setup Wizard, not at checkout. Keep the checkout flow short — more fields = more drop-off.

---

## 3. Setup Wizard (Steps 1-4)

The wizard appears on first login. It's a full-screen, step-by-step flow with a progress bar. Each step has a "Skip for now" option. Estimated total time: 5-10 minutes.

### Step 1: Your Business Profile

**Headline:** "Tell us about your business"
**Subtext:** "This helps us customize your server and gives your AI the context it needs to be useful from day one."

**Structured fields:**

| Field | Type | Required | Example |
|-------|------|----------|---------|
| Business name | Text | Yes (pre-filled from checkout) | "Bright Spark Consulting" |
| Industry | Dropdown | Yes | Marketing, Consulting, Design, Tech, eCommerce, Other |
| Team size | Radio | Yes | Just me / 2-5 / 6-10 / 11+ |
| Website | URL | No | brightsparkco.com |
| Primary role | Dropdown | No | Founder, Freelancer, Manager, Developer, Other |

**Freeform bio:**

| Field | Type | Required | Max length |
|-------|------|----------|------------|
| Business bio | Textarea | No | 500 chars |

**Placeholder text:** "Tell your AI about your business in a few sentences. What do you do? Who are your customers? What's your biggest challenge right now?"

**Example:** "We're a 3-person marketing consultancy specializing in B2B SaaS companies. We handle content strategy, email campaigns, and social media management. Our biggest challenge is keeping track of client communications across too many tools."

**What this data does:**
- Business name → brands the dashboard, email templates, invoices
- Industry + team size → sets default tool recommendations
- Bio → fed to the AI agent as persistent context, so it understands the business from the first interaction

**[Button: Next →]** / **[Link: Skip for now]**

---

### Step 2: Your Domain & Email

**Headline:** "Set up your domain"
**Subtext:** "Connect your domain for branded email (you@yourbusiness.com) and a custom dashboard URL."

**Two paths:**

**Path A: "I have a domain"**
- Enter domain name
- Instructions to add DNS records (MX, SPF, DKIM, DMARC)
- Verification check (can be async — "We'll notify you when it's verified")
- Email hosting configured on Stalwart Mail

**Path B: "I need a domain" / "I'll do this later"**
- Option to register a domain through LetsBe (if offered) or use a default subdomain (username.letsbe.biz)
- Default email: username@letsbe.biz (functional but not branded)
- Can add custom domain anytime from settings

**Important:** DNS propagation takes time. Don't block the wizard on verification. Let them proceed with a default subdomain and switch later when DNS is verified.

**[Button: Next →]** / **[Link: I'll set this up later]**

---

### Step 3: Choose Your Tools

**Headline:** "Pick your starter tools"
**Subtext:** "We recommend starting with these essentials. You can activate more tools anytime from the Tool Catalog."

**Pre-selected (recommended starter pack):**

| Tool | Why it's in the starter pack |
|------|---------------------------|
| **CRM** | Central to most business operations |
| **Email** | Everyone needs email |
| **Files** | File storage is universal |
| **Projects** | Task and project management |
| **Calendar** | Scheduling and time management |
| **AI Agents** | The core differentiator — always on |

**Additional tools grid** (checkboxes, unselected by default):

Each tool card shows: icon, name, one-line description, subdomain preview (e.g., crm.yourbiz.letsbe.biz).

Categories to organize the grid:
- **Communication:** Email Marketing, Chat, Forms & Surveys
- **Finance:** Invoicing, Time Tracking, Expenses
- **Content:** Notes & Wiki, Website Builder, Document Editor
- **Automation:** Workflow Automation, Analytics, Integrations
- **More:** (any additional tools)

**Behavior:**
- Starter pack tools are pre-checked but can be unchecked
- Users can check as many additional tools as they want
- Unchecked tools aren't hidden — they go to the Tool Catalog on the dashboard where they can be activated later
- AI Agents cannot be unchecked (it's the core product)

**[Button: Set Up My Server →]** / **[Link: Just give me everything]** (activates all tools)

---

### Step 4: Meet Your AI

**Headline:** "Meet your AI team."
**Subtext:** "This is the part that makes LetsBe different. Your AI doesn't just talk — it works."

**The guided demo:**

This step is interactive. The AI greets the user and walks them through a real task.

**Flow:**

1. **AI introduction:**
   > "Hey [First Name] — I'm your AI team. I have access to every tool on your server, and I can take real action: send emails, update your CRM, manage projects, and more. Let me show you."

2. **Prompt:** "Give me a real task to do. Here are some ideas:"
   - "Draft a follow-up email to a client"
   - "Create a project for [something I'm working on]"
   - "Set up a contact in my CRM"
   - Or type your own task

3. **AI executes the task** in real time, showing which tools it's accessing:
   > "Creating a new contact in your CRM... Done. ✓"
   > "Drafting a follow-up email... Here's what I wrote:"
   > [Shows draft]
   > "Want me to send this, edit it, or save it as a draft?"

4. **User responds** — send, edit, or save.

5. **AI closes:**
   > "That's the idea. I can do this across all your tools — CRM, email, projects, files, invoicing, and more. Just ask. You can find me in the AI panel in your sidebar, or use the keyboard shortcut [Cmd/Ctrl + K]."

**If the user skips the bio in Step 1**, the AI adapts:
> "I don't know much about your business yet. Want to tell me a bit about what you do? That way I can be more useful from the start."

**Fallback if no tools are populated yet** (no contacts, no projects):
> "Your tools are empty right now — let's fix that. Want me to create a sample project to show you how things work? Or import some contacts?"

**[Button: Go to My Dashboard →]**

---

## 4. Getting Started Checklist

After the wizard completes, a persistent "Getting Started" widget appears on the dashboard. It stays visible until dismissed or all tasks are completed.

### Checklist Items

| # | Task | Description | Skippable | Depends on |
|---|------|-------------|-----------|-----------|
| 1 | ✅ Set up business profile | Completed in wizard | — | — |
| 2 | ✅ Choose your tools | Completed in wizard | — | — |
| 3 | ✅ Complete your first AI task | Completed in wizard | — | — |
| 4 | Connect your domain | Add DNS records for branded email | Yes | Step 2 (if skipped) |
| 5 | Import your data | Connect Google, sync email via IMAP, or upload a CSV | Yes | — |
| 6 | Set up your first automation | Create a workflow that connects two or more tools | Yes | — |
| 7 | Schedule a morning briefing | Configure your daily AI briefing | Yes | — |
| 8 | Invite a team member | Add a colleague to your server (if team size > 1) | Yes | — |
| 9 | Explore the Tool Catalog | Browse and activate additional tools | Yes | — |

### Checklist Design

- Persistent card on the dashboard — top of page or sidebar, visible but not blocking
- Progress bar: "4 of 9 complete"
- Each task: checkbox + title + one-line description + "Do this →" link
- Completed tasks show a checkmark and are greyed out
- "Dismiss checklist" option after 5+ tasks completed (or after 7 days)
- If dismissed, accessible from Settings > Getting Started

---

## 5. Data Import & Integrations

### Import Options at Launch

LetsBe leverages OpenClaw's existing integration capabilities, which means the data import story is stronger than a typical V1. Three import methods are available from day one:

#### 5.1 CSV Import

**Location:** CRM → Import → Upload CSV

**Flow:**

1. **Upload:** Drag-and-drop or file picker for .csv file
2. **Preview:** Show first 5 rows of the file
3. **Column mapping:** Auto-detect common headers (Name, Email, Phone, Company). For unrecognized columns, dropdown to map to CRM fields or skip.
4. **Duplicate handling:** Option to skip duplicates (by email) or update existing
5. **Import:** Progress bar, count of imported/skipped/errored records
6. **Done:** "X contacts imported. [View in CRM →]"

**Use case:** Universal fallback — every CRM and spreadsheet can export CSV.

#### 5.2 Google Integration (via `gog` CLI in OpenClaw)

**Prerequisite:** Google integration tool installed on the server (offered during tool selection in Step 3).

**How it works:** OpenClaw uses the `gog` CLI binary to interact with Google APIs. The AI agent calls `gog` commands via the `exec` tool — there's no separate Google container. OAuth tokens are stored locally on the tenant VPS.

**Capabilities:**
- Google Contacts sync → CRM
- Google Calendar sync → Calendar
- Google Drive access → Files
- Gmail read access → AI context for email-related tasks

**Onboarding flow:**
1. User clicks "Connect Google Account"
2. OAuth flow → user authorizes specific scopes (this is a headless OAuth challenge — the user completes it in their browser, and the token is stored on their VPS)
3. Initial sync begins (contacts, calendar events)
4. Progress shown: "Syncing X contacts, Y calendar events..."
5. Done: "Your Google data is connected. Your AI can now reference your contacts and calendar."

**Important:** This is a read-and-sync flow, not a migration. Google remains the source for existing data; LetsBe syncs a copy. New data created in LetsBe stays in LetsBe unless the user sets up a two-way sync.

**Open challenge:** OAuth in a headless container requires a device-code or redirect-based flow that the user completes in their own browser. The exact UX for this needs to be designed — likely a "Connect Google" button in the dashboard that initiates the flow and captures the token.

#### 5.3 IMAP Email Import (via `himalaya` CLI in OpenClaw)

**Prerequisite:** `himalaya` CLI binary available on the tenant server (installed during provisioning).

**How it works:** OpenClaw uses the `himalaya` CLI binary to connect to any IMAP server. The AI agent calls `himalaya` commands via the `exec` tool to read, search, and manage email. No separate email container needed for import.

**Capabilities:**
- Connect any existing email account (Gmail, Outlook, Yahoo, custom IMAP) to LetsBe
- AI agents can read and reference existing email history
- Enables "draft a follow-up based on my last conversation" from day one

**Onboarding flow:**
1. User clicks "Connect Existing Email"
2. Enter IMAP server, email, password (or OAuth for Gmail/Outlook)
3. Connection test → success/failure with clear error messages
4. Choose what to sync: "Last 30 days" / "Last 90 days" / "Everything"
5. Sync begins in background
6. Done: "Your email history is connected. Your AI can now reference your past conversations."

**Note:** This doesn't replace the Stalwart Mail email hosting — it supplements it. Users can run their new branded email on LetsBe while still accessing their old email history through IMAP.

### Integration Catalog

Since OpenClaw provides integration capabilities beyond Google and IMAP, the Tool Catalog (Section 6) should include an **Integrations** category:

| Integration | Source | Description |
|------------|--------|-------------|
| Google Workspace | OpenClaw | Contacts, Calendar, Drive, Gmail |
| IMAP Email | OpenClaw (Himalaya) | Connect any email account for AI context |
| *Future: Microsoft 365* | OpenClaw / custom | Outlook, OneDrive, Teams |
| *Future: Notion import* | Custom | Page and database import |
| *Future: HubSpot import* | Custom | Contact and deal migration |

### What's NOT in V1 (Deferred)

- Two-way sync with Google (write-back to Google from LetsBe)
- Microsoft 365 / Outlook integration
- Direct CRM-to-CRM migration tools (HubSpot, Salesforce export)
- ClawHub marketplace integrations (evaluate post-beta based on user demand)

---

## 6. Tool Catalog

The Tool Catalog is the "app store" for tools on the user's server. All tools are included in their plan — activating them is free.

### Catalog Design

**Location:** Dashboard sidebar → "Tool Catalog" or gear icon

**Each tool card shows:**
- Tool icon
- Tool name
- One-line description
- Category tag
- Status: "Active" (green) or "Available" (neutral)
- "Activate" button (for inactive tools) or "Open" button (for active)
- Subdomain preview: tool.yourdomain.com

**Categories:**
- Essentials (CRM, Email, Files, Projects, Calendar)
- Communication (Email Marketing, Chat, Forms)
- Finance (Invoicing, Time Tracking, Expenses)
- Content (Notes, Wiki, Website Builder)
- Automation (Workflows, Analytics, AI Agents)

**Activating a tool:** One click. The tool's Docker container starts on their server (takes 10-30 seconds), gets its own isolated network, and is added to the AI's tool registry so agents can access it immediately. No additional configuration needed for basic use.

**Deactivating a tool:** Available from the tool's settings. Data is preserved but the service stops. Can be reactivated anytime.

---

## 7. AI-Assisted Help During Onboarding

### How It Works

The AI agent doubles as onboarding support. During the first 7 days, the AI proactively offers help based on context:

**Contextual prompts:**
- User opens CRM for the first time → AI suggests: "Want me to help you import contacts or set up your first deal pipeline?"
- User opens Email Marketing → AI suggests: "I can help you create your first subscriber list and draft a welcome email."
- User seems inactive for 3+ days → AI sends a dashboard notification: "Haven't seen you in a while. Want to pick up where we left off?"

### Escalation to Matt

If the AI can't resolve a question or the user expresses frustration:
- AI responds: "I'm not sure about that one. Let me connect you with Matt — he'll get back to you within a few hours."
- Creates a support ticket / sends notification to Matt with context (what the user asked, what tools they're using, where they are in onboarding)
- User sees: "Matt has been notified and will reach out shortly. In the meantime, here's [relevant help link]."

For white-glove founding members (first 10-20), Matt may proactively reach out on Day 1 via email regardless.

---

## 8. Onboarding Metrics

### What to Track

| Metric | Target | Why It Matters |
|--------|--------|---------------|
| Wizard completion rate | >70% | Are people finishing the setup? |
| Time to first AI task | <30 min from payment | Speed to aha moment |
| Step 1 (profile) completion | >80% | Bio quality affects AI usefulness |
| Step 2 (domain) completion | >40% | Expected lower — DNS is a barrier |
| Step 3 (tools) completion | >90% | Should be easy — just checkboxes |
| Step 4 (AI demo) completion | >60% | The aha moment — critical |
| Contacts imported (Day 7) | >30% of users | CRM populated = stickier product |
| Checklist tasks completed (Day 7) | >5 of 9 | Engagement depth |
| 7-day retention | >80% | Are they coming back? |
| 30-day retention | >60% | Are they staying? |

### Drop-Off Alerts

If a user drops off at any step:
- **During wizard:** Follow up with Email O3-O4 (onboarding drip) within 24 hours
- **After wizard but no AI task:** AI sends a dashboard notification on next login
- **No login after 3 days:** Email check-in (O5)
- **No login after 7 days:** Personal email from Matt for founding members

---

## 9. Onboarding Emails Integration

The email onboarding sequence (from Email Templates v1.0) maps to the product onboarding as follows:

| Email | Timing | Product State |
|-------|--------|--------------|
| O1: Welcome | Immediately after payment | Provisioning in progress |
| O2: Server is live | Server provisioned (~10-25 min) | Login available, wizard starts |
| O3: First AI agent | Day 1 | Post-wizard, reinforces Step 4 |
| O4: Three things to try | Day 3 | Maps to checklist items 5, 6, 7 |
| O5: Check-in | Day 7 | Feedback collection |
| O6: Power user tips | Day 14 | Deepening engagement |

Emails and in-product onboarding should complement, not duplicate. If a user already completed a task in-product, the corresponding email should acknowledge that (conditional content).

---

## 10. Edge Cases

| Scenario | Handling |
|----------|---------|
| User closes browser during provisioning | Email notification when ready (O2). Login link works whenever they return. |
| DNS verification fails | Dashboard notification with troubleshooting steps. Offer to keep using default subdomain. |
| CSV import has errors | Show which rows failed and why. Allow re-upload of corrected file. Don't lose the successful rows. |
| User activates all 25+ tools | Warn that this uses more server resources. If on Lite tier, suggest Resource Server upgrade. |
| User skips entire wizard | Checklist shows all 9 items as incomplete. AI proactively offers help on first dashboard visit. |
| Team member invited before domain is set up | Team member gets an invite to the default subdomain. Can switch when domain is configured. |
| User has no contacts to import | AI offers to create sample data or guides them through adding their first contact manually. |

---

## 11. Implementation Priority

### Must-Have for Beta (Phase 1)

- [ ] Provisioning progress page with email notification
- [ ] Setup Wizard Steps 1-4
- [ ] Getting Started checklist widget
- [ ] CSV contact import
- [ ] Google integration (via OpenClaw) — Contacts, Calendar, Drive sync
- [ ] IMAP email connection (via Himalaya in OpenClaw) — existing email access
- [ ] Tool Catalog with activate/deactivate
- [ ] AI introduction demo (Step 4)

### Nice-to-Have (Phase 2)

- [ ] Conditional email content based on onboarding state
- [ ] AI contextual suggestions when opening new tools
- [ ] Onboarding metrics dashboard
- [ ] Progressive tool recommendations based on industry
- [ ] In-app help widget with AI + escalation
- [ ] Two-way Google sync (write-back to Google from LetsBe)

### Future (Phase 3+)

- [ ] Microsoft 365 / Outlook integration
- [ ] Direct CRM migration from HubSpot, Salesforce
- [ ] ClawHub marketplace integrations
- [ ] Guided automation builder during onboarding
- [ ] Onboarding video tutorials embedded in-product
- [ ] A/B testing of wizard steps and checklist order

---

*The onboarding flow is the most important product experience. If this works, retention follows. If it's confusing or slow, nothing else matters. Prioritize the aha moment above all else.*
