docs: fix oauth path references

docs/configuration.md

@@ -91,18 +91,18 @@ Env var equivalent:
 
 ### Auth storage (OAuth + API keys)
 
-Clawdbot keeps subscription OAuth tokens + API keys in the **agent auth store**:
+Clawdbot stores **OAuth credentials** in:
+- `~/.clawdbot/credentials/oauth.json` (or `$CLAWDBOT_STATE_DIR/credentials/oauth.json`)
+
+Clawdbot stores **API keys** in the agent auth store:
 - `~/.clawdbot/agent/auth.json`
 
-The agent directory can be overridden with:
+Overrides:
-- `CLAWDBOT_AGENT_DIR` (preferred)
+- OAuth dir: `CLAWDBOT_OAUTH_DIR`
-- `PI_CODING_AGENT_DIR` (legacy)
+- Agent dir: `CLAWDBOT_AGENT_DIR` (preferred), `PI_CODING_AGENT_DIR` (legacy)
 
-Legacy OAuth storage is still supported for migration:
+On first use, Clawdbot imports `oauth.json` entries into `auth.json` so the embedded
-- Default: `~/.clawdbot/credentials/oauth.json` (or `$CLAWDBOT_STATE_DIR/credentials/oauth.json`)
+agent can use them. `oauth.json` remains the source of truth for OAuth refresh.
-- Override: `CLAWDBOT_OAUTH_DIR`
-
-On first use, Clawdbot auto‑migrates legacy `oauth.json` entries into `auth.json`.
 
 ### `identity`
 

docs/faq.md

@@ -14,9 +14,9 @@ Everything lives under `~/.clawdbot/`:
 | Path | Purpose |
 |------|---------|
 | `~/.clawdbot/clawdbot.json` | Main config (JSON5) |
-| `~/.clawdbot/agent/auth.json` | OAuth + API key store (Anthropic/OpenAI, etc.) |
+| `~/.clawdbot/credentials/oauth.json` | OAuth credentials (Anthropic/OpenAI, etc.) |
+| `~/.clawdbot/agent/auth.json` | API key store |
 | `~/.clawdbot/credentials/` | WhatsApp/Telegram auth tokens |
-| `~/.clawdbot/credentials/oauth.json` | Legacy OAuth store (auto‑migrated) |
 | `~/.clawdbot/sessions/` | Conversation history & state |
 | `~/.clawdbot/sessions/sessions.json` | Session metadata |
 
@@ -118,7 +118,7 @@ They're **separate billing**! An API key does NOT use your subscription.
 pnpm clawdbot login
 ```
 
-**If OAuth fails** (headless/container): Do OAuth on a normal machine, then copy `~/.clawdbot/agent/auth.json` to your server. The auth is just a JSON file.
+**If OAuth fails** (headless/container): Do OAuth on a normal machine, then copy `~/.clawdbot/credentials/oauth.json` to your server. The auth is just a JSON file.
 
 ### How are env vars loaded?
 
@@ -148,7 +148,7 @@ Or set `CLAWDBOT_LOAD_SHELL_ENV=1` (timeout: `CLAWDBOT_SHELL_ENV_TIMEOUT_MS=1500
 
 OAuth needs the callback to reach the machine running the CLI. Options:
 
-1. **Copy auth manually** — Run OAuth on your laptop, copy `~/.clawdbot/agent/auth.json` to the container.
+1. **Copy auth manually** — Run OAuth on your laptop, copy `~/.clawdbot/credentials/oauth.json` to the container.
 2. **SSH tunnel** — `ssh -L 18789:localhost:18789 user@server`
 3. **Tailscale** — Put both machines on your tailnet.
 

docs/onboarding.md

@@ -19,7 +19,7 @@ This doc describes the intended **first-run onboarding** for Clawdbot. The goal
 
 First question: where does the **Gateway** run?
 
-- **Local (this Mac):** onboarding can run OAuth flows and write the Clawdbot auth store locally.
+- **Local (this Mac):** onboarding can run OAuth flows and write OAuth credentials locally.
 - **Remote (over SSH/tailnet):** onboarding must not run OAuth locally, because credentials must exist on the **gateway host**.
 
 Gateway auth tip:
@@ -38,10 +38,10 @@ The macOS app should:
 - Start the Anthropic OAuth (PKCE) flow in the user’s browser.
 - Ask the user to paste the `code#state` value.
 - Exchange it for tokens and write credentials to:
-  - `~/.clawdbot/agent/auth.json` (file mode `0600`, directory mode `0700`)
+  - `~/.clawdbot/credentials/oauth.json` (file mode `0600`, directory mode `0700`)
 
-Why this location matters: it’s the Clawdbot-owned auth store (OAuth + API keys).
+Why this location matters: it’s the Clawdbot-owned OAuth store.
-Clawdbot auto-migrates legacy OAuth tokens from `~/.clawdbot/credentials/oauth.json` (and older pi/Claude locations) into `auth.json` on first use.
+Clawdbot also imports `oauth.json` into the agent auth store (`~/.clawdbot/agent/auth.json`) on first use.
 
 ### Recommended: OAuth (OpenAI Codex)
 
@@ -49,7 +49,7 @@ The macOS app should:
 - Start the OpenAI Codex OAuth (PKCE) flow in the user’s browser.
 - Auto-capture the callback on `http://127.0.0.1:1455/auth/callback` when possible.
 - If the callback fails, prompt the user to paste the redirect URL or code.
-- Store credentials in `~/.clawdbot/agent/auth.json` (same auth store as Anthropic).
+- Store credentials in `~/.clawdbot/credentials/oauth.json` (same OAuth store as Anthropic).
 
 ### Alternative: API key (instructions only)
 
@@ -148,12 +148,12 @@ If the Gateway runs on another machine, OAuth credentials must be created/stored
 
 For now, remote onboarding should:
 - explain why OAuth isn't shown
-- point the user at the credential location (`~/.clawdbot/agent/auth.json`) and the workspace location on the gateway host
+- point the user at the credential location (`~/.clawdbot/credentials/oauth.json`) and the workspace location on the gateway host
 - mention that the **bootstrap ritual happens on the gateway host** (same BOOTSTRAP/IDENTITY/USER files)
 
 ### Manual credential setup
 
-On the gateway host, create `~/.clawdbot/agent/auth.json` with this exact format:
+On the gateway host, create `~/.clawdbot/credentials/oauth.json` with this exact format:
 
 ```json
 {
@@ -162,7 +162,7 @@ On the gateway host, create `~/.clawdbot/agent/auth.json` with this exact format
 }
 ```
 
-Set permissions: `chmod 600 ~/.clawdbot/agent/auth.json`
+Set permissions: `chmod 600 ~/.clawdbot/credentials/oauth.json`
 
 **Note:** Clawdbot auto-imports from legacy pi-coding-agent paths (`~/.pi/agent/oauth.json`, etc.) but this does NOT work with Claude Code credentials — different file and format.
 
@@ -177,8 +177,8 @@ cat ~/.claude/.credentials.json | jq '{
     refresh: .claudeAiOauth.refreshToken,
     expires: .claudeAiOauth.expiresAt
   }
-}' > ~/.clawdbot/agent/auth.json
+}' > ~/.clawdbot/credentials/oauth.json
-chmod 600 ~/.clawdbot/agent/auth.json
+chmod 600 ~/.clawdbot/credentials/oauth.json
 ```
 
 | Claude Code field | Clawdbot field |

docs/wizard.md

@@ -52,7 +52,7 @@ It does **not** install or change anything on the remote host.
    - **API key**: stores the key for you.
    - **Minimax M2.1 (LM Studio)**: config is auto‑written for the LM Studio endpoint.
    - **Skip**: no auth configured yet.
-   - OAuth + API keys are stored in `~/.clawdbot/agent/auth.json`.
+   - OAuth credentials live in `~/.clawdbot/credentials/oauth.json`; API keys live in `~/.clawdbot/agent/auth.json`.
 
 3) **Workspace**
    - Default `~/clawd` (configurable).