# Bakery Setup Wizard - Complete Flow Specification

**Version**: 1.0
**Date**: 2025-11-06
**Status**: Design Specification
**Related**: `jtbd-analysis-inventory-setup.md`

---

## 📋 Table of Contents

1. [Executive Summary](#executive-summary)
2. [Design Principles](#design-principles)
3. [Wizard Architecture](#wizard-architecture)
4. [Complete Step Sequence](#complete-step-sequence)
5. [Step Specifications (Detailed)](#step-specifications-detailed)
6. [Progress Tracking & Navigation](#progress-tracking--navigation)
7. [Validation & Error Handling](#validation--error-handling)
8. [Smart Features](#smart-features)
9. [Technical Implementation Notes](#technical-implementation-notes)
10. [Success Metrics](#success-metrics)

---

## Executive Summary

### Problem Statement
After completing the initial onboarding wizard (Register Bakery → Upload Sales Data → ML Training → Completion), users are dropped onto a dashboard with no guidance on how to set up the foundational data needed for daily operations. This creates:
- High abandonment rates (users don't complete setup)
- Data quality issues (incomplete or incorrect entries)
- Delayed time-to-value (can't use the system effectively)

### Solution Overview
**Guided Bakery Setup Journey**: A continuation of the onboarding wizard that walks users through setting up suppliers, inventory, recipes, quality standards, and team in a logical, dependency-aware sequence.

### Key Innovations
1. **Continuous Journey**: Extends onboarding wizard (Step 5+) instead of separate flow
2. **Dependency Awareness**: Enforces order (suppliers before inventory before recipes)
3. **Progressive Disclosure**: Shows complex options only when needed
4. **Flexible Pacing**: Save progress, skip optional steps, resume later
5. **Contextual Guidance**: Every step explains why it matters and what comes next
6. **Celebration Moments**: Recognizes milestones to maintain motivation

---

## Design Principles

### 1. Guide, Don't Block
**Principle**: Provide clear direction while allowing flexibility
- ✅ Suggest optimal path but allow users to skip optional steps
- ✅ Show what's incomplete without preventing progress
- ❌ Don't force users into rigid workflows
- ❌ Don't hide advanced options from experienced users

### 2. Explain, Don't Assume
**Principle**: Use plain language and provide context
- ✅ Explain why each step matters to bakery operations
- ✅ Use bakery terminology, not software jargon
- ✅ Provide examples and common values
- ❌ Don't assume users understand database concepts
- ❌ Don't use technical terms without explanation

### 3. Validate Early, Fail Friendly
**Principle**: Catch errors before they happen, provide helpful guidance
- ✅ Real-time validation as users type
- ✅ Helpful error messages with suggestions
- ✅ Prevent invalid states (dependencies, cross-field validation)
- ❌ Don't wait until submit to show errors
- ❌ Don't show technical error messages

### 4. Progress Over Perfection
**Principle**: Help users make progress, even if data isn't perfect
- ✅ Allow "good enough" data to move forward
- ✅ Clearly mark what's required vs. optional
- ✅ Allow editing later without redoing the entire wizard
- ❌ Don't demand perfection that prevents progress
- ❌ Don't make optional fields feel required

### 5. Show Value Early
**Principle**: Unlock features as users progress
- ✅ Show what becomes possible after each step
- ✅ Preview features before they're available
- ✅ Celebrate completion milestones
- ❌ Don't wait until the end to show value
- ❌ Don't make setup feel like busywork

---

## Wizard Architecture

### Overall Flow Structure

```
┌─────────────────────────────────────────────────────────────┐
│  EXISTING ONBOARDING WIZARD (Steps 1-4)                     │
│  ────────────────────────────────────────────────────────   │
│  1. Register Tenant (setup)                                 │
│  2. Configure Inventory (smart-inventory-setup)             │
│  3. Train AI (ml-training)                                  │
│  4. Completion                                              │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  NEW: BAKERY SETUP WIZARD (Steps 5-11)                      │
│  ────────────────────────────────────────────────────────   │
│  PHASE 1: ORIENTATION & PLANNING                            │
│  5. Welcome & Setup Overview (setup-welcome)                │
│                                                              │
│  PHASE 2: CORE DEPENDENCIES (Critical Path)                 │
│  6. Add Suppliers (suppliers-setup)                         │
│  7. Set Up Inventory Items (inventory-items-setup)          │
│                                                              │
│  PHASE 3: OPERATIONAL DATA (Required for Production)        │
│  8. Create Recipes (recipes-setup)                          │
│  9. Define Quality Standards (quality-setup)                │
│                                                              │
│  PHASE 4: TEAM & FINALIZATION (Optional but Recommended)    │
│  10. Add Team Members (team-setup) [OPTIONAL]               │
│  11. Review & Launch (setup-completion)                     │
└─────────────────────────────────────────────────────────────┘
```

### Integration Point
- **Trigger**: When user completes existing Step 4 (Completion)
- **Transition**: Instead of navigating to dashboard, show "One more thing..." modal
- **Modal Content**: "Great start! Now let's set up your daily operations. This will take about 10-15 minutes and unlock powerful features like recipe costing, inventory tracking, and quality monitoring."
- **User Choice**:
  - **"Set Up Now"** (recommended) → Enter wizard at Step 5
  - **"I'll Do This Later"** → Go to dashboard with persistent "Complete Setup" banner

### Step Categories

| Category | Steps | Required? | Can Skip? | Estimated Time |
|----------|-------|-----------|-----------|----------------|
| **Orientation** | Step 5 (Welcome) | No | Yes | 2 min |
| **Critical Path** | Steps 6-7 (Suppliers, Inventory) | Yes | No | 5-8 min |
| **Production Setup** | Steps 8-9 (Recipes, Quality) | Yes | No | 5-10 min |
| **Team Setup** | Step 10 (Team) | No | Yes | 2-5 min |
| **Completion** | Step 11 (Review) | No | Yes | 1-2 min |

**Total Estimated Time**: 15-27 minutes (depending on data complexity)

---

## Complete Step Sequence

### PHASE 1: ORIENTATION & PLANNING

#### **Step 5: Welcome & Setup Overview** (`setup-welcome`)
**Purpose**: Orient user to what's ahead, reduce anxiety, set expectations

**User Job**: *"Help me understand what I need to set up and why"*

**Content**:
- Welcome message: "You've trained your AI. Now let's set up your daily operations."
- Visual roadmap showing all steps ahead
- Time estimate: "This takes about 15-20 minutes"
- What you'll need: "Have ready: supplier info, ingredient list, common recipes"
- What you'll gain: Feature preview cards showing value

**UI Components**:
```
┌──────────────────────────────────────────────────────┐
│  🎉 Excellent! Your AI is Ready                      │
│                                                       │
│  Now let's set up your bakery's daily operations     │
│  so the system can help you manage:                  │
│                                                       │
│  ✓ Inventory tracking & reorder alerts              │
│  ✓ Recipe costing & profitability analysis          │
│  ✓ Quality standards & production monitoring         │
│  ✓ Team coordination & task assignment              │
│                                                       │
│  ⏱️ Takes about 15-20 minutes                        │
│                                                       │
│  📋 What You'll Set Up:                              │
│  ────────────────────────────────────────────────    │
│  [CARD] Suppliers        | 2-3 min  | Required      │
│  [CARD] Inventory Items  | 5-8 min  | Required      │
│  [CARD] Recipes          | 5-10 min | Required      │
│  [CARD] Quality Checks   | 3-5 min  | Required      │
│  [CARD] Team Members     | 2-5 min  | Optional      │
│                                                       │
│  💡 You can save progress and resume anytime         │
│                                                       │
│  [Skip for Now]           [Let's Get Started! →]    │
└──────────────────────────────────────────────────────┘
```

**Validation**: None (informational step)

**Navigation**:
- **Next**: Step 6 (Suppliers Setup)
- **Skip**: Go to dashboard with "Resume Setup" banner

**Backend**: Mark `setup-welcome` as completed

---

### PHASE 2: CORE DEPENDENCIES (Critical Path)

#### **Step 6: Add Suppliers** (`suppliers-setup`)
**Purpose**: Set up supplier relationships as foundation for inventory

**User Job**: *"Add my suppliers so I can track where ingredients come from and manage orders"*

**Why This Step**:
> "Suppliers are the source of your ingredients. Setting them up now lets you track costs, manage orders, and analyze supplier performance."

**What Users Need to Add**: Minimum 1 supplier (recommended 2-3)

**Form Type**: **Wizard-Enhanced List Entry**

**UI Flow**:

```
┌──────────────────────────────────────────────────────┐
│  Step 2 of 7: Add Your Suppliers                     │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  💼 Suppliers                                         │
│  Your ingredient and material providers              │
│                                                       │
│  [==========>------------------] 29% Complete        │
│                                                       │
│  ┌──────────────────────────────────────────────┐   │
│  │  Why This Matters                            │   │
│  │  ─────────────────────────────────────────── │   │
│  │  Tracking suppliers helps you:               │   │
│  │  • Compare ingredient costs                  │   │
│  │  • Manage purchase orders                    │   │
│  │  • Analyze delivery performance              │   │
│  └──────────────────────────────────────────────┘   │
│                                                       │
│  ┌──────────────────────────────────────────────┐   │
│  │  📝 Your Suppliers (1 required, 2-3 ideal)   │   │
│  │                                               │   │
│  │  [+ Add Your First Supplier]                 │   │
│  │                                               │   │
│  │  Empty state illustration                     │   │
│  │  "Add at least one supplier to continue"     │   │
│  └──────────────────────────────────────────────┘   │
│                                                       │
│  💡 Tip: Start with your most frequently used        │
│     supplier. You can add more later.                │
│                                                       │
│  [← Back]                        [Skip] [Continue →] │
│  (disabled until 1 supplier added)                   │
└──────────────────────────────────────────────────────┘
```

**When "Add Supplier" clicked** → Opens inline wizard modal:

```
┌──────────────────────────────────────────────────────┐
│  ✕ Add Supplier                                       │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  Basic Information                                   │
│  ────────────────────────────────────────────────    │
│  Supplier Name *                                     │
│  [_____________________________________________]      │
│   e.g., "Molinos del Norte", "Ingredientes García"   │
│                                                       │
│  Supplier Type *                                     │
│  [▼ Select type___________________________]          │
│      ├─ Ingredients (flour, sugar, yeast...)         │
│      ├─ Packaging (boxes, bags, labels...)           │
│      └─ Equipment (mixers, ovens...)                 │
│                                                       │
│  Contact Information (Optional)                      │
│  ────────────────────────────────────────────────    │
│  ▼ Show optional fields                              │
│                                                       │
│  [Add Another Supplier]         [Cancel] [Add →]     │
└──────────────────────────────────────────────────────┘
```

**Fields**:

| Field | Type | Required | Validation | Help Text |
|-------|------|----------|------------|-----------|
| `name` | text | Yes | Min 2 chars | "The business name of your supplier" |
| `supplier_type` | select | Yes | Must select | "Ingredients, Packaging, or Equipment" |
| `contact_name` | text | No | - | "Main contact person at this supplier" |
| `email` | email | No | Valid email | "For sending purchase orders" |
| `phone` | tel | No | Valid phone | "For quick inquiries" |
| `payment_terms` | select | No | - | "Net 30, Net 60, Prepaid, COD..." |
| `status` | select | No | Default: Active | "Active, Inactive, Preferred" |

**After Adding Suppliers**:

```
┌──────────────────────────────────────────────────────┐
│  📝 Your Suppliers (2 added) ✓                       │
│                                                       │
│  ┌────────────────────────────────────────────┐     │
│  │ 💼 Molinos del Norte                       │ [⋮]  │
│  │    Type: Ingredients  │  Status: Active    │     │
│  │    Contact: Juan García                    │     │
│  └────────────────────────────────────────────┘     │
│                                                       │
│  ┌────────────────────────────────────────────┐     │
│  │ 📦 Empaques Premium                        │ [⋮]  │
│  │    Type: Packaging  │  Status: Active      │     │
│  │    Contact: María López                    │     │
│  └────────────────────────────────────────────┘     │
│                                                       │
│  [+ Add Another Supplier]                            │
│                                                       │
│  ✅ Great! You've added 2 suppliers                  │
│                                                       │
│  [← Back]                  [Continue to Inventory →] │
└──────────────────────────────────────────────────────┘
```

**Validation**:
- **Minimum**: 1 supplier required to continue
- **Real-time**: Check for duplicate names
- **Business Rule**: At least one "Ingredients" type supplier recommended (show warning if none)

**Navigation**:
- **Continue**: Only enabled when ≥1 supplier added
- **Skip**: Allowed, but shows warning: "You'll need suppliers later for purchase orders"

**Backend**:
- Save each supplier via `POST /api/v1/suppliers/`
- Mark step `suppliers-setup` as completed
- Store count in step data: `{suppliers_added: 2}`

**Smart Features**:
- **Template Suppliers**: "Use common supplier template" button → Pre-fills with typical Spanish bakery suppliers
- **Bulk Import**: "Import from spreadsheet" (CSV with name, type, contact)

---

#### **Step 7: Set Up Inventory Items** (`inventory-items-setup`)
**Purpose**: Add the ingredients and materials used in bakery operations

**User Job**: *"Add my ingredients so the system can track inventory levels and costs"*

**Why This Step**:
> "Inventory items are the building blocks of your recipes. Once set up, the system will track quantities, alert you when stock is low, and help you calculate recipe costs."

**What Users Need to Add**: Minimum 3 inventory items (recommended 10-15 for starter set)

**Dependency**: Requires ≥1 supplier from Step 6

**Form Type**: **Wizard-Enhanced List Entry with Bulk Options**

**UI Flow**:

```
┌──────────────────────────────────────────────────────┐
│  Step 3 of 7: Set Up Inventory Items                 │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  📦 Inventory Items                                   │
│  Ingredients and materials you use                   │
│                                                       │
│  [====================>--------] 57% Complete        │
│                                                       │
│  ┌──────────────────────────────────────────────┐   │
│  │  Why This Matters                            │   │
│  │  ─────────────────────────────────────────── │   │
│  │  Inventory tracking enables:                 │   │
│  │  • Low stock alerts (never run out!)        │   │
│  │  • Automatic reorder suggestions             │   │
│  │  • Accurate recipe costing                   │   │
│  └──────────────────────────────────────────────┘   │
│                                                       │
│  ┌──────────────────────────────────────────────┐   │
│  │  📝 Your Inventory (3 min required, 10 ideal)│   │
│  │                                               │   │
│  │  [+ Add Item] [📥 Import Spreadsheet]        │   │
│  │  [📋 Use Starter Template]                   │   │
│  │                                               │   │
│  │  (Empty state)                                │   │
│  │  "Add your most common ingredients first"    │   │
│  └──────────────────────────────────────────────┘   │
│                                                       │
│  💡 Quick Start: Use our starter template with       │
│     common bakery ingredients (flour, sugar, eggs,   │
│     butter...). You can customize them after.        │
│                                                       │
│  [← Back to Suppliers]         [Skip] [Continue →]   │
│  (disabled until 3 items added)                      │
└──────────────────────────────────────────────────────┘
```

**Starter Template Feature**:

When user clicks "Use Starter Template":

```
┌──────────────────────────────────────────────────────┐
│  ✕ Add Starter Ingredients                           │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  We'll add common bakery ingredients to get you      │
│  started. You can edit or remove any items.          │
│                                                       │
│  ☑️ Flour (White Bread Flour) - kg                   │
│  ☑️ Flour (Whole Wheat) - kg                         │
│  ☑️ Sugar (White Granulated) - kg                    │
│  ☑️ Butter (Unsalted) - kg                           │
│  ☑️ Eggs (Large) - units                             │
│  ☑️ Milk (Whole) - liters                            │
│  ☑️ Yeast (Active Dry) - kg                          │
│  ☑️ Salt (Fine) - kg                                 │
│  ☑️ Water - liters                                   │
│  ☑️ Chocolate Chips - kg                             │
│                                                       │
│  Assign Supplier (Optional):                         │
│  [▼ Molinos del Norte________________]               │
│      (will be set as supplier for flour & sugar)     │
│                                                       │
│  [Cancel]               [Add Selected Items (10) →]  │
└──────────────────────────────────────────────────────┘
```

**Manual Add Item Modal**:

```
┌──────────────────────────────────────────────────────┐
│  ✕ Add Inventory Item                  [Step 1 of 2] │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  ▼ Basic Information                                 │
│  ────────────────────────────────────────────────    │
│  Item Name *                                         │
│  [_____________________________________________]      │
│   e.g., "Harina de trigo 000", "Azúcar blanca"       │
│                                                       │
│  Category *                                          │
│  [▼ Select category_______________________]          │
│      ├─ Flour & Grains                               │
│      ├─ Dairy & Eggs                                 │
│      ├─ Sweeteners                                   │
│      ├─ Fats & Oils                                  │
│      ├─ Leavening Agents                             │
│      ├─ Flavorings & Additives                       │
│      └─ Packaging Materials                          │
│                                                       │
│  Unit of Measure *                                   │
│  [▼ Kilograms________________________]               │
│      ├─ Kilograms (kg)                               │
│      ├─ Grams (g)                                    │
│      ├─ Liters (L)                                   │
│      ├─ Milliliters (ml)                             │
│      └─ Units (pieces)                               │
│                                                       │
│  ▼ Supplier & Pricing (Optional - can add later)    │
│  ────────────────────────────────────────────────    │
│  ▶ Show optional fields                              │
│                                                       │
│  [Cancel]           [Continue to Stock Levels →]     │
└──────────────────────────────────────────────────────┘
```

**Step 2 of Add Item (Stock & Reorder Levels)**:

```
┌──────────────────────────────────────────────────────┐
│  ✕ Add Inventory Item                  [Step 2 of 2] │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  ✓ Harina de trigo 000 │ Flour & Grains │ kg        │
│                                                       │
│  ▼ Stock Levels & Alerts                             │
│  ────────────────────────────────────────────────    │
│  Current Stock (Optional)                            │
│  [________] kg                                        │
│   How much do you have right now?                    │
│                                                       │
│  Low Stock Alert At                                  │
│  [________] kg        (Recommended: 10-20 kg)        │
│   You'll get notified when stock falls below this    │
│                                                       │
│  Reorder Point                                       │
│  [________] kg        (Recommended: 5 kg)            │
│   System will suggest reordering at this level       │
│                                                       │
│  ▼ Advanced Options (Optional)                       │
│  ────────────────────────────────────────────────    │
│  ▶ Pricing, Shelf Life, SKU/Barcode                 │
│                                                       │
│  💡 Don't worry if you don't know exact numbers.     │
│     You can adjust these anytime based on usage.     │
│                                                       │
│  [← Back]          [Add Another Item] [Save & Done]  │
└──────────────────────────────────────────────────────┘
```

**Fields (Complete List)**:

**Step 1 - Required**:
| Field | Type | Required | Validation | Help Text |
|-------|------|----------|------------|-----------|
| `name` | text | Yes | Min 2 chars, unique | "The name you use for this item" |
| `category` | select | Yes | Must select | "Helps organize your inventory" |
| `unit_of_measure` | select | Yes | Must select | "How this item is measured" |

**Step 2 - Stock Levels**:
| Field | Type | Required | Validation | Help Text |
|-------|------|----------|------------|-----------|
| `current_quantity` | number | No | ≥0 | "Current stock on hand" |
| `low_stock_threshold` | number | No | ≥0 | "Alert me when below this level" |
| `reorder_point` | number | No | ≥0, ≤ low_stock | "Suggest reorder at this level" |

**Advanced - Optional**:
| Field | Type | Required | Validation | Help Text |
|-------|------|----------|------------|-----------|
| `supplier_id` | select | No | Must exist | "Primary supplier for this item" |
| `standard_cost` | currency | No | ≥0 | "Typical cost per unit" |
| `sku` | text | No | Unique | "Stock keeping unit code" |
| `barcode` | text | No | Valid barcode | "For scanning" |
| `shelf_life_days` | number | No | >0 | "Days until expires" |

**After Adding Items**:

```
┌──────────────────────────────────────────────────────┐
│  📝 Your Inventory Items (12 added) ✓                │
│                                                       │
│  Filter by: [All▼] [Search: _______________] [⚙️]    │
│                                                       │
│  ┌────────────────────────────────────────────┐     │
│  │ 🌾 Harina de trigo 000                     │ [⋮]  │
│  │    Flour & Grains  │  50 kg  │  Low: 20 kg │     │
│  │    Supplier: Molinos del Norte             │     │
│  └────────────────────────────────────────────┘     │
│                                                       │
│  ┌────────────────────────────────────────────┐     │
│  │ 🥚 Eggs (Large)                            │ [⋮]  │
│  │    Dairy & Eggs  │  200 units  │  Low: 50  │     │
│  │    No supplier set                         │     │
│  └────────────────────────────────────────────┘     │
│                                                       │
│  [... 10 more items ...]                             │
│                                                       │
│  [+ Add Item] [Import] [Use Template]                │
│                                                       │
│  ✅ Excellent! You've set up 12 inventory items      │
│                                                       │
│  [← Back to Suppliers]        [Continue to Recipes →]│
└──────────────────────────────────────────────────────┘
```

**Validation**:
- **Minimum**: 3 items required to continue
- **Real-time**: Check for duplicate names within category
- **Business Rules**:
  - Warn if no flour items (common for bakeries)
  - Warn if reorder_point > low_stock_threshold
  - Suggest supplier if none set for "Ingredients" type items

**Navigation**:
- **Continue**: Enabled when ≥3 items added
- **Skip**: Allowed with warning: "Recipes require ingredients. Sure you want to skip?"

**Backend**:
- Save each item via `POST /api/v1/inventory/ingredients/`
- For starter template: Bulk create via `POST /api/v1/inventory/ingredients/bulk/`
- Mark step `inventory-items-setup` as completed
- Store count: `{inventory_items_added: 12, used_template: true}`

**Smart Features**:
- **Smart Categories**: Auto-suggest category based on item name (ML)
- **Unit Conversion**: "Convert between units" helper
- **Supplier Recommendation**: Based on item category, suggest relevant suppliers from Step 6
- **Bulk Edit**: "Edit multiple items" for updating low stock thresholds

**Progress Indicator Within Step**:
```
┌──────────────────────────────────────┐
│  Progress: 12 items added            │
│  ▰▰▰▱▱ Minimum met (3+)  ✓           │
│  ▰▰▰▰▰ Recommended (10+) ✓           │
└──────────────────────────────────────┘
```

---

### PHASE 3: OPERATIONAL DATA (Required for Production)

#### **Step 8: Create Recipes** (`recipes-setup`)
**Purpose**: Define production recipes using inventory items

**User Job**: *"Add my recipes so the system can calculate costs, track production, and manage ingredient usage"*

**Why This Step**:
> "Recipes connect your inventory to production. The system will calculate exact costs per item, track ingredient consumption, and help you optimize your menu profitability."

**What Users Need to Add**: Minimum 1 recipe (recommended 3-5 core products)

**Dependency**: Requires ≥3 inventory items from Step 7

**Form Type**: **Multi-Step Recipe Builder**

**UI Flow**:

```
┌──────────────────────────────────────────────────────┐
│  Step 4 of 7: Create Your Recipes                    │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  👨‍🍳 Recipes                                           │
│  Your bakery's production formulas                   │
│                                                       │
│  [=============================>---] 71% Complete    │
│                                                       │
│  ┌──────────────────────────────────────────────┐   │
│  │  Why This Matters                            │   │
│  │  ─────────────────────────────────────────── │   │
│  │  Recipes unlock powerful features:           │   │
│  │  • Automatic ingredient cost calculation     │   │
│  │  • Production planning & scheduling          │   │
│  │  • Inventory consumption tracking            │   │
│  │  • Profitability analysis per product        │   │
│  └──────────────────────────────────────────────┘   │
│                                                       │
│  ┌──────────────────────────────────────────────┐   │
│  │  📝 Your Recipes (1 min required, 3-5 ideal) │   │
│  │                                               │   │
│  │  [+ Create Recipe] [📋 Use Recipe Template]  │   │
│  │                                               │   │
│  │  (Empty state)                                │   │
│  │  "Create recipes for your core products"     │   │
│  └──────────────────────────────────────────────┘   │
│                                                       │
│  💡 Quick Start: Use recipe templates for common     │
│     baked goods. Adjust quantities to match yours.   │
│                                                       │
│  [← Back to Inventory]            [Skip] [Continue →]│
│  (disabled until 1 recipe added)                     │
└──────────────────────────────────────────────────────┘
```

**Recipe Template Gallery**:

```
┌──────────────────────────────────────────────────────┐
│  ✕ Choose Recipe Template                            │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  Select a template to customize, or create from      │
│  scratch:                                            │
│                                                       │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐          │
│  │  🥖      │  │  🍞      │  │  🥐      │          │
│  │ Baguette │  │  White   │  │ Croissant│          │
│  │ Francesa │  │  Bread   │  │          │          │
│  └──────────┘  └──────────┘  └──────────┘          │
│                                                       │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐          │
│  │  🍰      │  │  🧁      │  │  ➕      │          │
│  │  Cake    │  │ Muffins  │  │  Create  │          │
│  │  Sponge  │  │ Blueberry│  │  Blank   │          │
│  └──────────┘  └──────────┘  └──────────┘          │
│                                                       │
│  [Cancel]                                            │
└──────────────────────────────────────────────────────┘
```

**Create Recipe - Step 1 (Basic Info)**:

```
┌──────────────────────────────────────────────────────┐
│  ✕ Create Recipe                       [Step 1 of 3] │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  Recipe Information                                  │
│  ────────────────────────────────────────────────    │
│  Recipe Name *                                       │
│  [_____________________________________________]      │
│   e.g., "Baguette Francesa", "Pan de Molde"          │
│                                                       │
│  Category *                                          │
│  [▼ Select category_______________________]          │
│      ├─ Bread                                        │
│      ├─ Pastry                                       │
│      ├─ Cake                                         │
│      ├─ Cookie                                       │
│      └─ Specialty                                    │
│                                                       │
│  Batch Yield *                                       │
│  [_____] units                                        │
│   How many items does this recipe make?              │
│                                                       │
│  Preparation Time (Optional)                         │
│  [_____] minutes                                      │
│                                                       │
│  Description (Optional)                              │
│  [_____________________________________________]      │
│  [_____________________________________________]      │
│   Brief description or notes about this recipe       │
│                                                       │
│  [Cancel]                    [Continue to Ingredients →]│
└──────────────────────────────────────────────────────┘
```

**Create Recipe - Step 2 (Add Ingredients)**:

```
┌──────────────────────────────────────────────────────┐
│  ✕ Create Recipe                       [Step 2 of 3] │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  ✓ Baguette Francesa │ Bread │ Yield: 10 units      │
│                                                       │
│  Recipe Ingredients (1 minimum)                      │
│  ────────────────────────────────────────────────    │
│                                                       │
│  ┌────────────────────────────────────────────┐     │
│  │  Ingredient #1                             │ [🗑️]  │
│  │  ──────────────────────────────────────    │     │
│  │  Ingredient *                              │     │
│  │  [▼ Harina de trigo 000______________]     │     │
│  │                                             │     │
│  │  Quantity *        Unit *                  │     │
│  │  [_____] kg   [▼ Kilograms_______]         │     │
│  │                                             │     │
│  │  ☐ Optional ingredient (e.g., optional     │     │
│  │     decoration or variation)               │     │
│  └────────────────────────────────────────────┘     │
│                                                       │
│  [+ Add Another Ingredient]                          │
│                                                       │
│  💡 Tip: Add ingredients in the order you use them   │
│     during production for easier reference.          │
│                                                       │
│  Estimated Cost: Calculating...                      │
│  (Cost per unit will be calculated automatically     │
│   based on ingredient prices)                        │
│                                                       │
│  [← Back]         [Skip to Review] [Add Instructions →]│
└──────────────────────────────────────────────────────┘
```

**After Adding Ingredient**:

```
│  ┌────────────────────────────────────────────┐     │
│  │  ✓ Ingredient #1                           │ [⋮]  │
│  │  ──────────────────────────────────────    │     │
│  │  🌾 Harina de trigo 000                    │     │
│  │  1.5 kg  │  €0.75/kg  │  Cost: €1.13       │     │
│  └────────────────────────────────────────────┘     │
│                                                       │
│  ┌────────────────────────────────────────────┐     │
│  │  Ingredient #2                             │ [🗑️]  │
│  │  [Empty - Click to add]                    │     │
│  └────────────────────────────────────────────┘     │
```

**Create Recipe - Step 3 (Instructions - Optional)**:

```
┌──────────────────────────────────────────────────────┐
│  ✕ Create Recipe                       [Step 3 of 3] │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  ✓ Baguette Francesa │ 4 ingredients │ €2.45/batch  │
│                                                       │
│  Production Instructions (Optional)                  │
│  ────────────────────────────────────────────────    │
│  Add step-by-step instructions to help your team     │
│  produce this recipe consistently.                   │
│                                                       │
│  ┌────────────────────────────────────────────┐     │
│  │  Step 1: Mixing                            │ [⋮]  │
│  │  [________________________________]         │     │
│  │  Duration: [___] min  │  Temp: [___]°C     │     │
│  └────────────────────────────────────────────┘     │
│                                                       │
│  [+ Add Step]                                        │
│                                                       │
│  💡 You can skip this for now and add instructions   │
│     later. The recipe will still work for costing.   │
│                                                       │
│  ▼ Advanced Options (Optional)                       │
│  ────────────────────────────────────────────────    │
│  ▶ Add process stages, equipment, yield notes        │
│                                                       │
│  [← Back to Ingredients]    [Skip] [Create Recipe →] │
└──────────────────────────────────────────────────────┘
```

**Fields (Complete List)**:

**Step 1 - Recipe Info**:
| Field | Type | Required | Validation | Help Text |
|-------|------|----------|------------|-----------|
| `name` | text | Yes | Min 2 chars, unique | "The name of this recipe/product" |
| `category` | select | Yes | Must select | "Type of baked good" |
| `yield_quantity` | number | Yes | >0 | "Number of units this recipe makes" |
| `yield_unit` | select | No | Default: "units" | "What does this recipe produce?" |
| `prep_time_minutes` | number | No | >0 | "Preparation time" |
| `description` | textarea | No | Max 500 chars | "Notes about this recipe" |

**Step 2 - Ingredients (List)**:
| Field | Type | Required | Validation | Help Text |
|-------|------|----------|------------|-----------|
| `ingredient_id` | select | Yes | Must exist in inventory | "Select from your inventory" |
| `quantity` | number | Yes | >0 | "Amount needed for this recipe" |
| `unit` | select | Yes | Must match ingredient unit or convertible | "Measurement unit" |
| `is_optional` | boolean | No | Default: false | "Optional or decoration ingredient" |
| `ingredient_order` | number | Auto | Auto-assigned | "Order in list" |

**Step 3 - Instructions (Optional)**:
| Field | Type | Required | Validation | Help Text |
|-------|------|----------|------------|-----------|
| `process_stages` | list | No | - | "Mixing, Proofing, Baking, etc." |
| `equipment_needed` | list | No | - | "Required equipment" |

**After Creating Recipes**:

```
┌──────────────────────────────────────────────────────┐
│  📝 Your Recipes (3 created) ✓                       │
│                                                       │
│  ┌────────────────────────────────────────────┐     │
│  │ 🥖 Baguette Francesa                       │ [⋮]  │
│  │    Bread  │  Yield: 10 units               │     │
│  │    Cost: €2.45/batch (€0.25/unit)          │     │
│  │    Ingredients: 4                          │     │
│  └────────────────────────────────────────────┘     │
│                                                       │
│  ┌────────────────────────────────────────────┐     │
│  │ 🍞 Pan de Molde                            │ [⋮]  │
│  │    Bread  │  Yield: 2 loaves               │     │
│  │    Cost: €3.20/batch (€1.60/loaf)          │     │
│  │    Ingredients: 7                          │     │
│  └────────────────────────────────────────────┘     │
│                                                       │
│  [+ Create Recipe] [Use Template]                    │
│                                                       │
│  ✅ Awesome! You've created 3 recipes                │
│     Total recipe value: €8.15                        │
│                                                       │
│  [← Back to Inventory]       [Continue to Quality →] │
└──────────────────────────────────────────────────────┘
```

**Validation**:
- **Minimum**: 1 recipe required
- **Real-time**:
  - Check ingredient availability (must be in inventory from Step 7)
  - Calculate cost as ingredients are added
  - Warn if unit mismatch (e.g., selecting grams when ingredient is in kg)
- **Business Rules**:
  - Must have ≥1 non-optional ingredient
  - Show warning if recipe uses >50% of current inventory stock

**Navigation**:
- **Continue**: Enabled when ≥1 recipe created
- **Skip**: Allowed with strong warning: "Recipes are essential for production planning. Skip anyway?"

**Backend**:
- Save recipe via `POST /api/v1/recipes/`
- For each ingredient: Save via recipe ingredients endpoint
- Mark step `recipes-setup` as completed
- Store count: `{recipes_added: 3, total_cost_value: 8.15}`

**Smart Features**:
- **Auto-Cost Calculation**: Real-time cost per batch and per unit
- **Unit Converter**: "Convert quantity" button for different units
- **Duplicate Recipe**: "Copy and modify" for variations
- **Ingredient Substitutions**: "Add substitution" for alternative ingredients

---

#### **Step 9: Define Quality Standards** (`quality-setup`)
**Purpose**: Set up quality checks for production monitoring

**User Job**: *"Define quality standards so my team knows what checks to perform and the system can track quality metrics"*

**Why This Step**:
> "Quality checks ensure consistent output and help you identify issues early. Define what 'good' looks like for each stage of production."

**What Users Need to Add**: Minimum 2 quality checks (recommended 5-8 across stages)

**Form Type**: **Wizard-Enhanced List with Stage Selection**

**UI Flow**:

```
┌──────────────────────────────────────────────────────┐
│  Step 5 of 7: Define Quality Standards               │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  ✅ Quality Checks                                    │
│  Standards for consistent production                 │
│                                                       │
│  [===================================>] 86% Complete │
│                                                       │
│  ┌──────────────────────────────────────────────┐   │
│  │  Why This Matters                            │   │
│  │  ─────────────────────────────────────────── │   │
│  │  Quality tracking helps you:                 │   │
│  │  • Maintain consistent product standards     │   │
│  │  • Train new team members                    │   │
│  │  • Identify production issues early          │   │
│  │  • Track quality metrics over time           │   │
│  └──────────────────────────────────────────────┘   │
│                                                       │
│  ┌──────────────────────────────────────────────┐   │
│  │  📝 Quality Checks (2 min required, 5 ideal) │   │
│  │                                               │   │
│  │  [+ Add Quality Check] [Use Template Set]    │   │
│  │                                               │   │
│  │  (Empty state)                                │   │
│  │  "Define checks for key production stages"   │   │
│  └──────────────────────────────────────────────┘   │
│                                                       │
│  💡 Quick Start: Use our template set of common      │
│     quality checks for bakeries. Customize after.    │
│                                                       │
│  [← Back to Recipes]              [Skip] [Continue →]│
│  (disabled until 2 checks added)                     │
└──────────────────────────────────────────────────────┘
```

**Quality Template Set**:

```
┌──────────────────────────────────────────────────────┐
│  ✕ Add Quality Check Template Set                    │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  We'll add common quality checks for each production │
│  stage. You can edit or remove any check.            │
│                                                       │
│  Mixing Stage:                                       │
│  ☑️ Dough temperature (18-24°C)                      │
│  ☑️ Dough consistency (smooth, elastic)              │
│                                                       │
│  Proofing Stage:                                     │
│  ☑️ Dough volume (doubled in size)                   │
│  ☑️ Proofing time (60-90 min)                        │
│                                                       │
│  Baking Stage:                                       │
│  ☑️ Internal temperature (95-98°C for bread)         │
│  ☑️ Crust color (golden brown)                       │
│                                                       │
│  Cooling Stage:                                      │
│  ☑️ Cooling time (30-45 min before packaging)        │
│                                                       │
│  Final Product:                                      │
│  ☑️ Weight (within 5% of target)                     │
│  ☑️ Visual inspection (no defects)                   │
│                                                       │
│  [Deselect All] [Cancel]      [Add Selected (9) →]   │
└──────────────────────────────────────────────────────┘
```

**Manual Add Quality Check**:

```
┌──────────────────────────────────────────────────────┐
│  ✕ Add Quality Check                                 │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  Check Information                                   │
│  ────────────────────────────────────────────────    │
│  Check Name *                                        │
│  [_____________________________________________]      │
│   e.g., "Dough temperature", "Crust color"            │
│                                                       │
│  Description                                         │
│  [_____________________________________________]      │
│   What to check and why                              │
│                                                       │
│  Production Stage *                                  │
│  [☑️ Mixing] [☑️ Proofing] [☑️ Baking] [☑️ Cooling]  │
│   (Select all stages where this check applies)       │
│                                                       │
│  Check Type *                                        │
│  [▼ Select type_______________________]              │
│      ├─ Visual Inspection                            │
│      ├─ Temperature Measurement                      │
│      ├─ Weight Measurement                           │
│      ├─ Time Tracking                                │
│      ├─ Yes/No Check                                 │
│      └─ Numeric Range                                │
│                                                       │
│  ▼ Pass Criteria (appears based on check type)      │
│  ────────────────────────────────────────────────    │
│  [For Temperature: Min/Max range fields]             │
│  [For Visual: Description of acceptable appearance]  │
│  [For Weight: Target weight ± tolerance]             │
│                                                       │
│  Priority                                            │
│  ( ) Critical  ( ) Important  (•) Standard           │
│                                                       │
│  [Cancel]             [Add Another] [Save & Done →]  │
└──────────────────────────────────────────────────────┘
```

**Fields**:

| Field | Type | Required | Validation | Help Text |
|-------|------|----------|------------|-----------|
| `name` | text | Yes | Min 3 chars | "Short name for this check" |
| `description` | textarea | No | Max 500 chars | "What to check and why it matters" |
| `production_stages` | multi-select | Yes | ≥1 stage | "When to perform this check" |
| `check_type` | select | Yes | Must select | "How to measure this quality aspect" |
| `pass_criteria` | varies | Conditional | Depends on type | "What defines a pass" |
| `priority` | select | No | Default: Standard | "Critical, Important, or Standard" |

**After Adding Quality Checks**:

```
┌──────────────────────────────────────────────────────┐
│  📝 Your Quality Checks (7 added) ✓                  │
│                                                       │
│  Group by: [Stage ▼]                                 │
│                                                       │
│  🔧 Mixing (2 checks)                                │
│  ┌────────────────────────────────────────────┐     │
│  │ 🌡️ Dough Temperature                        │ [⋮]  │
│  │    Range: 18-24°C  │  Priority: Critical    │     │
│  └────────────────────────────────────────────┘     │
│  ┌────────────────────────────────────────────┐     │
│  │ ✋ Dough Consistency                        │ [⋮]  │
│  │    Visual check  │  Priority: Important     │     │
│  └────────────────────────────────────────────┘     │
│                                                       │
│  🍞 Baking (3 checks)                                │
│  [... more checks ...]                               │
│                                                       │
│  [+ Add Check] [Use Template]                        │
│                                                       │
│  ✅ Great! You've defined 7 quality standards        │
│                                                       │
│  [← Back to Recipes]            [Continue to Team →] │
└──────────────────────────────────────────────────────┘
```

**Validation**:
- **Minimum**: 2 checks required
- **Business Rules**:
  - Recommend at least one "Critical" check
  - Warn if no checks for "Baking" stage (common oversight)

**Navigation**:
- **Continue**: Enabled when ≥2 checks added
- **Skip**: Allowed (quality is important but not blocking for basic operations)

**Backend**:
- Save via `POST /api/v1/quality-templates/`
- Mark step `quality-setup` as completed
- Store count: `{quality_checks_added: 7, critical_checks: 2}`

---

### PHASE 4: TEAM & FINALIZATION (Optional but Recommended)

#### **Step 10: Add Team Members** (`team-setup`)
**Purpose**: Set up user accounts for bakery staff

**User Job**: *"Add my team so they can access the system and we can coordinate work"*

**Why This Step**:
> "Adding team members allows you to assign tasks, track who does what, and give everyone the tools they need to work efficiently."

**What Users Need to Add**: Optional (0-10 team members)

**Form Type**: **Simple List Entry (Invite-Based)**

**UI Flow**:

```
┌──────────────────────────────────────────────────────┐
│  Step 6 of 7: Add Team Members (Optional)            │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  👥 Team                                              │
│  Your bakery staff                                   │
│                                                       │
│  [========================================] 93% Complete│
│                                                       │
│  ┌──────────────────────────────────────────────┐   │
│  │  Why This Matters                            │   │
│  │  ─────────────────────────────────────────── │   │
│  │  Team access enables:                        │   │
│  │  • Task assignment & coordination            │   │
│  │  • Production tracking by person             │   │
│  │  • Quality check accountability              │   │
│  │  • Permission-based access control           │   │
│  └──────────────────────────────────────────────┘   │
│                                                       │
│  ┌──────────────────────────────────────────────┐   │
│  │  📝 Team Members (Optional)                  │   │
│  │                                               │   │
│  │  [+ Invite Team Member]                      │   │
│  │                                               │   │
│  │  (Empty state)                                │   │
│  │  "Invite your staff to collaborate"          │   │
│  └──────────────────────────────────────────────┘   │
│                                                       │
│  💡 You can add team members later from Settings.    │
│     Skip this step if you're the only user for now.  │
│                                                       │
│  [← Back to Quality]      [Skip This Step] [Continue →]│
│  (always enabled - this step is optional)            │
└──────────────────────────────────────────────────────┘
```

**Invite Team Member Modal**:

```
┌──────────────────────────────────────────────────────┐
│  ✕ Invite Team Member                                │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  Member Information                                  │
│  ────────────────────────────────────────────────    │
│  Name *                                              │
│  [_____________________________________________]      │
│                                                       │
│  Email *                                             │
│  [_____________________________________________]      │
│   They'll receive an invitation to join             │
│                                                       │
│  Role *                                              │
│  [▼ Select role_______________________]              │
│      ├─ Baker (can view & record production)         │
│      ├─ Manager (can edit recipes & inventory)       │
│      └─ Admin (full access)                          │
│                                                       │
│  [Cancel]              [Send Invitation →]           │
└──────────────────────────────────────────────────────┘
```

**After Adding Team**:

```
│  📝 Team Members (3 invited) ✓                       │
│                                                       │
│  ┌────────────────────────────────────────────┐     │
│  │ 👤 María García                            │ [⋮]  │
│  │    maria@bakery.com  │  Role: Manager      │     │
│  │    Status: Invitation sent                 │     │
│  └────────────────────────────────────────────┘     │
│                                                       │
│  [... more team members ...]                         │
```

**Validation**: None (optional step)

**Navigation**:
- **Continue**: Always enabled
- **Skip**: Always allowed

**Backend**:
- Send invitation via `POST /api/v1/team/invitations/`
- Mark step `team-setup` as completed
- Store count: `{team_invitations_sent: 3}`

---

#### **Step 11: Review & Launch** (`setup-completion`)
**Purpose**: Celebrate completion and show what's now possible

**User Job**: *"Verify I've set everything up correctly and start using the system"*

**Why This Step**:
> "You're ready to go! Let's review what you've set up and show you what's now available."

**UI Flow**:

```
┌──────────────────────────────────────────────────────┐
│  Step 7 of 7: You're All Set! 🎉                     │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  ✅ Setup Complete                                    │
│  Your bakery system is ready                         │
│                                                       │
│  [=========================================>] 100%    │
│                                                       │
│  ┌──────────────────────────────────────────────┐   │
│  │  🎊 Congratulations!                         │   │
│  │  ─────────────────────────────────────────── │   │
│  │  Your bakery management system is fully      │   │
│  │  configured and ready to help you run your   │   │
│  │  operations more efficiently.                │   │
│  └──────────────────────────────────────────────┘   │
│                                                       │
│  📊 Setup Summary                                    │
│  ────────────────────────────────────────────────    │
│  ✅ 2 Suppliers added                                │
│  ✅ 12 Inventory items set up                        │
│  ✅ 3 Recipes created (Total value: €8.15)           │
│  ✅ 7 Quality checks defined                         │
│  ✅ 3 Team members invited                           │
│                                                       │
│  🎯 What You Can Do Now                              │
│  ────────────────────────────────────────────────    │
│  ┌──────────────────────────────────────────┐       │
│  │ 📦 Track Inventory                       │ [→]   │
│  │    Real-time stock levels & alerts       │       │
│  └──────────────────────────────────────────┘       │
│  ┌──────────────────────────────────────────┐       │
│  │ 👨‍🍳 Create Production Orders              │ [→]   │
│  │    Plan daily baking with your recipes   │       │
│  └──────────────────────────────────────────┘       │
│  ┌──────────────────────────────────────────┐       │
│  │ 💰 Analyze Costs & Profitability         │ [→]   │
│  │    See exact costs per recipe            │       │
│  └──────────────────────────────────────────┘       │
│  ┌──────────────────────────────────────────┐       │
│  │ 📈 View AI Forecasts                     │ [→]   │
│  │    Demand predictions for your products  │       │
│  └──────────────────────────────────────────┘       │
│                                                       │
│  💡 Quick Start Guide                                │
│  ────────────────────────────────────────────────    │
│  [📘 View Tutorial] [❓ Watch Demo Video]            │
│                                                       │
│  [← Back to Team]            [Go to Dashboard →]     │
└──────────────────────────────────────────────────────┘
```

**Validation**: None (review step)

**Navigation**:
- **Continue**: Go to dashboard (system fully operational)

**Backend**:
- Mark step `setup-completion` as completed
- Set overall onboarding status to "completed"
- Trigger: Send welcome email with quick start guide

---

## Progress Tracking & Navigation

### Overall Progress Indicator

**Visual Design** (appears at top of every step):

```
[====================>----------] 57% Complete
Step 3 of 7: Set Up Inventory Items
```

**Progress Calculation**:
```typescript
// Weight steps by estimated complexity/time
const STEP_WEIGHTS = {
  'setup-welcome': 5,        // 2 min (light)
  'suppliers-setup': 10,     // 5 min (moderate)
  'inventory-items-setup': 20, // 10 min (heavy)
  'recipes-setup': 20,       // 10 min (heavy)
  'quality-setup': 15,       // 7 min (moderate)
  'team-setup': 10,          // 5 min (optional)
  'setup-completion': 5      // 2 min (light)
};

const totalWeight = Object.values(STEP_WEIGHTS).reduce((a, b) => a + b);

function calculateProgress(currentStepIndex: number, completedSteps: string[]): number {
  let completedWeight = 0;

  // Add weight of fully completed steps
  completedSteps.forEach(stepId => {
    completedWeight += STEP_WEIGHTS[stepId] || 0;
  });

  // Add 50% of current step weight (user is midway through)
  const currentStepId = STEPS[currentStepIndex].id;
  completedWeight += (STEP_WEIGHTS[currentStepId] || 0) * 0.5;

  return Math.round((completedWeight / totalWeight) * 100);
}
```

### Step Navigation States

**Continue Button States**:

| Step | Enable Condition | Button Text | Behavior |
|------|------------------|-------------|----------|
| Welcome | Always | "Let's Get Started →" | Navigate to Step 6 |
| Suppliers | ≥1 supplier added | "Continue to Inventory →" | Navigate to Step 7 |
| Inventory | ≥3 items added | "Continue to Recipes →" | Navigate to Step 8 |
| Recipes | ≥1 recipe created | "Continue to Quality →" | Navigate to Step 9 |
| Quality | ≥2 checks added | "Continue to Team →" | Navigate to Step 10 |
| Team | Always (optional) | "Continue to Review →" | Navigate to Step 11 |
| Completion | Always | "Go to Dashboard →" | Exit wizard → Dashboard |

**Back Button Behavior**:
- Always visible (except on Step 5)
- Goes to previous step WITHOUT losing data (data is saved on each step completion)
- Disabled during save operations

**Skip Button**:
- Visible on Steps 5, 9, 10, 11 (optional/skippable steps)
- Shows confirmation dialog: "Are you sure you want to skip [Step Name]? You can set this up later from Settings."
- On confirm: Marks step as "skipped" (not "completed") and advances

### Mobile Navigation Patterns

**Small Screens (<640px)**:
- Progress bar: Full width, height: 8px
- Step title: Larger font (18px)
- Buttons: Stacked vertically
- Step indicators: Horizontal scroll

```
[========>------] 43%

📦 Inventory Items
Step 3 of 7

[Main content...]

[← Back       ]
[Skip This Step]
[Continue →    ]
```

**Desktop (≥640px)**:
- Progress bar: Full width, height: 12px
- Buttons: Horizontal layout
- Step indicators: All visible

### Save Progress & Resume Later

**Auto-Save Behavior**:
- Each entity added is immediately saved to backend
- Step is marked "completed" when user clicks Continue
- If user closes browser mid-step, data is preserved but step not marked complete

**Resume Behavior**:
```typescript
function determineResumeStep(userProgress: UserProgress): number {
  // Find first incomplete step
  for (let i = 0; i < SETUP_STEPS.length; i++) {
    const step = SETUP_STEPS[i];
    const stepProgress = userProgress.steps.find(s => s.step_name === step.id);

    if (!stepProgress?.completed && stepProgress?.status !== 'skipped') {
      return i; // Resume here
    }
  }

  // All steps complete → go to last step (completion)
  return SETUP_STEPS.length - 1;
}
```

**Resume Entry Point**:
- Dashboard shows "Complete Setup" banner if wizard not finished
- Banner shows: "You're 57% done! Continue setting up →"
- Click banner → Resume at first incomplete step

### Exit Points & Persistence

**User Can Exit At Any Time**:
1. Click browser back button
2. Click dashboard link in sidebar
3. Close browser tab

**On Exit (Not Completed)**:
- All data entered so far is saved
- Progress tracked in backend (`user_progress` table)
- Dashboard shows persistent banner: "Complete your setup to unlock all features"

**Re-Entry**:
- User clicks "Complete Setup" from dashboard
- System loads user progress and resumes at correct step
- Previously entered data is loaded (suppliers, inventory, recipes, etc.)

---

## Validation & Error Handling

### Real-Time Validation Strategy

**Field-Level Validation**:
- Trigger: `onChange` (debounced 300ms for text inputs)
- Display: Inline error message below field
- State: Field border turns red, error icon appears

**Example**:
```typescript
// Supplier name field
const [nameError, setNameError] = useState<string | null>(null);

const validateName = debounce((value: string) => {
  if (value.length < 2) {
    setNameError("Supplier name must be at least 2 characters");
    return false;
  }

  // Check for duplicates (async)
  checkDuplicateSupplier(value).then(isDuplicate => {
    if (isDuplicate) {
      setNameError("A supplier with this name already exists");
    } else {
      setNameError(null);
    }
  });

  return true;
}, 300);
```

**Cross-Field Validation**:
- Trigger: When dependent field changes
- Example: `reorder_point` must be ≤ `low_stock_threshold`

```typescript
function validateInventoryItem(item: InventoryItemForm): ValidationErrors {
  const errors: ValidationErrors = {};

  if (item.reorder_point && item.low_stock_threshold) {
    if (item.reorder_point > item.low_stock_threshold) {
      errors.reorder_point = "Reorder point must be less than or equal to low stock threshold";
    }
  }

  return errors;
}
```

**Step-Level Validation**:
- Trigger: When user clicks "Continue"
- Validates all requirements for current step
- If validation fails: Show error summary, scroll to first error

### Error Message Patterns

**Tone**: Helpful, not judgmental

| Error Type | Bad Message | Good Message |
|------------|-------------|--------------|
| Required field | "This field is required" | "Please enter a supplier name to continue" |
| Format error | "Invalid email" | "Please enter a valid email address (e.g., name@bakery.com)" |
| Duplicate | "Duplicate entry" | "You already have a supplier named 'Molinos'. Try a different name." |
| Dependency | "Dependency not met" | "Please add at least 3 inventory items before creating recipes" |

**Visual Pattern**:
```
┌────────────────────────────────────────┐
│  ⚠️ Please fix these issues:           │
│  ────────────────────────────────────  │
│  • Supplier name is required           │
│  • Email format is invalid             │
│                                        │
│  [Fix Issues]                          │
└────────────────────────────────────────┘
```

### Preventing Invalid States

**Dependency Enforcement**:
1. **Suppliers before Inventory**: Can't assign supplier to inventory item if no suppliers exist
   - Solution: Show "Add supplier" link inline in inventory form

2. **Inventory before Recipes**: Can't select ingredients if no inventory items exist
   - Solution: Wizard step order enforces this naturally

3. **No Empty Steps**: Can't mark step complete if minimum requirements not met
   - Solution: Disable "Continue" button until requirements met

**Business Rule Validation**:
```typescript
// Inventory item validation
function validateInventorySetup(items: InventoryItem[]): ValidationWarning[] {
  const warnings: ValidationWarning[] = [];

  // Warn if no flour (common for bakeries)
  const hasFlour = items.some(item =>
    item.category === 'flour_grains' ||
    item.name.toLowerCase().includes('flour')
  );

  if (!hasFlour) {
    warnings.push({
      severity: 'warning',
      message: "Most bakeries use flour. Did you mean to skip it?",
      action: "Add flour items",
      onAction: () => openAddItemModal({ category: 'flour_grains' })
    });
  }

  return warnings;
}
```

### Error Recovery Strategies

**Network Errors**:
- Retry failed requests automatically (max 3 attempts)
- Show toast: "Connection lost. Retrying..."
- If all retries fail: Show error with "Try Again" button

**Validation Errors**:
- Highlight all invalid fields
- Show summary of errors at top of form
- Scroll to first error
- Provide "Fix for me" suggestions where possible

**Example Recovery UI**:
```
┌────────────────────────────────────────┐
│  ❌ Couldn't save supplier             │
│                                        │
│  Network connection lost. Your data   │
│  is safe - we'll try again.           │
│                                        │
│  [Try Again] [Continue Offline]       │
└────────────────────────────────────────┘
```

---

## Smart Features

### 1. Intelligent Templates

**Starter Template for Inventory**:
- Pre-populated with 25 common bakery ingredients
- Categorized (Flour & Grains, Dairy, Sweeteners, etc.)
- Suggested units and typical low stock thresholds
- User can select which to import

**Recipe Templates**:
- Library of 15+ common recipes (baguette, white bread, croissant, muffins, etc.)
- User selects template → System maps template ingredients to user's inventory
- If ingredient missing: Prompt to add it or substitute

**Quality Check Templates**:
- Pre-configured checks for each production stage
- Based on industry best practices
- User can enable/disable individual checks

### 2. Auto-Suggestions & Smart Defaults

**Category Auto-Detection** (ML-powered):
```typescript
function suggestCategory(itemName: string): string {
  // ML model trained on bakery inventory data
  const prediction = categoryModel.predict(itemName);

  // Examples:
  // "harina" → "flour_grains"
  // "azúcar" → "sweeteners"
  // "leche" → "dairy_eggs"

  return prediction.category;
}
```

**Supplier Recommendations**:
- When adding inventory item, suggest supplier based on item category
- "Flour items usually come from: [Molinos del Norte ▼]"

**Unit Conversion Helper**:
```
Adding: Harina de trigo (1000g)
💡 Tip: 1000g = 1kg. Switch to kilograms? [Yes] [No]
```

**Cost Estimation**:
- If user doesn't know ingredient cost, suggest typical market price
- "Average cost for flour in Spain: €0.60-0.80/kg"

### 3. Bulk Import & Export

**CSV/Excel Import**:
- Upload spreadsheet → Map columns → Import in bulk
- Template downloadable: "Download sample spreadsheet"
- Validation before import: "Found 12 items, 2 have errors. Fix them?"

**Supported Entities**:
- Suppliers (name, type, contact, email, phone)
- Inventory Items (name, category, unit, supplier, cost, stock levels)
- Recipes (name, category, yield + separate ingredient list)

### 4. Contextual Help System

**Help Tooltips**:
- (?) icon next to complex fields
- Hover/click to see explanation

```
Low Stock Threshold (?)
────────────────────────
When inventory falls below this level,
you'll receive an alert to reorder.

Recommended: 2-3 weeks of typical usage

Example: If you use 50kg flour per week,
set threshold to 100-150kg
```

**Video Tutorials**:
- Embedded 30-60 second videos for complex steps
- "Watch how to create a recipe (45 sec)"

**Inline Examples**:
- Every field shows example value
- "e.g., Molinos del Norte" for supplier name
- "e.g., 1.5" for recipe ingredient quantity

### 5. Progress Celebrations & Motivation

**Milestone Animations**:
- When reaching 25%, 50%, 75% completion: Brief confetti animation
- "Great progress! You're halfway there! 🎉"

**Step Completion Feedback**:
- After each step: Success message with positive reinforcement
- "✅ Excellent! You've added 3 recipes. Your bakery is taking shape!"

**Comparison to Others** (Optional):
- "Most bakeries add 10-15 inventory items. You've added 12 - right on track!"

### 6. Intelligent Validation Warnings (Non-Blocking)

**Soft Warnings** (shown but don't prevent progress):
```
⚠️ Heads up!
You haven't set a cost for "Harina de trigo".
Recipe costing won't be accurate until you add it.

[Add Cost Now] [I'll Do It Later]
```

**Proactive Suggestions**:
```
💡 Suggestion
You've added "Baguette" recipe. Want to add a
"Whole Wheat Baguette" variation? We can copy
the recipe and you just adjust the flour.

[Create Variation] [No Thanks]
```

---

## Technical Implementation Notes

### Component Architecture

**Proposed Structure**:
```
frontend/src/components/domain/setup-wizard/
├── SetupWizard.tsx                    # Main wizard component (similar to OnboardingWizard)
├── steps/
│   ├── WelcomeStep.tsx
│   ├── SuppliersSetupStep.tsx
│   ├── InventorySetupStep.tsx
│   ├── RecipesSetupStep.tsx
│   ├── QualitySetupStep.tsx
│   ├── TeamSetupStep.tsx
│   └── CompletionStep.tsx
├── components/
│   ├── StepProgress.tsx               # Progress bar & indicators
│   ├── StepNavigation.tsx             # Back/Skip/Continue buttons
│   ├── AddEntityModal.tsx             # Generic modal for adding items
│   ├── TemplateSelector.tsx           # Template gallery
│   └── EntityList.tsx                 # List view for added items
└── hooks/
    ├── useSetupProgress.ts
    ├── useStepValidation.ts
    └── useAutoSave.ts
```

### Reusing Existing Patterns

**From OnboardingWizard**:
- Step configuration structure (`StepConfig` interface)
- Progress tracking (`useUserProgress` hook)
- Step completion (`useMarkStepCompleted` mutation)
- Step navigation logic
- Mobile/desktop responsive design
- Progress percentage calculation

**From AddModal**:
- Field configuration (`AddModalField` interface)
- Section-based organization
- ListFieldRenderer for managing collections
- Validation infrastructure
- Loading states & success animations

**Integration Strategy**:
```typescript
// Extend existing StepConfig to support setup wizard steps
interface SetupStepConfig extends StepConfig {
  id: string;
  title: string;
  description: string;
  component: React.ComponentType<SetupStepProps>;
  minRequired?: number;           // Minimum items to proceed
  isOptional?: boolean;           // Can be skipped
  estimatedMinutes?: number;      // For progress calculation
  dependencies?: string[];        // Step IDs that must be complete first
}
```

### Backend API Requirements

**New Endpoints Needed**:
```typescript
// Setup-specific progress tracking
GET  /api/v1/onboarding/progress/:userId?type=setup
POST /api/v1/onboarding/steps/:stepName/complete

// Bulk operations
POST /api/v1/inventory/ingredients/bulk           // Bulk create from template
POST /api/v1/quality-templates/bulk               // Bulk create checks
POST /api/v1/inventory/ingredients/import         // CSV import

// Templates
GET  /api/v1/templates/inventory-starter          // Get starter inventory
GET  /api/v1/templates/recipes/:category          // Get recipe templates
GET  /api/v1/templates/quality-checks             // Get quality check templates

// Smart suggestions
POST /api/v1/ml/suggest-category                  // ML category suggestion
GET  /api/v1/market-data/average-prices           // Average ingredient prices
```

**Existing Endpoints to Use**:
```typescript
// Already available
POST /api/v1/suppliers/
POST /api/v1/inventory/ingredients/
POST /api/v1/recipes/
POST /api/v1/quality-templates/
POST /api/v1/team/invitations/
```

### State Management

**Setup Wizard State**:
```typescript
interface SetupWizardState {
  currentStepIndex: number;
  completedSteps: string[];
  skippedSteps: string[];
  stepData: {
    [stepId: string]: {
      itemsAdded: number;
      totalValue?: number;
      completedAt?: string;
      // Step-specific data
    };
  };
  isInitialized: boolean;
  progressPercentage: number;
}
```

**Persisted State** (in backend):
```sql
-- user_progress table (already exists)
user_id: UUID
current_step: VARCHAR  -- e.g., "inventory-items-setup"
completion_percentage: INTEGER
steps: JSONB           -- Array of step progress objects
completed_at: TIMESTAMP (nullable)

-- step progress object structure
{
  "step_name": "suppliers-setup",
  "completed": true,
  "skipped": false,
  "completed_at": "2025-11-06T10:30:00Z",
  "data": {
    "suppliers_added": 2,
    "used_template": false
  }
}
```

### Performance Considerations

**Lazy Loading**:
- Load step components on-demand (React.lazy)
- Preload next step component in background

**Optimistic Updates**:
- Show success immediately, sync in background
- If sync fails, rollback with notification

**Caching**:
- Cache supplier/inventory lists in React Query
- Invalidate on mutations

**Debouncing**:
- Search/filter operations: 300ms debounce
- Validation: 300ms debounce for text inputs
- Auto-save draft: 1000ms debounce

### Accessibility (a11y)

**Keyboard Navigation**:
- Tab order: Top to bottom, left to right
- Enter: Submit form/Continue
- Esc: Close modal
- Arrow keys: Navigate step indicators

**Screen Reader Support**:
```tsx
<div role="progressbar" aria-valuenow={57} aria-valuemin={0} aria-valuemax={100}>
  Step 3 of 7: Set Up Inventory Items (57% complete)
</div>

<button
  aria-label="Continue to Recipes step"
  disabled={!canContinue}
  aria-disabled={!canContinue}
>
  Continue →
</button>
```

**Focus Management**:
- When step changes: Focus on step title
- When modal opens: Focus on first input
- When error: Focus on first invalid field

### Internationalization (i18n)

**Translation Keys**:
```json
{
  "setup_wizard": {
    "steps": {
      "welcome": {
        "title": "Welcome & Setup Overview",
        "description": "Let's set up your bakery operations",
        ...
      },
      "suppliers": {
        "title": "Add Suppliers",
        "description": "Your ingredient and material providers",
        "min_required": "Add at least {{count}} supplier to continue",
        ...
      }
    },
    "navigation": {
      "back": "Back",
      "skip": "Skip This Step",
      "continue": "Continue",
      ...
    }
  }
}
```

---

## Success Metrics

### Leading Indicators (During Wizard)

**Completion Rate**:
- **Metric**: % of users who complete all 7 steps
- **Target**: ≥80% completion rate
- **Measurement**: `(users_completed / users_started) * 100`

**Drop-Off Points**:
- **Metric**: Where users abandon the wizard
- **Target**: No single step has >15% drop-off
- **Measurement**: Track step entry vs. step completion

**Time to Complete**:
- **Metric**: Average time from Step 5 to Step 11
- **Target**: 15-25 minutes (matches estimate)
- **Measurement**: `completion_timestamp - start_timestamp`

**Data Quality Score**:
- **Metric**: % of records with complete, valid data
- **Target**: ≥90% of entities have all required + recommended fields
- **Calculation**:
```typescript
function calculateDataQuality(entity: any): number {
  const requiredFields = entity.requiredFields.filter(f => !!entity[f]);
  const optionalFields = entity.optionalFields.filter(f => !!entity[f]);

  return (requiredFields.length + (optionalFields.length * 0.5)) /
         (entity.requiredFields.length + entity.optionalFields.length);
}
```

**Template Usage Rate**:
- **Metric**: % of users who use starter templates
- **Target**: ≥60% use at least one template
- **Hypothesis**: Templates speed up setup and improve data quality

### Lagging Indicators (Post-Wizard)

**Feature Adoption Rate**:
- **Metric**: % of completed users actively using core features within 7 days
- **Features**: Inventory tracking, recipe costing, production planning, quality checks
- **Target**: ≥70% use ≥2 features weekly

**System Reliance**:
- **Metric**: Daily active usage frequency
- **Target**: ≥5 days per week for production-focused users
- **Measurement**: DAU/MAU ratio

**User Satisfaction** (NPS):
- **Metric**: Net Promoter Score for setup experience
- **Survey**: "How likely are you to recommend this setup process?" (0-10)
- **Target**: NPS ≥40

**Time to First Value**:
- **Metric**: Days from registration to first meaningful action (e.g., create production order, record sale)
- **Target**: ≤3 days (with wizard) vs. 7-10 days (without)

**Support Ticket Reduction**:
- **Metric**: "How do I..." support tickets related to setup
- **Target**: 50% reduction vs. previous un-guided experience

### Business Impact (Long-term)

**Operational Efficiency**:
- **Metric**: Waste reduction (% decrease in spoilage/overstock)
- **Target**: 15-20% reduction in first 3 months
- **Attribution**: Users with complete setup vs. incomplete

**Cost Visibility**:
- **Metric**: % of users who can accurately report per-recipe costs
- **Target**: 100% of users with recipes can see cost breakdowns
- **Value**: Enables pricing decisions, profitability analysis

**Quality Consistency**:
- **Metric**: Quality check compliance rate
- **Target**: ≥80% of production runs have quality checks recorded
- **Attribution**: Users who defined quality standards in wizard

### A/B Testing Opportunities

**Test Variations**:

1. **Template vs. Manual Entry**
   - A: Show templates prominently (current design)
   - B: Manual entry default, templates as optional
   - Hypothesis: Templates increase completion rate & speed

2. **Step Granularity**
   - A: 7 steps (current design)
   - B: 4 steps (combine some steps)
   - Hypothesis: Fewer steps reduce cognitive load, increase completion

3. **Progress Celebration**
   - A: Milestone animations + messages (current design)
   - B: No celebrations, just progress bar
   - Hypothesis: Celebrations increase motivation & completion

4. **Skip vs. No-Skip for Optional Steps**
   - A: Allow skipping Team & Quality steps
   - B: Encourage completion ("3 more minutes to 100%")
   - Hypothesis: Encouraging completion increases feature adoption

### Tracking Implementation

**Analytics Events**:
```typescript
// Track key events
analytics.track('setup_wizard_started', {
  user_id, timestamp
});

analytics.track('setup_step_completed', {
  user_id, step_id, items_added, duration_seconds, used_template
});

analytics.track('setup_step_skipped', {
  user_id, step_id, reason
});

analytics.track('setup_wizard_completed', {
  user_id, total_duration, suppliers_count, inventory_count, recipes_count,
  quality_checks_count, team_count, used_templates_count
});

analytics.track('setup_wizard_abandoned', {
  user_id, last_step_id, completion_percentage, duration
});
```

**Dashboard Metrics**:
```
Setup Wizard Performance
─────────────────────────
Completion Rate:      82% ✓ (target: 80%)
Avg. Time:            18 min ✓ (target: 15-25 min)
Drop-off Points:      Step 7 (Inventory): 12% ✓

Data Quality Score:   91% ✓ (target: 90%)

Template Usage:       68% ✓ (target: 60%)
  - Inventory starter: 55%
  - Recipe templates:  42%
  - Quality checks:    71%

Feature Adoption (7 days post-setup):
  - Inventory tracking:   78%
  - Recipe costing:       65%
  - Production planning:  52%
  - Quality monitoring:   48%
```

---

## Implementation Roadmap

### Phase 1: Foundation (Week 1-2)
- [ ] Create SetupWizard component structure
- [ ] Implement step navigation & progress tracking
- [ ] Integrate with existing OnboardingWizard
- [ ] Build StepProgress and StepNavigation components
- [ ] Set up backend endpoints for step completion

### Phase 2: Core Steps (Week 3-5)
- [ ] Implement Welcome Step (Step 5)
- [ ] Implement Suppliers Setup Step (Step 6)
- [ ] Implement Inventory Setup Step (Step 7)
- [ ] Implement Recipes Setup Step (Step 8)
- [ ] Add real-time validation for each step

### Phase 3: Advanced Features (Week 6-7)
- [ ] Implement Quality Setup Step (Step 9)
- [ ] Implement Team Setup Step (Step 10)
- [ ] Implement Completion Step (Step 11)
- [ ] Add template systems (inventory, recipes, quality)
- [ ] Implement bulk import functionality

### Phase 4: Polish & Smart Features (Week 8)
- [ ] Add contextual help & tooltips
- [ ] Implement auto-suggestions (ML category detection)
- [ ] Add celebration animations & milestone feedback
- [ ] Optimize performance (lazy loading, caching)
- [ ] Complete i18n translations

### Phase 5: Testing & Iteration (Week 9-10)
- [ ] User testing with 10-15 bakery owners
- [ ] Fix issues identified in testing
- [ ] A/B test setup (template vs. manual entry)
- [ ] Set up analytics tracking
- [ ] Write documentation & tutorial content

### Phase 6: Launch & Monitor (Week 11+)
- [ ] Soft launch to 10% of new users
- [ ] Monitor metrics & gather feedback
- [ ] Iterate based on data
- [ ] Full rollout to all users
- [ ] Ongoing optimization

---

## Appendix: Open Questions & Decisions Needed

### Design Decisions

1. **Should we allow users to edit data from previous steps within the wizard?**
   - Option A: Yes, "Edit" button on each step summary
   - Option B: No, must exit wizard and use normal UI
   - Recommendation: Option A (better UX, keeps users in flow)

2. **How do we handle users who want to skip the entire wizard?**
   - Option A: Allow full skip, but show persistent "Incomplete Setup" banner
   - Option B: Require minimum critical path (Steps 6-8)
   - Recommendation: Option B (ensures system can function)

3. **Should recipe templates include quantities, or just ingredient lists?**
   - Option A: Full recipes with quantities (more helpful, but may not match user's scale)
   - Option B: Just ingredient lists (user fills in quantities)
   - Recommendation: Option A with prominent "Adjust quantities to your batch size" notice

4. **What happens if a user creates an entity outside the wizard (e.g., manually adds a supplier)?**
   - Option A: Wizard counts it toward requirements
   - Option B: Wizard doesn't recognize it, asks user to add via wizard
   - Recommendation: Option A (recognize all entities, wizard is just guided experience)

### Technical Questions

1. **Should we reuse existing modal components or create wizard-specific ones?**
   - Recommendation: Reuse AddModal architecture, extend with wizard-specific features

2. **How do we handle wizard state if user switches tenants mid-wizard?**
   - Recommendation: Save progress per tenant, allow resuming

3. **Should wizard data be saved in a separate table or use main entity tables?**
   - Recommendation: Use main entity tables (suppliers, inventory, etc.) + track progress in user_progress

4. **How do we handle concurrent edits (user opens wizard, also opens suppliers page)?**
   - Recommendation: Real-time sync via websockets or periodic polling

### Content & Messaging

1. **Tone: Professional vs. Friendly?**
   - Recommendation: Friendly but professional ("Let's set up..." not "Time to configure your database!")

2. **Spanish vs. English default?**
   - Recommendation: Detect from user's browser locale, allow language switch

3. **Should we use bakery-specific terminology throughout?**
   - Recommendation: Yes (e.g., "recipes" not "production formulas", "ingredients" not "inventory items")

---

## Document Status

**Version**: 1.0 (Initial Draft)
**Date**: 2025-11-06
**Status**: Ready for Review
**Next Steps**:
1. Review with product team
2. Validate design with UX team
3. Review technical feasibility with engineering
4. Conduct user interviews to validate JTBD assumptions
5. Create detailed wireframes/mockups
6. Begin Phase 1 implementation

**Related Documents**:
- `jtbd-analysis-inventory-setup.md` - Jobs To Be Done analysis
- `OnboardingWizard.tsx` - Existing onboarding implementation
- `AddModal.tsx` - Existing modal component architecture

**Reviewers**:
- [ ] Product Manager
- [ ] UX Designer
- [ ] Tech Lead
- [ ] Backend Engineer
- [ ] QA Lead

**Approval**: Pending

---

*End of Specification*