# First-shift tutorial

Status: implemented for v0.8.0. The tutorial teaches the real controls and the real
inspection/wheel/radio panels; it is not a fake UI or a separate combat mode.
Scripted test/capture runs bypass it unless `--tutorial` is passed; a windowed
smoke covers completion, replay and skip.

## Rules

- One short, safe, compliant visitor. No emergency, threat, crowd panic or random
  event can interrupt the tutorial.
- Prompts advance on the performed action, not on a timer. The player can keep
  moving/looking while a prompt is visible.
- The tutorial is skippable at any point (F1). Completion and skip are both
  persisted separately; a skipped tutorial can be replayed from Settings.
- The tutorial state machine is independent of the shift FSM. It observes the
  same actions as normal play and must be deterministic for tests.

## Beat sheet

| # | Beat | Prompt | Advances when | Notes |
| --- | --- | --- | --- | --- |
| 1 | Arrive | "Walk forward and look around. The entrance is behind you." | The guard has moved at least 1 m and looked away/returned | Start at the normal guard post, facing the street. |
| 2 | Focus | "Look at the visitor. Press Tab or the mouse wheel to cycle targets." | A target is acquired and explicitly cycled | The visitor waits at the foot of the steps; no other guest is required. |
| 3 | Wheel | "Open the action wheel with Space or left click." | The radial wheel opens on the visitor | The wheel is the real de-escalation-first wheel. |
| 4 | Inspect | "Choose Inspect and read the access evidence." | The inspection panel is opened and the policy result is visible | Use a valid wristband so the tutorial can teach both evidence and a safe admit/deny decision. |
| 5 | Direction | "Close the panel and give a polite direction." | A Level 1 polite-direction action is applied | The visitor complies; there is no escalation requirement. |
| 6 | Warning | "Give a formal warning if the visitor persists. It arms the body camera." | A Level 2 warning is applied or the body camera is switched on | Show the REC overlay and the escalation cue. |
| 7 | Radio | "Open the assistance radio and submit a short report." | The assistance report is submitted successfully | A non-emergency assistance call; no responder is required to resolve the tutorial. |
| 8 | Review | "Finish the shift and review what happened." | The shift review opens | The tutorial ends; the real review remains available for inspection. |

## Visitor script

- Display name: `Visitor`.
- Intent: `enter` (approaches the door, then waits for interaction).
- Access: valid wristband evidence; the policy result should be unambiguous.
- Behavior: compliant at every escalation level; never becomes a threat, never
  joins a crowd and never triggers an emergency.
- Failure handling: if the player denies admission incorrectly, the tutorial
  explains the evidence but does not fail the run; the visitor remains safe and
  the review records the decision.

## Persistence and replay

Settings gain `tutorial_completed` and `tutorial_skipped`. A first launch starts
the tutorial after venue selection. Skipping sets `tutorial_skipped`; Settings/
Help offers "Replay tutorial", which clears both flags for the next shift.