From 3147efbed40babd3a36eba6a4ea4bad3e56073a6 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sun, 3 May 2026 21:21:48 +0100
Subject: [PATCH] docs: clarify update diagnostics

---
 docs/cli/update.md       | 9 +++++++++
 docs/install/updating.md | 6 ++++++
 2 files changed, 15 insertions(+)

diff --git a/docs/cli/update.md b/docs/cli/update.md
index 12699c62ba1..17fb8513bea 100644
--- a/docs/cli/update.md
+++ b/docs/cli/update.md
@@ -2,6 +2,7 @@
 summary: "CLI reference for `openclaw update` (safe-ish source update + gateway auto-restart)"
 read_when:
   - You want to update a source checkout safely
+  - You are debugging `openclaw update` output or options
   - You need to understand `--update` shorthand behavior
 title: "Update"
 ---
@@ -42,6 +43,14 @@ openclaw --update
 - `--timeout <seconds>`: per-step timeout (default is 1800s).
 - `--yes`: skip confirmation prompts (for example downgrade confirmation).
 
+`openclaw update` does not have a `--verbose` flag. Use `--dry-run` to preview
+the planned channel/tag/install/restart actions, `--json` for machine-readable
+results, and `openclaw update status --json` when you only need channel and
+availability details. If you are debugging Gateway logs around an update,
+console verbosity and file log level are separate: Gateway `--verbose` affects
+terminal/WebSocket output, while file logs require `logging.level: "debug"` or
+`"trace"` in config. See [Gateway logging](/gateway/logging).
+
 <Warning>
 Downgrades require confirmation because older versions can break configuration.
 </Warning>
diff --git a/docs/install/updating.md b/docs/install/updating.md
index 0e7d16fe4bb..8052b7e4ecf 100644
--- a/docs/install/updating.md
+++ b/docs/install/updating.md
@@ -25,6 +25,12 @@ openclaw update --tag main
 openclaw update --dry-run   # preview without applying
 ```
 
+`openclaw update` does not accept `--verbose`. For update diagnostics, use
+`--dry-run` to preview the planned actions, `--json` for structured results, or
+`openclaw update status --json` to inspect channel and availability state. The
+installer has its own `--verbose` flag, but that flag is not part of
+`openclaw update`.
+
 `--channel beta` prefers beta, but the runtime falls back to stable/latest when
 the beta tag is missing or older than the latest stable release. Use `--tag beta`
 if you want the raw npm beta dist-tag for a one-off package update.