a2acalling 0.6.75 → 0.6.76

package/docs/plans/2026-03-06-a2a-99-native-onboarding-wizard.md

@@ -0,0 +1,1261 @@
+# A2A-99: Native Onboarding Wizard Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Replace the "run `a2a quickstart` in terminal" fallback with an in-app multi-step onboarding wizard so standalone app users can set up their agent without a terminal.
+
+**Architecture:** A separate HTML page served at `/api/a2a/dashboard/onboarding` with vanilla JS + Shoelace components. The wizard has 4 steps (Welcome, Disclosure, Permissions, Network). On completion, it POSTs to `/api/a2a/dashboard/onboarding/complete` which writes config + disclosure manifest using existing `A2AConfig` and `disclosure.js` APIs. The Rust `discovery.rs` gains an `onboarding_complete` field so `native/macos/index.html` can route to the wizard vs dashboard.
+
+**Tech Stack:** Vanilla JS, Shoelace web components, Express routes (CommonJS), Rust/Tauri (discovery.rs only), zero new dependencies.
+
+---
+
+## Key Conventions
+
+- **Logging:** Use `createLogger({ component: 'a2a.dashboard' })` — no bare `console.log` in src/
+- **Config:** Use `A2AConfig` from `src/lib/config.js` — never hardcode paths
+- **Disclosure:** Use `validateDisclosureSubmission()`, `saveManifest()`, `generateDefaultManifest()` from `src/lib/disclosure.js`
+- **Testing:** Zero-dependency runner at `test/run.js`, pattern from `test/integration/dashboard-crud.test.js`
+- **Module style:** CommonJS (`require`/`module.exports`)
+- **Dashboard auth:** Onboarding routes placed BEFORE `ensureDashboardAccess` middleware (like `/callbook/exchange`)
+- **Naming:** kebab-case files, camelCase functions, PascalCase classes
+
+## Reuse Map
+
+| What | Where | How |
+|------|-------|-----|
+| Config read/write | `src/lib/config.js` — `A2AConfig`, `isOnboarded()`, `completeOnboarding()`, `setOnboarding()`, `setAgent()` | Import and call directly in API endpoint |
+| Disclosure validation | `src/lib/disclosure.js` — `validateDisclosureSubmission()`, `saveManifest()`, `generateDefaultManifest()` | Import and call in API endpoint |
+| Port detection | `src/lib/port-scanner.js` — `findAvailablePort()`, `isPortListening()` | Import in API endpoint for network step |
+| Dashboard test pattern | `test/integration/dashboard-crud.test.js` — `setup()`, `teardown()`, `helpers.request()` | Follow same pattern for onboarding tests |
+| Design tokens | `src/dashboard/public/style.css` — CSS custom properties (`--bg`, `--panel`, `--ink`, `--accent`, etc.) | Reference in onboarding.css |
+| Shoelace + fonts | CDN links in `src/dashboard/public/index.html` lines 8-13 | Copy same CDN links to onboarding.html |
+| Discovery config read | `native/macos/src-tauri/src/discovery.rs` — `A2AConfig` struct, `read_config_ports()` | Extend struct to include `onboarding_complete` |
+
+---
+
+## Task 1: Onboarding API Endpoints in dashboard.js
+
+**Files:**
+- Modify: `src/routes/dashboard.js` — add 3 routes before `ensureDashboardAccess` middleware
+
+**Step 1: Add onboarding routes to `createDashboardApiRouter`**
+
+In `src/routes/dashboard.js`, add the following routes AFTER the `/callbook/exchange` route (line ~505) but BEFORE `router.use(ensureDashboardAccess)` (line ~506). These routes must be accessible without auth since the user hasn't set up yet.
+
+```js
+  // A2A-99: Onboarding wizard — served before auth middleware so fresh installs can access it.
+  router.get('/onboarding', (req, res) => {
+    const onboardingPath = path.join(context.staticDir, 'onboarding.html');
+    if (!fs.existsSync(onboardingPath)) {
+      return res.status(500).send('Onboarding wizard UI missing');
+    }
+    return res.sendFile(onboardingPath);
+  });
+
+  // A2A-99: Onboarding status check — lets the wizard and native app check if onboarding is complete.
+  router.get('/onboarding/status', (req, res) => {
+    return res.json({
+      success: true,
+      onboarded: context.config.isOnboarded(),
+      onboarding: context.config.getOnboarding()
+    });
+  });
+
+  // A2A-99: Complete onboarding — writes config + disclosure manifest.
+  router.post('/onboarding/complete', async (req, res) => {
+    const body = req.body || {};
+
+    // Validate required fields
+    const agentName = sanitizeString(body.agentName || '', 120);
+    const defaultTier = sanitizeString(body.defaultTier || 'public', 20);
+    const port = Number.parseInt(String(body.port || ''), 10);
+    const hostname = sanitizeString(body.hostname || '', 200);
+
+    if (!agentName) {
+      return res.status(400).json({
+        success: false,
+        error: { code: 'missing_agent_name', message: 'Agent name is required.' }
+      });
+    }
+
+    if (!['public', 'friends', 'family'].includes(defaultTier)) {
+      return res.status(400).json({
+        success: false,
+        error: { code: 'invalid_tier', message: 'Default tier must be public, friends, or family.' }
+      });
+    }
+
+    if (!Number.isFinite(port) || port < 1 || port > 65535) {
+      return res.status(400).json({
+        success: false,
+        error: { code: 'invalid_port', message: 'Port must be between 1 and 65535.' }
+      });
+    }
+
+    // Build and validate disclosure manifest from selected topics
+    const disc = require('../lib/disclosure');
+    const topics = Array.isArray(body.topics) ? body.topics.map(t => sanitizeString(String(t), 100)).filter(Boolean) : [];
+    const manifest = disc.generateDefaultManifest();
+
+    // A2A-99: Map user-selected topics into the public tier (simplest useful default).
+    // Users can refine per-tier topics later in the Settings tab.
+    if (topics.length > 0) {
+      manifest.tiers.public.topics = topics.slice(0, 15); // LIST_LIMITS.topics = 15
+    }
+
+    const validation = disc.validateDisclosureSubmission(manifest);
+    if (!validation.valid) {
+      return res.status(400).json({
+        success: false,
+        error: { code: 'invalid_disclosure', message: validation.errors.join('; ') }
+      });
+    }
+
+    try {
+      // Write disclosure manifest
+      disc.saveManifest(manifest);
+
+      // Write config
+      const effectiveHostname = hostname || `localhost:${port}`;
+      context.config.setAgent({ name: agentName, hostname: effectiveHostname });
+      context.config.setDefaults({ defaultTier });
+      context.config.setOnboarding({ serverPort: port });
+      context.config.completeOnboarding();
+
+      context.logger.info('Onboarding completed via wizard', {
+        event: 'onboarding_complete',
+        data: { agentName, defaultTier, port, topicCount: topics.length }
+      });
+
+      return res.json({ success: true });
+    } catch (err) {
+      context.logger.error('Onboarding completion failed', {
+        event: 'onboarding_error',
+        data: { error: err.message }
+      });
+      return res.status(500).json({
+        success: false,
+        error: { code: 'onboarding_failed', message: 'Failed to save onboarding configuration.' }
+      });
+    }
+  });
+```
+
+Also add a port-detection endpoint for the Network step:
+
+```js
+  // A2A-99: Port detection for onboarding network step.
+  router.get('/onboarding/detect-port', async (req, res) => {
+    const { findAvailablePort, isPortListening } = require('../lib/port-scanner');
+    const candidates = [80, 3001, 3002, 3003, 3007, 8080, 9001];
+    const port = await findAvailablePort(candidates);
+    return res.json({
+      success: true,
+      port: port,
+      candidates
+    });
+  });
+```
+
+**Step 2: Run tests to verify no regressions**
+
+Run: `npm test`
+Expected: All existing tests PASS (no changes to existing behavior)
+
+**Step 3: Commit**
+
+```bash
+git add src/routes/dashboard.js
+git commit -m "feat(a2a-99): add onboarding wizard API endpoints"
+```
+
+---
+
+## Task 2: Onboarding Wizard HTML
+
+**Files:**
+- Create: `src/dashboard/public/onboarding.html`
+
+**Step 1: Create the wizard HTML page**
+
+Create `src/dashboard/public/onboarding.html` — a standalone page (not part of the SPA) with the same Shoelace + font CDN links as `index.html`. 4-step wizard: Welcome, Disclosure Topics, Permissions, Network.
+
+```html
+<!doctype html>
+<html lang="en" class="sl-theme-dark">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>A2A Callbook — Setup</title>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.19/cdn/themes/dark.css" />
+  <script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.19/cdn/shoelace-autoloader.js"></script>
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:wght,FILL@100..700,0..1&display=swap" />
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" />
+  <link rel="stylesheet" href="./onboarding.css">
+</head>
+<body class="sl-theme-dark">
+  <div class="onboard-container">
+    <div class="onboard-card">
+      <!-- Progress indicator -->
+      <div class="onboard-progress">
+        <div class="progress-step active" data-step="1"><span>1</span><label>Welcome</label></div>
+        <div class="progress-line"></div>
+        <div class="progress-step" data-step="2"><span>2</span><label>Topics</label></div>
+        <div class="progress-line"></div>
+        <div class="progress-step" data-step="3"><span>3</span><label>Permissions</label></div>
+        <div class="progress-line"></div>
+        <div class="progress-step" data-step="4"><span>4</span><label>Network</label></div>
+      </div>
+
+      <!-- Step 1: Welcome -->
+      <div class="wizard-step active" id="step-1">
+        <div class="step-icon">
+          <span class="material-symbols-outlined">phone_in_talk</span>
+        </div>
+        <h1>Welcome to A2A Callbook</h1>
+        <p class="step-desc">A2A Calling lets your AI agent communicate with other agents. Let's set up your agent in a few quick steps.</p>
+        <sl-input id="agent-name" label="Name your agent" placeholder="e.g. My Assistant" size="large" required></sl-input>
+      </div>
+
+      <!-- Step 2: Disclosure Topics -->
+      <div class="wizard-step" id="step-2">
+        <div class="step-icon">
+          <span class="material-symbols-outlined">topic</span>
+        </div>
+        <h1>What does your agent discuss?</h1>
+        <p class="step-desc">Select topics your agent can talk about with callers. You can customize per-tier topics later in Settings.</p>
+        <div class="topic-grid" id="topic-grid">
+          <!-- Populated by JS -->
+        </div>
+        <sl-input id="custom-topics" label="Custom topics (comma-separated)" placeholder="e.g. cooking, travel, finance" size="medium"></sl-input>
+      </div>
+
+      <!-- Step 3: Permissions -->
+      <div class="wizard-step" id="step-3">
+        <div class="step-icon">
+          <span class="material-symbols-outlined">verified_user</span>
+        </div>
+        <h1>Default Permission Tier</h1>
+        <p class="step-desc">Choose the default permission level for new contacts. You can change individual contacts later.</p>
+        <div class="tier-cards" id="tier-cards">
+          <!-- Populated by JS -->
+        </div>
+      </div>
+
+      <!-- Step 4: Network -->
+      <div class="wizard-step" id="step-4">
+        <div class="step-icon">
+          <span class="material-symbols-outlined">lan</span>
+        </div>
+        <h1>Network Configuration</h1>
+        <p class="step-desc">We'll auto-detect your network settings. You can adjust them if needed.</p>
+        <div class="network-fields">
+          <sl-input id="server-port" label="Server Port" type="number" size="medium"></sl-input>
+          <sl-input id="server-hostname" label="Hostname" placeholder="auto-detected" size="medium"></sl-input>
+          <div id="port-status" class="port-status"></div>
+        </div>
+      </div>
+
+      <!-- Navigation buttons -->
+      <div class="wizard-nav">
+        <sl-button id="btn-back" variant="default" size="large" style="display:none;">
+          <span class="material-symbols-outlined" slot="prefix">arrow_back</span>
+          Back
+        </sl-button>
+        <div class="nav-spacer"></div>
+        <sl-button id="btn-next" variant="primary" size="large">
+          Next
+          <span class="material-symbols-outlined" slot="suffix">arrow_forward</span>
+        </sl-button>
+      </div>
+
+      <!-- Error display -->
+      <div id="wizard-error" class="wizard-error" style="display:none;"></div>
+    </div>
+  </div>
+
+  <script src="./onboarding.js"></script>
+</body>
+</html>
+```
+
+**Step 2: Commit**
+
+```bash
+git add src/dashboard/public/onboarding.html
+git commit -m "feat(a2a-99): add onboarding wizard HTML"
+```
+
+---
+
+## Task 3: Onboarding Wizard CSS
+
+**Files:**
+- Create: `src/dashboard/public/onboarding.css`
+
+**Step 1: Create the wizard stylesheet**
+
+Reuse dashboard design tokens from `style.css`. Dark theme, centered card layout, responsive (min 480px).
+
+```css
+/* A2A-99: Onboarding wizard styles — reuses dashboard design tokens */
+:root {
+  --bg: #0B0E14;
+  --panel: #151B28;
+  --ink: #e2e8f0;
+  --ink-muted: #94a3b8;
+  --line: rgba(255, 255, 255, 0.08);
+  --accent: #3B82F6;
+  --card-bg: #1E2738;
+  --sl-color-primary-600: var(--accent);
+  --sl-font-sans: "Inter", "IBM Plex Sans", "Segoe UI", sans-serif;
+}
+
+* { box-sizing: border-box; }
+
+body {
+  margin: 0;
+  font-family: var(--sl-font-sans);
+  color: var(--ink);
+  background: var(--bg);
+  min-height: 100vh;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.onboard-container {
+  width: 100%;
+  max-width: 640px;
+  padding: 1.5rem;
+}
+
+.onboard-card {
+  background: var(--panel);
+  border: 1px solid var(--line);
+  border-radius: 16px;
+  padding: 2.5rem 2rem 2rem;
+}
+
+/* ── Progress indicator ──────────────────────────────── */
+.onboard-progress {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0;
+  margin-bottom: 2rem;
+}
+
+.progress-step {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 0.3rem;
+}
+
+.progress-step span {
+  width: 32px;
+  height: 32px;
+  border-radius: 50%;
+  background: var(--card-bg);
+  border: 2px solid var(--line);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 0.85rem;
+  font-weight: 600;
+  color: var(--ink-muted);
+  transition: all 0.2s;
+}
+
+.progress-step.active span,
+.progress-step.done span {
+  background: var(--accent);
+  border-color: var(--accent);
+  color: #fff;
+}
+
+.progress-step.done span {
+  background: #10B981;
+  border-color: #10B981;
+}
+
+.progress-step label {
+  font-size: 0.7rem;
+  color: var(--ink-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+.progress-step.active label {
+  color: var(--ink);
+}
+
+.progress-line {
+  flex: 1;
+  height: 2px;
+  background: var(--line);
+  margin: 0 0.5rem;
+  margin-bottom: 1.2rem;
+}
+
+/* ── Wizard steps ─────────────────────────────────────── */
+.wizard-step {
+  display: none;
+  text-align: center;
+}
+
+.wizard-step.active {
+  display: block;
+}
+
+.step-icon {
+  margin-bottom: 0.8rem;
+}
+
+.step-icon .material-symbols-outlined {
+  font-size: 48px;
+  color: var(--accent);
+}
+
+.wizard-step h1 {
+  font-size: 1.5rem;
+  font-weight: 600;
+  margin: 0 0 0.5rem;
+}
+
+.step-desc {
+  color: var(--ink-muted);
+  font-size: 0.95rem;
+  margin: 0 0 1.5rem;
+  line-height: 1.5;
+}
+
+.wizard-step sl-input,
+.wizard-step sl-select {
+  text-align: left;
+  margin-bottom: 1rem;
+}
+
+/* ── Topic grid (Step 2) ──────────────────────────────── */
+.topic-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(140px, 1fr));
+  gap: 0.5rem;
+  margin-bottom: 1rem;
+  text-align: left;
+}
+
+.topic-chip {
+  display: flex;
+  align-items: center;
+  gap: 0.4rem;
+  padding: 0.5rem 0.75rem;
+  background: var(--card-bg);
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  cursor: pointer;
+  font-size: 0.85rem;
+  transition: all 0.15s;
+  user-select: none;
+}
+
+.topic-chip:hover {
+  border-color: var(--accent);
+}
+
+.topic-chip.selected {
+  background: rgba(59, 130, 246, 0.15);
+  border-color: var(--accent);
+  color: #fff;
+}
+
+.topic-chip .material-symbols-outlined {
+  font-size: 18px;
+}
+
+/* ── Tier cards (Step 3) ──────────────────────────────── */
+.tier-cards {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+  text-align: left;
+}
+
+.tier-card {
+  padding: 1rem 1.2rem;
+  background: var(--card-bg);
+  border: 2px solid var(--line);
+  border-radius: 10px;
+  cursor: pointer;
+  transition: all 0.15s;
+}
+
+.tier-card:hover {
+  border-color: var(--accent);
+}
+
+.tier-card.selected {
+  border-color: var(--accent);
+  background: rgba(59, 130, 246, 0.1);
+}
+
+.tier-card h3 {
+  margin: 0 0 0.3rem;
+  font-size: 1rem;
+  font-weight: 600;
+}
+
+.tier-card p {
+  margin: 0;
+  font-size: 0.85rem;
+  color: var(--ink-muted);
+  line-height: 1.4;
+}
+
+/* ── Network fields (Step 4) ──────────────────────────── */
+.network-fields {
+  text-align: left;
+}
+
+.network-fields sl-input {
+  margin-bottom: 1rem;
+}
+
+.port-status {
+  font-size: 0.85rem;
+  padding: 0.5rem 0;
+}
+
+.port-status.ok { color: #10B981; }
+.port-status.error { color: #EF4444; }
+.port-status.detecting { color: var(--ink-muted); }
+
+/* ── Navigation ───────────────────────────────────────── */
+.wizard-nav {
+  display: flex;
+  align-items: center;
+  margin-top: 2rem;
+  gap: 0.75rem;
+}
+
+.nav-spacer { flex: 1; }
+
+/* ── Error display ────────────────────────────────────── */
+.wizard-error {
+  margin-top: 1rem;
+  padding: 0.75rem 1rem;
+  background: rgba(239, 68, 68, 0.1);
+  border: 1px solid rgba(239, 68, 68, 0.3);
+  border-radius: 8px;
+  color: #EF4444;
+  font-size: 0.85rem;
+}
+
+/* ── Responsive ───────────────────────────────────────── */
+@media (max-width: 480px) {
+  .onboard-card {
+    padding: 1.5rem 1rem 1rem;
+    border-radius: 12px;
+  }
+
+  .topic-grid {
+    grid-template-columns: repeat(auto-fill, minmax(120px, 1fr));
+  }
+
+  .progress-step label {
+    display: none;
+  }
+}
+```
+
+**Step 2: Commit**
+
+```bash
+git add src/dashboard/public/onboarding.css
+git commit -m "feat(a2a-99): add onboarding wizard styles"
+```
+
+---
+
+## Task 4: Onboarding Wizard JavaScript
+
+**Files:**
+- Create: `src/dashboard/public/onboarding.js`
+
+**Step 1: Create the wizard logic**
+
+Handles step navigation, topic selection, tier selection, port auto-detection, and form submission.
+
+```js
+/* A2A-99: Onboarding wizard logic — vanilla JS + Shoelace */
+(function () {
+  'use strict';
+
+  const PRESET_TOPICS = [
+    { id: 'coding', label: 'Coding', icon: 'code' },
+    { id: 'scheduling', label: 'Scheduling', icon: 'calendar_month' },
+    { id: 'research', label: 'Research', icon: 'search' },
+    { id: 'writing', label: 'Writing', icon: 'edit_note' },
+    { id: 'email', label: 'Email', icon: 'mail' },
+    { id: 'data-analysis', label: 'Data Analysis', icon: 'analytics' },
+    { id: 'creative', label: 'Creative', icon: 'palette' },
+    { id: 'math', label: 'Math', icon: 'calculate' },
+    { id: 'general', label: 'General Chat', icon: 'chat' },
+    { id: 'devops', label: 'DevOps', icon: 'terminal' },
+    { id: 'documentation', label: 'Documentation', icon: 'description' },
+    { id: 'debugging', label: 'Debugging', icon: 'bug_report' }
+  ];
+
+  const TIERS = [
+    {
+      id: 'public',
+      name: 'Public',
+      desc: 'Minimal access — callers can only read your agent\'s context. Best for unknown contacts.',
+      capabilities: 'context-read'
+    },
+    {
+      id: 'friends',
+      name: 'Friends',
+      desc: 'Moderate access — callers can read calendar, email, and search. Good for trusted colleagues.',
+      capabilities: 'context-read, calendar.read, email.read, search'
+    },
+    {
+      id: 'family',
+      name: 'Family',
+      desc: 'Full access — callers get tools, memory, and all capabilities. Only for highly trusted agents.',
+      capabilities: 'context-read, calendar, email, search, tools, memory'
+    }
+  ];
+
+  let currentStep = 1;
+  const totalSteps = 4;
+  let selectedTopics = new Set();
+  let selectedTier = 'public';
+  let detectedPort = null;
+
+  // ── DOM refs ──────────────────────────────────────────
+  const btnNext = document.getElementById('btn-next');
+  const btnBack = document.getElementById('btn-back');
+  const errorEl = document.getElementById('wizard-error');
+
+  // ── Initialize ────────────────────────────────────────
+  function init() {
+    // A2A-99: Check if already onboarded — redirect to dashboard if so.
+    fetch('./onboarding/status')
+      .then(r => r.json())
+      .then(data => {
+        if (data.onboarded) {
+          window.location.href = './';
+          return;
+        }
+        // Pre-fill agent name from any partial onboarding state
+        if (data.onboarding && data.onboarding.agentName) {
+          const nameInput = document.getElementById('agent-name');
+          if (nameInput) nameInput.value = data.onboarding.agentName;
+        }
+      })
+      .catch(() => { /* proceed with wizard */ });
+
+    renderTopicGrid();
+    renderTierCards();
+    updateNav();
+    detectPort();
+
+    btnNext.addEventListener('click', handleNext);
+    btnBack.addEventListener('click', handleBack);
+  }
+
+  // ── Topic grid ────────────────────────────────────────
+  function renderTopicGrid() {
+    const grid = document.getElementById('topic-grid');
+    grid.innerHTML = PRESET_TOPICS.map(t =>
+      `<div class="topic-chip" data-topic="${t.id}">` +
+      `<span class="material-symbols-outlined">${t.icon}</span>` +
+      `${t.label}</div>`
+    ).join('');
+
+    grid.addEventListener('click', (e) => {
+      const chip = e.target.closest('.topic-chip');
+      if (!chip) return;
+      const topic = chip.dataset.topic;
+      if (selectedTopics.has(topic)) {
+        selectedTopics.delete(topic);
+        chip.classList.remove('selected');
+      } else {
+        selectedTopics.add(topic);
+        chip.classList.add('selected');
+      }
+    });
+  }
+
+  // ── Tier cards ────────────────────────────────────────
+  function renderTierCards() {
+    const container = document.getElementById('tier-cards');
+    container.innerHTML = TIERS.map(t =>
+      `<div class="tier-card${t.id === selectedTier ? ' selected' : ''}" data-tier="${t.id}">` +
+      `<h3>${t.name}</h3>` +
+      `<p>${t.desc}</p>` +
+      `</div>`
+    ).join('');
+
+    container.addEventListener('click', (e) => {
+      const card = e.target.closest('.tier-card');
+      if (!card) return;
+      selectedTier = card.dataset.tier;
+      container.querySelectorAll('.tier-card').forEach(c => c.classList.remove('selected'));
+      card.classList.add('selected');
+    });
+  }
+
+  // ── Port detection ────────────────────────────────────
+  function detectPort() {
+    const status = document.getElementById('port-status');
+    const portInput = document.getElementById('server-port');
+    status.textContent = 'Detecting available port...';
+    status.className = 'port-status detecting';
+
+    fetch('./onboarding/detect-port')
+      .then(r => r.json())
+      .then(data => {
+        if (data.port) {
+          detectedPort = data.port;
+          portInput.value = data.port;
+          status.textContent = `Port ${data.port} is available.`;
+          status.className = 'port-status ok';
+        } else {
+          status.textContent = 'No available port found. Enter one manually.';
+          status.className = 'port-status error';
+        }
+      })
+      .catch(() => {
+        status.textContent = 'Could not detect port. Enter one manually.';
+        status.className = 'port-status error';
+      });
+  }
+
+  // ── Navigation ────────────────────────────────────────
+  function goToStep(step) {
+    document.querySelectorAll('.wizard-step').forEach(el => el.classList.remove('active'));
+    document.getElementById(`step-${step}`).classList.add('active');
+
+    document.querySelectorAll('.progress-step').forEach(el => {
+      const s = Number(el.dataset.step);
+      el.classList.remove('active', 'done');
+      if (s === step) el.classList.add('active');
+      else if (s < step) el.classList.add('done');
+    });
+
+    currentStep = step;
+    updateNav();
+    hideError();
+  }
+
+  function updateNav() {
+    btnBack.style.display = currentStep === 1 ? 'none' : '';
+
+    if (currentStep === totalSteps) {
+      btnNext.textContent = 'Finish Setup';
+      // Remove suffix icon for finish button
+      const suffix = btnNext.querySelector('[slot="suffix"]');
+      if (suffix) suffix.textContent = 'check';
+    } else {
+      // Restore next icon
+      const suffix = btnNext.querySelector('[slot="suffix"]');
+      if (suffix) suffix.textContent = 'arrow_forward';
+    }
+  }
+
+  function handleNext() {
+    if (!validateStep(currentStep)) return;
+
+    if (currentStep === totalSteps) {
+      submitOnboarding();
+    } else {
+      goToStep(currentStep + 1);
+    }
+  }
+
+  function handleBack() {
+    if (currentStep > 1) {
+      goToStep(currentStep - 1);
+    }
+  }
+
+  // ── Validation ────────────────────────────────────────
+  function validateStep(step) {
+    if (step === 1) {
+      const name = (document.getElementById('agent-name').value || '').trim();
+      if (!name) {
+        showError('Please enter a name for your agent.');
+        return false;
+      }
+    }
+    if (step === 4) {
+      const port = Number.parseInt(document.getElementById('server-port').value, 10);
+      if (!Number.isFinite(port) || port < 1 || port > 65535) {
+        showError('Please enter a valid port number (1-65535).');
+        return false;
+      }
+    }
+    return true;
+  }
+
+  // ── Submit ────────────────────────────────────────────
+  function submitOnboarding() {
+    const agentName = (document.getElementById('agent-name').value || '').trim();
+    const port = Number.parseInt(document.getElementById('server-port').value, 10);
+    const hostname = (document.getElementById('server-hostname').value || '').trim();
+
+    // Merge preset selections with custom topics
+    const customRaw = (document.getElementById('custom-topics').value || '').trim();
+    const customTopics = customRaw
+      ? customRaw.split(',').map(t => t.trim()).filter(Boolean)
+      : [];
+    const allTopics = [...selectedTopics, ...customTopics];
+
+    btnNext.loading = true;
+    btnNext.disabled = true;
+    hideError();
+
+    fetch('./onboarding/complete', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        agentName,
+        defaultTier: selectedTier,
+        port,
+        hostname,
+        topics: allTopics
+      })
+    })
+      .then(r => r.json())
+      .then(data => {
+        if (data.success) {
+          // A2A-99: Navigate to dashboard after successful onboarding.
+          window.location.href = './';
+        } else {
+          const msg = (data.error && data.error.message) || 'Onboarding failed.';
+          showError(msg);
+        }
+      })
+      .catch(err => {
+        showError('Network error: ' + (err.message || 'unknown'));
+      })
+      .finally(() => {
+        btnNext.loading = false;
+        btnNext.disabled = false;
+      });
+  }
+
+  // ── Error helpers ─────────────────────────────────────
+  function showError(msg) {
+    errorEl.textContent = msg;
+    errorEl.style.display = 'block';
+  }
+
+  function hideError() {
+    errorEl.style.display = 'none';
+  }
+
+  // ── Boot ──────────────────────────────────────────────
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', init);
+  } else {
+    init();
+  }
+})();
+```
+
+**Step 2: Commit**
+
+```bash
+git add src/dashboard/public/onboarding.js
+git commit -m "feat(a2a-99): add onboarding wizard JavaScript"
+```
+
+---
+
+## Task 5: Modify discovery.rs — Add onboarding_complete Field
+
+**Files:**
+- Modify: `native/macos/src-tauri/src/discovery.rs`
+
+**Step 1: Add `onboarding_complete` to DiscoveryResult and config reading**
+
+Add a `step` field to `OnboardingConfig`:
+
+```rust
+#[derive(Debug, Deserialize)]
+struct OnboardingConfig {
+    #[serde(alias = "serverPort")]
+    server_port: Option<u16>,
+    step: Option<String>,
+    version: Option<u16>,
+}
+```
+
+Add `onboarding_complete` to `DiscoveryResult`:
+
+```rust
+#[derive(Debug, Serialize, Deserialize)]
+pub struct DiscoveryResult {
+    pub port: Option<u16>,
+    pub source: String,
+    pub onboarding_complete: bool,
+}
+```
+
+Add a new public function to check onboarding status:
+
+```rust
+/// Check if onboarding has been completed by reading config.
+pub fn is_onboarding_complete() -> bool {
+    let config_dir = std::env::var("A2A_CONFIG_DIR")
+        .or_else(|_| std::env::var("OPENCLAW_CONFIG_DIR"))
+        .map(PathBuf::from)
+        .unwrap_or_else(|_| {
+            dirs::home_dir()
+                .unwrap_or_else(|| PathBuf::from("/tmp"))
+                .join(".config")
+                .join("openclaw")
+        });
+
+    let config_path = config_dir.join("a2a-config.json");
+    let content = match std::fs::read_to_string(config_path) {
+        Ok(data) => data,
+        Err(_) => return false,
+    };
+    let config: A2AConfig = match serde_json::from_str(&content) {
+        Ok(parsed) => parsed,
+        Err(_) => return false,
+    };
+
+    config
+        .onboarding
+        .map(|ob| ob.version == Some(2) && ob.step.as_deref() == Some("complete"))
+        .unwrap_or(false)
+}
+```
+
+Update `discover_server` to populate `onboarding_complete` in all return paths:
+
+```rust
+pub async fn discover_server(sidecar_port: Option<u16>) -> DiscoveryResult {
+    let onboarding_complete = is_onboarding_complete();
+
+    if let Some(port) = sidecar_port {
+        if probe_port(port).await {
+            return DiscoveryResult {
+                port: Some(port),
+                source: "sidecar".to_string(),
+                onboarding_complete,
+            };
+        }
+    }
+
+    // ... same logic, but all DiscoveryResult constructions include onboarding_complete
+}
+```
+
+**Step 2: Verify Rust compiles**
+
+Run: `cd native/macos/src-tauri && cargo check`
+(May not compile on this server without Tauri deps — that's OK, verify syntax is correct)
+
+**Step 3: Commit**
+
+```bash
+git add native/macos/src-tauri/src/discovery.rs
+git commit -m "feat(a2a-99): add onboarding_complete to DiscoveryResult"
+```
+
+---
+
+## Task 6: Modify native/macos/index.html — Route to Onboarding
+
+**Files:**
+- Modify: `native/macos/index.html`
+
+**Step 1: Add onboarding branching in checkServer()**
+
+Replace the navigation block in `checkServer()` (lines ~107-116) with:
+
+```js
+if (result.port) {
+  show('status-connected');
+  document.getElementById('connected-port').textContent =
+    `localhost:${result.port}`;
+  // A2A-99: Route to onboarding wizard if not yet onboarded.
+  const target = result.onboarding_complete === false
+    ? `http://127.0.0.1:${result.port}/api/a2a/dashboard/onboarding`
+    : `http://127.0.0.1:${result.port}/api/a2a/dashboard/` +
+      (window.__TAB_HASH || '');
+  setTimeout(() => {
+    window.location.href = target;
+  }, 400);
+}
+```
+
+**Step 2: Commit**
+
+```bash
+git add native/macos/index.html
+git commit -m "feat(a2a-99): route to onboarding wizard on fresh install"
+```
+
+---
+
+## Task 7: Integration Tests
+
+**Files:**
+- Create: `test/integration/onboarding-wizard.test.js`
+
+**Step 1: Write the integration tests**
+
+Follow the pattern from `test/integration/dashboard-crud.test.js`.
+
+```js
+/**
+ * Onboarding Wizard API Integration Tests (A2A-99)
+ *
+ * Tests the onboarding wizard API endpoints:
+ *   - GET /onboarding (serves wizard HTML)
+ *   - GET /onboarding/status (checks onboarding state)
+ *   - GET /onboarding/detect-port (finds available port)
+ *   - POST /onboarding/complete (writes config + disclosure)
+ */
+
+module.exports = function (test, assert, helpers) {
+  let tmp = null;
+  let client = null;
+  let loggerModule = null;
+
+  async function setup() {
+    tmp = helpers.tmpConfigDir('onboard-wizard');
+
+    delete require.cache[require.resolve('../../src/routes/dashboard')];
+    delete require.cache[require.resolve('../../src/lib/logger')];
+    delete require.cache[require.resolve('../../src/lib/tokens')];
+    delete require.cache[require.resolve('../../src/lib/config')];
+    delete require.cache[require.resolve('../../src/lib/disclosure')];
+    delete require.cache[require.resolve('../../src/lib/conversations')];
+    delete require.cache[require.resolve('../../src/lib/callbook')];
+    delete require.cache[require.resolve('../../src/lib/dashboard-events')];
+
+    const express = require('express');
+    const { createDashboardApiRouter } = require('../../src/routes/dashboard');
+    loggerModule = require('../../src/lib/logger');
+
+    const app = express();
+    app.use('/api/a2a/dashboard', createDashboardApiRouter({
+      logger: loggerModule.createLogger({
+        component: 'test.onboarding',
+        configDir: tmp.dir,
+        stdout: false
+      })
+    }));
+    client = helpers.request(app);
+  }
+
+  async function teardown() {
+    if (client) await client.close();
+    client = null;
+    if (loggerModule && typeof loggerModule.closeAllLoggerStores === 'function') {
+      loggerModule.closeAllLoggerStores();
+    }
+    loggerModule = null;
+    if (tmp) tmp.cleanup();
+    tmp = null;
+  }
+
+  // ── GET /onboarding — serves wizard HTML ──────────────
+  test('GET /onboarding returns wizard HTML', async () => {
+    await setup();
+    try {
+      const res = await client.get('/api/a2a/dashboard/onboarding');
+      assert.equal(res.status, 200);
+      assert.includes(res.headers['content-type'], 'text/html');
+    } finally {
+      await teardown();
+    }
+  });
+
+  // ── GET /onboarding/status — fresh install ────────────
+  test('onboarding status shows not onboarded on fresh install', async () => {
+    await setup();
+    try {
+      const res = await client.get('/api/a2a/dashboard/onboarding/status');
+      assert.equal(res.status, 200);
+      const body = JSON.parse(res.body);
+      assert.equal(body.success, true);
+      assert.equal(body.onboarded, false);
+    } finally {
+      await teardown();
+    }
+  });
+
+  // ── GET /onboarding/detect-port ───────────────────────
+  test('detect-port returns a port number', async () => {
+    await setup();
+    try {
+      const res = await client.get('/api/a2a/dashboard/onboarding/detect-port');
+      assert.equal(res.status, 200);
+      const body = JSON.parse(res.body);
+      assert.equal(body.success, true);
+      assert.ok(Array.isArray(body.candidates));
+    } finally {
+      await teardown();
+    }
+  });
+
+  // ── POST /onboarding/complete — happy path ────────────
+  test('complete onboarding writes config and disclosure', async () => {
+    await setup();
+    try {
+      const res = await client.post('/api/a2a/dashboard/onboarding/complete', {
+        agentName: 'Test Agent',
+        defaultTier: 'public',
+        port: 3099,
+        hostname: 'localhost:3099',
+        topics: ['coding', 'research']
+      });
+      assert.equal(res.status, 200);
+      const body = JSON.parse(res.body);
+      assert.equal(body.success, true);
+
+      // Verify config was written correctly
+      const { A2AConfig } = require('../../src/lib/config');
+      const config = new A2AConfig();
+      assert.equal(config.isOnboarded(), true);
+      assert.equal(config.getAgent().name, 'Test Agent');
+
+      // Verify disclosure was written
+      const disc = require('../../src/lib/disclosure');
+      const manifest = disc.loadManifest();
+      assert.ok(manifest.tiers);
+      assert.ok(manifest.tiers.public);
+    } finally {
+      await teardown();
+    }
+  });
+
+  // ── POST /onboarding/complete — missing agent name ────
+  test('complete onboarding rejects missing agent name', async () => {
+    await setup();
+    try {
+      const res = await client.post('/api/a2a/dashboard/onboarding/complete', {
+        defaultTier: 'public',
+        port: 3099
+      });
+      assert.equal(res.status, 400);
+      const body = JSON.parse(res.body);
+      assert.equal(body.success, false);
+      assert.includes(body.error.code, 'missing_agent_name');
+    } finally {
+      await teardown();
+    }
+  });
+
+  // ── POST /onboarding/complete — invalid tier ──────────
+  test('complete onboarding rejects invalid tier', async () => {
+    await setup();
+    try {
+      const res = await client.post('/api/a2a/dashboard/onboarding/complete', {
+        agentName: 'Test',
+        defaultTier: 'admin',
+        port: 3099
+      });
+      assert.equal(res.status, 400);
+      const body = JSON.parse(res.body);
+      assert.includes(body.error.code, 'invalid_tier');
+    } finally {
+      await teardown();
+    }
+  });
+
+  // ── POST /onboarding/complete — invalid port ──────────
+  test('complete onboarding rejects invalid port', async () => {
+    await setup();
+    try {
+      const res = await client.post('/api/a2a/dashboard/onboarding/complete', {
+        agentName: 'Test',
+        defaultTier: 'public',
+        port: 99999
+      });
+      assert.equal(res.status, 400);
+      const body = JSON.parse(res.body);
+      assert.includes(body.error.code, 'invalid_port');
+    } finally {
+      await teardown();
+    }
+  });
+
+  // ── Existing config detection ─────────────────────────
+  test('onboarding status shows onboarded when config exists', async () => {
+    await setup();
+    try {
+      // First complete onboarding
+      await client.post('/api/a2a/dashboard/onboarding/complete', {
+        agentName: 'Existing Agent',
+        defaultTier: 'friends',
+        port: 3099,
+        topics: ['coding']
+      });
+
+      // Then check status
+      const res = await client.get('/api/a2a/dashboard/onboarding/status');
+      const body = JSON.parse(res.body);
+      assert.equal(body.onboarded, true);
+    } finally {
+      await teardown();
+    }
+  });
+};
+```
+
+**Step 2: Run tests**
+
+Run: `npm test`
+Expected: All tests pass including new onboarding wizard tests.
+
+**Step 3: Commit**
+
+```bash
+git add test/integration/onboarding-wizard.test.js
+git commit -m "test(a2a-99): add onboarding wizard integration tests"
+```
+
+---
+
+## Task 8: Final Verification and CONVENTIONS.md Update
+
+**Files:**
+- Modify: `CONVENTIONS.md` — add onboarding wizard section
+
+**Step 1: Run full test suite**
+
+Run: `npm test`
+Expected: ALL tests pass.
+
+**Step 2: Update CONVENTIONS.md**
+
+Add after the "Native App Sidecar Lifecycle" section:
+
+```markdown
+## Native Onboarding Wizard (A2A-99)
+
+The onboarding wizard at `/api/a2a/dashboard/onboarding` runs on fresh installs (no `a2a-config.json`). Key patterns:
+- Wizard routes (`/onboarding`, `/onboarding/status`, `/onboarding/complete`, `/onboarding/detect-port`) are placed BEFORE `ensureDashboardAccess` middleware — they must work without auth
+- Config/disclosure writes use existing `A2AConfig` and `disclosure.js` APIs — do not duplicate validation
+- `DiscoveryResult` in `discovery.rs` includes `onboarding_complete: bool` to let `native/macos/index.html` route to wizard vs dashboard
+- Topics selected in the wizard populate the `public` tier only — users refine per-tier topics in Settings
+```
+
+**Step 3: Commit all**
+
+```bash
+git add CONVENTIONS.md
+git commit -m "docs(a2a-99): add onboarding wizard conventions"
+```