How Flowo Tells a First Run From a Returning Session

One flag chooses the first screen

Flowo chooses its first screen from a single boolean, onboardingCompleted, stored on the user profile in an encrypted local box. The root widget reads it once the boxes are open. If the value is true the app builds the main shell. If it is false the app builds the welcome screen.

A fresh install has no profile at all, so startup writes a default one with the flag set to false. An install that was closed halfway through onboarding has the same value. Both arrive at the welcome screen, and we treat them as the same case on purpose.

The flag is written in one place. The last onboarding screen shows today's plan and a single button, 'See my day'. Tapping it writes the flag, reads the profile back to confirm the write, and then replaces the whole navigation stack with the shell. If the profile box cannot be read, the check answers false, so a storage problem leads to onboarding. An empty shell would be the worse result.

What an interrupted first run keeps

An interrupted first run keeps the one thing that took effort to produce, the description of the week. Every change to that text field is written to the app's metadata box under a versioned key, bounded to 4000 characters. When the setup screen opens again it reads the stored text and fills the field.

The stored description is cleared when the plan is applied, when the person empties the field, or when they cancel the setup. Nothing else from an unfinished run is treated as progress. The flow starts again at the welcome screen.

Inside onboarding the setup screen has no back button. The route was pushed from the welcome screen, so a back gesture would return there and make the person repeat the eligibility and consent screens to reach text they had already typed. The same screen opened later from Settings does show a back button, because there it has somewhere useful to return to.

The landing after onboarding is the only entry to first-run guidance

First-run guidance in Flowo starts from exactly one call site. The completion screen builds the shell with a parameter named afterOnboarding set to true, and the shell calls FirstStepsService.start() only when that parameter is set. A normal launch builds the shell without it.

Starting the service records the start time and marks the first step, 'Your week's plan is ready', as done. The checklist therefore opens one step in. The state is one map in the encrypted metadata box with four fields.

• started_at: when the person landed after onboarding.
• hidden: whether the person closed the checklist for good.
• done: the names of the completed steps.
• shown: the names of the steps whose hint has been displayed.

An install that never called start shows nothing. People who finished onboarding on a build that predates the checklist are returning users, and an update does not present them with a beginner's list. Completing a step before start is ignored, so the task created inside onboarding does not count toward the checklist.

Real actions retire the guidance

Each first step in Flowo is completed by the action it teaches, and the completion call sits in the code that performs the action. There are five steps: the plan, adding a task, saying how a block went, writing a Braindump note, and sending a message to the assistant.

Creating a top-level task or an event completes the second step. A subtask does not. Confirming a passed block completes the third, saving any new Braindump note completes the fourth, and sending a chat message completes the fifth. The 'Got it' button on a hint also completes its step, and we record which of the two ways was used.

The third step waits for something real to exist. It becomes available when a block that belongs to the person's own task has ended and has no answer yet, looking back seven days. Sleep, meals and rest blocks do not qualify. Until then the checklist skips that step and labels it 'Opens once your first task has passed'.

Step names are persisted as strings. A step is retired by deleting its enum case and is never renamed, because a renamed step would read as not done on every existing install.

What a returning session gets instead

A returning session in Flowo opens Today at the current time with no checklist. An early build opened the day after onboarding at 00:00, which showed a screen full of sleep. We changed the landing so both kinds of session open on the now line.

The place on Today that holds the checklist shows an inline tip once the checklist is closed. There are five tips in total and three of them belong to Today. A tip is a card inside the content. It never covers the screen, only one shows per place, and it stays gone once done.

A tip is marked done when the person closes it or does what it describes. Pressing the create button retires the 'add' tip, and a long press on the same button retires the dictation tip. Tip state is one boolean per tip in device preferences. Settings has a Guides screen that can restore one tip or all of them, and it replays five topics as coach marks on the real controls.

Startup differs in two more ways. For a returning person the analytics SDKs start silently only when the stored analytics consent is still current, while a first-run person is asked on the consent screen and nothing starts before that. And the first time the app is opened on a new calendar day, a returning session replans quietly, leaving started blocks and everything inside a two-hour freeze horizon where they were.

Checks that must not confuse the two

Several startup checks in Flowo would misfire if they mistook a new install for a damaged old one, so each carries its own rule for telling them apart.

• The day-rhythm loss detector runs exactly once per install and stores its verdict. An empty schedule map counts as a fresh install, and a person who clears their own week later can never trigger the notice.
• The one-shot planner migration is skipped when onboarding is unfinished and there is no user data, because there is nothing to migrate.
• The timestamp that opens the launch-offer window is written only on the first completion of onboarding, so a second completion never reopens it.
• The store review prompt stamps the install date once and waits out a 24-hour settling period before it may appear.