fix(api): signal missing-key as user-error with mode-aware advice

A missing API key raised a raw `error`, so it backtraced under `debug-on-error`, and the stale advice pointed at customizing `pearl-api-key`. Now `pearl--headers` signals a `user-error` and branches the advice by mode: accounts mode points at `pearl-accounts` and `pearl-switch-account`, legacy mode at `pearl-api-key` and `pearl-load-api-key-from-env`. The credential-source resolver's three failure paths become `user-error` too, since a bad credential is a config problem, not a bug.

1 files changed, 10 insertions, 7 deletions

diff --git a/pearl.el b/pearl.el
index 522af9a..8540b9d 100644
--- a/pearl.el
+++ b/pearl.el
@@ -513,20 +513,20 @@ lookup -- when the key cannot be found or SOURCE is malformed."
     (`(:literal ,key) key)
     (`(:env ,var)
      (or (getenv var)
-         (error "No API key for account %s: environment variable %s is unset"
-                account var)))
+         (user-error "No API key for account %s: environment variable %s is unset"
+                     account var)))
     (`(:auth-source . ,plist)
      (let* ((found (car (apply #'auth-source-search
                                (append plist '(:require (:secret) :max 1)))))
             (secret (and found (plist-get found :secret))))
        (cond
         ((null secret)
-         (error "No API key for account %s: auth-source found no matching entry"
-                account))
+         (user-error "No API key for account %s: auth-source found no matching entry"
+                     account))
         ((functionp secret) (funcall secret))
         (t secret))))
-    (_ (error "No API key for account %s: unrecognized :api-key-source form"
-              account))))
+    (_ (user-error "No API key for account %s: unrecognized :api-key-source form"
+                   account))))
 
 (defun pearl--resolve-account (name)
   "Resolve account NAME from `pearl-accounts' to a context plist.
@@ -723,7 +723,10 @@ when it exists."
 (defun pearl--headers ()
   "Return headers for Linear API requests."
   (unless pearl-api-key
-    (error "Linear API key not set.  Use M-x customize-variable RET pearl-api-key"))
+    (user-error
+     (if pearl-accounts
+         "Linear API key not set: no active account key resolved.  Check `pearl-accounts' and its credential source, then M-x pearl-switch-account"
+       "Linear API key not set.  Set `pearl-api-key', or load it from the environment with M-x pearl-load-api-key-from-env")))
 
   ;; For personal API keys, the format is: "Authorization: <API_KEY>"
   ;; No "Bearer" prefix for personal API keys