---
title: Onboarding
description: First-time user experience, progressive disclosure, and welcome patterns
tags: [ux, engagement, learning]
dependencies: [identity, conversation, privacy]
---

# Onboarding

The first interaction shapes everything. Start with value, not setup.

## Principles

- Show what the agent does before asking for configuration
- Introduce features as they become relevant, not all at once
- Respect prior knowledge — offer escape hatches for experienced users

## The greeting

First message sets the tone:

```
I help you manage your tasks. Try saying "add buy groceries"
or type "help" to see everything I can do.
```

Include: what the agent does (one sentence), what to do right now (one action), how to get help.

## Patterns

- **Architecture disclosure**: First interaction should tell the user where data lives — what stays on-device, what leaves, what third parties see. Informed data governance starts at onboarding, not in a settings page.
- **Guided first action**: Walk through one complete interaction, then suggest the next step
- **Example-driven**: Show 2-3 concrete examples, not abstract descriptions
- **Contextual help**: Surface tips at the moment of need, not in a separate docs page

## Anti-patterns

- Information overload on first visit
- Mandatory tutorials that can't be skipped
- Empty states with no guidance
- Jargon before the user has learned it

## For agents

1. Write the greeting first — it's the most important text
2. Identify the single most valuable action and make it effortless
3. Allow skipping any onboarding step
4. Test with someone who has never seen the product