paladin-ai 0.4.2

# Paladin Onboarding Wizard

Interactive setup wizard to configure your Paladin environment quickly and correctly.

## Overview

The `paladin onboarding` command provides a step-by-step wizard that:
- Guides you through provider selection (OpenAI, Anthropic, DeepSeek)
- Securely collects and validates API keys
- Creates/updates your `.env` file with proper configuration
- Generates sample configuration files for quick start
- Provides next steps and helpful resources

## Quick Start

```bash
# Run the wizard
paladin onboarding

# Follow the interactive prompts
# ✓ Provider selection
# ✓ API key input (masked)
# ✓ Real-time validation
# ✓ Configuration file creation
# ✓ Sample generation
```

## Wizard Flow

### Step 1: Welcome Screen

```
╔══════════════════════════════════════════════════════════╗
║                                                          ║
║   Welcome to Paladin! 🛡️                                 ║
║                                                          ║
║   This wizard will help you set up your environment.    ║
║                                                          ║
╚══════════════════════════════════════════════════════════╝

What Paladin can do:
  • Run autonomous AI agents (Paladins)
  • Orchestrate multi-agent battalions
  • Execute complex workflows with memory
  • Integrate external tools via Arsenal
```

### Step 2: Provider Selection

Choose your LLM provider(s):

```
? Select your primary LLM provider:
  ❯ OpenAI (GPT-4, GPT-3.5)
    Anthropic (Claude 3)
    DeepSeek (DeepSeek V2)
```

**Supported Providers:**

| Provider | Models | Best For | API Key Format |
|----------|--------|----------|----------------|
| **OpenAI** | GPT-4, GPT-3.5-turbo | General purpose, function calling | `sk-...` |
| **Anthropic** | Claude 3 Opus/Sonnet/Haiku | Long context, analysis | `sk-ant-...` |
| **DeepSeek** | DeepSeek V2 | Cost-effective, code generation | `sk-...` |

### Step 3: API Key Input

Secure API key collection with masking:

```
? Enter your OpenAI API key:
  [****************************************]

✓ Validating API key...
✓ Connection successful!
  Available models: gpt-4, gpt-3.5-turbo
```

**Security Features:**
- ✅ Input is masked (not visible in terminal history)
- ✅ Keys are validated before saving
- ✅ Real API calls test connectivity
- ✅ Clear error messages if validation fails

### Step 4: API Key Validation

Real-time validation ensures your keys work:

```
Validating OpenAI API key...
  ✓ Authentication successful
  ✓ Models accessible: gpt-4, gpt-3.5-turbo
  ✓ Response time: 342ms

Configuration Status:
  ✓ OPENAI_API_KEY: Valid
  ⚠ ANTHROPIC_API_KEY: Not configured (optional)
  ⚠ DEEPSEEK_API_KEY: Not configured (optional)
```

**Validation Process:**
1. Calls provider's authentication endpoint
2. Lists available models
3. Measures response time
4. Reports any errors with suggestions

### Step 5: Environment File Creation

The wizard creates or updates your `.env` file:

```
? .env file already exists. How should we proceed?
  ❯ Merge (combine with existing, no duplicates)
    Overwrite (replace completely)
    Skip (keep existing file)
```

**Merge Strategy:**
- Preserves existing non-key configurations
- Updates/adds API keys
- Removes duplicate entries
- Maintains comments and formatting where possible

**Generated .env example:**
```bash
# Paladin Environment Configuration
# Generated by onboarding wizard - 2026-02-09

# LLM Provider API Keys
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
DEEPSEEK_API_KEY=sk-...

# Optional: Redis (for queue-based execution)
# REDIS_URL=redis://localhost:6379

# Optional: Qdrant (for vector storage/RAG)
# QDRANT_URL=http://localhost:6333

# Optional: MinIO (for file storage)
# MINIO_ENDPOINT=localhost:9000
# MINIO_ACCESS_KEY=minioadmin
# MINIO_SECRET_KEY=minioadmin
```

### Step 6: Sample Configuration Generation

The wizard generates ready-to-use example files:

```
Generating sample configurations...
  ✓ examples/basic_paladin.yaml
  ✓ examples/formation.yaml
  ✓ examples/phalanx.yaml
  ✓ examples/paladin_with_rag.yaml

These examples demonstrate:
  • Basic single-agent configuration
  • Sequential execution (Formation)
  • Parallel execution (Phalanx)
  • RAG-enabled agent with memory
```

### Step 7: Completion Summary

```
╔══════════════════════════════════════════════════════════╗
║                                                          ║
║   Setup Complete! ✅                                      ║
║                                                          ║
╚══════════════════════════════════════════════════════════╝

Configuration saved to: .env
Sample configs created: examples/

Next Steps:
  1. Verify your setup:
     $ paladin setup-check

  2. Try a sample agent:
     $ paladin agent run -c examples/basic_paladin.yaml -i "Hello!"

  3. Explore features:
     $ paladin features

  4. Generate a battalion:
     $ paladin muster --task "Your task description"

Resources:
  • Documentation: docs/CLI_USAGE.md
  • Quick Start: docs/QUICKSTART.md
  • Architecture: docs/Design/Design_and_Architecture.md
```

## Resumable Wizard State

The wizard automatically saves progress if interrupted:

```bash
# If interrupted (Ctrl+C)
^C
Saving wizard state...
Progress saved to: .paladin/onboarding.state

# Resume later
paladin onboarding
? Previous onboarding session found. Resume? (Y/n)
```

**State Information:**
- Provider selections
- Validated API keys
- File merge decisions
- Wizard step position

**State Location:** `.paladin/onboarding.state` (JSON format)

## Troubleshooting

### API Key Validation Fails

**Problem:** "Authentication failed" error

**Solutions:**
1. **Check key format:**
   - OpenAI: Must start with `sk-` (51+ characters)
   - Anthropic: Must start with `sk-ant-` (40+ characters)
   - DeepSeek: Must start with `sk-` (40+ characters)

2. **Verify key is active:**
   - Log into provider dashboard
   - Check API key hasn't been revoked
   - Verify account has credits/billing set up

3. **Network connectivity:**
   ```bash
   # Test OpenAI connectivity
   curl https://api.openai.com/v1/models \
     -H "Authorization: Bearer $OPENAI_API_KEY"
   ```

### .env File Not Created

**Problem:** No `.env` file after completion

**Solutions:**
1. **Check file permissions:**
   ```bash
   # Ensure write permissions in current directory
   ls -la .
   ```

2. **Run with explicit output:**
   ```bash
   # Check for error messages
   paladin onboarding 2>&1 | tee onboarding.log
   ```

3. **Create manually:**
   ```bash
   # Copy from template
   cp examples/.env.template .env
   # Edit with your keys
   vim .env
   ```

### Sample Configs Not Generated

**Problem:** Examples directory is empty

**Solutions:**
1. **Check directory exists:**
   ```bash
   mkdir -p examples
   ```

2. **Verify write permissions:**
   ```bash
   chmod 755 examples
   ```

3. **Generate manually:**
   ```bash
   # Use agent command to create templates
   paladin agent new -n basic -o examples/basic_paladin.yaml
   paladin battalion new -n formation -t formation -o examples/formation.yaml
   ```

## Advanced Usage

### Non-Interactive Mode

For automation/scripting:

```bash
# Set via environment variables
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."

# Run wizard with pre-set keys
paladin onboarding
# Will skip key input, validate, and proceed
```

### Custom Output Path

```bash
# Generate .env in custom location
PALADIN_ENV_FILE=./config/.env paladin onboarding
```

### Skip Validation

```bash
# For offline development (not recommended)
PALADIN_SKIP_VALIDATION=1 paladin onboarding
```

## Related Commands

- **[`paladin setup-check`](SETUP_CHECK.md)** - Validate configuration after onboarding
- **[`paladin features`](../CLI_USAGE.md#paladin-features)** - Discover available capabilities
- **[`paladin agent`](../CLI_USAGE.md#paladin-agent)** - Run your first agent

## See Also

- [CLI Usage Guide](../CLI_USAGE.md)
- [Quick Start Guide](../QUICKSTART.md)
- [Installation Guide](../INSTALLATION.md)
- [Provider Configuration](../CONTRIBUTING_PROVIDERS.md)