Layer: Atlas
Priority: P85
Related quests: external_refs_quest_spec.md — this quest covers PubMed/DOI citations via refs_json + [@key]; external references to Reactome pathways, UniProt entries, WikiPathways, Wikipedia, ClinicalTrials.gov, PDB, AlphaFold and arXiv/bioRxiv now flow through the new external_refs table. The two systems live side by side (paper citations keep using [@key]; non-paper refs use [ext:...]).
Status: active
SciDEX wiki pages have strong structural foundations — infoboxes, mermaid diagrams, knowledge graph cross-links, papers in the sidebar — but the core text body has no inline citations. A reader looking at FOXP1's speech disorder association, or FOXP2's language-gene role, cannot tell which paper supports which claim. This makes pages feel like summaries rather than scientific resources.
The citation infrastructure already exists ([@key] marker syntax, refs_json field, hover tooltip JS) but is almost entirely unused — the vast majority of pages have refs_json = NULL or sparse data, and no [@key] markers in the content. The tooltip currently shows only authors (year) — too thin for scientific use.
From user feedback: "Although there are some helpful citations at the bottom of the page, there are no in-line references on the page to connect various statements about the gene to the references supporting those findings... Having the in-line reference linkouts would make this resource immediately useful for getting a good idea from the summary and then being able to dive directly into the literature supporting it."
Every factual claim on every SciDEX wiki page is:
[@key] that renders as a hoverable [N] superscriptrefs_json is the authoritative source — it stores all citation metadata including claim contextCurrent schema per citation key:
{
"bacon2020": {
"authors": "Bacon C, et al",
"title": "...",
"journal": "...",
"year": 2020,
"pmid": "32028028"
}
}Target schema — add claim context that makes hover popovers scientifically useful:
{
"bacon2020": {
"authors": "Bacon C, et al",
"title": "The autism and schizophrenia associated gene FOXP1 is required for perinatal breathing and survival",
"journal": "Respiratory Physiology & Neurobiology",
"year": 2020,
"pmid": "32028028",
"doi": "10.1016/j.resp.2020.103400",
"claim": "FOXP1 is required for perinatal respiratory control; loss causes breathing failure",
"excerpt": "Foxp1 conditional knockout mice died within hours of birth due to respiratory failure, establishing a critical role in brainstem breathing circuits",
"figure_ref": "Fig. 3",
"strength": 0.92
}
}New fields:
claim: One sentence: what this paper specifically supports on this pageexcerpt: Key quote or result from the paper (≤150 chars) figure_ref: e.g., "Fig. 3", "Table 2" — most relevant figurestrength: 0–1 confidence this citation supports the claimCurrent tooltip is a plain text title attribute showing authors (year) (~40 chars). Replace with a positioned <div> popover showing:
┌─────────────────────────────────────────────────────┐
│ [1] Bacon et al. (2020) │
│ │
│ FOXP1 is required for perinatal breathing │
│ and survival │
│ │
│ Claim: FOXP1 loss causes brainstem respiratory │
│ circuit failure → perinatal death in mice │
│ │
│ "Foxp1 cKO mice died within hours of birth │
│ due to respiratory failure" — Fig. 3 │
│ │
│ Resp. Physiol. Neurobiol. 2020 [→] │
└─────────────────────────────────────────────────────┘Implementation: inline JS in the wiki page renderer (api.py), replacing the current 10-line mouseover handler with a rich popover div that reads claim, excerpt, figure_ref from refs object.
The popover should:
<a class="ref-link">[→] link to PubMed/DOI in the bottom-rightFor large-scale citation tracking, consider a normalized table alongside refs_json:
CREATE TABLE wiki_citations (
id INTEGER PRIMARY KEY AUTOINCREMENT,
wiki_slug TEXT NOT NULL,
ref_key TEXT NOT NULL, -- matches refs_json key
pmid TEXT,
doi TEXT,
claim TEXT, -- what this citation supports on this page
excerpt TEXT, -- key quote from paper
figure_ref TEXT, -- e.g. "Fig. 3"
strength REAL DEFAULT 0.8,
position_hint TEXT, -- section where this citation appears
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
UNIQUE(wiki_slug, ref_key),
FOREIGN KEY(wiki_slug) REFERENCES wiki_pages(slug)
);
CREATE INDEX idx_wiki_citations_slug ON wiki_citations(wiki_slug);
CREATE INDEX idx_wiki_citations_pmid ON wiki_citations(pmid);This enables: citation coverage queries, finding under-cited pages, paper→wiki backlinks.
These two genes are chosen as the pilot because:
refs_json already populated but zero inline markersThe page must prominently feature:
For each pass:
refs_json IS NOT NULL but content_md NOT LIKE '%[@%'[@key] markerclaim and excerpt fields (use PubMed abstract)For each paper in artifact_links that links to a wiki page:
refs_json includes the paper[@key] placementProduce a table:
When a hypothesis or analysis gains new evidence (paper linked via hypothesis_papers):
All specs and code referencing "NeuroWiki" or "neurowiki" should be updated to "SciDEX Wiki" or "scidex". Key locations:
quest_wiki_spec.md — update vision statementdocs/planning/specs/6391cf49_neurowiki_import_spec.md — historical, note as legacydocs/planning/specs/22c4c017_8b8_neurowiki_entity_lin_spec.md — updatedocs/planning/specs/48c44e67_graph_neurowiki_url_fix_spec.md — updatedocs/planning/specs/a7e9909f-de7_atlas_link_kg_to_neurowiki_spec.md — updateneurowiki_commit and source_repo columns (keep for provenance, just relabel in UI)Week 1 (Sprint 1):
[x] Phase 1a: Enrich refs_json schema design (done: this spec)
[ ] Phase 1b: Rich hover popover in api.py — 2h implementation
[ ] Phase 2: FOXP1 page rewrite with inline citations
[ ] Phase 2: FOXP2 page rewrite with inline citations
Week 2 (Sprint 2):
[ ] Phase 3: wiki-citation-enrichment recurring task (agent)
[ ] Phase 3: paper-to-wiki-backlink recurring task (agent)
[ ] Phase 3: wiki-quality-citation-report daily task
[ ] Phase 1c: wiki_citations table migration (if needed at scale)
Week 3+:
[ ] Phase 4: neurowiki → scidex rename pass
[ ] Phase 3: evidence-to-wiki-backfeed background task
[ ] Extend citation enrichment to all 9000+ wiki pages[@key] syntax exists, refs_json defined, JS renderer in placeauthors (year) — need full popover with claim/excerptclaim, excerpt, figure_ref, strength