Setup Guide Overview

The Setup Guide is the wizard that opens automatically when you create a new project at app.mosayic.io. It’s the recommended path for anyone shipping their first Mosayic app.

The guide is gated: each step has a “Continue” button that won’t enable until the dashboard can verify the previous step actually worked. You can’t accidentally skip past something half-finished.

How the guide works

The dashboard tracks which step you’re on per-project, and remembers it across sessions. You can:

• Close the tab and come back days later — you’ll land on the step you left off
• Use the back arrow to revisit a step (your previous answers are kept)
• Skip back to the Blueprint at any time using the sidebar (but new steps stay locked until earlier ones are complete)

Most steps run a command on your machine via the VS Code extension. You’ll see live status updates in the dashboard while the extension is working, and any failures show an error banner with the actual command output so you can debug.

Caution

Steps 4 onwards (everything from “Set Up Your Machine” forwards) require the VS Code extension to be installed and connected. If the extension goes offline mid-guide, the dashboard pops up a modal telling you to bring it back online.

The steps

The guide has 12 steps. They are roughly grouped into four phases:

Phase 1 — Orientation (no setup needed)

1. Choose Your Device — Pick iPhone or Android. This affects which Blueprint cards you see and which platform we focus on first.
2. Welcome / Intro — A narrative explainer. No actions to take.

Phase 2 — Get the bridge running

1. Connect Your Services — Link your GitHub, Google Cloud, and Expo accounts.
2. Install the VS Code Extension — Install and sign in to the extension. This is the gate that unlocks the rest of the guide.

Phase 3 — Set up your machine and your code

1. Set Up Your Machine — Install the CLI tools Mosayic needs (Node, Docker, Expo CLI, gcloud, Supabase CLI, optionally Claude Code).
2. Configure Your Project — Tell Mosayic where to put your code locally and scaffold the mobile and API repos.
3. Configure Supabase — Start a local Supabase instance and wire its credentials into your project.
4. All Services Connected — Final checklist that everything is talking to everything.

Phase 4 — Build and preview

1. App Configuration — Set your app name, bundle ID, and version.
2. Your First Build — Trigger the first Expo dev build via EAS.
3. Preview on Your Phone — Scan a QR code to install the build and connect to your local dev server.
4. Next Steps — Graduation. Links to the Blueprint and to your GitHub repos.

What “complete” looks like

When the guide is done, you should have:

• ✅ A green status badge on every service connection
• ✅ Two private GitHub repos: one for your mobile app, one for your API
• ✅ A local folder containing both repos, with dependencies installed
• ✅ A running local Supabase stack with auth, database, and storage
• ✅ A running local API server
• ✅ A development build of your mobile app installed on your phone
• ✅ The app on your phone connected to your local dev server, hot-reloading as you change code

From there, the Blueprint takes over as your primary workspace. The Blueprint is a set of cards covering features you’ll typically want next: push notifications, sign-in flows, payments, app store submission, and so on.

If something goes wrong

Most failures are one of:

• The extension isn’t connected. Check the bottom-left status bar in VS Code. If it says “signed out”, run Mosayic: Sign In.
• A CLI tool isn’t installed. The dashboard tells you which one is missing. Install it and click “Try again”.
• Wrong Google account. Make sure the dashboard and the extension are both signed in with the same Google account. The dashboard will warn you if they aren’t.
• Docker isn’t running. Local Supabase needs Docker Desktop running. Start it and re-try.

For deeper debugging, see Extension Troubleshooting.

Start with: Choose Your Device The first step of the guide.