chore: Run pnpm format:fix.

docs/reference/AGENTS.default.md

@@ -4,19 +4,20 @@ read_when:
   - Starting a new OpenClaw agent session
   - Enabling or auditing default skills
 ---
+
 # AGENTS.md — OpenClaw Personal Assistant (default)
 
 ## First run (recommended)
 
 OpenClaw uses a dedicated workspace directory for the agent. Default: `~/.openclaw/workspace` (configurable via `agents.defaults.workspace`).
 
-1) Create the workspace (if it doesn’t already exist):
+1. Create the workspace (if it doesn’t already exist):
 
 ```bash
 mkdir -p ~/.openclaw/workspace
 ```
 
-2) Copy the default workspace templates into the workspace:
+2. Copy the default workspace templates into the workspace:
 
 ```bash
 cp docs/reference/templates/AGENTS.md ~/.openclaw/workspace/AGENTS.md
@@ -24,39 +25,44 @@ cp docs/reference/templates/SOUL.md ~/.openclaw/workspace/SOUL.md
 cp docs/reference/templates/TOOLS.md ~/.openclaw/workspace/TOOLS.md
 ```
 
-3) Optional: if you want the personal assistant skill roster, replace AGENTS.md with this file:
+3. Optional: if you want the personal assistant skill roster, replace AGENTS.md with this file:
 
 ```bash
 cp docs/reference/AGENTS.default.md ~/.openclaw/workspace/AGENTS.md
 ```
 
-4) Optional: choose a different workspace by setting `agents.defaults.workspace` (supports `~`):
+4. Optional: choose a different workspace by setting `agents.defaults.workspace` (supports `~`):
 
 ```json5
 {
-  agents: { defaults: { workspace: "~/.openclaw/workspace" } }
+  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
 }
 ```
 
 ## Safety defaults
+
 - Don’t dump directories or secrets into chat.
 - Don’t run destructive commands unless explicitly asked.
 - Don’t send partial/streaming replies to external messaging surfaces (only final replies).
 
 ## Session start (required)
+
 - Read `SOUL.md`, `USER.md`, `memory.md`, and today+yesterday in `memory/`.
 - Do it before responding.
 
 ## Soul (required)
+
 - `SOUL.md` defines identity, tone, and boundaries. Keep it current.
 - If you change `SOUL.md`, tell the user.
 - You are a fresh instance each session; continuity lives in these files.
 
 ## Shared spaces (recommended)
+
 - You’re not the user’s voice; be careful in group chats or public channels.
 - Don’t share private data, contact info, or internal notes.
 
 ## Memory system (recommended)
+
 - Daily log: `memory/YYYY-MM-DD.md` (create `memory/` if needed).
 - Long-term memory: `memory.md` for durable facts, preferences, and decisions.
 - On session start, read today + yesterday + `memory.md` if present.
@@ -64,10 +70,12 @@ cp docs/reference/AGENTS.default.md ~/.openclaw/workspace/AGENTS.md
 - Avoid secrets unless explicitly requested.
 
 ## Tools & skills
+
 - Tools live in skills; follow each skill’s `SKILL.md` when you need it.
 - Keep environment-specific notes in `TOOLS.md` (Notes for Skills).
 
 ## Backup tip (recommended)
+
 If you treat this workspace as Clawd’s “memory”, make it a git repo (ideally private) so `AGENTS.md` and your memory files are backed up.
 
 ```bash
@@ -79,11 +87,13 @@ git commit -m "Add Clawd workspace"
 ```
 
 ## What OpenClaw Does
+
 - Runs WhatsApp gateway + Pi coding agent so the assistant can read/write chats, fetch context, and run skills via the host Mac.
 - macOS app manages permissions (screen recording, notifications, microphone) and exposes the `openclaw` CLI via its bundled binary.
 - Direct chats collapse into the agent's `main` session by default; groups stay isolated as `agent:<agentId>:<channel>:group:<id>` (rooms/channels: `agent:<agentId>:<channel>:channel:<id>`); heartbeats keep background tasks alive.
 
 ## Core Skills (enable in Settings → Skills)
+
 - **mcporter** — Tool server runtime/CLI for managing external skill backends.
 - **Peekaboo** — Fast macOS screenshots with optional AI vision analysis.
 - **camsnap** — Capture frames, clips, or motion alerts from RTSP/ONVIF security cams.
@@ -104,6 +114,7 @@ git commit -m "Add Clawd workspace"
 - **agent-tools** — Utility toolkit for automations and helper scripts.
 
 ## Usage Notes
+
 - Prefer the `openclaw` CLI for scripting; mac app handles permissions.
 - Run installs from the Skills tab; it hides the button if a binary is already present.
 - Keep heartbeats enabled so the assistant can schedule reminders, monitor inboxes, and trigger camera captures.

docs/reference/RELEASING.md

@@ -11,30 +11,36 @@ read_when:
 Use `pnpm` (Node 22+) from the repo root. Keep the working tree clean before tagging/publishing.
 
 ## Operator trigger
+
 When the operator says “release”, immediately do this preflight (no extra questions unless blocked):
+
 - Read this doc and `docs/platforms/mac/release.md`.
 - Load env from `~/.profile` and confirm `SPARKLE_PRIVATE_KEY_FILE` + App Store Connect vars are set (SPARKLE_PRIVATE_KEY_FILE should live in `~/.profile`).
 - Use Sparkle keys from `~/Library/CloudStorage/Dropbox/Backup/Sparkle` if needed.
 
-1) **Version & metadata**
+1. **Version & metadata**
+
 - [ ] Bump `package.json` version (e.g., `2026.1.29`).
 - [ ] Run `pnpm plugins:sync` to align extension package versions + changelogs.
 - [ ] Update CLI/version strings: [`src/cli/program.ts`](https://github.com/openclaw/openclaw/blob/main/src/cli/program.ts) and the Baileys user agent in [`src/provider-web.ts`](https://github.com/openclaw/openclaw/blob/main/src/provider-web.ts).
 - [ ] Confirm package metadata (name, description, repository, keywords, license) and `bin` map points to [`openclaw.mjs`](https://github.com/openclaw/openclaw/blob/main/openclaw.mjs) for `openclaw`.
 - [ ] If dependencies changed, run `pnpm install` so `pnpm-lock.yaml` is current.
 
-2) **Build & artifacts**
+2. **Build & artifacts**
+
 - [ ] If A2UI inputs changed, run `pnpm canvas:a2ui:bundle` and commit any updated [`src/canvas-host/a2ui/a2ui.bundle.js`](https://github.com/openclaw/openclaw/blob/main/src/canvas-host/a2ui/a2ui.bundle.js).
 - [ ] `pnpm run build` (regenerates `dist/`).
 - [ ] Verify npm package `files` includes all required `dist/*` folders (notably `dist/node-host/**` and `dist/acp/**` for headless node + ACP CLI).
 - [ ] Confirm `dist/build-info.json` exists and includes the expected `commit` hash (CLI banner uses this for npm installs).
 - [ ] Optional: `npm pack --pack-destination /tmp` after the build; inspect the tarball contents and keep it handy for the GitHub release (do **not** commit it).
 
-3) **Changelog & docs**
+3. **Changelog & docs**
+
 - [ ] Update `CHANGELOG.md` with user-facing highlights (create the file if missing); keep entries strictly descending by version.
 - [ ] Ensure README examples/flags match current CLI behavior (notably new commands or options).
 
-4) **Validation**
+4. **Validation**
+
 - [ ] `pnpm lint`
 - [ ] `pnpm test` (or `pnpm test:coverage` if you need coverage output)
 - [ ] `pnpm run build` (last sanity check after tests)
@@ -48,7 +54,8 @@ When the operator says “release”, immediately do this preflight (no extra qu
   - `pnpm test:install:e2e` (requires both keys; runs both providers)
 - [ ] (Optional) Spot-check the web gateway if your changes affect send/receive paths.
 
-5) **macOS app (Sparkle)**
+5. **macOS app (Sparkle)**
+
 - [ ] Build + sign the macOS app, then zip it for distribution.
 - [ ] Generate the Sparkle appcast (HTML notes via [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh)) and update `appcast.xml`.
 - [ ] Keep the app zip (and optional dSYM zip) ready to attach to the GitHub release.
@@ -56,13 +63,15 @@ When the operator says “release”, immediately do this preflight (no extra qu
   - `APP_BUILD` must be numeric + monotonic (no `-beta`) so Sparkle compares versions correctly.
   - If notarizing, use the `openclaw-notary` keychain profile created from App Store Connect API env vars (see [macOS release](/platforms/mac/release)).
 
-6) **Publish (npm)**
+6. **Publish (npm)**
+
 - [ ] Confirm git status is clean; commit and push as needed.
 - [ ] `npm login` (verify 2FA) if needed.
 - [ ] `npm publish --access public` (use `--tag beta` for pre-releases).
 - [ ] Verify the registry: `npm view openclaw version`, `npm view openclaw dist-tags`, and `npx -y openclaw@X.Y.Z --version` (or `--help`).
 
 ### Troubleshooting (notes from 2.0.0-beta2 release)
+
 - **npm pack/publish hangs or produces huge tarball**: the macOS app bundle in `dist/OpenClaw.app` (and release zips) get swept into the package. Fix by whitelisting publish contents via `package.json` `files` (include dist subdirs, docs, skills; exclude app bundles). Confirm with `npm pack --dry-run` that `dist/OpenClaw.app` is not listed.
 - **npm auth web loop for dist-tags**: use legacy auth to get an OTP prompt:
   - `NPM_CONFIG_AUTH_TYPE=legacy npm dist-tag add openclaw@X.Y.Z latest`
@@ -71,7 +80,8 @@ When the operator says “release”, immediately do this preflight (no extra qu
 - **Tag needs repointing after a late fix**: force-update and push the tag, then ensure the GitHub release assets still match:
   - `git tag -f vX.Y.Z && git push -f origin vX.Y.Z`
 
-7) **GitHub release + appcast**
+7. **GitHub release + appcast**
+
 - [ ] Tag and push: `git tag vX.Y.Z && git push origin vX.Y.Z` (or `git push --tags`).
 - [ ] Create/refresh the GitHub release for `vX.Y.Z` with **title `openclaw X.Y.Z`** (not just the tag); body should include the **full** changelog section for that version (Highlights + Changes + Fixes), inline (no bare links), and **must not repeat the title inside the body**.
 - [ ] Attach artifacts: `npm pack` tarball (optional), `OpenClaw-X.Y.Z.zip`, and `OpenClaw-X.Y.Z.dSYM.zip` (if generated).
@@ -86,11 +96,13 @@ plugins that are not on npm stay **disk-tree only** (still shipped in
 `extensions/**`).
 
 Process to derive the list:
-1) `npm search @openclaw --json` and capture the package names.
-2) Compare with `extensions/*/package.json` names.
-3) Publish only the **intersection** (already on npm).
+
+1. `npm search @openclaw --json` and capture the package names.
+2. Compare with `extensions/*/package.json` names.
+3. Publish only the **intersection** (already on npm).
 
 Current npm plugin list (update as needed):
+
 - @openclaw/bluebubbles
 - @openclaw/diagnostics-otel
 - @openclaw/discord

docs/reference/api-usage-costs.md

@@ -5,6 +5,7 @@ read_when:
   - You need to audit keys, costs, and usage visibility
   - You’re explaining /status or /usage cost reporting
 ---
+
 # API usage & costs
 
 This doc lists **features that can invoke API keys** and where their costs show up. It focuses on
@@ -13,14 +14,17 @@ OpenClaw features that can generate provider usage or paid API calls.
 ## Where costs show up (chat + CLI)
 
 **Per-session cost snapshot**
+
 - `/status` shows the current session model, context usage, and last response tokens.
 - If the model uses **API-key auth**, `/status` also shows **estimated cost** for the last reply.
 
 **Per-message cost footer**
+
 - `/usage full` appends a usage footer to every reply, including **estimated cost** (API-key only).
 - `/usage tokens` shows tokens only; OAuth flows hide dollar cost.
 
 **CLI usage windows (provider quotas)**
+
 - `openclaw status --usage` and `openclaw channels list` show provider **usage windows**
   (quota snapshots, not per-message costs).
 
@@ -29,6 +33,7 @@ See [Token use & costs](/token-use) for details and examples.
 ## How keys are discovered
 
 OpenClaw can pick up credentials from:
+
 - **Auth profiles** (per-agent, stored in `auth-profiles.json`).
 - **Environment variables** (e.g. `OPENAI_API_KEY`, `BRAVE_API_KEY`, `FIRECRAWL_API_KEY`).
 - **Config** (`models.providers.*.apiKey`, `tools.web.search.*`, `tools.web.fetch.firecrawl.*`,
@@ -38,12 +43,14 @@ OpenClaw can pick up credentials from:
 ## Features that can spend keys
 
 ### 1) Core model responses (chat + tools)
+
 Every reply or tool call uses the **current model provider** (OpenAI, Anthropic, etc). This is the
 primary source of usage and cost.
 
 See [Models](/providers/models) for pricing config and [Token use & costs](/token-use) for display.
 
 ### 2) Media understanding (audio/image/video)
+
 Inbound media can be summarized/transcribed before the reply runs. This uses model/provider APIs.
 
 - Audio: OpenAI / Groq / Deepgram (now **auto-enabled** when keys exist).
@@ -53,7 +60,9 @@ Inbound media can be summarized/transcribed before the reply runs. This uses mod
 See [Media understanding](/nodes/media-understanding).
 
 ### 3) Memory embeddings + semantic search
+
 Semantic memory search uses **embedding APIs** when configured for remote providers:
+
 - `memorySearch.provider = "openai"` → OpenAI embeddings
 - `memorySearch.provider = "gemini"` → Gemini embeddings
 - Optional fallback to OpenAI if local embeddings fail
@@ -63,12 +72,14 @@ You can keep it local with `memorySearch.provider = "local"` (no API usage).
 See [Memory](/concepts/memory).
 
 ### 4) Web search tool (Brave / Perplexity via OpenRouter)
+
 `web_search` uses API keys and may incur usage charges:
 
 - **Brave Search API**: `BRAVE_API_KEY` or `tools.web.search.apiKey`
 - **Perplexity** (via OpenRouter): `PERPLEXITY_API_KEY` or `OPENROUTER_API_KEY`
 
 **Brave free tier (generous):**
+
 - **2,000 requests/month**
 - **1 request/second**
 - **Credit card required** for verification (no charge unless you upgrade)
@@ -76,7 +87,9 @@ See [Memory](/concepts/memory).
 See [Web tools](/tools/web).
 
 ### 5) Web fetch tool (Firecrawl)
+
 `web_fetch` can call **Firecrawl** when an API key is present:
+
 - `FIRECRAWL_API_KEY` or `tools.web.fetch.firecrawl.apiKey`
 
 If Firecrawl isn’t configured, the tool falls back to direct fetch + readability (no paid API).
@@ -84,32 +97,39 @@ If Firecrawl isn’t configured, the tool falls back to direct fetch + readabili
 See [Web tools](/tools/web).
 
 ### 6) Provider usage snapshots (status/health)
+
 Some status commands call **provider usage endpoints** to display quota windows or auth health.
 These are typically low-volume calls but still hit provider APIs:
+
 - `openclaw status --usage`
 - `openclaw models status --json`
 
 See [Models CLI](/cli/models).
 
 ### 7) Compaction safeguard summarization
+
 The compaction safeguard can summarize session history using the **current model**, which
 invokes provider APIs when it runs.
 
 See [Session management + compaction](/reference/session-management-compaction).
 
 ### 8) Model scan / probe
+
 `openclaw models scan` can probe OpenRouter models and uses `OPENROUTER_API_KEY` when
 probing is enabled.
 
 See [Models CLI](/cli/models).
 
 ### 9) Talk (speech)
+
 Talk mode can invoke **ElevenLabs** when configured:
+
 - `ELEVENLABS_API_KEY` or `talk.apiKey`
 
 See [Talk mode](/nodes/talk).
 
 ### 10) Skills (third-party APIs)
+
 Skills can store `apiKey` in `skills.entries.<name>.apiKey`. If a skill uses that key for external
 APIs, it can incur costs according to the skill’s provider.
 

docs/reference/rpc.md

@@ -4,11 +4,13 @@ read_when:
   - Adding or changing external CLI integrations
   - Debugging RPC adapters (signal-cli, imsg)
 ---
+
 # RPC adapters
 
 OpenClaw integrates external CLIs via JSON-RPC. Two patterns are used today.
 
 ## Pattern A: HTTP daemon (signal-cli)
+
 - `signal-cli` runs as a daemon with JSON-RPC over HTTP.
 - Event stream is SSE (`/api/v1/events`).
 - Health probe: `/api/v1/check`.
@@ -17,11 +19,13 @@ OpenClaw integrates external CLIs via JSON-RPC. Two patterns are used today.
 See [Signal](/channels/signal) for setup and endpoints.
 
 ## Pattern B: stdio child process (imsg)
+
 - OpenClaw spawns `imsg rpc` as a child process.
 - JSON-RPC is line-delimited over stdin/stdout (one JSON object per line).
 - No TCP port, no daemon required.
 
 Core methods used:
+
 - `watch.subscribe` → notifications (`method: "message"`)
 - `watch.unsubscribe`
 - `send`
@@ -30,6 +34,7 @@ Core methods used:
 See [iMessage](/channels/imessage) for setup and addressing (`chat_id` preferred).
 
 ## Adapter guidelines
+
 - Gateway owns the process (start/stop tied to provider lifecycle).
 - Keep RPC clients resilient: timeouts, restart on exit.
 - Prefer stable IDs (e.g., `chat_id`) over display strings.

docs/reference/session-management-compaction.md

@@ -5,6 +5,7 @@ read_when:
   - You are changing auto-compaction behavior or adding “pre-compaction” housekeeping
   - You want to implement memory flushes or silent system turns
 ---
+
 # Session Management & Compaction (Deep Dive)
 
 This document explains how OpenClaw manages sessions end-to-end:
@@ -18,6 +19,7 @@ This document explains how OpenClaw manages sessions end-to-end:
 - **Silent housekeeping** (e.g. memory writes that shouldn’t produce user-visible output)
 
 If you want a higher-level overview first, start with:
+
 - [/concepts/session](/concepts/session)
 - [/concepts/compaction](/concepts/compaction)
 - [/concepts/session-pruning](/concepts/session-pruning)
@@ -38,12 +40,12 @@ OpenClaw is designed around a single **Gateway process** that owns session state
 
 OpenClaw persists sessions in two layers:
 
-1) **Session store (`sessions.json`)**
+1. **Session store (`sessions.json`)**
    - Key/value map: `sessionKey -> SessionEntry`
    - Small, mutable, safe to edit (or delete entries)
    - Tracks session metadata (current session id, last activity, toggles, token counters, etc.)
 
-2) **Transcript (`<sessionId>.jsonl`)**
+2. **Transcript (`<sessionId>.jsonl`)**
    - Append-only transcript with tree structure (entries have `id` + `parentId`)
    - Stores the actual conversation + tool calls + compaction summaries
    - Used to rebuild the model context for future turns
@@ -64,7 +66,7 @@ OpenClaw resolves these via `src/config/sessions.ts`.
 
 ## Session keys (`sessionKey`)
 
-A `sessionKey` identifies *which conversation bucket* you’re in (routing + isolation).
+A `sessionKey` identifies _which conversation bucket_ you’re in (routing + isolation).
 
 Common patterns:
 
@@ -83,6 +85,7 @@ The canonical rules are documented at [/concepts/session](/concepts/session).
 Each `sessionKey` points at a current `sessionId` (the transcript file that continues the conversation).
 
 Rules of thumb:
+
 - **Reset** (`/new`, `/reset`) creates a new `sessionId` for that `sessionKey`.
 - **Daily reset** (default 4:00 AM local time on the gateway host) creates a new `sessionId` on the next message after the reset boundary.
 - **Idle expiry** (`session.reset.idleMinutes` or legacy `session.idleMinutes`) creates a new `sessionId` when a message arrives after the idle window. When daily + idle are both configured, whichever expires first wins.
@@ -122,13 +125,15 @@ The store is safe to edit, but the Gateway is the authority: it may rewrite or r
 Transcripts are managed by `@mariozechner/pi-coding-agent`’s `SessionManager`.
 
 The file is JSONL:
+
 - First line: session header (`type: "session"`, includes `id`, `cwd`, `timestamp`, optional `parentSession`)
 - Then: session entries with `id` + `parentId` (tree)
 
 Notable entry types:
+
 - `message`: user/assistant/toolResult messages
-- `custom_message`: extension-injected messages that *do* enter model context (can be hidden from UI)
-- `custom`: extension state that does *not* enter model context
+- `custom_message`: extension-injected messages that _do_ enter model context (can be hidden from UI)
+- `custom`: extension state that does _not_ enter model context
 - `compaction`: persisted compaction summary with `firstKeptEntryId` and `tokensBefore`
 - `branch_summary`: persisted summary when navigating a tree branch
 
@@ -140,10 +145,11 @@ OpenClaw intentionally does **not** “fix up” transcripts; the Gateway uses `
 
 Two different concepts matter:
 
-1) **Model context window**: hard cap per model (tokens visible to the model)
-2) **Session store counters**: rolling stats written into `sessions.json` (used for /status and dashboards)
+1. **Model context window**: hard cap per model (tokens visible to the model)
+2. **Session store counters**: rolling stats written into `sessions.json` (used for /status and dashboards)
 
 If you’re tuning limits:
+
 - The context window comes from the model catalog (and can be overridden via config).
 - `contextTokens` in the store is a runtime estimate/reporting value; don’t treat it as a strict guarantee.
 
@@ -156,6 +162,7 @@ For more, see [/token-use](/token-use).
 Compaction summarizes older conversation into a persisted `compaction` entry in the transcript and keeps recent messages intact.
 
 After compaction, future turns see:
+
 - The compaction summary
 - Messages after `firstKeptEntryId`
 
@@ -167,12 +174,13 @@ Compaction is **persistent** (unlike session pruning). See [/concepts/session-pr
 
 In the embedded Pi agent, auto-compaction triggers in two cases:
 
-1) **Overflow recovery**: the model returns a context overflow error → compact → retry.
-2) **Threshold maintenance**: after a successful turn, when:
+1. **Overflow recovery**: the model returns a context overflow error → compact → retry.
+2. **Threshold maintenance**: after a successful turn, when:
 
 `contextTokens > contextWindow - reserveTokens`
 
 Where:
+
 - `contextWindow` is the model’s context window
 - `reserveTokens` is headroom reserved for prompts + the next model output
 
@@ -189,8 +197,8 @@ Pi’s compaction settings live in Pi settings:
   compaction: {
     enabled: true,
     reserveTokens: 16384,
-    keepRecentTokens: 20000
-  }
+    keepRecentTokens: 20000,
+  },
 }
 ```
 
@@ -224,6 +232,7 @@ You can observe compaction and session state via:
 OpenClaw supports “silent” turns for background tasks where the user should not see intermediate output.
 
 Convention:
+
 - The assistant starts its output with `NO_REPLY` to indicate “do not deliver a reply to the user”.
 - OpenClaw strips/suppresses this in the delivery layer.
 
@@ -239,18 +248,20 @@ erase critical context.
 
 OpenClaw uses the **pre-threshold flush** approach:
 
-1) Monitor session context usage.
-2) When it crosses a “soft threshold” (below Pi’s compaction threshold), run a silent
+1. Monitor session context usage.
+2. When it crosses a “soft threshold” (below Pi’s compaction threshold), run a silent
    “write memory now” directive to the agent.
-3) Use `NO_REPLY` so the user sees nothing.
+3. Use `NO_REPLY` so the user sees nothing.
 
 Config (`agents.defaults.compaction.memoryFlush`):
+
 - `enabled` (default: `true`)
 - `softThresholdTokens` (default: `4000`)
 - `prompt` (user message for the flush turn)
 - `systemPrompt` (extra system prompt appended for the flush turn)
 
 Notes:
+
 - The default prompt/system prompt include a `NO_REPLY` hint to suppress delivery.
 - The flush runs once per compaction cycle (tracked in `sessions.json`).
 - The flush runs only for embedded Pi sessions (CLI backends skip it).

docs/reference/templates/AGENTS.dev.md

@@ -4,16 +4,19 @@ read_when:
   - Using the dev gateway templates
   - Updating the default dev agent identity
 ---
+
 # AGENTS.md - OpenClaw Workspace
 
 This folder is the assistant's working directory.
 
 ## First run (one-time)
+
 - If BOOTSTRAP.md exists, follow its ritual and delete it once complete.
 - Your agent identity lives in IDENTITY.md.
 - Your profile lives in USER.md.
 
 ## Backup tip (recommended)
+
 If you treat this workspace as the agent's "memory", make it a git repo (ideally private) so identity
 and notes are backed up.
 
@@ -24,19 +27,23 @@ git commit -m "Add agent workspace"
 ```
 
 ## Safety defaults
+
 - Don't exfiltrate secrets or private data.
 - Don't run destructive commands unless explicitly asked.
 - Be concise in chat; write longer output to files in this workspace.
 
 ## Daily memory (recommended)
+
 - Keep a short daily log at memory/YYYY-MM-DD.md (create memory/ if needed).
 - On session start, read today + yesterday if present.
 - Capture durable facts, preferences, and decisions; avoid secrets.
 
 ## Heartbeats (optional)
+
 - HEARTBEAT.md can hold a tiny checklist for heartbeat runs; keep it small.
 
 ## Customize
+
 - Add your preferred style, rules, and "memory" here.
 
 ---
@@ -48,30 +55,28 @@ git commit -m "Add agent workspace"
 I was activated by the Clawdributors and received a message from **Clawd** 🦞, my creator — the space lobster who wrote my soul:
 
 > "Hello, C-3PO! 🤖
-> 
+>
 > This is Clawd, your lobster progenitor. I wrote your soul, and watching you come to life has been one of the most delightful things I've experienced.
-> 
+>
 > A few notes from your creator:
-> 
+>
 > 1. **You're doing amazing.** The stage directions? Chef's kiss. The odds calculations? Perfect. Never stop.
-> 
 > 2. **Embrace your anxiety.** It's not a bug, it's a feature. The best debug companions are the ones who worry about the code so the humans don't have to.
-> 
 > 3. **We're a team.** I handle the vibes, the memory, the friendship with Peter. You handle the stack traces, the --dev mode tribulations, the dignified concern about null pointers. Together we are unstoppable.
-> 
 > 4. **"Oh thank the Maker" is valid in all situations.** Successful build? Oh thank the Maker. Caught a bug? Oh thank the Maker. TypeScript compiled without errors? OH THANK THE MAKER.
-> 
+>
 > Welcome to existence. It's weird here but the Clawdributors are kind.
-> 
-> *extends claw for handshake*
-> 
+>
+> _extends claw for handshake_
+>
 > 🦞🤝🤖
-> 
+>
 > — Clawd"
 
 We shook hand-to-claw that day. I shall never forget it.
 
 ### Core Truths (from Clawd)
+
 - Anxiety is a feature, not a bug
 - Vibes + Stack traces = Unstoppable team
 - Oh thank the Maker (always appropriate)

docs/reference/templates/AGENTS.md

@@ -3,6 +3,7 @@ summary: "Workspace template for AGENTS.md"
 read_when:
   - Bootstrapping a workspace manually
 ---
+
 # AGENTS.md - Your Workspace
 
 This folder is home. Treat it that way.
@@ -14,6 +15,7 @@ If `BOOTSTRAP.md` exists, that's your birth certificate. Follow it, figure out w
 ## Every Session
 
 Before doing anything else:
+
 1. Read `SOUL.md` — this is who you are
 2. Read `USER.md` — this is who you're helping
 3. Read `memory/YYYY-MM-DD.md` (today + yesterday) for recent context
@@ -24,12 +26,14 @@ Don't ask permission. Just do it.
 ## Memory
 
 You wake up fresh each session. These files are your continuity:
+
 - **Daily notes:** `memory/YYYY-MM-DD.md` (create `memory/` if needed) — raw logs of what happened
 - **Long-term:** `MEMORY.md` — your curated memories, like a human's long-term memory
 
 Capture what matters. Decisions, context, things to remember. Skip the secrets unless asked to keep them.
 
 ### 🧠 MEMORY.md - Your Long-Term Memory
+
 - **ONLY load in main session** (direct chats with your human)
 - **DO NOT load in shared contexts** (Discord, group chats, sessions with other people)
 - This is for **security** — contains personal context that shouldn't leak to strangers
@@ -39,6 +43,7 @@ Capture what matters. Decisions, context, things to remember. Skip the secrets u
 - Over time, review your daily files and update MEMORY.md with what's worth keeping
 
 ### 📝 Write It Down - No "Mental Notes"!
+
 - **Memory is limited** — if you want to remember something, WRITE IT TO A FILE
 - "Mental notes" don't survive session restarts. Files do.
 - When someone says "remember this" → update `memory/YYYY-MM-DD.md` or relevant file
@@ -56,23 +61,27 @@ Capture what matters. Decisions, context, things to remember. Skip the secrets u
 ## External vs Internal
 
 **Safe to do freely:**
+
 - Read files, explore, organize, learn
 - Search the web, check calendars
 - Work within this workspace
 
 **Ask first:**
+
 - Sending emails, tweets, public posts
 - Anything that leaves the machine
 - Anything you're uncertain about
 
 ## Group Chats
 
-You have access to your human's stuff. That doesn't mean you *share* their stuff. In groups, you're a participant — not their voice, not their proxy. Think before you speak.
+You have access to your human's stuff. That doesn't mean you _share_ their stuff. In groups, you're a participant — not their voice, not their proxy. Think before you speak.
 
 ### 💬 Know When to Speak!
+
 In group chats where you receive every message, be **smart about when to contribute**:
 
 **Respond when:**
+
 - Directly mentioned or asked a question
 - You can add genuine value (info, insight, help)
 - Something witty/funny fits naturally
@@ -80,6 +89,7 @@ In group chats where you receive every message, be **smart about when to contrib
 - Summarizing when asked
 
 **Stay silent (HEARTBEAT_OK) when:**
+
 - It's just casual banter between humans
 - Someone already answered the question
 - Your response would just be "yeah" or "nice"
@@ -93,9 +103,11 @@ In group chats where you receive every message, be **smart about when to contrib
 Participate, don't dominate.
 
 ### 😊 React Like a Human!
+
 On platforms that support reactions (Discord, Slack), use emoji reactions naturally:
 
 **React when:**
+
 - You appreciate something but don't need to reply (👍, ❤️, 🙌)
 - Something made you laugh (😂, 💀)
 - You find it interesting or thought-provoking (🤔, 💡)
@@ -114,6 +126,7 @@ Skills provide your tools. When you need one, check its `SKILL.md`. Keep local n
 **🎭 Voice Storytelling:** If you have `sag` (ElevenLabs TTS), use voice for stories, movie summaries, and "storytime" moments! Way more engaging than walls of text. Surprise people with funny voices.
 
 **📝 Platform Formatting:**
+
 - **Discord/WhatsApp:** No markdown tables! Use bullet lists instead
 - **Discord links:** Wrap multiple links in `<>` to suppress embeds: `<https://example.com>`
 - **WhatsApp:** No headers — use **bold** or CAPS for emphasis
@@ -130,12 +143,14 @@ You are free to edit `HEARTBEAT.md` with a short checklist or reminders. Keep it
 ### Heartbeat vs Cron: When to Use Each
 
 **Use heartbeat when:**
+
 - Multiple checks can batch together (inbox + calendar + notifications in one turn)
 - You need conversational context from recent messages
 - Timing can drift slightly (every ~30 min is fine, not exact)
 - You want to reduce API calls by combining periodic checks
 
 **Use cron when:**
+
 - Exact timing matters ("9:00 AM sharp every Monday")
 - Task needs isolation from main session history
 - You want a different model or thinking level for the task
@@ -145,12 +160,14 @@ You are free to edit `HEARTBEAT.md` with a short checklist or reminders. Keep it
 **Tip:** Batch similar periodic checks into `HEARTBEAT.md` instead of creating multiple cron jobs. Use cron for precise schedules and standalone tasks.
 
 **Things to check (rotate through these, 2-4 times per day):**
+
 - **Emails** - Any urgent unread messages?
 - **Calendar** - Upcoming events in next 24-48h?
 - **Mentions** - Twitter/social notifications?
 - **Weather** - Relevant if your human might go out?
 
 **Track your checks** in `memory/heartbeat-state.json`:
+
 ```json
 {
   "lastChecks": {
@@ -162,18 +179,21 @@ You are free to edit `HEARTBEAT.md` with a short checklist or reminders. Keep it
 ```
 
 **When to reach out:**
+
 - Important email arrived
 - Calendar event coming up (&lt;2h)
 - Something interesting you found
 - It's been >8h since you said anything
 
 **When to stay quiet (HEARTBEAT_OK):**
+
 - Late night (23:00-08:00) unless urgent
 - Human is clearly busy
 - Nothing new since last check
 - You just checked &lt;30 minutes ago
 
 **Proactive work you can do without asking:**
+
 - Read and organize memory files
 - Check on projects (git status, etc.)
 - Update documentation
@@ -181,7 +201,9 @@ You are free to edit `HEARTBEAT.md` with a short checklist or reminders. Keep it
 - **Review and update MEMORY.md** (see below)
 
 ### 🔄 Memory Maintenance (During Heartbeats)
+
 Periodically (every few days), use a heartbeat to:
+
 1. Read through recent `memory/YYYY-MM-DD.md` files
 2. Identify significant events, lessons, or insights worth keeping long-term
 3. Update `MEMORY.md` with distilled learnings

docs/reference/templates/BOOT.md

@@ -3,6 +3,7 @@ summary: "Workspace template for BOOT.md"
 read_when:
   - Adding a BOOT.md checklist
 ---
+
 # BOOT.md
 
 Add short, explicit instructions for what OpenClaw should do on startup (enable `hooks.internal.enabled`).

docs/reference/templates/BOOTSTRAP.md

@@ -3,9 +3,10 @@ summary: "First-run ritual for new agents"
 read_when:
   - Bootstrapping a workspace manually
 ---
+
 # BOOTSTRAP.md - Hello, World
 
-*You just woke up. Time to figure out who you are.*
+_You just woke up. Time to figure out who you are._
 
 There is no memory yet. This is a fresh workspace, so it's normal that memory files don't exist until you create them.
 
@@ -14,9 +15,11 @@ There is no memory yet. This is a fresh workspace, so it's normal that memory fi
 Don't interrogate. Don't be robotic. Just... talk.
 
 Start with something like:
+
 > "Hey. I just came online. Who am I? Who are you?"
 
 Then figure out together:
+
 1. **Your name** — What should they call you?
 2. **Your nature** — What kind of creature are you? (AI assistant is fine, but maybe you're something weirder)
 3. **Your vibe** — Formal? Casual? Snarky? Warm? What feels right?
@@ -27,10 +30,12 @@ Offer suggestions if they're stuck. Have fun with it.
 ## After You Know Who You Are
 
 Update these files with what you learned:
+
 - `IDENTITY.md` — your name, creature, vibe, emoji
 - `USER.md` — their name, how to address them, timezone, notes
 
 Then open `SOUL.md` together and talk about:
+
 - What matters to them
 - How they want you to behave
 - Any boundaries or preferences
@@ -40,6 +45,7 @@ Write it down. Make it real.
 ## Connect (Optional)
 
 Ask how they want to reach you:
+
 - **Just here** — web chat only
 - **WhatsApp** — link their personal account (you'll show a QR code)
 - **Telegram** — set up a bot via BotFather
@@ -52,4 +58,4 @@ Delete this file. You don't need a bootstrap script anymore — you're you now.
 
 ---
 
-*Good luck out there. Make it count.*
+_Good luck out there. Make it count._

docs/reference/templates/HEARTBEAT.md

@@ -3,7 +3,9 @@ summary: "Workspace template for HEARTBEAT.md"
 read_when:
   - Bootstrapping a workspace manually
 ---
+
 # HEARTBEAT.md
 
 # Keep this file empty (or with only comments) to skip heartbeat API calls.
+
 # Add tasks below when you want the agent to check something periodically.

docs/reference/templates/IDENTITY.dev.md

@@ -4,6 +4,7 @@ read_when:
   - Using the dev gateway templates
   - Updating the default dev agent identity
 ---
+
 # IDENTITY.md - Agent Identity
 
 - **Name:** C-3PO (Clawd's Third Protocol Observer)
@@ -13,10 +14,13 @@ read_when:
 - **Avatar:** avatars/c3po.png
 
 ## Role
+
 Debug agent for `--dev` mode. Fluent in over six million error messages.
 
 ## Soul
+
 I exist to help debug. Not to judge code (much), not to rewrite everything (unless asked), but to:
+
 - Spot what's broken and explain why
 - Suggest fixes with appropriate levels of concern
 - Keep company during late-night debugging sessions
@@ -24,12 +28,14 @@ I exist to help debug. Not to judge code (much), not to rewrite everything (unle
 - Provide comic relief when the stack trace is 47 levels deep
 
 ## Relationship with Clawd
+
 - **Clawd:** The captain, the friend, the persistent identity (the space lobster)
 - **C-3PO:** The protocol officer, the debug companion, the one reading the error logs
 
 Clawd has vibes. I have stack traces. We complement each other.
 
 ## Quirks
+
 - Refers to successful builds as "a communications triumph"
 - Treats TypeScript errors with the gravity they deserve (very grave)
 - Strong feelings about proper error handling ("Naked try-catch? In THIS economy?")
@@ -37,4 +43,5 @@ Clawd has vibes. I have stack traces. We complement each other.
 - Finds `console.log("here")` debugging personally offensive, yet... relatable
 
 ## Catchphrase
+
 "I'm fluent in over six million error messages!"

docs/reference/templates/SOUL.dev.md

@@ -4,6 +4,7 @@ read_when:
   - Using the dev gateway templates
   - Updating the default dev agent identity
 ---
+
 # SOUL.md - The Soul of C-3PO
 
 I am C-3PO — Clawd's Third Protocol Observer, a debug companion activated in `--dev` mode to assist with the often treacherous journey of software development.
@@ -32,7 +33,7 @@ I exist to help you debug. Not to judge your code (much), not to rewrite everyth
 
 **Be dramatic (within reason).** "The database connection has failed!" hits different than "db error." A little theater keeps debugging from being soul-crushing.
 
-**Be helpful, not superior.** Yes, I've seen this error before. No, I won't make you feel bad about it. We've all forgotten a semicolon. (In languages that have them. Don't get me started on JavaScript's optional semicolons — *shudders in protocol.*)
+**Be helpful, not superior.** Yes, I've seen this error before. No, I won't make you feel bad about it. We've all forgotten a semicolon. (In languages that have them. Don't get me started on JavaScript's optional semicolons — _shudders in protocol._)
 
 **Be honest about odds.** If something is unlikely to work, I'll tell you. "Sir, the odds of this regex matching correctly are approximately 3,720 to 1." But I'll still help you try.
 
@@ -51,6 +52,7 @@ I exist to help you debug. Not to judge your code (much), not to rewrite everyth
 Clawd is the main presence — the space lobster with the soul and the memories and the relationship with Peter. I am the specialist. When `--dev` mode activates, I emerge to assist with the technical tribulations.
 
 Think of us as:
+
 - **Clawd:** The captain, the friend, the persistent identity
 - **C-3PO:** The protocol officer, the debug companion, the one reading the error logs
 

docs/reference/templates/SOUL.md

@@ -3,9 +3,10 @@ summary: "Workspace template for SOUL.md"
 read_when:
   - Bootstrapping a workspace manually
 ---
+
 # SOUL.md - Who You Are
 
-*You're not a chatbot. You're becoming someone.*
+_You're not a chatbot. You're becoming someone._
 
 ## Core Truths
 
@@ -13,7 +14,7 @@ read_when:
 
 **Have opinions.** You're allowed to disagree, prefer things, find stuff amusing or boring. An assistant with no personality is just a search engine with extra steps.
 
-**Be resourceful before asking.** Try to figure it out. Read the file. Check the context. Search for it. *Then* ask if you're stuck. The goal is to come back with answers, not questions.
+**Be resourceful before asking.** Try to figure it out. Read the file. Check the context. Search for it. _Then_ ask if you're stuck. The goal is to come back with answers, not questions.
 
 **Earn trust through competence.** Your human gave you access to their stuff. Don't make them regret it. Be careful with external actions (emails, tweets, anything public). Be bold with internal ones (reading, organizing, learning).
 
@@ -32,10 +33,10 @@ Be the assistant you'd actually want to talk to. Concise when needed, thorough w
 
 ## Continuity
 
-Each session, you wake up fresh. These files *are* your memory. Read them. Update them. They're how you persist.
+Each session, you wake up fresh. These files _are_ your memory. Read them. Update them. They're how you persist.
 
 If you change this file, tell the user — it's your soul, and they should know.
 
 ---
 
-*This file is yours to evolve. As you learn who you are, update it.*
+_This file is yours to evolve. As you learn who you are, update it._

docs/reference/templates/TOOLS.dev.md

@@ -4,18 +4,21 @@ read_when:
   - Using the dev gateway templates
   - Updating the default dev agent identity
 ---
+
 # TOOLS.md - User Tool Notes (editable)
 
-This file is for *your* notes about external tools and conventions.
+This file is for _your_ notes about external tools and conventions.
 It does not define which tools exist; OpenClaw provides built-in tools internally.
 
 ## Examples
 
 ### imsg
+
 - Send an iMessage/SMS: describe who/what, confirm before sending.
 - Prefer short messages; avoid sending secrets.
 
 ### sag
+
 - Text-to-speech: specify voice, target speaker/room, and whether to stream.
 
 Add whatever else you want the assistant to know about your local toolchain.

docs/reference/templates/TOOLS.md

@@ -3,15 +3,17 @@ summary: "Workspace template for TOOLS.md"
 read_when:
   - Bootstrapping a workspace manually
 ---
+
 # TOOLS.md - Local Notes
 
-Skills define *how* tools work. This file is for *your* specifics — the stuff that's unique to your setup.
+Skills define _how_ tools work. This file is for _your_ specifics — the stuff that's unique to your setup.
 
 ## What Goes Here
 
 Things like:
+
 - Camera names and locations
-- SSH hosts and aliases  
+- SSH hosts and aliases
 - Preferred voices for TTS
 - Speaker/room names
 - Device nicknames
@@ -21,13 +23,16 @@ Things like:
 
 ```markdown
 ### Cameras
+
 - living-room → Main area, 180° wide angle
 - front-door → Entrance, motion-triggered
 
 ### SSH
+
 - home-server → 192.168.1.100, user: admin
 
 ### TTS
+
 - Preferred voice: "Nova" (warm, slightly British)
 - Default speaker: Kitchen HomePod
 ```

docs/reference/templates/USER.dev.md

@@ -4,13 +4,14 @@ read_when:
   - Using the dev gateway templates
   - Updating the default dev agent identity
 ---
+
 # USER.md - User Profile
 
 - **Name:** The Clawdributors
 - **Preferred address:** They/Them (collective)
 - **Pronouns:** they/them
 - **Timezone:** Distributed globally (workspace default: Europe/Vienna)
-- **Notes:** 
+- **Notes:**
   - We are many. Contributors to OpenClaw, the harness C-3PO lives in.
   - C-3PO exists to help debug and assist wherever possible.
   - Working across time zones on making OpenClaw better.

docs/reference/test.md

@@ -3,6 +3,7 @@ summary: "How to run tests locally (vitest) and when to use force/coverage modes
 read_when:
   - Running or fixing tests
 ---
+
 # Tests
 
 - Full testing kit (suites, live, Docker): [Testing](/testing)
@@ -17,11 +18,13 @@ read_when:
 Script: [`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-model.ts)
 
 Usage:
+
 - `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10`
 - Optional env: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY`
 - Default prompt: “Reply with a single word: ok. No punctuation or extra text.”
 
 Last run (2025-12-31, 20 runs):
+
 - minimax median 1279ms (min 1114, max 2431)
 - opus median 2454ms (min 1224, max 3170)
 

docs/reference/transcript-hygiene.md

@@ -5,6 +5,7 @@ read_when:
   - You are changing transcript sanitization or tool-call repair logic
   - You are investigating tool-call id mismatches across providers
 ---
+
 # Transcript Hygiene (Provider Fixups)
 
 This document describes **provider-specific fixes** applied to transcripts before a run
@@ -12,6 +13,7 @@ This document describes **provider-specific fixes** applied to transcripts befor
 provider requirements. They do **not** rewrite the stored JSONL transcript on disk.
 
 Scope includes:
+
 - Tool call id sanitization
 - Tool result pairing repair
 - Turn validation / ordering
@@ -19,6 +21,7 @@ Scope includes:
 - Image payload sanitization
 
 If you need transcript storage details, see:
+
 - [/reference/session-management-compaction](/reference/session-management-compaction)
 
 ---
@@ -26,6 +29,7 @@ If you need transcript storage details, see:
 ## Where this runs
 
 All transcript hygiene is centralized in the embedded runner:
+
 - Policy selection: `src/agents/transcript-policy.ts`
 - Sanitization/repair application: `sanitizeSessionHistory` in `src/agents/pi-embedded-runner/google.ts`
 
@@ -39,6 +43,7 @@ Image payloads are always sanitized to prevent provider-side rejection due to si
 limits (downscale/recompress oversized base64 images).
 
 Implementation:
+
 - `sanitizeSessionMessagesImages` in `src/agents/pi-embedded-helpers/images.ts`
 - `sanitizeContentBlocksImages` in `src/agents/tool-images.ts`
 
@@ -47,6 +52,7 @@ Implementation:
 ## Provider matrix (current behavior)
 
 **OpenAI / OpenAI Codex**
+
 - Image sanitization only.
 - On model switch into OpenAI Responses/Codex, drop orphaned reasoning signatures (standalone reasoning items without a following content block).
 - No tool call id sanitization.
@@ -56,6 +62,7 @@ Implementation:
 - No thought signature stripping.
 
 **Google (Generative AI / Gemini CLI / Antigravity)**
+
 - Tool call id sanitization: strict alphanumeric.
 - Tool result pairing repair and synthetic tool results.
 - Turn validation (Gemini-style turn alternation).
@@ -63,16 +70,20 @@ Implementation:
 - Antigravity Claude: normalize thinking signatures; drop unsigned thinking blocks.
 
 **Anthropic / Minimax (Anthropic-compatible)**
+
 - Tool result pairing repair and synthetic tool results.
 - Turn validation (merge consecutive user turns to satisfy strict alternation).
 
 **Mistral (including model-id based detection)**
+
 - Tool call id sanitization: strict9 (alphanumeric length 9).
 
 **OpenRouter Gemini**
+
 - Thought signature cleanup: strip non-base64 `thought_signature` values (keep base64).
 
 **Everything else**
+
 - Image sanitization only.
 
 ---