intelligence-terminal/docs/source-fetch-instrumentation.md

Source Fetch Instrumentation

safeFetch() and safeFetchText() attribute requests to /api/metrics.fetch.bySource.

Rules:

• Prefer passing an explicit source option from source modules when the call has a clear Crucix source name.
• If source is omitted, the shared helper infers a stable provider name from the request host.
• Unknown hosts fall back to the lowercase host instead of the old unknown bucket.
• Raw fetch() calls should be limited to cases where the shared helper cannot represent the protocol cleanly.

Current raw-fetch exceptions:

Area	Reason
OAuth/session handshakes	Token exchange calls often need custom form bodies, credential headers, or status-specific diagnostics.
Bot and alert delivery	Telegram/Discord alert calls are outbound operator notifications, not intelligence source health.
LLM providers	Provider clients already track model/provider status separately from source fetch health.
Dashboard browser calls	Browser-side /api/* and asset fetches are UI behavior, not source provider health.

When adding a new intelligence source, use safeFetch(url, { source: 'SourceName' }) unless there is a documented exception.