docs: CLI + gateway + plugin harness coverage for 48h changes

docs/cli/doctor.md

@@ -39,6 +39,7 @@ openclaw doctor --generate-gateway-token
 Notes:
 
 - Interactive prompts (like keychain/OAuth fixes) only run when stdin is a TTY and `--non-interactive` is **not** set. Headless runs (cron, Telegram, no terminal) will skip prompts.
+- Performance: non-interactive `doctor` runs skip eager plugin loading so headless health checks stay fast. Interactive sessions still fully load plugins when a check needs their contribution.
 - `--fix` (alias for `--repair`) writes a backup to `~/.openclaw/openclaw.json.bak` and drops unknown config keys, listing each removal.
 - State integrity checks now detect orphan transcript files in the sessions directory and can archive them as `.deleted.<timestamp>` to reclaim space safely.
 - Doctor also scans `~/.openclaw/cron/jobs.json` (or `cron.store`) for legacy cron job shapes and can rewrite them in place before the scheduler has to auto-normalize them at runtime.

docs/cli/gateway.md

@@ -134,7 +134,7 @@ Options:
 
 Notes:
 
-- The recorder is active by default. Set `diagnostics.enabled: false` only when you need to disable Gateway diagnostic heartbeat collection.
+- The recorder is active by default and payload-free: it captures operational metadata only, not chat text, tool outputs, or raw request or response bodies. Set `diagnostics.enabled: false` only when you need to disable Gateway diagnostic heartbeat collection entirely.
 - Records keep operational metadata: event names, counts, byte sizes, memory readings, queue/session state, channel/plugin names, and redacted session summaries. They do not keep chat text, webhook bodies, tool outputs, raw request or response bodies, tokens, cookies, secret values, hostnames, or raw session ids.
 - On fatal Gateway exits, shutdown timeouts, and restart startup failures, OpenClaw writes the same diagnostic snapshot to `~/.openclaw/logs/stability/openclaw-stability-*.json` when the recorder has events. Inspect the newest bundle with `openclaw gateway stability --bundle latest`; `--limit`, `--type`, and `--since-seq` also apply to bundle output.
 

docs/cli/memory.md

@@ -56,6 +56,8 @@ openclaw memory index --agent main --verbose
 - `--fix`: repair stale recall locks and normalize promotion metadata.
 - `--json`: print JSON output.
 
+If `memory status` shows `Dreaming status: blocked`, the managed dreaming cron is enabled but the heartbeat that drives it is not firing for the default agent. See [Dreaming never runs](/concepts/dreaming#dreaming-never-runs-status-shows-blocked) for the two common causes.
+
 `memory index`:
 
 - `--force`: force a full reindex.

docs/cli/models.md

@@ -13,6 +13,7 @@ Model discovery, scanning, and configuration (default model, fallbacks, auth pro
 Related:
 
 - Providers + models: [Models](/providers/models)
+- Model selection concepts + `/models` slash command: [Models concept](/concepts/models)
 - Provider auth setup: [Getting started](/start/getting-started)
 
 ## Common commands

docs/cli/plugins.md

@@ -68,6 +68,13 @@ openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo
 Bare package names are checked against ClawHub first, then npm. Security note:
 treat plugin installs like running code. Prefer pinned versions.
 
+If your `plugins` section is backed by a single-file `$include`, `plugins install`,
+`plugins update`, `plugins enable`, `plugins disable`, and `plugins uninstall`
+write through to that included file and leave `openclaw.json` untouched. Root
+includes, include arrays, and includes with sibling overrides fail closed
+instead of flattening. See [Config includes](/gateway/configuration) for the
+supported shapes.
+
 If config is invalid, `plugins install` normally fails closed and tells you to
 run `openclaw doctor --fix` first. The only documented exception is a narrow
 bundled-plugin recovery path for plugins that explicitly opt into
@@ -79,6 +86,11 @@ the same id from a new local path, archive, ClawHub package, or npm artifact.
 For routine upgrades of an already tracked npm plugin, prefer
 `openclaw plugins update <id-or-npm-spec>`.
 
+If you run `plugins install` for a plugin id that is already installed, OpenClaw
+stops and points you at `plugins update <id-or-npm-spec>` for a normal upgrade,
+or at `plugins install <package> --force` when you genuinely want to overwrite
+the current install from a different source.
+
 `--pin` applies to npm installs only. It is not supported with `--marketplace`,
 because marketplace installs persist marketplace source metadata instead of an
 npm spec.

docs/cli/tui.md

@@ -25,6 +25,7 @@ Notes:
 - When launched from inside a configured agent workspace directory, TUI auto-selects that agent for the session key default (unless `--session` is explicitly `agent:<id>:...`).
 - Local mode uses the embedded agent runtime directly. Most local tools work, but Gateway-only features are unavailable.
 - Local mode adds `/auth [provider]` inside the TUI command surface.
+- Plugin approval gates still apply in local mode. Tools that require approval prompt for a decision in the terminal; nothing is silently auto-approved because the Gateway is not involved.
 
 ## Examples
 

docs/concepts/session-tool.md

@@ -29,10 +29,11 @@ orchestrate sub-agents.
 `sessions_list` returns sessions with their key, agentId, kind, channel, model,
 token counts, and timestamps. Filter by kind (`main`, `group`, `cron`, `hook`,
 `node`), exact `label`, exact `agentId`, search text, or recency
-(`activeMinutes`). When you need mailbox-style triage, it can also ask for
-derived titles, last-message previews, or bounded recent messages. Preview
-transcript reads are scoped to sessions visible under the configured session
-tool visibility policy.
+(`activeMinutes`). When you need mailbox-style triage, it can also ask for a
+visibility-scoped derived title, a last-message preview snippet, or bounded
+recent messages on each row. Derived titles and previews are produced only for
+sessions the caller can already see under the configured session tool
+visibility policy, so unrelated sessions stay hidden.
 
 `sessions_history` fetches the conversation transcript for a specific session.
 By default, tool results are excluded -- pass `includeTools: true` to see them.

docs/gateway/cli-backends.md

@@ -183,8 +183,12 @@ child process environment for the run.
   - `none`: never send a session id.
 - `claude-cli` defaults to `liveSession: "claude-stdio"`, `output: "jsonl"`,
   and `input: "stdin"` so follow-up turns reuse the live Claude process while
-  it is active. If the Gateway restarts or the idle process exits, OpenClaw
-  resumes from the stored Claude session id.
+  it is active. Warm stdio is the default now, including for custom configs
+  that omit transport fields. If the Gateway restarts or the idle process
+  exits, OpenClaw resumes from the stored Claude session id. Stored session
+  ids are verified against an existing readable project transcript before
+  resume, so phantom bindings are cleared with `reason=transcript-missing`
+  instead of silently starting a fresh Claude CLI session under `--resume`.
 - Stored CLI sessions are provider-owned continuity. The implicit daily session
   reset does not cut them; `/reset` and explicit `session.reset` policies still
   do.

docs/gateway/configuration.md

@@ -572,6 +572,19 @@ Most fields hot-apply without downtime. In `hybrid` mode, restart-required chang
 `gateway.reload` and `gateway.remote` are exceptions — changing them does **not** trigger a restart.
 </Note>
 
+### Reload planning
+
+When you edit a source file that is referenced through `$include`, OpenClaw plans
+the reload from the source-authored layout, not the flattened in-memory view.
+That keeps hot-reload decisions (hot-apply vs restart) predictable even when a
+single top-level section lives in its own included file such as
+`plugins: { $include: "./plugins.json5" }`.
+
+If a reload cannot be planned safely — for example, because the source layout
+combines root includes with sibling overrides — OpenClaw fails closed, logs the
+reason, and leaves the current running config in place so you can fix the source
+shape instead of silently falling back to a flattened reload.
+
 ## Config RPC (programmatic updates)
 
 <Note>

docs/plugins/codex-harness.md

@@ -17,13 +17,20 @@ discovery, native thread resume, native compaction, and app-server execution.
 OpenClaw still owns chat channels, session files, model selection, tools,
 approvals, media delivery, and the visible transcript mirror.
 
-Native Codex turns also respect the shared `before_prompt_build`,
-`before_compaction`, and `after_compaction` plugin hooks, so prompt shims and
-compaction-aware automation can stay aligned with the PI harness.
-Native Codex turns also respect the shared `before_prompt_build`,
-`before_compaction`, `after_compaction`, `llm_input`, `llm_output`, and
-`agent_end` plugin hooks, so prompt shims, compaction-aware automation, and
-lifecycle observers can stay aligned with the PI harness.
+Native Codex turns also respect the shared plugin hooks so prompt shims,
+compaction-aware automation, tool middleware, and lifecycle observers stay
+aligned with the PI harness:
+
+- `before_prompt_build`
+- `before_compaction`, `after_compaction`
+- `llm_input`, `llm_output`
+- `tool_result`, `after_tool_call`
+- `before_message_write`
+- `agent_end`
+
+Bundled plugins can also register a Codex app-server extension factory to add
+async `tool_result` middleware, and mirrored Codex transcript writes route
+through `before_message_write`.
 
 The harness is off by default. It is selected only when the `codex` plugin is
 enabled and the resolved model is a `codex/*` model, or when you explicitly

docs/tools/acp-agents.md

@@ -361,6 +361,7 @@ Interface details:
 - `resumeSessionId` (optional): resume an existing ACP session instead of creating a new one. The agent replays its conversation history via `session/load`. Requires `runtime: "acp"`.
 - `streamTo` (optional): `"parent"` streams initial ACP run progress summaries back to the requester session as system events.
   - When available, accepted responses include `streamLogPath` pointing to a session-scoped JSONL log (`<sessionId>.acp-stream.jsonl`) you can tail for full relay history.
+- `model` (optional): explicit model override for the ACP child session. Honored for `runtime: "acp"` so the child uses the requested model instead of silently falling back to the target agent default.
 
 ## Delivery model