docs: absorb contributor documentation fixes

Co-authored-by: ayesha-aziz123 <moizs4644@gmail.com>
Co-authored-by: dishraters <dishraters@gmail.com>
Co-authored-by: hougangdev <devchain7890@gmail.com>
Co-authored-by: Brandon Lipman <brandon@offdeck.com>

CHANGELOG.md

@@ -6,6 +6,7 @@ Docs: https://docs.openclaw.ai
 
 ### Changes
 
+- Docs: clarify context-pruning ratio bounds, local dashboard recovery, CLI env markers, remote onboarding token behavior, and Peekaboo Bridge permissions for subprocess agents. Thanks @ayesha-aziz123, @dishraters, @hougangdev, and @brandonlipman.
 - Docs: clarify browser CDP diagnostics, Plugin SDK allowlist imports, status-reaction timing defaults, queue steering behavior, limited-tool troubleshooting, cron HEARTBEAT handling, Telegram multi-agent groups, Bitwarden SecretRef setup, and EasyRunner deployments. Thanks @Quratulain-bilal, @mbelinky, @Mickey-, @vancece, @xenouzik, @posigit, @surlymochan, @janaka, and @choiking.
 - Docs: clarify IPv4-only Gateway BYOH binding, trusted-proxy scope clearing, Android pairing approval, macOS Accessibility grants, Zalo profile env vars, password-store SecretRef setup, and Chinese memory navigation. Thanks @itskai-dev, @gwh7078, @longstoryscott, @MoeJaberr, and @yuaiccc.
 - Docs: consolidate GLM under Z.AI, add the Upstash Box install guide and Gateway exposure runbook, clarify MEDIA directives, Copilot and Voyage setup, config path quoting, real behavior proof, and memory-file write guidance. Thanks @BobDu, @alitariksahin, @Jefsky, @musaabhasan, @OmerZeyveli, @leno23, @WuKongAI-CMU, @luoyanglang, and @majin1102.

docs/gateway/config-agents.md

@@ -723,6 +723,7 @@ Prunes **old tool results** from in-memory context before sending to the LLM. Do
 - `mode: "cache-ttl"` enables pruning passes.
 - `ttl` controls how often pruning can run again (after the last cache touch).
 - Pruning soft-trims oversized tool results first, then hard-clears older tool results if needed.
+- `softTrimRatio` and `hardClearRatio` accept values from `0.0` through `1.0`; config validation rejects values outside that range.
 
 **Soft-trim** keeps beginning + end and inserts `...` in the middle.
 

docs/gateway/troubleshooting.md

@@ -294,6 +294,21 @@ Look for:
 - Auth mode/token mismatch between client and gateway.
 - HTTP usage where device identity is required.
 
+If a local browser cannot connect to `127.0.0.1:18789` after an update, first
+recover the local Gateway service and confirm it is serving the dashboard:
+
+```bash
+openclaw gateway restart
+lsof -i :18789
+curl http://127.0.0.1:18789
+```
+
+If `curl` returns OpenClaw HTML, the Gateway is working and the remaining issue
+is likely browser cache, an old deep link, or stale tab state. Open
+`http://127.0.0.1:18789` directly and navigate from the dashboard. If restart
+does not leave the service running, run `openclaw gateway start` and recheck
+`openclaw gateway status`.
+
 <AccordionGroup>
   <Accordion title="Connect / auth signatures">
     - `device identity required` → non-secure context or missing device auth.

docs/help/environment.md

@@ -96,6 +96,7 @@ OpenClaw also injects context markers into spawned child processes:
 - `OPENCLAW_SHELL=acp`: set for ACP runtime backend process spawns (for example `acpx`).
 - `OPENCLAW_SHELL=acp-client`: set for `openclaw acp client` when it spawns the ACP bridge process.
 - `OPENCLAW_SHELL=tui-local`: set for local TUI `!` shell commands.
+- `OPENCLAW_CLI=1`: set for child processes spawned by the CLI entry point.
 
 These are runtime markers (not required user config). They can be used in shell/profile logic
 to apply context-specific rules.

docs/start/onboarding.md

@@ -46,7 +46,10 @@ Where does the **Gateway** run?
 - **This Mac (Local only):** onboarding can configure auth and write credentials
   locally.
 - **Remote (over SSH/Tailnet):** onboarding does **not** configure local auth;
-  credentials must exist on the gateway host.
+  credentials must exist on the gateway host. The remote gateway token field
+  stores the token used by the macOS app to connect to that Gateway; existing
+  non-plaintext `gateway.remote.token` values are preserved until you replace
+  them.
 - **Configure later:** skip setup and leave the app unconfigured.
 
 <Tip>

skills/peekaboo/SKILL.md

@@ -187,4 +187,12 @@ peekaboo type "Line 1\nLine 2" --delay 10
 Notes
 
 - Requires Screen Recording + Accessibility permissions.
+- In OpenClaw subprocesses, use the default Bridge path. Do not pass
+  `--no-remote` unless the calling process has its own Screen Recording grant.
+- Diagnose subprocess capture failures with `peekaboo bridge status --json`,
+  then `peekaboo permissions status --json`, then a normal Bridge-routed
+  capture such as `peekaboo image --mode screen --json`.
+- On macOS 15+, the "bypass private window picker" prompt is separate from the
+  base Screen Recording grant; it can appear even when Bridge permissions are
+  otherwise correct.
 - Use `peekaboo see --annotate` to identify targets before clicking.