> For the complete documentation index, see [llms.txt](https://help.resouris.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.resouris.com/start-here/getting-started.md). # Getting started ## Getting started There are three audiences for ReSouris. This page tells you which entry point applies and gets you signed in. ### If you are a roster-area admin You are the day-to-day operator + resource-catalogue maintainer. You author service lines, manage the staff / room / equipment / competency catalogues, publish rosters, triage sickness batches, maintain the reporting-structure org chart, and decide leave requests. Your surface is the **admin UI**, typically at `https://.rostaire.example/ui/admin/` (SaaS) or your local install URL (self-hosted). #### Signing in Two paths depending on your deployment: * **SSO (recommended)** — Google Workspace, Microsoft 365, or generic OIDC. Your organisation configures the provider at Tenant Settings → Sign-in; you click the "Sign in with ..." button on `/ui/sign-in`. * **Local credentials** — for a tenant's first administrator, and for break-glass. ⚠️ There is **no** `rostaire-admin` command: a tenant's first administrator is issued when the tenant is created from the Owner console, and the Owner account itself is made with `python -m host.cli.owner create`. See [Configuring a brand-new tenant](#configuring-a-brand-new-tenant). Sessions last **24 hours** by default. Signing out revokes the current session immediately. #### Finding your way around Navigation has two parts, and most of it is in the second. A short **top bar** carries the seven places you go most: ``` Tenant details · Staff admin · Competencies · Shifts · Rules · Rosters · Audit ``` Everything else lives in the **sidebar**, grouped by what you are doing: | Group | Holds | | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | **My ReSouris** | Your own roster, calendar, details, leave, feedback and equity. | | **Current roster** | The roster in force now. | | **Operate** | Rosters and Audit. | | **Organisation** | Roster areas, Estate, Estate labels, Spaces. | | **People management** | Staff admin, staff rosters, working-pattern templates, renewals, training plans. | | **Scheduling** | Auto-roster, its diagnostics, availability view and availability pool. | | **Catalogue** | Competencies, Shifts, Equipment, training catalogue. | | **Operations** | Setup checklist, production readiness, critical rules, diagnostics. | | **Throughput** | Trend dashboard, demand and capacity, training impact, scheduling impact. | | **Roster area admin** | Reporting structure, overrun time. | | **Trust Admin** | Upcoming / unpopulated / all services, and Trust Admins. | | **Job planning** | Workload plans, team workload plans, appeals, cycles, monitoring. | | **Fairness & cover** | Allocation policies, equity events, equity adjustments, cross-department cover. | | **Reporting**, **Platform operations**, **Assurance**, **Administration** | Reports, platform-level operations, assurance evidence and tenant administration. | > ⓘ **The screens say "Workload plan" where this documentation says "job plan".** They are the same thing: the database and the HCS framework call it a job plan, and the UI uses the less loaded word. Worth knowing before you go looking for a menu item called Job plans. Role-gated items do not appear at all if your role lacks the permission, so your sidebar may be shorter than this — see [Roles and access](/part-2-running-resouris/permissions.md). #### First-time bring-up If this is a brand-new tenant, see [**Configuring a brand-new tenant**](#configuring-a-brand-new-tenant) below. It is the ordered sequence, and the order is load-bearing. The [Quick start](/start-here/quick-start.md) walks an admin through the first roster generation once the tenant is configured. *** ## Configuring a brand-new tenant This is the whole sequence, from an empty database to a roster you can publish. > ⛔ **THE ORDER IS NOT A SUGGESTION.** Several steps produce nothing visible when run early — no error, just an empty screen or a roster with nobody in it. The dependencies below come from the product's own setup checklist (`/ui/admin/setup-checklist`), which tracks the same graph and shows you where you are. ### Stage 0 — Before any tenant exists A fresh database has **no way in**. Migrations create a `platform` tenant and a `platform-admin@…` user but **no password for it**, so the Owner account is the first thing you make. ```bash python -m host.cli.owner create --email you@example.com --name "Your Name" ``` You will be asked for a password (12 characters minimum), then shown a **two-factor secret once**. Scan it before answering the prompt that follows — it is not shown again. > ⚠️ There is **no** `rostaire-admin` command, and no web page that can create an Owner. This is deliberate: the account that can create tenants is not reachable from the internet. Then sign in to the **Owner console** and create the tenant. Creating it issues that tenant's **first administrator credentials** — that is the only way a tenant gets its first way in. ### Stage 1 — Platform (role: `platform_admin`) | Step | Where | Needs | | ----------------------------- | ----------------------- | ------------ | | **Trust anchor loaded** | `/ui/admin/deployment` | — | | **Licence installed** | `/ui/licences` | trust anchor | | **Plugins loaded** | `/ui/admin/diagnostics` | — | | **Identity adapter verified** | `/ui/admin/sso-config` | — | | **Audit chain bootstrapped** | `/ui/audit` | — | The licence genuinely depends on the trust anchor: a licence is a signed document, and without the anchor there is nothing to verify the signature against. See [Install a licence](/part-2-running-resouris/install-a-licence.md). ### Stage 2 — The tenant's shape (role: `tenant_admin`) > ⛔ **A NEW TENANT HAS NO ROLES.** Roles are per-tenant rows, not global ones. A tenant created this morning has an empty role catalogue, so the first administrator can reach the admin screens — the *name* `tenant_admin` gates those — while holding almost no individual permissions. Create the roles you need at `/ui/admin/roles` early, or later steps refuse with `permission_denied` and the cause is not obvious. > ⛔ **A NEW TENANT INHERITS NO CORPUS LOOKUPS EITHER.** Band grades, role titles and the other reference lists start empty. Populate them before staff records, or every staff form offers you an empty dropdown. | Step | Where | Needs | | -------------------------------- | ------------------------- | ----------- | | **Departments configured** | `/ui/admin/departments` | — | | **Service lines configured** | `/ui/admin/service-lines` | departments | | **Competency demand configured** | `/ui/admin/service-lines` | departments | | **Staff records complete** | `/ui/admin/staff` | departments | Everything hangs off departments (roster areas), so they come first. ### Stage 3 — The five resource classes A roster needs all five populated. See [Resource management model](/how-it-works/resource-management-model.md). 1. **People** — staff records, employment spells, working patterns, competencies and skills, line-management relationships. 2. **Rooms** — the space catalogue, and each room's weekly session pattern. 3. **Equipment** — items, which service lines need them, and the skills needed to operate them. 4. **Demand** — service lines with their activities, competency requirements and priority. 5. **Policy** — an allocation policy, covered in Stage 4. > ⛔ **ROOM SESSIONS BEFORE ROSTERS.** A roster is *expanded from* the sessions a room authors. A room with no authored week contributes nothing, and a service line scheduled into it is a clinic that never runs. Author the room week first, then attach the service lines, then allocate. > ⛔ **A SERVICE LINE WITH NO ROOM CAN NEVER BE STAFFED.** Candidate enumeration walks the rooms a line may use. A line with none is silently unstaffable — it does not error, it simply never appears in a roster. Check every line has at least one room at `/ui/admin/service-lines`. > ⛔ **A POSITION WITH NO SKILL REQUIREMENT IS UNFILLABLE.** The opposite of what most people expect: a position requiring nothing is not open to everyone, it is open to no one. Give every position at least one required skill. > ⓘ **Eligibility admits on ANY ONE required skill**, not all of them. A position requiring three skills admits somebody holding one. That is deliberate — it is how a service keeps running — but it surprises people reading a roster for the first time. ### Stage 4 — Allocation and the first roster | Step | Where | Needs | | -------------------------------- | ---------------------------------------- | -------------- | | **Fixed commitments loaded** | `/ui/admin/staff?view=fixed-commitments` | demand + staff | | **Auto-roster preset selected** | `/ui/admin/auto-roster` | demand + staff | | **Coverage traffic light green** | `/ui/rosters` | preset | | **Production readiness green** | `/ui/admin/production-readiness` | coverage | > ⛔ **THE ALLOCATION POLICY MUST BE `active`.** Without an active policy every weight falls back to zero, so competency, fairness and entitlement contribute **nothing** and the roster is solved on hard constraints alone. Nothing errors; the roster simply ignores everything you configured. See [Author an allocation policy](/set-up-what-you-schedule/author-an-allocation-policy.md). > ⚠️ **A fixed commitment is a seat, not a person.** It reserves capacity in the timetable; it does not name who fills it unless you pin somebody. An impossible pin aborts the entire solve rather than dropping one assignment. ### Stage 5 — Before anyone relies on it | Step | Where | Needs | | ---------------------------------------- | ------------------------------- | -------------------- | | **Workforce privacy notice recorded** | `/ui/admin/screens-and-sign-in` | — | | **Second factor required for everyone** | `/ui/my-resouris/security` | identity adapter | | **Operator handover signed** | — | production readiness | | **Support bundle export dry-run passed** | `/ui/admin/support-bundle` | handover | The privacy notice is a legal obligation before real workforce data is entered, not a finishing touch — record it before you import staff, not after. ### Checking where you are `/ui/admin/setup-checklist` shows every step above with its current state and a link straight to the screen that fixes it. It is the same graph this page describes, so the two cannot disagree. ### If you are a worker You interact with ReSouris through **My ReSouris** — a slimmed-down worker portal at `/ui/my-resouris` on the same site. It shows only what you need: * your published roster (weekly and horizon views), * your leave balance + submit-new-request form, * a report-sick button, * your training-plan progress (if you have one), * your job-plan entitlements (if you have one), * your Logbook — self-service CPD tracking (implementations, seminars attended, CPD credits; v1.7.2), * your team's reporting structure — read-only view with historical time-travel (v1.7.3). #### Signing in Same URL as your admin colleagues; the site routes you to `/ui/my-roster` automatically based on your role. Sign in via your organisation's SSO provider — same account you use for email. If you can see admin surfaces you have an admin role. Ask your roster-area admin to find you on `/ui/admin/users` and adjust. #### What you can do without an admin's help * View your roster and export it as an ICS calendar feed. * Submit a leave request — see [Submit a leave request](/for-clinical-staff/submit-a-leave-request.md). * Report sickness for the current or next roster day; the system will attempt cover automatically via the sickness-batch mechanism. * View your competencies + training-plan progress. * Add + delete Logbook entries (implementations, seminars attended, CPD credits) — see [Worker Logbook](/for-clinical-staff/worker-logbook.md). * View the reporting structure — see who reports to whom in your area, including historical time-travel. Anything that changes another worker's schedule needs a roster-area admin. ### If you are clinical leadership You typically won't operate the day-to-day surfaces. Your entry points are: * **`/ui/admin/about`** — tenant identity, deployment mode, licence status, corpus version. Copy-buttons for support tickets. * **Metrics dashboard** — solve times, roster-generation queue depth, sickness-batch turnaround, unread-decisions counts. * **Audit page** — filter the audit chain by role, area, or event kind. Confirm chain integrity via the daily seal status. * **Widget dashboards** — a SharePoint-style widget framework (v1.6) where any user with the right role can build a personal or tenant-scope dashboard from a catalogue of 128 platform widgets. The mental model that most helps: [Equity and fairness model](/how-it-works/equity-model.md) explains why a specific person got a specific slot; [Audit and compliance](/part-2-running-resouris/audit-and-compliance.md) explains how that decision is evidenced. ### What comes next * Anyone who wants the mental model first → [**Resource management model**](/how-it-works/resource-management-model.md) (start here — the scaffold everything else hangs on) → [Roster lifecycle](/how-it-works/roster-lifecycle.md) → [Equity and fairness model](/how-it-works/equity-model.md). * Roster-area admins → [Quick start](/start-here/quick-start.md). * Workers → [Submit a leave request](/for-clinical-staff/submit-a-leave-request.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://help.resouris.com/start-here/getting-started.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.