Tencent · iuyo5678 · Sep 15, 2026 · Sep 15, 2026 · Sep 15, 2026
diff --git a/AGENT_INSTALL.md b/AGENT_INSTALL.md
@@ -1,29 +1,66 @@
 # browser-skill — Install Guide for AI Agents
 
-You are an AI agent setting up browser-skill for the user. Done = `bsk doctor`
-reports no `fail` checks. Explain any remaining warnings to the user; a warning
-about local process identity permits browser use over working IPC. Never use
-`sudo`; you cannot install the extension yourself (Step 3 is the user's job).
+You are an AI agent setting up browser-skill for the user. Done = the intended
+harness can load `browser-skill`, `bsk doctor` reports no `fail` checks, and a
+small browser task succeeds and cleans up its session. Doctor alone does not
+verify skill installation or discovery: no installed skill is reported as `N/A`.
+Explain remaining warnings; a local process identity warning permits browser use
+over working IPC. Never use `sudo`; the user installs the browser extension.
 
-## 1. Install the CLI and skill
+## 1. Install the CLI
 
-Run the install command from [`README.md`](README.md):
+For an existing installation, check `bsk --version` and follow the
+[upgrade instructions](README.md#updating) if an update is needed. For a new install:
 
 **macOS / Linux:**
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.sh | sh
-bsk install-skill --yes
+export PATH="${BSK_INSTALL_DIR:-$HOME/.local/bin}:$PATH"
+bsk --version
 ```
 
 **Windows (PowerShell):**
 
 ```powershell
 irm https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.ps1 | iex
-bsk install-skill --yes
+bsk --version
 ```
 
-## 2. Run `bsk doctor`
+The Unix installer cannot update its parent shell's PATH. Repeat the export in
+later shell tool calls if needed, or use the installed binary's absolute path
+(`~/.local/bin/bsk` by default; `~/.local/bin/bsk.exe` on Windows). A running agent
+may retain its old PATH even after a new terminal picks up the installation.
+
+## 2. Install for the intended agent harness
+
+- **DeepSeek Harness (`dsh`):** follow the [plugin setup](README.md#deepseek-harness-plugin)
+  for the user's profile. The plugin supplies its own skill and native tools;
+  skip `bsk install-skill`.
+- **Other supported harnesses:** inspect the available IDs and paths:
+
+  ```sh
+  bsk install-skill --list --json
+  ```
+
+  Install into the intended harness explicitly. For Cursor, for example:
+
+  ```sh
+  bsk install-skill --harness cursor --json
+  ```
+
+  Replace `cursor` with the ID from the list. Explicit `--harness` works even
+  when detection is false. `--yes` without `--harness` selects every detected
+  harness and fails if none are detected; it does not identify the current agent.
+- **Unlisted harnesses:** follow the [manual skill instructions](README.md#quick-start)
+  and use that harness's documented skill directory.
+
+Check the install result and destination. Existing files are skipped; inspect
+them before deciding whether to keep them or restore the bundled skill with
+`--force`, which overwrites the file. Doctor explains paused automatic updates;
+custom instructions are preserved. Verify discovery in Step 5.
+
+## 3. Run `bsk doctor`
 
 If this environment reaps child processes after every shell command, first follow
 the [sandbox setup guide](docs/sandboxed-agents.md): arrange a persistent daemon
@@ -41,13 +78,16 @@ disabled, an unavailable daemon needs host-side startup using the same directory
 For a path/permission failure, use the resolved path in the report to check the
 shared directory and sandbox access rules; do not guess `/home/<user>` or delete
 daemon files. A fresh install where only `extension connected` fails is expected;
-go to Step 3.
+go to Step 4.
+
+## 4. Connect the browser extension
 
-## 3. Open the extension install page
+If the intended browser is already connected, continue to Step 5. If its extension
+is installed but disconnected, check that the connection is enabled and the local
+port matches the daemon. For a server deployment, follow
+[remote pairing](docs/remote-extension-connection.md).
 
-If `extension connected` is `FAIL` (`0 browsers connected`), the user likely
-has not installed or enabled the browser extension yet. Open the install page
-matching the user's browser —
+If the extension is not installed, open the page matching the user's browser —
 [Chrome Web Store](https://chromewebstore.google.com/detail/hhcmgoofomhgciiibhipgmgkgnoenaoi)
 for Chrome and other Chromium browsers,
 [Edge Add-ons](https://microsoftedge.microsoft.com/addons/detail/browserskill/emacgiaaaiojkkpkddmmdfhmokgmnikg)
@@ -58,5 +98,21 @@ for Microsoft Edge — then tell the user:
 > (or [Edge Add-ons](https://microsoftedge.microsoft.com/addons/detail/browserskill/emacgiaaaiojkkpkddmmdfhmokgmnikg)
 > on Edge), open the popup, and wait until it turns green. Reply when done.
 
-If opening the page fails, give the user the same link. Then run `bsk doctor`
-once more. No `fail` checks → tell the user it's ready and explain any warnings.
+If opening the page fails, give the user the same link. Wait for the user's reply,
+then run `bsk doctor` once more.
+
+## 5. Verify skill discovery and first use
+
+Confirm that the intended harness lists or can invoke `browser-skill`. If it needs
+a new agent session or profile restart to discover the skill, tell the user how
+to do that and report verification as pending until it has been loaded there.
+
+Use the installed skill to open `https://example.com` and summarize the page.
+For CLI harnesses, start with `bsk session start --no-focus --json`, retain the
+returned session ID, then navigate and observe using `--session <id>`. Stop that
+session with `bsk session stop <id>` on success or failure. With multiple browsers,
+use `bsk browsers` and add `--browser <id>` when starting the session.
+For dsh, use its injected `browser_*` tools instead.
+
+Report success only after the page is read and the test session is stopped.
+If a step remains blocked, report which part is ready and what remains unverified.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,8 +9,39 @@ Starting from 0.2.0, CLI / Extension / DSH Plugin share the same version number.
 
 ### Added
 
+- [Remote browser connections](docs/remote-extension-connection.md) with a built-in
+  server, one-use pairing links, device credential renewal and revocation, and
+  support for native TLS or a TLS reverse proxy. Remote upload and download are unsupported.
+- [Operation audit](docs/operation-audit.md): opt-in task history stored on the
+  daemon host, with redacted operation metadata, export, deletion and 30-day retention
+- [Full-page screenshots](docs/long-screenshot.md) from extension Quick Actions and
+  the CLI, with streamed PNG output, cancellation and lazy-loaded page capture
+- Canvas visual refs, on-demand element screenshots and screenshot-bound point
+  clicks; observation cursor continuation when an explicit token limit is used
 - [Scroll-to element primitive](docs/scroll-to.md) across CLI, Extension and DSH Plugin,
   with ancestor-clipped visible bounds, iframe support and cooperative cancellation
+- Native [mouse-wheel input](docs/wheel.md), explicit focus and blur actions
+- [Host-managed daemon setup](docs/sandboxed-agents.md) with `BSK_HOME` and
+  `BSK_AUTO_START=0` for agents whose command sandboxes reap background processes
+- Configurable local connection port in the extension popup and Korean localization
+
+### Changed
+
+- **Automation settings:** the extension's saved borrow-confirmation and human-help
+  switches govern existing and new sessions. `--unattended`, `tab borrow --no-confirm`
+  and `BSK_REQUEST_HELP=off` are deprecated compatibility inputs and cannot override
+  these switches. Set the browser preferences when upgrading unattended workflows.
+- Managed CLI skills update only while their content matches the installed baseline;
+  custom instructions and local edits are preserved, with recovery guidance in `doctor`
+- DSH Plugin: use the native browser sidebar when available, with a floating-panel fallback
+
+### Fixed
+
+- Windows installer path handling, verification of the resolved executable, and
+  replacement of installations using a daemon from another directory
+- Browser connection preference recovery and compatibility during staggered component upgrades
+- Observation document and frame geometry consistency, Canvas target identity checks,
+  and screenshot/session cleanup during cancellation or navigation
 
 ## [0.2.1] - 2026-09-09
 

diff --git a/README.md b/README.md
@@ -85,6 +85,7 @@ or [Edge Add-ons](https://microsoftedge.microsoft.com/addons/detail/browserskill
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.sh | sh
+export PATH="${BSK_INSTALL_DIR:-$HOME/.local/bin}:$PATH"
 ```
 
 **Windows** (PowerShell — installs to `~/.local/bin`):
@@ -93,7 +94,11 @@ curl -fsSL https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.s
 irm https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.ps1 | iex
 ```
 
-Verify the binary:
+The export makes the CLI available in the current Unix shell. A running agent may
+need the same PATH setting in each shell call, or the installed binary's absolute
+path. Restart the agent if it retains an old PATH after installation.
+
+Verify the binary in the terminal or agent environment that will use it:
 
 ```bash
 bsk --version
@@ -138,6 +143,11 @@ Use <kbd>Space</kbd> to select the Agent harness you want to install into, then
 press <kbd>Enter</kbd> to install the skill. Run `bsk install-skill --list` to see
 internal variants and install paths.
 
+For non-interactive installation, specify the intended harness, for example
+`bsk install-skill --harness cursor --json`. Explicit selection also works when
+the harness is not detected. `--yes` alone installs into every detected harness
+and fails when none are detected.
+
 To install your own instructions, use `bsk install-skill --harness cursor --source ./SKILL.md`.
 An explicit `--source` stays custom even if its contents match the bundled skill.
 Existing installations are skipped unless you add `--force`.
@@ -165,14 +175,59 @@ Other shell-capable agent harnesses are supported too. Copy
 `browser-skill/SKILL.md` to install the skill manually. DeepSeek Harness uses a
 dedicated plugin instead — see [DeepSeek Harness plugin](#deepseek-harness-plugin).
 
+#### 4. Verify the connection
+
+Run `bsk doctor` and follow its hints. Open the extension popup and confirm it is
+connected. Explain any warnings and resolve failures before testing browser use.
+Doctor can pass with no skill installed (`N/A`); verify skill discovery separately.
+
 </details>
 
-Start a new Agent session and write a prompt that needs the browser, for example:
+Start a new Agent session, confirm `browser-skill` is available in the harness,
+and ask it to open `https://example.com` and summarize the page. For harnesses
+with slash-command skill invocation, for example:
 
 ```text
 /browser-skill open example.com and summarize what is on the page.
 ```
 
+A successful first-use check reads the page and stops its BrowserSkill session.
+If the skill is missing, check the target harness and install path before retrying.
+
+### Updating
+
+For the default local setup, finish active browser tasks before updating:
+
+```sh
+bsk update --yes
+```
+
+If Windows reports a staged update, wait for the replacement to finish before
+checking `bsk --version`.
+
+When it installs an update, this command restarts a running daemon with default
+startup settings. If you replaced the binary using the installer instead, restart
+the existing daemon with `bsk daemon restart` after tasks finish.
+
+For a custom port, host-managed sandbox daemon, or remote server, stop the daemon
+in its owning host or supervisor, run `bsk update --yes --no-restart-daemon`, and
+start it there with its original flags and `BSK_HOME`. Set `BSK_AUTO_START=0`
+in agent commands while managing it; see the [sandbox](docs/sandboxed-agents.md)
+and [remote](docs/remote-extension-connection.md) setup guides.
+
+Update the extension through its browser store; for an unpacked development build,
+rebuild and reload it. Store availability may lag the CLI release. Check the CLI,
+daemon and extension versions with `bsk --version` and `bsk status`, then run
+`bsk doctor`. New features such as full-page screenshots need matching builds.
+Update the [DSH plugin separately](#deepseek-harness-plugin) and restart its profile.
+Managed CLI skills synchronize on daemon startup, `session start`, or `doctor`;
+local edits and custom skills are preserved. Start a new agent session to load
+updated instructions.
+
+**Upgrading to 0.3.0:** `--unattended`, `tab borrow --no-confirm`, and
+`BSK_REQUEST_HELP=off` no longer bypass confirmation or disable help. Choose the
+corresponding extension settings described below. See [what changed](CHANGELOG.md).
+
 ### Automation settings
 
 The extension popup has two independent **Automation settings**, both enabled by default.

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -73,6 +73,7 @@ BrowserSkill 由两个本地运行组件组成：`bsk` CLI/daemon 和浏览器
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.sh | sh
+export PATH="${BSK_INSTALL_DIR:-$HOME/.local/bin}:$PATH"
 ```
 
 **Windows**（PowerShell，安装到 `~/.local/bin`）：
@@ -81,7 +82,10 @@ curl -fsSL https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.s
 irm https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.ps1 | iex
 ```
 
-验证二进制：
+上面的 export 让当前 Unix shell 能找到 CLI。正在运行的 Agent 可能需要在每次 Shell
+调用中设置同样的 PATH，或使用安装后二进制的绝对路径。如果 Agent 安装后仍沿用旧 PATH，请重启 Agent。
+
+在实际使用工具的终端或 Agent 环境中验证二进制：
 
 ```bash
 bsk --version
@@ -123,6 +127,10 @@ bsk install-skill
 
 用 <kbd>Space</kbd> 选择需要安装的 Agent harness，然后按 <kbd>Enter</kbd> 安装 skill。运行 `bsk install-skill --list` 可查看 internal 变体及安装路径。
 
+非交互安装时显式指定目标 harness，例如 `bsk install-skill --harness cursor --json`。
+即使未检测到该 harness，也可显式选择。单独使用 `--yes` 会安装到所有检测到的 harness，
+一个也未检测到时会报错。
+
 安装自定义指令可运行 `bsk install-skill --harness cursor --source ./SKILL.md`。
 显式指定 `--source` 的安装始终视为自定义，即使内容与内置 skill 相同。
 已有安装默认跳过，添加 `--force` 才会覆盖。
@@ -143,14 +151,51 @@ daemon 启动、`session start` 和 `doctor` 会检查已安装的 skill：只
 
 其他支持 Shell 的 Agent harness 也可使用 BrowserSkill，但需手动将 [`skill/SKILL.md`](skill/SKILL.md) 复制到对应 skills 目录下的 `browser-skill/SKILL.md`。DeepSeek Harness 走独立插件，见 [DeepSeek Harness 插件](#deepseek-harness-插件)。
 
+#### 4. 验证连接
+
+运行 `bsk doctor` 并按提示处理，打开扩展弹窗确认已连接。测试浏览器操作前，说明警告并解决失败项。
+未安装任何 skill 时，doctor 仍可能通过（该项为 `N/A`）；skill 是否被发现需要单独验证。
+
 </details>
 
-启动一个新的 Agent 会话，写一条需要使用浏览器的 prompt，例如：
+启动一个新的 Agent 会话，确认 harness 中可用 `browser-skill`，再让它打开
+`https://example.com` 并总结页面。对于支持斜杠命令调用 skill 的 harness，例如：
 
 ```text
 /browser-skill open example.com and summarize what is on the page.
 ```
 
+首次使用验证应成功读取页面，并停止本次 BrowserSkill session。
+如果找不到 skill，先检查目标 harness 和安装路径，再重试。
+
+### 升级
+
+默认本地配置下，先结束正在执行的浏览器任务，再更新：
+
+```sh
+bsk update --yes
+```
+
+如果 Windows 提示更新已暂存（staged），请等待替换完成后再检查 `bsk --version`。
+
+该命令安装新版本时，会以默认启动配置重启正在运行的 daemon。
+如果通过安装脚本替换了二进制，则在任务结束后运行 `bsk daemon restart`，重启已有 daemon。
+
+对于自定义端口、宿主管理的沙盒 daemon 或远程服务器，先在所属宿主环境或进程管理器中停止 daemon，
+运行 `bsk update --yes --no-restart-daemon`，再以原有参数和 `BSK_HOME` 在那里启动。
+维护期间，在 Agent 命令中设置 `BSK_AUTO_START=0`；详见[沙盒](docs/sandboxed-agents.md)和
+[远程连接](docs/remote-extension-connection.md)配置说明。
+
+通过浏览器商店更新扩展；开发时加载的解压版本需要重新构建并重新加载。
+商店版本可能晚于 CLI 上线。使用 `bsk --version` 和 `bsk status` 核对 CLI、daemon 和扩展版本，
+再运行 `bsk doctor`。长截图等新功能需要匹配的版本。
+[DSH 插件需要单独更新](#deepseek-harness-插件)，并重启对应 profile。
+受管理的 CLI skill 会在 daemon 启动、`session start` 或 `doctor` 时同步；本地编辑和自定义 skill 会保留。
+启动新的 Agent 会话以加载更新后的指令。
+
+**升级到 0.3.0：** `--unattended`、`tab borrow --no-confirm` 和 `BSK_REQUEST_HELP=off`
+不再跳过确认或关闭人工协助。请在扩展中选择下文说明的对应设置。版本变化见[更新日志](CHANGELOG.md)。
+
 ### 自动化设置与无人值守
 
 插件弹窗提供两个默认开启的独立设置。**用户在插件中保存的设置对所有会话具有最终决定权：**