bookmark-research 0.5.0-beta.1

package/scripts/launcher.py

@@ -0,0 +1,186 @@
+"""The `bookmark-research` command: install, configure, check and update from one entry."""
+
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "scripts"))
+sys.path.insert(0, str(ROOT / "src"))
+
+USAGE = """usage: bookmark-research [--lang auto|en|zh] [COMMAND] [ARGS...]
+
+  (no command)          Open the menu in a terminal; print status JSON otherwise
+  install [HOST...]     Install into hosts: codex, claude, pi, dsh (wizard when omitted)
+  update [HOST...]      Update installed hosts (all when omitted)
+  verify [HOST...]      Verify installed hosts (all when omitted)
+  setup                 Preferences, services, hidden API-key entry and checks
+  status                Installed hosts, preferences and key status as JSON
+  config show|set       View or change preferences (set reads --input FILE or -)
+  doctor                Check Python and SQLite FTS5
+
+Other options are passed through, e.g. install claude dsh --profile web --non-interactive.
+API keys are never accepted as arguments: use setup or environment variables.
+"""
+
+
+def install_home():
+    data = Path(os.environ.get("XDG_DATA_HOME", str(Path.home() / ".local/share"))).expanduser()
+    if not data.is_absolute():
+        data = Path.home() / ".local/share"
+    return Path(os.environ.get("BOOKMARK_RESEARCH_INSTALL_DIR", str(data / "bookmark-research/installations"))).expanduser()
+
+
+def installed_targets(codex="codex"):
+    """Read managed receipts and the Codex registry; never contacts a network service."""
+    rows = []
+    home = install_home()
+    for receipt in sorted(home.glob("*/receipt.json")) if home.is_dir() else []:
+        try:
+            value = json.loads(receipt.read_text(encoding="utf-8"))
+            target = value["target"]
+        except (OSError, ValueError, KeyError, TypeError):
+            continue
+        rows.append({"host": target.get("host"), "scope": target.get("scope"), "project": target.get("project"),
+                     "profile": target.get("profile"), "version": value.get("version"), "state": value.get("state")})
+    try:
+        from install import CodexCli, _installed
+        import shutil
+        if shutil.which(codex):
+            plugin = _installed(CodexCli(codex, 30))
+            if plugin:
+                rows.insert(0, {"host": "codex", "scope": None, "project": None, "profile": None,
+                                "version": plugin.get("version"), "state": "installed"})
+    except (OSError, ValueError, RuntimeError, subprocess.TimeoutExpired):
+        pass
+    return rows
+
+
+def status():
+    from credentials import Credentials
+    from settings import Settings
+    settings = Settings()
+    current = settings.load()
+    return {"hosts": installed_targets(),
+            "preferences": {"depth": current["research"]["depth"], "language": current["research"]["response_language"],
+                            "search": current["search"]["providers"], "fallback": current["search"]["fallback_providers"],
+                            "readers": Settings.fetch_providers(current), "archive": current["archive"]["enabled"]},
+            "credentials": {row["name"]: row["source"] or "missing" for row in Credentials(settings).describe()["credentials"]},
+            "settings_path": str(settings.path)}
+
+
+def _split(arguments):
+    hosts, rest = [], []
+    for index, value in enumerate(arguments):
+        if value.startswith("-"):
+            rest = arguments[index:]
+            break
+        hosts.extend(part for part in value.split(",") if part)
+    return hosts, rest
+
+
+def _install_action(action, arguments, language):
+    import install
+    hosts, rest = _split(arguments)
+    if not hosts and action != "install" and "--host" not in rest:
+        targets = installed_targets()
+        if not targets:
+            print(json.dumps({"error": "Nothing is installed yet; run bookmark-research install"}), file=sys.stderr)
+            return 1
+        codes = []
+        for row in targets:
+            extra = ["--host", row["host"]]
+            for key in ("scope", "project", "profile"):
+                if row.get(key):
+                    extra += ["--" + key, row[key]]
+            codes.append(install.main([action, "--lang", language, *extra, *rest]))
+        return max(codes)
+    return install.main([action, "--lang", language, *[item for host in hosts for item in ("--host", host)], *rest])
+
+
+def _cli(arguments, language):
+    command = [sys.executable, str(ROOT / "src/cli.py"), *arguments]
+    if arguments and arguments[0] == "setup" and "--lang" not in arguments:
+        command += ["--lang", language]
+    return subprocess.call(command)
+
+
+def run(arguments, language):
+    if not arguments:
+        return menu(language)
+    command, rest = arguments[0], arguments[1:]
+    if command in ("-h", "--help", "help"):
+        print(USAGE)
+        return 0
+    if command in ("install", "update", "verify"):
+        return _install_action(command, rest, language)
+    if command == "status":
+        print(json.dumps(status(), ensure_ascii=False, indent=2))
+        return 0
+    if command in ("setup", "config", "doctor"):
+        return _cli([command, *rest], language)
+    print(USAGE, file=sys.stderr)
+    return 2
+
+
+def menu(language):
+    from onboarding import Console
+    with Console.open("auto", Console.resolve_language(language)) as console:
+        if console is None:
+            print(json.dumps(status(), ensure_ascii=False, indent=2))
+            return 0
+        console.intro("Bookmark Research", "Bookmark Research")
+        while True:
+            current = status()
+            hosts = ", ".join(row["host"] + ("(" + (row["profile"] or row["scope"] or "") + ")" if row["profile"] or row["scope"] else "")
+                              for row in current["hosts"]) or console.text("none", "无")
+            missing = [name.split("_")[0].lower() for name, source in current["credentials"].items() if source == "missing"]
+            console.say("Installed: " + hosts, "已安装：" + hosts)
+            console.say("Search: " + ", ".join(current["preferences"]["search"]) + ("  · keys missing: " + ", ".join(missing) if missing else ""),
+                        "搜索服务：" + ", ".join(current["preferences"]["search"]) + ("  · 未配置密钥：" + ", ".join(missing) if missing else ""))
+            choice = console.select("What would you like to do?", "要做什么？", _menu_options(), "setup")
+            if choice == "exit":
+                console.outro("Bye.", "再见。")
+                return 0
+            code = {"setup": lambda: _cli(["setup"], console.language),
+                    "check": lambda: _cli(["setup", "--non-interactive"], console.language),
+                    "install": lambda: _install_action("install", ["--interactive"], console.language),
+                    "update": lambda: _install_action("update", [], console.language),
+                    "status": lambda: print(json.dumps(status(), ensure_ascii=False, indent=2)) or 0}[choice]()
+            if code:
+                console.warn("Finished with exit code %s." % code, "结束，退出码 %s。" % code)
+
+
+def _menu_options():
+    from tui import Option
+    return [Option("setup", "Change preferences and API keys", "修改配置与 API Key"),
+            Option("check", "Check services", "检查服务是否可用"),
+            Option("install", "Install into another host", "安装到其他宿主"),
+            Option("update", "Update installed hosts", "更新已安装宿主"),
+            Option("status", "Show status JSON", "查看状态（JSON）"),
+            Option("exit", "Exit", "退出")]
+
+
+def main(argv=None):
+    from textio import utf8_stdio
+    utf8_stdio()
+    arguments = list(sys.argv[1:] if argv is None else argv)
+    language = "auto"
+    if arguments[:1] == ["--lang"] and len(arguments) > 1:
+        language, arguments = arguments[1], arguments[2:]
+    elif arguments and arguments[0].startswith("--lang="):
+        language, arguments = arguments[0].split("=", 1)[1], arguments[1:]
+    if language not in ("auto", "en", "zh"):
+        print("--lang must be auto, en or zh", file=sys.stderr)
+        return 2
+    from install import resolve_language
+    try:
+        return run(arguments, resolve_language(language))
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/verify_fixture.py

@@ -0,0 +1,220 @@
+#!/usr/bin/env python3
+"""Offline validation pack: source fidelity, context and a research lifecycle.
+
+Default inputs are synthetic. --package additionally checks a user-supplied
+package without changing it or sending anything to web providers.
+"""
+
+import argparse
+import hashlib
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "src"))
+from bookmark_index import BookmarkIndex
+from research import ResearchSessions
+from search_results import fuse_results
+from settings import Settings
+
+
+def fingerprints(package):
+    return {path.relative_to(package).as_posix(): hashlib.sha256(path.read_bytes()).hexdigest()
+            for path in sorted(package.rglob("*")) if path.is_file()}
+
+
+def raw_counts(package):
+    urls = []
+    sections = 0
+    def walk(items):
+        for item in items:
+            if isinstance(item.get("url"), str) and item["url"]:
+                urls.append(item["url"])
+            walk(item.get("children", []))
+    for path in package.rglob("*.json"):
+        value = json.loads(path.read_text(encoding="utf-8"))
+        if value.get("format") != "bookmark-canvas-section":
+            continue
+        sections += 1
+        if value.get("fileRole") == "copy-anchor":
+            continue
+        walk([value["tree"]] if "tree" in value else value.get("items", []))
+    return {"bookmarks": len(urls), "unique_urls": len(set(urls)), "sections": sections}
+
+
+class FixtureProvider:
+    """Recorded fictional responses; never instantiates a network client."""
+
+    def __init__(self, fixture):
+        self.fixture = fixture
+
+    def search(self, targets, providers, limit_per_target):
+        batches = [{"provider": provider, "target": target["target"], "query": target["query"],
+                    "status": "ok", "retrieved_at": "2026-09-10T00:00:00Z", "results": [
+                        {"url": url, "title": self.fixture["pages"][url].get("title", "Unavailable fixture"),
+                         "snippet": "Synthetic search snippet; read the fixture page for evidence."}
+                        for url in self.fixture["search_results"][target["target"]]]}
+                   for provider in providers for target in targets]
+        return {**fuse_results({"batches": batches, "limit_per_target": limit_per_target}),
+                "batches": batches, "usage": {"tool_calls": len(batches)}}
+
+    def fetch(self, urls, provider, archive, max_characters):
+        rows = [{"url": url, **self.fixture["pages"].get(url, {"error": "No synthetic response recorded for this URL"})}
+                for url in urls]
+        return {"provider": provider, "urls": urls, "tool": "fixture_fetch", "request_arguments": {"urls": urls},
+                "retrieved_at": "2026-09-10T00:00:00Z", "requested_max_characters": max_characters,
+                "usage": {"tool_calls": 1}, "result": {"structuredContent": {"results": rows}}}
+
+
+def verify_package(package, output, expected=None, queries=()):
+    before = fingerprints(package)
+    expected_raw = raw_counts(package)
+    with BookmarkIndex(output / "index.sqlite3") as index:
+        first = index.sync(package, "validation")
+        status = index.status("validation")
+        for name, number in {**expected_raw, **(expected or {})}.items():
+            if status["counts"][name] != number:
+                raise ValueError("Count mismatch for %s: raw/fixture=%s, index=%s" % (name, number, status["counts"][name]))
+        second = index.sync(package, "validation")
+        if second["changed_files"] != 0:
+            raise ValueError("An unchanged package was not recognized incrementally")
+        for case in queries:
+            options = {key: value for key, value in case.items() if key != "total"}
+            if index.search("validation", **options)["total"] != case["total"]:
+                raise ValueError("Fixture scope query returned the wrong count")
+        context = index.context("validation")
+        inventory = index.inventory(["validation"])
+    if (inventory["counts"]["unique_urls"] != status["counts"]["unique_urls"] or
+            inventory["counts"]["bookmark_instances"] != status["counts"]["bookmarks"]):
+        raise ValueError("Complete inventory changed the raw URL or bookmark-instance counts")
+    for source_file in inventory["files"]:
+        if before.get(source_file["file_path"]) != source_file["sha256"]:
+            raise ValueError("Inventory source hash differs from the original file")
+    sessions = ResearchSessions(output / "inventory-research", settings=Settings(output / "settings.json"),
+                                db_path=output / "index.sqlite3")
+    frozen = sessions.start("Offline inventory acceptance", [{"id": "q1", "question": "Were all original input IDs preserved?"}],
+                            source_ids=["validation"], providers=["exa"])
+    rows, offset, pages = [], 0, 0
+    while offset is not None:
+        page = sessions.inventory(frozen["research_id"], offset=offset, limit=100)
+        rows.extend(page["items"])
+        offset = page["next_offset"]
+        pages += 1
+    if [row["id"] for row in rows] != [row["id"] for row in inventory["entries"]]:
+        raise ValueError("Frozen research inventory pagination lost or reordered inputs")
+    manifest_path = Path(frozen["inventory_manifest"])
+    if json.loads(manifest_path.read_text(encoding="utf-8")) != inventory:
+        raise ValueError("Frozen manifest lost original bookmark metadata or relationships")
+    sessions.finish(frozen["research_id"], "Offline inventory inspection only; source pages were not read.",
+                    status="incomplete", limitations=["This is source-preservation acceptance, not substantive research."])
+    if before != fingerprints(package):
+        raise ValueError("Source package changed during validation")
+    return {"counts": status["counts"], "source_files": len(before), "source_sha256": before,
+            "source_unchanged": True, "unchanged_second_sync": True,
+            "scope_queries_checked": len(queries), "warnings": first.get("warnings", []),
+            "context_nodes": len(context["nodes"]),
+            "inventory": {"counts": inventory["counts"], "input_version": inventory["input_version"],
+                          "manifest_path": str(manifest_path), "manifest_sha256": hashlib.sha256(manifest_path.read_bytes()).hexdigest(),
+                          "pages_read": pages, "all_ids_preserved": True, "whole_scope_preserved": True,
+                          "initial_fetch_plan": frozen["initial_fetch_plan"]}}
+
+
+def verify_research(fixture, output):
+    sessions = ResearchSessions(output / "research", settings=Settings(output / "settings.json"),
+                                engine=FixtureProvider(fixture), db_path=output / "fixture/index.sqlite3")
+    with BookmarkIndex(output / "fixture/index.sqlite3") as index:
+        rows = index.search("validation", targets=["https://docs.example.test/search"])["results"]
+    refs = [{key: row[key] for key in ("source_id", "section_id", "item_id")} for row in rows]
+    task = sessions.start(**fixture["brief"], bookmark_refs=refs)
+    identifier = task["research_id"]
+    inventory = sessions.inventory(identifier)["items"]
+    by_url = {row["original_url"]: row["id"] for row in inventory}
+
+    def review(source, question):
+        source_id = source["id"]
+        entry = {"kind": "inventory_review", "inventory_id": by_url[source["url"]]}
+        if source["body_file"] is None:
+            sessions.record(identifier, {**entry, "disposition": "blocked",
+                "text": "Synthetic source has no saved page body: " + source["extraction_status"]})
+            return None, None
+        text = sessions.source(identifier, source_id)["text"]
+        sessions.record(identifier, {"kind": "source_review", "source_id": source_id, "verdict": "accepted",
+                                    "text": "Matches the selected synthetic fixture page."})
+        quote = text.splitlines()[0]
+        claim = sessions.record(identifier, {"kind": "claim", "question_id": question, "statement": quote,
+            "citations": [{"source_id": source_id, "quote": quote}]})["recorded"]["id"]
+        sessions.record(identifier, {**entry, "disposition": "reviewed", "question_ids": [question],
+                                    "source_ids": [source_id], "claim_ids": [claim], "text": quote})
+        return quote, claim
+
+    for question, page in (("q1", "https://docs.example.test/search"), ("q2", "https://docs.example.test/limits")):
+        sessions.search(identifier, question + "-search", [{"question_id": question, "query": fixture["brief"]["questions"][int(question[-1]) - 1]["question"]}])
+        fetched = sessions.fetch(identifier, question + "-read", question, [page])
+        quote, claim = review(fetched["sources"][0], question)
+        sessions.record(identifier, {"kind": "answer", "question_id": question, "answer": quote, "claim_ids": [claim]})
+        if question == "q1":
+            sessions.record(identifier, {"kind": "gap", "question_id": "q2", "text": "Need the extraction limitations page."})
+    remaining = [row["original_url"] for row in sessions.coverage(identifier, filter="unreviewed")["items"]]
+    last_batch = sessions.fetch(identifier, "q2-remaining-inputs", "q2", remaining)
+    for source in last_batch["sources"]:
+        review(source, "q2")
+    failure = next(source for source in last_batch["sources"] if source["url"] == "https://docs.example.test/unavailable")
+    if last_batch["status"] != "partial" or failure["body_file"] is not None:
+        raise ValueError("A failed fixture page was presented as source evidence")
+    reopened = ResearchSessions(output / "research", settings=Settings(output / "settings.json"),
+                                engine=FixtureProvider(fixture))
+    replay = reopened.fetch(identifier, "q1-read", "q1", ["https://docs.example.test/search"])
+    if not replay["replayed"]:
+        raise ValueError("A saved operation was resubmitted")
+    coverage = reopened.coverage(identifier)
+    if (coverage["total"] != fixture["expected_counts"]["unique_urls"] or
+            coverage["metrics"]["accounted_for"]["rate"] != 1 or coverage["completion_ready"]):
+        raise ValueError("Failed or missing fixture pages must remain explicit gaps in the complete input scope")
+    try:
+        reopened.finish(identifier, "This attempt must fail because original pages remain unread.")
+    except ValueError as error:
+        if "coverage incomplete" not in str(error):
+            raise
+    else:
+        raise ValueError("The coverage gate accepted unread original fixture pages")
+    finished = reopened.finish(identifier, "Synthetic contract run: supported answers with explicit unread input gaps.", status="incomplete",
+        limitations=["Fictional provider responses test the lifecycle, not real provider quality.",
+                     "Three original fixture pages have no body and remain blocked; no successful completion is claimed."])
+    return {"research_id": identifier, "status": finished["status"], "usage": finished["usage"],
+            "bookmark_context_count": len(finished["bookmark_context"]), "sources": len(finished["sources"]),
+            "claims": len(finished["claims"]), "artifacts": finished["artifacts"], "network_calls": 0,
+            "source_scope": finished["source_scope"], "coverage": coverage["metrics"],
+            "completion_gate_rejected_unread_inputs": True}
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--output", required=True, help="New or empty verification directory outside source packages and plugin")
+    parser.add_argument("--package", help="Additionally verify a supplied real package read-only")
+    args = parser.parse_args(argv)
+    try:
+        output = Settings.external_path(str(Path(args.output).expanduser().resolve()), "Verification directory")
+        if output.exists() and any(output.iterdir()):
+            raise ValueError("Use a new or empty output directory")
+        fixture_path = ROOT / "tests/fixtures/research-scenario.json"
+        if not fixture_path.is_file():
+            raise ValueError("Run this from the source checkout or the test pack; production bundles exclude test fixtures")
+        fixture = json.loads(fixture_path.read_text(encoding="utf-8"))
+        output.mkdir(parents=True, exist_ok=True)
+        summary = {"checked_at": datetime.now(timezone.utc).isoformat(), "network_calls": 0,
+                   "fixture": verify_package(ROOT / "tests/fixtures/canvas", output / "fixture", fixture["expected_counts"], fixture["queries"]),
+                   "research": verify_research(fixture, output)}
+        if args.package:
+            summary["provided_package"] = verify_package(Path(args.package).expanduser().resolve(), output / "provided")
+        (output / "verification.json").write_text(json.dumps(summary, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+        print(json.dumps(summary, ensure_ascii=False, indent=2))
+        return 0
+    except (ValueError, OSError, RuntimeError) as error:
+        print(json.dumps({"error": str(error)}, ensure_ascii=False))
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/verify_live.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""Opt-in public-network smoke test; save inspectable provider evidence."""
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+from web_search import SearchProviders
+from settings import Settings
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--output", required=True, help="Evidence directory outside any data package")
+    parser.add_argument("--fetch-only", action="store_true", help="Skip search; verify actual extraction and archival")
+    parser.add_argument("--fetch-url", action="append", help="Public URL to read; repeat for a bounded batch")
+    parser.add_argument("--provider", choices=("exa", "parallel"), default="exa", help="Fetch provider")
+    parser.add_argument("--max-characters", type=int, default=12000)
+    args = parser.parse_args()
+    output = Settings.external_path(str(Path(args.output).expanduser().resolve()), "Verification output directory")
+    output.mkdir(parents=True, exist_ok=True)
+    settings = Settings(output / "settings.json")
+    settings.update({"archive": {"enabled": True, "directory": str(output / "knowledge")}})
+    engine = SearchProviders(timeout=30, settings=settings)
+    search = {"successful_provider_count": 0, "batches": [], "targets": []} if args.fetch_only else engine.search([
+        {"target": "Agent Plugins", "query": "Agent Plugins official specification plugin.json MCP skills"},
+        {"target": "DeepSeek Harness", "query": "DeepSeek Harness official plugin bundle MCP client"},
+    ], limit_per_target=3)
+    (output / "live-search.json").write_text(json.dumps(search, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    try:
+        fetch = engine.fetch(args.fetch_url or ["https://agent-plugins.org/specification"],
+                             provider=args.provider, max_characters=args.max_characters)
+        fetch_ok = True
+    except (RuntimeError, ValueError, OSError) as error:
+        fetch = {"error": str(error)}
+        fetch_ok = False
+    (output / "live-fetch.json").write_text(json.dumps(fetch, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    summary = {
+        "checked_at": datetime.now(timezone.utc).isoformat(),
+        "search_performed": not args.fetch_only,
+        "successful_provider_count": search["successful_provider_count"],
+        "batches": [{"provider": row["provider"], "target": row["target"], "status": row["status"],
+                     "results": len(row["results"]), "error": row.get("error")} for row in search["batches"]],
+        "targets": [{"target": row["target"], "status": row["status"], "urls": [r["url"] for r in row["results"]]}
+                    for row in search["targets"]],
+        "fetch_transport_ok": fetch_ok,
+        "archive": fetch.get("archive"),
+        "fetch_note": "Transport success does not assert origin freshness or per-URL extraction success; inspect live-fetch.json.",
+        "evidence_directory": str(output),
+    }
+    (output / "live-summary.json").write_text(json.dumps(summary, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    print(json.dumps(summary, ensure_ascii=False, indent=2))
+    archived = fetch.get("archive", {})
+    archive_ok = archived.get("status") == "saved" and all(page["page_body_archived"] for page in archived.get("pages", []))
+    return 0 if fetch_ok and archive_ok and all(row["status"] == "ok" and row["results"] for row in search["batches"]) else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/verify_quality.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+"""Run an offline annotated quality example; this does not run any provider."""
+
+import argparse
+import json
+import math
+import sys
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+from evaluation import evaluate
+from research import ResearchSessions
+from settings import Settings
+
+
+def verify_expected(report, expected):
+    if report["run_count"] != expected["run_count"] or len(report["groups"]) != expected["group_count"]:
+        raise ValueError("Fixture run/group counts differ from the annotated expectation")
+    for field in ("answer_f1", "semantic_citation_accuracy"):
+        for run in report["runs"]:
+            actual = run["metrics"][field]
+            if actual is None or not math.isclose(actual, expected[field][run["run_id"]], abs_tol=1e-12):
+                raise ValueError("Fixture annotation score mismatch: " + run["run_id"] + " / " + field)
+    direct = next(system for group in report["groups"] for system in group["systems"] if system["system_id"] == "fixture-direct")
+    if not math.isclose(direct["metrics"]["answer_f1"]["sample_variance"], expected["direct_f1_sample_variance"], abs_tol=1e-12):
+        raise ValueError("Fixture sample variance mismatch")
+    workflow = next(run for run in report["runs"] if run["run_id"] == "workflow-1")
+    if workflow["metrics"]["text_coverage"] != expected["workflow_text_coverage"]:
+        raise ValueError("Unavailable sources disappeared from the coverage denominator")
+
+
+def markdown(report):
+    fmt = lambda value: "not scored / unknown" if value is None else "%.4f" % value
+    lines = ["# Annotated research evaluation", "", "Kind: **%s**" % report["kind"], "", report["limitations"][0], "",
+             "No provider or model is invoked by this script. All semantic scores come from the supplied labels and rubric.", "",
+             "| Run | Answer F1 | Semantic citation accuracy | Reviewed scope | Cost (USD) | Latency (s) | Measurement basis |",
+             "| --- | ---: | ---: | ---: | ---: | ---: | --- |"]
+    for run in report["runs"]:
+        metrics = run["metrics"]
+        lines.append("| %s | %s | %s | %s | %s | %s | %s |" %
+                     (run["run_id"], fmt(metrics["answer_f1"]), fmt(metrics["semantic_citation_accuracy"]),
+                      fmt(metrics["reviewed_coverage"]), fmt(metrics["cost_usd"]), fmt(metrics["latency_seconds"]),
+                      run["measurements"]["basis"]))
+    lines.extend(["", "## Repeat variation and comparability", ""])
+    for group in report["groups"]:
+        lines.extend(["### %s / %s" % (group["task_id"], group["comparison_group"]), "",
+                      "Declared controls match: %s. Differences: %s." %
+                      (group["comparability"]["controlled"], ", ".join(group["comparability"]["differences"]) or "None"), "",
+                      "| System | Repeats | Mean answer F1 | Sample variance |",
+                      "| --- | ---: | ---: | ---: |"])
+        for system in group["systems"]:
+            stats = system["metrics"]["answer_f1"]
+            lines.append("| %s | %s | %s | %s |" % (system["system_id"], stats["n"], fmt(stats["mean"]), fmt(stats["sample_variance"])))
+        lines.append("")
+    lines.extend(["## Interpretation limits", ""] + ["- " + item for item in report["limitations"]])
+    lines.extend(["", "The JSON report retains rubric text, evaluator identity, null scores, missing source IDs, control differences and input hashes.", ""])
+    return "\n".join(lines)
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--fixture", default=str(Path(__file__).resolve().parents[1] / "tests/fixtures/research-quality.json"),
+                        help="JSON with suite, runs, judgments and optional known fixture expectations")
+    parser.add_argument("--output", help="Artifact directory outside plugins and canvas packages")
+    args = parser.parse_args(argv)
+    fixture = json.loads(Path(args.fixture).read_text(encoding="utf-8"))
+    report = evaluate(fixture["suite"], fixture["runs"], fixture.get("judgments"))
+    if "expected" in fixture:
+        verify_expected(report, fixture["expected"])
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    output = Settings.external_path(args.output or str(Settings.data_directory() / "runs" / ("quality-" + stamp + "-" + uuid.uuid4().hex[:6])),
+                                    "Evaluation output")
+    output.mkdir(parents=True, exist_ok=True, mode=0o700)
+    artifacts = {"evaluation": str(output / "evaluation.json"), "report": str(output / "evaluation.md"), "inputs": str(output / "inputs.json")}
+    ResearchSessions._write(Path(artifacts["evaluation"]), report)
+    ResearchSessions._write(Path(artifacts["report"]), markdown(report))
+    ResearchSessions._write(Path(artifacts["inputs"]), fixture)
+    result = {"passed": True, "verification": "known_fixture_scores" if "expected" in fixture else "supplied_annotations_computed",
+              "kind": report["kind"], "network_calls": 0, "provider_quality_claim": False, "artifacts": artifacts}
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/bookmark-research/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: bookmark-research
+description: "Research ordinary bookmark URLs or Bookmark Canvas directories, ZIPs and cards: locate bookmarks, check linked pages, compare sources or deliver a scoped research report. Preserves original inputs; does not generate or write back canvas packages."
+---
+
+# Bookmark Research
+
+[中文阅读版](references/zh/skill-guide.md)
+
+Use the user's links, package paths or registered sources. Answer in the requested language, then the saved `research.response_language`; `auto` follows the task's language (English if none is selected). Read `get_settings` when saved preferences are unknown. Pass the resolved language to delegates and saved briefs; preserve original quotations and identifiers. Load references in one language only. Keep source packages unchanged and local notes out of public queries.
+
+## Choose the work the user needs
+
+| Request | Workflow |
+| --- | --- |
+| Find bookmarks, count items, inspect notes or canvas relationships | Query local metadata. |
+| Check a known link or a few facts | `quick`: read the URL and answer with evidence. |
+| Compare bookmarked tools or investigate an open question | `agentic`: the current host model searches/reads, assesses evidence and follows remaining gaps. |
+| Investigate a complete list/package, retain progress or deliver a verifiable report | `deep`: the same host-led investigation with frozen inputs, evidence records, independent review and coverage checks. |
+
+Honor the task's explicit depth, then saved preferences; the table guides `auto`. Depth and scope are separate: a topic comparison covers that topic, while a whole-package request retains all original URLs. Briefly state the scope when useful, then perform the work. A capabilities question alone does not start an investigation. Host-led search and deep research need no professional research API key.
+
+## Tools and the quick path
+
+Use the actual MCP tool names exposed by the host. If a required tool or parameter is missing from an older catalog, use the bundled CLI: `<plugin-root>/src/cli.py`, where the plugin root is `../..` from this Skill's directory. Use its absolute path. Other CLI operations and their names are in the [CLI reference](references/cli.md).
+
+Before each new question that needs web research, call `research_readiness` (CLI `readiness`). Supply the actual `host`, only actually observed host tools, and the intended providers when explicitly restricted. It respects cached/always/manual preferences; do not force repeated probes during one investigation. Offline bookmark queries need no network readiness check. After a connection/auth failure, inspect the affected provider and refresh after fixing it. Preserve an explicitly selected provider; optional API/MCP failures do not block other available routes.
+
+Read the returned status precisely: configured credentials, reachable catalogs, successful retrieval and host OAuth are distinct. Missing optional native research MCPs or collaboration do not prevent the host's own research loop. For setup or remediation, use CLI `setup` and [settings guidance](references/settings-and-archive.md). Never ask for keys in chat; the terminal supports hidden entry or environment variables. An actual sample retrieval test consumes provider quota and is opt-in; readiness never starts a professional research job.
+
+For a known public URL, call `fetch_web({urls:[url]})`. The equivalent fallback command is:
+
+```sh
+python3 <plugin-root>/src/cli.py fetch-web 'https://example.com/page' --timeout 20
+```
+
+`--timeout` limits individual provider HTTP requests, not the entire waterfall. Beyond the readiness check, ordinary URL checks need no package import, research session or additional reference. Public GitHub README pages use this same path.
+
+`fetch_web.pages` contains one selected extract per URL; each attempt retains status and archive paths. Read the relevant text and cite the original URL. Complete provider envelopes remain in the archive; `raw:true` (CLI `--raw`) returns them when needed. Check archive errors and completeness markers; a provider extract is not proof of a complete or live origin page.
+
+## Search, assess, follow up
+
+The current host model owns the first pass. Read known URLs directly; use `search_web` to discover sources, then read the relevant pages. Ordinary comparisons can answer directly. Create persistent research records when the user needs retained progress or a report.
+
+Omitting providers uses the saved retrieval fallback. Defaults: reading tries Exa, then Parallel + Jina concurrently for unresolved URLs; search starts with Exa + Parallel, then Tavily + keyed Jina for queries without usable results. Explicit providers restrict the call. Preserve successful siblings and inspect unresolved items, skipped providers and remaining budget.
+
+A nonempty response does not settle the question. Check page identity, relevant passages, date/version and whether the quotation supports the conclusion. For irrelevant, stale or insufficient text, follow up on that URL/question only: choose another permitted provider, a linked official document, an original-site API/Markdown view, or an available authorized browser. In a research session, record uncertain/rejected source reviews and use a new operation ID for justified new retrieval; do not replay a known inadequate result expecting new text. An alternative page can support an answer but cannot count as reading the original URL.
+
+Read [provider access](references/research-workflow.md) when choosing or diagnosing retrieval services; [GitHub boundaries](references/github-and-sync.md) for code, issues, releases, private access or Git synchronization; [research methods](references/research-methods.md) for systematic comparisons, conflicts or benchmarks. A small fact check does not need these full procedures.
+
+## Canvas context
+
+For Canvas input, first read [package semantics](references/package-semantics.md); reuse it within the session. Consult the original package guide only for new/conflicting fields or a requested convention check.
+
+- Find registered sources with `index_status`. Import a new export through `sync_package` in `snapshot` mode; use `live` for a persistent directory identified by the user. Only a confirmed full mirror uses `completeness:complete`; partial exports and single cards use `partial`. Reuse the actual source ID for moved exports of the same canvas. [Source lifecycle](references/source-lifecycle.md) covers migration, recovery and monitoring.
+- Batch search targets in `search_bookmarks`; follow each target's pagination. Matching is literal across metadata, so verify short-name hits against titles/domains. Preserve IDs, URLs and grouping context. Local metadata does not prove online capabilities.
+- Use `get_context` with `item_id` for a bookmark and its ancestors, and for card descriptions, groups and directed edges. A section overview does not enumerate all items. Obtain a folder ID from ancestors before restricting a search.
+- Inspect `source.state`: disclose pending updates; use `refresh:false` on an unavailable/error source only when the user accepts the saved index. Historical snapshots use `source_history`. Research inventories and Wiki pages retain versions; freshness warnings request review, not an automatic reinvestigation.
+
+## Deep research and collaboration
+
+Read the [deep workflow](references/deep-research.md) when this mode is needed. Start with explicit questions and the complete requested input:
+
+- Ordinary bookmarks: `research_start` with `urls:[...]`; duplicate positions remain in the frozen inventory. No Canvas registration is needed.
+- Canvas packages: use indexed `source_ids`; whole-package scope is the default. Only an explicit subset uses `scope_mode:subset` and selected inventory IDs or bookmark references.
+- A public question without an original bookmark list may omit both inputs. URLs mentioned only in the brief are not tracked input.
+
+Follow every `research_inventory.next_offset`. Keep original `u-...` inventory IDs separate from saved `sN` evidence IDs. Read original text, review it, record quoted claims and each inventory judgment. Batch ready `research_record.entries` (up to 50) with a stable `batch_id`; use returned IDs in dependent batches. Check coverage differences and continue until complete or budget-limited. Failure notes, bulk exclusions, search snippets and external report citations cannot establish full original-source review.
+
+The parent owns synthesis. When delegation is available and permitted, give independent readers/verifiers the scope, questions, output language, relevant instructions and actual MCP/CLI access. Read [host workflows](references/host-workflows.md) for Codex, Claude, Pi or DSH execution details; do not assume child context inheritance. Without delegation, conduct and disclose same-agent review.
+
+Professional research is optional support for a concrete subproblem or an explicit user selection. Read [research services](references/research-services.md) before using it. Preserve explicit provider choices and known run IDs; do not replace running or unknown-outcome jobs. `research_route` recommends support but launches no work. A saved API preference does not displace the host's first pass.
+
+## Delivery and settings
+
+Answer quick tasks directly. Before finishing a report, review the actual short answer against evidence and counterevidence; condensing supported claims must preserve their conditions and limits. Use `research_finish` for reports and source/coverage artifacts: distinguish accounted inputs, usable text, substantive review and answered questions. Use `completed` only when coverage, supported answers and conflict checks pass; otherwise retain an `incomplete` report and gaps. Resume an incomplete archive with a `resume` record. Saved state is not a background agent.
+
+Create Wiki pages when the user asks to retain conclusions in a Wiki or knowledge base; read [Wiki and evaluation](references/wiki-and-evaluation.md) for publication, lint and actual labeled quality comparisons. Do not infer semantic correctness from quote/hash checks.
+
+Use `get_settings` for configuration questions and `update_settings` for lasting preferences; temporary choices use per-call options. [Settings and archives](references/settings-and-archive.md) describes storage. All archives, indexes and authored outputs stay outside the original package.