melvincarvalho · Oct 18, 2026 · Oct 18, 2026 · Oct 18, 2026 · Oct 18, 2026 · Oct 18, 2026
diff --git a/docs/architecture/brain-and-hands.md b/docs/architecture/brain-and-hands.md
@@ -10,8 +10,8 @@ keywords: [openclaw, agent loop, agent runtime, llm integration, tools, exec app
 
 # Agent Runtime and Tools
 
-:::note About the name
-Earlier versions of this page called the model the "Brain" and the tools the "Hands". That is this site's analogy, not an OpenClaw concept, and there is no `brain` or `hands` config key. OpenClaw's own terms are the **agent loop** (runtime), **models**, **tools**, **exec approvals**, the **sandbox**, and **nodes**. This page uses those terms.
+:::note
+"Brain and hands" was this site's old analogy for models and tools. There is no `brain` or `hands` config key; this page uses OpenClaw's own terms.
 :::
 
 In one sentence: the agent loop sends the assembled prompt to a model, the model answers with text and/or tool calls, OpenClaw runs the tools (subject to tool policy, approvals and the sandbox), and feeds the results back until the model gives a final reply.
@@ -35,9 +35,7 @@ Tool calls use the provider's native tool-use format. OpenClaw does not have its
 
 From the CLI, `openclaw agent --message "..."` runs one turn through the Gateway, and `openclaw chat` opens the local terminal UI.
 
-### Bootstrap context
-
-Large bootstrap files are truncated when injected: `agents.defaults.bootstrapMaxChars` (default 20000 per file) and `bootstrapTotalMaxChars` (default 60000). Related keys: `skipBootstrap` (do not create the files) and `skipOptionalBootstrapFiles`. For cheap scheduled turns, `agents.defaults.heartbeat.lightContext` and `isolatedSession` reduce what a heartbeat loads. See [Agent workspace](https://docs.openclaw.ai/concepts/agent-workspace).
+What goes into the prompt, and the bootstrap size limits, are on [Architecture Overview](/architecture/overview#what-goes-into-the-prompt).
 
 ---
 
@@ -223,10 +221,6 @@ Check what applies to a session with `openclaw sandbox explain`. See [Sandboxing
 With the defaults (`tools.exec.mode: "full"`, sandbox `off`), anyone who can message the agent can get commands run on your host. Before you connect channels, set `tools.exec.mode` to `ask` or `allowlist`, restrict who can DM the bot, and consider `sandbox.mode: "non-main"`. See [Security Hardening](/security/hardening).
 :::
 
-### Advisory note
-
-GHSA-9p3r-hh9g-5cmg (critical) was a TOCTOU race in the remote filesystem bridge `readFile`. It affected versions up to 2026.3.28 and was fixed in 2026.3.31; GitHub credits AntAISecurityLab. Stay on a current release; see [Known Vulnerabilities](/security/known-vulnerabilities).
-
 ---
 
 ## Nodes

diff --git a/docs/contributing/openclaw.md b/docs/contributing/openclaw.md
@@ -36,7 +36,7 @@ pnpm build
 pnpm dev
 ```
 
-Run focused tests for what you touched rather than the whole suite: `pnpm test <file> --maxWorkers=1`, plus `pnpm test:extension <name>` for a plugin. PR CI runs the full suite.
+CONTRIBUTING.md asks for `pnpm build && pnpm check && pnpm test` before review. For a plugin change, start with the fast lane, `pnpm test:extension <name>`. If you add or change tests, the repo's `AGENTS.md` asks the PR to state the wall time of `pnpm test <file> --maxWorkers=1`.
 
 ## Pull requests
 

diff --git a/docs/getting-started/core-concepts.md b/docs/getting-started/core-concepts.md
@@ -9,7 +9,7 @@ keywords: [openclaw, openclaw architecture, how openclaw works, openclaw gateway
 
 # Core Concepts
 
-Before going deeper, learn the handful of parts that make OpenClaw work. Upstream's own overview is [Architecture](https://docs.openclaw.ai/concepts/architecture).
+The handful of parts that make OpenClaw work, each with a link to its deep dive. Upstream's own overview is [Architecture](https://docs.openclaw.ai/concepts/architecture).
 
 ## The Gateway
 
@@ -97,7 +97,7 @@ The **heartbeat** makes OpenClaw proactive. It is a scheduled turn in the agent'
 
 - Configure it under `agents.defaults.heartbeat` (`every`, `activeHours`, `model`, `isolatedSession`, `lightContext`, `target`).
 - A short standing checklist lives in the heartbeat's monitor scratch (`openclaw cron scratch <jobId> --set "..."`).
-- Jobs on a fixed schedule ("daily at 9am", "every Monday") are **automations**: `openclaw automations create` (alias `openclaw cron`). They can run in an isolated session and deliver results to a channel.
+- Jobs on a fixed schedule ("daily at 9am", "every Monday") are **automations**: `openclaw cron add` (`openclaw automations create` is the same command). They can run in an isolated session and deliver results to a channel.
 
 `HEARTBEAT.md` is retired: the runtime no longer reads it, and `openclaw doctor --fix` migrates an old one. See [Heartbeat](/architecture/heartbeat) and the official [heartbeat docs](https://docs.openclaw.ai/gateway/heartbeat).
 
@@ -121,20 +121,7 @@ graph TD
 
 ## SOUL.md (persona)
 
-`SOUL.md` in the workspace defines *who* the agent is: name, personality, tone, rules and boundaries.
-
-```markdown title="~/.openclaw/workspace/SOUL.md"
-# Agent Identity
-
-You are Jarvis, a helpful personal assistant.
-
-## Rules
-- Always respond politely
-- Never make purchases without explicit approval
-- Summarize long emails instead of forwarding them in full
-```
-
-It is loaded into every session. Operating rules ("how to work") belong in `AGENTS.md`; persona ("who to be") in `SOUL.md`. Because the agent can write to its own workspace, these files are also an [attack surface](/security/hardening#soulmd-protection) for prompt injection. See the [SOUL.md Guide](/guides/soul-md).
+`SOUL.md` in the workspace defines *who* the agent is: personality, tone and boundaries. It is loaded into every session; the [Quick Start](/getting-started/quick-start#step-6-personalize-your-agent-optional) has a starter file. A rule written there ("never make purchases without approval") is an instruction the model usually follows, not an enforced control; approvals and tool policy enforce. Operating rules ("how to work") belong in `AGENTS.md`; persona ("who to be") in `SOUL.md`. Because the agent can write to its own workspace, these files are also an [attack surface](/security/hardening#soulmd-protection) for prompt injection. See the [SOUL.md Guide](/guides/soul-md).
 
 ## Skills
 

diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
@@ -98,7 +98,7 @@ If you write your own `docker run` or Compose file, get these right:
 - **Health checks:** the image's built-in `HEALTHCHECK` uses `/healthz`. `/readyz` is the deeper, channel-aware probe.
 - Use only `ghcr.io/openclaw/openclaw` or the Docker Hub mirror `openclaw/openclaw`.
 
-On upgrade, the container entrypoint runs `openclaw doctor --fix` against the mounted state before the Gateway starts. Podman, Nix, Kubernetes, Ansible and cloud recipes are listed on the [install index](https://docs.openclaw.ai/install); see also [Deployment Options](/guides/deployment-options).
+The container entrypoint runs `openclaw doctor --fix --non-interactive` against the mounted state each time the Gateway container starts, so an image upgrade migrates state before the Gateway runs. Podman, Nix, Kubernetes, Ansible and cloud recipes are listed on the [install index](https://docs.openclaw.ai/install); see also [Deployment Options](/guides/deployment-options).
 
 ## Method 5: From source (developers)
 
@@ -125,17 +125,9 @@ The installer script starts onboarding for you. Otherwise run:
 openclaw onboard --install-daemon
 ```
 
-Onboarding:
+Onboarding checks your model access with a real request, creates the workspace (`~/.openclaw/workspace`) and `~/.openclaw/openclaw.json` with a generated Gateway token, and with `--install-daemon` installs the Gateway as a service (LaunchAgent on macOS, systemd user service on Linux and WSL2, Scheduled Task on Windows). The [Quick Start](/getting-started/quick-start#step-2-onboard) walks through it. Without `--install-daemon`, install the service later with `openclaw gateway install`.
 
-1. **Sets up model access.** It detects a Claude Code or Codex login or an API key and verifies it with a real request, or walks you through provider setup.
-2. **Creates the workspace** at `~/.openclaw/workspace` and writes `~/.openclaw/openclaw.json`, including a generated Gateway token.
-3. **Installs the Gateway service** (with `--install-daemon`): a LaunchAgent on macOS, a systemd user service on Linux and WSL2, or a Scheduled Task on Windows.
-
-Channels can be added later with `openclaw channels add`. To change things afterwards, use `openclaw configure`. Onboarding reference: [Onboarding (CLI)](https://docs.openclaw.ai/start/wizard).
-
-:::tip
-Without `--install-daemon`, onboarding can leave the Gateway running in the foreground of that terminal. Install the background service any time with `openclaw gateway install`.
-:::
+Change settings afterwards with `openclaw configure`; add channels with `openclaw channels add`. Reference: [Onboarding (CLI)](https://docs.openclaw.ai/start/wizard).
 
 ## Verify installation
 

diff --git a/docs/getting-started/introduction.md b/docs/getting-started/introduction.md
@@ -26,7 +26,7 @@ This site is a community companion to the official docs at [docs.openclaw.ai](ht
 | What it can touch | Text in, text out | Shell, files, browser, APIs, paired devices |
 | Memory | Per-session, or vendor-held | Markdown files in your workspace (`~/.openclaw/workspace`) |
 | How you reach it | One web app | Control UI, terminal UI, desktop and mobile apps, 20+ chat channels |
-| Proactivity | Waits for you | Optional [heartbeat](/architecture/heartbeat) and scheduled automations |
+| Proactivity | Waits for you | A [heartbeat](/architecture/heartbeat) (on by default) and scheduled automations |
 | Models | One vendor | Any supported provider, or local models |
 
 "Runs locally" does not mean "nothing leaves your machine". Your prompts, memory snippets and tool output go to the model provider you configure, and memory search uses OpenAI embeddings by default. See [Privacy and compliance](/guides/privacy-compliance).
@@ -96,9 +96,7 @@ As of 2026-10-18, [openclaw/openclaw](https://github.com/openclaw/openclaw) has
 - **Not just a CLI.** It ships a full web Control UI (open it with `openclaw dashboard`) and desktop and mobile apps. Use the Control UI rather than a third-party web client: [WebClaw](/guides/webclaw) only speaks Gateway protocol v3, and current Gateways require v4 from operator and UI clients ([protocol versioning](https://docs.openclaw.ai/gateway/protocol/versioning)), so it cannot connect.
 - **Not a coding IDE.** It can write and edit code, but it is a general-purpose agent, not a replacement for your editor.
 - **Not free to run.** OpenClaw is free; model API calls are not. Local models cost nothing per token but need capable hardware.
-- **Not safe by default.** It runs with your user's permissions, shell commands run without approval by default, and the sandbox is off. Read the [Security Overview](/security/overview) before connecting it to anything important.
 - **Not a hosted service.** You run it yourself. Third parties sell managed hosting; see [Hosting Providers](/guides/hosting-providers).
-- **Not multi-tenant.** Upstream's trust model is one trusted operator per Gateway. Give mutually untrusted people separate Gateways.
 
 ---
 
@@ -114,16 +112,7 @@ OpenClaw gives a language model real access to your machine. Know these facts be
 | **Many advisories** | As of 2026-10-18 GitHub lists 722 security advisories for openclaw/openclaw (14 critical, 249 high). Stay on a current release. |
 | **Skills are code** | Malicious skills have been published to ClawHub. Review before installing. |
 
-### How to stay safe
-
-1. **Update often:** `openclaw update`.
-2. **Keep the Gateway on loopback** (`gateway.bind: "loopback"`, the default). For remote access use SSH tunnels or Tailscale, not a public port.
-3. **Keep token auth on** (`gateway.auth.mode: "token"`).
-4. **Turn on exec approvals:** `openclaw config set tools.exec.mode ask`.
-5. **Consider the sandbox** for anything that reads untrusted input: `agents.defaults.sandbox.mode: "non-main"` or `"all"` (needs Docker or another backend). Note that the global `--container` flag only runs the CLI inside an existing container; it is not a sandbox.
-6. **Audit your setup:** `openclaw security audit --deep`.
-
-See [Security Overview](/security/overview) and the [Hardening Guide](/security/hardening).
+Keep the Gateway on loopback, turn on approvals and run `openclaw security audit --deep`. The twelve-item list is the [secure-by-default checklist](/getting-started/choosing-your-setup#checklist); the reasoning is in [Security Hardening](/security/hardening).
 
 :::warning
 Do not run OpenClaw as root. Do not expose port 18789 to the internet. Do not install skills you have not read.
@@ -133,19 +122,7 @@ Do not run OpenClaw as root. Do not expose port 18789 to the internet. Do not in
 
 ## The cost question
 
-OpenClaw itself is free. Your bill comes from model tokens, and it depends almost entirely on which model you use and how much the agent runs unattended. Check your provider's current price list rather than trusting a table on a community site.
-
-The main levers, all real config keys:
-
-| Lever | How |
-|---|---|
-| Cheaper model for the heartbeat | `agents.defaults.heartbeat.model`, e.g. `anthropic/claude-haiku-5-5` |
-| Less frequent heartbeat | `agents.defaults.heartbeat.every: "1h"` (or `"0m"` to turn the recurring heartbeat off) |
-| Only during waking hours | `agents.defaults.heartbeat.activeHours: { start: "08:00", end: "22:00" }` |
-| Smaller heartbeat context | `agents.defaults.heartbeat.isolatedSession: true` and `lightContext: true` |
-| Local models | Ollama, LM Studio or vLLM; see [Local Models](/guides/local-models) |
-
-See [Cost Management](/guides/cost-management) and the official [heartbeat docs](https://docs.openclaw.ai/gateway/heartbeat).
+OpenClaw itself is free. Your bill comes from model tokens, and it depends almost entirely on which model you use and how much the agent runs unattended, including the heartbeat. As a rough scale (as of 2026-10-18, 600 requests a month), Haiku 5.5 costs about $2 a month and Opus 5.5 about $72; local models cost nothing per token. The worked numbers and configs are in [Choosing Your Setup](/getting-started/choosing-your-setup#models), the levers in [Cost Management](/guides/cost-management).
 
 ---
 
@@ -181,10 +158,6 @@ For **local models**, the GPU matters far more than the Gateway. See [Local Mode
 
 ## Next steps
 
-| Step | Link |
-|---|---|
-| Install OpenClaw | [Installation](/getting-started/installation) |
-| Get your first chat working | [Quick Start](/getting-started/quick-start) |
-| Understand the moving parts | [Core Concepts](/getting-started/core-concepts) |
-| Structured learning path | [First 7 Days](/guides/first-7-days) |
-| Lock down security | [Security Hardening](/security/hardening) |
+1. [Choosing Your Setup](/getting-started/choosing-your-setup): pick a model, a channel and a host.
+2. [Installation](/getting-started/installation), then the [Quick Start](/getting-started/quick-start).
+3. [Core Concepts](/getting-started/core-concepts), or the [First 7 Days](/guides/first-7-days) path.
diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md
@@ -13,11 +13,9 @@ keywords: [openclaw, openclaw getting started, openclaw tutorial, openclaw quick
 
 # Quick Start
 
-Get from zero to a working OpenClaw agent in about 5 minutes. The official version of this walkthrough is [Getting started](https://docs.openclaw.ai/start/getting-started).
+From zero to a working agent in about 5 minutes. The official version is [Getting started](https://docs.openclaw.ai/start/getting-started). Not sure which model, channel or host to pick? [Choosing Your Setup](/getting-started/choosing-your-setup) recommends one for each.
 
-Not sure which model, channel or host to pick? [Choosing Your Setup](/getting-started/choosing-your-setup) recommends one for each.
-
-**What you'll have at the end:** a Gateway running as a background service, the Control UI open in your browser, and an agent that can answer questions, read and write files, and run shell commands. Optionally, a chat app on your phone connected to it.
+**At the end you have** a Gateway running as a background service, the Control UI open in your browser, and an agent that can answer questions, read and write files, and run shell commands. Optionally, a chat app on your phone connected to it.
 
 **Prerequisites:**
 - Node.js 24.16+ or 26.1+ (26 recommended; 22, 23 and 25 are unsupported). Check with `node --version`. The installer script installs Node for you if needed.
@@ -107,7 +105,7 @@ openclaw tui
 openclaw agent --agent main --message "What files are in my home directory?"
 ```
 
-`openclaw chat` is a shortcut for `openclaw tui --local`: it runs the agent in-process instead of through the Gateway. To start it with a first message use `openclaw chat --message "..."`. A bare positional argument (`openclaw chat "hi"`) is read as a session target, not a message.
+`openclaw chat` is a shortcut for `openclaw tui --local`: it runs the agent in-process instead of through the Gateway. To start it with a first message use `openclaw chat --message "..."`. `openclaw chat "hi"` fails: a positional argument is a session target, not a message, and local mode rejects targets.
 
 ## Step 5: Try some real tasks
 
@@ -264,35 +262,8 @@ If a step fails, `openclaw triage` collects sanitized diagnostics and can hand t
 
 ## What's next?
 
-### Do these first
-
-| Goal | Guide |
-|---|---|
-| Learn everyday commands | [Basic Usage](/guides/basic-usage) |
-| Lock down security | [Security Hardening](/security/hardening) |
-| Understand the moving parts | [Core Concepts](/getting-started/core-concepts) |
-
-### First week
-
-| Goal | Guide |
-|---|---|
-| Structured learning path | [First 7 Days](/guides/first-7-days) |
-| Customize your agent's personality | [SOUL.md Guide](/guides/soul-md) |
-| Connect messaging channels | [Channels Guide](/guides/channels) |
-| Set up scheduled tasks | [Automation](/guides/automation) |
-
-### Going deeper
-
-| Goal | Guide |
-|---|---|
-| Choose the right model for each task | [Model Selection](/guides/model-selection) |
-| Run without API costs | [Local Models](/guides/local-models) |
-| Find community skills | [ClawHub](/guides/clawhub) |
-| Build your own skills | [Skill Development](/guides/skill-development) |
-| Run multi-agent workflows | [Multi-Agent](/guides/multi-agent) |
-| Keep costs down | [Cost Management](/guides/cost-management) |
-| Build integrations | [API & Webhooks](/guides/api-webhooks) |
-
-:::tip
-Ask questions in the official [OpenClaw Discord](https://discord.gg/clawd), or on [r/OpenClaw](https://reddit.com/r/OpenClaw).
-:::
+1. Lock it down before you connect channels other people can reach: [Security Hardening](/security/hardening), or the short [secure-by-default checklist](/getting-started/choosing-your-setup#checklist).
+2. Learn the everyday commands: [Basic Usage](/guides/basic-usage).
+3. Follow the [First 7 Days](/guides/first-7-days) path: persona, daily use, automations, skills, channels, multi-agent and production.
+
+Questions go to the official [OpenClaw Discord](https://discord.gg/clawd).