docs: clarify agent auth + sandboxed skills

CHANGELOG.md

@@ -3,6 +3,8 @@
 ## 2026.1.14 (unreleased)
 
 ### Changes
+- Docs: clarify per-agent auth stores, sandboxed skill binaries, and elevated semantics.
+- Docs: add FAQ entries for missing provider auth after adding agents and Gemini thinking signature errors.
 - Security: add `clawdbot security audit` (`--deep`, `--fix`) and surface it in `status --all` and `doctor`.
 - Onboarding: add a security checkpoint prompt (docs link + sandboxing hint); require `--accept-risk` for `--non-interactive`.
 - Docs: expand gateway security hardening guidance and incident response checklist.

docs/concepts/multi-agent.md

@@ -17,6 +17,16 @@ An **agent** is a fully scoped brain with its own:
 - **State directory** (`agentDir`) for auth profiles, model registry, and per-agent config.
 - **Session store** (chat history + routing state) under `~/.clawdbot/agents/<agentId>/sessions`.
 
+Auth profiles are **per-agent**. Each agent reads from its own:
+
+```
+~/.clawdbot/agents/<agentId>/agent/auth-profiles.json
+```
+
+Main agent credentials are **not** shared automatically. Never reuse `agentDir`
+across agents (it causes auth/session collisions). If you want to share creds,
+copy `auth-profiles.json` into the other agent's `agentDir`.
+
 Skills are per-agent via each workspace’s `skills/` folder, with shared skills
 available from `~/.clawdbot/skills`. See [Skills: per-agent vs shared](/tools/skills#per-agent-vs-shared-skills).
 

docs/gateway/sandbox-vs-tool-policy-vs-elevated.md

@@ -93,6 +93,7 @@ Available groups:
 Elevated does **not** grant extra tools; it only affects `exec`.
 - If you’re sandboxed, `/elevated on` (or `exec` with `elevated: true`) runs on the host.
 - If you’re already running direct, elevated is effectively a no-op (still gated).
+- Elevated is **not** skill-scoped and does **not** override tool allow/deny.
 
 Gates:
 - Enablement: `tools.elevated.enabled` (and optionally `agents.list[].tools.elevated.enabled`)

docs/multi-agent-sandbox-tools.md

@@ -18,6 +18,15 @@ This allows you to run multiple agents with different security profiles:
 - Family/work agents with restricted tools
 - Public-facing agents in sandboxes
 
+Auth is per-agent: each agent reads from its own `agentDir` auth store at:
+
+```
+~/.clawdbot/agents/<agentId>/agent/auth-profiles.json
+```
+
+Credentials are **not** shared between agents. Never reuse `agentDir` across agents.
+If you want to share creds, copy `auth-profiles.json` into the other agent's `agentDir`.
+
 For how sandboxing behaves at runtime, see [Sandboxing](/gateway/sandboxing).
 For debugging “why is this blocked?”, see [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) and `clawdbot sandbox explain`.
 

docs/start/faq.md

@@ -1027,6 +1027,21 @@ Z.AI (GLM models):
 
 If you reference a provider/model but the required provider key is missing, you’ll get a runtime auth error (e.g. `No API key found for provider "zai"`).
 
+### “No API key found for provider …” after adding a new agent
+
+This usually means the **new agent** has an empty auth store. Auth is per-agent and
+stored in:
+
+```
+~/.clawdbot/agents/<agentId>/agent/auth-profiles.json
+```
+
+Fix options:
+- Run `clawdbot agents add <id>` and configure auth during the wizard.
+- Or copy `auth-profiles.json` from the main agent’s `agentDir` into the new agent’s `agentDir`.
+
+Do **not** reuse `agentDir` across agents; it causes auth/session collisions.
+
 ## Model failover and “All models failed”
 
 ### How does failover work?
@@ -1081,6 +1096,13 @@ If your model config includes Google Gemini as a fallback (or you switched to a
 
 Fix: either provide Google auth, or remove/avoid Google models in `agents.defaults.model.fallbacks` / aliases so fallback doesn’t route there.
 
+### “LLM request rejected: messages.*.thinking.signature required (google‑antigravity)”
+
+Cause: the session history contains **thinking blocks without signatures** (often from
+an aborted/partial stream). Google Antigravity requires signatures for thinking blocks.
+
+Fix: start a **new session** or set `/thinking off` for that agent.
+
 ## Auth profiles: what they are and how to manage them
 
 Related: [/concepts/oauth](/concepts/oauth) (OAuth flows, token storage, multi-account patterns, CLI sync)

docs/tools/elevated.md

@@ -20,6 +20,7 @@ read_when:
 - **Host execution**: elevated runs `exec` on the host (bypasses sandbox).
 - **Unsandboxed agents**: when there is no sandbox to bypass, elevated does not change where `exec` runs.
 - **Tool policy still applies**: if `exec` is denied by tool policy, elevated cannot be used.
+- **Not skill-scoped**: elevated cannot be limited to a specific skill; it only changes `exec` location.
 
 Note:
 - Sandbox on: `/elevated on` runs that `exec` command on the host.

docs/tools/skills.md

@@ -105,6 +105,13 @@ Fields under `metadata.clawdbot`:
 - `primaryEnv` — env var name associated with `skills.entries.<name>.apiKey`.
 - `install` — optional array of installer specs used by the macOS Skills UI (brew/node/go/uv).
 
+Note on sandboxing:
+- `requires.bins` is checked on the **host** at skill load time.
+- If an agent is sandboxed, the binary must also exist **inside the container**.
+  Install it via `agents.defaults.sandbox.docker.setupCommand` (or a custom image).
+  Example: the `summarize` skill (`skills/summarize/SKILL.md`) needs the `summarize` CLI
+  in the sandbox container to run there.
+
 Installer example:
 
 ```markdown