From 7366b55b14999bb44bedec39c5b00567fb103b6f Mon Sep 17 00:00:00 2001
From: William Stock <w.stock@yahoo.com>
Date: Thu, 1 Jan 2026 14:21:22 +0000
Subject: [PATCH] docs: Add manual OAuth setup for remote/headless deployments
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Expand "Remote mode note" section with:
- Exact oauth.json format required (access, refresh, expires)
- Note that auto-import doesn't work with Claude Code credentials
- jq script to convert Claude Code credentials to Clawdis format

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 docs/onboarding.md | 41 ++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 40 insertions(+), 1 deletion(-)

diff --git a/docs/onboarding.md b/docs/onboarding.md
index 958a953f3..ee11f6dcf 100644
--- a/docs/onboarding.md
+++ b/docs/onboarding.md
@@ -123,7 +123,46 @@ Daily memory lives under `memory/` in the workspace:
 If the Gateway runs on another machine, the Anthropic OAuth credentials must be created/stored on that host (where the agent runtime runs).
 
 For now, remote onboarding should:
-- explain why OAuth isn’t shown
+- explain why OAuth isn't shown
 - point the user at the credential location (`~/.clawdis/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 `~/.clawdis/credentials/oauth.json` with this exact format:
+
+```json
+{
+  "anthropic": {
+    "access": "sk-ant-oat01-...",
+    "refresh": "sk-ant-ort01-...",
+    "expires": 1767304352803
+  }
+}
+```
+
+Set permissions: `chmod 600 ~/.clawdis/credentials/oauth.json`
+
+**Note:** Clawdis can auto-import from legacy pi-coding-agent paths (`~/.pi/agent/oauth.json`, etc.) but this does NOT work with Claude Code credentials — different file and format.
+
+### Using Claude Code credentials
+
+If Claude Code is installed on the gateway host, convert its credentials:
+
+```bash
+cat ~/.claude/.credentials.json | jq '{
+  anthropic: {
+    access: .claudeAiOauth.accessToken,
+    refresh: .claudeAiOauth.refreshToken,
+    expires: .claudeAiOauth.expiresAt
+  }
+}' > ~/.clawdis/credentials/oauth.json
+chmod 600 ~/.clawdis/credentials/oauth.json
+```
+
+| Claude Code field | Clawdis field |
+|-------------------|---------------|
+| `accessToken` | `access` |
+| `refreshToken` | `refresh` |
+| `expiresAt` | `expires` |
 <!-- {% endraw %} -->