diff --git a/cmd/auth/auth.go b/cmd/auth/auth.go
index 2cfef97..5dfbaf9 100644
--- a/cmd/auth/auth.go
+++ b/cmd/auth/auth.go
@@ -9,7 +9,7 @@ func NewAuthCmd(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "auth",
 		Short: "Authenticate with KeeperHub",
-		Example: `  # Log in via browser
+		Example: `  # Log in (device code flow — prints a URL and code to confirm in a browser)
   kh auth login
 
   # Check current auth status
diff --git a/cmd/auth/login.go b/cmd/auth/login.go
index aa0d4eb..a295de7 100644
--- a/cmd/auth/login.go
+++ b/cmd/auth/login.go
@@ -52,7 +52,9 @@ func NewLoginCmd(f *cmdutil.Factory) *cobra.Command {
 		Short: "Log in to KeeperHub",
 		Args:  cobra.NoArgs,
 		Long: `Authenticate with KeeperHub using the device code flow.
-Prints a URL and a one-time code; open the URL in a browser to confirm it.
+Prints a URL and a one-time code. Open the URL in any browser (the browser
+does not open automatically — copy the URL from the terminal) and enter the
+code to complete sign-in. Codes expire after 15 minutes.
 Use --with-token to read an API key from stdin for non-interactive automation.
 
 See also: kh auth status, kh auth logout`,
diff --git a/cmd/wallet/wallet.go b/cmd/wallet/wallet.go
index 6664f5d..e9a3bc0 100644
--- a/cmd/wallet/wallet.go
+++ b/cmd/wallet/wallet.go
@@ -21,7 +21,9 @@ Agentic wallet (thin wrappers around npx @keeperhub/wallet):
   kh w info       print agentic subOrgId + walletAddress
   kh w fund       print Coinbase Onramp URL + Tempo deposit address
   kh w link       link agentic wallet to a KeeperHub account (needs KH_SESSION_COOKIE)
-  kh w feedback   submit ERC-8004 feedback for a workflow execution this wallet paid for`,
+  kh w feedback   submit ERC-8004 feedback for a workflow execution this wallet paid for
+
+Prerequisite for agentic subcommands: Node.js (v18+) and npx must be on your PATH.`,
 		Example: `  # Creator wallet balance (REST):
   kh w balance
 
diff --git a/docs/kh_auth.md b/docs/kh_auth.md
index cd74618..f5401d4 100644
--- a/docs/kh_auth.md
+++ b/docs/kh_auth.md
@@ -5,7 +5,7 @@ Authenticate with KeeperHub
 ### Examples
 
 ```
-  # Log in via browser
+  # Log in (device code flow — prints a URL and code to confirm in a browser)
   kh auth login
 
   # Check current auth status
diff --git a/docs/kh_auth_login.md b/docs/kh_auth_login.md
index 166f87c..2a8e7d9 100644
--- a/docs/kh_auth_login.md
+++ b/docs/kh_auth_login.md
@@ -5,7 +5,9 @@ Log in to KeeperHub
 ### Synopsis
 
 Authenticate with KeeperHub using the device code flow.
-Prints a URL and a one-time code; open the URL in a browser to confirm it.
+Prints a URL and a one-time code. Open the URL in any browser (the browser
+does not open automatically — copy the URL from the terminal) and enter the
+code to complete sign-in. Codes expire after 15 minutes.
 Use --with-token to read an API key from stdin for non-interactive automation.
 
 See also: kh auth status, kh auth logout
diff --git a/docs/kh_wallet.md b/docs/kh_wallet.md
index 61940a8..a002c5c 100644
--- a/docs/kh_wallet.md
+++ b/docs/kh_wallet.md
@@ -17,6 +17,8 @@ Agentic wallet (thin wrappers around npx @keeperhub/wallet):
   kh w link       link agentic wallet to a KeeperHub account (needs KH_SESSION_COOKIE)
   kh w feedback   submit ERC-8004 feedback for a workflow execution this wallet paid for
 
+Prerequisite for agentic subcommands: Node.js (v18+) and npx must be on your PATH.
+
 ### Examples
 
 ```
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 511c9d0..ae2e416 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -2,11 +2,24 @@
 
 ## Install
 
-**Homebrew (macOS/Linux):**
+**Homebrew (macOS/Linux with Homebrew):**
 ```
 brew install keeperhub/tap/kh
 ```
 
+**Linux (no Homebrew / headless):**
+```bash
+mkdir -p ~/.local/bin && cd "$(mktemp -d)"
+curl -fsSL https://api.github.com/repos/keeperhub/cli/releases/latest \
+  | grep browser_download_url | cut -d '"' -f 4 \
+  | grep -E 'linux_amd64\.tar\.gz|checksums\.txt' \
+  | xargs -n1 curl -fsSLO
+sha256sum --ignore-missing -c checksums.txt
+tar -xzf kh_*_linux_amd64.tar.gz -C ~/.local/bin kh
+```
+Replace `linux_amd64` with `linux_arm64` on ARM. Ensure `~/.local/bin` is on your `PATH`.
+The unauthenticated GitHub API is rate-limited to 60 requests per hour per IP; if you hit that limit, download directly from [GitHub Releases](https://github.com/keeperhub/cli/releases).
+
 **Go install:**
 ```
 go install github.com/keeperhub/cli/cmd/kh@latest
@@ -20,7 +33,7 @@ go install github.com/keeperhub/cli/cmd/kh@latest
 kh auth login
 ```
 
-This opens a browser window to authenticate. Your token is stored in the OS keyring.
+This uses the **device code flow**: it prints a URL and a short code. Open the URL in any browser (including on a different machine) and enter the code to complete sign-in. On headless or remote boxes the browser will not open automatically — copy the URL from the terminal. Codes expire after 15 minutes; re-run `kh auth login` if yours expires. Your token is stored in the OS keyring.
 
 To authenticate non-interactively (CI/CD), set `KH_API_KEY` instead.