Onboarding Walkthrough — the 5-step SOP for the new user

Why this matters

Born 2026-09-01 from the sleeper-mode production-readiness directive. Every AI IDE / CLI in 2026 ships a first-run walkthrough (verified across 7 sources: Cursor, VS Code Copilot, Cline, Windsurf/Devin, Claude Code, Aider, Continue). AIDE has the doctrine + the runtime for every walkthrough component (privacy, BYOK, workbench, desktop, system map) but no UI ties them together. This skill IS the wire-in. Per the audit (line 89): P2 Onboarding, 1 week, ships at end of week 3 (Gate 4, line 149).

The 5 steps (the spec)

Each step is a <walkthrough-step> component in the cockpit. State is held in walkthroughState: { currentStep, completed: Record<stepId, boolean>, userChoices: { name?, role?, workbench?, byokProvider?, byokKeyStored: boolean, desktopEnabled: boolean } }. Persisted to <workspace>/.aide/onboarding-state.json so the walkthrough is resumable across restarts. Each step has a next button (validates required fields) and a skip button (marks step as skipped:true and advances). On next for step 5, mark walkthroughComplete:true and route to the cockpit home page.

Step 1 — Welcome

• Tile: AIDE logo + 3 workbench thumbnails (sovereign-coder / sovereign-pipeline / sovereign-architect, loaded from workbenches/*.json).
• Form: name (string, max 80), role (enum: developer / researcher / student / other).
• Default selection: sovereign-coder (most common per the audit).
• next is enabled when name is non-empty.
• Citation: per Cline "Authorize with Cline" + Windsurf "1. Select your preferred theme 2. Log In 3. Start Building" + Cursor "Get started — Go from install to your first useful change."

Step 2 — Privacy

• Single card. The exact copy (operator canon, from aide-credo-guardrail):

  AIDE is offline-first. Your code. Your models. Your data. Nothing leaves without your hand. We journal every egress (if you opt in). See aide-master-roadmap law #2 (No-Phone-Home). Built-in workflows. In-house skills. Agents. Orchestrator. Everything improves with use.

• One button: "I understand. Continue." (no choice, no opt-out; this is the doctrine, not a preference).
• Citation: per VS Code Copilot "Trust Center FAQ" + Claude Code "Privacy choices" + Cursor "Trust & Safety" (the privacy disclosure IS the step, not buried in a settings menu).

Step 3 — BYOK opt-in

• Provider picker (dropdown): OpenAI / Anthropic / Cohere / OpenRouter / Mistral / Groq / Gemini. Each shows egressHost from aide-provider-connect §1 (built-ins, hosts verified 2026-08-20).
• API key input (password-masked, never echoed).
• On connect: POST to /api/byok/key {provider_id, api_key} per aide-cloud-handoff H2. Daemon stores DPAPI, returns {stored: true}. UI shows success or invalid_key / unreachable per the connect-flow in aide-provider-connect §3 (5s timeout, max_tokens 1, status cached 60s).
• skip is highlighted as "Continue offline" (the DEFAULT). BYOK is opt-in, not opt-out. Cline ships the same pattern: "use the Cline Provider for pay-as-you-go access, ClinePass for a flat monthly subscription, or bring your own provider key" (Cline docs, §Authorize with Cline).
• Citation: Cline (explicit "bring your own provider key") + Claude Code ("Most surfaces require a Claude subscription or Anthropic Console account. The Terminal CLI, VS Code, and JetBrains also support third-party providers.") + Aider (14 providers including Ollama, the offline-friendly default).

Step 4 — Desktop control opt-in

• Single card. The exact copy:

  AIDE can drive your desktop when you grant it. Every action is journaled. You can panic-stop at any time. Default = OFF. Click to enable.

• One button: "Enable desktop control" (opt-in). skip = "Not now" (default).
• On enable: POST to /api/desktop/grant { scope: "default" } per aide-p6-desktop-control (Stage A bounded grants). The cockpit shows the desktop control panel after walkthrough completion.
• Citation: the rivals do NOT ship desktop control. AIDE IS the differentiator (audit line 326). The opt-in pattern is the safer default (P5: never harm the operator; every action journaled per aide-credo-guardrail).

Step 5 — System map

• One screen showing 8 cards in a grid. Each card is a subsystem with status (live / offline / N/A), last-updated timestamp, and a journal link.
• The 8 cards:
  1. In-house model (North-Mini-Code-1.0 — models/manifest.json) — status from /api/models/status
  2. 3 Workbenches (sovereign-coder/pipeline/architect) — installed/available per /api/workbenches
  3. 197 Skills — count from skills/packs/ directory
  4. Agent loop (online/offline) — from /api/agent/status
  5. Micro-Experts (3 trained: task-router, diff-risk-gate, request-intent-classifier) — from /api/experts/list
  6. DNA-Helix memory (X1 spine / X2 join / X3 retention) — from harness/memory-spine.mjs
  7. Veritas + Selfheal (credo + 5 oaths + bounded repair) — from scripts/selfheal.mjs
  8. BYOK + Desktop control (if enabled in steps 3-4) — from /api/byok/status + /api/desktop/status
• "Click any tile to expand" → tile expands to show the subsystem doc + the doctrine skill + the runtime status.
• Final button: "Open the cockpit" → routes to / and marks walkthroughComplete:true.
• Citation: per Cursor capabilities list + VS Code "Customize agents" doc + Cline "Memory Bank" (the rivals show users what they have; this IS the system map).

Files to touch (when wiring — the runtime PRs)

File	Change
common/contracts/onboarding.ts	NEW: zod schemas for OnboardingState, OnboardingStep (discriminated union of 5 step types), OnboardingChoice (provider, workbench, desktopEnabled, name, role). All .strict().
node/src/services/onboarding.mjs	NEW: createOnboardingService({workspace}) with getState(), setState(state), nextStep(), prevStep(), skipStep(), complete(). Persists to <workspace>/.aide/onboarding-state.json atomically. Never mutates other .aide/ files.
node/src/routes/onboarding.ts	NEW: 4 routes — GET /api/onboarding/state, PUT /api/onboarding/state, POST /api/onboarding/next, POST /api/onboarding/complete. All zod-strict.
browser/src/cockpit/walkthrough/Walkthrough.tsx	NEW: the 5-step state machine + step router.
browser/src/cockpit/walkthrough/steps/Welcome.tsx	NEW: Step 1.
browser/src/cockpit/walkthrough/steps/Privacy.tsx	NEW: Step 2.
browser/src/cockpit/walkthrough/steps/ByokOptin.tsx	NEW: Step 3 (reuses the connect form from aide-provider-connect).
browser/src/cockpit/walkthrough/steps/DesktopOptin.tsx	NEW: Step 4.
browser/src/cockpit/walkthrough/steps/SystemMap.tsx	NEW: Step 5 (reuses the cards from aide-system-map).
browser/src/cockpit/walkthrough/index.ts	NEW: exports Walkthrough + the 5 steps.
node/src/openapi.ts	EXTEND: register routesForOnboarding(onboardingService) in the build routes.
common/openapi.json	REGENERATE: npm run contracts (per aide-typescript-strict-pass).
tests/arch/onboarding-walkthrough-doctrine.test.ts	NEW: parses this skill + asserts the 5 step names + the contract schemas + the 4 routes.

Threat matrix

Threat	Likelihood	Blast radius	Mitigation	Detection test
BYOK key echoed in WS events / logs / error strings	medium (real bug class — see aide-cloud-handoff §0 DPAPI pitfall)	credential leak	daemon-only; scrub all error paths; store providerId only in UI state; veritas secret-scan in CI	the key string never appears in any test fixture or egress-journal.jsonl
Desktop control granted accidentally	low (opt-in only)	machine-wide action	default = OFF; every action journaled; panic-stop button on every desktop route; bounded grants (Stage A)	the walkthrough defaults to desktop OFF, the test asserts that
Walkthrough state corruption crashes the cockpit on first launch	medium (state is persisted JSON)	new users see a broken app	atomic write (write to .partial then rename); zod-strict parse on load; if parse fails, reset to step 1 + journal the corruption	corrupt the file, reload, assert graceful reset
Egress allowlist bypass via custom BYOK host	medium (Aider ships this)	data exfiltration	explicit per-host approval + persist to .aide/provider-hosts.json; scripts/egress-audit.mjs FAIL rule: no provider host in browser/dist	add a malicious host, assert refused
Walkthrough skipped, user lands on cockpit with no system map context	low (skip is allowed)	user is lost	system map is ALSO a top-level cockpit panel (not walkthrough-only); once seen, always reachable	skip the walkthrough, assert the system map is in the cockpit
API key probe (1-token call) hangs the walkthrough	low (5s timeout)	walkthrough stalls	AbortController 5s; cached 60s TTL per aide-provider-connect §3	mock a hanging probe, assert 5s timeout fires
DPAPI refuses (non-Windows host, AIDE_ALLOW_PLAINTEXT_SECRETS unset)	low (Windows-only)	BYOK step fails cleanly	typed error surfaced to UI as "BYOK requires Windows in this build" with a fallback to Aider-style env-var key	non-Windows test asserts the error message
User picks a workbench they later regret	low (can re-pick)	wasted 5 minutes	workbench switcher in the cockpit header (sovereign-coder/pipeline/architect always one click away)	change workbench, assert the cockpit re-loads with new plugins

Dependencies

Upstream phase skills (must be loaded first):

• aide-ide-research — R1+R2 (3 sources per claim, this skill cites 7)
• aide-vscode-parity-roadmap — the per-phase skill spec this follows
• aide-cloud-handoff H1+H2 — the BYOK routes (8 BYOK + 4 provider)
• aide-provider-connect — the connect-flow doctrine + the 6 verified hosts
• aide-p6-desktop-control — the desktop control Stage A bounded grants
• aide-p2-descent-intro — the cinematic that plays BEFORE this walkthrough
• aide-p2-onboarding — the parent P2 phase (audit line 89, gate 4 line 149)
• aide-system-map — the sister skill (the walkthrough step 5 IS the system map UI)
• aide-typescript-strict-pass — for the zod-strict contract pattern
• aide-credo-guardrail — the credo copy that lands in step 2
• aide-master-roadmap law #2 (No-Phone-Home, offline-first) — the doctrine that step 2 enforces

Repo primitives this skill depends on:

• common/contracts/*.ts (zod-strict pattern)
• node/src/services/*.mjs (service factory pattern, see worktree.mjs for the canonical shape)
• node/src/routes/*.ts (route registry, see routesForWorktree for the canonical shape)
• node/src/openapi.ts (buildRoutes, single-source-of-truth hoist pattern)
• browser/src/cockpit/*.tsx (the cockpit component tree)
• scripts/egress-audit.mjs (the CI gate that catches browser→provider leaks)

Pitfalls (Windows + this repo)

• DPAPI payload passing: pass keys via env var AIDE_DPAPI_IN, never as a positional arg to powershell.exe (the trailing-args-join bug from aide-provider-connect §0)
• Status cache: the 60s TTL on GET /api/byok/status means the walkthrough sees a stale "connected" right after a key delete; the UI must show the cache timestamp
• The walkthrough must NEVER block on a probe: every network call has a 5s timeout via AbortController; if the probe fails, default to offline and let the user retry
• The credo copy is operator canon (audit line 325, aide-credo-guardrail); do not paraphrase, do not "improve" it, ship it verbatim
• The walkthrough is resumable (state persists); test that closing the tab mid-step and reopening lands on the same step
• The walkthrough must NOT auto-play on every cold start (descent cinematic does); only show when walkthroughComplete != true
• prefers-reduced-motion users skip the descent AND the walkthrough animation; show the steps instantly with no transition (per aide-p2-descent-intro tier C)

Gates (verification battery)

1. node --check browser/src/cockpit/walkthrough/*.tsx exit 0
2. node --test tests/arch/onboarding-walkthrough-doctrine.test.ts PASS — asserts: (a) this skill file has 5 step names in the spec; (b) the 4 zod schemas in common/contracts/onboarding.ts exist and are strict; (c) the 4 routes exist; (d) the BYOK opt-in step explicitly cites Cline "bring your own provider key" + Claude Code "third-party providers"; (e) the privacy step quotes the credo verbatim
3. node --test tests/arch/walkthrough-state-shape.test.ts PASS — asserts: the state machine handles forward, back, skip, complete; persisted state is loadable after process restart; corruption triggers graceful reset
4. npm run contracts is a no-op (openapi.json regenerates byte-identical, per aide-production-readiness-plan Phase 1 gate 1)
5. scripts/egress-audit.mjs PASS — no provider host in browser/dist (only in daemon code, per aide-provider-connect §4)
6. Manual: cold-start the daemon, observe the walkthrough play, complete all 5 steps, see the system map, end on the cockpit home page, restart the daemon, observe the walkthrough does NOT replay

Rollout (2 PRs)

PR A — Contracts + service + routes + tests (smaller, runtime-only)

• common/contracts/onboarding.ts (zod schemas)
• node/src/services/onboarding.mjs (state machine, atomic persistence)
• node/src/routes/onboarding.ts (4 routes)
• node/src/openapi.ts (register the routes)
• common/openapi.json (regenerate)
• 2 arch tests (doctrine parse + state shape)
• Commit: feat(onboarding): walkthrough state machine + 4 routes (PR A of aide-onboarding-walkthrough)

PR B — Cockpit UI + manual smoke

• browser/src/cockpit/walkthrough/ (the 5 step components)
• Wire the walkthrough into the cockpit root: if walkthroughComplete != true AND descent has played, route to walkthrough
• Add the system-map panel as a permanent cockpit top-level item
• Manual smoke on a real workspace
• Commit: feat(cockpit): onboarding walkthrough + system map panel (PR B of aide-onboarding-walkthrough)

References

• aide-ide-research (R1+R2: load before any AIDE feature, 3 sources per claim)
• aide-vscode-parity-roadmap (per-phase skill spec)
• aide-cloud-handoff (H1+H2, BYOK + cloud handoff shipped)
• aide-provider-connect (arch Phase 7, 6 verified hosts)
• aide-p6-desktop-control (Stage A bounded grants)
• aide-p2-descent-intro (the cinematic before the walkthrough)
• aide-p2-onboarding (P2 phase, gate 4)
• aide-system-map (sister skill, the walkthrough step 5)
• aide-credo-guardrail (the credo copy in step 2)
• aide-master-roadmap (law #2, No-Phone-Home)
• aide-typescript-strict-pass (zod-strict pattern)
• docs/AUDIT-2026-08-31.md PART 3 (4-week plan) + PART 5 gate 4 (line 149)
• E:/pip_temp/competitor-onboarding-byok.md (the 7-source gap analysis that motivated this skill)
• 7 vendor sources (all primary, all verified 2026-09-01):
  • Cursor — https://docs.cursor.com/welcome
  • VS Code Copilot — https://code.visualstudio.com/docs/copilot/chat/copilot-chat
  • Cline — https://docs.cline.bot/getting-started/installing-cline
  • Windsurf / Devin Desktop — https://docs.codeium.com/windsurf/getting-started
  • Claude Code — https://docs.anthropic.com/en/docs/claude-code/overview
  • Aider — https://aider.chat/docs/install.html
  • Continue — https://docs.continue.dev/getting-started/overview