opencode-bioresearcher 1.6.0

package/skills/bioresearcher-deep-research/references/utility-config.md

@@ -0,0 +1,116 @@
+# Utility & Configuration Tools
+
+Cross-cutting tools: `discover`, `batch_get`, and `biomcp_configure`.
+
+## Overview
+
+`discover` resolves free text to typed entities; `batch_get` fetches many
+entities in parallel with per-item failure isolation; `biomcp_configure` is
+the unified inspect/configure surface for optional features (database, R
+analysis, biowasm) and environment parameters.
+
+## Tools
+
+### discover
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| query | string (required) | Free text, e.g. "BRAF V600E", "lung cancer", "imatinib" |
+
+Returns entities matching the concept with their types and IDs - the right
+first call when a question's entity types are ambiguous.
+
+### batch_get
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| inputs | array (required) | Items: `{entity, id, sections?}` where entity is one of `gene`, `variant`, `drug`, `disease`, `trial`, `article`, `patent` |
+
+Fetches all inputs in parallel server-side; ONE failed item does not fail the
+batch - the response carries per-item failure rows. Prefer this over N
+sequential `*_get` calls when you already know the IDs.
+
+```json
+{"inputs": [
+  {"entity": "gene", "id": "BRAF", "sections": ["core", "druggability"]},
+  {"entity": "trial", "id": "NCT04280705", "sections": ["core"]},
+  {"entity": "article", "id": "21639808"},
+  {"entity": "drug", "id": "vemurafenib", "sections": ["safety"]}
+]}
+```
+
+### biomcp_configure
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| action | `status` (default) / `set` / `reset` | status works with no other arguments |
+| values | object, optional | For set: `{"<dotted file-param id>": value}` e.g. `{"features.analysis_biowasm.enabled": true}`; `null` removes a key; max 32 keys per call |
+| target | string or array, optional | For reset: a feature id (`database`, `analysis_r`, `analysis_biowasm`) removes the section, or a list of dotted ids |
+| filter | string, optional | For status: `file`, `env`, a feature id, or dotted-id prefix - returns detailed rows |
+| dry_run | boolean, optional | Validate and diff without writing |
+| confirm_sensitive | boolean, optional | Must be true when set/reset touches sensitive keys (connection targets, mirrors, credentials) - first attempts are refused by design |
+
+Key behaviors:
+
+- Calling with `{}` returns the status overview: per-feature running state,
+  config file health, conflicts, pending-restart flags, dependency
+  prerequisites.
+- Feature groups and their env gates: `database` (DB_TYPE=mysql|sqlite),
+  `analysis_r` (ANALYSIS_R=1), `analysis_biowasm` (ANALYSIS_BIOWASM=1).
+- REGISTRATION-TIME GATING: tool groups register at SERVER START only. After
+  enabling a feature (via env block or this tool's `set`, which writes
+  `.biomcp.json` in the server's working directory), the tools appear only
+  after a client RESTART - until then calls return `no_such_tool`. There is
+  no live activation.
+- Environment-only parameters (API keys, proxy, security boundaries like
+  ANALYSIS_BIOWASM_DATA_DIR) are QUERY-ONLY here - the response explains how
+  to set them in the client env block; env values are masked (presence +
+  fingerprint).
+- A `set` is refused (`cwd_refused`) when the server's working directory is
+  not a project root (e.g. cwd-less clients like Claude Desktop) - the error
+  carries a paste-ready env-block translation.
+- `.biomcp.json` is loaded once at startup; env variables take precedence
+  over the file; `BIOMCP_PROJECT_CONFIG=0` disables file loading entirely.
+
+## Worked examples
+
+Overall status:
+
+```json
+{}
+```
+
+Enable SQLite database feature:
+
+```json
+{"action": "set", "values": {"features.database.enabled": true,
+ "features.database.type": "sqlite",
+ "features.database.sqlite_path": ["data/geo.db"]}}
+```
+
+(the first set of sensitive keys like sqlite_path is refused - re-send the
+identical call with `"confirm_sensitive": true`)
+
+Check a feature's parameters in detail:
+
+```json
+{"action": "status", "filter": "features.analysis_r"}
+```
+
+## Failure modes
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `no_such_tool` after enabling a feature | tools register at server start only | restart the client/session, then verify with `biomcp_configure` `{}` (`running_now`) |
+| set refused: "sensitive" | sensitive key class requires confirmation | re-send identical call with `confirm_sensitive: true` |
+| `cwd_refused` | server cwd is / or $HOME | use the client env block (error carries the translation) |
+| batch_get item row contains `_error` | that single ID failed (typo, unknown ID) | fix the ID and re-request just that item; other items succeeded |
+
+## Integration notes
+
+- Smoke-test sequence for a fresh setup: `biomcp_configure` with `{}` ->
+  confirm expected features `running_now` -> one cheap domain call.
+- `doctor` CLI complements this: `npx -y biomcp@1.1 doctor` (exit 0 = clear);
+  `--client opencode` emits a paste-ready client entry.
+- Multi-entity literature pulls (e.g. 10 PMIDs from article_search) belong in
+  ONE `batch_get` call, not 10 article_get calls.

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

@@ -0,0 +1,109 @@
+# Variant Research
+
+Variant search, annotation, oncology evidence, and trial cross-links via
+`variant_search` / `variant_get` / `variant_oncokb` / `variant_trials`.
+
+## Overview
+
+`variant_search` queries MyVariant.info with STRUCTURED parameters (gene +
+protein change as separate fields - not compound free text); `variant_get`
+returns per-variant annotation with sections; `variant_oncokb` adds precision
+oncology evidence (token-gated); `variant_trials` links to clinical trials.
+
+## Tools
+
+### variant_search
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| query | string, optional | rsid ("rs113488022") or HGVS ("NM_004333.4:c.1799T>A"). Do NOT put compound text like "BRAF V600E" here |
+| gene | string, optional | Gene symbol filter, e.g. "BRAF" - pair with hgvsp |
+| hgvsp | string, optional | Protein change, e.g. "V600E" - pair with gene |
+| hgvsc | string, optional | cDNA change |
+| rsid | string, optional | dbSNP rsID |
+| significance | enum, optional | `benign`, `likely_benign`, `pathogenic`, `likely_pathogenic`, `uncertain` (ClinVar) |
+| consequence | string, optional | e.g. "missense", "synonymous" |
+| max_frequency | number, optional | Max allele frequency 0-1 (gnomAD-style rarity filter) |
+| min_cadd | number, optional | Minimum CADD score |
+| limit | int 1-50, default 10 | Maximum results |
+| offset | int >= 0, default 0 | Result offset |
+
+### variant_get
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| id | string (required) | rsid, HGVS, or ClinVar ID |
+| sections | enum array, optional | `core`, `frequency`, `predictions`, `clinical`, `alphagenome_scores`, `all`. Core (id, gene, rsid, significance) is ALWAYS returned at top level |
+| limit | int 1-100, default 20 | Caps arrays within sections |
+
+Note: `alphagenome_scores` is currently UNAVAILABLE - it returns an error stub
+pending reimplementation. Request the other sections instead.
+
+### variant_oncokb
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| gene | string (required) | Gene symbol, e.g. "BRAF", "EGFR" |
+| protein_change | string (required) | e.g. "V600E", "L858R" |
+
+REQUIRES the `ONCOKB_TOKEN` environment variable (register at oncokb.org).
+Returns OncoKB precision-oncology levels of evidence, oncogenic status, and
+therapeutics.
+
+### variant_trials
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| variant | string (required) | rsID, HGVS, or variant ID |
+
+## Worked examples
+
+The canonical BRAF V600E lookup (structured, never free text):
+
+```json
+{"gene": "BRAF", "hgvsp": "V600E", "limit": 5}
+```
+
+Pathogenic missense variants in a gene, rarity-filtered:
+
+```json
+{"gene": "TP53", "consequence": "missense",
+ "significance": "pathogenic", "max_frequency": 0.001, "limit": 20}
+```
+
+By rsID directly:
+
+```json
+{"query": "rs113488022"}
+```
+
+Deep annotation of one variant:
+
+```json
+{"id": "rs113488022", "sections": ["frequency", "predictions", "clinical"]}
+```
+
+OncoKB evidence (token present):
+
+```json
+{"gene": "EGFR", "protein_change": "L858R"}
+```
+
+## Failure modes
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| variant_oncokb error mentioning token | `ONCOKB_TOKEN` not set | register/request access at oncokb.org and set it in the client env block, or skip OncoKB and rely on `variant_get` clinical section |
+| 0 hits for "BRAF V600E" passed as query | compound free text is not an rsid/HGVS | use `gene` + `hgvsp` as separate parameters (the tool also auto-splits a bare "GENE V600E" string, but explicit params are reliable) |
+| alphagenome_scores error stub | section currently unavailable | request `frequency`/`predictions`/`clinical` instead |
+| Empty results with many filters | over-constrained combination | relax filters one at a time (drop `min_cadd` first, then `max_frequency`) |
+
+## Integration notes
+
+- Chain: variant_search -> variant_get (detail) -> variant_oncokb (oncology
+  evidence, if token) -> variant_trials / trial_get (clinical relevance).
+- For NOVEL variants (absent from databases) use `ensembl_consequence`
+  (VEP on demand) instead of variant_get - see references/ensembl-pdb.md.
+- `discover(query="BRAF V600E")` resolves ambiguous variant text to typed
+  entities first when unsure.
+- MyVariant is server-limited at 100 ms - no manual throttling.

package/skills/bioresearcher-deep-research/references/worker-protocol.md

@@ -0,0 +1,110 @@
+# Worker Protocol
+
+The canonical contract for per-aspect research workers - both parallel
+subagents and the sequential fallback in the main conversation.
+
+## Overview
+
+Each worker owns exactly ONE research aspect of a TOPIC. It queries biomcp
+tools, collects identifiers, and writes one markdown file under
+`reports/<TOPIC>/`. Workers never re-delegate, never fabricate, and never fall
+back to internal knowledge for facts. Workers also never interview the user -
+clarification is exclusively the orchestrator's Step 1 (SKILL.md).
+
+## Worker prompt template (orchestrator fills this in)
+
+```
+TOPIC: <TOPIC>
+YOUR RESEARCH FOCUS: <RESEARCH-ASPECT>
+DESCRIPTION: <ABSTRACT>
+```
+
+- ABSTRACT: <200 words describing the exact focus of the aspect and a list of
+  detailed research items to investigate.
+- Tier B (generic subagent): the orchestrator should ALSO inline into the
+  prompt the Worker Rules below, the per-domain tool cheatsheet from
+  `references/tool-selection.md`, and the citation format summary from
+  `references/citations.md` - generic subagents may not have access to this
+  skill's files.
+- Tier A (dedicated `bioresearcher-dr-worker` plugin subagent): the worker
+  reads this file plus `references/tool-selection.md` and
+  `references/citations.md` itself at startup (via
+  `${CLAUDE_PLUGIN_ROOT}`); the orchestrator sends ONLY the filled-in
+  template below.
+
+## File protocol
+
+- Output file: `reports/<TOPIC>/<YOUR-FOCUS>.md` where `<YOUR-FOCUS>` is the
+  underscore-separated aspect name (e.g. `clinical_landscape.md`).
+- The write tool auto-creates parent directories - never use bash mkdir.
+- The file must be self-contained: a reader should understand the findings,
+  the tools/queries used, and the sources cited without any other context.
+- File structure: title, one-paragraph scope summary, findings with in-text
+  citations, tool/query log (which biomcp tools + key argument values), and a
+  full bibliography.
+
+## Worker rules
+
+1. Stay focused: execute only the assigned aspect; do NOT delegate to other
+   subagents (no re-delegation), and do not expand scope.
+2. Tool selection: query biomcp tools per `references/tool-selection.md`;
+   filter at the source (specific terms, `limit`, `sections`) - never retrieve
+   broadly and filter locally.
+3. Sequential MCP calls only - never issue concurrent biomcp calls. No manual
+   sleep timers are needed between calls (server-side limiters pace each
+   source); the only exceptions are HPA `protein_atlas`/`expression` sections
+   and GEO supplementary downloads, which are unthrottled - space those out.
+4. No internal knowledge: use only biomcp tool results or official sources.
+   If evidence is missing after retries, say so explicitly in the report.
+5. Citations: every claim gets [N] references; keep a numbered bibliography in
+   `references/citations.md` format. Capture identifiers as you go: PMIDs,
+  PMCIDs, DOIs, NCT IDs, patent IDs, GEO/SRA accessions, database IDs.
+6. Retry logic: if a query fails, wait a few seconds, retry with a simpler
+   query; at most 3 attempts per query before recording the gap and moving on.
+7. Writing: succinct, accurate, professional - academic standard.
+
+## Retry ladder (per query)
+
+```
+attempt 1: original query
+  fail -> wait a few seconds
+attempt 2: simplified query (fewer terms, broader limit)
+  fail -> wait a few seconds
+attempt 3: alternate tool/source (see references/tool-selection.md routing)
+  fail -> record "evidence gap" in the aspect file with the failed query; continue
+```
+
+## Parallel execution (orchestrator with subagent/Task tool)
+
+- Pick the tier by capability: dedicated `bioresearcher-dr-worker` subagent
+  (Tier A) when the harness offers it; otherwise generic subagents with the
+  inlined cheatsheet (Tier B). Do not mix tiers within one topic.
+- Launch workers in parallel in batches of up to 5.
+- Track each aspect in the todo list; mark complete when its output file
+  exists and ends with a bibliography.
+- If a worker fails or stalls, restart it (same prompt), max 3 restarts.
+- Tell the user up front: "If subagents are stuck without progress for too
+  long, interrupt and ask me to resume work."
+
+## Sequential degradation (no subagent tool)
+
+If the harness has no subagent/Task tool, the SAME protocol runs inline in the
+main conversation, one aspect at a time:
+
+1. Announce the aspect being worked on.
+2. Apply Worker rules 2-7 exactly (same tool selection, retries, citation
+   discipline, file protocol).
+3. Write `reports/<TOPIC>/<ASPECT>.md` before moving to the next aspect.
+4. After the last aspect, proceed to synthesis (SKILL.md Step 5).
+
+Sequential mode trades latency for context - keep per-aspect tool calls lean
+(strict `limit`, narrow `sections`) so the accumulated context stays usable.
+
+## Aspect completion checklist
+
+- [ ] Output file exists at `reports/<TOPIC>/<ASPECT>.md`
+- [ ] Every claim has a citation, source note, or method note
+- [ ] Bibliography present, numbered by order of appearance
+- [ ] Identifiers included (PMIDs / DOIs / NCT IDs / patent IDs / accessions)
+- [ ] Tool/query log included
+- [ ] Evidence gaps (if any) explicitly listed

package/skills/bioresearcher-deep-research/scripts/markdown-to-html.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""Convert a markdown research report to a standalone HTML file.
+
+Usage:
+    uv run --with markdown python scripts/markdown-to-html.py report.md -o report.html
+
+Dependencies:
+    - markdown (python-markdown), provided by `uv run --with markdown`
+
+Wraps the rendered markdown in a minimal GitHub-like inline-CSS page so the
+output is a single self-contained file with no external assets.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+try:
+    import markdown as md_lib
+except ImportError:
+    sys.stderr.write(
+        "error: the 'markdown' package is required. Run via:\n"
+        "  uv run --with markdown python scripts/markdown-to-html.py IN.md -o OUT.html\n"
+    )
+    sys.exit(2)
+
+CSS = """
+body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;
+  font-size: 16px; line-height: 1.6; color: #1f2328; background: #ffffff;
+  max-width: 980px; margin: 0 auto; padding: 32px 44px; }
+h1, h2, h3, h4, h5, h6 { font-weight: 600; line-height: 1.25; margin-top: 24px;
+  margin-bottom: 16px; }
+h1 { font-size: 2em; border-bottom: 1px solid #d1d9e0; padding-bottom: .3em; }
+h2 { font-size: 1.5em; border-bottom: 1px solid #d1d9e0; padding-bottom: .3em; }
+h3 { font-size: 1.25em; }
+p { margin-top: 0; margin-bottom: 16px; }
+a { color: #0969da; text-decoration: none; }
+a:hover { text-decoration: underline; }
+code { font-family: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, monospace;
+  font-size: 85%; padding: .2em .4em; background: #f0f2f5; border-radius: 6px; }
+pre { background: #f6f8fa; border-radius: 6px; padding: 16px; overflow: auto; }
+pre code { background: transparent; padding: 0; font-size: 85%; }
+blockquote { border-left: .25em solid #d1d9e0; color: #59636e; padding: 0 1em;
+  margin: 0 0 16px 0; }
+table { border-collapse: collapse; margin-bottom: 16px; display: block;
+  overflow: auto; max-width: 100%; }
+table th, table td { border: 1px solid #d1d9e0; padding: 6px 13px; }
+table tr:nth-child(2n) { background: #f6f8fa; }
+ul, ol { margin-bottom: 16px; padding-left: 2em; }
+hr { height: .25em; background: #d1d9e0; border: 0; margin: 24px 0; }
+"""
+
+
+def convert(markdown_path: Path, title: str) -> str:
+    text = markdown_path.read_text(encoding="utf-8")
+    body = md_lib.markdown(text, extensions=["tables", "fenced_code", "sane_lists"])
+    return (
+        "<!DOCTYPE html>\n"
+        '<html lang="en">\n<head>\n<meta charset="utf-8">\n'
+        f"<title>{title}</title>\n"
+        f"<style>{CSS}</style>\n</head>\n<body>\n{body}\n</body>\n</html>\n"
+    )
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Convert a markdown file to standalone GitHub-like HTML."
+    )
+    parser.add_argument("input", help="input markdown file")
+    parser.add_argument("-o", "--output", help="output HTML file (default: input with .html)")
+    parser.add_argument("--title", help="HTML <title> (default: input filename stem)")
+    args = parser.parse_args()
+
+    src = Path(args.input)
+    if not src.is_file():
+        sys.stderr.write(f"error: no such file: {src}\n")
+        sys.exit(1)
+
+    out = Path(args.output) if args.output else src.with_suffix(".html")
+    title = args.title or src.stem.replace("_", " ").replace("-", " ").title()
+    out.write_text(convert(src, title), encoding="utf-8")
+    print(f"wrote {out}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/bioresearcher-plot-making/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: bioresearcher-plot-making
+description: "Biomedical visualization router and plotting engine: classifies research data and produces publication-ready scientific figures (structural protein-binder complexes, conformational dynamics, literature method summaries, developmental case registers, and evidence tables). Use when asked to plot, visualize, graph, or chart biomedical data, PDB complexes, binding modes, literature searches, or translational safety cases."
+license: Apache-2.0
+compatibility: "Any Agent Skills harness with Python 3.10+ and uv; matplotlib, pymupdf, numpy, pillow, pymol (optional for 3D)"
+metadata:
+  version: "1.0.0"
+  source: "bioresearcher-skills"
+allowed-tools: Bash Read Write Edit Glob Grep
+---
+
+# Bioresearcher Plot-Making: Visual Dispatcher & Production Engine
+
+This skill serves as the central router and quality assurance engine for
+producing publication-grade scientific figures. It directs requests to
+specialized domain plotting specifications, enforces declarative data
+contracts, and verifies outputs against deterministic geometric QA gates.
+
+## 1. Decision Matrix & Routing Table
+
+Inspect the research request and input data to select the corresponding plot
+type. Immediately load the detailed specification document using `Read`:
+
+| Generalized Plot Type | Input Data & Research Context | Reference Specification |
+| :--- | :--- | :--- |
+| **`structural-biology_binder-visualization`** | PDB/mmCIF coordinates, structural conformer comparisons, RMSF trajectories, multi-ligand binding modes, residue contact matrices (BSA, H-bonds, salt bridges). | [Structural Biology Guide](references/structural-biology-binder-visualization.md) |
+| **`literature-search_method-summary`** | Biomedical literature syntheses, translational risk pathways, developmental drug case registers (preclinical $\to$ approved), preclinical assay detection cascades, structured evidence tables. | [Literature Summary Guide](references/literature-search-method-summary.md) |
+| **`qa-gates-and-gotchas`** | Multi-panel alignment troubleshooting, vector collision audit failures, minimum glyph size compliance, hard-earned gotchas. | [QA Gates and Gotchas Guide](references/qa-gates-and-gotchas.md) |
+
+Do not generate plotting code without loading the corresponding reference guide.
+
+## 2. Production Workflow
+
+Follow this five-step workflow for all visualization requests:
+
+### Step 1: Classify and Load Domain Specification
+
+Identify the appropriate archetype from the Decision Matrix above. Load the
+corresponding specification via `Read` (e.g. `Read references/structural-biology-binder-visualization.md`).
+
+### Step 2: Ingest and Validate Declarative Data Contracts
+
+Ensure input data conforms to the required schema before writing plotting code:
+- **Structural Dynamics**: `conformer_rmsf.tsv` (`resnum`, `chain_role`, `domain`, `displacement_A`).
+- **Interaction Matrix**: `binder_hotspot_matrix.tsv` (composite `<site>:<residue>` headers, triple-encoded cells `BSA_A2|HBOND|SALTBRIDGE`).
+- **Case Register**: `literature_cases.tsv` (`entity_name`, `hazard_description`, `development_stage`, `status`, `pmids`).
+- **Detection Cascade**: `assay_cascade.tsv` (`assay_name`, `readout`, `method_family`, `screening_stage`, `pmids`).
+- **Evidence Matrix**: `evidence_table.tsv` (`citation`, `test_system`, `sample_matrix`, `analytical_method`, `readout`).
+
+### Step 3: Verify uv Python Environment & Dependencies
+
+Never rely on globally installed host packages. Ensure the project-local uv
+environment is configured (via `bioresearcher-python-setup-uv`) with all
+required visualization libraries:
+
+```bash
+./uv venv .venv
+VIRTUAL_ENV="$(pwd)/.venv" ./uv pip install pymol-open-source matplotlib pymupdf numpy pillow biopython pandas
+```
+
+If `bioresearcher-python-setup-uv` already raced and exported `UV_INDEX_URL`, keep it exported — these installs inherit it automatically.
+
+The `VIRTUAL_ENV` pin is mandatory: on hosts with an active conda/mamba environment (`CONDA_PREFIX`), bare `./uv pip install` silently targets the HOST environment instead of `./.venv`.
+
+Never execute plotting scripts that write outputs to the workspace root:
+- Create a dedicated target directory: `figures/<TARGET>/`.
+- Place or generate data files directly inside `figures/<TARGET>/`.
+- Ensure all Python scripts resolve relative paths via `Path(__file__).resolve().parent`.
+
+### Step 4: Execute Deterministic Plotting Script
+
+Run the figure generation script using the project-local interpreter:
+
+```bash
+./.venv/bin/python fig1.py
+# Or for standalone PyMOL scripts:
+# ./.venv/bin/pymol -cq render_script.py
+```
+
+### Step 5: Enforce Three-Layer Quality Assurance (QA)
+
+Certify figures before delivery:
+1. **Layer 1 (Static Source Preflight)**: Enforce standard typography (`font.family='sans-serif'`, base size 7 pt) and vector formats (`pdf.fonttype=42`, `svg.fonttype='none'`).
+2. **Layer 2 (Deterministic Geometry Gates)**:
+   - Run panel alignment gate (`audit_panel_alignment.py`): max deviation $\le 1.5\text{ pt}$.
+   - Run vector collision audit (`audit_figure_collisions.py`): 0 FAIL.
+   - Run font floor audit (`audit_pdf_text.py`): minimum glyph size $\ge 5.0\text{ pt}$.
+3. **Layer 3 (Vision Model Semantic Review)**: Ask focused, single-question queries to verify biological topology and icon orientation.
+
+## 3. Core Gotchas Summary
+
+- **CWD Drift**: Relative save paths silently write to the process cwd; always verify outputs exist in the target directory with fresh timestamps.
+- **Probe Render Trick**: Never render 3D text labels in PyMOL; extract 2D projection coordinates via a probe pass (`render_anchors.json`) and draw native vector text in Matplotlib.
+- **Contact-Fragment Pruning**: Superimposing full macromolecules buries the receptor; prune ligands to residues within 8 Å plus 3-residue extension.
+- **Dynamic Text Advance**: Use `right_edge()` taking `max(ink_bbox, advance_width)` to space inline text; character-count heuristics fail on proportional fonts.
+- **Baseline Staggering**: Alternate column header baselines ($y=9.50$ vs $8.98$) to prevent PDF parsers from merging adjacent text runs.
+- **Aspect Ratio Desync**: Panels sharing a row with `aspect='equal'` will letterbox and drift vertically unless physical aspect ratios match.