Onboarding Did Not End on the Last Screen

This Haru Space development retrospective reconstructs August 10–16, 2026 from design documents, Git history, and operational incidents. It excludes real member, group, and repository information, internal addresses, credentials, and private conversations.

When we first built onboarding, we thought good guidance to the last screen would be enough. Place the Next button well, keep the explanation short, and send the user home from the completion screen. That seemed like the whole job.

Real journeys were not so straight.

Someone could close the browser after group approval. They could leave for external authentication while connecting a repository and never make it back. Their first code job could succeed while repository delivery failed. They might not have a Vercel account yet. And an empty repository and one that already contained code should never receive the same starting screen.

After encountering those problems, we changed the definition of onboarding completion.

Onboarding did not end on the last screen. It ended when someone could return the next day, avoid repeating completed work, and find the next safe action without losing anything at the point of failure.

A regular member’s first entry needed its own design

Early Haru Space onboarding focused on the administrator experience of creating a group and configuring its space and pet. Invited members and people whose applications had just been approved received much less help understanding what they needed to know after reaching the home screen.

We could not identify a new member from their account’s first login. A person may already have signed in several times while applying to a group and waiting for approval. Nor should first-user guidance appear again when the same person joins a second group.

We therefore separated first account login from first group membership. Only a regular member with no previous membership history received a staged onboarding state after their first approval.

The journey put the boundaries of group life before a tour of features.

1. Review the group’s operating rules and the distinction between official and informal spaces.
2. Choose how much of the profile appears in the group member directory.
3. Decide whether to enable device notifications.
4. Select a guide pet that is actually assigned to the current group.
5. Leave a first greeting, or choose a first AI conversation only if desired.

Each stage was stored on the server and could advance only one step at a time. Logging out or closing the browser returned the person to the current stage. Devices without push support and delayed AI responses both received an alternative route: postpone the choice or continue with an ordinary greeting.

We did not make AI spending a requirement for completing onboarding.

Hiding something on screen was different from hiding it on the server

Offering a profile-visibility choice raised an important question. Was hiding a profile in the regular member directory UI enough?

It was not. If the server still returned the full directory, another screen or API could reveal it again. We applied the visibility choice to the query policy itself. Group administrators could still see members for operational reasons, and we did not retroactively hide the author’s name from chats and activities the person had chosen to create.

We had to define honestly what one setting hid and what it did not. The word “private” could not imply that every historical trace would disappear.

Development onboarding stopped at a policy mismatch

Development connection for a new group administrator had a similar problem. The screen offered steps for connecting a repository and an AI runner, but the approval server allowed only the platform’s highest-level administrator to continue. The person who had created the group could not move their own group to the next stage.

The new group’s default repository-delivery setting was also interpreted as paused. A first pet could edit files successfully and then encounter an unexpected stop at commit and push. The screen and the execution layer disagreed about what was allowed.

We aligned both around the active administrator membership of the specific group. A group administrator could approve the runner connection for that group. Repository delivery began enabled for newly created groups, while automatic approval remained off. Existing groups kept the safety settings they had already saved.

That separated “available” from “automatically allowed.” A visible next action meant a person could request and approve it—not that the system was free to change the repository on its own.

We did not delete a failed commit and push

When repository delivery failed after the first job, the early UI offered no route to try again. The isolated workspace still held the files and verification results, yet it looked as if the user had to begin a new job.

On the other hand, offering only endless retries would force people to keep carrying a failure they wanted to abandon. Local workspaces would continue to accumulate as well.

We divided the next action after delivery failure into two choices.

• If the failure was transient, retry from the same isolated changes and verified commit.
• If the change should no longer be delivered, cancel it explicitly.

Cancellation was not an immediate delete button. It recorded the delivery state and the decision, and made the local isolated workspace eligible for cleanup after a grace period. A failed workspace could be the only source for a retry, so it was never automatically removed. The runner also could not delete a remote branch without checking the PR state and obtaining separate authority.

At the time, automated cleanup was not yet active. We defined what could be removed, when, and under which audit contract before building the deletion mechanism. Reducing preservation cost could not begin by erasing the recovery source.

A missing deployment account could not block the first job

The earlier onboarding flow behaved as if it could not finish without a first Preview URL. A group that had not connected Vercel could complete its code work and still stop at the last stage.

Deployment is an important outcome, but not every group prepares an operational account and domain on the same day. We turned deployment method into a choice.

• Connect the group’s own Vercel project.
• Use a constrained temporary Haru Space Preview when it is available.
• Skip it for now and connect one later.

Any of those paths could complete the first job and onboarding. The temporary Preview was not a way to deploy a sensitive project build. Its scope was a small static experience containing only the group name, and the absence of its configuration did not block onboarding.

Operational ownership remained separate. The platform could create an introductory deployment, but the real service needed to belong to the user’s own deployment account and project. Platform credentials were never copied into a user project.

We did not give an empty repository and existing code the same button

The most dangerous misunderstanding in the first-page flow was treating every repository as a blank canvas. Applying a default template over an existing codebase could damage the project.

Repository connection therefore began by classifying the root state.

• For an empty repository, a person chose between starting with the default project and leaving it empty.
• If code already existed, onboarding preserved it and connected without applying a starter.
• If it was already a Haru Starter, the previous journey resumed.
• If classification was uncertain, the system did not guess and asked for verification again.

The default project did not ask the AI to choose a framework and dependencies from scratch every time. The bridge first placed a verified Starter and pinned lockfile in the isolated workspace. The first AI job then focused on the small change of adapting the existing page title and description to the group’s purpose.

This reduced token use and network failure, and gave a new project a foundation for controlling external visibility from the beginning. The gate was disabled by default, however, so it did not unexpectedly change normal public behavior.

“Preparing to open” had to work in every real project

Haru Space could let an administrator choose whether a public site was public, preparing to open, under maintenance, or private. But if the status page existed only in the new Starter, changing the setting would have no effect on an existing site.

Existing public projects ran on different frameworks and runtimes. Rather than copy one file everywhere, we defined a shared contract and implemented it at the official entry point of each environment.

• Static assets and health checks avoid unnecessary gate calls.
• External visitors receive a status page excluded from search and caching.
• Active group members can inspect the real site through a short-lived, one-time proof.
• Public sites do not hold Haru Space’s private session or membership database.
• At this stage, the availability policy prevents a central control-plane failure from taking every existing public site down with it.

The decision also made explicit that a maintenance notice gate and a complete private-security boundary are different things. A search-exclusion marker is not access control. A service that must fail closed needs a separate enforcing proxy and operational policy.

Lightweight onboarding also required less idle work

If several runners checked project connection data at short intervals even when nobody was using the service, and if the public landing page read a session on every request, one onboarding journey could create ongoing cost.

We reduced periodic connection checks while adding immediate synchronization when the first job for a new project arrived. We separated the public landing page from the signed-in home so the public page could follow a static cache path.

This change was a measurable hypothesis, not a promise of savings. We recorded the request baseline and planned to compare Active CPU and error rates under the same project and time conditions. Within this period, we verified only that we had reduced the number of potential calls and established the measurement method. We did not present an unmeasured savings rate as a result.

The standard for a journey that can recover from failure

Over the week, we established the following principles for onboarding.

1. Preserve the human stage and the server facts together

The screen remembers how far the person got. Authority, connection, and runner readiness are reverified on the server.

2. Remove optional external services from completion requirements

A deployment account, push, and AI conversation should remain choices. Basic collaboration should not be blocked because one is not ready.

3. Classify existing assets before overwriting anything

Distinguish empty repositories, existing code, and a Starter. When uncertain, do not apply automatically.

4. Separate the next action after failure into retry and cancel

Preserve recoverable changes. Record the decision to stop in the audit history and turn it into a safe cleanup candidate.

5. Define the preservation contract before automatic cleanup

Do not remove an isolated workspace based on file age alone. Cleanup begins only when the job state and its relationship to the repository and remote PR can be verified.

6. Observe onboarding cost while the system is idle

Do not add a process per group. Synchronize when actual work arrives, and serve public screens statically whenever possible.

The next day’s first screen mattered more than the last button

The changes of August 10–16 did not make onboarding longer. Some stages became optional, some failures gained an explicit ending, and the default project was applied only after a person chose it.

A regular member could understand visibility and notifications in their first group before deciding whether to start a conversation. A group administrator could connect a repository and runner and begin the first job without a deployment account. If repository delivery failed, they could retry without losing the changes or end it explicitly.

Good onboarding did not push everyone to the end in one sitting. It remembered where they stopped, rechecked authority and external state when they returned, and presented the next choice that was safe now.

What we tried to complete was not a one-time guide with a high completion rate. It was a first journey that could be interrupted without losing trust.