From a1bcb23239bc9a5525b27edd4fa51ff7094a9fdd Mon Sep 17 00:00:00 2001
From: jackwener <jakevingoo@gmail.com>
Date: Tue, 17 Mar 2026 16:00:46 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20reorder=20setup=20flow=20=E2=80=94=20do?=
 =?UTF-8?q?ctor=20first,=20then=20setup?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Logical flow: install extension → doctor (verify token discoverable) →
setup (distribute token to tools). --fix moved to a Tip block for
post-setup maintenance.
---
 README.md       | 24 ++++++++++++++----------
 README.zh-CN.md | 24 ++++++++++++++----------
 2 files changed, 28 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index d744f9c..a0605cf 100644
--- a/README.md
+++ b/README.md
@@ -48,7 +48,14 @@ OpenCLI connects to your browser through the Playwright MCP Bridge extension.
 ### Playwright MCP Bridge Extension Setup
 
 1. Install **[Playwright MCP Bridge](https://chromewebstore.google.com/detail/playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm)** extension in Chrome.
-2. Run `opencli setup` — it auto-discovers your token and lets you choose which tools to configure:
+2. Run `opencli doctor` to verify the extension is properly installed and its token is discoverable:
+
+```bash
+opencli doctor            # Token & config diagnosis
+opencli doctor --live     # Also test live browser connectivity
+```
+
+3. Run `opencli setup` to auto-discover the token and distribute it to your tools:
 
 ```bash
 opencli setup
@@ -59,6 +66,12 @@ The interactive TUI will:
 - ☑️ Show all detected tools (Codex, Cursor, Claude Code, Gemini CLI, etc.)
 - ✏️ Update only the files you select (Space to toggle, Enter to confirm)
 
+> **Tip**: If configs get out of sync later, use `opencli doctor --fix` to repair them:
+> ```bash
+> opencli doctor --fix      # Fix mismatched configs (interactive confirmation)
+> opencli doctor --fix -y   # Fix all configs non-interactively
+> ```
+
 <details>
 <summary>Manual setup (alternative)</summary>
 
@@ -86,15 +99,6 @@ export PLAYWRIGHT_MCP_EXTENSION_TOKEN="<your-token-here>"
 
 </details>
 
-Verify with `opencli doctor` — shows colored status for extension install, token consistency, and all config locations:
-
-```bash
-opencli doctor            # Token & config diagnosis
-opencli doctor --live     # Also test live browser connectivity
-opencli doctor --fix      # Fix mismatched configs (interactive confirmation)
-opencli doctor --fix -y   # Fix all configs non-interactively
-```
-
 ## Quick Start
 
 ### Install via npm (recommended)
diff --git a/README.zh-CN.md b/README.zh-CN.md
index d69d082..8c4b409 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -47,7 +47,14 @@ OpenCLI 通过 Playwright MCP Bridge 扩展与你的浏览器通信。
 ### Playwright MCP Bridge 扩展配置
 
 1. 安装 **[Playwright MCP Bridge](https://chromewebstore.google.com/detail/playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm)** 扩展
-2. 运行 `opencli setup` — 自动发现 Token 并让你选择要配置哪些工具：
+2. 运行 `opencli doctor` 确认扩展已安装、Token 可被发现：
+
+```bash
+opencli doctor            # Token 与配置诊断
+opencli doctor --live     # 额外测试浏览器连通性
+```
+
+3. 运行 `opencli setup` 自动发现 Token 并分发到各工具配置：
 
 ```bash
 opencli setup
@@ -58,6 +65,12 @@ opencli setup
 - ☑️ 显示所有支持的工具（Codex、Cursor、Claude Code、Gemini CLI 等）
 - ✏️ 只更新你选中的文件（空格切换，回车确认）
 
+> **Tip**：如果后续配置不一致，可用 `opencli doctor --fix` 修复：
+> ```bash
+> opencli doctor --fix      # 修复不一致的配置（交互确认）
+> opencli doctor --fix -y   # 无交互直接修复所有配置
+> ```
+
 <details>
 <summary>手动配置（备选方案）</summary>
 
@@ -85,15 +98,6 @@ export PLAYWRIGHT_MCP_EXTENSION_TOKEN="<你的-token>"
 
 </details>
 
-配置后运行 `opencli doctor` 检查扩展安装、Token 一致性和所有配置文件状态：
-
-```bash
-opencli doctor            # Token 与配置诊断
-opencli doctor --live     # 额外测试浏览器连通性
-opencli doctor --fix      # 修复不一致的配置（交互确认）
-opencli doctor --fix -y   # 无交互直接修复所有配置
-```
-
 ## 快速开始
 
 ### npm 全局安装（推荐）