docs: add registry dockge and dashboard operations

docs/sources/README.md

@@ -0,0 +1,18 @@
+# Source Operations
+
+Each source should fail visibly and safely. A missing key or remote outage must produce `degraded` source health instead of silent demo data.
+
+Check runtime state:
+
+```bash
+curl http://localhost:3117/api/health
+curl http://localhost:3117/api/metrics
+```
+
+Source docs:
+
+- [OpenSky](opensky.md)
+- [ACLED](acled.md)
+- [Telegram](telegram.md)
+- [FIRMS](firms.md)
+- [Maritime](maritime.md)

docs/sources/acled.md

@@ -0,0 +1,9 @@
+# ACLED
+
+Provides conflict events, fatalities, event types, and locations.
+
+- Auth: `ACLED_EMAIL` and `ACLED_PASSWORD`.
+- Flow: OAuth password grant is tried first, then cookie session fallback.
+- Failure modes: missing credentials, terms/profile not completed, expired token, account missing API access.
+- Behavior: missing or rejected credentials produce degraded source health with the ACLED error text.
+- Test: set credentials, run `node apis/sources/acled.mjs`, then check `/api/health`.

docs/sources/firms.md

@@ -0,0 +1,8 @@
+# FIRMS
+
+Provides NASA satellite fire and thermal detections.
+
+- Auth: `FIRMS_MAP_KEY` recommended.
+- Failure modes: missing key, timeout, regional API throttle.
+- Behavior: source health reports degraded or failed; dashboard panels stay visible and show available sources.
+- Test: set `FIRMS_MAP_KEY`, run a sweep, inspect thermal markers and `/api/metrics`.

docs/sources/maritime.md

@@ -0,0 +1,8 @@
+# Maritime
+
+Provides chokepoint context and optional AIS-related maritime data.
+
+- Auth: `AISSTREAM_API_KEY` enables richer AIS behavior where supported.
+- Failure modes: missing key, remote stream unavailable, no vessels in a monitored region.
+- Behavior: static chokepoint context remains available, live source health reports degraded when remote data is unavailable.
+- Test: run a sweep and inspect maritime markers, source health, and network metrics.

docs/sources/opensky.md

@@ -0,0 +1,9 @@
+# OpenSky
+
+Provides public aircraft state data for regional air-activity hotspots.
+
+- Auth: public queries work without credentials.
+- Failure modes: timeouts, `HTTP 429`, and empty regions.
+- Behavior: source health is marked degraded on API errors. The dashboard may use the most recent non-empty air snapshot from `runs/` and marks it in `airMeta.fallback`.
+- Test: start a sweep and inspect `/api/health` plus `airMeta` from `/api/data`.
+- Operator note: Crucix does not bypass OpenSky throttles. Increase `REFRESH_INTERVAL_MINUTES` if the source degrades repeatedly.

docs/sources/telegram.md

@@ -0,0 +1,9 @@
+# Telegram
+
+Provides OSINT posts and bot commands/alerts.
+
+- Source collection uses configured public/channel inputs where available.
+- Bot alerts require `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID`.
+- Polling failures are non-fatal and use backoff logging to avoid log spam.
+- `/brief` includes source integrity, evidence links, event id, why-it-matters, and next-step context.
+- Test: configure bot variables, start the container, send `/status` and `/brief`.