Imported from LodyAI/Lody (packages/components/src/components/onboarding/AGENTS.md). Install upstream with npx skills add LodyAI/Lody --skill onboarding. Copyright stays with the author.

Desktop Onboarding

• Electron opens /onboarding in the primary product renderer. Do not add a second window, renderer entry, provider tree, or runtime lease for onboarding.
• The Electron main process owns the durable completion marker. Product navigation starts immediately alongside that write and never waits for its IPC; renderer storage owns only resumable phase and draft state, and is cleared after both product navigation and the completion IPC succeed.
• Build the flow from platform capabilities. Local builds must not import or call cloud auth, workspace, or GitHub implementations.
• Provider selection distinguishes a published AgentConfig from a pending ProviderSetupTask; a setup task ID must never be stored or dispatched as an AgentConfig ID. Both selections may continue through project setup, but only a published AgentConfig paired with a local project enters First Task. A pending setup finishes on Summary while setup continues.
• User-facing onboarding copy calls the execution choice an Agent. Reserve Provider for Settings configuration management and internal AgentConfig/ProviderSetup state.
• Completion stays in the existing router and navigates to the created session when one exists. Reload recovery must target the normal product root after completion.
• Desktop onboarding owns the app theme for its whole route lifetime: enter and reload in light, and restore the persisted source to system only after completion succeeds or the route unmounts.
• Managed built-in runtimes prefetch CONCURRENTLY from onboarding mount, deduped per machine and agent, so the felt wait is the longest download rather than their sum. A selected provider only moves to the FRONT of the launch order; it never restarts or waits behind work in flight. Background prefetch must not subscribe to per-percent progress — handleMachineAcpBinaryProgress records a snapshot for everyone else, and a concurrent download would otherwise render-storm the ceremony animation.
• ceremony/intro-sequence.tsx owns the four-beat illustrated intro. Keep its approved assets and direction in intro-illustration-direction.md; setup screens must not replace it with a generic welcome card.
• Setup screens use the real TourStill product composition. Its Browser beat includes the production Visual Annotation surfaces; do not replace the tour with a hand-built mock.
• Provider rows keep the last durable result separate from request-scoped activity, and runtime progress comes from the refresh request owning the config, never the machine-and-agent global snapshot. AgentConfig tests and ProviderSetup rows share one progress button and one COLUMN GRID of FIXED-WIDTH slots (status, Edit, action, delete), because their contents are not fixed width and an intrinsic cluster moved every other column with them. A control that will not fit a slot replaces its occupant rather than widening the cluster; there is never a second activity row. Only SELECTION tints a row — status is the badge's job. A failed result keeps its reason inspectable from the badge until success or a config mutation clears it, and a status that already failed (error, unsupported-platform, incompatible-host) stays runtime-failed instead of reverting to checking-runtime: in-flight activity must not present a known failure as work in progress.
• Wait escalation is one binding, providerWaitEscalation. It changes what the UI CLAIMS and never invents a denominator. Its clock is REQUEST-scoped, so exceptional copy speaks of the whole setup, not the current stage — that would pin the elapsed number on work a second old. buildProviderWaitReport is that tier's pasteable block (unlocalized, phase ids), carried by the progress pill itself so the row's action column keeps its width.
• Leaving the step DETACHES probes, never aborts: the machine drops a refresh once its last consumer leaves, so unmount-abort made "continue" mean "give up on this agent". No late result may commit after edit, delete, replace, or unmount, but only the first three cancel (invalidate); detachAll blocks the commit alone, which is what lets the copy promise background work.
• The first-task primary action never strands onboarding behind run prerequisites or Session persistence. It requests product navigation immediately; when that navigation succeeds and a runnable prompt exists, Session creation and dispatch continue only as best-effort background work and never navigate or delay entry into the product. Failed navigation creates no Session and remains retryable. An empty task becomes Enter Lody rather than a disabled final action.
• Workspace is required product context when the platform exposes multi-workspace onboarding, so it has no Skip or Enter Lody action. A failed workspace-list read keeps the investigation detail and a real platform-backed Retry action. Mutations use bounded waits: after a stale write the UI releases its attempt lock so the user may retry or go back, while late results never navigate or clear a newer attempt. A slow slug availability query is still pending, not failed: explain the slow network, keep Create disabled until the server answers, and let the user restart the check without treating elapsed time as validation. Query errors stay inside the slug field with their detail and Retry. A slug-less existing workspace is repaired inline because its Settings route is unreachable until the slug exists.
• Every onboarding error path writes its underlying error or failure detail to console.error even when the UI also shows an inline message or toast. Recoverable user actions must become retryable again after failure; never leave an error with only explanatory copy when the same operation can be attempted safely.
• Desktop onboarding analytics use the shared flow/step/operation/completion event contract and one anonymous session-scoped flow_id. Capture is hard-gated by the platform telemetry capability, so the OSS local composition emits nothing. Properties may contain fixed state, action, failure-code, attempt, count, and duration values; never send names, slugs, repository paths, prompts, raw error messages, or other user-authored text.
• First Task keeps an exact published AgentConfig selection and may switch only among published configs on the selected project's machine. It never falls back to another config when that selection disappears. Skipping First Task completes onboarding without creating a Session, first turn, or dispatch request.
• Skipping provider setup completes onboarding as an exploration path. Its summary must not claim the product is ready to run; it sends the user into Lody and points later agent setup to Settings. This is distinct from the pending-setup summary, which uses a compact status table and says setup is still progressing without guessing whether the current work is download, installation, verification, authentication, or machine availability. The summary reads the live ProviderSetupTask: a durable failed status shows as setup failed (never as still progressing), and a deleted task shows as not configured — unless the machine has already replaced it with a published AgentConfig under the same id, which reads as ready.
• Provider setup failure codes are internal diagnostics. Onboarding maps them to specific, actionable user copy and never prints the raw enum in the UI.