Onboarding

Route: /onboarding (sidebar: More pages › Connect › Set up)

Scenario: You signed up 5 minutes ago. Your goal: get a real bug report from your app into Mushi Mushi before your afternoon standup. The page’s own target is a first plain-English diagnosis in under 2 minutes.

The Set up page is the shortest path from signup to a report in your queue.

First run: two screens

While your project has no report yet, the page shows two screens instead of the full checklist:

Name your project

Step 1 of 2. Enter a project name and create it. That is the only input: the create call also makes your report key (report:write), so there is no separate key step.

See your first diagnosis

Step 2 of 2. Click Send test report. The report goes through the real ingest path and the diagnosis appears on the same screen. From there, Install the SDK to get the same for real bugs.

Add ?view=all to the URL, or click Show all steps, to see the full checklist instead.

Full checklist

Once your project has a report (or with ?view=all), a progress rail tracks four steps: App created, Key made, App connected and First bug received. It reads “n of 4 done. Next: …” with a button for the next step, and “Your app is wired up” when all four are done.

Below the rail, the page has five tabs:

Tab	What it holds
Overview	Setup status, a diagram of what happens after a report, and what to do next
More to connect	Optional tools to connect once the app is set up (and the create form in CLI setup mode)
Test it	Generate API key, Submit test report / Send another, and the First report in your queue timer
Install	The SDK install snippet and a Go to Dashboard button
Fix a problem	SDK heartbeat, version and fix-dispatch checks for one project, with copy-paste commands

After you create a project

A success panel shows:

Your Project ID (UUID) in a one-click copy chip
The key that was made for you, and one prefilled mushi init --project-id … --api-key … command
A Generate API key button instead, if the key could not be made automatically

Generate an API key

Generate API key on the Test it tab makes an SDK key (report:write). The key is shown in plaintext exactly once, so copy it immediately.

Not Settings → AI keys. That tab holds your own Anthropic, OpenAI, Cursor and Firecrawl keys. SDK report keys are made here, or on Manage apps (/projects).

Test the connection

Click Submit test report to send a synthetic report through the ingest pipeline. A status chip shows idle → running → pass / fail. Click Send another to send more. Test reports are limited to 10 per user per hour.

The Test it tab also shows a First report in your queue timer: how long from making your first API key to seeing a plain-English diagnosis on a report. The target is under 2 minutes; the card reads “Under the 2-minute target ✓” once you beat it, or “Target: under 2 minutes” while pending.

Install the SDK

The Install tab shows install snippets per framework (a script tag, React, Vue, Svelte, React Native, Expo, Capacitor, Node, Express, Fastify, Hono and plain JavaScript), filled in with your API key and project ID.

Or run the CLI wizard from your app repo: see CLI ↔ console loop.

CLI setup mode (`?setup=cli`)

When you run npx mushi-mushi without saved credentials, the wizard can open the console at:


/onboarding?tab=steps&setup=cli

Behavior	Normal onboarding	`setup=cli`
First-run screens	Shown until the first report	Skipped: the full checklist opens on More to connect
Create form	Hidden if you already have projects	Always shown, so you can add another project
Banner	None	”Setting up from the CLI?” plus a “Your terminal is waiting” card
Success panel	Same UUID + CLI command	Same, meant for pasting back into the terminal

Use this path when the terminal wizard sent you here, or when you need a second project without leaving the Set up page.

CLI setup strip

Two places reuse the same 1-2-3 CLI setup strip (CliSetupGuide):

The Overview tab of this page, before you have any project
The empty state on Manage apps (/projects)

Steps match the CLI ↔ console loop: create → mint key → mushi init or mushi connect.

How the loop works

The Overview tab includes a static diagram, “What happens after a report”, with outcome copy instead of live counts, so you know what happens after a report lands before you see live numbers.

One-time key reveal — the plaintext API key is shown exactly once after generation. Copy it before clicking away. If you lose it, generate a new key on Manage apps. The old one can’t be recovered.

Troubleshooting the test report

If the test report shows fail:

Symptom	Likely cause	Fix
`401 Unauthorized`	Wrong API key in the SDK install	Re-copy the key from the reveal card
`429 Too Many Requests`	You sent more than 10 test reports in an hour	Wait up to an hour (the response’s `Retry-After` header says how long), then try again
Status stuck at `running`	No AI key the triage can use (self-hosted installs)	Go to Settings → AI keys → add an Anthropic key
Success but no report on Bugs	Wrong project in the SDK snippet	Check `projectId` in your install code

What happens after setup

Once the SDK sends its first real report from your app:

The “waiting for your first report” card on Home goes away.
The report gets a plain-English read and appears on Bugs.
The setup rail marks First bug received as done.

Setup gaps

Once the app exists, Setup gaps lists the configuration that is missing or broken, before a button fails. Each line has a Fix link to the page where you fix it. Checks that pass fold into one line, and a check Mushi Mushi could not read says so: the page never reads “all fine” while a check is unknown.

Check	What it reads	Why it matters
GitHub access, per repo	The Mushi Mushi GitHub App’s permissions, a classic token’s scopes, or a fine-grained token’s harmless reads	Pushing fix branches, opening pull requests and re-running CI each need their own permission. Without secrets access, Mushi Mushi gives you copy-paste commands instead.
Review follow-up key	Your team’s follow-up setting and the Cursor key it uses	Mushi Mushi turns follow-ups off on its own when that key is deleted.
Auto-fix agent key	Whether auto-fix is on and a Cursor key can start an agent	With no usable key, no fix starts on its own.
Deploy events	The last deploy Mushi Mushi saw	With none in 14 days, reporters are not told when their fix goes live.
Slack bot token	The latest Slack check (every 15 minutes)	Slack stops accepting a token when the app is removed from the workspace.

Mushi Mushi only reads to check. It never writes to GitHub to find out whether it may write, so a fine-grained token’s write permissions read can’t tell. Results are kept for 10 minutes; Check again re-checks.

Restarting the tour

Click Restart tour at the bottom of the page to replay the first-run tour of the console. It opens Home and starts the tour again. It does not reset your setup progress or delete any projects or data.

API


POST /v1/admin/projects               { name }          → also makes a report:write key
POST /v1/admin/projects/:id/keys      { scopes?, label? }  (scopes default to ['report:write'])
POST /v1/admin/projects/:id/test-report
GET  /v1/admin/onboarding/time-to-first-diagnosis   → { keyMintedAt, firstDiagnosisAt, ms }
GET  /v1/admin/setup-gaps?projectId=                → { projects: [{ gaps: [{ id, status, title, summary, fixHref }] }] }

CLI ↔ console loop: terminal wizard and deep link
Manage apps: manage multiple projects and keys
Connect: SDK heartbeat and copy-ready CLI commands
Settings: your own AI keys and SDK settings after setup
Home: the summary page for one app