opencode-bioresearcher 1.6.0

package/skills/bioresearcher-plot-making/references/literature-search-method-summary.md

@@ -0,0 +1,163 @@
+# Literature Search Method Summary Specification
+
+This guide specifies the production of publication-grade figures that synthesize complex, heterogeneous biomedical literature, clinical case registers, and preclinical assay cascades into standardized vector graphics.
+
+---
+
+## 1. Provenance Architecture & Verification Protocol
+
+Literature syntheses risk metric drift, recall errors, and false categorizations. Enforce strict verification before drawing:
+
+1. **NCBI E-Utilities Primary Verification**:
+   - Verify every PMID against NCBI E-Utilities (`esummary` / `efetch`).
+   - Extract and cross-check official publication year, journal, author list, and compound identifiers.
+   - *Case Lesson*: LLM recall frequently confuses adjacent PMIDs (e.g. unrelated papers or case reports). Never transcribe PMIDs from memory.
+2. **Evidence Balance Principle**:
+   - For every flagged safety risk or adverse event, include at least one well-tolerated benchmark or counterexample.
+   - For uncharacterized areas, include dedicated "evidence gap" indicators (gray markers) rather than omitting the domain.
+3. **Information Partitioning**:
+   - **On-Figure**: High-level qualitative hazard descriptors, developmental stage markers, and compact PMID tags (`tag_right(ax, "PMIDs ...", y)`).
+   - **In Legends (`LEGENDS.md`)**: Full quantitative cohort sizes, trial names, percentage incidences, and detailed assay parameters.
+
+---
+
+## 2. Declarative Data Contracts
+
+Decouple literature curation from matplotlib scripts using structured TSV tables.
+
+### Contract A: Developmental Case Register (`literature_cases.tsv`)
+Represents clinical and preclinical benchmark cases mapped across development:
+```tsv
+entity_name	structural_tag	hazard_description	development_stage	status	pmids
+Agent_Alpha	Kinase inhibitor (type II)	Grade-3 hepatotoxicity; Phase 3 terminated	phase 3	adverse_signal	00000001
+Agent_Beta	Kinase inhibitor (type I)	Tolerated benchmark; 0% transaminase elevation	approved	no_signal	00000002
+Agent_Gamma	Proteolysis degrader	Chronic tissue accumulation; under-reported	preclinical	under_reported	00000003
+```
+*Valid Stages*: `preclinical | phase 1 | phase 2 | phase 3 | approved`  
+*Valid Statuses*: `adverse_signal (red) | no_signal (green) | under_reported (gray)`
+
+### Contract B: Preclinical Detection Cascade (`assay_cascade.tsv`)
+Represents orthogonal screening assays arranged in a tiered detection matrix:
+```tsv
+assay_name	readout	method_family	screening_stage	pmids
+Reporter gene panel	Stress pathway activation	flow cytometry	preclinical	00000004
+Viability panel	Growth inhibition IC50	biochemical	in vitro lead	00000005
+Surface plasmon res	Binding kinetics	biochemical	orthogonal screen	00000006
+```
+*Valid Method Families*: `in silico | proteomics | flow cytometry | biochemical | MS bioanalysis | imaging | in vivo`
+
+### Contract C: Structured Evidence Matrix (`evidence_table.tsv`)
+Represents single-panel literature landscapes:
+```tsv
+row_id	scope_tag	citation	journal	pmid	test_system	sample_matrix	analytical_method	readout
+1	core	Author 2025	Nat Commun	00000010	Engineered kinase inhibitor	A549 cells	Phosphoproteomics	ERK pathway suppression
+2	protocol	Author 2016	Nat Protoc	00000011	Morphological assay	HeLa cells	High-content imaging	Phenotypic feature matrix
+3	transfer	Author 2024	Bioorg Chem	00000012	Small-molecule reference	HepG2 spheroids	LC-MS/MS	Off-target binding screen
+```
+*Valid Scope Tags*: `core (amber badge) | protocol (dagger †) | transfer (double dagger ‡) | benchmark`
+
+---
+
+## 3. Visual Archetype 1: The Three-Panel Composite (180 x 120 mm)
+
+The Three-Panel Composite pairs a biological concept schematic with an empirical case register and an assay detection matrix:
+
+```
++------------------------------------------+-------------------------------------------+
+| Panel a: Mechanistic Concept Diagram     | Panel b: Developmental Case Register      |
+| [0.035, 0.355, 0.435, 0.585]             | [0.525, 0.355, 0.440, 0.585]              |
+| - Topological cellular layout            | - Interventions + structural tags         |
+| - Membrane bilayers & receptors          | - Plain-language hazard summaries         |
+| - Compartments: cytosol, lysosome, mito  | - Developmental timeline dot axis         |
+| - Directional trajectory of risk         | - Tri-color status dots (red/green/gray)  |
++------------------------------------------+-------------------------------------------+
+| Panel c: Preclinical Detection Cascade Matrix Strip [0.035, 0.050, 0.930, 0.270]     |
+| - Columns: Assay | What it reads out | Method Family Chip (colored) | Typical Stage  |
+| - Alternating row banding (#F7F7F7) | Fixed column grid anchors                      |
++--------------------------------------------------------------------------------------+
+```
+
+### Layout Rules
+- **Panel a (Mechanics)**: Maintain strict biological topology. Receptors must sit within lipid bilayers with lumen/extracellular orientation preserved. Intracellular routes must terminate in bounded organelle compartments.
+- **Panel b (Cases)**: Position timeline stage columns with alternating baselines ($y = 9.50$ vs $8.98$) to prevent PDF text merging. Stagger rows with a pitch of $1.35$–$1.45$ data units. Directly above the provenance footer, always render the explicit status dot glyph legend:
+  ```python
+  for x_pt, col, lbl in [(0.30, PALETTE["danger"], "adverse signal"),
+                         (3.40, PALETTE["safe"], "no signal"),
+                         (6.70, PALETTE["gap"], "under-reported")]:
+      axb.plot(x_pt, 0.85, "o", color=col, ms=4.0, mec="white", mew=0.5)
+      axb.text(x_pt + 0.25, 0.85, lbl, fontsize=5.2, color=col, fontweight="bold", va="center")
+  ```
+- **Panel c (Assays)**: Full-width strip with alternating row backgrounds (`#F7F7F7`). Method family chips use rounded boxes (`FancyBboxPatch`, rounding 0.10) with bold 5.2 pt white text. Always include the assay PMID provenance footer at valid data coordinate $y = 0.35$ (inside $[0, 10]$):
+  ```python
+  tag_right(axc, "assay PMIDs: " + " · ".join(unique_pmids), 0.35)
+  ```
+
+---
+
+## 4. Visual Archetype 2: Single-Panel Structured Evidence Table (180 x 124–128 mm)
+
+For emerging literature landscapes, synthesize heterogeneous study designs into an vector-rendered evidence table:
+
+- **Single Axis**: `[0.030, 0.035, 0.940, 0.920]`
+- **Header Banner**: Bold thematic title with scope qualification text.
+- **Fixed Column Grid**: Allocate horizontal positions based on data complexity:
+  - Column 1: Row index / scope badge
+  - Column 2: Citation (`Author YYYY`), Journal, PMID
+  - Column 3: Test System / Compound
+  - Column 4: Sample Matrix / Cell Type
+  - Column 5: Analytical Workflow
+  - Column 6: Quantitative / Phenotypic Readout
+- **Font-Aware Text Wrapping**: Wrap multi-line cell entries dynamically using `wrap_cell_text()` to prevent text from overflowing column bounds and failing collision audits.
+- **Taxonomic Footnote**: Include explicit scope exclusions and sample boundaries at the bottom of the table.
+
+---
+
+## 5. Low-Level Matplotlib Engineering Patterns
+
+### Dynamic Text Spacing
+Proportional fonts cause character-count heuristics to fail. Always compute inline spacing using `right_edge`:
+```python
+from plot_helpers import right_edge
+
+t_name = axb.text(0.15, top - 0.34, case.entity_name, fontsize=6.2, fontweight="bold")
+tag_x = right_edge(axb, t_name) + 0.30
+axb.text(tag_x, top - 0.34, case.structural_tag, fontsize=5.2, color="#5A5A5A")
+```
+
+### Provenance Edge Pinning
+Pin citations flush against panel right edges using blended transforms:
+```python
+from plot_helpers import tag_right
+
+tag_right(axa, "mechanistic anchors: PMIDs 12345678, 23456789", 0.22)
+```
+
+### Eliminating PDF Baseline Merging
+When multiple headers share identical vertical coordinates, PDF extraction tools merge adjacent words into single garbled text runs. Always alternate header baselines:
+```python
+stages = [
+    ("preclinical", 5.95, 9.50),
+    ("phase 1",     7.20, 8.98),
+    ("phase 3",     8.40, 9.50),
+    ("approved",    9.42, 8.98),
+]
+for name, x, y in stages:
+    axb.text(x, y, name, fontsize=5.2, color="#5A5A5A", fontweight="bold", ha="center")
+```
+
+---
+
+## 6. Literature Summary QA Gate Checklist
+
+Before certifying any literature summary figure for release, verify:
+
+- [ ] Every PMID is validated against NCBI E-Utilities (`esummary`/`efetch`).
+- [ ] At least one tolerated counterexample and any evidence gaps are explicitly displayed.
+- [ ] Script resolves paths via `Path(__file__).resolve().parent`.
+- [ ] Biological topology is correct (bilayers, organelles, flow directions).
+- [ ] Column header baselines are staggered to prevent PDF text merging.
+- [ ] Inline text runs are spaced using `right_edge` dynamic metrics.
+- [ ] Table cells are wrapped using `wrap_cell_text` (no column overflow).
+- [ ] Figure passes `require_matplotlib_panel_alignment` with deviation $\le 1.5\text{ pt}$.
+- [ ] Vector PDF passes `audit_figure_collisions.py` with 0 FAIL.
+- [ ] All rendered text meets the $\ge 5.0\text{ pt}$ font size floor.

package/skills/bioresearcher-plot-making/references/qa-gates-and-gotchas.md

@@ -0,0 +1,156 @@
+# Quality Assurance Gates and Hard-Earned Gotchas
+
+This guide details the three-layer quality assurance (QA) pipeline and provides the complete catalog of hard-earned scientific plotting gotchas.
+
+---
+
+## 1. The Three-Layer Quality Assurance Architecture
+
+Every figure produced under `bioresearcher-plot-making` must pass three independent verification layers before publication.
+
+```
++-----------------------------------------------------------------------------------+
+| LAYER 1: STATIC SOURCE PREFLIGHT (Fast AST Check)                                 |
+| - Verifies rcParams: font.family='sans-serif', font floor >= 5.0 pt               |
+| - Verifies vector export: pdf.fonttype=42, svg.fonttype='none'                    |
+| - Confirms explicit panel alignment gate call in script source                    |
++-----------------------------------------------------------------------------------+
+                                         │ PASS
+                                         ▼
++-----------------------------------------------------------------------------------+
+| LAYER 2: RENDER-TIME DETERMINISTIC GEOMETRY GATES                                 |
+| 1. Panel Alignment Gate (scripts/audit_panel_alignment.py):                       |
+|    - Measures panel bounding boxes; enforces max tolerance <= 1.5 pt on rows/cols |
+|    - Exports *.alignment.json audit trail and *.alignment.svg overlay            |
+| 2. Vector PDF Collision Audit (scripts/audit_figure_collisions.py):                |
+|    - Detects text-text collisions, text-stroke crossings, canvas clipping         |
+|    - Enforces 0 FAIL (contained chip/badge fills permitted with WARN review)      |
+| 3. Glyph Floor Stream Audit (scripts/audit_pdf_text.py):                          |
+|    - Decodes PDF FlateDecode streams; verifies all 'Tf' font operators >= 5.0 pt  |
++-----------------------------------------------------------------------------------+
+                                         │ PASS
+                                         ▼
++-----------------------------------------------------------------------------------+
+| LAYER 3: VISION-MODEL PERCEPTUAL INSPECTION                                       |
+| - Single-question semantic verification queries                                   |
+| - Evaluates biological topology, pocket illumination, and unoccluded views        |
++-----------------------------------------------------------------------------------+
+```
+
+---
+
+## 2. Bundled Execution of Layer 2 QA Tools
+
+The skill bundles three deterministic audit tools under `scripts/`:
+
+### A. Panel Alignment Gate (`audit_panel_alignment.py`)
+Verifies that multi-panel rows and columns align to within $1.5\text{ pt}$:
+```python
+from audit_panel_alignment import require_matplotlib_panel_alignment
+
+# Multi-panel composite layout
+require_matplotlib_panel_alignment(
+    fig,
+    json_out="figure.alignment.json",
+    overlay_svg="figure.alignment.svg",
+    tolerance_pt=1.5,
+    strict=True,
+    panel_ids={axa: "a", axb: "b", axc: "c"},
+    row_groups=[["a", "b"]],
+)
+
+# Single-panel table layout (invariant: provide panel_ids to generate audit trail)
+require_matplotlib_panel_alignment(
+    fig,
+    json_out="table.alignment.json",
+    overlay_svg="table.alignment.svg",
+    tolerance_pt=1.5,
+    panel_ids={ax: "a"},
+)
+```
+
+### B. Vector PDF Collision Audit (`audit_figure_collisions.py`)
+Extracts text and path geometry from exported PDFs using PyMuPDF to flag overlaps:
+```bash
+./.venv/bin/python skills/bioresearcher-plot-making/scripts/audit_figure_collisions.py figure.pdf --json-out figure.collision-audit.json
+```
+- **FAIL Criteria**: Uncontained text-text collisions, text-stroke crossings, or canvas clipping.
+- **WARN Criteria**: Contained text overlays (e.g. text inside colored method family chips).
+
+### C. Glyph Size Floor Audit (`audit_pdf_text.py`)
+Parses low-level PDF font definitions to ensure no text falls below $5.0\text{ pt}$:
+```bash
+./.venv/bin/python skills/bioresearcher-plot-making/scripts/audit_pdf_text.py figure.pdf --min-pt 5.0
+```
+
+---
+
+## 3. The Catalog of Hard-Earned Gotchas
+
+### Process & Environment
+1. **Silent CWD Audit Pass Trap**:
+   - *Failure*: Saving with relative paths (`fig.pdf`) writes to the process current working directory. Running from repo root writes outputs to root while QA scripts audit stale files in the subfolder.
+   - *Fix*: Always resolve paths via `Path(__file__).resolve().parent`.
+2. **Silent Text Patch Failure**:
+   - *Failure*: Replacing text coordinates via regex or string replacement fails silently when surrounding lines drift, creating near-duplicate elements that trigger collision failures.
+   - *Fix*: Verify exact string replacements; rerun full QA suite after every edit.
+
+### 3D Macromolecular Rendering
+3. **Multi-Ligand Clutter**:
+   - *Failure*: Superimposing multiple full macromolecular binders completely buries the receptor.
+   - *Fix*: Prune binders to contact fragments: `byres ((ligand) within 8.0 of receptor) extend 3`.
+4. **Dark Cavity & Back-Face Voids**:
+   - *Failure*: Transparent surfaces produce black internal faces and polygon clipping.
+   - *Fix*: Use an opaque soft-gray surface (`#CDCDD4`) with `two_sided_lighting 1`, `ambient 0.50`, and a $+18^\circ$ camera tilt.
+5. **Distorted In-Scene Raster Labels**:
+   - *Failure*: PyMOL bitmap text (`cmd.label`) pixelates and scales unpredictably.
+   - *Fix*: Run a probe render pass to export 2D projected coordinates (`render_anchors.json`); render native vector text in Matplotlib.
+6. **Multi-Ligand Crystal Mixing**:
+   - *Failure*: Co-crystal PDBs containing multiple binders aggregate improperly when filtered only by PDB ID.
+   - *Fix*: Key interface extraction on the tuple: `(pdb_id, copy_id, binder_id)`.
+
+### Geometry & Axes Alignment
+7. **`aspect='equal'` Letterbox Desync**:
+   - *Failure*: `aspect='equal'` letterboxes axes within declared rectangles; row panels silently drift in height by points.
+   - *Fix*: Panels sharing a row must have identical physical aspect ratios or use `equal=False`.
+8. **Hidden Rounded-Corner Arcs**:
+   - *Failure*: `FancyBboxPatch` corners cut inward; text near rectangular edges collides with curvature strokes.
+   - *Fix*: Leave generous internal padding ($> 1.5 \times \text{rounding\_size}$).
+9. **Unclipped Text Spills**:
+   - *Failure*: `Patch` artists are clipped to axes by default, but `Text` has `clip_on=False`.
+   - *Fix*: Never park text outside declared axes limits; labels spill into neighboring subplots.
+10. **Curved Arrow Apex Bulges**:
+    - *Failure*: Curved arrows (`arc3,rad=0.2`) bulge outward; markers on paths get flagged as text-through-stroke.
+    - *Fix*: Place badges beside paths, not on them. Keep curvature radius minimal.
+
+### Typography & Text Metrics
+11. **Glyph Advance vs Ink Bbox**:
+    - *Failure*: `get_window_extent()` only measures drawn ink, ignoring font side bearings; inline text runs collide.
+    - *Fix*: Use `right_edge()` combining ink bbox and renderer advance width.
+12. **PDF Text Run Merging**:
+    - *Failure*: Adjacent column headers sharing an identical vertical baseline get merged into garbled text runs by PDF parsers.
+    - *Fix*: Stagger vertical baselines alternately ($y = 9.50$ vs $8.98$).
+13. **Legend Accumulation Drift**:
+    - *Failure*: Chaining dynamic text measurements sequentially across horizontal legends accumulates errors.
+    - *Fix*: For static legend items, use fixed relative offsets rather than chained dynamic measurements.
+14. **Multi-Line Independent Centering Spill**:
+    - *Failure*: Multi-line text with `ha='center'` centers each line independently; one long line breaks container bounds and clips or collides with adjacent strokes.
+    - *Fix*: Keep line lengths balanced or compute explicit block centering using `wrap_cell_text()`.
+
+### Data Synthesis & Quantitative Mechanics
+15. **In-Plot Mean Box Collisions**:
+    - *Failure*: Placing a mean baseline text box inside a profile plot collides with high data spikes.
+    - *Fix*: Remove in-plot box; integrate mean label directly into y-axis tick labels (`f"{mean:.2f}\n(mean)"`).
+16. **Manual Callout Coordinate Drift**:
+    - *Failure*: Manually placing peak callout arrows leads to arrows pointing at sub-peaks or background noise.
+    - *Fix*: Compute callout coordinates via algorithmic peak picking (`np.argmax(...)`).
+
+### Vision Model Inspection
+17. **Vision LLM Timeout on Complex Prompts**:
+    - *Failure*: Asking multiple visual questions in one prompt causes timeouts and hallucinations.
+    - *Fix*: Ask single-question, short prompts sequentially. Trust measured PDF coordinates for geometry.
+
+### Synchronized Multi-Panel Plots
+18. **`imshow` vs `barh` Vertical Inversion & Row Drift**:
+    - *Failure*: Matplotlib `imshow` defaults to top-to-bottom (`origin="upper"`), whereas `barh` plots bottom-to-top. Furthermore, default 5% axis margins cause horizontal bar centers to drift by multiple points from heatmap rows.
+    - *Fix*: Invert y-coordinates (`y_pos = np.arange(n)[::-1]`) AND explicitly set `ax.set_ylim(-0.5, n - 0.5)` to eliminate vertical row drift.

package/skills/bioresearcher-plot-making/references/structural-biology-binder-visualization.md

@@ -0,0 +1,206 @@
+# Structural Biology Binder Visualization Specification
+
+This guide specifies the production of publication-grade figures for protein–binder complexes, conformational plasticity, and multi-ligand interaction landscapes.
+
+---
+
+## 1. Domain Abstraction: The Entity-State-Topology-Matrix (ESTM) Model
+
+To keep visualization pipelines target-agnostic, abstract concrete biological entities into four standardized roles:
+
+1. **Target Receptor Entity**:
+   - **Primary Subunit**: Functional or catalytic chain carrying core interaction domains.
+   - **Secondary Subunit**: Heterodimer partner, invariant light chain, or structural scaffold.
+   - **Domain Architecture**: Contiguous residue intervals defining structural subdomains.
+2. **Conformational & Dynamic States**:
+   - **Reference State**: Apo, resting, wild-type, or physiological baseline structure.
+   - **Perturbed State**: Holo, active, acidic/basic, mutant, or simulated conformation.
+   - **Displacement Metric**: Euclidean vector displacement ($\Delta r_i = \|\mathbf{r}_i^{\text{state}_2} - \mathbf{r}_i^{\text{state}_1}\|_2$) or root-mean-square fluctuation (RMSF).
+3. **Binder Modality Registry**:
+   - Modalities: Monoclonal antibodies/Fabs, engineered scaffold proteins, cyclic/linear peptides, small molecules.
+   - Status: Active lead, preclinical benchmark, terminated/failed candidate, evidence gap.
+4. **Interaction Hotspot Topology**:
+   - Consensus Sites: Spatially segregated binding pockets (e.g. Site 1, Site 2).
+   - Interaction Dimensions: Continuous buried surface area (BSA) and discrete non-covalent contacts (hydrogen bonds, salt bridges).
+
+---
+
+## 2. Declarative Data Contracts
+
+Decouple scientific data curation from rendering code by adhering to strict TSV/JSON schemas.
+
+### Contract A: Conformer Dynamics (`conformer_rmsf.tsv`)
+Stores per-residue C$\alpha$ displacement between structural states:
+```tsv
+resnum	resname	chain_id	chain_role	domain	displacement_A	b_factor
+10	ALA	A	Primary	Domain1	0.4500	42.10
+11	GLY	A	Primary	Domain1	0.3200	38.50
+90	ASP	A	Primary	Domain2	0.2150	22.40
+2	VAL	B	Secondary	Scaffold	0.4120	18.20
+```
+
+### Contract B: Binder Hotspot Matrix (`binder_hotspot_matrix.tsv`)
+Composite column headers `<site>:<residue>` enable automatic generation of vertical partition dividers and site header chips. Cells use triple-encoding: `BSA_A2|HBOND_FLAG|SALTBRIDGE_FLAG`:
+```tsv
+binder_name	modality	target_site	Site1:R101	Site1:D105	Site2:K201	Site2:E204
+Binder_Fab_1	FAB	Site1	112.5|1|0	84.2|1|0	0.0|0|0	0.0|0|0
+Binder_Fc_2	FC	Site1	46.3|1|0	107.7|0|0	0.0|0|0	0.0|0|0
+Binder_Protein_3	PROTEIN	Site2	0.0|0|0	0.0|0|0	188.3|1|0	0.0|0|0
+```
+
+### Contract C: Binder Summary Metrics (`binder_summary_data.tsv`)
+Stores energetic metrics partitioned by receptor subunit:
+```tsv
+binder_id	binder_name	modality	target_site	bsa_primary	bsa_secondary	bsa_total	n_hbonds	n_saltbridges
+PDB1	Binder_Fab_1	FAB	Site1	520.0	80.0	600.0	4	0
+PDB2	Binder_Fc_2	FC	Site1	310.0	22.0	332.0	2	1
+PDB3	Binder_Protein_3	PROTEIN	Site2	640.0	90.0	730.0	6	2
+```
+
+### Contract D: Projected Chain Anchors (`render_anchors.json`)
+Stores 2D projection coordinates $(c_x, c_y)$ extracted from PyMOL camera probe passes:
+```json
+{
+  "frame": [2200, 1500],
+  "chain_labels": {
+    "primary": {
+      "display_text": "Primary Subunit",
+      "cx": 0.85,
+      "cy": 0.50,
+      "side": "right"
+    },
+    "secondary": {
+      "display_text": "Secondary Subunit",
+      "cx": 0.15,
+      "cy": 0.50,
+      "side": "left"
+    }
+  }
+}
+```
+
+---
+
+## 3. Headless PyMOL Orchestration Protocol
+
+Run PyMOL directly from the project-local uv environment (`./uv venv .venv` once, then `VIRTUAL_ENV="$(pwd)/.venv" ./uv pip install pymol-open-source`).
+Execution modes:
+- **Python API**: Run scripts using `./.venv/bin/python script.py` with `from pymol import cmd`.
+- **Virtualenv CLI**: Run standalone PyMOL scripts via `./.venv/bin/pymol -cq script.py`.
+
+Adhere to these essential rendering rules:
+
+### A. Contact-Fragment Pruning & Ligand Display
+Superimposing full-length macromolecular complexes buries the receptor. Prune protein binders to contact interfaces:
+```python
+# Select residues within 8.0 Angstroms of receptor, extend by 3 residues for ribbon continuity
+frag_sel = f"byres (({ligand_obj} and ({ligand_chains})) within 8.0 of ({receptor_obj}))"
+cmd.select(f"frag_{code}", f"byres (({frag_sel}) extend 3)")
+cmd.show("cartoon", f"frag_{code}")
+
+# Small molecules / covalent inhibitors: show in sticks with element coloring (orange carbons)
+cmd.show("sticks", f"{ligand_obj} and not polymer")
+cmd.color("orange", f"{ligand_obj} and name C*")
+```
+
+### B. Camera Orientation Modes (Disentangled)
+
+Disentangle the camera framing based on panel objective:
+
+- **Mode A (Conformational Ribbon Superposition)**:
+  Used when comparing structural states (apo vs holo, active vs inactive) to view secondary structure without cavity foreshortening:
+  ```python
+  cmd.orient("ref_structure")
+  cmd.turn("y", 20)
+  cmd.turn("x", -10)
+  cmd.zoom("ref_structure", buffer=2.5)
+  ```
+
+- **Mode B (Cavity Hotspot Surface)**:
+  Used when orienting an opaque receptor surface directly into an interior binding pocket:
+  ```python
+  import numpy as np
+
+  c_site = np.array(cmd.centerofmass(site_selection))
+  c_rec  = np.array(cmd.centerofmass(receptor_selection))
+
+  # Calculate outward normal vector
+  Z = (c_site - c_rec) / np.linalg.norm(c_site - c_rec)
+  up = np.array([0.0, 0.0, 1.0])
+  if abs(np.dot(up, Z)) > 0.9:
+      up = np.array([0.0, 1.0, 0.0])
+  X = np.cross(up, Z); X /= np.linalg.norm(X)
+  Y = np.cross(Z, X)
+  R = np.array([X, Y, Z])
+
+  # Apply transform with focal standoff distance and interior tilt
+  o = c_rec - 180.0 * Z
+  cmd.set_view(tuple(R.flatten().tolist() + o.tolist() + list(cmd.get_view()[12:])))
+  cmd.turn("x", 18)  # 18-degree tilt illuminates binding pocket interior
+  ```
+
+### C. Studio Lighting & Surface Geometry
+Prevent black back-face artifacts and polygonal facets:
+```python
+cmd.set("antialias", 2)
+cmd.set("cartoon_sampling", 2)
+cmd.set("two_sided_lighting", 1)  # Eliminates dark cavity back-faces
+cmd.set("ray_shadows", 0)         # Disables harsh interior drop-shadows
+cmd.set("ambient", 0.50)          # Fills deep pockets evenly
+cmd.set("direct", 0.60)
+cmd.set("hash_max", 300)          # High tessellation prevents polygon facets
+```
+
+### D. The Probe Render Pass for Vector Text Anchors
+Never use PyMOL bitmap text (`cmd.label`) in final publication figures. Execute a labels-only probe pass to export 2D projected anchor coordinates (`render_anchors.json`), then render sharp vector text in Matplotlib within dedicated padding gutters (`LABEL_PAD = 210 px`).
+
+---
+
+## 4. 2D Matplotlib Compositing Architecture
+
+### Layout Decoupling
+1. **Header Strips**: Place panel letters (`a`, `b`) and state tags in dedicated thin header axes (`height 0.040`) above 3D views.
+2. **Side Legend Columns**: Place color keys and modality chips in separate vertical axes flanking the 3D views.
+3. **Content Bounding-Box Cropping**: Load transparent 3D renders using `load_render_cropped(png_path, pad=(210, 12, 210, 12))` to reserve lateral margins for vector labels while maximizing structural scale.
+
+### Quantitative Plot Mechanics (Derived from Case Studies)
+- **1D Profile with Peak Callouts**: Callout dots must be positioned at true mathematical local maxima using windowed argmax (`np.argmax(...)`). Mean baseline must be integrated into y-axis tick labels (`f"{mean:.2f}\n(mean)"`) to prevent collision with data spikes. Callout text must be offset sufficiently from shaded region boundaries to avoid text-fill-edge warnings.
+- **Native Glyph Legend**: Bind glyphs directly to labels using Matplotlib's native legend placed beneath Panel c:
+  ```python
+  axc.plot([], [], marker="o", color="#1A1A1A", ls="none", markersize=3.0, label="H-bond")
+  axc.plot([], [], marker="^", color="#1B6CA8", ls="none", markersize=3.5, label="Salt bridge")
+  axc.legend(loc="upper left", bbox_to_anchor=(0.0, -0.22), ncol=2, fontsize=5.2, frameon=False)
+  ```
+- **Horizontal Colorbar Inset**: Place colorbar horizontally beneath the matrix beside the glyph legend (never vertical across heatmap rows):
+  ```python
+  cb_ax = fig.add_axes([0.32, 0.025, 0.15, 0.015])
+  cb = mpl.colorbar.ColorbarBase(cb_ax, cmap=cmap, norm=norm, orientation="horizontal")
+  cb_ax.text(1.06, 0.5, "BSA per residue (Ų)", transform=cb_ax.transAxes, fontsize=5.2, va="center", ha="left")
+  # Always pass cb_ax to exclude_axes in export_publication_figure
+  ```
+- **Gotcha 18: Heatmap & Bar Chart Row Synchronization**: Matplotlib `imshow` defaults to top-to-bottom (`origin="upper"`), whereas `barh` plots bottom-to-top. To keep horizontal bars aligned with heatmap rows and eliminate vertical row drift:
+  ```python
+  y_pos_rev = np.arange(n)[::-1]
+  axd.barh(y_pos_rev, bsa_vals, ...)
+  axd.set_ylim(-0.5, n - 0.5)  # Mandatory: prevents Matplotlib 5% margin row drift
+  ```
+- **Panel d Title & Labeling**: Set `axd.set_title("Total Interface BSA (Ų)", fontsize=6.5, fontweight="bold", pad=3)` and `axd.set_xlabel("Interface BSA (Ų)", fontsize=6.2)`.
+
+---
+
+## 5. Structural Biology QA Gate Checklist
+
+Before finalizing any binder visualization figure, verify:
+
+- [ ] PDB structures, chain identifiers, and sequence indexing are confirmed against primary records.
+- [ ] Working directory is resolved via `Path(__file__).resolve().parent`.
+- [ ] Ray-traced PNGs are high-resolution ($\ge 2200 \times 1600\text{ px}$) with `antialias 2`.
+- [ ] No titles, colorbars, or text labels sit inside 3D render panels.
+- [ ] Chain annotations are rendered as vector text in Matplotlib using `render_anchors.json`.
+- [ ] Macromolecular binders are pruned to contact fragments ($\le 8\text{ Å}$ from receptor $+ 3\text{ residues}$).
+- [ ] Surface is opaque with `two_sided_lighting 1` and $+18^\circ$ camera tilt (no black back-faces).
+- [ ] Peak callouts in sequence profiles use algorithmic windowed peak picking.
+- [ ] Stacked BSA bar totals equal the exact sum of partitioned chain values.
+- [ ] Figure passes `require_matplotlib_panel_alignment` with deviation $\le 1.5\text{ pt}$.
+- [ ] Exported vector PDF passes `audit_figure_collisions.py` with 0 FAIL.
+- [ ] Font size audit passes $\ge 5.0\text{ pt}$ floor across all text elements.