# Agency setup wizard (first login) — design Status: **phases 1 and 2 built**: packs, the first-run wizard, next steps, the policies and contracts library ("Needs PDF" placeholders), the draft job ad, and Add from award pack / Add from library. Sign-up no longer applies the starter pack. Phase 3 (module wizards, point-of-use blocks, console progress) is not built. The cutoffs keep their Monday 01:00 defaults rather than being asked. Placeholders all start scoped to everyone (no per-profession scope from the library). ## Why Today every new agency gets the whole starter pack (every award's professions, every certification, loadings) applied by `ApplyStarterPack` during provisioning, whatever the agency does. A nursing agency gets SCHADS disability roles; a disability provider gets Nurse Practitioners. Then they land on an empty dashboard and have to find Settings on their own, so new agencies either need training or get stuck. Instead: **ask, then provision what they chose**. On the super admin's first sign-in, a wizard they can't close until it's finished asks a few questions and seeds their workspace from the answers, then shows the next steps to get iShapps running. ## Principles - **Provisioning stays invisible; setup is the wizard.** Database, roles, super admin, Passport client and the award glossary need no choices and stay in the `TenantCreated` pipeline. `ApplyStarterPack` leaves the pipeline. - **Informative, not interrogating.** Every step says why it matters and what it creates. Every seeded item can be ticked off. Defaults are sensible, so pressing Next all the way gives a working agency. - **Mandatory means "rostering can't work without it"**: the agency's name, where it is, a support email, at least one profession. **The ABN is optional**: brand-new agencies may not have one yet. Everything else is optional or toggled. - **Same wizard rules as elsewhere** (`WizardDialog`): it never closes by itself; each step saves before moving on; resume is worked out from what exists, not from stored progress. The only stored state is the questionnaire answers and the time setup was finished. - **Seeded items are ordinary records.** Professions, certifications and policies are edited and deleted from their normal pages afterwards. The wizard is not the only way in: Professions gets **Add from award pack**, and Policies gets **Add from library**, both reusing the same services. ## Who sees it - **The super admin, at their first sign-in.** They are the first login of every new agency. `user.setup_pending` (sent at login, like `legal_pending`) shows `SetupGate`, after `TermsGate`. - **Other users** pass through: the super admin creates them only after setup anyway. - The iShapps support account (`developer`) passes through. - **Existing tenants** (Smart Healthcare) are marked finished by the migration and never see it. ## The first-run wizard | # | Step | Mandatory | Creates / saves | |---|---|---|---| | 1 | **Your agency**: trading and legal name, ABN (optional; ABR lookup when given), address and state (sets the timezone), phone, support email workers see. Logo (optional). | Name, state, support email | `tenants` + `tenant_settings` via `TenantSettingsService` (existing endpoints) | | 2 | **What you do** (tick any): nursing, aged care facilities, disability / NDIS, home care. Shows which modules their plan includes and what they do. | One answer | `tenant_settings.setup_profile` (answers); preselects later steps | | 3 | **Professions**: award packs (Nurses Award, Aged Care Award, SCHADS), preselected from step 2. Each expands to its professions and levels; untick any. Option "I'll add my own" (an empty pack, and a next step). | At least one profession, or "my own" | Categories, professions, levels (`StarterPackService`, per pack) | | 4 | **Worker certifications**: the general ones (police check, ID, licence, manual handling, flu vaccine) and those that came with the chosen packs (AHPRA, NDIS screening, WWCC, …). Untick any; switch mandatory / expiry. | — | Document catalogue + profession mappings | | 5 | **Policies and contracts**: the library (below), filtered by step 2. Each is created as **"Needs PDF"**: listed with what it should cover; the agency uploads its own document later. | — | Agreements without a version (new state, see Library) | | 6 | **Rates basics**: shift loadings (afternoon 10, night 15, Saturday 40, Sunday 60, public holiday 120, Christmas 120, editable) and superannuation (12%, the Superannuation Guarantee rate). Payroll and invoicing cutoffs (Monday 01:00) only when those modules are on. | — | `loading_schedules`, charge schedule `super_rate`, cutoffs | | 7 | **Recruitment** (HR module): "Create a draft job ad for {first chosen profession}". Shows the careers page link. | — | One unpublished `job_postings` row | | 8 | **Your words**: what you call workers (Worker / HCP / Carer) and, with Participants on, the people you care for. | — | `tenant_settings.terminology` | | 9 | **You're set up**: the next steps checklist (below). | — | `tenant_settings.setup_completed_at` | Loadings and super are seeded **for now**: rostering and billing still read them, until award interpretation takes over pay. They're shown with plain explanations ("added on top of the base pay rate for work at these times"). ## Award packs `database/starter-pack/pack.php` becomes a list of packs plus a shared base: ``` 'base' => [ general certifications, loadings, super ] 'packs' => [ 'nurses' => [ award MA000034, category, professions + levels, profession certifications, policies ], 'aged-care' => [ award MA000018, … ], 'schads' => [ award MA000100, … ], ] ``` - **Certifications and policies belong to packs**, so ticking SCHADS brings NDIS Worker Screening, WWCC and the NDIS Code of Conduct with it. A certification shared by packs (CPR, First Aid, Qualification) is created once and mapped to every chosen pack's professions. - **`StarterPackService::apply()` takes packs.** It keeps its existing rule: it only adds items missing by name and never pauses existing workers with surprise mandatory documents. - `tenant:starter-pack --pack=schads` and the console task take a pack too. ## Policies and contracts library `database/starter-pack/agreements.php`: a title, kind, a short description of what the document should cover, who it applies to (everyone / pack professions), a suggested "required to sign", and the verticals it's suggested for. **We supply names and guidance, not the documents.** Policies are legal and clinical content the agency owns. Each placeholder says so ("Upload your own policy. Your quality consultant or industry body usually provides templates."). ### "Needs PDF" agreements - `AgreementService::createPlaceholder()` creates an `agreements` row with no version (`current_version` null, status `draft`). - Lists show **Needs PDF**; the detail page opens on **Upload PDF**, which adds version 1 through the existing `addVersion` path. - A placeholder can't be published or sent, so it never reaches workers or blocks approvals until it has a document. It's deletable like any never-sent agreement. ### Suggested library Researched against the NDIS Practice Standards, the strengthened Aged Care Quality Standards (in force from 1 November 2025) and Fair Work's casual employment rules. To be reviewed before seeding. **Contracts** - Casual Employment Agreement (all; required): engagement terms, casual loading, shifts and cancellations, casual conversion. - Independent Contractor Agreement (not ticked by default; sham contracting risk, for agencies that genuinely use contractors). **Statements workers must receive** (published as policies to acknowledge; Fair Work provides the PDFs) - Fair Work Information Statement. - Casual Employment Information Statement. **Policies for everyone** - Code of Conduct - Privacy and Confidentiality - Work Health and Safety - Incident Reporting and Management - Complaints and Feedback - Infection Prevention and Control - Manual Handling - Bullying, Harassment and Discrimination (including the positive duty on sexual harassment) - Fitness for Work: Drugs and Alcohol - Social Media - Shift Availability and Cancellation (the agency's own rules) **Aged care** (Aged Care Award / aged care answer) - Aged Care Code of Conduct - Serious Incident Response Scheme (SIRS) - Elder Abuse Prevention and Safeguarding - Restrictive Practices - Medication Management - Open Disclosure **Disability / NDIS** (SCHADS / NDIS answer) - NDIS Code of Conduct - Reportable Incidents - Safeguarding: Abuse and Neglect Prevention - Restrictive Practices and Behaviour Support - Medication Management - Child Safe Practice (supports to children) - Participant Rights **Nursing** (Nurses Award) - Scope of Practice - Clinical Documentation - Medication Management - Open Disclosure A policy appearing in more than one group (for example Medication Management) is created once. ## Next steps (after the wizard, on the dashboard) The last step and a dashboard card show what's left, each opening the right page or its own wizard. Each step's completion is worked out from what exists, and the card disappears when every step is done or dismissed. 1. **Add your first organisation and facility** (`OrganisationWizard` → `FacilityWizard`). 2. **Set pay rates for each profession and level.** Later idea: prefill from the award minimums (`award_pay_rates`). 3. **Set your charges** (Agency module): super is already set; add markup and add-ons. 4. **Billing details** (Agency module): invoice bank account, payment terms, accounts email. 5. **Upload your policies and contracts** (count of "Needs PDF"). 6. **Employer signature for contracts** (HR module): `agreement_signatory_*`. 7. **Add your first worker**, or publish the draft job ad. 8. **Invite your team** (sub-admins). 9. **Get the worker app**: store links to share with workers. ### Blocking at the point of use Module essentials don't block sign-in, they block the action that needs them, with a link to finish the setup. For example: - issuing an invoice without billing details - sending a contract without an employer signature - publishing a policy that has no PDF ## Backend - **`TenantSetupService`**: `status()` returns the steps (mandatory, done, skipped, which module), the next steps, and `pending`. Also `complete()` (refused while a mandatory step is missing) and `saveProfile()`. - **Step registry** in `config/tenant_setup.php`, like `console_tasks.php`: key, module, mandatory flag, a completion check class. A module switched on later adds its next steps automatically. - **Endpoints** (super admin only): - `GET /setup` - `PUT /setup/profile` - `GET /setup/packs`: pack contents for preview - `POST /setup/packs` `{packs, exclude: {professions, documents}}` - `GET /setup/library` - `POST /setup/library` `{keys}` → placeholders - `POST /setup/job-draft` - `POST /setup/complete` Everything else saves through the existing settings endpoints. - **Stored state:** `tenant_settings.setup_profile` (json answers), `setup_completed_at`, `setup_dismissed` (json next-step keys). Migration sets `setup_completed_at` for existing tenants. - **Provisioning:** `ApplyStarterPack` is removed from the pipeline, and the pack's loadings are not seeded at sign-up. Payroll and invoicing cutoffs keep their Monday 01:00 defaults. ## Frontend - `SetupGate` (like `TermsGate`) shows `AgencySetupWizard` on `WizardDialog`; one component per step in `components/setup/`. - `NextStepsCard` goes on the dashboard. - "Add from award pack" on Professions; "Add from library" on Contracts & Agreements and Policies. - "Needs PDF" state on agreement lists and detail. ## Console The organisation page shows **setup progress**: finished or not, and which next steps are open. That's the "this agency needs training" signal for support. ## Guides A new public guide, **Getting started** (`website/lib/guides/getting-started.ts`): the wizard and the next steps. Update the Professions and Agreements guides for the pack and library buttons. ## Phases 1. **Packs, first-run wizard, next steps.** - Pack split. - Wizard steps 1–4, 6, 8, 9. - `SetupGate`. - Next steps card. - Remove `ApplyStarterPack` from sign-up. - Mark existing tenants finished. 2. **Library and recruitment.** Placeholders, "Needs PDF", step 5, step 7, the "Add from …" buttons. 3. **Module wizards and console.** Billing and signatory setup wizards, the point-of-use blocks, console setup progress. ## Open questions - **Placeholder wording:** confirm the library list and each "what it should cover" text before seeding. We're not giving legal advice. - **Changing step 3 after applying:** going back to step 3 after a pack was applied lets them remove unused items (`TaxonomyDeletionService`), but never items already in use.