clawdbot 2026.1.4-1

package/docs/session-tool.md

@@ -0,0 +1,119 @@
+---
+summary: "Agent session tools for listing sessions, fetching history, and sending cross-session messages"
+read_when:
+  - Adding or modifying session tools
+---
+
+# Session Tools
+
+Goal: small, hard-to-misuse tool surface so agents can list sessions, fetch history, and send to another session.
+
+## Tool Names
+- `sessions_list`
+- `sessions_history`
+- `sessions_send`
+
+## Key Model
+- Main direct chat bucket is always the literal key `"main"`.
+- Group chats use `surface:group:<id>` or `surface:channel:<id>`.
+- Cron jobs use `cron:<job.id>`.
+- Hooks use `hook:<uuid>` unless explicitly set.
+- Node bridge uses `node-<nodeId>` unless explicitly set.
+
+`global` and `unknown` are internal-only and never listed. If `session.scope = "global"`, we alias it to `main` for all tools so callers never see `global`.
+
+## sessions_list
+List sessions as an array of rows.
+
+Parameters:
+- `kinds?: string[]` filter: any of `"main" | "group" | "cron" | "hook" | "node" | "other"`
+- `limit?: number` max rows (default: server default, clamp e.g. 200)
+- `activeMinutes?: number` only sessions updated within N minutes
+- `messageLimit?: number` 0 = no messages (default 0); >0 = include last N messages
+
+Behavior:
+- `messageLimit > 0` fetches `chat.history` per session and includes the last N messages.
+- Tool results are filtered out in list output; use `sessions_history` for tool messages.
+
+Row shape (JSON):
+- `key`: session key (string)
+- `kind`: `main | group | cron | hook | node | other`
+- `provider`: `whatsapp | telegram | discord | signal | imessage | webchat | internal | unknown`
+- `displayName` (group display label if available)
+- `updatedAt` (ms)
+- `sessionId`
+- `model`, `contextTokens`, `totalTokens`
+- `thinkingLevel`, `verboseLevel`, `systemSent`, `abortedLastRun`
+- `sendPolicy` (session override if set)
+- `lastChannel`, `lastTo`
+- `transcriptPath` (best-effort path derived from store dir + sessionId)
+- `messages?` (only when `messageLimit > 0`)
+
+## sessions_history
+Fetch transcript for one session.
+
+Parameters:
+- `sessionKey` (required)
+- `limit?: number` max messages (server clamps)
+- `includeTools?: boolean` (default false)
+
+Behavior:
+- `includeTools=false` filters `role: "toolResult"` messages.
+- Returns messages array in the raw transcript format.
+
+## sessions_send
+Send a message into another session.
+
+Parameters:
+- `sessionKey` (required)
+- `message` (required)
+- `timeoutSeconds?: number` (default >0; 0 = fire-and-forget)
+
+Behavior:
+- `timeoutSeconds = 0`: enqueue and return `{ runId, status: "accepted" }`.
+- `timeoutSeconds > 0`: wait up to N seconds for completion, then return `{ runId, status: "ok", reply }`.
+- If wait times out: `{ runId, status: "timeout", error }`. Run continues; call `sessions_history` later.
+- If the run fails: `{ runId, status: "error", error }`.
+- Waits via gateway `agent.wait` (server-side) so reconnects don't drop the wait.
+- Agent-to-agent message context is injected for the primary run.
+- After the primary run completes, Clawdbot runs a **reply-back loop**:
+  - Round 2+ alternates between requester and target agents.
+  - Reply exactly `REPLY_SKIP` to stop the ping‑pong.
+  - Max turns is `session.agentToAgent.maxPingPongTurns` (0–5, default 5).
+- Once the loop ends, Clawdbot runs the **agent‑to‑agent announce step** (target agent only):
+  - Reply exactly `ANNOUNCE_SKIP` to stay silent.
+  - Any other reply is sent to the target channel.
+  - Announce step includes the original request + round‑1 reply + latest ping‑pong reply.
+
+## Provider Field
+- For groups, `provider` is the `surface` recorded on the session entry.
+- For direct chats, `provider` maps from `lastChannel`.
+- For cron/hook/node, `provider` is `internal`.
+- If missing, `provider` is `unknown`.
+
+## Security / Send Policy
+Policy-based blocking by surface/chat type (not per session id).
+
+```json
+{
+  "session": {
+    "sendPolicy": {
+      "rules": [
+        {
+          "match": { "surface": "discord", "chatType": "group" },
+          "action": "deny"
+        }
+      ],
+      "default": "allow"
+    }
+  }
+}
+```
+
+Runtime override (per session entry):
+- `sendPolicy: "allow" | "deny"` (unset = inherit config)
+- Settable via `sessions.patch` or owner-only `/send on|off|inherit`.
+
+Enforcement points:
+- `chat.send` / `agent` (gateway)
+- auto-reply delivery logic

package/docs/session.md

@@ -0,0 +1,84 @@
+---
+summary: "Session management rules, keys, and persistence for chats"
+read_when:
+  - Modifying session handling or storage
+---
+# Session Management
+
+Clawdbot treats **one session as primary**. The canonical key is fixed to `main` for direct chats (or `global` when scope is global); no configuration is required. `session.mainKey` is ignored. Older/local sessions can stay on disk, but only the primary key is used for desktop/web chat and direct agent calls.
+
+## Gateway is the source of truth
+All session state is **owned by the gateway** (the “master” Clawdbot). UI clients (macOS app, WebChat, etc.) must query the gateway for session lists and token counts instead of reading local files.
+
+- In **remote mode**, the session store you care about lives on the remote gateway host, not your Mac.
+- Token counts shown in UIs come from the gateway’s store fields (`inputTokens`, `outputTokens`, `totalTokens`, `contextTokens`). Clients do not parse JSONL transcripts to “fix up” totals.
+
+## Where state lives
+- On the **gateway host**:
+  - Store file: `~/.clawdbot/sessions/sessions.json` (legacy: `~/.clawdbot/sessions.json`).
+  - Transcripts: `~/.clawdbot/sessions/<SessionId>.jsonl` (one file per session id).
+- The store is a map `sessionKey -> { sessionId, updatedAt, ... }`. Deleting entries is safe; they are recreated on demand.
+- Group entries may include `displayName`, `surface`, `subject`, `room`, and `space` to label sessions in UIs.
+- Clawdbot does **not** read legacy Pi/Tau session folders.
+
+## Mapping transports → session keys
+- Direct chats (WhatsApp, Telegram, Discord, desktop Web Chat) all collapse to the **primary key** so they share context.
+- Multiple phone numbers can map to that same key; they act as transports into the same conversation.
+- Group chats isolate state with `surface:group:<id>` keys (rooms/channels use `surface:channel:<id>`); do not reuse the primary key for groups. (Discord display names show `discord:<guildSlug>#<channelSlug>`.)
+  - Legacy `group:<surface>:<id>` and `group:<id>` keys are still recognized.
+- Other sources:
+  - Cron jobs: `cron:<job.id>`
+  - Webhooks: `hook:<uuid>` (unless explicitly set by the hook)
+  - Node bridge runs: `node-<nodeId>`
+
+## Lifecyle
+- Idle expiry: `session.idleMinutes` (default 60). After the timeout a new `sessionId` is minted on the next message.
+- Reset triggers: exact `/new` or `/reset` (plus any extras in `resetTriggers`) start a fresh session id and pass the remainder of the message through. If `/new` or `/reset` is sent alone, Clawdbot runs a short “hello” greeting turn to confirm the reset.
+- Manual reset: delete specific keys from the store or remove the JSONL transcript; the next message recreates them.
+
+## Send policy (optional)
+Block delivery for specific session types without listing individual ids.
+
+```json5
+{
+  session: {
+    sendPolicy: {
+      rules: [
+        { action: "deny", match: { surface: "discord", chatType: "group" } },
+        { action: "deny", match: { keyPrefix: "cron:" } }
+      ],
+      default: "allow"
+    }
+  }
+}
+```
+
+Runtime override (owner only):
+- `/send on` → allow for this session
+- `/send off` → deny for this session
+- `/send inherit` → clear override and use config rules
+
+## Configuration (optional rename example)
+```json5
+// ~/.clawdbot/clawdbot.json
+{
+  session: {
+    scope: "per-sender",      // keep group keys separate
+    idleMinutes: 120,
+    resetTriggers: ["/new", "/reset"],
+    store: "~/.clawdbot/sessions/sessions.json",
+    // mainKey is ignored; primary key is fixed to "main"
+  }
+}
+```
+
+## Inspecting
+- `pnpm clawdbot status` — shows store path and recent sessions.
+- `pnpm clawdbot sessions --json` — dumps every entry (filter with `--active <minutes>`).
+- `pnpm clawdbot gateway call sessions.list --params '{}'` — fetch sessions from the running gateway (use `--url`/`--token` for remote gateway access).
+- Send `/status` in chat to see whether the agent is reachable, how much of the session context is used, current thinking/verbose toggles, and when your WhatsApp web creds were last refreshed (helps spot relink needs).
+- JSONL transcripts can be opened directly to review full turns.
+
+## Tips
+- Keep the primary key dedicated to 1:1 traffic; let groups keep their own keys.
+- When automating cleanup, delete individual keys instead of the whole store to preserve context elsewhere.

package/docs/sessions.md

@@ -0,0 +1,8 @@
+---
+summary: "Alias for session management docs"
+read_when:
+  - You looked for docs/sessions.md; canonical doc lives in docs/session.md
+---
+# Sessions
+
+Canonical session management docs live in `docs/session.md`.

package/docs/setup.md

@@ -0,0 +1,118 @@
+---
+summary: "Setup guide: keep your Clawdbot setup tailored while staying up-to-date"
+read_when:
+  - Setting up a new machine
+  - You want “latest + greatest” without breaking your personal setup
+---
+
+# Setup
+
+Last updated: 2026-01-01
+
+## TL;DR
+- **Tailoring lives outside the repo:** `~/clawd` (workspace) + `~/.clawdbot/clawdbot.json` (config).
+- **Stable workflow:** install the macOS app; let it run the bundled Gateway.
+- **Bleeding edge workflow:** run the Gateway yourself via `pnpm gateway:watch`, then point the macOS app at it using **Debug Settings → Gateway → Attach only**.
+
+## Prereqs (from source)
+- Node `>=22`
+- `pnpm`
+- Docker (optional; only for containerized setup/e2e — see `docs/docker.md`)
+
+## Tailoring strategy (so updates don’t hurt)
+
+If you want “100% tailored to me” *and* easy updates, keep your customization in:
+
+- **Config:** `~/.clawdbot/clawdbot.json` (JSON/JSON5-ish)
+- **Workspace:** `~/clawd` (skills, prompts, memories; make it a private git repo)
+
+Bootstrap once:
+
+```bash
+clawdbot setup
+```
+
+From inside this repo, use the local CLI entry:
+
+```bash
+pnpm clawdbot setup
+```
+
+## Stable workflow (macOS app first)
+
+1) Install + launch **Clawdbot.app** (menu bar).
+2) Complete the onboarding/permissions checklist (TCC prompts).
+3) Ensure Gateway is **Local** and running (the app manages it).
+4) Link surfaces (example: WhatsApp):
+
+```bash
+clawdbot login
+```
+
+5) Sanity check:
+
+```bash
+clawdbot health
+```
+
+If onboarding is still WIP/broken on your build:
+- Run `clawdbot setup`, then `clawdbot login`, then start the Gateway manually (`clawdbot gateway`).
+
+## Bleeding edge workflow (Gateway in a terminal)
+
+Goal: work on the TypeScript Gateway, get hot reload, keep the macOS app UI attached.
+
+### 0) (Optional) Run the macOS app from source too
+
+If you also want the macOS app on the bleeding edge:
+
+```bash
+./scripts/restart-mac.sh
+```
+
+### 1) Start the dev Gateway
+
+```bash
+pnpm install
+pnpm gateway:watch
+```
+
+`gateway:watch` runs `src/index.ts gateway --force` and reloads on `src/**/*.ts` changes.
+
+### 2) Point the macOS app at your running Gateway
+
+In **Clawdbot.app**:
+
+- Connection Mode: **Local**
+- Settings → **Debug Settings** → **Gateway** → enable **Attach only**
+
+This makes the app **only connect to an already-running gateway** and **never spawn** its own.
+
+### 3) Verify
+
+- In-app Gateway status should read **“Using existing gateway …”**
+- Or via CLI:
+
+```bash
+pnpm clawdbot health
+```
+
+### Common footguns
+- **Attach only enabled, but nothing is running:** app shows “Attach-only enabled; no gateway to attach”.
+- **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/`
+
+## Updating (without wrecking your setup)
+
+- Keep `~/clawd` and `~/.clawdbot/` as “your stuff”; don’t put personal prompts/config into the `clawdbot` repo.
+- Updating source: `git pull` + `pnpm install` (when lockfile changed) + keep using `pnpm gateway:watch`.
+
+## Related docs
+
+- `docs/gateway.md` (Gateway runbook; flags, supervision, ports)
+- `docs/configuration.md` (config schema + examples)
+- `docs/discord.md` and `docs/telegram.md` (reply tags + replyToMode settings)
+- `docs/clawd.md` (personal assistant setup)
+- `docs/clawdbot-mac.md` (macOS app behavior; gateway lifecycle + “Attach only”)

package/docs/signal.md

@@ -0,0 +1,113 @@
+---
+summary: "Signal support via signal-cli (JSON-RPC + SSE), setup, and number model"
+read_when:
+  - Setting up Signal support
+  - Debugging Signal send/receive
+---
+# Signal (signal-cli)
+
+Status: external CLI integration only. No libsignal embedding.
+
+## Why
+- Signal OSS stack is GPL/AGPL; not compatible with Clawdbot MIT if bundled.
+- signal-cli is unofficial; must stay up to date (Signal server churn).
+
+## The “number model” (important)
+- Clawdbot is a **device** connected via `signal-cli`.
+- If you run `signal-cli` on **your personal Signal account**, Clawdbot will **not** respond to messages sent from that same account (loop protection: ignore sender==account).
+  - Result: you **cannot** “text yourself” to chat with the AI.
+- For “I text her, she texts me back” you want a **separate Signal account/number for the bot**:
+  - Bot number runs `signal-cli` (linked device)
+  - Your personal number is in `signal.allowFrom`
+  - You DM the bot number; Clawdbot replies back to you
+
+You can still run Clawdbot on your own Signal account if your goal is “respond to other people as me”, but not for self-chat.
+
+## Model
+- Run `signal-cli` as separate process (user-installed).
+- Prefer `daemon --http=127.0.0.1:PORT` for JSON-RPC + SSE.
+- Alternative: `jsonRpc` mode over stdin/stdout.
+
+## Quickstart (bot number)
+1) Install `signal-cli` (keep Java installed).
+   - If you use the CLI wizard, it can auto-install to `~/.clawdbot/tools/signal-cli/...`.
+   - If you want a pinned version (example: `v0.13.22`), install manually:
+     - Download the release asset for your platform from GitHub (tag `v0.13.22`).
+     - Extract it somewhere stable (example: `~/.clawdbot/tools/signal-cli/0.13.22/`).
+     - Set `signal.cliPath` to the extracted `signal-cli` binary path.
+2) Link the bot account as a device:
+   - Run: `signal-cli link -n "Clawdbot"`
+   - Scan QR in Signal: Settings → Linked Devices → Link New Device
+   - Verify: `signal-cli listAccounts` includes the bot E.164
+3) Configure `~/.clawdbot/clawdbot.json`:
+```json5
+{
+  signal: {
+    enabled: true,
+    account: "+15551234567", // bot number (recommended)
+    cliPath: "signal-cli",
+    autoStart: true,
+    httpHost: "127.0.0.1",
+    httpPort: 8080,
+
+    // Who is allowed to talk to the bot
+    allowFrom: ["+15557654321"] // your personal number (or "*")
+  }
+}
+```
+4) Run gateway; sanity probe:
+   - `clawdbot gateway call providers.status --params '{"probe":true}'`
+   - Expect `signal.probe.ok=true` and `signal.probe.version`.
+5) DM the bot number from your phone; Clawdbot replies.
+
+## “Do I need a separate number?”
+- If you want “I text her and she texts me back”, yes: **use a separate Signal account/number for the bot**.
+- Your personal account can run `signal-cli`, but you can’t self-chat (Signal loop protection; Clawdbot ignores sender==account).
+
+If you have a second phone:
+- Create/activate the bot number on that phone.
+- Run `signal-cli link -n "Clawdbot"` on your Mac, scan the QR on the bot phone.
+- Put your personal number in `signal.allowFrom`, then DM the bot number from your personal phone.
+
+## Endpoints (daemon --http)
+- `POST /api/v1/rpc` JSON-RPC request (single or batch).
+- `GET /api/v1/events` SSE stream of `receive` notifications.
+- `GET /api/v1/check` health probe (200 = up).
+
+## Multi-account
+- Start daemon without `-a`.
+- Include `params.account` (E164) on JSON-RPC calls.
+- SSE `?account=+E164` filters events; no param = all accounts.
+
+## Troubleshooting
+- Gateway log coloring: `signal-cli: ...` lines are classified by severity; red means “treat this as an error”.
+- `Failed to initialize HTTP Server` typically means the daemon can’t bind the HTTP port (already in use). Stop the other daemon or change `signal.httpPort`.
+
+## Minimal RPC surface
+- `send` (recipient/groupId/username, message, attachments).
+- `listGroups` (map group IDs).
+- `subscribeReceive` / `unsubscribeReceive` (if manual receive).
+- `startLink` / `finishLink` (optional device link flow).
+
+## Addressing (send targets)
+- Direct: `signal:+15551234567` (or plain `+15551234567`)
+- Groups: `signal:group:<groupId>`
+- Usernames: `username:<name>` / `u:<name>`
+
+## Process plan (Clawdbot adapter)
+1) Detect `signal-cli` binary; refuse if missing.
+2) Launch daemon (HTTP preferred), store PID.
+3) Poll `/api/v1/check` until ready.
+4) Open SSE stream; parse `event: receive`.
+5) Translate receive payload into Clawdbot surface model.
+6) On SSE disconnect, backoff + reconnect.
+
+## Storage
+- signal-cli data lives in `$XDG_DATA_HOME/signal-cli/data` or
+  `$HOME/.local/share/signal-cli/data`.
+
+## References (local)
+- `~/Projects/oss/signal-cli/README.md`
+- `~/Projects/oss/signal-cli/man/signal-cli-jsonrpc.5.adoc`
+- `~/Projects/oss/signal-cli/src/main/java/org/asamk/signal/http/HttpServerHandler.java`
+- `~/Projects/oss/signal-cli/src/main/java/org/asamk/signal/jsonrpc/SignalJsonRpcDispatcherHandler.java`

package/docs/skills-config.md

@@ -0,0 +1,58 @@
+---
+summary: "Skills config schema and examples"
+read_when:
+  - Adding or modifying skills config
+  - Adjusting bundled allowlist or install behavior
+---
+# Skills Config
+
+All skills-related configuration lives under `skills` in `~/.clawdbot/clawdbot.json`.
+
+```json5
+{
+  skills: {
+    allowBundled: ["brave-search", "gemini"],
+    load: {
+      extraDirs: [
+        "~/Projects/agent-scripts/skills",
+        "~/Projects/oss/some-skill-pack/skills"
+      ]
+    },
+    install: {
+      preferBrew: true,
+      nodeManager: "npm" // npm | pnpm | yarn | bun
+    },
+    entries: {
+      "nano-banana-pro": {
+        enabled: true,
+        apiKey: "GEMINI_KEY_HERE",
+        env: {
+          GEMINI_API_KEY: "GEMINI_KEY_HERE"
+        }
+      },
+      peekaboo: { enabled: true },
+      sag: { enabled: false }
+    }
+  }
+}
+```
+
+## Fields
+
+- `allowBundled`: optional allowlist for **bundled** skills only. When set, only
+  bundled skills in the list are eligible (managed/workspace skills unaffected).
+- `load.extraDirs`: additional skill directories to scan (lowest precedence).
+- `install.preferBrew`: prefer brew installers when available (default: true).
+- `install.nodeManager`: node installer preference (`npm` | `pnpm` | `yarn` | `bun`, default: npm).
+- `entries.<skillKey>`: per-skill overrides.
+
+Per-skill fields:
+- `enabled`: set `false` to disable a skill even if it’s bundled/installed.
+- `env`: environment variables injected for the agent run (only if not already set).
+- `apiKey`: optional convenience for skills that declare a primary env var.
+
+## Notes
+
+- Keys under `entries` map to the skill name by default. If a skill defines
+  `metadata.clawdbot.skillKey`, use that key instead.
+- Changes to skills are picked up on the next new session.

package/docs/skills.md

@@ -0,0 +1,149 @@
+---
+summary: "Skills: managed vs workspace, gating rules, and config/env wiring"
+read_when:
+  - Adding or modifying skills
+  - Changing skill gating or load rules
+---
+<!-- {% raw %} -->
+# Skills (Clawdbot)
+
+Clawdbot uses **AgentSkills-compatible** skill folders to teach the agent how to use tools. Each skill is a directory containing a `SKILL.md` with YAML frontmatter and instructions. Clawdbot loads **bundled skills** plus optional local overrides, and filters them at load time based on environment, config, and binary presence.
+
+## Locations and precedence
+
+Skills are loaded from **three** places:
+
+1) **Bundled skills**: shipped with the install (npm package or Clawdbot.app)
+2) **Managed/local skills**: `~/.clawdbot/skills`
+3) **Workspace skills**: `<workspace>/skills`
+
+If a skill name conflicts, precedence is:
+
+`<workspace>/skills` (highest) → `~/.clawdbot/skills` → bundled skills (lowest)
+
+Additionally, you can configure extra skill folders (lowest precedence) via
+`skills.load.extraDirs` in `~/.clawdbot/clawdbot.json`.
+
+## Format (AgentSkills + Pi-compatible)
+
+`SKILL.md` must include at least:
+
+```markdown
+---
+name: nano-banana-pro
+description: Generate or edit images via Gemini 3 Pro Image
+---
+```
+
+Notes:
+- We follow the AgentSkills spec for layout/intent.
+- The parser used by the embedded agent supports **single-line** frontmatter keys only.
+- `metadata` should be a **single-line JSON object**.
+- Use `{baseDir}` in instructions to reference the skill folder path.
+- Optional frontmatter keys:
+  - `homepage` — URL surfaced as “Website” in the macOS Skills UI (also supported via `metadata.clawdbot.homepage`).
+
+## Gating (load-time filters)
+
+Clawdbot **filters skills at load time** using `metadata` (single-line JSON):
+
+```markdown
+---
+name: nano-banana-pro
+description: Generate or edit images via Gemini 3 Pro Image
+metadata: {"clawdbot":{"requires":{"bins":["uv"],"env":["GEMINI_API_KEY"],"config":["browser.enabled"]},"primaryEnv":"GEMINI_API_KEY"}}
+---
+```
+
+Fields under `metadata.clawdbot`:
+- `always: true` — always include the skill (skip other gates).
+- `emoji` — optional emoji used by the macOS Skills UI.
+- `homepage` — optional URL shown as “Website” in the macOS Skills UI.
+- `os` — optional list of platforms (`darwin`, `linux`, `win32`). If set, the skill is only eligible on those OSes.
+- `requires.bins` — list; each must exist on `PATH`.
+- `requires.anyBins` — list; at least one must exist on `PATH`.
+- `requires.env` — list; env var must exist **or** be provided in config.
+- `requires.config` — list of `clawdbot.json` paths that must be truthy.
+- `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).
+
+Installer example:
+
+```markdown
+---
+name: gemini
+description: Use Gemini CLI for coding assistance and Google search lookups.
+metadata: {"clawdbot":{"emoji":"♊️","requires":{"bins":["gemini"]},"install":[{"id":"brew","kind":"brew","formula":"gemini-cli","bins":["gemini"],"label":"Install Gemini CLI (brew)"}]}}
+---
+```
+
+Notes:
+- If multiple installers are listed, the gateway picks a **single** preferred option (brew when available, otherwise node).
+- Node installs honor `skills.install.nodeManager` in `clawdbot.json` (default: npm; options: npm/pnpm/yarn/bun).
+- Go installs: if `go` is missing and `brew` is available, the gateway installs Go via Homebrew first and sets `GOBIN` to Homebrew’s `bin` when possible.
+
+If no `metadata.clawdbot` is present, the skill is always eligible (unless
+disabled in config or blocked by `skills.allowBundled` for bundled skills).
+
+## Config overrides (`~/.clawdbot/clawdbot.json`)
+
+Bundled/managed skills can be toggled and supplied with env values:
+
+```json5
+{
+  skills: {
+    entries: {
+      "nano-banana-pro": {
+        enabled: true,
+        apiKey: "GEMINI_KEY_HERE",
+        env: {
+          GEMINI_API_KEY: "GEMINI_KEY_HERE"
+        }
+      },
+      peekaboo: { enabled: true },
+      sag: { enabled: false }
+    }
+  }
+}
+```
+
+Note: if the skill name contains hyphens, quote the key (JSON5 allows quoted keys).
+
+Config keys match the **skill name** by default. If a skill defines
+`metadata.clawdbot.skillKey`, use that key under `skills.entries`.
+
+Rules:
+- `enabled: false` disables the skill even if it’s bundled/installed.
+- `env`: injected **only if** the variable isn’t already set in the process.
+- `apiKey`: convenience for skills that declare `metadata.clawdbot.primaryEnv`.
+- `allowBundled`: optional allowlist for **bundled** skills only. If set, only
+  bundled skills in the list are eligible (managed/workspace skills unaffected).
+
+## Environment injection (per agent run)
+
+When an agent run starts, Clawdbot:
+1) Reads skill metadata.
+2) Applies any `skills.entries.<key>.env` or `skills.entries.<key>.apiKey` to
+   `process.env`.
+3) Builds the system prompt with **eligible** skills.
+4) Restores the original environment after the run ends.
+
+This is **scoped to the agent run**, not a global shell environment.
+
+## Session snapshot (performance)
+
+Clawdbot snapshots the eligible skills **when a session starts** and reuses that list for subsequent turns in the same session. Changes to skills or config take effect on the next new session.
+
+## Managed skills lifecycle
+
+Clawdbot ships a baseline set of skills as **bundled skills** as part of the
+install (npm package or Clawdbot.app). `~/.clawdbot/skills` exists for local
+overrides (for example, pinning/patching a skill without changing the bundled
+copy). Workspace skills are user-owned and override both on name conflicts.
+
+## Config reference
+
+See `docs/skills-config.md` for the full configuration schema.
+
+---
+<!-- {% endraw %} -->