Onboarding flow

A three-slide onboarding flow at /onboarding that shows once, before the app's tabs. I'd turn this on when new users need context - a value pitch, a permission explainer, a sign-in nudge - and leave it off when your first screen is self-explanatory. The route group has no header and no back gesture, the slides are built from @/components/ui primitives (no ScrollView paging), and finishing calls completeOnboarding() and router.replace("/").

SetupCopy Anchor Link

bun run setup --onboarding on

That's it - setup adds the route group (src/app/onboarding/_layout.tsx, src/app/onboarding/index.tsx), the screen src/screens/onboarding/onboarding-screen.tsx, and src/hooks/use-onboarding-redirect.ts, which the core root layout already calls.

UsageCopy Anchor Link

Edit the SLIDES array in src/screens/onboarding/onboarding-screen.tsx - each slide is a title, a description and an icon, rendered with Next / Back / Skip controls.

The state lives in core at src/stores/onboarding.ts under the key readynative:onboarding. useOnboardingRedirect() hydrates that store and redirects to /onboarding once navigation is ready and completed is still false.

To test the flow again, use Settings → "Reset onboarding" (shown because the hook file exports onboardingEnabled = true); it flips completed back and the hook sends you to /onboarding.

GotchasCopy Anchor Link

• Expo Go works - there's nothing native here.
• The redirect waits for navigation to be ready, so the first frame can be your root route before it replaces - keep the splash screen up if that flicker bothers you.
• Swapping stacks: bun run setup --onboarding off swaps the hook for a no-op and deletes the route and screen. The store and the Settings reset button stay (they're core).

Remove itCopy Anchor Link

While modules/ exists (a tree set up with --keep-modules), setup does all of it:

bun run setup --onboarding off --yes --keep-modules

In a finalized tree setup is a stub, so you undo it by hand. Here is everything this module added:

1. Delete the files that are still there: .maestro/flows/onboarding.yaml, src/app/onboarding/_layout.tsx, src/app/onboarding/index.tsx, src/screens/onboarding/onboarding-screen.tsx.
2. Replace, don't delete src/hooks/use-onboarding-redirect.ts: core code imports it, so swap in the no-op version from modules/onboarding/off/files/ of a fresh clone of your tier repo - same exports, nothing behind them.
3. Check it: bun run typecheck and bun run lint point at anything that still imports the removed files; bun run gen:graph refreshes docs/ARCHITECTURE.md.

ReferenceCopy Anchor Link

Everything below is generated from modules/onboarding/on/module.json - the same file bun run setup reads, so it is what actually lands in your repo.

InstallCopy Anchor Link

bun run setup --onboarding on

Module id: onboarding/on (the default for this category).

FilesCopy Anchor Link