[AZ-1133] Add perf gate preflight before PT-01

Probe API reachability after JWT mint; exit 7 with compose-up
instructions when the perf stack is down. Document in environment
and containerization guides.

Co-authored-by: Cursor <cursoragent@cursor.com>

_docs/02_tasks/done/AZ-1133_perf_gate_preflight.md

@@ -0,0 +1,95 @@
+# Perf gate preflight — health-check before PT-01
+
+**Task**: AZ-1133_perf_gate_preflight
+**Name**: Perf gate preflight — health-check before PT-01
+**Description**: Add a preflight reachability check to `scripts/run-performance-tests.sh` so Step 15 fails fast with actionable instructions when the perf compose stack is not running.
+**Complexity**: 1 point
+**Dependencies**: AZ-492 (perf harness), AZ-1123 (perf compose documentation)
+**Component**: test tooling — `scripts/run-performance-tests.sh` + deployment/test env docs
+**Tracker**: AZ-1133
+**Epic**: None
+
+## Problem
+
+Cycle 13 Step 15 first run failed at PT-01 because `API_URL` (`https://localhost:18980`) was unreachable — the perf overlay (`docker compose -f docker-compose.yml -f docker-compose.perf.yml up -d`) had not been started. The script proceeded through JWT mint/bootstrap and only surfaced the failure as a cryptic PT-01 HTTP error / non-zero exit, wasting operator time. This carry-over appears in cycle 13, 14, and 15 retros.
+
+## Outcome
+
+- `run-performance-tests.sh` verifies API reachability after JWT mint and before PT-01
+- Unreachable API exits with exit code **7** and prints the canonical compose-up command
+- Reachable API proceeds to PT-01 unchanged
+- `environment.md` and `containerization.md` document the preflight behavior
+
+## Scope
+
+### Included
+
+- Add `preflight_api_reachable` (or equivalent) helper in `scripts/run-performance-tests.sh`:
+  - Probe `$API_URL` with the same `CURL_OPTS` / TLS trust as PT-01 (e.g. `curl --connect-timeout 5` to a lightweight endpoint — authenticated `GET /api/satellite/tiles/latlon` with valid coords is acceptable since JWT is already minted)
+  - On connection failure / empty response → print error + `docker compose -f docker-compose.yml -f docker-compose.perf.yml up -d --build` and `exit 7`
+- Update `_docs/02_document/tests/environment.md` § Performance tests — mention script preflight + exit 7
+- Update `_docs/02_document/deployment/containerization.md` § Compose overlays — cross-link preflight
+
+### Excluded
+
+- Auto-starting the compose stack from the script (operator still starts it explicitly)
+- Changing PT-01..PT-10 thresholds or scenario logic
+- CI integration (perf remains local-only per `ci_cd_pipeline.md`)
+
+## Acceptance Criteria
+
+**AC-1: Preflight runs before PT-01**
+Given `run-performance-tests.sh` with valid `JWT_SECRET` / iss / aud
+When the script reaches the performance scenarios section
+Then a reachability probe executes after JWT mint and before the PT-01 banner.
+
+**AC-2: Unreachable API fails fast with instructions**
+Given the perf compose stack is not running (`API_URL` connection refused or timeout)
+When `run-performance-tests.sh` is executed
+Then the script exits with code **7**, stderr/stdout includes the perf overlay `docker compose … up` command, and PT-01 does not run.
+
+**AC-3: Reachable API proceeds unchanged**
+Given the perf stack is up and `API_URL` accepts authenticated requests
+When `run-performance-tests.sh` is executed
+Then preflight passes silently (or with a single "API reachable" line) and PT-01..PT-10 behave as before.
+
+**AC-4: Documentation reflects preflight**
+Given the post-task docs
+When `environment.md` and `containerization.md` are read
+Then both mention the script preflight and exit code 7 when the stack is down.
+
+## Non-Functional Requirements
+
+**Reliability**
+- Preflight must use the same TLS trust path as the rest of the script (`CURL_OPTS` / `certs/api.crt`).
+
+**Compatibility**
+- No change to default env vars (`API_URL`, `PERF_REPEAT_COUNT`, etc.).
+
+## Unit Tests
+
+| AC Ref | What to Test | Required Outcome |
+|--------|-------------|-----------------|
+| — | Shell-only change; no new C# unit tests required | N/A |
+
+## Blackbox Tests
+
+| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
+|--------|------------------------|-------------|-------------------|----------------|
+| AC-2 | Perf stack stopped; JWT env set | `./scripts/run-performance-tests.sh` | Exit 7 + compose instruction; no PT-01 timing output | Reliability |
+| AC-3 | Perf stack running | `./scripts/run-performance-tests.sh` (smoke: `PERF_REPEAT_COUNT=1` if needed) | Exit 0 or threshold fail only after PT-01 starts | Compatibility |
+
+## Constraints
+
+- Preserve `set -euo pipefail` globally — preflight must not mask real curl failures in scenario bodies.
+- Exit code **7** is reserved for "stack not up" to match cycle 13 perf report convention.
+
+## Risks & Mitigation
+
+**Risk 1: False negative when API returns 401/403**
+- *Risk*: Preflight treats auth errors as "reachable" vs connection errors as "down" — must distinguish connection/TLS failure from HTTP 4xx.
+- *Mitigation*: Use curl exit code / `--connect-timeout`; treat HTTP responses (even 401) as reachable.
+
+**Risk 2: Preflight adds latency to every perf run**
+- *Risk*: Extra round-trip before 10 scenarios.
+- *Mitigation*: Single lightweight GET; acceptable vs minutes-long perf suite.