> ## Documentation Index
> Fetch the complete documentation index at: https://docs.volvox.bot/llms.txt
> Use this file to discover all available pages before exploring further.

# 2026 05 21 setup wizard

# Setup Wizard Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development
> (recommended) or superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Build a skippable `/dashboard/setup` wizard that lets admins configure each first-run
section directly, always includes AI provider/model selection, and stores setup completion in guild
config.

**Architecture:** Add a guild-scoped `setup` config section, a pure web section/patch builder, and
a dashboard setup route that reuses `ConfigProvider` and the existing guild config `PUT` endpoint.
The welcome server picker routes install callbacks into setup; the Settings sidebar exposes setup
as an optional workflow that can be rerun later.

**Tech Stack:** Node 22, pnpm 11, Next.js 16 App Router, React 19, TypeScript, Tailwind 4, Vitest
4, Express config API, existing dashboard UI primitives.

***

## Task 1: Setup Config Section

**Files:**

* Modify: `config.json`

* Modify: `src/api/utils/configAllowlist.js`

* Modify: `src/api/utils/configValidation.js`

* Modify: `web/src/types/config.ts`

* Modify: `web/src/components/dashboard/config-editor-utils.ts`

* Test: `tests/api/utils/configAllowlist.test.js`

* Test: `tests/api/utils/configValidation.test.js`

* Test: `web/tests/components/dashboard/config-editor-utils.test.ts`

* [x] Add failing allowlist, schema, and web type-guard tests for `setup`.

* [x] Add `setup` defaults, safe/readable allowlist entries, schema validation, web types, and
  `isGuildConfig()` support.

* [x] Verify the focused config tests pass.

## Task 2: Provider Option Helper and Section Patch Builder

**Files:**

* Modify: `web/src/lib/provider-model-options.ts`

* Create: `web/src/lib/setup-sections.ts`

* Test: `web/tests/lib/provider-model-options.test.ts`

* Test: `web/tests/lib/setup-sections.test.ts`

* [x] Add provider filtering tests for configured provider and guild tier behavior.

* [x] Add section patch-builder tests for enabled sections, disabled sections, AI unavailable, and
  skipped setup metadata.

* [x] Implement `getAvailableProviderModelOptions()`.

* [x] Implement `SETUP_SECTIONS`, `buildSetupSectionPatches()`, `buildSetupSkipPatches()`, and
  `validateSetupStep()`.

* [x] Verify the focused helper tests pass.

## Task 3: Setup Wizard Component and Route

**Files:**

* Create: `web/src/app/dashboard/setup/page.tsx`

* Create: `web/src/components/dashboard/setup-wizard.tsx`

* Modify: `web/src/lib/page-titles.ts`

* Test: `web/tests/app/dashboard/setup/page.test.tsx`

* Test: `web/tests/components/dashboard/setup-wizard.test.tsx`

* Test: `web/tests/lib/page-titles.test.ts`

* [x] Add route/title tests for `/dashboard/setup` and `Setup`.

* [x] Add component tests proving the wizard starts at Welcome, does not show server presets, blocks
  enabled required fields, allows disabled/unavailable AI paths, and saves or skips correctly.

* [x] Implement the free-jump section stepper:
  1. Welcome
  2. Content safety
  3. Protected roles
  4. Warning rules
  5. Tickets
  6. Reputation
  7. Starboard
  8. Commands
  9. TL;DR
  10. Dashboard roles
  11. AI
  12. Review

* [x] Use the shared dashboard `ServerSelector` on the setup start page and broadcast server
  switches through the shared guild-selection bus before the wizard starts.

* [x] Lock the selected server inside setup step pages so channel and role selectors stay scoped to
  the route `guildId`.

* [x] Use the shared dashboard `AiModelSelect` and fan the selected model out to AI chat, triage,
  content safety, and TL;DR config.

* [x] Split setup into route-backed step pages under `/dashboard/setup/{step}` so each section can
  grow without being cramped into one in-memory panel.

* [x] Save via `fetch('/api/guilds/${guildId}/config', { method: 'PUT', body:
  JSON.stringify(patches) })`, refetch config on success, and show `Open dashboard`.

* [x] Verify the focused route/component tests pass.

## Task 4: Welcome Redirect and Sidebar Entry

**Files:**

* Modify: `web/src/components/dashboard/welcome-server-picker.tsx`

* Modify: `web/src/components/layout/sidebar.tsx`

* Test: `web/tests/components/dashboard/welcome-server-picker.test.tsx`

* Test: `web/tests/components/layout/sidebar.test.tsx`

* [x] Add a welcome redirect test for installed selectable guilds going to
  `/dashboard/setup?guildId=<id>`.

* [x] Add a sidebar test for the Settings `Setup wizard` link to `/dashboard/setup`.

* [x] Implement the redirect and sidebar entry.

* [x] Verify the focused tests pass.

## Task 5: Docs and Final Verification

**Files:**

* Modify: `docs/getting-started.mdx`

* Review: `AGENTS.md`

* Review: `DESIGN.md`

* [x] Update `docs/getting-started.mdx` to describe the skippable section-based setup wizard and
  later Settings `Setup wizard` entry.

* [x] Update `DESIGN.md`, `AGENTS.md`, and this implementation plan for the setup start page,
  locked step server, free-jump setup rail, and expanded setup sections.

* [x] Run focused backend and web tests.

* [x] Run broad web typecheck/lint, root lint, and provider catalog sync check.

* [x] Browser-check `/dashboard/setup` and `/dashboard/setup/welcome?guildId=...` at desktop and
  mobile sizes.