| name | lit-sync |
| description | Sync the Better BibTeX export to mi-spectral/literature/<citekey>.md files (citation-discipline bridge). Use when the user asks to "sync the literature", "refresh literature files", "lit-sync", or after exporting a new BibTeX from Zotero. Parses literature/mi-spectral-better-bibTeX.bib, finds each PDF in the MI-SPECTRAL drive folder by author/year, looks up cached Mathpix conversions by SHA256, and writes per-citekey markdown with YAML frontmatter. Idempotent. |
lit-sync
Bridge between Better BibTeX (which produces the citekeys we cite) and the citation-discipline hook (which checks literature/<citekey>.md exists before allowing an @<citekey> in manuscript/).
What it does
For each entry in literature/mi-spectral-better-bibTeX.bib:
- Read citekey from the entry header (
@type{citekey,)
- Find the migrated PDF in
~/Google Drive/Literature/MI-SPECTRAL/
- Try
<citekey>.pdf directly first
- Fall back to
<firstauthor-surname> + <year> filename match
- SHA-256 the PDF, look up
~/Google Drive/Literature/.litrev/mathpix_cache/<sha256>.md
- Write
mi-spectral/literature/<citekey>.md with YAML frontmatter + Mathpix markdown
- Scan
mi-spectral/manuscript/ for @citekey tokens, warn on any unsynced
Skips entries whose existing markdown already has a matching pdf_sha256 in its frontmatter — re-runs are cheap. Skips entries whose citekey has invalid characters (e.g., ; from a malformed Zotero author field) with a clear "fix the underlying Zotero entry" message.
When to run it
- After exporting a fresh BibTeX from Zotero (right-click collection → Export Collection → Better BibTeX → save to
literature/mi-spectral-better-bibTeX.bib)
- After dropping new PDFs into Zotero and running
migrate_zotero_attachments + index_papers.py
- Before adding a new
@citekey to manuscript/ (the PreToolUse hook needs the file to exist)
- Whenever the citation-discipline hook complains about a missing
literature/<citekey>.md
How to invoke
py scripts/lit_sync.py
Or via the /lit-sync slash command (this skill).
Prerequisites
- BibTeX export at
literature/mi-spectral-better-bibTeX.bib — refresh by right-click on the mi-spectral Zotero collection → Export Collection → Better BibTeX → save with that filename.
- PDFs in the drive folder —
mcp__litrev__migrate_zotero_attachments(project='MI-SPECTRAL') writes them as <litrev-key>.pdf.
- Mathpix cache populated by
index_papers.py (requires the _estimate_tokens patch from litrev_mcp issue #21 for long math-heavy books).
- Python deps:
bibtexparser (already installed).
Output frontmatter
---
citekey: cavanaughAkaikeInformationCriterion1998a
item_type: article
authors: Cavanaugh, Joseph E. and Shumway, Robert H.
year: '1998'
title: An Akaike information criterion for model selection in the presence of incomplete data
venue: Journal of Statistical Planning and Inference
volume: '67'
issue: '1'
pages: 45--65
doi: 10.1016/S0378-3758(97)00115-8
source_pdf: 'C:\Users\marcu\Google Drive\Literature\MI-SPECTRAL\cavanaugh_akaike_information_criterion_1998.pdf'
pdf_sha256: <64-hex>
converted_via: mcp__litrev__convert_pdf (Mathpix)
last_synced: 2026-05-22T17:30:00Z
---
Followed by the full Mathpix markdown body.
Failure modes and what to do
| Symptom | Cause | Fix |
|---|
ERROR: BibTeX export not found | No .bib file at the expected path | In Zotero: right-click collection → Export Collection → Better BibTeX → save to literature/mi-spectral-better-bibTeX.bib |
SKIP: citekey has invalid characters [';'] | Malformed Zotero author field collapses multiple authors into one literal name with semicolons | In Zotero: edit the item, replace the single author entry with multiple separate author entries (one Last/First per author); then re-export BBT |
SKIP: PDF not found | PDF still attached to Zotero, not migrated to drive folder | Run mcp__litrev__migrate_zotero_attachments(project='MI-SPECTRAL') |
SKIP: Mathpix cache miss | PDF was migrated but never indexed | Run py "Google Drive/Literature/MI-SPECTRAL/index_papers.py" |
| Snake_case key persists despite BBT default being camelCase | Litrev's zotero_add_paper set a Citation Key: line in the item's extra field; BBT inherits it on export | In Zotero: right-click the item → Better BibTeX → Refresh BibTeX key (overwrites with BBT's camelCase default) |
Related infrastructure
scripts/lit_sync.py — the implementation this skill invokestodo/001-literature-and-hooks.md — Phase 3 specifies the PreToolUse hook that enforces citation discipline at edit timeIDEAS.md — "Citation discipline" section explains why this whole pipeline existsCLAUDE.md — load-bearing rule: every @citekey in manuscript/ needs literature/<citekey>.md to exist and have been read in-session
Citekey convention (locked 2026-05-22)
Better BibTeX default: <firstauthor-lowercase><TitleWord1Word2Word3-camelCase><year>[a|b|...]. Examples:
cavanaughAkaikeInformationCriterion1998amengPerformingLikelihoodRatio1992bvaartAsymptoticStatistics1998a
The a/b disambiguator suffix appears when BBT detects multiple library-wide items that would otherwise collide. Don't strip it — it's part of the citekey.
