Outcome
A new user can open Flect, sign in to Pi, and complete a successful agent turn without a terminal, setup documentation, role selection, or a disabled dead end.
Required behavior
- Detect missing, expired, and existing Pi authentication before the first prompt is submitted.
- Put the next actionable step directly in the composer area with a clear primary action.
- Support the authentication methods the bundled Pi runtime actually exposes and complete them inside Flect or through an explicit, safely handled browser handoff.
- Reuse valid existing authentication automatically and never ask for secrets already available to the runtime.
- Choose a sensible default model automatically; model selection remains available as progressive disclosure.
- Keep internal App/Shaper/Guardian roles and tool routing invisible to first-run users.
- Show bounded progress, cancellation, expiry, retry, and offline states without disabling the whole interface.
- Store credentials only through the platform's secure credential boundary and redact them from logs, history, diagnostics, screenshots, and issue reports.
- Preserve the user's draft prompt across authentication and retry.
Acceptance criteria
- From a clean browser profile and a clean packaged macOS profile, a user reaches a successful agent response without opening a terminal or reading setup docs.
- The missing-auth notice contains an action in the same surface; it never ends at a passive Try again button.
- Successful authentication resumes the preserved draft and sends it exactly once.
- Existing valid authentication skips setup and opens directly into the usable workspace.
- Cancelled, denied, expired, offline, provider-error, and app-restart paths all offer a clear next action and keep the composer usable.
- Default model selection succeeds automatically where possible and explains an actionable provider limitation where not.
- Chromium and packaged macOS tests verify the full first-run path with real Pi boundaries.
- No credential, token, authorization URL payload, or provider response body appears in source history, logs, telemetry, diagnostics, or screenshots.
- The first-run UI contains no Shape/Use, review-state, branch, reset-mode, or internal-agent terminology.
Non-goals
- Building a generic credential manager UI.
- Supporting providers or authentication modes the bundled runtime cannot execute.
- Exposing internal orchestration roles as setup choices.
Outcome
A new user can open Flect, sign in to Pi, and complete a successful agent turn without a terminal, setup documentation, role selection, or a disabled dead end.
Required behavior
Acceptance criteria
Non-goals