bookmark-research 0.5.0-beta.13 → 0.5.0-beta.15

package/.agents/plugins/marketplace.json

@@ -9,7 +9,7 @@
       "source": {
         "source": "npm",
         "package": "bookmark-research",
-        "version": "0.5.0-beta.13",
+        "version": "0.5.0-beta.15",
         "registry": "https://registry.npmjs.org"
       },
       "policy": {

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "bookmark-research",
-  "version": "0.5.0-beta.13",
+  "version": "0.5.0-beta.15",
   "description": "Check bookmark URLs or Canvas packages, compare sources with host-led research, and retain verifiable reports.",
   "author": {
     "name": "kwenxu"

package/README.md

@@ -5,60 +5,61 @@
 [![GitHub Bookmark-Canvas](https://img.shields.io/badge/GitHub-Bookmark--Canvas-181717?logo=github&logoColor=white)](https://github.com/Browser-bookmark-hub/Bookmark-Canvas)
 [![npm version](https://img.shields.io/npm/v/bookmark-research/beta?logo=npm)](https://www.npmjs.com/package/bookmark-research)
 
-Research your bookmarks with verified web sources. Give it a list of bookmark URLs or a [Bookmark Canvas](https://github.com/Browser-bookmark-hub/Bookmark-Canvas) package; it checks every link, searches and reads the web, and writes a cited report you can resume.
-
-Works in **Codex, Claude Code, Pi and DSH (DeepSeek Harness)**.
+Research your bookmarks with verified web sources. Give it a list of bookmark URLs or a [Bookmark Canvas](https://github.com/Browser-bookmark-hub/Bookmark-Canvas) package; it checks every link, searches and reads the web, and writes a cited report you can resume. Works in **Codex, Claude Code, Pi and DSH (DeepSeek Harness)**.
 
 [Installation guide](docs/installation.en.md) · [User guide](docs/user-guide.en.md) · [Details](docs/details.en.md) · [npm](https://www.npmjs.com/package/bookmark-research)
 
 > [!NOTE]
-> **0.5.0 is a beta.** Report problems on [GitHub Issues](https://github.com/Browser-bookmark-hub/Bookmark-Research/issues).
+> **0.5.0 is a prerelease**, published on npm's `beta` tag; the `latest` tag still points at an older build. Report problems on [GitHub Issues](https://github.com/Browser-bookmark-hub/Bookmark-Research/issues).
+
+## How it works
 
-**Install releases from [npm](https://www.npmjs.com/package/bookmark-research).** GitHub Releases retain version notes and npm links; downloadable installation/test packages have been withdrawn. GitHub's automatic **Source code** archives are source checkouts, not installation packages.
+- **Local understanding.** A Bookmark Canvas package is read as structure, not a flat URL list: card and group layout, edges with their direction and labels, and the same bookmark appearing across cards (spatial context); dated fields, protocol-defined date segments in IDs, and Git commits that changed content (temporal context). These queries run offline.
+- **External research takes one of three routes.** Reading a known URL needs no reasoning; agentic search has the host model plan, search, read and follow the gaps; deep research adds a persistent inventory, independent verification, a coverage check and a report. Enabled OpenAI Deep Research or Parallel Task API runs are a separate, optional route; headless-browser and scraping projects are not bundled.
+- **Reviewed knowledge store.** Finished research can be compiled into a Wiki of reviewed pages with revisions and links, reused by later questions instead of searching the web again.
 
 ## Requirements
 
-- Python 3.9+ with SQLite FTS5 (check with `bookmark-research doctor`)
-- The CLI of at least one client: Codex, Claude Code, Pi or DSH (DSH also needs `pnpm`)
-- Node 18+ and npm for release installation (including the GitHub convenience script)
-- No API key is needed to install or to query bookmarks locally
+- Python 3.9+ with SQLite FTS5 (checked by `bookmark-research doctor`)
+- The CLI of at least one client: Codex, Claude Code, Pi or DSH. DSH also needs `pnpm`, unless it is the DeepSeek Harness Desktop CLI, which carries its own
+- Node 18+ and npm to install a release
+- No API key is needed to install, or to query bookmarks locally
 
 ## Install
 
-**Current beta (`0.5.0-beta.13`)**, interactive on macOS, Linux and Windows:
-
 ```sh
-npx bookmark-research@0.5.0-beta.13 install
+npx bookmark-research@beta install
 ```
 
-The installer automatically pins the running package version and upgrades all selected hosts seamlessly without requiring `--source`. Existing and new users can upgrade directly with this command; `@beta` currently points to `0.5.0-beta.13`.
-
-**Default-channel interactive installation:**
+`@beta` follows the newest prerelease; pin one build with `@0.5.0-beta.15`. Add `--lang zh` for the Chinese wizard. For a permanent command, run `npm install -g bookmark-research`; the GitHub convenience script uses the same npm release (macOS/Linux/WSL):
 
 ```sh
-npx bookmark-research@latest install
+curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Research/main/install.sh | bash
 ```
 
-Pick clients with the arrow keys and Space, confirm the summary, then choose search services and enter API keys. Start a new client session afterwards.
+### What the installer asks
 
-For a permanent `bookmark-research` command: `npm install -g bookmark-research`. The GitHub convenience script uses the same npm release (macOS/Linux/WSL): `curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Research/main/install.sh | bash`.
+1. **Clients** — arrow keys and Space to toggle; detected CLIs are preselected. The install plan is shown for confirmation.
+2. **Research depth (optional)** — leave `auto` and the depth is picked from each request; set `quick`, `agentic` or `deep` only to pin one default.
+3. **Answer and report language** — follow the question, Chinese or English.
+4. **Search and page-reading services** — one ordered multiselect. Unselected providers become the fallback search tier.
+5. **Storage** — the default data folder, one custom folder for archives and reports, or reports beside the bookmark file or folder.
+6. **Optional professional APIs** — off by default: OpenAI Deep Research or the Parallel Task API.
+7. **API keys** — one hidden prompt per selected key, checked immediately; every key is optional.
+8. **Service check** — runs on its own and reports each provider; a sample search/read test is opt-in.
 
-**One client, no prompts:**
+Enter keeps the highlighted value, so a full run can be just a few keystrokes. Then start a new client session so the Skill and MCP tools load. Wiki follow-up (suggest and ask first) and the pre-research availability check (15-minute cache) are on by default and need no answer.
+
+### Non-interactive install
 
 | Client | Command | Registers with |
 | --- | --- | --- |
-| Codex | `npx bookmark-research@latest install codex --non-interactive` | `codex plugin add` |
-| Claude Code | `npx bookmark-research@latest install claude --scope user --non-interactive` | `claude plugin install` |
-| Pi | `npx bookmark-research@latest install pi --non-interactive` | `pi install` |
-| DSH | `npx bookmark-research@latest install dsh --profile web --non-interactive` | `dsh plugin add` |
-
-**One release source for all four hosts:** npm contains the shared runtime, Skill and host adapters. The installer downloads the release, prepares the selected host format, then invokes the host’s native commands. Updates retain an npm selector rather than an npx cache path. GitHub hosts source and installation catalogs; unpublished source uses the Python installer. See [distribution policy and official references](docs/distribution.md).
-
-**DSH installs the release directly:** the published package declares `dsh.bundle.patch`, so `dsh plugin --profile <name> add bookmark-research@<version>` — or the DSH plugin manager — installs it with no export first, resolving Python and MCP paths from the installed package. DeepSeek Harness Desktop reserves the `desktop` profile for its own carrier, so install that one with the app's CLI. See the [installation guide](docs/installation.en.md).
+| Codex | `npx bookmark-research@beta install codex --non-interactive` | `codex plugin add` |
+| Claude Code | `npx bookmark-research@beta install claude --scope user --non-interactive` | `claude plugin install` |
+| Pi | `npx bookmark-research@beta install pi --non-interactive` | `pi install` |
+| DSH | `npx bookmark-research@beta install dsh --profile web --non-interactive` | `dsh plugin add` |
 
-**Windows:** the installer writes the detected Python path into each client's MCP config, because Windows often has no working `python3`. Install Codex with `bookmark-research install codex` rather than adding the repository to Codex directly. `bookmark-research status` shows the interpreter in use.
-
-Several at once: `npx bookmark-research@latest install claude dsh --profile web --non-interactive`. Project scope: `--scope project --project /path/to/project` (Claude Code, Pi). All options: [installation guide](docs/installation.en.md).
+Several at once: `npx bookmark-research@beta install claude dsh --profile web --non-interactive`. Project scope: `--scope project --project /path/to/project` (Claude Code, Pi). All options: [installation guide](docs/installation.en.md).
 
 **Ask your agent to install it.** Paste this into Codex, Claude Code, Pi or DSH:
 
@@ -66,30 +67,38 @@ Several at once: `npx bookmark-research@latest install claude dsh --profile web
 Install the Bookmark Research plugin into the client you are running in.
 
 1. Identify your own client: codex, claude, pi or dsh.
-2. Run: npx bookmark-research@latest install <client> --non-interactive
+2. Run: npx bookmark-research@beta install <client> --non-interactive
    - Claude Code or Pi: add --scope user (or --scope project --project <dir>).
    - DSH: add --profile <profile>; ask me for the profile name.
 3. The command prints JSON. Confirm "verified": true and report any "error".
 4. Do not ask me for API keys in chat. Tell me to run `bookmark-research setup`
-   (or `npx bookmark-research@latest setup`) in my terminal to enter them.
+   in my terminal to enter them.
 5. Tell me to start a new session so the Skill and MCP tools load.
 ```
 
-## Configure and API keys
+Install notes:
+
+- **npm is the single release source** for all four hosts; it contains the shared runtime, Skill and host adapters. The installer downloads the release, prepares the host's format, then calls the host's native commands. GitHub hosts source, versions and the installation catalog; unpublished source uses the Python installer. See [distribution policy](docs/distribution.md).
+- **DSH installs the release directly.** The package declares `dsh.bundle.patch`, so `dsh plugin --profile <name> add bookmark-research@<version>` installs it with no export first. The reserved `desktop` profile belongs to DeepSeek Harness Desktop; use that app's CLI, which the installer and wizard locate themselves.
+- **Windows** often has no working `python3`, so the installer writes the detected Python path into each client's MCP config. Install Codex with `bookmark-research install codex` rather than adding the repository to Codex directly; `bookmark-research status` shows the interpreter in use.
 
-No reinstall is needed. Settings and keys apply to every installed client; start a new client session after changing them.
+## Configure and update
+
+**Open the configuration page.** Run `bookmark-research` with no arguments in a terminal: the menu covers preferences and API keys, service checks, installing into another client, updates and status. The alias `bookmark` (or `bookmark research`) does the same, and `bookmark-research setup` goes straight to the wizard.
 
 | Task | Command |
 | --- | --- |
-| Menu: configure, check, install, update | `bookmark-research` |
 | Preferences and API keys | `bookmark-research setup` |
-| Installed clients, preferences, storage locations, recent research, key status | `bookmark-research status` |
-| Script preferences | `bookmark-research config show` · `bookmark-research config set --input prefs.json` |
+| Menu | `bookmark-research` · `bookmark` · `bookmark research` |
+| Clients, preferences, storage, recent research, key status | `bookmark-research status` |
+| Scripted preferences | `bookmark-research config show` · `bookmark-research config set --input prefs.json` |
 | Update or verify all clients | `bookmark-research update` · `bookmark-research verify` |
 
-Use `npx bookmark-research@latest …` if the command is not installed globally.
+Use `npx bookmark-research@beta …` if the command is not installed globally. Preferences and keys are user-wide, so one change applies to every installed client; start a new client session afterwards. `--lang zh` shows the wizard and menu in Chinese.
+
+**Update.** `bookmark-research update` refreshes every installed client from its registered source and keeps preferences, keys and data. Re-running `npx bookmark-research@beta install` also upgrades an existing Claude Code, Pi or DSH installation in place. A Codex installation keeps the source and version it was registered with; to move it to another version, remove that registration first (`codex plugin marketplace remove bookmark-research`) and install again.
 
-**API keys are optional.** Enter them in `bookmark-research setup` (hidden input, checked immediately, saved in a private local file) or set environment variables, which take precedence. Keys are never accepted in chat, command arguments or JSON files.
+**API keys are optional.** Enter them in `bookmark-research setup` (hidden input, checked immediately, saved in a private local file) or set environment variables, which take precedence.
 
 | Variable | Service | Without it |
 | --- | --- | --- |
@@ -99,9 +108,7 @@ Use `npx bookmark-research@latest …` if the command is not installed globally.
 | `JINA_API_KEY` | Jina search | Jina Reader still reads pages anonymously |
 | `OPENAI_API_KEY` | Optional OpenAI Deep Research runs | Feature off; host-led research still works |
 
-Setup also asks where research reports and evidence go: a central folder (default `<data dir>/research`, path changeable) or beside the bookmark file or folder (falls back to the central folder when that is not possible). This affects new research only; existing tasks stay where they are. It then asks whether finished research should update the Wiki: suggest pages and ask first (default), automatic, or off.
-
-Preferences (research depth, answer language, providers, archiving, output location, Wiki follow-up) can also be changed by asking the agent in a client session; it uses the `update_settings` tool.
+Keys are never accepted in chat, command arguments or JSON files. Preferences can also be changed by asking the agent in a client session ("Show Bookmark Research settings", "Use only Exa for future searches"); it uses the `update_settings` tool.
 
 ## Where data is stored
 
@@ -117,7 +124,9 @@ Nothing is written into your bookmark files or the plugin. The data directory is
 | `raw-library.sqlite3` | Rebuildable full-text index for `search_archive` |
 | `${XDG_CONFIG_HOME:-~/.config}/bookmark-research/` | `settings.json` and `credentials.json` (private, owner-only) |
 
-## Agent loops and delegation
+Changing the location affects new research only; existing tasks stay where they are.
+
+## Research loops and delegation
 
 The host model plans the research, searches or reads pages, evaluates the evidence and follows unresolved questions. The Skill guides this loop; MCP stores inputs, evidence, budgets and progress. Saving a research task does not start a background agent.
 
@@ -132,20 +141,18 @@ A bundle of one Skill, one local MCP server, and the remote MCPs and services th
 | Layer | Component | Runs as | Setup |
 | --- | --- | --- | --- |
 | Skill | [`bookmark-research`](skills/bookmark-research/SKILL.md) and 11 method references, each with a [Chinese copy](skills/bookmark-research/references/zh/skill-guide.md) | Loaded by the client | None |
-| Local MCP | `bookmark-research`, 42 tools (below; the list grows with capabilities) | Python process started by the client | Installed for you |
+| Local MCP | `bookmark-research`, 44 tools (below) | Python process started by the client | Installed for you |
 | Remote MCPs, called by the local MCP | [Exa](https://exa.ai) (search, page reading), [Parallel](https://parallel.ai) (search, fallback reading), [Tavily](https://tavily.com) (search fallback) | HTTPS, no local process | Optional API keys |
 | HTTP service, called by the local MCP | [Jina Reader](https://jina.ai/reader) (fallback reading; search with a key) | HTTPS | Optional `JINA_API_KEY` |
 | Optional client MCPs | Exa Agent, Parallel Task MCP, Tavily Research | Added to your client by you | `bookmark-research setup` shows the steps |
 
 Local MCP tools:
 
-This list describes the current source tree. `wiki_refresh` and `wiki_work` are available in local development builds and are not included in the published `0.5.0-beta.9` package. Implementation status and remaining work: [upgrade checklist](docs/upgrade-status-2026-10-11.md).
-
 | Group | Tools |
 | --- | --- |
-| Bookmarks | `sync_package`, `index_status`, `source_history`, `source_remove`, `source_merge`, `search_bookmarks`, `get_context` |
+| Bookmarks | `sync_package`, `index_status`, `source_history`, `source_remove`, `source_merge`, `search_bookmarks`, `get_context`, `plan_research` |
 | Web | `search_web`, `fetch_web`, `search_archive`, `search_providers` |
-| Research | `research_readiness`, `research_start`, `research_status`, `research_search`, `research_fetch`, `research_source`, `research_record`, `research_inventory`, `research_coverage`, `research_import_evidence`, `research_finish`, `research_route` |
+| Research | `research_readiness`, `research_start`, `research_status`, `research_search`, `research_fetch`, `research_source`, `research_record`, `research_inventory`, `research_coverage`, `research_import_evidence`, `research_finish`, `research_route`, `discovery_bundle` |
 | Research services (optional) | `research_services`, `research_service_prepare`, `_start`, `_status`, `_result`, `_cancel`, `_attach`, `_import` |
 | Settings | `get_settings`, `update_settings` |
 | Wiki and evaluation | `wiki_write`, `wiki_get`, `wiki_list`, `wiki_search`, `wiki_refresh`, `wiki_work`, `wiki_lint`, `wiki_acknowledge`, `evaluate_research` |

package/README.zh.md

@@ -5,60 +5,61 @@
 [![GitHub Bookmark-Canvas](https://img.shields.io/badge/GitHub-Bookmark--Canvas-181717?logo=github&logoColor=white)](https://github.com/Browser-bookmark-hub/Bookmark-Canvas)
 [![npm version](https://img.shields.io/npm/v/bookmark-research/beta?logo=npm)](https://www.npmjs.com/package/bookmark-research)
 
-用联网查证来研究你的书签。给它一份书签 URL 列表或 [Bookmark Canvas](https://github.com/Browser-bookmark-hub/Bookmark-Canvas) 数据包，它会逐条核对链接、搜索和阅读网页，写出带引用、可以接着做的研究报告。
-
-支持 **Codex、Claude Code、Pi、DSH（DeepSeek Harness）**。
+用联网查证来研究你的书签。给它一份书签 URL 列表或 [Bookmark Canvas](https://github.com/Browser-bookmark-hub/Bookmark-Canvas) 数据包，它会逐条核对链接、搜索和阅读网页，写出带引用、可以接着做的研究报告。支持 **Codex、Claude Code、Pi、DSH（DeepSeek Harness）**。
 
 [安装说明](docs/installation.md) · [使用指南](docs/user-guide.md) · [详细说明](docs/details.md) · [npm](https://www.npmjs.com/package/bookmark-research)
 
 > [!NOTE]
-> **0.5.0 是测试版。** 遇到问题请到 [GitHub Issues](https://github.com/Browser-bookmark-hub/Bookmark-Research/issues) 反馈。
+> **0.5.0 是测试版**，发布在 npm 的 `beta` 标签上；`latest` 标签仍指向更早的构建。遇到问题请到 [GitHub Issues](https://github.com/Browser-bookmark-hub/Bookmark-Research/issues) 反馈。
+
+## 它是怎么工作的
 
-**发布版统一从 [npm](https://www.npmjs.com/package/bookmark-research) 安装。** GitHub Releases 保留版本说明和 npm 链接，安装包／测试包附件已撤下。GitHub 自动生成的 **Source code** 压缩包是源码快照，不是安装包。
+- **本地理解层。** 数据包按结构读，而不是一张平铺的 URL 清单：卡片与分组的位置、连线的方向与标签、同一书签在不同卡片的出现位置（空间上下文）；日期字段、ID 中协议定义的日期段，以及真正改过内容的 Git 提交（时间上下文）。这些都是离线查询。
+- **外部调研走三条路线。** 读取已知 URL 不需要推理；Agentic 搜索由宿主模型自己规划、搜索、阅读并追查缺口；深度研究在此基础上加入持续清单、独立核验、覆盖检查与报告。启用后的 OpenAI Deep Research／Parallel Task API 是另一条可选路线；无头浏览器与爬虫类项目不在集成范围内。
+- **可复核的知识存储。** 完成的研究可以沉淀成 Wiki：带历史版本和相互链接的已审核页面，之后提问直接复用，不必重新搜索网页。
 
 ## 环境要求
 
-- Python 3.9+，含 SQLite FTS5（可用 `bookmark-research doctor` 检查）
-- 至少一个宿主的 CLI：Codex、Claude Code、Pi 或 DSH（DSH 另需 `pnpm`）
-- 发布版安装需要 Node 18+ 和 npm（GitHub 便捷脚本也需要）
+- Python 3.9+，含 SQLite FTS5（用 `bookmark-research doctor` 检查）
+- 至少一个宿主的 CLI：Codex、Claude Code、Pi 或 DSH。DSH 另需 `pnpm`；若用 DeepSeek Harness 桌面版自带 CLI，则它自带 pnpm，无需另装
+- 安装发布版需要 Node 18+ 和 npm
 - 安装和本地查书签都不需要 API Key
 
 ## 安装
 
-**当前测试版（`0.5.0-beta.13`）**，支持 macOS、Linux、Windows 交互安装：
-
 ```sh
-npx bookmark-research@0.5.0-beta.13 install
+npx bookmark-research@beta install
 ```
 
-安装器会自动锁定当前版本并平滑升级各宿主，无需再手动指定 `--source`。老用户或新用户均可直接执行此命令无感覆盖升级；`@beta` 标签当前指向 `0.5.0-beta.13`。
-
-**默认渠道的交互安装：**
+`@beta` 跟随最新测试版；要固定某个构建可写 `@0.5.0-beta.15`。加 `--lang zh` 可让向导显示中文。想一直能用 `bookmark-research` 命令，运行 `npm install -g bookmark-research`；GitHub 便捷脚本使用同一 npm 发布版（macOS/Linux/WSL）：
 
 ```sh
-npx bookmark-research@latest install
+curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Research/main/install.sh | bash
 ```
 
-用方向键和空格选择宿主，确认汇总后安装，再选择搜索服务、输入 API Key。装好后新建一个宿主会话。
+### 安装向导会问你什么
 
-想一直能用 `bookmark-research` 命令：`npm install -g bookmark-research`。GitHub 便捷脚本也使用同一 npm 发布版（macOS/Linux/WSL）：`curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Research/main/install.sh | bash`。
+1. **装到哪些宿主** —— 方向键移动、空格勾选；检测到的 CLI 默认已勾选，随后显示安装计划让你确认。
+2. **默认研究深度（可选）** —— 保持 `auto` 就会按每次请求自动定档；只有想钉死一个默认时才改成 `quick`、`agentic` 或 `deep`。
+3. **答复和报告语言** —— 跟随提问语言、中文或英文。
+4. **搜索与正文读取服务** —— 一个有序多选列表；未选中的服务自动作为备用搜索层。
+5. **存放位置** —— 默认数据目录、自定义统一目录（归档与研究报告），或研究报告放在书签文件／文件夹旁边。
+6. **可选专业研究 API** —— 默认关闭：OpenAI Deep Research 或 Parallel Task API。
+7. **API Key** —— 逐个隐藏输入，当场检查；全部可选，可整段跳过。
+8. **服务检查** —— 自动运行并逐个报告；样例搜索／阅读自检需另行选择。
 
-**指定宿主、不弹提示：**
+回车即保留当前选项，所以整轮可能只需按几次回车。装好后新建一个宿主会话，让 Skill 和 MCP 工具生效。Wiki 整理（默认「给出建议并先问你」）和联网前的可用性检查（默认 15 分钟缓存）都已自动开启，不需要回答。
+
+### 指定宿主、不弹提示
 
 | 宿主 | 命令 | 实际登记方式 |
 | --- | --- | --- |
-| Codex | `npx bookmark-research@latest install codex --non-interactive` | `codex plugin add` |
-| Claude Code | `npx bookmark-research@latest install claude --scope user --non-interactive` | `claude plugin install` |
-| Pi | `npx bookmark-research@latest install pi --non-interactive` | `pi install` |
-| DSH | `npx bookmark-research@latest install dsh --profile web --non-interactive` | `dsh plugin add` |
-
-**四个宿主统一发布来源：** npm 包包含共享运行时、Skill 和宿主适配。安装器下载发布包，生成所选宿主格式，再调用宿主原生命令；更新记录 npm 来源，不依赖 npx 临时缓存。GitHub 提供源码和安装清单，未发布源码用 Python 安装器。见[发布约定与官方依据](docs/distribution.md)。
-
-**DSH 可直接安装发布包：** 发布包声明 `dsh.bundle.patch`，`dsh plugin --profile <名称> add bookmark-research@<版本>`（或 DSH 插件管理界面）无需先导出即可安装，Python 与 MCP 路径按安装位置解析。DeepSeek Harness 桌面版把 `desktop` profile 保留给自身载体，该 profile 请用桌面版自带 CLI 安装。详见[安装说明](docs/installation.md)。
+| Codex | `npx bookmark-research@beta install codex --non-interactive` | `codex plugin add` |
+| Claude Code | `npx bookmark-research@beta install claude --scope user --non-interactive` | `claude plugin install` |
+| Pi | `npx bookmark-research@beta install pi --non-interactive` | `pi install` |
+| DSH | `npx bookmark-research@beta install dsh --profile web --non-interactive` | `dsh plugin add` |
 
-**Windows：** Windows 上常常没有能用的 `python3`，所以安装器会把检测到的 Python 路径写进各宿主的 MCP 配置。Codex 请用 `bookmark-research install codex` 安装，不要直接把仓库加进 Codex。`bookmark-research status` 可以查看实际使用的 Python。
-
-一次装多个：`npx bookmark-research@latest install claude dsh --profile web --non-interactive`。装到指定项目：`--scope project --project /path/to/project`（Claude Code、Pi）。全部参数见[安装说明](docs/installation.md)。
+一次装多个：`npx bookmark-research@beta install claude dsh --profile web --non-interactive`。装到指定项目：`--scope project --project /path/to/project`（Claude Code、Pi）。全部参数见[安装说明](docs/installation.md)。
 
 **让 agent 帮你装。** 把下面这段粘贴给 Codex、Claude Code、Pi 或 DSH：
 
@@ -66,30 +67,37 @@ npx bookmark-research@latest install
 请把 Bookmark Research 插件安装到你当前运行的这个宿主里。
 
 1. 先确认你自己是哪个宿主：codex、claude、pi 或 dsh。
-2. 运行：npx bookmark-research@latest install <宿主> --non-interactive
+2. 运行：npx bookmark-research@beta install <宿主> --non-interactive
    - Claude Code 或 Pi：加 --scope user（或 --scope project --project <目录>）。
    - DSH：加 --profile <名称>；profile 名称请先问我。
 3. 命令会输出 JSON。确认 "verified": true，有 "error" 就告诉我。
-4. 不要在对话里向我要 API Key。请让我在终端运行 `bookmark-research setup`
-   （或 `npx bookmark-research@latest setup`）自己输入。
+4. 不要在对话里向我要 API Key。请让我在终端运行 `bookmark-research setup` 自己输入。
 5. 提醒我新建一个会话，让 Skill 和 MCP 工具生效。
 ```
 
-## 配置与 API Key
+安装补充说明：
+
+- **npm 是四个宿主唯一的发布来源**，包内含共享运行时、Skill 和宿主适配文件。安装器下载发布包、生成该宿主需要的格式，再调用宿主原生命令登记。GitHub 提供源码、版本说明和安装清单；未发布源码用 Python 安装器。见[发布约定](docs/distribution.md)。
+- **DSH 可直接安装发布包。** 包内声明 `dsh.bundle.patch`，`dsh plugin --profile <名称> add bookmark-research@<版本>` 无需先导出即可安装。`desktop` profile 保留给 DeepSeek Harness 桌面版，请用桌面版自带 CLI 安装；安装器与向导会自行定位该 CLI。
+- **Windows** 上常常没有能用的 `python3`，所以安装器会把检测到的 Python 路径写进各宿主的 MCP 配置。Codex 请用 `bookmark-research install codex` 安装，不要直接把仓库加进 Codex；`bookmark-research status` 可以查看实际使用的 Python。
 
-不需要重新安装。配置和 Key 对所有已安装的宿主生效，修改后新建宿主会话即可。
+## 配置页与更新
+
+**进入配置页。** 在终端里不带参数运行 `bookmark-research` 就会打开菜单：修改配置与 API Key、检查服务、安装到其他宿主、更新、查看状态。别名 `bookmark`（或 `bookmark research`）等价，`bookmark-research setup` 直接进入向导。
 
 | 要做什么 | 命令 |
 | --- | --- |
-| 主菜单：配置、检查、安装、更新 | `bookmark-research` |
 | 修改偏好和 API Key | `bookmark-research setup` |
+| 打开菜单 | `bookmark-research` · `bookmark` · `bookmark research` |
 | 查看已装宿主、偏好、保存位置、最近研究、Key 状态 | `bookmark-research status` |
 | 用脚本改偏好 | `bookmark-research config show` · `bookmark-research config set --input prefs.json` |
 | 更新或验证所有宿主 | `bookmark-research update` · `bookmark-research verify` |
 
-没有全局安装时，在前面加 `npx`，例如 `npx bookmark-research@latest setup`。
+没有全局安装时，在前面加 `npx bookmark-research@beta`。偏好和 Key 是用户级的，改一次就对所有已安装宿主生效；改完新建宿主会话即可。加 `--lang zh` 可让向导和菜单显示中文。
+
+**更新。** `bookmark-research update` 会按各自登记的来源刷新所有已安装宿主，并保留偏好、Key 和数据。重跑 `npx bookmark-research@beta install` 也会就地升级已装的 Claude Code、Pi 或 DSH。Codex 安装会保留登记时的来源与版本，要换版本需先移除该登记（`codex plugin marketplace remove bookmark-research`）再重新安装。
 
-**API Key 都是可选的。** 在 `bookmark-research setup` 里输入（隐藏显示，输完当场检查，保存在仅当前用户可读的本地文件），或者设置环境变量（优先于已保存的 Key）。Key 不接受对话、命令参数或 JSON 文件。
+**API Key 都是可选的。** 在 `bookmark-research setup` 里输入（隐藏显示，输完当场检查，保存在仅当前用户可读的本地文件），或者设置环境变量（优先于已保存的 Key）。
 
 | 环境变量 | 服务 | 不配置时 |
 | --- | --- | --- |
@@ -99,9 +107,7 @@ npx bookmark-research@latest install
 | `JINA_API_KEY` | Jina 搜索 | Jina Reader 仍可匿名读取网页 |
 | `OPENAI_API_KEY` | 可选的 OpenAI Deep Research 任务 | 功能关闭；宿主自己的研究不受影响 |
 
-setup 还会问研究报告和证据放在哪里：统一目录（默认 `<数据目录>/research`，路径可改），或放在书签文件／文件夹旁边（放不了时退回统一目录）。只影响新的研究，已有任务留在原处。接着问研究结束后是否整理进 Wiki：给出建议并先问你（默认）、自动、关闭。
-
-研究深度、答复语言、服务选择、归档、结果位置、Wiki 整理这些偏好，也可以直接在宿主会话里让 agent 改，它会调用 `update_settings` 工具。
+Key 不接受对话、命令参数或 JSON 文件。偏好也可以直接在宿主会话里让 agent 改（「显示 Bookmark Research 的配置」「以后只用 Exa 搜索」），它会调用 `update_settings` 工具。
 
 ## 数据保存在哪里
 
@@ -117,6 +123,8 @@ setup 还会问研究报告和证据放在哪里：统一目录（默认 `<数
 | `raw-library.sqlite3` | `search_archive` 使用的全文索引，可重建 |
 | `${XDG_CONFIG_HOME:-~/.config}/bookmark-research/` | `settings.json` 和 `credentials.json`（仅当前用户可读） |
 
+位置设置只影响新的研究任务，已有任务留在原处。
+
 ## Agent 循环与子代理
 
 宿主模型负责规划、搜索／阅读、评估证据，再追查未解决的问题。Skill 指导这个循环，MCP 保存输入范围、证据、预算和进度；保存研究任务不会启动后台代理。
@@ -132,20 +140,18 @@ setup 还会问研究报告和证据放在哪里：统一目录（默认 `<数
 | 层 | 组成 | 运行方式 | 需要配置 |
 | --- | --- | --- | --- |
 | Skill | [`bookmark-research`](skills/bookmark-research/SKILL.md) 及 11 份方法参考，每份都有[中文版](skills/bookmark-research/references/zh/skill-guide.md) | 由宿主加载 | 不需要 |
-| 本地 MCP | `bookmark-research`，42 个工具（见下表；随能力增长） | 宿主启动的 Python 进程 | 安装器自动完成 |
+| 本地 MCP | `bookmark-research`，44 个工具（见下表） | 宿主启动的 Python 进程 | 安装器自动完成 |
 | 本地 MCP 调用的远程 MCP | [Exa](https://exa.ai)（搜索、网页读取）、[Parallel](https://parallel.ai)（搜索、备用读取）、[Tavily](https://tavily.com)（备用搜索） | HTTPS，不启动本地进程 | 可选 API Key |
 | 本地 MCP 调用的 HTTP 服务 | [Jina Reader](https://jina.ai/reader)（备用读取；有 Key 时可搜索） | HTTPS | 可选 `JINA_API_KEY` |
 | 可选的宿主 MCP | Exa Agent、Parallel Task MCP、Tavily Research | 需自行加到宿主里 | `bookmark-research setup` 会给出步骤 |
 
 本地 MCP 的工具：
 
-下表对应当前源码。`wiki_refresh` 和 `wiki_work` 已进入本地开发构建，尚未包含在已发布的 `0.5.0-beta.9` npm 包中。已实现与剩余事项见[升级核对记录](docs/upgrade-status-2026-10-11.md)。
-
 | 分类 | 工具 |
 | --- | --- |
-| 书签 | `sync_package`、`index_status`、`source_history`、`source_remove`、`source_merge`、`search_bookmarks`、`get_context` |
+| 书签 | `sync_package`、`index_status`、`source_history`、`source_remove`、`source_merge`、`search_bookmarks`、`get_context`、`plan_research` |
 | 网页 | `search_web`、`fetch_web`、`search_archive`、`search_providers` |
-| 研究 | `research_readiness`、`research_start`、`research_status`、`research_search`、`research_fetch`、`research_source`、`research_record`、`research_inventory`、`research_coverage`、`research_import_evidence`、`research_finish`、`research_route` |
+| 研究 | `research_readiness`、`research_start`、`research_status`、`research_search`、`research_fetch`、`research_source`、`research_record`、`research_inventory`、`research_coverage`、`research_import_evidence`、`research_finish`、`research_route`、`discovery_bundle` |
 | 专业研究服务（可选） | `research_services`、`research_service_prepare`、`_start`、`_status`、`_result`、`_cancel`、`_attach`、`_import` |
 | 设置 | `get_settings`、`update_settings` |
 | Wiki 与评测 | `wiki_write`、`wiki_get`、`wiki_list`、`wiki_search`、`wiki_refresh`、`wiki_work`、`wiki_lint`、`wiki_acknowledge`、`evaluate_research` |

package/bin/bookmark-research.js

@@ -22,8 +22,16 @@ if (!python) {
   process.exit(1);
 }
 
+// The same file is installed as `bookmark-research` and as the short alias
+// `bookmark`. A leading literal `research` is accepted in both spellings, so
+// `bookmark status`, `bookmark research status` and `bookmark-research status`
+// all run the same command, while `bookmark` or `bookmark research` alone
+// opens the menu.
+const args = process.argv.slice(2);
+if (args[0] === "research") args.shift();
+
 const [command, ...prefix] = python;
-const child = spawn(command, [...prefix, launcher, ...process.argv.slice(2)], { stdio: "inherit", windowsHide: true });
+const child = spawn(command, [...prefix, launcher, ...args], { stdio: "inherit", windowsHide: true });
 // The terminal delivers Ctrl+C to the whole process group; let Python handle it.
 process.on("SIGINT", () => {});
 child.on("exit", (code, signal) => process.exit(signal ? 130 : code ?? 1));