bookmark-research 0.6.0 → 0.7.0

package/docs/installation.en.md

@@ -52,9 +52,11 @@ The Codex branch manages `bookmark-research@bookmark-research`. If already insta
 
 ## Guided setup and readiness
 
-After installation the wizard asks only a few questions: research depth (`auto` by default, which picks a depth from each request), answer language, search and page-reading services (one ordered multiselect; unselected providers become the fallback search tier), where archives and research results are stored (default data folder, one custom folder for both, or research reports beside the bookmark file/folder with fallback to the central folder; new tasks only), and optional professional APIs. Wiki follow-up, the pre-research availability check and connectivity checks are enabled by default (suggest and ask first, 15-minute cache, automatic) and can be changed later with `setup` or `config set`. Enter keeps displayed preferences. API-key input is masked; each key is checked immediately and can be re-entered if the check fails. Keys are saved separately in `credentials.json` next to settings, with mode `0600`; this local file is not encrypted. `BOOKMARK_RESEARCH_CREDENTIALS` overrides its path, and environment variables override saved keys. No keys enter preferences, packages, receipts or readiness output. A ChatGPT/Codex login is separate from an OpenAI API key.
+After installation, the terminal wizard asks for research depth, answer language, search sources, storage location and optional professional APIs, and can configure a custom model endpoint. In the API-key step, select the keys needed by enabled services with Space, press Enter, then enter each value at the hidden prompt. You can skip the step. Keys are saved separately in `credentials.json` next to settings, with mode `0600`; this local file is unencrypted. Environment variables override saved keys, and `BOOKMARK_RESEARCH_CREDENTIALS` changes the credential path. No key values enter preferences, packages, receipts or readiness output. A ChatGPT/Codex login is separate from an OpenAI API key.
 
-Rerun setup at any time with `python3 <installed path>/src/cli.py setup`; the exact command (`getting_started.setup_command` in the JSON result) is printed after installation. From a checkout:
+The multiselect controls search-source primary and fallback tiers. Perplexity returns structured search results but cannot read pages, so page reading still uses its separate configured provider. Setup can also configure a custom OpenAI-compatible model Base URL, model and protocol, with `CUSTOM_AGENTIC_API_KEY` entered in the hidden-key step. It is called separately through `agentic_search`, outside URL fusion. Native Responses web search is requested only when explicitly selected and supported upstream; a Chat Completions prompt cannot guarantee search.
+
+Install and update receipts print the configuration JSON guide and the command to reopen setup. Updates retain existing keys and preferences and do not prompt for keys again. To add or replace keys, run the printed `setup` command or `bookmark-research setup`. You can import partial preferences with `bookmark-research config set --input <preferences.json>`; see the [user settings JSON guide](configuration.en.md) for the schema boundary and example. The absolute setup command is also included in `getting_started.setup_command` in JSON output. From a checkout:
 
 ```sh
 python3 src/cli.py setup --host claude_code --lang en

package/docs/installation.md

@@ -69,9 +69,11 @@ Codex 分支管理 `bookmark-research@bookmark-research`。已通过 `personal`
 
 ## 向导与就绪检查
 
-安装成功后只需回答少数问题：研究深度（默认 `auto`，按每次请求自动定档）、答复语言、搜索与正文读取服务（一个有序多选列表；未选中的服务自动作为备用搜索层）、归档与研究结果的存放位置（默认数据目录、自定义统一目录，或研究报告放在书签文件／文件夹旁边、放不了时退回统一目录；只影响新任务），以及可选专业 API。Wiki 整理、联网前的可用性检查与连通性检查都按默认值自动启用（分别为「建议并先询问」「15 分钟缓存」和自动检查），可随时在后续 `setup` 或 `config set` 中修改。回车保留显示的偏好。API Key 掩码输入并立即检查，失败可重新输入；密钥单独保存为配置旁权限 `0600` 的 `credentials.json`，是本地明文文件；可用 `BOOKMARK_RESEARCH_CREDENTIALS` 指定位置。环境变量优先于保存的密钥，密钥不进入偏好 JSON、安装包、安装记录或就绪检查输出。ChatGPT／Codex 登录与 OpenAI API Key 分开。
+安装后的终端向导会询问研究深度、答复语言、搜索来源、存放位置和可选专业 API，并可配置自定义模型端点。之后的 API Key 步骤先列出 Key 名称与状态：用空格勾选已启用服务所需的 Key，按回车后在隐藏输入框逐个输入；留空或不选都可以跳过。Key 会单独保存到配置旁权限为 `0600` 的 `credentials.json`，这是未加密的本地文件；也可使用环境变量，环境变量优先。`BOOKMARK_RESEARCH_CREDENTIALS` 可指定凭据路径。Key 不会进入偏好 JSON、安装包、安装记录或就绪检查输出。ChatGPT／Codex 登录与 OpenAI API Key 分开。
 
-以后随时运行 `python3 <安装路径>/src/cli.py setup` 重开向导，完整命令（JSON 结果中的 `getting_started.setup_command`）会在安装结束时打印；在源码中可运行：
+多选项配置的是搜索来源主层与备用层；Perplexity 只提供结构化搜索结果，不能读取页面，正文读取仍使用单独配置的 provider。setup 也可配置自定义 OpenAI 兼容模型端点的 Base URL、模型和协议，并在密钥步骤设置 `CUSTOM_AGENTIC_API_KEY`。该端点经独立 `agentic_search` 调用，不参与普通 URL 聚合；原生 Responses 搜索工具需明确选择且由上游支持，普通 Chat Completions 提示不能保证联网。
+
+安装或升级收据会打印配置 JSON 指南链接和重开向导的命令。升级会保留当前 Key 和偏好，不会自动重新询问 Key；要新增、替换 Key 或改偏好，运行收据给出的 `setup` 命令，或 `bookmark-research setup`。以后也可运行 `bookmark-research config set --input <偏好文件.json>` 导入部分偏好；字段说明与可复制示例见[用户配置 JSON 指南](configuration.md)。完整安装路径命令也会在 JSON 结果的 `getting_started.setup_command` 中提供。在源码中可运行：
 
 ```sh
 python3 src/cli.py setup --host claude_code --lang zh

package/docs/instructions.en.md

@@ -18,6 +18,7 @@ Bookmark Research has one execution Skill and one runtime. The execution Skill a
 | Host workflows | [Read](../skills/bookmark-research/references/host-workflows.md) | [阅读](../skills/bookmark-research/references/zh/host-workflows.md) |
 | Professional services | [Read](../skills/bookmark-research/references/research-services.md) | [阅读](../skills/bookmark-research/references/zh/research-services.md) |
 | Settings and archives | [Read](../skills/bookmark-research/references/settings-and-archive.md) | [阅读](../skills/bookmark-research/references/zh/settings-and-archive.md) |
+| User settings JSON | [Read](configuration.en.md) | [阅读](configuration.md) |
 | GitHub and sync | [Read](../skills/bookmark-research/references/github-and-sync.md) | [阅读](../skills/bookmark-research/references/zh/github-and-sync.md) |
 | Wiki | [Read](../skills/bookmark-research/references/wiki.md) | [阅读](../skills/bookmark-research/references/zh/wiki.md) |
 | Host prompt reference | [Read](prompt-reference.en.md) | [阅读](prompt-reference.md) |

package/docs/instructions.md

@@ -18,6 +18,7 @@ Bookmark Research 共用一个执行 Skill 和一套运行时。执行 Skill 及
 | 宿主工作流 | [Read](../skills/bookmark-research/references/host-workflows.md) | [阅读](../skills/bookmark-research/references/zh/host-workflows.md) |
 | 专业研究服务 | [Read](../skills/bookmark-research/references/research-services.md) | [阅读](../skills/bookmark-research/references/zh/research-services.md) |
 | 配置与归档 | [Read](../skills/bookmark-research/references/settings-and-archive.md) | [阅读](../skills/bookmark-research/references/zh/settings-and-archive.md) |
+| 用户配置 JSON | [Read](configuration.en.md) | [阅读](configuration.md) |
 | GitHub 与同步 | [Read](../skills/bookmark-research/references/github-and-sync.md) | [阅读](../skills/bookmark-research/references/zh/github-and-sync.md) |
 | Wiki | [Read](../skills/bookmark-research/references/wiki.md) | [阅读](../skills/bookmark-research/references/zh/wiki.md) |
 | 宿主提示完整说明 | [Read](prompt-reference.en.md) | [阅读](prompt-reference.md) |

package/docs/user-guide.en.md

@@ -52,7 +52,7 @@ Ask “Show Bookmark Research settings” or run `python3 src/cli.py config show
 
 The search result limit is not a limit on package scope. Requested text length does not guarantee a complete page. Deep research always preserves its task evidence, independently of the ordinary page archive preference.
 
-Run `python3 <plugin-root>/src/cli.py setup` for guided preferences and hidden key entry. Keys come from the host environment first, then a private `credentials.json` next to settings: `EXA_API_KEY`, `PARALLEL_API_KEY`, `TAVILY_API_KEY`, `JINA_API_KEY`, and, for professional OpenAI research, `OPENAI_API_KEY`. Access and quotas depend on each provider. Host-led research needs no additional professional-service key.
+Run `python3 <plugin-root>/src/cli.py setup` for guided preferences, an optional custom OpenAI-compatible model endpoint, and hidden key entry. Keys come from the host environment first, then a private `credentials.json` next to settings, including `CUSTOM_AGENTIC_API_KEY`. Configure the custom Base URL, model and Chat Completions/Responses protocol; Responses native `web_search` is requested only when explicitly selected and supported upstream. Prompt mode cannot guarantee the upstream searches. Custom models and Grok return separate model answers and citations through `agentic_search`; citations are not independently verified or URL-fused. Perplexity Search is a structured URL-source provider. `search_web` fuses only Bookmark Research providers. The host model calls other search MCP tools visible in its current session and compares their evidence.
 
 When access needs diagnosis, the advanced `research_readiness` tool checks selected services and observed host tools. Cached/always/manual modes control frequency; local queries stay offline. Optional native MCP connection/login steps are shown by setup, with actual OAuth handled in the host. Keys, visible tools and successfully tested operations have distinct status; checks never create a paid research job. See [settings and readiness](../skills/bookmark-research/references/settings-and-archive.md).
 

package/docs/user-guide.md

@@ -52,7 +52,7 @@ MCP 进程运行期间及查询前会检查 live 目录。一次性 CLI 命令
 
 搜索结果条数不限制数据包范围；长度参数不保证完整正文。API 结果与完整审计的任务证据独立保存，不受普通网页归档开关影响。
 
-可运行 `python3 <插件根目录>/src/cli.py setup` 引导设置偏好并隐藏输入密钥。密钥优先从宿主环境读取，其次读取配置旁的私有 `credentials.json`：`EXA_API_KEY`、`PARALLEL_API_KEY`、`TAVILY_API_KEY`、`JINA_API_KEY`；OpenAI 专业研究使用 `OPENAI_API_KEY`。访问和额度取决于服务方。宿主自身研究无需另配专业研究服务密钥。
+可运行 `python3 <插件根目录>/src/cli.py setup` 引导配置偏好、可选自定义 OpenAI 兼容模型端点并隐藏输入密钥。密钥优先从宿主环境读取，其次读取配置旁的私有 `credentials.json`，包括 `CUSTOM_AGENTIC_API_KEY`。自定义端点配置 Base URL、模型和 Chat Completions／Responses 协议；Responses 原生 `web_search` 需明确启用且上游支持，提示模式也不能保证上游实际联网。自定义模型与 Grok 通过 `agentic_search` 独立返回回答和引用，不参与 URL 排名；引用不会独立核验。Perplexity Search 是结构化 URL 来源。`search_web` 只聚合 Bookmark Research 自己配置的来源；宿主模型负责调用当前会话可见的其他搜索 MCP 并综合证据。
 
 需要诊断访问问题时，可用高级 `research_readiness` 检查所选服务和已观察到的宿主工具；cached／always／manual 控制频率，本地查询保持离线。setup 展示可选原生 MCP 的接入／授权步骤，实际 OAuth 由宿主管理。已填密钥、工具可见与实际操作成功分别报告，检查不会创建付费研究任务。详见[配置与就绪检查](../skills/bookmark-research/references/zh/settings-and-archive.md)。
 

package/hosts/dsh/plugin.js

@@ -38,6 +38,9 @@ const FORWARDED_ENV = [
   "TAVILY_API_KEY",
   "JINA_API_KEY",
   "DEEPSEEK_API_KEY",
+  "PERPLEXITY_API_KEY",
+  "XAI_API_KEY",
+  "CUSTOM_AGENTIC_API_KEY",
   "OPENAI_API_KEY",
   "SystemRoot",
   "windir",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bookmark-research",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Check bookmark URLs or Canvas packages, compare sources with host-led research, and retain verifiable reports.",
   "license": "GPL-3.0-only",
   "repository": {

package/scripts/bench_sync.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""Benchmark synchronization performance across full import, no-change rescan, and single-file edit.
+
+Accepts any Canvas package directory, ZIP, or creates a synthetic package if omitted.
+Runs all tests in an isolated temporary directory without touching original data.
+
+Examples:
+    python3 scripts/bench_sync.py
+    python3 scripts/bench_sync.py /path/to/Bookmark-Canvas/bookmark/书签画布
+    python3 scripts/bench_sync.py --json
+    python3 scripts/bench_sync.py --threshold 0.05
+
+Without a path (and without BOOKMARK_RESEARCH_BENCH_PACKAGE) it benchmarks a synthetic package.
+"""
+
+import argparse
+import json
+import os
+import shutil
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "src"))
+
+from bookmark_index import BookmarkIndex
+from source_manager import SourceManager
+from source_inputs import read_input
+
+
+DEFAULT_PACKAGE = (Path(os.environ["BOOKMARK_RESEARCH_BENCH_PACKAGE"]).expanduser()
+                  if os.environ.get("BOOKMARK_RESEARCH_BENCH_PACKAGE") else None)
+
+
+def make_synthetic_package(root, sections=10, items_per_section=50):
+    root.mkdir(parents=True, exist_ok=True)
+    canvas = root / "canvas.canvas"
+    canvas.write_text(json.dumps({"nodes": [], "edges": []}, ensure_ascii=False), encoding="utf-8")
+    for s in range(sections):
+        section_dir = root / "临时栏目" / "常规链式"
+        section_dir.mkdir(parents=True, exist_ok=True)
+        items = [{"id": f"item-{s}-{i}", "sectionId": f"temp-section-{s}",
+                  "type": "bookmark", "title": f"Bookmark {s}-{i}",
+                  "url": f"https://example.test/{s}/{i}"} for i in range(items_per_section)]
+        data = {
+            "format": "bookmark-canvas-section",
+            "schemaVersion": 2,
+            "sectionType": "temporary",
+            "id": f"temp-section-{s}",
+            "label": f"T-{s}",
+            "title": f"Test Card {s}",
+            "tempKind": "regular",
+            "items": items,
+        }
+        (section_dir / f"card-{s:03d}.json").write_text(json.dumps(data, ensure_ascii=False), encoding="utf-8")
+    return root
+
+
+def run_benchmark(package_path, threshold=0.05):
+    with tempfile.TemporaryDirectory(prefix="bookmark-bench-sync-") as tmpdir:
+        work_dir = Path(tmpdir)
+        db_path = work_dir / "index.sqlite3"
+        pkg_copy = work_dir / "package"
+
+        is_synthetic = False
+        if package_path and Path(package_path).exists():
+            orig = Path(package_path).expanduser().resolve()
+            if orig.is_dir():
+                shutil.copytree(orig, pkg_copy)
+            else:
+                shutil.copyfile(orig, pkg_copy)
+        elif DEFAULT_PACKAGE is not None and DEFAULT_PACKAGE.exists():
+            shutil.copytree(DEFAULT_PACKAGE, pkg_copy)
+        else:
+            make_synthetic_package(pkg_copy)
+            is_synthetic = True
+
+        prepared = read_input(pkg_copy)
+        total_files = len(prepared["files"])
+
+        with BookmarkIndex(db_path) as index:
+            manager = SourceManager(index)
+
+            # 1. Full initial import
+            t0 = time.perf_counter()
+            full_result = manager.sync(pkg_copy, "bench_source", mode="live", completeness="complete")
+            full_duration = time.perf_counter() - t0
+
+            # 2. No-change rescan
+            t0 = time.perf_counter()
+            nochange_result = manager.refresh("bench_source", force=False)
+            nochange_duration = time.perf_counter() - t0
+
+            # 3. Single-file modification
+            # Pick one json file in the package copy and append an item
+            target_json = None
+            if pkg_copy.is_dir():
+                for p in sorted(pkg_copy.rglob("*.json")):
+                    if not p.is_symlink() and p.is_file():
+                        target_json = p
+                        break
+
+            if target_json is not None:
+                content = json.loads(target_json.read_text(encoding="utf-8"))
+                items = content.setdefault("items", [])
+                items.append({
+                    "id": "item-bench-mod-1",
+                    "sectionId": content.get("id", "bench-section"),
+                    "type": "bookmark",
+                    "title": "Bench Added Bookmark",
+                    "url": "https://example.test/bench-added"
+                })
+                time.sleep(0.01)
+                target_json.write_text(json.dumps(content, ensure_ascii=False, indent=2), encoding="utf-8")
+
+            t0 = time.perf_counter()
+            single_result = manager.refresh("bench_source", force=True)
+            single_duration = time.perf_counter() - t0
+
+        threshold_exceeded = nochange_duration > threshold
+
+        return {
+            "package_path": str(package_path or (pkg_copy if is_synthetic else DEFAULT_PACKAGE or "")),
+            "is_synthetic": is_synthetic,
+            "total_files": total_files,
+            "threshold_seconds": threshold,
+            "full_import": {
+                "duration_seconds": round(full_duration, 4),
+                "changed_files": full_result.get("changed_files", 0),
+                "skipped_files": full_result.get("skipped_files", 0),
+                "items_inserted": full_result.get("items_inserted", 0),
+                "counts": full_result.get("counts", {}),
+            },
+            "no_change_rescan": {
+                "duration_seconds": round(nochange_duration, 6),
+                "changed_files": nochange_result.get("changed_files", 0),
+                "state": nochange_result.get("state"),
+                "threshold_exceeded": threshold_exceeded,
+            },
+            "single_file_change": {
+                "duration_seconds": round(single_duration, 4),
+                "changed_files": single_result.get("changed_files", 0),
+                "items_updated": single_result.get("items_updated", 0),
+                "items_inserted": single_result.get("items_inserted", 0),
+            }
+        }
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("package", nargs="?", default=None, help="Canvas package path (directory or ZIP)")
+    parser.add_argument("--threshold", type=float, default=0.05,
+                        help="No-change rescan threshold in seconds (default 0.05 s / 50 ms)")
+    parser.add_argument("--json", action="store_true", help="Output machine-readable JSON")
+    args = parser.parse_args()
+
+    results = run_benchmark(args.package, threshold=args.threshold)
+
+    if args.json:
+        print(json.dumps(results, ensure_ascii=False, indent=2))
+    else:
+        full = results["full_import"]
+        nochange = results["no_change_rescan"]
+        single = results["single_file_change"]
+
+        print("=" * 66)
+        print("Bookmark Research — Synchronization Benchmark")
+        print(f"Target: {results['package_path']}")
+        print(f"Total protocol files: {results['total_files']}")
+        print("-" * 66)
+        print(f"1. Full Import:        {full['duration_seconds']:8.4f} s  "
+              f"(files: {full['changed_files']}, inserted: {full['items_inserted']})")
+
+        nc_status = "WARNING: EXCEEDS THRESHOLD" if nochange["threshold_exceeded"] else "OK"
+        print(f"2. No-change Rescan:   {nochange['duration_seconds']:8.6f} s  "
+              f"(changed: {nochange['changed_files']}, state: {nochange['state']}) [{nc_status}]")
+        if nochange["threshold_exceeded"]:
+            print(f"   [!] No-change rescan took {nochange['duration_seconds']*1000:.2f} ms, "
+                  f"exceeding threshold {args.threshold*1000:.1f} ms!")
+
+        print(f"3. Single-file Change: {single['duration_seconds']:8.4f} s  "
+              f"(changed: {single['changed_files']}, inserted: {single['items_inserted']}, updated: {single['items_updated']})")
+        print("=" * 66)
+
+    return 1 if results["no_change_rescan"]["threshold_exceeded"] else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/bench_tools_list.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""Capture the production stdio tools/list response and measure its length.
+
+This deliberately drives ``serve`` instead of serializing TOOL_SCHEMAS itself.
+The resulting JSON artifact records the exact response line, tool names and
+serializer so schema-size estimates cannot silently become the regression gate.
+"""
+
+import argparse
+import hashlib
+import io
+import json
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "src"))
+
+import mcp_server  # noqa: E402
+from mcp_server import _legacy_compatibility_expired, serve  # noqa: E402
+from settings import Settings  # noqa: E402
+
+
+# Frozen 2026-11-06 quick catalog for before/after host comparisons.
+LEGACY_TOOLS = (
+    "sync_package", "index_status", "search_bookmarks", "lookup_url", "get_context",
+    "traverse_graph", "plan_research", "search_web", "merge_search_results",
+    "agentic_search", "fetch_web", "search_archive", "wiki_write", "wiki_get",
+    "wiki_list", "wiki_search", "research_services", "research_service_prepare",
+    "research_service_start", "research_service_status", "research_service_result",
+    "research_service_cancel", "research_service_attach", "get_settings", "update_settings",
+)
+PRESETS = ("quick", "legacy", "deep", "all")
+
+
+def _request(method, request_id=None, params=None):
+    value = {"jsonrpc": "2.0", "method": method}
+    if request_id is not None:
+        value["id"] = request_id
+    if params is not None:
+        value["params"] = params
+    return value
+
+
+def capture(preset, db_path=":memory:", excluded=()):
+    """Return the parsed tools/list response and its exact emitted line."""
+    if preset == "legacy" and _legacy_compatibility_expired(mcp_server.release_version()):
+        raise ValueError("The legacy tool surface ended at 0.8.0")
+    temporary = tempfile.TemporaryDirectory(prefix="bookmark-tools-list-")
+    old_scope = os.environ.get("BOOKMARK_RESEARCH_TOOL_SCOPE")
+    try:
+        # Use an isolated settings file and an explicit environment scope so a
+        # measurement cannot rewrite the user's config or inherit its preset.
+        settings = Settings(Path(temporary.name) / "settings.json")
+        if preset == "quick":
+            names = [name for name in Settings.QUICK_TOOLS if name not in excluded]
+            os.environ["BOOKMARK_RESEARCH_TOOL_SCOPE"] = ",".join(names)
+        elif preset == "legacy":
+            names = [name for name in LEGACY_TOOLS if name not in excluded]
+            os.environ["BOOKMARK_RESEARCH_TOOL_SCOPE"] = ",".join(names)
+        elif excluded:
+            from mcp_server import TOOL_SCHEMAS
+            names = [name for name in TOOL_SCHEMAS if name not in excluded]
+            os.environ["BOOKMARK_RESEARCH_TOOL_SCOPE"] = ",".join(names)
+        else:
+            # Empty override deliberately exposes the full catalog for all/deep.
+            os.environ["BOOKMARK_RESEARCH_TOOL_SCOPE"] = ""
+        incoming = "\n".join([
+            json.dumps(_request("initialize", 1, {"protocolVersion": "2025-11-25",
+                                                   "capabilities": {},
+                                                   "clientInfo": {"name": "bench-tools-list", "version": "1"}}),
+                       ensure_ascii=False),
+            json.dumps(_request("notifications/initialized"), ensure_ascii=False),
+            json.dumps(_request("tools/list", 2), ensure_ascii=False),
+            "",
+        ])
+        stdout, stderr = io.StringIO(), io.StringIO()
+        serve(db_path, stdin=io.StringIO(incoming), stdout=stdout, stderr=stderr,
+              settings=settings, workers=1, max_pending=1)
+        lines = stdout.getvalue().splitlines(keepends=True)
+        response_line = next((line for line in lines
+                              if json.loads(line).get("id") == 2), None)
+        if response_line is None:
+            raise RuntimeError("stdio tools/list response was not emitted: " + stdout.getvalue())
+        response = json.loads(response_line)
+        if "error" in response:
+            raise RuntimeError("tools/list failed: " + response["error"].get("message", "unknown error"))
+        tools = response["result"]["tools"]
+        return response, response_line, tools
+    finally:
+        if old_scope is None:
+            os.environ.pop("BOOKMARK_RESEARCH_TOOL_SCOPE", None)
+        else:
+            os.environ["BOOKMARK_RESEARCH_TOOL_SCOPE"] = old_scope
+        temporary.cleanup()
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--preset", choices=PRESETS, default="quick")
+    parser.add_argument("--db", default=":memory:")
+    parser.add_argument("--exclude", action="append", default=[], help="Exclude a tool for a pre-change comparison")
+    parser.add_argument("--out", type=Path, default=Path(".bench/tools-list.json"))
+    args = parser.parse_args(argv)
+    response, line, tools = capture(args.preset, db_path=args.db, excluded=args.exclude)
+    serializer = "json.dumps(ensure_ascii=False, allow_nan=False, separators=(',', ':')) + '\\n'"
+    artifact = {
+        "preset": args.preset,
+        "excluded": args.exclude,
+        "tool_count": len(tools),
+        "tool_names": [tool["name"] for tool in tools],
+        "response_characters": len(line),
+        "response_sha256": hashlib.sha256(line.encode("utf-8")).hexdigest(),
+        "serializer": serializer,
+        "response": response,
+    }
+    args.out.parent.mkdir(parents=True, exist_ok=True)
+    args.out.write_text(json.dumps(artifact, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    print(json.dumps({key: artifact[key] for key in
+                      ("preset", "excluded", "tool_count", "response_characters", "response_sha256")},
+                     ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/evaluate_ladder.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""Validate and summarize a 15-question research ladder capture.
+
+The harness-specific runs are supplied as JSON so Codex/Claude/dsh can capture
+their own traces without the evaluator pretending to run those hosts. Each
+question needs three runs, Q1 and Q3-Q5 counts per run, and human Q2 claim
+annotations for the median-step run.
+"""
+
+import argparse
+import json
+import statistics
+import sys
+from pathlib import Path
+
+
+CATEGORIES = ("L1", "L2", "L3", "L4", "L5")
+
+
+def template():
+    return {
+        "schema_version": 1,
+        "baseline_id": "",
+        "tool_surface": "",
+        "questions": [
+            {"id": "%s-%s" % (category, number), "category": category,
+             "prompt": "", "target_refs": [], "runs": []}
+            for category in CATEGORIES for number in range(1, 4)
+        ],
+    }
+
+
+def evaluate(data):
+    if not isinstance(data, dict) or not isinstance(data.get("questions"), list):
+        raise ValueError("input must contain a questions array")
+    questions = data["questions"]
+    if len(questions) != 15:
+        raise ValueError("the ladder must contain exactly 15 questions")
+    ids, categories = set(), {category: 0 for category in CATEGORIES}
+    all_runs = []
+    q2_missing = []
+    for question in questions:
+        if not isinstance(question, dict) or not question.get("id"):
+            raise ValueError("each question needs an id")
+        if question["id"] in ids:
+            raise ValueError("question IDs must be unique")
+        ids.add(question["id"])
+        category = question.get("category")
+        if category not in categories:
+            raise ValueError("question category must be one of " + ", ".join(CATEGORIES))
+        categories[category] += 1
+        if not isinstance(question.get("prompt"), str) or not question["prompt"].strip():
+            raise ValueError("question %s has no frozen prompt" % question["id"])
+        runs = question.get("runs")
+        if not isinstance(runs, list) or len(runs) < 3:
+            raise ValueError("question %s needs at least three runs" % question["id"])
+        for run in runs:
+            if not isinstance(run, dict):
+                raise ValueError("runs must be objects")
+            for field in ("steps", "wall_seconds", "q1_matches", "q1_citations",
+                          "q3_content_state_misses", "q4_silent_truncations", "q5_coverage_gaps"):
+                if field not in run:
+                    raise ValueError("run for %s is missing %s" % (question["id"], field))
+            if type(run["steps"]) is not int or run["steps"] < 0:
+                raise ValueError("steps must be a non-negative integer")
+            if not isinstance(run["wall_seconds"], (int, float)) or run["wall_seconds"] < 0:
+                raise ValueError("wall_seconds must be non-negative")
+            if type(run["q1_matches"]) is not int or type(run["q1_citations"]) is not int:
+                raise ValueError("Q1 counts must be integers")
+            if run["q1_matches"] < 0 or run["q1_citations"] < run["q1_matches"]:
+                raise ValueError("invalid Q1 match counts")
+            for field in ("q3_content_state_misses", "q4_silent_truncations", "q5_coverage_gaps"):
+                if type(run[field]) is not int or run[field] < 0:
+                    raise ValueError(field + " must be a non-negative integer")
+            all_runs.append(run)
+        median_steps = statistics.median(run["steps"] for run in runs)
+        median_run = next(run for run in runs if run["steps"] == median_steps)
+        if "q2_claims" not in median_run:
+            q2_missing.append(question["id"])
+        elif not isinstance(median_run["q2_claims"], list):
+            raise ValueError("q2_claims must be a list of human annotations")
+        else:
+            for claim in median_run["q2_claims"]:
+                if not isinstance(claim, dict) or claim.get("supported") not in (True, False):
+                    raise ValueError("each Q2 annotation needs a boolean supported field")
+                if not isinstance(claim.get("claim"), str) or not isinstance(claim.get("source_ids"), list):
+                    raise ValueError("each Q2 annotation needs claim text and source_ids")
+    if any(count != 3 for count in categories.values()):
+        raise ValueError("the ladder requires exactly three questions in each L1-L5 category")
+    citations = sum(run["q1_citations"] for run in all_runs)
+    q1_matches = sum(run["q1_matches"] for run in all_runs)
+    claim_rows = [claim for question in questions for run in question["runs"]
+                  if run["steps"] == statistics.median(r["steps"] for r in question["runs"])
+                  for claim in run.get("q2_claims", [])]
+    supported = sum(claim["supported"] is True for claim in claim_rows)
+    summary = {
+        "baseline_id": data.get("baseline_id"),
+        "tool_surface": data.get("tool_surface"),
+        "question_count": len(questions),
+        "run_count": len(all_runs),
+        "category_counts": categories,
+        "median_steps": statistics.median(statistics.median(run["steps"] for run in q["runs"])
+                                           for q in questions),
+        "median_wall_seconds": statistics.median(statistics.median(run["wall_seconds"] for run in q["runs"])
+                                                  for q in questions),
+        "q1": {"matches": q1_matches, "citations": citations,
+               "rate": q1_matches / citations if citations else None},
+        "q2": {"supported_claims": supported, "claims": len(claim_rows),
+               "rate": supported / len(claim_rows) if claim_rows else None,
+               "missing_median_run_annotations": q2_missing},
+        "q3_content_state_misses": sum(run["q3_content_state_misses"] for run in all_runs),
+        "q4_silent_truncations": sum(run["q4_silent_truncations"] for run in all_runs),
+        "q5_coverage_gaps": sum(run["q5_coverage_gaps"] for run in all_runs),
+        "gate_pass": bool(citations and not q2_missing and q1_matches == citations and
+                           not any(run["q3_content_state_misses"] or run["q4_silent_truncations"] or
+                                   run["q5_coverage_gaps"] for run in all_runs)),
+    }
+    return summary
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("input", type=Path, nargs="?", help="Harness ladder JSON with frozen questions and run traces")
+    parser.add_argument("--template", action="store_true", help="Write an empty L1-L5, 15-question capture template")
+    parser.add_argument("--out", type=Path, default=Path(".bench/ladder-summary.json"))
+    args = parser.parse_args(argv)
+    try:
+        if args.template:
+            if args.input is None:
+                raise ValueError("provide an output path as input with --template")
+            args.input.parent.mkdir(parents=True, exist_ok=True)
+            args.input.write_text(json.dumps(template(), ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+            print(json.dumps({"template": str(args.input), "questions": 15}, ensure_ascii=False))
+            return 0
+        if args.input is None:
+            raise ValueError("provide a ladder JSON input, or use --template <path>")
+        data = json.loads(args.input.read_text(encoding="utf-8"))
+        result = evaluate(data)
+        args.out.parent.mkdir(parents=True, exist_ok=True)
+        args.out.write_text(json.dumps(result, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+        print(json.dumps(result, ensure_ascii=False))
+        return 0 if result["gate_pass"] else 2
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        print(json.dumps({"error": str(error)}, ensure_ascii=False), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/export_bundle.py

@@ -30,6 +30,8 @@ REQUIRED_FILES = (
     "src/bookmark_index.py",
     "src/cli.py",
     "src/credentials.py",
+    "src/perplexity.py",
+    "src/grok_search.py",
     "src/onboarding.py",
     "src/package_paths.py",
     "src/readiness.py",

package/scripts/host_install.py

@@ -127,7 +127,10 @@ def runtime_check(root, timeout):
             raise RuntimeError("Exported MCP runtime failed to start")
         responses = {row.get("id"): row for row in map(json.loads, mcp.stdout.splitlines())}
         names = sorted(row["name"] for row in responses.get(2, {}).get("result", {}).get("tools", []))
-        if "result" not in responses.get(1, {}) or not {"search_bookmarks", "search_web", "fetch_web"} <= set(names):
+        available = set(names)
+        has_runtime_surface = ({"locate", "search", "fetch"} <= available or
+                               {"search_bookmarks", "search_web", "fetch_web"} <= available)
+        if "result" not in responses.get(1, {}) or not has_runtime_surface:
             raise RuntimeError("Exported MCP runtime did not expose the expected tools")
         if (data / "data/index.sqlite3").exists():
             raise RuntimeError("Runtime discovery unexpectedly created a database")