huge doc rewrite

stream-api/reference/operations.md

@@ -0,0 +1,37 @@
+# Health, testing, and safe operations
+
+<p class="page-description">Observe SDK providers and diagnose a Stream API deployment without making debug data public.</p>
+
+## Health
+
+`GET /health` (or `/api/health`) probes active providers and returns a JSON summary. It includes a status, timestamp, TMDB-key presence, cache size, and a map of provider keys to `{ ok, ms }` results.
+
+Health is a signal, not a promise of playback. Provider behavior can differ by title, client network, and the moment of the request. Use it for observability and source selection—not as a guarantee that a viewer will receive a stream.
+
+## Test one provider
+
+`GET /test/:id?source=:providerKey` resolves a single provider for a movie. Add `season` and `episode` (or `s` and `e`) for TV.
+
+```bash
+curl "http://localhost:7860/test/155?source=provider-key"
+curl "http://localhost:7860/test/1396?season=1&episode=1&source=provider-key"
+```
+
+Use source keys reported by the running deployment. A test result reports whether resolution and verification succeeded; clients should inspect the result body rather than relying only on a transport success.
+
+## Debug route
+
+`GET /debug/:id?source=:providerKey` offers detailed candidate and request traces, but it is only available when `ENABLE_DEBUG_ROUTE=true`.
+
+:::callout-warning
+Do not enable the debug route on a public deployment. It can expose upstream request data, raw candidates, and headers. Enable it temporarily in a controlled environment, then disable it again.
+:::
+
+## Production checklist
+
+- Set `TMDB_API_KEY` when metadata-dependent sources are required.
+- Keep `ENABLE_DEBUG_ROUTE=false` outside controlled troubleshooting.
+- Use TLS and enforce your own access policy before making the service remotely reachable.
+- Monitor health trends and playback failures separately.
+- Run updates and provider changes through your normal deployment process.
+- Build player fallbacks instead of assuming a specific provider is always available.