# Acurity Setup Wizard Guide

## Overview

The Acurity extension now includes a friendly setup wizard that guides users through initial configuration. This provides a better first-run experience and makes settings more discoverable.

## User Experience Flow

### First-Time Activation

When a user installs and activates the Acurity extension for the first time:

1. **2-second delay** - Extension activates in the background
2. **Welcome message appears**: 
   ```
   Welcome to Acurity!
   Let's configure the extension for your needs. 
   You can change these settings anytime.
   
   [Continue]  [Skip]
   ```

### Setup Wizard Steps

#### Step 1: Standards Profile Selection

A quick-pick menu with three options:

```
⭐ Default
Balanced approach - warnings for style, errors for bugs
(Recommended for most projects)

📦 Legacy Compatible
Relaxed rules for older codebases - disables ROBODOC requirements and naming rules
(Good for brownfield projects)

🛡️ Strict Modern
Strict enforcement - ROBODOC required, all naming rules as errors
(Best for new greenfield projects)
```

**Sets**: `acurity.rules.profile`

#### Step 2: ROBODOC Validation

```
✓ Enable ROBODOC Validation
Validate documentation blocks in Acurity files

✗ Disable ROBODOC Validation
Skip documentation checks
```

**Sets**: `acurity.robodoc.enabled`

#### Step 3: Author Name (if ROBODOC enabled)

```
👤 Set Author Name
Configure your name for ROBODOC @author tags

⏭️ Skip for Now
You can set this later in settings
```

If user selects "Set Author Name":
```
Input Box:
Enter the author name for ROBODOC templates
Placeholder: e.g. John Smith
```

**Sets**: `acurity.robodoc.authorName`

#### Step 4: Completion

```
Setup complete! 
You can adjust these settings anytime using the 
'Acurity: Open Settings' command.

[View Settings]  [Done]
```

If "View Settings" is clicked, opens VS Code Settings UI filtered to `@ext:jibbius.acurity`.

## Accessing Settings Later

### Command Palette Commands

Users can access configuration at any time via:

1. **`Acurity: Configure Extension`**
   - Re-runs the entire setup wizard
   - Useful for reconfiguring the extension

2. **`Acurity: Open Settings`**
   - Opens VS Code Settings UI filtered to Acurity
   - Shows all extension settings in a GUI format
   - Changes are automatically saved to `settings.json`

### Settings UI View

When `Acurity: Open Settings` is invoked, users see a filtered view showing only Acurity settings:

```
Settings > Extensions > Acurity

Search: @ext:jibbius.acurity

┌─────────────────────────────────────────┐
│ ACURITY: DIAGNOSTICS                    │
│ ✓ Debounce Ms: 500                      │
│                                         │
│ ACURITY: LOGGING                        │
│ ☐ Enabled                               │
│                                         │
│ ACURITY: ROBODOC                        │
│ ✓ Enabled                               │
│ ✓ Require Doc Block                     │
│ Author Name: John Smith                 │
│ Include Header Prefix: header           │
│ Report Filename Pattern: ^[A-Za...      │
│ Report Header Prefix: report            │
│ ✓ Validate Header Target                │
│ Required Sections: NAME, SYNOPSI...     │
│                                         │
│ ACURITY: STANDARDS                      │
│ Profile: default ▼                      │
│   • default                             │
│   • legacy-compatible                   │
│   • strict-modern                       │
│                                         │
│ Rules Naming Prefix Scope: warning ▼    │
│ Rules Naming Prefix Type: warning ▼     │
│ Rules Naming Reserved Prefix: ......    │
└─────────────────────────────────────────┘
```

All changes are automatically synced to the user's `settings.json`:

```json
{
  "acurity.rules.profile": "default",
  "acurity.robodoc.enabled": true,
  "acurity.robodoc.authorName": "John Smith"
}
```

## Technical Implementation

### First-Run Detection

- Uses VS Code's `globalState` to track if wizard has been shown
- Key: `acurity.setupWizardCompleted`
- Persists across workspace changes
- Resets only if extension is uninstalled/reinstalled

### Configuration Storage

All settings use `ConfigurationTarget.Global`:
- Settings apply to all workspaces
- Stored in user's global `settings.json`
- Can be overridden per-workspace if needed

### No Persistence Issues

- Uses only VS Code APIs (`globalState`, `workspace.getConfiguration`)
- No file system operations
- No external dependencies
- Corporate-friendly (no subprocess execution)

## Developer Testing

To test the wizard after implementation:

1. **Reset first-run state** (one of these methods):
   ```powershell
   # Method 1: Developer command
   Developer: Inspect Context Keys
   Search for: acurity.setupWizardCompleted
   Clear it
   
   # Method 2: Reload window
   Developer: Reload Window
   ```

2. **Or clear extension state** (nuclear option):
   ```powershell
   # Close VS Code
   # Delete extension storage
   Remove-Item -Recurse "$env:APPDATA\Code\User\globalStorage\acurity"
   ```

3. **Reload the window** to trigger first-run again

## User Benefits

✅ **Guided Configuration** - No need to hunt through settings  
✅ **Profile-Based** - Intelligent defaults for different use cases  
✅ **Discoverable** - Commands visible in Command Palette  
✅ **Non-Intrusive** - 2-second delay, easy to skip  
✅ **Persistent** - Only shows once per installation  
✅ **Reconfigurable** - Easy to re-run or jump to settings  
✅ **GUI-Friendly** - VS Code renders JSON as nice form UI  

## Future Enhancements

Potential additions for v2:

- [ ] Status bar item showing active profile
- [ ] Quick-switch profile from status bar
- [ ] "Reset to Defaults" command
- [ ] Per-workspace configuration wizard
- [ ] Export/import configuration profiles
- [ ] Context-aware recommendations based on file patterns
