ShrubberyDocs
API ReferenceSign in
Guide

Onboarding & Joining an Org

How a new user finishes setup, names their org or joins someone else's, and clears the onboarding gate.

01 · Overview

Overview

Authenticated users with onboarded_at null cannot use gated product routes until they complete the onboarding wizard at /onboarding. The wizard covers welcome, display name, optional BYOK, and organisation choice (name your solo org or request to join by owner email). Finish sets onboarded_at and lands them on /capture.

02 · Actors

Actors

  • New user — just signed up or invited; must complete onboarding if the gate applies.
  • Org Owner — receives join requests; may have invited the user (invited users see a "you've joined" org step instead of create/join choose).
  • Squire — not an actor in the wizard; BYOK only stores the key the Squire will use later.
03 · Flow

Flow

  1. System redirects gated routes (/home, /capture, /dashboard, /oversight, /accord, /team, /org, /settings, …) to /onboarding while onboarded_at is null.
  2. User steps through: welcome → set display name → optional provider key (OpenAI / Anthropic / Google) or skip → org step.
  3. Org step (owner path) — rename the auto-created organisation, or request to join another org by entering the Org Owner's email (requestToJoinOrg). Join stays pending until that owner accepts.
  4. Org step (invited path) — if the user is not org owner (joined via invite), they see a read-only confirmation of the org they already belong to.
  5. User finishes — completeOnboarding stamps onboarded_at; client navigates to /capture. Product surfaces unlock.
04 · Edge cases

Edge cases

  • Join pending at finish — user can complete onboarding while a join request is still open; they remain on their original org until the owner accepts.
  • Join accept later — owner accept moves organisation membership and default-team role; blocked if the requester still has Shrubberies on the old org.
  • Invite vs join request — invite is owner-initiated (email magic from Supabase); join request is user-initiated by owner email. Different tables, same eventual membership goal.
  • BYOK skip — Smart Paste needs a key later; skipping onboarding does not block finish.
  • Re-entry — once onboarded_at is set, the gate does not force the wizard again; profile and org settings remain editable in-app.
05 · Related

Last updated: 24 July 2026