tui: dependency installer / first-run wizard

claude-desktop commented

2026-04-14 20:13:52 +00:00

Collaborator

User story

As a first-time user starting loom-tui, I want a guided check that the required dependencies (Forge backend reachable, plugins discovered, picker initialised) are present, with a friendly install hint when they're not, so that I'm not staring at empty screens with no idea what to do.

Background

GTK has a multi-step onboarding flow at crates/loom-gtk/src/components/onboarding/ (welcome, backend, plugins, presets, downloads) plus crates/loom-gtk/src/dep_install.rs. The TUI just bootstraps and silently degrades if anything is missing. Users hit walls without explanation.

Acceptance criteria

First-run detection

On startup, check whether ~/.config/loom/settings.toml exists; absence triggers the wizard
Wizard is OverlayKind::Onboarding(OnboardingStep), blocks all other input until completed or dismissed (Esc skips with a notification "you can re-run via Settings")

Steps

Welcome — short banner, Enter to begin
Backend — text input for generation_backend URL (default http://127.0.0.1:7860), Enter runs bridge.health_check() and surfaces the result
Plugins — list discovered plugins; the user toggles which to enable; Enter saves
Done — summary of what was set, Enter saves settings and dismisses

Mid-app health hint

When the active backend health check fails, show a persistent banner above the status bar with a "(s)ettings" hint
Single-key hint dismissible with b

Re-run

Settings screen gets a "Re-run onboarding" entry that pushes the wizard

Tests

Unit: missing settings.toml triggers the wizard
Integration: completing all steps writes a valid settings file

Out of scope

Auto-installing the Forge backend (pointer to install instructions only)
Plugin downloads (handled by the model browser)

References

crates/loom-gtk/src/components/onboarding/ (GTK reference)
crates/loom-gtk/src/dep_install.rs
crates/loom-tui/src/main.rs (bootstrap_core)

## User story As a first-time user starting loom-tui, I want a guided check that the required dependencies (Forge backend reachable, plugins discovered, picker initialised) are present, with a friendly install hint when they're not, so that I'm not staring at empty screens with no idea what to do. ## Background GTK has a multi-step onboarding flow at `crates/loom-gtk/src/components/onboarding/` (welcome, backend, plugins, presets, downloads) plus `crates/loom-gtk/src/dep_install.rs`. The TUI just bootstraps and silently degrades if anything is missing. Users hit walls without explanation. ## Acceptance criteria ### First-run detection - [ ] On startup, check whether `~/.config/loom/settings.toml` exists; absence triggers the wizard - [ ] Wizard is `OverlayKind::Onboarding(OnboardingStep)`, blocks all other input until completed or dismissed (`Esc` skips with a notification "you can re-run via Settings") ### Steps 1. [ ] **Welcome** — short banner, `Enter` to begin 2. [ ] **Backend** — text input for `generation_backend` URL (default `http://127.0.0.1:7860`), `Enter` runs `bridge.health_check()` and surfaces the result 3. [ ] **Plugins** — list discovered plugins; the user toggles which to enable; `Enter` saves 4. [ ] **Done** — summary of what was set, `Enter` saves settings and dismisses ### Mid-app health hint - [ ] When the active backend health check fails, show a persistent banner above the status bar with a "(s)ettings" hint - [ ] Single-key hint dismissible with `b` ### Re-run - [ ] Settings screen gets a "Re-run onboarding" entry that pushes the wizard ### Tests - [ ] Unit: missing settings.toml triggers the wizard - [ ] Integration: completing all steps writes a valid settings file ## Out of scope - Auto-installing the Forge backend (pointer to install instructions only) - Plugin downloads (handled by the model browser) ## References - `crates/loom-gtk/src/components/onboarding/` (GTK reference) - `crates/loom-gtk/src/dep_install.rs` - `crates/loom-tui/src/main.rs` (bootstrap_core)

claude-desktop added this to the loom-tui v0.1.0 milestone

2026-04-14 20:13:52 +00:00

claude-desktop added the

type:user-story

area:infra

labels

2026-04-14 20:13:52 +00:00

claude-desktop referenced this issue

2026-04-14 20:14:47 +00:00

tui: tracking — loom-tui v0.1.0 roadmap & implementation order #47