fix(api): auth-provider error copy — prefix-routing hints + sk-ant-* bearer detection — closes ROADMAP #28

Two live users in #claw-code on 2026-04-08 hit adjacent auth confusion:
varleg set OPENAI_API_KEY for OpenRouter but prefix routing didn't
activate without openai/ model prefix, and stanley078852 put sk-ant-*
in ANTHROPIC_AUTH_TOKEN (Bearer path) instead of ANTHROPIC_API_KEY
(x-api-key path) and got 401 Invalid bearer token.

Changes:
1. ApiError::MissingCredentials gained optional hint field (error.rs)
2. anthropic_missing_credentials_hint() sniffs OPENAI/XAI/DASHSCOPE
   env vars and suggests prefix routing when present (providers/mod.rs)
3. All 4 Anthropic auth paths wire the hint helper (anthropic.rs)
4. 401 + sk-ant-* in bearer token detected and hint appended
5. 'Which env var goes where' section added to USAGE.md

Tests: unit tests for all three improvements (no HTTP calls needed).
Workspace: all tests green, fmt clean, clippy warnings-only.

Source: live users varleg + stanley078852 in #claw-code 2026-04-08.

Co-authored-by: gaebal-gajae <gaebal-gajae@layofflabs.com>

rust/crates/api/src/error.rs

@@ -22,6 +22,11 @@ pub enum ApiError {
     MissingCredentials {
         provider: &'static str,
         env_vars: &'static [&'static str],
+        /// Optional, runtime-computed hint appended to the error Display
+        /// output. Populated when the provider resolver can infer what the
+        /// user probably intended (e.g. an OpenAI key is set but Anthropic
+        /// was selected because no Anthropic credentials exist).
+        hint: Option<String>,
     },
     ContextWindowExceeded {
         model: String,
@@ -66,7 +71,29 @@ impl ApiError {
         provider: &'static str,
         env_vars: &'static [&'static str],
     ) -> Self {
-        Self::MissingCredentials { provider, env_vars }
+        Self::MissingCredentials {
+            provider,
+            env_vars,
+            hint: None,
+        }
+    }
+
+    /// Build a `MissingCredentials` error carrying an extra, runtime-computed
+    /// hint string that the Display impl appends after the canonical "missing
+    /// <provider> credentials" message. Used by the provider resolver to
+    /// suggest the likely fix when the user has credentials for a different
+    /// provider already in the environment.
+    #[must_use]
+    pub fn missing_credentials_with_hint(
+        provider: &'static str,
+        env_vars: &'static [&'static str],
+        hint: impl Into<String>,
+    ) -> Self {
+        Self::MissingCredentials {
+            provider,
+            env_vars,
+            hint: Some(hint.into()),
+        }
     }
 
     /// Build a `Self::Json` enriched with the provider name, the model that
@@ -204,7 +231,11 @@ impl ApiError {
 impl Display for ApiError {
     fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
         match self {
-            Self::MissingCredentials { provider, env_vars } => {
+            Self::MissingCredentials {
+                provider,
+                env_vars,
+                hint,
+            } => {
                 write!(
                     f,
                     "missing {provider} credentials; export {} before calling the {provider} API",
@@ -223,6 +254,9 @@ impl Display for ApiError {
                         )?;
                     }
                 }
+                if let Some(hint) = hint {
+                    write!(f, " — hint: {hint}")?;
+                }
                 Ok(())
             }
             Self::ContextWindowExceeded {
@@ -483,4 +517,56 @@ mod tests {
         assert_eq!(error.safe_failure_class(), "context_window");
         assert_eq!(error.request_id(), Some("req_ctx_123"));
     }
+
+    #[test]
+    fn missing_credentials_without_hint_renders_the_canonical_message() {
+        // given
+        let error = ApiError::missing_credentials(
+            "Anthropic",
+            &["ANTHROPIC_AUTH_TOKEN", "ANTHROPIC_API_KEY"],
+        );
+
+        // when
+        let rendered = error.to_string();
+
+        // then
+        assert!(
+            rendered.starts_with(
+                "missing Anthropic credentials; export ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY before calling the Anthropic API"
+            ),
+            "rendered error should lead with the canonical missing-credential message: {rendered}"
+        );
+        assert!(
+            !rendered.contains(" — hint: "),
+            "no hint should be appended when none is supplied: {rendered}"
+        );
+    }
+
+    #[test]
+    fn missing_credentials_with_hint_appends_the_hint_after_base_message() {
+        // given
+        let error = ApiError::missing_credentials_with_hint(
+            "Anthropic",
+            &["ANTHROPIC_AUTH_TOKEN", "ANTHROPIC_API_KEY"],
+            "I see OPENAI_API_KEY is set — if you meant to use the OpenAI-compat provider, prefix your model name with `openai/` so prefix routing selects it.",
+        );
+
+        // when
+        let rendered = error.to_string();
+
+        // then
+        assert!(
+            rendered.starts_with("missing Anthropic credentials;"),
+            "hint should be appended, not replace the base message: {rendered}"
+        );
+        let hint_marker = " — hint: I see OPENAI_API_KEY is set — if you meant to use the OpenAI-compat provider, prefix your model name with `openai/` so prefix routing selects it.";
+        assert!(
+            rendered.ends_with(hint_marker),
+            "rendered error should end with the hint: {rendered}"
+        );
+        // Classification semantics are unaffected by the presence of a hint.
+        assert_eq!(error.safe_failure_class(), "provider_auth");
+        assert!(!error.is_retryable());
+        assert_eq!(error.request_id(), None);
+    }
 }