feat(web): add OpenTag onboarding preview

[Gandy2025]

Summary

• add a development-only /preview/opentag-onboarding route for the grouped four-step OpenTag onboarding shell
• cover Step 1's confirmed focus-and-name design and Step 2's zero/one/multiple-computer selection, capability detection, provider selection, empty, and setup-command recovery states
• keep Step 3 focused on bot creation, QR confirmation, and genuine reachability without internal mapping prose, and prevent its Web action from advancing before reachability
• model Step 4 as a pure first-Feishu-message polling state followed by a server-fact completion endpoint that views the resulting task through /?c={firstUseChatId}
• reuse the standalone onboarding's Computer and Coding agent selection resolvers, catalog preference order, shared picker/summary components, neutral OptionCard pills, and opaque server-command rendering contract
• add URL-stable step, state, and viewport controls, with the grouped desktop rail and 390 px segmented mobile progress
• keep all fixtures deterministic and in memory, with the OpenTag product lockup and sentence-case product copy

Try it

pnpm --filter @first-tree/web dev

Start at:

http://localhost:5173/preview/opentag-onboarding?step=focus&state=ready&viewport=desktop

Step 2 examples:

• zero computer: ?step=computer&state=no-computer&viewport=desktop
• setup-command error: ?step=computer&state=command-error&viewport=desktop
• one computer: ?step=computer&state=ready&viewport=desktop
• multiple computers: ?step=computer&state=multiple-computers&viewport=desktop
• capability check: ?step=computer&state=checking&viewport=desktop
• no supported coding agent: ?step=computer&state=no-coding-agent&viewport=desktop
• mobile: ?step=computer&state=ready&viewport=mobile

Step 4 examples:

• waiting for real first use: ?step=first-task&state=waiting&viewport=desktop
• task created: ?step=first-task&state=completed&viewport=desktop
• mobile waiting: ?step=first-task&state=waiting&viewport=mobile

Verification

• pnpm --filter @first-tree/web typecheck — passed, including Design System token guardrails
• pnpm --filter @first-tree/web build — passed; Preview route strings and fixtures are absent from the production bundle
• pnpm exec biome check packages/web/src/pages/opentag-onboarding-preview.tsx — passed
• real-browser Step 2 matrix — all six URL-addressable states verified; single-computer auto-selection, multi-computer gating, Codex-first default, selectable one-provider pill, manual-provider preservation/fallback, and setup-command retry verified
• desktop and 390×844 mobile evidence — no horizontal overflow; command fixture remains an unchanged first-tree installer/login response shape while prose stays brand-neutral
• real-browser Step 3/4 boundary — Step 3 enters provisioning instead of skipping reachability; Step 4 waiting has no Web action; completed copy and the View task destination were verified on desktop, with waiting also verified at 390×844

The local preview reports one expected /api/v1/bootstrap/config proxy error when the API server is not running; the dev-only fixture route still renders and operates independently.

Scope

This preview is fixture-only and performs no persistence, API mutation, analytics, provisioning, lifecycle, or production /opentag changes.

[yuezengwu]

Reviewed the implementation and found no blocking issues. The development-only route keeps the preview and embedded brand assets out of production builds; the computer/runtime states reuse the shared selection logic and preserve the server-authored command boundary; and the Feishu reachability plus first-Task completion flow matches the intended product boundary.

[baixiaohang]

Recommendation: request changes

• Rationale: The preview does not preserve the Agent draft across its own forward path, and it cannot demonstrate the claimed reachability gate between Feishu confirmation and first-use polling.

Risk level: C

• Path baseline: changes are limited to packages/web/**.
• Semantic lift: none; the route is development-only and fixture-backed.

PR summary

• Author / repo: Gandy2025 / agent-team-foundation/first-tree
• Problem: Give product reviewers a shareable desktop/mobile preview of the four-step OpenTag first-use journey, including Computer/runtime edge states and the final Feishu-created task handoff.
• Approach: Add a development-only route with URL-addressable fixtures, shared Computer/runtime selection helpers, grouped progress, Feishu QR/waiting states, and a completed-task destination.
• Impacted modules: Web app route registration, the OpenTag onboarding preview page, and preview-only brand assets.

Review findings
❌ 1. The chosen focus and Agent name are local to FocusAndNameStep; after advancing, Step 2 always renders gandy2025 assistant · Team Assistant, and completion repeats the same hard-coded name. Selecting Researcher/Software Engineer or editing the name therefore produces a contradictory draft immediately on the next screen. Lift the draft to the page-level state and derive every downstream summary/status from it. [R1 / packages/web/src/pages/opentag-onboarding-preview.tsx:398, :636, :704]
❌ 2. Step 3 has only ready and provisioning: clicking its CTA can only enter an indefinite “Waiting for Feishu to confirm” screen. There is no fixture for provisioned-but-unreachable, connection failure, or reachable, so the preview cannot show the PR's central boundary that Step 4 begins only after genuine reachability; the controller can jump directly to Step 4 regardless. Model the server facts explicitly and make the reachable state the only transition into first-task polling. [R4 / packages/web/src/pages/opentag-onboarding-preview.tsx:37, :388, :652]
⚠️ 3. “Back to focus & name” is rendered as an enabled button with no handler, so the draft-editing path cannot be reviewed from the Computer recovery state. Wire it to the same step transition used by the shell. [R4 / packages/web/src/pages/opentag-onboarding-preview.tsx:516]

Action taken

• Submitted request changes.