# Guided Activation Flow Feature Spec

## Overview

This feature introduces a **post-setup guided activation flow** for new companies.

After completing the setup wizard, users should be guided through their **first real workflow** so they understand how to use the system immediately.

This is NOT a tooltip tour.

This is a **guided outcome flow using real system actions** (quotes, jobs, invoices).

---

## Problem

Current behavior:
- Users complete setup wizard
- Land on dashboard
- Do not create quotes, jobs, or invoices
- Drop off

Goal:
- Ensure users complete at least ONE real workflow
- Create an "aha moment" within first session

---

## Business Workflows

### 1. Quote-First Workflow
- Create Quote
- Send to customer
- Convert Quote → Job
- Process Job
- Create Invoice
- Customer Pays

### 2. Job-First Workflow (Walk-in)
- Create Job directly
- Process Job
- Create Invoice
- Customer Pays

---

## Feature Behavior

### Trigger Condition

IF:
- setup wizard is completed
- AND firstWorkflowCompleted == false

THEN:
→ redirect user to guided activation flow

---

## Step 1: Workflow Selection

Display full-screen page:

### Title:
"Your shop is set up. Let’s run your first workflow."

### Subtitle:
"Choose how jobs usually start for your shop and we’ll guide you through it."

### Question:
"How do jobs usually start for your shop?"

### Options:

#### Option A:
Title: "I send a quote first"
Description: "Create a quote, convert it to a job, then invoice when work is complete."

#### Option B:
Title: "I start with a job"
Description: "For walk-ins or approved work where you start immediately."

---

### On Selection:
Save:
- onboardingPath = "quote_first" | "job_first"

Then continue into guided flow

---

## Step 2: Guided Flow

### Path A — Quote First

#### Step A1: Create Quote
- Use existing quote creation logic
- Pre-fill fields:
  - Customer: "Sample Customer"
  - Item: "Wheel Set"
  - Quantity: 4
  - Notes: "Sample onboarding quote"
- Allow editing before submit

#### Step A2: Show Quote Created
Message:
"This is the quote you would send to your customer."

CTA:
"Convert to Job"

#### Step A3: Convert Quote → Job
- Use existing conversion logic

#### Step A4: Show Job
Message:
"This job is now tracked in your workflow."

CTA:
"Create Invoice" (if supported)

#### Step A5: Create Invoice (optional)
- Use existing invoice logic

#### Completion:
Set:
- firstWorkflowCompleted = true

---

### Path B — Job First

#### Step B1: Create Job
- Use existing job creation logic
- Pre-fill:
  - Customer: "Walk-in Customer"
  - Item: "Wheel Set"
  - Quantity: 4
  - Notes: "Sample onboarding job"

#### Step B2: Show Job
Message:
"This job is now in your workflow."

CTA:
"Create Invoice" (optional)

#### Step B3: Create Invoice (optional)

#### Completion:
Set:
- firstWorkflowCompleted = true

---

## Skipping

Provide "Skip for now" option.

If skipped:
- DO NOT set firstWorkflowCompleted
- Redirect to dashboard
- Continue showing activation banner

---

## Dashboard Behavior

If:
- setup complete
- AND firstWorkflowCompleted == false

Show persistent banner:

Title:
"Create your first job or quote"

Text:
"Run a quick 2-minute workflow to see how the system works."

CTA:
"Start first workflow"

---

## Data Model Changes

Add to Company or User:

- onboardingPath: string | null
- firstWorkflowCompleted: boolean

Optional:
- firstQuoteCreatedAt: datetime
- firstJobCreatedAt: datetime
- firstInvoiceCreatedAt: datetime

---

## Events / Tracking (if system exists)

Track:
- onboarding_path_selected
- first_quote_created
- first_job_created
- first_invoice_created
- first_workflow_completed
- first_workflow_skipped

---

## Implementation Constraints

- MUST reuse existing quote/job/invoice logic
- DO NOT duplicate business logic
- DO NOT create separate fake systems
- Use existing forms and APIs where possible
- Keep UI minimal and fast
- Pre-fill as much as possible

---

## UX Requirements

- No tooltip tours
- Linear guided flow only
- One action at a time
- Minimize user effort
- Show immediate visual feedback

---

## Developer Instructions

Before coding:
1. Inspect setup wizard completion logic
2. Identify routing after setup
3. Identify quote/job/invoice creation flows
4. Identify data model structure

Then:
5. Propose implementation plan
6. Wait for approval
7. Implement incrementally
8. Summarize changes
9. Provide manual QA steps

---

## Success Criteria

- % of users creating first job increases significantly
- Users complete at least one workflow during onboarding
- Reduced drop-off after setup wizard

Target:
≥ 30% of new users create at least one job or quote