# Onboarding and first value

**Flow key:** `onboarding-and-first-value`

## Outcome

A new user understands the product, completes only necessary setup, can skip or resume optional guidance, and reaches a meaningful first successful outcome.

## Actors

- New user
- Product/onboarding service
- Optional admin/teammate
- Analytics/notification systems

## Preconditions and entry points

- A fresh synthetic account exists.
- The first-value event is defined.
- Role, segment, device, locale, and sample-data policies are known.

## Required test data

Use synthetic, isolated, resettable data. Never use real credentials, payment instruments, private customer records, or production notifications.

| Data | Canonical valid seed | Critical variations |
|---|---|---|
| User | new standard user | admin, invited member, returning incomplete, SSO-provisioned |
| Workspace | new empty `CARBON Lab` | pre-populated sample, existing invited tenant |
| Setup data | name, goal, preference, optional integration | skip, invalid, Unicode/emoji, denied permission |
| First value | create first synthetic record | import, invite, connect integration, generate AI result |
| Environment | desktop `en-US` | mobile, RTL, offline/slow, reduced motion |

## Canonical steps

Treat this as the ordinary successful path inferred from common product behavior. Adapt it to observed labels, business rules, APIs, and implementation evidence; do not invent a requirement.

| Step | User or system action | Expected evidence |
|---:|---|---|
| 1 | Enter immediately after signup/invitation. | Onboarding matches role and does not repeat completed signup work. |
| 2 | Understand progress, value, skip, and exit choices. | Required versus optional steps are honest and accessible. |
| 3 | Complete minimum required setup. | Defaults are reversible and failed optional integrations do not block unrelated value. |
| 4 | Create/import/connect enough data for first value. | Synthetic data remains clearly distinguishable from user data. |
| 5 | Complete the first-value action. | The user sees a truthful result and knows the next useful action. |
| 6 | Leave, return, skip, or reset onboarding. | Progress and product state resume/reset according to explicit policy. |

## Alternate paths

- Guided tour
- Checklist
- Sample workspace
- Role-based onboarding
- Integration-first onboarding

## Failure and recovery paths

- Step fails after progress save
- Tour blocks the UI
- Skipped step remains required later
- Analytics duplicates completion
- User joins an already-configured tenant

## Completion oracle

- The stated outcome is true in visible UI and authoritative persisted state.
- Exactly one intended business result and no unintended side effect occurred.
- Identity, tenant, authorization, money/data, lifecycle, notifications, integrations, analytics, and audit agree where applicable.
- Refresh, retry, back/forward, and a second authorized read do not reveal a contradictory result.
- Any partial, delayed, canceled, failed, or unknown outcome is labeled truthfully and has a safe recovery path.

## Evidence to capture

- Entry context, actor, tenant, role, feature flags, locale, time zone, and initial identifiers/state.
- Step-level screenshots or DOM state plus request/response, correlation, job, event, and stable business IDs where available.
- Before/after authoritative records, versions, totals, permissions, lifecycle states, and downstream side effects.
- Notifications, audit events, integration deliveries, retries, deduplication, latency, and recovery evidence.
- Untested branches, unsafe-to-run cases, product decisions, and evidence tier.

## Product decisions to resolve

- Exact eligibility, required data, authorization, and validation rules.
- Which steps are synchronous, asynchronous, optional, skippable, reversible, or irreversible.
- Idempotency, concurrency, timeout, retry, cancellation, and compensation semantics.
- Retention, privacy, notification, audit, performance, accessibility, and localization commitments.

## Related CARBON items

- [registration and invitation](../../items/identity/registration-and-invitation.md)
- [project task subtask](../../items/records/project-task-subtask.md)
- [form view](../../items/views/form-view.md)
- [accessibility](../../items/quality/accessibility.md)

[Back to Productivity and collaboration flows](index.md)
