From df09fe9adf15cc25e98a0de8b89330ddc4bb1f95 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sat, 4 Apr 2026 08:28:41 +0100
Subject: [PATCH] docs: refresh system health and sessions refs

---
 docs/cli/health.md   | 11 +++++++++++
 docs/cli/index.md    |  5 +++++
 docs/cli/sessions.md |  3 +++
 docs/cli/system.md   | 11 +++++++++++
 4 files changed, 30 insertions(+)

diff --git a/docs/cli/health.md b/docs/cli/health.md
index 0d39da7e9e3..6761c2d6a4a 100644
--- a/docs/cli/health.md
+++ b/docs/cli/health.md
@@ -9,10 +9,21 @@ title: "health"
 
 Fetch health from the running Gateway.
 
+Options:
+
+- `--json`: machine-readable output
+- `--timeout <ms>`: connection timeout in milliseconds (default `10000`)
+- `--verbose`: verbose logging
+- `--debug`: alias for `--verbose`
+
+Examples:
+
 ```bash
 openclaw health
 openclaw health --json
+openclaw health --timeout 2500
 openclaw health --verbose
+openclaw health --debug
 ```
 
 Notes:
diff --git a/docs/cli/index.md b/docs/cli/index.md
index ed84c0208c9..b6ab332e238 100644
--- a/docs/cli/index.md
+++ b/docs/cli/index.md
@@ -889,6 +889,7 @@ Options:
 - `--json`
 - `--timeout <ms>`
 - `--verbose`
+- `--debug` (alias for `--verbose`)
 
 ### `sessions`
 
@@ -907,6 +908,10 @@ Subcommands:
 
 - `sessions cleanup` — remove expired or orphaned sessions
 
+Notes:
+
+- `sessions cleanup` also supports `--fix-missing` to prune entries whose transcript files are gone.
+
 ## Reset / Uninstall
 
 ### `reset`
diff --git a/docs/cli/sessions.md b/docs/cli/sessions.md
index bb75782c4cd..97decd77741 100644
--- a/docs/cli/sessions.md
+++ b/docs/cli/sessions.md
@@ -14,12 +14,14 @@ openclaw sessions
 openclaw sessions --agent work
 openclaw sessions --all-agents
 openclaw sessions --active 120
+openclaw sessions --verbose
 openclaw sessions --json
 ```
 
 Scope selection:
 
 - default: configured default agent store
+- `--verbose`: verbose logging
 - `--agent <id>`: one configured agent store
 - `--all-agents`: aggregate all configured agent stores
 - `--store <path>`: explicit store path (cannot be combined with `--agent` or `--all-agents`)
@@ -71,6 +73,7 @@ openclaw sessions cleanup --json
 - `--dry-run`: preview how many entries would be pruned/capped without writing.
   - In text mode, dry-run prints a per-session action table (`Action`, `Key`, `Age`, `Model`, `Flags`) so you can see what would be kept vs removed.
 - `--enforce`: apply maintenance even when `session.maintenance.mode` is `warn`.
+- `--fix-missing`: remove entries whose transcript files are missing, even if they would not normally age/count out yet.
 - `--active-key <key>`: protect a specific active key from disk-budget eviction.
 - `--agent <id>`: run cleanup for one configured agent store.
 - `--all-agents`: run cleanup for all configured agent stores.
diff --git a/docs/cli/system.md b/docs/cli/system.md
index ca26b1d2515..0956b42326f 100644
--- a/docs/cli/system.md
+++ b/docs/cli/system.md
@@ -12,10 +12,18 @@ title: "system"
 System-level helpers for the Gateway: enqueue system events, control heartbeats,
 and view presence.
 
+All `system` subcommands use Gateway RPC and accept the shared client flags:
+
+- `--url <url>`
+- `--token <token>`
+- `--timeout <ms>`
+- `--expect-final`
+
 ## Common commands
 
 ```bash
 openclaw system event --text "Check for urgent follow-ups" --mode now
+openclaw system event --text "Check for urgent follow-ups" --url ws://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"
 openclaw system heartbeat enable
 openclaw system heartbeat last
 openclaw system presence
@@ -32,6 +40,7 @@ Flags:
 - `--text <text>`: required system event text.
 - `--mode <mode>`: `now` or `next-heartbeat` (default).
 - `--json`: machine-readable output.
+- `--url`, `--token`, `--timeout`, `--expect-final`: shared Gateway RPC flags.
 
 ## `system heartbeat last|enable|disable`
 
@@ -44,6 +53,7 @@ Heartbeat controls:
 Flags:
 
 - `--json`: machine-readable output.
+- `--url`, `--token`, `--timeout`, `--expect-final`: shared Gateway RPC flags.
 
 ## `system presence`
 
@@ -53,6 +63,7 @@ instances, and similar status lines).
 Flags:
 
 - `--json`: machine-readable output.
+- `--url`, `--token`, `--timeout`, `--expect-final`: shared Gateway RPC flags.
 
 ## Notes