AltimateAI / AltimateAI/altimate-code

[Feature] First-run onboarding wizard with guided setup

Aperta
#59 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
enhancement onboarding priority:high ux
Lingua principale
TypeScript
Stelle
811
Fork
134
Merge medio
3g 2h
PR unite (30g)
50

Descrizione

## Problem

New users with no configuration get dropped into a raw prompt with no guidance. There's no detection of missing API keys, no guided warehouse setup, and `/discover` isn't surfaced automatically. This creates high friction for adoption — especially for less technical users (team leads, analysts).

**Current behavior:**
- Launch `altimate` with no config → empty prompt, no guidance
- No API key configured → generic "no providers found" error
- `/discover` exists but users must know about it

**Evidence from testing:** Running `altimate run --model nonexistent/model "hello"` shows a raw `ProviderModelNotFoundError` with file paths and line numbers instead of a friendly message.

## Proposed Solution

Implement a multi-pathway onboarding wizard that detects first-run state and guides users through setup.

### Design (informed by industry research)

**Step 1: Detect first-run state**
- Check if any provider is configured (API key or auth token)
- Check if any warehouse connections exist
- Check if a dbt project is detected nearby

**Step 2: Show welcome screen when no config exists**
```
┌─ Welcome to Altimate Code ──────────────────────┐
│ │
│ Let's get you set up: │
│ │
│ 1. Quick Start (recommended) │
│ → Configure AI provider │
│ │
│ 2. Connect Warehouse │
│ → Set up Snowflake, BigQuery, Postgres, etc. │
│ │
│ 3. Discover Existing Setup │
│ → Auto-detect dbt projects & connections │
│ │
│ 4. Skip (I'll configure later) │
│ → Jump straight to the prompt │
│ │
└──────────────────────────────────────────────────┘
```

**Step 3: After provider setup, validate immediately**
```
✓ Connected to Anthropic (claude-sonnet-4-6)
✓ 3 DuckDB connections found
✗ DuckDB driver not installed — install now? [Y/n]
```

### Industry patterns to follow
- **Goose (block/goose):** Multi-pathway welcome screen with Quick Setup, OAuth, OpenRouter, manual config options
- **Aider:** Zero-config fallback — auto-offers OpenRouter if no keys found, selects best model
- **GitHub CLI:** Step-by-step narrowing with OAuth Device Flow
- **dbt init:** Interactive prompts for project name → adapter → credentials
- **Cursor:** 14-day free trial, VS Code import, no payment upfront

### Key files to modify
- `packages/altimate-code/src/cli/cmd/tui/app.tsx` — Root TUI application
- `packages/altimate-code/src/cli/cmd/tui/routes/home.tsx` — Home screen (add onboarding detection)
- `packages/altimate-code/src/provider/provider.ts` — Provider detection and error handling
- `packages/altimate-code/src/config/` — Config loading and validation

### Acceptance criteria
- [ ] First launch with no config shows a guided setup flow
- [ ] Missing API key triggers provider setup, not a crash
- [ ] `/discover` is offered as part of onboarding, not a hidden command
- [ ] Each step validates immediately (connection test, model test)
- [ ] `--skip-setup` flag available for CI/automation
- [ ] Onboarding works in both TUI and `altimate run` modes

Guida per i contributori

Apri la guida per i contributori

Valutazione

Questa issue non è ancora stata valutata.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.