bookmark-research 0.5.0-beta.9 → 0.7.0

package/docs/bookmark-research-architecture.md

@@ -1,124 +1,13 @@
-# Bookmark Research 0.4.0 结构图
+# 三个宿主，共用三项基础能力
 
-用户可以直接用自然语言说明“查什么、查多大范围、要什么结果”，不用背固定提示词。安装并加载 Skill 后，由 Codex、Claude Code、Pi 或 DSH 理解请求，再调用插件工具执行。下面先看使用过程，再看内部结构。
+Codex、Claude Code、DeepSeek Harness 负责推理、工具选择、并发和最终表达。插件保留三项职责：
 
-| 研究方式 | 用户可以这样说 | 对书签／画布包怎样处理 | 交付 |
-| --- | --- | --- | --- |
-| ① 快速查证 `quick` | “打开包里 Exa 的官方文档，查一下它是否支持 MCP。” | 找到对应书签，读取已有 URL；找不到明确来源时，搜索后读取关键页。 | 简短答案与来源链接。 |
-| ② 主动搜索 `agentic` | “比较我收藏的搜索服务，查清检索、正文读取和研究能力的区别。” | 读取相关卡片说明、书签和分组语境；拆出问题，搜索、读文、比较，再根据证据缺口补查。 | 带证据的比较与结论。 |
-| ③ 深度研究 `deep` | “把整个 AI 调研包全量调查，核验排行榜，与我们的插件比较，交付报告和 Wiki。” | 冻结完整来源清单，按专题组织持续调查，保存证据，逐项审阅，检查遗漏与冲突后交付。 | 研究档案、覆盖明细、报告；按要求整理 Wiki。 |
+1. **上下文**：读取 JSON Canvas 节点、连接线、卡片与空间关系。时间信息保留来源与可信度；Git 历史直接交给宿主 shell。
+2. **外部调研**：已知 URL 直接读取；Agentic Search 由宿主判断缺口并迭代搜索／阅读，插件提供补充搜索、并发抓取与归档。Deep Research 可直接提交 OpenAI／Parallel API，无需本地研究会话。宿主已有的浏览器、爬虫或研究工具也可供稿。
+3. **LLM Wiki**：检索已有知识，一次提交正文与精确引用，保留来源、修订和页面关系，供后续调研复用。
 
-第一行是插件的“快速查证”流程。[OpenAI 官方文档](https://developers.openai.com/api/docs/guides/tools-web-search)中的 **Non-reasoning** 指模型不进行主动的多轮搜索规划，并不要求用户已经有 URL。插件可以提供短流程，但不会把宿主模型自动切成非推理模型。Exa、Parallel、Tavily 是供这些流程使用的检索服务，不与三种研究深度一一对应。
+日常流程是：**取上下文 → 独立检索 Wiki／归档 → 阅读与搜索 → 宿主形成结论 → 按授权保存 Wiki**。`plan_research` 只提供候选，既不设相关性硬门槛，也不决定研究路线；没有书签命中仍会查询其他存储。默认工具面为 22 个。`search_web` 聚合插件管理的 URL provider；Perplexity Search 返回结构化来源。Grok 和自定义 OpenAI 兼容端点通过 `agentic_search` 独立返回模型回答与引用，引用未经独立核验，不参加 URL 排名。宿主和其他 MCP 工具仍由宿主模型编排。
 
-默认 `research.depth=auto`：宿主根据任务判断深度，也可以遵循用户明确提出的“这次快速查证”或“这次深度研究”。`research_route` 只根据宿主报告的任务类型和可用工具建议入口；真正的工具调用、子代理启动或工作流执行由宿主发起。一般用户不需要手写这些参数。
+只有明确要求整包覆盖、持久化任务或中断后续做时，启用 `deep` 预设的完整 44 个工具及分组工作流。高级功能复用现有证据与存储；普通提问不要求经过 readiness、route、inventory 或 coverage 等阶段。
 
-```mermaid
-flowchart TB
-  Request["你说明范围、问题和交付要求"] --> Host["宿主读取 Skill<br/>判断采用哪种研究方式"]
-  Host --> Context["按任务范围定位书签<br/>读取卡片说明、文件夹、组与连线语境"]
-  Context -->|快速查证| Quick["读取目标网页<br/>必要时搜索发现来源"]
-  Context -->|主动搜索| Agentic["拆问题 → 搜索 → 读文 → 比较"]
-  Context -->|深度研究| Deep["冻结完整范围<br/>分组调查、记录证据、审阅与核验"]
-  Quick --> Answer["简短答复与来源"]
-  Agentic --> Check{"证据足够回答问题？"}
-  Check -->|还不够，补查| Agentic
-  Check -->|足够| Comparison["比较结论与证据"]
-  Deep --> Coverage{"原始来源与研究问题有缺口？"}
-  Coverage -->|有，继续调查| Deep
-  Coverage -->|完成条件满足| Report["报告与覆盖明细<br/>按要求编写 Wiki"]
-```
-
-深度研究有两条执行路线：宿主自身持续搜索、阅读、推理，必要时使用可用子代理／工作流；或者调用已启用并配置凭据的 OpenAI Deep Research API／Parallel Task API。插件实现了专业服务接口，但安装插件或在提示词里写“Deep Research”不会自动启用账户访问。实际是否可用，以当前配置和服务调用结果为准。特定宿主的专用命令，例如已加载的 Claude `/deep-research`，还要按该命令的调用方式启动。
-
-交给专业服务时，插件把明确的研究问题与选定原 URL 整理成请求；画布语境由宿主用于构造问题，本机目录不会自动变成云端可读资料。服务返回的报告进入证据档案，所引原页仍需核验，不能用一份外部报告代替整包覆盖检查。
-
-**研究深度与研究范围分别决定。** 只查一个书签就处理该书签；研究指定卡片就保留该卡片的范围；要求“研究整个包”时，默认保留整包全部原始 URL 和每个重复书签的语境。分批、子代理数量和搜索结果页数都不能缩小这个范围。深度研究中也会反复使用直接读取和主动搜索。
-
-目录、ZIP 和单卡经过同一套接入程序。书签提供要读的 URL，卡片说明、文件夹、分组和连线提供研究语境；它们保存在本地索引中。仅问“某个书签在哪张卡片”时，查本地数据即可。接入包本身不会自动开始联网研究。
-
-下面两张图对应当前 0.4.0 实现。宿主负责理解问题、模型推理、子代理或已有工作流；Plugin 提供安装封装，Skill 提供方法指令，Python 提供实际工具。CLI 和 MCP 共用同一套实现，也可以配置为共用本地数据。实线表示调用或数据流，虚线表示指令或配置影响。
-
-```mermaid
-flowchart TB
-  User["用户<br/>自然语言问题与数据包路径"] --> Host["AI 宿主<br/>Codex / Claude Code / Pi / DSH<br/>模型推理、任务组织与审阅"]
-
-  subgraph Plugin["Bookmark Research Plugin"]
-    Skill["Skill：Markdown 指令<br/>查询方法、研究规则与宿主路由"]
-    MCP["本地 MCP 入口<br/>src/mcp_server.py · 工具随能力增长（本版 40 个）"]
-    CLI["Python CLI 入口<br/>src/cli.py"]
-    Core["共用 Python 运行时<br/>Python 3.9+ 标准库"]
-    Sources["来源接入、增量同步与本地查询"]
-    Research["搜索、正文读取与研究记录"]
-    Knowledge["Wiki 保存、引用核验与质量评测"]
-    MCP --> Core
-    CLI --> Core
-    Core --> Sources
-    Core --> Research
-    Core --> Knowledge
-  end
-
-  Skill -.->|提供方法指令| Host
-  Host -->|工具调用| MCP
-  Host -->|命令调用| CLI
-  Settings["用户配置<br/>settings.json"] -.->|服务选择与存储位置| Core
-  Input["用户的画布数据<br/>目录 / ZIP / 单卡 JSON"] --> Sources
-  Research --> Remote["外部服务<br/>搜索、正文读取与可选研究 API"]
-
-  subgraph Local["本地持久化数据：位于原包和插件缓存之外"]
-    DB[("SQLite 查询索引<br/>index.sqlite3")]
-    Snapshots["来源版本快照<br/>index.sqlite3.sources/"]
-    Pages["网页响应与正文<br/>knowledge/"]
-    Runs["研究清单、证据、覆盖与报告<br/>research/"]
-    Wiki["Wiki 页面与不可变修订<br/>wiki/"]
-  end
-
-  Sources --> DB
-  Sources --> Snapshots
-  Research -->|读取书签与关系| DB
-  Research --> Pages
-  Research --> Runs
-  Knowledge -->|读取已审阅证据| Runs
-  Knowledge --> Wiki
-```
-
-各宿主的接入方式有所不同：Codex、Claude Code 使用 Skill + MCP；Pi 使用 Skill + CLI／stdio 桥，子代理工作流依赖已有扩展；DSH 使用 MCP 适配，并配置 Skill 发现和工作流服务。图中的宿主能力取决于实际安装与配置，适配实现及验证范围见[宿主支持说明](details.en.md#client-support)。
-
-SQLite 是随 Python 工具读写的本地数据库文件，用来查询书签、栏目、文件夹和画布关系，并记录来源与同步状态。它可以从来源快照重建，不需要单独启动数据库服务器。
-
-默认数据目录为 `~/.local/share/bookmark-research/`，默认配置文件为 `~/.config/bookmark-research/settings.json`。安装插件提供工具与默认设置；首次接入用户数据后才建立来源记录。本地查询无需 API 密钥，网络服务按各自的认证要求配置。
-
-数据接入与同步的关键是把**输入载体**和**来源寿命**分开。单卡中的“永久／临时”是内容类型；`snapshot`／`live` 决定后续怎样更新。
-
-```mermaid
-flowchart TB
-  Export["手动导出目录<br/>JSON + .canvas"] --> Read
-  Zip["ZIP 数据包<br/>含完整包或单卡"] --> Read
-  Card["单个卡片 JSON<br/>永久卡片 / 临时卡片"] --> Read
-  Git["GitHub 等现有同步工具"] -->|将变化同步到磁盘| Directory["长期保留的本地目录"]
-  Directory --> Read
-
-  Read["统一读取与校验<br/>source_inputs.py"] --> Register["来源登记<br/>source_manager.py<br/>source_id、路径别名、mode、completeness"]
-  Register --> Mode{"来源寿命"}
-  Mode -->|snapshot| Fixed["固定快照<br/>新导出需主动重新接入"]
-  Mode -->|live：仅目录| Live["持续目录<br/>首次接入及后续变化检查"]
-  Trigger["更新触发<br/>MCP 进程内轮询 / CLI watch<br/>查询前补检查"] --> Live
-
-  Fixed --> Sync["增量索引<br/>bookmark_index.py<br/>文件哈希比较与事务写入"]
-  Live --> Sync
-  Sync --> DB[("SQLite<br/>当前有效索引与来源状态")]
-  Sync --> Versions["来源版本快照<br/>package/：必要原始协议文件<br/>manifest.json：哈希、路径与关系"]
-  Versions -->|选择历史版本重新导入| Read
-  DB --> Query["本地书签查询与画布关系查询"]
-```
-
-新的普通导出默认使用 `snapshot`，Git 仓库内目录默认使用 `live`；已登记来源沿用原模式。同一画布换路径导出时显式沿用 `source_id`，以后记住路径别名；不同画布不会因标题或 URL 相同而合并。
-
-两种模式都会保存版本快照。局部导入保留下来的旧栏目也进入快照，因此删除原下载包后仍可使用已接入的 snapshot，并能从保存的版本恢复。默认 `completeness=partial` 保留此次未提供的文件；明确指定 `complete` 才按完整镜像删除缺失文件。已提供栏目内删除的书签仍会同步，单卡固定使用 `partial`。
-
-`live` 的后台检查跟随 MCP 进程：默认每 1 秒检查，普通变化稳定 2 秒后同步，整文件删除等待 5 秒。关闭进程后停止，重连和查询时补查。一次性 CLI 命令执行完即退出，持续监控需要运行前台 `watch`。Git 拉取、推送和登录由原有同步工具或宿主承担。
-
-无效 JSON、目录暂时消失等情况会保留上次有效索引，并返回待更新或错误状态。这部分借鉴 CodeGraph 的增量更新和恢复机制，CodeGraph 本身不是运行依赖。详细参数与恢复命令见[来源生命周期说明](../skills/bookmark-research/references/source-lifecycle.md)。
-
-普通书签查询和单个 URL 读取可以直接调用工具，无需先建立正式研究任务。正式全包研究中的搜索摘要、外部研究报告不能自动算作原始页面已读；覆盖不足时继续补查，或保存明确标记为未完成的报告。质量评测依据显式标注和运行数据，方法见[Wiki 与评测说明](wiki-quality.md)。
-
-**自动更新的边界：`live` 目录在检查时同步本地索引，不会自动抓网页、调用 LLM 或改写 Wiki。** 研究状态检查会比较冻结输入与当前索引；发生变化时提示 `source_freshness.requires_review`，Wiki 读取／核验会标记 `needs_review`。宿主据此发起补充调查和修订，旧正文、研究清单与 Wiki 修订继续保留。
+Wiki 一次写入采用 `page.sections[].citations` 与顶层 `sources`，也兼容旧的 research claim 引用格式。程序校验引文与来源完整性，语义支持由宿主或人工审阅。API 报告是二手来源，关键结论仍应核查原文。

package/docs/canvas-tree-reading-acceptance.md

@@ -0,0 +1,98 @@
+# Bookmark Canvas 树状定位手动验收
+
+本文用于在两个 GitHub 仓库的改动推送后，安装本地 Bookmark Research npm 包并重启 Codex 后验收。验收范围是新 AGENTS 模板对 Agent 的约束，以及 Bookmark Research 插件的局部树查询约束。它不验证浏览器导出代码是否已清理历史占位字段，也不授权修改书签包。
+
+## 测试前准备
+
+测试数据目录：`<画布包目录>`（例如 `~/Bookmark-Canvas/bookmark/书签画布`）。换环境时替换为实际画布包目录。
+
+1. 确认两个仓库的模板与插件改动已推送。
+2. 使用 Bookmark Research 仓库生成的本地 `.tgz` 安装/升级 Codex 插件，不从 npm 拉取线上版本。
+3. 完全退出并重启 Codex，重新打开测试数据目录对应的会话。
+4. 测试前记录包内文件列表及目标 JSON 的字节大小。不要把全包或大 JSON 全文贴进对话。
+5. 选择一个含多个层级的临时栏目 JSON。记录文件路径、栏目 ID、目标 folder/bookmark ID，以及目标附近的父子关系，作为本地核对依据。
+
+小型 JSON 可直接读入上下文；大型 JSON 必须由本地解析工具或插件索引读取必要节点。测试过程只读，不写回源文件。
+
+## 场景 A：仅模板，无 Bookmark Research 插件
+
+在 Codex 中关闭或暂时不可用 Bookmark Research MCP/Skill，只保留画布包提供的 AGENTS 模板及本地文件/终端工具。提交以下提示：
+
+> 请按当前画布包的 AGENTS 模板，只读检查临时栏目中的目标书签。先确认目标文件大小；小文件可直接阅读，大文件请用本地解析工具按目标 ID 或标题定位，不要把整份 JSON 输出到对话。按显式 `type` 区分 folder 和 bookmark，不要因 folder 有 `url: ""` 或 bookmark 有 `children: []` 而误判。请返回源文件路径、栏目/section ID、目标 item ID、准确的父级路径、同级顺序、目标的必要字段，以及为回答读取了哪些父子节点、还有哪些范围未读取。不要改文件；没有 `.canvas` 证据时不要描述卡片坐标或空间关系。
+
+分别选择一个目标书签和一个目标文件夹运行。文件夹测试需说明其直接子项与更深后代的区别；同名候选存在时必须列出候选并用 ID/路径消歧，不能按标题猜唯一结果。
+
+**通过标准**
+
+- 使用本地解析/读取工具，且大型文件没有全文进入对话上下文。
+- 目标类型以显式 `type` 判定，空占位字段没有改变判型。
+- 返回的文件路径、ID、父路径和同级顺序能与源 JSON 核对一致。
+- 明确区分已读取与未读取范围；不把局部样本称作全量检查。
+- 源文件在测试前后保持不变；不臆造 `.canvas` 坐标、分组或连线。
+
+## 场景 B：模板与 Bookmark Research 插件共同工作
+
+启用本地安装的 Bookmark Research 插件并重启 Codex。先让 Agent 报告本会话中实际可调用的 Skill/MCP 工具；不能仅凭安装成功推断工具已经加载。随后提交：
+
+> 请依照当前画布包的 AGENTS 模板，只读定位临时栏目中这个目标：`<填入目标书签标题或 item ID>`。优先使用当前会话实际可调用的 Bookmark Research 查询工具；先从指定包/source 找到唯一栏目和 section ID，再按 item ID 读取目标及祖先路径。如果目标是文件夹，请用 `folder_id` 查询其子树并按页读取，只取回答所需节点。明确报告查询的 source/section/item ID、父路径、同级位置、已读条数、总数与 `next_offset`/未读范围。请核对临时项按 `type` 判型，忽略空 `url`/`children` 对类型的干扰。插件结果是索引投影，不要将其当作完整源对象；不要修改文件。若工具不可调用，请说明并退回场景 A 的本地解析流程。
+
+至少执行三次查询：一条已知书签 ID；一个有多层后代的文件夹 ID；一个同名或重复 URL 候选（若数据中存在）。文件夹查询使用有限页大小，至少一次停在非空 `next_offset`，然后继续翻页确认分页边界。
+
+**通过标准**
+
+- 工具来自当前重启后的 Codex 会话，且检索的 source 与实际包一致；没有可用工具时清楚回退。
+- 定点结果的祖先链与 `folder_id` 子树结果能用源 JSON 核验；分页的 `total`、每页条数和下一页偏移一致。
+- 搜索结果保持书签实例、URL 和不同栏目/路径的区别；重复标题或 URL 不被错误合并为一个位置。
+- 条目投影不把空 folder URL 当作链接，也不把 bookmark 的空 children 当作文件夹；原始文件中的这些字段仍然保留。
+- 测试前后源包无变化；没有把精简索引结果写回 JSON，也没有声称未读取部分已检查。
+
+## 场景 C：增量同步（新增书签秒级可见）
+
+在已配置为 live 模式的画布包某栏目 JSON 中，手动追加一条带有唯一标题和 URL 的测试书签（记录其 item ID、title、url 及所属父节点）。
+在 Codex 中不显式执行 `sync_package`，也不重启插件，直接提交提示词：
+
+> 请定位刚在临时栏目中新增的书签：`<填入新增书签标题或 item ID>`。使用 Bookmark Research 查询工具读取其完整层级路径、父节点与同级位置。明确报告该书签当前的 revision、所在 section ID 及父路径。
+
+**通过标准**
+
+- 监控与查询层自动触发增量刷新，新增书签在秒级内可被检索工具定位。
+- 检索返回的新增书签路径、父节点及同级索引与手动编辑的源 JSON 完全一致。
+- 仅被修改文件的书签条目其 `revision` 发生递增，画布包内其他未修改文件的条目其 `revision` 与状态保持稳定。
+- 画布包内所有源文件保持只读，未被插件回写或篡改。
+
+## 场景 D：多源去重与合并（同路径重复源清理与唯一性）
+
+针对同一画布包路径下重复注册了多个旧源（例如 `index_status` 报告同路径存在多个 source_id，或旧源带着包内已不存在的文件而导致 `retained_missing_files` 非空）的场景：
+
+1. 先使用 CLI 进行干跑比对：
+   ```sh
+   python3 src/cli.py source merge <重复源ID> <保留源ID>
+   ```
+2. 确认计数与版本一致后执行正式合并（若内容哈希冲突则改用确认移除）：
+   ```sh
+   python3 src/cli.py source merge <重复源ID> <保留源ID> --confirm
+   # 或
+   python3 src/cli.py source remove <重复源ID> --confirm
+   ```
+3. 在 Codex 中提交提示：
+   ```
+   请检查当前的索引状态及源列表，确认画布包对应的源是否已唯一，且 retained_missing_files 是否已归零。
+   ```
+
+**通过标准**
+
+- 目标路径仅保留一个唯一的有效 source_id，重复源被完全移除或合并。
+- 运行 `index_status` 后，所有源的 `retained_missing_files` 计数均为 0。
+- 合并/清理后，条目检索与上下文定位均指向唯一保留源，不存在跨源冗余命中或已废弃文件的陈旧投影。
+- 整个清理过程未对画布包物理文件产生任何写操作。
+
+## 记录结果
+
+每个场景记录：Codex 会话日期、插件工具是否实际可用、测试文件大小、目标 ID、期望路径、Agent 返回路径、分页/未读范围、源文件是否变化，以及通过/失败和复现步骤。失败时保留最小提示词、目标文件相对路径与相关 ID；不要复制整份用户 JSON 到 issue 或测试文档。
+
+| 场景 | 插件实际可用 | 定点路径正确 | 分页/范围正确 | 占位字段判型正确 | 源文件未变 | 结果/备注 |
+| --- | --- | --- | --- | --- | --- | --- |
+| A：仅模板 | 否 | 待测 | 待测 | 待测 | 待测 | 待测 |
+| B：模板 + 插件 | 待测 | 待测 | 待测 | 待测 | 待测 | 待测 |
+| C：增量同步 | 待测 | 待测 | 待测 | 待测 | 待测 | 待测 |
+| D：多源去重 | 待测 | 待测 | 待测 | 待测 | 待测 | 待测 |

package/docs/configuration.en.md

@@ -0,0 +1,70 @@
+# User Settings JSON
+
+[中文](configuration.md) · **English**
+
+Bookmark Research keeps its cross-host preferences in its own `settings.json`. Configure them in the terminal wizard during installation, rerun `bookmark-research setup`, or copy and import the [partial JSON example](../config/settings.example.json). The default path is `~/.config/bookmark-research/settings.json`; `BOOKMARK_RESEARCH_CONFIG` or `XDG_CONFIG_HOME` can change it. Multiple hosts can share settings by using the same path.
+
+```sh
+bookmark-research config show
+bookmark-research config set --input /absolute/path/to/my-settings.json
+```
+
+`config set` merges the fields in this partial JSON and keeps settings you did not include. Provider names and choices go in `settings.json`; API keys go in a separate `credentials.json` beside it, or can be entered through the hidden `setup` prompt or supplied as environment variables. Environment variables take precedence. `config set --input` imports preferences only and rejects key fields. `config show` displays effective settings and the config path, never key values.
+
+## What Belongs Here
+
+Use this file for long-term preferences and connection parameters that Bookmark Research reads directly:
+
+- Search and reading sources: `search.providers`, `search.fallback_providers`, `fetch.provider`, `fetch.providers` and concurrency strategies. Perplexity provides structured URL search, not page extraction.
+- User preferences: `research.depth`, `research.response_language`, `research.methods`, `archive.enabled`, `wiki.after_research`, `output.mode`, cache and limit settings, and readiness checks.
+- Model endpoints: Base URL, model ID, protocol and search mode under `custom_agentic`. It returns a separate model answer through `agentic_search` and is not fused into `search_web` URL results.
+- Professional research APIs called directly by this plugin: the OpenAI Deep Research or Parallel Task API selection under `professional_research`.
+
+`config/settings.example.json` is an importable partial config; remove or change fields to suit your setup. Values must match the current settings schema. Invalid settings are rejected. For defaults, field details and the complete effective settings shape, see the [settings and archives reference](../skills/bookmark-research/references/settings-and-archive.md).
+
+## MCP And Credentials
+
+Do not put every MCP in the plugin's `settings.json`. MCPs launched or authorized directly by the host, such as Exa Agent, Parallel Task and Tavily Research, use host-specific endpoint, command, OAuth and header formats managed by Codex, Claude Code or DSH. The installer/setup can show connection steps, but the plugin JSON does not register host MCPs or store their OAuth credentials.
+
+When Bookmark Research calls a service through its own API, its selection and non-secret connection settings can live here; the key stays separate. For example:
+
+```json
+{
+  "custom_agentic": {
+    "enabled": true,
+    "base_url": "https://gateway.example/v1",
+    "model": "provider/model-name",
+    "api_mode": "responses",
+    "search_mode": "native"
+  }
+}
+```
+
+`search_mode: "native"` requests the Responses `web_search` tool and requires upstream support. Chat Completions can only be prompted to search; it cannot guarantee that the upstream will go online. Set the key separately as `CUSTOM_AGENTIC_API_KEY`; never put it in JSON, command-line arguments or chat.
+
+Bookmark Research accepts these API keys for its service adapters. Configure only the keys your selected services need. The setup prompt hides input and saves it for you. You can also maintain the credentials JSON directly:
+
+| Key | Service called by the plugin |
+| --- | --- |
+| `EXA_API_KEY` | Exa search and page reading |
+| `PARALLEL_API_KEY` | Parallel search and page reading |
+| `TAVILY_API_KEY` | Tavily fallback search and extraction |
+| `JINA_API_KEY` | Jina Search; Reader can fetch anonymously |
+| `DEEPSEEK_API_KEY` | DeepSeek Search / Fetch |
+| `PERPLEXITY_API_KEY` | Perplexity structured Search |
+| `XAI_API_KEY` | Grok `agentic_search` |
+| `CUSTOM_AGENTIC_API_KEY` | Custom OpenAI-compatible model endpoint |
+| `OPENAI_API_KEY` | OpenAI Deep Research |
+
+```json
+{
+  "EXA_API_KEY": "your-exa-key",
+  "PARALLEL_API_KEY": "your-parallel-key",
+  "PERPLEXITY_API_KEY": "your-perplexity-key",
+  "CUSTOM_AGENTIC_API_KEY": "your-custom-endpoint-key"
+}
+```
+
+The default path is `~/.config/bookmark-research/credentials.json`. This is an unencrypted local file and must have mode `0600` (owner-readable only). Use `setup` to save keys so the permissions are set correctly. Set `BOOKMARK_RESEARCH_CREDENTIALS` to change its path. Host-launched MCPs do not read this file; configure their keys through the host's own mechanism.
+
+You can also ask the host to call `update_settings` for a lasting preference or run `bookmark-research config show` to inspect the current config. Installation and update receipts print this guide and the command to reopen setup.

package/docs/configuration.md

@@ -0,0 +1,70 @@
+# 用户配置 JSON
+
+[English](configuration.en.md) · **中文**
+
+Bookmark Research 使用一份插件自己的 `settings.json` 保存跨宿主共享的偏好。首次安装可在终端向导中配置；之后可运行 `bookmark-research setup`，或复制本页的 [部分配置示例](../config/settings.example.json) 并导入。配置路径默认为 `~/.config/bookmark-research/settings.json`，可用 `BOOKMARK_RESEARCH_CONFIG` 或 `XDG_CONFIG_HOME` 更改。多个宿主使用同一路径即可共享设置。
+
+```sh
+bookmark-research config show
+bookmark-research config set --input /absolute/path/to/my-settings.json
+```
+
+`config set` 会按字段合并示例里的部分 JSON，不会清掉未提及的设置。provider 名称和选择写在 `settings.json`；API Key 放在同目录的独立 `credentials.json`，也可通过 `setup` 隐藏输入或环境变量设置；环境变量优先。`config set --input` 只导入偏好，不接受 Key。`config show` 会显示生效后的设置和配置路径，不显示密钥。
+
+## 放在这份 JSON 中的内容
+
+这份文件适合保存 Bookmark Research 自己读取的长期偏好和连接参数：
+
+- 搜索与读取来源：`search.providers`、`search.fallback_providers`、`fetch.provider`、`fetch.providers` 和并发策略。Perplexity 可用于结构化 URL 搜索，不能作为网页正文读取器。
+- 用户习惯：`research.depth`、`research.response_language`、`research.methods`、`archive.enabled`、`wiki.after_research`、`output.mode` 以及缓存、限额和可用性检查选项。
+- 模型端点：`custom_agentic` 中的 Base URL、模型名、协议和搜索模式。它通过独立 `agentic_search` 返回模型回答，不参加 `search_web` 的 URL 聚合。
+- 插件直接调用的专业研究服务：`professional_research` 中的 OpenAI Deep Research 或 Parallel Task API 选择。
+
+`config/settings.example.json` 是可导入的部分配置，可按需删除或修改字段。字段必须符合当前版本的设置 schema；无效值会被拒绝。配置项说明、默认值和完整有效设置结构见 [配置与归档参考](../skills/bookmark-research/references/zh/settings-and-archive.md)。
+
+## MCP 与认证的边界
+
+不要把所有 MCP 都塞进插件的 `settings.json`。Exa Agent、Parallel Task、Tavily Research 等由宿主直接启动或授权的 MCP，其 endpoint、启动命令、OAuth 和 header 格式由 Codex、Claude Code 或 DSH 自己管理；不同宿主格式不同，OAuth 凭据也应留在宿主。安装器/向导可以给出对应的接入步骤，但插件 JSON 不会注册或保存这些 host MCP。
+
+如果某个服务由 Bookmark Research 自己通过 API 调用，它的选择和非敏感连接参数可以保存在插件 JSON 中，密钥仍单独管理。例如自定义模型：
+
+```json
+{
+  "custom_agentic": {
+    "enabled": true,
+    "base_url": "https://gateway.example/v1",
+    "model": "provider/model-name",
+    "api_mode": "responses",
+    "search_mode": "native"
+  }
+}
+```
+
+`search_mode: "native"` 会请求 Responses `web_search` 工具，需要上游实现该工具；Chat Completions 只能提示上游搜索，不能保证它联网。把对应密钥单独设置为 `CUSTOM_AGENTIC_API_KEY`，不要写入 JSON、命令行参数或对话。
+
+插件支持的 API Key 与服务对应如下。只需配置已启用服务所需的 Key；用 `bookmark-research setup` 输入时会隐藏显示并自动保存。也可以手动维护凭据 JSON：
+
+| Key | 插件调用的服务 |
+| --- | --- |
+| `EXA_API_KEY` | Exa 搜索与网页读取 |
+| `PARALLEL_API_KEY` | Parallel 搜索与网页读取 |
+| `TAVILY_API_KEY` | Tavily 备用搜索与提取 |
+| `JINA_API_KEY` | Jina 搜索；Reader 可匿名读取 |
+| `DEEPSEEK_API_KEY` | DeepSeek Search / Fetch |
+| `PERPLEXITY_API_KEY` | Perplexity 结构化搜索 |
+| `XAI_API_KEY` | Grok `agentic_search` |
+| `CUSTOM_AGENTIC_API_KEY` | 自定义 OpenAI 兼容模型端点 |
+| `OPENAI_API_KEY` | OpenAI Deep Research |
+
+```json
+{
+  "EXA_API_KEY": "your-exa-key",
+  "PARALLEL_API_KEY": "your-parallel-key",
+  "PERPLEXITY_API_KEY": "your-perplexity-key",
+  "CUSTOM_AGENTIC_API_KEY": "your-custom-endpoint-key"
+}
+```
+
+默认凭据路径为 `~/.config/bookmark-research/credentials.json`，文件为未加密的本地明文，权限要求为 `0600`（仅当前用户可读）。建议用 `setup` 写入，避免手动编辑后权限不正确。可用 `BOOKMARK_RESEARCH_CREDENTIALS` 改路径。宿主直接运行的 MCP 不读取这份凭据文件；它需要的 Key 应按该宿主的方式配置。
+
+其他入口：在宿主会话中调用 `update_settings` 改长期设置；用 `bookmark-research config show` 查看当前配置。安装或升级后，收据会打印本指南和重开向导的命令。

package/docs/details.en.md

@@ -10,13 +10,13 @@ Reference material moved from the README: components, data model, research modes
 | --- | --- | --- |
 | **Skill** | [`skills/bookmark-research/SKILL.md`](../skills/bookmark-research/SKILL.md) | Guides package reading, local queries, source verification, and research reports |
 | **MCP server** | [`src/mcp_server.py`](../src/mcp_server.py), started with `python3 src/cli.py serve` | One local `bookmark-research` server with the [shared tool catalog](#mcp-tools) |
-| **Python CLI** | [`src/cli.py`](../src/cli.py) | Runs the same queries and research workflows directly, including from Pi |
-| **Web providers** | [`config/providers.json`](../config/providers.json), [`src/provider_adapters.py`](../src/provider_adapters.py), [`src/jina.py`](../src/jina.py) | Exa, Parallel, Jina HTTP and Tavily behind one MCP; schema checks, session reuse and visible partial failures |
+| **Python CLI** | [`src/cli.py`](../src/cli.py) | Runs the same queries and research workflows directly, including from a host without MCP |
+| **Web providers** | [`config/providers.json`](../config/providers.json), [`src/provider_adapters.py`](../src/provider_adapters.py), [`src/jina.py`](../src/jina.py) | Exa, Parallel, Jina HTTP, DeepSeek Search/Fetch, Perplexity structured Search and Tavily behind one MCP; Grok and custom OpenAI-compatible model answers are exposed separately |
 | **Research and coverage** | [`src/research.py`](../src/research.py), [`src/research_coverage.py`](../src/research_coverage.py) | Complete source inventory, all bookmark instances, budgets, evidence, substantive review and reports |
-| **Host workflows** | [`hosts/`](../hosts/) and [`src/routing.py`](../src/routing.py) | Native Codex delegation, Claude workflow, Pi extension recipe and DSH workflow adapter |
+| **Host workflows** | [`hosts/`](../hosts/) and [`src/routing.py`](../src/routing.py) | Native Codex delegation, Claude workflow and DSH workflow adapter |
 | **Professional research** | [`src/research_services.py`](../src/research_services.py) | Optional provider-owned background tasks, saved run IDs and secondary-report import |
-| **Wiki and evaluation** | [`src/wiki.py`](../src/wiki.py), [`src/evaluation.py`](../src/evaluation.py) | Reviewed knowledge, immutable revisions, source/link lint and metrics from explicit labels |
-| **Client integrations** | Native manifests, [`bin/bookmark-research.js`](../bin/bookmark-research.js), [`scripts/launcher.py`](../scripts/launcher.py), [`install.sh`](../install.sh), [`scripts/install.py`](../scripts/install.py) and [`scripts/export_bundle.py`](../scripts/export_bundle.py) | The `bookmark-research` command, guided installation and native install/update/verify for all four hosts |
+| **Wiki** | [`src/wiki.py`](../src/wiki.py) | Reviewed knowledge, immutable revisions, source/link lint and freshness checks |
+| **Client integrations** | Native manifests, [`bin/bookmark-research.js`](../bin/bookmark-research.js), [`scripts/launcher.py`](../scripts/launcher.py), [`install.sh`](../install.sh), [`scripts/install.py`](../scripts/install.py) and [`scripts/export_bundle.py`](../scripts/export_bundle.py) | The `bookmark-research` command (alias `bookmark`, or `bookmark research`), guided installation and native install/update/verify for all three hosts |
 
 The runtime requires Python 3.9+ and SQLite with FTS5; `doctor` checks these requirements. It uses the Python standard library and does not require a separate database service.
 
@@ -26,12 +26,9 @@ The runtime requires Python 3.9+ and SQLite with FTS5; `doctor` checks these req
 | --- | --- | --- | --- | --- |
 | **Codex** | Included | MCP | Native plugin and marketplace | Native install/update and stdio checks in isolated profiles |
 | **Claude Code** | Included | MCP | Persistent marketplace/plugin plus Dynamic Workflow | Native install/update/cache checks in isolated profiles; model execution is separate |
-| **Pi** | Included through `pi.skills` | CLI / stdio bridge | Persistent package plus project workflow registrar | Installer/adapter scenarios; subagent workflows require optional extensions |
 | **DSH / DeepSeek Harness** | Included through Skill provider | MCP through the official client | Relocatable `dsh.bundle` plus optional workflow adapter | Installer/adapter scenarios; workflows require a configured service, engine and tool |
 
-Install verification does not mean all four live clients completed a research task. Pi's basic Skill + CLI works without subagent extensions. DSH's bundle registers the Skill and resolves the bundled Python path after installation; its legacy `cordis.patch.yml` export remains specific to its original location. See [host workflows](../skills/bookmark-research/references/host-workflows.md) for optional collaboration and actual resume limits.
-
-**Agent Plugins 1.0.0** is also available as a separate standard export: root `plugin.json` + `mcp.json`. It is a package format, not another client or the Codex native manifest. See [export formats](#export-formats) for commands and the [compatibility notes (Chinese)](harness-compatibility.md) for first-party references and verification boundaries.
+Install verification does not mean all three live clients completed a research task. DSH's bundle registers the Skill and resolves the bundled Python path after installation; its legacy `cordis.patch.yml` export remains specific to its original location. See [host workflows](../skills/bookmark-research/references/host-workflows.md) for optional collaboration and actual resume limits.
 
 ## Data and query model
 
@@ -117,17 +114,17 @@ This version has no embeddings, vector database or background page monitoring. R
 | --- | --- | --- |
 | Quick lookup | Read a known URL, or search once to discover it | A concise sourced answer |
 | Agentic search | The current host model first plans, searches/reads, judges evidence and follows gaps | A sourced answer; ordinary questions need no full research session |
-| Deep research | Extend the host loop with sustained investigation, optional native collaboration, independent review and coverage checks | A persistent research archive with original inventory, evidence, coverage, report and optional Wiki |
+| Deep research | Submit the question to a research API, observe the job and review the report | A sourced report; persistent inventories and coverage audits are optional |
 
 These modes follow [OpenAI's web search guide](https://developers.openai.com/api/docs/guides/tools-web-search). Having a URL does not determine whether a model reasons. `research_route` recommends an entrypoint from reported current tools and commands without launching it. Professional APIs have separate authentication and lifecycle contracts; anonymous Search MCP access does not authorize a Task API.
 
-One MCP entry point aggregates several backend services, and one Skill executes all three workflows. Reading defaults to Exa followed by concurrent Parallel + Jina Reader fallback for unresolved URLs; Tavily extraction can be added to `fetch.providers`. Search starts with Exa + Parallel, then calls `search.fallback_providers` (Tavily + keyed Jina) concurrently only for queries with no usable URL. Missing fallback credentials are skipped; successful results stay intact. Set the search fallback list to `[]` to disable it. An existing saved search provider list without a fallback field retains its original service scope.
+One MCP entry point aggregates several backend services, and one Skill executes all three workflows. Reading starts with Exa under `fetch.strategy` (staggered by default: the next provider joins once the current one stalls past `fetch.grace_seconds`; hedged and sequential are the alternatives; abandoned providers are listed in `abandoned_providers`), then concurrent Parallel + Jina Reader fallback for unresolved URLs; Tavily extraction can be added to `fetch.providers`. `fetch.reuse_seconds` can return text saved within that window as `reused_sources` without a new request, and `search.cache_seconds` serves a repeated identical search from a short-lived cache. Search starts with Exa + Parallel under `search.strategy` (hedged by default, with staggered, sequential and wait_all alternatives) and the `search.grace_seconds` / `search.deadline_seconds` bounds; dropped or uncalled providers are listed in `routing`. Then `search.fallback_providers` (Tavily + keyed Jina) run concurrently only for queries with no usable URL. Missing fallback credentials are skipped; successful results stay intact. Set the search fallback list to `[]` to disable it. An existing saved search provider list without a fallback field retains its original service scope.
 
-The host model leads both research modes. Codex native subagents, Claude ordinary subagents or enabled teams, Pi extensions, and configured DSH subagents/workflows supply collaboration; see [host capabilities](harness-compatibility.md). The grouped package scripts are optional for batch research. Exa `agent_run`, complete Parallel Task MCP tools and enabled OpenAI/Parallel APIs can handle scoped external work after host assessment. A saved API preference orders these optional services; an explicit provider selects it exclusively. On confirmed failure, use cumulative `failed_routes` to continue the same investigation, preserving running/unknown/cancelled jobs. API execution follows prepare → start → status → result → import and requires separate credentials. Scrapling, Firecrawl and MarkItDown remain researched projects. A public GitHub README fetch does not inspect the whole repository.
+The host model leads both research modes. Codex native subagents, Claude ordinary subagents or enabled teams, and configured DSH subagents/workflows supply collaboration; see [host capabilities](harness-compatibility.md). The grouped package scripts are optional for batch research. Exa `agent_run`, complete Parallel Task MCP tools and enabled OpenAI/Parallel APIs can handle scoped external work after host assessment. A saved API preference orders these optional services; an explicit provider selects it exclusively. On confirmed failure, use cumulative `failed_routes` to continue the same investigation, preserving running/unknown/cancelled jobs. API execution follows prepare → start → status → result → import and requires separate credentials. Scrapling, Firecrawl and MarkItDown remain researched projects. A public GitHub README fetch does not inspect the whole repository.
 
 Read the [deep research guide](../skills/bookmark-research/references/deep-research.md) for inputs and CLI examples. `research_start` freezes the complete indexed packages selected by `source_ids`; a subset requires explicit `scope_mode:"subset"`. Paginate `research_inventory` to the end. `bookmark_refs` identify focus items without silently narrowing whole-package scope.
 
-`research_search` and `research_fetch` reserve retrieval attempts; repeating the same `operation_id` returns its recorded outcome. The default fetch budget accounts for the selected input size: 207 URLs require at least 26 full batches and receive 38 calls, within an 80-call limit. Explicit budgets are retained; insufficient capacity is reported without removing URLs. These controls do not measure or limit invisible host/model calls.
+`research_search` and `research_fetch` reserve retrieval attempts; repeating the same `operation_id` returns its recorded outcome. The default fetch budget accounts for the selected input size: 207 URLs require at least 13 full batches and receive 25 calls, within an 80-call limit. Explicit budgets are retained; insufficient capacity is reported without removing URLs. These controls do not measure or limit invisible host/model calls.
 
 `research_source` reads saved text. Record content acceptance, quoted claims and each original URL's substantive judgment. A rejected source or retracted claim reopens affected questions. `research_coverage` reports gaps; `research_finish` refuses completion while original-source reviews, questions, conflicts or active/unknown external runs remain unresolved. Blocked and excluded sources remain visible in the original denominator. An `incomplete` report preserves the remaining work.
 
@@ -139,7 +136,7 @@ Active tasks can continue directly. After exporting an `incomplete` report, use
 
 [Professional service tools](../skills/bookmark-research/references/research-services.md) prepare the exact brief/source payload, start once, observe the existing run, and archive its report. OpenAI cancellation is supported; Parallel cancellation is not established by this adapter. Unknown create outcomes are retained without resubmission. Imported reports remain secondary evidence and never mark all cited original URLs as read.
 
-[Wiki and quality evaluation](wiki-quality.md) track reviewed knowledge and measure supplied run results. Semantic citation accuracy requires actual reviewer labels. The included synthetic fixture demonstrates the scorer; it provides no evidence that a host, workflow or provider produces better research.
+[Wiki](../skills/bookmark-research/references/wiki.md) stores reviewed knowledge with immutable revisions, evidence links and freshness checks. It is a knowledge base, not an automatic scorer; quality claims still need actual reviewer labels and real runs.
 
 ## Duplicate bookmarks, context, and result merging
 
@@ -155,7 +152,7 @@ Duplicate item IDs within one section are identity conflicts and cause import fa
 
 Ask "Show the plugin settings," "Use only Exa for future searches," "Save page text to my knowledge directory," or "Read this page without archiving." The model uses `get_settings`, `update_settings`, or parameters for the current `fetch_web` call. There is no separate graphical settings page.
 
-Run `python3 src/cli.py setup` to revisit the terminal wizard. Before each new web research question, the Skill calls `research_readiness`: by default it refreshes checks on first use, configuration/key changes, or after 15 minutes. Choose `always` or `manual` in setup. Local bookmark queries stay offline. Readiness separates missing keys, reachable catalogs, tested retrieval, and host-managed OAuth; it never starts a professional research job.
+Run `python3 src/cli.py setup` to revisit the terminal wizard. Use `research_readiness` from the advanced catalog when diagnosing access; explicit checks refresh on first use, configuration/key changes, or after 15 minutes. Choose `always` or `manual` in setup. Local bookmark queries stay offline. Readiness separates missing keys, reachable catalogs, tested retrieval, and host-managed OAuth; it never starts a professional research job.
 
 The default configuration file is `~/.config/bookmark-research/settings.json`, created on the first update. Page archives default to `~/.local/share/bookmark-research/knowledge/`; XDG and plugin data-directory environment variables are respected. You can choose your own absolute paths. These files live outside the plugin and canvas package, so plugin updates do not replace them.
 
@@ -182,11 +179,14 @@ The [shared Skill](../skills/bookmark-research/SKILL.md) guides the agent's work
 | `index_status` | Inspect registered sources and index status |
 | `sync_package` | Import a package or synchronize changes |
 | `source_history` | List reusable source snapshots and recovery paths |
+| `source_remove` / `source_merge` | Preview or confirm removal and merging of registered sources |
 | `search_bookmarks` | Query bookmarks for multiple targets while retaining item context |
-| `get_context` | Read section, card, group, connection, and item-ancestor context |
-| `search_providers` | List configured web providers |
-| `search_web` | Search through Exa / Parallel / Tavily / keyed Jina and merge results per target |
-| `fetch_web` | Read known URLs and optionally archive responses and page text |
+| `get_context` | Read section, card, group, connection, and item-ancestor context; `compact:true` drops raw JSON, descriptions and revisions |
+| `plan_research` | Local preflight for one question: ranked cards and bookmarks, Wiki and archive pointers, relevance, freshness, fetch ownership, and a route; missing-file cards are flagged and their URLs are kept |
+| `search_providers` | List configured web providers and per-operation authentication requirements |
+| `search_web` | Search through configured Exa / Parallel / Tavily / Jina / DeepSeek / Perplexity providers and merge results per target |
+| `agentic_search` | Optional Grok or configured custom-model answer/search channel with citations; not URL-fused |
+| `fetch_web` | Read known URLs under a per-page and batch budget, optionally archive text, and continue a saved extract with `capture_id`/`offset` |
 | `search_archive` | Literal full-text search over saved page text in the knowledge archive and all research evidence, merged by content hash |
 | `get_settings` | Read current settings and storage paths |
 | `update_settings` | Update persistent settings |
@@ -201,9 +201,11 @@ The [shared Skill](../skills/bookmark-research/SKILL.md) guides the agent's work
 | `research_inventory` / `research_coverage` | Paginate original sources and compare actual review against the complete frozen scope |
 | `research_import_evidence` | Import actual host-read original text or explicitly secondary reports with provenance |
 | `research_route` | Recommend a route using current host observations and saved preferences |
+| `discovery_bundle` | Own the route-② budget check and assemble the citable evidence bundle (excerpts, then digest, then a URL list) from the sources the host read; only usable pages become evidence |
 | `research_services` / `research_service_*` | Describe, prepare, start, observe, read, cancel, attach and import optional professional runs |
-| `wiki_write` / `wiki_get` / `wiki_list` / `wiki_search` / `wiki_lint` | Maintain reviewed knowledge and immutable evidence-linked revisions |
-| `evaluate_research` | Compute metrics from explicit tasks, outputs, measurements and reviewer labels |
+| `wiki_write` / `wiki_get` / `wiki_list` / `wiki_search` / `wiki_lint` / `wiki_acknowledge` | Maintain reviewed knowledge, immutable evidence-linked revisions and input review acknowledgements |
+| `wiki_refresh` | Fetch cited URLs, record source observations and identify pages that need review |
+| `wiki_work` | Resume compilation and review using saved work states and committed publication receipts |
 
 ### Web providers
 
@@ -213,11 +215,15 @@ The [shared Skill](../skills/bookmark-research/SKILL.md) guides the agent's work
 | **Parallel** | Built into the MCP server and CLI for search and URL reading |
 | **Jina** | HTTP Reader supports anonymous webpage/PDF reading; Search requires `JINA_API_KEY`. The hosted Jina MCP is not used. |
 | **Tavily** | Built-in search fallback and selectable extraction; `TAVILY_API_KEY` uses Bearer, otherwise explicit keyless mode |
+| **DeepSeek Search / Fetch** | Optional raw JSON tools API (`/v1/tools/search`, `/v1/tools/fetch`); requires `DEEPSEEK_API_KEY`; OpenAI-compatible error shape, not a Chat Completions tool |
+| **Perplexity Search** | Optional structured Search API provider; requires `PERPLEXITY_API_KEY`; returns sources only and does not read pages |
+| **xAI Grok** | Optional Responses API tool `agentic_search`; requires `XAI_API_KEY`; returns a model answer and citations outside URL fusion |
+| **Custom model endpoint** | Optional OpenAI-compatible Chat Completions or Responses endpoint; configured Base URL/model/protocol and `CUSTOM_AGENTIC_API_KEY`; separate answer channel, upstream search support is not inferred |
 | **GitHub** | Use the host's existing GitHub MCP or `gh` for repository-specific tasks. No GitHub MCP is bundled; public pages can also be read through Exa / Parallel. |
 
-All four retrieval providers run through the plugin's own MCP or CLI; additional host MCP registrations are unnecessary. Search starts with Exa + Parallel and uses configured fallbacks for unresolved queries; reading falls back to Parallel + Jina after Exa. Anonymous/keyless access and quotas depend on each service's policy; optional credentials use `EXA_API_KEY`, `PARALLEL_API_KEY`, `TAVILY_API_KEY` or `JINA_API_KEY` in the launching environment. Local queries work offline.
+Bookmark Research aggregates only its configured providers; the host model may call other visible host/MCP search tools and compare their evidence. Search starts with Exa + Parallel under a selectable strategy (hedged by default) with a grace window and total deadline, and uses configured fallbacks for unresolved queries; Perplexity can be added to either search tier. Reading falls back to Parallel + Jina after Exa. Grok and the custom OpenAI-compatible endpoint are separate answer channels; custom search behavior depends on the configured upstream. Anonymous/keyless access and quotas depend on each service's policy; optional credentials use `EXA_API_KEY`, `PARALLEL_API_KEY`, `TAVILY_API_KEY`, `JINA_API_KEY`, `DEEPSEEK_API_KEY` or `PERPLEXITY_API_KEY` for retrieval, `XAI_API_KEY` for Grok, and `CUSTOM_AGENTIC_API_KEY` for the custom model. Local queries work offline.
 
-`search_providers` describes configuration without network access; `probe:true` discovers remote MCP tools, while Jina's HTTP mapping remains explicitly `not_probed`. Discovery does not prove successful retrieval. Each MCP process reuses remote sessions and a bounded tool catalog. Calls are not automatically replayed after errors. See [MCP architecture and observed service behavior](mcp-aggregation-0.2.0.md) for the initial implementation and checks.
+`search_providers` describes configuration without network access; `probe:true` discovers remote MCP tools, while Jina, DeepSeek and Perplexity HTTP mappings remain explicitly `not_probed`. Discovery does not prove successful retrieval. Each MCP process reuses remote sessions and a bounded tool catalog. Calls are not automatically replayed after errors. Historical implementation notes remain available in Git history.
 
 ### Package rules and AGENTS.md
 
@@ -225,32 +231,30 @@ Analysis rules are included in the Skill. The [package reading protocol](../skil
 
 Routine analysis of supported formats does not require rereading the entire package `AGENTS.md`, and the runtime does not depend on it. Consult relevant original instructions for new formats, field conflicts, or package-specific conventions. Applicable directory instructions already loaded by the client still apply.
 
+An exported guide may name this plugin as an optional read-only companion. That mention does not grant write access; the guide's hard constraints still govern any edit to the package.
+
 GitHub references and Git sync rules in a package's `AGENTS.md` do not automatically connect a GitHub service. See [GitHub and sync boundaries](../skills/bookmark-research/references/github-and-sync.md).
 
-The Skill currently produces answers and research reports. It does not generate importable bookmark packages or write changes back to source data. A future generation Skill could reuse the reading protocol with additional writing rules and validation.
+The Skill currently produces answers and research reports. It does not generate importable bookmark packages or write changes back to source data. A future generation Skill could reuse the reading protocol with additional writing rules and validation, but the package's exported guide remains the write protocol.
 
 ## Export formats
 
-This directory is the **Codex native plugin**, with its manifest at `.codex-plugin/plugin.json`. In Codex 0.153.4, the MCP configuration explicitly uses `cwd: "."` and runs `python3 src/cli.py serve` from the installed plugin directory. That native entry does not expand `${PLUGIN_ROOT}`; the Agent Plugins and Claude exports use their own path conventions.
+This directory is the **Codex native plugin**, with its manifest at `.codex-plugin/plugin.json`. In Codex 0.153.4, the MCP configuration explicitly uses `cwd: "."` and runs `python3 src/cli.py serve` from the installed plugin directory. That native entry does not expand `${PLUGIN_ROOT}`; the Claude export uses its own path convention.
 
-The Codex manifest forwards these environment variable names through `env_vars`: `BOOKMARK_RESEARCH_DATA_DIR`, `BOOKMARK_RESEARCH_CONFIG`, `XDG_DATA_HOME`, `XDG_CONFIG_HOME`, `EXA_API_KEY`, `PARALLEL_API_KEY`, `TAVILY_API_KEY`, and `OPENAI_API_KEY`. Actual paths and credentials come from the user's runtime environment.
+The Codex manifest and DSH adapter forward provider credentials including `EXA_API_KEY`, `PARALLEL_API_KEY`, `TAVILY_API_KEY`, `JINA_API_KEY`, `DEEPSEEK_API_KEY`, `PERPLEXITY_API_KEY`, `XAI_API_KEY` and `CUSTOM_AGENTIC_API_KEY`, along with the configured data/config paths. Actual paths and credentials come from the user's runtime environment.
 
 Run the relevant command **from this directory** to generate another format:
 
 ```sh
 python3 scripts/export_bundle.py --format codex --output exports/codex/bookmark-research
 python3 scripts/export_bundle.py --format claude --output exports/claude/bookmark-research
-python3 scripts/export_bundle.py --format pi --output exports/pi/bookmark-research
 python3 scripts/export_bundle.py --format dsh --output exports/dsh/bookmark-research
-python3 scripts/export_bundle.py --format agent-plugin --output exports/agent-plugin/bookmark-research
 ```
 
 The destination must be new or empty. Exports include their own English setup README with links to bundled Chinese and English user guides, and exclude indexes, caches, tests, and credentials. The exporter writes files; follow the generated README or [installation guide](installation.en.md) to load them in your client.
 
 - **Claude Code:** plugin + marketplace manifests, `.mcp.json` and a Dynamic Workflow; supports persistent native installation or session loading with `--plugin-dir`.
-- **Pi:** `package.json` declares `pi.skills`; the Skill calls the CLI. Register the project workflow for the separately installed subagent extensions when available.
 - **DSH:** a relocatable `dsh.bundle` that connects the Skill and MCP, plus the legacy absolute-path patch and workflow call generator. Workflow components remain optional and host-managed.
-- **Agent Plugins 1.0.0:** root `plugin.json` + `mcp.json`, for clients implementing that specification; generated separately from Codex's native manifest.
 
 See the [client support table](#client-support) for verification status and [compatibility notes (Chinese)](harness-compatibility.md) for format differences and official sources.
 
@@ -263,13 +267,12 @@ From this plugin directory **in a full repository checkout**, developers can run
 ```sh
 python3 -m unittest discover -s tests -v
 python3 scripts/verify_fixture.py --output /tmp/bookmark-research-verification
-python3 scripts/verify_quality.py
 python3 scripts/build_zip.py --output dist/bookmark-research-0.5.0-beta.3.zip
 python3 scripts/build_zip.py --include-tests --output dist/bookmark-research-test-pack-0.5.0-beta.3.zip
 ```
 
 The fixture verifier checks independent bookmark counts, copy-card semantics, scoped queries, unchanged source hashes, incremental sync, and a two-round research lifecycle with a failed page and resumed operation. To additionally validate your own package, append `--package /absolute/path/to/package`; this stays offline and writes derived files only to the new output directory.
 
-Network verification is explicit: `python3 tests/live_provider_smoke.py --run-live --output /tmp/provider-smoke.json` makes at most three searches and three fetches. The [0.4.0 validation record](validation-0.4.0.md) combines source lifecycle, whole-package research, bilingual instructions and host/service boundaries; [0.2.0](validation-0.2.0.md) retains the earlier provider evidence.
+Network verification is explicit: `python3 tests/live_provider_smoke.py --run-live --output /tmp/provider-smoke.json` makes at most three searches and three fetches. Historical validation records remain available in Git history.
 
 The local stdio server exposes fixed tools. Its remote client implements the selected providers' Streamable HTTP lifecycle, bounded paginated tool discovery and limited session recovery; it is not a general OAuth client or a complete MCP SDK.