Update to Molecular Structure Viewer

{
  "name": "structure-viewer",
  "description": "Open, query, analyze, compare, style, animate, and render local molecular structures in Codex's interactive molecular workspace powered by Mol*. Use for PDB, CIF/mmCIF and their gzip/BGZF variants, MOL/SDF/MOL2, PQR/PDBQT, GRO/XYZ, molecular objects, residue exposure, density maps, and topology-plus-trajectory workflows.",
  "included_files": [],
  "skill_md_contents": "---\nname: structure-viewer\ndescription: Open, query, analyze, compare, style, animate, and render local molecular structures in Codex's interactive molecular workspace powered by Mol*. Use for PDB, CIF/mmCIF and their gzip/BGZF variants, MOL/SDF/MOL2, PQR/PDBQT, GRO/XYZ, molecular objects, residue exposure, density maps, and topology-plus-trajectory workflows.\n---\n\n# Molecular Structure Viewer\n\nUse this skill when a user wants to inspect a molecular structure visually inside Codex.\n\n## Opening Workflow\n\nThe plugin contributes native file-pane preview and a model-visible MCP App for supported molecular structure files. A workspace click uses the existing native file viewer. For a new viewer, call `structure.open_from_chat` to open in chat or `structure.open_in_side_pane` to open directly in the side pane; default to chat when the user has no placement preference. Do not read or copy structure bytes into the conversation, start a localhost or browser server, scaffold another viewer, edit project files, or substitute a static image merely to display an existing local structure. An explicitly requested accession download or authorized export remains a separate intentional action.\n\n1. Resolve the user's intended molecular structure source. Prefer the explicitly named path. If the user asks to view an example, generic, or demo protein structure without naming a path, accession, or protein, use the bundled `gfp-1ema` example; do not search the workspace, ask a clarification question, or download it. If the request supplies an RCSB PDB accession or `https://files.rcsb.org/download/<ID>.pdb` URL and no local file, download that exact entry to a workspace-local `.pdb` file before continuing; the accession or URL is sufficient input, so do not ask the user to provide another file. Otherwise, if the request is ambiguous, search only the relevant workspace and ask a short clarification question when multiple plausible structures remain.\n2. Confirm that the primary file is a supported PDB, CIF, mmCIF, MOL, SDF, MOL2, PQR, PDBQT, GRO, or XYZ artifact, or a supported gzip/BGZF-compressed PDB, CIF, or mmCIF coordinate file. Related maps and trajectories are loaded after the primary viewer mounts.\n3. Generate one UUID `openIntentId` for this user request, then call the opening tool for the chosen placement with exactly one source: `exampleId: \"gfp-1ema\"` for the unnamed example-protein request above, or the exact absolute local `path` whenever available. Both tools accept the same arguments. Omit the deprecated `presentation` argument. Chat previews use compact controls; side panes and native file previews use the full viewer, with **Show controls** in narrow panes. **Open viewer** moves the same chat preview to the side pane without reopening its source. Reuse the same tool and `openIntentId` for delivery retries and omit `reopen`; the two tools share one opening intent, so changing tools does not create or move another viewer. Even if a retry accidentally supplies a fresh UUID, the server reuses the active viewer in the host conversation. Only when the user explicitly asks to open another viewer, generate a fresh UUID and set `reopen: true`. A workspace-relative path works only when the MCP host exposes active roots. The bundled example is read-only and does not grant source-relative workspace publication. The tool returns a `viewerSessionId` in `structuredContent`; use that ID immediately for same-turn `structure.control_viewer` calls instead of waiting for later model context. Before a same-turn `structure.molecular_action`, read its required `expectedRevision` from `structure.molecular_actions` or `structure.get_state` for that same session.\n4. Read `viewerOpen.mountState`, `viewerOpen.renderState`, and `viewerReady` before describing the viewer; use `structure.get_viewer_status` for subsequent lifecycle observations. `presentation-issued`, `mount-pending`, and `renderState: \"pending\"` mean the same native viewer is still opening; `sessionReady` confirms only its server session. Say that the Molecular Structure Viewer is opening in the requested surface. Call it visible, rendered, or ready only when `viewerReady: true`, `renderState: \"ready\"`, and the authenticated viewer is `mounted`; read `structure.get_context` for fresh scene state. If rendering reports `\"error\"` or opening or a side-pane request stalls or fails, briefly report the actual state and retry the existing session; do not create a second viewer or claim the pane succeeded. Do not repeat or code-format the file name or path, say that the path was opened, or imply that a path or file citation is clickable; citation clicks can open raw text instead.\n5. After the Mol\\* app opens, call `structure.get_context` for follow-up questions about the displayed structure, representation, coloring, focused ligand, chain, residue, or selection. Opening and interacting with the viewer do not automatically add its state to chat.\n\nDo not call the app-only `structure.open` tool directly from chat. It is reserved for Codex's native file-preview host because it requires an opaque `codex-resource://` URI that only the host can mint. Use the model-visible opening tool for the requested placement.\n\nThe mounted app requests explicit host `text` for known structures and `blob` for known binary related data, using auto-detection only for unknown dependencies. It privately retains typed native ETag/writability metadata for downstream host capability work, but that metadata is not a model tool, path, project identity, or permission to mutate the source. Never claim that an opened source was subscribed, replaced, or made writable; this version keeps sources immutable and creates derived artifacts only through the established publication tools.\n\nOne user request owns one viewer open. Never call either opening tool again to recover from a control, analysis, alignment, or render failure; retry the failed operation against the original `viewerSessionId`. For comparisons, keep both structures in that viewer with `structure.add_structure` and the alignment tools.\n\nIf the user asks to move, send, pin, or open an already-mounted viewer in the right pane, do not call either opening tool again. Use `structure.control_viewer` with the resolved `sessionId` and action `set_display_mode`; use `fullscreen` for the side pane and `inline` for chat. The in-view **Open viewer** and **Return to chat** buttons change placement. Native file previews retain **Ask about selection** to establish a chat reference; chat-opened viewers use their existing session. Sharing an image requires an explicit image render.\n\nThe visible **Measure** control opens the molecule analysis panel, where the user can choose any two polymer residues, including residues on different chains, and inspect the closest-heavy-atom distance and atom pair without asking the model. Ligand contact controls and cutoff provenance are available in the same panel.\n\n## Shipped Starter Workflows\n\nTreat the manifest's three starter prompts as exact contracts. Before opening or adding any starter structure, read the packaged [starter example contract](../../examples/starter-examples.json), resolve every named RCSB accession through its recorded URL, and download it into the active workspace. Verify every downloaded source against its contract record: RCSB revision, exact byte length, SHA-256 digest, and atom count must all match. If any value differs, stop before `structure.open_from_chat` or `structure.add_structure` and report source-drift diagnostics with the accession and expected versus observed values; do not silently substitute another revision or continue against stale scientific expectations. Use one `openIntentId`, one `structure.open_from_chat` call, one visible viewer card, and one active `viewerSessionId` for each starter; all later tools must reuse that session.\n\n### MDM2–p53 interface analysis\n\nExact prompt:\n\n> Open RCSB 1YCR once; analyze 4 Å MDM2–p53 contacts and buried area, label p53 Phe19/Trp23/Leu26, and report methods.\n\nAfter opening, call `structure.get_state`; run `structure.analyze` for `contacts` with a 4 Å cutoff and for `buried_area` with a 1.4 Å probe and 240 samples between atom-disjoint chains A and B; then apply hotspot styling and selection annotations to author-numbered chain B residues PHE19, TRP23, and LEU26 at the returned revision. Preserve the complete complex as a cartoon, add connected hotspot sticks as a separate layer, use conventional element coloring for those sticks, and keep labels restrained; do not replace the surrounding protein with isolated lines, oversized spheres, or giant labels. Frame the complete primary object with the current orientation and zoom `1.3`, so the complex is prominent without clipping. Report `interfaceAreaSquareAngstrom ≈ 735.864963 Ų` and `totalSasaLossSquareAngstrom ≈ 1471.729925 Ų` separately: the one-sided interface area is half the coordinate-derived Shrake–Rupley SASA loss across both partners. Preserve the 705/113 partner-atom counts, component SASAs, truncation, exact result count, probe, samples, and provenance; never report either geometric quantity as affinity, binding energy, or the other quantity.\n\n### Adenylate-kinase conformational comparison\n\nExact prompt:\n\n> Open RCSB 4AKE once; add 1AKE to the same viewer, align chain A, color teal/magenta, show AP5, and report RMSD/TM-scores.\n\nOpen only 4AKE. Call `structure.add_structure` for 1AKE with `objectId: \"ap5a_bound\"`, then list the returned object IDs and verify that exact ID before calling `structure.align_structures` with `method: \"structure\"` and chain A selections. Apply object-specific cartoon colors plus an AP5 sticks layer in the same viewer, then frame exactly primary chain A and `ap5a_bound` chain A from the left at zoom `1.15`; do not include unrepresented chain B atoms in the camera bound. This projection keeps both conformers clear of the card edges while using the host-owned inline width more effectively. Report Mol\\* TM-align's aligned count, RMSD, and both directional TM-scores; do not replace them with literature values or imply that two merely visible structures are aligned.\n\n### GFP publication image\n\nExact prompt:\n\n> Open RCSB 1EMA once; style and label its chromophore; save a versioned 1600×1200 PNG to structure-viewer/gfp.png with sidecar.\n\nKeep `1EMA.pdb` at the active workspace root and create the named child output folder before opening; do not fabricate or invoke app-only destination-picker tokens from a model tool. Target CRO by chain A, author residue 66, and component ID `CRO`, because the chromophore is polymer-linked and must not depend on generic ligand ranking. Apply the canonical layers, label, dark background, and a front camera focused on the complete primary object at zoom `1.15`; call `structure.validate_render`, then `structure.render_image` with matching `outputPath` and `destination.relativePath`, `destination.kind: \"workspace\"`, `base: \"opened-source\"`, and `collisionPolicy: \"versioned\"`. Report only workspace-relative paths. A successful result must include the PNG and its `.render.json` sidecar; if the source-relative publication capability is absent, report that prerequisite instead of silently falling back to an absolute path or overwrite.\n\nThe authoritative source digests, expected numeric results, budgets, artifact invariants, allowed nondeterminism, and downstream qualification runbook live in the packaged [starter example contract](../../examples/starter-examples.json). They are contract targets pending final clean-installed-host qualification; do not claim that qualification has already happened.\n\n## Read Context On Demand\n\nUse the session ID from the opening result or an explicit **Ask about selection** request. Otherwise call `structure.list_viewers`; it includes only previously referenced sessions successfully read in trusted conversation scope, not every open viewer. A manually opened viewer first needs an explicit selection-action reference. When discovery is unavailable, use an existing explicit session reference or ask the user to identify the viewer through its selection action. Resolve multiple matches instead of choosing the most recently opened viewer.\n\nStart with `structure.list_documents`, choose an actual `documentId`, then use `structure.read_document` to read it or `structure.search_document` with a literal `query` to locate relevant text. Read the matching range in context. These general document tools support questions beyond the predefined molecular queries; use domain tools as typed shortcuts when they fit, not as an exhaustive menu of available information.\n\nSearch is case-insensitive by default; set `caseSensitive: true` when needed. Match snippets are previews. Continue with `offset: nextOffset` and set `expectedRevision` to the preceding response's `revision` until `eof` when more matches are needed, then read exact UTF-16 ranges from the same document revision.\n\nUse `structure.get_context` when a compact orientation is useful, with the needed `sections`: `overview`, `selection`, `viewport`, `display`, `annotations`, `results`, `inventory`, `status`, or `capabilities`. Check freshness, readiness, source/revision, requested/effective scope, unavailable sections, and truncation. `last_observed` cannot establish the current visible scene; unavailable selection is not empty selection. Use `expectedRevision` for reads tied to a particular snapshot and refresh after conflicts. Preserve focused versus selected targets, object and assembly-instance identity, author versus label numbering, insertion codes, and coordinate frames. For regular command sessions, source revision identifies loaded geometry rather than a file-content hash; native observations retain their native source revision separately from scene and geometry revisions. Selection and visible scopes expose only applicable sections; use document/source reads for information outside the compact snapshot.\n\nFor complete literal data, call `structure.list_documents` and read an exact returned `documentId` with `structure.read_document`. Use `offset`/`length` for a range or `full: true` to read as far as one response permits. Read offsets are UTF-16 code units. To read the whole document, start at `offset: 0`, append returned `text`, and repeat `full: true` with `offset: nextOffset` until `eof`. Keep `expectedRevision` pinned to the descriptor's opaque document revision rather than substituting the numeric scene revision. `continuationReason: \"transport_limit\"` means more data remains, not that the document was shortened; total document access has no transport ceiling. Reads fail if source/revision identity changes. Loaded documents describe the current workbench rather than original source bytes or unimported models/frames. `atoms.json` provides identity/property records, not Cartesian coordinates; existing analysis documents report retained, expired, and incomplete results honestly. Preserve these coverage semantics when answering.\n\nInspect `source.json` when available and use `structure.read_source` when the question needs authorized source content, including coordinate records. Its `offsetDecimal` is a decimal byte offset and `length` is a byte count. For the whole source, start with `full: true` and `offsetDecimal: \"0\"`; decode each returned `dataBase64` and repeat `full: true` with `offsetDecimal: nextOffsetDecimal` and the exact source `expectedRevision` until `eof`. Large results report `continuationReason: \"transport_limit\"` and require continuation. The source revision is distinct from the document revision. Preserve `representation: \"original\" | \"logical-decompressed\"`: a native gzip reader may supply decompressed logical content, not the original compressed bytes. Honor random-access versus forward-only metadata and do not invent a total size when it is unknown. A view without source access cannot supply those bytes; current scene documents are not a substitute for the original. Reading local source content does not authorize a public lookup or upload using it.\n\nA native preview's first **Ask about selection** lazily creates a session for the same mounted viewer and its document providers. Read `structure.get_context` with `sections: [\"capabilities\"]`: when the capabilities section advertises `presentationControls`, use only its `actions` with `structure.control_viewer` with the returned context revision as `expectedRevision`. This supports changing the existing display and selection without reopening the file. A reference without that capability remains read-only; neither reference grants new analyses, source writes, artifact publication, or image rendering.\n\nSession/document references remain stable during ordinary activity and eight-hour sleep. Command and native observation sessions expire after 24 hours without renderer activity; model reads cannot renew them. Chat recovery requires the saved presentation, source, and renderer ownership to remain valid. Native fallback viewers offer **Retry viewer controls** with a fresh session reference, while the next **Ask about selection** after an expired native poll is observed obtains a fresh observation reference. Source replacement, renderer rebinding, closing, or server restart also requires current references. Refresh after a revision conflict instead of replaying a stale control.\n\nUse `structure.get_state` for the canonical scene and `structure.query` for bounded molecular pages; scene/object listings and read-only quality/symmetry queries use their existing tools. `structure.analyze` with an existing result cursor pages a completed result without starting a new analysis. Follow exact returned IDs and revision-bound continuations. Data reads do not compute measurements, alter the view, or render images; use the dedicated tools for new results with their existing authority and computation limits.\n\n## Viewer Control Workflow\n\nUse `structure.control_viewer` only for the active mounted viewer and with the resolved `sessionId`. Residue identifiers use author chain and author residue numbering; include an insertion code when present.\n\nRun mounted-viewer control in the same conversation that contains the viewer. Do not delegate these actions to a subagent, inspect the webview through browser or DevTools automation, or search the source tree for UI state. The app's context and control tools are the supported path. When an opening request also includes control actions, open the viewer first, read `structure.get_context`, and then call `structure.control_viewer` directly for each requested action.\n\n- `focus_residue`, `select_residue_range`, `select_chain`, or `select_residues`: focus one author-numbered residue or select a numeric range, a whole polymer chain, or a noncontiguous residue set. Use the exact author chain, residue number, and insertion code from model context. Pass `objectId` when the target belongs to an added structure rather than the primary object; the resulting live context preserves object, model, unit, and operator provenance.\n- `clear_selection`: clear the current structure selection and inspector focus.\n- `focus_ligand`: focus a ligand by component ID and optional chain.\n- `show_ligand_contacts`: return and display polymer residues within a 2-8 Å cutoff using closest heavy-atom Euclidean distance.\n- `measure_residue_distance`: measure the closest heavy-atom distance between two author-numbered residues.\n- `set_representation` or `set_color`: change the live Mol\\* representation or color mode. Protein-like structures support `cartoon`, `surface`, `sphere`, `ballStick`, and `stick`; small molecules support `ballStick` and `stick`. Unsupported combinations are rejected without changing the live scene.\n- The legacy primary-display names map exactly to canonical scene layers: `ballStick` becomes `ball_and_stick` (atom spheres plus bonds), while `stick` becomes `lines` (thin lines). Canonical `sticks` independently means genuine bond cylinders without atom spheres. Use the canonical names in `structure.apply_scene`, saved scenes, and render layers; legacy aliases are rejected at those boundaries.\n- `set_view_options`: explicitly set a dark or light background and toggle hydrogens, side chains or bases, and animation. The legacy `showMoleculeInspector` option now controls the RCSB **Measurements** section; it does not reopen a separate legacy panel.\n- `set_workspace_options`: show or hide the Contents explorer, sequence strip, Measurements inspector, command console, Workbench, or Render panel, or set atom/residue/chain/object picking. `measurementsVisible` controls the inspector and atom-picking mode; it does not hide rendered measurements or guides. Supply at least one of `explorerVisible`, `sequenceVisible`, `measurementsVisible`, `commandConsoleVisible`, `workbenchVisible`, `renderPanelVisible`, or `selectionGranularity`; `false` is an intentional valid value. The Workbench and Render panel are mutually exclusive; opening Render never starts a render, writes an artifact, or bypasses its existing availability check.\n- `set_toolbar_visibility`: pass `{sessionId, action: \"set_toolbar_visibility\", visible: true}` to show the viewport tool rail, or `visible: false` to hide it. The controls toggle remains available in the full viewer; there is no hover-revealed legacy header toolbar.\n- `set_display_mode`: move the same live viewer between the full `fullscreen` pane and compact `inline` chat preview while preserving its scientific state.\n- `reset_view`: reset the Mol\\* camera.\n\nBefore combining styles, read the current scene and its available capabilities, then choose settings supported by the loaded source. After the acknowledged actions, read `structure.get_context` again to verify the requested representation, coloring, and selection on the same viewer. State exactly what changed and preserve measurement methods and cutoffs. An `applied: false` response, unavailable color mode, or pending render is not a successful visible change.\n\n## Molecular Workspace And Action Parity\n\nThe **Structure** inspector's **Components** section and its **Actions** menu are direct manipulation surfaces, not actions reserved for the user. The menu retains **Action / Show / Hide / Label / Color** operations without requiring five separate small buttons on each row. Call read-only `structure.molecular_actions({ sessionId })` to discover the authenticated viewer's supported actions, representations, and current `sceneRevision`; execute the same typed operations with `structure.molecular_action({ sessionId, expectedRevision, action })`. The current `expectedRevision` is required for every model mutation; missing or stale revisions fail closed, so refresh the same session instead of guessing or opening another viewer. Every enabled graphical scientific operation must have an equivalent agent action; use the richer canonical query, analysis, scene, comparison, rendering, and export tools whenever they express the user's request more precisely.\n\n- Target or edit the selection with `focus` and `select`; use set/add/subtract/intersect semantics and save explicitly requested named selections.\n- Apply scoped representations with `show`, `show_as`, and `hide`. `show` is additive: retain the complete protein cartoon while adding connected residue or ligand `sticks`; reserve `show_as` for an explicit replacement. Canonical representations are `cartoon`, `backbone`, `putty`, `surface`, `gaussian_surface`, `ball_and_stick`, `sticks`, `lines`, `points`, `spheres`, `ellipsoid`, `carbohydrate`, `gaussian_volume`, `label`, `orientation`, `plane`, `polyhedron`, and `interactions`. `sticks` means connected bond cylinders without atom spheres; `ball_and_stick` separately includes visible atom spheres; neither means `lines`. A component `plane` is a colored molecular slice, and component `orientation` uses per-unit ellipsoids; use `structure.manage_guides` for a selection's best-fit plane or principal axes instead.\n- Apply conventional element or other typed coloring with `color`, and create, resize, or hide targeted annotations with `label`. Explicit `mode: \"atom\" | \"residue\" | \"chain\"` selects genuinely distinct labeling levels preserved in both the live viewer and image/MP4 renders.\n- Control object, map, and measurement visibility with `object_visibility`, `volume_visibility`, and `measurement_visibility`. To hide a rendered distance, angle, or dihedral, use `measurement_visibility` with its exact `measurementId` and `visible: false`; hide a saved guide with `structure.manage_guides` using its exact guide ID. Verify the same entry's visibility in the returned scene. Use `remove_object` only for the explicitly named non-primary object and `derive_object` only for an explicitly requested, immutable-source derived model.\n- Density-map rows expose only genuine **Action / Show / Hide** operations: evaluate the exact nonempty current selection in the chosen map at 1σ, correlate with another actually loaded map, or change that map's visibility. Use the Workbench for the existing contour, color, opacity, zoning, and map-style controls; never claim map label or object-color actions that do not exist.\n- Visible **Extract into new structure**, **Derive solvent-free copy**, and **Rename chain in new copy** operations all create a newly named derived object; they never rewrite or rename the original source. The first deletes only the selection complement in that copy, the second removes only water, and the third accepts a safe one- or two-character alphanumeric chain ID. Distance and 4 Å contact actions compare the exact chosen target with the current selection.\n- Use `align` for real whole-object superposition: specify distinct loaded `mobileObjectId` and `referenceObjectId`, keep the primary object fixed, and choose `method: \"structure\" | \"sequence\" | \"atoms\"`. Report the returned alignment method, aligned count, RMSD, and available scores; use `structure.align_structures` instead when the user requests a specific chain, residue set, or paired atoms.\n- Use `workspace` to independently set `explorerVisible`, `sequenceVisible`, `measurementsVisible`, `commandConsoleVisible`, `workbenchVisible`, `renderPanelVisible`, or `selectionGranularity: \"atom\" | \"residue\" | \"chain\" | \"object\"`. Include at least one option; use explicit `false` to hide an element without changing its molecular data or opening another viewer. Never request both mutually exclusive drawers at once, and never treat opening Render as permission to render, export, or choose a destination.\n- Use its `sequenceView` patch for the same ribbon Structure/Mode/Entity/Chain/Layout controls: `objectId`, `mode: \"all\" | \"chain\" | \"everything\"`, `entityId` or `null`, exact `chain` or `null`, and `layout: \"wrapped\" | \"single-line\"`. The chain carries actual `authAsymId`, `labelAsymId`, `labelEntityId`, `modelId`, and `instanceId`; atom/residue query pages supply those source-backed identities (`entityId` maps to `labelEntityId`). Use `showKnownSequence: true` instead of chain/entity/mode to perform the same-object shortcut. UI and command readback share these session-only preferences; they do not change selection, rename `UNK`, or persist model UUIDs in projects. Never guess an alias or retry a stale chain as another assembly copy.\n- Apply reversible `preset`, `save_scene`, `restore_scene`, `undo`, and `redo` actions; adjust `clip`, `camera`, or trajectory `frame` without replacing the active viewer. Presets include `empty`, `automatic`, `atomic_detail`, `polymer_cartoon`, `polymer_and_ligand`, `protein_and_nucleic`, `coarse_surface`, `illustrative`, `molecular_surface`, and `automatic_detail`, plus `protein_ligand`, `binding_site`, `confidence`, and `publication`. For the UI's whole-workspace preset, set `presentation: \"workbench\"` and an unscoped `target: { kind: \"all\" }`; for a bounded component target, use `presentation: \"scoped\"` and its exact selection expression.\n- Run `analyze` or `measure` through the same revisioned action contract, or prefer `structure.analyze` and `structure.measure` for their richer typed results and pagination.\n\nThe [RCSB inspector tool map](../../examples/CAPABILITY_MATRIX.md#rcsb-workspace-capabilities) lists the exact routes for construction, components, View, guides, QA/PAE, symmetry, public motif/density, images, animation, and geometry/model exports. Source construction uses `structure.apply_scene.objectUpdates[].construction`; advanced representation parameters use `layers[].representationOptions`, shared computed-interaction/display parameters use `representationOptions` (or `null` to reset), and viewport effects use `viewSettings`. Color kinds include `carbohydrate`, `illustrative`, and `interaction_type` (for computed interaction representations), plus the strictly enumerated `native` themes and bounded parameters. Do not pass arbitrary Mol\\* parameter objects or invent source-backed quality metrics.\n\nPublic motif/density/annotation tools require explicit public identifiers and do not upload local structures. QA `operation: \"query\"` can return exact PAE residue indices/regions and a `selectionFingerprint`; use those with `operation: \"select\"` rather than treating a PAE index as an author residue number. Public density box requests transmit their box coordinates to PDBe, so never derive private-structure bounds without consent. For a workspace background, call shared `structure.browse_related_data`, retain its fresh `callerId`/`commandId` pair, and pass only returned image tokens to `structure.load_background`; do not call app-only background/annotation range helpers or fabricate paths, URLs, leases, or resource handles.\n\nBackground images have a 32 MiB encoded / 128 MiB decoded RGBA-and-mip / 128-face document-lifetime budget, including failures and export reloads. Respect an explicit close/reopen instruction at exhaustion; do not retry around the limit. Native-file hosts must advertise admitted image-purpose support or the workflow is unavailable. This is separate from public-data admission and ordinary scene rendering.\n\nImage export uses `structure.render_image` with `format: \"png\" | \"jpeg\" | \"webp\"`, optional JPEG/WebP `quality`, `autoCrop`, and `cropPadding`. PNG is the default; JPEG cannot be transparent, and unsupported WebP encoding fails explicitly. Animation uses `structure.render_movie.timeline` for camera spin/rock, molecular spin/unwind, trajectory animation, time, and scene transitions, in addition to the existing ordered steps. Use `structure.export` for selected PDB/mmCIF/BinaryCIF, split-model mmCIF/BinaryCIF ZIPs, or visible GLB/STL/OBJ/USDZ geometry. Preserve exact identity, color, crop, and artifact provenance; geometry errors must not be described as partial success. Browser download and clipboard buttons are host delivery gestures: return the same authorized rendered artifact to the user, without pretending to click a download or obtaining clipboard permission through a model tool.\n\nThe optional command bar understands a bounded molecular dialect, not a Python interpreter. Readable selection examples include `chain A+C`, `resi 19+23+26`, `resn HEM`, `name CA+CB`, `elem O+N`, `polymer.protein`, `organic`, `solvent`, `%catalytic`, `byres (organic around 4)`, and `/primary//A/57/CA`. Safe commands also support `align comparison, primary, structure`, `clip far, 20`, `angle catalytic, chain A, chain B, chain C`, and `dihedral backbone, chain A, chain B, chain C, chain D`; angle and dihedral commands accept only exact distinct selection targets, never raw Cartesian coordinates. In the explicitly selected molecular dialect, `model primary` means object `primary`; the existing native dialect keeps `model` as a biological model ID. Use typed tools rather than injecting commands, scripts, shell, filesystem access, arbitrary Python, or JavaScript.\n\nFor residue solvent exposure, call `structure.analyze` with `kind: \"sasa\"`, the **complete molecular occluder context as the first selection**, an optional residue subset as the second selection, and `options: { sasaAggregation: \"residue\" }`. For a protein-chain request, intersect the chain with protein atoms so crystallographic waters never appear as protein residues while all surrounding atoms remain occluders. For absolute accessibility thresholds use `minAreaSquareAngstrom` and report each residue's `areaSquareAngstrom` in **Ų**; for relative thresholds use `minRelativeExposurePercent` with `relativeSasaReference: \"tien_2013_maximum\"` and report `relativeExposurePercent` as a **percentage**. Tien normalization requires the standard **1.4 Å solvent probe**; a nonstandard probe supports absolute Ų only and cannot produce a valid Tien percentage. Thresholds mean strictly greater than their value. Tien observed maxima are residue-specific; unknown residues have null relative/reference values, and percentages can exceed 100. Never calculate one isolated residue at a time, present square ångströms as ångströms, or conflate a 50 Ų threshold with 50% exposure. Preserve the probe radius, samples, author numbering/insertion code, selection scope, normalization reference, and any truncation.\n\nLoad the bundled [molecular workspace action guide](../../examples/MOLECULAR_WORKSPACE.md) when the user asks for the complete object-menu mapping, supported command grammar, typed action examples, or absolute-versus-relative residue exposure details.\n\n## Canonical Scene And Analysis Workflow\n\nPrefer the canonical tools for precise or composable work. `SelectionExpr v1` and `SceneState v2` are shared by the UI, model tools, live context, render targets, scene recipes, and exports.\n\n1. Call `structure.get_state` before a multi-step mutation and use its `sceneRevision`, valid object IDs, capability manifest, pending/error state, selection/focus, maps, trajectory, and named scenes.\n2. Pass `expectedRevision` on mutations. Use the returned `appliedRevision` for the next mutation. On a revision conflict, re-read state; do not blindly retry stale coordinates or object IDs.\n3. Use `structure.query` for exact revision-bound atom/residue/chain/object pages. Pass `expression` and explicitly choose `level` (default `\"atom\"`); for example, `{sessionId, expression: {kind: \"residue_range\", objectId: \"primary\", chain: \"A\", start: 330, end: 344}, level: \"residue\"}` using actual object and chain IDs from state. Exact atoms use `{kind: \"atom_ids\", atomIds: [...]}` with IDs returned by query. Prefer ranges for contiguous residues, or a chain-scoped `allOf` with `{kind: \"property\", property: \"residueNumber\", operator: \"in\", value: [...]}` for up to 100 residue numbers. Reuse `{kind: \"current\", target: \"selection\"}` or `{kind: \"named\", name: \"site\"}` instead of enumerating atoms again. Boolean `allOf`/`anyOf` allow at most 32 children; complete expressions allow 12 levels and 128 nodes. Follow returned cursors with the same expression and level rather than treating the bounded live-context summary as complete.\n4. Use `structure.set_selection` with `set`, `add`, `subtract`, or `intersect`, and optionally save the exact result as a named selection. Pass `focus: true` with the exact selected expression and `mode: \"set\"` to match the viewer's **Focus selection** control without widening the selected atoms. This records molecular focus; the workspace `focus` action only frames the camera. Expressions support object/model/entity/chain/residue/atom, exact `atom_ids` snapshots from query results, component class, property comparisons, boolean `allOf`/`anyOf`/`not`, spatial `within`, bounded `bondedTo`, current selection/focus, and named selections.\n5. Use `structure.apply_scene` to atomically update camera, active object, object transform/visibility, ordered layers, labels/annotations, maps, lighting/background, or a reusable storyboard. Use `dryRun: true` when targets are uncertain; failures roll back both Mol\\* and canonical state.\n6. Use `structure.measure` for distance, angle, or dihedral overlays. Distances resolve to one stable closest atom pair, while multi-atom angle or dihedral targets resolve to persisted centroids; the model-visible result includes atom identity/source cardinality, the measured scalar, units, and provenance, while exact Cartesian points remain app-internal for rendering. Dynamic `current` and named targets are snapshotted at measurement time so later selection changes cannot retarget the result. Use `structure.analyze` for contacts, clashes, valence- and geometry-screened hydrogen bonds, RMSD, centroid/principal axes/best-fit plane, SASA, buried area, density fit, map correlation, or measurement-over-trajectory. Buried-area targets must be atom-disjoint interaction partners; if an overlap is rejected, use the returned counts, coverage fractions, and bounded atom-ID examples to refine one or both selections. Overlap follows stable object-, symmetry-instance-, and atom-aware identity, not coordinate coincidence, so aligned objects and genuine symmetry mates remain distinct. Hydrogen-bond roles do not depend on selection order; preserve the returned donor/acceptor identities, chosen explicit donor-H identity, alternate locations, occupancies, angles, confidence, assumption, units, cutoffs, truncation/cursor, and provenance. Endpoints and every chosen hydrogen/heavy-atom geometry participant require positive occupancy and mutually compatible alternate locations; covalently adjacent sites and unresolved directional geometry are deliberately excluded. RMSD requires at least three non-collinear atom pairs. Pass two `atom_ids` selections in the intended pair order for explicit correspondence; otherwise the viewer matches unique biochemical identities and reports unmatched or ambiguous atoms. Otherwise unique cross-object candidates must have the same alternate-location label; different isolated conformers are reported unmatched. Repeated model, symmetry, or alternate-conformer copies are deliberately ambiguous because their labels are source-local; use explicit ordered IDs to establish the intended correspondence. If the user asks to stop an active analysis, immediately call `structure.control_viewer` with `action: \"cancel_analysis\"`; cancellation is out of band and does not wait behind the running analysis.\n7. Use `structure.save_scene`, `structure.list_scenes`, `structure.load_scene`, and `structure.delete_scene` for complete live scenes. Named scenes restore camera, layers, exact selection/focus, object transforms/visibility, annotations, measurements, maps, trajectory state, storyboard, and background. Use `structure.undo`/`redo` for safe exploration.\n8. Use `structure.export` for SceneState JSON, selected PDB/mmCIF/BinaryCIF coordinates, split-model mmCIF/BinaryCIF ZIPs, visible GLB/STL/OBJ/USDZ geometry, or analysis CSV. When the live viewer advertises source-relative workspace publication, pass `destination: { \"kind\": \"workspace\", \"base\": \"opened-source\", \"relativePath\": \"...\", \"collisionPolicy\": \"exact\" | \"versioned\" }` and the same requested relative path as `outputPath`; this is create-new only and may traverse to another existing directory only inside the bound publication root. An active root grants workspace reads plus publication; a captured publication-only root does not grant related-data or project-manifest reads. Use `versioned` when the next deterministic collision-free name is acceptable, or `exact` when any existing artifact or sidecar must stop the operation. Never fabricate an app-only directory or plan token, an absolute destination, or this capability when it is absent. `selection-pdb` emits new sequential 1-based atom serials and preserves only identities representable by the legacy fixed-width fields. Prefer `selection-mmcif` or `selection-bcif` when source atom-site IDs must survive, atom counts can exceed 99,999, author residue numbers fall outside -999 through 9,999, identifiers need more than PDB's fixed-width fields, the selection spans multiple loaded objects, source models, or symmetry instances, or the user asks for maximally preserving coordinate identity. If `selection-pdb` reports that an identity cannot be represented, retry with `selection-mmcif` and a `.cif` or `.mmcif` output path; never truncate or renumber around the error. The command result and atomic artifact provenance report the exact identifier policy and generated, namespaced, or remapped fallback counts; `identityPreserving` is true only when no fallback was needed. Coordinate exports deliberately omit explicit `CONECT`/`struct_conn` bond records and do not preserve bond order, so use the original source or an explicit topology file when connectivity fidelity matters. Analysis CSV results include a model-visible `spreadsheetSafety` contract for UTF-8 encoding, CRLF framing, full quoting, formula neutralization, and exact reversal. Use `structure.derive_object` only for explicitly requested, non-destructive bounded derived-coordinate operations; never imply the source changed.\n\nThe visible **Structure** inspector, **Components** Actions menu, command bar, and Workbench call the same operations. For manual instructions, direct the user to the appropriate menu group or **Select · Analyze · Compare · Related data · Style · Animate · Export** task, not a hidden Mol\\* expert panel. **Related data** is a source-relative browser exposed to both app and model through `structure.browse_related_data`; use it only when the viewer advertises the capability and retain opaque tokens with their caller/command pair. The app-only token loader still requires user-facing confirmation before loading a suggested topology/trajectory pair. Model requests use explicit `structure.load_data` paths for molecular companions or `structure.load_background` with returned image tokens for backgrounds; neither grants arbitrary workspace access.\n\nThe Export task's **Save Project** persists a complete Project Manifest v1 plus provenance through the visible exact/versioned destination picker. Its optional strict `presentation` version 1 saves only the seven bounded workspace controls: explorer, sequence, measurements, command console, Workbench, Render panel, and picking granularity. **Open Project** is always an explicit user action on a source-associated relative label: the server verifies the source, every dependency digest and identity, and the graph before restore; presentation is applied only after the authenticated scene commits and its viewer becomes ready. If a restore returns `presentationPending: true` with `presentationRestored: false`, report that display preferences are still pending instead of claiming they were restored. Older manifests without presentation remain compatible. Drawer visibility remains mutually exclusive, measurement mode requires atom picking, and presentation never stores command history, session credentials, tokens, filesystem paths, or Cartesian coordinates. Never fabricate project tokens, ask for an absolute manifest path, silently apply an offered project, substitute a same-basename dependency, or claim partial restoration; report structured repair items or an explicit presentation-restore warning when available.\n\n## Structure Object And Alignment Workflow\n\nUse the dedicated object tools when the user wants to compare, superpose, move, or choreograph more than one structure. These tools operate on the live mounted viewer and are useful independently of image or movie rendering.\n\n- `structure.add_structure`: load another supported local structure under a stable `objectId`, optional initial representation, and optional uniform color. If representation is omitted, macromolecular files use cartoon and MOL/SDF ligands use sticks.\n- `structure.list_structures`: inspect the current object IDs, visibility, coordinate-frame counts, source names, and transforms before targeting them.\n- `structure.align_structures`: align a mobile target to a reference target with `structure` (protein Cα TM-align, one Cα coordinate per residue), `sequence` (sequence-guided superposition), or `atoms` (paired-atom superposition). Use `sequence` or `atoms` for nucleic acids, coarse structures, and other polymers. Both targets must include `objectId`; narrow them to matching chains or residue sets when appropriate. Report RMSD, aligned count, and any returned TM or sequence score.\n- `structure.transform_object`: independently translate, rotate, scale, or apply a 4×4 matrix. Relative transforms compose with prior alignment; absolute transforms replace the object's current transform.\n- `structure.set_object_visibility`: show or hide an object without removing it.\n- `structure.remove_structure`: remove a non-primary object from the mounted viewer.\n\nUsers can perform the same load, targeted alignment, diagnostics, object visibility, per-object styling, undo, and named-scene workflows from **Compare** and **Style** without chat.\n\n## Density And Trajectory Workflow\n\n- In a trusted workspace viewer, the visible **Related data** tab can classify and rank supported files near the opened source, navigate one bounded physical directory at a time, and suggest topology/coordinate pairs. Its labels are workspace-relative and its opaque tokens are operation-bound, not reusable paths. The model can use `structure.browse_related_data` and retain its caller/command pair for `structure.load_background`; do not fabricate tokens or ask the user to transcribe them. Pair suggestions are advisory and load only after explicit confirmation.\n- Use `structure.load_data` with `kind: \"volume\"` for CCP4/MRC/MAP, DSN6, CUBE, DX, or DensityServer CIF. Maps are named objects with contour type/level, isosurface/wireframe/slice/direct-volume style, color, opacity, visibility, and optional zoning around any SelectionExpr. Use `density_fit` for atom-sampled support and `map_correlation` for compatible grids; report the exact method rather than calling either a refinement score.\n- Use `structure.load_data` with `kind: \"trajectory\"`, a topology path, and a coordinate path. Supported topology families are PDB/mmCIF/GRO/XYZ/PSF/PRMTOP/TOP; coordinate families are XTC/DCD/TRR/NetCDF/LAMMPS trajectory. Then use `structure.set_trajectory_state` for frame, play/pause, loop, speed, stride, backbone/current-selection alignment, and periodic-image handling. Current frame/playback is in live context.\n- Use `trajectory_series` analysis for distance/angle/dihedral values across bounded sampled frames. The starting frame is restored after analysis; preserve sampling stride and periodic/alignment provenance.\n\nUse the exact object IDs returned by the tools or a fresh context read. List objects first when IDs are uncertain. Do not claim that two structures are aligned merely because they are both visible; call the alignment tool and use its returned metrics.\n\n## Image And Movie Rendering\n\nUse `structure.render_image` and `structure.render_movie` to execute publication or presentation renders in the active mounted viewer. Return the rendered artifact rather than a script or manual rendering instructions. Both tools use a declarative scene contract and save the result plus a `.render.json` provenance sidecar inside the bound publication root.\n\nWhen source-relative publication is available, use the same explicit `destination` object and matching requested `outputPath` described for `structure.export`. Do not request overwrite, fabricate picker tokens, expose an absolute path, or silently fall back from a rejected source-relative destination.\n\n- Pass the live `viewerSessionId` as `sessionId`.\n- Call `structure.validate_render` before an expensive, reusable, or target-rich render. It does not encode or save; it resolves live SelectionExpr targets, object references, trajectory ranges, and returns duration/frame/pixel estimates at the current scene revision.\n- Read a live endpoint with `structure.get_state({ sessionId, renderEndpoint: {} })`, or a named saved endpoint with `renderEndpoint: { sceneName }`, without loading or mutating that scene. Use the complete `state.renderEndpoint.renderScene` for the render's `scene` or a movie scene keyframe, including its opaque scientific references; never reconstruct private arrays or guess fingerprints. `sourceRevision` identifies the endpoint, while `state.sceneRevision` is the current live revision for mutations. Over-64-KiB or render-limit endpoints fail rather than truncate. Omit `renderEndpoint` for the ordinary state summary.\n- Omit `scene.layers` to render the current visible scene. Explicit layers accept the same 18 canonical representations listed above, including carbohydrate, Gaussian volume, labels, orientations, molecular slices, polyhedra, and computed interactions, with their typed appearance options.\n- Preserve explicit `scene.density` from the endpoint for every image or movie keyframe: at most 32 exact source/channel proofs and appearances. Omission snapshots current admitted maps, `[]` hides them, and scene transitions switch density at phase 0.5. Rendering never downloads missing maps. A `complete-source` digest covers admitted bytes, including bounded public BCIF data; a `native-window` digest covers displayed DX bytes, not the whole original map. Never fabricate proof, silently bind another same-named channel, or describe unsupported geometry as partial success.\n- Prefer target kind `expression` with the exact `SelectionExpr v1` used in the live scene. Compatibility targets include `current_selection`, `current_focus`, `all`, `chain`, `ligand`, `residue`, `residue_range`, `residues`, and `ligand_contacts`; explicit legacy targets can include `objectId` where their schema allows it.\n- Preserve visible distance, angle, and dihedral overlays in images and MP4 movies. Legacy distances retain `{ from, to }`; an angle adds `kind: \"angle\"` and one ordered `via` target, while a dihedral uses `kind: \"dihedral\"` and exactly two ordered `via` targets. Distances use Å and angular measurements use degrees. Stable atom IDs preserve motion across transforms and trajectory frames; exact Cartesian endpoints remain app-internal and must never be reconstructed or exposed in model context.\n- Image output is PNG (default), JPEG, or host-supported WebP. JPEG rejects transparency; PNG/WebP may retain it. JPEG/WebP accept `quality` from 0 to 1; `autoCrop` and `cropPadding` retain exact source/crop/output dimensions in provenance. Dimensions, background, lighting, antialiasing, labels, annotations, measurements, camera, and clipping use the shared scene. For a molecular callout, set `kind: \"selection\"` and provide an exact render target; the annotation follows that target instead of using its fallback screen position. Live stereo views export monoscopically.\n- Movie output is H.264 MP4. Build an ordered timeline from `rotate`, `camera_spin`, `rock`, `zoom`, `focus`, `camera`, `transform`, `align`, `visibility`, `trajectory`, `trajectory_animation`, `spin`, `unwind`, `scene`, `time`, and `hold` steps. Unwind requires an actual loaded assembly. Trajectory animation has bounded fixed/computed/FPS-limited sequential timing and loop/once/palindrome modes. Quantization maps to bounded bitrate, not guaranteed constant-QP encoding. Steps are evaluated sequentially: later targets and alignments use transforms, visibility, and frames established by earlier steps.\n- MP4s are encoded and persisted through a bounded streaming path with a server-returned disk quota (up to 1 GiB by default) that is separate from the 192 KiB raw-chunk request limit. The app admits the destination before encoding, streams fragmented WebCodecs output while encoding with incremental integrity checks and backpressure, and atomically publishes the destination-adjacent staged movie with provenance; never substitute a full-buffer upload or bypass this path.\n- Use `transform` steps for rigid molecular translation, rotation, or scaling; `trajectory` steps for coordinate motion; and multiple eased `camera` or `transform` steps for paths.\n- Use `visibility` steps to smoothly bring named objects into or out of view. Use smooth `scene` transitions to crossfade representations, arbitrary target colors, backgrounds, and annotations; give an annotation a stable `id` to animate its position and style between scenes. Selection annotations are reprojected on every encoded frame, so they track camera paths, object transforms/alignment, and trajectory coordinates.\n- Use `align` inside a movie when superposition is part of the choreography. Use `structure.align_structures` instead when the user wants the live viewer aligned without rendering a movie.\n- Keep requests within the tool-reported limits. If a request fails validation, reduce resolution, duration, or FPS instead of attempting an external renderer.\n- Leave `waitForCompletion` at its default `true` for ordinary requests. For a long or explicitly asynchronous workflow, set it to `false`, poll `structure.get_render_status` with the returned job ID, and use `structure.cancel_render` if the user asks to stop.\n\nAfter success, tell the user what was rendered and give the returned workspace artifact and provenance paths. The live viewer context also records the latest render. Do not claim completion while status is queued, running, or saving.\n\n## Supported Artifacts\n\n- `.pdb` for PDB text coordinates.\n- `.cif` and `.mmcif` for CIF/mmCIF-style coordinate text.\n- `.pdb.gz`/`.pdb.bgz`/`.pdb.bgzf`, `.cif.gz`/`.cif.bgz`/`.cif.bgzf`, and `.mmcif.gz`/`.mmcif.bgz`/`.mmcif.bgzf` for bounded gzip/BGZF coordinate decoding; ZIP and unrelated archive formats are unsupported.\n- `.mol` for MDL MOL small-molecule records.\n- `.sdf` for MDL SD files supported by Mol\\*.\n- `.mol2` for Tripos MOL2 records.\n- `.pqr` and `.pdbqt` for charged/radius or docking-coordinate PDB variants.\n- `.gro` for GROMACS coordinates and `.xyz` for XYZ coordinates.\n- Related data after opening: CCP4/MRC/MAP, DSN6, CUBE, DX, DensityServer CIF maps; XTC/DCD/TRR/NetCDF/LAMMPS trajectories with an explicit compatible topology.\n\n## Boundaries\n\n- Do not read, inline, truncate, or summarize file contents merely to open the viewer.\n- Do not pass a workspace path, `file://` URI, or fabricated `codex-resource://` URI to `structure.open`.\n- When the MCP host exposes active local roots, both opening tools confine relative and absolute paths to those roots. When roots are unavailable, they require an exact absolute local path.\n- Both opening tools accept only supported files.\n- Never execute or propose arbitrary PML, Python, or JavaScript inside the viewer. Use the typed selection, scene, analysis, derived-object, and render contracts.\n- Do not serialize unbounded atoms/results into chat. Use live summaries plus `structure.query` or analysis cursors, and say when results are partial.\n- Do not infer the user's current selection from the source file after the app is open. Use the viewer context because the user may have rotated the model, focused a ligand, changed representations, or selected residues interactively.\n- Do not call the automatically suggested ligand the biologically relevant ligand without evidence. It is a convenience ranking that excludes solvent and common crystallization additives; the user can choose another ligand.\n- Report ligand contacts and residue measurements as coordinate-derived closest-heavy-atom distances, not inferred bonds or energetic interactions.\n- Prefer author chain, residue number, and insertion code in user-facing residue references. Keep label numbering available for provenance.\n- Biological assemblies can contain multiple transformed copies with the same author chain and residue numbering. Preserve the `instanceId` and instance/operator label from live context, and pass that `instanceId` to selection, measurement, alignment, or render tools when targeting one copy. If a tool returns instance candidates, ask or retry with one of those exact IDs rather than choosing silently.\n\n## Follow-Up Questions\n\nWhen answering from the mounted viewer context, prioritize the literal current state before adding biological interpretation. Useful context includes the active file, coordinate format, experiment and resolution metadata, model count, chain inventory, author and label residue coordinates, molecular components, current representation, color mode, selected ligand, distance cutoff, contact list, selected residues, measurements, and the exact focus or selection state.\n\n### User-facing interaction target\n\nSelection and focus are independent backend states, but they are usually one user-facing interaction target. Follow the structured `interaction` relation and its response guidance:\n\n- For `focus-only`, treat the focused residue, ligand, or molecule as the user's current selection. Never say that the user \"technically\" has no selection and do not expose that backend selection is empty.\n- For `selection-only`, answer about the selection without mentioning that focus is empty.\n- For `overlapping`, answer once about the selected region. The focus may provide useful specificity, but do not explain the focus/selection distinction.\n- Only for `distinct`, explain that two different regions are active. Identify the selected region and the focused region, then answer separately for each and label which region each statement concerns.\n- For `none`, say that no region is active only when the user's question depends on a current target.\n\nIf older viewer context lacks `interaction`, apply the same fallback: use selection when populated, otherwise use focus; mention both only when both are populated and non-overlapping.\n"
}