Break the README into focused docs pages

docs/getting-started.md

@@ -0,0 +1,97 @@
+# Setup, Run and Test, and Controls
+
+## Setup
+
+1. Download the Godot 4.3 editor (official build) and put `godot` on your PATH.
+2. Open or run the project from this directory.
+
+## Run and Test
+
+```bash
+# Open in the editor
+godot --editor --path .
+
+# Run the game
+godot --path .
+
+# Headless smoke boot (120 frames then exit)
+godot --headless --path . --quit-after 120
+
+# Run all unit tests headlessly (exit code 0 = pass)
+godot --headless --path . --script res://src/test/test_runner.gd
+
+# Save a screenshot to user:// (windowed)
+godot --path . --script res://src/test/take_screenshot.gd
+
+# Visual-regression smoke: render the staged captures + prop gallery, then compare them
+./tools/check_screenshots.sh
+
+# Windowed control smoke: focus circle, action wheel, wheel cycling + right-click clear; saves PNGs, exits 1 on failure
+godot --path . --script res://src/test/smoke_focus_radial.gd
+
+# Session-shell smoke: menu → shift → pause → settings → menu (headless or windowed)
+godot --headless --path . --script res://src/test/smoke_session_shell.gd
+
+# PLAN-verb smoke: recognize, request reason, body camera, warning, blocking
+godot --headless --path . --script res://src/test/smoke_plan_verbs.gd
+
+# Prop-collision smoke (windowed): guard stops at a bench, guest routes around it
+godot --path . --script res://src/test/smoke_props.gd
+
+# NPC budget smoke: 16 full-rig avatars against the documented frame budget
+godot --headless --path . --script res://src/test/smoke_npc_budget.gd
+
+# Movement smoke (windowed): steps, precision walk, footsteps and landing
+godot --path . --script res://src/test/smoke_movement.gd
+
+# Crowd smoke: rubbernecking on aggression, panic clearing the entrance
+godot --headless --path . --script res://src/test/smoke_crowd.gd
+
+# Emergency smoke: unjustified call, investigation note, evacuation aftermath
+godot --headless --path . --script res://src/test/smoke_emergency.gd
+
+# Body-camera timeline smoke: review → timeline → step through → back to review
+godot --headless --path . --script res://src/test/smoke_timeline.gd
+
+# Audio smoke: crowd bed follows mood, radio open/close crackle
+godot --headless --path . --script res://src/test/smoke_audio.gd
+
+# Scenario-content smoke: wand refusal, celebrity crowd spike
+godot --headless --path . --script res://src/test/smoke_scenario_content.gd
+```
+
+The unit test runner is the project's own lightweight harness (no editor plugin required) so CI can run it without the editor.
+
+## Controls
+
+Keyboard and mouse are the default; a gamepad works without configuration (left stick moves,
+right stick looks, A opens/confirms the wheel, B cancels, X inspects, Y calls the radio, LB walks
+slowly, RB uses the wand). Keys and pad buttons can be rebound in Settings, and the remaps persist
+in `user://settings.json`. The HUD legend switches to gamepad hints when a pad event arrives.
+
+| Input | Action |
+| --- | --- |
+| W/A/S/D + mouse | Move and look |
+| Space / left click | Action wheel for the focused person (Stop, Look, Point, No, Ask, Inspect, Wand, Warn, Block, Reason, Recognize, Radio) |
+| A / D or ←/→ | Step through the action wheel (while it is open) |
+| Space / left click | Confirm the highlighted action (while the wheel is open) |
+| Esc / right click | Close the top panel; Esc with nothing open pauses the shift (Esc again resumes) |
+| ← / → or ↑ / ↓ | Navigate the venue menu and the pause / settings panels |
+| Enter | Start the highlighted venue from the menu, or confirm in a panel |
+| 1 / 2 / 3 | Quick gestures without the wheel: raise hand, point, head shake (Level 1) |
+| Q | Polite direction (Level 1) |
+| 4 | Formal warning (Level 2) |
+| 5 | Blocking and positioning (Level 3) |
+| 6 | Security assistance radio (Level 4) |
+| R | Emergency radio, hold on-screen button ~1.6s (Level 5) |
+| E | Inspect access artifacts / close inspection |
+| C | Handheld wand screening (wand venues only) |
+| A / D | Allow / deny entry during inspection or wand check |
+| V | Cycle venue (debug shortcut; restart via V restarts the current shift) |
+| Tab / mouse wheel ↓ / ↑ | Cycle the target among nearby NPCs, nearest first (aim-free; the target stays selected) |
+| Right click (nothing open) | Clear the focused person and return to aim-based focus |
+| Shift (hold) | Precision walk at roughly half speed for close work at the door |
+| G | Toggle flashlight (widens NPC perception at night) |
+| B | Toggle the body camera; a formal warning switches it on automatically |
+| L | Lock / unlock the restricted door (thwarts forced entry) |
+| F | Toggle debug overlay |