Improve ux for biologist

.changeset/three-chicken-try.md

@@ -0,0 +1,10 @@
+---
+'@platforma-open/milaboratories.vdj-integration.software': patch
+'@platforma-open/milaboratories.vdj-integration.workflow': patch
+'@platforma-open/milaboratories.vdj-integration': patch
+'@platforma-open/milaboratories.vdj-integration.model': patch
+'@platforma-open/milaboratories.vdj-integration.test': patch
+'@platforma-open/milaboratories.vdj-integration.ui': patch
+---
+
+UX improvement

block/package.json

@@ -32,7 +32,7 @@
       "logo": "file:../logos/block-logo.png",
       "url": "https://github.com/platforma-open/milaboratories.vdj-integration",
       "support": "mailto:support@milaboratories.com",
-      "description": "Matches VDJ clonotypes between two datasets by exact sequence and V/J gene matching, producing bidirectional linker columns",
+      "description": "Matches clonotypes between two VDJ datasets to bring reference properties (paired chains, liabilities) onto the matched clonotypes.",
       "longDescription": "file:../docs/description.md",
       "changelog": "file:../CHANGELOG.md",
       "tags": [

docs/description.md

@@ -1,7 +1,7 @@
 # Overview
 
-This block matches clonotypes between two VDJ datasets, enabling integration of bulk and single-cell sequencing data. It is designed for antibody discovery workflows where researchers need to identify which clonotypes from a deep bulk sequencing run also appear in a paired single-cell VDJ dataset.
+This block bridges two VDJ datasets by finding clonotypes that appear in both. It is designed for antibody discovery workflows where researchers need to combine a deep target dataset (typically bulk sequencing — broad coverage, no chain pairing) with a reference dataset (typically single-cell sequencing — paired chains, smaller scale).
 
-The block takes two clonotyping run outputs as inputs — a target dataset and a reference dataset. It performs exact matching on nucleotide or amino acid sequences along with V and J gene usage, automatically selecting the widest shared sequence feature (e.g. VDJRegion or CDR3) available in both datasets.
+The block performs exact matching on the widest sequence region shared by both datasets (e.g. VDJRegion or CDR3), in either nucleotide or amino acid alphabet, with optional V and J gene matching at gene level. When a clonotype matches multiple candidates, the block selects the most abundant match and reports a confidence score — 1.0 for unique matches, lower for ambiguous ones.
 
-When a clonotype matches multiple candidates, the block selects the best match and reports a confidence score (1.0 for unique matches, decreasing for ambiguous ones). The output includes bidirectional linker columns that allow downstream blocks such as lead selection, SHM trees, and GraphMaker to join data across the two datasets.
+After running, any column from the reference dataset — paired chains, liabilities, cluster labels, abundance — becomes accessible on the matched target clonotypes in downstream blocks such as Lead Selection, GraphMaker, and SHM Trees. A match summary shows how many clonotypes from each side were matched.

model/src/index.ts

@@ -50,7 +50,7 @@ const datasetOptionConfig = {
 
 export function getDefaultBlockLabel(data: { targetLabel?: string; referenceLabel?: string }) {
   if (data.targetLabel && data.referenceLabel)
-    return `${data.targetLabel} to ${data.referenceLabel}`;
+    return `${data.targetLabel} ↔ ${data.referenceLabel}`;
   return "Select datasets";
 }
 

ui/src/pages/MainPage.vue

@@ -13,6 +13,7 @@ import {
   PlNumberField,
   PlSectionSeparator,
   PlSlideModal,
+  PlTooltip,
   usePlDataTableSettingsV2,
 } from "@platforma-sdk/ui-vue";
 import { computed, ref, watch } from "vue";
@@ -73,7 +74,7 @@ watch(
 );
 
 const sequenceTypeOptions = [
-  { label: "Aminoacid", value: "aminoacid" },
+  { label: "Amino acid", value: "aminoacid" },
   { label: "Nucleotide", value: "nucleotide" },
 ];
 
@@ -120,30 +121,60 @@ const tableSettings = usePlDataTableSettingsV2({
       <PlDropdownRef
         v-model="app.model.data.targetRef"
         :options="app.model.outputs.targetOptions"
-        label="Target dataset"
+        label="Target repertoire"
         clearable
         required
-      />
+      >
+        <template #tooltip>
+          The repertoire whose clonotypes you want to enrich with extra information — usually a deep
+          bulk dataset.
+        </template>
+      </PlDropdownRef>
       <PlDropdownRef
         v-model="app.model.data.referenceRef"
         :options="app.model.outputs.referenceOptions"
-        label="Reference dataset"
+        label="Reference repertoire"
         clearable
         required
-      />
+      >
+        <template #tooltip>
+          Provides clonotype properties (paired chains, liabilities, clusters) that get carried onto
+          matched target clonotypes — usually a single-cell dataset.
+        </template>
+      </PlDropdownRef>
       <PlBtnGroup
         v-model="app.model.data.sequenceType"
         label="Sequence type"
         :options="sequenceTypeOptions"
         compact
-      />
+      >
+        <template #tooltip>
+          Nucleotide is more precise. Switch to amino acid only when one of the datasets has no
+          nucleotide information — for example, an amino-acid-only dataset brought in through the
+          Import VDJ Data block.
+        </template>
+      </PlBtnGroup>
       <PlDropdown
         v-model="app.model.data.feature"
         :options="featureOptions"
-        label="Feature"
+        label="Matching region"
         :disabled="!app.model.data.targetRef || !app.model.data.referenceRef"
-      />
-      <PlCheckbox v-model="app.model.data.useGeneMatching"> Use V/J gene matching </PlCheckbox>
+      >
+        <template #tooltip>
+          VDJRegion is most precise; CDR3 yields more matches at slightly lower specificity. Only
+          regions present in both datasets appear here.
+        </template>
+      </PlDropdown>
+      <PlCheckbox v-model="app.model.data.useGeneMatching">
+        Require matching V and J genes
+        <PlTooltip class="info" position="top">
+          <template #tooltip>
+            Turn off only when the two datasets use different V/J gene naming conventions — for
+            example, a dataset brought in through the Import VDJ Data block, which preserves the
+            source pipeline's original gene names.
+          </template>
+        </PlTooltip>
+      </PlCheckbox>
       <PlAccordionSection label="Advanced Settings">
         <PlSectionSeparator>Resource Allocation</PlSectionSeparator>
         <PlNumberField