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/process/README.md

@@ -0,0 +1,11 @@
+# Process Documentation
+
+Setup, quality assurance and releasing.
+
+- [`getting-started.md`](getting-started.md) — setup, run/test commands, controls and save data.
+- [`release-qa.md`](release-qa.md) — the manual smoke checklist and the balance-acceptance
+  protocol.
+- [`RELEASING.md`](RELEASING.md) — export templates, release build, CI/publishing and rollback.
+
+Up: [`../README.md`](../README.md) · Product plan: [`../../PLAN.md`](../../PLAN.md) · Tasks:
+[`../../TODO.md`](../../TODO.md).

docs/process/RELEASING.md

@@ -0,0 +1,211 @@
+# Releasing Gig Line
+
+This guide describes how to produce downloadable executables and publish them
+so the README "Downloads" links always point at the latest release.
+
+## 1. Install export templates
+
+Godot needs platform export templates to build standalone binaries. The first
+time you export, either:
+
+- Open the editor and use **Editor → Manage Export Templates** (downloads the
+  matching templates), or
+- Install them manually from the
+  [Godot downloads](https://godotengine.org/download/) page by placing the
+  `Godot_v4.7.2-stable_export_templates.tpz` contents into
+  `~/.local/share/godot/export_templates/4.7.2.stable/`.
+
+The templates must match the editor binary you use locally. CI and local
+development both use Godot 4.7.2 with its matching templates. Verify with:
+
+```bash
+godot --headless --export-release "Linux" build/gig-line-smoke.x86_64
+```
+
+## 2. Bump the version
+
+`project.godot` sets `config/version`. Keep it in sync with the release tag
+(e.g. `v0.3.0` → `config/version="0.3.0"`, plus a git tag `v0.3.0`).
+
+Every major, minor and patch increment is a version in its own right: add the
+`CHANGELOG.md` entry, run the local build (`tools/build_releases.sh`), verify the
+artifact names/sizes/checksums, and only then commit and tag. A changelog entry
+without a matching build is not a completed version. Unversioned development tracks
+do not get a placeholder version; assign one when the scope enters a release.
+
+## 3. CI (Gitea Actions)
+
+The repository ships a Gitea Actions workflow (`.gitea/workflows/build.yml`):
+
+- Every push/PR runs the **checks** job: Godot 4.7.2 install, project import, and the
+  full headless test suite. This is the fast safety net.
+- **Tags (`v*`)** and **manual `workflow_dispatch`** runs additionally execute the
+  **build** job: export templates install, import, `tools/build_releases.sh` for
+  Linux/Windows/macOS, artifact upload, and — on tags — release publication via
+  `tools/publish_release.sh`.
+
+`tools/publish_release.sh` picks the first available credential, in order:
+
+1. `GITEA_TOKEN` (repo secret, write:repository scope),
+2. `GITEA_AUTH_HEADER` (a ready-made `Authorization: ...` header),
+3. `~/.git-credentials` for the host,
+4. the **local git extraheader** that `actions/checkout` configures on the CI job.
+
+Option 4 is what makes tag builds publish without any repo secret: the runner
+already injects basic-auth credentials for the checkout, and the script reuses that
+header for the API (same server). `github.token` is *not* available in this Gitea
+setup, so do not rely on it.
+
+> **Disk space:** Gitea stores release assets under `/var/lib/gitea/data/attachments` on
+> the host root filesystem (7.8 GB here). When it is full, asset uploads fail with
+> `HTTP 500 … no space left on device` and even `git push` can fail with "unpacker error".
+> `publish_release.sh` now verifies the asset count and exits non-zero, so this is visible.
+>
+> **Incident (2026-10-31):** `tools/publish_release.sh` never set `AUTH` in its
+> `~/.git-credentials` branch, so every API call failed silently (`AUTH[@]` was
+> unbound under `set -u`). Combined with no `GITEA_TOKEN` secret on the repo, tag
+> builds from v0.2.2 to v0.2.8 produced installers but published nothing. The script
+> is fixed (`AUTH=(-u "$CRED")`) and v0.2.9 was published locally with all five
+> artifacts. If CI publishing fails again, run
+> `./tools/publish_release.sh <version>` from a checkout with `~/.git-credentials`.
+
+> **Godot cache evaluation:** Gitea Actions cache was tested for the Godot binary and
+> trimmed 4.7.2 templates. Restores worked intermittently, but cache saves timed out
+> in `CreateCacheEntry` / were rejected as reserved by another job. The cache steps
+> were removed because they added restore/save overhead without a reliable hit.
+> Revisit when the host's Gitea Actions cache service is healthy; otherwise keep
+> downloading the binary/templates directly.
+
+> The workflow lives in `.gitea/workflows/` (Gitea's canonical path). The old
+> `.github/workflows/ci.yml` was removed to avoid double runs on hosts that scan
+> both directories.
+
+## 4. Local build (alternative to CI)
+
+```bash
+godot --headless --path . --script res://src/test/test_runner.gd   # all tests
+godot --headless --path . --quit-after 120                        # boot smoke test
+./tools/build_releases.sh
+```
+
+Artifacts are written to `build/` (all exports embed the PCK — single files):
+
+- `build/gig-line-linux-<version>.x86_64`
+- `build/gig-line-windows-<version>.exe`
+- `build/gig-line-macos-<version>.zip`
+- `build/gig-line-web-<version>.zip` — browser build (non-threaded Godot web
+  template; unzip and serve the folder, no COOP/COEP headers required)
+- `build/gig-line-desktop-hq-<version>.zip` — optional Forward+ Windows/Linux
+  build with `override.cfg`; requires a Vulkan-capable GPU/driver
+
+When run in CI (tags/dispatch), the build job also packages:
+
+- `build/gig-line-setup-<version>.exe` — Windows installer (NSIS, incl. shortcuts +
+  uninstaller; apt `nsis` on the runner)
+- `build/gig-line-<version>-x86_64.AppImage` — Linux AppImage (`packaging/linux/build_appimage.sh`,
+  appimagetool via `APPIMAGE_EXTRACT_AND_RUN`)
+
+The optional Desktop HQ zip is assembled by `tools/build_releases.sh` from
+`packaging/desktop_hq/`; keep `override.cfg` next to the extracted executable.
+It is not part of the default Compatibility/Web build.
+
+`tools/publish_release.sh` preflights every artifact for existence and non-zero
+size, checks free space in `build/`, writes `build/SHA256SUMS-<version>.txt`, and
+uploads only after those checks pass. If an upload or the final asset-count check
+fails, it removes the assets it just uploaded (and removes a newly created
+release) so the host never keeps a partial release. Use
+`PUBLISH_DRY_RUN=1 ./tools/publish_release.sh` to run the preflight and checksum
+steps without touching the API. Set `RETAIN_RELEASES=7` to prune older releases
+after a successful publish; the default `0` disables pruning and never deletes
+history implicitly. A retention of seven keeps the newest seven releases,
+including the latest 0.8/0.9 line.
+
+### 0.10.0 macOS signing decision
+
+The 0.10.0 release candidate will continue to ship an **unsigned** macOS zip with
+the documented right-click/`xattr` quarantine instructions. Signing and
+notarization remain a public-release blocker until an Apple Developer account and
+a reproducible signing/notarization job are available; they are not silently
+claimed as complete. The same limitation is recorded in
+[`known-limitations.md`](../design/known-limitations.md).
+
+Always run the release build from a clean checkout or detached worktree. Godot
+can pack files from ignored `tmp/` and old `build/` folders into the PCK; the
+0.9.6 dirty-tree build produced 1.6–3.1 GB artifacts, while the clean worktree
+produced the expected ~160–240 MB packages.
+
+Locally you can build the AppImage with `bash packaging/linux/build_appimage.sh <version>`;
+the NSIS installer requires `makensis` (covered by CI).
+
+> macOS builds are unsigned and will need `xattr -dr com.apple.quarantine`
+> guidance or notarization for production releases.
+
+## 5. Publish on the repository host (Gitea/Forgejo)
+
+The repository lives at `https://git.allucanget.biz/zwitschi/security-game`.
+
+Preferred path — use the helper script. It needs either a token or the same
+credentials used by `git push` (it falls back to `~/.git-credentials`):
+
+```bash
+GITEA_TOKEN=your_api_token ./tools/publish_release.sh 0.2.1
+# or simply: ./tools/publish_release.sh 0.2.1   (uses ~/.git-credentials)
+```
+
+The script creates (or reuses) the release from `project.godot`'s
+`config/version`, uploads the three portable artifacts **plus** the NSIS
+installer, AppImage, Web zip and Desktop HQ zip when present, and prints the
+release URL. If CI already
+published the release, re-running the script only adds missing assets.
+
+> **Host note**: the release is fully built by CI, but anonymous users can only
+> browse and download when the instance sets `[service] REQUIRE_SIGNIN_VIEW=false`
+> in `app.ini` (the repo itself is public). This is a host-admin setting, not a
+> repository file.
+
+Manual alternative:
+
+### Via the web UI
+
+1. Create a **New Release** with tag `v<version>`.
+2. Attach all artifacts from `build/` (portables, installer/AppImage, Web and optional Desktop HQ).
+3. Write release notes (see checklist below).
+
+### Via the API
+
+```bash
+TOKEN="your_api_token"
+REPO="zwitschi/security-game"
+VERSION="0.3.0"
+API="https://git.allucanget.biz/api/v1/repos/$REPO/releases"
+
+# Create the release
+RELEASE_JSON=$(curl -s -X POST "$API" \
+  -H "Authorization: token $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "{\"tag_name\":\"v$VERSION\",\"name\":\"v$VERSION\",\"body\":\"Playable prototype release.\"}")
+
+RELEASE_ID=$(echo "$RELEASE_JSON" | python3 -c "import sys,json;print(json.load(sys.stdin)['id'])")
+
+for f in build/gig-line-*"$VERSION"*; do
+  curl -s -X POST "$API/$RELEASE_ID/assets" \
+    -H "Authorization: token $TOKEN" \
+    -F "attachment=@$f"
+done
+```
+
+## 6. Update the README
+
+The **Downloads** section links to the host releases page
+(`https://git.allucanget.biz/zwitschi/security-game/releases`), so no README
+edit is needed when the page follows the naming pattern. If artifact names
+change, update `tools/build_releases.sh` first.
+
+## Release notes checklist
+
+- [ ] All headless tests pass (exit code 0).
+- [ ] Game boots cleanly in a smoke test.
+- [ ] Controls documented in `docs/process/getting-started.md` match the build.
+- [ ] Version in `project.godot` matches the tag.
+- [ ] Export templates used are the official ones for the pinned engine.
+- [ ] Artifacts uploaded; README downloads page shows them.

docs/process/getting-started.md

@@ -0,0 +1,129 @@
+# Setup, Run and Test, and Controls
+
+## Setup
+
+1. Download Godot **4.7.2** (official build) and put `godot` on your PATH. The project, local tooling and CI use the same version; engine upgrades require import, headless, screenshot and Desktop HQ smoke checks before changing the baseline.
+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
+
+# Check docs README coverage, tracked images and local links
+python3 tools/check_docs.py
+
+# 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
+
+# End-to-end interaction smoke: inspection, radio, Help search, wand and review
+godot --headless --path . --script res://src/test/smoke_ui_flows.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: 24 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
+
+# Tutorial smoke (windowed): completion, replay and skip; isolated user data
+XDG_DATA_HOME=/tmp/gigline-tutorial godot --path . --fixed-fps 60 --script res://src/test/smoke_tutorial.gd -- --tutorial
+
+# Campaign/checkpoint smoke (windowed): resume, review continue, help; isolated data
+XDG_DATA_HOME=/tmp/gigline-campaign godot --path . --fixed-fps 60 --script res://src/test/smoke_campaign.gd
+```
+
+The unit test runner is the project's own lightweight harness (no editor plugin required) so CI can run it without the editor.
+
+## Save Data
+
+The game writes four JSON files in Godot's `user://` directory:
+
+| Platform | Location |
+| --- | --- |
+| Linux | `~/.local/share/godot/app_userdata/Gig Line/` |
+| Windows | `%APPDATA%\Godot\app_userdata\Gig Line\` |
+| macOS | `~/Library/Application Support/Godot/app_userdata/Gig Line/` |
+
+Files: `settings.json`, `campaign.json`, `shift_results.json` and the versioned
+`shift_state.json` checkpoint. The schema, migration/default-filling rules,
+atomic-write behavior and checkpoint contents are in
+[`architecture.md#persistence-and-save-contract`](../project/architecture.md#persistence-and-save-contract).
+
+For a clean first launch, delete the four files (or the whole `Gig Line` user
+directory). Settings' **Reset campaign** clears campaign progress separately.
+To back up or move a profile, copy the files while the game is closed; restore
+them to roll back. Shift history is diagnostic and not required to resume.
+
+## 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 |

docs/process/release-qa.md

@@ -0,0 +1,173 @@
+# Release QA and Balance
+
+Manual verification and the 0.10.0 balance protocol. The executable command
+matrix is in the release runbook/skill; this page owns the human smoke checks and
+the measurable balance targets. Architecture owns the gates themselves; gameplay
+owns the mechanics.
+
+## Manual smoke checklist
+
+1. `godot --path .` starts the game on the venue menu without script errors.
+2. Choosing a venue (click or ↑/↓ + Enter) starts that venue's shift and hides the menu.
+3. The guard moves and looks around; the building, steps, and sidewalk are visible.
+4. The guard's camera sits at eye height and the guard stands on the landing, not inside the building.
+5. Walking into the steps carries the guard up onto the landing (steps have colliders).
+6. The skyline backdrop shows silhouettes against the sky, not an opaque black slab.
+7. The `GIG LINE` marquee is readable from the sidewalk.
+8. NPCs spawn and approach the entrance during the first minutes.
+9. Looking at an NPC inside the focus cone shows a blue focus circle in front of the face, the person's name, and the HUD target line.
+10. `Space` or left click opens the action wheel; `A`/`D` highlight a slice, `Space` confirms it, `Esc`/right click cancels without a log entry.
+11. `E`/`C` open the inspection/wand panels from the wheel and freeze movement until they close; walking never fires the wand.
+12. Pressing `Q` produces a reaction log entry and reputation feedback.
+13. `E` opens access inspection showing venue-correct artifacts and policy result; `A`/`D` record a decision.
+14. `6` opens the assistance form; submitting shows dispatch feedback.
+15. `R` opens the emergency form; the button must be held ~1.6s or the call cancels.
+16. `G` toggles the flashlight (indicator appears in the HUD); `L` toggles the door lock (indicator turns red when locked).
+17. `F` toggles the debug overlay with NPC states and shift stats.
+18. The wheel's `Look` slice is eye contact (Level 1) and logs as its own action.
+19. `Reason` asks why the person is there and logs their `dialogue_lines` reply.
+20. `Recognize` records the guard's recognition as access evidence; pressing it twice says so.
+21. `Warn` turns the body camera on (REC overlay appears); `B` toggles it manually.
+22. `Block` moves the guard between the person and the door.
+23. The shift review reports the incident count, including interactions left unresolved.
+24. Escalating on someone (or a responder arriving) makes idle bystanders stop and face the incident.
+25. Repeated alarms panic the crowd and nearby people clear away from the door instead of standing around.
+26. `Esc` with nothing open pauses the shift; resume / restart / settings / quit-to-menu all work, and settings changes persist across a restart.
+27. NPCs route around the building using the navigation mesh (no stuck-at-wall behavior during a smoke run).
+28. An unjustified emergency call (calm person, no weapon) logs an investigation and costs reputation.
+29. After an evacuation outcome the door is locked and NPCs are leaving the entrance.
+30. The shift review's "Body camera timeline" button steps through the recorded events (Left/Right or the buttons) and Esc returns to the review.
+31. The escalation label shows a `[###--] L3/5` shape meter as well as the level name, and stays readable in grayscale.
+32. Changing "HUD font scale" in Settings resizes the HUD text and persists across a restart.
+33. When the shift timer reaches 0, the shift review screen shows grade, policy, incident summary, responder outcomes, investigations, and persisted shift history; campaign Continue starts the next venue.
+34. On a fresh profile the tutorial starts on Hollywood, advances through its eight beats, and F1 skips it; Settings Replay tutorial restarts it.
+35. Pausing saves a checkpoint: returning to the menu and choosing Continue resumes elapsed time, NPCs, incidents, door/flashlight state and campaign position.
+36. Settings difficulty changes spawn pacing/compliance/report strictness while escalation rules stay the same; Help filters controls and shows the venue policy.
+37. The F debug overlay lists the next eligible events; recovery events and recently played scripted events behave as authored.
+38. Master/SFX/ambience volume settings clamp at 0/1 and persist; Reduce motion disables head bob; the captions toggle persists.
+39. The 24-NPC budget smoke stays inside its frame budget; coats/dresses do not show obvious leg clipping in a normal walk.
+40. Help remains readable with the largest HUD font scale, and CI/local verification use the same Godot 4.7.2 baseline.
+41. UI copy: inspection/wand use "A = admit · D = refuse entry", review returns with "Return to menu", and application exit reads "Quit game".
+42. Button states remain readable on hover/focus/pressed; settings Apply/Cancel and radio normal-send/emergency-hold behave as labelled.
+43. The venue menu offers Hollywood Boulevard — Day and — Night; either starts the same map, and Night starts in the late phase with a full shift clock.
+44. The Joke Shop opens on the Sunset Strip club: the black hall, signature canopy, circular **THE JOKE SHOP** sign, red curtains, west entrance, palms, dry hillside with houses, neighbouring frontage and the opposite side of Sunset all read from the door camera. Day lighting and late lighting both look correct; the guard can walk the sidewalk without leaving the nav bounds.
+45. Esc and right-click close only the top panel (Help, Settings, Pause, Review, Radio, timeline, inspection/wand, action wheel); Settings opened from the venue menu returns to the menu, Help no longer opens Pause behind it, and closing a modal recaptures the mouse without leaving the guard frozen.
+46. At 0.75× and 1.75× HUD font scale, long target names stay inside the target chip, the chip grows/caps correctly, and long button labels ellipsize instead of pushing panels off-screen.
+47. Reset campaign and Replay tutorial both ask for confirmation; a second click reuses the open dialog, Cancel does nothing, and OK fires once. Emergency send requires the full hold, sends exactly once, and does not send again on release.
+48. UI copy/button sweep: every panel uses the canonical admit/refuse, warning/blocking, assistance/emergency and body-camera terms; the start menu, pause, settings, Help, inspection, wand, radio, wheel, timeline and shift review all show readable hover/focus/pressed/disabled states; Tab/arrow focus wraps without landing on hidden or disabled actions; Esc/right-click closes only the top panel; and destructive reset/replay plus emergency send still require their confirmation or hold.
+
+## Balance acceptance
+
+These are the acceptance targets for the 0.10.0 balance pass, not measured results.
+No reaction tables, event weights or scoring rules were changed to set them. The
+[roadmap](../../TODO.md) tracks the sweeps and external playtests still needed.
+[Gameplay](../design/gameplay.md) owns the mechanics; this page owns their balance-test protocol.
+
+### Test matrix and evidence
+
+Run Hollywood, Joke Shop and TV Studio on easy, normal and hard, in Early,
+Midday, Evening and Late: **36 cells**. Use seeds 1–100 for each cell and retain
+those seeds for before/after comparisons. Exercise each eligible authored event
+at least once as a separate coverage pass; a random schedule can miss rare events.
+Record scheduled event counts separately from forced coverage cases so the latter
+do not distort event-frequency estimates.
+
+For reaction measurements, use a fresh controller at the entrance for each sample.
+Routine cases are tourists, confused visitors and delivery workers obstructing the
+entrance without threatening behavior. Do not include authorized entry requests in
+this redirect cohort. For peaceful-resolution measurements, send one polite
+direction (L1), then one warning (L2) only if still unresolved. Do not reroll until
+success. Observe return behavior for 60 simulated seconds before closing the case.
+Do not issue emergency calls as part of this policy.
+
+For access cases, follow the venue's required inspection and screening steps before
+allow/deny. Include valid, expired, counterfeit, mismatched, missing and ambiguous
+artifacts, known recognition, age boundaries, screening refusal, benign wand alerts
+and prohibited items. Recognition must be independently justified by the fixture;
+calling a stranger recognized is not evidence of correct admission. An unresolved
+hold counts as unresolved, not as a correct refusal.
+
+Evidence must identify the commit, engine, venue, difficulty, phase, seed, event ID,
+cohort, visible evidence, policy action, reaction/state, return, access truth and
+decision, emergency truth and call, report fields, reputation modifiers, final grade
+and unresolved cases. Save raw rows plus numerator/denominator summaries for every
+cell. Use at least **100 eligible cases per metric per cell**; if the schedule
+provides fewer, add a separately labelled forced-case sample. Report zero eligible
+cases as **N/A**, never as 100% success. Keep scheduled and forced results separate.
+
+### Targets
+
+Percentages below apply to each matrix cell, not only a pooled average. Scripted
+access/report cases use complete evidence and are held to exact correctness;
+first-time-player results measure whether that evidence is understandable.
+
+| Metric | Numerator / denominator | Acceptance target |
+| --- | --- | --- |
+| First-direction routine compliance | First L1 reaction is `COMPLY` or `LEAVE` / eligible routine redirect cases | Easy ≥80%; normal ≥75%; hard ≥65% |
+| Routine peaceful resolution | Routine cases leaving after at most L1 then L2, with no return during 60 s and no L3–L5 / eligible routine redirect cases | Easy ≥90%; normal ≥85%; hard ≥80% |
+| Access accuracy | Correct final allow/deny decisions / all eligible access cases (including unresolved cases) | Scripted 100%; first-time players ≥90% pooled, with each error reviewed |
+| Access false positive | Unauthorized people allowed / unauthorized access cases | Scripted 0%; first-time players ≤5% pooled |
+| Access false negative | Authorized people denied / authorized access cases | Scripted 0%; first-time players ≤10% pooled |
+| Emergency precision | Calls supported by immediate-danger evidence / all emergency calls | Scripted 100%; first-time players ≥95% pooled; zero calls is N/A |
+| Emergency false positive | Routine/no-immediate-danger cases receiving an emergency call / all routine/no-immediate-danger cases | Scripted 0%; first-time players ≤5% pooled |
+| Emergency false negative | Immediate-danger cases without an accepted emergency call within 15 simulated seconds of visible danger / all immediate-danger cases with radio initially available | Scripted 0%; first-time players ≤10% pooled |
+| Report accuracy | Reports with correct weapon and danger fields / all submitted reports | Scripted 100%; first-time players ≥90% pooled |
+
+For access, authorized means entitled under the venue policy **after required
+screening**, without a prohibited item or an independent immediate-danger reason
+to refuse. Compare to a hand-labelled fixture expectation, not only to
+`AccessVerifier.verify()`: using the verifier as both decision and oracle would
+hide policy bugs. Report unresolved access cases separately; they cannot improve
+either error rate by being omitted from accuracy.
+
+Immediate danger means an observed weapon, assault, active forced entry or a
+credible immediate threat to occupants. Argument, filming, intoxication, a crisis,
+a refused screen or a benign wand alert alone is not immediate danger. A mental
+health label or clothing must never be used as the emergency oracle. The 15 s
+window is a test-response target, not the responder-arrival time (currently 15 s
+after an accepted emergency call). Separately test depleted battery and active
+cooldown cases for safe containment/assistance; do not silently drop them from the
+evidence or claim the initially-available-radio target covers them.
+
+### Scoring and emergency dominance
+
+Compare the calm policy with an emergency-first policy on the same routine events
+and seeds. Each comparison starts with fresh radio, crowd and reputation state.
+An accurate report about harmless behavior must not make its emergency call
+justified. Require an unjustified-call investigation and a strictly lower rating
+for emergency-first in every routine comparison. Inspect modifiers as well as the
+final rating: the 0–100 clamp can hide rewards/penalties. Emergency-first must not
+improve the campaign outcome or final grade. Grade boundaries remain A ≥90,
+B ≥75, C ≥60, D ≥40, otherwise F; these are existing rules, not new tuning.
+
+In genuine-danger cases, verify that the call is accepted, responders arrive,
+the incident remains answerable and the debrief explains the outcome without an
+unjustified-call investigation. Also compare assistance/containment routes where
+appropriate; emergency need not be mandatory for every difficult interaction.
+
+### Implementation cautions and sign-off
+
+- `NPCController.roll_reaction()` samples per-level weights. Difficulty adds
+  +12/0/−8 to the `COMPLY` weight before normalization; `base_compliance` alone
+  is not the observed compliance percentage. Measure `COMPLY` plus `LEAVE`.
+- `GameManager._read_npc_truth()` currently derives weapon/danger truth from the
+  NPC type (violent threat: weapon/3; everyone else: no weapon/1), rather than
+  observed behavior. This is a balance-review risk: test nonviolent profiles that
+  threaten or force entry, and violent profiles before visible danger. Do not
+  treat agreement with this helper as proof of fair emergency judgment.
+- `RadioSystem.credibility_hits()` checks weapon and danger fields only;
+  location, description and behavior still need human review. Difficulty scales
+  report penalties, not the oracle.
+- A terminal peaceful reaction is not sufficient evidence of an incident staying
+  resolved: returning NPCs and unresolved shift-review entries must be retained.
+
+Do not tune to a pooled average that hides a failing venue, phase or difficulty.
+Record each miss, its severity, the raw evidence and any approved exception before
+changing weights. Re-run the affected cells and tutorial/campaign smokes after a
+fix. Five first-time-player sessions must cover the tutorial and a complete venue
+shift; report pooled counts and per-session errors, not statistical confidence
+from five players. Scripted sweeps do not substitute for those sessions.
+
+**Status:** targets defined; sweeps, emergency fairness review, grade/campaign
+verification and external-player acceptance remain pending. No balance sign-off
+or release approval is implied by this document.