security-game/docs/tutorial.md

First-shift tutorial

Status: planned 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.

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. Completion and skip are both persisted separately; a skipped tutorial can be replayed from Help/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.