Reorganize docs into category folders and drop the retired head-review page

Group the top-level docs into docs/project, docs/design, docs/assets and
docs/process, each with its own README index. Delete the superseded
docs/screens/head-review page and sheets. Rewrite every markdown link,
absolute docs path and tool/test reference to the new locations, fix the
pre-existing broken anchors and remove the dead Joke Shop photo-board link.
check_docs OK, Python tooling 167/167.

docs/design/gameplay.md

@@ -0,0 +1,118 @@
+# Gameplay
+
+The complete design rationale also lives in [`PLAN.md`](../../PLAN.md); this page keeps the playable mechanics close to the README.
+
+## Game Overview
+
+A typical shift lasts 10–15 minutes. The first-person camera stays at the gameplay height of 1.7 m; the concept frames use a lower ~1.55 m reference camera, but gameplay readability and body-camera framing take priority. The player:
+
+1. Watches the entrance, steps, queue, and surrounding sidewalk.
+2. Determines why each person is approaching.
+3. Uses simple gestures or polite directions first.
+4. Verifies authorized access using recognition, wristbands, credentials, tickets, or guest lists.
+5. Escalates only when a person refuses directions, attempts unauthorized entry, or presents a genuine threat.
+6. Records the incident through body-camera and radio systems.
+7. Finishes the shift with a performance review based on safety, judgment, and professionalism.
+
+The game rewards calm resolutions rather than aggressive behavior. Emergency assistance and armed responders are rare last-resort systems with meaningful consequences.
+
+The first shift starts with an in-game tutorial covering movement/look, focus cycling, the action wheel, access inspection, polite direction, formal warning/body camera, radio and shift review. See the tutorial section below. After that a short campaign runs Hollywood → Joke Shop → TV Studio; progress, difficulty and a pause-safe checkpoint are persisted locally. Help (from the venue menu) explains the controls and the current venue policy.
+
+## Venues
+
+### El Capitan Entertainment Centre (6840 Hollywood Blvd)
+
+The map is a stylized reconstruction of the real building and block; the
+reference notes and geometry mapping are in
+[`venues.md`](venues.md#hollywood-boulevard). The venue menu
+offers the same map as **Hollywood Boulevard — Day** and **Hollywood Boulevard
+— Night**; the night variant starts directly in the late phase instead of
+waiting for the shift clock.
+
+The original scenario — the starting point of the campaign — places the guard at the top of the eight stone steps outside the historic Masonic Temple / El Capitan Entertainment Centre on Hollywood Boulevard, the building that houses the *Jimmy Kimmel Live!* stage and studio. Tourists, street performers, influencers, confused visitors, intoxicated pedestrians, trespassers, people experiencing a mental-health crisis, and rare violent threats may approach the entrance.
+
+Authorized people must either be recognized by the guard or present a valid wristband. Wristbands can have different colors, patterns, dates, or event markings. They may be valid, expired, counterfeit, or missing.
+
+### The Joke Shop
+
+The Joke Shop is a Sunset Strip comedy club inspired by the real Comedy Store at 8433 Sunset Blvd: a black hall under a deep signature-covered canopy, a circular blade sign, red velvet curtains, a west-end entrance, neighbouring low-rise frontage and a dry hillside of houses behind. The real-site mapping is in [`venues.md`](venues.md#the-joke-shop). The door person checks IDs, tickets, reservations, and guest-list status, then uses a handheld security wand according to venue policy. The player must interpret wand alerts rather than treating every alert as proof of a weapon; keys, belts, phones, and other harmless objects can trigger false alarms.
+
+### Hollywood Boulevard Late Night TV Studio
+
+This scenario combines the previously defined NPC types with a busy television-studio entrance: the same El Capitan Entertainment Centre block as the Hollywood day shift, restaged as a late-night studio arrival — the stone facade and steps, a bulb-lit canopy, a glossy black car at the curb, and stanchions/barriers holding the arrival line. The player manages audience members, production staff, performers, guests, deliveries, celebrity arrivals, tourists, street performers, influencers, confused visitors, intoxicated pedestrians, trespassers, people experiencing a mental-health crisis, and rare violent threats.
+
+The studio uses wristbands, credentials, tickets, guest-list confirmation, and personal recognition to authorize entry. Crowd control, filming boundaries, following authorized guests through the door, and counterfeit credentials are key events.
+
+## Escalation Model
+
+The common escalation model has six levels:
+
+0. **Observation** — Decide whether intervention is necessary.
+1. **Simple deterrence and polite direction** — Raise an open hand, make eye contact, point toward the sidewalk or check-in area, shake the head, or give a short instruction.
+2. **Formal warning** — Clearly explain the rule and request compliance.
+3. **Blocking and physical positioning** — Secure the entrance, maintain distance, preserve an escape route, and deny access without starting a fight.
+4. **Radio for security assistance** — Request a supervisor, second guard, building management, or other appropriate support.
+5. **Emergency response** — Hold the emergency-radio button and confirm only when there is an immediate threat, such as a weapon, assault, forced entry, or serious threat to occupants.
+
+An off-duty law-enforcement officer or armed emergency responder may arrive during a valid emergency. This character is not intended to be a routine stronger attack. Their role is crisis control, evacuation, restraint, arrest, or other appropriate intervention, with force governed by the situation and meaningful consequences for unjustified calls.
+
+## Core Systems
+
+- **NPC behavior:** NPCs have different motivations, temperaments, compliance levels, and reactions to the player’s approach.
+- **Access verification:** Recognition, wristbands, IDs, tickets, credentials, and guest lists determine who may enter.
+- **Nonverbal deterrence:** Small actions such as raising a hand can resolve low-risk situations without dialogue or force.
+- **Dialogue:** Polite directions and warnings affect outcomes; simple gestures can resolve low-risk situations without dialogue.
+- **Escalation:** The player chooses the lowest effective response.
+- **Radio assistance:** Calls require useful information and may take time to arrive.
+- **Evidence:** Body-camera records support shift review and accountability.
+- **Crowd reaction:** Aggressive behavior, visible weapons, and emergency response can create panic or attract a crowd.
+- **Reputation:** Peaceful resolutions, accurate reports, low property damage, and justified calls improve performance; unnecessary confrontations and false reports reduce it.
+- **Shift review:** The player receives feedback on access decisions, escalation choices, public complaints, injuries, and security outcomes.
+
+## 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.