opencode-bioresearcher 1.6.0

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

@@ -0,0 +1,146 @@
+# Citation Formats
+
+Numbered-citation formats per source type, with URL forms.
+
+## Overview
+
+All findings are cited with numbered in-text markers ([1], [2, 3], [1-5]),
+numbered by order of appearance, resolved against a bibliography at the end
+of the document. Each source type has a fixed format so reports stay
+consistent across workers and aspects.
+
+## In-text citation forms
+
+```markdown
+Single:    BRAF V600E occurs in ~50% of cutaneous melanomas [1].
+Multiple:  Several studies confirm the association [1, 2, 3].
+Range:     Extensively documented [1-5].
+Timeline:  Approved in 2011 [1] and became standard of care [2, 3].
+```
+
+## Bibliography formats by source type
+
+### Journal articles (from article_search / article_get)
+
+```
+[N] FirstAuthor AB, SecondAuthor CD, et al. Article Title. Journal. Year;Volume(Issue):Pages. PMID: XXXXXXXX.
+```
+
+Example:
+
+```
+[1] Chapman PB, Hauschild A, Robert C, et al. Improved survival with vemurafenib in melanoma with BRAF V600E mutation. N Engl J Med. 2011;364(26):2507-2516. PMID: 21639808.
+```
+
+When PMID is unavailable, use DOI: `DOI: 10.xxxx/xxxxx`. Both may be given.
+
+### Clinical trials (from trial_search / trial_get)
+
+```
+[N] NCTXXXXXXXX: Official Title. Phase X. Sponsor: [sponsor]. Status: [status]. https://clinicaltrials.gov/study/NCTXXXXXXXX
+```
+
+Example:
+
+```
+[2] NCT04280705: A Study of Encorafenib Plus Cetuximab With or Without Nivolumab in Metastatic Colorectal Cancer. Phase 2. Sponsor: Pfizer. Status: Completed. https://clinicaltrials.gov/study/NCT04280705
+```
+
+### Patents (from patent_search / patent_get)
+
+```
+[N] [Assignee]. Title of invention. Patent publication number (status). URL
+```
+
+Example:
+
+```
+[3] ModernaTx, Inc. Nucleoside-modified mRNA encoding SARS-CoV-2 spike protein. US11027025B2 (granted). https://patents.google.com/patent/US11027025B2
+```
+
+EP/WO patents: use `https://register.epo.org/application?number=<number>` or
+Google Patents.
+
+### Genes (from gene_search / gene_get)
+
+```
+[N] SYMBOL: Full gene name. NCBI Gene ID: XXXXXX. HGNC: HGNC:XXXX. https://www.ncbi.nlm.nih.gov/gene/XXXXXX
+```
+
+Example:
+
+```
+[4] BRAF: B-Raf proto-oncogene, serine/threonine kinase. NCBI Gene ID: 673. HGNC: HGNC:1097. https://www.ncbi.nlm.nih.gov/gene/673
+```
+
+### Variants (from variant_search / variant_get / variant_oncokb)
+
+```
+[N] GENE p.PROTEINCHANGE (rsID): ClinVar significance [ClinVar ID]. URL
+```
+
+Example:
+
+```
+[5] BRAF p.V600E (rs113488022): Pathogenic/Likely pathogenic [ClinVar: 13961]. https://www.ncbi.nlm.nih.gov/clinvar/variation/13961
+```
+
+### Drugs (from drug_search / drug_get)
+
+```
+[N] Drug Name. Indication: [indication]. [ChEMBL ID / ChEBI ID / UNII when present]. URL
+```
+
+Example:
+
+```
+[6] Vemurafenib. Indication: BRAF V600E-mutant melanoma. ChEMBL: CHEMBL1229517. https://www.ebi.ac.uk/chembl/compound_report_card/CHEMBL1229517/
+```
+
+FDA label findings cite the safety section: append "Source: FDA label
+(drug_get safety section)."
+
+### Diseases (from disease_search / disease_get)
+
+```
+[N] Disease Name. Ontology ID ([DOID/MONDO/OMIM/EFO]). URL
+```
+
+Example:
+
+```
+[7] Cutaneous melanoma. MONDO:0002025. https://monarchinitiative.org/MONDO:0002025
+```
+
+### Datasets / sequences (geo_get / sra_get / genbank_get)
+
+```
+[N] GEO series GSEXXXXXX: [title]. [organism]. https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSEXXXXXX
+[N] SRA run SRRXXXXXXX: [experiment description]. https://trace.ncbi.nlm.nih.gov/Traces/?run=SRRXXXXXXX
+[N] GenBank accession XXXXXXXX.X: [definition]. https://www.ncbi.nlm.nih.gov/nuccore/XXXXXXXX.X
+```
+
+### Official web sources (fallback when biomcp lacks coverage)
+
+```
+[N] Page Title. Organization. Updated [date if shown]. URL. Accessed: YYYY-MM-DD.
+```
+
+## What to cite
+
+| Source type | Cite? |
+|-------------|-------|
+| Tool-returned articles, trials, patents, annotations | Yes |
+| Statistical/quantitative claims | Yes - always |
+| Direct quotes | Yes |
+| General textbook knowledge ("DNA has 4 bases") | No |
+
+## Integrity rules
+
+1. Verify identifiers exist in the tool output - never fabricate a PMID,
+   NCT ID, or accession.
+2. Cite primary sources over reviews when both are available.
+3. Quote accurately; do not overstate findings beyond what the source says.
+4. Per-aspect files keep their own [1..N]; the orchestrator re-numers all
+   citations into one bibliography for final_report.md.
+5. Access dates only for web sources (tools log their own query date).

package/skills/bioresearcher-deep-research/references/clinical-trials.md

@@ -0,0 +1,87 @@
+# Clinical Trials Research
+
+ClinicalTrials.gov search and detail via `trial_search` / `trial_get`.
+
+## Overview
+
+`trial_search` queries the ClinicalTrials.gov API v2 by condition,
+intervention, or keyword with status/phase filters and CURSOR pagination.
+`trial_get` retrieves one trial by NCT ID with selectable sections.
+
+## Tools
+
+### trial_search
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| query | string (required) | Condition, intervention, or keyword |
+| status | string, optional | e.g. "Recruiting", "Completed" |
+| phase | string, optional | e.g. "Phase 1", "Phase 2" |
+| intervention_type | string, optional | e.g. "Drug", "Device" |
+| limit | int 1-50, default 10 | Maximum results per page |
+| page_token | string, optional | Cursor from the previous response - the ONLY pagination mechanism (no offset) |
+
+Response includes a next-page token when more results exist; pass it back as
+`page_token` to continue.
+
+### trial_get
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| nct_id | string (required) | e.g. "NCT01234567" |
+| sections | enum array, optional | `core`, `eligibility`, `locations`, `outcomes`, `all` |
+| limit | int 1-100, default 20 | Caps array lengths (e.g. location rows) |
+
+IMPORTANT: there is NO `protocol` section. Trial protocol content (design,
+arms, eligibility) is covered by `core` + `eligibility`:
+
+```json
+{"nct_id": "NCT04280705", "sections": ["core", "eligibility"]}
+```
+
+Section contents: `core` = identification, status, phase, design, sponsors,
+brief/official summary; `eligibility` = inclusion/exclusion criteria, sex,
+age range, healthy-volunteer acceptance; `locations` = sites and contacts;
+`outcomes` = primary/secondary outcome measures.
+
+## Worked examples
+
+Recruiting Phase 3 melanoma drug trials:
+
+```json
+{"query": "melanoma", "status": "Recruiting", "phase": "Phase 3",
+ "intervention_type": "Drug", "limit": 20}
+```
+
+Page deeper with the cursor from the previous response:
+
+```json
+{"query": "melanoma", "status": "Recruiting", "phase": "Phase 3",
+ "limit": 20, "page_token": "<token from previous response>"}
+```
+
+Outcome measures for one trial:
+
+```json
+{"nct_id": "NCT04511078", "sections": ["outcomes"]}
+```
+
+## Failure modes
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Sections missing after requesting "protocol" | no such section exists | request `["core","eligibility"]` for protocol content |
+| Same first page returned repeatedly | retrying with the same args re-issues page 1 | thread `page_token` from each response; do not use offset-style paging |
+| 0 hits for a valid condition | overly narrow combined filters | drop filters one at a time (keep `query`), then re-apply selectively |
+| Trial not found for an NCT ID | typo or unindexed/very new record | verify the NCT ID via `trial_search(query="NCT04511078")` |
+
+## Integration notes
+
+- Cross-entity shortcuts avoid manual query crafting: `drug_trials(drug)`,
+  `gene_trials(symbol)`, `disease_trials(disease_id)`, `variant_trials(variant)`
+  return compact nct_id/title/status lists - then use `trial_get` for detail.
+- `disease_trials` accepts a disease ID (DOID/MONDO/OMIM) or a plain disease
+  name; IDs are resolved to a name before searching.
+- Cite trials by NCT ID with the clinicaltrials.gov URL (references/citations.md).
+- ClinicalTrials.gov API is server-limited at 100 ms intervals - no manual
+  throttling needed.

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

@@ -0,0 +1,94 @@
+# Disease Research
+
+Disease discovery, annotation, and cross-links via `disease_search` /
+`disease_get` / `disease_drugs` / `disease_trials`.
+
+## Overview
+
+`disease_search` finds diseases by name/phenotype/keyword (MyDisease-backed);
+`disease_get` retrieves detail by ontology ID; `disease_drugs` returns
+OpenTargets drug-disease associations; `disease_trials` searches
+ClinicalTrials.gov by the resolved disease name.
+
+## Tools
+
+### disease_search
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| query | string (required) | Disease name, phenotype, or keyword |
+| limit | int 1-50, default 10 | Maximum results |
+| offset | int >= 0, default 0 | Result offset |
+
+Use it to obtain the canonical `disease_id` for `disease_get`.
+
+### disease_get
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| disease_id | string (required) | Disease ID: DOID (`DOID:0060268`), MONDO, OMIM, OMOPS, EFO, Orphanet (`ORPHA...`/`Orphanet:...`), or UMLS CUI (`C0018794`, matches `C` + 7 digits) |
+| sections | enum array, optional | `core`, `gene_associations`, `phenotypes`, `pathways`, `all` |
+| limit | int 1-100, default 20 | Caps arrays (gene association rows, phenotype rows, etc.) |
+
+Section contents: `core` = names, definitions, ontology cross-refs;
+`gene_associations` = associated genes; `phenotypes` = HPO phenotype terms;
+`pathways` = implicated pathways.
+
+### disease_drugs
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| disease_id | string (required) | Disease ID (ontology ID or name resolvable via OpenTargets) |
+| limit | int 1-50, default 20 | Caps the association list |
+
+Sources drugs via OpenTargets.
+
+### disease_trials
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| disease_id | string (required) | Disease ID OR plain disease name - IDs are resolved to a name first |
+| limit | int 1-50, default 20 | Page size |
+
+Returns compact `{nct_id, title, status}` rows; follow up with `trial_get`.
+
+## Worked examples
+
+Find the canonical ID, then annotate:
+
+```json
+{"query": "melanoma", "limit": 5}
+```
+
+```json
+{"disease_id": "DOID:0060268", "sections": ["core", "gene_associations", "phenotypes"]}
+```
+
+Drugs associated with a disease:
+
+```json
+{"disease_id": "MONDO:0002025", "limit": 15}
+```
+
+Trial landscape directly (name accepted):
+
+```json
+{"disease_id": "pancreatic adenocarcinoma", "limit": 20}
+```
+
+## Failure modes
+
+| 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 |
+| 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 |
+
+## Integration notes
+
+- Gene-centric disease questions can go the other way: `gene_diseases(symbol)`
+  (references/genes.md) - note its DisGeNET/OpenTargets fallback semantics.
+- Disease -> trials -> detail chain: `disease_trials` then `trial_get`
+  (references/clinical-trials.md).
+- MyDisease and Monarch are server-limited at 100 ms; OpenTargets at 500 ms -
+  no manual throttling.

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

@@ -0,0 +1,88 @@
+# Drug Research
+
+Drug identity, regulatory status, labels, adverse events, and targets via
+`drug_search` / `drug_get` / `drug_trials`.
+
+## Overview
+
+`drug_search` finds drugs by name/mechanism/keyword (MyChem-backed);
+`drug_get` returns per-drug detail with sections spanning US/EU/WHO
+regulatory data, FDA labels (safety), FAERS adverse events, targets, and
+indications; `drug_trials` cross-links to clinical trials.
+
+## Tools
+
+### drug_search
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| query | string (required) | Drug name, mechanism, or keyword |
+| limit | int 1-50, default 10 | Maximum results |
+| offset | int >= 0, default 0 | Result offset |
+
+### drug_get
+
+| 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` |
+| limit | int 1-100, default 20 | For `adverse_events`, caps the number of ranked reaction rows |
+
+Section semantics (important - commonly confused):
+
+| Section | Contents |
+|---------|----------|
+| 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 |
+| 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 |
+| indications | approved/use indications |
+| all | every non-core section |
+
+### drug_trials
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| drug | string (required) | Drug name |
+
+## Worked examples
+
+Label (safety) information for vemurafenib:
+
+```json
+{"name": "vemurafenib", "sections": ["safety"]}
+```
+
+Top FAERS adverse events (ranked, unfilterable):
+
+```json
+{"name": "imatinib", "sections": ["adverse_events"], "limit": 15}
+```
+
+Regulatory snapshot + targets + indications in one call:
+
+```json
+{"name": "trastuzumab",
+ "sections": ["us_regulatory", "eu_regulatory", "targets", "indications"]}
+```
+
+## Failure modes
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| 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 |
+| Payload too large | `sections: ["all"]` on a heavily annotated drug | request only the needed sections; lower `limit` for reaction rows |
+
+## Integration notes
+
+- Reverse direction (target -> drugs): `gene_drugs(symbol)`; disease ->
+  drugs: `disease_drugs(disease_id)` (references/diseases.md).
+- openFDA rate limits improve with `OPENFDA_API_KEY`
+  (references/rate-limiting-auth.md).
+- MyChem and openFDA are server-limited at 100 ms - no manual throttling.
+- Cite drugs with identifiers (ChEMBL/ChEBI/UNII where present in core output; drugBank IDs are not returned by drug_get)
+  per references/citations.md.

package/skills/bioresearcher-deep-research/references/ensembl-pdb.md

@@ -0,0 +1,134 @@
+# Ensembl & PDB Research
+
+Identifier/structure authority and variant consequence prediction via
+`ensembl_*` tools, and macromolecular structures via the tri-mode `pdb` tool.
+
+## Overview
+
+The Ensembl tools cover any of 356 Ensembl species: stable-ID lookup,
+cross-species homology, on-demand VEP consequence prediction (works for novel
+variants), and region content. The single `pdb` tool switches between search,
+metadata get, and file download by its arguments.
+
+## Tools
+
+### ensembl_lookup
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| gene_or_id | string (required) | HGNC symbol (BRAF) or Ensembl gene ID (ENSG00000157764, versioned or bare - versions resolve to current) |
+| species | string, default "human" | Name or alias: "human", "mus_musculus", "mouse", "rat", ... (356 species) |
+| expand | boolean, default false | Include all transcripts with translation/protein IDs |
+
+Returns stable ID, symbol<->ID mapping, canonical transcript, coordinates on
+the current assembly (GRCh38 human, GRCm39 mouse, ...). For rich HUMAN gene
+annotation use `gene_get` (references/genes.md) - this tool is the
+identifier/structure authority.
+
+### ensembl_homology
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| gene | string (required) | Symbol or Ensembl gene ID |
+| species | string, default "human" | Source species |
+| type | `orthologues` (default) / `paralogues` | Homology type |
+| target_species | string, optional | Restrict to one species, e.g. "mouse" |
+| target_taxon | int, optional | Restrict to taxon ID, e.g. 10090 (Mus musculus) |
+| limit | int 1-100, default 20 | Max homologies (sorted by percent identity) |
+
+### ensembl_consequence
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| variant | string (required) | HGVS c./p./g. ("NM_004333:c.1799T>A", "ENST00000288602:c.1799T>A") or dbSNP rsID ("rs113488060"); prefer HGVS over rsIDs |
+| species | string, default "human" | Species |
+| limit | int 1-50, default 10 | Max transcript consequences (sorted by impact severity) |
+
+Predicts functional consequence via Ensembl VEP - works even for NOVEL
+variants absent from every database, and for non-human species. Returns most
+severe consequence, per-transcript effects (impact, codon/amino-acid change,
+SIFT/PolyPhen), and co-located known variants (ClinVar/COSMIC IDs,
+gnomAD/1000G frequencies when present). For KNOWN human variants,
+`variant_get` additionally provides pre-computed deep scores (CADD, REVEL,
+ClinVar stars).
+
+### ensembl_region
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| region | string (required) | `chr:start-end`, 1-based, e.g. "7:140450000-140480000" (GRCh38 for human) |
+| features | array, default ["gene","variation"] | From `gene`, `transcript`, `variation` |
+| species | string, default "human" | Species |
+| limit | int 1-500, default 50 | Max features (output capped with a truncated marker) |
+
+Ideal for locus triage ("what genes and known variants sit in this GWAS hit
+interval?"). Keep spans modest (< 1 Mb recommended). For sequence TEXT use
+`genbank_get`; for annotation chain IDs into `gene_get`/`variant_get`.
+
+### pdb (tri-mode tool)
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| query | string, optional | SEARCH mode: free-text structure search; omit pdb_id |
+| pdb_id | string, optional | GET mode: 4-char ID (e.g. "4HHB"); required for get/download |
+| sections | enum array, optional | `core`, `polymer_entities`, `ligands`, `assembly`, `experiment`, `citation`, `all` |
+| download | boolean, default false | DOWNLOAD mode: saves the structure file, returns file path (only with pdb_id) |
+| format | `cif` (default) / `pdb` | Download format; cif always available, legacy pdb may not exist for some entries |
+| limit / offset | int | Search result paging (limit 1-50, default 10) |
+
+Providing NEITHER query nor pdb_id is an error.
+
+## Worked examples
+
+All human BRAF transcripts:
+
+```json
+{"gene_or_id": "BRAF", "expand": true}
+```
+
+Mouse orthologues of BRAF:
+
+```json
+{"gene": "BRAF", "type": "orthologues", "target_species": "mouse"}
+```
+
+Consequence of a novel HGVS variant:
+
+```json
+{"variant": "NM_004333.4:c.1799T>A"}
+```
+
+What lives in a GWAS interval:
+
+```json
+{"region": "7:140450000-140480000", "features": ["gene", "variation"]}
+```
+
+Structure workflow:
+
+```json
+{"query": "BRAF kinase inhibitor"}
+```
+
+```json
+{"pdb_id": "4HHB", "sections": ["core", "experiment"]}
+```
+
+## Failure modes
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Transient Ensembl 5xx errors | upstream REST occasionally 500/503s | the server retries 3x with backoff; one client retry is reasonable if it still fails |
+| pdb error "Provide either query or pdb_id" | neither argument given | pass `query` for search or `pdb_id` for get/download |
+| Legacy `format: "pdb"` download fails | not all entries have the legacy format | use `format: "cif"` |
+| ensembl_region output truncated | span or feature count too high | narrow the region (< 1 Mb) or raise `limit` toward 500 |
+| ensembl_consequence vague for an rsID | rsID coordinate mapping is less specific | prefer HGVS notation input |
+
+## Integration notes
+
+- Ensembl REST is server-limited at 100 ms; RCSB data endpoints at 100-200 ms
+  - no manual throttling.
+- `pdb` download writes to disk (readOnlyHint false) - clean up large files if
+  the workspace matters.
+- Chain ensembl_lookup -> gene_get for human annotation; ensembl_region ->
+  variant_get for variant detail; pdb citation sections -> article_get.

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

@@ -0,0 +1,118 @@
+# Functional Genomics Research
+
+Dataset and sequence research via GEO (`geo_search`/`geo_get`), SRA
+(`sra_search`/`sra_get`), GenBank (`genbank_search`/`genbank_get`/
+`genbank_genes`), and GTEx (`gtex_expression`/`gtex_eqtl`).
+
+## Overview
+
+These tools find and retrieve functional genomics studies (expression,
+RNA-seq, sequencing runs, sequence records) and tissue expression genetics,
+with rich cross-links (accession chaining) between them.
+
+## Tools
+
+### geo_search / geo_get
+
+`geo_search`: `query` (free text or NCBI field syntax like
+`GSE183947[Accession]`), `entry_type` (`gse` study default / `gsm` sample /
+`gpl` platform / `gds` curated dataset), `organism`, `limit` (1-50, default
+10), `offset`. Results carry chaining fields: `sra_project` -> sra_get,
+`bioproject`, `pubmed_ids` -> article_get, `accession` -> geo_get.
+
+`geo_get`: `accession` (matches `^(GSE|GSM|GPL|GDS)\d+$`), `download`
+(boolean; saves the FIRST supplementary file .gz/.csv/.txt to a local temp
+path and returns path/size/URL), `max_bytes` (min 1,000,000; default
+52428800 = 50 MB). GDS accessions return guidance pointing at the underlying
+GSE/GSM.
+
+### sra_search / sra_get
+
+`sra_search`: `query` (free text, an accession SRP/SRX/SRR/SRS, or field
+syntax like `RNA-SEQ AND Homo sapiens[Organism]`), `limit`, `offset`.
+
+`sra_get`: `accession` - SRP study / SRX experiment / SRR run / SRS sample.
+European (ERP/ERR) and DDBJ (DRP/DRR) accessions are REJECTED - NCBI SRA does
+not index them; the error points at ENA (https://www.ebi.ac.uk/ena).
+
+### genbank_search / genbank_get / genbank_genes
+
+`genbank_search`: `query` (terms, accession, or field syntax like
+`TP53[Gene Name] AND Homo sapiens[Organism]`), `organism`, `limit`, `offset`.
+
+`genbank_get`: `accession` (versioned or bare, e.g. NC_000023.11),
+`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.
+
+`genbank_genes`: maps a nucleotide accession to NCBI Gene IDs (elink
+nuccore->gene) usable directly with gene_get/gene_search (entrezgene IDs) -
+the bridge from sequence records to gene annotation.
+
+### gtex_expression / gtex_eqtl
+
+`gtex_expression`: `gene` (HGNC symbol or Ensembl gene ID, versioned or
+bare), `tissue` (optional tissueSiteDetailId filter, e.g. Brain_Cortex,
+Whole_Blood), `limit` (1-54, default 20; tissues sorted highest TPM first).
+GTEx Analysis v10, 54 tissue sites, median TPM.
+
+`gtex_eqtl`: `gene`, `tissue` (REQUIRED tissueSiteDetailId), `limit`
+(1-100, default 20). Significant cis-eQTLs sorted by ascending p-value:
+variant_id, p_value, NES.
+
+## Worked examples
+
+Find melanoma single-cell studies:
+
+```json
+{"query": "melanoma single cell", "organism": "Homo sapiens", "limit": 10}
+```
+
+Series detail with supplementary download:
+
+```json
+{"accession": "GSE183947", "download": true, "max_bytes": 100000000}
+```
+
+Runs for a study:
+
+```json
+{"query": "SRP123456"}
+```
+
+A 5 kb region slice of a big chromosome record:
+
+```json
+{"accession": "NC_000023.11", "seq_start": 43070000, "seq_stop": 43075000,
+ "format": "fasta"}
+```
+
+Expression profile across tissues:
+
+```json
+{"gene": "TP53", "limit": 10}
+```
+
+## Failure modes
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| sra_get error: European/DDBJ accession | ERP/ERR/DRP/DRR not in NCBI SRA | use ENA (https://www.ebi.ac.uk/ena) for those accessions |
+| genbank_get error requiring region | record > 2,000,000 bp without seq_start/seq_stop | supply a 1-based inclusive region (max 10 Mb span) |
+| sequence_text ends with "...[truncated N of M chars ...]" | output guard caps at 200,000 chars | request a narrower region for the full text |
+| geo_get download refused | non-NCBI host or file exceeds max_bytes | raise `max_bytes` (cap applies) or download manually from the returned URL |
+| GEO supplementary downloads slow | unthrottled raw downloads | pace download calls manually; only download when analysis truly needs the file |
+| gtex_eqtl error about tissue | missing/invalid tissueSiteDetailId | tissue is required - use e.g. "Whole_Blood", "Brain_Cortex" |
+
+## Integration notes
+
+- Chaining map: geo -> sra (`sra_project`/first_run), geo -> literature
+  (`pubmed_ids` -> article_get), genbank -> genes (`genbank_genes`), gene ->
+  GTEx (symbol or Ensembl ID), geo sample/platform -> geo_get.
+- E-utilities (PubMed/GEO/SRA/GenBank) share ONE server-side limiter: 334 ms
+  keyless, 100 ms with NCBI_API_KEY - no manual throttling.
+- GEO SOFT record fetches are separately limited at 300 ms; supplementary
+  file downloads are unthrottled.