Update to Slide Viewer

{
  "name": "slide-viewer",
  "description": "Open and control whole-slide microscopy, supported DICOM/OME-Zarr and spatial AnnData sources; inspect live state, registered molecular layers, single-user projects and bounded source-backed research workflows.",
  "included_files": [],
  "skill_md_contents": "---\nname: slide-viewer\ndescription: Open and control whole-slide microscopy, supported DICOM/OME-Zarr and spatial AnnData sources; inspect live state, registered molecular layers, single-user projects and bounded source-backed research workflows.\n---\n\n# Slide Viewer\n\nUse this skill when a user wants to inspect a whole-slide microscopy or pathology image, explore spatial transcriptomics and gene expression, work with an existing tissue annotation or segmentation layer, or control an active Slide Viewer session inside Codex.\n\n## Opening\n\n1. Identify the user's intended `.svs`, `.tif`, `.tiff`, `.h5ad`, or compatible local DICOM WSI (`.dcm`/`.dicom`) file in the active local workspace.\n2. Prefer an explicitly named file; if none is named, look only for supported local workspace files and ask a brief clarification when more than one is plausible.\n3. Call `slide.open_from_chat` with the exact authorized workspace path. Omit `presentation` for the default `\"full\"` viewer; pass `presentation: \"inline\"` only when the user or onboarding flow explicitly requests minimal controls. Hidden controls remain available by moving the pointer to the viewer's top edge or focusing that edge with the keyboard; **Show toolbar** restores their pinned state.\n4. Retain the returned `viewerSessionId`. The open result authorizes the source but has `viewerReady: false` / `viewerState: \"awaiting-viewer\"`; it does not prove a mounted frame.\n5. Open the existing card, then read `slide.get_viewer_state` and inspect `slide.get_capabilities`. `status: \"active\"` confirms mounted state, not a ready frame. If the mounted inline viewer is offscreen, request `set_display_mode` with `displayMode: \"fullscreen\"` before waiting for a frame. Use `slide.wait_for_render` with the resulting state revision before saying that the viewer is ready. A missing snapshot is awaiting-viewer; a superseded revision requires a fresh state query, not a success claim. **Open in side pane** moves the same live viewer when the host supports it.\n\nFor an explicitly named OME-Zarr directory or public HTTPS dataset root, use the advertised `slide.open_ome_zarr` schema. For a DICOM pyramid, pass the actual authorized instance list to `slide.open_dicom_series`; an arbitrary directory or one instance does not establish a series. Do not invent credentials, companion files, channel identities or specimen associations. Unknown/unsupported hosts must not be made to work by fabricating permission metadata.\n\nDo not repeat or expose the local file path after the viewer opens. Do not download a public dataset, create an annotation, or assume a particular example file exists unless the user explicitly requests that work; selecting a first-run public-example prompt is that request. Never install a package or fabricate a specimen to satisfy an example.\n\nDo not call the app-only `slide.open` tool from chat. Codex reserves `slide.open` for native file-tree previews and supplies its opaque file resource.\n\n## Read Context On Demand\n\nOpening and interacting with the viewer do not automatically add slide context or images to chat. Use the session ID from the opening result or an explicit **Ask about selection** or **Ask about this view** request. Otherwise call `slide.list_viewers`; it recalls previously referenced sessions successfully read in trusted conversation scope, not every open viewer. A manually opened viewer first needs one of these explicit references. If discovery is unavailable, use an existing explicit session reference or ask the user to identify the viewer through its ask action. Resolve multiple matches instead of selecting the most recently opened viewer.\n\nNative file previews retain **Ask about this view** and **Ask about selection** to establish a chat reference; chat-opened viewers use their existing session. **Ask about this view** identifies the current viewport and display at its UI revision without requiring a selection. Read that exact session and revision before interpreting the view; refresh after a revision conflict. These actions send a reference for a question, while **Return to chat** changes placement. Use `slide.capture_image` explicitly when the question requires current pixels, or an export tool when the user requests a saved artifact.\n\nStart with `slide.list_documents`, choose an actual `documentId`, then use `slide.read_document` to read it or `slide.search_document` with a literal `query` to locate relevant text. Read the matching range in context. Pass the returned opaque document `revision` unchanged as `expectedRevision`; use the numeric viewer revision only for context, rendering, and commands. These general tools support questions beyond the predefined gene/layer/entity queries; use those domain tools as optional typed shortcuts.\n\nSearch is case-insensitive by default; set `caseSensitive: true` when needed. Match snippets are previews. Continue with returned `nextOffset` and use the returned `revision` as `expectedRevision` until `eof` when more matches are needed, and read exact UTF-16 ranges from the same document revision before interpreting them.\n\nUse `slide.get_context` when a compact orientation is useful, with only the needed `sections`: `overview`, `selection`, `viewport`, `display`, `annotations`, `results`, `inventory`, `status`, `capabilities`, `spatial`, or `microscopy`. The default is overview, selection, and viewport. Inspect freshness, readiness, source/revision, requested/effective scope, unavailable sections, and truncation. `last_observed` cannot establish the current view; unavailable selection does not mean empty selection. `expectedRevision` is the numeric UI revision, distinct from the source-content revision. Preserve coordinate frames, calibration, image registration, matrix identity, selected physical observations, and C/Z/T/plane provenance. Context covers loaded state; requesting source scope does not turn loaded subsets into complete-assay data.\n\nFor complete data, call `slide.list_documents` and read the exact returned `documentId` with `slide.read_document`. Use `offset`/`length` for a range or `full: true` to read as far as one response permits. 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` and the same `expectedRevision` until `eof`. `continuationReason: \"transport_limit\"` means more data remains; total document access has no transport ceiling. Reads fail on source/revision changes. Documents contain complete loaded selections, layers, annotations, coordinate frames, microscopy, spatial and analysis state, existing results, and available gene-expression vectors. Gene documents preserve matrix, physical column, and physical observation identities without changing the displayed gene. Complete loaded data is not complete-assay coverage; preserve the descriptor's source, revision, and completeness. Existing source-admission, parser, and computation limits still apply.\n\nUse `slide.query_viewer` or indexed source queries for precise pages and source-backed records when the current capabilities allow them. Native previews use the same loaded-document and pure UI-query providers through their existing plugin command session. References survive ordinary backgrounding and eight-hour sleep, but expire after 24 hours without accepted renderer activity; model reads do not renew them. After expiry, use existing saved-access recovery or a fresh authorized open. Refresh after source changes or a new renderer, and continue only with matching source, selection, matrix, and scene identities. Read access does not create a source-file grant, export permission, or new analysis authority. Document and metadata reads never capture images.\n\nWhen pixels are needed, call `slide.capture_image` with `sessionId`, optional numeric `expectedRevision`, and `target: \"viewport\"` or `target: \"region\"`. For a region, supply `bounds: {x, y, width, height}` in base-image pixels; omit bounds for the current viewport. This explicitly captures a fresh image without requiring a prior manual capture or changing the camera/selection. Viewport images include displayed overlays; region images contain current display-rendered source pixels. Preserve the returned source, revision, timestamp, bounds, dimensions, and pixel semantics, and do not treat a bounded display image as raw quantitative samples. Native images remain bound to their exact `viewBinding` instance/source revision. The legacy `slide.get_selected_region_image` reads an existing user capture with `freshness: \"existing_user_capture\"`; do not describe it as a fresh screenshot.\n\n## Control\n\nUse `slide.control_viewer` only for an active mounted viewer and pass its current `viewerSessionId` as `sessionId`.\n\n- `set_toolbar_visibility` accepts `{sessionId, action: \"set_toolbar_visibility\", visible: true}` to show and pin the toolbar, or `visible: false` to hide it; this changes the same state as **Show toolbar** and **Hide toolbar**. A hidden toolbar temporarily reappears on top-edge pointer hover or keyboard focus. Confirm the change only from the action's `applied: true` acknowledgement; do not infer it from image-bearing viewer context or request a new tissue screenshot.\n- `set_display_mode` moves the same viewer between `fullscreen` and `inline`; it controls the host layout, not toolbar visibility or opening `presentation`.\n- `fit_view` resets the viewport to the complete slide.\n- `focus_region`, `select_region`, and `clear_regions` operate in base-level slide pixel coordinates.\n- `set_spatial_gene` and `set_spatial_clusters` update spatial transcriptomics visualization.\n- `set_layer_visibility` controls `image`, `spatial`, `segmentation`, or a current GeoJSON layer ID.\n- `set_segmentation_class_visibility` controls one current segmentation class by ID or exact name.\n\nThe same typed control surface exposes viewport, layer styles/removal, theme/search, workspace sections and panels, spatial views/panels/selections, annotation history, source/library/registration choices, microscopy C/Z/T/channel/projection settings, projects and source-authorized exports. Use `set_workspace_section` for the Layers/Sources/Project/Inspect workspace. Consult current capabilities and the advertised schema rather than inventing IDs or assuming every source supports every operation. The agent may use additional queries/workflows beyond the UI.\n\n`set_command_search` opens, filters or dismisses the Commands palette with `visible` and/or `query`; its current transient state is `presentation.commandSearch`. It is separate from gene/layer `set_search_query`. Search results invoke existing typed actions with their current capability and export-scope checks; finding a command is not executing it. For per-channel opacity, first read the current microscopy selection, preserve the other channels/planes, and use `set_microscopy_selection` with the intended channel's `opacity` in `0..1` (omitted means `1`). Opacity, color, window and gamma affect the display, not raw quantitative samples. An all-disabled, zero-opacity or black-tinted composite cannot grant source-image capture consent.\n\nOmit the optional `commandId` for ordinary calls. For idempotent retries, supply a UUID and reuse it only with an unchanged payload. Use `expectedRevision` for the current UI state revision; it is not the command sequence or source-content revision. On conflicts, re-read state before proposing or applying a new action.\n\nFor the complete UI observation selection, use `slide.query_viewer` with `query: \"selected_observations\"`; do not treat the snapshot's capped ID list as the entire selection. For microscopy scene discovery, query `microscopy_scenes` and use the returned scene ID and exact `defaultSelection` rather than guessing channel settings. Both queries start at `offset: 0` and continue with the returned `nextCursor`, exact `nextOffset`, and unchanged limit/filter; restart after a stale continuation instead of mixing sources, matrices, selections, or catalogues. Keep the returned source identity with the result: the microscopy image and selected analysis assay may be different files, and cursors never renew source permissions or grant image consent.\n\nReport an applied change only when the tool returns `applied: true`; report a visible change only when its corresponding render state is ready/synced at that revision. Queued, timed-out, unsupported, failed or superseded receipts are not success. Read `slide.get_context` before describing current visible bounds, selections, genes, clusters, annotation layers, segmentation classes, or viewport changes; use `slide.query_viewer` for exact catalog/entity IDs and details.\n\nInterpret tissue morphology from an actual `slide.capture_image` result for the relevant current viewport or region. Programmatic `select_region` changes coordinates but does not itself capture an image; call the image tool explicitly when pixels are needed. Do not reuse an old screenshot for a later source, scene, plane, or display. A pending or failed render/capture is not current image evidence. If the image is unavailable or contains no visible tissue, report verified coordinates and metadata and explain that tissue morphology cannot be inspected from that result. Reading a rendered image does not authorize raw-pixel exports.\n\nWhen an annotation or segmentation overlay has not been loaded, use the supported `import_layer` action with the user's authorized workspace path, or the existing attachment flow. Importing an image does not establish registration with an existing spatial dataset. Do not align unrelated images or all observations from multiple libraries without a verified association. Describe an overlay as visible only after a current viewer read confirms that its layer is present.\n\n## Acquiring public research examples\n\nOnly an explicit request for one of the first-run examples authorizes downloading its named public artifact into the active Codex workspace. An explicit request to open the public CMU-1 example also authorizes acquiring that exact specimen when a verified copy is not already present. Use only the following HTTPS sources and exact integrity pins:\n\n- Full OpenSlide CMU-1 brightfield pathology slide (CC0-1.0): `https://openslide.cs.cmu.edu/download/openslide-testdata/Aperio/CMU-1-JP2K-33005.svs`; save as `CMU-1-JP2K-33005.svs`; exact size `132565343` bytes (132.6 MB); SHA-256 `9a1923cd9bcb260ba4d99d64f8d6e32550648c332ba48817f920662f3a513420`. This is a genuine JPEG 2000 whole-slide pyramid, not the small exported-region fixture; [OpenSlide's metadata index](https://openslide.cs.cmu.edu/download/openslide-testdata/index.json) publishes its size, checksum, and license.\n- Squidpy/10x mouse-brain H&E crop: `https://exampledata.scverse.org/squidpy/visium_hne_adata_crop.h5ad`; save as `squidpy-mouse-brain-hne.h5ad`; exact size `94259482` bytes; SHA-256 `9c9b277bde9f34a022df7f3e35b35ce7ecc80f006d6640b0786f4ace6f6eb5dd`. It contains 684 Visium spots, 18,078 genes and its own registered 600×600 RGB H&E image. Attribute Giovanni Palla (2021), [Brain Coronal HnE Adata Crop, Figshare v1](https://doi.org/10.6084/m9.figshare.13604177.v1), CC BY 4.0, and the original [10x Genomics mouse-brain coronal dataset](https://www.10xgenomics.com/datasets/mouse-brain-section-coronal-1-standard-1-1-0). The matching record contains Figshare file 26098382; do not borrow the fluorescence record's attribution or infer a dataset license from software.\n- Squidpy/10x Genomics adult mouse-brain coronal fluorescence crop: `https://ndownloader.figshare.com/files/30639279`; save as `squidpy-mouse-brain-coronal.h5ad`; exact size `27856369` bytes; SHA-256 `c4caaa4b8708a46b0d4b4ae7390256034e78e02280da3ed16de1ca3a198cddf8`. It contains 704 spots, 16,562 genes, and its own 600-by-600-pixel fluorescence tissue preview.\n\nResolve the active authorized workspace first and write only to a non-symlinked `pathology-slide-viewer-examples` directory inside that workspace. Reuse an existing example only after both its exact byte count and SHA-256 match the pin; never overwrite a preexisting file that fails verification. Download only the pinned source, reject responses larger than its declared exact byte count, verify the final exact byte count and SHA-256, and publish the verified file without replacing an existing destination. For the fluorescence source only, allow one HTTPS redirect to the exact origin and path `https://s3-eu-west-1.amazonaws.com/pfigshare-u-files/30639279/squidpyvisium.h5ad`; preserve its temporary signing query only for that request, omit credentials, and never print or persist the signed URL. Reject all other redirects, including redirects from the direct H&E mirror and CMU-1 source. Do not fetch arbitrary URLs, write outside the active workspace, install packages, bundle the mouse-brain dataset, or silently substitute synthetic or unrelated data. Attribute the mouse-brain crop to Luke Zappia, Squidpy, and 10x Genomics; its [Figshare dataset record](https://figshare.com/articles/dataset/squidpy-visium_h5ad/16566057) explicitly assigns CC BY 4.0 to the dataset, independently of software licenses. If the host is offline, the workspace is unavailable, a source changes, or an integrity check fails, stop and explain the specific problem without claiming that a viewer opened. After verification, call `slide.open_from_chat` exactly once with the authorized workspace path and retain the returned `viewerSessionId`. For either mouse-brain example, use that file's own tissue and coordinate/scale metadata, start with tissue visible and expression hidden, and verify its actual image layer and spot/gene counts. Compare `Slc17a7` and `Gad1` only when their exact names are present. Identify H&E versus fluorescence correctly. Both embedded images are 600-pixel previews, not whole original sections or full-resolution performance validation; do not assume their processed `X` matrices are raw counts. Spots are Visium capture locations, not single cells. Reuse an active matching viewer for later cluster questions. Show only actual expression-graph groups and counts; they are computational groupings, not validated cell identities. Missing clusters must not be replaced with invented labels/data. The 49-spot Squidpy software-test fixture is for developer regression tests, not a first-run specimen. Never imply that the unrelated CMU-1 slide, H&E crop and fluorescence crop are paired or registered to one another.\n\n## First-run research examples\n\n- Download OpenSlide’s full CMU-1 brightfield slide (132.6 MB), open it, and ask me to draw a region before inspecting tissue.\n- Download Squidpy’s H&E mouse-brain crop, open its registered tissue image, and inspect the real spot and gene counts.\n- Download Squidpy’s fluorescence mouse-brain crop and compare Slc17a7/Gad1 over its registered tissue preview, if present.\n- Show requested spatial markers only if they are present in the current dataset and report the current spot and gene counts.\n- Guide the user in adding an available GeoJSON or CellViT-style segmentation overlay, then focus on a segmentation class that the live viewer actually reports.\n- Describe existing graph clusters or spatial domains from authoritative viewer state and focus on an already available cluster when requested.\n- Report a selected region in base-level slide pixel coordinates and use only derived formats supported by the current plugin, source and permissions.\n\n## Derived artifacts\n\nThe original pathology slide remains unchanged. Use the model-facing `slide.control_viewer` actions `save_project`, `load_project`, `recover_project` and `resume_project_save` for private single-user projects, with actual destination/source revisions and conflict handling. Restored files require fresh authorization and genuine source reimports. They do not restore permission, image consent, native host bindings or unfinished job authority.\n\n`load_project` can reopen plain project JSON or the plugin's own uncompressed annotation ZIP directly; it does not extract files or support arbitrary ZIP layouts. DICOM collection projects retain explicit ordered member paths, identities and source-derived topology, then independently reauthorize every member and create a fresh live aggregate. Never infer new handles or source revisions from a saved digest. If old-plus-new sources exceed the session's handle budget, report the capacity failure and preserve the old scene; do not evict sources or widen limits automatically.\n\nThe `export_microscopy_region` action requires the genuine current user capture, exact source/revision, destination and qualified native level. Microscopy exports retain actual C/Z/T/projection selection; qualified native Gray/RGB files use their real IFD/SOP/frame identity, never invented C/Z/T. A nonzero level also carries the exact base capture rectangle and must map inward within it, with exact physical-plane membership. The `capture` argument is coordinates, not permission or a way to manufacture user image consent. A prepared request is not an exported file. Confirm only its actual byte/hash receipt; decoded color values, original numeric samples and derived projections have distinct semantics, and none is new model image context.\n\nOME-Zarr project recipes require the same unchanged inventoried local directory, or explicit manifest-defined public SHA pins supplied through `slide.open_ome_zarr`'s authorized `manifestPath`. Do not auto-invent a complete manifest, silently hash an entire large store, use an ETag as publisher authenticity, or treat unlisted chunks as fill pixels. Reopening prepares fresh source bindings in the model call; only the exact consumed operation reconstructs scientific indexes or writes recovery state. Saved recipes, missing recovery records and a canceled preparation must not create new authority or imply successful restoration.\n\nThe default plugin's `slide.control_viewer` action `export_view` supports source-bound annotation GeoJSON, calibrated measurement CSV, loaded-view spatial CSV, portable project JSON, annotation ZIP and eligible source PNG. Supply the exact current source/revision, format, authorized destination and retry key, plus the actual gene or captured region/plane where required. `set_export_options` exposes the same destination, retry-key and annotation-name controls as the UI; its draft destination field is `destinationPath`, whereas the actual export uses `path`. A spatial CSV covers every loaded observation for one selected source gene and matrix, not the complete assay; supply the actual `matrix` descriptor and retain coverage, original IDs, value scale and missingness. Omission means legacy `X`, never whichever layer is visible. Do not substitute the primary image file for a separately registered expression source. Measurements require the annotation's actual coordinate frame and verified calibration for physical units. Pixel units are valid only for an established image-pixel frame; missing image association is not pixel calibration. Geometry from another source/scene/plane must not be relabeled or exported as current. Source PNG is not a screenshot, false-color composite or proof of new image context; it requires the same genuine current user-capture consent as numeric exports and must preserve supported source samples. Use numeric TIFF/OME-TIFF for unsupported PNG channel/sample layouts.\n\nAn annotation bundle contains a genuine portable project with labels and edit history and requires explicit annotation-name inclusion. Standalone portable projects also preserve authored state; these files are not de-identified. Every published artifact requires its actual byte/hash receipt. Existing destinations are never overwritten; do not reuse a retry key with changed source, view, destination or content. The app-only `slide.export_view` callback is distinct from the model-facing `export_view` action: do not call it directly or supply captured payloads/approval flags from chat. The app supplies the current bounded state after consuming a private single-use prepared operation.\n\nScientific CSV display identifiers are protected against spreadsheet formulas and may have an added apostrophe. For exact joins, decode `annotation_id_json`, `observation_id_json` or `gene_symbol_json` with `JSON.parse(cell).value`; `identifier_encoding` is `json-object-v1`. These companion fields preserve the original string/number identity without collisions. Do not strip punctuation or guess that a numeric-looking string is a number. Numeric measurements remain numeric, including finite negative values and negative zero.\n\nStandalone GeoJSON has a stricter safe-identifier policy than projects. Unsupported or overlong IDs must produce an explicit error, never silently renamed or filtered geometry; use a portable project to preserve the original authored identity. Geometry restored without verifiable source/scene/plane provenance is retained but withheld from aligned rendering, GeoJSON, measurement CSV and annotation ZIP. Standalone project JSON preserves the unaligned geometry and its provenance. A legacy filename or matching dimensions cannot establish alignment. DICOM collection annotation, measurement, eligible PNG and portable project/bundle exports retain every member's identity; reopening still requires fresh member authorization and exact topology verification.\n\nLegacy `slide.export_artifact` may additionally exist on a native host; inspect its actual capabilities rather than assuming availability or fabricating native grants. Local project CAS is not cross-user ACLs, coediting or collaborative storage. The `slide.save_annotations` tool and project/raw-write callbacks are also app-only. Their short-lived one-use operation grants are private server state, not caller-provided approval flags.\n\n## Source-bound scientific jobs\n\nUse `slide.spatial_indexed` for bounded metadata, gene/observation/expression, embedding and declared observation-field reads. Its `matrices` operation lists available and unsupported literal `X`, layer and `raw/X` choices. `{kind: \"raw\"}` uses independent `raw/var` features on the actual common observation axis; do not intersect features or substitute the main `/var`. Select with `slide.control_viewer` action `set_spatial_matrix`, supplying the actual `sourceId`, `sourceRevision`, `matrixSelection` and `matrixRevision` from the catalogue. Retain that selector/revision in indexed reads and workflow options; never rewrite a layer name, substitute `X`, or borrow `obs/total_counts` for another matrix. Neither `raw/X` nor a layer name establishes count scale. Loaded rows/genes are a subset of the source; preserve physical row indices and IDs, and do not invent coordinates for a matrix-only file or infer EOF from an empty filtered page.\n\nUse the physical `column` returned by a current `slide.query_viewer` gene query with `set_spatial_gene` when selecting a duplicate symbol or an indexed column. It binds `sourceId`, `sourceRevision`, `matrixRevision` and the original physical `index`; never fabricate or reuse it across matrices. Name-only selection requires a unique match. A successful matrix switch can intentionally leave the gene empty, expression hidden and a missing/ambiguous selection notice; that is not a request to choose another gene automatically. Spatial exports retain the actual selected column, not the first matching symbol. Portable projects revalidate saved column recipes against freshly authorized data. If a native transport reports `matrix-not-restored`, preserve the requested recipe and the explicit unavailable state rather than declaring a fallback `X` view restored.\n\n`slide.import_analysis_source_from_chat` reads explicitly mapped processed CSV/TSV molecular/cell or region-assay data through current guarded workspace authority. Region IDs, cells and molecules are distinct entities. A morphology join needs real matching IDs, and aggregate region counts do not provide transcript locations. This import is an agent-only operation; no duplicate UI form is required.\n\nExploratory spatial work uses the guarded model tools `slide.run_analysis_from_chat`, `slide.get_analysis_from_chat` and `slide.cancel_analysis_from_chat`. The older four analysis routes without `_from_chat` are app-only; do not use them as model authorization shortcuts. Complete-source and reference workflows use `slide.run_workflow`, `get_workflow`, `cancel_workflow`, `resume_workflow` and `read_workflow_artifact`. Import explicit counts tables with `slide.import_workflow_source` when the recipe requires them; source IDs must come from actual results, not paths inserted into ID fields. Pathology uses `slide.run_pathology`, `get_pathology`, `cancel_pathology` and `resume_pathology`. Durable recovery checks current permissions, unchanged sources and stored job identity; a cached UI row or saved job ID alone is not recovery.\n\nPrivileged UI buttons send an explicit user request into chat. Delivery is not admission or success: use the typed model operation and follow its actual job ID. Safe live-list/artifact reads cannot create a job, restore private disk state or renew a grant. Never copy widget `_meta` into a model permission context.\n\nTo apply a completed PCA/cluster/reference result, use `slide.control_viewer` action `apply_workflow_artifact` with the actual source/matrix binding, durable/job/attempt identity, artifact ID/SHA and supported projection. The plugin verifies signed bytes during the guarded model call; the app reads the prepared projection through `slide.read_live_workflow_projection` and joins actual physical observation indices and IDs before committing it. Do not supply rows or labels from chat, relabel predictions as measured annotations, infer results for excluded/unanalyzed observations, or recompute a missing artifact merely to restore a project. A cache miss requires an explicitly authorized preparation; a queued receipt is not a rendered linked view.\n\nCheck budgets, retain job/source identities and report completion only from a terminal successful result. Do not silently drop rows/genes to fit a limit or reuse an idempotency key for changed inputs. Cancellation is complete only when actual workers and IO have drained, not merely when a cancel request was accepted.\n\nThis permissive-only release excludes the native engine. Do not start or resume `hvg-cluster` or `reference-labels`; full-assay HVG/PCA/graphs and newly computed UMAP/t-SNE are unavailable. Existing source embeddings and authenticated historical artifacts can still be inspected/applied with their original provenance. Independent browser PCA/Louvain is limited to 8,000 loaded observations and 16 selected genes and is not a substitute for full-assay preprocessing. An unknown H5AD value scale must remain unknown; never silently declare counts or use selected gene totals as full-assay library sizes. Preserve normalization, graph/null model, seed, multiple-testing correction and statistical limitations in any reported result.\n\nFor historical reference-labeling artifacts, preserve the original reference matrix/feature/label identities, species, mapping, unresolved/tied assignments and hierarchy crosswalk provenance; this release cannot recompute them. Ligand/receptor work requires actual partner and complex definitions; without a declared inferential run, scores are descriptive. Region QC requires genuine region/probe/negative-control roles and coverage. The optional historical GeoMx compatibility mode reproduces a documented legacy p-value bug; never enable it silently or describe it as recommended QC.\n\nUse `slide.import_scientific_layer`, `list_scientific_layers`, `query_scientific_layer` and `get_scientific_entity` for actual cell/bin/molecule layers. For local ANN/SR overlays, use import `kind: \"dicom-annotation\"` with the actual annotation path and exact already-opened image target, optionally selecting declared ANN groups or SR content items. The plugin must verify both sources and original image references; a supplied SOP UID or plausible transform is not proof of alignment. Retain stable annotation/tracking IDs, coded units, missing values and measurement association scope. Ellipse tessellation is display-only; a MultiPoint remains one source annotation. Explicit authorization renewal is model-only, never a widget permission. A density overview is not a subsample of measured cells, and displayed entities are not the full source.\n\nForeground components, predicted nuclei/cell regions, user-trained classifier probabilities, source annotations and measured cells are not interchangeable. Optional CPU/model provisioning is an explicit operator task described in `PATHOLOGY.md`; never install dependencies or acquire weights during a job. Classifiers require explicit training labels and held-out evaluation; annotated-only references cannot establish precision/F1/PQ over unannotated objects. Scores are not calibrated clinical probabilities. Spatial association and exploratory spot-level permutation tests do not prove cell communication or independent biological replication.\n\n## Supported files\n\n- `.svs` for Aperio-style whole-slide pathology images.\n- `.tif` and `.tiff` for compatible tiled whole-slide images.\n- `.h5ad` for supported AnnData expression matrices, with spatial viewing only when actual coordinates are present. Matrix-only files expose matrix/analysis controls, not tissue images or fabricated coordinates.\n- `.dcm`/`.dicom` for supported Part 10 WSI series and separately inspected ANN/SR/SEG/parametric-map objects, not arbitrary clinical DICOM.\n- OME-Zarr/NGFF directories or explicitly authorized anonymous HTTPS roots via `slide.open_ome_zarr`.\n\nDICOM semantic import/export and DICOMweb query/metadata/object reads use their advertised dedicated tools. Use `slide.open_dicomweb_wsi` only with an explicit public endpoint and selected study/series/SOP list; supply an authorized `manifestPath` when required for content integrity. A selected reduced instance is not full-resolution coverage, and a caller-acquired SHA manifest is not publisher authentication. Portable remote projects require complete selected metadata/frame SHA pins; strong validators alone support viewing and metadata-only annotation/measurement exports, not a durable pixel snapshot. Reopening checks fresh metadata/topology and bounded codec probes; later frame reads must match their pins, not an assumed atomic origin snapshot. Remote PNG and native numeric exports remain unavailable. Preserve real SOP/frame/coordinate/unit provenance and unusable-depth warnings; unbound patient coordinates are not registered to the slide. A read grant does not authorize upload, arbitrary URLs or credential forwarding.\n\nUse `slide.prepare_dicom_upload` and then `slide.submit_dicom_upload` only after the user explicitly requests uploading those original files to that exact public HTTPS DICOMweb destination. Preparation is not a POST or evidence of human approval; its private one-use operation expires after 30 seconds. The combined limit is 16 instances and 32 MiB including multipart framing. Originals may contain patient identifiers and are not de-identified or transcoded. Never upload as an automatic follow-up to reading, viewing or local export, and never automatically retry a partial or indeterminate upload.\n\nOME scene/channel/Z/T support is source/codec/host-dependent. Do not synthesize channels or promise native plane selection on a host that exposes only its default image. See the installed `IMPLEMENTATION_STATUS.md` for format, host and capacity limits; a function name or enum is not acceptance.\n\nCompatible `.geojson` and `.json` files may provide annotations or segmentation overlays after a supported slide is open, but they are not standalone slide entrypoints.\n\n## Boundaries\n\n- Do not read or copy a whole pathology-scale binary into chat merely to open it.\n- Do not fabricate or expose `codex-resource://` or `viewer-file://` handles.\n- Use `slide.get_context` for compact current state, `slide.list_documents`/`slide.read_document` for complete available data, and `slide.capture_image` for explicit fresh viewport or region images.\n- Keep native file-tree and chat opening as independent routes.\n- Do not present visual interpretation, spatial gene patterns, computational clusters, segmentation labels, or authored annotations as a clinical diagnosis or validated cell identity.\n- Do not claim image registration, objective magnification, physical measurements, gene presence, or segmentation classes unless the current source or viewer state verifies them.\n- Keep research observations, computational inferences, and remaining uncertainty explicitly distinct.\n"
}