From 4198fcd7db4725ba47708887eb17215f4578a024 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 21:29:41 +0000 Subject: [PATCH] docs: correct paths and setup guidance --- docs/RELEASING.md | 2 +- docs/agent.md | 2 +- docs/configuration.md | 4 ++-- docs/docker.md | 2 +- docs/faq.md | 4 ++-- docs/getting-started.md | 4 ++-- docs/mac/dev-setup.md | 2 +- docs/model-failover.md | 4 ++-- docs/multi-agent.md | 1 + docs/onboarding.md | 4 ++-- docs/plans/group-policy-hardening.md | 5 +++++ docs/remote-gateway-readme.md | 6 +++--- docs/security.md | 2 +- docs/setup.md | 5 +++-- docs/troubleshooting.md | 6 +++--- docs/wizard.md | 6 +++--- 16 files changed, 33 insertions(+), 26 deletions(-) diff --git a/docs/RELEASING.md b/docs/RELEASING.md index efc319c41..32f750a17 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -13,7 +13,7 @@ Use `pnpm` (Node 22+) from the repo root. Keep the working tree clean before tag 1) **Version & metadata** - [ ] Bump `package.json` version (e.g., `1.1.0`). - [ ] Update CLI/version strings: [`src/cli/program.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/cli/program.ts) and the Baileys user agent in [`src/provider-web.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/provider-web.ts). -- [ ] Confirm package metadata (name, description, repository, keywords, license) and `bin` map points to [`dist/index.js`](https://github.com/clawdbot/clawdbot/blob/main/dist/index.js) for `clawdbot`. +- [ ] Confirm package metadata (name, description, repository, keywords, license) and `bin` map points to [`dist/entry.js`](https://github.com/clawdbot/clawdbot/blob/main/dist/entry.js) for `clawdbot`. - [ ] If dependencies changed, run `pnpm install` so `pnpm-lock.yaml` is current. 2) **Build & artifacts** diff --git a/docs/agent.md b/docs/agent.md index 8a27f9507..44b449748 100644 --- a/docs/agent.md +++ b/docs/agent.md @@ -74,7 +74,7 @@ Apply these notes **only** when the user is Peter Steinberger at steipete. ## Sessions Session transcripts are stored as JSONL at: -- `~/.clawdbot/sessions/.jsonl` +- `~/.clawdbot/agents//sessions/.jsonl` The session ID is stable and chosen by CLAWDBOT. Legacy Pi/Tau session folders are **not** read. diff --git a/docs/configuration.md b/docs/configuration.md index 4b1b0ee7b..b4881fc04 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -933,11 +933,11 @@ URL is injected per session. Clawdbot uses the **pi-coding-agent** model catalog. You can add custom providers (LiteLLM, local OpenAI-compatible servers, Anthropic proxies, etc.) by writing -`~/.clawdbot/agent/models.json` or by defining the same schema inside your +`~/.clawdbot/agents//agent/models.json` or by defining the same schema inside your Clawdbot config under `models.providers`. When `models.providers` is present, Clawdbot writes/merges a `models.json` into -`~/.clawdbot/agent/` on startup: +`~/.clawdbot/agents//agent/` on startup: - default behavior: **merge** (keeps existing providers, overrides on name) - set `models.mode: "replace"` to overwrite the file contents diff --git a/docs/docker.md b/docs/docker.md index add8c0043..5950c3fb4 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -68,7 +68,7 @@ pnpm test:docker:qr ### Notes - Gateway bind defaults to `lan` for container use. -- The gateway container is the source of truth for sessions (`~/.clawdbot/sessions`). +- The gateway container is the source of truth for sessions (`~/.clawdbot/agents//sessions/`). ## Per-session Agent Sandbox (host gateway + Docker tools) diff --git a/docs/faq.md b/docs/faq.md index db6e205ed..2614ebe36 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -122,7 +122,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/credentials/oauth.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/agents//agent/auth-profiles.json` (and `auth.json` if present) to your server. Legacy installs can still import `~/.clawdbot/credentials/oauth.json` on first use. ### How are env vars loaded? @@ -152,7 +152,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/credentials/oauth.json` to the container. +1. **Copy auth manually** — Run OAuth on your laptop, copy `~/.clawdbot/agents//agent/auth-profiles.json` (and `auth.json` if present) to the container. Legacy flow: copy `~/.clawdbot/credentials/oauth.json` to trigger import. 2. **SSH tunnel** — `ssh -L 18789:localhost:18789 user@server` 3. **Tailscale** — Put both machines on your tailnet. diff --git a/docs/getting-started.md b/docs/getting-started.md index 5ebe6dc44..3244784fb 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -69,8 +69,8 @@ Wizard doc: https://docs.clawd.bot/wizard ### Auth: where it lives (important) -- OAuth credentials: `~/.clawdbot/credentials/oauth.json` -- Auth profiles (OAuth + API keys): `~/.clawdbot/agent/auth-profiles.json` +- OAuth credentials (legacy import): `~/.clawdbot/credentials/oauth.json` +- Auth profiles (OAuth + API keys): `~/.clawdbot/agents//agent/auth-profiles.json` Headless/server tip: do OAuth on a normal machine first, then copy `oauth.json` to the gateway host. diff --git a/docs/mac/dev-setup.md b/docs/mac/dev-setup.md index 2b0e2301a..a208e2195 100644 --- a/docs/mac/dev-setup.md +++ b/docs/mac/dev-setup.md @@ -57,7 +57,7 @@ The macOS app requires a symlink named `clawdbot` in `/usr/local/bin` or `/opt/h Alternatively, you can manually link it from your Admin account: ```bash -sudo ln -sf "/Users/$(whoami)/clawdbot/dist/Clawdbot.app/Contents/Resources/Relay/clawdbot" /usr/local/bin/clawdbot +sudo ln -sf "/Users/$(whoami)/Projects/clawdbot/dist/Clawdbot.app/Contents/Resources/Relay/clawdbot" /usr/local/bin/clawdbot ``` ## Troubleshooting diff --git a/docs/model-failover.md b/docs/model-failover.md index 39617981f..11c571e27 100644 --- a/docs/model-failover.md +++ b/docs/model-failover.md @@ -17,7 +17,7 @@ This doc explains the runtime rules and the data that backs them. Clawdbot uses **auth profiles** for both API keys and OAuth tokens. -- Secrets live in `~/.clawdbot/agent/auth-profiles.json` (default agent; multi-agent stores under `~/.clawdbot/agents//agent/auth-profiles.json`). +- Secrets live in `~/.clawdbot/agents//agent/auth-profiles.json` (legacy: `~/.clawdbot/agent/auth-profiles.json`). - Config `auth.profiles` / `auth.order` are **metadata + routing only** (no secrets). - Legacy import-only OAuth file: `~/.clawdbot/credentials/oauth.json` (imported into `auth-profiles.json` on first use). @@ -31,7 +31,7 @@ OAuth logins create distinct profiles so multiple accounts can coexist. - Default: `provider:default` when no email is available. - OAuth with email: `provider:` (for example `google-antigravity:user@gmail.com`). -Profiles live in `~/.clawdbot/agent/auth-profiles.json` under `profiles`. +Profiles live in `~/.clawdbot/agents//agent/auth-profiles.json` under `profiles`. ## Rotation order diff --git a/docs/multi-agent.md b/docs/multi-agent.md index e00c688c0..c0253346c 100644 --- a/docs/multi-agent.md +++ b/docs/multi-agent.md @@ -1,4 +1,5 @@ --- +summary: "Multi-agent routing: isolated agents, provider accounts, and bindings" title: Multi-Agent Routing read_when: "You want multiple isolated agents (workspaces + auth) in one gateway process." status: active diff --git a/docs/onboarding.md b/docs/onboarding.md index bc897e5e3..77da0c341 100644 --- a/docs/onboarding.md +++ b/docs/onboarding.md @@ -41,7 +41,7 @@ The macOS app should: - `~/.clawdbot/credentials/oauth.json` (file mode `0600`, directory mode `0700`) Why this location matters: it’s the Clawdbot-owned OAuth store. -Clawdbot also imports `oauth.json` into the agent auth profile store (`~/.clawdbot/agent/auth-profiles.json`) on first use. +Clawdbot also imports `oauth.json` into the agent auth profile store (`~/.clawdbot/agents//agent/auth-profiles.json`) on first use. ### Recommended: OAuth (OpenAI Codex) @@ -149,7 +149,7 @@ 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/credentials/oauth.json`) and the auth profile store (`~/.clawdbot/agent/auth-profiles.json`) on the gateway host +- point the user at the credential location (`~/.clawdbot/credentials/oauth.json`) and the auth profile store (`~/.clawdbot/agents//agent/auth-profiles.json`) on the gateway host - mention that the **bootstrap ritual happens on the gateway host** (same BOOTSTRAP/IDENTITY/USER files) ### Manual credential setup diff --git a/docs/plans/group-policy-hardening.md b/docs/plans/group-policy-hardening.md index c2000b1b7..208b95beb 100644 --- a/docs/plans/group-policy-hardening.md +++ b/docs/plans/group-policy-hardening.md @@ -1,3 +1,8 @@ +--- +summary: "Spec: groupPolicy hardening for Telegram allowlist parity" +read_when: + - Reviewing historical Telegram allowlist normalization changes +--- # Engineering Execution Spec: groupPolicy Hardening (Telegram Allowlist Parity) **Date**: 2026-01-05 diff --git a/docs/remote-gateway-readme.md b/docs/remote-gateway-readme.md index 039955a6d..f0b3f8ba4 100644 --- a/docs/remote-gateway-readme.md +++ b/docs/remote-gateway-readme.md @@ -108,7 +108,7 @@ Save this as `~/Library/LaunchAgents/com.clawdbot.ssh-tunnel.plist`: ### Load the Launch Agent ```bash -launchctl load ~/Library/LaunchAgents/com.clawdbot.ssh-tunnel.plist +launchctl bootstrap gui/$UID ~/Library/LaunchAgents/com.clawdbot.ssh-tunnel.plist ``` The tunnel will now: @@ -130,13 +130,13 @@ lsof -i :18789 **Restart the tunnel:** ```bash -launchctl restart com.clawdbot.ssh-tunnel +launchctl kickstart -k gui/$UID/com.clawdbot.ssh-tunnel ``` **Stop the tunnel:** ```bash -launchctl unload ~/Library/LaunchAgents/com.clawdbot.ssh-tunnel.plist +launchctl bootout gui/$UID/com.clawdbot.ssh-tunnel ``` --- diff --git a/docs/security.md b/docs/security.md index 1ea44fb97..a30d211f6 100644 --- a/docs/security.md +++ b/docs/security.md @@ -162,7 +162,7 @@ If your AI does something bad: 1. **Stop it:** stop the macOS app (if it’s supervising the Gateway) or terminate your `clawdbot gateway` process 2. **Check logs:** `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log` (or your configured `logging.file`) -3. **Review session:** Check `~/.clawdbot/sessions/` for what happened +3. **Review session:** Check `~/.clawdbot/agents//sessions/` for what happened 4. **Rotate secrets:** If credentials were exposed 5. **Update rules:** Add to your security prompt diff --git a/docs/setup.md b/docs/setup.md index c83026f3e..e331fc47e 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -77,7 +77,7 @@ pnpm install pnpm gateway:watch ``` -`gateway:watch` runs `src/index.ts gateway --force` and reloads on [`src/**/*.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/**/*.ts) changes. +`gateway:watch` runs `src/entry.ts gateway --force` and reloads on [`src/**/*.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/**/*.ts) changes. ### 2) Point the macOS app at your running Gateway @@ -102,7 +102,8 @@ pnpm clawdbot health - **Wrong port:** Gateway WS defaults to `ws://127.0.0.1:18789`; keep app + CLI on the same port. - **Where state lives:** - Credentials: `~/.clawdbot/credentials/` - - Sessions/logs: `~/.clawdbot/sessions/` + - Sessions: `~/.clawdbot/agents//sessions/` + - Logs: `/tmp/clawdbot/` ## Updating (without wrecking your setup) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index ec36c7bf1..f119b5029 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -14,7 +14,7 @@ When your CLAWDBOT misbehaves, here's how to fix it. The agent was interrupted mid-response. **Causes:** -- User sent `stop`, `abort`, `esc`, or `exit` +- User sent `stop`, `abort`, `esc`, `wait`, or `exit` - Timeout exceeded - Process crashed @@ -50,7 +50,7 @@ Known issue: When you send an image with ONLY a mention (no other text), WhatsAp **Check 1:** Is the session file there? ```bash -ls -la ~/.clawdbot/sessions/ +ls -la ~/.clawdbot/agents//sessions/ ``` **Check 2:** Is `idleMinutes` too short? @@ -188,7 +188,7 @@ clawdbot login --verbose | Log | Location | |-----|----------| | Main logs (default) | `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log` | -| Session files | `~/.clawdbot/sessions/` | +| Session files | `~/.clawdbot/agents//sessions/` | | Media cache | `~/.clawdbot/media/` | | Credentials | `~/.clawdbot/credentials/` | diff --git a/docs/wizard.md b/docs/wizard.md index da427146b..76ac67534 100644 --- a/docs/wizard.md +++ b/docs/wizard.md @@ -54,7 +54,7 @@ It does **not** install or change anything on the remote host. - **Minimax M2.1 (LM Studio)**: config is auto‑written for the LM Studio endpoint. - **Skip**: no auth configured yet. - Wizard runs a model check and warns if the configured model is unknown or missing auth. - - OAuth credentials live in `~/.clawdbot/credentials/oauth.json`; auth profiles live in `~/.clawdbot/agent/auth-profiles.json` (API keys + OAuth). + - OAuth credentials live in `~/.clawdbot/credentials/oauth.json`; auth profiles live in `~/.clawdbot/agents//agent/auth-profiles.json` (API keys + OAuth). 3) **Workspace** - Default `~/clawd` (configurable). @@ -156,8 +156,8 @@ Typical fields in `~/.clawdbot/clawdbot.json`: - `wizard.lastRunCommand` - `wizard.lastRunMode` -WhatsApp credentials go to `~/.clawdbot/credentials/`. -Sessions are stored under `~/.clawdbot/sessions/`. +WhatsApp credentials go under `~/.clawdbot/credentials/whatsapp//`. +Sessions are stored under `~/.clawdbot/agents//sessions/`. ## Related docs