Ship production optimization M1-M12.5A: queues, metrics, HTTP observability, and vector search reliability.

Keep similar-ai from tripping the global circuit on a lone URL 502, clamp Qdrant search to 100, and add Server-Timing plus slow-request logging. Studio shared props, Academy S3 exists caching, heat chunking, and Redis/scheduler hygiene stay in this rollout.

docs/optimization-m12.2-vector-gateway-circuit.md

@@ -0,0 +1,27 @@
+# M12.2 — Vector Gateway Search Reliability & Circuit Breaker Hotfix
+
+```text
+STATUS: COMPLETE (application-only)
+PRODUCTION: no nginx / env / FPM / Redis / Horizon changes required
+```
+
+## Root cause
+
+`VectorGatewayClient::searchByFileContents()` tripped the global circuit on **any** HTTP failure or thrown exception **before** `AiArtworkVectorSearchService` could run `searchByUrl()`. The fallback then hit `guardCircuit()` and failed immediately. Intermittent 502s (~0.23–0.55s) match fail-fast circuit-open, not cold 1.5–3s searches.
+
+4xx from the file endpoint also opened the circuit.
+
+## Circuit policy
+
+- Combined similar-ai starts only if the circuit is **closed**.
+- File search, then URL fallback. **Neither method trips or guards the circuit.**
+- After **both** fail, trip only if **every** gateway failure is circuit-worthy.
+- Successful fallback **leaves the circuit closed**.
+- TTL remains **30s**. Search timeouts remain 2s/6s, retries 0.
+
+Circuit-worthy: connection/timeout, HTTP 408/429/5xx.  
+Not: 400/401/403/404/409/422 and other input 4xx.
+
+## Deploy
+
+`bash ./sync.sh` only. Do not reload nginx. Do not clear the circuit key.