docs(auth): frame login --device as browserless human sign-in, not CI

The device-authorization grant (RFC 8628) is human-delegated — a person
must approve the code + URL on the approval page — so it is not an
unattended path. The `--device` help text listed "CI" as a use case;
correct it to a human signing in from a remote/SSH shell with no local
browser, and point unattended callers to `auth create-token` instead.

Also flag an unverified assumption: the device grant drops `offline_access`
and banks on the server returning a refresh token anyway. That has not been
confirmed against the live endpoint, so the scope comment now says so
rather than asserting it as fact.

Generated by the operator's software factory.
On behalf of: @benw5483
Co-Authored-By: Actual AI Factory Bot <factory-bot@actual.ai.invalid>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: 3 people

src/auth/oauth.rs

@@ -29,8 +29,13 @@ const DEFAULT_CLIENT_ID: &str = "actual-cli";
 const DEFAULT_SCOPES: &str = "openid profile offline_access adr:query adr:review";
 
 /// Default scopes for the browserless device-authorization grant. Colon-form
-/// resource scopes only — the device grant still returns a refresh token
-/// without an explicit `offline_access`. Overridable via `ACTUAL_OAUTH_SCOPES`.
+/// resource scopes only, dropping `offline_access`.
+///
+/// UNVERIFIED: whether the server returns a refresh token for the device grant
+/// without an explicit `offline_access` has not yet been confirmed against the
+/// live endpoint, and the refresh path depends on it. If the server does not
+/// return one, add `offline_access` here (or via `ACTUAL_OAUTH_SCOPES`).
+/// Overridable via `ACTUAL_OAUTH_SCOPES`.
 const DEFAULT_DEVICE_SCOPES: &str = "adr:query adr:review mcp:invoke";
 
 /// URN grant type for the OAuth 2.0 device-authorization grant (RFC 8628 §3.4).

src/cli/args.rs

@@ -475,9 +475,11 @@ pub struct LoginArgs {
     pub no_browser: bool,
 
     /// Use the browserless device-authorization flow (RFC 8628): print a short
-    /// code + URL to approve on any device, then poll for the session. Intended
-    /// for remote/SSH/CI shells with no local browser. `--org` is ignored in
-    /// this mode (the org is selected on the approval page).
+    /// code + URL for a person to approve on any device, then poll for the
+    /// session. For a human signing in from a remote or SSH shell with no local
+    /// browser — a person must approve the code, so this is not an unattended
+    /// path (CI has no approver; use `auth create-token` there instead). `--org`
+    /// is ignored in this mode (the org is selected on the approval page).
     #[arg(long)]
     pub device: bool,
 }