fix: report adsb unavailable state as degraded

docs/sources/README.md

@@ -16,3 +16,4 @@ Source docs:
 - [Telegram](telegram.md)
 - [FIRMS](firms.md)
 - [Maritime](maritime.md)
+- [ADS-B](adsb.md)

docs/sources/adsb.md

@@ -0,0 +1,24 @@
+# ADS-B Source
+
+ADS-B Exchange support is optional and intended for unfiltered aircraft and military-flight awareness.
+
+- Source module: `apis/sources/adsb.mjs`
+- Preferred provider: ADS-B Exchange via RapidAPI
+- Credentials: `ADSB_API_KEY` or `RAPIDAPI_KEY`
+- Runtime status without credentials: `disabled`
+- Runtime status when providers fail: `degraded`
+- Runtime status with usable aircraft payloads: `live`
+
+The source does not treat a missing key or unavailable public feed as normal live data. `/api/health` and `/api/metrics` surface the degraded source state through the sweep source summary.
+
+Known failure modes:
+
+- Missing `ADSB_API_KEY` / `RAPIDAPI_KEY`: source is disabled with operator guidance.
+- RapidAPI rejects or rate-limits the request: source is degraded and records provider failure detail.
+- Public feed is blocked, rate-limited, or changes shape: source remains degraded instead of returning stale-looking data.
+
+Register for the provider documented in the README, then set:
+
+```env
+ADSB_API_KEY=<rapidapi-key>
+```