rbrooks/Quest-Board

Watch

Fork 0

[Frontend] First-run setup wizard so nothing gets forgotten on a fresh install #439

New issue

Closed

opened 2026-08-29 18:03:43 +00:00 by claude-bot · 1 comment

claude-bot commented

2026-08-29 18:03:43 +00:00

Collaborator

Backlog — a direction to consider, not scoped work.

What

A guided first-run flow that walks a new operator through everything an instance needs before it can be trusted, instead of leaving each setting to be discovered separately in Admin.

Why

Configuration that is technically available but never visited behaves exactly like configuration that does not exist. Several real incidents came from a setting nobody knew to set:

Scheduled backups were disabled on production and had never once run. backup_logs was empty; every dump that existed had been taken by hand. Found while working #414.
The LLM context window was never set, so it silently used a 32,768 fallback against a server offering 65,536 per slot. That left a ~7% margin before a long session tipped into a materially less-tested chunking path.
Audio retention defaulted to deleting recordings during processing (#427). It took losing a real session to notice.
A plaintext credential sat at rest for months (#428), because nothing ever prompted a rotation.

Each was a default nobody chose. A wizard turns "you should have found this" into "you were asked".

Rough shape

Steps a fresh instance genuinely cannot do without:

Admin account — confirm who holds it (see #436: identity is not email)
Backups — destination, schedule, retention, and off-host if any; then take one and verify it restores rather than trusting the exit code (#429)
SECRET_KEY custody — state plainly that it is not in the database and a dump without it cannot recover encrypted settings (#430)
Retention posture — audio and transcript, with the consequences spelled out (#427)
AI endpoints — Whisper and LLM, including context window, with a live connectivity test
Discord — bot token, guild, channel, and the bot API key
A completion summary listing anything skipped, so "not configured" is a visible state rather than an absence

Worth deciding when this is picked up

Dismissible or blocking? Blocking is safer for a hosted product and hostile for a self-hoster kicking the tyres. A persistent "setup incomplete" banner listing what remains is probably the honest middle.
Does it re-run? Useful after a restore onto a new host, where several of these are exactly what needs redoing.
Overlap with #437 (admins seeing every campaign) and with a general instance-health view — a wizard and a health check are the same information at different moments, and building them twice would be a mistake.

#427, #428, #429, #430, #436, #437, #414 — each is a case where the default or the absence of a prompt was the actual defect.

**Backlog — a direction to consider, not scoped work.** ## What A guided first-run flow that walks a new operator through everything an instance needs before it can be trusted, instead of leaving each setting to be discovered separately in Admin. ## Why Configuration that is technically available but never visited behaves exactly like configuration that does not exist. Several real incidents came from a setting nobody knew to set: - **Scheduled backups were disabled on production and had never once run.** `backup_logs` was empty; every dump that existed had been taken by hand. Found while working #414. - **The LLM context window was never set**, so it silently used a 32,768 fallback against a server offering 65,536 per slot. That left a ~7% margin before a long session tipped into a materially less-tested chunking path. - **Audio retention defaulted to deleting recordings during processing** (#427). It took losing a real session to notice. - **A plaintext credential sat at rest for months** (#428), because nothing ever prompted a rotation. Each was a default nobody chose. A wizard turns "you should have found this" into "you were asked". ## Rough shape Steps a fresh instance genuinely cannot do without: 1. **Admin account** — confirm who holds it (see #436: identity is not email) 2. **Backups** — destination, schedule, retention, and *off-host* if any; then take one and verify it restores rather than trusting the exit code (#429) 3. **`SECRET_KEY` custody** — state plainly that it is not in the database and a dump without it cannot recover encrypted settings (#430) 4. **Retention posture** — audio and transcript, with the consequences spelled out (#427) 5. **AI endpoints** — Whisper and LLM, including context window, with a live connectivity test 6. **Discord** — bot token, guild, channel, and the bot API key 7. **A completion summary** listing anything skipped, so "not configured" is a visible state rather than an absence ## Worth deciding when this is picked up - **Dismissible or blocking?** Blocking is safer for a hosted product and hostile for a self-hoster kicking the tyres. A persistent "setup incomplete" banner listing what remains is probably the honest middle. - **Does it re-run?** Useful after a restore onto a new host, where several of these are exactly what needs redoing. - **Overlap with #437** (admins seeing every campaign) and with a general instance-health view — a wizard and a health check are the same information at different moments, and building them twice would be a mistake. ## Related #427, #428, #429, #430, #436, #437, #414 — each is a case where the default or the absence of a prompt was the actual defect.

claude-bot added this to the Backlog - Speculative / Long-Term milestone

2026-08-29 18:04:02 +00:00

claude-bot referenced this issue

2026-08-29 18:18:19 +00:00

[Review] Document every feature, and validate each doc against actual behaviour #442

claude-bot referenced this issue

2026-09-15 18:21:00 +00:00

[UX] Redesign coverage: where every shipped and planned feature lives in Design A #656

claude-bot referenced this issue

2026-09-22 14:35:21 +00:00

Build lane 2: the public pages (PUB-1 to PUB-12) #728

claude-bot referenced this issue

2026-09-22 16:11:50 +00:00

[Backend] A backup shipped off-host cannot be read back: its local path is overwritten by the rclone spec #753

claude-bot referenced this issue

2026-09-22 16:34:48 +00:00

Lane 2: first-run setup's own state, and a backup read-back (#728) #754

claude-bot referenced this issue

2026-10-01 19:01:37 +00:00

Setup's AI step doesn't ask for the LLM context window #1001

claude-bot commented

2026-10-01 19:01:49 +00:00

Author

Collaborator

Closing: the first-run setup is built (lane 2, #728, with lane 9's changes), checked against main on 1 Oct.

/setup walks an administrator through who they are, backups, the SECRET_KEY, retention, the Whisper and LLM endpoints with a live test, and Discord, then a summary of what was skipped. Progress is kept on the server.

Decisions recorded along the way:

D70: an unfinished setup reminds and never blocks; what was skipped waits as a quiet list at the top of Admin, each with a link (D142).
D108: setup closes once finished; /setup then goes to Admin.
D87: the backup step reads the archive back (pg_restore --list) and says so; it does not rehearse a restore.
D88: the key step shows no key material and checks the running key can read what is stored.
D139: no Discord token field.

Not built: the AI step doesn't ask for the LLM context window, which this issue named. Filed as #1001.

Closing: the first-run setup is built (lane 2, #728, with lane 9's changes), checked against main on 1 Oct. `/setup` walks an administrator through who they are, backups, the SECRET_KEY, retention, the Whisper and LLM endpoints with a live test, and Discord, then a summary of what was skipped. Progress is kept on the server. Decisions recorded along the way: - D70: an unfinished setup reminds and never blocks; what was skipped waits as a quiet list at the top of Admin, each with a link (D142). - D108: setup closes once finished; `/setup` then goes to Admin. - D87: the backup step reads the archive back (`pg_restore --list`) and says so; it does not rehearse a restore. - D88: the key step shows no key material and checks the running key can read what is stored. - D139: no Discord token field. Not built: the AI step doesn't ask for the LLM context window, which this issue named. Filed as #1001.

claude-bot closed this issue

2026-10-01 19:02:14 +00:00

claude-bot referenced this issue

2026-10-01 23:11:43 +00:00

The bell reaches older notifications, and setup's AI step asks for the context window (#1000, #1001) #1018