diff --git a/docs/cli/browser.md b/docs/cli/browser.md
index dbe047a2ca1..8a6886e5af0 100644
--- a/docs/cli/browser.md
+++ b/docs/cli/browser.md
@@ -213,7 +213,13 @@ Current existing-session limits:
 - `click` is left-click only
 - `type` does not support `slowly=true`
 - `press` does not support `delayMs`
+- `hover`, `scrollintoview`, `drag`, `select`, `fill`, and `evaluate` reject
+  per-call timeout overrides
+- `select` supports one value only
 - `wait --load networkidle` is not supported
+- file uploads require `--ref` / `--input-ref`, do not support CSS
+  `--element`, and currently support one file at a time
+- dialog hooks do not support `--timeout`
 - screenshots support page captures and `--ref`, but not CSS `--element`
 - `responsebody`, download interception, PDF export, and batch actions still
   require a managed browser or raw CDP profile
diff --git a/docs/gateway/troubleshooting.md b/docs/gateway/troubleshooting.md
index 691e9d38237..9464caa0bc9 100644
--- a/docs/gateway/troubleshooting.md
+++ b/docs/gateway/troubleshooting.md
@@ -364,6 +364,10 @@ Common signatures:
 - `Playwright is not available in this gateway build; '<feature>' is unsupported.` → the current gateway install lacks the full Playwright package; ARIA snapshots and basic page screenshots can still work, but navigation, AI snapshots, CSS-selector element screenshots, and PDF export stay unavailable.
 - `fullPage is not supported for element screenshots` → screenshot request mixed `--full-page` with `--ref` or `--element`.
 - `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Chrome MCP / `existing-session` screenshot calls must use page capture or a snapshot `--ref`, not CSS `--element`.
+- `existing-session file uploads do not support element selectors; use ref/inputRef.` → Chrome MCP upload hooks need snapshot refs, not CSS selectors.
+- `existing-session file uploads currently support one file at a time.` → send one upload per call on Chrome MCP profiles.
+- `existing-session dialog handling does not support timeoutMs.` → dialog hooks on Chrome MCP profiles do not support timeout overrides.
+- `response body is not supported for existing-session profiles yet.` → `responsebody` still requires a managed browser or raw CDP profile.
 - stale viewport / dark-mode / locale / offline overrides on attach-only or remote CDP profiles → run `openclaw browser stop --browser-profile <name>` to close the active control session and release Playwright/CDP emulation state without restarting the whole gateway.
 
 Related:
diff --git a/docs/help/faq.md b/docs/help/faq.md
index 336c352f5c0..9a860d83c4d 100644
--- a/docs/help/faq.md
+++ b/docs/help/faq.md
@@ -1232,6 +1232,12 @@ for usage/billing and raise limits as needed.
 
     This path is host-local. If the Gateway runs elsewhere, either run a node host on the browser machine or use remote CDP instead.
 
+    Current limits on `existing-session` / `user`:
+
+    - actions are ref-driven, not CSS-selector driven
+    - uploads require `ref` / `inputRef` and currently support one file at a time
+    - `responsebody`, PDF export, download interception, and batch actions still need a managed browser or raw CDP profile
+
   </Accordion>
 </AccordionGroup>
 
diff --git a/docs/tools/browser.md b/docs/tools/browser.md
index 532f6fbc8d0..049e8aecc5f 100644
--- a/docs/tools/browser.md
+++ b/docs/tools/browser.md
@@ -508,11 +508,14 @@ Notes:
   - `click` is left-button only (no button overrides or modifiers)
   - `type` does not support `slowly=true`; use `fill` or `press`
   - `press` does not support `delayMs`
-  - `hover`, `scrollIntoView`, `drag`, `select`, and `evaluate` do not support
-    per-call timeout overrides
+  - `hover`, `scrollIntoView`, `drag`, `select`, `fill`, and `evaluate` do not
+    support per-call timeout overrides
   - `select` currently supports a single value only
 - Existing-session `wait --url` supports exact, substring, and glob patterns
   like other browser drivers. `wait --load networkidle` is not supported yet.
+- Existing-session upload hooks require `ref` or `inputRef`, support one file
+  at a time, and do not support CSS `element` targeting.
+- Existing-session dialog hooks do not support timeout overrides.
 - Some features still require the managed browser path, including batch
   actions, PDF export, download interception, and `responsebody`.
 - Existing-session is host-local. If Chrome lives on a different machine or a