docs: explain how to actually get a CLAUDE_CODE_OAUTH_TOKEN

app/DEPLOY.md

@@ -94,7 +94,12 @@ Runs in-process against the repo's live workspace directory.
 
 1. Set `ANTHROPIC_API_KEY=<your key>` on the deployment (and/or in a local `.env.local` for dev). Restart/redeploy.
 2. `npm install` already pulls the correct platform binary via `@anthropic-ai/claude-agent-sdk`'s `optionalDependencies` (Linux glibc/musl x64+arm64, macOS, Windows), so this works in the Docker image with no extra install step.
-3. **Subscription mode (`CLAUDE_CODE_OAUTH_TOKEN` / "Use my Claude subscription" toggle) requires real evidence of a working login on this exact server process** — either `CLAUDE_CODE_OAUTH_TOKEN` set as an env var, or a `~/.claude/.credentials.json` file from having run `claude login` on that same host. On Render (and most container hosts), the home directory is NOT on the persistent disk and there's no interactive terminal to run `claude login` in the first place, so a credentials file can never exist there — `CLAUDE_CODE_OAUTH_TOKEN` is the only way subscription mode can work on this deployment model. CodeGraph checks for this evidence server-side (`claudeSubscriptionCredentialsAvailable()` in `lib/settings.ts`) before ever offering Claude via the subscription path — toggling the Settings checkbox alone, with no real credentials, correctly leaves the Claude tab unavailable instead of producing a broken chat session ("Not logged in — Please run /login", followed by "/login isn't available in this environment", since the SDK session is headless and can't prompt interactively).
+3. **To use your Claude Pro/Max/Team subscription instead of an API key** (the "Use my Claude subscription" toggle on the Settings page), CodeGraph requires real evidence this exact server process can authenticate — an `ANTHROPIC_API_KEY`-free login. On a hosted/container deployment (Render, Docker, etc.) there's no persistent home directory and no interactive terminal to ever run `claude login` directly on the server, so the only way this works is a portable long-lived token:
+   1. On **your own computer** (not the server) — run `npx @anthropic-ai/claude-code setup-token` (or `claude setup-token` if you already have Claude Code installed globally). This is a real subcommand of the official CLI: `Set up a long-lived authentication token (requires Claude subscription)`.
+   2. It opens a browser to sign in with your Claude.ai account (Pro/Max/Team) — or prints a URL/code to paste manually if a browser can't open (e.g. over SSH).
+   3. On success it prints a token valid for **1 year**: `Your OAuth token (valid for 1 year): ... Use this token by setting: export CLAUDE_CODE_OAUTH_TOKEN=<token>`. Copy it now — you won't be able to see it again.
+   4. Set `CLAUDE_CODE_OAUTH_TOKEN=<that token>` on the deployment (Render dashboard → your service → Environment → Add Environment Variable) and redeploy/restart.
+   5. CodeGraph checks for this evidence server-side (`claudeSubscriptionCredentialsAvailable()` in `lib/settings.ts`) before ever offering Claude via the subscription path, so the toggle only "just works" once the token is actually set — no server-side login needed beyond this one env var.
 
 ### Local model (any OpenAI-compatible server)
 Talks over plain HTTP to a model server running on your own hardware — no data leaves the machine running CodeGraph. Tested against the OpenAI-compatible `/v1/chat/completions` shape that Ollama, LM Studio, llama.cpp's `server`, vLLM, and text-generation-webui all implement; tool-calling quality (and therefore how well the assistant can actually edit files) depends entirely on the model you pick — recent tool-calling-tuned models (e.g. Qwen2.5-Coder, Llama 3.1+) work noticeably better than older/small ones.

app/src/app/settings/page.tsx

@@ -314,19 +314,26 @@ export default function SettingsPage() {
                 </span>
               </label>
               <p className="text-xs text-gray-500 mt-1.5 ml-6">
-                Only works if the machine running CodeGraph already has Claude Code logged in
-                (run <code className="text-gray-400">claude login</code> in a terminal there once), or has{" "}
-                <code className="text-gray-400">CLAUDE_CODE_OAUTH_TOKEN</code> set in its environment.
-                Uses your subscription&apos;s included usage instead of per-token API billing.
-                An API Key above, if set, always takes priority over this.
+                Uses your subscription&apos;s included usage instead of per-token API billing. An API Key above, if set, always
+                takes priority over this.
               </p>
               {useSubscription && settings && !settings.claudeSubscriptionUsable && (
-                <p className="text-xs text-amber-400 mt-1.5 ml-6">
-                  ⚠ This server has no usable Claude Code login right now (no <code className="text-amber-300">CLAUDE_CODE_OAUTH_TOKEN</code>{" "}
-                  and no local <code className="text-amber-300">claude login</code> session) — starting a chat with this toggle on and no
-                  API Key set above will fail. Set an Anthropic API Key above instead, or ask the site operator to configure{" "}
-                  <code className="text-amber-300">CLAUDE_CODE_OAUTH_TOKEN</code>.
-                </p>
+                <div className="text-xs text-amber-400 mt-1.5 ml-6 space-y-1.5">
+                  <p>⚠ This server has no usable Claude Code login right now — starting a chat with this toggle on and no API Key set above will fail.</p>
+                  <p className="text-gray-400">
+                    To actually use your subscription instead of an API key, on <strong className="text-gray-300">your own computer</strong>{" "}
+                    (not this server) run:
+                  </p>
+                  <pre className="bg-black/40 border border-white/10 rounded px-2 py-1.5 text-amber-300 font-mono overflow-x-auto">
+                    npx @anthropic-ai/claude-code setup-token
+                  </pre>
+                  <p className="text-gray-400">
+                    This opens a browser to sign in with your Claude Pro/Max/Team account and prints a long-lived (1 year)
+                    token. Set that as <code className="text-amber-300">CLAUDE_CODE_OAUTH_TOKEN</code> in this deployment&apos;s
+                    environment (e.g. the Render dashboard&apos;s Environment tab) and redeploy — the server itself never needs
+                    an interactive login, only that one token.
+                  </p>
+                </div>
               )}
             </div>
             <div>