@swarmclawai/swarmclaw 1.6.1 → 1.7.0

package/README.md

@@ -399,15 +399,24 @@ Operational docs: https://swarmclaw.ai/docs/observability
 
 ## Releases
 
-### v1.6.1 Highlights
+### v1.7.0 Highlights
 
-Follow-up release for v1.6 with workflow starts, safer metadata handling, A2A discovery polish, and [#61](https://github.com/swarmclawai/swarmclaw/pull/61) by [@latentwill](https://github.com/latentwill). Thanks latentwill!
+Extended CLI provider roster, first-run polish, and a batch of v1.6 follow-ups including [#61](https://github.com/swarmclawai/swarmclaw/pull/61) by [@latentwill](https://github.com/latentwill). Thanks latentwill!
 
+**Coding-agent reach**
+
+- **31 new CLI providers.** Aider, Amp, Augment, AdaL, IBM Bob, Cline, CodeBuddy, Command Code, Continue, Cortex Code, Crush, Deep Agents, Firebender, iFlow, Junie, Kilo Code, Kimi, Kode, MCPJam, Mistral Vibe, Mux, Neovate, OpenHands, Pochi, Qoder, Replit Agent, Roo Code, TRAE CN, Warp Agent, Windsurf, and Zencoder are now first-class provider IDs in `ProviderType`, matching the SwarmSkills roster.
+- **Generic CLI streamer.** New `streamGenericCliChat` (`src/lib/providers/generic-cli.ts`) spawns the configured binary with the prompt as final argv and emits stdout lines as SSE deltas. Used by the new providers when no bespoke parser is available; existing bespoke parsers (Claude, Codex, Cursor, Gemini, Copilot, Droid, Qwen, OpenCode, Goose) are untouched.
+- **Capability metadata.** `CLI_PROVIDER_CAPABILITIES` (`src/lib/providers/cli-utils.ts`) carries a one-line description for each new provider so the UI and `isCliProvider()` recognize them.
+
+**First-run and operator polish**
+
+- **First useful action after install.** Setup completion and the home launchpad share the same assistant, workflow, and mission paths.
+- **Provider setup is easier to scan.** The setup wizard groups providers into fast local/no-key starts, recommended API providers, and advanced catalog/custom options, with the readiness check visible before provider details.
 - **Mission and protocol templates for real work.** New starter paths cover codebase review sprints, research bureau scans, content studio cycles, release readiness panels, synthesis panels, and builder review loops.
-- **Home launchpad paths.** First-run users can choose a self-hosted assistant, visual workflow, or autonomous mission path, with quality actions still one click away.
-- **A2A discovery is easier to integrate.** The canonical `/.well-known/agent-card.json` endpoint now works alongside the legacy API route and hides disabled or trashed agents from public discovery.
+- **A2A discovery is easier to integrate.** The canonical `/.well-known/agent-card.json` endpoint works alongside the legacy API route and hides disabled or trashed agents from public discovery.
 - **Internal metadata stripping is safer.** Side-channel JSON is removed with balanced-object parsing and zod validation so nested payloads are scrubbed without deleting ordinary user JSON.
-- **Browser smoke gate restored.** `npm run test:e2e` now runs a Playwright smoke against health, A2A discovery, `/home`, and `/quality`, either against a live URL or a temporary local dev server.
+- **Browser smoke gate restored.** `npm run test:e2e` runs a Playwright smoke against health, A2A discovery, `/home` launch paths, and `/quality`, either against a live URL or a temporary local dev server.
 - **OpenCode CLI hang fixed.** OpenCode CLI delegation no longer keeps an inherited stdin pipe open, preventing hangs in non-interactive runs.
 
 ### v1.6.0 Highlights

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "description": "Build and run autonomous AI agents with OpenClaw, Hermes, multiple model providers, orchestration, delegation, memory, skills, schedules, and chat connectors.",
   "main": "electron-dist/main.js",
   "license": "MIT",
@@ -87,7 +87,7 @@
     "test:cli": "node --test src/cli/*.test.js bin/*.test.js scripts/postinstall.test.mjs scripts/run-next-build.test.mjs scripts/run-next-typegen.test.mjs",
     "test:setup": "tsx --test src/app/api/setup/check-provider/route.test.ts src/lib/server/provider-model-discovery.test.ts src/components/auth/setup-wizard/utils.test.ts src/components/auth/setup-wizard/types.test.ts src/hooks/setup-done-detection.test.ts src/lib/setup-defaults.test.ts src/lib/server/storage-auth.test.ts src/lib/server/storage-auth-docker.test.ts",
     "test:openclaw": "tsx --test src/lib/openclaw/openclaw-agent-id.test.ts src/lib/openclaw/openclaw-endpoint.test.ts src/lib/server/agents/agent-runtime-config.test.ts src/lib/server/build-llm.test.ts src/lib/server/connectors/connector-routing.test.ts src/lib/server/connectors/openclaw.test.ts src/lib/server/connectors/swarmdock.test.ts src/lib/server/gateway/protocol.test.ts src/lib/server/llm-response-cache.test.ts src/lib/server/mcp-conformance.test.ts src/lib/server/openclaw/agent-resolver.test.ts src/lib/server/openclaw/deploy.test.ts src/lib/server/openclaw/skills-normalize.test.ts src/lib/server/session-tools/openclaw-nodes.test.ts src/lib/server/session-tools/swarmdock.test.ts src/lib/server/tasks/task-quality-gate.test.ts src/lib/server/tasks/task-validation.test.ts src/lib/server/tool-capability-policy.test.ts src/lib/providers/openai.test.ts src/lib/providers/openclaw-exports.test.ts src/app/api/openclaw/dashboard-url/route.test.ts",
-    "test:runtime": "tsx --test src/lib/a2a/agent-card.test.ts src/lib/strip-internal-metadata.test.ts src/lib/providers/opencode-cli.test.ts src/lib/server/mcp-gateway-runtime.test.ts src/lib/server/mcp-connection-pool.test.ts src/lib/server/knowledge-sources.test.ts src/lib/server/chat-execution/chat-execution-grounding.test.ts src/lib/server/chat-execution/chat-turn-preparation.test.ts src/lib/server/chat-execution/iteration-timers.test.ts src/lib/server/chat-execution/post-stream-finalization.test.ts src/lib/server/chats/clear-undo-snapshots.test.ts src/lib/server/connectors/email.test.ts src/lib/server/protocols/protocol-service.test.ts src/lib/server/runtime/run-ledger.test.ts src/lib/server/observability/otel-config.test.ts src/lib/server/safe-parse-body.test.ts src/lib/server/missions/mission-templates.test.ts src/lib/app/view-constants.test.ts src/lib/quality/quality-summary.test.ts src/app/api/approvals/route.test.ts src/app/api/agents/agents-route.test.ts src/app/api/tasks/tasks-route.test.ts src/app/api/chats/chat-route.test.ts src/app/api/chats/clear-route.test.ts src/app/api/chats/compact-route.test.ts src/app/api/chats/context-status-route.test.ts src/app/api/connectors/connector-doctor-route.test.ts src/app/api/healthz/route.test.ts src/app/api/logs/route.test.ts src/app/api/providers/[id]/route.test.ts src/app/api/tts/route.test.ts",
+    "test:runtime": "tsx --test src/lib/a2a/agent-card.test.ts src/lib/strip-internal-metadata.test.ts src/lib/providers/opencode-cli.test.ts src/lib/providers/cli-utils.test.ts src/lib/providers/generic-cli.test.ts src/lib/server/mcp-gateway-runtime.test.ts src/lib/server/mcp-connection-pool.test.ts src/lib/server/knowledge-sources.test.ts src/lib/server/chat-execution/chat-execution-grounding.test.ts src/lib/server/chat-execution/chat-turn-preparation.test.ts src/lib/server/chat-execution/iteration-timers.test.ts src/lib/server/chat-execution/post-stream-finalization.test.ts src/lib/server/chats/clear-undo-snapshots.test.ts src/lib/server/connectors/email.test.ts src/lib/server/protocols/protocol-service.test.ts src/lib/server/runtime/run-ledger.test.ts src/lib/server/observability/otel-config.test.ts src/lib/server/safe-parse-body.test.ts src/lib/server/missions/mission-templates.test.ts src/lib/app/view-constants.test.ts src/lib/quality/quality-summary.test.ts src/app/api/approvals/route.test.ts src/app/api/agents/agents-route.test.ts src/app/api/tasks/tasks-route.test.ts src/app/api/chats/chat-route.test.ts src/app/api/chats/clear-route.test.ts src/app/api/chats/compact-route.test.ts src/app/api/chats/context-status-route.test.ts src/app/api/connectors/connector-doctor-route.test.ts src/app/api/healthz/route.test.ts src/app/api/logs/route.test.ts src/app/api/providers/[id]/route.test.ts src/app/api/tts/route.test.ts",
     "test:builder": "tsx --test src/features/protocols/builder/utils/nodes-to-template.test.ts src/features/protocols/builder/utils/template-to-nodes.test.ts src/features/protocols/builder/validators/dag-validator.test.ts",
     "test:e2e": "node --import tsx scripts/browser-e2e-smoke.ts",
     "test:mcp:conformance": "node --import tsx ./scripts/mcp-conformance-check.ts",

package/src/app/home/page.tsx

@@ -14,7 +14,13 @@ import { useNavigate } from '@/lib/app/navigation'
 import { safeStorageGet, safeStorageRemove } from '@/lib/app/safe-storage'
 import { isLocalhostBrowser, isVisibleSessionForViewer } from '@/lib/observability/local-observability'
 import { getSessionLastMessage } from '@/lib/chat/session-summary'
-import { DEFAULT_BUILDER_ROUTE, deriveHomeMode, HOME_LAUNCHPAD_AFTER_SETUP_KEY } from '@/lib/home-launchpad'
+import {
+  deriveHomeMode,
+  HOME_LAUNCHPAD_AFTER_SETUP_KEY,
+  resolveLaunchPathHref,
+  type LaunchPathAction,
+  type LaunchPathId,
+} from '@/lib/home-launchpad'
 import { getNotificationActivityAt, getNotificationOccurrenceCount } from '@/lib/notifications/notification-utils'
 import { timeAgo, timeUntil } from '@/lib/time-format'
 import type { Agent, Session, BoardTask, AppNotification, ActivityEntry } from '@/types'
@@ -254,16 +260,8 @@ export default function HomePage() {
     todayCost,
   })
 
-  const openFirstAgent = () => {
-    if (firstAgent) {
-      navigateTo('agents', firstAgent.id)
-      return
-    }
-    navigateTo('agents')
-  }
-
-  const openBuilder = () => {
-    router.push(DEFAULT_BUILDER_ROUTE)
+  const handleLaunchPathAction = (id: LaunchPathId, action: LaunchPathAction) => {
+    router.push(resolveLaunchPathHref(id, action, firstAgent?.id))
   }
 
   if (homeMode === 'launchpad') {
@@ -278,15 +276,8 @@ export default function HomePage() {
             scheduleCount={scheduleCount}
             connectorCount={connectorCount}
             todayCost={todayCost}
-            onOpenFirstAgent={openFirstAgent}
-            onOpenProtocols={() => navigateTo('protocols')}
-            onOpenBuilder={openBuilder}
-            onOpenConnectors={() => navigateTo('connectors')}
+            onLaunchPathAction={handleLaunchPathAction}
             onOpenUsage={() => navigateTo('usage')}
-            onRunEvalSuite={() => navigateTo('quality')}
-            onReviewApprovals={() => navigateTo('quality')}
-            onInspectFailedRuns={() => navigateTo('quality')}
-            onStartReleaseQaMission={() => navigateTo('missions')}
           />
         </div>
       </MainContent>

package/src/components/auth/setup-wizard/index.tsx

@@ -11,7 +11,7 @@ import {
   type OnboardingPath,
   type SetupProvider,
 } from '@/lib/setup-defaults'
-import { DEFAULT_BUILDER_ROUTE } from '@/lib/home-launchpad'
+import { resolveLaunchPathHref } from '@/lib/home-launchpad'
 import type {
   SetupStep,
   SetupWizardProps,
@@ -482,11 +482,7 @@ export function SetupWizard({ onComplete }: SetupWizardProps) {
         <StepNext
           createdAgents={createdAgents}
           onContinueToDashboard={() => finishSetup('/home')}
-          onOpenFirstAgent={() => finishSetup(createdAgents[0]?.id ? `/agents/${encodeURIComponent(createdAgents[0].id)}` : '/agents')}
-          onOpenProtocols={() => finishSetup('/protocols')}
-          onOpenBuilder={() => finishSetup(DEFAULT_BUILDER_ROUTE)}
-          onOpenConnectors={() => finishSetup('/connectors')}
-          onOpenUsage={() => finishSetup('/usage')}
+          onLaunchPathAction={(id, action) => finishSetup(resolveLaunchPathHref(id, action, createdAgents[0]?.id))}
         />
       )}
 

package/src/components/auth/setup-wizard/step-next.tsx

@@ -1,19 +1,48 @@
 'use client'
 
-import { LaunchActionCard } from '@/components/shared/launch-action-card'
+import { getLaunchPathCards, type LaunchPathAction, type LaunchPathCardCopy, type LaunchPathId } from '@/lib/home-launchpad'
 import type { StepNextProps } from './types'
 import { StepShell } from './shared'
 
+function PathCard({
+  card,
+  onAction,
+}: {
+  card: LaunchPathCardCopy
+  onAction: (id: LaunchPathId, action: LaunchPathAction) => void
+}) {
+  return (
+    <div className="flex min-h-[220px] flex-col rounded-[18px] border border-white/[0.07] bg-white/[0.03] p-5 text-left">
+      <div className="text-[11px] font-700 uppercase tracking-[0.12em] text-text-3/55">{card.kicker}</div>
+      <div className="mt-3 text-[18px] font-display font-700 tracking-normal text-text">{card.title}</div>
+      <p className="mt-2 flex-1 text-[13px] leading-relaxed text-text-3/72">{card.description}</p>
+      <div className="mt-5 flex flex-wrap gap-2">
+        <button
+          type="button"
+          onClick={() => onAction(card.id, 'primary')}
+          className="rounded-[10px] bg-accent-bright px-3.5 py-2 text-[12px] font-display font-700 text-black transition-opacity hover:opacity-90"
+        >
+          {card.primaryLabel}
+        </button>
+        <button
+          type="button"
+          onClick={() => onAction(card.id, 'secondary')}
+          className="rounded-[10px] border border-white/[0.08] bg-white/[0.04] px-3.5 py-2 text-[12px] font-display font-700 text-text-2 transition-colors hover:bg-white/[0.08]"
+        >
+          {card.secondaryLabel}
+        </button>
+      </div>
+    </div>
+  )
+}
+
 export function StepNext({
   createdAgents,
   onContinueToDashboard,
-  onOpenFirstAgent,
-  onOpenProtocols,
-  onOpenBuilder,
-  onOpenConnectors,
-  onOpenUsage,
+  onLaunchPathAction,
 }: StepNextProps) {
   const firstAgent = createdAgents[0] || null
+  const launchPathCards = getLaunchPathCards({ firstAgentName: firstAgent?.name })
 
   return (
     <StepShell wide>
@@ -29,46 +58,10 @@ export function StepNext({
           : 'You finished setup without starter agents, so the launch options below focus on wiring up the rest of the workspace.'}
       </p>
 
-      <div className="grid gap-3 md:grid-cols-2 xl:grid-cols-3 mb-8">
-        <LaunchActionCard
-          title={firstAgent ? 'Open First Agent Chat' : 'Open Agents'}
-          description={firstAgent
-            ? `Jump straight into ${firstAgent.name} and start working from the workspace you just created.`
-            : 'Open the agents workspace so you can create or tune the first agent manually.'}
-          actionLabel={firstAgent ? 'Open Chat' : 'Open Agents'}
-          onClick={onOpenFirstAgent}
-          tone="primary"
-        />
-        <LaunchActionCard
-          title="Start Structured Session"
-          description="Open bounded collaboration runs for reviews, planning rounds, decision-making, or focused multi-agent work."
-          actionLabel="Open Protocols"
-          onClick={onOpenProtocols}
-        />
-        <LaunchActionCard
-          title="Open Workflow Builder"
-          description="Jump into the visual protocol builder if you want a reusable orchestration graph instead of a one-off run."
-          actionLabel="Open Builder"
-          onClick={onOpenBuilder}
-        />
-        <LaunchActionCard
-          title="Connect a Platform"
-          description="Bridge agents into Discord, Slack, Telegram, WhatsApp, or other runtime connectors."
-          actionLabel="Open Connectors"
-          onClick={onOpenConnectors}
-        />
-        <LaunchActionCard
-          title="Review Usage"
-          description="Inspect cost, provider health, and agent activity so the workspace stays observable from day one."
-          actionLabel="Open Usage"
-          onClick={onOpenUsage}
-        />
-        <LaunchActionCard
-          title="Go to Dashboard"
-          description="Land on the main home view. Fresh workspaces open in guided launch mode before switching to the normal ops dashboard."
-          actionLabel="Open Home"
-          onClick={onContinueToDashboard}
-        />
+      <div className="grid gap-3 xl:grid-cols-3 mb-8">
+        {launchPathCards.map((card) => (
+          <PathCard key={card.id} card={card} onAction={onLaunchPathAction} />
+        ))}
       </div>
 
       <button

package/src/components/auth/setup-wizard/step-providers.tsx

@@ -3,10 +3,89 @@
 import { useState } from 'react'
 import { api } from '@/lib/app/api-client'
 import { errorMessage } from '@/lib/shared-utils'
-import { SETUP_PROVIDERS } from '@/lib/setup-defaults'
 import type { StepProvidersProps, SetupDoctorResponse } from './types'
+import { getSetupProviderGroups } from './utils'
 import { StepShell, ConfiguredProviderChips } from './shared'
 
+function ReadinessPanel({
+  state,
+  report,
+  error,
+  onRun,
+}: {
+  state: 'idle' | 'checking' | 'done' | 'error'
+  report: SetupDoctorResponse | null
+  error: string
+  onRun: () => void
+}) {
+  const problemChecks = report?.checks.filter((check) => check.status !== 'pass') || []
+  const statusLabel = state === 'done'
+    ? report?.ok
+      ? 'Ready'
+      : `${problemChecks.length} item${problemChecks.length === 1 ? '' : 's'} to review`
+    : state === 'error'
+      ? 'Check failed'
+      : 'Optional check'
+
+  return (
+    <div className="mb-6 rounded-[16px] border border-white/[0.08] bg-white/[0.025] p-4 text-left">
+      <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
+        <div>
+          <div className="text-[12px] font-display font-700 text-text">Setup readiness</div>
+          <p className="mt-1 text-[12px] leading-relaxed text-text-3/70">
+            Check Node, npm, local storage, secrets, and starter workspace state before connecting a provider.
+          </p>
+        </div>
+        <button
+          type="button"
+          onClick={onRun}
+          disabled={state === 'checking'}
+          className="shrink-0 rounded-[10px] border border-white/[0.08] bg-white/[0.04] px-3 py-2 text-[12px] font-display font-700 text-text-2 transition-colors hover:bg-white/[0.08] disabled:opacity-40"
+        >
+          {state === 'checking' ? 'Checking...' : 'Run Check'}
+        </button>
+      </div>
+
+      <div className="mt-3 flex flex-wrap items-center gap-2">
+        <span className={`rounded-full px-2.5 py-1 text-[11px] font-700 ${
+          state === 'done' && report?.ok
+            ? 'bg-emerald-500/10 text-emerald-300'
+            : state === 'done' || state === 'error'
+              ? 'bg-amber-500/10 text-amber-300'
+              : 'bg-white/[0.05] text-text-3'
+        }`}>
+          {statusLabel}
+        </span>
+        {report && (
+          <span className="text-[11px] text-text-3/65">
+            {report.summary}
+          </span>
+        )}
+        {state === 'error' && error && (
+          <span className="text-[11px] text-rose-300">{error}</span>
+        )}
+      </div>
+
+      {problemChecks.length > 0 && (
+        <div className="mt-3 grid gap-2 sm:grid-cols-2">
+          {problemChecks.slice(0, 4).map((check) => (
+            <div key={check.id} className="rounded-[10px] border border-white/[0.06] bg-white/[0.025] px-3 py-2">
+              <div className="text-[11px] font-700 text-text-2">{check.label}</div>
+              <div className="mt-0.5 text-[11px] leading-relaxed text-text-3/70">{check.detail}</div>
+            </div>
+          ))}
+        </div>
+      )}
+
+      {!!report?.actions?.length && (
+        <div className="mt-3 text-[11px] leading-relaxed text-text-3/70">
+          Next: {report.actions.slice(0, 2).join(' ')}
+        </div>
+      )}
+    </div>
+  )
+}
+
 export function StepProviders({
   configuredProviders,
   configuredProviderIds,
@@ -21,6 +100,7 @@ export function StepProviders({
   const [doctorState, setDoctorState] = useState<'idle' | 'checking' | 'done' | 'error'>('idle')
   const [doctorError, setDoctorError] = useState('')
   const [doctorReport, setDoctorReport] = useState<SetupDoctorResponse | null>(null)
+  const providerGroups = getSetupProviderGroups()
 
   const runSetupDoctor = async () => {
     setDoctorState('checking')
@@ -50,84 +130,70 @@ export function StepProviders({
 
       <ConfiguredProviderChips providers={configuredProviders} onRemove={onRemoveProvider} />
 
-      <div className="flex flex-col gap-3 max-h-[42vh] overflow-y-auto pr-1">
-        {SETUP_PROVIDERS.map((candidate) => {
-          const isConfigured = configuredProviderIds.has(candidate.id)
-          return (
-            <button
-              key={candidate.id}
-              onClick={() => onSelectProvider(candidate.id)}
-              className={`w-full px-5 py-4 rounded-[14px] border bg-surface text-left
-                transition-all duration-200 flex items-start gap-4 cursor-pointer
-                ${isConfigured
-                  ? 'border-emerald-500/25 hover:border-emerald-500/40 hover:bg-surface-hover'
-                  : 'border-white/[0.08] hover:border-accent-bright/30 hover:bg-surface-hover'
-                }`}
-            >
-              <div className={`w-10 h-10 rounded-[10px] border flex items-center justify-center shrink-0 mt-0.5 ${
-                isConfigured ? 'bg-emerald-500/10 border-emerald-500/20' : 'bg-white/[0.04] border-white/[0.06]'
-              }`}>
-                <span className={`text-[16px] font-display font-700 ${isConfigured ? 'text-emerald-400' : 'text-accent-bright'}`}>
-                  {candidate.icon}
-                </span>
-              </div>
-              <div className="flex-1">
-                <div className="text-[15px] font-display font-600 text-text mb-1">
-                  {candidate.name}
-                  {isConfigured ? (
-                    <span className="ml-2 inline-flex items-center gap-1 px-2 py-0.5 rounded-md bg-emerald-500/10 text-emerald-300 text-[10px] uppercase tracking-[0.08em] font-600">
-                      Connected · Edit
-                    </span>
-                  ) : candidate.badge ? (
-                    <span className="ml-2 inline-flex items-center gap-1 px-2 py-0.5 rounded-md bg-accent-bright/15 text-accent-bright text-[10px] uppercase tracking-[0.08em] font-600">
-                      {candidate.badge}
-                    </span>
-                  ) : null}
-                </div>
-                <div className="text-[13px] text-text-3 leading-relaxed">{candidate.description}</div>
-                {!candidate.requiresKey && !isConfigured && (
-                  <div className="mt-1.5 inline-flex items-center gap-1.5 px-2 py-0.5 rounded-md bg-emerald-500/10 text-emerald-400 text-[11px] font-500">
-                    <span className="w-1.5 h-1.5 rounded-full bg-emerald-400" />
-                    No API key required
-                  </div>
-                )}
-              </div>
-            </button>
-          )
-        })}
-      </div>
-
-      <div className="mt-4 text-left">
-        <button
-          onClick={runSetupDoctor}
-          disabled={doctorState === 'checking'}
-          className="w-full px-4 py-3 rounded-[12px] border border-white/[0.08] bg-white/[0.02] text-[13px] text-text-2
-            cursor-pointer hover:bg-white/[0.05] transition-all duration-200 disabled:opacity-40"
-        >
-          {doctorState === 'checking' ? 'Running System Check...' : 'Run System Check'}
-        </button>
+      <ReadinessPanel
+        state={doctorState}
+        report={doctorReport}
+        error={doctorError}
+        onRun={runSetupDoctor}
+      />
 
-        {doctorState === 'error' && doctorError && (
-          <p className="mt-2 text-[12px] text-red-300">{doctorError}</p>
-        )}
-
-        {doctorReport && doctorState === 'done' && (
-          <div className="mt-3 p-3 rounded-[12px] border border-white/[0.08] bg-surface">
-            <div className={`text-[12px] font-600 ${doctorReport.ok ? 'text-emerald-300' : 'text-amber-300'}`}>
-              {doctorReport.summary}
-            </div>
-            {doctorReport.checks.filter((check) => check.status !== 'pass').slice(0, 3).map((check) => (
-              <div key={check.id} className="mt-1 text-[11px] text-text-3">
-                - {check.label}: {check.detail}
+      <div className="max-h-[46vh] overflow-y-auto pr-1 text-left">
+        <div className="flex flex-col gap-5">
+          {providerGroups.map((group) => (
+            <section key={group.id}>
+              <div className="mb-2 px-1">
+                <div className="text-[12px] font-display font-700 text-text">{group.title}</div>
+                <p className="mt-0.5 text-[11px] leading-relaxed text-text-3/65">{group.description}</p>
               </div>
-            ))}
-            {!!doctorReport.actions?.length && (
-              <div className="mt-2 text-[11px] text-text-3/80">
-                Next: {doctorReport.actions.slice(0, 2).join(' ')}
+              <div className="flex flex-col gap-3">
+                {group.providers.map((candidate) => {
+                  const isConfigured = configuredProviderIds.has(candidate.id)
+                  return (
+                    <button
+                      key={candidate.id}
+                      onClick={() => onSelectProvider(candidate.id)}
+                      className={`w-full px-5 py-4 rounded-[14px] border bg-surface text-left
+                        transition-all duration-200 flex items-start gap-4 cursor-pointer
+                        ${isConfigured
+                          ? 'border-emerald-500/25 hover:border-emerald-500/40 hover:bg-surface-hover'
+                          : 'border-white/[0.08] hover:border-accent-bright/30 hover:bg-surface-hover'
+                        }`}
+                    >
+                      <div className={`w-10 h-10 rounded-[10px] border flex items-center justify-center shrink-0 mt-0.5 ${
+                        isConfigured ? 'bg-emerald-500/10 border-emerald-500/20' : 'bg-white/[0.04] border-white/[0.06]'
+                      }`}>
+                        <span className={`text-[16px] font-display font-700 ${isConfigured ? 'text-emerald-400' : 'text-accent-bright'}`}>
+                          {candidate.icon}
+                        </span>
+                      </div>
+                      <div className="flex-1">
+                        <div className="text-[15px] font-display font-600 text-text mb-1">
+                          {candidate.name}
+                          {isConfigured ? (
+                            <span className="ml-2 inline-flex items-center gap-1 px-2 py-0.5 rounded-md bg-emerald-500/10 text-emerald-300 text-[10px] uppercase tracking-[0.08em] font-600">
+                              Connected · Edit
+                            </span>
+                          ) : candidate.badge ? (
+                            <span className="ml-2 inline-flex items-center gap-1 px-2 py-0.5 rounded-md bg-accent-bright/15 text-accent-bright text-[10px] uppercase tracking-[0.08em] font-600">
+                              {candidate.badge}
+                            </span>
+                          ) : null}
+                        </div>
+                        <div className="text-[13px] text-text-3 leading-relaxed">{candidate.description}</div>
+                        {!candidate.requiresKey && !isConfigured && (
+                          <div className="mt-1.5 inline-flex items-center gap-1.5 px-2 py-0.5 rounded-md bg-emerald-500/10 text-emerald-400 text-[11px] font-500">
+                            <span className="w-1.5 h-1.5 rounded-full bg-emerald-400" />
+                            No API key required
+                          </div>
+                        )}
+                      </div>
+                    </button>
+                  )
+                })}
               </div>
-            )}
-          </div>
-        )}
+            </section>
+          ))}
+        </div>
       </div>
 
       {error && <p className="mt-4 text-[13px] text-red-400">{error}</p>}

package/src/components/auth/setup-wizard/types.ts

@@ -1,5 +1,6 @@
 import type { GatewayProfile, ProviderId } from '@/types'
 import type { SetupProvider } from '@/lib/setup-defaults'
+import type { LaunchPathAction, LaunchPathId } from '@/lib/home-launchpad'
 
 export type SetupStep = 'profile' | 'path' | 'providers' | 'connect' | 'agents' | 'next' | 'done'
 export type CheckState = 'idle' | 'checking' | 'ok' | 'error'
@@ -162,11 +163,7 @@ export interface StepAgentsProps {
 export interface StepNextProps {
   createdAgents: CreatedAgentSummary[]
   onContinueToDashboard: () => void
-  onOpenFirstAgent: () => void
-  onOpenProtocols: () => void
-  onOpenBuilder: () => void
-  onOpenConnectors: () => void
-  onOpenUsage: () => void
+  onLaunchPathAction: (id: LaunchPathId, action: LaunchPathAction) => void
 }
 
 export interface StepDoneProps {

package/src/components/auth/setup-wizard/utils.test.ts

@@ -8,6 +8,7 @@ import {
   isLocalOpenClawEndpoint,
   resolveOpenClawDashboardUrl,
   getOpenClawErrorHint,
+  getSetupProviderGroups,
   requiresSetupProviderVerification,
   withHttpScheme,
   buildStarterDrafts,
@@ -76,6 +77,24 @@ test('getStarterKitsForPath: manual keeps the full catalog', () => {
   assert.equal(ids.has('openclaw_fleet'), true)
 })
 
+test('getSetupProviderGroups puts fast local and no-key providers first', () => {
+  const groups = getSetupProviderGroups()
+  assert.deepEqual(groups.map((group) => group.id), ['fast-local', 'recommended-api', 'advanced-catalog'])
+  assert.equal(groups[0]?.providers[0]?.id, 'claude-cli')
+  assert.equal(groups[0]?.providers.some((provider) => provider.id === 'openclaw'), true)
+  assert.equal(groups[0]?.providers.some((provider) => provider.id === 'ollama'), true)
+})
+
+test('getSetupProviderGroups separates recommended APIs from advanced catalogs', () => {
+  const groups = getSetupProviderGroups()
+  const recommendedIds = new Set(groups.find((group) => group.id === 'recommended-api')?.providers.map((provider) => provider.id))
+  const advancedIds = new Set(groups.find((group) => group.id === 'advanced-catalog')?.providers.map((provider) => provider.id))
+  assert.equal(recommendedIds.has('openai'), true)
+  assert.equal(recommendedIds.has('openrouter'), true)
+  assert.equal(advancedIds.has('custom'), true)
+  assert.equal(advancedIds.has('deepseek'), true)
+})
+
 // ---------------------------------------------------------------------------
 // formatEndpointHost
 // ---------------------------------------------------------------------------

package/src/components/auth/setup-wizard/utils.ts

@@ -1,14 +1,47 @@
 import {
+  SETUP_PROVIDERS,
   STARTER_KITS,
   getDefaultModelForProvider,
   type OnboardingPath,
   type StarterKit,
+  type SetupProviderOption,
   type SetupProvider,
   type StarterKitAgentTemplate,
 } from '@/lib/setup-defaults'
 import type { ConfiguredProvider, SetupStep, StarterDraftAgent } from './types'
 import { STEP_ORDER } from './types'
 
+export type SetupProviderGroupId = 'fast-local' | 'recommended-api' | 'advanced-catalog'
+
+export interface SetupProviderGroup {
+  id: SetupProviderGroupId
+  title: string
+  description: string
+  providers: SetupProviderOption[]
+}
+
+const FAST_LOCAL_PROVIDER_IDS = new Set<SetupProvider>([
+  'claude-cli',
+  'codex-cli',
+  'opencode-cli',
+  'gemini-cli',
+  'copilot-cli',
+  'droid-cli',
+  'cursor-cli',
+  'qwen-code-cli',
+  'goose',
+  'ollama',
+  'openclaw',
+  'hermes',
+])
+
+const RECOMMENDED_API_PROVIDER_IDS = new Set<SetupProvider>([
+  'openai',
+  'openrouter',
+  'anthropic',
+  'google',
+])
+
 export function stepIndex(step: SetupStep): number {
   if (step === 'connect') return STEP_ORDER.indexOf('providers')
   return STEP_ORDER.indexOf(step)
@@ -38,6 +71,42 @@ export function getStarterKitsForPath(path: OnboardingPath): StarterKit[] {
   return STARTER_KITS
 }
 
+export function getSetupProviderGroups(providers: SetupProviderOption[] = SETUP_PROVIDERS): SetupProviderGroup[] {
+  const groups: SetupProviderGroup[] = [
+    {
+      id: 'fast-local',
+      title: 'Fast local and no-key starts',
+      description: 'Use an installed CLI, a local runtime, or an existing OpenClaw/Hermes gateway.',
+      providers: [],
+    },
+    {
+      id: 'recommended-api',
+      title: 'Recommended API providers',
+      description: 'Good first choices for cloud-backed chats, agents, and workflow runs.',
+      providers: [],
+    },
+    {
+      id: 'advanced-catalog',
+      title: 'Advanced catalog and custom endpoints',
+      description: 'Specialized model catalogs, OpenAI-compatible servers, and provider-specific setups.',
+      providers: [],
+    },
+  ]
+  const byId = new Map(groups.map((group) => [group.id, group]))
+
+  for (const provider of providers) {
+    if (FAST_LOCAL_PROVIDER_IDS.has(provider.id)) {
+      byId.get('fast-local')!.providers.push(provider)
+    } else if (RECOMMENDED_API_PROVIDER_IDS.has(provider.id)) {
+      byId.get('recommended-api')!.providers.push(provider)
+    } else {
+      byId.get('advanced-catalog')!.providers.push(provider)
+    }
+  }
+
+  return groups.filter((group) => group.providers.length > 0)
+}
+
 export function applyIntentContext(prompt: string, intentText: string): string {
   const trimmed = intentText.trim()
   if (!trimmed) return prompt