# Agent onboarding state

The User model stores `onboarding_step`, `takafulhub_experience`, `onboarding_started_at`, and `onboarding_completed_at`. Steps are centralized in `AgentOnboardingStep`: experience question, tutorial, balance inquiry, and completed.

Existing users are backfilled as completed. When a pending registration is approved, its onboarding state is initialized to `experience_question` without being started.

On the first successful login for an eligible approved Agent, `onboarding_started_at` is set once. Authenticated Inertia pages receive only `agent_onboarding.required` and, when required, the current step. The blocking modal records the experience answer: `first_time` advances to the tutorial and `returning` advances to Balance Inquiry.

The authenticated layout renders a blocking modal for each active onboarding step. Tutorial completion marks first-time agents complete. Returning agents at `balance_inquiry` may request a Membership Balance, Lead Credit Balance, or both, with an optional plain-text note. Submission atomically creates one normal Support ticket in the existing `balance_inquiry` category and completes onboarding. Skipping creates no ticket and completes onboarding.

Balance Inquiry is limited to Membership and Lead Credit. It is not a migration request and performs no automatic old-system lookup, balance calculation, E-Wallet credit, or refund. The request is handled through the ordinary Support workflow.

Following manual Support review, an administrator may credit one approved amount to the agent's normal E-Wallet and resolve the inquiry. This does not restore Membership directly or grant Lead Credit directly.

The completed refund also creates a database notification in the existing agent bell and Notifications page, linking back to the Balance Inquiry ticket.

Admins may configure plain-text welcome title/message and an optional normalized HTTPS YouTube, Vimeo, or Loom embed URL.