[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>

scripts/run-performance-tests.sh

@@ -117,6 +117,26 @@ PERF_TMP_DIR="$(mktemp -d -t perf-XXXXXX)"
 
 # --- Helper functions ---
 
+preflight_api_reachable() {
+    local perf_compose_up="docker compose -f docker-compose.yml -f docker-compose.perf.yml up -d --build"
+    local http_code curl_exit
+    set +e
+    http_code=$(curl "${CURL_OPTS[@]}" --connect-timeout 5 -s -o /dev/null -w "%{http_code}" \
+        -H "$AUTH_HEADER" \
+        "$API_URL/api/satellite/tiles/latlon?lat=47.461347&lon=37.646663&zoom=18")
+    curl_exit=$?
+    set -e
+
+    if (( curl_exit != 0 )); then
+        echo "ERROR: API at $API_URL is unreachable (curl exit $curl_exit)."
+        echo "Start the perf overlay stack:"
+        echo "  $perf_compose_up"
+        exit 7
+    fi
+
+    echo "API reachable at $API_URL (HTTP $http_code)"
+}
+
 check_threshold() {
     local test_name="$1"
     local actual_ms="$2"
@@ -163,6 +183,9 @@ wait_region_completed() {
     return 1
 }
 
+preflight_api_reachable
+echo ""
+
 # --- PT-01..PT-06 (existing scenarios; now with Bearer token) ---
 
 # PT-01: Tile download latency for a fresh tile (cold path).