Admin guide

This guide covers the admin path: org, shifts, blocks, availability, solving, deploy, publish, manual edits, promotion, and roles.

Before you start

Clepsy has five permission levels.

PGY is not a role

PGY-1 through PGY-4 are per-year PGY levels, not roles. The underlying service role (EM Resident, FM Resident, TY Resident, Visiting Resident) carries no PGY. Incoming-PGY-1 writes next-year status and is invisible to current scheduling.

Chief is a flag

Chief authority is a per-year flag (Admin / chief in the user editor). A flagged resident acts as chief_resident even with an ordinary role, and only Super User and above can change it. There is no built-in Attending role, and Director or Coordinator applications become Super User. System Administrator maps to Admin.

Simple versus Advanced

Simple and Advanced are per-user display preferences, not permissions. Advanced is the default; the toggle is in the sidebar footer. Simple hides the Schedule Generator, Simulation, Annual Promotion, blackouts, capacity and priority fields, quotas, Permission Definitions, Allow Intern Supervision, and the visiting-resident checkbox. Hidden fields keep their values, with no authorization change.

Build the org tree

The tree is Health System to Residency to Site. Open Program then Residency Settings.

1. At the root, choose Add Health System.
2. Select it and choose Add Residency; name it and its site.
3. The site name defaults to "Residency name Main Site." Saving creates the site and seeds three shifts.
4. Select the Residency and choose Add Site for other hospitals or units. Shifts live at the Site.

Seeded shifts are Day 07:00-17:00, Evening 12:00-22:00, and Night 19:00-07:00. Org edits need Super User or above; chiefs manage shifts inside a site but cannot add org levels. Super Users are residency-scoped; Admin and Superduper switch residencies.

Define shifts

Shifts are site templates; select a Site, then add or click a shift. Chief Resident and above can manage them.

AI shift import

Use Import via AI: copy the prompt, paste it with your rules document into any AI chat, paste the code back, Validate & Stage, review warnings, then Import New. Nothing is written before that step. To replace templates, delete old shifts first; the importer adds definitions and will not overwrite rows.

For mid-year hour changes, set an Effective Date and click Apply Changes. Only start and end cascade; staffing, capacities, and history remain.

Build the block schedule

Open Program then Block Editor, and click Add Block Schedule.

1. Choose the academic year being planned.
2. Set Start date and End date. The default is July 1 to June 30.
3. Choose 4-Week Blocks, 2-Week Blocks, or Calendar Months.
4. Pick the week-start day; if the start does not match, choose Long or Short first block.
5. Choose whether to split 4-week blocks into 2-week A/B halves.
6. Review B1-B13. Edit any date; contiguity is enforced, and the last end is the year anchor.
7. Click Save Schedule.

Blocks are at least seven days and contiguous: one end plus one day equals the next start. Mid-week starts, a prolonged first block, and an abridged last block are valid. A wrong anchor shifts every later block, so check B1 and B13.

Block 0 and the pre-block window

Block 0 covers the seven days before Block 1. Enter pre-year shifts so rest, hours, and day-off math continues into the first block. It is for first-year setup; once prior data exists, history comes from assignments.

Set availability

The grid is resident by half-block. Checked EM means available for EM shifts; unchecked is off-service, becomes strong off, and gets no EM shifts.

Availability is per half-block, so a resident can be on EM for A and off-service for B. Edit by hand or use Populate via AI, which copies a prompt, takes a block schedule through any AI chat, stages rows, and maps them to residents. Save the block schedule first; it only populates an existing structure.

The Residency Settings checkbox Include visiting residents in schedule solver is inverted. When it is off, off-service residents such as FM, IM, TY, visiting, and medical students are treated as a bonus and excluded from the solver, but can still be placed manually over a fully staffed shift. It is hidden in Simple mode.

Run the solver

Schedule Generator has six sections: Block (site, dates, length), Shift Selection, Staffing, Blackout Constraints (hidden in Simple mode), Scheduling Parameters, and Review & Generate. The browser builds a JSON payload and multiplies weights by 1000; the backend normalizes them. The solver handles one date range at a time; cross-block effects enter as prior history.

Reality Check

Reality Check compares resident capacity against hospital demand. A failed check does not block you: the button becomes Reality check failed - start anyway. Fixing the configuration is faster than solving an impossible model.

Choose a time budget

Choose Quick Solve (15s), Standard Solve (30s), or Deep Optimize (60s). This is a maximum, not a promise to use it all. Click Start Simulation. Production and sandbox submit to the async dispatcher and poll every three seconds; local development can POST directly. The overlay shows progress and elapsed time.

States are pending, processing, completed, and failed. A stale job fails after ten minutes; rows are reaped after seven days. There is no cancel or history; the result is durable only if deployed.

Review and deploy

The Simulation screen shows OPTIMAL (Proven) or FEASIBLE. OPTIMAL means no better objective is possible and is the only badge with an objective value. FEASIBLE means a valid schedule exists but optimality was not proven, and is still deployable.

Diagnostics show what the objective traded off. The high-impact panel lists top penalty contributors, but only backward rotation, short turnaround, and post-night recovery are exposed. Shortfall, load imbalance, soft off, non-intern gaps, group imbalance, prior night streaks, and permission mismatch are weighted but not shown.

The Night Equity Blockers panel shows night-count distribution and blocked slots. Night equity is a hidden hard rule: highest and lowest counts for comparable residents may differ by at most one. It can make a model infeasible, so check it before unrelated changes.

Deploy Schedule

1. Confirm the badge and diagnostics are acceptable.
2. Click Deploy Schedule.
3. If the range has active shifts, read Overwrite existing shifts? and confirm only when intended.
4. Wait for Engaged N assignments into the live schedule.

Deploy writes draft assignments with publish_state = 'draft'. It does not publish. The engage call soft-cancels Active assignments in the range, cancels pending swaps tied to them, and runs in one transaction.

Publish and distribute

The schedule editor's top bar has Publish (N) and Wipe (N), where N reflects the current scope.

• Publish (N) flips drafts to published and does not touch already-published shifts. Residents and the calendar feed can then see them.
• Wipe (N) soft-cancels every active assignment in scope, draft and published, and cancels non-terminal swaps tied to them. It cannot be undone.

There is no unpublish or revert-to-draft. Correct a published schedule by editing assignments or wiping the scope and rebuilding. Treat publication as a one-way gate.

Distribute Schedules lists personal webcal:// and public-schedule links and can copy an email body. It is not a publishing step. The Public Schedule is read-only and strips email, numeric user ID, role, and quota, showing display name, full name, PGY, service, and published shifts. See Calendar sync.

Manual overrides and fill

The editor has View, Fill, and Swap modes. Fill lists residents as rows and candidate slots, colored ideal, tight rest, or warning. It uses an 8-hour rest threshold; the solver and swap engine use 10 hours.

• Fill mode: select a resident, then click an eligible slot. It checks same-day conflicts, rest, capacity, and required permissions.
• Add Assignment: click an empty slot, choose a provider, optionally mark orientation, and save.
• Manual Provider Override: clicking an occupied shift to replace its provider warns that this bypasses all conflict checking and is almost certainly not what you want. Use Swap Shift for trades.
• Edit Hours: change the start and end for every provider in a slot; the dialog states how many will be updated.

Add Assignment lists users across roles without requiring a matching service or PGY. Fill mode checks permissions and prefer but still uses 8-hour rest. Verify service, PGY, and supervision eligibility yourself.

An 8-to-10-hour manual turnaround can be accepted but make the next solve infeasible, because the solver requires 10 hours. Undo covers fill, drop, and chief swap execution only, not publish, wipe, engage, Add Assignment, or Manual Provider Override.

Annual promotion

Annual Promotion always stages current academic year plus one. Defaults: Incoming-PGY-1 becomes PGY-1, PGY-1 becomes PGY-2, PGY-2 becomes PGY-3, PGY-3 graduates or can be promoted to PGY-4, and PGY-4 graduates. Review every row; graduating residents get no next-year status row.

The wizard writes only the per-year status record. It does not create schedules, move assignments, or change current-year visibility. Incoming-PGY-1 stays invisible until the year rolls over, and current schedules are unaffected.

Roles and access

User administration lives in Users, with role defaults in User Roles.

• Quota defaults: strong off 4 per academic year, weak off 12, swap requests 10. A per-user override wins.
• What counts: off-request quota counts pending and approved; swap quota counts pending target, pending chief, and approved, only for the requester. Chiefs and above are exempt.
• Chief flag: the Admin / chief checkbox is enabled only for Super User and above.
• Permissions: custom definitions can be required by a shift and are checked in Fill mode. The manager is hidden in Simple mode.
• Passwords: Admin and Superduper can set one from the user editor: 8 to 200 characters, 10 changes per actor per hour, and it revokes Better Auth sessions.
• Applications: Admin and Superduper review them in Onboarding (heading Applications Admin). Super Users do not see them.

Simple mode hides quota columns, the yearly quota block, Permission Definitions, and the visiting-resident checkbox. It hides controls, not data; effective quotas and permissions still apply.

Limitations to know

These are product gaps, not configuration mistakes. The full comparison is in ACGME compliance.

The solver defaults to five consecutive nights; the swap engine allows six. One day off in seven caps consecutive work at six days.

Animation walkthroughs

These short walkthroughs cover the three setup tasks that most often cause support questions: importing a roster, defining site shifts, and importing a block schedule. Each player has chapter controls and a scrubber. The written steps beneath each player match the animation.

Import users into your roster

Set up shifts for a hospital or site

Import your block schedule

For the rules behind the solver and swap checks, see ACGME compliance. For trades and chief approvals, see Shift swaps. For calendar and public links, see Calendar sync. For quick answers by role, see the FAQ.