opencode-bioresearcher 1.11.1 → 1.13.0

package/skills/bioresearcher-deep-research/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: bioresearcher-deep-research
-description: "Deep biomedical research orchestrator powered by the biomcp MCP server: clarifies the question, aligns research area plan with user, decomposes into 2-5 aspects, researches each aspect via subagents (sequential fallback), and synthesizes a fully cited report. Use for deep research, literature review, clinical trials, drugs, genes, variants, diseases, patents, PubMed, functional genomics, biomcp."
+description: "Deep biomedical research orchestrator powered by the biomcp MCP server: clarifies the question, aligns research area plan with user, decomposes into 2-5 aspects, researches each aspect via subagents (sequential fallback), and synthesizes a fully cited report; optional map-first empirical cartography for category/landscape questions. Use for deep research, literature review, clinical trials, drugs, genes, variants, diseases, patents, PubMed, functional genomics, biomcp."
 license: Apache-2.0
 compatibility: "Any Agent Skills harness (opencode, Claude Code, Codex, Cursor, Gemini CLI) with the biomcp MCP server connected; the Claude Code plugin bundles the server and the bioresearcher-dr-worker subagent; a subagent/Task tool is optional - a sequential fallback is provided. The allowed-tools mcp__ entries apply on Claude Code only"
 metadata:
-  version: "1.7.0"
+  version: "1.9.0"
   source: "opencode-bioresearcher-plugin@1.7.2"
 allowed-tools: Read Write Bash Task mcp__plugin_bioresearcher_biomcp mcp__biomcp
 ---
@@ -31,6 +31,10 @@ Harness-agnostic: works with or without a subagent/Task tool.
   generates the bibliography from the merged ledger, and `vet-references.py`
   audits the result (structural + NCBI) - producing `final_report.md` and, by
   default, `final_report.html` (the `no-html` prefix skips rendering).
+- Optionally (map-first mode, for category-discovery questions) maps the
+  field's method/category landscape empirically BEFORE plan review via
+  scoped + anti-pinned cartography workers - see
+  `references/cartography.md`.
 
 ## When to use (triggers)
 
@@ -41,6 +45,8 @@ Harness-agnostic: works with or without a subagent/Task tool.
 - Gene / variant / disease questions (annotations, associations, evidence).
 - Patent landscape or prior-art questions.
 - Multi-entity questions spanning several of the above.
+- Category/landscape discovery ("what methods/approaches/classes exist for
+  X", "landscape of X") - offer the map-first mode (Step 1).
 
 Single-fact lookups (e.g. "what is the HGNC symbol for HER2") do not need the
 full workflow - answer directly with the matching biomcp tool using
@@ -50,16 +56,16 @@ full workflow - answer directly with the matching biomcp tool using
 
 The biomcp MCP server (npm package [`biomcp`](https://www.npmjs.com/package/biomcp),
 canonical source [yeyuan98/biomcp-ts](https://github.com/yeyuan98/biomcp-ts) pinned to
-`biomcp@1.4.0`) connected to the harness. For automated zero-dependency local
+`biomcp@1.6.0`) connected to the harness. For automated zero-dependency local
 setup, run the `bioresearcher-onboard` skill.
 
 Recommended client command (all features):
 
 ```json
-["npx", "-y", "-p", "biomcp@1.4.0", "-p", "webr@0.6", "-p", "mysql2@3", "biomcp"]
+["npx", "-y", "-p", "biomcp@1.6.0", "-p", "webr@0.6", "-p", "mysql2@3", "biomcp"]
 ```
 
-Requires Node.js >= 22.13. Verify with `npx -y biomcp@1.4.0 doctor` (exit 0 =
+Requires Node.js >= 22.13. Verify with `npx -y biomcp@1.6.0 doctor` (exit 0 =
 healthy). API keys are optional except where noted in
 `references/rate-limiting-auth.md`.
 
@@ -82,6 +88,7 @@ mid-query never trigger.
 | `no-interview` | Skip the interview workflow entirely (both Step 1 questions and Step 2 plan review) |
 | `light-research` | Combine and/or pick only the top TWO aspects (Step 2) |
 | `no-html` | Skip the Step 6 HTML rendering (markdown-only output) |
+| `map-first` | Run empirical field cartography (Step 1.5) before plan review, for category-discovery questions - see `references/cartography.md` |
 
 ## Workflow
 
@@ -103,6 +110,29 @@ answer your own questions. If the query carries `no-interview`, skip to Step 2.
   unattended session: write questions and chosen defaults to
   `reports/<TOPIC>/assumptions.md` and cite that file in Limitations.
 
+**Map-first offer (conditional):** if the query is category-discovery shaped
+(the deliverable is a taxonomy/landscape: "what methods/approaches/classes/
+evidence types exist", "landscape of", "how is X done across ..."), include
+ONE additional interview question offering empirical cartography (recommend
+ON); if accepted, confirm the PRIMARY SCOPE in the same message per
+`references/cartography.md`. Entity-anchored queries: never ask. The
+`map-first` prefix forces the mode on without the question. When the mode is
+off (not offered or declined), Steps 1-6 run exactly as if this feature did
+not exist.
+
+### Step 1.5: Cartography (map-first mode only)
+
+Skipped entirely when map-first is off. Dispatch cartographers per
+`references/cartography.md`: 2 focus-tier axes scoped to the confirmed
+primary scope (synthesis-mining, boundary-vocabulary) plus 1-2 anti-pinned
+context axes, using the same tier dispatch, ledger discipline, and
+completion gates as Step 4 (cartographer template and anti-pinning contract
+live in the reference). Then merge the axis maps into
+`reports/<TOPIC>/category_taxonomy.md` (tiered categories, coverage audit
+against >= 2 scope-internal syntheses, unanchored leads); the venue-sweep
+remediation axis fires only when syntheses are scarce. Cartography ledgers
+land in `evidence/` and merge in Step 5a like any aspect ledger.
+
 ### Step 2: Decompose & Review Plan
 
 Comprehend the inquiry and identify 2-5 critical research aspects (top 2 under
@@ -126,6 +156,14 @@ focus, primary tools); never paste raw ABSTRACTs into the question UI.
 4. **Waiver / Degrade:** Skip plan review turn if query has `no-interview`, or
    degrade per Step 1 rules if unattended (record plan in `assumptions.md`).
 
+**Map-first variant:** the plan review operates on the category taxonomy
+(`references/cartography.md`): present tiers, coverage-audit results, and a
+recommended selection; iterate until confirmed - this taxonomy walk-through
+IS the plan review, non-waivable except by `no-interview` (autonomous
+conversion records its rationale in `assumptions.md`). Selected categories
+become the aspects; each still gets a full deep-dive ABSTRACT with binding
+inclusion/exclusion criteria.
+
 Track finalized aspects in the harness's todo tool (TodoWrite or equivalent).
 
 ### Step 3: Create the output directory
@@ -226,7 +264,9 @@ Read all per-aspect reports. Summarize findings into a succinct, accurate
 final report addressing the user's inquiry, following the mandatory 6-section
 structure in `references/report-template.md` (Executive Summary, Data Sources,
 Analysis Methodology, Findings, Limitations, References - the References
-section itself is generated later by `render`). Reconcile conflicting findings
+section itself is generated later by `render`). Under map-first, also apply
+that reference's optional landscape and decision-guide sections (decision
+guide default-on). Reconcile conflicting findings
 across aspects explicitly rather than silently dropping one side.
 
 Write the synthesized draft to `reports/<TOPIC>/final_report.draft.md` citing
@@ -336,9 +376,14 @@ python3 <skill_dir>/scripts/vet-references.py reports/<TOPIC>/final_report.md --
 ```
 reports/<TOPIC>/
 ├── plan.md                # durable research plan (Step 3; boundaries live here)
+├── category_map_<axis>.md # per-axis cartography maps (map-first only)
+├── category_taxonomy.md   # merged tiered taxonomy + coverage audit
+│                          # (map-first only)
 ├── evidence/
 │   ├── <aspect_1>.jsonl    # per-aspect evidence ledger (worker-written)
 │   ├── <aspect_2>.jsonl
+│   ├── cartography_<axis>.jsonl  # cartography ledgers (map-first only;
+│   │                             # merge like aspect ledgers)
 │   ├── ...
 │   ├── _invalid.jsonl      # merge quarantine (only when malformed lines occur)
 │   └── sources.jsonl       # merged + verified ledger (Step 5a output)
@@ -395,6 +440,7 @@ reports/<TOPIC>/
 | File | Contents |
 |------|----------|
 | `references/worker-protocol.md` | Worker prompt template, file protocol, no re-delegation, retry/degrade rules |
+| `references/cartography.md` | map-first mode: scopes, axis archetypes, anti-pinning contract, taxonomy + coverage audit, interaction matrix |
 | `references/tool-selection.md` | Question-type to tool decision tree; sections/limit/pagination patterns; biomcp_ prefix note |
 | `references/article-literature.md` | article_search / article_get: sources, dateRange, citations |
 | `references/clinical-trials.md` | trial_search / trial_get: filters, cursor paging, sections |

package/skills/bioresearcher-deep-research/references/analysis-methods.md

@@ -31,6 +31,7 @@ An aspect is DONE when ALL of these hold:
 | Variant evidence | Variant annotation + (if token) OncoKB + trials | variant_search, variant_get, variant_oncokb |
 | Patent landscape | 10-30 patents incl. seminal prior art | patent_search, patent_get |
 | Dataset hunt | Candidate accessions + linked publication | geo_search, sra_search, genbank_search |
+| Category cartography (map-first) | 15-30 anchored categories per axis; every category >= 1 synthesis structure or >= 2 primaries | article_search, article_get |
 
 ## Source-quality rules
 
@@ -118,6 +119,20 @@ ABSTRACT; these rules govern how workers apply any such criteria.
    improvised categories); re-check rules 1-2 whenever synthesis rewords a
    claim or transcribes a number from an aspect report.
 
+## Cartography discipline (map-first mode)
+
+- Category anchoring bar: a listed category needs >= 1 retrieved synthesis
+  whose structure demonstrably contains it, or >= 2 primary records -
+  keyword overlap is not coverage (anti-pinning contract:
+  `references/cartography.md`).
+- Scope-relative tiers: adoption tiers (1/2/3) are relative to the primary
+  scope's own practice; state the reference frame, never present a tier as
+  absolute.
+- Coverage audit: the merged taxonomy is reconciled against >= 2
+  scope-internal syntheses; synthesis-enumerated categories missing from
+  the map are added or declared as gaps - silent omission is the failure
+  mode this audit exists to catch.
+
 ## Failure modes
 
 | Symptom | Fix |

package/skills/bioresearcher-deep-research/references/article-literature.md

@@ -5,10 +5,11 @@ Literature search and retrieval via `article_search` / `article_get`
 
 ## Overview
 
-`article_search` runs federated search across up to five backends with
-deduplication; `article_get` retrieves one article by PMID/PMCID/DOI with
-optional open-access full text, annotations, and citation graphs. Both tools
-enforce a 30-second execution timeout.
+`article_search` runs federated search across up to six backends with
+deduplication; `article_get` retrieves one article by PMID/PMCID/DOI (journal
+or preprint DOI) with optional annotations, citation graphs, and opt-in
+full text. `article_search` enforces a 30-second execution timeout,
+`article_get` 60 seconds.
 
 ## Tools
 
@@ -17,10 +18,10 @@ enforce a 30-second execution timeout.
 | Parameter | Type | Notes |
 |-----------|------|-------|
 | query | string (required) | Search query (title, abstract, or keyword) |
-| source | enum, optional | `pubmed`, `europepmc`, `semantic_scholar`, `pubtator`, `litsense`; omit for federated search over all |
+| source | enum, optional | `pubmed`, `europepmc`, `semantic_scholar`, `pubtator`, `litsense`, `preprint_only`, `arxiv`; omit for federated search (bioRxiv/medRxiv preprints are NOT included unless `preprint_only` is explicit; the default federation does include the `arxiv` leg) |
 | limit | int 1-50, default 10 | Applied to FINAL deduplicated results, not per-source |
 | offset | int >= 0, default 0 | Result offset |
-| dateRange | string, optional | `YYYY-MM-DD/YYYY-MM-DD`; open-ended `2020-01-01/` or `/2023-12-31`; at least one endpoint required. Only `pubmed`, `europepmc`, `semantic_scholar` support it - NOT `pubtator`/`litsense` |
+| dateRange | string, optional | `YYYY-MM-DD/YYYY-MM-DD`; open-ended `2020-01-01/` or `/2023-12-31`; at least one endpoint required. Supported by `pubmed`, `europepmc`, `semantic_scholar`, `preprint_only`, `arxiv` - NOT `pubtator`/`litsense` |
 
 Federated sources at a glance:
 
@@ -31,20 +32,34 @@ Federated sources at a glance:
 | semantic_scholar | CS/ML-adjacent and citation graph (key optional) |
 | pubtator | Biomedical entity-tagged (gene/disease/drug/variant/chemical) |
 | litsense | Sentence-level semantic match to the query |
+| preprint_only | bioRxiv/medRxiv preprints only (rows carry `preprint_server`, `ppr_id`) |
+| arxiv | arXiv preprint server (rows carry `arxiv_id`) |
 
 ### article_get
 
 | Parameter | Type | Notes |
 |-----------|------|-------|
-| id | string (required) | PMID (numeric, e.g. "12345"), PMCID ("PMC1234567"), or DOI ("10.1038/s41586-021-03819-2") |
-| sections | enum array, optional | `core`, `oa`, `annotations`, `graph`, `citation`, `all`; omit for core metadata only |
+| id | string (required) | PMID (numeric, e.g. "12345"), PMCID ("PMC1234567"), journal DOI ("10.1038/s41586-021-03819-2"), or preprint DOI ("10.1101/YYYY.MM.NN.NNNNNN", new prefix "10.64898/...") |
+| sections | enum array, optional | `core`, `oa`, `fulltext`, `annotations`, `graph`, `citation`, `all`; omit for core metadata only. `["all"]` = oa+annotations+graph+citation WITHOUT fulltext - request `["fulltext"]` separately |
 | limit | int 1-100, default 20 | Max items per section (e.g. 20 citations) |
 | citation_mode | `fast` (default) / `full` | fast ~4 s, 4 providers with auto-fallback to PubMed; full ~15-30 s, all 5 providers incl. PubMed |
 | citation_direction | `forward` / `backward` / `both` (default) | forward = articles citing this one; backward = its references |
-
-Section contents: `core` = title/authors/journal/abstract; `oa` = open-access
-full text (PMC OA); `annotations` = PubTator entity annotations; `graph` =
-citation graph; `citation` = forward citations + backward references.
+| fulltext_output | `file` (default) / `inline` | `sections:["fulltext"]` output mode - see below |
+| fulltext_max_chars | int 1000-200000, default 40000 | Inline-mode only cap for `fulltext` text; ignored in file mode |
+
+Section contents: `core` = title/authors/journal/abstract; `oa` =
+license/access metadata and links ONLY - status vocabulary
+`open_access | free_to_read | paywalled | not_in_pmc | unknown` (a pdf_url
+does not by itself mean the text is fetchable); `fulltext` = the ACTUAL
+text when freely readable in PMC/Europe PMC (opt-in, never triggered by
+`"all"`); `annotations` = PubTator entity annotations; `graph` = citation
+graph; `citation` = forward citations + backward references.
+
+`fulltext` is file-first: by default the complete text is written to a
+server-side markdown file and the reply carries `file_path` plus an outline
+(Read/Grep the file selectively). Use `fulltext_output: "inline"` (capped by
+`fulltext_max_chars`) only when the harness cannot read server-side files.
+`oa`/`fulltext` do not apply to preprint DOIs.
 
 ## Worked examples
 
@@ -74,25 +89,28 @@ Full metadata plus citations for a known PMID:
 | Symptom | Cause | Fix |
 |---------|-------|-----|
 | Tool error "timed out after 30000ms" | federated fan-out exceeded 30 s | retry with a single `source`, narrower `dateRange`, or `limit` lowered |
-| dateRange silently ignored | `source` was pubtator or litsense | filter dates client-side, or switch source to pubmed/europepmc/semantic_scholar |
+| dateRange silently ignored | `source` was pubtator or litsense | filter dates client-side, or switch source to pubmed/europepmc/semantic_scholar/arxiv/preprint_only |
 | Fewer results than limit on federated search | dedup-then-limit semantics | page with `offset`; duplicates across sources collapse into one entry |
 | citation section empty in fast mode | providers returned no items (fast auto-falls back to PubMed) | retry with `citation_mode: "full"` |
 
-## Field contract (biomcp >= 1.4.0)
+## Field contract (biomcp >= 1.6.0)
 
 Article records from every article tool path (`article_search`,
 `article_get`, `batch_get`, `discover`) carry: `pmid`, `pmcid`, `doi`,
 `title`, `authors` (full "LastName ForeName" strings - Vancouver initials are
-computed by the evidence-ledger `bib` command), `journal`, `publication_date`
-(raw string), `volume`, `issue`, `pages` (null when the upstream record has
-none, e.g. epub-ahead-of-print), plus `mesh_headings`/`publication_types`/
-`keywords`/`chemicals` on PubMed paths. HTML entities are decoded to UTF-8.
+computed by the evidence-ledger `bib` command), `journal`, `journal_issn`,
+`publication_date` (raw string), `volume`, `issue`, `pages` (null when the
+upstream record has none, e.g. epub-ahead-of-print), plus `mesh_headings`/
+`publication_types`/`keywords`/`chemicals` on PubMed paths. HTML entities are
+decoded to UTF-8.
 
 Backend coverage notes:
 
 - Only `pubmed` and `europepmc` return locator fields (volume/issue/pages).
 - `semantic_scholar`, `pubtator`, and `litsense` records never carry
   locators.
+- `preprint_only` rows carry `preprint_server`/`ppr_id` and `arxiv` rows
+  carry `arxiv_id`; neither carries journal locator fields.
 - LitSense hits are HINT records: `{pmid, pmcid, score, source}` only - no
   title, no abstract. Before citing a LitSense-only PMID, enrich it with
   `article_get(pmid)` (one sequential call; standard retry ladder on

package/skills/bioresearcher-deep-research/references/cartography.md

@@ -0,0 +1,190 @@
+# Empirical Cartography (map-first mode)
+
+Optional Stage-1 field mapping for the deep-research skill: discover the
+method/category landscape empirically BEFORE proposing the research plan,
+then run the standard aspect workflow on user-selected categories. This mode
+is field-, community-, and question-agnostic: it applies to any
+category-discovery question in the biomedical realm (methods, approaches,
+evidence classes, taxonomies, landscapes), in any discipline.
+
+## When map-first applies
+
+- OFFER it (inside the Step 1 interview, one extra question, only when the
+  query is category-discovery shaped): the deliverable is a taxonomy or
+  landscape - "what methods/approaches/classes/evidence types exist for X",
+  "landscape of X", "how is X done across ...", "categories of X".
+- Do NOT offer for entity-anchored queries (one drug, variant, trial, gene,
+  disease) - the default workflow is already right.
+- The `map-first` prefix forces the mode on without the offer question.
+- Default OFF: with map-first off, every workflow step, file, gate, and
+  report section is identical to the non-cartography skill. The only
+  default-mode addition is the conditional offer question itself.
+
+## Primary scope vs context scope
+
+The user designates a PRIMARY SCOPE - the literature segment where category
+recall is the success criterion - defined by any combination of community,
+discipline, disease/therapeutic area, modality, technique family, organism,
+data type, or question type. Everything else is CONTEXT SCOPE: mapped for
+awareness, never exhaustively. The orchestrator infers a candidate primary
+scope from query vocabulary (e.g. "industry-ready", "clinical practice",
+"food science", "diagnostic assay development") and asks for confirmation
+in the same interview message - the recall target depends on it, and users
+rarely name it spontaneously. If the user declines to specify, run with the
+scope implied by the query terms and record the assumption in plan.md.
+
+## Two-tier dispatch
+
+Focus tier (2 workers, scoped to the primary scope, method-unpinned):
+
+- `cartography_synthesis_mining` - transcribe the scope's OWN synthesis
+  ecosystem (reviews, guidelines, consensus statements, position papers,
+  protocol series): harvest their section structures as candidate
+  categories and expand via backward citations (article_get
+  sections=["citation"]) to founding anchors. The scope's own taxonomies
+  are the recall target.
+- `cartography_boundary_vocabulary` - hunt categories that answer the
+  question's underlying information need but self-describe under different
+  terms: adjacent vocabulary, hypernyms, enabling/auxiliary measurements,
+  neighboring endpoints. Ask, per formulation of the information need:
+  "what does this scope call the things that do X?"
+
+Context tier (1-2 workers, fully anti-pinned, breadth across the rest of
+the field) - pick archetypes by question shape:
+
+- `cartography_context_principle` - enumerate the distinct
+  experimental/analytical principles by which the question is answered;
+  let the categories emerge from retrieved records.
+- `cartography_context_casespace` - partition the question's object space
+  (barriers, diseases, organisms, tissues, modalities - whatever partitions
+  it) and map category coverage per stratum.
+- `cartography_context_segment` - sweep how OTHER communities/disciplines
+  frame and categorize the same question; vocabulary differences are
+  themselves findings.
+
+Budget: ~15-25 biomcp calls per cartographer (hard cap 30); parallel
+batches of up to 5; Tier A/B dispatch and the Tier C sequential fallback
+follow SKILL.md Step 4, using the cartographer template below.
+
+Conditional remediation axis (orchestrator-dispatched after the focus tier
+returns, only when needed):
+
+- `cartography_venue_sweep` - fires IFF the focus tier found fewer than two
+  field-spanning syntheses OR the interview flagged an emerging area: sweep
+  the primary scope's primary-literature venues for categories its thin
+  synthesis ecosystem under-covers.
+
+## Anti-pinning contract (binding on every cartographer)
+
+1. No method names, assay names, or category lists enter a cartographer
+   prompt. Focus-tier prompts pin the PRIMARY SCOPE and the question's
+   information need - never methods. Context-tier prompts pin nothing but
+   the question.
+2. A category may be listed ONLY if anchored in retrieved records: either
+   >= 1 retrieved synthesis whose structure demonstrably contains it, OR
+   >= 2 primary records found via search.
+3. Never assert a category from model memory; memory shapes query design
+   only. A failed query line is logged under Evidence Gaps - never turned
+   into a category.
+4. Probe deliberately across the assigned axis before concluding; do not
+   stop at the first handful of categories.
+
+## Cartographer prompt template
+
+```md
+TOPIC: <TOPIC>
+YOUR RESEARCH FOCUS: cartography_<axis>
+AXIS: <archetype name + one-line instantiation, e.g. "case-space partition:
+the variable that partitions this question's object space is <variable>">
+PRIMARY SCOPE: <primary scope - focus tier only; context tier: "none -
+stay anti-pinned">
+MISSION: Produce an empirically anchored, high-level map of the major
+method/category families for <question>, entering the field from your
+axis. 15-30 categories maximum (merge near-duplicates and say so).
+OUTPUT: reports/<TOPIC>/category_map_<axis>.md (title; one-paragraph scope
+summary; ONE subsection per category: name, one-line description, 1-3
+anchor papers as cite-key markers, maturity signals - synthesis existence,
+approximate hit volume, founding era - and which queries surfaced it; then
+"## Query Log" and "## Evidence Gaps" with failed query lines) plus
+reports/<TOPIC>/evidence/cartography_<axis>.jsonl.
+SKILL_DIR: <absolute skill dir>   # Tier B only; resolve before dispatch
+EXECUTION RULE: Do NOT read or inspect evidence-ledger.py or other skill
+scripts; all schemas and commands are fully specified here.
+```
+
+Tier B orchestrators additionally inline the anti-pinning contract, the
+anchoring rule, the ledger discipline (worker-protocol.md rules 5-8), and
+the completion-gate command. Cartographers follow every Worker rule in
+`references/worker-protocol.md` (sequential calls, retry ladder, verbatim
+ledger records, no bibliography) with the category map replacing the
+aspect report and `check --markers category_map_<axis>.md` as the gate.
+
+## Taxonomy merge + coverage audit (orchestrator)
+
+Merge all axis maps into `reports/<TOPIC>/category_taxonomy.md`:
+
+- Deduplicated category list; per category: name, one-line description,
+  anchors, maturity signals, surfaced-by axes (cross-axis confirmation is
+  a robustness signal), and an adoption tier (1 = established /
+  industry-grade, 2 = discovery-grade, 3 = emerging/niche) - tiers are
+  scope-relative and the taxonomy must say so explicitly.
+- "## Coverage Audit" section: reconcile the merged map against the
+  enumerated method/category lists of >= 2 scope-internal syntheses. Any
+  category a synthesis enumerates that the map lacks must be added (with
+  anchors) or explained as a declared gap. If the scope yielded fewer than
+  2 syntheses, anchor the audit on cross-axis overlap instead and flag
+  synthesis scarcity (this also triggers the venue-sweep remediation).
+- "## Unanchored Leads" section: suspected-but-unanchored territories,
+  listed as the query lines tried - never as categories.
+
+## Interaction matrix
+
+| Mode | Behavior |
+|------|----------|
+| Default, heuristic fired | Step 1 interview includes ONE offer question ("empirical field mapping first?" - recommend ON) and, if accepted, primary-scope confirmation in the same message; nothing else changes |
+| Default, heuristic not fired | Identical to the non-cartography skill: no question, no cartography files |
+| `map-first` | Cartography on without the offer question; the interview still runs (scope + clarifiers) unless `no-interview` is also present |
+| `map-first` + `no-interview` | Cartography on; taxonomy -> plan conversion is autonomous: record the category-selection rationale and coverage-audit outcome in plan.md + assumptions.md, and state in the report Limitations that scope selection was not user-reviewed |
+| `no-interview` alone | Identical to the non-cartography skill (Step 1 is skipped, so no offer fires) |
+
+Cartography does NOT waive the Step 2 plan review: with map-first on (and
+no `no-interview`), the taxonomy walk-through IS the plan review - present
+the taxonomy with tiers, coverage-audit results, and a recommended category
+selection, then iterate with the user until the plan is confirmed (same
+rounding rules as Step 2). Selected categories become the Step 3 aspects
+(standard deep-dive ABSTRACTs; the taxonomy's inclusion signals seed the
+ABSTRACT boundaries; the set may exceed 5 when the user insists - batch
+dispatches accordingly). Categories discovered but not selected stay
+citable: their cartography ledgers merge into sources.jsonl in Step 5a
+like any aspect ledger, and the report carries them in the optional
+landscape section (`references/report-template.md`).
+
+## Report integration
+
+- Landscape section (map-first only): one line per discovered-but-
+  unselected category, citing its cartography anchors - acknowledged, not
+  researched; the report must say so.
+- Decision guide by question scenario (map-first default-on): one compact
+  "scenario -> recommended method sequence -> tier -> caveat" table per
+  user-confirmed question scenario, built only from ledger-verified
+  sources, tiers labeled scope-relative.
+- The field's own taxonomy disagreements (syntheses classifying the same
+  subject differently) are reported in Analysis Methodology or Findings,
+  never silently resolved.
+
+## Degradation + consistency
+
+- No subagent tool: run axes sequentially in the main conversation (same
+  contract, leaner budgets).
+- Server unavailable: cartography cannot run - proceed with the default
+  workflow and say so explicitly.
+- map-first OFF: behavior is identical to the non-cartography skill
+  (steps, files, gates, report structure). The existing agent-test
+  deep-research suite (q01-q07) is the regression guarantee and stays
+  unchanged.
+
+## Out of scope / future work
+
+- Report update mode (re-running an existing report): a verify-and-refresh
+  worker tier for previously covered core areas - deliberately NOT part of
+  map-first, which always researches from scratch.

package/skills/bioresearcher-deep-research/references/diseases.md

@@ -80,7 +80,7 @@ Trial landscape directly (name accepted):
 
 | Symptom | Cause | Fix |
 |---------|-------|-----|
-| `_error: Disease ... not found` from disease_trials | invalid/unresolvable ID | call `disease_search` first and copy the exact ID; supported formats are MONDO/DOID/OMIM (message text) plus EFO/Orphanet/CUI accepted by the resolver |
+| `_error: Disease 'X' not found. Try disease_search...` from disease_trials | invalid/unresolvable ID | call `disease_search` first and copy the exact ID; supported formats are MONDO/DOID/OMIM/UMLS CUI (message text) plus EFO/Orphanet accepted by the resolver |
 | disease_get 0 hits for a raw name | the tool wants an ID, not a name | resolve via `disease_search`, or use `disease_trials`/`disease_drugs` which accept names |
 | Sections empty | over-narrow section set or sparse annotation for rare diseases | try `sections: ["all"]` and note data sparsity in the report |
 

package/skills/bioresearcher-deep-research/references/drugs.md

@@ -6,7 +6,7 @@ Drug identity, regulatory status, labels, adverse events, and targets via
 ## Overview
 
 `drug_search` finds drugs by name/mechanism/keyword (MyChem-backed);
-`drug_get` returns per-drug detail with sections spanning US/EU/WHO
+`drug_get` returns per-drug detail with sections spanning US/WHO
 regulatory data, FDA labels (safety), FAERS adverse events, targets, and
 indications; `drug_trials` cross-links to clinical trials.
 
@@ -25,7 +25,7 @@ indications; `drug_trials` cross-links to clinical trials.
 | Parameter | Type | Notes |
 |-----------|------|-------|
 | name | string (required) | Drug name, e.g. "imatinib", "aspirin" |
-| sections | enum array, optional | `core`, `us_regulatory`, `eu_regulatory`, `who_regulatory`, `safety`, `targets`, `indications`, `adverse_events`, `all` |
+| sections | enum array, optional | `core`, `us_regulatory`, `who_regulatory`, `safety`, `targets`, `indications`, `adverse_events`, `all` |
 | limit | int 1-100, default 20 | For `adverse_events`, caps the number of ranked reaction rows |
 
 Section semantics (important - commonly confused):
@@ -34,7 +34,7 @@ Section semantics (important - commonly confused):
 |---------|----------|
 | core | identity, identifiers, description |
 | us_regulatory | US brand name + `fda_status` (e.g. approved) - NOT full labels, NOT approval history |
-| eu_regulatory / who_regulatory | EMA / WHO regulatory summaries |
+| who_regulatory | WHO Prequalification products: `{prequalified, products, note}` - prequalification listing, not regulatory summaries |
 | safety | FDA LABEL TEXT: box_warning, warnings, adverse_reactions - this is where label prose lives |
 | adverse_events | FDA FAERS adverse reactions RANKED by report count - no filters (no patient age/sex/date/reaction filtering) |
 | targets | drug targets |
@@ -65,7 +65,7 @@ Regulatory snapshot + targets + indications in one call:
 
 ```json
 {"name": "trastuzumab",
- "sections": ["us_regulatory", "eu_regulatory", "targets", "indications"]}
+ "sections": ["us_regulatory", "who_regulatory", "targets", "indications"]}
 ```
 
 ## Failure modes
@@ -75,6 +75,7 @@ Regulatory snapshot + targets + indications in one call:
 | us_regulatory is surprisingly thin | it only carries brand name + fda_status | label text (warnings, box warning, adverse reactions) is in `safety` |
 | Wanting FAERS filtered by age/sex/date | `adverse_events` exposes ranked counts only - no filters | take the ranked list and note the limitation in the report; do not claim subgroup-level FAERS results |
 | 0 hits for a trade name | search index prefers generic/mechanism terms | `drug_search` by generic name or mechanism, then `drug_get` by the matched name |
+| `sections: ["eu_regulatory"]` rejected (MCP -32602) | `eu_regulatory` was removed in biomcp 1.6.0 | drop it; US status is `us_regulatory`, WHO prequalification is `who_regulatory` |
 | Payload too large | `sections: ["all"]` on a heavily annotated drug | request only the needed sections; lower `limit` for reaction rows |
 
 ## Integration notes

package/skills/bioresearcher-deep-research/references/functional-genomics.md

@@ -44,9 +44,13 @@ not index them; the error points at ENA (https://www.ebi.ac.uk/ena).
 `format` (`genbank` default / `fasta`), `seq_start`/`seq_stop` (1-based
 inclusive region), `strand` (1 plus; 2 minus, allows seq_start > seq_stop for
 reverse slices), `max_response_bytes` (default 30,000,000; oversized errors
-rather than truncates). Caps: whole-record fetches max 2,000,000 bp - larger
-records REQUIRE a seq_start/seq_stop region (up to 10 Mb span); output
-`sequence_text` is truncated to its first 200,000 characters when oversized.
+rather than truncates), `sequence_output` (`file` default / `inline`). Caps:
+whole-record fetches max 2,000,000 bp - larger records REQUIRE a
+seq_start/seq_stop region (up to 10 Mb span). Sequences over 1,000 characters
+default to FILE mode: the full text is written to a server-side cache file
+and the reply carries `file_path` + char counts (never truncated) - Read/Grep
+the file selectively. `sequence_output: "inline"` opts back into inline
+`sequence_text`, capped at its first 200,000 characters.
 
 `genbank_genes`: maps a nucleotide accession to NCBI Gene IDs (elink
 nuccore->gene) usable directly with gene_get/gene_search (entrezgene IDs) -

package/skills/bioresearcher-deep-research/references/genes.md

@@ -40,11 +40,11 @@ Protein Atlas - see pacing note below), `druggability` (DGIdb),
 
 | Tool | Parameters | Notes |
 |------|-----------|-------|
-| gene_diseases | symbol, limit (1-50, default 10) | DisGeNET associations NEED `DISGENET_API_KEY`; without it the tool falls back to OpenTargets gene-disease associations |
+| gene_diseases | symbol, limit (1-50, default 10) | DisGeNET associations NEED `DISGENET_API_KEY`; without it the tool silently returns OpenTargets gene-disease rows (source: "opentargets") |
 | gene_drugs | symbol | Drugs targeting the gene |
 | gene_trials | symbol | Clinical trials referencing the gene |
 | gene_articles | symbol | Articles about the gene (relevance search, no recency sort) |
-| gene_enrich | genes (list of HGNC symbols) | Reactome pathway enrichment; returns `_error` row on failure |
+| gene_enrich | genes (min 3 HGNC symbols), limit (1-100, default 30) | Reactome pathway enrichment; success returns `{pathways, total_reported, truncated}`; a single `_error` row on failure |
 
 ## Worked examples
 
@@ -77,7 +77,7 @@ Enrichment on a hit list:
 | Symptom | Cause | Fix |
 |---------|-------|-----|
 | gene_get error: not a valid HGNC symbol | alias or outdated name used | pass the official symbol, or set `smart: true` |
-| gene_diseases returns `_error` re DisGeNET | `DISGENET_API_KEY` missing | the tool already fell back to OpenTargets data; add the key for DisGeNET-grade associations |
+| gene_diseases returns an `_error` row | BOTH DisGeNET and OpenTargets failed - not merely a missing key | without `DISGENET_API_KEY` the tool silently returns OpenTargets rows (source: "opentargets"); add the key for DisGeNET-grade associations and retry transient backend failures |
 | HPA sections slow/erroring when iterating many genes | `protein_atlas`/`expression` use an unthrottled raw fetch | pace these calls manually; other sections are server-limited |
 | gene_enrich single `_error` row | Reactome AnalysisService rejected the input | check symbols are valid HGNC; retry with a smaller list |
 
@@ -90,4 +90,6 @@ Enrichment on a hit list:
   gene expression questions with tissue profiles.
 - `ensembl_lookup` (references/ensembl-pdb.md) is the identifier/structure
   authority (stable IDs, coordinates, transcripts) for ANY Ensembl species.
+- `gene_enrich` runs 15-45 s typically (~105 s worst case, its server-side
+  budget) - keep client tool timeouts generous (>= 120 s) for it.
 - MyGene is server-limited at 100 ms - no manual throttling.

package/skills/bioresearcher-deep-research/references/patents.md

@@ -29,7 +29,12 @@ the biomedical ones: search is bounded at 60 s, detail at 120 s.
 | seminal | boolean, optional, default true | Co-citation mining of top results to surface foundational prior art in `seminal_prior_art`; adds ~5-30 s - set `false` for the fastest bibliographic lookups |
 
 Default (no `source`) "auto" mode: queries worldwide + ppubs concurrently; if
-ppubs fails hard it falls back to uspto_odp once (tagged `_note`).
+ppubs fails hard it falls back to uspto_odp once (noted in `warnings`). The
+success payload is an envelope: `{patents, total_hits, total_hits_basis,
+seminal_prior_art, mined_count, errors?, warnings?}` - backend failures
+(e.g. a google_patents timeout) ride in `errors` as `{source, message}`
+entries, fallback/coverage notes in `warnings`; there are no in-band marker
+rows inside `patents`.
 
 ### patent_get
 
@@ -82,8 +87,9 @@ Pull claims and citations for a specific patent:
 
 ## Integration notes
 
-- Auto-mode `_note` fields flag backend fallbacks - mention data lineage in
-  the report when present.
+- Auto-mode envelope fields flag data lineage - `errors[]` entries
+  (source + message) record backend failures and `warnings[]` records
+  fallback/coverage notes; mention them in the report when present.
 - EPO OPS and USPTO are server-limited at ~1 s token buckets - no manual
   throttling; expect patent tools to be the slowest calls in an aspect.
 - Cite patents by publication number with a Google Patents or Espacenet URL

package/skills/bioresearcher-deep-research/references/rate-limiting-auth.md

@@ -49,7 +49,11 @@ Everything else: call sequentially, no timers.
 
 | Tool | Budget |
 |------|--------|
-| article_search / article_get | 30 s |
+| article_search / journal_metrics | 30 s |
+| article_get | 60 s |
+| gene_get / disease_get / drug_get / variant_get / pdb | 40 s |
+| trial_get / variant_trials | 45 s |
+| gene_enrich | up to ~105 s (keep client tool timeouts >= 120 s) |
 | patent_search | 60 s |
 | patent_get | 120 s |
 | Per-source HTTP timeout (most sources) | 15 s |
@@ -75,6 +79,7 @@ Everything else: call sequentially, no timers.
 | `CROSSREF_EMAIL` | Crossref polite pool - faster citation metadata |
 | `EPO_OPS_CONSUMER_KEY` + `EPO_OPS_CONSUMER_SECRET` | EPO OPS patent backend: worldwide search + EP/WO claims (BOTH must be set together) |
 | `USPTO_API_KEY` | USPTO Open Data Portal application search backend |
+| `OPENALEX_API_KEY` | `journal_metrics`: private per-key daily budget instead of the shared keyless OpenAlex pool (free key at openalex.org) |
 
 Set keys in the MCP client's env block (opencode: `environment`; Claude/
 Codex: `env`), then restart the client - config changes never apply live.
@@ -84,7 +89,7 @@ Codex: `env`), then restart the client - config changes never apply live.
 - Patents: US search works keyless via USPTO Public Search (ppubs default US
   backend); Google Patents is a best-effort fallback.
 - Drug regulatory/FAERS data works keyless (lower limits).
-- Literature works keyless across all five federated sources.
+- Literature works keyless across all six federated sources.
 
 ## Integration notes