fix(setup): quick wizard — require key on first run, drop SOUL/knowledge/tools steps

[mabry1985]

Why

Two problems, found live on the Deck during first real bring-up:

1. The wizard let you "finish" with a blank API key. The key field's placeholder said "Leave blank to preserve current key" — wrong on a first run (there's nothing to preserve). So Finish "succeeded", wrote no key, setup_complete stayed false, and the modal — gated on setup_complete === false — could never close. An inescapable loop with no key configured.
2. Too much for a BYO-key setup. Editing protoPen's SOUL and configuring the knowledge DB don't belong in setup.

What

• Require the API key on first run. Finish is disabled until a key is entered, and the placeholder reads "Enter your API key". Only a reconfigure (key already set) may leave it blank to keep the existing one.
• Genuine quick setup: Welcome → Identity → Model → Finish. Dropped the SOUL/persona editor, the knowledge/workspace step, and the middleware-toggle step. All keep their server-side defaults — run_setup only overrides what's sent, so protoPen's SOUL and knowledge config are untouched.

Testing

Deployed live to the Deck and validated: clean tsc + vite build, wizard renders the 4 steps, Finish stays disabled until a key is entered, and completing it flips setup_complete true → modal closes → console.

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

• Improvements
  • Streamlined the setup wizard with a simplified flow focusing on essential configuration steps.
  • Enhanced API key handling with conditional requirements based on your setup status.
  • Improved validation and error messaging during the setup process.

[protoquinn]

👀 Quinn is reviewing — verdict (PASS / WARN / FAIL) + findings to follow.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: ebf1b8ff-8a68-4f12-b6f2-719abce5e017

📥 Commits

Reviewing files that changed from the base of the PR and between f646760 and 0296a2b.

📒 Files selected for processing (1)

• apps/web/src/setup/SetupWizard.tsx

---

Walkthrough

SetupWizard.tsx is refactored from a multi-step full-setup flow (persona, tools, workspace, SOUL, middleware, knowledge) into a four-step quick-setup flow: welcome, identity, model, and finish. The WizardState and hydration are narrowed to identity and model-gateway fields; finishSetup sends a minimal payload; a needsKey flag gates API key requirements; and all step UI content is updated to match the reduced scope.

Changes

Quick Setup Wizard Refactor

Layer / File(s)	Summary
Step union, WizardState, and hydration apps/web/src/setup/SetupWizard.tsx	Step type is narrowed to welcome | identity | model | finish; WizardState is reduced to identity and model-gateway fields; defaultState and hydrateState are rewritten to match; needsKey state is added and set from status.setup_complete in the load effect.
Validation logic and finishSetup API call apps/web/src/setup/SetupWizard.tsx	keyOk is derived from needsKey and state.apiKey; canGoNext on the model step requires apiBase, modelName, and keyOk; finishSetup guards on needsKey, calls api.finishSetup with a minimal model + identity payload, and surfaces response.message on non-ok responses.
Step UI rendering updates apps/web/src/setup/SetupWizard.tsx	Welcome summary removes SOUL/workspace/subagents indicators; model step API key field is dynamically marked required with conditional placeholder text; finish step drops workspace/knowledge/researcher status rows; Finish button gains disabled={busy || !keyOk}.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/setup-wizard-quick

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[protoquinn]

QA Audit — PR #276 | fix(setup): quick wizard — require key on first run, drop SOUL/knowledge/tools steps

VERDICT: WARN (non-terminal CI — comment only; re-review once checks settle)

---

CI Status

• Verify workspace config: queued
• Lint: queued

Diff Review

• Single-file change to apps/web/src/setup/SetupWizard.tsx (~328 lines). Reduces wizard from 7 steps to 4 (welcome → identity → model → finish) and enforces API key on first run.
• Key enforcement logic is sound: needsKey derived from !status.setup_complete, keyOk gates both canGoNext (model step) and finishSetup — two-layer guard against the blank-key loop.
• All removed state fields, imports, functions (setMiddleware, loadPreset), and props (projectPath, onProjectPathChange) are cleaned up consistently. No dangling references.
• run_setup payload now sends empty string for soul and omits middleware/subagents/knowledge config — relies on server-side defaults per PR description.

Observations

• LOW: Diff truncated at 200/328 lines — the JSX render block for the simplified steps and tail of finishSetup not reviewable. No red flags in the portion visible.
• LOW: Clawpatch structural review unavailable — protoLabsAI/protoPen not in project registry.
• LOW: projectPath/onProjectPathChange props removed from signature but no caller changes in diff. Author reports clean tsc + vite build; CI will confirm.

— Quinn, QA Engineer

[protoquinn]

Submitted COMMENT review on #276.

[protoquinn]

CI terminal-green, no blockers on prior review — auto-approving on green (#748).