Skip to main content

​
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
  • Add failing allowlist, schema, and web type-guard tests for setup.
  • Add setup defaults, safe/readable allowlist entries, schema validation, web types, and isGuildConfig() support.
  • 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
  • Add provider filtering tests for configured provider and guild tier behavior.
  • Add section patch-builder tests for enabled sections, disabled sections, AI unavailable, and skipped setup metadata.
  • Implement getAvailableProviderModelOptions().
  • Implement SETUP_SECTIONS, buildSetupSectionPatches(), buildSetupSkipPatches(), and validateSetupStep().
  • 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
  • Add route/title tests for /dashboard/setup and Setup.
  • 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.
  • 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
  • Use the shared dashboard ServerSelector on the setup start page and broadcast server switches through the shared guild-selection bus before the wizard starts.
  • Lock the selected server inside setup step pages so channel and role selectors stay scoped to the route guildId.
  • Use the shared dashboard AiModelSelect and fan the selected model out to AI chat, triage, content safety, and TL;DR config.
  • Split setup into route-backed step pages under /dashboard/setup/{step} so each section can grow without being cramped into one in-memory panel.
  • Save via fetch('/api/guilds/${guildId}/config', { method: 'PUT', body: JSON.stringify(patches) }), refetch config on success, and show Open dashboard.
  • 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
  • Add a welcome redirect test for installed selectable guilds going to /dashboard/setup?guildId=<id>.
  • Add a sidebar test for the Settings Setup wizard link to /dashboard/setup.
  • Implement the redirect and sidebar entry.
  • Verify the focused tests pass.

​
Task 5: Docs and Final Verification

Files:
  • Modify: docs/getting-started.mdx
  • Review: AGENTS.md
  • Review: DESIGN.md
  • Update docs/getting-started.mdx to describe the skippable section-based setup wizard and later Settings Setup wizard entry.
  • 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.
  • Run focused backend and web tests.
  • Run broad web typecheck/lint, root lint, and provider catalog sync check.
  • Browser-check /dashboard/setup and /dashboard/setup/welcome?guildId=... at desktop and mobile sizes.
Last modified on May 27, 2026