Setup wizard
The Setup wizard is the guided checklist a new organisation's Admin sees after signing up. It walks through the five things that turn an empty workspace into a working portal, in the order the product is actually assembled, and ticks each step automatically when the underlying data exists. It is a nudge, not a gate: nothing in ZekoHR is locked until the wizard is finished.
Who can do this: Anyone with `settings.manage` (Admin by default). Everyone else who opens the page sees "Nothing to set up here. The setup guide is for administrators."
Where to find it
Two entry points:
- The Finish setting up card on the Dashboard, which shows "{n} of 5 steps done", a progress bar, Next: {step}, a Resume setup button and a shortcut to that step.
- The full page at `/setup-wizard`, headed Set up your workspace with the line "Five steps from an empty workspace to a working HR portal. Pick up wherever you left off."
The five steps
| Step | Opens | Counted as done when |
|---|---|---|
| Add your companies | Settings → Companies | Your first company exists. Signup creates it, so this starts ticked |
| Set up departments | Settings → Departments | You add a department after the seeded starter set, or rename one of the seeded ones |
| Configure your leave year | Settings → Leave year config | A leave year configuration has been saved; nothing seeds one |
| Invite your team | People → Employees | A second non-offboarded person exists besides the signup admin |
| Import employees from CSV | Employees → Bulk import | Headcount reaches five, whichever way the people were added |
Finished steps collapse behind a tick. The first unfinished step is expanded with its description and two buttons: the deep link (for example Open leave year settings) and Mark as done. Later steps show only their link.
Marking a step done by hand
A five-person company may never use the CSV importer, and a single-entity organisation has nothing to add under companies. Click Mark as done on the expanded step; it is recorded as a manual tick for the whole organisation. Marking is first-come: a later real signal still counts, but a manual tick never un-does a detected one, and there is no way to un-tick.
Hiding the dashboard card
At the bottom of the page, Hide the setup card from my dashboard removes the card from your dashboard in this browser only. Another Admin on another laptop keeps seeing it. The page itself stays reachable at `/setup-wizard`, where the link becomes Show the setup card on my dashboard again to undo.
What happens next
- When all five steps are done the page shows a "Setup is done" banner and the dashboard card disappears for everyone.
- Progress feeds the trial email sequence: early nudges name the next unfinished item, and mid-trial check-ins are skipped when the organisation is clearly active. See Plans and trial.
- Nothing here writes to the audit log; the actions you take on the linked pages do.
Rules and limits
- The checklist is never plan-gated; a plan change cannot close it.
- Detection is derived from live data, so it also backfills organisations created before the wizard existed.
- Departments created in the first ten minutes after signup are treated as the seeded baseline and do not count.
- The card renders nothing if the checklist cannot be loaded, so a loading failure never breaks the dashboard.
- Dismissal lives in browser storage; clearing site data brings the card back.
Troubleshooting
The card has gone but we are not finished. Someone hid it in this browser. Open `/setup-wizard` and click Show the setup card on my dashboard again.
"Set up departments" will not tick although we have departments. They are the seeded set. Rename one, or add a new one, or use Mark as done.
A non-admin colleague sees the empty state. By design; only Admins run setup.
I marked a step done by mistake. It cannot be undone, but it has no effect beyond the checklist.