feat(046): wizard v2 — 3 tabs, sidebar Setup, sectioned import w/ rename, activity panel

Related #46

Reframes the first-run wizard as a persistent, idempotent setup surface
driven by the activation funnel telemetry (SynapBus #27345, 78.2% → 11.7%
cliff at IDE connect). Replaces the linear v1 flow with three idempotent
tabs (Clients · Servers · Verify), a top-pinned sidebar entry with an
animated badge, and a passive Verify tab that flips green automatically
on the first successful MCP `initialize` round-trip — closing the loop
on the cliff in-product.

## Changes

Spec
- specs/046-local-first-onboarding/spec.md: appended a "v2 — Wizard
  Surface Redesign" section. v1 text preserved verbatim.

Backend (Go)
- internal/httpapi/onboarding.go: extended /api/v1/onboarding/state with
  first_mcp_client_ever, mcp_clients_seen_ever, incomplete_tab_count.
  ShouldShowWizard semantics widened to cover Verify.
- internal/httpapi/server.go + internal/server/server.go +
  internal/runtime/runtime.go: new GetActivationFirstMCPClient() reads
  Spec 044's existing FirstMCPClientEver / MCPClientsSeenEver from the
  ActivationStore. No new BBolt buckets, no new MCP hook.
- internal/httpapi/import.go: ImportFromPathRequest gains skip_quarantine
  query param ("Import as active") and a rename map applied after
  parsing — so the wizard can disambiguate cross-source name collisions
  like "mcpproxy" appearing in both Claude Code and Claude Desktop.

Frontend (Vue 3 + Pinia)
- frontend/src/components/OnboardingWizard.vue: full rewrite as a 3-tab
  modal at min(960px, 90vw) × min(640px, 85vh). Tabs are bidirectionally
  clickable; per-tab idempotent state.
  - Clients tab: detected sort -> always-pinned trio (Claude Code /
    Codex / Gemini) -> "Show N more" collapse. Inline security
    expander.
  - Servers tab: sectioned checkbox list with indented server rows
    under each section header; per-section "select all" with proper
    indeterminate state; cross-source name collisions render an inline
    rename pill ("→ <renamed>"); sticky non-scrollable footer with
    selection count, conflict count, and two equal-width action buttons
    (Import & quarantine, Import as active). Compact toggles for
    Docker isolation and quarantine_enabled with inline Docker-
    availability warning. Educational note about post-hoc scanning.
  - Verify tab: passive, flips green on FirstMCPClientEver. Three
    sample prompts annotated with the built-in tool each one exercises.
    Recent Activity panel below shows the last 5 records with status
    badges and "View all in Activity Log" link.
- frontend/src/components/SidebarNav.vue: top-pinned "Setup" entry
  above Dashboard for personal edition.
- frontend/src/views/Dashboard.vue: removed the v1 "Run setup wizard"
  button.
- frontend/src/stores/onboarding.ts + types/api.ts + services/api.ts:
  store gains firstMCPClientEver, mcpClientsSeenEver, incompleteTabCount
  computeds. importServersFromPath supports skip_quarantine + rename.

OpenAPI
- oas/swagger.yaml + oas/docs.go: ImportFromPathRequest gains rename.

Verification
- specs/046-local-first-onboarding/verification/: 7 Playwright-captured
  PNGs and a self-contained report.html (1.4 MB, base64-embedded
  screenshots).

## Testing

- internal/httpapi unit + contract tests pass; mocks updated.
- frontend vue-tsc clean.
- Playwright sweep on a fresh data dir: all scenarios pass; out-of-band
  curl confirms rename produces mcpproxy_claude_code /
  mcpproxy_claude_desktop with quarantined=true.

Author: claude

frontend/src/components/OnboardingWizard.vue

@@ -131,6 +131,52 @@
 
         <!-- Personal Edition: Grouped Menu -->
         <template v-else>
+          <!-- Spec 046 v2: top-pinned Setup entry (above Dashboard).
+               Shows badge with count of incomplete tabs while > 0; collapses
+               to a quiet checkmark when all three tabs (clients/servers/verify)
+               are satisfied. Click reopens the wizard at the first
+               incomplete tab. -->
+          <ul class="menu menu-sm gap-0.5 p-0 mb-1">
+            <li>
+              <a
+                href="#"
+                class="rounded-lg font-medium relative group"
+                :class="setupIncomplete
+                  ? 'bg-gradient-to-r from-primary/10 to-secondary/10 hover:from-primary/15 hover:to-secondary/15'
+                  : 'text-base-content/60'"
+                :title="collapsed ? setupTitleAttr : ''"
+                data-test="sidebar-setup"
+                @click.prevent="onClickSetup"
+              >
+                <span class="relative inline-flex items-center justify-center">
+                  <IconSparkles
+                    class="w-5 h-5 shrink-0"
+                    :class="setupIncomplete ? 'text-primary' : 'text-base-content/40'"
+                  />
+                  <!-- Pulse halo when incomplete -->
+                  <span
+                    v-if="setupIncomplete"
+                    class="absolute inline-flex h-5 w-5 rounded-full bg-primary opacity-30 animate-ping"
+                    aria-hidden="true"
+                  ></span>
+                </span>
+                <span v-show="!collapsed" class="flex-1">
+                  <span v-if="setupIncomplete">Setup</span>
+                  <span v-else class="inline-flex items-center gap-1">
+                    <span>Setup</span>
+                    <span class="text-success text-xs">✓</span>
+                  </span>
+                </span>
+                <span
+                  v-if="setupIncomplete && setupCount > 0"
+                  class="badge badge-primary badge-sm"
+                  :class="collapsed ? 'absolute -top-1 -right-1 badge-xs' : ''"
+                  data-test="sidebar-setup-badge"
+                >{{ setupCount }}</span>
+              </a>
+            </li>
+          </ul>
+
           <!-- Dashboard (solo top row, no section label) -->
           <ul class="menu menu-sm gap-0.5 p-0">
             <li>
@@ -342,15 +388,45 @@
 </template>
 
 <script setup lang="ts">
-import { computed, h, type FunctionalComponent } from 'vue'
+import { computed, h, onMounted, type FunctionalComponent } from 'vue'
 import { useRoute, useRouter } from 'vue-router'
 import { useSystemStore } from '@/stores/system'
 import { useAuthStore } from '@/stores/auth'
+import { useOnboardingStore } from '@/stores/onboarding'
 
 const route = useRoute()
 const router = useRouter()
 const systemStore = useSystemStore()
 const authStore = useAuthStore()
+const onboardingStore = useOnboardingStore()
+
+// Spec 046 v2: badge count drives the sidebar Setup entry's pulse + count.
+// Refetched on mount; the wizard itself drives subsequent updates while open.
+const setupCount = computed(() => onboardingStore.incompleteTabCount)
+const setupIncomplete = computed(() => setupCount.value > 0)
+const setupTitleAttr = computed(() =>
+  setupIncomplete.value
+    ? `Setup (${setupCount.value} step${setupCount.value === 1 ? '' : 's'} remaining)`
+    : 'Setup ✓'
+)
+
+function onClickSetup() {
+  // Open the wizard via the store. If the user is on a deep route, they stay
+  // there — the wizard is a modal and renders above whatever view is mounted.
+  if (route.path !== '/') {
+    router.push('/').then(() => onboardingStore.openWizard())
+  } else {
+    onboardingStore.openWizard()
+  }
+}
+
+onMounted(() => {
+  // Pull initial state so the badge is correct on first render. Personal-
+  // edition only — the surrounding template gates this for personal users.
+  if (!authStore.isTeamsEdition) {
+    void onboardingStore.fetchState()
+  }
+})
 
 const collapsed = computed(() => systemStore.sidebarCollapsed)
 
@@ -437,6 +513,10 @@ const IconRepo = makeIcon(
 const IconSettings = makeIcon(
   'M10.3 3.6a1.5 1.5 0 013.4 0l.2 1.1a7 7 0 011.9.8l1-.6a1.5 1.5 0 012.1 2.1l-.6 1a7 7 0 01.8 1.9l1.1.2a1.5 1.5 0 010 3.4l-1.1.2a7 7 0 01-.8 1.9l.6 1a1.5 1.5 0 01-2.1 2.1l-1-.6a7 7 0 01-1.9.8l-.2 1.1a1.5 1.5 0 01-3.4 0l-.2-1.1a7 7 0 01-1.9-.8l-1 .6a1.5 1.5 0 01-2.1-2.1l.6-1a7 7 0 01-.8-1.9l-1.1-.2a1.5 1.5 0 010-3.4l1.1-.2a7 7 0 01.8-1.9l-.6-1a1.5 1.5 0 012.1-2.1l1 .6a7 7 0 011.9-.8l.2-1.1zM12 9a3 3 0 100 6 3 3 0 000-6z'
 )
+// Spec 046 v2: sparkles icon for the top-pinned Setup entry.
+const IconSparkles = makeIcon(
+  'M12 3l1.6 4.6L18 9l-4.4 1.4L12 15l-1.6-4.6L6 9l4.4-1.4L12 3zm6 11l.8 2.4L21 17l-2.2.6L18 20l-.8-2.4L15 17l2.2-.6L18 14zM6 14l.8 2.4L9 17l-2.2.6L6 20l-.8-2.4L3 17l2.2-.6L6 14z'
+)
 
 // Server edition menus (unchanged behavior)
 const teamsUserMenu = [

frontend/src/components/SidebarNav.vue

@@ -702,20 +702,29 @@ class APIService {
     return this.request<CanonicalConfigPathsResponse>('/api/v1/servers/import/paths')
   }
 
-  // Import servers from a file path on the server's filesystem
+  // Import servers from a file path on the server's filesystem.
+  // Spec 046 v2: skip_quarantine=true imports as already-trusted (skips
+  // the quarantine holding state). Default false preserves the safe-by-
+  // default posture for any caller that doesn't pass the flag.
   async importServersFromPath(params: {
     path: string
     format?: string
     server_names?: string[]
     preview?: boolean
+    skip_quarantine?: boolean
+    rename?: Record<string, string>
   }): Promise<APIResponse<ImportResponse>> {
-    const url = `/api/v1/servers/import/path${params.preview ? '?preview=true' : ''}`
+    const qs: string[] = []
+    if (params.preview) qs.push('preview=true')
+    if (params.skip_quarantine) qs.push('skip_quarantine=true')
+    const url = `/api/v1/servers/import/path${qs.length ? '?' + qs.join('&') : ''}`
     return this.request<ImportResponse>(url, {
       method: 'POST',
       body: JSON.stringify({
         path: params.path,
         format: params.format,
-        server_names: params.server_names
+        server_names: params.server_names,
+        rename: params.rename,
       })
     })
   }

frontend/src/services/api.ts

@@ -35,8 +35,13 @@ export const useOnboardingStore = defineStore('onboarding', () => {
   const hasConfiguredServer = computed(() => state.value?.has_configured_server ?? false)
   const isEngaged = computed(() => state.value?.state.engaged ?? false)
 
-  // The list of step IDs the wizard should render, in order. Derived
-  // from the live predicates so the wizard adapts to state on each open.
+  // Spec 046 v2 — passive Verify tab + sidebar badge sources.
+  const firstMCPClientEver = computed(() => state.value?.first_mcp_client_ever ?? false)
+  const mcpClientsSeenEver = computed<string[]>(() => state.value?.mcp_clients_seen_ever ?? [])
+  const incompleteTabCount = computed(() => state.value?.incomplete_tab_count ?? 0)
+
+  // v1 visibleSteps kept for back-compat with any remaining caller. The v2
+  // wizard renders a fixed three-tab surface and ignores this value.
   const visibleSteps = computed<Array<'connect' | 'server'>>(() => {
     const steps: Array<'connect' | 'server'> = []
     if (!hasConnectedClient.value) steps.push('connect')
@@ -153,6 +158,9 @@ export const useOnboardingStore = defineStore('onboarding', () => {
     hasConnectedClient,
     hasConfiguredServer,
     isEngaged,
+    firstMCPClientEver,
+    mcpClientsSeenEver,
+    incompleteTabCount,
     visibleSteps,
     fetchState,
     mark,

frontend/src/stores/onboarding.ts

@@ -692,6 +692,10 @@ export interface OnboardingStateResponse {
   configured_server_count: number
   state: OnboardingState
   should_show_wizard: boolean
+  // Spec 046 v2 — passive Verify tab + sidebar badge
+  first_mcp_client_ever: boolean
+  mcp_clients_seen_ever: string[]
+  incomplete_tab_count: number
 }
 
 export interface OnboardingMarkRequest {

frontend/src/types/api.ts

@@ -121,9 +121,6 @@
           <button @click="showConnectModal = true" class="btn btn-primary btn-sm w-full gap-1">
             Connect Clients
           </button>
-          <button @click="onboardingStore.openWizard()" class="btn btn-ghost btn-xs w-full gap-1" data-test="run-setup-wizard">
-            Run setup wizard
-          </button>
           <button @click="showAddServer = true" class="btn btn-secondary btn-outline btn-sm w-full gap-1">
             <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
               <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 16v1a3 3 0 003 3h10a3 3 0 003-3v-1m-4-8l-4-4m0 0L8 8m4-4v12" />

frontend/src/views/Dashboard.vue

@@ -345,6 +345,7 @@ func (m *MockServerController) GetOnboardingState() (*storage.OnboardingState, e
 	return &storage.OnboardingState{}, nil
 }
 func (m *MockServerController) SaveOnboardingState(_ *storage.OnboardingState) error { return nil }
+func (m *MockServerController) GetActivationFirstMCPClient() (bool, []string)        { return false, nil }
 
 // Test contract compliance for API responses
 func TestAPIContractCompliance(t *testing.T) {

internal/httpapi/contracts_test.go

@@ -16,20 +16,20 @@ import (
 
 // ImportRequest represents a request to import servers from JSON/TOML content
 type ImportRequest struct {
-	Content     string   `json:"content"`               // Raw JSON or TOML content
-	Format      string   `json:"format,omitempty"`      // Optional format hint
+	Content     string   `json:"content"`                // Raw JSON or TOML content
+	Format      string   `json:"format,omitempty"`       // Optional format hint
 	ServerNames []string `json:"server_names,omitempty"` // Optional: import only these servers
 }
 
 // ImportResponse represents the response from an import operation
 type ImportResponse struct {
-	Format      string                       `json:"format"`
-	FormatName  string                       `json:"format_name"`
-	Summary     configimport.ImportSummary   `json:"summary"`
-	Imported    []ImportedServerResponse     `json:"imported"`
-	Skipped     []configimport.SkippedServer `json:"skipped"`
-	Failed      []configimport.FailedServer  `json:"failed"`
-	Warnings    []string                     `json:"warnings"`
+	Format     string                       `json:"format"`
+	FormatName string                       `json:"format_name"`
+	Summary    configimport.ImportSummary   `json:"summary"`
+	Imported   []ImportedServerResponse     `json:"imported"`
+	Skipped    []configimport.SkippedServer `json:"skipped"`
+	Failed     []configimport.FailedServer  `json:"failed"`
+	Warnings   []string                     `json:"warnings"`
 }
 
 // ImportedServerResponse represents an imported server in the response
@@ -47,12 +47,12 @@ type ImportedServerResponse struct {
 
 // CanonicalConfigPath represents a well-known config file path
 type CanonicalConfigPath struct {
-	Name        string `json:"name"`         // Display name (e.g., "Claude Desktop")
-	Format      string `json:"format"`       // Format identifier (e.g., "claude_desktop")
-	Path        string `json:"path"`         // Full path to the config file
-	Exists      bool   `json:"exists"`       // Whether the file exists
-	OS          string `json:"os"`           // Operating system (darwin, windows, linux)
-	Description string `json:"description"`  // Brief description
+	Name        string `json:"name"`        // Display name (e.g., "Claude Desktop")
+	Format      string `json:"format"`      // Format identifier (e.g., "claude_desktop")
+	Path        string `json:"path"`        // Full path to the config file
+	Exists      bool   `json:"exists"`      // Whether the file exists
+	OS          string `json:"os"`          // Operating system (darwin, windows, linux)
+	Description string `json:"description"` // Brief description
 }
 
 // CanonicalConfigPathsResponse represents the response for canonical config paths
@@ -164,6 +164,11 @@ type ImportFromPathRequest struct {
 	Path        string   `json:"path"`                   // File path to import from
 	Format      string   `json:"format,omitempty"`       // Optional format hint
 	ServerNames []string `json:"server_names,omitempty"` // Optional: import only these servers
+	// Rename maps OriginalName → new name. Applied after parsing so the
+	// caller can disambiguate cross-source name collisions (Spec 046 v2 —
+	// e.g. "mcpproxy" → "mcpproxy_claude_code"). Keys not present in the
+	// imported set are ignored.
+	Rename map[string]string `json:"rename,omitempty"`
 }
 
 // handleImportFromPath godoc
@@ -220,7 +225,7 @@ func (s *Server) handleImportFromPath(w http.ResponseWriter, r *http.Request) {
 	preview := r.URL.Query().Get("preview") == "true"
 
 	// Use the common runImport function
-	result, err := s.runImport(r, content, req.Format, req.ServerNames, preview)
+	result, err := s.runImport(r, content, req.Format, req.ServerNames, preview, req.Rename)
 	if err != nil {
 		logger.Error("Import from path failed", "path", path, "error", err)
 		s.writeError(w, r, http.StatusBadRequest, err.Error())
@@ -283,8 +288,8 @@ func (s *Server) handleImportServers(w http.ResponseWriter, r *http.Request) {
 		}
 	}
 
-	// Run import
-	result, err := s.runImport(r, content, formatHint, serverNames, preview)
+	// Run import (rename not supported via multipart upload — leave nil)
+	result, err := s.runImport(r, content, formatHint, serverNames, preview, nil)
 	if err != nil {
 		logger.Error("Import failed", "error", err)
 		s.writeError(w, r, http.StatusBadRequest, err.Error())
@@ -326,7 +331,7 @@ func (s *Server) handleImportServersJSON(w http.ResponseWriter, r *http.Request)
 	preview := r.URL.Query().Get("preview") == "true"
 
 	// Run import
-	result, err := s.runImport(r, []byte(req.Content), req.Format, req.ServerNames, preview)
+	result, err := s.runImport(r, []byte(req.Content), req.Format, req.ServerNames, preview, nil)
 	if err != nil {
 		logger.Error("Import failed", "error", err)
 		s.writeError(w, r, http.StatusBadRequest, err.Error())
@@ -336,14 +341,23 @@ func (s *Server) handleImportServersJSON(w http.ResponseWriter, r *http.Request)
 	s.writeSuccess(w, result)
 }
 
-// runImport executes the import logic and optionally applies the servers
-func (s *Server) runImport(r *http.Request, content []byte, formatHint string, serverNames []string, preview bool) (*ImportResponse, error) {
+// runImport executes the import logic and optionally applies the servers.
+// rename is an optional map of OriginalName → new name applied after parsing,
+// before adding the servers — used by the wizard to disambiguate cross-source
+// name collisions. May be nil.
+func (s *Server) runImport(r *http.Request, content []byte, formatHint string, serverNames []string, preview bool, rename map[string]string) (*ImportResponse, error) {
 	logger := s.getRequestLogger(r)
 
+	// Spec 046 v2: opt-in trust path. Default behaviour is unchanged
+	// (servers enter quarantine). The wizard's "Import active" path passes
+	// `skip_quarantine=true` to import them as already-trusted.
+	skipQuarantine := r.URL.Query().Get("skip_quarantine") == "true"
+
 	// Build import options
 	opts := &configimport.ImportOptions{
-		Preview: preview,
-		Now:     time.Now(),
+		Preview:        preview,
+		SkipQuarantine: skipQuarantine,
+		Now:            time.Now(),
 	}
 
 	// Parse format hint
@@ -378,6 +392,18 @@ func (s *Server) runImport(r *http.Request, content []byte, formatHint string, s
 		return nil, err
 	}
 
+	// Spec 046 v2: apply caller-supplied renames before persisting. Keyed
+	// by OriginalName so the caller doesn't need to know the parser's name-
+	// sanitization rules. Server.Name is rewritten in place; OriginalName is
+	// preserved on the response so the caller can reconcile the mapping.
+	if len(rename) > 0 {
+		for i := range result.Imported {
+			if newName, ok := rename[result.Imported[i].OriginalName]; ok && newName != "" {
+				result.Imported[i].Server.Name = newName
+			}
+		}
+	}
+
 	// Build response
 	response := &ImportResponse{
 		Format:     string(result.Format),

internal/httpapi/import.go

@@ -41,9 +41,30 @@ type OnboardingStateResponse struct {
 	State storage.OnboardingState `json:"state"`
 
 	// ShouldShowWizard is the derived flag the frontend uses to decide
-	// whether to auto-show. True when not engaged and at least one
-	// predicate is false.
+	// whether to auto-show. True when not engaged and IncompleteTabCount > 0
+	// (Spec 046 v2 — semantics widened to also count the Verify tab).
 	ShouldShowWizard bool `json:"should_show_wizard"`
+
+	// --- Spec 046 v2 additions ---
+
+	// FirstMCPClientEver is true once any MCP client has successfully completed
+	// an `initialize` round-trip with this mcpproxy. Sourced from the Spec 044
+	// activation bucket. Drives the Verify tab's "green check" state.
+	FirstMCPClientEver bool `json:"first_mcp_client_ever"`
+
+	// MCPClientsSeenEver is the capped list of recognized client names that
+	// have ever called this mcpproxy. Names come from the MCP `initialize`
+	// payload's `clientInfo.name` field, sanitized. Surfaces on the Verify tab
+	// so the user can see whether their real IDE — not a test client — has
+	// connected.
+	MCPClientsSeenEver []string `json:"mcp_clients_seen_ever"`
+
+	// IncompleteTabCount is the number of wizard tabs whose state is incomplete.
+	// Drives the sidebar Setup entry's badge. Formula:
+	//   +1 if HasConnectedClient == false
+	//   +1 if HasConfiguredServer == false
+	//   +1 if FirstMCPClientEver == false
+	IncompleteTabCount int `json:"incomplete_tab_count"`
 }
 
 // OnboardingMarkRequest is the request body for /api/v1/onboarding/mark
@@ -182,7 +203,24 @@ func (s *Server) computeOnboardingState() (*OnboardingStateResponse, error) {
 	}
 	resp.State = *state
 
-	resp.ShouldShowWizard = !state.Engaged && (!resp.HasConnectedClient || !resp.HasConfiguredServer)
+	// Spec 046 v2: pull activation state for the Verify tab.
+	resp.FirstMCPClientEver, resp.MCPClientsSeenEver = s.controller.GetActivationFirstMCPClient()
+	if resp.MCPClientsSeenEver == nil {
+		resp.MCPClientsSeenEver = []string{}
+	}
+
+	// Badge formula: +1 per incomplete tab.
+	if !resp.HasConnectedClient {
+		resp.IncompleteTabCount++
+	}
+	if !resp.HasConfiguredServer {
+		resp.IncompleteTabCount++
+	}
+	if !resp.FirstMCPClientEver {
+		resp.IncompleteTabCount++
+	}
+
+	resp.ShouldShowWizard = !state.Engaged && resp.IncompleteTabCount > 0
 
 	return resp, nil
 }

internal/httpapi/onboarding.go

@@ -342,3 +342,4 @@ func (m *baseController) GetOnboardingState() (*storage.OnboardingState, error)
 	return &storage.OnboardingState{}, nil
 }
 func (m *baseController) SaveOnboardingState(_ *storage.OnboardingState) error { return nil }
+func (m *baseController) GetActivationFirstMCPClient() (bool, []string)        { return false, nil }