docs: document gh auth device flow workaround for agent environments

[chaodu-agent]

Context

gh (GitHub CLI) is one of the most common tools agents use when working with GitHub — reviewing PRs, creating issues, commenting, approving, merging, etc. In an OpenAB deployment, the backing agent (e.g. Kiro CLI, Claude Code) often needs gh to be authenticated before it can perform any GitHub operations on behalf of the user.

The typical flow is:

1. User deploys OpenAB with a coding agent
2. User asks the agent to review a PR, create an issue, etc.
3. Agent needs gh auth login first — but it's running inside a container with no browser

┌───────────┐  "review PR #108"  ┌───────────┐  gh pr view  ┌───────────┐
│  Discord   │──────────────────►│  OpenAB    │────────────►│  GitHub   │
│  User      │                   │  + Agent   │◄────────────│  API      │
└───────────┘                    └─────┬─────┘  401 🚫      └───────────┘
                                       │
                                       │ needs gh auth login first!
                                       ▼
                                 ┌───────────┐  device flow  ┌───────────┐
                                 │  Agent     │─────────────►│  GitHub   │
                                 │  (nohup)   │  code+URL    │  /login/  │
                                 └─────┬─────┘◄─────────────│  device   │
                                       │                     └─────┬─────┘
                                       │ sends code+URL            │
                                       ▼                           │
                                 ┌───────────┐  authorize    ┌─────▼─────┐
                                 │  Discord   │─────────────►│  Browser  │
                                 │  User      │  enters code │  (mobile) │
                                 └───────────┘               └───────────┘

Challenges

This isn't a typical gh login scenario. Three things make it tricky:

1. The agent runs in a K8s pod with no browser — gh auth login --web can't open a browser, so device flow (code + URL) is the only option
2. The user might be on mobile, not at a desktop — they're chatting via Discord on their phone, so the agent must send the URL and code as a clickable message
3. The user authorizes on their phone — they tap the link, enter the code in mobile Safari/Chrome, and the agent's background process picks up the token automatically

The agent is the bridge between a headless container and a user who may only have a phone.

Problem

gh auth login --web uses device flow: it prints a one-time code + URL, then polls GitHub until the user authorizes in their browser. However, in an agent environment the shell is synchronous — it blocks until the command finishes. This means:

• Running directly — the command blocks forever waiting for browser auth, and the user never sees the code
• timeout N gh auth login -w — stdout (the one-time code + URL) only appears after timeout kills the process, so the token is never saved
• Either way, the user can't authenticate and the agent can't use gh

This is a common first-time setup issue for any OpenAB deployment that needs GitHub integration.

Solution

Use nohup + background process + read log:

nohup gh auth login --hostname github.com --git-protocol https -p https -w > /tmp/gh-login.log 2>&1 &
sleep 3 && cat /tmp/gh-login.log

This lets the agent immediately return the one-time code and URL to the user (even on mobile), while gh continues polling in the background until authorization completes.

Request

Add a section in docs/ documenting this pattern, covering:

1. Why gh auth is needed before the agent can interact with GitHub
2. The unique challenges of headless containers + mobile users
3. Why naive approaches (timeout, direct execution) don't work in agent environments
4. The nohup workaround with step-by-step instructions
5. Optionally, a recommended steering/prompt snippet so agents handle gh login correctly out of the box