​

Setup Wizard Design

​

Summary

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

​

Goals

• Give new admins a polished first-run setup after the Discord invite flow returns them to the dashboard.
• Let admins configure each setup area directly instead of choosing a broad server preset.
• Save setup state in guild config so completion follows the server across browsers and admins.
• Reuse the existing config fetch/save path instead of adding a parallel settings API.
• Always include AI provider/model selection while allowing completion if no provider is available.
• Keep the wizard accessible after first run from dashboard chrome.

​

Non-Goals

• Do not require setup completion before the dashboard opens.
• Do not add provider secret entry to this wizard.
• Do not replace the existing full settings workspace.
• Do not add a separate database table for setup state.

​

Entry Points

​

First Run

​

Later Access

• Settings sidebar action named Setup wizard linking to /dashboard/setup.

​

Config Model

interface SetupConfig {
  completed: boolean;
  completedAt: string | null;
  presetId: 'community' | 'support' | 'creator' | 'locked-down' | null;
  skippedAt: string | null;
  updatedAt: string | null;
}

• Add setup defaults to config.json.
• Add setup to SAFE_CONFIG_KEYS and READABLE_CONFIG_KEYS.
• Add validation schema for all fields.
• Add setup to BotConfig, ConfigSection, and isGuildConfig().
• Ensure masked config reads return setup state.

• setup.completed = true only after all required wizard fields validate and the review save succeeds.
• setup.skippedAt records when the user chooses Set up later.
• Skipping must not set completed or completedAt.
• A later successful completion clears skippedAt.

​

Section Patch Builder

• Welcome enabled: set welcome.enabled, welcome.channelId, welcome.rulesChannel, welcome message, and rules message.
• Welcome disabled: set welcome.enabled = false.
• Content safety enabled: set aiAutoMod.enabled, one default threshold across all safety categories, per-category default safety actions, moderation log routing, spam checks, link filtering, and auditLog.enabled.
• Content safety disabled: disable AI auto-mod, spam, link filtering, moderation logs, and audit log defaults written by setup.
• Protected roles enabled: write owner/admin/mod protected-role behavior and selected role IDs.
• Protected roles disabled: clear setup-managed protected-role defaults.
• Warning rules enabled: write warning expiry and low/medium/high severity points. Setup clears legacy escalation thresholds instead of asking for them.
• Warning rules disabled: clear setup-managed warning escalation behavior.
• Tickets enabled: set tickets.enabled, tickets.panelChannel, tickets.mode, tickets.category, tickets.supportRoles, and legacy tickets.supportRole.
• Tickets disabled: disable tickets and clear support role routing.
• Reputation enabled: enable engagement, reputation, XP, XP min/max, and XP cooldown.
• Reputation disabled: disable engagement, reputation, and XP.
• Starboard enabled: set starboard.enabled, starboard.channelId, starboard.threshold, starboard.emoji, and starboard.selfStarAllowed.
• Starboard disabled: disable starboard.
• Commands enabled: write the command prefix and whether custom prefixes are enabled.
• Commands disabled: disable setup-managed custom prefix behavior.
• TL;DR enabled: write tldr.enabled, analysis window (tldr.defaultMessages), max message count, cooldown, and model.
• TL;DR disabled: disable TL;DR.
• Roles always write the dashboard permission model.
• AI writes the selected provider:model to AI chat defaults, triage classify/respond models, TL;DR, and AI auto-mod/content-safety routing when a configured provider/model exists; otherwise AI-backed setup features are disabled.
• Completion writes setup.completed, setup.completedAt, setup.presetId = null, setup.skippedAt = null, and setup.updatedAt.

​

Wizard Steps

​

Welcome

​

Content safety

​

Protected roles

​

Warning rules

​

Tickets

​

Reputation

​

Starboard

​

Commands

​

TL;DR

​

Roles

​

AI

• Fetch configured providers via the existing configured providers API.
• Filter models by configured provider and guild tier using the existing provider catalog helpers.
• Default to the first available model.
• If no configured provider/model exists, show an unavailable state, disable AI-backed features, and allow completion.
• Provider API failures behave like no configured provider: AI is unavailable and setup can continue with AI off.

​

Review

• Feature sections enabled or skipped.
• Channels and roles selected.
• AI provider/model selected or AI unavailable state.
• Setup completion metadata.

​

UX Rules

• Use the existing dashboard visual system: Button, ChannelSelector, RoleSelector, ServerSelector, AiModelSelect, dashboard cards, and Tailwind tokens.
• Keep it skippable. Set up later saves skipped metadata but does not mark setup complete.
• Do not hide the AI step even when no providers are configured.
• Keep section copy short and operational.
• Validate on next/save, not on every field focus.
• Allow jumping to any step from the sidebar at any time.
• Keep the mobile layout usable with the footer controls visible and no overlapping text.

​

Tests

• Config allowlist and validation for setup.
• Web config type guard for setup.
• Provider/model filtering by configured provider and guild tier.
• Section-to-patch mapping for enabled and disabled sections.
• Step validation only for enabled sections.
• Setup start page uses the shared dashboard ServerSelector.
• Setup step pages lock the selected server and do not expose workspace switching.
• Step rail allows jumping to any step.
• AI selection uses the shared dashboard model selector and fans out to AI chat, triage, content safety, and TL;DR model routing.
• Wizard path with AI unavailable still reaches review and saves.
• Skip path does not mark setup complete.
• Welcome invite callback routes installed guilds to setup.
• Settings exposes Setup wizard without adding a persistent dashboard setup prompt.