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

New issue

Open

opened 2026-08-29 18:03:43 +00:00 by claude-bot · 0 comments

claude-bot commented

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

Contributor

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