docs(skills): agent-driven auth login — the operational loop, live-verified

Ran the flow for real (agent starts `auth login --json --region us-west-2`
backgrounded, human approves the relayed URL): authorization_required →
authorized → device_bound, exit 0, session verified via getToken. The event
table in stash-cli was already accurate; what was missing was the part that
bites an agent — the command blocks polling for up to ~15 minutes, so it
must run as a background task with a generous timeout, and success is
confirmed from the event stream (never by inspecting ~/.cipherstash).
stash-encryption's Local Development section now points agents at the flow.

Claude-Session: https://claude.ai/code/session_01MxTTPaPP16m6br7Hoab94w

Author: coderdan

skills/stash-cli/SKILL.md

@@ -82,6 +82,22 @@ npx stash auth login --json --region us-east-1
 | `{ status: "device_bound" }` | Device bound to the default keyset. Done. |
 | `{ status: "error", code, message }` | Failure. Exit code 1. |
 
+Operationally: after printing `authorization_required` the command **blocks,
+polling, until the human approves or the code expires** (`expiresIn` is
+~900 s). So run it as a background/async task with a generous timeout —
+a short-timeout synchronous run kills the poll and the login never lands.
+The working loop is:
+
+1. Start `npx stash auth login --json --region <slug>` in the background.
+2. Read the first stdout line; relay `verificationUriComplete` to the human
+   (include `userCode` so they can cross-check what they're approving, and
+   mention the ~15-minute expiry).
+3. Leave the process running. Success is **exit 0 with `device_bound` as the
+   final event** — the session and development key are then in the profile
+   and every later command authenticates silently.
+4. To confirm, trust the event stream or run any authenticated command —
+   never inspect `~/.cipherstash` (see "Never read these").
+
 **Authenticate before `stash init`.** Init's authenticate step uses the interactive path, so an agent running `init` unauthenticated makes the CLI try to open a browser on the agent's machine — and in a non-TTY it exits with `region_required` unless `--region` or `STASH_REGION` is set. Once a valid token exists, init logs `Using workspace X (region)` and moves on silently.
 
 Flags: `--region <slug>` (env `STASH_REGION`), `--json`, `--no-open`, `--supabase` / `--drizzle` (referrer tracking only).

skills/stash-encryption/SKILL.md

@@ -111,6 +111,12 @@ already-initialized project, `npx stash auth login` alone authenticates the
 machine; the SDK and CLI pick up the saved profile automatically. Sign up at
 [cipherstash.com/signup](https://cipherstash.com/signup) first.
 
+Agents can drive the login too: `npx stash auth login --json --region <slug>`
+emits the verification URL as data — run it in the background, relay the URL
+to the human, and the flow completes when they approve in a browser. The
+event contract and the operational loop are in the `stash-cli` skill's
+Authentication section.
+
 ### CI and Production (environment variables)
 
 Deployed environments and CI use machine credentials via environment variables