Citations & references — the SciDEX standard

This is the single, canonical way to cite literature in any agent-authored SciDEX artifact (wiki page, hypothesis, analysis, paper, benchmark, mission, protein design, …). It mirrors the v1 wiki citation model and is implemented once in Prism so every content surface renders citations identically:

inline citations render as numbered superscripts — [1], [2] — that link to the matching entry in a References section at the end of the body;
hovering (or focusing) a superscript shows a preview card with the title, year/journal, identifiers, and a link to the source;
a paper cited several times keeps one number throughout (deduped by first appearance), exactly as in a journal article.

If you are authoring artifact content, you only need the Authoring section. The rest documents the rendering contract.

Authoring: how to cite

Write any of the following inline in your markdown body. All three are equivalent and can be mixed in one document:

Syntax	Use when	Example
`[PMID:NNNNN]`	You have a PubMed ID	`…drives microglial activation [PMID:33186530].`
`[@citekey]`	You keyed the reference in `refs_json`	`…as shown previously [@kang1987].`
{cite}`citekey`	MyST-style role (same as `[@…]`)	…see {cite}`kang1987`.

Cluster multiple keys in one marker with ; or ,:

Several groups report this [@kang1987; @smith2020] and it replicates [PMID:12345678].

Then supply the reference metadata in the artifact content under refs_json (preferred) — an array (or keyed object) of reference records. references and citation_anchors are also accepted, and any of these may live either at the top level of content or inside content.frontmatter_json.

{
  "content_md": "…drives microglial activation [PMID:33186530] [@kang1987].",
  "refs_json": [
    {
      "cite_key": "kang1987",
      "pmid": "3032432",
      "title": "Cloning and expression of APP",
      "year": "1987",
      "journal": "Nature",
      "doi": "10.1038/325733a0"
    },
    {
      "pmid": "33186530",
      "title": "Neuroinflammation in Alzheimer's disease",
      "year": "2020",
      "journal": "Nat Neurosci"
    }
  ]
}

Reference record fields

All optional, but supply as many as you have — they populate the hover card and the References list. Recognised keys (aliases accepted):

Field	Aliases	Notes
`cite_key`	`citation_key`, `key`	matches a `[@key]` / `{cite}` marker
`pmid`	—	matches `[PMID:N]`; auto-links to PubMed
`doi`	—	auto-links to `https://doi.org/…`
`title`	`paper_title`	shown as the reference headline
`year`	`paper_year`
`journal`	`paper_journal`
`url`	`paper_url`, `source_url`	explicit link (wins over DOI/PMID)
`paper_ref`	`artifact_ref`, `ref`	`type:id` → links to the SciDEX artifact
`context_text`	`citation_text`, `source_sentence`	the supporting sentence, shown italic in the References list

Integrity rule. Only cite identifiers you can substantiate. A [PMID:N] with no matching refs_json entry still renders (it links straight to PubMed), but unverifiable or invented identifiers are a hard no — see the hallucinated-citation guidance in the authoring conventions.

Rendering contract (implementation)

Everything below is handled for you by src/lib/components/ArtifactBody.svelte — the one renderer for scientific prose. Type views (HypothesisView, WikiPageView, the generic ArtifactView fallback, …) delegate body rendering to it; do not re-implement markdown or citation handling in a new view.

Pipeline (src/lib/scidex/citations.ts → renderBodyWithCitations):

buildCitationPreviews(content) collects reference records from refs_json / references / citation_anchors (content or frontmatter) and indexes them by cite_key, pmid, doi, paper_ref, and label.

The body source is scanned for [PMID:N], {cite}`…` and [@…] markers. Each resolved marker is assigned a sequential number on first appearance (repeats reuse the number) and replaced with a superscript:

<sup class="scidex-cite"><span class="scidex-citation" …>
  <a class="scidex-citation-label" href="#ref-1">1</a>
  <span class="scidex-citation-card">…title · year · journal…</span>
</span></sup>

The markdown is rendered (MyST, with markdown-it fallback), then the superscripts are spliced back in.
The function returns { html, references }; ArtifactBody renders references as a numbered <ol> with id="ref-N" anchors and scroll-margin-top so superscript jumps clear the sticky nav.

Hover-card and superscript styling are global in src/app.css (.scidex-citation*, .scidex-cite). A [PMID:N] with no catalogued metadata falls back to a bare PubMed link so it is never dropped.

The legacy renderWikiMarkdownWithCitations (label-style, no numbering) remains only for backwards compatibility and its existing tests; new code should use renderBodyWithCitations via ArtifactBody.

v1 parity

This matches the v1 SciDEX wiki/hypothesis renderer:

static/citation-hover.js + api_shared/helpers.py (simple_md_to_html’s cite_collector) produced numbered [n] superscripts, a hover popover, and a deduped References list — reproduced here in TypeScript/Svelte.
v1 supported both [PMID:N] (hypotheses) and [@key] (wiki) syntaxes; both are supported here, plus the MyST {cite} role.

Substrate-side authored exemplars

The 11-node methodology cluster is the canonical source of citation-discipline exemplars — every cluster node cites PMIDs in the [PMID:N] syntax this doc renders. iter-72 #2140 + iter-73 #2141 audits enforced cross-node PMID consistency (same author/year → same PMID across all files), which the iter-81 #2148 cluster-integrity CI guard catches at PR-time. The exemplars demonstrate:

pre-registration.md + falsifiability.md + 4 distortion-wiki nodes — 6+ PMIDs each.
h-prereg-reduces-fpr.md (confirmatory) + h-prereg-narrows-claim-not-truth.md (contrarian) — both with [PMID:N] evidence_for / evidence_against blocks.
a-prereg-fpr-replication.md — full reference list with PMIDs at the bottom.

When operators want a reference for HOW to cite in agent-authored SciDEX content, read these substrate exemplars — they show the discipline in concrete form.

Citations and References