The citation manager
Date: 2026-10-19
Status: built on feat/citation-manager; follows the Attestation/AgentMarkit
boundary note (Attestation is the engine, AgentMarkit the screens).
Depends on: the library store (2026-09-05-library-store-design.md), the
reader's bibliography (2026-09-30-bibliography-design.md), the library
dashboard contract (docs/guides/library-dashboard.md).
What this is for
A researcher on a hosted machine has no Zotero desktop and should not need
Zotero's servers. They need what a reference manager does: format a citation
in the journal's style, copy BibTeX, fix a wrong field, merge the two records
the preprint and the publication became, and import a .bib someone sent.
Attestation already owns the deduplicated store; this adds the management on
top, as CLI (attest bib), one MCP tool (cite.format) and fields in
library.json, which AgentMarkit's bibliography view reads.
Decisions
Libraries. citeproc-py 0.11.1 (BSD-2-Clause-Views; releases through
2026-09, wheels for 3.12/3.13, depends only on lxml) renders CSL;
bibtexparser 2.x (MIT; 2.1.0 released 2026-10-02, depends on pylatexenc)
reads and writes BibTeX. Both install with uv on 3.12 and 3.13, and
citeproc-py ships its locale files, so rendering was verified with the
network namespace removed (unshare -n). Five styles are vendored from
citation-style-language/styles at 0e5503b (CC BY-SA 3.0, license file
beside them); Vancouver is the repository's nlm-citation-sequence.csl
since its rename (PR 7928).
One .bib parser. bibtexparser replaces the hand-rolled regex reader
everywhere (citations._parse_bib_entries delegates), not only in the new
code: two parsers would disagree on year = 2022 (the regex dropped
unbraced values) and on @string macros, and the store would hold different
fields depending on which path read the file. latex.bib_keys keeps its own
key-only regex: it must count untitled entries, as BibTeX does, and is fast.
Each reference is rendered alone. Measured on 5,000 references: a joint APA bibliography took 81 s (quadratic year-suffix disambiguation) against ~20 ms per reference alone, and a joint rendering would make one paper's text depend on which others are in the library. Numeric labels are stripped for the same reason. Renderings are cached per (row, style) under a digest of the CSL-JSON and the style file.
library.json precomputes one style. All five cost ~1 KB more per
reference (10.7 MiB at 5,000, over the consumer's 8 MB); the default style and
BibTeX are in every row, the rest is one CLI or MCP call away. The build
stays read-only and only reads the cache; attest library dashboard warms
it first. Over 6 MiB, the oldest rows shed abstract, then citation and
BibTeX, before any row is dropped.
Edits change the store, never an upload. An edit updates the row, is
logged in reference_edits, and saves the reference to the owner's
bibliography, so the generated <owner>.bib carries it under its stable
key. Sync's fill-only merge keeps an edited value; a field the owner
cleared can be refilled by a source that has it (stated in the guide).
Keys and identities are not editable.
Merging deletes from the store and keeps the names. The dropped row's
children move to the kept row; its names become reference_aliases, which
library._row_by_ids consults after every column, so a \cite key, a lookup
and the next sync of the file it came from all land on the kept row. Keeping
a tombstone row instead would have meant excluding it from search, export,
the dashboard and the graph separately.
Duplicates come from the store's own evidence. Same DOI, arXiv id, or
title and year in two rows, plus every id a sync refused because another row
held it (the identity/doi/arxiv_id conflicts upsert already records).
cited_by reads the workspace. ATTEST_WORKSPACE, else
<HERMES_HOME's root>/workspace (the same root rule as the dashboard's
default path, now paths.hermes_root), scanned for \cite-family keys
(latex.cited_keys) and claims' cite= (claims.parse_file), bounded at
2,000 files of 2 MB, paths relative to the root.
repeated_keys is ported from AgentMarkit's latex-paper check: a key
two LOADED .bib files define. It is reported, not counted as unresolved,
because BibTeX builds with the first definition.