#Role onboarding and credentials

Module id: MOD-ONBOARDING
Doc profile: capability

After sign-up and activation, contractors and companies complete profile setup on /onboarding before entering the shift marketplace. Target stack is a React route with Supabase profiles / documents and a Country State City edge proxy; Bubble page workflows are the behavior evidence, not the runtime.

#Purpose

New Contractor or Company users must finish a first-run wizard: choose the matching role chrome, enter profile and location, upload required contractor documents (or company pay-practice and safety fields), accept terms, and persist profiles.onboarding_complete so later modules can treat them as onboarded. This module owns the onboarding page shell, role panels, CSC location proxy, document uploads for Drivers License and Resume, and the Save writes that mark onboarding complete. It does not own auth forms, workspace chrome, or shift list bodies.

#Scope boundaries

#Actors

#Capability composition

Onboarding is one narrow page with two role panels gated by ?nav=Contractor|Company (NavigationOnboarding). Shared location dropdowns call the CSC edge proxy. Contractor document list linkage happens on upload/remove workflows, not on Save; company Save writes company fields on the same profiles row. Activation and approved redirects are PageLoaded gates on the same page.

Bubble evidence for composition is under Traceability / IR evidence.

#Primary journeys

Journeys are reconstructed from onboarding PageLoaded and ButtonClicked / InputChanged workflows (gates → role chrome → CSC-backed fields → Save → ChangePage). Where ACC-AUTH-SURFACE replaces Bubble active=yes, that activation step is skipped; the form journeys still apply after profiles.active is true.

#J1 — Land on onboarding, activate, and role chrome

1. An authenticated contractor or company opens /onboarding (or arrives with empty nav); the app requires a session and bounces anonymous, admin, or other roles to /.
2. When nav is missing and onboarding is incomplete, the app sets nav from the profile role display (Contractor or Company) and shows only that panel.
3. If the URL has active=yes while the profile is still inactive and unapproved (preserve path), the app sets profiles.active true, strips the param, and shows the Welcome popup.
4. If the profile is already approved, the app leaves onboarding for the role home (company → company shifts; contractor → contractor shifts).
5. Logout clears the session and returns to /.

#J2 — Contractor completes profile, documents, and save

1. Contractor with nav=Contractor sees General Information and Documents chrome, fills legal names, phone, emergency contact, skills free-text, and picks US state then city from CSC.
2. Contractor uploads Drivers License and Resume; each creates a typed document and links it on the profile document list (replacing removes the prior row of that type). Remove controls delete the prior document thing.
3. Contractor checks Terms; Save stays blocked until terms are accepted.
4. On Save, the app updates profile fields only (skills summary, city/state, dependability score 5, onboarding complete, and related name/phone fields) — not the document list — then navigates to /contractor/shifts.
5. Upload or Save failure shows a user-visible error and leaves the user on the contractor panel.

#J3 — Company completes profile, pay practices, and save

1. Company with nav=Company sees company name, rules/regulations, state/city, contact area, OSHA, job site / safety / important contact / rules protocol, and pay-practices multi-select (four concrete trades only).
2. Company selects location via the same CSC helpers and optionally sets a company picture.
3. Company checks Terms; Save stays disabled when terms are unchecked or any of these required inputs is empty: company name, state, city, rules/regulations, pay practices (selected count < 1), contact area, OSHA, job site information, safety handbook, important contact information, or rules/protocol.
4. On Save, the app updates company fields on profiles, sets onboarding complete, and navigates to /contractor/shifts (same Bubble ChangePage target as contractor Save — not company shifts on first save).
5. Save failure shows a user-visible error and stays on the company panel.

#Vertical slices (decompose)

#Key UI states

#Style and fidelity

Narrow intentional shell (onboarding column). Transcribe visible labels and stamp data-bubble-id on migrated roots (page, main column, role panels, Save, Welcome popup). Shared tokens come from the app-level stylesheet that SHELL-LAYOUT (MOD-SHELL) delivers out of IR styles (ir/slices/styles____part_all.json — 49 styles, 8 color tokens, 1 font token); this cycle's module map has no separate design-system module, so do not defer a token to one. Stripe footer sentence is static disclaimer copy only.

#Failure modes

#Traceability

#IR evidence

#Module evidence roots

• bTHDn0 — onboarding page (/pages/bTHDr0): role panels, PageLoaded gates, Save workflows, Welcome popup.

Supporting segments from module-map: ir/slices/bTHDr0____root.json, documents, skill_set (residual — not used on this page), docs_type, external_ns:bTKtr.

#Path-key ↔ inventory id aliases

Prefer inventory ids in evidence_refs; path keys are locators when chasing the sanitized export.

#Gate and activation matrix (chased)

• bTHsj1: not logged in or role neither contractor nor company → ChangePage index.
• bTNJN0: logged in, onboarding incomplete, role ≠ admin, nav empty → set URL nav from role display.
• bTHsZ1 / bTHse1: URL active=yes and currently inactive (and unapproved per decompose) → set active__boolean true, strip param, show Welcome.
• bTKsL: approve1_boolean true → company → company shifts page; contractor → contractor shifts page.
• bTKYU3: active true, approved false, active param empty → stay on onboarding with nav.
• bTKpL: LogOut → index.

#Contractor Save vs document list (chased)

• bTHtH1 gated by terms checkbox (bTHLF0).
• bTHtN1 ChangeThing CurrentUser writes profile image, names, phone, emergency contact, skills free-text (short_summary_about_your_experience_text), city/state from CSC names, dependability_scoup_number literal 5, onboarding_boolean true, and full_name__search__text. It does not write docs_list_custom_documents.
• bTKwr1 ChangePage → bTHMg (contractor shifts).
• Document list add/replace: InputChanged bTHKX0 (Drivers License) and bTLAz1 (Resume) run NewThing + MakeChangeCurrentUser on docs_list_custom_documents (bTKzP1 / bTLBH1) with docs_type driver_s_license / resume (bTKzH1, bTKzC1). Remove controls bTHsx1 / bTLBN1 DeleteThing the prior document.

#Company Save button-state matrix (chased)

• Terms gate: element_condition:bTHJb0:1 — checkbox bTHLf0 not checked → button_disabled.
• Required fields gate: element_condition:bTHJb0:0 — Save (bTHJb0) disables when any of these is empty (OR chain), or pay-practices count < 1:

• Workflow bTHub1 / ChangeThing bTHuh1 then writes company name into first_name_text, plus contact/OSHA/pay_practices/rules/safety fields, city/state, onboarding_boolean true.
• bTKuL ChangePage → bTHMg (contractor shifts) — same exit as contractor first save; approved-company redirect to company dashboard remains bTKsL only.

#Location API (chased)

• external_ns:bTKtr Country State City; calls bTKts (states) and bTKvG (cities) used private headers in Bubble — target edge must keep the key server-side.
• State/city UI on both panels (bTHEd0 / bTKwT1 and related dropdowns); persist display names on city_text / state_text.

#Residual: skill_set

• Option set / custom type skill_set exists in the catalog but this page never reads or writes it. Contractor “skills” here are free-text skills_summary. Owned by later contractor profile/shift surfaces (MOD-CONTRACTOR-SHIFTS).

#Privacy & authorization

• Target: RLS owner read/write on profiles and documents; Storage owner policies for avatars/docs.
• CSC edge: valid user JWT required; no anon public proxy.
• Bubble documents privacy roles (admin/company/user select) inform later admin views; onboarding writes are owner-scoped.

#Option sets used on this page

• navigationonboarding: contractor | company (display Contractor | Company).
• pay_practices: concrete_carpenter, concrete_walls, concrete_laborer, concrete_finisher.
• docs_type: only driver_s_license and resume required as upload affordances here (full enum lives in DATA-MODEL).