First Run Is the Launch Surface
First run is the launch surface
The first run of an app is not setup glue. It is the part of the product that proves the rest of the product can exist for this user.
This matters most for local-first and daemon-backed tools. The app has to create local state, start or find the daemon, connect accounts, handle credentials, and recover from partial setup. If the happy path opens an empty shell and expects the user to know what to do next, the product is still speaking to its author.
The rule
A v1 client needs a boring first run:
- Detect no accounts or broken accounts.
- Put the user into account setup, not an empty work surface.
- Keep credential prompts visible in the same client the user is using.
- Test the account before claiming it is saved.
- End in a real synced state, or show a repairable error with one next action.
No hidden terminals. No raw config unless the user asks for advanced mode. No "open logs and figure it out."
What mxr taught us
The older Mxr Desktop App work had enough real UI to feel close. That was the trap. The reassessment found that a clean desktop run could land on mailbox state with no account, while account setup was still a JSON textarea. Gmail OAuth could also fall into device flow behind a daemon path, where the user might never see the code.
None of that means the architecture is wrong. The daemon/client split is still the right shape. It means first-run state is a product surface and needs its own route through the daemon contract.
The current repo no longer ships that native desktop client. The live lesson moved to mxr web: the GUI surface should guide account setup and OAuth clearly without pretending the daemon can hide every credential side effect.
The Gmail v1 pass added a quieter version. One-click OAuth is not a launch
promise while the shared Google client is unverified. The honest first-run path
can be BYOC, but only if the docs and setup flow make "create a Desktop OAuth
client, paste the ID/secret, then authorize" feel like a bounded task rather
than a scavenger hunt through Google Cloud. A bundled unverified client is a
fallback, not a substitute for first-run design.
The demo taught the performance version of the same lesson. mxr demo is the README's "try it" command, which makes it a first run too, and in August 2026 it died on a Kubuntu machine with "IPC request timed out after 120 seconds" (issue 179). The seed was correct; it was just slower than a deadline tuned on the author's Mac. A first-run surface has a performance budget on the slowest machine you claim to support, and it deserves an end-to-end test in CI like any other launch surface. The fix streamed progress and waited on stalls instead of the wall clock; see Deadlines Bound Stalls, Not Work.
What to check in any app
- What happens with an empty profile?
- What happens after a failed auth attempt?
- What happens after the user closes the app halfway through setup?
- Can the app tell the difference between "no data yet" and "user is done, inbox is empty"?
- Are background prompts represented as foreground state?
- Does the user ever need to paste JSON to reach the main product?
If the answer is fuzzy, the launch blocker is not polish. It is the first run.
Worth Your Time example
In Worth Your Time, onboarding creates the taste data used by the main film verdict. It is not complete merely because the user reached the last screen.
The free-text taste description once affected suggested films inside onboarding but was dropped when the profile was saved. The first run looked complete while the main decision path never received that signal. The current flow stores it, includes it in taste-profile generation and verdict context, and advances cache versions when it changes.
That gives first run a stronger completion test: can the product make its first real decision with the state onboarding claimed to collect? See Personalization Inputs Need End-to-End Lineage.
Release verification on 12 September exercised that test on a fresh iOS Release install. Anonymous setup saved one taste description, produced and saved a personal first pick, then supported a separate search and verdict for Arrival. Reaching the last onboarding screen was not the acceptance criterion. The first run passed because the core product could make a useful decision from the state setup collected.
Operator first runs
The Notto Daily Pipeline Runner showed the same rule for internal operations. A daily refresh is not ready just because an agent can do it once by hand. The first operator run has to check dependencies, take the safety dump, start the local stack, pause for the user-owned CSV drop, monitor Dagster, and wind down cleanly.
That is still first-run design. The "user" is an operator, and the product surface is a script plus a runbook.
Linganisa example
Linganisa showed the media side of first run. Its onboarding morph only
became a credible launch surface after the source images were cut from 40.3 MB
to 0.70 MB per platform, the loop waited for both assets, and reduced motion
kept a stable state.
Custom art did not make the first run correct by itself. The useful contract was
that the screen could become ready without a flash or long decode. See
Crafted interfaces make system state legible.