| 1 | # Onboarding checklist |
| 2 | |
| 3 | From the Clover Chat onboarding research: eight research agents, more than 20 |
| 4 | products torn down from their shipped strings. It is written for account, |
| 5 | connect and permission flows, and applies to any first run. |
| 6 | |
| 7 | 1. Open on the person's own content, or on the action that creates it. Derive |
| 8 | "first run" from state (no accounts); never store a flag. |
| 9 | 2. Ask nothing up front unless it is required, needs consent, or is |
| 10 | irreversible with no safe default. Turn everything else into a default plus a |
| 11 | later choice. |
| 12 | 3. Never show a choice between options a newcomer can't yet compare (storage |
| 13 | location, architecture, server). |
| 14 | 4. Pre-select the safest, most private default. Never show an unselected pair. |
| 15 | 5. Cut welcome carousels and tutorials. Teach each feature when it is first |
| 16 | used, and suggest novel features only when real data makes them true. |
| 17 | 6. Request each permission inside the flow that needs it, with a specific |
| 18 | purpose sentence. Give pre-alert screens one button. |
| 19 | 7. For permissions without a system prompt, deep-link to the pane, poll for the |
| 20 | grant, and offer "Quit & Reopen" as a fallback. |
| 21 | 8. Ask for one identifier per account; discover servers, ports and TLS. Open |
| 22 | advanced settings only after discovery fails, pre-filled with what was tried. |
| 23 | 9. Reuse the provider's own words and menu paths for linking steps. Cap QR |
| 24 | rotation and offer "Refresh Code". |
| 25 | 10. State each network's history depth before the person commits. |
| 26 | 11. Close the connect step as soon as the first content exists. Never block on |
| 27 | backfill. Show progress as counts or dates, never as an ETA. |
| 28 | 12. Make every empty state say what will appear and give the button that fills |
| 29 | it. Never end setup on a "done" page with nothing in it. |
| 30 | 13. Offer optional power features only when the claim is true on this device: |
| 31 | inline, never modal, never at launch. Cap them with "Not Now" (30 days) and |
| 32 | "Don't Suggest Again". |
| 33 | 14. Start any local-network scan only after the person asks to find a device. |
| 34 | Pair new devices with an invite link or QR, never a typed code or CLI |
| 35 | command. |
| 36 | 15. Name components by what they do for the person. Use one term per concept |
| 37 | and check it against every other noun on the same screen. The owner's |
| 38 | established term wins. |
| 39 | 16. Label where each account lives, and make moving it a merge-by-default with |
| 40 | a count. |
| 41 | 17. Write strings to the `ui-copy` budgets. |
| 42 | 18. Measure time to the first real conversation and per-account connect success |
| 43 | with on-device counters. Send them only as an opt-in report the person can |
| 44 | read first, with no identifier. |
| 45 | 19. Discard any onboarding statistic without a named primary dataset. |
| 46 | |
| 47 | ## What Clover decided after reading it |
| 48 | |
| 49 | - First run is the main window's empty state: a short welcome, then "Connect a |
| 50 | Chat Account" (opens a modal) and "Setup Archive Server". The server became a |
| 51 | peer button rather than a hidden link. |
| 52 | - She kept the name "archive server", against the research's "your server". |
| 53 | - Discord stays, gated behind the server with a prominent warning, against the |
| 54 | research's "drop it". |
| 55 | - Distribution is Developer ID, so iMessage can read the local database. The |
| 56 | Mac App Store sandbox would block that. |
| 57 | |
| 58 | Research supplies defaults and evidence. Identity calls stay with the owner. |