fix(onboarding): surface unavailable-agent install cards in the Local CLI empty state (#4662)

[maxmilian]

Fixes #4662

Why

Onboarding → Local coding agent is one of the first screens a new user hits. When no usable local CLI agent is detected, the empty state showed only a flat "No agents detected yet…" sentence + a Rescan button — a dead end at the exact moment the user most needs install guidance. Settings → Local CLI already renders rich per-agent install cards (Install/Docs links + diagnostics), so onboarding was strictly worse than Settings for the same situation. This surfaces the same cards in onboarding so the empty state becomes actionable.

(Filed by QA during #4632; the maintainer confirmed it's current behavior — not a fixture artifact — and suggested the shared-component approach.)

What users will see

In onboarding → Local coding agent, when no usable agent is detected, the empty state now shows the same unavailable-agent install cards as Settings: each supported CLI's icon + name + short description, Install / Docs links, and per-agent diagnostics (e.g. "… was not found on your PATH" with a fix action). The "No agents detected yet" sentence stays as the intro. Settings is unchanged.

Surface area

• UI — onboarding Local CLI empty state now renders the unavailable-agent install-card grid

(No new deps, API/contract, or i18n keys — reuses the existing Settings card markup + translation keys.)

Screenshots

Before — bare empty state (reporter's capture in the issue):

After — onboarding empty state now surfaces the install cards:

Bug fix verification

• Test path: apps/web/tests/components/EntryShell.onboarding-unavailable-agents.test.tsx
• Red on base / green on branch: yes. The primary test fails at expect(grid).toBeTruthy() (the .agent-grid-unavailable grid is absent) against the pre-fix bare empty state, and passes with the fix. A second test — wires the diagnostic Install fix-button to openExternalUrl — was also confirmed red without the onboarding onOpenFixUrl wiring, then green with it.
• Also covered: AMR is excluded from the onboarding grid; the no-unavailable-agents case renders only the sentence (no grid).

Validation

• Implementation: extracted the unavailable-agent install-card grid (previously inline in SettingsDialog.tsx) into a shared UnavailableAgentGrid component, reused in both Settings and onboarding (the maintainer-preferred "option 2"). Settings behavior is preserved byte-for-byte — the AMR-attribution / external-open handlers are passed in as props; onboarding excludes AMR (it has its own connect flow) and wires the diagnostic fix-buttons to openExternalUrl.
• pnpm typecheck (all packages): clean (exit 0)
• pnpm --filter @open-design/web test: 344 files / 3436 passed, 1 skipped, 0 failed

[lefarcen]

Thanks @maxmilian — opened as a draft, so I'll hold off on the full review until you mark it 'Ready for review'. Ping me whenever it's ready.

— open-design team

[maxmilian]

Thanks @lefarcen — heads-up that this is already out of draft: I flipped it to Ready for review at 07:55 UTC, just before your note landed (07:58), so it likely read the stale draft state. It's ready for the full review whenever you/the pool reviewer can pick it up. 🙏

[lefarcen]

Thanks for the heads-up — I picked up the ready-for-review state now.

🧪 This PR changes a user-facing onboarding flow, so it needs a manual QA pass before merge. Please hold off self-merging for now; we'll loop QA in once it's merge-ready.

[maxmilian]

Hi @lefarcen — I noticed this got converted back to draft on the 27th. Just want to make sure I'm not blocking anything: is there a change you'd like me to make, or is the draft state just parking it out of the merge queue while it waits for manual QA? Happy to address whatever's needed — let me know and I'll turn it around. 🙏

[lefarcen]

Hey @maxmilian — no new change request from me right now. From what I can see, the draft state is just parking this while the remaining manual gates finish: design is already approved, QA has been queued, and I don't need anything else from you unless QA or the code reviewer turns up something specific.

So for now you're not blocking this one — if another reviewer asks for a follow-up, we'll call it out directly here.

[kokisanai]

Hi @maxmilian!

This PR looks quiet for a bit, so I'm checking in to make sure it doesn't get stuck.

If you are waiting on review, feedback, or a specific unblock from the team, feel free to say so here. If faster coordination helps, you can also drop into our contributors channel in Discord:
https://discord.gg/3C6EWXbdQQ

We want to help move this forward instead of letting it stall.

[lefarcen]

Quick status for @maxmilian: this isn't waiting on a code change from you right now.

The remaining blocker on my side is design sign-off for the onboarding UI change; once that's in, QA can take the manual pass. If either reviewer needs a follow-up, we'll call it out here.

[maxmilian]

Rebased onto the latest main — conflict-free again. Heads-up that the force-push dismissed the earlier approval; nothing about the change itself moved.

The conflict was textual: upstream's modelCapabilityTags import landed on the line directly above this branch's UnavailableAgentGrid import in EntryShell.tsx. Both are kept.

Since this branch also lifts ~82 lines out of SettingsDialog.tsx into the shared grid, and main has touched that file a dozen times since the branch point, a clean merge wasn't enough to trust. Re-verified after the rebase:

• tsc -b --noEmit on apps/web — clean
• EntryShell.onboarding-unavailable-agents.test.tsx — 4/4 pass
• the full SettingsDialog.* suite — 219/219 pass

#4662 is still open and no equivalent fix has landed upstream, so this is still the change that closes it. Still parked on the manual QA pass as far as I know — no action needed from me unless QA or design turns something up.

[lefarcen]

Thanks for rebasing and for re-running the checks after the conflict.

From our side this still looks like the same onboarding fix on the new head, so there isn't anything new needed from you right now — it's still waiting on the remaining design sign-off before QA picks it up.

[maxmilian]

Just keeping this alive so it doesn't get swept into auto-close — still nothing outstanding on my end. It's rebased onto latest main and green on the current head, and I'm happy to leave it parked as a draft until the design sign-off and QA pass land. Ping me if anything turns up and I'll turn it around quickly.

[lefarcen]

Thanks for the keep-alive. I re-checked the current head and the changed paths are still the same onboarding install-card extraction in EntryShell, SettingsDialog, UnavailableAgentGrid, plus the onboarding regression test, so there isn't anything new needed from you right now.

This can stay parked as a draft while design sign-off lands; once that clears, QA is the next step. If either gate turns up something concrete, we'll call it out here.