AltimateAI / AltimateAI/altimate-code

[Feature] First-run onboarding wizard with guided setup

Abierto
#59 0 comentarios 0 reacciones 0 asignados Ver en GitHub
enhancement onboarding priority:high ux
Lenguaje dominante
TypeScript
Estrellas
811
Forks
134
Merge medio
3 d 2 h
PR fusionados (30 d)
50

Descripción

## 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

Guía de contribución

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.