# Task D.7.6 Dashboard Setup Wizard UI

Date: 2026-07-03
Status: implemented

## Scope Delivered

Added dashboard-native setup wizard route:

- `GET /dashboard/administration/setup`
- Server-side page access restricted to `super_admin`
- Admin navigation item for `Setup Wizard`

Added setup UI orchestration:

- `src/features/setup/components/setup-wizard.tsx`
- `src/app/dashboard/administration/setup/page.tsx`

Extended setup API client surface:

- `src/features/setup/api/types.ts`
- `src/features/setup/api/service.ts`
- `src/features/setup/api/queries.ts`
- `src/features/setup/api/use-csv-commit.ts`
- `src/features/setup/api/use-setup-verification.ts`

## Behavior

- Step 1 calls setup readiness and displays overall status, PASS / WARNING / FAIL counts, grouped checks, suggested fixes, loading, error, and permission states.
- Step 2 calls template metadata and displays registered setup templates from the existing setup template API.
- Step 3 accepts one or more CSV files and does not upload them until the user clicks preview.
- Step 4 calls CSV preview, stores `previewHash` in client state only, displays per-file summaries, row/error/warning counts, and grouped safe error messages.
- Step 5 calls CSV commit with the latest `previewHash`.
- Commit is disabled when preview has `FAIL`.
- Commit requires warning acknowledgement when preview has `WARNING`.
- File changes after preview clear commit eligibility and require re-preview, using file name + size + lastModified fingerprint.
- Step 6 calls setup verification and displays grouped checks plus summary counts.
- Step 7 summarizes readiness, preview, commit, and verification results for the current browser session.

## Security And API Notes

- Setup page uses `auth()` and `PageContainer` access fallback for non-super-admin users.
- Existing setup APIs remain the enforcement boundary and still require `super_admin`.
- Upload requests use `FormData` directly so browser-managed multipart boundaries are preserved.
- UI reads safe API error messages and does not render raw stack traces.
- CSV files are uploaded only to the preview and commit endpoints.
- The wizard does not log CSV data.

## Out Of Scope Preserved

- No setup state persistence.
- No seed manifest persistence.
- No destructive reset or reseed behavior.
- No seed execution.
- No database migrations.
- No new CRM behavior.
- No file download or ZIP template generation.

Persistent setup runs and resume behavior remain deferred to D.7.8.

## Validation

- `npm run typecheck -- --pretty false` passed.
- `npx oxlint src/features/setup/api/types.ts src/features/setup/api/service.ts src/features/setup/api/queries.ts src/features/setup/api/use-csv-commit.ts src/features/setup/api/use-setup-verification.ts src/features/setup/components/setup-wizard.tsx src/app/dashboard/administration/setup/page.tsx src/config/nav-config.ts` passed.
- Existing dev server was already running at `http://localhost:3000`.
- `curl.exe -I -L --max-time 20 http://localhost:3000/dashboard/administration/setup` returned `200 OK`.

## Residual Notes

- `plans/task-d.7.6.md` was already untracked during implementation and was not modified as part of this delivery.
- The wizard is intentionally session-only until the D.7.8 setup-state persistence slice.