Record why some answers have no citations, and the option to change it

[adamjohnwright]

Documentation only. Found while answering a question the website asked about event ordering — the measurement turned up something neither of us knew.

Some answers have no citations, by construction

"How do I use the pathway browser?" returns 0 citations and 452 tokens. Not a failure: a citation carries st_id, a Reactome stable identifier, and only the Reactome and disease-variant collections have them. The userguide collection indexes documentation pages whose metadata is a page URL, so nothing there can become a citation in the contract's shape.

Worth writing down because it is the opposite of what testing would suggest:

• it correlates with the fastest answers (the userguide question is also the 3.3s-to-first-token one), so it is common rather than exotic
• the four questions anyone would naturally reach for all produce citations, so it is exactly the case a reasonable test pass misses

The website had this right in their panel already — heading and list inside one conditional — but untested, which they have now fixed at two levels.

Citations always precede prose, and that is structural

Measured across five questions: every one producing both had its last citation at event 11 and first token at event 12, no interleaving. But the useful part is the reason, not the samples — citations are emitted only on on_retriever_end, and token events are gated on that same event, because retrieval completing is how the answer's tokens are told apart from the query expander's.

So "sources are complete when the first token arrives" is a design fact a caller can rely on, not a timing observation that might not hold next week.

Open, not scheduled: citing userguide pages

Proposed by the website session, agreed in shape, deliberately not scheduled. A documentation URL does not fit {st_id, display_name}, and a fabricated R- id is not an option — it would resolve to nothing, or worse to the wrong entity. An optional sibling works, exactly one of the two present:

{"st_id": "R-HSA-8862803", "display_name": "..."}             # unchanged
{"url": "/userguide/pathway-browser", "display_name": "..."}  # new

A consumer that understands only st_id keeps working by skipping what it does not recognise. Recorded as T020b; Adam's call, and not a blocker — an answer honest about having no sources beats an invented one.

🤖 Generated with Claude Code