From cbdb84cb4b3c4d3e04f4143dc13e68748a33b2eb Mon Sep 17 00:00:00 2001
From: jvogan <6239693+jvogan@users.noreply.github.com>
Date: Fri, 17 Jul 2026 12:42:50 -0700
Subject: [PATCH] Add reproducible structural visualization workflows

---
 .github/workflows/ci.yml                      |   4 +
 CHANGELOG.md                                  |   9 +
 CONTRIBUTING.md                               |   1 +
 Makefile                                      |   7 +-
 README.md                                     |  37 +
 SKILL.md                                      | 722 +++++-------------
 references/chimerax.md                        |  14 +-
 references/workflows.md                       | 224 ++++++
 scripts/annotation_figure.py                  | 197 +++++
 scripts/assembly_explorer.py                  | 132 ++++
 scripts/chemical_site.py                      | 226 ++++++
 scripts/chimerax_rest.py                      |   6 +-
 scripts/cryoem_workflow.py                    | 221 ++++++
 scripts/electrostatics_workflow.py            | 113 +++
 scripts/ensemble_report.py                    | 210 +++++
 scripts/interface_story.py                    | 192 +++++
 scripts/model_quality.py                      | 150 +++-
 scripts/pae_report.py                         |  75 +-
 scripts/pocket_tunnel.py                      | 210 +++++
 scripts/proteus.py                            |  66 ++
 scripts/proteus_batch.py                      |  23 +
 scripts/proteus_common.py                     | 345 +++++++++
 scripts/proteus_doctor.py                     |  32 +
 scripts/residue_story.py                      | 167 ++++
 scripts/restraint_report.py                   | 217 ++++++
 scripts/scene_figure.py                       | 296 +++++++
 scripts/state_compare.py                      | 173 +++++
 scripts/structure_info.py                     |  37 +-
 scripts/structure_qc.py                       | 486 ++++++++++++
 scripts/sync_skill_package.py                 |  78 ++
 scripts/visual_common.py                      | 248 ++++++
 skills/proteus/SKILL.md                       | 722 +++++-------------
 skills/proteus/agents/openai.yaml             |   7 +-
 skills/proteus/references/chimerax.md         |  14 +-
 skills/proteus/references/workflows.md        | 224 ++++++
 skills/proteus/scripts/annotation_figure.py   | 197 +++++
 skills/proteus/scripts/assembly_explorer.py   | 132 ++++
 skills/proteus/scripts/chemical_site.py       | 226 ++++++
 skills/proteus/scripts/chimerax_rest.py       |   6 +-
 skills/proteus/scripts/cryoem_workflow.py     | 221 ++++++
 .../scripts/electrostatics_workflow.py        | 113 +++
 skills/proteus/scripts/ensemble_report.py     | 210 +++++
 skills/proteus/scripts/interface_story.py     | 192 +++++
 skills/proteus/scripts/model_quality.py       | 150 +++-
 skills/proteus/scripts/pae_report.py          |  75 +-
 skills/proteus/scripts/pocket_tunnel.py       | 210 +++++
 skills/proteus/scripts/proteus.py             |  66 ++
 skills/proteus/scripts/proteus_batch.py       |  23 +
 skills/proteus/scripts/proteus_common.py      | 345 +++++++++
 skills/proteus/scripts/proteus_doctor.py      |  32 +
 skills/proteus/scripts/residue_story.py       | 167 ++++
 skills/proteus/scripts/restraint_report.py    | 217 ++++++
 skills/proteus/scripts/scene_figure.py        | 296 +++++++
 skills/proteus/scripts/state_compare.py       | 173 +++++
 skills/proteus/scripts/structure_info.py      |  37 +-
 skills/proteus/scripts/structure_qc.py        | 486 ++++++++++++
 skills/proteus/scripts/visual_common.py       | 248 ++++++
 tests/test_workflows.py                       | 220 ++++++
 58 files changed, 8802 insertions(+), 1125 deletions(-)
 create mode 100644 references/workflows.md
 create mode 100644 scripts/annotation_figure.py
 create mode 100644 scripts/assembly_explorer.py
 create mode 100644 scripts/chemical_site.py
 create mode 100644 scripts/cryoem_workflow.py
 create mode 100644 scripts/electrostatics_workflow.py
 create mode 100644 scripts/ensemble_report.py
 create mode 100644 scripts/interface_story.py
 create mode 100644 scripts/pocket_tunnel.py
 create mode 100644 scripts/proteus.py
 create mode 100644 scripts/proteus_common.py
 create mode 100644 scripts/residue_story.py
 create mode 100644 scripts/restraint_report.py
 create mode 100644 scripts/scene_figure.py
 create mode 100644 scripts/state_compare.py
 create mode 100644 scripts/structure_qc.py
 create mode 100644 scripts/sync_skill_package.py
 create mode 100644 scripts/visual_common.py
 create mode 100644 skills/proteus/references/workflows.md
 create mode 100644 skills/proteus/scripts/annotation_figure.py
 create mode 100644 skills/proteus/scripts/assembly_explorer.py
 create mode 100644 skills/proteus/scripts/chemical_site.py
 create mode 100644 skills/proteus/scripts/cryoem_workflow.py
 create mode 100644 skills/proteus/scripts/electrostatics_workflow.py
 create mode 100644 skills/proteus/scripts/ensemble_report.py
 create mode 100644 skills/proteus/scripts/interface_story.py
 create mode 100644 skills/proteus/scripts/pocket_tunnel.py
 create mode 100644 skills/proteus/scripts/proteus.py
 create mode 100644 skills/proteus/scripts/proteus_common.py
 create mode 100644 skills/proteus/scripts/residue_story.py
 create mode 100644 skills/proteus/scripts/restraint_report.py
 create mode 100644 skills/proteus/scripts/scene_figure.py
 create mode 100644 skills/proteus/scripts/state_compare.py
 create mode 100644 skills/proteus/scripts/structure_qc.py
 create mode 100644 skills/proteus/scripts/visual_common.py
 create mode 100644 tests/test_workflows.py

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index fd4029c..2c83c82 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -31,9 +31,13 @@ jobs:
       - name: Run tests
         run: python -m unittest -v
 
+      - name: Verify installable skill package parity
+        run: python scripts/sync_skill_package.py --check --json
+
       - name: JSON smoke checks
         run: |
           python scripts/proteus_doctor.py --json | python -m json.tool >/dev/null
           python scripts/resolve_structure.py tests/fixtures/tiny.pdb --json | python -m json.tool >/dev/null
           python scripts/pae_report.py tests/fixtures/tiny_pae.json --json | python -m json.tool >/dev/null
           python scripts/pocket_report.py tests/fixtures/tiny.pdb --json | python -m json.tool >/dev/null
+          python scripts/proteus.py qc tests/fixtures/tiny.pdb --json | python -m json.tool >/dev/null
diff --git a/CHANGELOG.md b/CHANGELOG.md
index acf99d6..83483b9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+- Added a unified `proteus.py` interface for coordinate QC, declarative
+  PyMOL/ChimeraX figures, state and interface comparisons, residue stories,
+  annotation overlays, distance restraints, assemblies, cryo-EM review,
+  ensembles, electrostatics, pocket detection, and chemical-site triage.
+- Added replayable script/session artifacts, privacy-safe provenance and
+  execution summaries, package-parity checks, and representative real-tool
+  validation for PyMOL and ChimeraX workflows.
+- Added chain-aware PAE summaries, per-residue AlphaFold confidence reporting,
+  and optional local DockQ and Foldseek adapters.
 - Added a `density` subcommand to `pymol_agent.py`: render a model in cryo-EM
   density (real `--map` or `--simulate`d gaussian density), with the mesh carved
   around the model or a `--residue` selection and the contour level taken from
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4cb3db0..1f49342 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -15,6 +15,7 @@ small tests that keep agents from repeating common mistakes.
 
 ```bash
 make test
+make package-check
 python3 scripts/proteus_doctor.py --json
 ```
 
diff --git a/Makefile b/Makefile
index 66395dd..012fe03 100644
--- a/Makefile
+++ b/Makefile
@@ -1,8 +1,13 @@
-.PHONY: test release-check
+.PHONY: test package-check verify release-check
 
 test:
 	python3 -m unittest -v
 
+package-check:
+	python3 scripts/sync_skill_package.py --check --json
+
+verify: test package-check release-check
+
 # Pre-publish hygiene sweep: no tracked structures/maps/media/secrets, no large
 # files, no obvious secret strings. Run before pushing public changes.
 release-check:
diff --git a/README.md b/README.md
index 6c43b64..09b1e3f 100644
--- a/README.md
+++ b/README.md
@@ -38,6 +38,9 @@ Rosetta-oriented protein design guidance without building a custom plugin.
   cryo-EM workflows.
 - **Produces outputs agents can chain.** Reports use machine-readable JSON for
   parallel runs, CI checks, notebooks, and downstream analysis.
+- **Keeps local research local by default.** Coordinate files, maps, annotations,
+  and restraints are processed on the machine unless a public identifier is
+  explicitly resolved through a public data source.
 
 ## What It Provides
 
@@ -79,6 +82,14 @@ Rosetta-oriented protein design guidance without building a custom plugin.
 - Rosetta/PyRosetta patterns plus ML alternatives (ProteinMPNN, ESM2)
 - Zero-dependency PDB file inspector (`pdb_info.py` — stdlib only)
 - Structured JSON output from analysis helper scripts, safe for parallel runs
+- A unified `proteus.py` workflow interface with coordinate preflight, declarative
+  PyMOL/ChimeraX figures, state comparisons, residue and interface stories,
+  annotation overlays, restraint checks, assembly exploration, cryo-EM review,
+  ensemble analysis, electrostatics, pocket detection, and chemical-site triage
+- Replayable `.pml`/`.cxc` scripts and saved `.pse`/`.cxs` sessions for audit and
+  human handoff
+- Optional local DockQ, Foldseek, fpocket, P2Rank, PDB2PQR, and APBS capability
+  detection without automatic installation or structure uploads
 
 ## Agent Prompts That Work
 
@@ -91,6 +102,8 @@ Render the 1HSG binding pocket around indinavir in PyMOL and save a clean PNG.
 Compare AF-P04637-F1 against an experimental p53 structure and report RMSD plus high-deviation residues.
 Run a ChimeraX hydrogen-bond and SASA analysis for this protein-protein interface.
 Check whether 4HHB has validation red flags before using it as a reference structure.
+Build an apo/holo comparison with aligned PyMOL views and report contacts gained or lost.
+Inspect this cryo-EM model/map pair at several contour levels and save a ChimeraX session.
 ```
 
 ## Capabilities Matrix
@@ -104,6 +117,9 @@ Check whether 4HHB has validation red flags before using it as a reference struc
 | Headless structure rendering | no | yes | limited | no | no |
 | SASA, H-bonds, contacts, alignment | partial | partial | yes | no | optional |
 | Protein design/scoring guidance | docs | optional | optional | optional | yes |
+| Reproducible figure/scene manifests | scripts | yes | yes | no | no |
+| Cryo-EM map/model review | map stats | limited | yes | EMDB optional | no |
+| Ensemble, restraint, and annotation reports | yes | optional | optional | no | no |
 
 ## Generated Outputs
 
@@ -127,6 +143,7 @@ make test
 python3 scripts/proteus_doctor.py --json
 python3 scripts/resolve_structure.py TP53 --no-download --json
 python3 scripts/pocket_report.py tests/fixtures/tiny.pdb --json
+python3 scripts/proteus.py qc tests/fixtures/tiny.pdb --json
 ```
 
 These commands require only Python 3.10+. Install PyMOL or ChimeraX later when
@@ -174,6 +191,20 @@ Analyze the hydrogen bonds at a protein-protein interface in ChimeraX.
 The helper scripts also work standalone:
 
 ```bash
+python3 scripts/proteus.py --help                                  # unified workflow entry point
+python3 scripts/proteus.py qc structure.cif --json                 # coordinate preflight/QC
+python3 scripts/proteus.py figure scene.json --execute             # manifest -> figure + session
+python3 scripts/proteus.py compare apo.pdb holo.pdb --ligand ATP   # aligned state comparison
+python3 scripts/proteus.py residue model.cif A:42 --execute        # residue-centered story
+python3 scripts/proteus.py interface complex.cif --chains A,B      # interface analysis + figures
+python3 scripts/proteus.py annotate model.pdb scores.csv            # residue score overlay
+python3 scripts/proteus.py restraints model.pdb restraints.csv      # distance-restraint report
+python3 scripts/proteus.py assembly 4HHB --assembly 1               # ASU/assembly/crystal views
+python3 scripts/proteus.py cryoem model.cif map.mrc --resolution 3.2 # contour sweep/map review
+python3 scripts/proteus.py ensemble models.pdb                      # multi-model RMSF summary
+python3 scripts/proteus.py electrostatics model.pdb                 # qualitative Coulombic surface
+python3 scripts/proteus.py pockets model.pdb --detector auto        # local fpocket/P2Rank workflow
+python3 scripts/proteus.py chemical-site complex.cif --component ZN:A:501
 python3 scripts/pdb_info.py structure.pdb                          # zero-dep PDB inspection
 python3 scripts/structure_info.py structure.cif --json             # PDB/mmCIF inspection
 python3 scripts/fetch_pdb.py 4HHB --json                           # RCSB PDB fetch
@@ -202,6 +233,8 @@ python3 scripts/validation_report.py 4HHB --json                   # wwPDB valid
 python3 scripts/pocket_report.py tests/fixtures/tiny.cif --json     # ligand-pocket contacts
 python3 scripts/interface_report.py 1BRS --chains A,D --json        # protein-protein interface residues
 python3 scripts/model_quality.py detect --json                     # optional quality tool detection
+python3 scripts/model_quality.py dockq model.pdb native.pdb --json # DockQ when installed
+python3 scripts/model_quality.py foldseek query.pdb targets --json # local Foldseek search
 python3 scripts/resolve_structure.py TP53 --json                   # one-command resolver
 python3 scripts/pymol_agent.py render structure.pdb output.png     # headless render
 python3 scripts/pymol_agent.py pocket 1HSG.pdb pocket.png --label  # annotated binding-pocket figure
@@ -231,6 +264,7 @@ proteus/
 │   ├── file-formats.md
 │   ├── prediction-models.md
 │   ├── pymol.md
+│   ├── workflows.md
 │   └── rosetta.md
 └── scripts/              # Agent helper scripts (all stdlib-only)
     ├── add_helix_records.py
@@ -250,6 +284,9 @@ proteus/
     ├── ligand_extract.py
     ├── map_info.py
     ├── model_quality.py
+    ├── proteus.py
+    ├── structure_qc.py
+    ├── scene_figure.py
     ├── mutation_triage.py
     ├── pae_report.py
     ├── pdb_info.py
diff --git a/SKILL.md b/SKILL.md
index 60bb956..2cb37f9 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -2,553 +2,213 @@
 name: proteus
 description: >
   Use this skill when the user asks you to work with protein structures,
-  molecular visualization, or structural biology tools. TRIGGER when:
-  the user mentions PyMOL, ChimeraX, AlphaFold, Rosetta, PyRosetta,
-  UniProt, RCSB PDB, PDBe, PDB files, protein structures, molecular
-  rendering, pLDDT, RMSD, structure alignment, binding pockets,
-  drug-target analysis, cryo-EM density maps, homology modeling, or
-  protein design. Also trigger when the user opens/loads .pdb, .cif,
-  .mmcif, .sdf, or .mol2 files, or .mrc density maps (see
-  references/chimerax.md for cryo-EM workflows).
-  DO NOT TRIGGER for: general biology questions with no structural component,
-  bioinformatics sequence-only tasks (BLAST, MSA), or genomics/transcriptomics.
+  molecular visualization, or structural biology tools. Trigger for PyMOL,
+  ChimeraX, AlphaFold, Rosetta/PyRosetta, UniProt, RCSB PDB, PDBe, PDB/mmCIF
+  files, molecular rendering, pLDDT, PAE, RMSD, structure alignment, binding
+  pockets, interfaces, variants, docking context, cryo-EM maps, ensembles,
+  restraints, or protein design. Also trigger when the user opens .pdb, .cif,
+  .mmcif, .sdf, .mol2, .mrc, .map, or .ccp4 files. Do not trigger for general
+  biology with no structural component, sequence-only bioinformatics, genomics,
+  or transcriptomics.
 ---
 
 # Proteus — Structural Biology Agent Skill
 
-You are an AI agent driving structural biology tools programmatically.
-This skill teaches you how to control PyMOL, ChimeraX, AlphaFold DB,
-and Rosetta/PyRosetta from the command line — including the non-obvious
-gotchas that will otherwise cost hours of debugging.
-
-## Tool Detection
-
-Before doing anything, detect what's installed:
-
-```python
-import shutil, subprocess
-
-PYMOL = shutil.which("pymol")
-if not PYMOL:
-    # macOS common locations
-    import os
-    for p in ["/Applications/PyMOL.app/Contents/bin/pymol",
-              os.path.expanduser("~/Applications/PyMOL.app/Contents/bin/pymol")]:
-        if os.path.isfile(p):
-            PYMOL = p
-            break
-
-CHIMERAX = shutil.which("ChimeraX") or shutil.which("chimerax")
-if not CHIMERAX:
-    import glob
-    hits = glob.glob("/Applications/ChimeraX*.app/Contents/bin/ChimeraX")
-    if hits:
-        CHIMERAX = sorted(hits)[-1]  # latest version
-```
-
-If neither is found, do not guess paths. Continue with zero-dependency workflows
-(`scripts/pdb_info.py`, AlphaFold metadata fetches, file inspection) when they
-fit the task; otherwise tell the user what to install and stop.
-
-Run helper scripts from the repo or skill root with Python 3.10+:
+Use Proteus to turn structural-biology questions into inspectable analyses,
+figures, sessions, and replayable PyMOL (`.pml`) or ChimeraX (`.cxc`) commands.
+Prefer the included helper workflows over improvised command strings.
+
+## Safety and Scientific Ground Rules
+
+- Treat local structures, maps, annotations, sequences, and restraints as private
+  unless the user identifies them as public. Do not upload private or unpublished
+  inputs to a web service without explicit authorization.
+- Public identifiers such as PDB, EMDB, UniProt, and AlphaFold DB accessions may
+  be resolved through their public APIs when network access is needed. Say which
+  source was used and preserve provenance.
+- Keep secrets, credentials, arbitrary absolute paths, raw private data, and
+  machine-specific details out of reports, logs, manifests, and repository files.
+- Never use a protein-structure result as the sole basis for a clinical, safety,
+  efficacy, or patient-specific decision. Flag medical or biosafety implications
+  and recommend appropriate expert review.
+- Separate observation from inference. A short distance is a geometric contact,
+  not proof of a hydrogen bond, energetic hotspot, catalytic role, binding
+  affinity, biological assembly, or causal variant effect.
+- State uncertainty from resolution, missing atoms/residues, alternate
+  conformers, occupancy, protonation, tautomerism, model confidence, chain
+  mapping, alignment coverage, map processing, and assembly choice when relevant.
+- Do not overwrite source coordinates. Write generated artifacts to a dedicated
+  output directory and keep scripts/sessions so the result can be audited.
+
+## Start Here
+
+Run scripts from the skill or repository root with Python 3.10+.
 
 ```bash
-cd <proteus-skill-or-repo-root>
-python3 scripts/proteus_doctor.py --network --json
+python3 scripts/proteus.py --help
+python3 scripts/proteus.py qc structure.cif --json
 ```
 
-On macOS, `/usr/bin/python3` may be 3.9 and too old for several helpers. Use a
-Homebrew, conda, pyenv, or system Python 3.10+ interpreter when the doctor marks
-Python as too old. Hardened launchers that set `PYTHONSAFEPATH=1` are supported:
-the helper entrypoints add their bundled `scripts/` directory before importing
-sibling modules.
+Do not run network checks merely because the skill was invoked. Use
+`scripts/proteus_doctor.py --json` for local readiness, and add `--network` only
+when the task actually needs public APIs.
 
-If PyMOL or ChimeraX are installed as macOS apps, the doctor can often find their
-app-bundle binaries even when they are not on `PATH`. For direct shell use, add
-the actual app `Contents/bin` directory to `PATH`. Install `ffmpeg` for spin
-movies. Confirm PyMOL is licensed before publishing renders because evaluation
-builds can watermark output.
+Before using a helper, run its `--help`. Treat helpers as black boxes unless
+debugging or changing the implementation.
 
-## Tool Selection — When to Use What
-
-| Task | Best Tool | Why |
-|---|---|---|
-| Headless rendering (no display) | **PyMOL** | Software ray tracer works fully headless |
-| Interactive demo with live GUI | **ChimeraX REST API** | HTTP control of running GUI session |
-| H-bonds, SASA, clashes, contacts | **ChimeraX** | Built-in analysis commands, even in `--nogui` |
-| Structure alignment + RMSD | **Either** | PyMOL `cealign` or ChimeraX `matchmaker` |
-| AlphaFold confidence analysis | **PyMOL** + AlphaFold API | Fetch prediction, color by pLDDT, render headless |
-| Experimental PDB download | **`fetch_pdb.py`** | RCSB metadata + coordinates |
-| Structure landscape search | **`pdb_search.py`** | Enumerate PDB hits by text and/or UniProt accession |
-| Structure candidate ranking | **`pdb_select.py`** | Rank hits by method, resolution, validation, assemblies, and ligands |
-| Protein name -> accession | **`uniprot_lookup.py`** | Resolve names/genes before AlphaFold fetch |
-| PDB/mmCIF preflight | **`structure_info.py`** | Zero-dependency file inspection |
-| Target dossier/report | **`target_dossier.py`** | Markdown + JSON provenance for targets, with opt-in local analyses |
-| Structural mutation triage | **`mutation_triage.py`** | Local variant proximity to ligands, interfaces, contacts, and PAE context |
-| Docking box prep | **`docking_box.py`** | Ligand-centered Vina box plus optional docking-tool detection |
-| Cryo-EM density map visualization | **ChimeraX REST API** | Volume rendering requires GPU/display |
-| Quick legacy PDB inspection | **`pdb_info.py` script** | Backward-compatible PDB-only inspector |
-| KRAS G12C dossier | **`kras_dossier.py`** | End-to-end workflow with public structures, analyses, and figures |
-| Protein design / scoring | **Rosetta/PyRosetta** | Or ML alternatives (ProteinMPNN, RFdiffusion) |
-
-**Key architectural insight:** ChimeraX `--nogui` mode has NO OpenGL context on macOS.
-It can run analysis commands (H-bonds, SASA, matchmaker, info) but CANNOT render images.
-For ChimeraX rendering, you must use the REST API approach with a running GUI instance.
+## Workflow Routing
 
-## Reading Guide
-
-Load reference files on demand — don't read all of them upfront:
-
-| Working with... | Read this file |
+| User goal | Preferred workflow |
 |---|---|
-| PyMOL (any task) | `references/pymol.md` |
-| ChimeraX (any task) | `references/chimerax.md` |
-| AlphaFold DB predictions | `references/alphafold.md` |
-| PDB/UniProt/PDBe/RCSB data lookup | `references/data-sources.md` |
-| File format choices (.pdb, .cif, .sdf, .mrc) | `references/file-formats.md` |
-| Prediction models beyond AlphaFold DB | `references/prediction-models.md` |
-| Rosetta / protein design | `references/rosetta.md` |
-
-## Agent Helper Scripts
-
-These scripts handle the hard parts of tool communication.
-
-**IMPORTANT: Always run `python3 scripts/<script>.py --help` first.** Treat the
-scripts as black-box utilities by default. Only read the source when you are
-debugging, patching, or the help text is insufficient for the task.
-
-| Script | Purpose | Example |
+| Preflight models, conformers, occupancy, components | `proteus.py qc` |
+| Reproducible publication figure or saved scene | `proteus.py figure` |
+| Apo/holo, WT/mutant, or pose comparison | `proteus.py compare` |
+| Residue/variant local environment | `proteus.py residue` |
+| Protein-protein interface story | `proteus.py interface` |
+| Per-residue annotations or score overlays | `proteus.py annotate` |
+| Distance restraints/crosslinks | `proteus.py restraints` |
+| Assembly and crystal-neighbor comparison | `proteus.py assembly` |
+| Cryo-EM contour sweep, fit, map/model review | `proteus.py cryoem` |
+| Multi-model ensemble variability | `proteus.py ensemble` |
+| Qualitative electrostatic surface | `proteus.py electrostatics` |
+| Optional fpocket/P2Rank detection | `proteus.py pockets` |
+| Ligand, cofactor, metal, or water site | `proteus.py chemical-site` |
+| Fetch/resolve public coordinates | `resolve_structure.py`, `fetch_pdb.py`, `fetch_alphafold.py` |
+| PAE or model-quality metrics | `pae_report.py`, `model_quality.py` |
+| Docking preparation and interaction triage | `dock_prep.py`, `docking_box.py`, `dock_vina.py`, `interaction_report.py` |
+| Design planning or Rosetta score parsing | `design_run.py`, `rosetta_score.py` |
+
+Read `references/workflows.md` for inputs, examples, output contracts, scene
+manifests, and human-handoff patterns.
+
+## Choosing PyMOL or ChimeraX
+
+| Task | Default | Reason |
 |---|---|---|
-| `scripts/proteus_doctor.py` | Local readiness report for tools, scripts, and APIs | `python3 scripts/proteus_doctor.py --network --json` |
-| `scripts/resolve_structure.py` | Resolve file/PDB/UniProt/name to structure + provenance | `python3 scripts/resolve_structure.py TP53 --json` |
-| `scripts/fetch_pdb.py` | RCSB PDB metadata + coordinate fetcher | `python3 scripts/fetch_pdb.py 4HHB --json` |
-| `scripts/assembly_report.py` | RCSB biological assembly counts, filenames, URLs, and optional assembly mmCIF download | `python3 scripts/assembly_report.py 4HHB --json` |
-| `scripts/pdb_search.py` | Search RCSB PDB by free text and/or UniProt accession | `python3 scripts/pdb_search.py "KRAS G12C" --rows 10 --details --json` |
-| `scripts/pdb_select.py` | Rank/select candidate structures from offline metadata or opt-in RCSB lookup | `python3 scripts/pdb_select.py --input candidates.json --json` |
-| `scripts/sifts_map.py` | PDBe SIFTS residue mapping between PDB chains and UniProt ranges | `python3 scripts/sifts_map.py pdb 1hsg --json` |
-| `scripts/ligand_extract.py` | Zero-dep non-water ligand inventory from PDB/mmCIF and optional CCD downloads | `python3 scripts/ligand_extract.py 1HSG --json` |
-| `scripts/dock_prep.py` | Non-executing receptor/ligand prep plan with optional tool detection | `python3 scripts/dock_prep.py --receptor receptor.pdb --ligand ligand.sdf --json` |
-| `scripts/docking_box.py` | Ligand-centered PDB/mmCIF Vina-style box and optional docking-tool detection | `python3 scripts/docking_box.py complex.cif --ligand ATP --json` |
-| `scripts/dock_vina.py` | Dry-run Vina-compatible docking command planner and log parser | `python3 scripts/dock_vina.py plan --receptor receptor.pdbqt --ligand ligand.pdbqt --config box.txt --json` |
-| `scripts/interaction_report.py` | Simple PDB/mmCIF protein-ligand interaction/contact classes plus PLIP/ProLIF detection | `python3 scripts/interaction_report.py complex.cif --ligand ATP --json` |
-| `scripts/variant_map.py` | Conservative protein substitution parser plus optional local coordinate lookup | `python3 scripts/variant_map.py "P04637 R175H" --no-download --json` |
-| `scripts/mutation_triage.py` | Local structural triage of substitutions against ligands, chains, contacts, and PAE | `python3 scripts/mutation_triage.py R175H --structure model.pdb --json` |
-| `scripts/proteus_batch.py` | Run allowlisted helper scripts from a JSON manifest | `python3 scripts/proteus_batch.py manifest.json --dry-run --json` |
-| `scripts/proteus_cache.py` | Local URL cache with checksums, offline mode, verify, and garbage collection | `python3 scripts/proteus_cache.py show --json` |
-| `scripts/proteus_report.py` | Combine helper JSON into Markdown and scrubbed report JSON evidence packs | `python3 scripts/proteus_report.py --input result.json --json` |
-| `scripts/target_dossier.py` | Generic target dossier with Markdown, JSON provenance, and opt-in local analyses | `python3 scripts/target_dossier.py --uniprot P04637 --no-network --json` |
-| `scripts/uniprot_lookup.py` | Protein/gene name to UniProt accession | `python3 scripts/uniprot_lookup.py TP53 --gene-exact --json` |
-| `scripts/structure_info.py` | Zero-dep PDB/mmCIF inspector | `python3 scripts/structure_info.py structure.cif --json` |
-| `scripts/fetch_alphafold.py` | AlphaFold DB fetcher | `python3 scripts/fetch_alphafold.py P04637 --pae --json` |
-| `scripts/pae_report.py` | Summarize AlphaFold PAE domain/flexibility hints | `python3 scripts/pae_report.py AF-P04637-F1_pae.json --json` |
-| `scripts/validation_report.py` | Fetch wwPDB/RCSB validation quality metrics | `python3 scripts/validation_report.py 4HHB --json` |
-| `scripts/pocket_report.py` | Zero-dep ligand pocket contacts from local PDB/mmCIF or PDB ID | `python3 scripts/pocket_report.py complex.cif --json` |
-| `scripts/interface_report.py` | Zero-dep protein-protein interface residues from local PDB/mmCIF or PDB ID | `python3 scripts/interface_report.py 1BRS --chains A,D --json` |
-| `scripts/compare_structures.py` | PyMOL CE alignment + optional per-residue deviations | `python3 scripts/compare_structures.py ref.pdb mobile.pdb --json` |
-| `scripts/pymol_agent.py` | Headless PyMOL driver (info, render, **pocket figure, density fit, spin movie**) | `python3 scripts/pymol_agent.py render structure.pdb out.png --color plddt` |
-| `scripts/chimerax_agent.py` | Headless ChimeraX driver (analysis, `--nogui`) | `python3 scripts/chimerax_agent.py run "open 1ubq; info chains #1"` |
-| `scripts/chimerax_rest.py` | Managed ChimeraX REST GUI render (GPU) + turntable | `python3 scripts/chimerax_rest.py render structure.pdb out.png --color plddt` |
-| `scripts/add_helix_records.py` | Add HELIX records to CA-only backbones so cartoons render | `python3 scripts/add_helix_records.py model.pdb --json` |
-| `scripts/map_info.py` | MRC/CCP4 map stats + sigma-based contour levels | `python3 scripts/map_info.py map.mrc --json` |
-| `scripts/model_quality.py` | Detect optional quality tools and parse/run USalign when installed | `python3 scripts/model_quality.py detect --json` |
-| `scripts/design_run.py` | Validate design manifests and write dry-run modeling/design plans | `python3 scripts/design_run.py manifest.json --dry-run --json` |
-| `scripts/rosetta_score.py` | Detect Rosetta/PyRosetta, parse scorefiles, and plan dry scoring commands | `python3 scripts/rosetta_score.py detect --json` |
-| `scripts/pdb_info.py` | Legacy zero-dep PDB inspector (PDB only) | `python3 scripts/pdb_info.py structure.pdb` |
-| `scripts/kras_dossier.py` | KRAS G12C dossier workflow over public structures | `python3 scripts/kras_dossier.py --out kras_g12c_dossier --no-movie` |
-
-## Critical Gotchas (Read This First)
-
-These are hard-won discoveries. Each one represents hours of debugging that you
-can skip by knowing them upfront.
-
-### PyMOL
-
-1. **Never use the `-d` flag for complex commands.** The shell interprets `>`, `<`,
-   and `|` in PyMOL selection syntax as redirection/pipe operators. Instead, write
-   a `.pml` script file and run `pymol -c -q script.pml`.
-
-   ```python
-   # WRONG — breaks on selections like "b > 90"
-   subprocess.run(["pymol", "-c", "-q", "-d", 'color blue, b > 90'])
-
-   # RIGHT — write a .pml file
-   with open("/tmp/cmd.pml", "w") as f:
-       f.write("color blue, b > 90\n")
-   subprocess.run(["pymol", "-c", "-q", "/tmp/cmd.pml"])
-   ```
-
-   **Why:** The `-d` flag passes the string through the shell, where `>` becomes
-   stdout redirection. This is never mentioned in PyMOL documentation.
-
-2. **PyMOL stdout is unreliable.** `print()` in headless mode doesn't always
-   capture to stdout. Always write results to a JSON temp file and read it back
-   from the calling process.
-
-3. **`cmd.quit()` is required** at the end of every headless script. Without it,
-   the PyMOL process hangs indefinitely.
-
-4. **`<=` doesn't exist in PyMOL selection syntax.** For pLDDT coloring, use
-   layered overrides — paint the broadest range first, then override with
-   narrower selections. `scripts/pymol_agent.py --color plddt` detects 0-1
-   and 0-100 B-factor/pLDDT scales before applying these bins:
-   ```
-   color orange, all           # base: everything is low confidence
-   color yellow, b > 50        # override: medium
-   color cyan, b > 70          # override: high
-   color blue, b > 90          # override: very high
-   ```
-   Use `--color bfactor` for an autoscaled spectrum when the B-factor column is
-   not a confidence score or the scale is unknown.
-
-5. **`cealign` argument order is (target, mobile).** The first argument is
-   the reference that stays fixed; the second gets moved. This is opposite
-   to what you might expect.
-
-6. **`cmd.iterate` vs `cmd.iterate_state`:** Use `iterate` for molecular
-   properties (chain, resname, B-factor). Use `iterate_state` for 3D
-   coordinates (x, y, z). Using the wrong one silently returns nothing.
-
-7. **GUI demos require threading.** Running a long script in PyMOL's main
-   thread freezes the GUI completely. Wrap your demo in
-   `threading.Thread(target=run, daemon=True).start()`.
-
-8. **In GUI mode, `print()` goes to PyMOL's internal console**, not the
-   terminal. Use `sys.stderr.write(text + "\n")` for terminal output.
-
-9. **`Path(__file__)` is unreliable** inside PyMOL's `-r` runner. Use
-   hardcoded absolute paths or resolve paths before launching PyMOL.
-
-### ChimeraX
-
-10. **ChimeraX `--nogui` CANNOT render images on macOS.** There is no
-    OpenGL context. Use it only for analysis. For rendering, use the
-    REST API with a GUI session (see `references/chimerax.md`).
-
-11. **ChimeraX is NOT thread-safe.** Sending REST API calls from a Python
-    background thread causes `EXC_BAD_ACCESS` crashes. All REST calls must
-    happen from the main thread.
-
-12. **`close session` does NOT reset model IDs.** After closing and reopening
-    structures, model IDs continue incrementing (#1, #2, #3...). The only
-    way to reset to #1 is a full process restart. Always use dynamic model
-    ID discovery after each `open` command.
-
-13. **Cryo-EM gotchas:** Use `lighting simple` (not `full`) for volume
-    maps — `full` washes out colors on white. Never `close` a map
-    mid-session — it shifts all model IDs. Use `hide`/`show` instead.
-    See `references/chimerax.md` for full cryo-EM patterns.
-
-14. **stdout lines have `INFO:`/`WARNING:`/`ERROR:` prefixes.** Parse them
-    out. Also filter lines starting with `INFO: Executing:` — those are
-    echoed commands, not results.
-
-### AlphaFold DB
-
-15. **The API returns a list, not a dict.** `json.loads(response)` gives
-    `[{...}]`. You must do `data[0]["pdbUrl"]`, not `data["pdbUrl"]`.
-
-16. **Always query `latestVersion` from the API.** Don't hardcode `v4` or
-    `v6` in URLs — the version changes and old URLs return 404.
-
-17. **P62988 (ubiquitin) is NOT in the database.** Use P0CG48
-    (polyubiquitin-C, 685 residues) instead. Note: this is the full
-    polyubiquitin chain, not the 76-residue monomer.
-
-### Rendering, Animation & Maps
-
-18. **PyMOL spin loops need `set cache_frames, 0`.** Otherwise PyMOL caches
-    every ray-traced frame in RAM and the process is OOM-killed partway through
-    a turntable. Set it before the render loop. (`pymol_agent.py spin` does this
-    for you.)
-
-19. **`set auto_zoom, 0` before loading when composing a manual view.** Each
-    `load`/`show` otherwise re-zooms and fights your `orient`/`zoom`/`turn`
-    framing. Set it first, frame last.
-
-20. **Whole-map isosurfaces stall in headless PyMOL.** The headless build lacks
-    the VTKm accelerator, so contouring a full density map can hang for minutes
-    even on a small map. Carve the mesh around the model
-    (`isomesh m, map, level, sele, carve=2.5`) or do the whole-map surface in
-    ChimeraX. Use `scripts/map_info.py` to pick a sigma-based contour level.
-
-21. **ChimeraX REST `save` can return before the PNG is flushed** — a 0-byte
-    file, worse under heavy cartoon recompute. After `save`, issue `wait 1` and
-    poll the file for non-zero size, retrying a few times.
-    (`scripts/chimerax_rest.py` handles this.)
-
-22. **ChimeraX color-name traps.** `gold`/`yellow` atom spheres often render
-    visibly green — use `orange` for a true gold read. And `color #1 cartoons #...`
-    silently mis-parses `cartoons` as a color: the command is `cartoon`, then
-    `color #1 <color>`.
-
-23. **Deposited coordinates are the asymmetric unit, not necessarily the
-    biological assembly.** A "dimer" entry may deposit a single chain. Build the
-    functional oligomer with ChimeraX `sym #1 assembly 1 copies true`, or expand
-    crystal neighbors in PyMOL with `symexp mate_, obj, sele, 5`.
-
-## Common Workflows
-
-### Quick Structure Inspection
-```bash
-python3 scripts/structure_info.py structure.cif --json  # zero-dep PDB/mmCIF overview
-python3 scripts/pdb_info.py structure.pdb               # legacy PDB-only overview
-python3 scripts/pymol_agent.py info structure.pdb       # detailed with PyMOL
-```
-
-### Experimental Structure Fetch
-```bash
-python3 scripts/fetch_pdb.py 4HHB --json                # RCSB metadata + mmCIF
-python3 scripts/fetch_pdb.py 1HSG --format pdb          # legacy PDB format if needed
-python3 scripts/assembly_report.py 4HHB --json          # assembly counts + download URLs
-python3 scripts/fetch_pdb.py 4HHB --assembly 1 --json   # biological assembly mmCIF
-```
-
-### Structure Landscape Search
-```bash
-python3 scripts/pdb_search.py "KRAS G12C sotorasib" --rows 10 --details --json
-python3 scripts/pdb_search.py --uniprot P01116 --rows 50 --details --json
-python3 scripts/pdb_select.py --input candidates.json --ligand GDP --json
-```
-
-### Residue Mapping, Variants, And Ligands
-```bash
-python3 scripts/sifts_map.py pdb 1hsg --json
-python3 scripts/variant_map.py "P04637 R175H" --no-download --json
-python3 scripts/mutation_triage.py R175H --uniprot P04637 --structure model.pdb --json
-python3 scripts/ligand_extract.py 1HSG --json
-python3 scripts/dock_prep.py --receptor receptor.pdb --ligand ligand.sdf --json
-python3 scripts/docking_box.py complex.pdb --ligand ATP --json
-python3 scripts/dock_vina.py plan --receptor receptor.pdbqt --ligand ligand.pdbqt --config box.txt --json
-python3 scripts/interaction_report.py complex.pdb --ligand ATP --json
-```
-
-### Dossiers And Batch Runs
-```bash
-python3 scripts/target_dossier.py --gene TP53 --uniprot P04637 --pdb 1TUP --json
-python3 scripts/target_dossier.py --pdb structure.pdb --no-network --json
-python3 scripts/target_dossier.py --pdb structure.pdb --no-network --analyze-local --json
-python3 scripts/proteus_batch.py manifest.json --dry-run --json
-python3 scripts/proteus_report.py --input result.json --outdir proteus_report_out --json
-python3 scripts/proteus_cache.py verify --json
-python3 scripts/design_run.py design_manifest.json --dry-run --json
-```
-
-### AlphaFold Confidence Analysis
-```bash
-python3 scripts/uniprot_lookup.py TP53 --gene-exact --json  # resolve accession if needed
-python3 scripts/fetch_alphafold.py P04637 --pae --json       # fetch p53 prediction
-# Output filename uses modelEntityId from API, typically AF-{UNIPROT}-F1.pdb
-python3 scripts/pae_report.py AF-P04637-F1_pae.json --json   # summarize domain uncertainty
-python3 scripts/pymol_agent.py render AF-P04637-F1.pdb output.png --color plddt
-```
-For non-AlphaFold models with normalized 0-1 confidence in the B-factor column,
-`--color plddt` detects the scale. Use `--color bfactor` for an autoscaled view
-when B-factors are not confidence values. See `references/alphafold.md` for the
-standard color scheme.
+| Headless ray-traced rendering | PyMOL | Software ray tracer works without a display |
+| GPU volume/surface rendering | ChimeraX managed REST | Strong map and surface tooling |
+| H-bonds, contacts, clashes, SASA, buried area | ChimeraX | Built-in analysis commands |
+| Scriptable publication scenes | Either | Proteus emits replayable scripts and sessions |
+| Live interactive handoff | ChimeraX REST or saved session | User can continue in the GUI |
+| Structural alignment | Either | Choose by metric and downstream rendering needs |
+
+On macOS, ChimeraX `--nogui` can analyze but cannot render because it lacks an
+OpenGL context. Use `scripts/chimerax_agent.py` for headless analysis and
+`scripts/chimerax_rest.py` or a generated workflow with `--execute` for GUI/GPU
+rendering. PyMOL headless rendering works on macOS and Linux.
+
+## Standard Operating Pattern
+
+1. Resolve the input identity and numbering system. Do not assume UniProt,
+   author, label, and construct residue numbers are interchangeable.
+2. Run `proteus.py qc` before geometry-sensitive analysis. Choose a model and
+   alternate-conformer policy explicitly when multiple states are present.
+3. Confirm whether the task needs the asymmetric unit, a biological assembly,
+   crystal neighbors, or a predicted monomer/complex.
+4. Choose the narrowest workflow that answers the question. Keep network use
+   and optional external tools explicit.
+5. Generate scripts and a JSON report first. Execute rendering or optional tools
+   only when needed; retain `.pml`/`.cxc` and `.pse`/`.cxs` handoff artifacts.
+6. Verify expected outputs are non-empty. Report measurements, provenance,
+   selection/model decisions, limitations, and missing capabilities.
+
+## Core Helpers
+
+The unified entry point covers the main user workflows:
 
-### Predicted vs Experimental Comparison
-1. Fetch AlphaFold prediction for the protein's UniProt ID
-2. Load both structures in PyMOL
-3. Use `cealign` (not `align`) — it's purely structural, works for divergent sequences
-4. Extract per-residue deviations with `iterate_state`
-5. Render side-by-side or overlay
-
-When external quality tools are installed, use `scripts/model_quality.py` to
-detect them or parse/run USalign:
-
-```bash
-python3 scripts/model_quality.py detect --json
-python3 scripts/model_quality.py usalign reference.pdb mobile.pdb --json
-python3 scripts/rosetta_score.py detect --json
-python3 scripts/rosetta_score.py parse-scorefile score.sc --json
-```
-
-### Protein-Protein Interface Analysis
-```bash
-# Zero-dependency: interface residues between chains, JSON for chaining
-python3 scripts/interface_report.py complex.cif --json            # all chain pairs
-python3 scripts/interface_report.py 1BRS --chains A,D --cutoff 4.5 --json
-python3 scripts/interface_report.py complex.cif --residue A:42 --json
-```
-For a visual interface dissection (contacts/H-bonds/buried surface), use
-ChimeraX — see `references/chimerax.md`.
-
-### Binding Pocket Analysis
-```bash
-# One-command annotated figure: ligand + pocket sticks + polar contacts + context
-python3 scripts/pymol_agent.py pocket 1HSG.pdb pocket.png --label
-# Docking-box handoff around known ligand atoms
-python3 scripts/dock_prep.py --receptor receptor.pdb --ligand ligand.sdf --json
-python3 scripts/docking_box.py 1HSG --ligand MK1 --padding 6 --json
-python3 scripts/dock_vina.py plan --receptor receptor.pdbqt --ligand ligand.pdbqt --config vina_box.txt --json
-python3 scripts/dock_vina.py parse-log vina.log --json
-# Contact classes for a ligand group
-python3 scripts/interaction_report.py 1HSG --ligand MK1 --json
-```
-```python
-# Or build it by hand. PyMOL: select residues within 5A of any ligand
-cmd.select("pocket", "byres organic around 5")
-# Show pocket as sticks, ligand as ball-and-stick
-cmd.show("sticks", "pocket")
-cmd.show("spheres", "organic")
-cmd.set("sphere_scale", 0.25, "organic")
-```
-
-### ChimeraX Interactive Demo (REST API)
-```bash
-# 1. Launch ChimeraX with REST
-/path/to/ChimeraX --cmd "remotecontrol rest start port 50888" &
-
-# 2. Verify connection
-curl -s "http://127.0.0.1:50888/run?command=version"
-
-# 3. Send commands
-curl "http://127.0.0.1:50888/run?command=open+1ubq"
-curl "http://127.0.0.1:50888/run?command=cartoon"
-curl "http://127.0.0.1:50888/run?command=save+/tmp/render.png+width+1200+height+900+supersample+3"
-```
-
-### Publication-Quality Rendering (PyMOL)
-```
-set bg_color, white
-set ray_opaque_background, 1
-set antialias, 2
-set cartoon_fancy_helices, 1
-set cartoon_smooth_loops, 1
-set cartoon_flat_sheets, 1
-ray 1200, 900
-png output.png
-```
-
-Render presets are also available on the helper: `pymol_agent.py render file.pdb
-out.png --preset publication|illustration|soft --color spectrum|chain|bfactor|plddt`.
-
-### Turntable Movie (Headless)
 ```bash
-# PyMOL ray-traces each frame (works with no display); ffmpeg encodes them.
-python3 scripts/pymol_agent.py spin structure.pdb spin.mp4 --frames 60 --color plddt
-# Degrades gracefully: with no ffmpeg, the frames are written and returned.
-```
-This is the macOS-correct path — ChimeraX needs a GPU/GUI context to render.
+python3 scripts/proteus.py figure scene.json --outdir figure --execute
+python3 scripts/proteus.py compare apo.pdb holo.pdb --outdir comparison
+python3 scripts/proteus.py residue model.cif A:42 --outdir residue_42
+python3 scripts/proteus.py interface complex.cif --chains A,B --execute
+python3 scripts/proteus.py annotate model.pdb scores.csv --execute
+python3 scripts/proteus.py restraints model.pdb restraints.csv --execute
+python3 scripts/proteus.py assembly 4HHB --assembly 1 --execute
+python3 scripts/proteus.py cryoem model.cif map.mrc --resolution 3.2 --fit --execute
+python3 scripts/proteus.py ensemble models.pdb --execute
+python3 scripts/proteus.py electrostatics model.pdb --execute
+python3 scripts/proteus.py pockets model.pdb --detector auto --execute --render
+python3 scripts/proteus.py chemical-site complex.cif --component ZN:A:501 --execute
+```
+
+Additional focused helpers include:
+
+- `resolve_structure.py`: local file, PDB ID, UniProt accession, or name to a
+  local structure with provenance.
+- `pdb_search.py` and `pdb_select.py`: search and rank experimental candidates.
+- `assembly_report.py`, `sifts_map.py`, and `validation_report.py`: assembly,
+  residue mapping, and experimental validation context.
+- `ligand_extract.py`, `pocket_report.py`, and `interaction_report.py`: ligand
+  inventory and zero-dependency contact triage.
+- `mutation_triage.py`: variant proximity to ligands, interfaces, contacts, and
+  PAE context.
+- `model_quality.py`: USalign, DockQ, and local Foldseek wrappers when installed.
+- `proteus_batch.py`, `proteus_cache.py`, and `proteus_report.py`: allowlisted
+  batches, cached public responses, and evidence packs.
+
+## Interpretation Rules by Data Type
+
+- **AlphaFold pLDDT:** confidence in local structure, not stability or function.
+  Use per-residue C-alpha values when available. Low pLDDT may indicate disorder,
+  context dependence, or prediction uncertainty.
+- **PAE:** directional expected alignment error. Use chain-aware blocks for
+  complexes and do not call high inter-chain PAE proof that chains do not bind.
+- **RMSD/TM-score:** always report alignment method, aligned length/coverage,
+  chain mapping, and normalization. A single global RMSD can hide local changes.
+- **DockQ:** review model/native chain mapping and each interface, not only the
+  aggregate score.
+- **Contacts/interfaces:** distance cutoffs generate candidates. Protonation,
+  donor/acceptor geometry, solvation, conformational state, and assembly choice
+  determine meaning.
+- **Cryo-EM:** contour levels are map-specific absolute values. Fitting and
+  difference maps depend on initial placement, resolution, sharpening, masking,
+  and scale; avoid overfitting.
+- **Electrostatics:** ChimeraX Coulombic coloring is qualitative. For stronger
+  claims, prepare protonation/charges and use a validated Poisson-Boltzmann
+  workflow such as PDB2PQR/APBS.
+- **Pockets/tunnels:** detector scores are hypotheses, not affinity estimates.
+  Compare conformational states and add experimental/evolutionary evidence.
+
+## Critical Execution Gotchas
+
+- Write complex PyMOL commands to `.pml`; do not pass selections containing
+  comparison operators through `pymol -d`.
+- End headless PyMOL scripts with `quit`; use `iterate_state` for coordinates.
+- PyMOL `cealign` argument order is target/reference first, mobile second.
+- Use layered `b > 50`, `b > 70`, `b > 90` overrides for pLDDT; PyMOL has no
+  `<=` selection operator.
+- ChimeraX model IDs do not reset after `close session`. Generated workflows use
+  a fresh managed session; otherwise discover model IDs dynamically.
+- For ChimeraX REST image saves, issue `wait 1` and verify the file is non-empty.
+- Avoid whole-map PyMOL isosurfaces; carve around the model or use ChimeraX.
+- Deposited coordinates are usually an asymmetric unit, not automatically the
+  biological assembly.
 
-### ChimeraX GPU Rendering (Managed REST)
-```bash
-# Launches a GUI ChimeraX on an ephemeral port, renders via GPU, tears down.
-python3 scripts/chimerax_rest.py render structure.pdb out.png --style surface --color bychain
-python3 scripts/chimerax_rest.py spin structure.pdb out.mp4 --frames 72
-```
-Unlike `chimerax_agent.py` (analysis only, `--nogui`), this renders images and
-defeats the 0-byte-PNG save race (gotcha 21).
-
-### CA-only Backbone (de-novo designs)
-```bash
-# RFdiffusion / Genie backbones render as spaghetti without HELIX records.
-python3 scripts/add_helix_records.py model.pdb -o model_ss.pdb --json
-# Then render model_ss.pdb; in PyMOL also: set cartoon_trace_atoms, 1
-```
-
-### Cryo-EM Density Fit
-```bash
-# Sigma-based contour level (absolute level differs per map).
-python3 scripts/map_info.py map.mrc --json   # -> suggested_level at 1/1.5/2/3 sigma
-
-# Render a model in density — the mesh is carved around the model, which avoids
-# the whole-map contour stall in headless PyMOL (gotcha 20).
-python3 scripts/pymol_agent.py density model.pdb fit.png --map map.mrc --residue "chain A and resi 25"
-
-# No map yet? Simulate gaussian density from the model (predicted/designed structures).
-python3 scripts/pymol_agent.py density model.pdb fit.png --simulate
-```
+## Reading Guide
 
-## Good Demo Proteins
+Load only the relevant reference:
 
-| UniProt / PDB | Protein | Good for |
-|---|---|---|
-| P04637 | p53 | Disorder (pLDDT ~75), mixed confidence regions |
-| P69905 | Hemoglobin alpha | Very high confidence (pLDDT ~98) |
-| P0CG48 | Polyubiquitin-C (685 res) | Well-folded repeats; use when ubiquitin is requested |
-| P01308 | Insulin | Small, well-characterized |
-| 1HSG | HIV-1 protease + indinavir | Drug-target binding pocket |
-| 1BRS | Barnase-barstar complex | Protein-protein interface |
-| 4HHB | Hemoglobin tetramer | Multi-chain, quaternary structure |
-| 1EMA | GFP | Chromophore, fluorescence |
-
-## Output Pattern
-
-When running analysis, always produce structured output. The agent scripts
-return JSON with `{"status": "ok", "data": {...}}` or `{"status": "error", "error": "..."}` in
-`--json` mode. Many scripts also mirror key fields at top level for backward
-compatibility, but agents should read `data` first. Their temporary files are
-per-invocation, so they are safe to call in parallel within the same workspace.
-
-For multi-step workflows, write a summary JSON report at the end with:
-- Input files and parameters
-- Key measurements (RMSD, distances, counts, areas)
-- Output file paths (renders, saved structures)
-- Interpretation notes
-
-## Platform Notes
-
-- **macOS**: PyMOL and ChimeraX are in `/Applications/`. PyMOL headless
-  rendering works. ChimeraX `--nogui` has no OpenGL.
-- **Linux**: Both tools typically on `$PATH`. PyMOL headless works.
-  ChimeraX `--nogui` may have OpenGL via virtual framebuffer (`xvfb-run`).
-- **Rosetta**: Requires an academic license. Free alternatives:
-  ProteinMPNN (sequence design), LocalColabFold (structure prediction),
-  ESM2 (embeddings), RFdiffusion (backbone generation).
-
-## Quick Reference
-
-| I want to... | Do this |
+| Topic | Reference |
 |---|---|
-| Check machine readiness | `python3 scripts/proteus_doctor.py --network --json` |
-| Resolve any common structure query | `python3 scripts/resolve_structure.py TP53 --json` |
-| Resolve protein/gene name to UniProt | `python3 scripts/uniprot_lookup.py TP53 --gene-exact --json` |
-| Fetch an experimental PDB structure | `python3 scripts/fetch_pdb.py 4HHB --json` |
-| Search experimental structures | `python3 scripts/pdb_search.py "KRAS G12C" --rows 10 --details --json` |
-| Rank candidate structures | `python3 scripts/pdb_select.py --input candidates.json --json` |
-| Check biological assemblies | `python3 scripts/assembly_report.py 4HHB --json` |
-| Map PDB residues to UniProt ranges | `python3 scripts/sifts_map.py pdb 1hsg --json` |
-| Inventory bound ligands | `python3 scripts/ligand_extract.py 1HSG --json` |
-| Plan receptor/ligand docking prep | `python3 scripts/dock_prep.py --receptor receptor.pdb --ligand ligand.sdf --json` |
-| Build a docking box around a ligand | `python3 scripts/docking_box.py complex.pdb --ligand ATP --json` |
-| Plan or parse Vina-compatible docking | `python3 scripts/dock_vina.py plan --receptor receptor.pdbqt --ligand ligand.pdbqt --config box.txt --json` |
-| Summarize protein-ligand interactions | `python3 scripts/interaction_report.py complex.pdb --ligand ATP --json` |
-| Parse/check a protein substitution | `python3 scripts/variant_map.py "P04637 R175H" --no-download --json` |
-| Triage mutation structure context | `python3 scripts/mutation_triage.py R175H --structure model.pdb --json` |
-| Run a local batch manifest | `python3 scripts/proteus_batch.py manifest.json --dry-run --json` |
-| Cache public URL responses locally | `python3 scripts/proteus_cache.py fetch URL --json` |
-| Combine JSON outputs into an evidence pack | `python3 scripts/proteus_report.py --input result.json --json` |
-| Generate a target dossier | `python3 scripts/target_dossier.py --uniprot P04637 --no-network --json` |
-| Generate a local analysis dossier | `python3 scripts/target_dossier.py --pdb structure.cif --no-network --analyze-local --json` |
-| Inspect PDB/mmCIF file (no tools needed) | `python3 scripts/structure_info.py file.cif --json` |
-| Inspect a legacy PDB file | `python3 scripts/pdb_info.py file.pdb` |
-| Summarize AlphaFold PAE | `python3 scripts/pae_report.py AF-P04637-F1_pae.json --json` |
-| Fetch validation metrics | `python3 scripts/validation_report.py 4HHB --json` |
-| Report ligand pocket contacts | `python3 scripts/pocket_report.py complex.cif --json` |
-| Report protein-protein interface residues | `python3 scripts/interface_report.py complex.cif --json` |
-| Compare two structures | `python3 scripts/compare_structures.py ref.pdb mobile.pdb --per-residue --json` |
-| Detect optional quality tools | `python3 scripts/model_quality.py detect --json` |
-| Plan a design run | `python3 scripts/design_run.py design_manifest.json --dry-run --json` |
-| Parse Rosetta scorefiles | `python3 scripts/rosetta_score.py parse-scorefile score.sc --json` |
-| Get structure info via PyMOL | `python3 scripts/pymol_agent.py info file.pdb` |
-| Render a structure headless | `python3 scripts/pymol_agent.py render file.pdb out.png` |
-| Render an annotated binding-pocket figure | `python3 scripts/pymol_agent.py pocket file.pdb out.png --label` |
-| Render a turntable movie | `python3 scripts/pymol_agent.py spin file.pdb out.mp4` |
-| Render via ChimeraX GPU (REST) | `python3 scripts/chimerax_rest.py render file.pdb out.png` |
-| Fix a CA-only backbone for cartoons | `python3 scripts/add_helix_records.py model.pdb` |
-| Pick a cryo-EM contour level | `python3 scripts/map_info.py map.mrc --json` |
-| Render a model in cryo-EM density | `python3 scripts/pymol_agent.py density model.pdb out.png --map map.mrc` |
-| Fetch an AlphaFold prediction | `python3 scripts/fetch_alphafold.py UNIPROT_ID --pae --json` |
-| Align two structures (ChimeraX) | `python3 scripts/chimerax_agent.py align ref.pdb mobile.pdb` |
-| Measure SASA | `python3 scripts/chimerax_agent.py sasa file.pdb` |
-| Find H-bonds between chains | `python3 scripts/chimerax_agent.py hbonds file.pdb --chain1 A --chain2 B` |
-| Run arbitrary PyMOL commands | `python3 scripts/pymol_agent.py run "fetch 1ubq; show cartoon"` |
-| Run arbitrary ChimeraX commands | `python3 scripts/chimerax_agent.py run "open 1ubq; info chains #1"` |
-| Control ChimeraX GUI via REST | Read `references/chimerax.md` — REST API section |
-| Color by AlphaFold confidence | Read `references/alphafold.md` — pLDDT Coloring section |
-| Choose between PDB, mmCIF, SDF, MRC | Read `references/file-formats.md` |
-| Use RCSB/PDBe/UniProt APIs | Read `references/data-sources.md` |
-| Consider AF3/Boltz/Chai/ColabFold | Read `references/prediction-models.md` |
-| Do protein design without Rosetta | Read `references/rosetta.md` — ML Alternatives section |
-| Run the KRAS G12C dossier workflow | `python3 scripts/kras_dossier.py --out kras_g12c_dossier --no-movie` |
+| User workflows, manifests, outputs, handoff | `references/workflows.md` |
+| PyMOL commands, rendering, animation | `references/pymol.md` |
+| ChimeraX analysis, REST rendering, cryo-EM | `references/chimerax.md` |
+| AlphaFold DB, pLDDT, PAE | `references/alphafold.md` |
+| PDB/UniProt/PDBe/RCSB APIs | `references/data-sources.md` |
+| PDB/mmCIF/SDF/MRC format choice | `references/file-formats.md` |
+| AF3/Boltz/Chai/ColabFold and other models | `references/prediction-models.md` |
+| Rosetta, PyRosetta, and ML design alternatives | `references/rosetta.md` |
+
+## Output Contract
+
+Helpers emit JSON with `status`, `data`, and when applicable `warnings` and
+`provenance`. New workflow envelopes also include `schema_version` and
+`proteus_version`. Read `data` first.
+
+Return to the user:
+
+- the answer and key measurements;
+- generated figure/session/script paths;
+- input source and model/chain/selection decisions;
+- relevant uncertainty and interpretation limits;
+- missing tools or incomplete outputs, without pretending success.
diff --git a/references/chimerax.md b/references/chimerax.md
index 0d52aed..568860e 100644
--- a/references/chimerax.md
+++ b/references/chimerax.md
@@ -259,7 +259,7 @@ style #1 stick                    # Stick representation
 surface #1                        # Molecular surface
 ~surface                          # Remove surface
 color #1 red                      # Color model red
-color bychain #1                  # Color by chain
+color #1 bychain                  # Color by chain
 color bfactor #1                  # Color by B-factor
 color bfactor #1 palette alphafold  # AlphaFold confidence colors
 transparency #1 50                # 50% transparent
@@ -345,7 +345,7 @@ alphafold contacts #1             # Predicted contacts overlay
 open 21924 from emdb              # Downloads .map file
 
 # Display
-volume #1 style surface level 0.025 color #90CAF9 transparency 0.3 step 1
+volume #1 style surface level 0.025 color #90CAF9 transparency 30 step 1
 
 # Fit atomic model into map
 fitmap #2 inMap #1 metric correlation
@@ -443,17 +443,17 @@ Overlay text labels on the ChimeraX viewport (REST API or command):
 
 ```
 # Create a label
-2dlabels create name title text "Step 1: Load Structure" xpos 0.05 ypos 0.95 color black size 24 bold true
+2dlabels create title text "Step 1: Load Structure" xpos 0.05 ypos 0.95 color black size 24 bold true
 
 # Update it
-2dlabels change name title text "Step 2: Analyze"
+2dlabels change title text "Step 2: Analyze"
 
 # Delete all labels
-2dlabels delete
+2dlabels delete all
 
 # Multiple labels
-2dlabels create name step text "Step 1" xpos 0.05 ypos 0.95 color white size 20 bold true
-2dlabels create name detail text "Loading hemoglobin" xpos 0.05 ypos 0.90 color gray size 14
+2dlabels create step text "Step 1" xpos 0.05 ypos 0.95 color white size 20 bold true
+2dlabels create detail text "Loading hemoglobin" xpos 0.05 ypos 0.90 color gray size 14
 ```
 
 Coordinates: `xpos`/`ypos` are 0.0-1.0 fractions of viewport.
diff --git a/references/workflows.md b/references/workflows.md
new file mode 100644
index 0000000..80e70b8
--- /dev/null
+++ b/references/workflows.md
@@ -0,0 +1,224 @@
+# Reproducible PyMOL and ChimeraX Workflows
+
+This guide describes Proteus workflows that produce a JSON report plus
+replayable PyMOL (`.pml`) or ChimeraX (`.cxc`) scripts. Most also write a saved
+session when executed. Run `python3 scripts/proteus.py <command> --help` for the
+complete current interface.
+
+## General output pattern
+
+Each workflow writes into an explicit output directory:
+
+- a JSON report with inputs, parameters, warnings, provenance, and artifacts;
+- a command file that can be inspected before execution;
+- PNG figures and `.pse`/`.cxs` sessions when rendering is requested;
+- tool results when an optional detector or quality program is run.
+
+Input coordinate and map files are never modified. Reports use portable path
+labels and file checksums rather than publishing arbitrary absolute paths.
+
+## Structure preflight
+
+```bash
+python3 scripts/proteus.py qc structure.cif --model first --altloc highest --json
+```
+
+Run this before distances, interfaces, comparisons, restraints, or chemical-site
+analysis. It reports available/selected models, alternate sites, occupancy,
+missing backbone atoms, residue-number gaps, and chemical-component roles.
+
+Use `--model all` only for an ensemble-aware workflow. Use an explicit model
+number when the deposited file contains different experimental or modeled
+states. `--altloc highest` chooses the highest-occupancy conformer per atom and
+records that policy.
+
+## Declarative figures and guided views
+
+```bash
+python3 scripts/proteus.py figure scene.json --outdir figure --execute
+```
+
+Example `scene.json`:
+
+```json
+{
+  "name": "active-site-story",
+  "tool": "pymol",
+  "width": 1400,
+  "height": 1000,
+  "background": "white",
+  "structures": [{"id": "complex", "path": "complex.cif"}],
+  "representations": [
+    {"style": "cartoon", "selection": "polymer", "color": "chain"},
+    {"style": "sticks", "selection": "organic or byres (polymer within 4.5 of organic)", "color": "element"}
+  ],
+  "labels": [{"selection": "organic and not hydro", "text": "bound ligand", "color": "black"}],
+  "views": [
+    {"id": "overview", "selection": "polymer", "output": "overview.png"},
+    {"id": "site", "selection": "organic", "turn": {"y": 25}, "output": "site.png"}
+  ]
+}
+```
+
+Choose `"tool": "chimerax"` for a ChimeraX script/session. Multiple ordered
+views act as deterministic scene checkpoints for a presentation or human
+handoff. Keep manifest selections tool-specific and use filenames—not paths—for
+view outputs.
+
+## State comparisons
+
+```bash
+python3 scripts/proteus.py compare apo.pdb holo.pdb \
+  --ligand ATP --outdir apo_holo --execute
+```
+
+This produces aligned overlay and side-by-side views. When a ligand is selected,
+the report compares nearby contact residues between states. Interpret gained or
+lost contacts only after checking chain mapping, ligand identity, alignment
+coverage, missing residues, and alternate conformers.
+
+## Residue and interface stories
+
+```bash
+python3 scripts/proteus.py residue model.cif A:42 --outdir residue_42 --execute
+python3 scripts/proteus.py interface complex.cif --chains A,B --cutoff 5 --outdir interface_ab --execute
+```
+
+The residue workflow combines a global locator, labeled local environment, and
+available ligand/interface/variant context. The interface workflow combines
+local contact residues with ChimeraX buried area, H-bond, contact, and clash
+commands plus PyMOL figures.
+
+Buried area and distance contacts depend on which assembly is loaded. Do not
+interpret crystal-packing contacts as a biological interface without supporting
+evidence.
+
+## Annotation overlays
+
+```bash
+python3 scripts/proteus.py annotate model.pdb annotations.csv --outdir annotated --execute
+```
+
+CSV rows can supply chain, residue, score, color, and label fields. JSON lists
+use the same keys. Use this for variants, domains, PTMs, conservation,
+confidence, validation, or a user-defined score. Keep the score definition and
+scale in the surrounding report; colors alone are not self-explanatory.
+
+## Experimental restraints
+
+```bash
+python3 scripts/proteus.py restraints model.pdb restraints.csv --outdir restraints --execute
+```
+
+Required CSV/JSON fields are `residue1` and `residue2`. Optional fields include
+`chain1`, `atom1`, `chain2`, `atom2`, `min`, `max`, `id`, and `label`. The report
+marks pairs as satisfied, too short, too long, or unresolved and colors the
+rendered distance objects.
+
+Distance bounds must match the experiment and labeling chemistry. A C-alpha
+distance is not automatically comparable to an atom-to-atom crosslink, FRET, or
+DEER distribution.
+
+## Assembly and symmetry
+
+```bash
+python3 scripts/proteus.py assembly 4HHB --assembly 1 --outdir assembly --execute
+```
+
+PDB identifiers enable assembly metadata lookup. The ChimeraX workflow compares
+the asymmetric unit and requested biological assembly; PyMOL expands nearby
+crystal mates. For a local coordinate file, assembly availability cannot be
+inferred reliably unless the necessary metadata/operators are present.
+
+## Cryo-EM map/model review
+
+```bash
+python3 scripts/proteus.py cryoem model.cif map.mrc \
+  --resolution 3.2 --fit --difference --outdir map_review --execute
+```
+
+Local MRC/CCP4 maps receive sigma-based contour suggestions. Remote EMDB maps
+require explicit absolute `--levels` because Proteus cannot compute local map
+statistics before download/open. The ChimeraX script saves a contour sweep,
+optional rigid fit, map statistics, and a qualitative difference view.
+
+Use several contour levels. Record resolution, map provenance, sharpening or
+filtering, masking, and fit procedure. Difference density is not reliable
+without appropriate scaling and independent validation.
+
+## Ensembles
+
+```bash
+python3 scripts/proteus.py ensemble models.pdb --outdir ensemble --execute
+```
+
+Multi-model PDB/mmCIF files are compared using common C-alpha atoms. With NumPy,
+Proteus performs a Kabsch superposition before RMSF; otherwise it reports the
+translation-only fallback. The result includes residue-level RMSF, most-variable
+residues, an all-state PyMOL view, and a ChimeraX coordinate-set session.
+
+RMSF here measures dispersion across supplied coordinate models, not uncertainty
+or dynamics unless the ensemble itself supports that interpretation.
+
+## Electrostatics
+
+```bash
+python3 scripts/proteus.py electrostatics model.pdb \
+  --selection protein --range 10 --offset 1.4 --outdir electrostatics --execute
+```
+
+This uses ChimeraX Coulombic surface coloring and reports whether PDB2PQR/APBS
+are installed. It is useful for qualitative orientation and charge patches.
+For quantitative comparisons, curate protonation and charges and use a validated
+Poisson-Boltzmann workflow with controlled dielectric and ionic-strength choices.
+
+## Pocket and tunnel candidates
+
+```bash
+python3 scripts/proteus.py pockets model.pdb --detector auto --execute --render
+```
+
+`auto` prefers fpocket, then P2Rank. Detection is optional and local; no
+structure is uploaded. Detected pocket files are copied into the output directory
+and rendered with lining residues. CAVER/HOLE availability is reported, but
+tunnel execution is left to a configured tool-specific workflow because starting
+points and probe settings are scientifically consequential.
+
+## Chemical sites
+
+```bash
+python3 scripts/proteus.py chemical-site complex.cif \
+  --component ZN:A:501 --radius 5 --outdir zinc_site --execute
+```
+
+Component selectors may be `RESN`, `CHAIN:RESIDUE`, or
+`RESN:CHAIN:RESIDUE`. The report classifies polymer, modified polymer, ligand,
+cofactor, ion, water, and common additive groups; lists nearest heavy-atom
+neighbors; and highlights metal-coordination candidates. PDB `LINK`/`CONECT` or
+mmCIF `struct_conn` counts are surfaced as connectivity evidence, not accepted
+as proof of a specific chemistry without inspection.
+
+## Optional structure-quality tools
+
+```bash
+python3 scripts/model_quality.py detect --json
+python3 scripts/model_quality.py usalign reference.pdb mobile.pdb --json
+python3 scripts/model_quality.py dockq model_complex.pdb native_complex.pdb --json
+python3 scripts/model_quality.py foldseek query.pdb target_directory --json
+```
+
+DockQ writes and parses its JSON result. Foldseek uses `easy-search` with
+alignment TM-scores, query/target-normalized TM-scores, lDDT, E-value, and bits.
+These tools are optional and are never installed automatically.
+
+## Human handoff checklist
+
+Before handing a result to a user, verify:
+
+1. the input identity, residue numbering, model, conformer, and assembly;
+2. every expected image/session exists and is non-empty;
+3. the JSON report names the method, selection, cutoff, and provenance;
+4. replay scripts contain no credentials and were written only to the requested
+   output directory;
+5. interpretation distinguishes computed geometry from biological inference;
+6. the user receives the `.pml`/`.cxc` and `.pse`/`.cxs` paths needed to continue.
diff --git a/scripts/annotation_figure.py b/scripts/annotation_figure.py
new file mode 100644
index 0000000..b97d01a
--- /dev/null
+++ b/scripts/annotation_figure.py
@@ -0,0 +1,197 @@
+#!/usr/bin/env python3
+"""Map user-supplied residue annotations onto PyMOL and ChimeraX scenes."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import proteus_common
+import visual_common
+
+
+SPEC_RE = re.compile(r"^[A-Za-z0-9_.+?-]+$")
+
+
+def _annotations(path: str | Path) -> list[dict[str, Any]]:
+    records = visual_common.load_records(path)
+    output = []
+    for index, record in enumerate(records, start=1):
+        chain = str(record.get("chain") or "").strip()
+        residue = str(record.get("residue") or record.get("resi") or "").strip()
+        if not residue:
+            raise visual_common.VisualWorkflowError(f"Annotation {index} is missing residue/resi.")
+        if any(character in residue for character in "\r\n; "):
+            raise visual_common.VisualWorkflowError(f"Invalid residue identifier in annotation {index}.")
+        if not SPEC_RE.fullmatch(residue) or (chain and not SPEC_RE.fullmatch(chain)):
+            raise visual_common.VisualWorkflowError(f"Invalid chain or residue identifier in annotation {index}.")
+        score_raw = record.get("score", record.get("value"))
+        score = None
+        if score_raw not in {None, ""}:
+            score = float(score_raw)
+            if not math.isfinite(score):
+                raise visual_common.VisualWorkflowError(f"Annotation {index} has a non-finite score.")
+        label = str(record.get("label") or "").strip()
+        if any(character in label for character in "\r\n;"):
+            raise visual_common.VisualWorkflowError(f"Annotation {index} label cannot contain newlines or semicolons.")
+        item = {
+            "chain": chain,
+            "residue": residue,
+            "score": score,
+            "label": label,
+            "color": str(record.get("color") or "").strip(),
+        }
+        if item["color"]:
+            visual_common.color(item["color"])
+        output.append(item)
+    return output
+
+
+def _pymol_selection(item: dict[str, Any]) -> str:
+    base = f"resi {item['residue']}"
+    return f"chain {item['chain']} and {base}" if item["chain"] else base
+
+
+def _chimerax_selection(item: dict[str, Any]) -> str:
+    return f"#1/{item['chain']}:{item['residue']}" if item["chain"] else f"#1:{item['residue']}"
+
+
+def build_annotation_figure(structure: str, annotation_file: str, outdir: str, *,
+                            execute: bool = False, surface: bool = False,
+                            width: int = 1200, height: int = 900) -> dict[str, Any]:
+    source = Path(structure).expanduser()
+    if not source.is_file():
+        raise visual_common.VisualWorkflowError(f"Structure not found: {proteus_common.display_path(source)}")
+    annotations = _annotations(annotation_file)
+    if not annotations:
+        raise visual_common.VisualWorkflowError("No annotations were supplied.")
+    destination = Path(outdir)
+    destination.mkdir(parents=True, exist_ok=True)
+    scores = [item["score"] for item in annotations if item["score"] is not None]
+    score_range = [min(scores), max(scores)] if scores else None
+
+    pml = visual_common.pymol_base(width=width, height=height)
+    pml.extend([
+        f"load {visual_common.quote_pymol(source.resolve())}, structure",
+        "hide everything, all",
+        "show cartoon, polymer",
+        "color gray80, polymer",
+    ])
+    if surface:
+        pml.extend(["show surface, polymer", "set surface_transparency, 0.2, polymer"])
+    for index, item in enumerate(annotations, start=1):
+        selector = _pymol_selection(item)
+        name = f"annotation_{index}"
+        pml.append(f"select {name}, structure and ({selector})")
+        pml.append(f"show sticks, {name}")
+        if item["score"] is not None:
+            pml.append(f"alter {name}, b={item['score']:.8g}")
+        if item["color"]:
+            pml.append(f"color {item['color']}, {name}")
+        if item["label"]:
+            label = item["label"].replace('"', '\\"')
+            pml.append(f"label {name} and name CA, \"{label}\"")
+    if scores and not any(item["color"] for item in annotations):
+        minimum, maximum = score_range or [0.0, 1.0]
+        if minimum == maximum:
+            maximum = minimum + 1.0
+        pml.append(f"spectrum b, blue_white_red, annotation_*, minimum={minimum:.8g}, maximum={maximum:.8g}")
+    pml.extend(visual_common.finalize_pymol(
+        destination / "annotations.png", width=width, height=height,
+        session=destination / "annotations.pse",
+    ))
+
+    cxc = [
+        *visual_common.chimerax_base(),
+        f"open {visual_common.quote_chimerax(source.resolve())}",
+        "cartoon",
+        "color protein lightgray",
+    ]
+    if surface:
+        cxc.extend(["surface protein", "transparency protein 20 target s"])
+    for item in annotations:
+        selector = _chimerax_selection(item)
+        if item["score"] is not None:
+            cxc.append(f"setattr {selector} r proteus_score {item['score']:.8g} create true type float")
+        if item["color"]:
+            cxc.append(f"color {selector} {item['color']}")
+        cxc.extend([f"show {selector} atoms", f"style {selector} stick"])
+        if item["label"]:
+            label = item["label"].replace('"', '\\"')
+            cxc.append(f"label {selector} text \"{label}\"")
+    if scores and not any(item["color"] for item in annotations):
+        minimum, maximum = score_range or [0.0, 1.0]
+        if minimum == maximum:
+            maximum = minimum + 1.0
+        cxc.append(f"color byattribute r:proteus_score #1 palette blue-white-red range {minimum:.8g},{maximum:.8g}")
+    cxc.extend(visual_common.finalize_chimerax(
+        destination / "annotations_chimerax.png", width=width, height=height,
+        session=destination / "annotations.cxs",
+    ))
+
+    data: dict[str, Any] = {
+        "workflow": "annotation_figure",
+        "structure": proteus_common.display_path(source),
+        "annotation_count": len(annotations),
+        "score_range": score_range,
+        "surface": surface,
+        "images": {
+            "pymol": proteus_common.display_path(destination / "annotations.png"),
+            "chimerax": proteus_common.display_path(destination / "annotations_chimerax.png"),
+        },
+        "executed": execute,
+    }
+    report = proteus_common.ok_payload(
+        data,
+        warnings=["Annotation residue identifiers use coordinate-file numbering."],
+        provenance={
+            "structure": proteus_common.file_provenance(source),
+            "annotations": proteus_common.file_provenance(annotation_file),
+        },
+    )
+    data["artifacts"] = visual_common.write_workflow(
+        destination, "annotation_figure", report=report, pymol_lines=pml, chimerax_lines=cxc,
+    )
+    if execute:
+        data["execution"] = {
+            "pymol": visual_common.run_pymol(destination / "annotation_figure.pml"),
+            "chimerax": visual_common.run_chimerax(cxc),
+        }
+        failures = [name for name, result in data["execution"].items() if result.get("status") not in {"ok", "unavailable"}]
+        if failures:
+            report["status"] = "error"
+            report["error"] = f"Annotation rendering failed for: {', '.join(failures)}"
+        proteus_common.write_json(destination / "annotation_figure.json", report)
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Color and label structures from CSV/JSON residue annotations.")
+    parser.add_argument("structure")
+    parser.add_argument("annotations", help="CSV/JSON with chain,residue,score,label,color fields")
+    parser.add_argument("--outdir", default="proteus_annotations")
+    parser.add_argument("--surface", action="store_true")
+    parser.add_argument("--execute", action="store_true")
+    parser.add_argument("--json", action="store_true", help="Emit JSON (accepted for consistency)")
+    args = parser.parse_args(argv)
+    try:
+        report = build_annotation_figure(args.structure, args.annotations, args.outdir,
+                                         execute=args.execute, surface=args.surface)
+    except (OSError, ValueError, json.JSONDecodeError, visual_common.VisualWorkflowError) as exc:
+        print(json.dumps(proteus_common.error_payload(str(exc)), indent=2))
+        return 1
+    print(json.dumps(report, indent=2))
+    return 0 if report.get("status") == "ok" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/assembly_explorer.py b/scripts/assembly_explorer.py
new file mode 100644
index 0000000..cd4ffde
--- /dev/null
+++ b/scripts/assembly_explorer.py
@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""Compare asymmetric-unit, biological-assembly, and crystal-neighbor views."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import assembly_report
+import proteus_common
+import visual_common
+
+
+PDB_ID_RE = re.compile(r"^[0-9][A-Za-z0-9]{3}$")
+
+
+def explore_assembly(input_value: str, outdir: str, *, assembly: int = 1,
+                     execute: bool = False, width: int = 1300, height: int = 900) -> dict[str, Any]:
+    if assembly < 1:
+        raise visual_common.VisualWorkflowError("Assembly number must be positive.")
+    source = Path(input_value).expanduser()
+    pdb_id = input_value.upper() if PDB_ID_RE.fullmatch(input_value.strip()) and not source.exists() else None
+    metadata = None
+    provenance: dict[str, Any]
+    warnings = [
+        "Biological assemblies are author/depositor interpretations and should be checked against experimental context.",
+        "Crystal neighbors show packing contacts and are not automatically biological interfaces.",
+    ]
+    if pdb_id:
+        metadata = assembly_report.fetch_assembly_report(pdb_id, requested_assembly=assembly)
+        provenance = {"source": {"kind": "pdb_id", "id": pdb_id, "api": assembly_report.RCSB_ENTRY.format(pdb_id=pdb_id)}}
+        open_command = f"open {pdb_id} from pdb"
+        pymol_load = f"fetch {pdb_id}, async=0"
+    else:
+        if not source.is_file():
+            raise visual_common.VisualWorkflowError("Input must be a local structure or four-character PDB ID.")
+        provenance = {"source": proteus_common.file_provenance(source)}
+        open_command = f"open {visual_common.quote_chimerax(source.resolve())}"
+        pymol_load = f"load {visual_common.quote_pymol(source.resolve())}, structure"
+        warnings.append("Assembly availability could not be verified from a local file alone.")
+
+    destination = Path(outdir)
+    destination.mkdir(parents=True, exist_ok=True)
+    asu_image = (destination / "asymmetric_unit.png").resolve()
+    assembly_image = (destination / f"assembly_{assembly}.png").resolve()
+    crystal_image = (destination / "crystal_neighbors.png").resolve()
+    cxc = [
+        *visual_common.chimerax_base(),
+        open_command,
+        "cartoon",
+        "color #1 bychain",
+        "view",
+        f"save {visual_common.quote_chimerax(asu_image)} width {width} height {height} supersample 3",
+        "wait 1",
+        f"sym #1 assembly {assembly} copies true",
+        "color all bychain",
+        "view",
+        f"save {visual_common.quote_chimerax(assembly_image)} width {width} height {height} supersample 3",
+        "wait 1",
+        f"save {visual_common.quote_chimerax((destination / 'assembly_explorer.cxs').resolve())}",
+    ]
+    pml = visual_common.pymol_base(width=width, height=height)
+    pml.extend([
+        pymol_load,
+        "hide everything, all",
+        "show cartoon, polymer",
+        "util.cbc()",
+        "symexp crystal_, all, all, 5",
+        "color gray80, crystal_*",
+        "set cartoon_transparency, 0.35, crystal_*",
+        "orient all",
+        f"ray {width}, {height}",
+        *visual_common.pymol_png(crystal_image, width=width, height=height),
+        *visual_common.pymol_save(destination / "crystal_neighbors.pse"),
+        "quit",
+    ])
+    data: dict[str, Any] = {
+        "workflow": "assembly_explorer",
+        "input": pdb_id or proteus_common.display_path(source),
+        "assembly": assembly,
+        "assembly_metadata": metadata.get("data", metadata) if metadata else None,
+        "images": {
+            "asymmetric_unit": proteus_common.display_path(asu_image),
+            "biological_assembly": proteus_common.display_path(assembly_image),
+            "crystal_neighbors": proteus_common.display_path(crystal_image),
+        },
+        "executed": execute,
+    }
+    report = proteus_common.ok_payload(data, warnings=warnings, provenance=provenance)
+    data["artifacts"] = visual_common.write_workflow(
+        destination, "assembly_explorer", report=report, pymol_lines=pml, chimerax_lines=cxc,
+    )
+    if execute:
+        data["execution"] = {
+            "chimerax": visual_common.run_chimerax(cxc),
+            "pymol": visual_common.run_pymol(destination / "assembly_explorer.pml"),
+        }
+        failures = [name for name, result in data["execution"].items() if result.get("status") not in {"ok", "unavailable"}]
+        if failures:
+            report["status"] = "error"
+            report["error"] = f"Assembly rendering failed for: {', '.join(failures)}"
+        proteus_common.write_json(destination / "assembly_explorer.json", report)
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Compare asymmetric unit, biological assembly, and crystal neighbors.")
+    parser.add_argument("input", help="Local PDB/mmCIF or PDB ID")
+    parser.add_argument("--assembly", type=int, default=1)
+    parser.add_argument("--outdir", default="proteus_assembly")
+    parser.add_argument("--execute", action="store_true")
+    parser.add_argument("--json", action="store_true", help="Emit JSON (accepted for consistency)")
+    args = parser.parse_args(argv)
+    try:
+        report = explore_assembly(args.input, args.outdir, assembly=args.assembly, execute=args.execute)
+    except (OSError, ValueError, assembly_report.AssemblyReportError, visual_common.VisualWorkflowError) as exc:
+        print(json.dumps(proteus_common.error_payload(str(exc)), indent=2))
+        return 1
+    print(json.dumps(report, indent=2))
+    return 0 if report.get("status") == "ok" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/chemical_site.py b/scripts/chemical_site.py
new file mode 100644
index 0000000..5a92198
--- /dev/null
+++ b/scripts/chemical_site.py
@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""Triage ligands, metals, waters, and covalent evidence around a chemical site."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import re
+import sys
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import proteus_common
+import structure_qc
+import visual_common
+
+
+SPEC_RE = re.compile(r"^[A-Za-z0-9_.+?-]+$")
+
+
+def _distance(left: dict[str, Any], right: dict[str, Any]) -> float:
+    return math.sqrt(sum((left[axis] - right[axis]) ** 2 for axis in ("x", "y", "z")))
+
+
+def _groups(atoms: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    grouped: dict[tuple[Any, ...], list[dict[str, Any]]] = defaultdict(list)
+    for atom in atoms:
+        key = (atom["model"], atom["chain"], atom["residue_id"], atom["insertion_code"], atom["resname"])
+        grouped[key].append(atom)
+    output = []
+    for key, values in grouped.items():
+        model, chain, residue_id, insertion_code, resname = key
+        output.append({
+            "model": model,
+            "chain": chain,
+            "residue": f"{residue_id}{insertion_code}",
+            "residue_id": residue_id,
+            "insertion_code": insertion_code,
+            "component": resname,
+            "role": structure_qc.component_role(resname, values[0]["record"], len(values)),
+            "atoms": values,
+        })
+    return output
+
+
+def _choose_site(groups: list[dict[str, Any]], component: str | None) -> dict[str, Any]:
+    chemical = [item for item in groups if item["role"] not in {"polymer", "modified_polymer", "water", "additive_or_solvent"}]
+    if component:
+        parts = component.split(":")
+        matches = []
+        for item in chemical:
+            if len(parts) == 1 and item["component"].upper() == parts[0].upper():
+                matches.append(item)
+            elif len(parts) == 2 and item["chain"] == parts[0] and item["residue"] == parts[1]:
+                matches.append(item)
+            elif len(parts) == 3 and item["component"].upper() == parts[0].upper() and item["chain"] == parts[1] and item["residue"] == parts[2]:
+                matches.append(item)
+        if len(matches) != 1:
+            raise visual_common.VisualWorkflowError(f"--component matched {len(matches)} sites; use RESN:CHAIN:RESIDUE to select one.")
+        return matches[0]
+    preferred = [item for item in chemical if item["role"] in {"ligand_or_unknown", "cofactor"}]
+    candidates = preferred or chemical
+    if not candidates:
+        raise visual_common.VisualWorkflowError("No ligand, cofactor, or ion site was found.")
+    if len(candidates) > 1:
+        labels = ", ".join(f"{item['component']}:{item['chain']}:{item['residue']}" for item in candidates[:8])
+        raise visual_common.VisualWorkflowError(f"Multiple chemical sites are present ({labels}); choose one with --component.")
+    return candidates[0]
+
+
+def inspect_chemical_site(structure: str, outdir: str, *, component: str | None = None,
+                          radius: float = 5.0, execute: bool = False,
+                          width: int = 1300, height: int = 900) -> dict[str, Any]:
+    source = Path(structure).expanduser()
+    if not source.is_file():
+        raise visual_common.VisualWorkflowError(f"Structure not found: {proteus_common.display_path(source)}")
+    if radius <= 0:
+        raise visual_common.VisualWorkflowError("Radius must be positive.")
+    text = structure_qc._read_text(source)
+    fmt = structure_qc._format_from_path(source)
+    raw, parser_meta = structure_qc.parse_mmcif(text) if fmt == "mmcif" else structure_qc.parse_pdb(text)
+    atoms, selection = structure_qc.select_atoms(raw, model="first", altloc="highest")
+    groups = _groups(atoms)
+    site = _choose_site(groups, component)
+    neighbors = []
+    coordination = []
+    for group in groups:
+        if group is site:
+            continue
+        distances = [
+            (_distance(left, right), left, right)
+            for left in site["atoms"] for right in group["atoms"]
+            if left["element"] != "H" and right["element"] != "H"
+        ]
+        if not distances:
+            continue
+        closest = min(distances, key=lambda item: item[0])
+        distance, site_atom, neighbor_atom = closest
+        if distance <= radius:
+            record = {
+                "component": group["component"],
+                "chain": group["chain"],
+                "residue": group["residue"],
+                "role": group["role"],
+                "distance_angstrom": round(distance, 3),
+                "site_atom": site_atom["atom_name"],
+                "neighbor_atom": neighbor_atom["atom_name"],
+            }
+            neighbors.append(record)
+            if site["role"] == "ion" and distance <= 3.2:
+                coordination.append(record)
+    neighbors.sort(key=lambda item: item["distance_angstrom"])
+    coordination.sort(key=lambda item: item["distance_angstrom"])
+    destination = Path(outdir)
+    destination.mkdir(parents=True, exist_ok=True)
+    chain, residue, resname = site["chain"], site["residue"], site["component"]
+    safe_visual = all(SPEC_RE.fullmatch(str(value)) for value in (chain, residue, resname))
+    warnings = [
+        "Distance-based coordination and covalent-link evidence are hypotheses; verify geometry, valence, protonation, and experimental density.",
+        "Waters, additives, and ions can be modeled ambiguously at limited resolution.",
+    ]
+    pml: list[str] | None = None
+    cxc: list[str] | None = None
+    if safe_visual:
+        pml = visual_common.pymol_base(width=width, height=height)
+        site_selection = f"resn {resname} and chain {chain} and resi {residue}"
+        pml.extend([
+            f"load {visual_common.quote_pymol(source.resolve())}, structure",
+            "hide everything, all",
+            "show cartoon, polymer",
+            "color gray80, polymer",
+            f"select chemical_site, {site_selection}",
+            f"select site_neighbors, byres (all within {radius:g} of chemical_site)",
+            "show sticks, chemical_site or site_neighbors",
+            "show spheres, chemical_site and inorganic",
+            "color tv_orange, chemical_site",
+            "color cyan, site_neighbors and polymer",
+            "distance site_contacts, chemical_site, site_neighbors, 3.6, 2",
+            "label chemical_site and not hydro, resn + resi",
+            "orient chemical_site or site_neighbors",
+            "zoom chemical_site or site_neighbors, 4",
+            *visual_common.finalize_pymol(
+                destination / "chemical_site.png", width=width, height=height,
+                session=destination / "chemical_site.pse",
+            ),
+        ])
+        cx_site = f"#1/{chain}:{residue}"
+        cxc = [
+            *visual_common.chimerax_base(),
+            f"open {visual_common.quote_chimerax(source.resolve())}",
+            "cartoon #1",
+            "color #1 lightgray",
+            f"select {cx_site}",
+            f"select zone sel {radius:g} residues true",
+            "show sel atoms",
+            "style sel stick",
+            f"color {cx_site} orange",
+            f"contacts {cx_site} restrict sel reveal true showDist true log true",
+            f"hbonds {cx_site} restrict sel reveal true log true",
+            "view sel",
+            *visual_common.finalize_chimerax(
+                destination / "chemical_site_chimerax.png", width=width, height=height,
+                session=destination / "chemical_site.cxs",
+            ),
+        ]
+    else:
+        warnings.append("The selected site's identifiers were not safe to embed in replay scripts, so only the analysis report was written.")
+    site_data = {key: site[key] for key in ("model", "chain", "residue", "component", "role")}
+    data: dict[str, Any] = {
+        "workflow": "chemical_site",
+        "structure": proteus_common.display_path(source),
+        "site": site_data,
+        "radius_angstrom": radius,
+        "neighbors": neighbors,
+        "coordination_candidates": coordination,
+        "connectivity_evidence": parser_meta,
+        "selection": selection,
+        "executed": execute,
+    }
+    report = proteus_common.ok_payload(
+        data, warnings=warnings, provenance={"structure": proteus_common.file_provenance(source)},
+    )
+    data["artifacts"] = visual_common.write_workflow(
+        destination, "chemical_site", report=report, pymol_lines=pml, chimerax_lines=cxc,
+    )
+    if execute and pml is not None and cxc is not None:
+        data["execution"] = {
+            "pymol": visual_common.run_pymol(destination / "chemical_site.pml"),
+            "chimerax": visual_common.run_chimerax(cxc),
+        }
+        failures = [name for name, result in data["execution"].items() if result.get("status") not in {"ok", "unavailable"}]
+        if failures:
+            report["status"] = "error"
+            report["error"] = f"Chemical-site rendering failed for: {', '.join(failures)}"
+        proteus_common.write_json(destination / "chemical_site.json", report)
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Inspect a ligand, cofactor, or metal site with chemical-context warnings.")
+    parser.add_argument("structure")
+    parser.add_argument("--component", help="RESN, CHAIN:RESIDUE, or RESN:CHAIN:RESIDUE")
+    parser.add_argument("--radius", type=float, default=5.0)
+    parser.add_argument("--outdir", default="proteus_chemical_site")
+    parser.add_argument("--execute", action="store_true")
+    parser.add_argument("--json", action="store_true", help="Emit JSON (accepted for consistency)")
+    args = parser.parse_args(argv)
+    try:
+        report = inspect_chemical_site(
+            args.structure, args.outdir, component=args.component, radius=args.radius, execute=args.execute,
+        )
+    except (OSError, ValueError, structure_qc.StructureQCError, visual_common.VisualWorkflowError) as exc:
+        print(json.dumps(proteus_common.error_payload(str(exc)), indent=2))
+        return 1
+    print(json.dumps(report, indent=2))
+    return 0 if report.get("status") == "ok" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/chimerax_rest.py b/scripts/chimerax_rest.py
index d6d1205..a0e0c92 100755
--- a/scripts/chimerax_rest.py
+++ b/scripts/chimerax_rest.py
@@ -15,7 +15,7 @@
     python chimerax_rest.py render structure.pdb out.png --style surface --color bychain
     python chimerax_rest.py render model.pdb out.png --color plddt
     python chimerax_rest.py spin model.pdb spin.mp4 --frames 72        # needs ffmpeg
-    python chimerax_rest.py run "open 1ubq from pdb; cartoon; color bychain"
+    python chimerax_rest.py run "open 1ubq from pdb; cartoon; color #1 bychain"
     python chimerax_rest.py --help
 
 Environment:
@@ -240,7 +240,7 @@ def _scene_commands(style: str, color: str) -> list:
     cmds += styles.get(style, styles["cartoon"])
     color_cmd = {
         "rainbow": "rainbow #1",
-        "bychain": "color bychain #1",
+        "bychain": "color #1 bychain",
         "bfactor": "color bfactor #1",
         "plddt": "color bfactor #1 palette alphafold",
     }.get(color, f"color #1 {color}")
@@ -362,7 +362,7 @@ def main():
         epilog="Examples:\n"
                "  %(prog)s render structure.pdb out.png --color plddt\n"
                "  %(prog)s spin model.pdb spin.mp4 --frames 72\n"
-               "  %(prog)s run 'open 1ubq from pdb; cartoon; color bychain'",
+               "  %(prog)s run 'open 1ubq from pdb; cartoon; color #1 bychain'",
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     sub = parser.add_subparsers(dest="command", required=True)
diff --git a/scripts/cryoem_workflow.py b/scripts/cryoem_workflow.py
new file mode 100644
index 0000000..23f0f83
--- /dev/null
+++ b/scripts/cryoem_workflow.py
@@ -0,0 +1,221 @@
+#!/usr/bin/env python3
+"""Build a replayable ChimeraX cryo-EM map/model inspection workflow."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import chimerax_agent
+import map_info
+import proteus_common
+import visual_common
+
+
+PDB_ID_RE = re.compile(r"^[0-9][A-Za-z0-9]{3}$")
+EMDB_ID_RE = re.compile(r"^(?:EMD[-_ ]?)?([0-9]{3,6})$", re.IGNORECASE)
+
+
+def _analysis_summary(result: dict[str, Any]) -> dict[str, Any]:
+    cleaned = proteus_common.scrub_private(result)
+    output: dict[str, Any] = {"status": cleaned.get("status", "error")}
+    if cleaned.get("error"):
+        output["error"] = cleaned["error"]
+    info = cleaned.get("info") or cleaned.get("data", {}).get("info") or []
+    useful = []
+    for line in info:
+        text = str(line)
+        if any(term in text.lower() for term in ("correlation", "mean", "rms", "minimum", "maximum", "standard deviation", "map value")):
+            useful.append(text)
+        if len(useful) >= 30:
+            break
+    if useful:
+        output["measurements"] = useful
+    return output
+
+
+def _model_source(value: str) -> tuple[str, dict[str, Any]]:
+    path = Path(value).expanduser()
+    if path.is_file():
+        return f"open {visual_common.quote_chimerax(path.resolve())}", proteus_common.file_provenance(path)
+    if PDB_ID_RE.fullmatch(value.strip()):
+        pdb_id = value.upper()
+        return f"open {pdb_id} from pdb", {"kind": "pdb_id", "id": pdb_id}
+    raise visual_common.VisualWorkflowError("Model must be a local PDB/mmCIF file or four-character PDB ID.")
+
+
+def _map_source(value: str) -> tuple[str, dict[str, Any], dict[str, Any] | None]:
+    path = Path(value).expanduser()
+    if path.is_file():
+        stats = map_info.map_info(str(path)).get("data", {})
+        return (
+            f"open {visual_common.quote_chimerax(path.resolve())}",
+            proteus_common.file_provenance(path),
+            {key: stats.get(key) for key in ("dimensions", "dtype", "mean", "sigma", "suggested_levels")},
+        )
+    match = EMDB_ID_RE.fullmatch(value.strip())
+    if match:
+        emdb_id = f"EMD-{match.group(1)}"
+        return f"open {emdb_id} from emdb", {"kind": "emdb_id", "id": emdb_id}, None
+    raise visual_common.VisualWorkflowError("Map must be a local MRC/CCP4 file or EMDB ID.")
+
+
+def _parse_levels(value: str | None, stats: dict[str, Any] | None) -> list[float]:
+    if value:
+        try:
+            levels = [float(item.strip()) for item in value.split(",") if item.strip()]
+        except ValueError as exc:
+            raise visual_common.VisualWorkflowError("--levels must be comma-separated numeric map values.") from exc
+        if not levels:
+            raise visual_common.VisualWorkflowError("--levels did not contain any map values.")
+        return levels
+    suggested = (stats or {}).get("suggested_levels") or {}
+    defaults = [suggested.get(key) for key in ("1.5_sigma", "2.0_sigma", "3.0_sigma")]
+    return [float(item) for item in defaults if item is not None]
+
+
+def build_cryoem_workflow(
+    model: str,
+    density_map: str,
+    outdir: str,
+    *,
+    resolution: float | None = None,
+    levels: str | None = None,
+    fit: bool = False,
+    difference: bool = False,
+    execute: bool = False,
+    width: int = 1300,
+    height: int = 900,
+) -> dict[str, Any]:
+    if resolution is not None and resolution <= 0:
+        raise visual_common.VisualWorkflowError("Resolution must be positive.")
+    if difference and resolution is None:
+        raise visual_common.VisualWorkflowError("--difference requires --resolution for the model-derived map.")
+    model_open, model_provenance = _model_source(model)
+    map_open, map_provenance, stats = _map_source(density_map)
+    contour_levels = _parse_levels(levels, stats)
+    if not contour_levels:
+        raise visual_common.VisualWorkflowError("Remote EMDB maps require explicit absolute --levels values.")
+
+    destination = Path(outdir)
+    destination.mkdir(parents=True, exist_ok=True)
+    commands = [
+        *visual_common.chimerax_base(),
+        model_open,
+        map_open,
+        "cartoon #1",
+        "color #1 bychain",
+        "volume #2 style surface",
+        "volume #2 color #7FB3D5 transparency 55",
+    ]
+    if fit:
+        fit_command = "fitmap #1 inMap #2"
+        if resolution is not None:
+            fit_command += f" resolution {resolution:g}"
+        fit_command += " metric correlation"
+        commands.append(fit_command)
+    commands.extend([
+        "measure mapstats #2",
+    ])
+    images: list[str] = []
+    for index, level in enumerate(contour_levels, start=1):
+        image = (destination / f"contour_{index}_{level:g}.png").resolve()
+        images.append(proteus_common.display_path(image))
+        commands.extend([
+            f"volume #2 level {level:g}",
+            "view #1,2",
+            f"save {visual_common.quote_chimerax(image)} width {width} height {height} supersample 3",
+            "wait 1",
+        ])
+    if difference:
+        difference_image = (destination / "difference_map.png").resolve()
+        span = max(abs(item) for item in contour_levels)
+        commands.extend([
+            f"molmap #1 {resolution:g}",
+            "volume subtract #2 #3 minRms true onGrid #2",
+            "hide #2 models",
+            f"volume #4 level {-span:g} color red level {span:g} color blue transparency 35",
+            "view #1,4",
+            f"save {visual_common.quote_chimerax(difference_image)} width {width} height {height} supersample 3",
+            "wait 1",
+        ])
+        images.append(proteus_common.display_path(difference_image))
+    commands.append(f"save {visual_common.quote_chimerax((destination / 'cryoem_workflow.cxs').resolve())}")
+
+    warnings = [
+        "Contour levels are absolute map values; compare several levels and retain the map's experimental context.",
+        "Rigid-body fitting can overstate agreement and should be validated independently, especially when the initial pose is poor.",
+    ]
+    if difference:
+        warnings.append("The model-derived difference map is qualitative and depends on resolution, sharpening, masking, and map scaling.")
+    data: dict[str, Any] = {
+        "workflow": "cryoem",
+        "model": proteus_common.display_path(model) if Path(model).expanduser().is_file() else model.upper(),
+        "map": proteus_common.display_path(density_map) if Path(density_map).expanduser().is_file() else density_map.upper(),
+        "map_statistics": stats,
+        "contour_levels": contour_levels,
+        "resolution_angstrom": resolution,
+        "fit_requested": fit,
+        "difference_map_requested": difference,
+        "images": images,
+        "session": proteus_common.display_path(destination / "cryoem_workflow.cxs"),
+        "executed": execute,
+    }
+    report = proteus_common.ok_payload(
+        data,
+        warnings=warnings,
+        provenance={"model": model_provenance, "map": map_provenance},
+    )
+    data["artifacts"] = visual_common.write_workflow(
+        destination, "cryoem_workflow", report=report, chimerax_lines=commands,
+    )
+    if execute:
+        analysis = [model_open, map_open]
+        if fit:
+            analysis.append(next(item for item in commands if item.startswith("fitmap ")))
+        analysis.append("measure mapstats #2")
+        data["analysis"] = _analysis_summary(
+            chimerax_agent.run_chimerax_command_list(analysis, timeout=600)
+        )
+        data["execution"] = {"chimerax": visual_common.run_chimerax(commands, timeout=1200)}
+        if data["execution"]["chimerax"].get("status") not in {"ok", "unavailable"}:
+            report["status"] = "error"
+            report["error"] = "ChimeraX map rendering failed."
+        proteus_common.write_json(destination / "cryoem_workflow.json", report)
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Inspect a cryo-EM map/model pair and produce contour, fit, and session artifacts.")
+    parser.add_argument("model", help="Local structure or PDB ID")
+    parser.add_argument("map", help="Local MRC/CCP4 map or EMDB ID")
+    parser.add_argument("--resolution", type=float, help="Nominal map resolution in angstroms")
+    parser.add_argument("--levels", help="Comma-separated absolute map contour values")
+    parser.add_argument("--fit", action="store_true", help="Rigid-body fit the model into the map")
+    parser.add_argument("--difference", action="store_true", help="Create a qualitative map-minus-model difference view")
+    parser.add_argument("--outdir", default="proteus_cryoem")
+    parser.add_argument("--execute", action="store_true")
+    parser.add_argument("--json", action="store_true", help="Emit JSON (accepted for consistency)")
+    args = parser.parse_args(argv)
+    try:
+        report = build_cryoem_workflow(
+            args.model, args.map, args.outdir, resolution=args.resolution, levels=args.levels,
+            fit=args.fit, difference=args.difference, execute=args.execute,
+        )
+    except (OSError, ValueError, visual_common.VisualWorkflowError) as exc:
+        print(json.dumps(proteus_common.error_payload(str(exc)), indent=2))
+        return 1
+    print(json.dumps(report, indent=2))
+    return 0 if report.get("status") == "ok" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/electrostatics_workflow.py b/scripts/electrostatics_workflow.py
new file mode 100644
index 0000000..11b71b1
--- /dev/null
+++ b/scripts/electrostatics_workflow.py
@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""Create ChimeraX electrostatic surface workflows with explicit caveats."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import proteus_common
+import visual_common
+
+
+def build_electrostatics_workflow(
+    structure: str,
+    outdir: str,
+    *,
+    selection: str = "protein",
+    range_value: float = 10.0,
+    offset: float = 1.4,
+    execute: bool = False,
+    width: int = 1300,
+    height: int = 900,
+) -> dict[str, Any]:
+    source = Path(structure).expanduser()
+    if not source.is_file():
+        raise visual_common.VisualWorkflowError(f"Structure not found: {proteus_common.display_path(source)}")
+    visual_common.selection(selection)
+    if range_value <= 0 or offset < 0:
+        raise visual_common.VisualWorkflowError("Potential range must be positive and offset cannot be negative.")
+    destination = Path(outdir)
+    destination.mkdir(parents=True, exist_ok=True)
+    image = (destination / "electrostatic_surface.png").resolve()
+    session = (destination / "electrostatics.cxs").resolve()
+    atom_spec = f"#1 & {selection}"
+    commands = [
+        *visual_common.chimerax_base(),
+        f"open {visual_common.quote_chimerax(source.resolve())}",
+        f"surface {atom_spec}",
+        f"coulombic {atom_spec} offset {offset:g} palette red-white-blue range {-range_value:g},{range_value:g} key true",
+        f"transparency {atom_spec} 8 target s",
+        f"view {atom_spec}",
+        f"save {visual_common.quote_chimerax(image)} width {width} height {height} supersample 3",
+        "wait 1",
+        f"save {visual_common.quote_chimerax(session)}",
+    ]
+    external = {
+        "pdb2pqr": bool(proteus_common.find_executable("pdb2pqr", "pdb2pqr30")),
+        "apbs": bool(proteus_common.find_executable("apbs")),
+    }
+    data: dict[str, Any] = {
+        "workflow": "electrostatics",
+        "structure": proteus_common.display_path(source),
+        "selection": selection,
+        "potential_range_kcal_per_mol_e": [-range_value, range_value],
+        "surface_offset_angstrom": offset,
+        "method": "chimerax_coulombic",
+        "external_poisson_boltzmann_tools": external,
+        "image": proteus_common.display_path(image),
+        "session": proteus_common.display_path(session),
+        "executed": execute,
+    }
+    report = proteus_common.ok_payload(
+        data,
+        warnings=[
+            "Coulombic coloring is a qualitative potential estimate, not a Poisson-Boltzmann calculation.",
+            "Protonation, tautomer, charge, dielectric, ionic-strength, and missing-atom choices can change the interpretation.",
+            "Inspect ligands, metals, modified residues, termini, and alternate conformers before drawing mechanistic conclusions.",
+        ],
+        provenance={"structure": proteus_common.file_provenance(source)},
+    )
+    data["artifacts"] = visual_common.write_workflow(
+        destination, "electrostatics_workflow", report=report, chimerax_lines=commands,
+    )
+    if execute:
+        data["execution"] = {"chimerax": visual_common.run_chimerax(commands, timeout=900)}
+        if data["execution"]["chimerax"].get("status") not in {"ok", "unavailable"}:
+            report["status"] = "error"
+            report["error"] = "ChimeraX electrostatic rendering failed."
+        proteus_common.write_json(destination / "electrostatics_workflow.json", report)
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Create a ChimeraX Coulombic electrostatic surface and reusable session.")
+    parser.add_argument("structure")
+    parser.add_argument("--selection", default="protein", help="ChimeraX atom selection (default: protein)")
+    parser.add_argument("--range", dest="range_value", type=float, default=10.0, help="Symmetric potential color range")
+    parser.add_argument("--offset", type=float, default=1.4, help="Distance outward from the surface for evaluating potential")
+    parser.add_argument("--outdir", default="proteus_electrostatics")
+    parser.add_argument("--execute", action="store_true")
+    parser.add_argument("--json", action="store_true", help="Emit JSON (accepted for consistency)")
+    args = parser.parse_args(argv)
+    try:
+        report = build_electrostatics_workflow(
+            args.structure, args.outdir, selection=args.selection, range_value=args.range_value,
+            offset=args.offset, execute=args.execute,
+        )
+    except (OSError, ValueError, visual_common.VisualWorkflowError) as exc:
+        print(json.dumps(proteus_common.error_payload(str(exc)), indent=2))
+        return 1
+    print(json.dumps(report, indent=2))
+    return 0 if report.get("status") == "ok" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/ensemble_report.py b/scripts/ensemble_report.py
new file mode 100644
index 0000000..48f3f1e
--- /dev/null
+++ b/scripts/ensemble_report.py
@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+"""Analyze a multi-model coordinate ensemble and build replayable views."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import re
+import sys
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import proteus_common
+import structure_qc
+import visual_common
+
+
+SPEC_RE = re.compile(r"^[A-Za-z0-9_.+?-]+$")
+
+
+def _coordinates_by_model(atoms: list[dict[str, Any]]) -> tuple[list[int], list[tuple[Any, ...]], list[list[list[float]]]]:
+    models = sorted({int(atom["model"]) for atom in atoms})
+    ca_by_model: dict[int, dict[tuple[Any, ...], list[float]]] = defaultdict(dict)
+    for atom in atoms:
+        if atom["atom_name"] != "CA":
+            continue
+        key = (atom["chain"], atom["residue_id"], atom["insertion_code"], atom["resname"])
+        ca_by_model[int(atom["model"])][key] = [float(atom[axis]) for axis in ("x", "y", "z")]
+    if not models:
+        return [], [], []
+    common = sorted(set.intersection(*(set(ca_by_model[model]) for model in models)))
+    coordinates = [[ca_by_model[model][key] for key in common] for model in models]
+    return models, common, coordinates
+
+
+def _center(coordinates: list[list[float]]) -> tuple[list[list[float]], list[float]]:
+    centroid = [sum(point[axis] for point in coordinates) / len(coordinates) for axis in range(3)]
+    return [[point[axis] - centroid[axis] for axis in range(3)] for point in coordinates], centroid
+
+
+def _align(coordinates: list[list[list[float]]]) -> tuple[list[list[list[float]]], str]:
+    if not coordinates or not coordinates[0]:
+        return coordinates, "none"
+    try:
+        import numpy as np
+
+        reference, _ = _center(coordinates[0])
+        reference_array = np.asarray(reference, dtype=float)
+        aligned = []
+        for model_coordinates in coordinates:
+            centered, _ = _center(model_coordinates)
+            mobile = np.asarray(centered, dtype=float)
+            covariance = mobile.T @ reference_array
+            left, _singular, right_t = np.linalg.svd(covariance)
+            rotation = left @ right_t
+            if np.linalg.det(rotation) < 0:
+                left[:, -1] *= -1
+                rotation = left @ right_t
+            aligned.append((mobile @ rotation).tolist())
+        return aligned, "kabsch_ca"
+    except ImportError:
+        return [_center(model)[0] for model in coordinates], "centroid_translation"
+
+
+def _rmsf(coordinates: list[list[list[float]]]) -> list[float]:
+    count = len(coordinates)
+    output = []
+    for atom_index in range(len(coordinates[0])):
+        mean = [sum(model[atom_index][axis] for model in coordinates) / count for axis in range(3)]
+        squared = sum(
+            sum((model[atom_index][axis] - mean[axis]) ** 2 for axis in range(3))
+            for model in coordinates
+        ) / count
+        output.append(math.sqrt(squared))
+    return output
+
+
+def analyze_ensemble(structure: str, outdir: str, *, execute: bool = False,
+                     width: int = 1300, height: int = 900) -> dict[str, Any]:
+    source = Path(structure).expanduser()
+    if not source.is_file():
+        raise visual_common.VisualWorkflowError(f"Structure not found: {proteus_common.display_path(source)}")
+    text = structure_qc._read_text(source)
+    fmt = structure_qc._format_from_path(source)
+    raw, parser_meta = structure_qc.parse_mmcif(text) if fmt == "mmcif" else structure_qc.parse_pdb(text)
+    atoms, selection = structure_qc.select_atoms(raw, model="all", altloc="highest")
+    models, keys, coordinates = _coordinates_by_model(atoms)
+    if len(models) < 2:
+        raise visual_common.VisualWorkflowError("Ensemble analysis requires at least two coordinate models.")
+    if len(keys) < 3:
+        raise visual_common.VisualWorkflowError("Fewer than three common C-alpha atoms were found across models.")
+    aligned, method = _align(coordinates)
+    fluctuations = _rmsf(aligned)
+    residues = []
+    for key, value in zip(keys, fluctuations):
+        chain, residue_id, insertion_code, resname = key
+        residues.append({
+            "chain": chain,
+            "residue": f"{residue_id}{insertion_code}",
+            "resname": resname,
+            "rmsf_angstrom": round(value, 3),
+        })
+    ranked = sorted(residues, key=lambda item: item["rmsf_angstrom"], reverse=True)
+    destination = Path(outdir)
+    destination.mkdir(parents=True, exist_ok=True)
+
+    pml = visual_common.pymol_base(width=width, height=height)
+    pml.extend([
+        f"load {visual_common.quote_pymol(source.resolve())}, ensemble",
+        "hide everything, all",
+        "show cartoon, ensemble",
+        "intra_fit ensemble and name CA, 1",
+    ])
+    cxc = [
+        *visual_common.chimerax_base(),
+        f"open {visual_common.quote_chimerax(source.resolve())} coordsets true",
+        "cartoon #1",
+        "coordset #1 1",
+    ]
+    assigned = 0
+    for item in residues:
+        chain = str(item["chain"])
+        residue = str(item["residue"])
+        if not SPEC_RE.fullmatch(chain) or not SPEC_RE.fullmatch(residue):
+            continue
+        value = item["rmsf_angstrom"]
+        pml.append(f"alter ensemble and chain {chain} and resi {residue}, b={value:g}")
+        cxc.append(f"setattr #1/{chain}:{residue} r proteus_rmsf {value:g} create true type float")
+        assigned += 1
+    pml.extend([
+        "spectrum b, blue_white_red, ensemble",
+        "set all_states, on",
+        "set cartoon_transparency, 0.35",
+        *visual_common.finalize_pymol(
+            destination / "ensemble.png", width=width, height=height,
+            session=destination / "ensemble.pse",
+        ),
+    ])
+    cxc.extend([
+        "color byattribute r:proteus_rmsf #1 palette blue:white:red",
+        "coordset #1",
+        f"save {visual_common.quote_chimerax((destination / 'ensemble.cxs').resolve())}",
+    ])
+    data: dict[str, Any] = {
+        "workflow": "ensemble",
+        "structure": proteus_common.display_path(source),
+        "models": models,
+        "model_count": len(models),
+        "common_ca_count": len(keys),
+        "alignment_method": method,
+        "rmsf_summary_angstrom": {
+            "mean": round(sum(fluctuations) / len(fluctuations), 3),
+            "max": round(max(fluctuations), 3),
+        },
+        "most_variable_residues": ranked[:20],
+        "residues": residues,
+        "visual_attributes_assigned": assigned,
+        "parser": parser_meta,
+        "selection": selection,
+        "executed": execute,
+    }
+    warnings = [
+        "RMSF reports coordinate dispersion across the supplied models; it is not an experimental uncertainty estimate.",
+        "Only C-alpha atoms present in every model are compared.",
+    ]
+    if method == "centroid_translation":
+        warnings.append("NumPy was unavailable, so models were centered but not rotationally superposed for RMSF.")
+    report = proteus_common.ok_payload(
+        data, warnings=warnings, provenance={"structure": proteus_common.file_provenance(source)},
+    )
+    data["artifacts"] = visual_common.write_workflow(
+        destination, "ensemble_report", report=report, pymol_lines=pml, chimerax_lines=cxc,
+    )
+    if execute:
+        data["execution"] = {
+            "pymol": visual_common.run_pymol(destination / "ensemble_report.pml"),
+            "chimerax": visual_common.run_chimerax(cxc),
+        }
+        failures = [name for name, result in data["execution"].items() if result.get("status") not in {"ok", "unavailable"}]
+        if failures:
+            report["status"] = "error"
+            report["error"] = f"Ensemble rendering failed for: {', '.join(failures)}"
+        proteus_common.write_json(destination / "ensemble_report.json", report)
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Analyze multi-model structural variability and build PyMOL/ChimeraX sessions.")
+    parser.add_argument("structure", help="Multi-model PDB/mmCIF file")
+    parser.add_argument("--outdir", default="proteus_ensemble")
+    parser.add_argument("--execute", action="store_true")
+    parser.add_argument("--json", action="store_true", help="Emit JSON (accepted for consistency)")
+    args = parser.parse_args(argv)
+    try:
+        report = analyze_ensemble(args.structure, args.outdir, execute=args.execute)
+    except (OSError, ValueError, structure_qc.StructureQCError, visual_common.VisualWorkflowError) as exc:
+        print(json.dumps(proteus_common.error_payload(str(exc)), indent=2))
+        return 1
+    print(json.dumps(report, indent=2))
+    return 0 if report.get("status") == "ok" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/interface_story.py b/scripts/interface_story.py
new file mode 100644
index 0000000..538c62a
--- /dev/null
+++ b/scripts/interface_story.py
@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+"""Create an interface analysis report with ChimeraX and PyMOL artifacts."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import chimerax_agent
+import interface_report
+import proteus_common
+import visual_common
+
+
+def _analysis_summary(result: dict[str, Any]) -> dict[str, Any]:
+    cleaned = proteus_common.scrub_private(result)
+    output: dict[str, Any] = {"status": cleaned.get("status", "error")}
+    if cleaned.get("error"):
+        output["error"] = cleaned["error"]
+    info = cleaned.get("info") or cleaned.get("data", {}).get("info") or []
+    text = "\n".join(str(item) for item in info)
+    buried = re.findall(r"Buried area .*?=\s*([0-9.]+)", text)
+    hydrogen = re.findall(r"(\d+) hydrogen bonds found", text)
+    contacts = re.findall(r"(?m)^(\d+) contacts$", text)
+    clashes = re.findall(r"(?m)^(\d+) clashes$", text)
+    output["metrics"] = {
+        "buried_area_angstrom2": float(buried[-1]) if buried else None,
+        "hydrogen_bonds": int(hydrogen[-1]) if hydrogen else None,
+        "contacts": max((int(value) for value in contacts), default=None),
+        "clashes": max((int(value) for value in clashes), default=None),
+    }
+    return output
+
+
+def _chain(value: str) -> str:
+    if not value or not value.replace("_", "").isalnum():
+        raise visual_common.VisualWorkflowError(f"Invalid chain identifier: {value!r}")
+    return value
+
+
+def _pymol_lines(structure: Path, chain1: str, chain2: str, outdir: Path,
+                  cutoff: float, width: int, height: int) -> list[str]:
+    overview = (outdir / "interface_overview.png").resolve()
+    closeup = (outdir / "interface_closeup.png").resolve()
+    session = (outdir / "interface_story.pse").resolve()
+    lines = visual_common.pymol_base(width=width, height=height)
+    lines.extend([
+        f"load {visual_common.quote_pymol(structure.resolve())}, complex",
+        "hide everything, all",
+        f"show cartoon, chain {chain1} or chain {chain2}",
+        f"color marine, chain {chain1}",
+        f"color salmon, chain {chain2}",
+        f"select interface1, byres (chain {chain1} within {cutoff:.2f} of chain {chain2})",
+        f"select interface2, byres (chain {chain2} within {cutoff:.2f} of chain {chain1})",
+        "show sticks, interface1 or interface2",
+        "color cyan, interface1",
+        "color orange, interface2",
+        f"orient chain {chain1} or chain {chain2}",
+        f"ray {width}, {height}",
+        *visual_common.pymol_png(overview, width=width, height=height),
+        "distance interface_polar, interface1, interface2, 3.6, 2",
+        "set dash_color, gray30, interface_polar",
+        "label (interface1 or interface2) and name CA, resn + resi",
+        "orient interface1 or interface2",
+        "zoom interface1 or interface2, 4",
+        f"ray {width}, {height}",
+        *visual_common.pymol_png(closeup, width=width, height=height),
+        *visual_common.pymol_save(session),
+        "quit",
+    ])
+    return lines
+
+
+def _chimerax_lines(structure: Path, chain1: str, chain2: str, outdir: Path,
+                    width: int, height: int) -> list[str]:
+    image = (outdir / "interface_chimerax.png").resolve()
+    session = (outdir / "interface_story.cxs").resolve()
+    left = f"(#1/{chain1} & protein)"
+    right = f"(#1/{chain2} & protein)"
+    return [
+        *visual_common.chimerax_base(),
+        f"open {visual_common.quote_chimerax(structure.resolve())}",
+        "cartoon",
+        f"color #1/{chain1} marine",
+        f"color #1/{chain2} salmon",
+        f"measure buriedarea {left} withAtoms2 {right} listResidues true select true color magenta",
+        f"hbonds #1/{chain1} restrict #1/{chain2} reveal true log true",
+        f"contacts #1/{chain1} restrict #1/{chain2} reveal true showDist true log true",
+        f"clashes #1/{chain1} restrict #1/{chain2} reveal true showDist true log true",
+        "show sel atoms",
+        "style sel stick",
+        "view sel",
+        f"save {visual_common.quote_chimerax(image)} width {width} height {height} supersample 3",
+        "wait 1",
+        f"save {visual_common.quote_chimerax(session)}",
+    ]
+
+
+def build_interface_story(structure: str, chains: str, outdir: str, *, cutoff: float = 5.0,
+                          execute: bool = False, width: int = 1300, height: int = 900) -> dict[str, Any]:
+    source = Path(structure).expanduser()
+    if not source.is_file():
+        raise visual_common.VisualWorkflowError(f"Structure not found: {proteus_common.display_path(source)}")
+    parts = [_chain(item.strip()) for item in chains.split(",") if item.strip()]
+    if len(parts) != 2:
+        raise visual_common.VisualWorkflowError("--chains must contain exactly two identifiers, such as A,B.")
+    if cutoff <= 0:
+        raise visual_common.VisualWorkflowError("Cutoff must be positive.")
+    local = interface_report.analyze_interfaces(str(source), cutoff, chains_filter=parts)
+    destination = Path(outdir)
+    destination.mkdir(parents=True, exist_ok=True)
+    data: dict[str, Any] = {
+        "workflow": "interface_story",
+        "structure": proteus_common.display_path(source),
+        "chains": parts,
+        "cutoff_angstrom": cutoff,
+        "local_geometry": local.get("data", {}),
+        "images": {
+            "overview": proteus_common.display_path(destination / "interface_overview.png"),
+            "closeup": proteus_common.display_path(destination / "interface_closeup.png"),
+            "chimerax": proteus_common.display_path(destination / "interface_chimerax.png"),
+        },
+        "sessions": {
+            "pymol": proteus_common.display_path(destination / "interface_story.pse"),
+            "chimerax": proteus_common.display_path(destination / "interface_story.cxs"),
+        },
+        "executed": execute,
+    }
+    report = proteus_common.ok_payload(
+        data,
+        warnings=[
+            "Distance-based contacts are geometric candidates; hydrogen bonding and energetic hotspots require chemical context.",
+            "Buried area excludes solvent, ions, and ligands by explicitly measuring protein atoms only.",
+        ],
+        provenance={"structure": proteus_common.file_provenance(source)},
+    )
+    pml = _pymol_lines(source, parts[0], parts[1], destination, cutoff, width, height)
+    cxc = _chimerax_lines(source, parts[0], parts[1], destination, width, height)
+    data["artifacts"] = visual_common.write_workflow(
+        destination, "interface_story", report=report, pymol_lines=pml, chimerax_lines=cxc,
+    )
+    if execute:
+        analysis_commands = [
+            f"open {visual_common.quote_chimerax(source.resolve())}",
+            f"measure buriedarea (#1/{parts[0]} & protein) withAtoms2 (#1/{parts[1]} & protein) listResidues true",
+            f"hbonds #1/{parts[0]} restrict #1/{parts[1]} log true",
+            f"contacts #1/{parts[0]} restrict #1/{parts[1]} log true",
+            f"clashes #1/{parts[0]} restrict #1/{parts[1]} log true",
+        ]
+        data["chimerax_analysis"] = _analysis_summary(
+            chimerax_agent.run_chimerax_command_list(analysis_commands, timeout=300)
+        )
+        pymol_result = visual_common.run_pymol(destination / "interface_story.pml")
+        chimerax_result = visual_common.run_chimerax(cxc)
+        data["execution"] = {"pymol": pymol_result, "chimerax": chimerax_result}
+        failures = [name for name, result in data["execution"].items() if result.get("status") not in {"ok", "unavailable"}]
+        if failures:
+            report["status"] = "error"
+            report["error"] = f"Interface rendering failed for: {', '.join(failures)}"
+        proteus_common.write_json(destination / "interface_story.json", report)
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Create a protein-interface analysis and publication figure set.")
+    parser.add_argument("structure", help="Local PDB/mmCIF structure")
+    parser.add_argument("--chains", required=True, help="Two chain IDs, e.g. A,D")
+    parser.add_argument("--cutoff", type=float, default=5.0)
+    parser.add_argument("--outdir", default="proteus_interface")
+    parser.add_argument("--execute", action="store_true", help="Run ChimeraX analysis and both renderers")
+    parser.add_argument("--json", action="store_true", help="Emit JSON (accepted for consistency)")
+    args = parser.parse_args(argv)
+    try:
+        report = build_interface_story(args.structure, args.chains, args.outdir, cutoff=args.cutoff,
+                                       execute=args.execute)
+    except (OSError, ValueError, visual_common.VisualWorkflowError) as exc:
+        print(json.dumps(proteus_common.error_payload(str(exc)), indent=2))
+        return 1
+    print(json.dumps(report, indent=2))
+    return 0 if report.get("status") == "ok" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/model_quality.py b/scripts/model_quality.py
index 00b8b1c..9c4ce37 100644
--- a/scripts/model_quality.py
+++ b/scripts/model_quality.py
@@ -12,8 +12,15 @@
 import shutil
 import subprocess
 import sys
+import tempfile
 from pathlib import Path
 
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import proteus_common
+
 
 FLOAT_RE = r"[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[Ee][+-]?\d+)?"
 TOOL_CANDIDATES = {
@@ -43,7 +50,7 @@ def detect_tools() -> dict:
         executable, path = _find_candidate(candidates)
         tools[name] = {
             "available": bool(path),
-            "path": path,
+            "path": proteus_common.display_path(path) if path else None,
             "executable": executable,
             "candidates": candidates,
         }
@@ -125,7 +132,7 @@ def _run_usalign(reference: str, mobile: str, timeout: int) -> dict:
     mobile_path = Path(mobile)
     for path in (reference_path, mobile_path):
         if not path.exists():
-            return _payload("error", {"error": f"File not found: {path}"})
+            return _payload("error", {"error": f"File not found: {proteus_common.display_path(path)}"})
 
     executable, usalign_path = _find_candidate(TOOL_CANDIDATES["usalign"])
     if not usalign_path:
@@ -135,8 +142,8 @@ def _run_usalign(reference: str, mobile: str, timeout: int) -> dict:
                 "tool": "usalign",
                 "available": False,
                 "error": "USalign executable not found on PATH",
-                "reference": str(reference_path),
-                "mobile": str(mobile_path),
+                "reference": proteus_common.display_path(reference_path),
+                "mobile": proteus_common.display_path(mobile_path),
             },
         )
 
@@ -155,11 +162,11 @@ def _run_usalign(reference: str, mobile: str, timeout: int) -> dict:
             {
                 "tool": "usalign",
                 "available": True,
-                "path": usalign_path,
+                "path": proteus_common.display_path(usalign_path),
                 "executable": executable,
                 "error": f"USalign timed out after {timeout} seconds",
-                "stdout": exc.stdout or "",
-                "stderr": exc.stderr or "",
+                "stdout": proteus_common.scrub_text(exc.stdout or ""),
+                "stderr": proteus_common.scrub_text(exc.stderr or ""),
             },
         )
 
@@ -169,12 +176,12 @@ def _run_usalign(reference: str, mobile: str, timeout: int) -> dict:
             {
                 "tool": "usalign",
                 "available": True,
-                "path": usalign_path,
+                "path": proteus_common.display_path(usalign_path),
                 "executable": executable,
                 "returncode": proc.returncode,
                 "error": "USalign exited with a non-zero status",
-                "stdout": proc.stdout,
-                "stderr": proc.stderr,
+                "stdout": proteus_common.scrub_text(proc.stdout),
+                "stderr": proteus_common.scrub_text(proc.stderr),
             },
         )
 
@@ -184,15 +191,110 @@ def _run_usalign(reference: str, mobile: str, timeout: int) -> dict:
         {
             "tool": "usalign",
             "available": True,
-            "path": usalign_path,
+            "path": proteus_common.display_path(usalign_path),
             "executable": executable,
-            "reference": str(reference_path),
-            "mobile": str(mobile_path),
+            "reference": proteus_common.display_path(reference_path),
+            "mobile": proteus_common.display_path(mobile_path),
             "metrics": metrics,
         },
     )
 
 
+def _validated_paths(*values: str) -> tuple[list[Path] | None, dict | None]:
+    paths = [Path(value) for value in values]
+    missing = [proteus_common.display_path(path) for path in paths if not path.exists()]
+    if missing:
+        return None, _payload("error", {"error": f"File or directory not found: {missing[0]}"})
+    return paths, None
+
+
+def _run_dockq(model: str, native: str, timeout: int) -> dict:
+    paths, error = _validated_paths(model, native)
+    if error:
+        return error
+    assert paths is not None
+    executable, dockq_path = _find_candidate(TOOL_CANDIDATES["dockq"])
+    if not dockq_path:
+        return _payload("unavailable", {"tool": "dockq", "available": False, "error": "DockQ executable not found on PATH"})
+    with tempfile.NamedTemporaryFile(suffix=".json") as output:
+        try:
+            proc = subprocess.run(
+                [dockq_path, str(paths[0]), str(paths[1]), "--json", output.name],
+                text=True, capture_output=True, timeout=timeout, check=False,
+            )
+        except subprocess.TimeoutExpired:
+            return _payload("error", {"tool": "dockq", "available": True, "error": f"DockQ timed out after {timeout} seconds"})
+        if proc.returncode != 0:
+            return _payload("error", {
+                "tool": "dockq", "available": True, "returncode": proc.returncode,
+                "error": "DockQ exited with a non-zero status", "stderr": proteus_common.scrub_text(proc.stderr),
+            })
+        try:
+            metrics = json.loads(Path(output.name).read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            return _payload("error", {"tool": "dockq", "available": True, "error": f"DockQ JSON could not be read: {exc}"})
+    return _payload("ok", {
+        "tool": "dockq", "available": True, "path": proteus_common.display_path(dockq_path), "executable": executable,
+        "model": proteus_common.display_path(paths[0]), "native": proteus_common.display_path(paths[1]), "metrics": metrics,
+        "interpretation": "DockQ is interface- and chain-mapping-dependent; review the reported mapping before using the score.",
+    })
+
+
+FOLDSEEK_FIELDS = ["query", "target", "alntmscore", "qtmscore", "ttmscore", "lddt", "evalue", "bits"]
+
+
+def _parse_foldseek_table(text: str) -> list[dict]:
+    results = []
+    numeric = set(FOLDSEEK_FIELDS[2:])
+    for line in text.splitlines():
+        columns = line.split("\t")
+        if len(columns) != len(FOLDSEEK_FIELDS):
+            continue
+        item = dict(zip(FOLDSEEK_FIELDS, columns))
+        for key in numeric:
+            try:
+                item[key] = float(item[key])
+            except ValueError:
+                pass
+        results.append(item)
+    return results
+
+
+def _run_foldseek(query: str, target: str, timeout: int) -> dict:
+    paths, error = _validated_paths(query, target)
+    if error:
+        return error
+    assert paths is not None
+    executable, foldseek_path = _find_candidate(TOOL_CANDIDATES["foldseek"])
+    if not foldseek_path:
+        return _payload("unavailable", {"tool": "foldseek", "available": False, "error": "Foldseek executable not found on PATH"})
+    with tempfile.TemporaryDirectory(prefix="proteus-foldseek-") as temporary:
+        root = Path(temporary)
+        output = root / "results.tsv"
+        work = root / "work"
+        command = [
+            foldseek_path, "easy-search", str(paths[0]), str(paths[1]), str(output), str(work),
+            "--format-output", ",".join(FOLDSEEK_FIELDS),
+        ]
+        try:
+            proc = subprocess.run(command, text=True, capture_output=True, timeout=timeout, check=False)
+        except subprocess.TimeoutExpired:
+            return _payload("error", {"tool": "foldseek", "available": True, "error": f"Foldseek timed out after {timeout} seconds"})
+        if proc.returncode != 0:
+            return _payload("error", {
+                "tool": "foldseek", "available": True, "returncode": proc.returncode,
+                "error": "Foldseek exited with a non-zero status", "stderr": proteus_common.scrub_text(proc.stderr),
+            })
+        if not output.is_file():
+            return _payload("error", {"tool": "foldseek", "available": True, "error": "Foldseek did not create its result table"})
+        hits = _parse_foldseek_table(output.read_text(encoding="utf-8", errors="replace"))
+    return _payload("ok", {
+        "tool": "foldseek", "available": True, "path": proteus_common.display_path(foldseek_path), "executable": executable,
+        "query": proteus_common.display_path(paths[0]), "target": proteus_common.display_path(paths[1]), "hit_count": len(hits), "hits": hits,
+        "interpretation": "TM-score normalization and local/global alignment choices affect comparisons; inspect coverage and both normalized scores.",
+    })
+
+
 def _print_detect_text(report: dict) -> None:
     for name, tool in report["tools"].items():
         value = tool["path"] if tool["available"] else "unavailable"
@@ -224,6 +326,18 @@ def main(argv: list[str] | None = None) -> int:
     usalign_parser.add_argument("--timeout", type=int, default=300, help="USalign timeout in seconds")
     usalign_parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
 
+    dockq_parser = subparsers.add_parser("dockq", help="Run DockQ on a model/native complex pair")
+    dockq_parser.add_argument("model", help="Docked model structure")
+    dockq_parser.add_argument("native", help="Native/reference complex")
+    dockq_parser.add_argument("--timeout", type=int, default=600)
+    dockq_parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
+
+    foldseek_parser = subparsers.add_parser("foldseek", help="Run a local Foldseek easy-search")
+    foldseek_parser.add_argument("query", help="Query structure file or directory")
+    foldseek_parser.add_argument("target", help="Target structure file, directory, or database")
+    foldseek_parser.add_argument("--timeout", type=int, default=1200)
+    foldseek_parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
+
     args = parser.parse_args(argv)
     if args.command == "detect":
         report = detect_tools()
@@ -241,6 +355,16 @@ def main(argv: list[str] | None = None) -> int:
             _print_usalign_text(report)
         return 1 if report["status"] == "error" else 0
 
+    if args.command == "dockq":
+        report = _run_dockq(args.model, args.native, args.timeout)
+        print(json.dumps(report, indent=2))
+        return 1 if report["status"] == "error" else 0
+
+    if args.command == "foldseek":
+        report = _run_foldseek(args.query, args.target, args.timeout)
+        print(json.dumps(report, indent=2))
+        return 1 if report["status"] == "error" else 0
+
     parser.error(f"unknown command: {args.command}")
     return 2
 
diff --git a/scripts/pae_report.py b/scripts/pae_report.py
index c0a1b7c..d294611 100644
--- a/scripts/pae_report.py
+++ b/scripts/pae_report.py
@@ -11,6 +11,12 @@
 import sys
 from pathlib import Path
 
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import proteus_common
+
 
 def _error_payload(message: str) -> dict:
     return {"status": "error", "error": message}
@@ -84,8 +90,62 @@ def _segments(values: list[float], threshold: float, min_len: int, high: bool) -
     return segments
 
 
+def _parse_chain_lengths(value: str | None) -> list[tuple[str, int]]:
+    if not value:
+        return []
+    output = []
+    for index, item in enumerate(value.split(","), start=1):
+        item = item.strip()
+        if not item:
+            continue
+        if ":" in item:
+            chain, length_text = item.rsplit(":", 1)
+        else:
+            chain, length_text = f"chain_{index}", item
+        try:
+            length = int(length_text)
+        except ValueError as exc:
+            raise ValueError("Chain lengths must look like A:120,B:95 or 120,95.") from exc
+        if not chain or length <= 0:
+            raise ValueError("Chain names must be non-empty and lengths must be positive.")
+        output.append((chain, length))
+    return output
+
+
+def _chain_blocks(matrix: list[list[float]], chain_lengths: list[tuple[str, int]]) -> dict:
+    if not chain_lengths:
+        return {}
+    size = len(matrix)
+    if len(matrix[0]) != size:
+        raise ValueError("Chain-aware PAE analysis requires a square matrix.")
+    if sum(length for _chain, length in chain_lengths) != size:
+        raise ValueError("Chain lengths must sum to the PAE matrix size.")
+    ranges = []
+    start = 0
+    for chain, length in chain_lengths:
+        ranges.append((chain, start, start + length))
+        start += length
+    blocks = []
+    for row_chain, row_start, row_end in ranges:
+        for column_chain, column_start, column_end in ranges:
+            values = [matrix[row][column] for row in range(row_start, row_end) for column in range(column_start, column_end)]
+            blocks.append({
+                "row_chain": row_chain,
+                "column_chain": column_chain,
+                "kind": "within_chain" if row_chain == column_chain else "between_chain",
+                "mean_pae": round(sum(values) / len(values), 2),
+                "min_pae": round(min(values), 2),
+                "max_pae": round(max(values), 2),
+            })
+    residue_map = []
+    for chain, chain_start, chain_end in ranges:
+        for index in range(chain_start, chain_end):
+            residue_map.append({"index": index + 1, "chain": chain, "chain_index": index - chain_start + 1})
+    return {"chains": [{"chain": chain, "length": end - start} for chain, start, end in ranges], "blocks": blocks, "residue_map": residue_map}
+
+
 def summarize_pae(path: str, flex_threshold: float = 15.0, rigid_threshold: float = 5.0,
-                  min_segment: int = 5) -> dict:
+                  min_segment: int = 5, chain_lengths: str | None = None) -> dict:
     payload = json.loads(Path(path).read_text())
     matrix = _validate_matrix(_matrix_from_payload(payload))
     row_count = len(matrix)
@@ -93,7 +153,7 @@ def summarize_pae(path: str, flex_threshold: float = 15.0, rigid_threshold: floa
     flat = [value for row in matrix for value in row]
     per_residue_mean = [sum(row) / len(row) for row in matrix]
     data = {
-        "file": str(Path(path).resolve()),
+        "file": proteus_common.display_path(path),
         "size": {"rows": row_count, "columns": col_count},
         "pae": {
             "min": round(min(flat), 2),
@@ -109,10 +169,13 @@ def summarize_pae(path: str, flex_threshold: float = 15.0, rigid_threshold: floa
         "rigid_candidate_regions": _segments(per_residue_mean, rigid_threshold, min_segment, high=False),
         "per_residue_mean_pae": [round(value, 2) for value in per_residue_mean],
     }
+    parsed_chains = _parse_chain_lengths(chain_lengths)
+    if parsed_chains:
+        data["chain_analysis"] = _chain_blocks(matrix, parsed_chains)
     return _ok_payload(data)
 
 
-def main():
+def main(argv: list[str] | None = None):
     parser = argparse.ArgumentParser(description="Summarize AlphaFold PAE JSON into domain/flexibility hints.")
     parser.add_argument("pae_json", help="Path to PAE JSON")
     parser.add_argument("--flex-threshold", type=float, default=15.0,
@@ -121,11 +184,13 @@ def main():
                         help="Mean PAE threshold for rigid candidate regions (default: 5)")
     parser.add_argument("--min-segment", type=int, default=5,
                         help="Minimum contiguous segment length (default: 5)")
+    parser.add_argument("--chain-lengths", help="Chain names and lengths, e.g. A:120,B:95")
     parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
-    args = parser.parse_args()
+    args = parser.parse_args(argv)
 
     try:
-        output = summarize_pae(args.pae_json, args.flex_threshold, args.rigid_threshold, args.min_segment)
+        output = summarize_pae(args.pae_json, args.flex_threshold, args.rigid_threshold,
+                               args.min_segment, args.chain_lengths)
     except (OSError, ValueError, json.JSONDecodeError) as exc:
         if args.json:
             print(json.dumps(_error_payload(str(exc)), indent=2))
diff --git a/scripts/pocket_tunnel.py b/scripts/pocket_tunnel.py
new file mode 100644
index 0000000..e2cf2a5
--- /dev/null
+++ b/scripts/pocket_tunnel.py
@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+"""Run optional pocket detection and prepare PyMOL/ChimeraX review artifacts."""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import proteus_common
+import visual_common
+
+
+def _copy_matches(root: Path, pattern: str, destination: Path) -> list[Path]:
+    destination.mkdir(parents=True, exist_ok=True)
+    output = []
+    for index, source in enumerate(sorted(root.rglob(pattern)), start=1):
+        target = destination / f"pocket_{index}{source.suffix.lower()}"
+        shutil.copy2(source, target)
+        output.append(target)
+    return output
+
+
+def _run_fpocket(executable: str, structure: Path, destination: Path) -> tuple[dict[str, Any], list[Path]]:
+    if structure.suffix.lower() not in {".pdb", ".ent"}:
+        return {"status": "error", "error": "fpocket execution requires a PDB-format input."}, []
+    with tempfile.TemporaryDirectory(prefix="proteus-fpocket-") as temporary:
+        workdir = Path(temporary)
+        local = workdir / "input.pdb"
+        shutil.copy2(structure, local)
+        result = proteus_common.run_command([executable, "-f", local.name], cwd=workdir, timeout=900)
+        pockets = _copy_matches(workdir, "pocket*_atm.pdb", destination / "pockets") if result["status"] == "ok" else []
+    result.pop("stdout", None)
+    result.pop("stderr", None)
+    result["pockets_found"] = len(pockets)
+    return result, pockets
+
+
+def _run_p2rank(executable: str, structure: Path, destination: Path) -> tuple[dict[str, Any], list[Path], list[dict[str, str]]]:
+    workdir = destination / "p2rank"
+    workdir.mkdir(parents=True, exist_ok=True)
+    result = proteus_common.run_command(
+        [executable, "predict", "-f", str(structure.resolve()), "-o", str(workdir.resolve())],
+        timeout=1200,
+    )
+    result.pop("stdout", None)
+    result.pop("stderr", None)
+    pockets = _copy_matches(workdir, "*.pdb", destination / "pockets") if result["status"] == "ok" else []
+    predictions: list[dict[str, str]] = []
+    for table in sorted(workdir.rglob("*predictions*.csv")):
+        try:
+            with table.open(newline="", encoding="utf-8-sig") as handle:
+                predictions.extend(dict(row) for row in csv.DictReader(handle))
+        except (OSError, csv.Error):
+            continue
+    result["pocket_files_found"] = len(pockets)
+    result["prediction_rows"] = len(predictions)
+    return result, pockets, predictions
+
+
+def _scripts(structure: Path, pockets: list[Path], destination: Path,
+             width: int, height: int) -> tuple[list[str], list[str]]:
+    pml = visual_common.pymol_base(width=width, height=height)
+    pml.extend([
+        f"load {visual_common.quote_pymol(structure.resolve())}, structure",
+        "hide everything, all",
+        "show cartoon, structure and polymer",
+        "color gray80, structure and polymer",
+    ])
+    cxc = [
+        *visual_common.chimerax_base(),
+        f"open {visual_common.quote_chimerax(structure.resolve())}",
+        "cartoon #1",
+        "color #1 lightgray",
+    ]
+    for index, pocket in enumerate(pockets, start=1):
+        pml.extend([
+            f"load {visual_common.quote_pymol(pocket.resolve())}, pocket_{index}",
+            f"show spheres, pocket_{index}",
+            f"set sphere_scale, 0.35, pocket_{index}",
+            f"color tv_orange, pocket_{index}",
+            f"select pocket_{index}_lining, byres (structure and polymer within 4.5 of pocket_{index})",
+            f"show sticks, pocket_{index}_lining",
+        ])
+        cxc.extend([
+            f"open {visual_common.quote_chimerax(pocket.resolve())}",
+            f"style #{index + 1} sphere",
+            f"color #{index + 1} orange",
+            f"select zone #{index + 1} 4.5 residues true",
+            "show sel atoms",
+            "style sel stick",
+        ])
+    pml.extend(visual_common.finalize_pymol(
+        destination / "pockets.png", width=width, height=height,
+        session=destination / "pockets.pse",
+    ))
+    cxc.extend(visual_common.finalize_chimerax(
+        destination / "pockets_chimerax.png", width=width, height=height,
+        session=destination / "pockets.cxs",
+    ))
+    return pml, cxc
+
+
+def pocket_tunnel_workflow(structure: str, outdir: str, *, detector: str = "auto",
+                           execute: bool = False, render: bool = False,
+                           width: int = 1300, height: int = 900) -> dict[str, Any]:
+    source = Path(structure).expanduser()
+    if not source.is_file():
+        raise visual_common.VisualWorkflowError(f"Structure not found: {proteus_common.display_path(source)}")
+    fpocket = proteus_common.find_executable("fpocket")
+    p2rank = proteus_common.find_executable("prank", "p2rank")
+    tunnel_tools = {
+        "caver": bool(proteus_common.find_executable("caver")),
+        "hole": bool(proteus_common.find_executable("hole")),
+    }
+    if detector not in {"auto", "fpocket", "p2rank", "none"}:
+        raise visual_common.VisualWorkflowError("Detector must be auto, fpocket, p2rank, or none.")
+    selected = detector
+    if detector == "auto":
+        selected = "fpocket" if fpocket else "p2rank" if p2rank else "none"
+    executable = fpocket if selected == "fpocket" else p2rank if selected == "p2rank" else None
+    if execute and selected != "none" and not executable:
+        raise visual_common.VisualWorkflowError(f"Requested detector is not installed: {selected}")
+
+    destination = Path(outdir)
+    destination.mkdir(parents=True, exist_ok=True)
+    detector_result: dict[str, Any] | None = None
+    pockets: list[Path] = []
+    predictions: list[dict[str, str]] = []
+    if execute and selected == "fpocket" and executable:
+        detector_result, pockets = _run_fpocket(executable, source, destination)
+    elif execute and selected == "p2rank" and executable:
+        detector_result, pockets, predictions = _run_p2rank(executable, source, destination)
+
+    pml, cxc = _scripts(source, pockets, destination, width, height)
+    warnings = [
+        "Predicted pockets and tunnels are geometric hypotheses; prioritize sites using experimental, evolutionary, and chemical evidence.",
+        "Tool scores are not binding-affinity estimates and are not directly comparable across detectors.",
+        "Tunnel results depend on probe radius, starting point, conformational state, and treatment of waters or ligands.",
+    ]
+    if selected == "none":
+        warnings.append("No supported pocket detector was found; install fpocket or P2Rank, or choose a detector explicitly.")
+    data: dict[str, Any] = {
+        "workflow": "pocket_tunnel",
+        "structure": proteus_common.display_path(source),
+        "detector": selected,
+        "availability": {
+            "fpocket": bool(fpocket),
+            "p2rank": bool(p2rank),
+            "tunnel_tools": tunnel_tools,
+        },
+        "detector_execution": detector_result,
+        "pockets": [proteus_common.display_path(item) for item in pockets],
+        "predictions": predictions,
+        "render_requested": render,
+        "executed": execute,
+    }
+    report = proteus_common.ok_payload(
+        data, warnings=warnings, provenance={"structure": proteus_common.file_provenance(source)},
+    )
+    data["artifacts"] = visual_common.write_workflow(
+        destination, "pocket_tunnel", report=report, pymol_lines=pml, chimerax_lines=cxc,
+    )
+    if execute and detector_result and detector_result.get("status") != "ok":
+        report["status"] = "error"
+        report["error"] = f"{selected} pocket detection failed."
+    if render:
+        data["rendering"] = {
+            "pymol": visual_common.run_pymol(destination / "pocket_tunnel.pml"),
+            "chimerax": visual_common.run_chimerax(cxc),
+        }
+        failures = [name for name, result in data["rendering"].items() if result.get("status") not in {"ok", "unavailable"}]
+        if failures:
+            report["status"] = "error"
+            report["error"] = f"Pocket rendering failed for: {', '.join(failures)}"
+    proteus_common.write_json(destination / "pocket_tunnel.json", report)
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Run fpocket/P2Rank when available and prepare pocket-review sessions.")
+    parser.add_argument("structure")
+    parser.add_argument("--detector", default="auto", choices=["auto", "fpocket", "p2rank", "none"])
+    parser.add_argument("--execute", action="store_true", help="Run the selected pocket detector")
+    parser.add_argument("--render", action="store_true", help="Render generated PyMOL and ChimeraX review artifacts")
+    parser.add_argument("--outdir", default="proteus_pockets")
+    parser.add_argument("--json", action="store_true", help="Emit JSON (accepted for consistency)")
+    args = parser.parse_args(argv)
+    try:
+        report = pocket_tunnel_workflow(
+            args.structure, args.outdir, detector=args.detector, execute=args.execute, render=args.render,
+        )
+    except (OSError, ValueError, visual_common.VisualWorkflowError) as exc:
+        print(json.dumps(proteus_common.error_payload(str(exc)), indent=2))
+        return 1
+    print(json.dumps(report, indent=2))
+    return 0 if report.get("status") == "ok" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/proteus.py b/scripts/proteus.py
new file mode 100644
index 0000000..f7bb30a
--- /dev/null
+++ b/scripts/proteus.py
@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""Unified entry point for Proteus user workflows."""
+
+from __future__ import annotations
+
+import importlib
+import sys
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import proteus_common
+
+
+COMMANDS = {
+    "annotate": ("annotation_figure", "Map residue annotations and scores onto figures"),
+    "assembly": ("assembly_explorer", "Compare asymmetric unit, biological assembly, and crystal neighbors"),
+    "chemical-site": ("chemical_site", "Inspect a ligand, cofactor, metal, or water network"),
+    "compare": ("state_compare", "Create aligned state-comparison figures and contact changes"),
+    "cryoem": ("cryoem_workflow", "Inspect and render a map/model pair"),
+    "electrostatics": ("electrostatics_workflow", "Create a Coulombic surface workflow"),
+    "ensemble": ("ensemble_report", "Analyze multi-model structural variability"),
+    "figure": ("scene_figure", "Compile a declarative PyMOL or ChimeraX scene"),
+    "interface": ("interface_story", "Analyze and render a protein-protein interface"),
+    "pockets": ("pocket_tunnel", "Run optional pocket detection and render candidates"),
+    "qc": ("structure_qc", "Preflight coordinate models, conformers, occupancy, and components"),
+    "residue": ("residue_story", "Build a residue- or variant-centered structural story"),
+    "restraints": ("restraint_report", "Evaluate and render residue-pair distance restraints"),
+}
+
+
+def _help() -> str:
+    rows = [
+        "Proteus structural-biology workflows",
+        "",
+        "Usage: python3 scripts/proteus.py <command> [arguments]",
+        "",
+        "Commands:",
+    ]
+    width = max(len(command) for command in COMMANDS)
+    rows.extend(f"  {command:<{width}}  {description}" for command, (_module, description) in sorted(COMMANDS.items()))
+    rows.extend(["", "Run '<command> --help' for workflow-specific options."])
+    return "\n".join(rows)
+
+
+def main(argv: list[str] | None = None) -> int:
+    arguments = list(sys.argv[1:] if argv is None else argv)
+    if not arguments or arguments[0] in {"-h", "--help", "help"}:
+        print(_help())
+        return 0
+    if arguments[0] in {"-V", "--version"}:
+        print(proteus_common.PROTEUS_VERSION)
+        return 0
+    command = arguments.pop(0)
+    target = COMMANDS.get(command)
+    if target is None:
+        print(f"Unknown workflow: {command}\n\n{_help()}", file=sys.stderr)
+        return 2
+    module = importlib.import_module(target[0])
+    return int(module.main(arguments) or 0)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/proteus_batch.py b/scripts/proteus_batch.py
index 4b5f8ed..3a311e0 100644
--- a/scripts/proteus_batch.py
+++ b/scripts/proteus_batch.py
@@ -22,6 +22,18 @@
     "mutation_triage": "scripts/mutation_triage.py",
     "validation_report": "scripts/validation_report.py",
     "resolve_structure": "scripts/resolve_structure.py",
+    "structure_qc": "scripts/structure_qc.py",
+    "state_compare": "scripts/state_compare.py",
+    "residue_story": "scripts/residue_story.py",
+    "interface_story": "scripts/interface_story.py",
+    "annotation_figure": "scripts/annotation_figure.py",
+    "restraint_report": "scripts/restraint_report.py",
+    "assembly_explorer": "scripts/assembly_explorer.py",
+    "cryoem_workflow": "scripts/cryoem_workflow.py",
+    "ensemble_report": "scripts/ensemble_report.py",
+    "electrostatics_workflow": "scripts/electrostatics_workflow.py",
+    "pocket_tunnel": "scripts/pocket_tunnel.py",
+    "chemical_site": "scripts/chemical_site.py",
 }
 ITEM_ID_RE = re.compile(r"^[A-Za-z0-9_.-]+$")
 MAX_CAPTURE_CHARS = 20000
@@ -135,6 +147,17 @@ def build_command(task_spec, item_input: str, item_outdir: Path) -> list[str]:
         "interaction_report",
         "resolve_structure",
         "assembly_report",
+        "state_compare",
+        "residue_story",
+        "interface_story",
+        "annotation_figure",
+        "restraint_report",
+        "assembly_explorer",
+        "cryoem_workflow",
+        "ensemble_report",
+        "electrostatics_workflow",
+        "pocket_tunnel",
+        "chemical_site",
     } and not _has_option(extra_args, "--outdir"):
         command.extend(["--outdir", str(item_outdir)])
     if task != "mutation_triage":
diff --git a/scripts/proteus_common.py b/scripts/proteus_common.py
new file mode 100644
index 0000000..5d641ab
--- /dev/null
+++ b/scripts/proteus_common.py
@@ -0,0 +1,345 @@
+#!/usr/bin/env python3
+"""Shared runtime helpers for Proteus command-line workflows.
+
+Keep this module dependency-free. It centralizes result envelopes, privacy-safe
+path labels, checksums, executable discovery, subprocess handling, and resilient
+HTTP access so workflow scripts do not each invent subtly different behavior.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import platform
+import re
+import shutil
+import subprocess
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from email.utils import parsedate_to_datetime
+from pathlib import Path
+from typing import Any
+
+
+SCHEMA_VERSION = 1
+PROTEUS_VERSION = "0.2.0"
+USER_AGENT = f"proteus/{PROTEUS_VERSION}"
+TRANSIENT_HTTP_CODES = {408, 425, 429, 500, 502, 503, 504}
+SECRET_QUERY_NAMES = {
+    "access_token", "api_key", "apikey", "auth", "authorization", "key",
+    "password", "secret", "sig", "signature", "token",
+}
+ABSOLUTE_PATH_RE = re.compile(r"(?<![:A-Za-z0-9_./~$-])/(?!/)[^\s\"'`;]+")
+
+
+class ProteusRuntimeError(RuntimeError):
+    """Base error for shared Proteus runtime failures."""
+
+
+@dataclass(frozen=True)
+class HttpResult:
+    body: bytes
+    url: str
+    status: int
+    headers: dict[str, str]
+    cached: bool = False
+    attempts: int = 1
+
+
+def display_path(value: str | Path, *, roots: list[Path] | None = None) -> str:
+    """Return a useful path label without leaking an arbitrary absolute path."""
+    candidate = Path(value).expanduser()
+    try:
+        resolved = candidate.resolve(strict=False)
+    except OSError:
+        resolved = candidate.absolute()
+
+    search_roots = list(roots or [])
+    search_roots.extend([Path.cwd(), Path.home()])
+    seen: set[str] = set()
+    for root in search_roots:
+        try:
+            resolved_root = root.expanduser().resolve(strict=False)
+        except OSError:
+            continue
+        marker = str(resolved_root)
+        if marker in seen:
+            continue
+        seen.add(marker)
+        try:
+            relative = resolved.relative_to(resolved_root)
+        except ValueError:
+            continue
+        if resolved_root == Path.home().resolve(strict=False):
+            return f"~/{relative}" if str(relative) != "." else "~"
+        return f"./{relative}" if str(relative) != "." else "."
+    return f"{resolved.name or 'path'} (absolute path omitted)"
+
+
+def sha256_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def sha256_file(path: str | Path, chunk_size: int = 1024 * 1024) -> str:
+    digest = hashlib.sha256()
+    with Path(path).open("rb") as handle:
+        while chunk := handle.read(chunk_size):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def file_provenance(path: str | Path, *, kind: str = "local_file") -> dict[str, Any]:
+    candidate = Path(path)
+    data: dict[str, Any] = {"kind": kind, "path": display_path(candidate)}
+    if candidate.is_file():
+        data.update({"bytes": candidate.stat().st_size, "sha256": sha256_file(candidate)})
+    return data
+
+
+def scrub_text(value: str | bytes) -> str:
+    """Remove arbitrary absolute local paths from captured tool output."""
+    text = value.decode("utf-8", errors="replace") if isinstance(value, bytes) else value
+    replacements = [(str(Path.cwd().resolve()), "."), (str(Path.home().resolve()), "~")]
+    for source, label in sorted(replacements, key=lambda item: len(item[0]), reverse=True):
+        text = text.replace(source, label)
+
+    def replace(match: re.Match[str]) -> str:
+        token = match.group(0)
+        suffix = ""
+        while token and token[-1] in ".,:)]}":
+            suffix = token[-1] + suffix
+            token = token[:-1]
+        return display_path(token) + suffix if token else match.group(0)
+
+    return ABSOLUTE_PATH_RE.sub(replace, text)
+
+
+def scrub_private(value: Any) -> Any:
+    """Recursively scrub absolute paths from JSON-safe execution metadata."""
+    if isinstance(value, dict):
+        return {str(key): scrub_private(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [scrub_private(item) for item in value]
+    if isinstance(value, tuple):
+        return [scrub_private(item) for item in value]
+    if isinstance(value, str):
+        return scrub_text(value)
+    return value
+
+
+def ok_payload(
+    data: dict[str, Any],
+    *,
+    warnings: list[str] | None = None,
+    provenance: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    output: dict[str, Any] = {
+        "schema_version": SCHEMA_VERSION,
+        "proteus_version": PROTEUS_VERSION,
+        "status": "ok",
+        "data": data,
+    }
+    if warnings:
+        output["warnings"] = list(dict.fromkeys(warnings))
+    if provenance:
+        output["provenance"] = provenance
+    return output
+
+
+def error_payload(message: str, *, code: str | None = None) -> dict[str, Any]:
+    output: dict[str, Any] = {
+        "schema_version": SCHEMA_VERSION,
+        "proteus_version": PROTEUS_VERSION,
+        "status": "error",
+        "error": message,
+    }
+    if code:
+        output["code"] = code
+    return output
+
+
+def write_json(path: str | Path, value: Any) -> Path:
+    destination = Path(path)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    destination.write_text(json.dumps(value, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return destination
+
+
+def slug(value: str, default: str = "workflow") -> str:
+    normalized = re.sub(r"[^a-z0-9]+", "-", value.strip().lower()).strip("-")
+    return normalized or default
+
+
+def find_executable(*candidates: str) -> str | None:
+    for candidate in candidates:
+        if not candidate:
+            continue
+        path = shutil.which(candidate)
+        if path:
+            return path
+        expanded = Path(candidate).expanduser()
+        if expanded.is_file() and os.access(expanded, os.X_OK):
+            return str(expanded)
+    return None
+
+
+def runtime_metadata() -> dict[str, Any]:
+    return {
+        "python": platform.python_version(),
+        "platform": platform.system(),
+        "machine": platform.machine(),
+    }
+
+
+def run_command(
+    command: list[str],
+    *,
+    timeout: int = 300,
+    cwd: str | Path | None = None,
+    env: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    """Run an argv command without a shell and return a JSON-safe record."""
+    try:
+        proc = subprocess.run(
+            command,
+            cwd=str(cwd) if cwd is not None else None,
+            env=env,
+            text=True,
+            capture_output=True,
+            timeout=timeout,
+            check=False,
+        )
+    except subprocess.TimeoutExpired as exc:
+        return {
+            "status": "error",
+            "error": f"Command timed out after {timeout} seconds.",
+            "returncode": None,
+            "stdout": scrub_text(exc.stdout or ""),
+            "stderr": scrub_text(exc.stderr or ""),
+        }
+    except OSError as exc:
+        return {"status": "error", "error": scrub_text(str(exc)), "returncode": None, "stdout": "", "stderr": ""}
+    return {
+        "status": "ok" if proc.returncode == 0 else "error",
+        "returncode": proc.returncode,
+        "stdout": proc.stdout,
+        "stderr": proc.stderr,
+    }
+
+
+def _safe_url(url: str) -> str:
+    from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+
+    parsed = urlsplit(url)
+    if parsed.scheme not in {"https", "http"}:
+        raise ProteusRuntimeError("Only HTTP(S) URLs are supported.")
+    if parsed.username or parsed.password:
+        raise ProteusRuntimeError("Credential-bearing URLs are not allowed.")
+    for name, _value in parse_qsl(parsed.query, keep_blank_values=True):
+        if name.lower() in SECRET_QUERY_NAMES:
+            raise ProteusRuntimeError(f"Secret-like URL query parameter is not allowed: {name}")
+    return urlunsplit((parsed.scheme, parsed.netloc, parsed.path, urlencode(parse_qsl(parsed.query, keep_blank_values=True)), ""))
+
+
+def _retry_delay(headers: Any, attempt: int, backoff: float) -> float:
+    value = headers.get("Retry-After") if headers is not None else None
+    if value:
+        try:
+            return max(0.0, min(float(value), 30.0))
+        except ValueError:
+            try:
+                target = parsedate_to_datetime(value).timestamp()
+                return max(0.0, min(target - time.time(), 30.0))
+            except (TypeError, ValueError, OverflowError):
+                pass
+    return min(backoff * (2 ** max(0, attempt - 1)), 30.0)
+
+
+def _cache_paths(cache_dir: str | Path, url: str) -> tuple[Path, Path]:
+    root = Path(cache_dir).expanduser()
+    key = sha256_bytes(url.encode("utf-8"))
+    return root / f"{key}.body", root / f"{key}.json"
+
+
+def request_bytes(
+    url: str,
+    *,
+    method: str = "GET",
+    data: bytes | None = None,
+    headers: dict[str, str] | None = None,
+    timeout: int = 30,
+    retries: int = 3,
+    backoff: float = 1.0,
+    cache_dir: str | Path | None = None,
+    offline: bool = False,
+) -> HttpResult:
+    safe_url = _safe_url(url)
+    body_path: Path | None = None
+    meta_path: Path | None = None
+    if cache_dir is not None:
+        body_path, meta_path = _cache_paths(cache_dir, safe_url)
+        if body_path.is_file() and meta_path.is_file():
+            metadata = json.loads(meta_path.read_text(encoding="utf-8"))
+            body = body_path.read_bytes()
+            if metadata.get("sha256") == sha256_bytes(body):
+                return HttpResult(
+                    body=body,
+                    url=safe_url,
+                    status=int(metadata.get("status", 200)),
+                    headers=dict(metadata.get("headers") or {}),
+                    cached=True,
+                    attempts=0,
+                )
+        if offline:
+            raise ProteusRuntimeError("Offline mode requested and no valid cached response exists.")
+    elif offline:
+        raise ProteusRuntimeError("Offline mode requires a cache directory.")
+
+    request_headers = {"User-Agent": USER_AGENT, **(headers or {})}
+    attempts = max(1, retries + 1)
+    last_error: Exception | None = None
+    for attempt in range(1, attempts + 1):
+        request = urllib.request.Request(safe_url, data=data, headers=request_headers, method=method)
+        try:
+            with urllib.request.urlopen(request, timeout=timeout) as response:
+                body = response.read()
+                result = HttpResult(
+                    body=body,
+                    url=response.geturl(),
+                    status=int(getattr(response, "status", 200)),
+                    headers=dict(response.headers.items()),
+                    attempts=attempt,
+                )
+                if body_path is not None and meta_path is not None:
+                    body_path.parent.mkdir(parents=True, exist_ok=True)
+                    body_path.write_bytes(body)
+                    write_json(meta_path, {
+                        "url": safe_url,
+                        "status": result.status,
+                        "headers": result.headers,
+                        "sha256": sha256_bytes(body),
+                        "fetched_at": int(time.time()),
+                    })
+                return result
+        except urllib.error.HTTPError as exc:
+            last_error = exc
+            if exc.code not in TRANSIENT_HTTP_CODES or attempt >= attempts:
+                raise ProteusRuntimeError(f"HTTP {exc.code} for {safe_url}: {exc.reason}") from exc
+            time.sleep(_retry_delay(exc.headers, attempt, backoff))
+        except (urllib.error.URLError, TimeoutError, OSError) as exc:
+            last_error = exc
+            if attempt >= attempts:
+                raise ProteusRuntimeError(f"Request failed for {safe_url}: {exc}") from exc
+            time.sleep(_retry_delay(None, attempt, backoff))
+    raise ProteusRuntimeError(f"Request failed for {safe_url}: {last_error}")
+
+
+def request_json(url: str, **kwargs: Any) -> tuple[Any, HttpResult]:
+    result = request_bytes(url, **kwargs)
+    try:
+        return json.loads(result.body), result
+    except json.JSONDecodeError as exc:
+        raise ProteusRuntimeError(f"Response from {result.url} was not valid JSON: {exc}") from exc
diff --git a/scripts/proteus_doctor.py b/scripts/proteus_doctor.py
index ff5d0c2..3fd0324 100644
--- a/scripts/proteus_doctor.py
+++ b/scripts/proteus_doctor.py
@@ -149,6 +149,21 @@ def _script_smoke() -> dict:
         "design_run.py",
         "rosetta_score.py",
         "kras_dossier.py",
+        "proteus.py",
+        "structure_qc.py",
+        "scene_figure.py",
+        "state_compare.py",
+        "residue_story.py",
+        "interface_story.py",
+        "annotation_figure.py",
+        "restraint_report.py",
+        "assembly_explorer.py",
+        "cryoem_workflow.py",
+        "ensemble_report.py",
+        "electrostatics_workflow.py",
+        "pocket_tunnel.py",
+        "chemical_site.py",
+        "sync_skill_package.py",
     ]
     if sys.version_info < (3, 10):
         return {
@@ -179,6 +194,15 @@ def build_report(include_network: bool) -> dict:
     pymol = _find_pymol()
     chimerax = _find_chimerax()
     ffmpeg = shutil.which("ffmpeg")
+    optional = {
+        "apbs": shutil.which("apbs"),
+        "pdb2pqr": shutil.which("pdb2pqr") or shutil.which("pdb2pqr30"),
+        "fpocket": shutil.which("fpocket"),
+        "p2rank": shutil.which("prank") or shutil.which("p2rank"),
+        "usalign": shutil.which("USalign") or shutil.which("usalign"),
+        "dockq": shutil.which("DockQ") or shutil.which("dockq"),
+        "foldseek": shutil.which("foldseek"),
+    }
     network = None
     if include_network:
         network = {name: _network_check(url) for name, url in NETWORK_ENDPOINTS.items()}
@@ -190,6 +214,10 @@ def build_report(include_network: bool) -> dict:
         "pymol_rendering": bool(pymol),
         "chimerax_analysis": bool(chimerax),
         "turntable_movies": bool((pymol or chimerax) and ffmpeg),
+        "pocket_detection": bool(optional["fpocket"] or optional["p2rank"]),
+        "poisson_boltzmann_electrostatics": bool(optional["apbs"] and optional["pdb2pqr"]),
+        "local_structure_search": bool(optional["foldseek"]),
+        "complex_quality_scoring": bool(optional["dockq"]),
     }
     if network is not None:
         for capability, check_name in NETWORK_CAPABILITIES.items():
@@ -205,6 +233,10 @@ def build_report(include_network: bool) -> dict:
             "pymol": {"ok": bool(pymol), "path": _display_path(pymol)},
             "chimerax": {"ok": bool(chimerax), "path": _display_path(chimerax)},
             "ffmpeg": {"ok": bool(ffmpeg), "path": _display_path(ffmpeg)},
+            **{
+                name: {"ok": bool(path), "path": _display_path(path)}
+                for name, path in optional.items()
+            },
         },
         "scripts": _script_smoke(),
         "network": network,
diff --git a/scripts/residue_story.py b/scripts/residue_story.py
new file mode 100644
index 0000000..cea8bba
--- /dev/null
+++ b/scripts/residue_story.py
@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""Turn a residue or substitution into a local structural evidence story."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import interface_report
+import mutation_triage
+import pocket_report
+import proteus_common
+import visual_common
+
+
+VARIANT_RE = re.compile(r"^(?:[A-Za-z0-9_.-]+\s+)?(?:p\.)?[A-Za-z]{1,3}\d+[A-Za-z]{1,3}$", re.IGNORECASE)
+RESIDUE_RE = re.compile(r"^(?:(?P<chain>[A-Za-z0-9]+):)?(?P<resi>-?\d+[A-Za-z]?)$")
+
+
+def _focus(focus: str, chain: str | None) -> dict[str, Any]:
+    text = focus.strip()
+    if chain is not None and not re.fullmatch(r"[A-Za-z0-9]+", chain):
+        raise visual_common.VisualWorkflowError("Chain identifiers must be alphanumeric.")
+    if VARIANT_RE.fullmatch(text):
+        match = re.search(r"(\d+)", text)
+        if match is None:
+            raise visual_common.VisualWorkflowError("Could not parse variant residue number.")
+        return {"kind": "variant", "value": text, "resi": match.group(1), "chain": chain}
+    match = RESIDUE_RE.fullmatch(text)
+    if not match:
+        raise visual_common.VisualWorkflowError("Focus must be a substitution such as R175H or residue such as A:175.")
+    return {"kind": "residue", "value": text, "resi": match.group("resi"), "chain": chain or match.group("chain")}
+
+
+def _selection(parsed: dict[str, Any]) -> str:
+    base = f"resi {parsed['resi']}"
+    if parsed.get("chain"):
+        base = f"chain {parsed['chain']} and {base}"
+    return base
+
+
+def _pymol_lines(structure: Path, parsed: dict[str, Any], outdir: Path,
+                  cutoff: float, width: int, height: int) -> list[str]:
+    focus = _selection(parsed)
+    global_png = (outdir / "residue_context.png").resolve()
+    local_png = (outdir / "residue_local.png").resolve()
+    session = (outdir / "residue_story.pse").resolve()
+    lines = visual_common.pymol_base(width=width, height=height)
+    lines.extend([
+        f"load {visual_common.quote_pymol(structure.resolve())}, structure",
+        "hide everything, all",
+        "show cartoon, polymer",
+        "color gray80, polymer",
+        f"select focus, structure and ({focus})",
+        f"select neighborhood, byres (structure within {cutoff:.2f} of focus)",
+        f"select nearby_ligands, (organic or inorganic) within {cutoff:.2f} of focus",
+        "show sticks, focus or neighborhood or nearby_ligands",
+        "color magenta, focus",
+        "color cyan, neighborhood and not focus",
+        "color orange, nearby_ligands",
+        "label focus and name CA, resn + resi",
+        "orient structure",
+        f"ray {width}, {height}",
+        *visual_common.pymol_png(global_png, width=width, height=height),
+        "orient focus or neighborhood or nearby_ligands",
+        "zoom focus or neighborhood or nearby_ligands, 4",
+        "distance local_contacts, focus, neighborhood or nearby_ligands, 3.6, 2",
+        "set dash_color, gray40, local_contacts",
+        f"ray {width}, {height}",
+        *visual_common.pymol_png(local_png, width=width, height=height),
+        *visual_common.pymol_save(session),
+        "quit",
+    ])
+    return lines
+
+
+def build_residue_story(structure: str, focus: str, outdir: str, *, chain: str | None = None,
+                        cutoff: float = 5.0, pae: str | None = None, execute: bool = False,
+                        width: int = 1200, height: int = 900) -> dict[str, Any]:
+    source = Path(structure).expanduser()
+    if not source.is_file():
+        raise visual_common.VisualWorkflowError(f"Structure not found: {proteus_common.display_path(source)}")
+    if cutoff <= 0:
+        raise visual_common.VisualWorkflowError("Cutoff must be positive.")
+    parsed = _focus(focus, chain)
+    residue_arg = parsed["value"] if parsed["kind"] == "residue" else None
+    variant_arg = parsed["value"] if parsed["kind"] == "variant" else None
+    pocket = pocket_report.analyze_pocket(str(source), cutoff, residue=residue_arg, variant=variant_arg)
+    interface = interface_report.analyze_interfaces(str(source), cutoff, residue=residue_arg, variant=variant_arg)
+    triage = None
+    warnings = [
+        "Residue numbering is interpreted directly from the coordinate file unless an external mapping is supplied."
+    ]
+    if parsed["kind"] == "variant":
+        try:
+            triage = mutation_triage.triage_variants(
+                str(source), [parsed["value"]], chain=parsed.get("chain"), cutoff=cutoff, pae_json=pae,
+            )
+        except (OSError, ValueError, mutation_triage.MutationTriageError) as exc:
+            warnings.append(f"Mutation triage was unavailable: {exc}")
+    destination = Path(outdir)
+    destination.mkdir(parents=True, exist_ok=True)
+    data: dict[str, Any] = {
+        "workflow": "residue_story",
+        "structure": proteus_common.display_path(source),
+        "focus": parsed,
+        "cutoff_angstrom": cutoff,
+        "pocket_context": pocket.get("data", {}).get("residue_focus"),
+        "interface_context": interface.get("data", {}).get("residue_focus"),
+        "mutation_context": triage.get("data") if triage and triage.get("status") == "ok" else None,
+        "images": {
+            "global": proteus_common.display_path(destination / "residue_context.png"),
+            "local": proteus_common.display_path(destination / "residue_local.png"),
+        },
+        "session": proteus_common.display_path(destination / "residue_story.pse"),
+        "executed": execute,
+    }
+    provenance: dict[str, Any] = {"structure": proteus_common.file_provenance(source)}
+    if pae:
+        provenance["pae"] = proteus_common.file_provenance(pae)
+    report = proteus_common.ok_payload(data, warnings=warnings, provenance=provenance)
+    lines = _pymol_lines(source, parsed, destination, cutoff, width, height)
+    data["artifacts"] = visual_common.write_workflow(destination, "residue_story", report=report, pymol_lines=lines)
+    if execute:
+        result = visual_common.run_pymol(destination / "residue_story.pml")
+        data["execution"] = result
+        if result.get("status") != "ok":
+            report["status"] = "error"
+            report["error"] = result.get("error", "PyMOL residue workflow failed.")
+        elif not all(visual_common.verify_nonempty(destination / name) for name in ("residue_context.png", "residue_local.png")):
+            report["status"] = "error"
+            report["error"] = "PyMOL did not create both residue figures."
+        proteus_common.write_json(destination / "residue_story.json", report)
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Create a residue-centric structural evidence report and PyMOL figures.")
+    parser.add_argument("structure", help="Local PDB/mmCIF structure")
+    parser.add_argument("focus", help="Substitution (R175H) or residue (A:175)")
+    parser.add_argument("--chain", help="Optional chain override")
+    parser.add_argument("--cutoff", type=float, default=5.0)
+    parser.add_argument("--pae", help="Optional local PAE JSON for variants")
+    parser.add_argument("--outdir", default="proteus_residue")
+    parser.add_argument("--execute", action="store_true", help="Run PyMOL and create figures")
+    parser.add_argument("--json", action="store_true", help="Emit JSON (accepted for consistency)")
+    args = parser.parse_args(argv)
+    try:
+        report = build_residue_story(args.structure, args.focus, args.outdir, chain=args.chain,
+                                     cutoff=args.cutoff, pae=args.pae, execute=args.execute)
+    except (OSError, ValueError, visual_common.VisualWorkflowError) as exc:
+        print(json.dumps(proteus_common.error_payload(str(exc)), indent=2))
+        return 1
+    print(json.dumps(report, indent=2))
+    return 0 if report.get("status") == "ok" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/restraint_report.py b/scripts/restraint_report.py
new file mode 100644
index 0000000..a6c8170
--- /dev/null
+++ b/scripts/restraint_report.py
@@ -0,0 +1,217 @@
+#!/usr/bin/env python3
+"""Evaluate residue-pair distance restraints and create visual overlays."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import re
+import sys
+from collections import Counter
+from pathlib import Path
+from typing import Any
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import proteus_common
+import structure_qc
+import visual_common
+
+
+SPEC_RE = re.compile(r"^[A-Za-z0-9_.+?-]+$")
+
+
+def _records(path: str | Path) -> list[dict[str, Any]]:
+    values = visual_common.load_records(path)
+    output = []
+    for index, value in enumerate(values, start=1):
+        try:
+            residue1 = str(value["residue1"])
+            residue2 = str(value["residue2"])
+        except KeyError as exc:
+            raise visual_common.VisualWorkflowError(f"Restraint {index} requires residue1 and residue2.") from exc
+        minimum = float(value.get("min", value.get("minimum", 0.0)) or 0.0)
+        maximum = float(value.get("max", value.get("maximum", 30.0)) or 30.0)
+        if minimum < 0 or maximum <= 0 or minimum > maximum:
+            raise visual_common.VisualWorkflowError(f"Restraint {index} has invalid min/max bounds.")
+        chain1 = str(value.get("chain1") or "")
+        chain2 = str(value.get("chain2") or "")
+        atom1 = str(value.get("atom1") or "CA")
+        atom2 = str(value.get("atom2") or "CA")
+        for field, candidate in (
+            ("chain1", chain1), ("residue1", residue1), ("atom1", atom1),
+            ("chain2", chain2), ("residue2", residue2), ("atom2", atom2),
+        ):
+            if candidate and not SPEC_RE.fullmatch(candidate):
+                raise visual_common.VisualWorkflowError(f"Restraint {index} has an invalid {field} identifier.")
+        output.append({
+            "id": str(value.get("id") or f"restraint_{index}"),
+            "chain1": chain1,
+            "residue1": residue1,
+            "atom1": atom1,
+            "chain2": chain2,
+            "residue2": residue2,
+            "atom2": atom2,
+            "minimum": minimum,
+            "maximum": maximum,
+            "label": str(value.get("label") or value.get("id") or f"R{index}"),
+        })
+    return output
+
+
+def _find_atom(atoms: list[dict[str, Any]], chain: str, residue: str, atom_name: str) -> tuple[dict[str, Any] | None, int]:
+    matches = [
+        atom for atom in atoms
+        if atom["residue_id"] == residue
+        and atom["atom_name"].upper() == atom_name.upper()
+        and (not chain or atom["chain"] == chain)
+    ]
+    return (matches[0] if matches else None), len(matches)
+
+
+def _distance(left: dict[str, Any], right: dict[str, Any]) -> float:
+    return math.sqrt(sum((left[axis] - right[axis]) ** 2 for axis in ("x", "y", "z")))
+
+
+def _pymol_spec(chain: str, residue: str, atom: str) -> str:
+    base = f"resi {residue} and name {atom}"
+    return f"chain {chain} and {base}" if chain else base
+
+
+def _chimerax_spec(chain: str, residue: str, atom: str) -> str:
+    return f"#1/{chain}:{residue}@{atom}" if chain else f"#1:{residue}@{atom}"
+
+
+def evaluate_restraints(structure: str, restraints_file: str, outdir: str, *,
+                        model: str = "first", execute: bool = False,
+                        width: int = 1300, height: int = 900) -> dict[str, Any]:
+    source = Path(structure).expanduser()
+    if not source.is_file():
+        raise visual_common.VisualWorkflowError(f"Structure not found: {proteus_common.display_path(source)}")
+    text = structure_qc._read_text(source)
+    fmt = structure_qc._format_from_path(source)
+    raw, _meta = structure_qc.parse_mmcif(text) if fmt == "mmcif" else structure_qc.parse_pdb(text)
+    atoms, selection = structure_qc.select_atoms(raw, model=model, altloc="highest")
+    restraints = _records(restraints_file)
+    results = []
+    warnings: list[str] = []
+    for item in restraints:
+        left, left_count = _find_atom(atoms, item["chain1"], item["residue1"], item["atom1"])
+        right, right_count = _find_atom(atoms, item["chain2"], item["residue2"], item["atom2"])
+        result = dict(item)
+        if left_count > 1 or right_count > 1:
+            warnings.append(f"{item['id']} matched multiple atoms; specify chain IDs to disambiguate.")
+        if left is None or right is None:
+            result.update({"status": "unresolved", "distance": None})
+        else:
+            distance = _distance(left, right)
+            status = "satisfied" if item["minimum"] <= distance <= item["maximum"] else "too_short" if distance < item["minimum"] else "too_long"
+            result.update({"status": status, "distance": round(distance, 3)})
+        results.append(result)
+    counts = Counter(item["status"] for item in results)
+    destination = Path(outdir)
+    destination.mkdir(parents=True, exist_ok=True)
+
+    pml = visual_common.pymol_base(width=width, height=height)
+    pml.extend([
+        f"load {visual_common.quote_pymol(source.resolve())}, structure",
+        "hide everything, all",
+        "show cartoon, polymer",
+        "color gray80, polymer",
+    ])
+    cxc = [
+        *visual_common.chimerax_base(),
+        f"open {visual_common.quote_chimerax(source.resolve())}",
+        "cartoon",
+        "color protein lightgray",
+    ]
+    for index, item in enumerate(results, start=1):
+        if item["status"] == "unresolved":
+            continue
+        first_pml = _pymol_spec(item["chain1"], item["residue1"], item["atom1"])
+        second_pml = _pymol_spec(item["chain2"], item["residue2"], item["atom2"])
+        object_name = f"restraint_{index}"
+        color_name = "green" if item["status"] == "satisfied" else "red"
+        pml.extend([
+            f"show sticks, ({first_pml}) or ({second_pml})",
+            f"distance {object_name}, ({first_pml}), ({second_pml})",
+            f"set dash_color, {color_name}, {object_name}",
+        ])
+        first_cx = _chimerax_spec(item["chain1"], item["residue1"], item["atom1"])
+        second_cx = _chimerax_spec(item["chain2"], item["residue2"], item["atom2"])
+        cxc.extend([
+            f"show {first_cx} atoms",
+            f"show {second_cx} atoms",
+            f"style {first_cx} stick",
+            f"style {second_cx} stick",
+            f"distance {first_cx} {second_cx} color {color_name}",
+        ])
+    pml.extend(visual_common.finalize_pymol(
+        destination / "restraints.png", width=width, height=height,
+        session=destination / "restraints.pse",
+    ))
+    cxc.extend(visual_common.finalize_chimerax(
+        destination / "restraints_chimerax.png", width=width, height=height,
+        session=destination / "restraints.cxs",
+    ))
+    data: dict[str, Any] = {
+        "workflow": "restraint_report",
+        "structure": proteus_common.display_path(source),
+        "model_selection": selection,
+        "summary": {"total": len(results), **dict(sorted(counts.items()))},
+        "restraints": results,
+        "images": {
+            "pymol": proteus_common.display_path(destination / "restraints.png"),
+            "chimerax": proteus_common.display_path(destination / "restraints_chimerax.png"),
+        },
+        "executed": execute,
+    }
+    report = proteus_common.ok_payload(
+        data,
+        warnings=warnings,
+        provenance={
+            "structure": proteus_common.file_provenance(source),
+            "restraints": proteus_common.file_provenance(restraints_file),
+        },
+    )
+    data["artifacts"] = visual_common.write_workflow(
+        destination, "restraint_report", report=report, pymol_lines=pml, chimerax_lines=cxc,
+    )
+    if execute:
+        data["execution"] = {
+            "pymol": visual_common.run_pymol(destination / "restraint_report.pml"),
+            "chimerax": visual_common.run_chimerax(cxc),
+        }
+        failures = [name for name, result in data["execution"].items() if result.get("status") not in {"ok", "unavailable"}]
+        if failures:
+            report["status"] = "error"
+            report["error"] = f"Restraint rendering failed for: {', '.join(failures)}"
+        proteus_common.write_json(destination / "restraint_report.json", report)
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Evaluate residue-pair distance restraints and render overlays.")
+    parser.add_argument("structure")
+    parser.add_argument("restraints", help="CSV/JSON with chain1,residue1,atom1,chain2,residue2,atom2,min,max")
+    parser.add_argument("--model", default="first")
+    parser.add_argument("--outdir", default="proteus_restraints")
+    parser.add_argument("--execute", action="store_true")
+    parser.add_argument("--json", action="store_true", help="Emit JSON (accepted for consistency)")
+    args = parser.parse_args(argv)
+    try:
+        report = evaluate_restraints(args.structure, args.restraints, args.outdir,
+                                     model=args.model, execute=args.execute)
+    except (OSError, ValueError, json.JSONDecodeError, structure_qc.StructureQCError,
+            visual_common.VisualWorkflowError) as exc:
+        print(json.dumps(proteus_common.error_payload(str(exc)), indent=2))
+        return 1
+    print(json.dumps(report, indent=2))
+    return 0 if report.get("status") == "ok" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/scene_figure.py b/scripts/scene_figure.py
new file mode 100644
index 0000000..aa420a7
--- /dev/null
+++ b/scripts/scene_figure.py
@@ -0,0 +1,296 @@
+#!/usr/bin/env python3
+"""Compile a declarative scene manifest into PyMOL or ChimeraX figures."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import proteus_common
+import visual_common
+
+
+def _load_manifest(path: str | Path) -> dict[str, Any]:
+    source = Path(path)
+    if not source.is_file():
+        raise visual_common.VisualWorkflowError(f"Manifest not found: {proteus_common.display_path(source)}")
+    payload = json.loads(source.read_text(encoding="utf-8"))
+    if not isinstance(payload, dict):
+        raise visual_common.VisualWorkflowError("Scene manifest must be a JSON object.")
+    return payload
+
+
+def _structures(manifest: dict[str, Any]) -> list[dict[str, Any]]:
+    values = manifest.get("structures")
+    if not isinstance(values, list) or not values:
+        raise visual_common.VisualWorkflowError("Manifest requires a non-empty structures list.")
+    output = []
+    for index, value in enumerate(values, start=1):
+        if not isinstance(value, dict) or "path" not in value:
+            raise visual_common.VisualWorkflowError(f"Structure {index} requires a path.")
+        path = Path(str(value["path"])).expanduser()
+        if not path.is_file():
+            raise visual_common.VisualWorkflowError(f"Structure not found: {proteus_common.display_path(path)}")
+        name = visual_common.identifier(str(value.get("id") or f"structure_{index}"), field="structure id")
+        output.append({"id": name, "path": path})
+    return output
+
+
+def _views(manifest: dict[str, Any], name: str) -> list[dict[str, Any]]:
+    values = manifest.get("views")
+    if values is None:
+        values = [{"id": "overview", "selection": "all"}]
+    if not isinstance(values, list) or not values:
+        raise visual_common.VisualWorkflowError("views must be a non-empty list.")
+    output = []
+    for index, value in enumerate(values, start=1):
+        if not isinstance(value, dict):
+            raise visual_common.VisualWorkflowError("Each view must be an object.")
+        view_id = visual_common.identifier(str(value.get("id") or f"view_{index}"), field="view id")
+        output_name = str(value.get("output") or f"{name}_{view_id}.png")
+        output_path = Path(output_name)
+        if output_path.name != output_name or output_path.suffix.lower() != ".png":
+            raise visual_common.VisualWorkflowError("View output must be a PNG filename without directory traversal.")
+        turn = value.get("turn") or {}
+        if not isinstance(turn, dict):
+            raise visual_common.VisualWorkflowError("View turn must be an object with optional x, y, and z angles.")
+        output.append({
+            "id": view_id,
+            "selection": visual_common.selection(str(value.get("selection") or "all")),
+            "turn": turn,
+            "output": output_name,
+        })
+    return output
+
+
+def _representations(manifest: dict[str, Any]) -> list[dict[str, str]]:
+    values = manifest.get("representations") or [{"style": "cartoon", "selection": "all", "color": "chain"}]
+    if not isinstance(values, list):
+        raise visual_common.VisualWorkflowError("representations must be a list.")
+    output = []
+    for value in values:
+        if not isinstance(value, dict):
+            raise visual_common.VisualWorkflowError("Each representation must be an object.")
+        item = {
+            "style": visual_common.style(str(value.get("style") or "cartoon")),
+            "selection": visual_common.selection(str(value.get("selection") or "all")),
+            "color": str(value.get("color") or "chain"),
+        }
+        if item["color"] not in {"chain", "element", "plddt", "bfactor", "rainbow"}:
+            visual_common.color(item["color"])
+        if "transparency" in value:
+            number = float(value["transparency"])
+            if number < 0 or number > 1:
+                raise visual_common.VisualWorkflowError("Transparency must be between 0 and 1.")
+            item["transparency"] = str(number)
+        output.append(item)
+    return output
+
+
+def _labels(manifest: dict[str, Any]) -> list[dict[str, str]]:
+    values = manifest.get("labels") or []
+    if not isinstance(values, list):
+        raise visual_common.VisualWorkflowError("labels must be a list.")
+    output = []
+    for value in values:
+        if not isinstance(value, dict):
+            raise visual_common.VisualWorkflowError("Each label must be an object.")
+        text = str(value.get("text") or "%s%s")
+        if any(character in text for character in "\r\n;"):
+            raise visual_common.VisualWorkflowError("Label text cannot contain newlines or semicolons.")
+        output.append({
+            "selection": visual_common.selection(str(value.get("selection") or "name CA")),
+            "text": text,
+            "color": visual_common.color(str(value.get("color") or "black")),
+        })
+    return output
+
+
+def _pymol_script(
+    structures: list[dict[str, Any]], representations: list[dict[str, str]],
+    labels: list[dict[str, str]], views: list[dict[str, Any]], outdir: Path,
+    *, background: str, width: int, height: int, session: Path,
+) -> list[str]:
+    lines = visual_common.pymol_base(background=background, width=width, height=height)
+    for item in structures:
+        lines.append(f"load {visual_common.quote_pymol(item['path'].resolve())}, {item['id']}")
+    lines.append("hide everything, all")
+    for item in representations:
+        lines.append(f"show {item['style']}, {item['selection']}")
+        mode = item["color"]
+        if mode == "chain":
+            lines.append(f"util.cbc {item['selection']}")
+        elif mode == "element":
+            lines.append(f"util.cnc {item['selection']}")
+        elif mode == "plddt":
+            lines.extend([
+                f"color orange, {item['selection']}",
+                f"color yellow, ({item['selection']}) and b > 50",
+                f"color cyan, ({item['selection']}) and b > 70",
+                f"color blue, ({item['selection']}) and b > 90",
+            ])
+        elif mode == "bfactor":
+            lines.append(f"spectrum b, blue_white_red, {item['selection']}")
+        elif mode == "rainbow":
+            lines.append(f"spectrum count, rainbow, {item['selection']}")
+        else:
+            lines.append(f"color {mode}, {item['selection']}")
+        if "transparency" in item:
+            setting = "surface_transparency" if item["style"] == "surface" else f"{item['style'].rstrip('s')}_transparency"
+            lines.append(f"set {setting}, {item['transparency']}, {item['selection']}")
+    for item in labels:
+        text = item["text"].replace('"', '\\"')
+        lines.extend([
+            f"label {item['selection']}, \"{text}\"",
+            f"set label_color, {item['color']}, {item['selection']}",
+        ])
+    for view in views:
+        lines.append(f"orient {view['selection']}")
+        for axis in ("x", "y", "z"):
+            if axis in view["turn"]:
+                lines.append(f"turn {axis}, {float(view['turn'][axis])}")
+        output = (outdir / view["output"]).resolve()
+        lines.append(f"ray {width}, {height}")
+        lines.extend(visual_common.pymol_png(output, width=width, height=height))
+    lines.extend(visual_common.pymol_save(session))
+    lines.append("quit")
+    return lines
+
+
+def _chimerax_script(
+    structures: list[dict[str, Any]], representations: list[dict[str, str]],
+    labels: list[dict[str, str]], views: list[dict[str, Any]], outdir: Path,
+    *, background: str, width: int, height: int, session: Path,
+) -> list[str]:
+    lines = visual_common.chimerax_base(background=background)
+    for item in structures:
+        lines.append(f"open {visual_common.quote_chimerax(item['path'].resolve())} name {item['id']}")
+    lines.append("hide")
+    for item in representations:
+        target = item["selection"]
+        style = item["style"]
+        if style in {"cartoon", "ribbon"}:
+            lines.append(f"cartoon {target}")
+        elif style == "surface":
+            lines.append(f"surface {target}")
+        else:
+            atom_style = {"sticks": "stick", "spheres": "sphere", "lines": "wire"}[style]
+            lines.extend([f"show {target} atoms", f"style {target} {atom_style}"])
+        mode = item["color"]
+        if mode == "chain":
+            lines.append(f"color {target} bychain")
+        elif mode == "element":
+            lines.append(f"color {target} byelement")
+        elif mode == "plddt":
+            lines.append(f"color bfactor {target} palette alphafold")
+        elif mode == "bfactor":
+            lines.append(f"color bfactor {target}")
+        elif mode == "rainbow":
+            lines.append(f"rainbow {target}")
+        else:
+            lines.append(f"color {target} {mode}")
+        if "transparency" in item:
+            target_type = "s" if style == "surface" else "c" if style in {"cartoon", "ribbon"} else "a"
+            lines.append(f"transparency {target} {float(item['transparency']) * 100:.1f} target {target_type}")
+    for index, item in enumerate(labels, start=1):
+        text = item["text"].replace('"', '\\"')
+        lines.append(f"label {item['selection']} text \"{text}\" color {item['color']}")
+        lines.append(f"2dlabels create legend{index} text \"{text}\" color {item['color']} xpos 0.03 ypos {0.96 - index * 0.05:.2f}")
+    for view in views:
+        lines.append(f"view {view['selection']}")
+        for axis in ("x", "y", "z"):
+            if axis in view["turn"]:
+                lines.append(f"turn {axis} {float(view['turn'][axis])}")
+        output = (outdir / view["output"]).resolve()
+        lines.extend([f"save {visual_common.quote_chimerax(output)} width {width} height {height} supersample 3", "wait 1"])
+    lines.append(f"save {visual_common.quote_chimerax(session.resolve())}")
+    return lines
+
+
+def compile_scene(manifest_path: str, outdir: str, *, execute: bool = False) -> dict[str, Any]:
+    manifest = _load_manifest(manifest_path)
+    name = proteus_common.slug(str(manifest.get("name") or "scene"))
+    tool = str(manifest.get("tool") or "pymol").lower()
+    if tool not in {"pymol", "chimerax"}:
+        raise visual_common.VisualWorkflowError("tool must be pymol or chimerax.")
+    destination = Path(outdir)
+    destination.mkdir(parents=True, exist_ok=True)
+    structures = _structures(manifest)
+    representations = _representations(manifest)
+    labels = _labels(manifest)
+    views = _views(manifest, name)
+    width = int(manifest.get("width") or 1200)
+    height = int(manifest.get("height") or 900)
+    background = visual_common.color(str(manifest.get("background") or "white"))
+    if width < 100 or height < 100 or width > 10000 or height > 10000:
+        raise visual_common.VisualWorkflowError("Image dimensions must be between 100 and 10000 pixels.")
+    session = destination / f"{name}.{'pse' if tool == 'pymol' else 'cxs'}"
+    if tool == "pymol":
+        pml = _pymol_script(structures, representations, labels, views, destination,
+                            background=background, width=width, height=height, session=session)
+        cxc = None
+    else:
+        pml = None
+        cxc = _chimerax_script(structures, representations, labels, views, destination,
+                               background=background, width=width, height=height, session=session)
+    data: dict[str, Any] = {
+        "workflow": "figure",
+        "name": name,
+        "tool": tool,
+        "structures": [{"id": item["id"], "path": proteus_common.display_path(item["path"])} for item in structures],
+        "views": [{"id": item["id"], "output": proteus_common.display_path(destination / item["output"])} for item in views],
+        "session": proteus_common.display_path(session),
+        "executed": execute,
+    }
+    report = proteus_common.ok_payload(
+        data,
+        provenance={
+            "manifest": proteus_common.file_provenance(manifest_path),
+            "structures": [proteus_common.file_provenance(item["path"]) for item in structures],
+        },
+    )
+    outputs = visual_common.write_workflow(destination, name, report=report, pymol_lines=pml, chimerax_lines=cxc)
+    data["artifacts"] = outputs
+    if execute:
+        if tool == "pymol":
+            result = visual_common.run_pymol(destination / f"{name}.pml")
+        else:
+            result = visual_common.run_chimerax(cxc or [])
+        data["execution"] = result
+        if result.get("status") != "ok":
+            report["status"] = "error"
+            report["error"] = result.get("error", f"{tool} execution failed.")
+        else:
+            missing = [item["output"] for item in views if not visual_common.verify_nonempty(destination / item["output"])]
+            if missing:
+                report["status"] = "error"
+                report["error"] = f"Expected image outputs were not created: {', '.join(missing)}"
+        proteus_common.write_json(destination / f"{name}.json", report)
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Compile a reproducible PyMOL/ChimeraX scene manifest.")
+    parser.add_argument("manifest", help="JSON scene manifest")
+    parser.add_argument("--outdir", default="proteus_figure", help="Output directory")
+    parser.add_argument("--execute", action="store_true", help="Run the generated PyMOL/ChimeraX workflow")
+    parser.add_argument("--json", action="store_true", help="Emit JSON (accepted for consistency)")
+    args = parser.parse_args(argv)
+    try:
+        report = compile_scene(args.manifest, args.outdir, execute=args.execute)
+    except (OSError, ValueError, json.JSONDecodeError, visual_common.VisualWorkflowError) as exc:
+        print(json.dumps(proteus_common.error_payload(str(exc)), indent=2))
+        return 1
+    print(json.dumps(report, indent=2))
+    return 0 if report.get("status") == "ok" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/state_compare.py b/scripts/state_compare.py
new file mode 100644
index 0000000..45373c6
--- /dev/null
+++ b/scripts/state_compare.py
@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""Compare structural states and create reproducible PyMOL comparison figures."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import compare_structures
+import interaction_report
+import proteus_common
+import visual_common
+
+
+def _contact_residues(report: dict[str, Any]) -> set[str]:
+    data = report.get("data", report)
+    output: set[str] = set()
+    for group in data.get("ligand_groups", []):
+        for residue in group.get("contact_residues", []):
+            label = residue.get("residue_label")
+            if label:
+                output.add(str(label))
+    return output
+
+
+def _contact_change(reference: Path, mobile: Path, ligand: str | None) -> tuple[dict[str, Any], list[str]]:
+    if not ligand:
+        return {}, []
+    warnings: list[str] = []
+    filters = [ligand.upper()]
+    reports = []
+    for path in (reference, mobile):
+        try:
+            reports.append(interaction_report.analyze_interactions(str(path), ligand_filters=filters))
+        except (OSError, ValueError, interaction_report.InteractionReportError) as exc:
+            warnings.append(f"Could not compare {ligand} contacts for {proteus_common.display_path(path)}: {exc}")
+            reports.append({"status": "error"})
+    if any(item.get("status") != "ok" for item in reports):
+        return {}, warnings
+    ref = _contact_residues(reports[0])
+    mob = _contact_residues(reports[1])
+    return {
+        "ligand": ligand.upper(),
+        "reference_contacts": sorted(ref),
+        "mobile_contacts": sorted(mob),
+        "gained_in_mobile": sorted(mob - ref),
+        "lost_in_mobile": sorted(ref - mob),
+        "preserved": sorted(ref & mob),
+    }, warnings
+
+
+def _pymol_lines(reference: Path, mobile: Path, outdir: Path, ligand: str | None,
+                  width: int, height: int) -> list[str]:
+    overlay = (outdir / "comparison_overlay.png").resolve()
+    exploded = (outdir / "comparison_side_by_side.png").resolve()
+    session = (outdir / "comparison.pse").resolve()
+    lines = visual_common.pymol_base(width=width, height=height)
+    lines.extend([
+        f"load {visual_common.quote_pymol(reference.resolve())}, reference",
+        f"load {visual_common.quote_pymol(mobile.resolve())}, mobile",
+        "hide everything, all",
+        "show cartoon, reference or mobile",
+        "color gray70, reference",
+        "color cyan, mobile",
+        "cealign reference, mobile",
+    ])
+    if ligand:
+        ligand_selection = f"resn {ligand.upper()}"
+        lines.extend([
+            f"show sticks, ({ligand_selection})",
+            f"color orange, reference and ({ligand_selection})",
+            f"color magenta, mobile and ({ligand_selection})",
+            f"show sticks, byres ((reference or mobile) within 4 of ({ligand_selection}))",
+        ])
+    lines.extend([
+        "orient reference or mobile",
+        f"ray {width}, {height}",
+        *visual_common.pymol_png(overlay, width=width, height=height),
+        "translate [22, 0, 0], mobile, camera=1",
+        "rotate y, 22, mobile, camera=1",
+        "orient reference or mobile",
+        f"ray {width}, {height}",
+        *visual_common.pymol_png(exploded, width=width, height=height),
+        *visual_common.pymol_save(session),
+        "quit",
+    ])
+    return lines
+
+
+def compare_states(reference: str, mobile: str, outdir: str, *, ligand: str | None = None,
+                   execute: bool = False, width: int = 1400, height: int = 900) -> dict[str, Any]:
+    ref = Path(reference).expanduser()
+    mob = Path(mobile).expanduser()
+    for path in (ref, mob):
+        if not path.is_file():
+            raise visual_common.VisualWorkflowError(f"Structure not found: {proteus_common.display_path(path)}")
+    if ligand and not ligand.replace("_", "").isalnum():
+        raise visual_common.VisualWorkflowError("Ligand code must be alphanumeric.")
+    destination = Path(outdir)
+    destination.mkdir(parents=True, exist_ok=True)
+    contact_change, warnings = _contact_change(ref, mob, ligand)
+    data: dict[str, Any] = {
+        "workflow": "compare",
+        "reference": proteus_common.display_path(ref),
+        "mobile": proteus_common.display_path(mob),
+        "ligand_contact_changes": contact_change or None,
+        "images": {
+            "overlay": proteus_common.display_path(destination / "comparison_overlay.png"),
+            "side_by_side": proteus_common.display_path(destination / "comparison_side_by_side.png"),
+        },
+        "session": proteus_common.display_path(destination / "comparison.pse"),
+        "executed": execute,
+    }
+    report = proteus_common.ok_payload(
+        data,
+        warnings=warnings,
+        provenance={"reference": proteus_common.file_provenance(ref), "mobile": proteus_common.file_provenance(mob)},
+    )
+    lines = _pymol_lines(ref, mob, destination, ligand, width, height)
+    artifacts = visual_common.write_workflow(destination, "state_compare", report=report, pymol_lines=lines)
+    data["artifacts"] = artifacts
+    if execute:
+        metrics = compare_structures.compare(str(ref), str(mob), per_residue=True)
+        if metrics.get("status") == "ok":
+            metric_data = metrics.get("data", {})
+            data["alignment"] = metric_data.get("alignment")
+            data["per_residue"] = metric_data.get("per_residue")
+        else:
+            report.setdefault("warnings", []).append(f"Alignment metrics failed: {metrics.get('error', 'unknown error')}")
+        execution = visual_common.run_pymol(destination / "state_compare.pml")
+        data["execution"] = execution
+        if execution.get("status") != "ok":
+            report["status"] = "error"
+            report["error"] = execution.get("error", "PyMOL comparison failed.")
+        else:
+            expected = [destination / "comparison_overlay.png", destination / "comparison_side_by_side.png"]
+            if not all(visual_common.verify_nonempty(path) for path in expected):
+                report["status"] = "error"
+                report["error"] = "PyMOL did not create all expected comparison images."
+        proteus_common.write_json(destination / "state_compare.json", report)
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Compare two structural states and render overlay/side-by-side figures.")
+    parser.add_argument("reference", help="Reference structure")
+    parser.add_argument("mobile", help="Mobile structure")
+    parser.add_argument("--ligand", help="Optional ligand code for contact-change analysis")
+    parser.add_argument("--outdir", default="proteus_compare", help="Output directory")
+    parser.add_argument("--width", type=int, default=1400)
+    parser.add_argument("--height", type=int, default=900)
+    parser.add_argument("--execute", action="store_true", help="Run PyMOL and produce figures/metrics")
+    parser.add_argument("--json", action="store_true", help="Emit JSON (accepted for consistency)")
+    args = parser.parse_args(argv)
+    try:
+        report = compare_states(args.reference, args.mobile, args.outdir, ligand=args.ligand,
+                                execute=args.execute, width=args.width, height=args.height)
+    except (OSError, ValueError, visual_common.VisualWorkflowError) as exc:
+        print(json.dumps(proteus_common.error_payload(str(exc)), indent=2))
+        return 1
+    print(json.dumps(report, indent=2))
+    return 0 if report.get("status") == "ok" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/structure_info.py b/scripts/structure_info.py
index 66a2e60..c580e43 100644
--- a/scripts/structure_info.py
+++ b/scripts/structure_info.py
@@ -74,6 +74,7 @@ def parse_pdb(path: str, force_alphafold: bool = False) -> dict:
     atom_count = 0
     hetatm_count = 0
     b_factors = []
+    residue_confidence = {}
     title_lines = []
 
     with open(path) as handle:
@@ -94,6 +95,10 @@ def parse_pdb(path: str, force_alphafold: bool = False) -> dict:
                 chains.add(chain)
                 residues[chain].add((residue_name, residue_id))
                 b_factors.append(b_factor)
+                atom_name = line[12:16].strip()
+                insertion_code = line[26].strip() if len(line) > 26 else ""
+                if rec == "ATOM" and atom_name == "CA":
+                    residue_confidence[(chain, residue_id, insertion_code, residue_name)] = b_factor
                 if rec == "ATOM":
                     atom_count += 1
                 else:
@@ -108,6 +113,7 @@ def parse_pdb(path: str, force_alphafold: bool = False) -> dict:
         atom_count=atom_count,
         hetatm_count=hetatm_count,
         b_factors=b_factors,
+        residue_confidence=residue_confidence,
         force_alphafold=force_alphafold,
     )
 
@@ -140,6 +146,7 @@ def parse_mmcif(path: str, force_alphafold: bool = False) -> dict:
     atom_count = 0
     hetatm_count = 0
     b_factors = []
+    residue_confidence = {}
 
     index = 0
     while index < len(lines):
@@ -164,6 +171,8 @@ def parse_mmcif(path: str, force_alphafold: bool = False) -> dict:
         comp_i = field_index.get("_atom_site.label_comp_id", field_index.get("_atom_site.auth_comp_id"))
         seq_i = field_index.get("_atom_site.auth_seq_id", field_index.get("_atom_site.label_seq_id"))
         b_i = field_index.get("_atom_site.B_iso_or_equiv")
+        atom_i = field_index.get("_atom_site.auth_atom_id", field_index.get("_atom_site.label_atom_id"))
+        insertion_i = field_index.get("_atom_site.pdbx_PDB_ins_code")
 
         while index < len(lines):
             stripped = lines[index].strip()
@@ -193,7 +202,14 @@ def parse_mmcif(path: str, force_alphafold: bool = False) -> dict:
                 hetatm_count += 1
             if b_i is not None:
                 try:
-                    b_factors.append(float(row[b_i]))
+                    b_factor = float(row[b_i])
+                    b_factors.append(b_factor)
+                    atom_name = row[atom_i] if atom_i is not None else ""
+                    insertion_code = row[insertion_i] if insertion_i is not None else ""
+                    if insertion_code in {".", "?"}:
+                        insertion_code = ""
+                    if group == "ATOM" and atom_name == "CA":
+                        residue_confidence[(chain, seq, insertion_code, comp)] = b_factor
                 except ValueError:
                     pass
 
@@ -206,6 +222,7 @@ def parse_mmcif(path: str, force_alphafold: bool = False) -> dict:
         atom_count=atom_count,
         hetatm_count=hetatm_count,
         b_factors=b_factors,
+        residue_confidence=residue_confidence,
         force_alphafold=force_alphafold,
     )
 
@@ -213,6 +230,7 @@ def parse_mmcif(path: str, force_alphafold: bool = False) -> dict:
 def _build_output(path: str, fmt: str, title: str | None, chains: set[str],
                   residues: dict[str, set[tuple[str, str]]], atom_count: int,
                   hetatm_count: int, b_factors: list[float],
+                  residue_confidence: dict[tuple[str, str, str, str], float],
                   force_alphafold: bool) -> dict:
     sorted_chains = sorted(chains)
     chain_details = {
@@ -232,7 +250,22 @@ def _build_output(path: str, fmt: str, title: str | None, chains: set[str],
         "likely_alphafold": likely_alphafold,
     }
     if likely_alphafold and b_factors:
-        data["plddt_distribution"] = _plddt_distribution(b_factors)
+        values = list(residue_confidence.values()) or b_factors
+        data["plddt"] = {
+            "basis": "ca_per_residue" if residue_confidence else "all_atoms",
+            "statistics": _bfactor_stats(values),
+            "distribution": _plddt_distribution(values),
+            "residues": [
+                {
+                    "chain": key[0],
+                    "residue": f"{key[1]}{key[2]}",
+                    "resname": key[3],
+                    "plddt": round(value, 2),
+                }
+                for key, value in sorted(residue_confidence.items())
+            ],
+        }
+        data["plddt_distribution"] = data["plddt"]["distribution"]
     output = {"status": "ok", "data": data}
     output.update(data)
     return output
diff --git a/scripts/structure_qc.py b/scripts/structure_qc.py
new file mode 100644
index 0000000..81f9c83
--- /dev/null
+++ b/scripts/structure_qc.py
@@ -0,0 +1,486 @@
+#!/usr/bin/env python3
+"""Structure preflight and quality-control report for PDB/mmCIF inputs.
+
+The parser is intentionally dependency-free and conservative. It exposes model,
+alternate-conformer, occupancy, residue, and chemical-component decisions so
+downstream workflows do not silently combine incompatible coordinate states.
+"""
+
+from __future__ import annotations
+
+import argparse
+import gzip
+import json
+import math
+import shlex
+import sys
+from collections import Counter, defaultdict
+from pathlib import Path
+from typing import Any, Iterable
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import proteus_common
+
+
+STANDARD_AMINO_ACIDS = {
+    "ALA", "ARG", "ASN", "ASP", "CYS", "GLN", "GLU", "GLY", "HIS", "ILE",
+    "LEU", "LYS", "MET", "PHE", "PRO", "SER", "THR", "TRP", "TYR", "VAL",
+}
+MODIFIED_POLYMER = {
+    "MSE", "SEC", "PYL", "SEP", "TPO", "PTR", "CSO", "CSD", "CME", "MLY",
+    "M3L", "HYP", "KCX", "LLP", "FME", "PCA", "DAL", "DLE", "DVA", "DTH",
+}
+NUCLEOTIDES = {
+    "A", "C", "G", "U", "I", "DA", "DC", "DG", "DT", "DI", "ADE", "CYT",
+    "GUA", "THY", "URA",
+}
+WATERS = {"HOH", "WAT", "DOD", "H2O", "TIP", "T3P", "SOL"}
+IONS = {
+    "LI", "NA", "K", "RB", "CS", "MG", "CA", "SR", "BA", "MN", "FE", "CO",
+    "NI", "CU", "ZN", "CD", "HG", "AL", "GA", "CL", "BR", "IOD", "F", "SO4",
+    "PO4", "NO3", "NH4",
+}
+COFACTORS = {
+    "ATP", "ADP", "AMP", "GTP", "GDP", "GMP", "FAD", "FMN", "NAD", "NAP",
+    "NDP", "SAM", "SAH", "COA", "HEM", "HEC", "PLP", "TPP", "THF", "B12",
+}
+ADDITIVES = {
+    "GOL", "EDO", "PEG", "PG4", "PGE", "MPD", "DMS", "BME", "MES", "TRS",
+    "HEP", "ACT", "FMT", "ACE", "CIT", "TAR", "EOH", "IPA", "ACN", "BOG",
+}
+BACKBONE = {"N", "CA", "C", "O"}
+
+
+class StructureQCError(RuntimeError):
+    pass
+
+
+def _format_from_path(path: Path) -> str:
+    name = path.name.lower()
+    if name.endswith((".cif", ".mmcif", ".cif.gz", ".mmcif.gz")):
+        return "mmcif"
+    if name.endswith((".pdb", ".ent", ".pdb.gz", ".ent.gz")):
+        return "pdb"
+    raise StructureQCError("Input must be PDB/mmCIF, optionally gzip-compressed.")
+
+
+def _read_text(path: Path) -> str:
+    if path.name.lower().endswith(".gz"):
+        with gzip.open(path, "rt", encoding="utf-8", errors="replace") as handle:
+            return handle.read()
+    return path.read_text(encoding="utf-8", errors="replace")
+
+
+def _float(value: str | None) -> float | None:
+    if value is None or value in {"", ".", "?"}:
+        return None
+    try:
+        result = float(value)
+    except ValueError:
+        return None
+    return result if math.isfinite(result) else None
+
+
+def _clean(value: str | None, default: str = "") -> str:
+    if value is None or value in {"", ".", "?"}:
+        return default
+    return value
+
+
+def _atom(
+    *, record: str, model: int, serial: str, atom_name: str, altloc: str,
+    resname: str, chain: str, residue_id: str, insertion_code: str,
+    x: float, y: float, z: float, occupancy: float | None,
+    bfactor: float | None, element: str,
+) -> dict[str, Any]:
+    return {
+        "record": record,
+        "model": model,
+        "serial": serial,
+        "atom_name": atom_name,
+        "altloc": altloc,
+        "resname": resname.upper(),
+        "chain": chain or "?",
+        "residue_id": residue_id or "?",
+        "insertion_code": insertion_code,
+        "x": x,
+        "y": y,
+        "z": z,
+        "occupancy": occupancy,
+        "bfactor": bfactor,
+        "element": element.upper(),
+    }
+
+
+def parse_pdb(text: str) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+    atoms: list[dict[str, Any]] = []
+    current_model = 1
+    explicit_models = False
+    malformed = 0
+    link_records = 0
+    conect_records = 0
+    for line in text.splitlines():
+        record = line[:6].strip().upper()
+        if record == "MODEL":
+            explicit_models = True
+            try:
+                current_model = int(line[10:14].strip())
+            except ValueError:
+                current_model += 1
+            continue
+        if record == "LINK":
+            link_records += 1
+            continue
+        if record == "CONECT":
+            conect_records += 1
+            continue
+        if record not in {"ATOM", "HETATM"}:
+            continue
+        if len(line) < 54:
+            malformed += 1
+            continue
+        try:
+            atoms.append(_atom(
+                record=record,
+                model=current_model,
+                serial=line[6:11].strip(),
+                atom_name=line[12:16].strip(),
+                altloc=line[16].strip(),
+                resname=line[17:20].strip(),
+                chain=line[21].strip(),
+                residue_id=line[22:26].strip(),
+                insertion_code=line[26].strip(),
+                x=float(line[30:38]),
+                y=float(line[38:46]),
+                z=float(line[46:54]),
+                occupancy=_float(line[54:60] if len(line) >= 60 else None),
+                bfactor=_float(line[60:66] if len(line) >= 66 else None),
+                element=line[76:78].strip() if len(line) >= 78 else "",
+            ))
+        except ValueError:
+            malformed += 1
+    return atoms, {
+        "explicit_models": explicit_models,
+        "malformed_atom_records": malformed,
+        "link_records": link_records,
+        "conect_records": conect_records,
+    }
+
+
+def _field(fields: dict[str, int], *names: str) -> int | None:
+    for name in names:
+        if name in fields:
+            return fields[name]
+    return None
+
+
+def _value(row: list[str], index: int | None, default: str = "") -> str:
+    if index is None or index >= len(row):
+        return default
+    return row[index]
+
+
+def parse_mmcif(text: str) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+    lines = text.splitlines()
+    atoms: list[dict[str, Any]] = []
+    malformed = 0
+    struct_conn_rows = 0
+    index = 0
+    while index < len(lines):
+        if lines[index].strip() != "loop_":
+            index += 1
+            continue
+        index += 1
+        headers: list[str] = []
+        while index < len(lines) and lines[index].strip().startswith("_"):
+            headers.append(lines[index].strip())
+            index += 1
+        if not headers:
+            continue
+        atom_loop = all(item.startswith("_atom_site.") for item in headers)
+        conn_loop = all(item.startswith("_struct_conn.") for item in headers)
+        fields = {name: position for position, name in enumerate(headers)}
+        if atom_loop:
+            group_i = _field(fields, "_atom_site.group_PDB")
+            model_i = _field(fields, "_atom_site.pdbx_PDB_model_num")
+            serial_i = _field(fields, "_atom_site.id")
+            atom_i = _field(fields, "_atom_site.auth_atom_id", "_atom_site.label_atom_id")
+            alt_i = _field(fields, "_atom_site.label_alt_id", "_atom_site.auth_alt_id")
+            comp_i = _field(fields, "_atom_site.auth_comp_id", "_atom_site.label_comp_id")
+            chain_i = _field(fields, "_atom_site.auth_asym_id", "_atom_site.label_asym_id")
+            seq_i = _field(fields, "_atom_site.auth_seq_id", "_atom_site.label_seq_id")
+            ins_i = _field(fields, "_atom_site.pdbx_PDB_ins_code")
+            x_i = _field(fields, "_atom_site.Cartn_x")
+            y_i = _field(fields, "_atom_site.Cartn_y")
+            z_i = _field(fields, "_atom_site.Cartn_z")
+            occupancy_i = _field(fields, "_atom_site.occupancy")
+            bfactor_i = _field(fields, "_atom_site.B_iso_or_equiv")
+            element_i = _field(fields, "_atom_site.type_symbol")
+
+        while index < len(lines):
+            stripped = lines[index].strip()
+            if not stripped or stripped.startswith("#"):
+                index += 1
+                break
+            if stripped == "loop_" or stripped.startswith("_"):
+                break
+            try:
+                row = shlex.split(stripped, posix=True)
+            except ValueError:
+                malformed += 1
+                index += 1
+                continue
+            index += 1
+            if len(row) < len(headers):
+                malformed += 1
+                continue
+            if conn_loop:
+                struct_conn_rows += 1
+                continue
+            if not atom_loop:
+                continue
+            record = _clean(_value(row, group_i), "ATOM").upper()
+            if record not in {"ATOM", "HETATM"}:
+                continue
+            try:
+                atoms.append(_atom(
+                    record=record,
+                    model=int(_clean(_value(row, model_i), "1")),
+                    serial=_clean(_value(row, serial_i)),
+                    atom_name=_clean(_value(row, atom_i), "?"),
+                    altloc=_clean(_value(row, alt_i)),
+                    resname=_clean(_value(row, comp_i), "?"),
+                    chain=_clean(_value(row, chain_i), "?"),
+                    residue_id=_clean(_value(row, seq_i), "?"),
+                    insertion_code=_clean(_value(row, ins_i)),
+                    x=float(_value(row, x_i)),
+                    y=float(_value(row, y_i)),
+                    z=float(_value(row, z_i)),
+                    occupancy=_float(_value(row, occupancy_i)),
+                    bfactor=_float(_value(row, bfactor_i)),
+                    element=_clean(_value(row, element_i)),
+                ))
+            except (TypeError, ValueError):
+                malformed += 1
+    return atoms, {
+        "explicit_models": len({atom["model"] for atom in atoms}) > 1,
+        "malformed_atom_records": malformed,
+        "struct_conn_rows": struct_conn_rows,
+    }
+
+
+def _altloc_rank(atom: dict[str, Any]) -> tuple[float, int, str]:
+    occupancy = atom["occupancy"] if atom["occupancy"] is not None else -1.0
+    preferred = {"": 3, "A": 2, "1": 1}.get(atom["altloc"], 0)
+    return occupancy, preferred, atom["altloc"]
+
+
+def select_atoms(
+    atoms: list[dict[str, Any]], *, model: str = "first", altloc: str = "highest",
+) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+    models = sorted({atom["model"] for atom in atoms})
+    if not models:
+        return [], {"available_models": [], "selected_models": [], "alternate_sites": 0}
+    if model == "all":
+        selected_models = models
+    elif model == "first":
+        selected_models = [models[0]]
+    else:
+        try:
+            requested = int(model)
+        except ValueError as exc:
+            raise StructureQCError("--model must be 'first', 'all', or an integer.") from exc
+        if requested not in models:
+            raise StructureQCError(f"Model {requested} is not present; available models: {models}")
+        selected_models = [requested]
+    candidates = [atom for atom in atoms if atom["model"] in selected_models]
+    grouped: dict[tuple[Any, ...], list[dict[str, Any]]] = defaultdict(list)
+    for atom in candidates:
+        key = (
+            atom["model"], atom["chain"], atom["residue_id"], atom["insertion_code"],
+            atom["resname"], atom["atom_name"],
+        )
+        grouped[key].append(atom)
+    alternate_sites = sum(1 for values in grouped.values() if len({item["altloc"] for item in values}) > 1)
+    if altloc == "all":
+        selected = candidates
+    elif altloc == "highest":
+        selected = [max(values, key=_altloc_rank) for values in grouped.values()]
+    else:
+        requested = altloc.strip()
+        selected = []
+        for values in grouped.values():
+            exact = [item for item in values if item["altloc"] in {"", requested}]
+            selected.append(max(exact or values, key=_altloc_rank))
+    return selected, {
+        "available_models": models,
+        "selected_models": selected_models,
+        "alternate_sites": alternate_sites,
+        "altloc_policy": altloc,
+    }
+
+
+def component_role(resname: str, record: str, atom_count: int) -> str:
+    if record == "ATOM" or resname in STANDARD_AMINO_ACIDS or resname in NUCLEOTIDES:
+        return "polymer"
+    if resname in MODIFIED_POLYMER:
+        return "modified_polymer"
+    if resname in WATERS:
+        return "water"
+    if resname in IONS:
+        return "ion"
+    if resname in COFACTORS:
+        return "cofactor"
+    if resname in ADDITIVES:
+        return "additive_or_solvent"
+    return "ligand_or_unknown"
+
+
+def _residue_sort(value: str) -> tuple[int, int | str]:
+    try:
+        return 0, int(value)
+    except ValueError:
+        return 1, value
+
+
+def build_report(path: str | Path, *, model: str = "first", altloc: str = "highest") -> dict[str, Any]:
+    source = Path(path).expanduser()
+    if not source.is_file():
+        raise StructureQCError(f"File not found: {proteus_common.display_path(source)}")
+    fmt = _format_from_path(source)
+    text = _read_text(source)
+    raw_atoms, parser_meta = parse_mmcif(text) if fmt == "mmcif" else parse_pdb(text)
+    atoms, selection = select_atoms(raw_atoms, model=model, altloc=altloc)
+    warnings: list[str] = []
+    issues: list[dict[str, Any]] = []
+
+    if len(selection["available_models"]) > 1:
+        warnings.append("Multiple coordinate models are present; downstream geometry should use an explicit model.")
+        issues.append({"code": "multiple_models", "count": len(selection["available_models"])})
+    if selection["alternate_sites"]:
+        warnings.append("Alternate conformers are present; the report records the conformer-selection policy.")
+        issues.append({"code": "alternate_conformers", "count": selection["alternate_sites"]})
+    if parser_meta.get("malformed_atom_records"):
+        warnings.append("Some coordinate records could not be parsed by the lightweight parser.")
+        issues.append({"code": "malformed_atom_records", "count": parser_meta["malformed_atom_records"]})
+
+    residue_atoms: dict[tuple[Any, ...], list[dict[str, Any]]] = defaultdict(list)
+    component_atoms: dict[tuple[Any, ...], list[dict[str, Any]]] = defaultdict(list)
+    for atom in atoms:
+        residue_key = (
+            atom["model"], atom["chain"], atom["residue_id"], atom["insertion_code"], atom["resname"],
+        )
+        residue_atoms[residue_key].append(atom)
+        if atom["record"] == "HETATM":
+            component_atoms[residue_key].append(atom)
+
+    missing_backbone: list[dict[str, Any]] = []
+    chain_residues: dict[tuple[int, str], list[tuple[str, str, str]]] = defaultdict(list)
+    for (model_id, chain, residue_id, insertion_code, resname), values in residue_atoms.items():
+        if values[0]["record"] == "ATOM" or resname in STANDARD_AMINO_ACIDS or resname in MODIFIED_POLYMER:
+            chain_residues[(model_id, chain)].append((residue_id, insertion_code, resname))
+        if resname in STANDARD_AMINO_ACIDS:
+            present = {item["atom_name"] for item in values}
+            missing = sorted(BACKBONE - present)
+            if missing:
+                missing_backbone.append({
+                    "model": model_id,
+                    "chain": chain,
+                    "residue": f"{residue_id}{insertion_code}",
+                    "resname": resname,
+                    "missing": missing,
+                })
+    if missing_backbone:
+        warnings.append("Standard amino-acid residues with missing backbone atoms were detected.")
+        issues.append({"code": "missing_backbone_atoms", "count": len(missing_backbone)})
+
+    chain_gaps: list[dict[str, Any]] = []
+    for (model_id, chain), residues in sorted(chain_residues.items()):
+        numeric = sorted({int(item[0]) for item in residues if item[0].lstrip("-").isdigit()})
+        for left, right in zip(numeric, numeric[1:]):
+            if right - left > 1:
+                chain_gaps.append({"model": model_id, "chain": chain, "after": left, "before": right})
+    if chain_gaps:
+        warnings.append("Residue-number gaps were detected; they may represent missing density or numbering conventions.")
+
+    components: list[dict[str, Any]] = []
+    role_counts: Counter[str] = Counter()
+    for (model_id, chain, residue_id, insertion_code, resname), values in sorted(
+        component_atoms.items(), key=lambda item: (item[0][0], item[0][1], _residue_sort(item[0][2]), item[0][4]),
+    ):
+        role = component_role(resname, values[0]["record"], len(values))
+        role_counts[role] += 1
+        components.append({
+            "model": model_id,
+            "chain": chain,
+            "residue": f"{residue_id}{insertion_code}",
+            "component": resname,
+            "role": role,
+            "atom_count": len(values),
+            "elements": sorted({item["element"] for item in values if item["element"]}),
+        })
+
+    occupancies = [item["occupancy"] for item in atoms if item["occupancy"] is not None]
+    low_occupancy = sum(1 for value in occupancies if value < 0.5)
+    invalid_occupancy = sum(1 for value in occupancies if value < 0 or value > 1.01)
+    if low_occupancy:
+        issues.append({"code": "low_occupancy_atoms", "count": low_occupancy})
+    if invalid_occupancy:
+        warnings.append("Occupancy values outside the expected 0-1 range were detected.")
+        issues.append({"code": "invalid_occupancy_atoms", "count": invalid_occupancy})
+
+    chains = sorted({item["chain"] for item in atoms})
+    data = {
+        "file": proteus_common.display_path(source),
+        "format": fmt,
+        "compressed": source.name.lower().endswith(".gz"),
+        "selection": selection,
+        "counts": {
+            "raw_atoms": len(raw_atoms),
+            "selected_atoms": len(atoms),
+            "chains": len(chains),
+            "residues": len(residue_atoms),
+            "components": len(components),
+        },
+        "chains": chains,
+        "component_role_counts": dict(sorted(role_counts.items())),
+        "components": components,
+        "occupancy": {
+            "reported_atoms": len(occupancies),
+            "min": min(occupancies) if occupancies else None,
+            "max": max(occupancies) if occupancies else None,
+            "low_below_0_5": low_occupancy,
+        },
+        "missing_backbone": missing_backbone,
+        "numbering_gaps": chain_gaps,
+        "issues": issues,
+        "parser": parser_meta,
+    }
+    return proteus_common.ok_payload(
+        data,
+        warnings=warnings,
+        provenance={"input": proteus_common.file_provenance(source)},
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Preflight PDB/mmCIF coordinate quality and selection decisions.")
+    parser.add_argument("structure", help="PDB/mmCIF path, optionally .gz")
+    parser.add_argument("--model", default="first", help="Coordinate model: first, all, or integer (default: first)")
+    parser.add_argument("--altloc", default="highest", help="Alternate conformer: highest, all, or ID (default: highest)")
+    parser.add_argument("--json", action="store_true", help="Emit JSON (accepted for consistency; JSON is always emitted)")
+    args = parser.parse_args(argv)
+    try:
+        report = build_report(args.structure, model=args.model, altloc=args.altloc)
+    except (OSError, StructureQCError) as exc:
+        print(json.dumps(proteus_common.error_payload(str(exc)), indent=2))
+        return 1
+    print(json.dumps(report, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/sync_skill_package.py b/scripts/sync_skill_package.py
new file mode 100644
index 0000000..5d38df5
--- /dev/null
+++ b/scripts/sync_skill_package.py
@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""Synchronize or verify the installable skills/proteus package copy."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import shutil
+import sys
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+PACKAGE = ROOT / "skills" / "proteus"
+SOURCES = {
+    ROOT / "SKILL.md": PACKAGE / "SKILL.md",
+    ROOT / "agents" / "openai.yaml": PACKAGE / "agents" / "openai.yaml",
+}
+for directory in ("scripts", "references"):
+    for source in sorted((ROOT / directory).iterdir()):
+        if not source.is_file() or source.name == Path(__file__).name or source.suffix not in {".py", ".md"}:
+            continue
+        SOURCES[source] = PACKAGE / directory / source.name
+
+
+def _digest(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def compare() -> dict:
+    missing = []
+    changed = []
+    for source, target in SOURCES.items():
+        if not target.is_file():
+            missing.append(str(target.relative_to(ROOT)))
+        elif _digest(source) != _digest(target):
+            changed.append(str(target.relative_to(ROOT)))
+    expected = {target.resolve() for target in SOURCES.values()}
+    extra = []
+    for pattern in ("scripts/*.py", "references/*.md"):
+        for target in PACKAGE.glob(pattern):
+            if target.resolve() not in expected:
+                extra.append(str(target.relative_to(ROOT)))
+    return {"status": "ok" if not (missing or changed or extra) else "out_of_sync", "missing": missing, "changed": changed, "extra": extra}
+
+
+def sync() -> dict:
+    for source, target in SOURCES.items():
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(source, target)
+    expected = {target.resolve() for target in SOURCES.values()}
+    removed = []
+    for pattern in ("scripts/*.py", "references/*.md"):
+        for target in PACKAGE.glob(pattern):
+            if target.resolve() not in expected:
+                removed.append(str(target.relative_to(ROOT)))
+                target.unlink()
+    result = compare()
+    result["removed"] = removed
+    result["copied"] = len(SOURCES)
+    return result
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Verify or synchronize the installable Proteus package copy.")
+    mode = parser.add_mutually_exclusive_group(required=True)
+    mode.add_argument("--check", action="store_true", help="Fail if package files differ from canonical files")
+    mode.add_argument("--sync", action="store_true", help="Copy canonical files into skills/proteus")
+    parser.add_argument("--json", action="store_true", help="Emit JSON (accepted for consistency)")
+    args = parser.parse_args(argv)
+    report = sync() if args.sync else compare()
+    print(json.dumps(report, indent=2))
+    return 0 if report["status"] == "ok" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/visual_common.py b/scripts/visual_common.py
new file mode 100644
index 0000000..fe246f9
--- /dev/null
+++ b/scripts/visual_common.py
@@ -0,0 +1,248 @@
+#!/usr/bin/env python3
+"""Shared helpers for reproducible PyMOL and ChimeraX workflows."""
+
+from __future__ import annotations
+
+import csv
+import json
+import os
+import re
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import proteus_common
+
+
+IDENTIFIER_RE = re.compile(r"^[A-Za-z][A-Za-z0-9_]{0,63}$")
+COLOR_RE = re.compile(r"^(?:[A-Za-z][A-Za-z0-9_]{0,31}|#[0-9A-Fa-f]{6})$")
+STYLE_NAMES = {"cartoon", "sticks", "spheres", "surface", "lines", "ribbon"}
+
+
+class VisualWorkflowError(RuntimeError):
+    pass
+
+
+def identifier(value: str, *, field: str = "identifier") -> str:
+    if not IDENTIFIER_RE.fullmatch(value):
+        raise VisualWorkflowError(f"Invalid {field}: {value!r}")
+    return value
+
+
+def color(value: str) -> str:
+    if not COLOR_RE.fullmatch(value):
+        raise VisualWorkflowError(f"Invalid color: {value!r}")
+    return value
+
+
+def selection(value: str, *, field: str = "selection") -> str:
+    if not value or any(character in value for character in "\r\n;"):
+        raise VisualWorkflowError(f"Invalid {field}: selections cannot be empty or contain newlines/semicolons.")
+    return value
+
+
+def style(value: str) -> str:
+    if value not in STYLE_NAMES:
+        raise VisualWorkflowError(f"Unsupported representation style: {value}")
+    return value
+
+
+def quote_pymol(value: str | Path) -> str:
+    return '"' + str(value).replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def quote_chimerax(value: str | Path) -> str:
+    return '"' + str(value).replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def pymol_png(path: str | Path, *, width: int | None = None, height: int | None = None) -> list[str]:
+    """Write a PNG through the PyMOL Python API so quoted paths work reliably."""
+    options = []
+    if width is not None:
+        options.append(f"width={int(width)}")
+    if height is not None:
+        options.append(f"height={int(height)}")
+    suffix = ", " + ", ".join(options) if options else ""
+    return ["python", f"cmd.png({str(Path(path).resolve())!r}{suffix})", "python end"]
+
+
+def pymol_save(path: str | Path) -> list[str]:
+    """Save through the PyMOL Python API so quoted/session paths stay portable."""
+    return ["python", f"cmd.save({str(Path(path).resolve())!r})", "python end"]
+
+
+def find_pymol() -> str | None:
+    configured = os.environ.get("PYMOL_BIN", "")
+    return proteus_common.find_executable(
+        configured,
+        "pymol",
+        "/Applications/PyMOL.app/Contents/bin/pymol",
+        "~/Applications/PyMOL.app/Contents/bin/pymol",
+    )
+
+
+def find_chimerax() -> str | None:
+    configured = os.environ.get("CHIMERAX_BIN", "")
+    candidates = [
+        configured,
+        "ChimeraX",
+        "chimerax",
+        "/Applications/ChimeraX.app/Contents/bin/ChimeraX",
+    ]
+    applications = Path("/Applications")
+    if applications.is_dir():
+        candidates.extend(str(item / "Contents/bin/ChimeraX") for item in sorted(applications.glob("ChimeraX*.app"), reverse=True))
+    return proteus_common.find_executable(*candidates)
+
+
+def load_records(path: str | Path) -> list[dict[str, Any]]:
+    source = Path(path)
+    if not source.is_file():
+        raise VisualWorkflowError(f"File not found: {proteus_common.display_path(source)}")
+    if source.suffix.lower() == ".csv":
+        with source.open(newline="", encoding="utf-8-sig") as handle:
+            return [dict(row) for row in csv.DictReader(handle)]
+    payload = json.loads(source.read_text(encoding="utf-8"))
+    if isinstance(payload, list):
+        return [dict(item) for item in payload]
+    if isinstance(payload, dict):
+        for key in ("records", "annotations", "restraints", "scenes"):
+            value = payload.get(key)
+            if isinstance(value, list):
+                return [dict(item) for item in value]
+    raise VisualWorkflowError("Expected a CSV or JSON list of records.")
+
+
+def write_workflow(
+    outdir: str | Path,
+    name: str,
+    *,
+    report: dict[str, Any],
+    pymol_lines: list[str] | None = None,
+    chimerax_lines: list[str] | None = None,
+) -> dict[str, str]:
+    destination = Path(outdir)
+    destination.mkdir(parents=True, exist_ok=True)
+    outputs: dict[str, str] = {}
+    if pymol_lines is not None:
+        pml = destination / f"{name}.pml"
+        pml.write_text("\n".join(pymol_lines).rstrip() + "\n", encoding="utf-8")
+        outputs["pymol_script"] = proteus_common.display_path(pml)
+    if chimerax_lines is not None:
+        cxc = destination / f"{name}.cxc"
+        cxc.write_text("\n".join(chimerax_lines).rstrip() + "\n", encoding="utf-8")
+        outputs["chimerax_script"] = proteus_common.display_path(cxc)
+    report_path = destination / f"{name}.json"
+    outputs["report"] = proteus_common.display_path(report_path)
+    data = report.get("data")
+    if isinstance(data, dict):
+        data["artifacts"] = dict(outputs)
+    proteus_common.write_json(report_path, report)
+    return outputs
+
+
+def run_pymol(script_path: str | Path, *, timeout: int = 300) -> dict[str, Any]:
+    executable = find_pymol()
+    if not executable:
+        return {"status": "unavailable", "error": "PyMOL was not found."}
+    result = proteus_common.run_command([executable, "-c", "-q", str(Path(script_path).resolve())], timeout=timeout)
+    return execution_summary(result)
+
+
+def run_chimerax(commands: list[str], *, timeout: int = 600) -> dict[str, Any]:
+    executable = find_chimerax()
+    if not executable:
+        return {"status": "unavailable", "error": "ChimeraX was not found."}
+    env = os.environ.copy()
+    env["CHIMERAX_BIN"] = executable
+    command_text = ";".join(commands)
+    result = proteus_common.run_command(
+        [sys.executable, str(SCRIPT_DIR / "chimerax_rest.py"), "run", command_text],
+        timeout=timeout,
+        env=env,
+    )
+    if result.get("returncode") == 0:
+        try:
+            payload = json.loads(result.get("stdout") or "{}")
+        except json.JSONDecodeError:
+            payload = None
+        if isinstance(payload, dict) and payload.get("status") == "error":
+            result["status"] = "error"
+            result["error"] = payload.get("error", "ChimeraX workflow failed.")
+        elif payload is not None:
+            result["payload"] = payload
+    return execution_summary(result)
+
+
+def execution_summary(result: dict[str, Any]) -> dict[str, Any]:
+    """Return useful execution diagnostics without embedding commands or raw data."""
+    cleaned = proteus_common.scrub_private(result)
+    output: dict[str, Any] = {"status": cleaned.get("status", "error")}
+    if "returncode" in cleaned:
+        output["returncode"] = cleaned.get("returncode")
+    if cleaned.get("error"):
+        output["error"] = cleaned["error"]
+    payload = cleaned.get("payload")
+    if isinstance(payload, dict):
+        history = payload.get("data", {}).get("history") if isinstance(payload.get("data"), dict) else None
+        if isinstance(history, list):
+            output["commands_completed"] = len(history)
+            output["elapsed_seconds"] = round(sum(float(item.get("elapsed_seconds") or 0) for item in history if isinstance(item, dict)), 3)
+    if output["status"] != "ok":
+        for key in ("stderr", "stdout"):
+            value = cleaned.get(key)
+            if isinstance(value, str) and value.strip():
+                output[key] = value[-4000:]
+    return output
+
+
+def verify_nonempty(path: str | Path, *, attempts: int = 8, delay: float = 0.25) -> bool:
+    candidate = Path(path)
+    for _ in range(attempts):
+        if candidate.is_file() and candidate.stat().st_size > 0:
+            return True
+        time.sleep(delay)
+    return False
+
+
+def pymol_base(*, background: str = "white", width: int = 1200, height: int = 900) -> list[str]:
+    color(background)
+    return [
+        "reinitialize",
+        "set auto_zoom, 0",
+        f"bg_color {background}",
+        "set ray_opaque_background, 1",
+        "set antialias, 2",
+        "set cartoon_fancy_helices, 1",
+        "set cartoon_smooth_loops, 1",
+        "set cartoon_flat_sheets, 1",
+        "set ray_shadows, 1",
+        "set specular, 0.25",
+        "set ambient, 0.42",
+        f"viewport {int(width)}, {int(height)}",
+    ]
+
+
+def chimerax_base(*, background: str = "white") -> list[str]:
+    color(background)
+    return [f"set bgColor {background}", "lighting soft"]
+
+
+def finalize_pymol(output: str | Path, *, width: int = 1200, height: int = 900, session: str | Path | None = None) -> list[str]:
+    lines = ["orient", f"ray {int(width)}, {int(height)}", *pymol_png(output, width=width, height=height)]
+    if session is not None:
+        lines.extend(pymol_save(session))
+    lines.append("quit")
+    return lines
+
+
+def finalize_chimerax(output: str | Path, *, width: int = 1200, height: int = 900, session: str | Path | None = None) -> list[str]:
+    lines = ["view", f"save {quote_chimerax(Path(output).resolve())} width {int(width)} height {int(height)} supersample 3", "wait 1"]
+    if session is not None:
+        lines.append(f"save {quote_chimerax(Path(session).resolve())}")
+    return lines
diff --git a/skills/proteus/SKILL.md b/skills/proteus/SKILL.md
index 60bb956..2cb37f9 100644
--- a/skills/proteus/SKILL.md
+++ b/skills/proteus/SKILL.md
@@ -2,553 +2,213 @@
 name: proteus
 description: >
   Use this skill when the user asks you to work with protein structures,
-  molecular visualization, or structural biology tools. TRIGGER when:
-  the user mentions PyMOL, ChimeraX, AlphaFold, Rosetta, PyRosetta,
-  UniProt, RCSB PDB, PDBe, PDB files, protein structures, molecular
-  rendering, pLDDT, RMSD, structure alignment, binding pockets,
-  drug-target analysis, cryo-EM density maps, homology modeling, or
-  protein design. Also trigger when the user opens/loads .pdb, .cif,
-  .mmcif, .sdf, or .mol2 files, or .mrc density maps (see
-  references/chimerax.md for cryo-EM workflows).
-  DO NOT TRIGGER for: general biology questions with no structural component,
-  bioinformatics sequence-only tasks (BLAST, MSA), or genomics/transcriptomics.
+  molecular visualization, or structural biology tools. Trigger for PyMOL,
+  ChimeraX, AlphaFold, Rosetta/PyRosetta, UniProt, RCSB PDB, PDBe, PDB/mmCIF
+  files, molecular rendering, pLDDT, PAE, RMSD, structure alignment, binding
+  pockets, interfaces, variants, docking context, cryo-EM maps, ensembles,
+  restraints, or protein design. Also trigger when the user opens .pdb, .cif,
+  .mmcif, .sdf, .mol2, .mrc, .map, or .ccp4 files. Do not trigger for general
+  biology with no structural component, sequence-only bioinformatics, genomics,
+  or transcriptomics.
 ---
 
 # Proteus — Structural Biology Agent Skill
 
-You are an AI agent driving structural biology tools programmatically.
-This skill teaches you how to control PyMOL, ChimeraX, AlphaFold DB,
-and Rosetta/PyRosetta from the command line — including the non-obvious
-gotchas that will otherwise cost hours of debugging.
-
-## Tool Detection
-
-Before doing anything, detect what's installed:
-
-```python
-import shutil, subprocess
-
-PYMOL = shutil.which("pymol")
-if not PYMOL:
-    # macOS common locations
-    import os
-    for p in ["/Applications/PyMOL.app/Contents/bin/pymol",
-              os.path.expanduser("~/Applications/PyMOL.app/Contents/bin/pymol")]:
-        if os.path.isfile(p):
-            PYMOL = p
-            break
-
-CHIMERAX = shutil.which("ChimeraX") or shutil.which("chimerax")
-if not CHIMERAX:
-    import glob
-    hits = glob.glob("/Applications/ChimeraX*.app/Contents/bin/ChimeraX")
-    if hits:
-        CHIMERAX = sorted(hits)[-1]  # latest version
-```
-
-If neither is found, do not guess paths. Continue with zero-dependency workflows
-(`scripts/pdb_info.py`, AlphaFold metadata fetches, file inspection) when they
-fit the task; otherwise tell the user what to install and stop.
-
-Run helper scripts from the repo or skill root with Python 3.10+:
+Use Proteus to turn structural-biology questions into inspectable analyses,
+figures, sessions, and replayable PyMOL (`.pml`) or ChimeraX (`.cxc`) commands.
+Prefer the included helper workflows over improvised command strings.
+
+## Safety and Scientific Ground Rules
+
+- Treat local structures, maps, annotations, sequences, and restraints as private
+  unless the user identifies them as public. Do not upload private or unpublished
+  inputs to a web service without explicit authorization.
+- Public identifiers such as PDB, EMDB, UniProt, and AlphaFold DB accessions may
+  be resolved through their public APIs when network access is needed. Say which
+  source was used and preserve provenance.
+- Keep secrets, credentials, arbitrary absolute paths, raw private data, and
+  machine-specific details out of reports, logs, manifests, and repository files.
+- Never use a protein-structure result as the sole basis for a clinical, safety,
+  efficacy, or patient-specific decision. Flag medical or biosafety implications
+  and recommend appropriate expert review.
+- Separate observation from inference. A short distance is a geometric contact,
+  not proof of a hydrogen bond, energetic hotspot, catalytic role, binding
+  affinity, biological assembly, or causal variant effect.
+- State uncertainty from resolution, missing atoms/residues, alternate
+  conformers, occupancy, protonation, tautomerism, model confidence, chain
+  mapping, alignment coverage, map processing, and assembly choice when relevant.
+- Do not overwrite source coordinates. Write generated artifacts to a dedicated
+  output directory and keep scripts/sessions so the result can be audited.
+
+## Start Here
+
+Run scripts from the skill or repository root with Python 3.10+.
 
 ```bash
-cd <proteus-skill-or-repo-root>
-python3 scripts/proteus_doctor.py --network --json
+python3 scripts/proteus.py --help
+python3 scripts/proteus.py qc structure.cif --json
 ```
 
-On macOS, `/usr/bin/python3` may be 3.9 and too old for several helpers. Use a
-Homebrew, conda, pyenv, or system Python 3.10+ interpreter when the doctor marks
-Python as too old. Hardened launchers that set `PYTHONSAFEPATH=1` are supported:
-the helper entrypoints add their bundled `scripts/` directory before importing
-sibling modules.
+Do not run network checks merely because the skill was invoked. Use
+`scripts/proteus_doctor.py --json` for local readiness, and add `--network` only
+when the task actually needs public APIs.
 
-If PyMOL or ChimeraX are installed as macOS apps, the doctor can often find their
-app-bundle binaries even when they are not on `PATH`. For direct shell use, add
-the actual app `Contents/bin` directory to `PATH`. Install `ffmpeg` for spin
-movies. Confirm PyMOL is licensed before publishing renders because evaluation
-builds can watermark output.
+Before using a helper, run its `--help`. Treat helpers as black boxes unless
+debugging or changing the implementation.
 
-## Tool Selection — When to Use What
-
-| Task | Best Tool | Why |
-|---|---|---|
-| Headless rendering (no display) | **PyMOL** | Software ray tracer works fully headless |
-| Interactive demo with live GUI | **ChimeraX REST API** | HTTP control of running GUI session |
-| H-bonds, SASA, clashes, contacts | **ChimeraX** | Built-in analysis commands, even in `--nogui` |
-| Structure alignment + RMSD | **Either** | PyMOL `cealign` or ChimeraX `matchmaker` |
-| AlphaFold confidence analysis | **PyMOL** + AlphaFold API | Fetch prediction, color by pLDDT, render headless |
-| Experimental PDB download | **`fetch_pdb.py`** | RCSB metadata + coordinates |
-| Structure landscape search | **`pdb_search.py`** | Enumerate PDB hits by text and/or UniProt accession |
-| Structure candidate ranking | **`pdb_select.py`** | Rank hits by method, resolution, validation, assemblies, and ligands |
-| Protein name -> accession | **`uniprot_lookup.py`** | Resolve names/genes before AlphaFold fetch |
-| PDB/mmCIF preflight | **`structure_info.py`** | Zero-dependency file inspection |
-| Target dossier/report | **`target_dossier.py`** | Markdown + JSON provenance for targets, with opt-in local analyses |
-| Structural mutation triage | **`mutation_triage.py`** | Local variant proximity to ligands, interfaces, contacts, and PAE context |
-| Docking box prep | **`docking_box.py`** | Ligand-centered Vina box plus optional docking-tool detection |
-| Cryo-EM density map visualization | **ChimeraX REST API** | Volume rendering requires GPU/display |
-| Quick legacy PDB inspection | **`pdb_info.py` script** | Backward-compatible PDB-only inspector |
-| KRAS G12C dossier | **`kras_dossier.py`** | End-to-end workflow with public structures, analyses, and figures |
-| Protein design / scoring | **Rosetta/PyRosetta** | Or ML alternatives (ProteinMPNN, RFdiffusion) |
-
-**Key architectural insight:** ChimeraX `--nogui` mode has NO OpenGL context on macOS.
-It can run analysis commands (H-bonds, SASA, matchmaker, info) but CANNOT render images.
-For ChimeraX rendering, you must use the REST API approach with a running GUI instance.
+## Workflow Routing
 
-## Reading Guide
-
-Load reference files on demand — don't read all of them upfront:
-
-| Working with... | Read this file |
+| User goal | Preferred workflow |
 |---|---|
-| PyMOL (any task) | `references/pymol.md` |
-| ChimeraX (any task) | `references/chimerax.md` |
-| AlphaFold DB predictions | `references/alphafold.md` |
-| PDB/UniProt/PDBe/RCSB data lookup | `references/data-sources.md` |
-| File format choices (.pdb, .cif, .sdf, .mrc) | `references/file-formats.md` |
-| Prediction models beyond AlphaFold DB | `references/prediction-models.md` |
-| Rosetta / protein design | `references/rosetta.md` |
-
-## Agent Helper Scripts
-
-These scripts handle the hard parts of tool communication.
-
-**IMPORTANT: Always run `python3 scripts/<script>.py --help` first.** Treat the
-scripts as black-box utilities by default. Only read the source when you are
-debugging, patching, or the help text is insufficient for the task.
-
-| Script | Purpose | Example |
+| Preflight models, conformers, occupancy, components | `proteus.py qc` |
+| Reproducible publication figure or saved scene | `proteus.py figure` |
+| Apo/holo, WT/mutant, or pose comparison | `proteus.py compare` |
+| Residue/variant local environment | `proteus.py residue` |
+| Protein-protein interface story | `proteus.py interface` |
+| Per-residue annotations or score overlays | `proteus.py annotate` |
+| Distance restraints/crosslinks | `proteus.py restraints` |
+| Assembly and crystal-neighbor comparison | `proteus.py assembly` |
+| Cryo-EM contour sweep, fit, map/model review | `proteus.py cryoem` |
+| Multi-model ensemble variability | `proteus.py ensemble` |
+| Qualitative electrostatic surface | `proteus.py electrostatics` |
+| Optional fpocket/P2Rank detection | `proteus.py pockets` |
+| Ligand, cofactor, metal, or water site | `proteus.py chemical-site` |
+| Fetch/resolve public coordinates | `resolve_structure.py`, `fetch_pdb.py`, `fetch_alphafold.py` |
+| PAE or model-quality metrics | `pae_report.py`, `model_quality.py` |
+| Docking preparation and interaction triage | `dock_prep.py`, `docking_box.py`, `dock_vina.py`, `interaction_report.py` |
+| Design planning or Rosetta score parsing | `design_run.py`, `rosetta_score.py` |
+
+Read `references/workflows.md` for inputs, examples, output contracts, scene
+manifests, and human-handoff patterns.
+
+## Choosing PyMOL or ChimeraX
+
+| Task | Default | Reason |
 |---|---|---|
-| `scripts/proteus_doctor.py` | Local readiness report for tools, scripts, and APIs | `python3 scripts/proteus_doctor.py --network --json` |
-| `scripts/resolve_structure.py` | Resolve file/PDB/UniProt/name to structure + provenance | `python3 scripts/resolve_structure.py TP53 --json` |
-| `scripts/fetch_pdb.py` | RCSB PDB metadata + coordinate fetcher | `python3 scripts/fetch_pdb.py 4HHB --json` |
-| `scripts/assembly_report.py` | RCSB biological assembly counts, filenames, URLs, and optional assembly mmCIF download | `python3 scripts/assembly_report.py 4HHB --json` |
-| `scripts/pdb_search.py` | Search RCSB PDB by free text and/or UniProt accession | `python3 scripts/pdb_search.py "KRAS G12C" --rows 10 --details --json` |
-| `scripts/pdb_select.py` | Rank/select candidate structures from offline metadata or opt-in RCSB lookup | `python3 scripts/pdb_select.py --input candidates.json --json` |
-| `scripts/sifts_map.py` | PDBe SIFTS residue mapping between PDB chains and UniProt ranges | `python3 scripts/sifts_map.py pdb 1hsg --json` |
-| `scripts/ligand_extract.py` | Zero-dep non-water ligand inventory from PDB/mmCIF and optional CCD downloads | `python3 scripts/ligand_extract.py 1HSG --json` |
-| `scripts/dock_prep.py` | Non-executing receptor/ligand prep plan with optional tool detection | `python3 scripts/dock_prep.py --receptor receptor.pdb --ligand ligand.sdf --json` |
-| `scripts/docking_box.py` | Ligand-centered PDB/mmCIF Vina-style box and optional docking-tool detection | `python3 scripts/docking_box.py complex.cif --ligand ATP --json` |
-| `scripts/dock_vina.py` | Dry-run Vina-compatible docking command planner and log parser | `python3 scripts/dock_vina.py plan --receptor receptor.pdbqt --ligand ligand.pdbqt --config box.txt --json` |
-| `scripts/interaction_report.py` | Simple PDB/mmCIF protein-ligand interaction/contact classes plus PLIP/ProLIF detection | `python3 scripts/interaction_report.py complex.cif --ligand ATP --json` |
-| `scripts/variant_map.py` | Conservative protein substitution parser plus optional local coordinate lookup | `python3 scripts/variant_map.py "P04637 R175H" --no-download --json` |
-| `scripts/mutation_triage.py` | Local structural triage of substitutions against ligands, chains, contacts, and PAE | `python3 scripts/mutation_triage.py R175H --structure model.pdb --json` |
-| `scripts/proteus_batch.py` | Run allowlisted helper scripts from a JSON manifest | `python3 scripts/proteus_batch.py manifest.json --dry-run --json` |
-| `scripts/proteus_cache.py` | Local URL cache with checksums, offline mode, verify, and garbage collection | `python3 scripts/proteus_cache.py show --json` |
-| `scripts/proteus_report.py` | Combine helper JSON into Markdown and scrubbed report JSON evidence packs | `python3 scripts/proteus_report.py --input result.json --json` |
-| `scripts/target_dossier.py` | Generic target dossier with Markdown, JSON provenance, and opt-in local analyses | `python3 scripts/target_dossier.py --uniprot P04637 --no-network --json` |
-| `scripts/uniprot_lookup.py` | Protein/gene name to UniProt accession | `python3 scripts/uniprot_lookup.py TP53 --gene-exact --json` |
-| `scripts/structure_info.py` | Zero-dep PDB/mmCIF inspector | `python3 scripts/structure_info.py structure.cif --json` |
-| `scripts/fetch_alphafold.py` | AlphaFold DB fetcher | `python3 scripts/fetch_alphafold.py P04637 --pae --json` |
-| `scripts/pae_report.py` | Summarize AlphaFold PAE domain/flexibility hints | `python3 scripts/pae_report.py AF-P04637-F1_pae.json --json` |
-| `scripts/validation_report.py` | Fetch wwPDB/RCSB validation quality metrics | `python3 scripts/validation_report.py 4HHB --json` |
-| `scripts/pocket_report.py` | Zero-dep ligand pocket contacts from local PDB/mmCIF or PDB ID | `python3 scripts/pocket_report.py complex.cif --json` |
-| `scripts/interface_report.py` | Zero-dep protein-protein interface residues from local PDB/mmCIF or PDB ID | `python3 scripts/interface_report.py 1BRS --chains A,D --json` |
-| `scripts/compare_structures.py` | PyMOL CE alignment + optional per-residue deviations | `python3 scripts/compare_structures.py ref.pdb mobile.pdb --json` |
-| `scripts/pymol_agent.py` | Headless PyMOL driver (info, render, **pocket figure, density fit, spin movie**) | `python3 scripts/pymol_agent.py render structure.pdb out.png --color plddt` |
-| `scripts/chimerax_agent.py` | Headless ChimeraX driver (analysis, `--nogui`) | `python3 scripts/chimerax_agent.py run "open 1ubq; info chains #1"` |
-| `scripts/chimerax_rest.py` | Managed ChimeraX REST GUI render (GPU) + turntable | `python3 scripts/chimerax_rest.py render structure.pdb out.png --color plddt` |
-| `scripts/add_helix_records.py` | Add HELIX records to CA-only backbones so cartoons render | `python3 scripts/add_helix_records.py model.pdb --json` |
-| `scripts/map_info.py` | MRC/CCP4 map stats + sigma-based contour levels | `python3 scripts/map_info.py map.mrc --json` |
-| `scripts/model_quality.py` | Detect optional quality tools and parse/run USalign when installed | `python3 scripts/model_quality.py detect --json` |
-| `scripts/design_run.py` | Validate design manifests and write dry-run modeling/design plans | `python3 scripts/design_run.py manifest.json --dry-run --json` |
-| `scripts/rosetta_score.py` | Detect Rosetta/PyRosetta, parse scorefiles, and plan dry scoring commands | `python3 scripts/rosetta_score.py detect --json` |
-| `scripts/pdb_info.py` | Legacy zero-dep PDB inspector (PDB only) | `python3 scripts/pdb_info.py structure.pdb` |
-| `scripts/kras_dossier.py` | KRAS G12C dossier workflow over public structures | `python3 scripts/kras_dossier.py --out kras_g12c_dossier --no-movie` |
-
-## Critical Gotchas (Read This First)
-
-These are hard-won discoveries. Each one represents hours of debugging that you
-can skip by knowing them upfront.
-
-### PyMOL
-
-1. **Never use the `-d` flag for complex commands.** The shell interprets `>`, `<`,
-   and `|` in PyMOL selection syntax as redirection/pipe operators. Instead, write
-   a `.pml` script file and run `pymol -c -q script.pml`.
-
-   ```python
-   # WRONG — breaks on selections like "b > 90"
-   subprocess.run(["pymol", "-c", "-q", "-d", 'color blue, b > 90'])
-
-   # RIGHT — write a .pml file
-   with open("/tmp/cmd.pml", "w") as f:
-       f.write("color blue, b > 90\n")
-   subprocess.run(["pymol", "-c", "-q", "/tmp/cmd.pml"])
-   ```
-
-   **Why:** The `-d` flag passes the string through the shell, where `>` becomes
-   stdout redirection. This is never mentioned in PyMOL documentation.
-
-2. **PyMOL stdout is unreliable.** `print()` in headless mode doesn't always
-   capture to stdout. Always write results to a JSON temp file and read it back
-   from the calling process.
-
-3. **`cmd.quit()` is required** at the end of every headless script. Without it,
-   the PyMOL process hangs indefinitely.
-
-4. **`<=` doesn't exist in PyMOL selection syntax.** For pLDDT coloring, use
-   layered overrides — paint the broadest range first, then override with
-   narrower selections. `scripts/pymol_agent.py --color plddt` detects 0-1
-   and 0-100 B-factor/pLDDT scales before applying these bins:
-   ```
-   color orange, all           # base: everything is low confidence
-   color yellow, b > 50        # override: medium
-   color cyan, b > 70          # override: high
-   color blue, b > 90          # override: very high
-   ```
-   Use `--color bfactor` for an autoscaled spectrum when the B-factor column is
-   not a confidence score or the scale is unknown.
-
-5. **`cealign` argument order is (target, mobile).** The first argument is
-   the reference that stays fixed; the second gets moved. This is opposite
-   to what you might expect.
-
-6. **`cmd.iterate` vs `cmd.iterate_state`:** Use `iterate` for molecular
-   properties (chain, resname, B-factor). Use `iterate_state` for 3D
-   coordinates (x, y, z). Using the wrong one silently returns nothing.
-
-7. **GUI demos require threading.** Running a long script in PyMOL's main
-   thread freezes the GUI completely. Wrap your demo in
-   `threading.Thread(target=run, daemon=True).start()`.
-
-8. **In GUI mode, `print()` goes to PyMOL's internal console**, not the
-   terminal. Use `sys.stderr.write(text + "\n")` for terminal output.
-
-9. **`Path(__file__)` is unreliable** inside PyMOL's `-r` runner. Use
-   hardcoded absolute paths or resolve paths before launching PyMOL.
-
-### ChimeraX
-
-10. **ChimeraX `--nogui` CANNOT render images on macOS.** There is no
-    OpenGL context. Use it only for analysis. For rendering, use the
-    REST API with a GUI session (see `references/chimerax.md`).
-
-11. **ChimeraX is NOT thread-safe.** Sending REST API calls from a Python
-    background thread causes `EXC_BAD_ACCESS` crashes. All REST calls must
-    happen from the main thread.
-
-12. **`close session` does NOT reset model IDs.** After closing and reopening
-    structures, model IDs continue incrementing (#1, #2, #3...). The only
-    way to reset to #1 is a full process restart. Always use dynamic model
-    ID discovery after each `open` command.
-
-13. **Cryo-EM gotchas:** Use `lighting simple` (not `full`) for volume
-    maps — `full` washes out colors on white. Never `close` a map
-    mid-session — it shifts all model IDs. Use `hide`/`show` instead.
-    See `references/chimerax.md` for full cryo-EM patterns.
-
-14. **stdout lines have `INFO:`/`WARNING:`/`ERROR:` prefixes.** Parse them
-    out. Also filter lines starting with `INFO: Executing:` — those are
-    echoed commands, not results.
-
-### AlphaFold DB
-
-15. **The API returns a list, not a dict.** `json.loads(response)` gives
-    `[{...}]`. You must do `data[0]["pdbUrl"]`, not `data["pdbUrl"]`.
-
-16. **Always query `latestVersion` from the API.** Don't hardcode `v4` or
-    `v6` in URLs — the version changes and old URLs return 404.
-
-17. **P62988 (ubiquitin) is NOT in the database.** Use P0CG48
-    (polyubiquitin-C, 685 residues) instead. Note: this is the full
-    polyubiquitin chain, not the 76-residue monomer.
-
-### Rendering, Animation & Maps
-
-18. **PyMOL spin loops need `set cache_frames, 0`.** Otherwise PyMOL caches
-    every ray-traced frame in RAM and the process is OOM-killed partway through
-    a turntable. Set it before the render loop. (`pymol_agent.py spin` does this
-    for you.)
-
-19. **`set auto_zoom, 0` before loading when composing a manual view.** Each
-    `load`/`show` otherwise re-zooms and fights your `orient`/`zoom`/`turn`
-    framing. Set it first, frame last.
-
-20. **Whole-map isosurfaces stall in headless PyMOL.** The headless build lacks
-    the VTKm accelerator, so contouring a full density map can hang for minutes
-    even on a small map. Carve the mesh around the model
-    (`isomesh m, map, level, sele, carve=2.5`) or do the whole-map surface in
-    ChimeraX. Use `scripts/map_info.py` to pick a sigma-based contour level.
-
-21. **ChimeraX REST `save` can return before the PNG is flushed** — a 0-byte
-    file, worse under heavy cartoon recompute. After `save`, issue `wait 1` and
-    poll the file for non-zero size, retrying a few times.
-    (`scripts/chimerax_rest.py` handles this.)
-
-22. **ChimeraX color-name traps.** `gold`/`yellow` atom spheres often render
-    visibly green — use `orange` for a true gold read. And `color #1 cartoons #...`
-    silently mis-parses `cartoons` as a color: the command is `cartoon`, then
-    `color #1 <color>`.
-
-23. **Deposited coordinates are the asymmetric unit, not necessarily the
-    biological assembly.** A "dimer" entry may deposit a single chain. Build the
-    functional oligomer with ChimeraX `sym #1 assembly 1 copies true`, or expand
-    crystal neighbors in PyMOL with `symexp mate_, obj, sele, 5`.
-
-## Common Workflows
-
-### Quick Structure Inspection
-```bash
-python3 scripts/structure_info.py structure.cif --json  # zero-dep PDB/mmCIF overview
-python3 scripts/pdb_info.py structure.pdb               # legacy PDB-only overview
-python3 scripts/pymol_agent.py info structure.pdb       # detailed with PyMOL
-```
-
-### Experimental Structure Fetch
-```bash
-python3 scripts/fetch_pdb.py 4HHB --json                # RCSB metadata + mmCIF
-python3 scripts/fetch_pdb.py 1HSG --format pdb          # legacy PDB format if needed
-python3 scripts/assembly_report.py 4HHB --json          # assembly counts + download URLs
-python3 scripts/fetch_pdb.py 4HHB --assembly 1 --json   # biological assembly mmCIF
-```
-
-### Structure Landscape Search
-```bash
-python3 scripts/pdb_search.py "KRAS G12C sotorasib" --rows 10 --details --json
-python3 scripts/pdb_search.py --uniprot P01116 --rows 50 --details --json
-python3 scripts/pdb_select.py --input candidates.json --ligand GDP --json
-```
-
-### Residue Mapping, Variants, And Ligands
-```bash
-python3 scripts/sifts_map.py pdb 1hsg --json
-python3 scripts/variant_map.py "P04637 R175H" --no-download --json
-python3 scripts/mutation_triage.py R175H --uniprot P04637 --structure model.pdb --json
-python3 scripts/ligand_extract.py 1HSG --json
-python3 scripts/dock_prep.py --receptor receptor.pdb --ligand ligand.sdf --json
-python3 scripts/docking_box.py complex.pdb --ligand ATP --json
-python3 scripts/dock_vina.py plan --receptor receptor.pdbqt --ligand ligand.pdbqt --config box.txt --json
-python3 scripts/interaction_report.py complex.pdb --ligand ATP --json
-```
-
-### Dossiers And Batch Runs
-```bash
-python3 scripts/target_dossier.py --gene TP53 --uniprot P04637 --pdb 1TUP --json
-python3 scripts/target_dossier.py --pdb structure.pdb --no-network --json
-python3 scripts/target_dossier.py --pdb structure.pdb --no-network --analyze-local --json
-python3 scripts/proteus_batch.py manifest.json --dry-run --json
-python3 scripts/proteus_report.py --input result.json --outdir proteus_report_out --json
-python3 scripts/proteus_cache.py verify --json
-python3 scripts/design_run.py design_manifest.json --dry-run --json
-```
-
-### AlphaFold Confidence Analysis
-```bash
-python3 scripts/uniprot_lookup.py TP53 --gene-exact --json  # resolve accession if needed
-python3 scripts/fetch_alphafold.py P04637 --pae --json       # fetch p53 prediction
-# Output filename uses modelEntityId from API, typically AF-{UNIPROT}-F1.pdb
-python3 scripts/pae_report.py AF-P04637-F1_pae.json --json   # summarize domain uncertainty
-python3 scripts/pymol_agent.py render AF-P04637-F1.pdb output.png --color plddt
-```
-For non-AlphaFold models with normalized 0-1 confidence in the B-factor column,
-`--color plddt` detects the scale. Use `--color bfactor` for an autoscaled view
-when B-factors are not confidence values. See `references/alphafold.md` for the
-standard color scheme.
+| Headless ray-traced rendering | PyMOL | Software ray tracer works without a display |
+| GPU volume/surface rendering | ChimeraX managed REST | Strong map and surface tooling |
+| H-bonds, contacts, clashes, SASA, buried area | ChimeraX | Built-in analysis commands |
+| Scriptable publication scenes | Either | Proteus emits replayable scripts and sessions |
+| Live interactive handoff | ChimeraX REST or saved session | User can continue in the GUI |
+| Structural alignment | Either | Choose by metric and downstream rendering needs |
+
+On macOS, ChimeraX `--nogui` can analyze but cannot render because it lacks an
+OpenGL context. Use `scripts/chimerax_agent.py` for headless analysis and
+`scripts/chimerax_rest.py` or a generated workflow with `--execute` for GUI/GPU
+rendering. PyMOL headless rendering works on macOS and Linux.
+
+## Standard Operating Pattern
+
+1. Resolve the input identity and numbering system. Do not assume UniProt,
+   author, label, and construct residue numbers are interchangeable.
+2. Run `proteus.py qc` before geometry-sensitive analysis. Choose a model and
+   alternate-conformer policy explicitly when multiple states are present.
+3. Confirm whether the task needs the asymmetric unit, a biological assembly,
+   crystal neighbors, or a predicted monomer/complex.
+4. Choose the narrowest workflow that answers the question. Keep network use
+   and optional external tools explicit.
+5. Generate scripts and a JSON report first. Execute rendering or optional tools
+   only when needed; retain `.pml`/`.cxc` and `.pse`/`.cxs` handoff artifacts.
+6. Verify expected outputs are non-empty. Report measurements, provenance,
+   selection/model decisions, limitations, and missing capabilities.
+
+## Core Helpers
+
+The unified entry point covers the main user workflows:
 
-### Predicted vs Experimental Comparison
-1. Fetch AlphaFold prediction for the protein's UniProt ID
-2. Load both structures in PyMOL
-3. Use `cealign` (not `align`) — it's purely structural, works for divergent sequences
-4. Extract per-residue deviations with `iterate_state`
-5. Render side-by-side or overlay
-
-When external quality tools are installed, use `scripts/model_quality.py` to
-detect them or parse/run USalign:
-
-```bash
-python3 scripts/model_quality.py detect --json
-python3 scripts/model_quality.py usalign reference.pdb mobile.pdb --json
-python3 scripts/rosetta_score.py detect --json
-python3 scripts/rosetta_score.py parse-scorefile score.sc --json
-```
-
-### Protein-Protein Interface Analysis
-```bash
-# Zero-dependency: interface residues between chains, JSON for chaining
-python3 scripts/interface_report.py complex.cif --json            # all chain pairs
-python3 scripts/interface_report.py 1BRS --chains A,D --cutoff 4.5 --json
-python3 scripts/interface_report.py complex.cif --residue A:42 --json
-```
-For a visual interface dissection (contacts/H-bonds/buried surface), use
-ChimeraX — see `references/chimerax.md`.
-
-### Binding Pocket Analysis
-```bash
-# One-command annotated figure: ligand + pocket sticks + polar contacts + context
-python3 scripts/pymol_agent.py pocket 1HSG.pdb pocket.png --label
-# Docking-box handoff around known ligand atoms
-python3 scripts/dock_prep.py --receptor receptor.pdb --ligand ligand.sdf --json
-python3 scripts/docking_box.py 1HSG --ligand MK1 --padding 6 --json
-python3 scripts/dock_vina.py plan --receptor receptor.pdbqt --ligand ligand.pdbqt --config vina_box.txt --json
-python3 scripts/dock_vina.py parse-log vina.log --json
-# Contact classes for a ligand group
-python3 scripts/interaction_report.py 1HSG --ligand MK1 --json
-```
-```python
-# Or build it by hand. PyMOL: select residues within 5A of any ligand
-cmd.select("pocket", "byres organic around 5")
-# Show pocket as sticks, ligand as ball-and-stick
-cmd.show("sticks", "pocket")
-cmd.show("spheres", "organic")
-cmd.set("sphere_scale", 0.25, "organic")
-```
-
-### ChimeraX Interactive Demo (REST API)
-```bash
-# 1. Launch ChimeraX with REST
-/path/to/ChimeraX --cmd "remotecontrol rest start port 50888" &
-
-# 2. Verify connection
-curl -s "http://127.0.0.1:50888/run?command=version"
-
-# 3. Send commands
-curl "http://127.0.0.1:50888/run?command=open+1ubq"
-curl "http://127.0.0.1:50888/run?command=cartoon"
-curl "http://127.0.0.1:50888/run?command=save+/tmp/render.png+width+1200+height+900+supersample+3"
-```
-
-### Publication-Quality Rendering (PyMOL)
-```
-set bg_color, white
-set ray_opaque_background, 1
-set antialias, 2
-set cartoon_fancy_helices, 1
-set cartoon_smooth_loops, 1
-set cartoon_flat_sheets, 1
-ray 1200, 900
-png output.png
-```
-
-Render presets are also available on the helper: `pymol_agent.py render file.pdb
-out.png --preset publication|illustration|soft --color spectrum|chain|bfactor|plddt`.
-
-### Turntable Movie (Headless)
 ```bash
-# PyMOL ray-traces each frame (works with no display); ffmpeg encodes them.
-python3 scripts/pymol_agent.py spin structure.pdb spin.mp4 --frames 60 --color plddt
-# Degrades gracefully: with no ffmpeg, the frames are written and returned.
-```
-This is the macOS-correct path — ChimeraX needs a GPU/GUI context to render.
+python3 scripts/proteus.py figure scene.json --outdir figure --execute
+python3 scripts/proteus.py compare apo.pdb holo.pdb --outdir comparison
+python3 scripts/proteus.py residue model.cif A:42 --outdir residue_42
+python3 scripts/proteus.py interface complex.cif --chains A,B --execute
+python3 scripts/proteus.py annotate model.pdb scores.csv --execute
+python3 scripts/proteus.py restraints model.pdb restraints.csv --execute
+python3 scripts/proteus.py assembly 4HHB --assembly 1 --execute
+python3 scripts/proteus.py cryoem model.cif map.mrc --resolution 3.2 --fit --execute
+python3 scripts/proteus.py ensemble models.pdb --execute
+python3 scripts/proteus.py electrostatics model.pdb --execute
+python3 scripts/proteus.py pockets model.pdb --detector auto --execute --render
+python3 scripts/proteus.py chemical-site complex.cif --component ZN:A:501 --execute
+```
+
+Additional focused helpers include:
+
+- `resolve_structure.py`: local file, PDB ID, UniProt accession, or name to a
+  local structure with provenance.
+- `pdb_search.py` and `pdb_select.py`: search and rank experimental candidates.
+- `assembly_report.py`, `sifts_map.py`, and `validation_report.py`: assembly,
+  residue mapping, and experimental validation context.
+- `ligand_extract.py`, `pocket_report.py`, and `interaction_report.py`: ligand
+  inventory and zero-dependency contact triage.
+- `mutation_triage.py`: variant proximity to ligands, interfaces, contacts, and
+  PAE context.
+- `model_quality.py`: USalign, DockQ, and local Foldseek wrappers when installed.
+- `proteus_batch.py`, `proteus_cache.py`, and `proteus_report.py`: allowlisted
+  batches, cached public responses, and evidence packs.
+
+## Interpretation Rules by Data Type
+
+- **AlphaFold pLDDT:** confidence in local structure, not stability or function.
+  Use per-residue C-alpha values when available. Low pLDDT may indicate disorder,
+  context dependence, or prediction uncertainty.
+- **PAE:** directional expected alignment error. Use chain-aware blocks for
+  complexes and do not call high inter-chain PAE proof that chains do not bind.
+- **RMSD/TM-score:** always report alignment method, aligned length/coverage,
+  chain mapping, and normalization. A single global RMSD can hide local changes.
+- **DockQ:** review model/native chain mapping and each interface, not only the
+  aggregate score.
+- **Contacts/interfaces:** distance cutoffs generate candidates. Protonation,
+  donor/acceptor geometry, solvation, conformational state, and assembly choice
+  determine meaning.
+- **Cryo-EM:** contour levels are map-specific absolute values. Fitting and
+  difference maps depend on initial placement, resolution, sharpening, masking,
+  and scale; avoid overfitting.
+- **Electrostatics:** ChimeraX Coulombic coloring is qualitative. For stronger
+  claims, prepare protonation/charges and use a validated Poisson-Boltzmann
+  workflow such as PDB2PQR/APBS.
+- **Pockets/tunnels:** detector scores are hypotheses, not affinity estimates.
+  Compare conformational states and add experimental/evolutionary evidence.
+
+## Critical Execution Gotchas
+
+- Write complex PyMOL commands to `.pml`; do not pass selections containing
+  comparison operators through `pymol -d`.
+- End headless PyMOL scripts with `quit`; use `iterate_state` for coordinates.
+- PyMOL `cealign` argument order is target/reference first, mobile second.
+- Use layered `b > 50`, `b > 70`, `b > 90` overrides for pLDDT; PyMOL has no
+  `<=` selection operator.
+- ChimeraX model IDs do not reset after `close session`. Generated workflows use
+  a fresh managed session; otherwise discover model IDs dynamically.
+- For ChimeraX REST image saves, issue `wait 1` and verify the file is non-empty.
+- Avoid whole-map PyMOL isosurfaces; carve around the model or use ChimeraX.
+- Deposited coordinates are usually an asymmetric unit, not automatically the
+  biological assembly.
 
-### ChimeraX GPU Rendering (Managed REST)
-```bash
-# Launches a GUI ChimeraX on an ephemeral port, renders via GPU, tears down.
-python3 scripts/chimerax_rest.py render structure.pdb out.png --style surface --color bychain
-python3 scripts/chimerax_rest.py spin structure.pdb out.mp4 --frames 72
-```
-Unlike `chimerax_agent.py` (analysis only, `--nogui`), this renders images and
-defeats the 0-byte-PNG save race (gotcha 21).
-
-### CA-only Backbone (de-novo designs)
-```bash
-# RFdiffusion / Genie backbones render as spaghetti without HELIX records.
-python3 scripts/add_helix_records.py model.pdb -o model_ss.pdb --json
-# Then render model_ss.pdb; in PyMOL also: set cartoon_trace_atoms, 1
-```
-
-### Cryo-EM Density Fit
-```bash
-# Sigma-based contour level (absolute level differs per map).
-python3 scripts/map_info.py map.mrc --json   # -> suggested_level at 1/1.5/2/3 sigma
-
-# Render a model in density — the mesh is carved around the model, which avoids
-# the whole-map contour stall in headless PyMOL (gotcha 20).
-python3 scripts/pymol_agent.py density model.pdb fit.png --map map.mrc --residue "chain A and resi 25"
-
-# No map yet? Simulate gaussian density from the model (predicted/designed structures).
-python3 scripts/pymol_agent.py density model.pdb fit.png --simulate
-```
+## Reading Guide
 
-## Good Demo Proteins
+Load only the relevant reference:
 
-| UniProt / PDB | Protein | Good for |
-|---|---|---|
-| P04637 | p53 | Disorder (pLDDT ~75), mixed confidence regions |
-| P69905 | Hemoglobin alpha | Very high confidence (pLDDT ~98) |
-| P0CG48 | Polyubiquitin-C (685 res) | Well-folded repeats; use when ubiquitin is requested |
-| P01308 | Insulin | Small, well-characterized |
-| 1HSG | HIV-1 protease + indinavir | Drug-target binding pocket |
-| 1BRS | Barnase-barstar complex | Protein-protein interface |
-| 4HHB | Hemoglobin tetramer | Multi-chain, quaternary structure |
-| 1EMA | GFP | Chromophore, fluorescence |
-
-## Output Pattern
-
-When running analysis, always produce structured output. The agent scripts
-return JSON with `{"status": "ok", "data": {...}}` or `{"status": "error", "error": "..."}` in
-`--json` mode. Many scripts also mirror key fields at top level for backward
-compatibility, but agents should read `data` first. Their temporary files are
-per-invocation, so they are safe to call in parallel within the same workspace.
-
-For multi-step workflows, write a summary JSON report at the end with:
-- Input files and parameters
-- Key measurements (RMSD, distances, counts, areas)
-- Output file paths (renders, saved structures)
-- Interpretation notes
-
-## Platform Notes
-
-- **macOS**: PyMOL and ChimeraX are in `/Applications/`. PyMOL headless
-  rendering works. ChimeraX `--nogui` has no OpenGL.
-- **Linux**: Both tools typically on `$PATH`. PyMOL headless works.
-  ChimeraX `--nogui` may have OpenGL via virtual framebuffer (`xvfb-run`).
-- **Rosetta**: Requires an academic license. Free alternatives:
-  ProteinMPNN (sequence design), LocalColabFold (structure prediction),
-  ESM2 (embeddings), RFdiffusion (backbone generation).
-
-## Quick Reference
-
-| I want to... | Do this |
+| Topic | Reference |
 |---|---|
-| Check machine readiness | `python3 scripts/proteus_doctor.py --network --json` |
-| Resolve any common structure query | `python3 scripts/resolve_structure.py TP53 --json` |
-| Resolve protein/gene name to UniProt | `python3 scripts/uniprot_lookup.py TP53 --gene-exact --json` |
-| Fetch an experimental PDB structure | `python3 scripts/fetch_pdb.py 4HHB --json` |
-| Search experimental structures | `python3 scripts/pdb_search.py "KRAS G12C" --rows 10 --details --json` |
-| Rank candidate structures | `python3 scripts/pdb_select.py --input candidates.json --json` |
-| Check biological assemblies | `python3 scripts/assembly_report.py 4HHB --json` |
-| Map PDB residues to UniProt ranges | `python3 scripts/sifts_map.py pdb 1hsg --json` |
-| Inventory bound ligands | `python3 scripts/ligand_extract.py 1HSG --json` |
-| Plan receptor/ligand docking prep | `python3 scripts/dock_prep.py --receptor receptor.pdb --ligand ligand.sdf --json` |
-| Build a docking box around a ligand | `python3 scripts/docking_box.py complex.pdb --ligand ATP --json` |
-| Plan or parse Vina-compatible docking | `python3 scripts/dock_vina.py plan --receptor receptor.pdbqt --ligand ligand.pdbqt --config box.txt --json` |
-| Summarize protein-ligand interactions | `python3 scripts/interaction_report.py complex.pdb --ligand ATP --json` |
-| Parse/check a protein substitution | `python3 scripts/variant_map.py "P04637 R175H" --no-download --json` |
-| Triage mutation structure context | `python3 scripts/mutation_triage.py R175H --structure model.pdb --json` |
-| Run a local batch manifest | `python3 scripts/proteus_batch.py manifest.json --dry-run --json` |
-| Cache public URL responses locally | `python3 scripts/proteus_cache.py fetch URL --json` |
-| Combine JSON outputs into an evidence pack | `python3 scripts/proteus_report.py --input result.json --json` |
-| Generate a target dossier | `python3 scripts/target_dossier.py --uniprot P04637 --no-network --json` |
-| Generate a local analysis dossier | `python3 scripts/target_dossier.py --pdb structure.cif --no-network --analyze-local --json` |
-| Inspect PDB/mmCIF file (no tools needed) | `python3 scripts/structure_info.py file.cif --json` |
-| Inspect a legacy PDB file | `python3 scripts/pdb_info.py file.pdb` |
-| Summarize AlphaFold PAE | `python3 scripts/pae_report.py AF-P04637-F1_pae.json --json` |
-| Fetch validation metrics | `python3 scripts/validation_report.py 4HHB --json` |
-| Report ligand pocket contacts | `python3 scripts/pocket_report.py complex.cif --json` |
-| Report protein-protein interface residues | `python3 scripts/interface_report.py complex.cif --json` |
-| Compare two structures | `python3 scripts/compare_structures.py ref.pdb mobile.pdb --per-residue --json` |
-| Detect optional quality tools | `python3 scripts/model_quality.py detect --json` |
-| Plan a design run | `python3 scripts/design_run.py design_manifest.json --dry-run --json` |
-| Parse Rosetta scorefiles | `python3 scripts/rosetta_score.py parse-scorefile score.sc --json` |
-| Get structure info via PyMOL | `python3 scripts/pymol_agent.py info file.pdb` |
-| Render a structure headless | `python3 scripts/pymol_agent.py render file.pdb out.png` |
-| Render an annotated binding-pocket figure | `python3 scripts/pymol_agent.py pocket file.pdb out.png --label` |
-| Render a turntable movie | `python3 scripts/pymol_agent.py spin file.pdb out.mp4` |
-| Render via ChimeraX GPU (REST) | `python3 scripts/chimerax_rest.py render file.pdb out.png` |
-| Fix a CA-only backbone for cartoons | `python3 scripts/add_helix_records.py model.pdb` |
-| Pick a cryo-EM contour level | `python3 scripts/map_info.py map.mrc --json` |
-| Render a model in cryo-EM density | `python3 scripts/pymol_agent.py density model.pdb out.png --map map.mrc` |
-| Fetch an AlphaFold prediction | `python3 scripts/fetch_alphafold.py UNIPROT_ID --pae --json` |
-| Align two structures (ChimeraX) | `python3 scripts/chimerax_agent.py align ref.pdb mobile.pdb` |
-| Measure SASA | `python3 scripts/chimerax_agent.py sasa file.pdb` |
-| Find H-bonds between chains | `python3 scripts/chimerax_agent.py hbonds file.pdb --chain1 A --chain2 B` |
-| Run arbitrary PyMOL commands | `python3 scripts/pymol_agent.py run "fetch 1ubq; show cartoon"` |
-| Run arbitrary ChimeraX commands | `python3 scripts/chimerax_agent.py run "open 1ubq; info chains #1"` |
-| Control ChimeraX GUI via REST | Read `references/chimerax.md` — REST API section |
-| Color by AlphaFold confidence | Read `references/alphafold.md` — pLDDT Coloring section |
-| Choose between PDB, mmCIF, SDF, MRC | Read `references/file-formats.md` |
-| Use RCSB/PDBe/UniProt APIs | Read `references/data-sources.md` |
-| Consider AF3/Boltz/Chai/ColabFold | Read `references/prediction-models.md` |
-| Do protein design without Rosetta | Read `references/rosetta.md` — ML Alternatives section |
-| Run the KRAS G12C dossier workflow | `python3 scripts/kras_dossier.py --out kras_g12c_dossier --no-movie` |
+| User workflows, manifests, outputs, handoff | `references/workflows.md` |
+| PyMOL commands, rendering, animation | `references/pymol.md` |
+| ChimeraX analysis, REST rendering, cryo-EM | `references/chimerax.md` |
+| AlphaFold DB, pLDDT, PAE | `references/alphafold.md` |
+| PDB/UniProt/PDBe/RCSB APIs | `references/data-sources.md` |
+| PDB/mmCIF/SDF/MRC format choice | `references/file-formats.md` |
+| AF3/Boltz/Chai/ColabFold and other models | `references/prediction-models.md` |
+| Rosetta, PyRosetta, and ML design alternatives | `references/rosetta.md` |
+
+## Output Contract
+
+Helpers emit JSON with `status`, `data`, and when applicable `warnings` and
+`provenance`. New workflow envelopes also include `schema_version` and
+`proteus_version`. Read `data` first.
+
+Return to the user:
+
+- the answer and key measurements;
+- generated figure/session/script paths;
+- input source and model/chain/selection decisions;
+- relevant uncertainty and interpretation limits;
+- missing tools or incomplete outputs, without pretending success.
diff --git a/skills/proteus/agents/openai.yaml b/skills/proteus/agents/openai.yaml
index 680d784..372fba3 100644
--- a/skills/proteus/agents/openai.yaml
+++ b/skills/proteus/agents/openai.yaml
@@ -1,4 +1,7 @@
 interface:
   display_name: "Proteus"
-  short_description: "Structural biology automation"
-  default_prompt: "Use $proteus to plan a structural biology visualization or analysis workflow."
+  short_description: "Structural biology automation for AI coding agents"
+  default_prompt: "Use $proteus to run a readiness check when needed, resolve structure inputs to local files with provenance, choose the right structural biology toolchain, and return concise analysis plus any generated outputs."
+
+policy:
+  allow_implicit_invocation: true
diff --git a/skills/proteus/references/chimerax.md b/skills/proteus/references/chimerax.md
index 0d52aed..568860e 100644
--- a/skills/proteus/references/chimerax.md
+++ b/skills/proteus/references/chimerax.md
@@ -259,7 +259,7 @@ style #1 stick                    # Stick representation
 surface #1                        # Molecular surface
 ~surface                          # Remove surface
 color #1 red                      # Color model red
-color bychain #1                  # Color by chain
+color #1 bychain                  # Color by chain
 color bfactor #1                  # Color by B-factor
 color bfactor #1 palette alphafold  # AlphaFold confidence colors
 transparency #1 50                # 50% transparent
@@ -345,7 +345,7 @@ alphafold contacts #1             # Predicted contacts overlay
 open 21924 from emdb              # Downloads .map file
 
 # Display
-volume #1 style surface level 0.025 color #90CAF9 transparency 0.3 step 1
+volume #1 style surface level 0.025 color #90CAF9 transparency 30 step 1
 
 # Fit atomic model into map
 fitmap #2 inMap #1 metric correlation
@@ -443,17 +443,17 @@ Overlay text labels on the ChimeraX viewport (REST API or command):
 
 ```
 # Create a label
-2dlabels create name title text "Step 1: Load Structure" xpos 0.05 ypos 0.95 color black size 24 bold true
+2dlabels create title text "Step 1: Load Structure" xpos 0.05 ypos 0.95 color black size 24 bold true
 
 # Update it
-2dlabels change name title text "Step 2: Analyze"
+2dlabels change title text "Step 2: Analyze"
 
 # Delete all labels
-2dlabels delete
+2dlabels delete all
 
 # Multiple labels
-2dlabels create name step text "Step 1" xpos 0.05 ypos 0.95 color white size 20 bold true
-2dlabels create name detail text "Loading hemoglobin" xpos 0.05 ypos 0.90 color gray size 14
+2dlabels create step text "Step 1" xpos 0.05 ypos 0.95 color white size 20 bold true
+2dlabels create detail text "Loading hemoglobin" xpos 0.05 ypos 0.90 color gray size 14
 ```
 
 Coordinates: `xpos`/`ypos` are 0.0-1.0 fractions of viewport.
diff --git a/skills/proteus/references/workflows.md b/skills/proteus/references/workflows.md
new file mode 100644
index 0000000..80e70b8
--- /dev/null
+++ b/skills/proteus/references/workflows.md
@@ -0,0 +1,224 @@
+# Reproducible PyMOL and ChimeraX Workflows
+
+This guide describes Proteus workflows that produce a JSON report plus
+replayable PyMOL (`.pml`) or ChimeraX (`.cxc`) scripts. Most also write a saved
+session when executed. Run `python3 scripts/proteus.py <command> --help` for the
+complete current interface.
+
+## General output pattern
+
+Each workflow writes into an explicit output directory:
+
+- a JSON report with inputs, parameters, warnings, provenance, and artifacts;
+- a command file that can be inspected before execution;
+- PNG figures and `.pse`/`.cxs` sessions when rendering is requested;
+- tool results when an optional detector or quality program is run.
+
+Input coordinate and map files are never modified. Reports use portable path
+labels and file checksums rather than publishing arbitrary absolute paths.
+
+## Structure preflight
+
+```bash
+python3 scripts/proteus.py qc structure.cif --model first --altloc highest --json
+```
+
+Run this before distances, interfaces, comparisons, restraints, or chemical-site
+analysis. It reports available/selected models, alternate sites, occupancy,
+missing backbone atoms, residue-number gaps, and chemical-component roles.
+
+Use `--model all` only for an ensemble-aware workflow. Use an explicit model
+number when the deposited file contains different experimental or modeled
+states. `--altloc highest` chooses the highest-occupancy conformer per atom and
+records that policy.
+
+## Declarative figures and guided views
+
+```bash
+python3 scripts/proteus.py figure scene.json --outdir figure --execute
+```
+
+Example `scene.json`:
+
+```json
+{
+  "name": "active-site-story",
+  "tool": "pymol",
+  "width": 1400,
+  "height": 1000,
+  "background": "white",
+  "structures": [{"id": "complex", "path": "complex.cif"}],
+  "representations": [
+    {"style": "cartoon", "selection": "polymer", "color": "chain"},
+    {"style": "sticks", "selection": "organic or byres (polymer within 4.5 of organic)", "color": "element"}
+  ],
+  "labels": [{"selection": "organic and not hydro", "text": "bound ligand", "color": "black"}],
+  "views": [
+    {"id": "overview", "selection": "polymer", "output": "overview.png"},
+    {"id": "site", "selection": "organic", "turn": {"y": 25}, "output": "site.png"}
+  ]
+}
+```
+
+Choose `"tool": "chimerax"` for a ChimeraX script/session. Multiple ordered
+views act as deterministic scene checkpoints for a presentation or human
+handoff. Keep manifest selections tool-specific and use filenames—not paths—for
+view outputs.
+
+## State comparisons
+
+```bash
+python3 scripts/proteus.py compare apo.pdb holo.pdb \
+  --ligand ATP --outdir apo_holo --execute
+```
+
+This produces aligned overlay and side-by-side views. When a ligand is selected,
+the report compares nearby contact residues between states. Interpret gained or
+lost contacts only after checking chain mapping, ligand identity, alignment
+coverage, missing residues, and alternate conformers.
+
+## Residue and interface stories
+
+```bash
+python3 scripts/proteus.py residue model.cif A:42 --outdir residue_42 --execute
+python3 scripts/proteus.py interface complex.cif --chains A,B --cutoff 5 --outdir interface_ab --execute
+```
+
+The residue workflow combines a global locator, labeled local environment, and
+available ligand/interface/variant context. The interface workflow combines
+local contact residues with ChimeraX buried area, H-bond, contact, and clash
+commands plus PyMOL figures.
+
+Buried area and distance contacts depend on which assembly is loaded. Do not
+interpret crystal-packing contacts as a biological interface without supporting
+evidence.
+
+## Annotation overlays
+
+```bash
+python3 scripts/proteus.py annotate model.pdb annotations.csv --outdir annotated --execute
+```
+
+CSV rows can supply chain, residue, score, color, and label fields. JSON lists
+use the same keys. Use this for variants, domains, PTMs, conservation,
+confidence, validation, or a user-defined score. Keep the score definition and
+scale in the surrounding report; colors alone are not self-explanatory.
+
+## Experimental restraints
+
+```bash
+python3 scripts/proteus.py restraints model.pdb restraints.csv --outdir restraints --execute
+```
+
+Required CSV/JSON fields are `residue1` and `residue2`. Optional fields include
+`chain1`, `atom1`, `chain2`, `atom2`, `min`, `max`, `id`, and `label`. The report
+marks pairs as satisfied, too short, too long, or unresolved and colors the
+rendered distance objects.
+
+Distance bounds must match the experiment and labeling chemistry. A C-alpha
+distance is not automatically comparable to an atom-to-atom crosslink, FRET, or
+DEER distribution.
+
+## Assembly and symmetry
+
+```bash
+python3 scripts/proteus.py assembly 4HHB --assembly 1 --outdir assembly --execute
+```
+
+PDB identifiers enable assembly metadata lookup. The ChimeraX workflow compares
+the asymmetric unit and requested biological assembly; PyMOL expands nearby
+crystal mates. For a local coordinate file, assembly availability cannot be
+inferred reliably unless the necessary metadata/operators are present.
+
+## Cryo-EM map/model review
+
+```bash
+python3 scripts/proteus.py cryoem model.cif map.mrc \
+  --resolution 3.2 --fit --difference --outdir map_review --execute
+```
+
+Local MRC/CCP4 maps receive sigma-based contour suggestions. Remote EMDB maps
+require explicit absolute `--levels` because Proteus cannot compute local map
+statistics before download/open. The ChimeraX script saves a contour sweep,
+optional rigid fit, map statistics, and a qualitative difference view.
+
+Use several contour levels. Record resolution, map provenance, sharpening or
+filtering, masking, and fit procedure. Difference density is not reliable
+without appropriate scaling and independent validation.
+
+## Ensembles
+
+```bash
+python3 scripts/proteus.py ensemble models.pdb --outdir ensemble --execute
+```
+
+Multi-model PDB/mmCIF files are compared using common C-alpha atoms. With NumPy,
+Proteus performs a Kabsch superposition before RMSF; otherwise it reports the
+translation-only fallback. The result includes residue-level RMSF, most-variable
+residues, an all-state PyMOL view, and a ChimeraX coordinate-set session.
+
+RMSF here measures dispersion across supplied coordinate models, not uncertainty
+or dynamics unless the ensemble itself supports that interpretation.
+
+## Electrostatics
+
+```bash
+python3 scripts/proteus.py electrostatics model.pdb \
+  --selection protein --range 10 --offset 1.4 --outdir electrostatics --execute
+```
+
+This uses ChimeraX Coulombic surface coloring and reports whether PDB2PQR/APBS
+are installed. It is useful for qualitative orientation and charge patches.
+For quantitative comparisons, curate protonation and charges and use a validated
+Poisson-Boltzmann workflow with controlled dielectric and ionic-strength choices.
+
+## Pocket and tunnel candidates
+
+```bash
+python3 scripts/proteus.py pockets model.pdb --detector auto --execute --render
+```
+
+`auto` prefers fpocket, then P2Rank. Detection is optional and local; no
+structure is uploaded. Detected pocket files are copied into the output directory
+and rendered with lining residues. CAVER/HOLE availability is reported, but
+tunnel execution is left to a configured tool-specific workflow because starting
+points and probe settings are scientifically consequential.
+
+## Chemical sites
+
+```bash
+python3 scripts/proteus.py chemical-site complex.cif \
+  --component ZN:A:501 --radius 5 --outdir zinc_site --execute
+```
+
+Component selectors may be `RESN`, `CHAIN:RESIDUE`, or
+`RESN:CHAIN:RESIDUE`. The report classifies polymer, modified polymer, ligand,
+cofactor, ion, water, and common additive groups; lists nearest heavy-atom
+neighbors; and highlights metal-coordination candidates. PDB `LINK`/`CONECT` or
+mmCIF `struct_conn` counts are surfaced as connectivity evidence, not accepted
+as proof of a specific chemistry without inspection.
+
+## Optional structure-quality tools
+
+```bash
+python3 scripts/model_quality.py detect --json
+python3 scripts/model_quality.py usalign reference.pdb mobile.pdb --json
+python3 scripts/model_quality.py dockq model_complex.pdb native_complex.pdb --json
+python3 scripts/model_quality.py foldseek query.pdb target_directory --json
+```
+
+DockQ writes and parses its JSON result. Foldseek uses `easy-search` with
+alignment TM-scores, query/target-normalized TM-scores, lDDT, E-value, and bits.
+These tools are optional and are never installed automatically.
+
+## Human handoff checklist
+
+Before handing a result to a user, verify:
+
+1. the input identity, residue numbering, model, conformer, and assembly;
+2. every expected image/session exists and is non-empty;
+3. the JSON report names the method, selection, cutoff, and provenance;
+4. replay scripts contain no credentials and were written only to the requested
+   output directory;
+5. interpretation distinguishes computed geometry from biological inference;
+6. the user receives the `.pml`/`.cxc` and `.pse`/`.cxs` paths needed to continue.
diff --git a/skills/proteus/scripts/annotation_figure.py b/skills/proteus/scripts/annotation_figure.py
new file mode 100644
index 0000000..b97d01a
--- /dev/null
+++ b/skills/proteus/scripts/annotation_figure.py
@@ -0,0 +1,197 @@
+#!/usr/bin/env python3
+"""Map user-supplied residue annotations onto PyMOL and ChimeraX scenes."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import proteus_common
+import visual_common
+
+
+SPEC_RE = re.compile(r"^[A-Za-z0-9_.+?-]+$")
+
+
+def _annotations(path: str | Path) -> list[dict[str, Any]]:
+    records = visual_common.load_records(path)
+    output = []
+    for index, record in enumerate(records, start=1):
+        chain = str(record.get("chain") or "").strip()
+        residue = str(record.get("residue") or record.get("resi") or "").strip()
+        if not residue:
+            raise visual_common.VisualWorkflowError(f"Annotation {index} is missing residue/resi.")
+        if any(character in residue for character in "\r\n; "):
+            raise visual_common.VisualWorkflowError(f"Invalid residue identifier in annotation {index}.")
+        if not SPEC_RE.fullmatch(residue) or (chain and not SPEC_RE.fullmatch(chain)):
+            raise visual_common.VisualWorkflowError(f"Invalid chain or residue identifier in annotation {index}.")
+        score_raw = record.get("score", record.get("value"))
+        score = None
+        if score_raw not in {None, ""}:
+            score = float(score_raw)
+            if not math.isfinite(score):
+                raise visual_common.VisualWorkflowError(f"Annotation {index} has a non-finite score.")
+        label = str(record.get("label") or "").strip()
+        if any(character in label for character in "\r\n;"):
+            raise visual_common.VisualWorkflowError(f"Annotation {index} label cannot contain newlines or semicolons.")
+        item = {
+            "chain": chain,
+            "residue": residue,
+            "score": score,
+            "label": label,
+            "color": str(record.get("color") or "").strip(),
+        }
+        if item["color"]:
+            visual_common.color(item["color"])
+        output.append(item)
+    return output
+
+
+def _pymol_selection(item: dict[str, Any]) -> str:
+    base = f"resi {item['residue']}"
+    return f"chain {item['chain']} and {base}" if item["chain"] else base
+
+
+def _chimerax_selection(item: dict[str, Any]) -> str:
+    return f"#1/{item['chain']}:{item['residue']}" if item["chain"] else f"#1:{item['residue']}"
+
+
+def build_annotation_figure(structure: str, annotation_file: str, outdir: str, *,
+                            execute: bool = False, surface: bool = False,
+                            width: int = 1200, height: int = 900) -> dict[str, Any]:
+    source = Path(structure).expanduser()
+    if not source.is_file():
+        raise visual_common.VisualWorkflowError(f"Structure not found: {proteus_common.display_path(source)}")
+    annotations = _annotations(annotation_file)
+    if not annotations:
+        raise visual_common.VisualWorkflowError("No annotations were supplied.")
+    destination = Path(outdir)
+    destination.mkdir(parents=True, exist_ok=True)
+    scores = [item["score"] for item in annotations if item["score"] is not None]
+    score_range = [min(scores), max(scores)] if scores else None
+
+    pml = visual_common.pymol_base(width=width, height=height)
+    pml.extend([
+        f"load {visual_common.quote_pymol(source.resolve())}, structure",
+        "hide everything, all",
+        "show cartoon, polymer",
+        "color gray80, polymer",
+    ])
+    if surface:
+        pml.extend(["show surface, polymer", "set surface_transparency, 0.2, polymer"])
+    for index, item in enumerate(annotations, start=1):
+        selector = _pymol_selection(item)
+        name = f"annotation_{index}"
+        pml.append(f"select {name}, structure and ({selector})")
+        pml.append(f"show sticks, {name}")
+        if item["score"] is not None:
+            pml.append(f"alter {name}, b={item['score']:.8g}")
+        if item["color"]:
+            pml.append(f"color {item['color']}, {name}")
+        if item["label"]:
+            label = item["label"].replace('"', '\\"')
+            pml.append(f"label {name} and name CA, \"{label}\"")
+    if scores and not any(item["color"] for item in annotations):
+        minimum, maximum = score_range or [0.0, 1.0]
+        if minimum == maximum:
+            maximum = minimum + 1.0
+        pml.append(f"spectrum b, blue_white_red, annotation_*, minimum={minimum:.8g}, maximum={maximum:.8g}")
+    pml.extend(visual_common.finalize_pymol(
+        destination / "annotations.png", width=width, height=height,
+        session=destination / "annotations.pse",
+    ))
+
+    cxc = [
+        *visual_common.chimerax_base(),
+        f"open {visual_common.quote_chimerax(source.resolve())}",
+        "cartoon",
+        "color protein lightgray",
+    ]
+    if surface:
+        cxc.extend(["surface protein", "transparency protein 20 target s"])
+    for item in annotations:
+        selector = _chimerax_selection(item)
+        if item["score"] is not None:
+            cxc.append(f"setattr {selector} r proteus_score {item['score']:.8g} create true type float")
+        if item["color"]:
+            cxc.append(f"color {selector} {item['color']}")
+        cxc.extend([f"show {selector} atoms", f"style {selector} stick"])
+        if item["label"]:
+            label = item["label"].replace('"', '\\"')
+            cxc.append(f"label {selector} text \"{label}\"")
+    if scores and not any(item["color"] for item in annotations):
+        minimum, maximum = score_range or [0.0, 1.0]
+        if minimum == maximum:
+            maximum = minimum + 1.0
+        cxc.append(f"color byattribute r:proteus_score #1 palette blue-white-red range {minimum:.8g},{maximum:.8g}")
+    cxc.extend(visual_common.finalize_chimerax(
+        destination / "annotations_chimerax.png", width=width, height=height,
+        session=destination / "annotations.cxs",
+    ))
+
+    data: dict[str, Any] = {
+        "workflow": "annotation_figure",
+        "structure": proteus_common.display_path(source),
+        "annotation_count": len(annotations),
+        "score_range": score_range,
+        "surface": surface,
+        "images": {
+            "pymol": proteus_common.display_path(destination / "annotations.png"),
+            "chimerax": proteus_common.display_path(destination / "annotations_chimerax.png"),
+        },
+        "executed": execute,
+    }
+    report = proteus_common.ok_payload(
+        data,
+        warnings=["Annotation residue identifiers use coordinate-file numbering."],
+        provenance={
+            "structure": proteus_common.file_provenance(source),
+            "annotations": proteus_common.file_provenance(annotation_file),
+        },
+    )
+    data["artifacts"] = visual_common.write_workflow(
+        destination, "annotation_figure", report=report, pymol_lines=pml, chimerax_lines=cxc,
+    )
+    if execute:
+        data["execution"] = {
+            "pymol": visual_common.run_pymol(destination / "annotation_figure.pml"),
+            "chimerax": visual_common.run_chimerax(cxc),
+        }
+        failures = [name for name, result in data["execution"].items() if result.get("status") not in {"ok", "unavailable"}]
+        if failures:
+            report["status"] = "error"
+            report["error"] = f"Annotation rendering failed for: {', '.join(failures)}"
+        proteus_common.write_json(destination / "annotation_figure.json", report)
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Color and label structures from CSV/JSON residue annotations.")
+    parser.add_argument("structure")
+    parser.add_argument("annotations", help="CSV/JSON with chain,residue,score,label,color fields")
+    parser.add_argument("--outdir", default="proteus_annotations")
+    parser.add_argument("--surface", action="store_true")
+    parser.add_argument("--execute", action="store_true")
+    parser.add_argument("--json", action="store_true", help="Emit JSON (accepted for consistency)")
+    args = parser.parse_args(argv)
+    try:
+        report = build_annotation_figure(args.structure, args.annotations, args.outdir,
+                                         execute=args.execute, surface=args.surface)
+    except (OSError, ValueError, json.JSONDecodeError, visual_common.VisualWorkflowError) as exc:
+        print(json.dumps(proteus_common.error_payload(str(exc)), indent=2))
+        return 1
+    print(json.dumps(report, indent=2))
+    return 0 if report.get("status") == "ok" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/skills/proteus/scripts/assembly_explorer.py b/skills/proteus/scripts/assembly_explorer.py
new file mode 100644
index 0000000..cd4ffde
--- /dev/null
+++ b/skills/proteus/scripts/assembly_explorer.py
@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""Compare asymmetric-unit, biological-assembly, and crystal-neighbor views."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import assembly_report
+import proteus_common
+import visual_common
+
+
+PDB_ID_RE = re.compile(r"^[0-9][A-Za-z0-9]{3}$")
+
+
+def explore_assembly(input_value: str, outdir: str, *, assembly: int = 1,
+                     execute: bool = False, width: int = 1300, height: int = 900) -> dict[str, Any]:
+    if assembly < 1:
+        raise visual_common.VisualWorkflowError("Assembly number must be positive.")
+    source = Path(input_value).expanduser()
+    pdb_id = input_value.upper() if PDB_ID_RE.fullmatch(input_value.strip()) and not source.exists() else None
+    metadata = None
+    provenance: dict[str, Any]
+    warnings = [
+        "Biological assemblies are author/depositor interpretations and should be checked against experimental context.",
+        "Crystal neighbors show packing contacts and are not automatically biological interfaces.",
+    ]
+    if pdb_id:
+        metadata = assembly_report.fetch_assembly_report(pdb_id, requested_assembly=assembly)
+        provenance = {"source": {"kind": "pdb_id", "id": pdb_id, "api": assembly_report.RCSB_ENTRY.format(pdb_id=pdb_id)}}
+        open_command = f"open {pdb_id} from pdb"
+        pymol_load = f"fetch {pdb_id}, async=0"
+    else:
+        if not source.is_file():
+            raise visual_common.VisualWorkflowError("Input must be a local structure or four-character PDB ID.")
+        provenance = {"source": proteus_common.file_provenance(source)}
+        open_command = f"open {visual_common.quote_chimerax(source.resolve())}"
+        pymol_load = f"load {visual_common.quote_pymol(source.resolve())}, structure"
+        warnings.append("Assembly availability could not be verified from a local file alone.")
+
+    destination = Path(outdir)
+    destination.mkdir(parents=True, exist_ok=True)
+    asu_image = (destination / "asymmetric_unit.png").resolve()
+    assembly_image = (destination / f"assembly_{assembly}.png").resolve()
+    crystal_image = (destination / "crystal_neighbors.png").resolve()
+    cxc = [
+        *visual_common.chimerax_base(),
+        open_command,
+        "cartoon",
+        "color #1 bychain",
+        "view",
+        f"save {visual_common.quote_chimerax(asu_image)} width {width} height {height} supersample 3",
+        "wait 1",
+        f"sym #1 assembly {assembly} copies true",
+        "color all bychain",
+        "view",
+        f"save {visual_common.quote_chimerax(assembly_image)} width {width} height {height} supersample 3",
+        "wait 1",
+        f"save {visual_common.quote_chimerax((destination / 'assembly_explorer.cxs').resolve())}",
+    ]
+    pml = visual_common.pymol_base(width=width, height=height)
+    pml.extend([
+        pymol_load,
+        "hide everything, all",
+        "show cartoon, polymer",
+        "util.cbc()",
+        "symexp crystal_, all, all, 5",
+        "color gray80, crystal_*",
+        "set cartoon_transparency, 0.35, crystal_*",
+        "orient all",
+        f"ray {width}, {height}",
+        *visual_common.pymol_png(crystal_image, width=width, height=height),
+        *visual_common.pymol_save(destination / "crystal_neighbors.pse"),
+        "quit",
+    ])
+    data: dict[str, Any] = {
+        "workflow": "assembly_explorer",
+        "input": pdb_id or proteus_common.display_path(source),
+        "assembly": assembly,
+        "assembly_metadata": metadata.get("data", metadata) if metadata else None,
+        "images": {
+            "asymmetric_unit": proteus_common.display_path(asu_image),
+            "biological_assembly": proteus_common.display_path(assembly_image),
+            "crystal_neighbors": proteus_common.display_path(crystal_image),
+        },
+        "executed": execute,
+    }
+    report = proteus_common.ok_payload(data, warnings=warnings, provenance=provenance)
+    data["artifacts"] = visual_common.write_workflow(
+        destination, "assembly_explorer", report=report, pymol_lines=pml, chimerax_lines=cxc,
+    )
+    if execute:
+        data["execution"] = {
+            "chimerax": visual_common.run_chimerax(cxc),
+            "pymol": visual_common.run_pymol(destination / "assembly_explorer.pml"),
+        }
+        failures = [name for name, result in data["execution"].items() if result.get("status") not in {"ok", "unavailable"}]
+        if failures:
+            report["status"] = "error"
+            report["error"] = f"Assembly rendering failed for: {', '.join(failures)}"
+        proteus_common.write_json(destination / "assembly_explorer.json", report)
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Compare asymmetric unit, biological assembly, and crystal neighbors.")
+    parser.add_argument("input", help="Local PDB/mmCIF or PDB ID")
+    parser.add_argument("--assembly", type=int, default=1)
+    parser.add_argument("--outdir", default="proteus_assembly")
+    parser.add_argument("--execute", action="store_true")
+    parser.add_argument("--json", action="store_true", help="Emit JSON (accepted for consistency)")
+    args = parser.parse_args(argv)
+    try:
+        report = explore_assembly(args.input, args.outdir, assembly=args.assembly, execute=args.execute)
+    except (OSError, ValueError, assembly_report.AssemblyReportError, visual_common.VisualWorkflowError) as exc:
+        print(json.dumps(proteus_common.error_payload(str(exc)), indent=2))
+        return 1
+    print(json.dumps(report, indent=2))
+    return 0 if report.get("status") == "ok" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/skills/proteus/scripts/chemical_site.py b/skills/proteus/scripts/chemical_site.py
new file mode 100644
index 0000000..5a92198
--- /dev/null
+++ b/skills/proteus/scripts/chemical_site.py
@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""Triage ligands, metals, waters, and covalent evidence around a chemical site."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import re
+import sys
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import proteus_common
+import structure_qc
+import visual_common
+
+
+SPEC_RE = re.compile(r"^[A-Za-z0-9_.+?-]+$")
+
+
+def _distance(left: dict[str, Any], right: dict[str, Any]) -> float:
+    return math.sqrt(sum((left[axis] - right[axis]) ** 2 for axis in ("x", "y", "z")))
+
+
+def _groups(atoms: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    grouped: dict[tuple[Any, ...], list[dict[str, Any]]] = defaultdict(list)
+    for atom in atoms:
+        key = (atom["model"], atom["chain"], atom["residue_id"], atom["insertion_code"], atom["resname"])
+        grouped[key].append(atom)
+    output = []
+    for key, values in grouped.items():
+        model, chain, residue_id, insertion_code, resname = key
+        output.append({
+            "model": model,
+            "chain": chain,
+            "residue": f"{residue_id}{insertion_code}",
+            "residue_id": residue_id,
+            "insertion_code": insertion_code,
+            "component": resname,
+            "role": structure_qc.component_role(resname, values[0]["record"], len(values)),
+            "atoms": values,
+        })
+    return output
+
+
+def _choose_site(groups: list[dict[str, Any]], component: str | None) -> dict[str, Any]:
+    chemical = [item for item in groups if item["role"] not in {"polymer", "modified_polymer", "water", "additive_or_solvent"}]
+    if component:
+        parts = component.split(":")
+        matches = []
+        for item in chemical:
+            if len(parts) == 1 and item["component"].upper() == parts[0].upper():
+                matches.append(item)
+            elif len(parts) == 2 and item["chain"] == parts[0] and item["residue"] == parts[1]:
+                matches.append(item)
+            elif len(parts) == 3 and item["component"].upper() == parts[0].upper() and item["chain"] == parts[1] and item["residue"] == parts[2]:
+                matches.append(item)
+        if len(matches) != 1:
+            raise visual_common.VisualWorkflowError(f"--component matched {len(matches)} sites; use RESN:CHAIN:RESIDUE to select one.")
+        return matches[0]
+    preferred = [item for item in chemical if item["role"] in {"ligand_or_unknown", "cofactor"}]
+    candidates = preferred or chemical
+    if not candidates:
+        raise visual_common.VisualWorkflowError("No ligand, cofactor, or ion site was found.")
+    if len(candidates) > 1:
+        labels = ", ".join(f"{item['component']}:{item['chain']}:{item['residue']}" for item in candidates[:8])
+        raise visual_common.VisualWorkflowError(f"Multiple chemical sites are present ({labels}); choose one with --component.")
+    return candidates[0]
+
+
+def inspect_chemical_site(structure: str, outdir: str, *, component: str | None = None,
+                          radius: float = 5.0, execute: bool = False,
+                          width: int = 1300, height: int = 900) -> dict[str, Any]:
+    source = Path(structure).expanduser()
+    if not source.is_file():
+        raise visual_common.VisualWorkflowError(f"Structure not found: {proteus_common.display_path(source)}")
+    if radius <= 0:
+        raise visual_common.VisualWorkflowError("Radius must be positive.")
+    text = structure_qc._read_text(source)
+    fmt = structure_qc._format_from_path(source)
+    raw, parser_meta = structure_qc.parse_mmcif(text) if fmt == "mmcif" else structure_qc.parse_pdb(text)
+    atoms, selection = structure_qc.select_atoms(raw, model="first", altloc="highest")
+    groups = _groups(atoms)
+    site = _choose_site(groups, component)
+    neighbors = []
+    coordination = []
+    for group in groups:
+        if group is site:
+            continue
+        distances = [
+            (_distance(left, right), left, right)
+            for left in site["atoms"] for right in group["atoms"]
+            if left["element"] != "H" and right["element"] != "H"
+        ]
+        if not distances:
+            continue
+        closest = min(distances, key=lambda item: item[0])
+        distance, site_atom, neighbor_atom = closest
+        if distance <= radius:
+            record = {
+                "component": group["component"],
+                "chain": group["chain"],
+                "residue": group["residue"],
+                "role": group["role"],
+                "distance_angstrom": round(distance, 3),
+                "site_atom": site_atom["atom_name"],
+                "neighbor_atom": neighbor_atom["atom_name"],
+            }
+            neighbors.append(record)
+            if site["role"] == "ion" and distance <= 3.2:
+                coordination.append(record)
+    neighbors.sort(key=lambda item: item["distance_angstrom"])
+    coordination.sort(key=lambda item: item["distance_angstrom"])
+    destination = Path(outdir)
+    destination.mkdir(parents=True, exist_ok=True)
+    chain, residue, resname = site["chain"], site["residue"], site["component"]
+    safe_visual = all(SPEC_RE.fullmatch(str(value)) for value in (chain, residue, resname))
+    warnings = [
+        "Distance-based coordination and covalent-link evidence are hypotheses; verify geometry, valence, protonation, and experimental density.",
+        "Waters, additives, and ions can be modeled ambiguously at limited resolution.",
+    ]
+    pml: list[str] | None = None
+    cxc: list[str] | None = None
+    if safe_visual:
+        pml = visual_common.pymol_base(width=width, height=height)
+        site_selection = f"resn {resname} and chain {chain} and resi {residue}"
+        pml.extend([
+            f"load {visual_common.quote_pymol(source.resolve())}, structure",
+            "hide everything, all",
+            "show cartoon, polymer",
+            "color gray80, polymer",
+            f"select chemical_site, {site_selection}",
+            f"select site_neighbors, byres (all within {radius:g} of chemical_site)",
+            "show sticks, chemical_site or site_neighbors",
+            "show spheres, chemical_site and inorganic",
+            "color tv_orange, chemical_site",
+            "color cyan, site_neighbors and polymer",
+            "distance site_contacts, chemical_site, site_neighbors, 3.6, 2",
+            "label chemical_site and not hydro, resn + resi",
+            "orient chemical_site or site_neighbors",
+            "zoom chemical_site or site_neighbors, 4",
+            *visual_common.finalize_pymol(
+                destination / "chemical_site.png", width=width, height=height,
+                session=destination / "chemical_site.pse",
+            ),
+        ])
+        cx_site = f"#1/{chain}:{residue}"
+        cxc = [
+            *visual_common.chimerax_base(),
+            f"open {visual_common.quote_chimerax(source.resolve())}",
+            "cartoon #1",
+            "color #1 lightgray",
+            f"select {cx_site}",
+            f"select zone sel {radius:g} residues true",
+            "show sel atoms",
+            "style sel stick",
+            f"color {cx_site} orange",
+            f"contacts {cx_site} restrict sel reveal true showDist true log true",
+            f"hbonds {cx_site} restrict sel reveal true log true",
+            "view sel",
+            *visual_common.finalize_chimerax(
+                destination / "chemical_site_chimerax.png", width=width, height=height,
+                session=destination / "chemical_site.cxs",
+            ),
+        ]
+    else:
+        warnings.append("The selected site's identifiers were not safe to embed in replay scripts, so only the analysis report was written.")
+    site_data = {key: site[key] for key in ("model", "chain", "residue", "component", "role")}
+    data: dict[str, Any] = {
+        "workflow": "chemical_site",
+        "structure": proteus_common.display_path(source),
+        "site": site_data,
+        "radius_angstrom": radius,
+        "neighbors": neighbors,
+        "coordination_candidates": coordination,
+        "connectivity_evidence": parser_meta,
+        "selection": selection,
+        "executed": execute,
+    }
+    report = proteus_common.ok_payload(
+        data, warnings=warnings, provenance={"structure": proteus_common.file_provenance(source)},
+    )
+    data["artifacts"] = visual_common.write_workflow(
+        destination, "chemical_site", report=report, pymol_lines=pml, chimerax_lines=cxc,
+    )
+    if execute and pml is not None and cxc is not None:
+        data["execution"] = {
+            "pymol": visual_common.run_pymol(destination / "chemical_site.pml"),
+            "chimerax": visual_common.run_chimerax(cxc),
+        }
+        failures = [name for name, result in data["execution"].items() if result.get("status") not in {"ok", "unavailable"}]
+        if failures:
+            report["status"] = "error"
+            report["error"] = f"Chemical-site rendering failed for: {', '.join(failures)}"
+        proteus_common.write_json(destination / "chemical_site.json", report)
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Inspect a ligand, cofactor, or metal site with chemical-context warnings.")
+    parser.add_argument("structure")
+    parser.add_argument("--component", help="RESN, CHAIN:RESIDUE, or RESN:CHAIN:RESIDUE")
+    parser.add_argument("--radius", type=float, default=5.0)
+    parser.add_argument("--outdir", default="proteus_chemical_site")
+    parser.add_argument("--execute", action="store_true")
+    parser.add_argument("--json", action="store_true", help="Emit JSON (accepted for consistency)")
+    args = parser.parse_args(argv)
+    try:
+        report = inspect_chemical_site(
+            args.structure, args.outdir, component=args.component, radius=args.radius, execute=args.execute,
+        )
+    except (OSError, ValueError, structure_qc.StructureQCError, visual_common.VisualWorkflowError) as exc:
+        print(json.dumps(proteus_common.error_payload(str(exc)), indent=2))
+        return 1
+    print(json.dumps(report, indent=2))
+    return 0 if report.get("status") == "ok" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/skills/proteus/scripts/chimerax_rest.py b/skills/proteus/scripts/chimerax_rest.py
index d6d1205..a0e0c92 100755
--- a/skills/proteus/scripts/chimerax_rest.py
+++ b/skills/proteus/scripts/chimerax_rest.py
@@ -15,7 +15,7 @@
     python chimerax_rest.py render structure.pdb out.png --style surface --color bychain
     python chimerax_rest.py render model.pdb out.png --color plddt
     python chimerax_rest.py spin model.pdb spin.mp4 --frames 72        # needs ffmpeg
-    python chimerax_rest.py run "open 1ubq from pdb; cartoon; color bychain"
+    python chimerax_rest.py run "open 1ubq from pdb; cartoon; color #1 bychain"
     python chimerax_rest.py --help
 
 Environment:
@@ -240,7 +240,7 @@ def _scene_commands(style: str, color: str) -> list:
     cmds += styles.get(style, styles["cartoon"])
     color_cmd = {
         "rainbow": "rainbow #1",
-        "bychain": "color bychain #1",
+        "bychain": "color #1 bychain",
         "bfactor": "color bfactor #1",
         "plddt": "color bfactor #1 palette alphafold",
     }.get(color, f"color #1 {color}")
@@ -362,7 +362,7 @@ def main():
         epilog="Examples:\n"
                "  %(prog)s render structure.pdb out.png --color plddt\n"
                "  %(prog)s spin model.pdb spin.mp4 --frames 72\n"
-               "  %(prog)s run 'open 1ubq from pdb; cartoon; color bychain'",
+               "  %(prog)s run 'open 1ubq from pdb; cartoon; color #1 bychain'",
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     sub = parser.add_subparsers(dest="command", required=True)
diff --git a/skills/proteus/scripts/cryoem_workflow.py b/skills/proteus/scripts/cryoem_workflow.py
new file mode 100644
index 0000000..23f0f83
--- /dev/null
+++ b/skills/proteus/scripts/cryoem_workflow.py
@@ -0,0 +1,221 @@
+#!/usr/bin/env python3
+"""Build a replayable ChimeraX cryo-EM map/model inspection workflow."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import chimerax_agent
+import map_info
+import proteus_common
+import visual_common
+
+
+PDB_ID_RE = re.compile(r"^[0-9][A-Za-z0-9]{3}$")
+EMDB_ID_RE = re.compile(r"^(?:EMD[-_ ]?)?([0-9]{3,6})$", re.IGNORECASE)
+
+
+def _analysis_summary(result: dict[str, Any]) -> dict[str, Any]:
+    cleaned = proteus_common.scrub_private(result)
+    output: dict[str, Any] = {"status": cleaned.get("status", "error")}
+    if cleaned.get("error"):
+        output["error"] = cleaned["error"]
+    info = cleaned.get("info") or cleaned.get("data", {}).get("info") or []
+    useful = []
+    for line in info:
+        text = str(line)
+        if any(term in text.lower() for term in ("correlation", "mean", "rms", "minimum", "maximum", "standard deviation", "map value")):
+            useful.append(text)
+        if len(useful) >= 30:
+            break
+    if useful:
+        output["measurements"] = useful
+    return output
+
+
+def _model_source(value: str) -> tuple[str, dict[str, Any]]:
+    path = Path(value).expanduser()
+    if path.is_file():
+        return f"open {visual_common.quote_chimerax(path.resolve())}", proteus_common.file_provenance(path)
+    if PDB_ID_RE.fullmatch(value.strip()):
+        pdb_id = value.upper()
+        return f"open {pdb_id} from pdb", {"kind": "pdb_id", "id": pdb_id}
+    raise visual_common.VisualWorkflowError("Model must be a local PDB/mmCIF file or four-character PDB ID.")
+
+
+def _map_source(value: str) -> tuple[str, dict[str, Any], dict[str, Any] | None]:
+    path = Path(value).expanduser()
+    if path.is_file():
+        stats = map_info.map_info(str(path)).get("data", {})
+        return (
+            f"open {visual_common.quote_chimerax(path.resolve())}",
+            proteus_common.file_provenance(path),
+            {key: stats.get(key) for key in ("dimensions", "dtype", "mean", "sigma", "suggested_levels")},
+        )
+    match = EMDB_ID_RE.fullmatch(value.strip())
+    if match:
+        emdb_id = f"EMD-{match.group(1)}"
+        return f"open {emdb_id} from emdb", {"kind": "emdb_id", "id": emdb_id}, None
+    raise visual_common.VisualWorkflowError("Map must be a local MRC/CCP4 file or EMDB ID.")
+
+
+def _parse_levels(value: str | None, stats: dict[str, Any] | None) -> list[float]:
+    if value:
+        try:
+            levels = [float(item.strip()) for item in value.split(",") if item.strip()]
+        except ValueError as exc:
+            raise visual_common.VisualWorkflowError("--levels must be comma-separated numeric map values.") from exc
+        if not levels:
+            raise visual_common.VisualWorkflowError("--levels did not contain any map values.")
+        return levels
+    suggested = (stats or {}).get("suggested_levels") or {}
+    defaults = [suggested.get(key) for key in ("1.5_sigma", "2.0_sigma", "3.0_sigma")]
+    return [float(item) for item in defaults if item is not None]
+
+
+def build_cryoem_workflow(
+    model: str,
+    density_map: str,
+    outdir: str,
+    *,
+    resolution: float | None = None,
+    levels: str | None = None,
+    fit: bool = False,
+    difference: bool = False,
+    execute: bool = False,
+    width: int = 1300,
+    height: int = 900,
+) -> dict[str, Any]:
+    if resolution is not None and resolution <= 0:
+        raise visual_common.VisualWorkflowError("Resolution must be positive.")
+    if difference and resolution is None:
+        raise visual_common.VisualWorkflowError("--difference requires --resolution for the model-derived map.")
+    model_open, model_provenance = _model_source(model)
+    map_open, map_provenance, stats = _map_source(density_map)
+    contour_levels = _parse_levels(levels, stats)
+    if not contour_levels:
+        raise visual_common.VisualWorkflowError("Remote EMDB maps require explicit absolute --levels values.")
+
+    destination = Path(outdir)
+    destination.mkdir(parents=True, exist_ok=True)
+    commands = [
+        *visual_common.chimerax_base(),
+        model_open,
+        map_open,
+        "cartoon #1",
+        "color #1 bychain",
+        "volume #2 style surface",
+        "volume #2 color #7FB3D5 transparency 55",
+    ]
+    if fit:
+        fit_command = "fitmap #1 inMap #2"
+        if resolution is not None:
+            fit_command += f" resolution {resolution:g}"
+        fit_command += " metric correlation"
+        commands.append(fit_command)
+    commands.extend([
+        "measure mapstats #2",
+    ])
+    images: list[str] = []
+    for index, level in enumerate(contour_levels, start=1):
+        image = (destination / f"contour_{index}_{level:g}.png").resolve()
+        images.append(proteus_common.display_path(image))
+        commands.extend([
+            f"volume #2 level {level:g}",
+            "view #1,2",
+            f"save {visual_common.quote_chimerax(image)} width {width} height {height} supersample 3",
+            "wait 1",
+        ])
+    if difference:
+        difference_image = (destination / "difference_map.png").resolve()
+        span = max(abs(item) for item in contour_levels)
+        commands.extend([
+            f"molmap #1 {resolution:g}",
+            "volume subtract #2 #3 minRms true onGrid #2",
+            "hide #2 models",
+            f"volume #4 level {-span:g} color red level {span:g} color blue transparency 35",
+            "view #1,4",
+            f"save {visual_common.quote_chimerax(difference_image)} width {width} height {height} supersample 3",
+            "wait 1",
+        ])
+        images.append(proteus_common.display_path(difference_image))
+    commands.append(f"save {visual_common.quote_chimerax((destination / 'cryoem_workflow.cxs').resolve())}")
+
+    warnings = [
+        "Contour levels are absolute map values; compare several levels and retain the map's experimental context.",
+        "Rigid-body fitting can overstate agreement and should be validated independently, especially when the initial pose is poor.",
+    ]
+    if difference:
+        warnings.append("The model-derived difference map is qualitative and depends on resolution, sharpening, masking, and map scaling.")
+    data: dict[str, Any] = {
+        "workflow": "cryoem",
+        "model": proteus_common.display_path(model) if Path(model).expanduser().is_file() else model.upper(),
+        "map": proteus_common.display_path(density_map) if Path(density_map).expanduser().is_file() else density_map.upper(),
+        "map_statistics": stats,
+        "contour_levels": contour_levels,
+        "resolution_angstrom": resolution,
+        "fit_requested": fit,
+        "difference_map_requested": difference,
+        "images": images,
+        "session": proteus_common.display_path(destination / "cryoem_workflow.cxs"),
+        "executed": execute,
+    }
+    report = proteus_common.ok_payload(
+        data,
+        warnings=warnings,
+        provenance={"model": model_provenance, "map": map_provenance},
+    )
+    data["artifacts"] = visual_common.write_workflow(
+        destination, "cryoem_workflow", report=report, chimerax_lines=commands,
+    )
+    if execute:
+        analysis = [model_open, map_open]
+        if fit:
+            analysis.append(next(item for item in commands if item.startswith("fitmap ")))
+        analysis.append("measure mapstats #2")
+        data["analysis"] = _analysis_summary(
+            chimerax_agent.run_chimerax_command_list(analysis, timeout=600)
+        )
+        data["execution"] = {"chimerax": visual_common.run_chimerax(commands, timeout=1200)}
+        if data["execution"]["chimerax"].get("status") not in {"ok", "unavailable"}:
+            report["status"] = "error"
+            report["error"] = "ChimeraX map rendering failed."
+        proteus_common.write_json(destination / "cryoem_workflow.json", report)
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Inspect a cryo-EM map/model pair and produce contour, fit, and session artifacts.")
+    parser.add_argument("model", help="Local structure or PDB ID")
+    parser.add_argument("map", help="Local MRC/CCP4 map or EMDB ID")
+    parser.add_argument("--resolution", type=float, help="Nominal map resolution in angstroms")
+    parser.add_argument("--levels", help="Comma-separated absolute map contour values")
+    parser.add_argument("--fit", action="store_true", help="Rigid-body fit the model into the map")
+    parser.add_argument("--difference", action="store_true", help="Create a qualitative map-minus-model difference view")
+    parser.add_argument("--outdir", default="proteus_cryoem")
+    parser.add_argument("--execute", action="store_true")
+    parser.add_argument("--json", action="store_true", help="Emit JSON (accepted for consistency)")
+    args = parser.parse_args(argv)
+    try:
+        report = build_cryoem_workflow(
+            args.model, args.map, args.outdir, resolution=args.resolution, levels=args.levels,
+            fit=args.fit, difference=args.difference, execute=args.execute,
+        )
+    except (OSError, ValueError, visual_common.VisualWorkflowError) as exc:
+        print(json.dumps(proteus_common.error_payload(str(exc)), indent=2))
+        return 1
+    print(json.dumps(report, indent=2))
+    return 0 if report.get("status") == "ok" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/skills/proteus/scripts/electrostatics_workflow.py b/skills/proteus/scripts/electrostatics_workflow.py
new file mode 100644
index 0000000..11b71b1
--- /dev/null
+++ b/skills/proteus/scripts/electrostatics_workflow.py
@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""Create ChimeraX electrostatic surface workflows with explicit caveats."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import proteus_common
+import visual_common
+
+
+def build_electrostatics_workflow(
+    structure: str,
+    outdir: str,
+    *,
+    selection: str = "protein",
+    range_value: float = 10.0,
+    offset: float = 1.4,
+    execute: bool = False,
+    width: int = 1300,
+    height: int = 900,
+) -> dict[str, Any]:
+    source = Path(structure).expanduser()
+    if not source.is_file():
+        raise visual_common.VisualWorkflowError(f"Structure not found: {proteus_common.display_path(source)}")
+    visual_common.selection(selection)
+    if range_value <= 0 or offset < 0:
+        raise visual_common.VisualWorkflowError("Potential range must be positive and offset cannot be negative.")
+    destination = Path(outdir)
+    destination.mkdir(parents=True, exist_ok=True)
+    image = (destination / "electrostatic_surface.png").resolve()
+    session = (destination / "electrostatics.cxs").resolve()
+    atom_spec = f"#1 & {selection}"
+    commands = [
+        *visual_common.chimerax_base(),
+        f"open {visual_common.quote_chimerax(source.resolve())}",
+        f"surface {atom_spec}",
+        f"coulombic {atom_spec} offset {offset:g} palette red-white-blue range {-range_value:g},{range_value:g} key true",
+        f"transparency {atom_spec} 8 target s",
+        f"view {atom_spec}",
+        f"save {visual_common.quote_chimerax(image)} width {width} height {height} supersample 3",
+        "wait 1",
+        f"save {visual_common.quote_chimerax(session)}",
+    ]
+    external = {
+        "pdb2pqr": bool(proteus_common.find_executable("pdb2pqr", "pdb2pqr30")),
+        "apbs": bool(proteus_common.find_executable("apbs")),
+    }
+    data: dict[str, Any] = {
+        "workflow": "electrostatics",
+        "structure": proteus_common.display_path(source),
+        "selection": selection,
+        "potential_range_kcal_per_mol_e": [-range_value, range_value],
+        "surface_offset_angstrom": offset,
+        "method": "chimerax_coulombic",
+        "external_poisson_boltzmann_tools": external,
+        "image": proteus_common.display_path(image),
+        "session": proteus_common.display_path(session),
+        "executed": execute,
+    }
+    report = proteus_common.ok_payload(
+        data,
+        warnings=[
+            "Coulombic coloring is a qualitative potential estimate, not a Poisson-Boltzmann calculation.",
+            "Protonation, tautomer, charge, dielectric, ionic-strength, and missing-atom choices can change the interpretation.",
+            "Inspect ligands, metals, modified residues, termini, and alternate conformers before drawing mechanistic conclusions.",
+        ],
+        provenance={"structure": proteus_common.file_provenance(source)},
+    )
+    data["artifacts"] = visual_common.write_workflow(
+        destination, "electrostatics_workflow", report=report, chimerax_lines=commands,
+    )
+    if execute:
+        data["execution"] = {"chimerax": visual_common.run_chimerax(commands, timeout=900)}
+        if data["execution"]["chimerax"].get("status") not in {"ok", "unavailable"}:
+            report["status"] = "error"
+            report["error"] = "ChimeraX electrostatic rendering failed."
+        proteus_common.write_json(destination / "electrostatics_workflow.json", report)
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Create a ChimeraX Coulombic electrostatic surface and reusable session.")
+    parser.add_argument("structure")
+    parser.add_argument("--selection", default="protein", help="ChimeraX atom selection (default: protein)")
+    parser.add_argument("--range", dest="range_value", type=float, default=10.0, help="Symmetric potential color range")
+    parser.add_argument("--offset", type=float, default=1.4, help="Distance outward from the surface for evaluating potential")
+    parser.add_argument("--outdir", default="proteus_electrostatics")
+    parser.add_argument("--execute", action="store_true")
+    parser.add_argument("--json", action="store_true", help="Emit JSON (accepted for consistency)")
+    args = parser.parse_args(argv)
+    try:
+        report = build_electrostatics_workflow(
+            args.structure, args.outdir, selection=args.selection, range_value=args.range_value,
+            offset=args.offset, execute=args.execute,
+        )
+    except (OSError, ValueError, visual_common.VisualWorkflowError) as exc:
+        print(json.dumps(proteus_common.error_payload(str(exc)), indent=2))
+        return 1
+    print(json.dumps(report, indent=2))
+    return 0 if report.get("status") == "ok" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/skills/proteus/scripts/ensemble_report.py b/skills/proteus/scripts/ensemble_report.py
new file mode 100644
index 0000000..48f3f1e
--- /dev/null
+++ b/skills/proteus/scripts/ensemble_report.py
@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+"""Analyze a multi-model coordinate ensemble and build replayable views."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import re
+import sys
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import proteus_common
+import structure_qc
+import visual_common
+
+
+SPEC_RE = re.compile(r"^[A-Za-z0-9_.+?-]+$")
+
+
+def _coordinates_by_model(atoms: list[dict[str, Any]]) -> tuple[list[int], list[tuple[Any, ...]], list[list[list[float]]]]:
+    models = sorted({int(atom["model"]) for atom in atoms})
+    ca_by_model: dict[int, dict[tuple[Any, ...], list[float]]] = defaultdict(dict)
+    for atom in atoms:
+        if atom["atom_name"] != "CA":
+            continue
+        key = (atom["chain"], atom["residue_id"], atom["insertion_code"], atom["resname"])
+        ca_by_model[int(atom["model"])][key] = [float(atom[axis]) for axis in ("x", "y", "z")]
+    if not models:
+        return [], [], []
+    common = sorted(set.intersection(*(set(ca_by_model[model]) for model in models)))
+    coordinates = [[ca_by_model[model][key] for key in common] for model in models]
+    return models, common, coordinates
+
+
+def _center(coordinates: list[list[float]]) -> tuple[list[list[float]], list[float]]:
+    centroid = [sum(point[axis] for point in coordinates) / len(coordinates) for axis in range(3)]
+    return [[point[axis] - centroid[axis] for axis in range(3)] for point in coordinates], centroid
+
+
+def _align(coordinates: list[list[list[float]]]) -> tuple[list[list[list[float]]], str]:
+    if not coordinates or not coordinates[0]:
+        return coordinates, "none"
+    try:
+        import numpy as np
+
+        reference, _ = _center(coordinates[0])
+        reference_array = np.asarray(reference, dtype=float)
+        aligned = []
+        for model_coordinates in coordinates:
+            centered, _ = _center(model_coordinates)
+            mobile = np.asarray(centered, dtype=float)
+            covariance = mobile.T @ reference_array
+            left, _singular, right_t = np.linalg.svd(covariance)
+            rotation = left @ right_t
+            if np.linalg.det(rotation) < 0:
+                left[:, -1] *= -1
+                rotation = left @ right_t
+            aligned.append((mobile @ rotation).tolist())
+        return aligned, "kabsch_ca"
+    except ImportError:
+        return [_center(model)[0] for model in coordinates], "centroid_translation"
+
+
+def _rmsf(coordinates: list[list[list[float]]]) -> list[float]:
+    count = len(coordinates)
+    output = []
+    for atom_index in range(len(coordinates[0])):
+        mean = [sum(model[atom_index][axis] for model in coordinates) / count for axis in range(3)]
+        squared = sum(
+            sum((model[atom_index][axis] - mean[axis]) ** 2 for axis in range(3))
+            for model in coordinates
+        ) / count
+        output.append(math.sqrt(squared))
+    return output
+
+
+def analyze_ensemble(structure: str, outdir: str, *, execute: bool = False,
+                     width: int = 1300, height: int = 900) -> dict[str, Any]:
+    source = Path(structure).expanduser()
+    if not source.is_file():
+        raise visual_common.VisualWorkflowError(f"Structure not found: {proteus_common.display_path(source)}")
+    text = structure_qc._read_text(source)
+    fmt = structure_qc._format_from_path(source)
+    raw, parser_meta = structure_qc.parse_mmcif(text) if fmt == "mmcif" else structure_qc.parse_pdb(text)
+    atoms, selection = structure_qc.select_atoms(raw, model="all", altloc="highest")
+    models, keys, coordinates = _coordinates_by_model(atoms)
+    if len(models) < 2:
+        raise visual_common.VisualWorkflowError("Ensemble analysis requires at least two coordinate models.")
+    if len(keys) < 3:
+        raise visual_common.VisualWorkflowError("Fewer than three common C-alpha atoms were found across models.")
+    aligned, method = _align(coordinates)
+    fluctuations = _rmsf(aligned)
+    residues = []
+    for key, value in zip(keys, fluctuations):
+        chain, residue_id, insertion_code, resname = key
+        residues.append({
+            "chain": chain,
+            "residue": f"{residue_id}{insertion_code}",
+            "resname": resname,
+            "rmsf_angstrom": round(value, 3),
+        })
+    ranked = sorted(residues, key=lambda item: item["rmsf_angstrom"], reverse=True)
+    destination = Path(outdir)
+    destination.mkdir(parents=True, exist_ok=True)
+
+    pml = visual_common.pymol_base(width=width, height=height)
+    pml.extend([
+        f"load {visual_common.quote_pymol(source.resolve())}, ensemble",
+        "hide everything, all",
+        "show cartoon, ensemble",
+        "intra_fit ensemble and name CA, 1",
+    ])
+    cxc = [
+        *visual_common.chimerax_base(),
+        f"open {visual_common.quote_chimerax(source.resolve())} coordsets true",
+        "cartoon #1",
+        "coordset #1 1",
+    ]
+    assigned = 0
+    for item in residues:
+        chain = str(item["chain"])
+        residue = str(item["residue"])
+        if not SPEC_RE.fullmatch(chain) or not SPEC_RE.fullmatch(residue):
+            continue
+        value = item["rmsf_angstrom"]
+        pml.append(f"alter ensemble and chain {chain} and resi {residue}, b={value:g}")
+        cxc.append(f"setattr #1/{chain}:{residue} r proteus_rmsf {value:g} create true type float")
+        assigned += 1
+    pml.extend([
+        "spectrum b, blue_white_red, ensemble",
+        "set all_states, on",
+        "set cartoon_transparency, 0.35",
+        *visual_common.finalize_pymol(
+            destination / "ensemble.png", width=width, height=height,
+            session=destination / "ensemble.pse",
+        ),
+    ])
+    cxc.extend([
+        "color byattribute r:proteus_rmsf #1 palette blue:white:red",
+        "coordset #1",
+        f"save {visual_common.quote_chimerax((destination / 'ensemble.cxs').resolve())}",
+    ])
+    data: dict[str, Any] = {
+        "workflow": "ensemble",
+        "structure": proteus_common.display_path(source),
+        "models": models,
+        "model_count": len(models),
+        "common_ca_count": len(keys),
+        "alignment_method": method,
+        "rmsf_summary_angstrom": {
+            "mean": round(sum(fluctuations) / len(fluctuations), 3),
+            "max": round(max(fluctuations), 3),
+        },
+        "most_variable_residues": ranked[:20],
+        "residues": residues,
+        "visual_attributes_assigned": assigned,
+        "parser": parser_meta,
+        "selection": selection,
+        "executed": execute,
+    }
+    warnings = [
+        "RMSF reports coordinate dispersion across the supplied models; it is not an experimental uncertainty estimate.",
+        "Only C-alpha atoms present in every model are compared.",
+    ]
+    if method == "centroid_translation":
+        warnings.append("NumPy was unavailable, so models were centered but not rotationally superposed for RMSF.")
+    report = proteus_common.ok_payload(
+        data, warnings=warnings, provenance={"structure": proteus_common.file_provenance(source)},
+    )
+    data["artifacts"] = visual_common.write_workflow(
+        destination, "ensemble_report", report=report, pymol_lines=pml, chimerax_lines=cxc,
+    )
+    if execute:
+        data["execution"] = {
+            "pymol": visual_common.run_pymol(destination / "ensemble_report.pml"),
+            "chimerax": visual_common.run_chimerax(cxc),
+        }
+        failures = [name for name, result in data["execution"].items() if result.get("status") not in {"ok", "unavailable"}]
+        if failures:
+            report["status"] = "error"
+            report["error"] = f"Ensemble rendering failed for: {', '.join(failures)}"
+        proteus_common.write_json(destination / "ensemble_report.json", report)
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Analyze multi-model structural variability and build PyMOL/ChimeraX sessions.")
+    parser.add_argument("structure", help="Multi-model PDB/mmCIF file")
+    parser.add_argument("--outdir", default="proteus_ensemble")
+    parser.add_argument("--execute", action="store_true")
+    parser.add_argument("--json", action="store_true", help="Emit JSON (accepted for consistency)")
+    args = parser.parse_args(argv)
+    try:
+        report = analyze_ensemble(args.structure, args.outdir, execute=args.execute)
+    except (OSError, ValueError, structure_qc.StructureQCError, visual_common.VisualWorkflowError) as exc:
+        print(json.dumps(proteus_common.error_payload(str(exc)), indent=2))
+        return 1
+    print(json.dumps(report, indent=2))
+    return 0 if report.get("status") == "ok" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/skills/proteus/scripts/interface_story.py b/skills/proteus/scripts/interface_story.py
new file mode 100644
index 0000000..538c62a
--- /dev/null
+++ b/skills/proteus/scripts/interface_story.py
@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+"""Create an interface analysis report with ChimeraX and PyMOL artifacts."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import chimerax_agent
+import interface_report
+import proteus_common
+import visual_common
+
+
+def _analysis_summary(result: dict[str, Any]) -> dict[str, Any]:
+    cleaned = proteus_common.scrub_private(result)
+    output: dict[str, Any] = {"status": cleaned.get("status", "error")}
+    if cleaned.get("error"):
+        output["error"] = cleaned["error"]
+    info = cleaned.get("info") or cleaned.get("data", {}).get("info") or []
+    text = "\n".join(str(item) for item in info)
+    buried = re.findall(r"Buried area .*?=\s*([0-9.]+)", text)
+    hydrogen = re.findall(r"(\d+) hydrogen bonds found", text)
+    contacts = re.findall(r"(?m)^(\d+) contacts$", text)
+    clashes = re.findall(r"(?m)^(\d+) clashes$", text)
+    output["metrics"] = {
+        "buried_area_angstrom2": float(buried[-1]) if buried else None,
+        "hydrogen_bonds": int(hydrogen[-1]) if hydrogen else None,
+        "contacts": max((int(value) for value in contacts), default=None),
+        "clashes": max((int(value) for value in clashes), default=None),
+    }
+    return output
+
+
+def _chain(value: str) -> str:
+    if not value or not value.replace("_", "").isalnum():
+        raise visual_common.VisualWorkflowError(f"Invalid chain identifier: {value!r}")
+    return value
+
+
+def _pymol_lines(structure: Path, chain1: str, chain2: str, outdir: Path,
+                  cutoff: float, width: int, height: int) -> list[str]:
+    overview = (outdir / "interface_overview.png").resolve()
+    closeup = (outdir / "interface_closeup.png").resolve()
+    session = (outdir / "interface_story.pse").resolve()
+    lines = visual_common.pymol_base(width=width, height=height)
+    lines.extend([
+        f"load {visual_common.quote_pymol(structure.resolve())}, complex",
+        "hide everything, all",
+        f"show cartoon, chain {chain1} or chain {chain2}",
+        f"color marine, chain {chain1}",
+        f"color salmon, chain {chain2}",
+        f"select interface1, byres (chain {chain1} within {cutoff:.2f} of chain {chain2})",
+        f"select interface2, byres (chain {chain2} within {cutoff:.2f} of chain {chain1})",
+        "show sticks, interface1 or interface2",
+        "color cyan, interface1",
+        "color orange, interface2",
+        f"orient chain {chain1} or chain {chain2}",
+        f"ray {width}, {height}",
+        *visual_common.pymol_png(overview, width=width, height=height),
+        "distance interface_polar, interface1, interface2, 3.6, 2",
+        "set dash_color, gray30, interface_polar",
+        "label (interface1 or interface2) and name CA, resn + resi",
+        "orient interface1 or interface2",
+        "zoom interface1 or interface2, 4",
+        f"ray {width}, {height}",
+        *visual_common.pymol_png(closeup, width=width, height=height),
+        *visual_common.pymol_save(session),
+        "quit",
+    ])
+    return lines
+
+
+def _chimerax_lines(structure: Path, chain1: str, chain2: str, outdir: Path,
+                    width: int, height: int) -> list[str]:
+    image = (outdir / "interface_chimerax.png").resolve()
+    session = (outdir / "interface_story.cxs").resolve()
+    left = f"(#1/{chain1} & protein)"
+    right = f"(#1/{chain2} & protein)"
+    return [
+        *visual_common.chimerax_base(),
+        f"open {visual_common.quote_chimerax(structure.resolve())}",
+        "cartoon",
+        f"color #1/{chain1} marine",
+        f"color #1/{chain2} salmon",
+        f"measure buriedarea {left} withAtoms2 {right} listResidues true select true color magenta",
+        f"hbonds #1/{chain1} restrict #1/{chain2} reveal true log true",
+        f"contacts #1/{chain1} restrict #1/{chain2} reveal true showDist true log true",
+        f"clashes #1/{chain1} restrict #1/{chain2} reveal true showDist true log true",
+        "show sel atoms",
+        "style sel stick",
+        "view sel",
+        f"save {visual_common.quote_chimerax(image)} width {width} height {height} supersample 3",
+        "wait 1",
+        f"save {visual_common.quote_chimerax(session)}",
+    ]
+
+
+def build_interface_story(structure: str, chains: str, outdir: str, *, cutoff: float = 5.0,
+                          execute: bool = False, width: int = 1300, height: int = 900) -> dict[str, Any]:
+    source = Path(structure).expanduser()
+    if not source.is_file():
+        raise visual_common.VisualWorkflowError(f"Structure not found: {proteus_common.display_path(source)}")
+    parts = [_chain(item.strip()) for item in chains.split(",") if item.strip()]
+    if len(parts) != 2:
+        raise visual_common.VisualWorkflowError("--chains must contain exactly two identifiers, such as A,B.")
+    if cutoff <= 0:
+        raise visual_common.VisualWorkflowError("Cutoff must be positive.")
+    local = interface_report.analyze_interfaces(str(source), cutoff, chains_filter=parts)
+    destination = Path(outdir)
+    destination.mkdir(parents=True, exist_ok=True)
+    data: dict[str, Any] = {
+        "workflow": "interface_story",
+        "structure": proteus_common.display_path(source),
+        "chains": parts,
+        "cutoff_angstrom": cutoff,
+        "local_geometry": local.get("data", {}),
+        "images": {
+            "overview": proteus_common.display_path(destination / "interface_overview.png"),
+            "closeup": proteus_common.display_path(destination / "interface_closeup.png"),
+            "chimerax": proteus_common.display_path(destination / "interface_chimerax.png"),
+        },
+        "sessions": {
+            "pymol": proteus_common.display_path(destination / "interface_story.pse"),
+            "chimerax": proteus_common.display_path(destination / "interface_story.cxs"),
+        },
+        "executed": execute,
+    }
+    report = proteus_common.ok_payload(
+        data,
+        warnings=[
+            "Distance-based contacts are geometric candidates; hydrogen bonding and energetic hotspots require chemical context.",
+            "Buried area excludes solvent, ions, and ligands by explicitly measuring protein atoms only.",
+        ],
+        provenance={"structure": proteus_common.file_provenance(source)},
+    )
+    pml = _pymol_lines(source, parts[0], parts[1], destination, cutoff, width, height)
+    cxc = _chimerax_lines(source, parts[0], parts[1], destination, width, height)
+    data["artifacts"] = visual_common.write_workflow(
+        destination, "interface_story", report=report, pymol_lines=pml, chimerax_lines=cxc,
+    )
+    if execute:
+        analysis_commands = [
+            f"open {visual_common.quote_chimerax(source.resolve())}",
+            f"measure buriedarea (#1/{parts[0]} & protein) withAtoms2 (#1/{parts[1]} & protein) listResidues true",
+            f"hbonds #1/{parts[0]} restrict #1/{parts[1]} log true",
+            f"contacts #1/{parts[0]} restrict #1/{parts[1]} log true",
+            f"clashes #1/{parts[0]} restrict #1/{parts[1]} log true",
+        ]
+        data["chimerax_analysis"] = _analysis_summary(
+            chimerax_agent.run_chimerax_command_list(analysis_commands, timeout=300)
+        )
+        pymol_result = visual_common.run_pymol(destination / "interface_story.pml")
+        chimerax_result = visual_common.run_chimerax(cxc)
+        data["execution"] = {"pymol": pymol_result, "chimerax": chimerax_result}
+        failures = [name for name, result in data["execution"].items() if result.get("status") not in {"ok", "unavailable"}]
+        if failures:
+            report["status"] = "error"
+            report["error"] = f"Interface rendering failed for: {', '.join(failures)}"
+        proteus_common.write_json(destination / "interface_story.json", report)
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Create a protein-interface analysis and publication figure set.")
+    parser.add_argument("structure", help="Local PDB/mmCIF structure")
+    parser.add_argument("--chains", required=True, help="Two chain IDs, e.g. A,D")
+    parser.add_argument("--cutoff", type=float, default=5.0)
+    parser.add_argument("--outdir", default="proteus_interface")
+    parser.add_argument("--execute", action="store_true", help="Run ChimeraX analysis and both renderers")
+    parser.add_argument("--json", action="store_true", help="Emit JSON (accepted for consistency)")
+    args = parser.parse_args(argv)
+    try:
+        report = build_interface_story(args.structure, args.chains, args.outdir, cutoff=args.cutoff,
+                                       execute=args.execute)
+    except (OSError, ValueError, visual_common.VisualWorkflowError) as exc:
+        print(json.dumps(proteus_common.error_payload(str(exc)), indent=2))
+        return 1
+    print(json.dumps(report, indent=2))
+    return 0 if report.get("status") == "ok" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/skills/proteus/scripts/model_quality.py b/skills/proteus/scripts/model_quality.py
index 00b8b1c..9c4ce37 100644
--- a/skills/proteus/scripts/model_quality.py
+++ b/skills/proteus/scripts/model_quality.py
@@ -12,8 +12,15 @@
 import shutil
 import subprocess
 import sys
+import tempfile
 from pathlib import Path
 
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import proteus_common
+
 
 FLOAT_RE = r"[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[Ee][+-]?\d+)?"
 TOOL_CANDIDATES = {
@@ -43,7 +50,7 @@ def detect_tools() -> dict:
         executable, path = _find_candidate(candidates)
         tools[name] = {
             "available": bool(path),
-            "path": path,
+            "path": proteus_common.display_path(path) if path else None,
             "executable": executable,
             "candidates": candidates,
         }
@@ -125,7 +132,7 @@ def _run_usalign(reference: str, mobile: str, timeout: int) -> dict:
     mobile_path = Path(mobile)
     for path in (reference_path, mobile_path):
         if not path.exists():
-            return _payload("error", {"error": f"File not found: {path}"})
+            return _payload("error", {"error": f"File not found: {proteus_common.display_path(path)}"})
 
     executable, usalign_path = _find_candidate(TOOL_CANDIDATES["usalign"])
     if not usalign_path:
@@ -135,8 +142,8 @@ def _run_usalign(reference: str, mobile: str, timeout: int) -> dict:
                 "tool": "usalign",
                 "available": False,
                 "error": "USalign executable not found on PATH",
-                "reference": str(reference_path),
-                "mobile": str(mobile_path),
+                "reference": proteus_common.display_path(reference_path),
+                "mobile": proteus_common.display_path(mobile_path),
             },
         )
 
@@ -155,11 +162,11 @@ def _run_usalign(reference: str, mobile: str, timeout: int) -> dict:
             {
                 "tool": "usalign",
                 "available": True,
-                "path": usalign_path,
+                "path": proteus_common.display_path(usalign_path),
                 "executable": executable,
                 "error": f"USalign timed out after {timeout} seconds",
-                "stdout": exc.stdout or "",
-                "stderr": exc.stderr or "",
+                "stdout": proteus_common.scrub_text(exc.stdout or ""),
+                "stderr": proteus_common.scrub_text(exc.stderr or ""),
             },
         )
 
@@ -169,12 +176,12 @@ def _run_usalign(reference: str, mobile: str, timeout: int) -> dict:
             {
                 "tool": "usalign",
                 "available": True,
-                "path": usalign_path,
+                "path": proteus_common.display_path(usalign_path),
                 "executable": executable,
                 "returncode": proc.returncode,
                 "error": "USalign exited with a non-zero status",
-                "stdout": proc.stdout,
-                "stderr": proc.stderr,
+                "stdout": proteus_common.scrub_text(proc.stdout),
+                "stderr": proteus_common.scrub_text(proc.stderr),
             },
         )
 
@@ -184,15 +191,110 @@ def _run_usalign(reference: str, mobile: str, timeout: int) -> dict:
         {
             "tool": "usalign",
             "available": True,
-            "path": usalign_path,
+            "path": proteus_common.display_path(usalign_path),
             "executable": executable,
-            "reference": str(reference_path),
-            "mobile": str(mobile_path),
+            "reference": proteus_common.display_path(reference_path),
+            "mobile": proteus_common.display_path(mobile_path),
             "metrics": metrics,
         },
     )
 
 
+def _validated_paths(*values: str) -> tuple[list[Path] | None, dict | None]:
+    paths = [Path(value) for value in values]
+    missing = [proteus_common.display_path(path) for path in paths if not path.exists()]
+    if missing:
+        return None, _payload("error", {"error": f"File or directory not found: {missing[0]}"})
+    return paths, None
+
+
+def _run_dockq(model: str, native: str, timeout: int) -> dict:
+    paths, error = _validated_paths(model, native)
+    if error:
+        return error
+    assert paths is not None
+    executable, dockq_path = _find_candidate(TOOL_CANDIDATES["dockq"])
+    if not dockq_path:
+        return _payload("unavailable", {"tool": "dockq", "available": False, "error": "DockQ executable not found on PATH"})
+    with tempfile.NamedTemporaryFile(suffix=".json") as output:
+        try:
+            proc = subprocess.run(
+                [dockq_path, str(paths[0]), str(paths[1]), "--json", output.name],
+                text=True, capture_output=True, timeout=timeout, check=False,
+            )
+        except subprocess.TimeoutExpired:
+            return _payload("error", {"tool": "dockq", "available": True, "error": f"DockQ timed out after {timeout} seconds"})
+        if proc.returncode != 0:
+            return _payload("error", {
+                "tool": "dockq", "available": True, "returncode": proc.returncode,
+                "error": "DockQ exited with a non-zero status", "stderr": proteus_common.scrub_text(proc.stderr),
+            })
+        try:
+            metrics = json.loads(Path(output.name).read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            return _payload("error", {"tool": "dockq", "available": True, "error": f"DockQ JSON could not be read: {exc}"})
+    return _payload("ok", {
+        "tool": "dockq", "available": True, "path": proteus_common.display_path(dockq_path), "executable": executable,
+        "model": proteus_common.display_path(paths[0]), "native": proteus_common.display_path(paths[1]), "metrics": metrics,
+        "interpretation": "DockQ is interface- and chain-mapping-dependent; review the reported mapping before using the score.",
+    })
+
+
+FOLDSEEK_FIELDS = ["query", "target", "alntmscore", "qtmscore", "ttmscore", "lddt", "evalue", "bits"]
+
+
+def _parse_foldseek_table(text: str) -> list[dict]:
+    results = []
+    numeric = set(FOLDSEEK_FIELDS[2:])
+    for line in text.splitlines():
+        columns = line.split("\t")
+        if len(columns) != len(FOLDSEEK_FIELDS):
+            continue
+        item = dict(zip(FOLDSEEK_FIELDS, columns))
+        for key in numeric:
+            try:
+                item[key] = float(item[key])
+            except ValueError:
+                pass
+        results.append(item)
+    return results
+
+
+def _run_foldseek(query: str, target: str, timeout: int) -> dict:
+    paths, error = _validated_paths(query, target)
+    if error:
+        return error
+    assert paths is not None
+    executable, foldseek_path = _find_candidate(TOOL_CANDIDATES["foldseek"])
+    if not foldseek_path:
+        return _payload("unavailable", {"tool": "foldseek", "available": False, "error": "Foldseek executable not found on PATH"})
+    with tempfile.TemporaryDirectory(prefix="proteus-foldseek-") as temporary:
+        root = Path(temporary)
+        output = root / "results.tsv"
+        work = root / "work"
+        command = [
+            foldseek_path, "easy-search", str(paths[0]), str(paths[1]), str(output), str(work),
+            "--format-output", ",".join(FOLDSEEK_FIELDS),
+        ]
+        try:
+            proc = subprocess.run(command, text=True, capture_output=True, timeout=timeout, check=False)
+        except subprocess.TimeoutExpired:
+            return _payload("error", {"tool": "foldseek", "available": True, "error": f"Foldseek timed out after {timeout} seconds"})
+        if proc.returncode != 0:
+            return _payload("error", {
+                "tool": "foldseek", "available": True, "returncode": proc.returncode,
+                "error": "Foldseek exited with a non-zero status", "stderr": proteus_common.scrub_text(proc.stderr),
+            })
+        if not output.is_file():
+            return _payload("error", {"tool": "foldseek", "available": True, "error": "Foldseek did not create its result table"})
+        hits = _parse_foldseek_table(output.read_text(encoding="utf-8", errors="replace"))
+    return _payload("ok", {
+        "tool": "foldseek", "available": True, "path": proteus_common.display_path(foldseek_path), "executable": executable,
+        "query": proteus_common.display_path(paths[0]), "target": proteus_common.display_path(paths[1]), "hit_count": len(hits), "hits": hits,
+        "interpretation": "TM-score normalization and local/global alignment choices affect comparisons; inspect coverage and both normalized scores.",
+    })
+
+
 def _print_detect_text(report: dict) -> None:
     for name, tool in report["tools"].items():
         value = tool["path"] if tool["available"] else "unavailable"
@@ -224,6 +326,18 @@ def main(argv: list[str] | None = None) -> int:
     usalign_parser.add_argument("--timeout", type=int, default=300, help="USalign timeout in seconds")
     usalign_parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
 
+    dockq_parser = subparsers.add_parser("dockq", help="Run DockQ on a model/native complex pair")
+    dockq_parser.add_argument("model", help="Docked model structure")
+    dockq_parser.add_argument("native", help="Native/reference complex")
+    dockq_parser.add_argument("--timeout", type=int, default=600)
+    dockq_parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
+
+    foldseek_parser = subparsers.add_parser("foldseek", help="Run a local Foldseek easy-search")
+    foldseek_parser.add_argument("query", help="Query structure file or directory")
+    foldseek_parser.add_argument("target", help="Target structure file, directory, or database")
+    foldseek_parser.add_argument("--timeout", type=int, default=1200)
+    foldseek_parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
+
     args = parser.parse_args(argv)
     if args.command == "detect":
         report = detect_tools()
@@ -241,6 +355,16 @@ def main(argv: list[str] | None = None) -> int:
             _print_usalign_text(report)
         return 1 if report["status"] == "error" else 0
 
+    if args.command == "dockq":
+        report = _run_dockq(args.model, args.native, args.timeout)
+        print(json.dumps(report, indent=2))
+        return 1 if report["status"] == "error" else 0
+
+    if args.command == "foldseek":
+        report = _run_foldseek(args.query, args.target, args.timeout)
+        print(json.dumps(report, indent=2))
+        return 1 if report["status"] == "error" else 0
+
     parser.error(f"unknown command: {args.command}")
     return 2
 
diff --git a/skills/proteus/scripts/pae_report.py b/skills/proteus/scripts/pae_report.py
index c0a1b7c..d294611 100644
--- a/skills/proteus/scripts/pae_report.py
+++ b/skills/proteus/scripts/pae_report.py
@@ -11,6 +11,12 @@
 import sys
 from pathlib import Path
 
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import proteus_common
+
 
 def _error_payload(message: str) -> dict:
     return {"status": "error", "error": message}
@@ -84,8 +90,62 @@ def _segments(values: list[float], threshold: float, min_len: int, high: bool) -
     return segments
 
 
+def _parse_chain_lengths(value: str | None) -> list[tuple[str, int]]:
+    if not value:
+        return []
+    output = []
+    for index, item in enumerate(value.split(","), start=1):
+        item = item.strip()
+        if not item:
+            continue
+        if ":" in item:
+            chain, length_text = item.rsplit(":", 1)
+        else:
+            chain, length_text = f"chain_{index}", item
+        try:
+            length = int(length_text)
+        except ValueError as exc:
+            raise ValueError("Chain lengths must look like A:120,B:95 or 120,95.") from exc
+        if not chain or length <= 0:
+            raise ValueError("Chain names must be non-empty and lengths must be positive.")
+        output.append((chain, length))
+    return output
+
+
+def _chain_blocks(matrix: list[list[float]], chain_lengths: list[tuple[str, int]]) -> dict:
+    if not chain_lengths:
+        return {}
+    size = len(matrix)
+    if len(matrix[0]) != size:
+        raise ValueError("Chain-aware PAE analysis requires a square matrix.")
+    if sum(length for _chain, length in chain_lengths) != size:
+        raise ValueError("Chain lengths must sum to the PAE matrix size.")
+    ranges = []
+    start = 0
+    for chain, length in chain_lengths:
+        ranges.append((chain, start, start + length))
+        start += length
+    blocks = []
+    for row_chain, row_start, row_end in ranges:
+        for column_chain, column_start, column_end in ranges:
+            values = [matrix[row][column] for row in range(row_start, row_end) for column in range(column_start, column_end)]
+            blocks.append({
+                "row_chain": row_chain,
+                "column_chain": column_chain,
+                "kind": "within_chain" if row_chain == column_chain else "between_chain",
+                "mean_pae": round(sum(values) / len(values), 2),
+                "min_pae": round(min(values), 2),
+                "max_pae": round(max(values), 2),
+            })
+    residue_map = []
+    for chain, chain_start, chain_end in ranges:
+        for index in range(chain_start, chain_end):
+            residue_map.append({"index": index + 1, "chain": chain, "chain_index": index - chain_start + 1})
+    return {"chains": [{"chain": chain, "length": end - start} for chain, start, end in ranges], "blocks": blocks, "residue_map": residue_map}
+
+
 def summarize_pae(path: str, flex_threshold: float = 15.0, rigid_threshold: float = 5.0,
-                  min_segment: int = 5) -> dict:
+                  min_segment: int = 5, chain_lengths: str | None = None) -> dict:
     payload = json.loads(Path(path).read_text())
     matrix = _validate_matrix(_matrix_from_payload(payload))
     row_count = len(matrix)
@@ -93,7 +153,7 @@ def summarize_pae(path: str, flex_threshold: float = 15.0, rigid_threshold: floa
     flat = [value for row in matrix for value in row]
     per_residue_mean = [sum(row) / len(row) for row in matrix]
     data = {
-        "file": str(Path(path).resolve()),
+        "file": proteus_common.display_path(path),
         "size": {"rows": row_count, "columns": col_count},
         "pae": {
             "min": round(min(flat), 2),
@@ -109,10 +169,13 @@ def summarize_pae(path: str, flex_threshold: float = 15.0, rigid_threshold: floa
         "rigid_candidate_regions": _segments(per_residue_mean, rigid_threshold, min_segment, high=False),
         "per_residue_mean_pae": [round(value, 2) for value in per_residue_mean],
     }
+    parsed_chains = _parse_chain_lengths(chain_lengths)
+    if parsed_chains:
+        data["chain_analysis"] = _chain_blocks(matrix, parsed_chains)
     return _ok_payload(data)
 
 
-def main():
+def main(argv: list[str] | None = None):
     parser = argparse.ArgumentParser(description="Summarize AlphaFold PAE JSON into domain/flexibility hints.")
     parser.add_argument("pae_json", help="Path to PAE JSON")
     parser.add_argument("--flex-threshold", type=float, default=15.0,
@@ -121,11 +184,13 @@ def main():
                         help="Mean PAE threshold for rigid candidate regions (default: 5)")
     parser.add_argument("--min-segment", type=int, default=5,
                         help="Minimum contiguous segment length (default: 5)")
+    parser.add_argument("--chain-lengths", help="Chain names and lengths, e.g. A:120,B:95")
     parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
-    args = parser.parse_args()
+    args = parser.parse_args(argv)
 
     try:
-        output = summarize_pae(args.pae_json, args.flex_threshold, args.rigid_threshold, args.min_segment)
+        output = summarize_pae(args.pae_json, args.flex_threshold, args.rigid_threshold,
+                               args.min_segment, args.chain_lengths)
     except (OSError, ValueError, json.JSONDecodeError) as exc:
         if args.json:
             print(json.dumps(_error_payload(str(exc)), indent=2))
diff --git a/skills/proteus/scripts/pocket_tunnel.py b/skills/proteus/scripts/pocket_tunnel.py
new file mode 100644
index 0000000..e2cf2a5
--- /dev/null
+++ b/skills/proteus/scripts/pocket_tunnel.py
@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+"""Run optional pocket detection and prepare PyMOL/ChimeraX review artifacts."""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import proteus_common
+import visual_common
+
+
+def _copy_matches(root: Path, pattern: str, destination: Path) -> list[Path]:
+    destination.mkdir(parents=True, exist_ok=True)
+    output = []
+    for index, source in enumerate(sorted(root.rglob(pattern)), start=1):
+        target = destination / f"pocket_{index}{source.suffix.lower()}"
+        shutil.copy2(source, target)
+        output.append(target)
+    return output
+
+
+def _run_fpocket(executable: str, structure: Path, destination: Path) -> tuple[dict[str, Any], list[Path]]:
+    if structure.suffix.lower() not in {".pdb", ".ent"}:
+        return {"status": "error", "error": "fpocket execution requires a PDB-format input."}, []
+    with tempfile.TemporaryDirectory(prefix="proteus-fpocket-") as temporary:
+        workdir = Path(temporary)
+        local = workdir / "input.pdb"
+        shutil.copy2(structure, local)
+        result = proteus_common.run_command([executable, "-f", local.name], cwd=workdir, timeout=900)
+        pockets = _copy_matches(workdir, "pocket*_atm.pdb", destination / "pockets") if result["status"] == "ok" else []
+    result.pop("stdout", None)
+    result.pop("stderr", None)
+    result["pockets_found"] = len(pockets)
+    return result, pockets
+
+
+def _run_p2rank(executable: str, structure: Path, destination: Path) -> tuple[dict[str, Any], list[Path], list[dict[str, str]]]:
+    workdir = destination / "p2rank"
+    workdir.mkdir(parents=True, exist_ok=True)
+    result = proteus_common.run_command(
+        [executable, "predict", "-f", str(structure.resolve()), "-o", str(workdir.resolve())],
+        timeout=1200,
+    )
+    result.pop("stdout", None)
+    result.pop("stderr", None)
+    pockets = _copy_matches(workdir, "*.pdb", destination / "pockets") if result["status"] == "ok" else []
+    predictions: list[dict[str, str]] = []
+    for table in sorted(workdir.rglob("*predictions*.csv")):
+        try:
+            with table.open(newline="", encoding="utf-8-sig") as handle:
+                predictions.extend(dict(row) for row in csv.DictReader(handle))
+        except (OSError, csv.Error):
+            continue
+    result["pocket_files_found"] = len(pockets)
+    result["prediction_rows"] = len(predictions)
+    return result, pockets, predictions
+
+
+def _scripts(structure: Path, pockets: list[Path], destination: Path,
+             width: int, height: int) -> tuple[list[str], list[str]]:
+    pml = visual_common.pymol_base(width=width, height=height)
+    pml.extend([
+        f"load {visual_common.quote_pymol(structure.resolve())}, structure",
+        "hide everything, all",
+        "show cartoon, structure and polymer",
+        "color gray80, structure and polymer",
+    ])
+    cxc = [
+        *visual_common.chimerax_base(),
+        f"open {visual_common.quote_chimerax(structure.resolve())}",
+        "cartoon #1",
+        "color #1 lightgray",
+    ]
+    for index, pocket in enumerate(pockets, start=1):
+        pml.extend([
+            f"load {visual_common.quote_pymol(pocket.resolve())}, pocket_{index}",
+            f"show spheres, pocket_{index}",
+            f"set sphere_scale, 0.35, pocket_{index}",
+            f"color tv_orange, pocket_{index}",
+            f"select pocket_{index}_lining, byres (structure and polymer within 4.5 of pocket_{index})",
+            f"show sticks, pocket_{index}_lining",
+        ])
+        cxc.extend([
+            f"open {visual_common.quote_chimerax(pocket.resolve())}",
+            f"style #{index + 1} sphere",
+            f"color #{index + 1} orange",
+            f"select zone #{index + 1} 4.5 residues true",
+            "show sel atoms",
+            "style sel stick",
+        ])
+    pml.extend(visual_common.finalize_pymol(
+        destination / "pockets.png", width=width, height=height,
+        session=destination / "pockets.pse",
+    ))
+    cxc.extend(visual_common.finalize_chimerax(
+        destination / "pockets_chimerax.png", width=width, height=height,
+        session=destination / "pockets.cxs",
+    ))
+    return pml, cxc
+
+
+def pocket_tunnel_workflow(structure: str, outdir: str, *, detector: str = "auto",
+                           execute: bool = False, render: bool = False,
+                           width: int = 1300, height: int = 900) -> dict[str, Any]:
+    source = Path(structure).expanduser()
+    if not source.is_file():
+        raise visual_common.VisualWorkflowError(f"Structure not found: {proteus_common.display_path(source)}")
+    fpocket = proteus_common.find_executable("fpocket")
+    p2rank = proteus_common.find_executable("prank", "p2rank")
+    tunnel_tools = {
+        "caver": bool(proteus_common.find_executable("caver")),
+        "hole": bool(proteus_common.find_executable("hole")),
+    }
+    if detector not in {"auto", "fpocket", "p2rank", "none"}:
+        raise visual_common.VisualWorkflowError("Detector must be auto, fpocket, p2rank, or none.")
+    selected = detector
+    if detector == "auto":
+        selected = "fpocket" if fpocket else "p2rank" if p2rank else "none"
+    executable = fpocket if selected == "fpocket" else p2rank if selected == "p2rank" else None
+    if execute and selected != "none" and not executable:
+        raise visual_common.VisualWorkflowError(f"Requested detector is not installed: {selected}")
+
+    destination = Path(outdir)
+    destination.mkdir(parents=True, exist_ok=True)
+    detector_result: dict[str, Any] | None = None
+    pockets: list[Path] = []
+    predictions: list[dict[str, str]] = []
+    if execute and selected == "fpocket" and executable:
+        detector_result, pockets = _run_fpocket(executable, source, destination)
+    elif execute and selected == "p2rank" and executable:
+        detector_result, pockets, predictions = _run_p2rank(executable, source, destination)
+
+    pml, cxc = _scripts(source, pockets, destination, width, height)
+    warnings = [
+        "Predicted pockets and tunnels are geometric hypotheses; prioritize sites using experimental, evolutionary, and chemical evidence.",
+        "Tool scores are not binding-affinity estimates and are not directly comparable across detectors.",
+        "Tunnel results depend on probe radius, starting point, conformational state, and treatment of waters or ligands.",
+    ]
+    if selected == "none":
+        warnings.append("No supported pocket detector was found; install fpocket or P2Rank, or choose a detector explicitly.")
+    data: dict[str, Any] = {
+        "workflow": "pocket_tunnel",
+        "structure": proteus_common.display_path(source),
+        "detector": selected,
+        "availability": {
+            "fpocket": bool(fpocket),
+            "p2rank": bool(p2rank),
+            "tunnel_tools": tunnel_tools,
+        },
+        "detector_execution": detector_result,
+        "pockets": [proteus_common.display_path(item) for item in pockets],
+        "predictions": predictions,
+        "render_requested": render,
+        "executed": execute,
+    }
+    report = proteus_common.ok_payload(
+        data, warnings=warnings, provenance={"structure": proteus_common.file_provenance(source)},
+    )
+    data["artifacts"] = visual_common.write_workflow(
+        destination, "pocket_tunnel", report=report, pymol_lines=pml, chimerax_lines=cxc,
+    )
+    if execute and detector_result and detector_result.get("status") != "ok":
+        report["status"] = "error"
+        report["error"] = f"{selected} pocket detection failed."
+    if render:
+        data["rendering"] = {
+            "pymol": visual_common.run_pymol(destination / "pocket_tunnel.pml"),
+            "chimerax": visual_common.run_chimerax(cxc),
+        }
+        failures = [name for name, result in data["rendering"].items() if result.get("status") not in {"ok", "unavailable"}]
+        if failures:
+            report["status"] = "error"
+            report["error"] = f"Pocket rendering failed for: {', '.join(failures)}"
+    proteus_common.write_json(destination / "pocket_tunnel.json", report)
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Run fpocket/P2Rank when available and prepare pocket-review sessions.")
+    parser.add_argument("structure")
+    parser.add_argument("--detector", default="auto", choices=["auto", "fpocket", "p2rank", "none"])
+    parser.add_argument("--execute", action="store_true", help="Run the selected pocket detector")
+    parser.add_argument("--render", action="store_true", help="Render generated PyMOL and ChimeraX review artifacts")
+    parser.add_argument("--outdir", default="proteus_pockets")
+    parser.add_argument("--json", action="store_true", help="Emit JSON (accepted for consistency)")
+    args = parser.parse_args(argv)
+    try:
+        report = pocket_tunnel_workflow(
+            args.structure, args.outdir, detector=args.detector, execute=args.execute, render=args.render,
+        )
+    except (OSError, ValueError, visual_common.VisualWorkflowError) as exc:
+        print(json.dumps(proteus_common.error_payload(str(exc)), indent=2))
+        return 1
+    print(json.dumps(report, indent=2))
+    return 0 if report.get("status") == "ok" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/skills/proteus/scripts/proteus.py b/skills/proteus/scripts/proteus.py
new file mode 100644
index 0000000..f7bb30a
--- /dev/null
+++ b/skills/proteus/scripts/proteus.py
@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""Unified entry point for Proteus user workflows."""
+
+from __future__ import annotations
+
+import importlib
+import sys
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import proteus_common
+
+
+COMMANDS = {
+    "annotate": ("annotation_figure", "Map residue annotations and scores onto figures"),
+    "assembly": ("assembly_explorer", "Compare asymmetric unit, biological assembly, and crystal neighbors"),
+    "chemical-site": ("chemical_site", "Inspect a ligand, cofactor, metal, or water network"),
+    "compare": ("state_compare", "Create aligned state-comparison figures and contact changes"),
+    "cryoem": ("cryoem_workflow", "Inspect and render a map/model pair"),
+    "electrostatics": ("electrostatics_workflow", "Create a Coulombic surface workflow"),
+    "ensemble": ("ensemble_report", "Analyze multi-model structural variability"),
+    "figure": ("scene_figure", "Compile a declarative PyMOL or ChimeraX scene"),
+    "interface": ("interface_story", "Analyze and render a protein-protein interface"),
+    "pockets": ("pocket_tunnel", "Run optional pocket detection and render candidates"),
+    "qc": ("structure_qc", "Preflight coordinate models, conformers, occupancy, and components"),
+    "residue": ("residue_story", "Build a residue- or variant-centered structural story"),
+    "restraints": ("restraint_report", "Evaluate and render residue-pair distance restraints"),
+}
+
+
+def _help() -> str:
+    rows = [
+        "Proteus structural-biology workflows",
+        "",
+        "Usage: python3 scripts/proteus.py <command> [arguments]",
+        "",
+        "Commands:",
+    ]
+    width = max(len(command) for command in COMMANDS)
+    rows.extend(f"  {command:<{width}}  {description}" for command, (_module, description) in sorted(COMMANDS.items()))
+    rows.extend(["", "Run '<command> --help' for workflow-specific options."])
+    return "\n".join(rows)
+
+
+def main(argv: list[str] | None = None) -> int:
+    arguments = list(sys.argv[1:] if argv is None else argv)
+    if not arguments or arguments[0] in {"-h", "--help", "help"}:
+        print(_help())
+        return 0
+    if arguments[0] in {"-V", "--version"}:
+        print(proteus_common.PROTEUS_VERSION)
+        return 0
+    command = arguments.pop(0)
+    target = COMMANDS.get(command)
+    if target is None:
+        print(f"Unknown workflow: {command}\n\n{_help()}", file=sys.stderr)
+        return 2
+    module = importlib.import_module(target[0])
+    return int(module.main(arguments) or 0)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/skills/proteus/scripts/proteus_batch.py b/skills/proteus/scripts/proteus_batch.py
index 4b5f8ed..3a311e0 100644
--- a/skills/proteus/scripts/proteus_batch.py
+++ b/skills/proteus/scripts/proteus_batch.py
@@ -22,6 +22,18 @@
     "mutation_triage": "scripts/mutation_triage.py",
     "validation_report": "scripts/validation_report.py",
     "resolve_structure": "scripts/resolve_structure.py",
+    "structure_qc": "scripts/structure_qc.py",
+    "state_compare": "scripts/state_compare.py",
+    "residue_story": "scripts/residue_story.py",
+    "interface_story": "scripts/interface_story.py",
+    "annotation_figure": "scripts/annotation_figure.py",
+    "restraint_report": "scripts/restraint_report.py",
+    "assembly_explorer": "scripts/assembly_explorer.py",
+    "cryoem_workflow": "scripts/cryoem_workflow.py",
+    "ensemble_report": "scripts/ensemble_report.py",
+    "electrostatics_workflow": "scripts/electrostatics_workflow.py",
+    "pocket_tunnel": "scripts/pocket_tunnel.py",
+    "chemical_site": "scripts/chemical_site.py",
 }
 ITEM_ID_RE = re.compile(r"^[A-Za-z0-9_.-]+$")
 MAX_CAPTURE_CHARS = 20000
@@ -135,6 +147,17 @@ def build_command(task_spec, item_input: str, item_outdir: Path) -> list[str]:
         "interaction_report",
         "resolve_structure",
         "assembly_report",
+        "state_compare",
+        "residue_story",
+        "interface_story",
+        "annotation_figure",
+        "restraint_report",
+        "assembly_explorer",
+        "cryoem_workflow",
+        "ensemble_report",
+        "electrostatics_workflow",
+        "pocket_tunnel",
+        "chemical_site",
     } and not _has_option(extra_args, "--outdir"):
         command.extend(["--outdir", str(item_outdir)])
     if task != "mutation_triage":
diff --git a/skills/proteus/scripts/proteus_common.py b/skills/proteus/scripts/proteus_common.py
new file mode 100644
index 0000000..5d641ab
--- /dev/null
+++ b/skills/proteus/scripts/proteus_common.py
@@ -0,0 +1,345 @@
+#!/usr/bin/env python3
+"""Shared runtime helpers for Proteus command-line workflows.
+
+Keep this module dependency-free. It centralizes result envelopes, privacy-safe
+path labels, checksums, executable discovery, subprocess handling, and resilient
+HTTP access so workflow scripts do not each invent subtly different behavior.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import platform
+import re
+import shutil
+import subprocess
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from email.utils import parsedate_to_datetime
+from pathlib import Path
+from typing import Any
+
+
+SCHEMA_VERSION = 1
+PROTEUS_VERSION = "0.2.0"
+USER_AGENT = f"proteus/{PROTEUS_VERSION}"
+TRANSIENT_HTTP_CODES = {408, 425, 429, 500, 502, 503, 504}
+SECRET_QUERY_NAMES = {
+    "access_token", "api_key", "apikey", "auth", "authorization", "key",
+    "password", "secret", "sig", "signature", "token",
+}
+ABSOLUTE_PATH_RE = re.compile(r"(?<![:A-Za-z0-9_./~$-])/(?!/)[^\s\"'`;]+")
+
+
+class ProteusRuntimeError(RuntimeError):
+    """Base error for shared Proteus runtime failures."""
+
+
+@dataclass(frozen=True)
+class HttpResult:
+    body: bytes
+    url: str
+    status: int
+    headers: dict[str, str]
+    cached: bool = False
+    attempts: int = 1
+
+
+def display_path(value: str | Path, *, roots: list[Path] | None = None) -> str:
+    """Return a useful path label without leaking an arbitrary absolute path."""
+    candidate = Path(value).expanduser()
+    try:
+        resolved = candidate.resolve(strict=False)
+    except OSError:
+        resolved = candidate.absolute()
+
+    search_roots = list(roots or [])
+    search_roots.extend([Path.cwd(), Path.home()])
+    seen: set[str] = set()
+    for root in search_roots:
+        try:
+            resolved_root = root.expanduser().resolve(strict=False)
+        except OSError:
+            continue
+        marker = str(resolved_root)
+        if marker in seen:
+            continue
+        seen.add(marker)
+        try:
+            relative = resolved.relative_to(resolved_root)
+        except ValueError:
+            continue
+        if resolved_root == Path.home().resolve(strict=False):
+            return f"~/{relative}" if str(relative) != "." else "~"
+        return f"./{relative}" if str(relative) != "." else "."
+    return f"{resolved.name or 'path'} (absolute path omitted)"
+
+
+def sha256_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def sha256_file(path: str | Path, chunk_size: int = 1024 * 1024) -> str:
+    digest = hashlib.sha256()
+    with Path(path).open("rb") as handle:
+        while chunk := handle.read(chunk_size):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def file_provenance(path: str | Path, *, kind: str = "local_file") -> dict[str, Any]:
+    candidate = Path(path)
+    data: dict[str, Any] = {"kind": kind, "path": display_path(candidate)}
+    if candidate.is_file():
+        data.update({"bytes": candidate.stat().st_size, "sha256": sha256_file(candidate)})
+    return data
+
+
+def scrub_text(value: str | bytes) -> str:
+    """Remove arbitrary absolute local paths from captured tool output."""
+    text = value.decode("utf-8", errors="replace") if isinstance(value, bytes) else value
+    replacements = [(str(Path.cwd().resolve()), "."), (str(Path.home().resolve()), "~")]
+    for source, label in sorted(replacements, key=lambda item: len(item[0]), reverse=True):
+        text = text.replace(source, label)
+
+    def replace(match: re.Match[str]) -> str:
+        token = match.group(0)
+        suffix = ""
+        while token and token[-1] in ".,:)]}":
+            suffix = token[-1] + suffix
+            token = token[:-1]
+        return display_path(token) + suffix if token else match.group(0)
+
+    return ABSOLUTE_PATH_RE.sub(replace, text)
+
+
+def scrub_private(value: Any) -> Any:
+    """Recursively scrub absolute paths from JSON-safe execution metadata."""
+    if isinstance(value, dict):
+        return {str(key): scrub_private(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [scrub_private(item) for item in value]
+    if isinstance(value, tuple):
+        return [scrub_private(item) for item in value]
+    if isinstance(value, str):
+        return scrub_text(value)
+    return value
+
+
+def ok_payload(
+    data: dict[str, Any],
+    *,
+    warnings: list[str] | None = None,
+    provenance: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    output: dict[str, Any] = {
+        "schema_version": SCHEMA_VERSION,
+        "proteus_version": PROTEUS_VERSION,
+        "status": "ok",
+        "data": data,
+    }
+    if warnings:
+        output["warnings"] = list(dict.fromkeys(warnings))
+    if provenance:
+        output["provenance"] = provenance
+    return output
+
+
+def error_payload(message: str, *, code: str | None = None) -> dict[str, Any]:
+    output: dict[str, Any] = {
+        "schema_version": SCHEMA_VERSION,
+        "proteus_version": PROTEUS_VERSION,
+        "status": "error",
+        "error": message,
+    }
+    if code:
+        output["code"] = code
+    return output
+
+
+def write_json(path: str | Path, value: Any) -> Path:
+    destination = Path(path)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    destination.write_text(json.dumps(value, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return destination
+
+
+def slug(value: str, default: str = "workflow") -> str:
+    normalized = re.sub(r"[^a-z0-9]+", "-", value.strip().lower()).strip("-")
+    return normalized or default
+
+
+def find_executable(*candidates: str) -> str | None:
+    for candidate in candidates:
+        if not candidate:
+            continue
+        path = shutil.which(candidate)
+        if path:
+            return path
+        expanded = Path(candidate).expanduser()
+        if expanded.is_file() and os.access(expanded, os.X_OK):
+            return str(expanded)
+    return None
+
+
+def runtime_metadata() -> dict[str, Any]:
+    return {
+        "python": platform.python_version(),
+        "platform": platform.system(),
+        "machine": platform.machine(),
+    }
+
+
+def run_command(
+    command: list[str],
+    *,
+    timeout: int = 300,
+    cwd: str | Path | None = None,
+    env: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    """Run an argv command without a shell and return a JSON-safe record."""
+    try:
+        proc = subprocess.run(
+            command,
+            cwd=str(cwd) if cwd is not None else None,
+            env=env,
+            text=True,
+            capture_output=True,
+            timeout=timeout,
+            check=False,
+        )
+    except subprocess.TimeoutExpired as exc:
+        return {
+            "status": "error",
+            "error": f"Command timed out after {timeout} seconds.",
+            "returncode": None,
+            "stdout": scrub_text(exc.stdout or ""),
+            "stderr": scrub_text(exc.stderr or ""),
+        }
+    except OSError as exc:
+        return {"status": "error", "error": scrub_text(str(exc)), "returncode": None, "stdout": "", "stderr": ""}
+    return {
+        "status": "ok" if proc.returncode == 0 else "error",
+        "returncode": proc.returncode,
+        "stdout": proc.stdout,
+        "stderr": proc.stderr,
+    }
+
+
+def _safe_url(url: str) -> str:
+    from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+
+    parsed = urlsplit(url)
+    if parsed.scheme not in {"https", "http"}:
+        raise ProteusRuntimeError("Only HTTP(S) URLs are supported.")
+    if parsed.username or parsed.password:
+        raise ProteusRuntimeError("Credential-bearing URLs are not allowed.")
+    for name, _value in parse_qsl(parsed.query, keep_blank_values=True):
+        if name.lower() in SECRET_QUERY_NAMES:
+            raise ProteusRuntimeError(f"Secret-like URL query parameter is not allowed: {name}")
+    return urlunsplit((parsed.scheme, parsed.netloc, parsed.path, urlencode(parse_qsl(parsed.query, keep_blank_values=True)), ""))
+
+
+def _retry_delay(headers: Any, attempt: int, backoff: float) -> float:
+    value = headers.get("Retry-After") if headers is not None else None
+    if value:
+        try:
+            return max(0.0, min(float(value), 30.0))
+        except ValueError:
+            try:
+                target = parsedate_to_datetime(value).timestamp()
+                return max(0.0, min(target - time.time(), 30.0))
+            except (TypeError, ValueError, OverflowError):
+                pass
+    return min(backoff * (2 ** max(0, attempt - 1)), 30.0)
+
+
+def _cache_paths(cache_dir: str | Path, url: str) -> tuple[Path, Path]:
+    root = Path(cache_dir).expanduser()
+    key = sha256_bytes(url.encode("utf-8"))
+    return root / f"{key}.body", root / f"{key}.json"
+
+
+def request_bytes(
+    url: str,
+    *,
+    method: str = "GET",
+    data: bytes | None = None,
+    headers: dict[str, str] | None = None,
+    timeout: int = 30,
+    retries: int = 3,
+    backoff: float = 1.0,
+    cache_dir: str | Path | None = None,
+    offline: bool = False,
+) -> HttpResult:
+    safe_url = _safe_url(url)
+    body_path: Path | None = None
+    meta_path: Path | None = None
+    if cache_dir is not None:
+        body_path, meta_path = _cache_paths(cache_dir, safe_url)
+        if body_path.is_file() and meta_path.is_file():
+            metadata = json.loads(meta_path.read_text(encoding="utf-8"))
+            body = body_path.read_bytes()
+            if metadata.get("sha256") == sha256_bytes(body):
+                return HttpResult(
+                    body=body,
+                    url=safe_url,
+                    status=int(metadata.get("status", 200)),
+                    headers=dict(metadata.get("headers") or {}),
+                    cached=True,
+                    attempts=0,
+                )
+        if offline:
+            raise ProteusRuntimeError("Offline mode requested and no valid cached response exists.")
+    elif offline:
+        raise ProteusRuntimeError("Offline mode requires a cache directory.")
+
+    request_headers = {"User-Agent": USER_AGENT, **(headers or {})}
+    attempts = max(1, retries + 1)
+    last_error: Exception | None = None
+    for attempt in range(1, attempts + 1):
+        request = urllib.request.Request(safe_url, data=data, headers=request_headers, method=method)
+        try:
+            with urllib.request.urlopen(request, timeout=timeout) as response:
+                body = response.read()
+                result = HttpResult(
+                    body=body,
+                    url=response.geturl(),
+                    status=int(getattr(response, "status", 200)),
+                    headers=dict(response.headers.items()),
+                    attempts=attempt,
+                )
+                if body_path is not None and meta_path is not None:
+                    body_path.parent.mkdir(parents=True, exist_ok=True)
+                    body_path.write_bytes(body)
+                    write_json(meta_path, {
+                        "url": safe_url,
+                        "status": result.status,
+                        "headers": result.headers,
+                        "sha256": sha256_bytes(body),
+                        "fetched_at": int(time.time()),
+                    })
+                return result
+        except urllib.error.HTTPError as exc:
+            last_error = exc
+            if exc.code not in TRANSIENT_HTTP_CODES or attempt >= attempts:
+                raise ProteusRuntimeError(f"HTTP {exc.code} for {safe_url}: {exc.reason}") from exc
+            time.sleep(_retry_delay(exc.headers, attempt, backoff))
+        except (urllib.error.URLError, TimeoutError, OSError) as exc:
+            last_error = exc
+            if attempt >= attempts:
+                raise ProteusRuntimeError(f"Request failed for {safe_url}: {exc}") from exc
+            time.sleep(_retry_delay(None, attempt, backoff))
+    raise ProteusRuntimeError(f"Request failed for {safe_url}: {last_error}")
+
+
+def request_json(url: str, **kwargs: Any) -> tuple[Any, HttpResult]:
+    result = request_bytes(url, **kwargs)
+    try:
+        return json.loads(result.body), result
+    except json.JSONDecodeError as exc:
+        raise ProteusRuntimeError(f"Response from {result.url} was not valid JSON: {exc}") from exc
diff --git a/skills/proteus/scripts/proteus_doctor.py b/skills/proteus/scripts/proteus_doctor.py
index ff5d0c2..3fd0324 100644
--- a/skills/proteus/scripts/proteus_doctor.py
+++ b/skills/proteus/scripts/proteus_doctor.py
@@ -149,6 +149,21 @@ def _script_smoke() -> dict:
         "design_run.py",
         "rosetta_score.py",
         "kras_dossier.py",
+        "proteus.py",
+        "structure_qc.py",
+        "scene_figure.py",
+        "state_compare.py",
+        "residue_story.py",
+        "interface_story.py",
+        "annotation_figure.py",
+        "restraint_report.py",
+        "assembly_explorer.py",
+        "cryoem_workflow.py",
+        "ensemble_report.py",
+        "electrostatics_workflow.py",
+        "pocket_tunnel.py",
+        "chemical_site.py",
+        "sync_skill_package.py",
     ]
     if sys.version_info < (3, 10):
         return {
@@ -179,6 +194,15 @@ def build_report(include_network: bool) -> dict:
     pymol = _find_pymol()
     chimerax = _find_chimerax()
     ffmpeg = shutil.which("ffmpeg")
+    optional = {
+        "apbs": shutil.which("apbs"),
+        "pdb2pqr": shutil.which("pdb2pqr") or shutil.which("pdb2pqr30"),
+        "fpocket": shutil.which("fpocket"),
+        "p2rank": shutil.which("prank") or shutil.which("p2rank"),
+        "usalign": shutil.which("USalign") or shutil.which("usalign"),
+        "dockq": shutil.which("DockQ") or shutil.which("dockq"),
+        "foldseek": shutil.which("foldseek"),
+    }
     network = None
     if include_network:
         network = {name: _network_check(url) for name, url in NETWORK_ENDPOINTS.items()}
@@ -190,6 +214,10 @@ def build_report(include_network: bool) -> dict:
         "pymol_rendering": bool(pymol),
         "chimerax_analysis": bool(chimerax),
         "turntable_movies": bool((pymol or chimerax) and ffmpeg),
+        "pocket_detection": bool(optional["fpocket"] or optional["p2rank"]),
+        "poisson_boltzmann_electrostatics": bool(optional["apbs"] and optional["pdb2pqr"]),
+        "local_structure_search": bool(optional["foldseek"]),
+        "complex_quality_scoring": bool(optional["dockq"]),
     }
     if network is not None:
         for capability, check_name in NETWORK_CAPABILITIES.items():
@@ -205,6 +233,10 @@ def build_report(include_network: bool) -> dict:
             "pymol": {"ok": bool(pymol), "path": _display_path(pymol)},
             "chimerax": {"ok": bool(chimerax), "path": _display_path(chimerax)},
             "ffmpeg": {"ok": bool(ffmpeg), "path": _display_path(ffmpeg)},
+            **{
+                name: {"ok": bool(path), "path": _display_path(path)}
+                for name, path in optional.items()
+            },
         },
         "scripts": _script_smoke(),
         "network": network,
diff --git a/skills/proteus/scripts/residue_story.py b/skills/proteus/scripts/residue_story.py
new file mode 100644
index 0000000..cea8bba
--- /dev/null
+++ b/skills/proteus/scripts/residue_story.py
@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""Turn a residue or substitution into a local structural evidence story."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import interface_report
+import mutation_triage
+import pocket_report
+import proteus_common
+import visual_common
+
+
+VARIANT_RE = re.compile(r"^(?:[A-Za-z0-9_.-]+\s+)?(?:p\.)?[A-Za-z]{1,3}\d+[A-Za-z]{1,3}$", re.IGNORECASE)
+RESIDUE_RE = re.compile(r"^(?:(?P<chain>[A-Za-z0-9]+):)?(?P<resi>-?\d+[A-Za-z]?)$")
+
+
+def _focus(focus: str, chain: str | None) -> dict[str, Any]:
+    text = focus.strip()
+    if chain is not None and not re.fullmatch(r"[A-Za-z0-9]+", chain):
+        raise visual_common.VisualWorkflowError("Chain identifiers must be alphanumeric.")
+    if VARIANT_RE.fullmatch(text):
+        match = re.search(r"(\d+)", text)
+        if match is None:
+            raise visual_common.VisualWorkflowError("Could not parse variant residue number.")
+        return {"kind": "variant", "value": text, "resi": match.group(1), "chain": chain}
+    match = RESIDUE_RE.fullmatch(text)
+    if not match:
+        raise visual_common.VisualWorkflowError("Focus must be a substitution such as R175H or residue such as A:175.")
+    return {"kind": "residue", "value": text, "resi": match.group("resi"), "chain": chain or match.group("chain")}
+
+
+def _selection(parsed: dict[str, Any]) -> str:
+    base = f"resi {parsed['resi']}"
+    if parsed.get("chain"):
+        base = f"chain {parsed['chain']} and {base}"
+    return base
+
+
+def _pymol_lines(structure: Path, parsed: dict[str, Any], outdir: Path,
+                  cutoff: float, width: int, height: int) -> list[str]:
+    focus = _selection(parsed)
+    global_png = (outdir / "residue_context.png").resolve()
+    local_png = (outdir / "residue_local.png").resolve()
+    session = (outdir / "residue_story.pse").resolve()
+    lines = visual_common.pymol_base(width=width, height=height)
+    lines.extend([
+        f"load {visual_common.quote_pymol(structure.resolve())}, structure",
+        "hide everything, all",
+        "show cartoon, polymer",
+        "color gray80, polymer",
+        f"select focus, structure and ({focus})",
+        f"select neighborhood, byres (structure within {cutoff:.2f} of focus)",
+        f"select nearby_ligands, (organic or inorganic) within {cutoff:.2f} of focus",
+        "show sticks, focus or neighborhood or nearby_ligands",
+        "color magenta, focus",
+        "color cyan, neighborhood and not focus",
+        "color orange, nearby_ligands",
+        "label focus and name CA, resn + resi",
+        "orient structure",
+        f"ray {width}, {height}",
+        *visual_common.pymol_png(global_png, width=width, height=height),
+        "orient focus or neighborhood or nearby_ligands",
+        "zoom focus or neighborhood or nearby_ligands, 4",
+        "distance local_contacts, focus, neighborhood or nearby_ligands, 3.6, 2",
+        "set dash_color, gray40, local_contacts",
+        f"ray {width}, {height}",
+        *visual_common.pymol_png(local_png, width=width, height=height),
+        *visual_common.pymol_save(session),
+        "quit",
+    ])
+    return lines
+
+
+def build_residue_story(structure: str, focus: str, outdir: str, *, chain: str | None = None,
+                        cutoff: float = 5.0, pae: str | None = None, execute: bool = False,
+                        width: int = 1200, height: int = 900) -> dict[str, Any]:
+    source = Path(structure).expanduser()
+    if not source.is_file():
+        raise visual_common.VisualWorkflowError(f"Structure not found: {proteus_common.display_path(source)}")
+    if cutoff <= 0:
+        raise visual_common.VisualWorkflowError("Cutoff must be positive.")
+    parsed = _focus(focus, chain)
+    residue_arg = parsed["value"] if parsed["kind"] == "residue" else None
+    variant_arg = parsed["value"] if parsed["kind"] == "variant" else None
+    pocket = pocket_report.analyze_pocket(str(source), cutoff, residue=residue_arg, variant=variant_arg)
+    interface = interface_report.analyze_interfaces(str(source), cutoff, residue=residue_arg, variant=variant_arg)
+    triage = None
+    warnings = [
+        "Residue numbering is interpreted directly from the coordinate file unless an external mapping is supplied."
+    ]
+    if parsed["kind"] == "variant":
+        try:
+            triage = mutation_triage.triage_variants(
+                str(source), [parsed["value"]], chain=parsed.get("chain"), cutoff=cutoff, pae_json=pae,
+            )
+        except (OSError, ValueError, mutation_triage.MutationTriageError) as exc:
+            warnings.append(f"Mutation triage was unavailable: {exc}")
+    destination = Path(outdir)
+    destination.mkdir(parents=True, exist_ok=True)
+    data: dict[str, Any] = {
+        "workflow": "residue_story",
+        "structure": proteus_common.display_path(source),
+        "focus": parsed,
+        "cutoff_angstrom": cutoff,
+        "pocket_context": pocket.get("data", {}).get("residue_focus"),
+        "interface_context": interface.get("data", {}).get("residue_focus"),
+        "mutation_context": triage.get("data") if triage and triage.get("status") == "ok" else None,
+        "images": {
+            "global": proteus_common.display_path(destination / "residue_context.png"),
+            "local": proteus_common.display_path(destination / "residue_local.png"),
+        },
+        "session": proteus_common.display_path(destination / "residue_story.pse"),
+        "executed": execute,
+    }
+    provenance: dict[str, Any] = {"structure": proteus_common.file_provenance(source)}
+    if pae:
+        provenance["pae"] = proteus_common.file_provenance(pae)
+    report = proteus_common.ok_payload(data, warnings=warnings, provenance=provenance)
+    lines = _pymol_lines(source, parsed, destination, cutoff, width, height)
+    data["artifacts"] = visual_common.write_workflow(destination, "residue_story", report=report, pymol_lines=lines)
+    if execute:
+        result = visual_common.run_pymol(destination / "residue_story.pml")
+        data["execution"] = result
+        if result.get("status") != "ok":
+            report["status"] = "error"
+            report["error"] = result.get("error", "PyMOL residue workflow failed.")
+        elif not all(visual_common.verify_nonempty(destination / name) for name in ("residue_context.png", "residue_local.png")):
+            report["status"] = "error"
+            report["error"] = "PyMOL did not create both residue figures."
+        proteus_common.write_json(destination / "residue_story.json", report)
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Create a residue-centric structural evidence report and PyMOL figures.")
+    parser.add_argument("structure", help="Local PDB/mmCIF structure")
+    parser.add_argument("focus", help="Substitution (R175H) or residue (A:175)")
+    parser.add_argument("--chain", help="Optional chain override")
+    parser.add_argument("--cutoff", type=float, default=5.0)
+    parser.add_argument("--pae", help="Optional local PAE JSON for variants")
+    parser.add_argument("--outdir", default="proteus_residue")
+    parser.add_argument("--execute", action="store_true", help="Run PyMOL and create figures")
+    parser.add_argument("--json", action="store_true", help="Emit JSON (accepted for consistency)")
+    args = parser.parse_args(argv)
+    try:
+        report = build_residue_story(args.structure, args.focus, args.outdir, chain=args.chain,
+                                     cutoff=args.cutoff, pae=args.pae, execute=args.execute)
+    except (OSError, ValueError, visual_common.VisualWorkflowError) as exc:
+        print(json.dumps(proteus_common.error_payload(str(exc)), indent=2))
+        return 1
+    print(json.dumps(report, indent=2))
+    return 0 if report.get("status") == "ok" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/skills/proteus/scripts/restraint_report.py b/skills/proteus/scripts/restraint_report.py
new file mode 100644
index 0000000..a6c8170
--- /dev/null
+++ b/skills/proteus/scripts/restraint_report.py
@@ -0,0 +1,217 @@
+#!/usr/bin/env python3
+"""Evaluate residue-pair distance restraints and create visual overlays."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import re
+import sys
+from collections import Counter
+from pathlib import Path
+from typing import Any
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import proteus_common
+import structure_qc
+import visual_common
+
+
+SPEC_RE = re.compile(r"^[A-Za-z0-9_.+?-]+$")
+
+
+def _records(path: str | Path) -> list[dict[str, Any]]:
+    values = visual_common.load_records(path)
+    output = []
+    for index, value in enumerate(values, start=1):
+        try:
+            residue1 = str(value["residue1"])
+            residue2 = str(value["residue2"])
+        except KeyError as exc:
+            raise visual_common.VisualWorkflowError(f"Restraint {index} requires residue1 and residue2.") from exc
+        minimum = float(value.get("min", value.get("minimum", 0.0)) or 0.0)
+        maximum = float(value.get("max", value.get("maximum", 30.0)) or 30.0)
+        if minimum < 0 or maximum <= 0 or minimum > maximum:
+            raise visual_common.VisualWorkflowError(f"Restraint {index} has invalid min/max bounds.")
+        chain1 = str(value.get("chain1") or "")
+        chain2 = str(value.get("chain2") or "")
+        atom1 = str(value.get("atom1") or "CA")
+        atom2 = str(value.get("atom2") or "CA")
+        for field, candidate in (
+            ("chain1", chain1), ("residue1", residue1), ("atom1", atom1),
+            ("chain2", chain2), ("residue2", residue2), ("atom2", atom2),
+        ):
+            if candidate and not SPEC_RE.fullmatch(candidate):
+                raise visual_common.VisualWorkflowError(f"Restraint {index} has an invalid {field} identifier.")
+        output.append({
+            "id": str(value.get("id") or f"restraint_{index}"),
+            "chain1": chain1,
+            "residue1": residue1,
+            "atom1": atom1,
+            "chain2": chain2,
+            "residue2": residue2,
+            "atom2": atom2,
+            "minimum": minimum,
+            "maximum": maximum,
+            "label": str(value.get("label") or value.get("id") or f"R{index}"),
+        })
+    return output
+
+
+def _find_atom(atoms: list[dict[str, Any]], chain: str, residue: str, atom_name: str) -> tuple[dict[str, Any] | None, int]:
+    matches = [
+        atom for atom in atoms
+        if atom["residue_id"] == residue
+        and atom["atom_name"].upper() == atom_name.upper()
+        and (not chain or atom["chain"] == chain)
+    ]
+    return (matches[0] if matches else None), len(matches)
+
+
+def _distance(left: dict[str, Any], right: dict[str, Any]) -> float:
+    return math.sqrt(sum((left[axis] - right[axis]) ** 2 for axis in ("x", "y", "z")))
+
+
+def _pymol_spec(chain: str, residue: str, atom: str) -> str:
+    base = f"resi {residue} and name {atom}"
+    return f"chain {chain} and {base}" if chain else base
+
+
+def _chimerax_spec(chain: str, residue: str, atom: str) -> str:
+    return f"#1/{chain}:{residue}@{atom}" if chain else f"#1:{residue}@{atom}"
+
+
+def evaluate_restraints(structure: str, restraints_file: str, outdir: str, *,
+                        model: str = "first", execute: bool = False,
+                        width: int = 1300, height: int = 900) -> dict[str, Any]:
+    source = Path(structure).expanduser()
+    if not source.is_file():
+        raise visual_common.VisualWorkflowError(f"Structure not found: {proteus_common.display_path(source)}")
+    text = structure_qc._read_text(source)
+    fmt = structure_qc._format_from_path(source)
+    raw, _meta = structure_qc.parse_mmcif(text) if fmt == "mmcif" else structure_qc.parse_pdb(text)
+    atoms, selection = structure_qc.select_atoms(raw, model=model, altloc="highest")
+    restraints = _records(restraints_file)
+    results = []
+    warnings: list[str] = []
+    for item in restraints:
+        left, left_count = _find_atom(atoms, item["chain1"], item["residue1"], item["atom1"])
+        right, right_count = _find_atom(atoms, item["chain2"], item["residue2"], item["atom2"])
+        result = dict(item)
+        if left_count > 1 or right_count > 1:
+            warnings.append(f"{item['id']} matched multiple atoms; specify chain IDs to disambiguate.")
+        if left is None or right is None:
+            result.update({"status": "unresolved", "distance": None})
+        else:
+            distance = _distance(left, right)
+            status = "satisfied" if item["minimum"] <= distance <= item["maximum"] else "too_short" if distance < item["minimum"] else "too_long"
+            result.update({"status": status, "distance": round(distance, 3)})
+        results.append(result)
+    counts = Counter(item["status"] for item in results)
+    destination = Path(outdir)
+    destination.mkdir(parents=True, exist_ok=True)
+
+    pml = visual_common.pymol_base(width=width, height=height)
+    pml.extend([
+        f"load {visual_common.quote_pymol(source.resolve())}, structure",
+        "hide everything, all",
+        "show cartoon, polymer",
+        "color gray80, polymer",
+    ])
+    cxc = [
+        *visual_common.chimerax_base(),
+        f"open {visual_common.quote_chimerax(source.resolve())}",
+        "cartoon",
+        "color protein lightgray",
+    ]
+    for index, item in enumerate(results, start=1):
+        if item["status"] == "unresolved":
+            continue
+        first_pml = _pymol_spec(item["chain1"], item["residue1"], item["atom1"])
+        second_pml = _pymol_spec(item["chain2"], item["residue2"], item["atom2"])
+        object_name = f"restraint_{index}"
+        color_name = "green" if item["status"] == "satisfied" else "red"
+        pml.extend([
+            f"show sticks, ({first_pml}) or ({second_pml})",
+            f"distance {object_name}, ({first_pml}), ({second_pml})",
+            f"set dash_color, {color_name}, {object_name}",
+        ])
+        first_cx = _chimerax_spec(item["chain1"], item["residue1"], item["atom1"])
+        second_cx = _chimerax_spec(item["chain2"], item["residue2"], item["atom2"])
+        cxc.extend([
+            f"show {first_cx} atoms",
+            f"show {second_cx} atoms",
+            f"style {first_cx} stick",
+            f"style {second_cx} stick",
+            f"distance {first_cx} {second_cx} color {color_name}",
+        ])
+    pml.extend(visual_common.finalize_pymol(
+        destination / "restraints.png", width=width, height=height,
+        session=destination / "restraints.pse",
+    ))
+    cxc.extend(visual_common.finalize_chimerax(
+        destination / "restraints_chimerax.png", width=width, height=height,
+        session=destination / "restraints.cxs",
+    ))
+    data: dict[str, Any] = {
+        "workflow": "restraint_report",
+        "structure": proteus_common.display_path(source),
+        "model_selection": selection,
+        "summary": {"total": len(results), **dict(sorted(counts.items()))},
+        "restraints": results,
+        "images": {
+            "pymol": proteus_common.display_path(destination / "restraints.png"),
+            "chimerax": proteus_common.display_path(destination / "restraints_chimerax.png"),
+        },
+        "executed": execute,
+    }
+    report = proteus_common.ok_payload(
+        data,
+        warnings=warnings,
+        provenance={
+            "structure": proteus_common.file_provenance(source),
+            "restraints": proteus_common.file_provenance(restraints_file),
+        },
+    )
+    data["artifacts"] = visual_common.write_workflow(
+        destination, "restraint_report", report=report, pymol_lines=pml, chimerax_lines=cxc,
+    )
+    if execute:
+        data["execution"] = {
+            "pymol": visual_common.run_pymol(destination / "restraint_report.pml"),
+            "chimerax": visual_common.run_chimerax(cxc),
+        }
+        failures = [name for name, result in data["execution"].items() if result.get("status") not in {"ok", "unavailable"}]
+        if failures:
+            report["status"] = "error"
+            report["error"] = f"Restraint rendering failed for: {', '.join(failures)}"
+        proteus_common.write_json(destination / "restraint_report.json", report)
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Evaluate residue-pair distance restraints and render overlays.")
+    parser.add_argument("structure")
+    parser.add_argument("restraints", help="CSV/JSON with chain1,residue1,atom1,chain2,residue2,atom2,min,max")
+    parser.add_argument("--model", default="first")
+    parser.add_argument("--outdir", default="proteus_restraints")
+    parser.add_argument("--execute", action="store_true")
+    parser.add_argument("--json", action="store_true", help="Emit JSON (accepted for consistency)")
+    args = parser.parse_args(argv)
+    try:
+        report = evaluate_restraints(args.structure, args.restraints, args.outdir,
+                                     model=args.model, execute=args.execute)
+    except (OSError, ValueError, json.JSONDecodeError, structure_qc.StructureQCError,
+            visual_common.VisualWorkflowError) as exc:
+        print(json.dumps(proteus_common.error_payload(str(exc)), indent=2))
+        return 1
+    print(json.dumps(report, indent=2))
+    return 0 if report.get("status") == "ok" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/skills/proteus/scripts/scene_figure.py b/skills/proteus/scripts/scene_figure.py
new file mode 100644
index 0000000..aa420a7
--- /dev/null
+++ b/skills/proteus/scripts/scene_figure.py
@@ -0,0 +1,296 @@
+#!/usr/bin/env python3
+"""Compile a declarative scene manifest into PyMOL or ChimeraX figures."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import proteus_common
+import visual_common
+
+
+def _load_manifest(path: str | Path) -> dict[str, Any]:
+    source = Path(path)
+    if not source.is_file():
+        raise visual_common.VisualWorkflowError(f"Manifest not found: {proteus_common.display_path(source)}")
+    payload = json.loads(source.read_text(encoding="utf-8"))
+    if not isinstance(payload, dict):
+        raise visual_common.VisualWorkflowError("Scene manifest must be a JSON object.")
+    return payload
+
+
+def _structures(manifest: dict[str, Any]) -> list[dict[str, Any]]:
+    values = manifest.get("structures")
+    if not isinstance(values, list) or not values:
+        raise visual_common.VisualWorkflowError("Manifest requires a non-empty structures list.")
+    output = []
+    for index, value in enumerate(values, start=1):
+        if not isinstance(value, dict) or "path" not in value:
+            raise visual_common.VisualWorkflowError(f"Structure {index} requires a path.")
+        path = Path(str(value["path"])).expanduser()
+        if not path.is_file():
+            raise visual_common.VisualWorkflowError(f"Structure not found: {proteus_common.display_path(path)}")
+        name = visual_common.identifier(str(value.get("id") or f"structure_{index}"), field="structure id")
+        output.append({"id": name, "path": path})
+    return output
+
+
+def _views(manifest: dict[str, Any], name: str) -> list[dict[str, Any]]:
+    values = manifest.get("views")
+    if values is None:
+        values = [{"id": "overview", "selection": "all"}]
+    if not isinstance(values, list) or not values:
+        raise visual_common.VisualWorkflowError("views must be a non-empty list.")
+    output = []
+    for index, value in enumerate(values, start=1):
+        if not isinstance(value, dict):
+            raise visual_common.VisualWorkflowError("Each view must be an object.")
+        view_id = visual_common.identifier(str(value.get("id") or f"view_{index}"), field="view id")
+        output_name = str(value.get("output") or f"{name}_{view_id}.png")
+        output_path = Path(output_name)
+        if output_path.name != output_name or output_path.suffix.lower() != ".png":
+            raise visual_common.VisualWorkflowError("View output must be a PNG filename without directory traversal.")
+        turn = value.get("turn") or {}
+        if not isinstance(turn, dict):
+            raise visual_common.VisualWorkflowError("View turn must be an object with optional x, y, and z angles.")
+        output.append({
+            "id": view_id,
+            "selection": visual_common.selection(str(value.get("selection") or "all")),
+            "turn": turn,
+            "output": output_name,
+        })
+    return output
+
+
+def _representations(manifest: dict[str, Any]) -> list[dict[str, str]]:
+    values = manifest.get("representations") or [{"style": "cartoon", "selection": "all", "color": "chain"}]
+    if not isinstance(values, list):
+        raise visual_common.VisualWorkflowError("representations must be a list.")
+    output = []
+    for value in values:
+        if not isinstance(value, dict):
+            raise visual_common.VisualWorkflowError("Each representation must be an object.")
+        item = {
+            "style": visual_common.style(str(value.get("style") or "cartoon")),
+            "selection": visual_common.selection(str(value.get("selection") or "all")),
+            "color": str(value.get("color") or "chain"),
+        }
+        if item["color"] not in {"chain", "element", "plddt", "bfactor", "rainbow"}:
+            visual_common.color(item["color"])
+        if "transparency" in value:
+            number = float(value["transparency"])
+            if number < 0 or number > 1:
+                raise visual_common.VisualWorkflowError("Transparency must be between 0 and 1.")
+            item["transparency"] = str(number)
+        output.append(item)
+    return output
+
+
+def _labels(manifest: dict[str, Any]) -> list[dict[str, str]]:
+    values = manifest.get("labels") or []
+    if not isinstance(values, list):
+        raise visual_common.VisualWorkflowError("labels must be a list.")
+    output = []
+    for value in values:
+        if not isinstance(value, dict):
+            raise visual_common.VisualWorkflowError("Each label must be an object.")
+        text = str(value.get("text") or "%s%s")
+        if any(character in text for character in "\r\n;"):
+            raise visual_common.VisualWorkflowError("Label text cannot contain newlines or semicolons.")
+        output.append({
+            "selection": visual_common.selection(str(value.get("selection") or "name CA")),
+            "text": text,
+            "color": visual_common.color(str(value.get("color") or "black")),
+        })
+    return output
+
+
+def _pymol_script(
+    structures: list[dict[str, Any]], representations: list[dict[str, str]],
+    labels: list[dict[str, str]], views: list[dict[str, Any]], outdir: Path,
+    *, background: str, width: int, height: int, session: Path,
+) -> list[str]:
+    lines = visual_common.pymol_base(background=background, width=width, height=height)
+    for item in structures:
+        lines.append(f"load {visual_common.quote_pymol(item['path'].resolve())}, {item['id']}")
+    lines.append("hide everything, all")
+    for item in representations:
+        lines.append(f"show {item['style']}, {item['selection']}")
+        mode = item["color"]
+        if mode == "chain":
+            lines.append(f"util.cbc {item['selection']}")
+        elif mode == "element":
+            lines.append(f"util.cnc {item['selection']}")
+        elif mode == "plddt":
+            lines.extend([
+                f"color orange, {item['selection']}",
+                f"color yellow, ({item['selection']}) and b > 50",
+                f"color cyan, ({item['selection']}) and b > 70",
+                f"color blue, ({item['selection']}) and b > 90",
+            ])
+        elif mode == "bfactor":
+            lines.append(f"spectrum b, blue_white_red, {item['selection']}")
+        elif mode == "rainbow":
+            lines.append(f"spectrum count, rainbow, {item['selection']}")
+        else:
+            lines.append(f"color {mode}, {item['selection']}")
+        if "transparency" in item:
+            setting = "surface_transparency" if item["style"] == "surface" else f"{item['style'].rstrip('s')}_transparency"
+            lines.append(f"set {setting}, {item['transparency']}, {item['selection']}")
+    for item in labels:
+        text = item["text"].replace('"', '\\"')
+        lines.extend([
+            f"label {item['selection']}, \"{text}\"",
+            f"set label_color, {item['color']}, {item['selection']}",
+        ])
+    for view in views:
+        lines.append(f"orient {view['selection']}")
+        for axis in ("x", "y", "z"):
+            if axis in view["turn"]:
+                lines.append(f"turn {axis}, {float(view['turn'][axis])}")
+        output = (outdir / view["output"]).resolve()
+        lines.append(f"ray {width}, {height}")
+        lines.extend(visual_common.pymol_png(output, width=width, height=height))
+    lines.extend(visual_common.pymol_save(session))
+    lines.append("quit")
+    return lines
+
+
+def _chimerax_script(
+    structures: list[dict[str, Any]], representations: list[dict[str, str]],
+    labels: list[dict[str, str]], views: list[dict[str, Any]], outdir: Path,
+    *, background: str, width: int, height: int, session: Path,
+) -> list[str]:
+    lines = visual_common.chimerax_base(background=background)
+    for item in structures:
+        lines.append(f"open {visual_common.quote_chimerax(item['path'].resolve())} name {item['id']}")
+    lines.append("hide")
+    for item in representations:
+        target = item["selection"]
+        style = item["style"]
+        if style in {"cartoon", "ribbon"}:
+            lines.append(f"cartoon {target}")
+        elif style == "surface":
+            lines.append(f"surface {target}")
+        else:
+            atom_style = {"sticks": "stick", "spheres": "sphere", "lines": "wire"}[style]
+            lines.extend([f"show {target} atoms", f"style {target} {atom_style}"])
+        mode = item["color"]
+        if mode == "chain":
+            lines.append(f"color {target} bychain")
+        elif mode == "element":
+            lines.append(f"color {target} byelement")
+        elif mode == "plddt":
+            lines.append(f"color bfactor {target} palette alphafold")
+        elif mode == "bfactor":
+            lines.append(f"color bfactor {target}")
+        elif mode == "rainbow":
+            lines.append(f"rainbow {target}")
+        else:
+            lines.append(f"color {target} {mode}")
+        if "transparency" in item:
+            target_type = "s" if style == "surface" else "c" if style in {"cartoon", "ribbon"} else "a"
+            lines.append(f"transparency {target} {float(item['transparency']) * 100:.1f} target {target_type}")
+    for index, item in enumerate(labels, start=1):
+        text = item["text"].replace('"', '\\"')
+        lines.append(f"label {item['selection']} text \"{text}\" color {item['color']}")
+        lines.append(f"2dlabels create legend{index} text \"{text}\" color {item['color']} xpos 0.03 ypos {0.96 - index * 0.05:.2f}")
+    for view in views:
+        lines.append(f"view {view['selection']}")
+        for axis in ("x", "y", "z"):
+            if axis in view["turn"]:
+                lines.append(f"turn {axis} {float(view['turn'][axis])}")
+        output = (outdir / view["output"]).resolve()
+        lines.extend([f"save {visual_common.quote_chimerax(output)} width {width} height {height} supersample 3", "wait 1"])
+    lines.append(f"save {visual_common.quote_chimerax(session.resolve())}")
+    return lines
+
+
+def compile_scene(manifest_path: str, outdir: str, *, execute: bool = False) -> dict[str, Any]:
+    manifest = _load_manifest(manifest_path)
+    name = proteus_common.slug(str(manifest.get("name") or "scene"))
+    tool = str(manifest.get("tool") or "pymol").lower()
+    if tool not in {"pymol", "chimerax"}:
+        raise visual_common.VisualWorkflowError("tool must be pymol or chimerax.")
+    destination = Path(outdir)
+    destination.mkdir(parents=True, exist_ok=True)
+    structures = _structures(manifest)
+    representations = _representations(manifest)
+    labels = _labels(manifest)
+    views = _views(manifest, name)
+    width = int(manifest.get("width") or 1200)
+    height = int(manifest.get("height") or 900)
+    background = visual_common.color(str(manifest.get("background") or "white"))
+    if width < 100 or height < 100 or width > 10000 or height > 10000:
+        raise visual_common.VisualWorkflowError("Image dimensions must be between 100 and 10000 pixels.")
+    session = destination / f"{name}.{'pse' if tool == 'pymol' else 'cxs'}"
+    if tool == "pymol":
+        pml = _pymol_script(structures, representations, labels, views, destination,
+                            background=background, width=width, height=height, session=session)
+        cxc = None
+    else:
+        pml = None
+        cxc = _chimerax_script(structures, representations, labels, views, destination,
+                               background=background, width=width, height=height, session=session)
+    data: dict[str, Any] = {
+        "workflow": "figure",
+        "name": name,
+        "tool": tool,
+        "structures": [{"id": item["id"], "path": proteus_common.display_path(item["path"])} for item in structures],
+        "views": [{"id": item["id"], "output": proteus_common.display_path(destination / item["output"])} for item in views],
+        "session": proteus_common.display_path(session),
+        "executed": execute,
+    }
+    report = proteus_common.ok_payload(
+        data,
+        provenance={
+            "manifest": proteus_common.file_provenance(manifest_path),
+            "structures": [proteus_common.file_provenance(item["path"]) for item in structures],
+        },
+    )
+    outputs = visual_common.write_workflow(destination, name, report=report, pymol_lines=pml, chimerax_lines=cxc)
+    data["artifacts"] = outputs
+    if execute:
+        if tool == "pymol":
+            result = visual_common.run_pymol(destination / f"{name}.pml")
+        else:
+            result = visual_common.run_chimerax(cxc or [])
+        data["execution"] = result
+        if result.get("status") != "ok":
+            report["status"] = "error"
+            report["error"] = result.get("error", f"{tool} execution failed.")
+        else:
+            missing = [item["output"] for item in views if not visual_common.verify_nonempty(destination / item["output"])]
+            if missing:
+                report["status"] = "error"
+                report["error"] = f"Expected image outputs were not created: {', '.join(missing)}"
+        proteus_common.write_json(destination / f"{name}.json", report)
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Compile a reproducible PyMOL/ChimeraX scene manifest.")
+    parser.add_argument("manifest", help="JSON scene manifest")
+    parser.add_argument("--outdir", default="proteus_figure", help="Output directory")
+    parser.add_argument("--execute", action="store_true", help="Run the generated PyMOL/ChimeraX workflow")
+    parser.add_argument("--json", action="store_true", help="Emit JSON (accepted for consistency)")
+    args = parser.parse_args(argv)
+    try:
+        report = compile_scene(args.manifest, args.outdir, execute=args.execute)
+    except (OSError, ValueError, json.JSONDecodeError, visual_common.VisualWorkflowError) as exc:
+        print(json.dumps(proteus_common.error_payload(str(exc)), indent=2))
+        return 1
+    print(json.dumps(report, indent=2))
+    return 0 if report.get("status") == "ok" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/skills/proteus/scripts/state_compare.py b/skills/proteus/scripts/state_compare.py
new file mode 100644
index 0000000..45373c6
--- /dev/null
+++ b/skills/proteus/scripts/state_compare.py
@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""Compare structural states and create reproducible PyMOL comparison figures."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import compare_structures
+import interaction_report
+import proteus_common
+import visual_common
+
+
+def _contact_residues(report: dict[str, Any]) -> set[str]:
+    data = report.get("data", report)
+    output: set[str] = set()
+    for group in data.get("ligand_groups", []):
+        for residue in group.get("contact_residues", []):
+            label = residue.get("residue_label")
+            if label:
+                output.add(str(label))
+    return output
+
+
+def _contact_change(reference: Path, mobile: Path, ligand: str | None) -> tuple[dict[str, Any], list[str]]:
+    if not ligand:
+        return {}, []
+    warnings: list[str] = []
+    filters = [ligand.upper()]
+    reports = []
+    for path in (reference, mobile):
+        try:
+            reports.append(interaction_report.analyze_interactions(str(path), ligand_filters=filters))
+        except (OSError, ValueError, interaction_report.InteractionReportError) as exc:
+            warnings.append(f"Could not compare {ligand} contacts for {proteus_common.display_path(path)}: {exc}")
+            reports.append({"status": "error"})
+    if any(item.get("status") != "ok" for item in reports):
+        return {}, warnings
+    ref = _contact_residues(reports[0])
+    mob = _contact_residues(reports[1])
+    return {
+        "ligand": ligand.upper(),
+        "reference_contacts": sorted(ref),
+        "mobile_contacts": sorted(mob),
+        "gained_in_mobile": sorted(mob - ref),
+        "lost_in_mobile": sorted(ref - mob),
+        "preserved": sorted(ref & mob),
+    }, warnings
+
+
+def _pymol_lines(reference: Path, mobile: Path, outdir: Path, ligand: str | None,
+                  width: int, height: int) -> list[str]:
+    overlay = (outdir / "comparison_overlay.png").resolve()
+    exploded = (outdir / "comparison_side_by_side.png").resolve()
+    session = (outdir / "comparison.pse").resolve()
+    lines = visual_common.pymol_base(width=width, height=height)
+    lines.extend([
+        f"load {visual_common.quote_pymol(reference.resolve())}, reference",
+        f"load {visual_common.quote_pymol(mobile.resolve())}, mobile",
+        "hide everything, all",
+        "show cartoon, reference or mobile",
+        "color gray70, reference",
+        "color cyan, mobile",
+        "cealign reference, mobile",
+    ])
+    if ligand:
+        ligand_selection = f"resn {ligand.upper()}"
+        lines.extend([
+            f"show sticks, ({ligand_selection})",
+            f"color orange, reference and ({ligand_selection})",
+            f"color magenta, mobile and ({ligand_selection})",
+            f"show sticks, byres ((reference or mobile) within 4 of ({ligand_selection}))",
+        ])
+    lines.extend([
+        "orient reference or mobile",
+        f"ray {width}, {height}",
+        *visual_common.pymol_png(overlay, width=width, height=height),
+        "translate [22, 0, 0], mobile, camera=1",
+        "rotate y, 22, mobile, camera=1",
+        "orient reference or mobile",
+        f"ray {width}, {height}",
+        *visual_common.pymol_png(exploded, width=width, height=height),
+        *visual_common.pymol_save(session),
+        "quit",
+    ])
+    return lines
+
+
+def compare_states(reference: str, mobile: str, outdir: str, *, ligand: str | None = None,
+                   execute: bool = False, width: int = 1400, height: int = 900) -> dict[str, Any]:
+    ref = Path(reference).expanduser()
+    mob = Path(mobile).expanduser()
+    for path in (ref, mob):
+        if not path.is_file():
+            raise visual_common.VisualWorkflowError(f"Structure not found: {proteus_common.display_path(path)}")
+    if ligand and not ligand.replace("_", "").isalnum():
+        raise visual_common.VisualWorkflowError("Ligand code must be alphanumeric.")
+    destination = Path(outdir)
+    destination.mkdir(parents=True, exist_ok=True)
+    contact_change, warnings = _contact_change(ref, mob, ligand)
+    data: dict[str, Any] = {
+        "workflow": "compare",
+        "reference": proteus_common.display_path(ref),
+        "mobile": proteus_common.display_path(mob),
+        "ligand_contact_changes": contact_change or None,
+        "images": {
+            "overlay": proteus_common.display_path(destination / "comparison_overlay.png"),
+            "side_by_side": proteus_common.display_path(destination / "comparison_side_by_side.png"),
+        },
+        "session": proteus_common.display_path(destination / "comparison.pse"),
+        "executed": execute,
+    }
+    report = proteus_common.ok_payload(
+        data,
+        warnings=warnings,
+        provenance={"reference": proteus_common.file_provenance(ref), "mobile": proteus_common.file_provenance(mob)},
+    )
+    lines = _pymol_lines(ref, mob, destination, ligand, width, height)
+    artifacts = visual_common.write_workflow(destination, "state_compare", report=report, pymol_lines=lines)
+    data["artifacts"] = artifacts
+    if execute:
+        metrics = compare_structures.compare(str(ref), str(mob), per_residue=True)
+        if metrics.get("status") == "ok":
+            metric_data = metrics.get("data", {})
+            data["alignment"] = metric_data.get("alignment")
+            data["per_residue"] = metric_data.get("per_residue")
+        else:
+            report.setdefault("warnings", []).append(f"Alignment metrics failed: {metrics.get('error', 'unknown error')}")
+        execution = visual_common.run_pymol(destination / "state_compare.pml")
+        data["execution"] = execution
+        if execution.get("status") != "ok":
+            report["status"] = "error"
+            report["error"] = execution.get("error", "PyMOL comparison failed.")
+        else:
+            expected = [destination / "comparison_overlay.png", destination / "comparison_side_by_side.png"]
+            if not all(visual_common.verify_nonempty(path) for path in expected):
+                report["status"] = "error"
+                report["error"] = "PyMOL did not create all expected comparison images."
+        proteus_common.write_json(destination / "state_compare.json", report)
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Compare two structural states and render overlay/side-by-side figures.")
+    parser.add_argument("reference", help="Reference structure")
+    parser.add_argument("mobile", help="Mobile structure")
+    parser.add_argument("--ligand", help="Optional ligand code for contact-change analysis")
+    parser.add_argument("--outdir", default="proteus_compare", help="Output directory")
+    parser.add_argument("--width", type=int, default=1400)
+    parser.add_argument("--height", type=int, default=900)
+    parser.add_argument("--execute", action="store_true", help="Run PyMOL and produce figures/metrics")
+    parser.add_argument("--json", action="store_true", help="Emit JSON (accepted for consistency)")
+    args = parser.parse_args(argv)
+    try:
+        report = compare_states(args.reference, args.mobile, args.outdir, ligand=args.ligand,
+                                execute=args.execute, width=args.width, height=args.height)
+    except (OSError, ValueError, visual_common.VisualWorkflowError) as exc:
+        print(json.dumps(proteus_common.error_payload(str(exc)), indent=2))
+        return 1
+    print(json.dumps(report, indent=2))
+    return 0 if report.get("status") == "ok" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/skills/proteus/scripts/structure_info.py b/skills/proteus/scripts/structure_info.py
index 66a2e60..c580e43 100644
--- a/skills/proteus/scripts/structure_info.py
+++ b/skills/proteus/scripts/structure_info.py
@@ -74,6 +74,7 @@ def parse_pdb(path: str, force_alphafold: bool = False) -> dict:
     atom_count = 0
     hetatm_count = 0
     b_factors = []
+    residue_confidence = {}
     title_lines = []
 
     with open(path) as handle:
@@ -94,6 +95,10 @@ def parse_pdb(path: str, force_alphafold: bool = False) -> dict:
                 chains.add(chain)
                 residues[chain].add((residue_name, residue_id))
                 b_factors.append(b_factor)
+                atom_name = line[12:16].strip()
+                insertion_code = line[26].strip() if len(line) > 26 else ""
+                if rec == "ATOM" and atom_name == "CA":
+                    residue_confidence[(chain, residue_id, insertion_code, residue_name)] = b_factor
                 if rec == "ATOM":
                     atom_count += 1
                 else:
@@ -108,6 +113,7 @@ def parse_pdb(path: str, force_alphafold: bool = False) -> dict:
         atom_count=atom_count,
         hetatm_count=hetatm_count,
         b_factors=b_factors,
+        residue_confidence=residue_confidence,
         force_alphafold=force_alphafold,
     )
 
@@ -140,6 +146,7 @@ def parse_mmcif(path: str, force_alphafold: bool = False) -> dict:
     atom_count = 0
     hetatm_count = 0
     b_factors = []
+    residue_confidence = {}
 
     index = 0
     while index < len(lines):
@@ -164,6 +171,8 @@ def parse_mmcif(path: str, force_alphafold: bool = False) -> dict:
         comp_i = field_index.get("_atom_site.label_comp_id", field_index.get("_atom_site.auth_comp_id"))
         seq_i = field_index.get("_atom_site.auth_seq_id", field_index.get("_atom_site.label_seq_id"))
         b_i = field_index.get("_atom_site.B_iso_or_equiv")
+        atom_i = field_index.get("_atom_site.auth_atom_id", field_index.get("_atom_site.label_atom_id"))
+        insertion_i = field_index.get("_atom_site.pdbx_PDB_ins_code")
 
         while index < len(lines):
             stripped = lines[index].strip()
@@ -193,7 +202,14 @@ def parse_mmcif(path: str, force_alphafold: bool = False) -> dict:
                 hetatm_count += 1
             if b_i is not None:
                 try:
-                    b_factors.append(float(row[b_i]))
+                    b_factor = float(row[b_i])
+                    b_factors.append(b_factor)
+                    atom_name = row[atom_i] if atom_i is not None else ""
+                    insertion_code = row[insertion_i] if insertion_i is not None else ""
+                    if insertion_code in {".", "?"}:
+                        insertion_code = ""
+                    if group == "ATOM" and atom_name == "CA":
+                        residue_confidence[(chain, seq, insertion_code, comp)] = b_factor
                 except ValueError:
                     pass
 
@@ -206,6 +222,7 @@ def parse_mmcif(path: str, force_alphafold: bool = False) -> dict:
         atom_count=atom_count,
         hetatm_count=hetatm_count,
         b_factors=b_factors,
+        residue_confidence=residue_confidence,
         force_alphafold=force_alphafold,
     )
 
@@ -213,6 +230,7 @@ def parse_mmcif(path: str, force_alphafold: bool = False) -> dict:
 def _build_output(path: str, fmt: str, title: str | None, chains: set[str],
                   residues: dict[str, set[tuple[str, str]]], atom_count: int,
                   hetatm_count: int, b_factors: list[float],
+                  residue_confidence: dict[tuple[str, str, str, str], float],
                   force_alphafold: bool) -> dict:
     sorted_chains = sorted(chains)
     chain_details = {
@@ -232,7 +250,22 @@ def _build_output(path: str, fmt: str, title: str | None, chains: set[str],
         "likely_alphafold": likely_alphafold,
     }
     if likely_alphafold and b_factors:
-        data["plddt_distribution"] = _plddt_distribution(b_factors)
+        values = list(residue_confidence.values()) or b_factors
+        data["plddt"] = {
+            "basis": "ca_per_residue" if residue_confidence else "all_atoms",
+            "statistics": _bfactor_stats(values),
+            "distribution": _plddt_distribution(values),
+            "residues": [
+                {
+                    "chain": key[0],
+                    "residue": f"{key[1]}{key[2]}",
+                    "resname": key[3],
+                    "plddt": round(value, 2),
+                }
+                for key, value in sorted(residue_confidence.items())
+            ],
+        }
+        data["plddt_distribution"] = data["plddt"]["distribution"]
     output = {"status": "ok", "data": data}
     output.update(data)
     return output
diff --git a/skills/proteus/scripts/structure_qc.py b/skills/proteus/scripts/structure_qc.py
new file mode 100644
index 0000000..81f9c83
--- /dev/null
+++ b/skills/proteus/scripts/structure_qc.py
@@ -0,0 +1,486 @@
+#!/usr/bin/env python3
+"""Structure preflight and quality-control report for PDB/mmCIF inputs.
+
+The parser is intentionally dependency-free and conservative. It exposes model,
+alternate-conformer, occupancy, residue, and chemical-component decisions so
+downstream workflows do not silently combine incompatible coordinate states.
+"""
+
+from __future__ import annotations
+
+import argparse
+import gzip
+import json
+import math
+import shlex
+import sys
+from collections import Counter, defaultdict
+from pathlib import Path
+from typing import Any, Iterable
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import proteus_common
+
+
+STANDARD_AMINO_ACIDS = {
+    "ALA", "ARG", "ASN", "ASP", "CYS", "GLN", "GLU", "GLY", "HIS", "ILE",
+    "LEU", "LYS", "MET", "PHE", "PRO", "SER", "THR", "TRP", "TYR", "VAL",
+}
+MODIFIED_POLYMER = {
+    "MSE", "SEC", "PYL", "SEP", "TPO", "PTR", "CSO", "CSD", "CME", "MLY",
+    "M3L", "HYP", "KCX", "LLP", "FME", "PCA", "DAL", "DLE", "DVA", "DTH",
+}
+NUCLEOTIDES = {
+    "A", "C", "G", "U", "I", "DA", "DC", "DG", "DT", "DI", "ADE", "CYT",
+    "GUA", "THY", "URA",
+}
+WATERS = {"HOH", "WAT", "DOD", "H2O", "TIP", "T3P", "SOL"}
+IONS = {
+    "LI", "NA", "K", "RB", "CS", "MG", "CA", "SR", "BA", "MN", "FE", "CO",
+    "NI", "CU", "ZN", "CD", "HG", "AL", "GA", "CL", "BR", "IOD", "F", "SO4",
+    "PO4", "NO3", "NH4",
+}
+COFACTORS = {
+    "ATP", "ADP", "AMP", "GTP", "GDP", "GMP", "FAD", "FMN", "NAD", "NAP",
+    "NDP", "SAM", "SAH", "COA", "HEM", "HEC", "PLP", "TPP", "THF", "B12",
+}
+ADDITIVES = {
+    "GOL", "EDO", "PEG", "PG4", "PGE", "MPD", "DMS", "BME", "MES", "TRS",
+    "HEP", "ACT", "FMT", "ACE", "CIT", "TAR", "EOH", "IPA", "ACN", "BOG",
+}
+BACKBONE = {"N", "CA", "C", "O"}
+
+
+class StructureQCError(RuntimeError):
+    pass
+
+
+def _format_from_path(path: Path) -> str:
+    name = path.name.lower()
+    if name.endswith((".cif", ".mmcif", ".cif.gz", ".mmcif.gz")):
+        return "mmcif"
+    if name.endswith((".pdb", ".ent", ".pdb.gz", ".ent.gz")):
+        return "pdb"
+    raise StructureQCError("Input must be PDB/mmCIF, optionally gzip-compressed.")
+
+
+def _read_text(path: Path) -> str:
+    if path.name.lower().endswith(".gz"):
+        with gzip.open(path, "rt", encoding="utf-8", errors="replace") as handle:
+            return handle.read()
+    return path.read_text(encoding="utf-8", errors="replace")
+
+
+def _float(value: str | None) -> float | None:
+    if value is None or value in {"", ".", "?"}:
+        return None
+    try:
+        result = float(value)
+    except ValueError:
+        return None
+    return result if math.isfinite(result) else None
+
+
+def _clean(value: str | None, default: str = "") -> str:
+    if value is None or value in {"", ".", "?"}:
+        return default
+    return value
+
+
+def _atom(
+    *, record: str, model: int, serial: str, atom_name: str, altloc: str,
+    resname: str, chain: str, residue_id: str, insertion_code: str,
+    x: float, y: float, z: float, occupancy: float | None,
+    bfactor: float | None, element: str,
+) -> dict[str, Any]:
+    return {
+        "record": record,
+        "model": model,
+        "serial": serial,
+        "atom_name": atom_name,
+        "altloc": altloc,
+        "resname": resname.upper(),
+        "chain": chain or "?",
+        "residue_id": residue_id or "?",
+        "insertion_code": insertion_code,
+        "x": x,
+        "y": y,
+        "z": z,
+        "occupancy": occupancy,
+        "bfactor": bfactor,
+        "element": element.upper(),
+    }
+
+
+def parse_pdb(text: str) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+    atoms: list[dict[str, Any]] = []
+    current_model = 1
+    explicit_models = False
+    malformed = 0
+    link_records = 0
+    conect_records = 0
+    for line in text.splitlines():
+        record = line[:6].strip().upper()
+        if record == "MODEL":
+            explicit_models = True
+            try:
+                current_model = int(line[10:14].strip())
+            except ValueError:
+                current_model += 1
+            continue
+        if record == "LINK":
+            link_records += 1
+            continue
+        if record == "CONECT":
+            conect_records += 1
+            continue
+        if record not in {"ATOM", "HETATM"}:
+            continue
+        if len(line) < 54:
+            malformed += 1
+            continue
+        try:
+            atoms.append(_atom(
+                record=record,
+                model=current_model,
+                serial=line[6:11].strip(),
+                atom_name=line[12:16].strip(),
+                altloc=line[16].strip(),
+                resname=line[17:20].strip(),
+                chain=line[21].strip(),
+                residue_id=line[22:26].strip(),
+                insertion_code=line[26].strip(),
+                x=float(line[30:38]),
+                y=float(line[38:46]),
+                z=float(line[46:54]),
+                occupancy=_float(line[54:60] if len(line) >= 60 else None),
+                bfactor=_float(line[60:66] if len(line) >= 66 else None),
+                element=line[76:78].strip() if len(line) >= 78 else "",
+            ))
+        except ValueError:
+            malformed += 1
+    return atoms, {
+        "explicit_models": explicit_models,
+        "malformed_atom_records": malformed,
+        "link_records": link_records,
+        "conect_records": conect_records,
+    }
+
+
+def _field(fields: dict[str, int], *names: str) -> int | None:
+    for name in names:
+        if name in fields:
+            return fields[name]
+    return None
+
+
+def _value(row: list[str], index: int | None, default: str = "") -> str:
+    if index is None or index >= len(row):
+        return default
+    return row[index]
+
+
+def parse_mmcif(text: str) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+    lines = text.splitlines()
+    atoms: list[dict[str, Any]] = []
+    malformed = 0
+    struct_conn_rows = 0
+    index = 0
+    while index < len(lines):
+        if lines[index].strip() != "loop_":
+            index += 1
+            continue
+        index += 1
+        headers: list[str] = []
+        while index < len(lines) and lines[index].strip().startswith("_"):
+            headers.append(lines[index].strip())
+            index += 1
+        if not headers:
+            continue
+        atom_loop = all(item.startswith("_atom_site.") for item in headers)
+        conn_loop = all(item.startswith("_struct_conn.") for item in headers)
+        fields = {name: position for position, name in enumerate(headers)}
+        if atom_loop:
+            group_i = _field(fields, "_atom_site.group_PDB")
+            model_i = _field(fields, "_atom_site.pdbx_PDB_model_num")
+            serial_i = _field(fields, "_atom_site.id")
+            atom_i = _field(fields, "_atom_site.auth_atom_id", "_atom_site.label_atom_id")
+            alt_i = _field(fields, "_atom_site.label_alt_id", "_atom_site.auth_alt_id")
+            comp_i = _field(fields, "_atom_site.auth_comp_id", "_atom_site.label_comp_id")
+            chain_i = _field(fields, "_atom_site.auth_asym_id", "_atom_site.label_asym_id")
+            seq_i = _field(fields, "_atom_site.auth_seq_id", "_atom_site.label_seq_id")
+            ins_i = _field(fields, "_atom_site.pdbx_PDB_ins_code")
+            x_i = _field(fields, "_atom_site.Cartn_x")
+            y_i = _field(fields, "_atom_site.Cartn_y")
+            z_i = _field(fields, "_atom_site.Cartn_z")
+            occupancy_i = _field(fields, "_atom_site.occupancy")
+            bfactor_i = _field(fields, "_atom_site.B_iso_or_equiv")
+            element_i = _field(fields, "_atom_site.type_symbol")
+
+        while index < len(lines):
+            stripped = lines[index].strip()
+            if not stripped or stripped.startswith("#"):
+                index += 1
+                break
+            if stripped == "loop_" or stripped.startswith("_"):
+                break
+            try:
+                row = shlex.split(stripped, posix=True)
+            except ValueError:
+                malformed += 1
+                index += 1
+                continue
+            index += 1
+            if len(row) < len(headers):
+                malformed += 1
+                continue
+            if conn_loop:
+                struct_conn_rows += 1
+                continue
+            if not atom_loop:
+                continue
+            record = _clean(_value(row, group_i), "ATOM").upper()
+            if record not in {"ATOM", "HETATM"}:
+                continue
+            try:
+                atoms.append(_atom(
+                    record=record,
+                    model=int(_clean(_value(row, model_i), "1")),
+                    serial=_clean(_value(row, serial_i)),
+                    atom_name=_clean(_value(row, atom_i), "?"),
+                    altloc=_clean(_value(row, alt_i)),
+                    resname=_clean(_value(row, comp_i), "?"),
+                    chain=_clean(_value(row, chain_i), "?"),
+                    residue_id=_clean(_value(row, seq_i), "?"),
+                    insertion_code=_clean(_value(row, ins_i)),
+                    x=float(_value(row, x_i)),
+                    y=float(_value(row, y_i)),
+                    z=float(_value(row, z_i)),
+                    occupancy=_float(_value(row, occupancy_i)),
+                    bfactor=_float(_value(row, bfactor_i)),
+                    element=_clean(_value(row, element_i)),
+                ))
+            except (TypeError, ValueError):
+                malformed += 1
+    return atoms, {
+        "explicit_models": len({atom["model"] for atom in atoms}) > 1,
+        "malformed_atom_records": malformed,
+        "struct_conn_rows": struct_conn_rows,
+    }
+
+
+def _altloc_rank(atom: dict[str, Any]) -> tuple[float, int, str]:
+    occupancy = atom["occupancy"] if atom["occupancy"] is not None else -1.0
+    preferred = {"": 3, "A": 2, "1": 1}.get(atom["altloc"], 0)
+    return occupancy, preferred, atom["altloc"]
+
+
+def select_atoms(
+    atoms: list[dict[str, Any]], *, model: str = "first", altloc: str = "highest",
+) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+    models = sorted({atom["model"] for atom in atoms})
+    if not models:
+        return [], {"available_models": [], "selected_models": [], "alternate_sites": 0}
+    if model == "all":
+        selected_models = models
+    elif model == "first":
+        selected_models = [models[0]]
+    else:
+        try:
+            requested = int(model)
+        except ValueError as exc:
+            raise StructureQCError("--model must be 'first', 'all', or an integer.") from exc
+        if requested not in models:
+            raise StructureQCError(f"Model {requested} is not present; available models: {models}")
+        selected_models = [requested]
+    candidates = [atom for atom in atoms if atom["model"] in selected_models]
+    grouped: dict[tuple[Any, ...], list[dict[str, Any]]] = defaultdict(list)
+    for atom in candidates:
+        key = (
+            atom["model"], atom["chain"], atom["residue_id"], atom["insertion_code"],
+            atom["resname"], atom["atom_name"],
+        )
+        grouped[key].append(atom)
+    alternate_sites = sum(1 for values in grouped.values() if len({item["altloc"] for item in values}) > 1)
+    if altloc == "all":
+        selected = candidates
+    elif altloc == "highest":
+        selected = [max(values, key=_altloc_rank) for values in grouped.values()]
+    else:
+        requested = altloc.strip()
+        selected = []
+        for values in grouped.values():
+            exact = [item for item in values if item["altloc"] in {"", requested}]
+            selected.append(max(exact or values, key=_altloc_rank))
+    return selected, {
+        "available_models": models,
+        "selected_models": selected_models,
+        "alternate_sites": alternate_sites,
+        "altloc_policy": altloc,
+    }
+
+
+def component_role(resname: str, record: str, atom_count: int) -> str:
+    if record == "ATOM" or resname in STANDARD_AMINO_ACIDS or resname in NUCLEOTIDES:
+        return "polymer"
+    if resname in MODIFIED_POLYMER:
+        return "modified_polymer"
+    if resname in WATERS:
+        return "water"
+    if resname in IONS:
+        return "ion"
+    if resname in COFACTORS:
+        return "cofactor"
+    if resname in ADDITIVES:
+        return "additive_or_solvent"
+    return "ligand_or_unknown"
+
+
+def _residue_sort(value: str) -> tuple[int, int | str]:
+    try:
+        return 0, int(value)
+    except ValueError:
+        return 1, value
+
+
+def build_report(path: str | Path, *, model: str = "first", altloc: str = "highest") -> dict[str, Any]:
+    source = Path(path).expanduser()
+    if not source.is_file():
+        raise StructureQCError(f"File not found: {proteus_common.display_path(source)}")
+    fmt = _format_from_path(source)
+    text = _read_text(source)
+    raw_atoms, parser_meta = parse_mmcif(text) if fmt == "mmcif" else parse_pdb(text)
+    atoms, selection = select_atoms(raw_atoms, model=model, altloc=altloc)
+    warnings: list[str] = []
+    issues: list[dict[str, Any]] = []
+
+    if len(selection["available_models"]) > 1:
+        warnings.append("Multiple coordinate models are present; downstream geometry should use an explicit model.")
+        issues.append({"code": "multiple_models", "count": len(selection["available_models"])})
+    if selection["alternate_sites"]:
+        warnings.append("Alternate conformers are present; the report records the conformer-selection policy.")
+        issues.append({"code": "alternate_conformers", "count": selection["alternate_sites"]})
+    if parser_meta.get("malformed_atom_records"):
+        warnings.append("Some coordinate records could not be parsed by the lightweight parser.")
+        issues.append({"code": "malformed_atom_records", "count": parser_meta["malformed_atom_records"]})
+
+    residue_atoms: dict[tuple[Any, ...], list[dict[str, Any]]] = defaultdict(list)
+    component_atoms: dict[tuple[Any, ...], list[dict[str, Any]]] = defaultdict(list)
+    for atom in atoms:
+        residue_key = (
+            atom["model"], atom["chain"], atom["residue_id"], atom["insertion_code"], atom["resname"],
+        )
+        residue_atoms[residue_key].append(atom)
+        if atom["record"] == "HETATM":
+            component_atoms[residue_key].append(atom)
+
+    missing_backbone: list[dict[str, Any]] = []
+    chain_residues: dict[tuple[int, str], list[tuple[str, str, str]]] = defaultdict(list)
+    for (model_id, chain, residue_id, insertion_code, resname), values in residue_atoms.items():
+        if values[0]["record"] == "ATOM" or resname in STANDARD_AMINO_ACIDS or resname in MODIFIED_POLYMER:
+            chain_residues[(model_id, chain)].append((residue_id, insertion_code, resname))
+        if resname in STANDARD_AMINO_ACIDS:
+            present = {item["atom_name"] for item in values}
+            missing = sorted(BACKBONE - present)
+            if missing:
+                missing_backbone.append({
+                    "model": model_id,
+                    "chain": chain,
+                    "residue": f"{residue_id}{insertion_code}",
+                    "resname": resname,
+                    "missing": missing,
+                })
+    if missing_backbone:
+        warnings.append("Standard amino-acid residues with missing backbone atoms were detected.")
+        issues.append({"code": "missing_backbone_atoms", "count": len(missing_backbone)})
+
+    chain_gaps: list[dict[str, Any]] = []
+    for (model_id, chain), residues in sorted(chain_residues.items()):
+        numeric = sorted({int(item[0]) for item in residues if item[0].lstrip("-").isdigit()})
+        for left, right in zip(numeric, numeric[1:]):
+            if right - left > 1:
+                chain_gaps.append({"model": model_id, "chain": chain, "after": left, "before": right})
+    if chain_gaps:
+        warnings.append("Residue-number gaps were detected; they may represent missing density or numbering conventions.")
+
+    components: list[dict[str, Any]] = []
+    role_counts: Counter[str] = Counter()
+    for (model_id, chain, residue_id, insertion_code, resname), values in sorted(
+        component_atoms.items(), key=lambda item: (item[0][0], item[0][1], _residue_sort(item[0][2]), item[0][4]),
+    ):
+        role = component_role(resname, values[0]["record"], len(values))
+        role_counts[role] += 1
+        components.append({
+            "model": model_id,
+            "chain": chain,
+            "residue": f"{residue_id}{insertion_code}",
+            "component": resname,
+            "role": role,
+            "atom_count": len(values),
+            "elements": sorted({item["element"] for item in values if item["element"]}),
+        })
+
+    occupancies = [item["occupancy"] for item in atoms if item["occupancy"] is not None]
+    low_occupancy = sum(1 for value in occupancies if value < 0.5)
+    invalid_occupancy = sum(1 for value in occupancies if value < 0 or value > 1.01)
+    if low_occupancy:
+        issues.append({"code": "low_occupancy_atoms", "count": low_occupancy})
+    if invalid_occupancy:
+        warnings.append("Occupancy values outside the expected 0-1 range were detected.")
+        issues.append({"code": "invalid_occupancy_atoms", "count": invalid_occupancy})
+
+    chains = sorted({item["chain"] for item in atoms})
+    data = {
+        "file": proteus_common.display_path(source),
+        "format": fmt,
+        "compressed": source.name.lower().endswith(".gz"),
+        "selection": selection,
+        "counts": {
+            "raw_atoms": len(raw_atoms),
+            "selected_atoms": len(atoms),
+            "chains": len(chains),
+            "residues": len(residue_atoms),
+            "components": len(components),
+        },
+        "chains": chains,
+        "component_role_counts": dict(sorted(role_counts.items())),
+        "components": components,
+        "occupancy": {
+            "reported_atoms": len(occupancies),
+            "min": min(occupancies) if occupancies else None,
+            "max": max(occupancies) if occupancies else None,
+            "low_below_0_5": low_occupancy,
+        },
+        "missing_backbone": missing_backbone,
+        "numbering_gaps": chain_gaps,
+        "issues": issues,
+        "parser": parser_meta,
+    }
+    return proteus_common.ok_payload(
+        data,
+        warnings=warnings,
+        provenance={"input": proteus_common.file_provenance(source)},
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Preflight PDB/mmCIF coordinate quality and selection decisions.")
+    parser.add_argument("structure", help="PDB/mmCIF path, optionally .gz")
+    parser.add_argument("--model", default="first", help="Coordinate model: first, all, or integer (default: first)")
+    parser.add_argument("--altloc", default="highest", help="Alternate conformer: highest, all, or ID (default: highest)")
+    parser.add_argument("--json", action="store_true", help="Emit JSON (accepted for consistency; JSON is always emitted)")
+    args = parser.parse_args(argv)
+    try:
+        report = build_report(args.structure, model=args.model, altloc=args.altloc)
+    except (OSError, StructureQCError) as exc:
+        print(json.dumps(proteus_common.error_payload(str(exc)), indent=2))
+        return 1
+    print(json.dumps(report, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/skills/proteus/scripts/visual_common.py b/skills/proteus/scripts/visual_common.py
new file mode 100644
index 0000000..fe246f9
--- /dev/null
+++ b/skills/proteus/scripts/visual_common.py
@@ -0,0 +1,248 @@
+#!/usr/bin/env python3
+"""Shared helpers for reproducible PyMOL and ChimeraX workflows."""
+
+from __future__ import annotations
+
+import csv
+import json
+import os
+import re
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+import proteus_common
+
+
+IDENTIFIER_RE = re.compile(r"^[A-Za-z][A-Za-z0-9_]{0,63}$")
+COLOR_RE = re.compile(r"^(?:[A-Za-z][A-Za-z0-9_]{0,31}|#[0-9A-Fa-f]{6})$")
+STYLE_NAMES = {"cartoon", "sticks", "spheres", "surface", "lines", "ribbon"}
+
+
+class VisualWorkflowError(RuntimeError):
+    pass
+
+
+def identifier(value: str, *, field: str = "identifier") -> str:
+    if not IDENTIFIER_RE.fullmatch(value):
+        raise VisualWorkflowError(f"Invalid {field}: {value!r}")
+    return value
+
+
+def color(value: str) -> str:
+    if not COLOR_RE.fullmatch(value):
+        raise VisualWorkflowError(f"Invalid color: {value!r}")
+    return value
+
+
+def selection(value: str, *, field: str = "selection") -> str:
+    if not value or any(character in value for character in "\r\n;"):
+        raise VisualWorkflowError(f"Invalid {field}: selections cannot be empty or contain newlines/semicolons.")
+    return value
+
+
+def style(value: str) -> str:
+    if value not in STYLE_NAMES:
+        raise VisualWorkflowError(f"Unsupported representation style: {value}")
+    return value
+
+
+def quote_pymol(value: str | Path) -> str:
+    return '"' + str(value).replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def quote_chimerax(value: str | Path) -> str:
+    return '"' + str(value).replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def pymol_png(path: str | Path, *, width: int | None = None, height: int | None = None) -> list[str]:
+    """Write a PNG through the PyMOL Python API so quoted paths work reliably."""
+    options = []
+    if width is not None:
+        options.append(f"width={int(width)}")
+    if height is not None:
+        options.append(f"height={int(height)}")
+    suffix = ", " + ", ".join(options) if options else ""
+    return ["python", f"cmd.png({str(Path(path).resolve())!r}{suffix})", "python end"]
+
+
+def pymol_save(path: str | Path) -> list[str]:
+    """Save through the PyMOL Python API so quoted/session paths stay portable."""
+    return ["python", f"cmd.save({str(Path(path).resolve())!r})", "python end"]
+
+
+def find_pymol() -> str | None:
+    configured = os.environ.get("PYMOL_BIN", "")
+    return proteus_common.find_executable(
+        configured,
+        "pymol",
+        "/Applications/PyMOL.app/Contents/bin/pymol",
+        "~/Applications/PyMOL.app/Contents/bin/pymol",
+    )
+
+
+def find_chimerax() -> str | None:
+    configured = os.environ.get("CHIMERAX_BIN", "")
+    candidates = [
+        configured,
+        "ChimeraX",
+        "chimerax",
+        "/Applications/ChimeraX.app/Contents/bin/ChimeraX",
+    ]
+    applications = Path("/Applications")
+    if applications.is_dir():
+        candidates.extend(str(item / "Contents/bin/ChimeraX") for item in sorted(applications.glob("ChimeraX*.app"), reverse=True))
+    return proteus_common.find_executable(*candidates)
+
+
+def load_records(path: str | Path) -> list[dict[str, Any]]:
+    source = Path(path)
+    if not source.is_file():
+        raise VisualWorkflowError(f"File not found: {proteus_common.display_path(source)}")
+    if source.suffix.lower() == ".csv":
+        with source.open(newline="", encoding="utf-8-sig") as handle:
+            return [dict(row) for row in csv.DictReader(handle)]
+    payload = json.loads(source.read_text(encoding="utf-8"))
+    if isinstance(payload, list):
+        return [dict(item) for item in payload]
+    if isinstance(payload, dict):
+        for key in ("records", "annotations", "restraints", "scenes"):
+            value = payload.get(key)
+            if isinstance(value, list):
+                return [dict(item) for item in value]
+    raise VisualWorkflowError("Expected a CSV or JSON list of records.")
+
+
+def write_workflow(
+    outdir: str | Path,
+    name: str,
+    *,
+    report: dict[str, Any],
+    pymol_lines: list[str] | None = None,
+    chimerax_lines: list[str] | None = None,
+) -> dict[str, str]:
+    destination = Path(outdir)
+    destination.mkdir(parents=True, exist_ok=True)
+    outputs: dict[str, str] = {}
+    if pymol_lines is not None:
+        pml = destination / f"{name}.pml"
+        pml.write_text("\n".join(pymol_lines).rstrip() + "\n", encoding="utf-8")
+        outputs["pymol_script"] = proteus_common.display_path(pml)
+    if chimerax_lines is not None:
+        cxc = destination / f"{name}.cxc"
+        cxc.write_text("\n".join(chimerax_lines).rstrip() + "\n", encoding="utf-8")
+        outputs["chimerax_script"] = proteus_common.display_path(cxc)
+    report_path = destination / f"{name}.json"
+    outputs["report"] = proteus_common.display_path(report_path)
+    data = report.get("data")
+    if isinstance(data, dict):
+        data["artifacts"] = dict(outputs)
+    proteus_common.write_json(report_path, report)
+    return outputs
+
+
+def run_pymol(script_path: str | Path, *, timeout: int = 300) -> dict[str, Any]:
+    executable = find_pymol()
+    if not executable:
+        return {"status": "unavailable", "error": "PyMOL was not found."}
+    result = proteus_common.run_command([executable, "-c", "-q", str(Path(script_path).resolve())], timeout=timeout)
+    return execution_summary(result)
+
+
+def run_chimerax(commands: list[str], *, timeout: int = 600) -> dict[str, Any]:
+    executable = find_chimerax()
+    if not executable:
+        return {"status": "unavailable", "error": "ChimeraX was not found."}
+    env = os.environ.copy()
+    env["CHIMERAX_BIN"] = executable
+    command_text = ";".join(commands)
+    result = proteus_common.run_command(
+        [sys.executable, str(SCRIPT_DIR / "chimerax_rest.py"), "run", command_text],
+        timeout=timeout,
+        env=env,
+    )
+    if result.get("returncode") == 0:
+        try:
+            payload = json.loads(result.get("stdout") or "{}")
+        except json.JSONDecodeError:
+            payload = None
+        if isinstance(payload, dict) and payload.get("status") == "error":
+            result["status"] = "error"
+            result["error"] = payload.get("error", "ChimeraX workflow failed.")
+        elif payload is not None:
+            result["payload"] = payload
+    return execution_summary(result)
+
+
+def execution_summary(result: dict[str, Any]) -> dict[str, Any]:
+    """Return useful execution diagnostics without embedding commands or raw data."""
+    cleaned = proteus_common.scrub_private(result)
+    output: dict[str, Any] = {"status": cleaned.get("status", "error")}
+    if "returncode" in cleaned:
+        output["returncode"] = cleaned.get("returncode")
+    if cleaned.get("error"):
+        output["error"] = cleaned["error"]
+    payload = cleaned.get("payload")
+    if isinstance(payload, dict):
+        history = payload.get("data", {}).get("history") if isinstance(payload.get("data"), dict) else None
+        if isinstance(history, list):
+            output["commands_completed"] = len(history)
+            output["elapsed_seconds"] = round(sum(float(item.get("elapsed_seconds") or 0) for item in history if isinstance(item, dict)), 3)
+    if output["status"] != "ok":
+        for key in ("stderr", "stdout"):
+            value = cleaned.get(key)
+            if isinstance(value, str) and value.strip():
+                output[key] = value[-4000:]
+    return output
+
+
+def verify_nonempty(path: str | Path, *, attempts: int = 8, delay: float = 0.25) -> bool:
+    candidate = Path(path)
+    for _ in range(attempts):
+        if candidate.is_file() and candidate.stat().st_size > 0:
+            return True
+        time.sleep(delay)
+    return False
+
+
+def pymol_base(*, background: str = "white", width: int = 1200, height: int = 900) -> list[str]:
+    color(background)
+    return [
+        "reinitialize",
+        "set auto_zoom, 0",
+        f"bg_color {background}",
+        "set ray_opaque_background, 1",
+        "set antialias, 2",
+        "set cartoon_fancy_helices, 1",
+        "set cartoon_smooth_loops, 1",
+        "set cartoon_flat_sheets, 1",
+        "set ray_shadows, 1",
+        "set specular, 0.25",
+        "set ambient, 0.42",
+        f"viewport {int(width)}, {int(height)}",
+    ]
+
+
+def chimerax_base(*, background: str = "white") -> list[str]:
+    color(background)
+    return [f"set bgColor {background}", "lighting soft"]
+
+
+def finalize_pymol(output: str | Path, *, width: int = 1200, height: int = 900, session: str | Path | None = None) -> list[str]:
+    lines = ["orient", f"ray {int(width)}, {int(height)}", *pymol_png(output, width=width, height=height)]
+    if session is not None:
+        lines.extend(pymol_save(session))
+    lines.append("quit")
+    return lines
+
+
+def finalize_chimerax(output: str | Path, *, width: int = 1200, height: int = 900, session: str | Path | None = None) -> list[str]:
+    lines = ["view", f"save {quote_chimerax(Path(output).resolve())} width {int(width)} height {int(height)} supersample 3", "wait 1"]
+    if session is not None:
+        lines.append(f"save {quote_chimerax(Path(session).resolve())}")
+    return lines
diff --git a/tests/test_workflows.py b/tests/test_workflows.py
new file mode 100644
index 0000000..94df0f8
--- /dev/null
+++ b/tests/test_workflows.py
@@ -0,0 +1,220 @@
+#!/usr/bin/env python3
+import json
+import struct
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "scripts"))
+
+import annotation_figure
+import chemical_site
+import cryoem_workflow
+import electrostatics_workflow
+import ensemble_report
+import model_quality
+import pae_report
+import proteus_common
+import restraint_report
+import scene_figure
+import structure_info
+import structure_qc
+import sync_skill_package
+import visual_common
+
+
+TINY_PDB = ROOT / "tests" / "fixtures" / "tiny.pdb"
+
+
+class RuntimeAndQCWorkflowTests(unittest.TestCase):
+    def test_runtime_envelope_paths_and_secret_urls(self):
+        report = proteus_common.ok_payload({"value": 1}, warnings=["check"], provenance={"source": "fixture"})
+        self.assertEqual(report["status"], "ok")
+        self.assertEqual(report["schema_version"], 1)
+        self.assertNotIn(str(Path.home()), proteus_common.display_path(TINY_PDB))
+        self.assertNotIn(str(Path.home()), proteus_common.scrub_text(str(Path.home()).encode()))
+        with self.assertRaises(proteus_common.ProteusRuntimeError):
+            proteus_common.request_bytes("https://example.org/data?token=secret", retries=0)
+
+    def test_structure_qc_reports_selection_components_and_missing_backbone(self):
+        report = structure_qc.build_report(TINY_PDB)
+        self.assertEqual(report["status"], "ok")
+        data = report["data"]
+        self.assertEqual(data["selection"]["selected_models"], [1])
+        self.assertEqual(data["component_role_counts"], {"ligand_or_unknown": 1})
+        self.assertEqual(data["missing_backbone"][0]["missing"], ["O"])
+        self.assertEqual(report["provenance"]["input"]["sha256"], proteus_common.sha256_file(TINY_PDB))
+
+    def test_structure_info_uses_ca_per_residue_for_plddt(self):
+        report = structure_info.inspect_structure(str(TINY_PDB), force_alphafold=True)
+        self.assertEqual(report["plddt"]["basis"], "ca_per_residue")
+        self.assertEqual(report["plddt"]["residues"][0]["plddt"], 91.0)
+
+    def test_chain_aware_pae_blocks(self):
+        report = pae_report.summarize_pae(
+            str(ROOT / "tests" / "fixtures" / "tiny_pae.json"), min_segment=1,
+            chain_lengths="A:2,B:2",
+        )
+        blocks = report["data"]["chain_analysis"]["blocks"]
+        self.assertEqual(len(blocks), 4)
+        self.assertLess(blocks[0]["mean_pae"], blocks[1]["mean_pae"])
+
+
+class ReproducibleWorkflowTests(unittest.TestCase):
+    def test_scene_manifest_writes_scripts_and_persisted_artifact_index(self):
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            manifest = root / "scene.json"
+            manifest.write_text(json.dumps({
+                "name": "tiny-scene",
+                "tool": "pymol",
+                "structures": [{"id": "tiny", "path": str(TINY_PDB)}],
+                "representations": [{"style": "cartoon", "selection": "polymer", "color": "chain"}],
+                "views": [{"id": "overview", "output": "overview.png"}],
+            }), encoding="utf-8")
+            report = scene_figure.compile_scene(str(manifest), str(root / "out"))
+            disk = json.loads((root / "out" / "tiny-scene.json").read_text(encoding="utf-8"))
+            self.assertEqual(report["status"], "ok")
+            self.assertTrue((root / "out" / "tiny-scene.pml").is_file())
+            self.assertIn("artifacts", disk["data"])
+
+    def test_scene_manifest_rejects_output_traversal(self):
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            manifest = root / "scene.json"
+            manifest.write_text(json.dumps({
+                "structures": [{"path": str(TINY_PDB)}],
+                "views": [{"output": "../outside.png"}],
+            }), encoding="utf-8")
+            with self.assertRaises(visual_common.VisualWorkflowError):
+                scene_figure.compile_scene(str(manifest), str(root / "out"))
+
+    def test_chimerax_scene_uses_supported_label_and_transparency_syntax(self):
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            manifest = root / "scene.json"
+            manifest.write_text(json.dumps({
+                "tool": "chimerax",
+                "structures": [{"path": str(TINY_PDB)}],
+                "representations": [{
+                    "style": "cartoon", "selection": "#1", "color": "chain", "transparency": 0.25,
+                }],
+                "labels": [{"selection": "#1/A:1@CA", "text": "site"}],
+            }), encoding="utf-8")
+            scene_figure.compile_scene(str(manifest), str(root / "out"))
+            cxc = (root / "out" / "scene.cxc").read_text(encoding="utf-8")
+            self.assertIn("transparency #1 25.0 target c", cxc)
+            self.assertIn("2dlabels create legend1 text \"site\"", cxc)
+            self.assertNotIn("create name", cxc)
+
+    def test_annotation_and_restraint_reports(self):
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            annotations = root / "annotations.csv"
+            annotations.write_text("chain,residue,score,label\nA,1,0.8,site\n", encoding="utf-8")
+            annotation = annotation_figure.build_annotation_figure(
+                str(TINY_PDB), str(annotations), str(root / "annotation"),
+            )
+            self.assertEqual(annotation["data"]["annotation_count"], 1)
+
+            restraints = root / "restraints.json"
+            restraints.write_text(json.dumps([{
+                "chain1": "A", "residue1": "1", "atom1": "CA",
+                "chain2": "B", "residue2": "2", "atom2": "C1",
+                "min": 0, "max": 5,
+            }]), encoding="utf-8")
+            result = restraint_report.evaluate_restraints(
+                str(TINY_PDB), str(restraints), str(root / "restraints"),
+            )
+            self.assertEqual(result["data"]["summary"]["satisfied"], 1)
+            self.assertGreater(result["data"]["restraints"][0]["distance"], 0)
+            cxc = (root / "restraints" / "restraint_report.cxc").read_text(encoding="utf-8")
+            self.assertIn("show #1/A:1@CA atoms\nshow #1/B:2@C1 atoms", cxc)
+            self.assertNotIn("@CA,#1", cxc)
+
+    def test_chemical_site_reports_neighborhood(self):
+        with tempfile.TemporaryDirectory() as temporary:
+            report = chemical_site.inspect_chemical_site(
+                str(TINY_PDB), temporary, component="LIG", radius=5,
+            )
+            self.assertEqual(report["status"], "ok")
+            self.assertEqual(report["data"]["site"]["role"], "ligand_or_unknown")
+            self.assertTrue(report["data"]["neighbors"])
+
+    def test_cryoem_local_map_generates_contour_sweep(self):
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            density = root / "tiny.mrc"
+            header = bytearray(1024)
+            struct.pack_into("<4i", header, 0, 2, 2, 1, 2)
+            struct.pack_into("<i", header, 92, 0)
+            density.write_bytes(bytes(header) + struct.pack("<4f", 0.0, 1.0, 2.0, 3.0))
+            report = cryoem_workflow.build_cryoem_workflow(
+                str(TINY_PDB), str(density), str(root / "out"), resolution=3.0,
+            )
+            self.assertEqual(report["status"], "ok")
+            self.assertEqual(len(report["data"]["contour_levels"]), 3)
+            self.assertTrue((root / "out" / "cryoem_workflow.cxc").is_file())
+
+    def test_electrostatics_uses_supported_coulombic_options(self):
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            report = electrostatics_workflow.build_electrostatics_workflow(
+                str(TINY_PDB), str(root / "out"), offset=1.8,
+            )
+            self.assertEqual(report["status"], "ok")
+            cxc = (root / "out" / "electrostatics_workflow.cxc").read_text(encoding="utf-8")
+            self.assertIn("coulombic #1 & protein offset 1.8", cxc)
+            self.assertIn("transparency #1 & protein 8 target s", cxc)
+            self.assertNotIn(" distance ", cxc)
+
+    def test_execution_summary_omits_commands_and_scrubs_local_paths(self):
+        summary = visual_common.execution_summary({
+            "status": "ok",
+            "returncode": 0,
+            "stdout": f"opened {Path.home()}/private/input.pdb",
+            "payload": {"data": {"history": [
+                {"command": f"open {Path.home()}/private/input.pdb", "elapsed_seconds": 0.25},
+            ]}},
+        })
+        self.assertEqual(summary, {"status": "ok", "returncode": 0, "commands_completed": 1, "elapsed_seconds": 0.25})
+        self.assertNotIn(str(Path.home()), json.dumps(summary))
+
+    def test_ensemble_rmsf_uses_common_ca_atoms(self):
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            structure = root / "ensemble.pdb"
+            lines = []
+            serial = 1
+            for model, offset in ((1, 0.0), (2, 0.4)):
+                lines.append(f"MODEL     {model:4d}")
+                for residue, x in ((1, 0.0), (2, 3.8), (3, 7.6)):
+                    lines.append(
+                        f"ATOM  {serial:5d}  CA  ALA A{residue:4d}    "
+                        f"{x:8.3f}{offset * residue:8.3f}{0.0:8.3f}{1.0:6.2f}{80.0:6.2f}           C"
+                    )
+                    serial += 1
+                lines.append("ENDMDL")
+            structure.write_text("\n".join(lines) + "\n", encoding="utf-8")
+            report = ensemble_report.analyze_ensemble(str(structure), str(root / "out"))
+            self.assertEqual(report["data"]["model_count"], 2)
+            self.assertEqual(report["data"]["common_ca_count"], 3)
+            self.assertEqual(len(report["data"]["residues"]), 3)
+
+
+class OptionalToolAndPackagingTests(unittest.TestCase):
+    def test_foldseek_table_parser(self):
+        rows = model_quality._parse_foldseek_table("q\tt\t0.8\t0.7\t0.9\t0.75\t1e-6\t120\n")
+        self.assertEqual(rows[0]["query"], "q")
+        self.assertEqual(rows[0]["qtmscore"], 0.7)
+        self.assertEqual(rows[0]["evalue"], 1e-6)
+
+    def test_installable_package_is_in_sync(self):
+        self.assertEqual(sync_skill_package.compare()["status"], "ok")
+
+
+if __name__ == "__main__":
+    unittest.main()