auto-discover: surface the specific discover-failure reason (not generic "failed to discover") in async status/alerts

[jwhartley]

Problem

When a scheduled autoDiscover fails for a structural / spec reason — most commonly a target collection whose schema is not connector-managed (no flow://connector-schema entry in $defs) — the failure surfaces only as the generic string failed to discover. It appears that way in both:

• the capture's controller status: status.controller.autoDiscover.failure.lastOutcome.errors[].detail = "failed to discover", and
• the auto_discover_failed alert error field.

The specific, actionable message already exists — the synchronous discover path (the UI "refresh bindings" button, and flowctl discover) returns:

collection <name> has a schema that is not managed by auto-discover (it has no $defs entry
for 'flow://connector-schema'). To opt in, add {"$defs": {"flow://connector-schema": {}}} to
the collection schema

but the async / scheduled path flattens it to failed to discover before it reaches status/alerts.

Scope (what this is not about)

This is not about transient connectivity/auth/abandoned-task failures (DB auth, SSH tunnels, OAuth expiry, DNS, missing REPLICATION role, etc.). Those already carry a specific reason through this same field and are expected. The gap is specifically the structural/spec failures, where the actionable reason is dropped and the user is left with weeks of opaque failed to discover and no way to self-diagnose except manually clicking refresh in the UI.

This exact "not managed by auto-discover" case has recurred across multiple customers, so the opacity has real support cost even though the volume is modest.

Asks

1. Propagate the specific discover-failure reason into status.controller.autoDiscover...errors[].detail and the auto_discover_failed alert, matching what the synchronous path already produces. The alert plumbing already interpolates {first_error_detail}; the reason is being collapsed upstream before it gets there.
2. For the not-managed case specifically, have the error text link to the docs guidance (concepts/schemas.md → "Connector-managed schemas and auto-discover", added in docs: document connector-managed schemas and auto-discover behavior #3252) once that page is live, so the message points users straight to the fix.

References

• The error is produced by update_connector_schema in crates/control-plane-api/src/discovers/specs.rs (added by control-plane-api: enforce strict $defs check in update_connector_schema #2720).
• The alert was built in Alerts: on auto-discover failures #2187.
• Docs for the underlying behavior + migration: docs: document connector-managed schemas and auto-discover behavior #3252.

Priority

Low — modest volume and a UI-refresh workaround exists — but it's a genuine actionability defect: the information the user needs is computed and then discarded on the path they actually see.