> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Wizard Selection Guide

> Purpose: Help developers and AI agents choose the correct wizard system for their use case.

**Purpose:** Help developers and AI agents choose the correct wizard system for their use case.

**Last Updated:** 2026-04-14

***

## Quick Decision

| I need to...                                       | Use This              | Spec                                                                  |
| -------------------------------------------------- | --------------------- | --------------------------------------------------------------------- |
| Create a multi-step **data capture form**          | Form Wizard (FW-31)   | [FW-31](../../../specs/fw/archive/FW-31-multi-step-form-wizards.md)   |
| Build a **business process** (onboarding, payroll) | Module Wizard (PF-41) | [PF-41](../../../specs/pf/specs/PF-41-configurable-module-wizards.md) |

***

## Decision Tree

```
I need a multi-step guided experience:
│
├─ Is it primarily for DATA CAPTURE?
│   │
│   ├─ YES: Does data go to form submissions?
│   │   │
│   │   ├─ YES → Use Form Wizard (FW-31)
│   │   │   └─ Enable wizard mode on a multi-page form
│   │   │
│   │   └─ NO: Does data go to module-specific tables?
│   │       │
│   │       └─ YES → Use Module Wizard (PF-41)
│   │
│   └─ NO: Is it a BUSINESS PROCESS?
│       │
│       ├─ YES: Does it need custom React components?
│       │   │
│       │   ├─ YES → Use Module Wizard (PF-41)
│       │   │
│       │   └─ NO: Can it be done with form fields only?
│       │       │
│       │       └─ YES → Use Form Wizard (FW-31)
│       │
│       └─ NO → Probably not a wizard use case
```

***

## Detailed Comparison

### Form Wizard (FW-31)

**What it is:** Multi-step mode for FW-01 forms with guided progression, step validation, and draft persistence.

**Best for:**

* ✅ Multi-page surveys with conditional sections
* ✅ Intake forms with step-by-step data collection
* ✅ Assessments that need progress tracking
* ✅ Forms where all steps are standard form fields

**Data storage:** `fw_form_submissions` table

**Key features:**

* Extends existing FW-01 multi-page forms
* Step-level validation before advancing
* Progress tracking with visual indicator
* Auto-save drafts on step transition
* Conditional step visibility based on prior answers

**Example use cases:**

* Resident intake wizard (collect demographics → medical → emergency contacts)
* Employee satisfaction survey (multiple sections)
* Compliance assessment (step through requirements)
* Application forms (personal → education → experience)

**How to create:**

1. Create a multi-page form in FW-01
2. Enable wizard mode in form settings (`wizard_config`)
3. Configure step validation and visibility conditions

***

### Module Wizard (PF-41)

**What it is:** Configurable business process wizard with custom step components, stored in `pf_wizard_templates`.

**Best for:**

* ✅ Employee onboarding (creates employee, credentials, access)
* ✅ Resident admission (creates resident record, bed assignment, intake docs)
* ✅ Payroll runs (validates, calculates, approves, submits)
* ✅ Any process that creates records in multiple module tables

**Data storage:** Module-specific tables (e.g., `hr_onboarding_instances`, `rh_admissions`)

**Key features:**

* Custom React components for complex steps
* Organization-customizable wizard templates
* System templates with cloning support
* Step registry per module
* Cross-module wizard support (Phase 3)
* Wizard marketplace for sharing templates

**Example use cases:**

* Employee onboarding (HR module) - creates employee, credentials, system access
* Resident admission (RH module) - creates resident, assigns bed, generates intake forms
* Payroll run (HR module) - validates data, calculates, gets approval, submits
* Organization setup (PF) - configures org settings, creates admin, enables modules

**How to create:**

1. Create wizard template in `pf_wizard_templates`
2. Register custom step components in module step registry
3. Create wizard page using `ModuleWizardRenderer`

***

## Side-by-Side Comparison

| Aspect                | Form Wizard (FW-31)     | Module Wizard (PF-41)   |
| --------------------- | ----------------------- | ----------------------- |
| **Primary Purpose**   | Data capture            | Business process        |
| **Data Destination**  | `fw_form_submissions`   | Module-specific tables  |
| **Step Types**        | Form fields only        | Form, Custom, Review    |
| **Custom Components** | ❌ Not supported         | ✅ Per-module registry   |
| **Org Customization** | Field configuration     | Full step customization |
| **Draft Storage**     | `wizard_progress` JSONB | Module execution tables |
| **Template System**   | Form templates (FW-01)  | `pf_wizard_templates`   |
| **Marketplace**       | ❌ Not supported         | ✅ Phase 3               |

***

## Common Mistakes

### ❌ Using Form Wizard for Business Processes

**Wrong:** Creating an FW-31 form wizard for employee onboarding

**Problem:**

* Data goes to `fw_form_submissions`, not HR tables
* Can't create employee records, credentials, system access
* No custom components for complex steps

**Solution:** Use Module Wizard (PF-41)

***

### ❌ Using Module Wizard for Simple Data Capture

**Wrong:** Building a PF-41 wizard for a satisfaction survey

**Problem:**

* Overkill for simple form data
* Requires custom step component registration
* Data needs to go to form submissions anyway

**Solution:** Use Form Wizard (FW-31)

***

### ❌ Building Custom Wizard Instead of Using Platform

**Wrong:** Creating a custom wizard component from scratch

**Problem:**

* Duplicates existing infrastructure
* Misses draft persistence, validation, progress tracking
* No organization customization support

**Solution:** Use FW-31 or PF-41 based on your needs

***

## Integration Points

### Form Wizard (FW-31) integrates with:

* FW-01 (Form Builder) - Base form infrastructure
* FW-05 (Multi-Page Forms) - Page structure
* FW-15 (Lookups) - Dynamic dropdowns
* PF-10 (Notifications) - Resume email

### Module Wizard (PF-41) integrates with:

* PF-01 (Organizations) - Multi-tenant scoping
* PF-02 (RBAC) - Permission checks
* Module step registries - Custom components
* Module data tables - Record creation

***

## Shell Selection (After Choosing FW-31 or PF-41)

Once you've decided on FW-31 or PF-41, choose the rendering shell:

### Shell Decision Tree

```text theme={null}
Using PF-41 (Module Wizard)?
│
├─ Is this actually parallel tab navigation (non-sequential)?
│   └─ Not a wizard — use tabs/segmented controls
│
├─ Should orgs customize steps via template builder?
│   └─ ModuleWizardRenderer (data-driven from pf_wizard_templates)
│
├─ Steps are hardcoded (regulatory, tightly coupled)?
│   ├─ 5+ steps, complex layout → WizardShell layout="timeline" or "sidebar"
│   ├─ 3-5 simple steps → WizardShell layout="horizontal"
│   └─ Dialog flow (≤4 steps) → DialogWizardShell
│
└─ Hybrid (some customizable, some custom components)?
    └─ ModuleWizardRenderer + registerWizardStep()
```

### Shell Quick Reference

| Shell                               | When                           | Layout                          |
| ----------------------------------- | ------------------------------ | ------------------------------- |
| `WizardShell` `layout="horizontal"` | 3-5 step full-page wizard      | Sticky header stepper           |
| `WizardShell` `layout="timeline"`   | 5+ steps, complex flows        | Vertical timeline sidebar       |
| `WizardShell` `layout="sidebar"`    | Data-heavy operational wizards | Full sidebar with progress      |
| `DialogWizardShell`                 | Short creation/entry flows     | Dialog with horizontal stepper  |
| `ModuleWizardRenderer`              | Template-driven configurable   | Auto-selects layout from config |

### Step Icons

All wizard steps SHOULD include a Lucide icon. For `WizardShell`, pass components directly via `step.icon`. For PF-41 templates, use string keys from `WIZARD_STEP_ICONS` and resolve with `resolveStepIcon()` from `@/platform/wizards`.

Common assignments: `user` (personal info), `mail` (contact), `calendar` (schedule), `briefcase` (employment), `wallet` (payment), `file-text` (documents), `shield-check` (credentials), `review` (review/summary), `complete` (success).

***

## Validation Pattern Selection

Use one validation pattern per wizard (do not mix):

* `ModuleWizardRenderer` template steps: PF-41 `validation.rules`.
* `registerWizardStep` custom steps: `StepComponentProps` (`onValidate`) for new code.
* `WizardShell` / `DialogWizardShell`: step-local `react-hook-form` validation before `onNext`.

***

## Step Naming Conventions

Prefer these standard titles for consistency: `Personal Information`, `Contact Information`, `Employment Details`, `Schedule`, `Payment Information`, `Documents`, `Credentials`, `Consent & Agreements`, `Configuration`, `Review & Submit`, `Complete`.

When a flow needs domain-specific wording, keep semantic intent equivalent (for example, `Position & Department` or `Review & Finalize`).

***

## Related Documentation

* [TERMINOLOGY.md](../../architecture/standards/TERMINOLOGY.md) - Wizard terminology definitions
* [FW-31 Spec](../../../specs/fw/archive/FW-31-multi-step-form-wizards.md) - Form Wizard specification
* [PF-41 Spec](../../../specs/pf/specs/PF-41-configurable-module-wizards.md) - Module Wizard specification
* [Clarity Analysis](./clarity-analysis.md) - Feature comparison
* [Template Selection Guide](./template-selection.md) - Choosing template types

***

**Last Updated:** 2026-05-13