diff --git a/docs/help/debugging.md b/docs/help/debugging.md
index 85f75c8e8be..cd56d36b6a9 100644
--- a/docs/help/debugging.md
+++ b/docs/help/debugging.md
@@ -249,21 +249,24 @@ Reset flow (fresh start):
 pnpm gateway:dev:reset
 ```
 
-Note: `--dev` is a **global** profile flag and gets eaten by some runners.
-If you need to spell it out, use the env var form:
+<Note>
+`--dev` is a **global** profile flag and gets eaten by some runners. If you need to spell it out, use the env var form:
 
 ```bash
 OPENCLAW_PROFILE=dev openclaw gateway --dev --reset
 ```
+</Note>
 
 `--reset` wipes config, credentials, sessions, and the dev workspace (using
 `trash`, not `rm`), then recreates the default dev setup.
 
-Tip: if a non‑dev gateway is already running (launchd/systemd), stop it first:
+<Tip>
+If a non-dev gateway is already running (launchd or systemd), stop it first:
 
 ```bash
 openclaw gateway stop
 ```
+</Tip>
 
 ## Raw stream logging (OpenClaw)
 
diff --git a/docs/help/testing-live.md b/docs/help/testing-live.md
index 9323873113d..8507deef646 100644
--- a/docs/help/testing-live.md
+++ b/docs/help/testing-live.md
@@ -127,12 +127,14 @@ Live tests are split into two layers so we can isolate failures:
     - Embedded agent forwards a multimodal user message to the model
     - Assertion: reply contains `cat` + the code (OCR tolerance: minor mistakes allowed)
 
-Tip: to see what you can test on your machine (and the exact `provider/model` ids), run:
+<Tip>
+To see what you can test on your machine (and the exact `provider/model` ids), run:
 
 ```bash
 openclaw models list
 openclaw models list --json
 ```
+</Tip>
 
 ## Live: CLI backend smoke (Claude, Codex, Gemini, or other local CLIs)
 
@@ -413,7 +415,9 @@ More providers you can include in the live matrix (if you have creds/config):
 - Built-in: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot`
 - Via `models.providers` (custom endpoints): `minimax` (cloud/API), plus any OpenAI/Anthropic-compatible proxy (LM Studio, vLLM, LiteLLM, etc.)
 
-Tip: don’t try to hardcode “all models” in docs. The authoritative list is whatever `discoverModels(...)` returns on your machine + whatever keys are available.
+<Tip>
+Do not hardcode "all models" in docs. The authoritative list is whatever `discoverModels(...)` returns on your machine plus whatever keys are available.
+</Tip>
 
 ## Credentials (never commit)
 
diff --git a/docs/help/testing.md b/docs/help/testing.md
index 52bd52c639b..5110034dd5e 100644
--- a/docs/help/testing.md
+++ b/docs/help/testing.md
@@ -84,7 +84,9 @@ When debugging real providers/models (requires real creds):
   against `moonshot/kimi-k2.6`. Verify the JSON reports Moonshot/K2.6 and the
   assistant transcript stores normalized `usage.cost`.
 
-Tip: when you only need one failing case, prefer narrowing live tests via the allowlist env vars described below.
+<Tip>
+When you only need one failing case, prefer narrowing live tests via the allowlist env vars described below.
+</Tip>
 
 ## QA-specific runners
 
diff --git a/docs/tools/acp-agents-setup.md b/docs/tools/acp-agents-setup.md
index 0234c20fede..44787262c0f 100644
--- a/docs/tools/acp-agents-setup.md
+++ b/docs/tools/acp-agents-setup.md
@@ -304,9 +304,11 @@ openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail
 
 Restart the gateway after changing these values.
 
-> **Important:** OpenClaw currently defaults to `permissionMode=approve-reads` and `nonInteractivePermissions=fail`. In non-interactive ACP sessions, any write or exec that triggers a permission prompt can fail with `AcpRuntimeError: Permission prompt unavailable in non-interactive mode`.
->
-> If you need to restrict permissions, set `nonInteractivePermissions` to `deny` so sessions degrade gracefully instead of crashing.
+<Warning>
+OpenClaw defaults to `permissionMode=approve-reads` and `nonInteractivePermissions=fail`. In non-interactive ACP sessions, any write or exec that triggers a permission prompt can fail with `AcpRuntimeError: Permission prompt unavailable in non-interactive mode`.
+
+If you need to restrict permissions, set `nonInteractivePermissions` to `deny` so sessions degrade gracefully instead of crashing.
+</Warning>
 
 ## Related
 
diff --git a/docs/tools/lobster.md b/docs/tools/lobster.md
index ba9487d5d05..0b94c2cd4fd 100644
--- a/docs/tools/lobster.md
+++ b/docs/tools/lobster.md
@@ -190,9 +190,9 @@ Or per-agent:
 
 Avoid using `tools.allow: ["lobster"]` unless you intend to run in restrictive allowlist mode.
 
-Note: allowlists are opt-in for optional plugins. If your allowlist only names
-plugin tools (like `lobster`), OpenClaw keeps core tools enabled. To restrict core
-tools, include the core tools or groups you want in the allowlist too.
+<Note>
+Allowlists are opt-in for optional plugins. If your allowlist only names plugin tools (like `lobster`), OpenClaw keeps core tools enabled. To restrict core tools, include the core tools or groups you want in the allowlist too.
+</Note>
 
 ## Example: Email triage