From 6b6785ee0f18e6184cad682067bf61433e20b484 Mon Sep 17 00:00:00 2001
From: Adam Wright <adam.j.wright82@gmail.com>
Date: Wed, 16 Sep 2026 16:47:53 +0000
Subject: [PATCH 1/2] docs(specs): record why the interactor overlay is built
 the way it is

The reasoning behind these choices lived only in commit messages, and
nobody reads those in a year when they are wondering why a number is what
it is.

specs/002-interactor-overlay-decisions records eleven decisions, each with
what was rejected and the measurement that settled it: the count being
interactions rather than entities, the badge not being drawn below 0.6
zoom and the notice that replaces it, the download being the data rather
than the view, the threshold being per-resource, a reader's own data being
read in the browser, and the rest.

Two things it deliberately does that the template does not ask for:

- Every figure is attributed to a measurement and a date, because several
  of these decisions exist *because* a measurement contradicted an
  assumption, and a reader should be able to tell which.
- Decisions still open are recorded as open -- where the control belongs,
  and the badge colour -- rather than omitted. An absent decision reads as
  an oversight; a recorded one reads as a choice nobody has made yet.

D7 is the one to read first if anything in this area misbehaves: a
reader's gesture and the address being replayed reach the same code, two
released bugs came from not distinguishing them, and a third of the same
shape is plausible.

The custom upload contract is written down as measured rather than as
documented, because it is not documented anywhere: the header the service
wants, the third column it refuses, and the first pair it silently eats
without one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../checklists/requirements.md                |  45 ++++
 .../research.md                               | 230 ++++++++++++++++++
 .../002-interactor-overlay-decisions/spec.md  | 174 +++++++++++++
 3 files changed, 449 insertions(+)
 create mode 100644 specs/002-interactor-overlay-decisions/checklists/requirements.md
 create mode 100644 specs/002-interactor-overlay-decisions/research.md
 create mode 100644 specs/002-interactor-overlay-decisions/spec.md

diff --git a/specs/002-interactor-overlay-decisions/checklists/requirements.md b/specs/002-interactor-overlay-decisions/checklists/requirements.md
new file mode 100644
index 00000000..744885f4
--- /dev/null
+++ b/specs/002-interactor-overlay-decisions/checklists/requirements.md
@@ -0,0 +1,45 @@
+# Specification Quality Checklist: The interactor overlay, as built
+
+**Purpose**: Validate this record is usable by someone who was not here
+**Created**: 2026-09-16
+**Feature**: [spec.md](../spec.md) · [research.md](../research.md)
+
+## Content Quality
+
+- [x] No implementation details in the spec itself — they are in research.md,
+      where a decision needs them to be understood
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders (spec.md; research.md is for
+      whoever maintains this next)
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic
+- [x] All acceptance scenarios are defined, and each names the spec that holds it
+- [x] Edge cases are identified — each is one a released bug actually hit
+- [x] Scope is clearly bounded: this records shipped behaviour, not future work
+- [x] Dependencies and assumptions identified
+
+## Record Quality
+
+This checklist adds items the standard one does not, because this document's
+purpose is to be believed later.
+
+- [x] Every figure is attributed to a measurement and a date
+- [x] Every decision names what was rejected, not only what was chosen
+- [x] Decisions that match the old browser cite the source file
+- [x] Open decisions are recorded as open (D10: the control's position, and the
+      badge colour) rather than omitted
+- [x] Where a measurement contradicted an assumption, that is said
+
+## Notes
+
+- D7 is the one to read first if something in this area misbehaves: two released
+  bugs came from the same cause and a third of the same shape is plausible.
+- The numbers here describe third-party data on a particular day. Tests assert
+  invariants rather than these figures, deliberately; do not "fix" a test to
+  match a number in this document.
diff --git a/specs/002-interactor-overlay-decisions/research.md b/specs/002-interactor-overlay-decisions/research.md
new file mode 100644
index 00000000..2fd4c5d0
--- /dev/null
+++ b/specs/002-interactor-overlay-decisions/research.md
@@ -0,0 +1,230 @@
+# Decisions behind the interactor overlay
+
+Each entry: what was decided, why, what was rejected, and the measurement that
+settled it. Dates are when the figure was read off beta or the ContentService.
+
+---
+
+## D1. The count beside a resource is interactions, not entities
+
+**Decision**: The number beside each resource counts **interactions** — the same
+unit as the badge drawn on an entity. How many entities carry them is in the
+tooltip.
+
+**Why**: It was entities, and the two were rendered identically with nothing
+saying so. Reported from beta as impossible: Reactome-FIs read **15** beside an
+MCM7 badge reading **17**. Both were correct and the pair was nonsense.
+
+**Measured** (2026-09-15, R-HSA-69306 with Reactome-FIs): 18 accessions posted,
+13 entities returned, **78 interactions**, MCM7 alone **17**. The service's
+`count` field equals the interactor array length throughout.
+
+**Rejected**: keeping entities and relabelling. Coverage is the more useful
+signal when choosing between resources, but a bare number that cannot be compared
+to the badge beside it is worse than a less useful number that can. Coverage
+survives in the tooltip.
+
+---
+
+## D2. A diagram tally counts each protein once
+
+**Decision**: When tallying what is drawn, badges are deduplicated by accession.
+
+**Why**: A protein drawn twice on a diagram carries two badges repeating the same
+interactions. Summing badges therefore overstates.
+
+**Measured** (2026-09-15, R-HSA-69306): **15 badges over 13 accessions**; summing
+badges gives 84 where the resource holds 78. The panel asks the resource directly
+before anything is drawn, so it would have shown 78 and then changed its mind to
+84 on the click.
+
+---
+
+## D3. The count badge is not drawn below 0.6 zoom
+
+**Decision**: Below 0.6 the badge is not drawn at all.
+
+**Why**: It is 30 model units wide. At the **0.283** R-HSA-1368108 opens at, that
+is **six screen pixels** holding a two-digit number. The old browser stops drawing
+it too: `RendererManager.setFactor` swaps renderer tiers at 0.5 and
+`ProteinRenderer000` never calls `drawSummaryItems`.
+
+**Rejected**: holding a minimum on-screen size as a map pin does — issue #200's
+suggestion 3. A badge that keeps its size while the diagram shrinks detaches from
+the entity it belongs to, and at the zooms in question would cover it.
+
+**0.6 rather than 0.5**: chosen here rather than copied, because a cytoscape zoom
+and a GWT factor are not the same quantity. 0.6 puts the badge at 18 screen
+pixels, which is where its digits stop being a smudge.
+
+---
+
+## D4. If they cannot be seen, say so
+
+**Decision**: When a resource has badges and none can be drawn, a bar says so and
+offers "Zoom to them".
+
+**Why**: D3 is right and left a hole. Measured (2026-09-15, R-HSA-1368108 at its
+opening zoom of 0.283): choosing IntAct put **nine badges** on the graph, **none
+visible**, and said nothing anywhere. The overlay appeared to do nothing — which
+is the complaint this whole feature began with.
+
+**The button fits the badges' _entities_, not the badges.** `cy.fit` ignores
+elements it cannot see, so fitting to hidden badges moved nothing: 0.283 before,
+0.283 after. Fitting those nine entities reaches only 0.308, still below the
+drawing threshold, so there is a floor just past it.
+
+---
+
+## D5. The download is the data, not the view
+
+**Decision**: The file carries every interaction the opened entities hold,
+whatever the threshold.
+
+**Why**: A spreadsheet can filter further; nothing recovers rows that were never
+written; and a file of twelve rows beside a badge reading 73 is a contradiction
+the reader has to resolve. Reading the drawn nodes also quietly lost one of
+BHLHE40's 73 — an interaction whose partner is already on the diagram gets an
+edge but no node of its own. The badge counts it; so should the file.
+
+It also means the drawing cap cannot truncate the file: draw 100 of 150 and the
+file still carries 150.
+
+---
+
+## D6. The threshold is remembered per resource
+
+**Decision**: Each resource opens at the threshold it was last left at; one never
+seen opens at the default (0.45, the old browser's `DEFAULT_SCORE`).
+
+**Why**: Resources do not score alike, so one number across all of them is the
+wrong shape. The old browser holds the same map —
+`Map<String, Double> interactorsThreshold` in `InteractorsContent.java`.
+
+**Deliberately not in the URL**: the address carries the threshold _in force_,
+which is what sharing needs. Putting all fourteen in it would make the address
+unreadable for no one's benefit.
+
+**A resource never seen does not inherit.** Inheriting is how a reader ends up
+with an empty diagram and no idea why.
+
+---
+
+## D7. A reader's gesture and the address being replayed are different things
+
+**Decision**: The replay path says it is a replay.
+
+**Why**: Both reach the same method — `stateToDiagram` reads the address and
+hands it to the same call a click goes through. Two released bugs came from not
+distinguishing them:
+
+1. A shared threshold was reset on load. Measured: `?overlay=Reactome-FIs&
+interactorScore=0.8` arrived and settled at no threshold at all, while the same
+   address _without_ the overlay kept 0.8.
+2. The overlay was lost on Back, because the replay looked like the
+   toggle-to-unselect gesture. Measured by logging history writes: the browser
+   restored `?overlay=IntAct&tab=details` and the app immediately pushed
+   `?tab=details` over it.
+
+**This is the recurring fault in this area.** Any path where the URL is replayed
+through a handler that also serves a reader's gesture is suspect.
+
+---
+
+## D8. A reader's own data is read in the browser
+
+**Decision**: A file or pasted table is parsed in the page. No request is made.
+Uploading is an explicit tick-box.
+
+**Why**: Uploading was inherited from the GWT browser, not required. Traced
+(2026-09-15): the content was posted to the ContentService, parsed there, written
+to `custom/<token>.bin`, and named by a token that became part of the page's
+address. A fresh upload was read back by a request carrying **no session**. The
+store held **323 files, oldest 2019-05-01**, and nothing expires.
+
+**Measured**: adding a local resource went from **two** requests to **zero**.
+
+**Kept as a choice** because that token is the only thing that makes an overlay
+survive a reload or open for a colleague. Removing it would have taken away a real
+capability in the name of privacy; making it a choice gives the reader both.
+
+**URL and PSICQUIC options still go to the server**: a page cannot fetch an
+arbitrary origin.
+
+---
+
+## D9. Nothing is asked until the panel is open
+
+**Decision**: Resource counts are prefetched when the reader opens the panel, not
+when a pathway loads.
+
+**Why**: The panel is hidden with `display`, never destroyed, so an ungated
+prefetch fired **thirteen requests to third-party PSICQUIC servers on every
+pathway anyone opened**. Measured on R-HSA-1368108: a reader who never opens the
+panel made **14** interactor requests; now **1**.
+
+It also starved the same-origin connection pool — browsers allow about six
+connections per host — and broke an unrelated test, the Molecules tab, which
+timed out waiting for data behind those requests. That failure is what made the
+cost visible.
+
+Opening the panel is the moment the counts are wanted, so nothing is lost.
+
+---
+
+## D10. The control is called "Interactors"
+
+**Decision**: The header control says "Interactors", with the chosen resource
+beneath it.
+
+**Why**: It said "Overlay" — the category it belongs to, not the thing it turns
+on. A reader looking for interactors had no word to look for, and two readers in
+a row missed a feature that was working.
+
+**Rejected for now**: moving it to the diagram toolbar, which is where production
+puts it (#200 suggestion 2). That is a layout change, not a label change, and is
+still open.
+
+**Rejected**: matching production's red badge (#200 suggestion 4). Disease badges
+are already red (`#BA1A1A`) and ordinary interactor badges purple (`#68297C`);
+making ordinary badges red would make the two indistinguishable. That needs a
+decision about which distinction matters more, not a colour swap.
+
+---
+
+## D11. The header controls stay divs
+
+**Decision**: They keep their markup and gain `role`, `tabindex`, key handling,
+labels and `aria-controls`, rather than becoming `<button>` elements.
+
+**Why**: They were plain divs with a click handler —
+`{ role: null, tabindex: null, focusable: false }`, measured — so species
+filtering and the whole interactor overlay were closed to anyone not using a
+mouse. A `<button>` would bring its own layout, and these divs carry layout the
+surrounding flex rules depend on.
+
+Escape closes either panel and **returns focus to the control**: without that,
+focus fell to `<body>` and a reader who closed the panel had lost their place on
+the page entirely.
+
+---
+
+## The custom upload contract
+
+Measured against beta's ContentService, 2026-09-15, by probing rather than
+reading source:
+
+| Input                        | Result                                                           |
+| ---------------------------- | ---------------------------------------------------------------- |
+| `#ID_A<tab>ID_B` then pairs  | accepted, no warning                                             |
+| no header, two columns       | accepted, **first pair read as the header and dropped**, warned  |
+| any third column             | refused                                                          |
+| not tabular                  | refused: "Could not Parse your file"                             |
+| rows not matching the header | refused: "Line 2 does not have mandatory field(s): [ID_A, ID_B]" |
+
+The in-browser reader matches this format deliberately, so the same file works
+either way, with two differences in the reader's favour: a missing header warns
+instead of silently eating a pair, and a malformed line is skipped and named
+rather than failing the file. Uploaded tuples are assigned a score of 1.0 by the
+service, so the in-browser reader does the same — otherwise the confidence filter
+would hide every custom interaction.
diff --git a/specs/002-interactor-overlay-decisions/spec.md b/specs/002-interactor-overlay-decisions/spec.md
new file mode 100644
index 00000000..b300bf06
--- /dev/null
+++ b/specs/002-interactor-overlay-decisions/spec.md
@@ -0,0 +1,174 @@
+# Feature Specification: The interactor overlay, as built
+
+**Feature Branch**: `docs/interactor-overlay-decisions`
+**Created**: 2026-09-16
+**Status**: Shipped — this records behaviour already released
+**Input**: Record the design decisions behind the interactor overlay so the reasoning survives the commit log.
+
+## What this document is
+
+A record, not a proposal. Everything here is released: #204, #206, #207, #208,
+#209, #210, #211, #212. It exists because the reasoning behind these choices
+lived only in commit messages, and nobody reads those in a year when they are
+wondering why a number is what it is.
+
+The decisions themselves, with what was rejected and why, are in
+[research.md](./research.md). This file records what the feature does, in terms
+that can be checked, and names the test that holds each one.
+
+**Every figure is measured.** Where a number appears, it was read off beta or off
+the ContentService on the date given, not inferred from the code. Several of the
+decisions below exist _because_ a measurement contradicted an assumption.
+
+## User Scenarios & Testing _(mandatory)_
+
+### User Story 1 - Find out whether a resource has anything here (Priority: P1)
+
+A curator opens a pathway and wants to know which interaction resource is worth
+choosing, out of fourteen.
+
+**Why this priority**: Without it, choosing between resources is fourteen clicks
+and six to seventeen seconds each, and five of the thirteen PSICQUIC servers had
+nothing at all for the pathway measured.
+
+**Acceptance Scenarios**
+
+1. **Given** the interactors panel is open, **When** the counts arrive, **Then**
+   each resource shows how many interactions it holds for this diagram, and the
+   tooltip also says across how many entities.
+2. **Given** a resource holds nothing here, **When** its count arrives, **Then**
+   it reads 0 and is visibly distinct from a resource not yet asked.
+3. **Given** the panel has never been opened, **When** a pathway is viewed,
+   **Then** no resource is asked anything.
+
+Held by: `e2e/interactor-threshold.spec.ts` — "is in the same unit as the badges
+it describes".
+
+### User Story 2 - See the interactors, and know they are there (Priority: P1)
+
+A reader chooses a resource at the zoom a pathway opens at.
+
+**Why this priority**: This is the complaint the whole feature began with — two
+readers in a row failed to find a feature that was working correctly.
+
+**Acceptance Scenarios**
+
+1. **Given** a resource with interactors here, **When** it is chosen at a zoom
+   where the count badge cannot be read, **Then** the reader is told they exist
+   and offered a way to reach them.
+2. **Given** that notice, **When** the reader takes it, **Then** the diagram
+   moves to the entities carrying interactors and the badges become readable.
+3. **Given** a resource with nothing here, **When** it is chosen, **Then** the
+   reader is told that, and not shown the same message as (1).
+
+Held by: `e2e/interactor-threshold.spec.ts` — "An overlay that cannot be seen
+yet", "The interactor count badge".
+
+### User Story 3 - Filter by confidence, and take the data away (Priority: P2)
+
+A curator raises the confidence threshold to clear out weakly-supported
+interactions, then wants the data in a spreadsheet.
+
+**Acceptance Scenarios**
+
+1. **Given** interactors drawn, **When** the threshold is raised, **Then** only
+   interactions at or above it remain drawn, and the diagram keeps up as the
+   control moves rather than when it is released.
+2. **Given** any threshold, **When** the file is downloaded, **Then** it carries
+   **every** interaction the opened entities hold, not the filtered view.
+3. **Given** a threshold that hides everything, **When** the diagram empties,
+   **Then** the reader is told the threshold is the cause, which is different
+   from the entity having none.
+
+Held by: `e2e/interactor-threshold.spec.ts`, `interactor-threshold.spec.ts`,
+`interactor-export.spec.ts`.
+
+### User Story 4 - Bring your own interactions (Priority: P3)
+
+A researcher has their own list of interacting pairs and wants to see it on a
+Reactome diagram.
+
+**Acceptance Scenarios**
+
+1. **Given** a file or a pasted table, **When** it is submitted, **Then** it is
+   read in the browser and **no request is made**.
+2. **Given** the reader ticks the sharing option, **When** it is submitted,
+   **Then** it is uploaded and the resulting address opens the same overlay for
+   someone else.
+3. **Given** the service refuses the data, **When** that happens, **Then** the
+   reader is told why, in words that say what to fix, and the dialog stays open.
+4. **Given** a resource the reader added, **When** they delete it, **Then** it
+   leaves both the list and the diagram.
+
+Held by: `e2e/custom-interactor-dialog.spec.ts`,
+`custom-interactor-parse.spec.ts`.
+
+### Edge Cases
+
+- A threshold in a shared address must survive arriving at it, including `0`.
+- Going back to a pathway must bring its overlay with it.
+- A pair listed twice, or listed both ways round, is one interaction.
+- A self-interaction is one interaction, not two.
+- Lower-case accessions must match a diagram that carries them upper-case.
+- A protein drawn twice on one diagram carries two badges for the same
+  interactions, and must not be counted twice.
+
+## Requirements _(mandatory)_
+
+### Functional Requirements
+
+- **FR-001**: The count beside a resource MUST be in the same unit as the badge
+  on an entity — interactions.
+- **FR-002**: A diagram tally MUST count each protein once, however many times it
+  is drawn.
+- **FR-003**: The count badge MUST NOT be drawn at a zoom where its digits cannot
+  be read.
+- **FR-004**: When badges exist but none can be drawn, the reader MUST be told,
+  and offered a way to reach them.
+- **FR-005**: The download MUST carry every interaction the opened entities hold,
+  independent of the threshold.
+- **FR-006**: The threshold MUST be remembered per resource.
+- **FR-007**: A threshold or overlay named in the address MUST survive arriving
+  at it, and MUST survive returning to it.
+- **FR-008**: A file or pasted table MUST be read without leaving the browser
+  unless the reader asks for a shareable link.
+- **FR-009**: Resources MUST NOT be asked anything until the reader opens the
+  panel.
+- **FR-010**: Deleting a resource the reader added MUST remove it from the
+  diagram as well as the list.
+- **FR-011**: Both header controls MUST be operable from the keyboard, and MUST
+  return focus when closed.
+
+### Key Entities
+
+- **Interaction**: a pair of accessions with a confidence score. Score is the
+  only field that decides visibility.
+- **Resource**: a named source of interactions — IntAct, a PSICQUIC service, or
+  one the reader supplied.
+- **Tally**: what a resource holds for one diagram, in both units —
+  `interactions` and `entities`.
+
+## Success Criteria _(mandatory)_
+
+### Measurable Outcomes
+
+- **SC-001**: A reader can tell which of fourteen resources is worth choosing
+  without choosing any of them.
+- **SC-002**: Choosing a resource never leaves the screen unchanged and silent.
+- **SC-003**: A reader who has never opened the interactors panel causes no
+  interaction lookups at all.
+- **SC-004**: A link shared by one reader opens the same overlay for another.
+- **SC-005**: Moving the confidence control redraws the diagram without
+  refetching.
+- **SC-006**: Someone using only a keyboard can reach the overlay, choose a
+  resource, and close the panel.
+
+## Assumptions
+
+- Curators compare this site against the old browser, so where the old browser
+  made a defensible choice it is matched deliberately and the source is cited.
+- An interaction with no confidence score is treated as below every threshold.
+  None were seen in measured data; the rule exists so the absent case follows the
+  weak case rather than being waved through.
+- Interaction data is third-party and changes. Tests therefore assert invariants
+  and relationships, not the particular numbers recorded here.

From 9e5fb9e11242cc7571465d694e61f5850d7bbc7c Mon Sep 17 00:00:00 2001
From: Adam Wright <adam.j.wright82@gmail.com>
Date: Wed, 16 Sep 2026 16:55:24 +0000
Subject: [PATCH 2/2] docs(specs): correct a figure this document's own rule
 should have caught

Reviewing the record against the standard it sets found one claim without
a date: "five of the thirteen PSICQUIC servers had nothing at all". On
re-measuring (2026-09-16, R-HSA-1368108) there were **twelve** resources
offered, not thirteen, five of them empty. The five was right; the
thirteen was a day old.

The list is served by third parties and changes, so the counts that
describe it are now dated and said to be variable, and the requirement is
written as "the reader can tell which is worth choosing" rather than
around a number that will be wrong again next week.

The checklist records the catch, because a document about being believed
later should show its own correction rather than quietly absorb it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../checklists/requirements.md                  |  4 ++++
 .../research.md                                 | 13 ++++++++-----
 specs/002-interactor-overlay-decisions/spec.md  | 17 +++++++++++------
 3 files changed, 23 insertions(+), 11 deletions(-)

diff --git a/specs/002-interactor-overlay-decisions/checklists/requirements.md b/specs/002-interactor-overlay-decisions/checklists/requirements.md
index 744885f4..b363218e 100644
--- a/specs/002-interactor-overlay-decisions/checklists/requirements.md
+++ b/specs/002-interactor-overlay-decisions/checklists/requirements.md
@@ -35,6 +35,10 @@ purpose is to be believed later.
 - [x] Open decisions are recorded as open (D10: the control's position, and the
       badge colour) rather than omitted
 - [x] Where a measurement contradicted an assumption, that is said
+- [x] Figures that describe a third-party list say so, and are not written as if
+      they were constants. Reviewing this document against its own standard
+      caught one: "five of the thirteen PSICQUIC servers" had no date, and on
+      re-measuring there were twelve, not thirteen. The five was right.
 
 ## Notes
 
diff --git a/specs/002-interactor-overlay-decisions/research.md b/specs/002-interactor-overlay-decisions/research.md
index 2fd4c5d0..93e14717 100644
--- a/specs/002-interactor-overlay-decisions/research.md
+++ b/specs/002-interactor-overlay-decisions/research.md
@@ -102,8 +102,8 @@ wrong shape. The old browser holds the same map —
 `Map<String, Double> interactorsThreshold` in `InteractorsContent.java`.
 
 **Deliberately not in the URL**: the address carries the threshold _in force_,
-which is what sharing needs. Putting all fourteen in it would make the address
-unreadable for no one's benefit.
+which is what sharing needs. Putting every resource's threshold in it would make
+the address unreadable for no one's benefit.
 
 **A resource never seen does not inherit.** Inheriting is how a reader ends up
 with an empty diagram and no idea why.
@@ -159,9 +159,12 @@ arbitrary origin.
 when a pathway loads.
 
 **Why**: The panel is hidden with `display`, never destroyed, so an ungated
-prefetch fired **thirteen requests to third-party PSICQUIC servers on every
-pathway anyone opened**. Measured on R-HSA-1368108: a reader who never opens the
-panel made **14** interactor requests; now **1**.
+prefetch fired **a request to every third-party PSICQUIC server on every pathway
+anyone opened** — thirteen of them on 2026-09-15, twelve on 2026-09-16, because
+the list is served by third parties and changes.
+
+Measured on R-HSA-1368108: a reader who never opens the panel made **14**
+interactor requests; now **1**.
 
 It also starved the same-origin connection pool — browsers allow about six
 connections per host — and broke an unrelated test, the Molecules tab, which
diff --git a/specs/002-interactor-overlay-decisions/spec.md b/specs/002-interactor-overlay-decisions/spec.md
index b300bf06..45589ba8 100644
--- a/specs/002-interactor-overlay-decisions/spec.md
+++ b/specs/002-interactor-overlay-decisions/spec.md
@@ -25,11 +25,16 @@ decisions below exist _because_ a measurement contradicted an assumption.
 ### User Story 1 - Find out whether a resource has anything here (Priority: P1)
 
 A curator opens a pathway and wants to know which interaction resource is worth
-choosing, out of fourteen.
+choosing, out of a dozen or more.
 
-**Why this priority**: Without it, choosing between resources is fourteen clicks
-and six to seventeen seconds each, and five of the thirteen PSICQUIC servers had
-nothing at all for the pathway measured.
+**Why this priority**: Without it, choosing between resources is a click and six
+to seventeen seconds each, and many hold nothing. Measured 2026-09-16 on
+R-HSA-1368108: **12 PSICQUIC resources offered, 5 of them empty**, the rest
+ranging from 2 to 192 interactions.
+
+The resource list is served by third parties and changes — it was 13 the previous
+day. That is why the requirement is "the reader can tell which is worth choosing"
+rather than a number.
 
 **Acceptance Scenarios**
 
@@ -152,8 +157,8 @@ Held by: `e2e/custom-interactor-dialog.spec.ts`,
 
 ### Measurable Outcomes
 
-- **SC-001**: A reader can tell which of fourteen resources is worth choosing
-  without choosing any of them.
+- **SC-001**: A reader can tell which resource is worth choosing without
+  choosing any of them.
 - **SC-002**: Choosing a resource never leaves the screen unchanged and silent.
 - **SC-003**: A reader who has never opened the interactors panel causes no
   interaction lookups at all.