# Circuit user guide

Version: private preview  
Service: <https://circuit.oscebank.info>

Circuit runs human-led mock OSCEs. Organisers create the event and schedule,
examiners control prompt release and mark students, and students see only the
station information they are allowed to see.

## The whole workflow

1. An organiser creates an organisation.
2. The organiser adds students and examiners through email-locked invites or a
   temporary shared join code.
3. The organiser creates reusable templates in **Station bank**.
4. The organiser creates an event, adds stations and generates or edits the
   schedule.
5. Students and examiners sign in with the invited Google account.
6. On the day, the organiser checks attendance and starts the circuit clock.
7. An examiner presses **Start & release prompt** for their assigned student.
8. The student’s locked screen immediately changes to the candidate prompt and
   countdown.
9. The examiner records marks, replay events and feedback, then submits.
10. The organiser reviews, locks and releases results.
11. Students receive their station results, criterion breakdown, cross-station
    themes and OSCE Replay.

## First sign-in

1. Open <https://circuit.oscebank.info>.
2. Select **Continue with Google**.
3. Use the same email address the organiser pre-registered or invited.
4. Choose your starting intention. This does not grant access; the secure
   organisation membership determines what you can do.
5. If you received a direct invitation link, open it while signed into the
   matching Google account.
6. If you received a shared eight-character code, choose **Join an
   organisation** and enter it.

If Circuit says the invite is email-locked, sign out and use the exact invited
Google account. Do not share a one-use link.

## Organiser guide

### 1. Create the organisation

On first use, choose **Create an organisation**, enter its display name and
continue. The creator becomes the owner. Owners and organisers can build
events, manage participants and release results.

Use the organisation switcher at the top right if your account belongs to more
than one organisation.

### 2. Add participants

Open **Participants**.

For a planned cohort:

1. Paste a list or import CSV data using `name,email,role`.
2. Use `student` or `examiner` as the role.
3. Generate individual, email-locked, one-use invitations.
4. Download the invitation sheet and distribute each person’s own link.
5. Watch the joined status before the event.
6. Review **Organisation members** and correct any examiner or student role
   before generating the schedule.

Students can be pre-registered before they create an account. When they later
sign in with the same verified Google email, Circuit links their assignments.

For a last-minute replacement, generate a temporary shared student or examiner
code. Revoke codes that are no longer required.

Role changes take effect immediately, but Circuit deliberately does not rewrite
existing assignments. If you change someone from examiner to student, or the
reverse, review every affected schedule slot before continuing. Owners can also
promote a trusted joined member to organiser; organisers cannot grant organiser
or owner access.

### 3. Configure the workspace

Open **Settings** to:

- update the organisation name shown to joined users and active invitations;
- choose the default station duration and venue for this browser;
- review the prompt, result-release and data-handling safeguards.

Renaming an organisation does not change event titles or historical marks.

### 4. Build the station bank

Open **Station bank**. This is the reusable library, separate from any one
event.

For each template:

- use a clear title;
- write the candidate prompt exactly as it should appear after release;
- add one observable action per mark-scheme row;
- mark safety-critical criteria as critical;
- avoid real patient-identifiable information.

Templates can be edited, duplicated, reused in multiple events and removed when
no longer needed. Adding a template to an event creates an event-specific copy,
so later template edits do not silently change historical mocks.

### 5. Create the event

Open **Events**, then **Create event**. Set:

- event name;
- station duration;
- date and start time;
- venue;
- private organiser notes.

Inside the event, use the three pages:

- **Build** — details, stations, participants and schedule;
- **Live control** — attendance, clock, exceptions and day-of changes;
- **Results** — completeness, quality assurance, export and release.

Draft events are safe to edit. Publish only after the candidate-facing details
and schedule are ready.

### 6. Add stations and locations

In **Build**, add reusable templates from the station bank or create an
event-specific station. Give every physical station a clear location, such as
“Room 2 · Clinical Skills”.

Use duplicate and reorder controls to shape the circuit. Check every candidate
prompt and mark scheme before generating the schedule.

### 7. Generate and check the schedule

Select the joined or pre-registered students, examiners and stations, then
generate a round-robin rotation. Circuit prevents the same student or examiner
from occupying two assignments in the same round.

You can:

- search and filter assignments;
- reassign one student or examiner;
- swap two students or two examiners atomically;
- preview conflicts before committing;
- mark a student absent and later restore them;
- change the schedule during the event.

Every operational schedule change is written to the audit trail. Never edit
several related rows independently when a swap action is available.

### 8. Run the preflight

Before candidates arrive:

1. Confirm every station has a prompt, mark scheme and location.
2. Confirm every student and examiner is represented in the schedule.
3. Use **Participants** to chase anyone who has not joined and verify every
   joined person’s role.
4. Test one ready → live → completed assignment.
5. Confirm the student sees **Prompt locked** before examiner start.
6. Confirm results remain hidden after examiner submission.
7. Print the emergency pack from **Live control**.
8. Nominate the chief organiser and paper-reconciliation owner.
9. Prepare venue Wi-Fi, a hotspot, chargers and spare devices.

### 9. Run the live circuit

Open **Live control** on a laptop or large tablet.

1. Check students in and record late, break or withdrawn states.
2. Start the circuit clock when the room is ready.
3. Watch ready, live, completed and absent counts.
4. Investigate overdue live attempts and missing submissions.
5. Pause before making a disruptive whole-circuit change.
6. Advance only after the confirmation shows the intended next round.

An examiner controls each candidate prompt independently. Starting the global
clock does not reveal every prompt.

### 10. Review and release results

Open **Results** only after all assignments are completed or deliberately marked
absent.

1. Review missing submissions and unusual values.
2. Check station performance and common missed criteria.
3. Use examiner comparison as a calibration prompt, not proof that anyone
   marked incorrectly.
4. Lock the review snapshot.
5. Export attendance and results CSV.
6. Release results.

If an assignment changes after the review snapshot, Circuit requires a fresh
review before release. Release is deliberate and cannot be inferred from event
completion.

## Examiner guide

### Before the station

1. Sign in with the invited Google account.
2. Open **Events** and select the correct mock.
3. Confirm candidate, round, station title and physical location.
4. Keep the device positioned so a waiting student cannot read examiner-only
   material.

The candidate prompt is locked on the student device until you start that exact
assignment.

### Start and mark

1. When the candidate is ready, press **Start & release prompt**.
2. Confirm their screen shows the correct prompt and countdown.
3. Tap mark-scheme criteria as they are achieved.
4. Use OSCE Replay shortcuts for useful moments such as strong empathy, missed
   red flag or good summary.
5. Choose a global rating.
6. Write concise feedback with one strength and one next priority.

Draft marks autosave after changes. Watch the save indicator:

- **All marks saved** — Firebase has acknowledged the draft;
- **Saving…** — wait;
- **Offline · changes queued** — do not submit until reconnected;
- **Draft save failed · retrying** — check connectivity and use paper fallback
  if it persists.

### Submit

Press **Submit marks & complete** once. The attempt changes to completed and the
student sees only “Station complete” until the organiser releases results.

If the device fails, record marks on the printed emergency sheet, sign it and
tell the chief organiser. Never ask another examiner to use your signed-in
account.

## Student guide

### Before the event

1. Open your individual invitation link.
2. Sign in using the exact invited Google email.
3. Confirm the event appears in **Events**.
4. Keep your device charged and allow normal internet access.

### Moving between stations

Your queue shows round, station title, location and examiner. It does not reveal
future candidate prompts.

At a ready station you will see **Prompt locked**. Wait for the examiner. When
they press start, your screen updates automatically with:

- candidate instructions;
- the same server-aligned countdown used by the examiner.

At 00:00 the candidate prompt is hidden again. Do not refresh repeatedly while
waiting; schedule changes arrive automatically.

### Results

After the organiser releases results, each completed station shows:

- score and global rating;
- examiner feedback;
- achieved and missed criteria;
- critical criteria labels;
- timestamped OSCE Replay events.

The report also identifies repeated strengths and practice priorities across
stations when enough comparable criteria exist. Use **Print my report** to save
or print your copy.

## Day-of changes

- **Student has not signed up:** keep the pre-filled email assignment. Ask them
  to sign in with that verified Google account; Circuit links it automatically.
- **Different student attends:** use a replacement invite, then reassign or
  swap with conflict preview.
- **Examiner changes:** invite the replacement and reassign their slots.
- **Student is absent:** mark the affected assignment absent with a reason;
  restore only if they return and the round remains safe.
- **Station runs late:** inspect the overdue alert, then pause or recover the
  attempt deliberately.
- **Wrong person is shown:** do not start. Resolve the assignment first.

## Connectivity and fallback

Every role has a connectivity banner. For a venue-wide outage:

1. pause the circuit;
2. test a hotspot;
3. switch to the printed emergency pack if the outage continues;
4. sign and timestamp paper marks;
5. reconcile with two authorised people before result release.

Full procedures are in `docs/INCIDENT_RUNBOOK.md` in the project repository.

## Data handling

- Use fictional or de-identified station cases only.
- Do not enter real patient identifiers or candidate health information.
- Restrict CSV exports and paper mark sheets to authorised people.
- Export before approved deletion.
- Review identifiable pilot event data for deletion within 90 days of result
  release unless the organisation documents another necessary period.

The pilot does not yet include self-service recursive account/organisation
deletion. Verified deletion requests require the service operator.

## Recommended device use

- Organiser control room: laptop or large tablet.
- Examiner mark sheet: phone, tablet or laptop; portrait phone is supported.
- Student prompt: phone or tablet; keep the screen awake during the station.
- All roles: use a current browser, avoid private browsing for the live event
  and do not share accounts.

## Support checklist

When reporting a problem, provide:

- event name;
- role;
- round and station title;
- approximate time;
- what the screen said;
- whether the device was online.

Do not send candidate marks, prompts, invite codes, authentication tokens or
screenshots containing unrelated participant data unless the authorised service
operator specifically requires and secures them.