> ## 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.

# Module Guided Setup

> This document describes the platform's module guided setup system: the module setup registry, per-module settings tours, optional setup wizards, and the centra…

This document describes the platform's **module guided setup** system: the module setup registry, per-module settings tours, optional setup wizards, and the central Getting Started surface.

***

## 1. Module setup registry

### Location and shape

* **File:** `src/platform/setup/module-setup-registry.ts`
* **Type:** `ModuleSetupConfig` with:
  * `moduleId: string` – e.g. `'hr'`, `'fa'`
  * `setupTourId: string | null` – tour id for the module settings page (e.g. `'hr-settings-tour'`)
  * `setupWizardRoute: string | null` – route to a setup wizard if any (e.g. `'/fa/close/setup'`)
  * `setupCompleteCheck: 'wizard' | 'settings_saved' | 'organization' | 'none'` – how to infer "setup complete" for the Getting Started card

### Helpers

* `getModuleSetupConfig(moduleId)` – config for one module
* `getAllModuleSetupConfigs()` – all configs (used by Getting Started card)
* `registerModuleSetupConfig(moduleId, patch)` – add or update a module's setup config

***

## 2. Adding a new module setup tour

1. **Create the tour definition**\
   Add a file under `src/platform/help/tours/`, e.g. `{core}-settings-tour.ts`. Use `specs/_templates/GUIDED_TOUR_TEMPLATE.md`. Define **2–7 steps** with unique `target` values (e.g. `[data-tour="hr-settings-general"]`). **Settings tours** (e.g. gr-settings, ce-settings, fa-settings, fm-settings, fw-settings, it-settings, lo-settings, rh-settings) typically use **2–3 steps**; feature tours may use 4–7 steps (hr-settings is an example with more steps).

2. **Export the tour**\
   Export from `src/platform/help/tours/index.ts`.

3. **Add `data-tour` on the settings page**\
   On the module settings page (e.g. `src/cores/hr/pages/HRSettings.tsx`), add `data-tour` attributes on the page wrapper and section cards so they match the tour step targets.

4. **Wire the tour on the settings page**
   * `const [searchParams] = useSearchParams();`
   * `const tour = useTour({ tour: yourSettingsTour, autoStart: searchParams.get('tour') === 'your-core-settings-tour' });`
   * Add `HelpButton` that calls `tour.start`.
   * Render `GuidedTour` with `tour`, `isActive`, `onComplete`, `onSkip`, `onStepChange`, `startStep`.

5. **Register in the registry**\
   In `module-setup-registry.ts`, set `setupTourId: 'your-core-settings-tour'` for that module (or use `registerModuleSetupConfig` if adding at runtime).

**Deep link:** Linking to `/{core}/settings?tour=your-core-settings-tour` will open the settings page and auto-start the tour (used by the Getting Started card).

***

## 3. Adding a new setup wizard and registering it

1. **Implement the wizard**\
   Use PF-41 with `wizard_type: 'setup'` where possible, or a dedicated flow that persists completion (e.g. in `{core}_module_settings` or a dedicated table).

2. **Add the route**\
   Ensure the setup wizard has a stable route (e.g. `/fa/close/setup`, `/ce/settings/telephony/ringcentral-setup`).

3. **Register in the module setup registry**\
   Set `setupWizardRoute` to that route and `setupCompleteCheck`:
   * `'wizard'` if completion is stored when the user finishes the wizard
   * `'settings_saved'` if completion is inferred from e.g. a row in `{core}_module_settings`
   * `'none'` if there is no completion check

The Getting Started card will show a "Setup wizard" link for that module when `setupWizardRoute` is set.

***

## 4. How the Getting Started card uses the registry

* **Component:** `src/platform/setup/components/GettingStartedCard.tsx`
* **Placement:** Dashboard (for org\_admin) and `/settings/getting-started`.

**Behavior:**

1. **Organization setup**\
   Uses `isOrganizationSetupComplete(organizationId)` (from `useOrganizationSetup`). If not complete, shows "Start setup" linking to `/settings/setup`; if complete, links to org settings.

2. **Enabled modules**\
   Uses `useModuleAccess()` (or equivalent) to list enabled modules. For each module, reads `getModuleSetupConfig(moduleId)` from the registry.

3. **Per-module row**
   * **Setup tour:** Link to `/{core}/settings?tour={setupTourId}` (or "Tour again" if tour completion is known via `getCompletedTours()`).
   * **Setup wizard:** If `setupWizardRoute` is set, show a link to that route.
   * **Setup complete:** When `setupCompleteCheck` is `'wizard'`, completion may be derived from wizard completion state; for tours, completion is read from tour completion state (e.g. localStorage via the same key pattern as `useTour`).

4. **Visibility**\
   The card is shown only to users with permission `system.organizations.admin`.

***

## References

* **Tour template:** `specs/_templates/GUIDED_TOUR_TEMPLATE.md`
* **Help module:** `src/platform/help/README.md` (GuidedTour, useTour, HelpButton)
* **PF-UX-01:** Organization setup wizard spec and plan in `specs/pf/plans/`
* **Wizard selection:** `docs/guides/use-cases/wizard-selection.md`