/lit-sync

name: lit-sync
description: Use when references in a .bib file (often from /search-lit) should land in Zotero and Obsidian. Syncs them to the Zotero library, writes Obsidian literature notes and extracts cross-cutting concept notes once enough accumulate. A folder of PDFs is /obsidian-paper-vault.
metadata:
  triggers: "lit-sync, 문헌 동기화, 레퍼런스 정리, 개념 노트 추출, lit sync, Zotero 동기화, reference sync, 참고문헌 옵시디언"

Literature Sync: Zotero + Obsidian Pipeline

Takes the `.bib` output of `/search-lit` (or any user-specified .bib file), synchronizes the references into the Zotero library and Obsidian literature notes, and extracts cross-cutting concept notes once enough literature notes accumulate.

Prerequisites

• **Project owner only.** Collaborators consume the committed `manuscript/_src/refs.bib` snapshot

read-only. If the current user is a collaborator (no Zotero access per `SSOT.yaml` `reference_manager.required_for`), abort with instructions to flag `[@NEW:topic]` placeholders in the manuscript and notify the owner.

• Zotero desktop 7.x + Better BibTeX plugin, with Better BibTeX "Keep updated" auto-export

configured to `<project>/manuscript/_src/refs.bib`.

• Zotero MCP server (if not connected, skip Phase 2; auto-export still refreshes once Zotero is

reopened).

• Obsidian CLI or direct file writing to the vault; vault path from the user's environment

(e.g., `$OBSIDIAN_VAULT`).

Artifact Contract

`/lit-sync` is the **sole writer** of `manuscript/_src/refs.bib` (via the Better BibTeX auto-export trigger), `references/zotero_collection.json`, and `references/fulltext_retrieval.json` (Phase 2.7). **NEVER write `refs.bib` directly** — not even to compensate for a missing Zotero connection — because only Better BibTeX's export keeps it in step with the library; if auto-export is broken, fix the Zotero setup. Direct hand edits to `refs.bib` are drift — revert on sight.

---

Phase 1: Parse BibTeX

Parse the user-specified `.bib` file, or the `references/library.bib` just produced by `/search-lit`, with regex. Extract per entry: citekey, doi, pmid, title, authors (first + last minimum), journal, year, and volume/number/pages if present. Log any parse failures and skip those entries. All bibliographic data in later phases comes from these entries or from API responses.

A parsed citekey is not yet a library key: `/search-lit` candidate keys (`Kim_2024_Validation`) are provisional, and Better BibTeX mints the real key when Phase 2 adds the item. Never compose a key; Step 3.2 §Citekey provenance says where the note's key comes from.

---

Phase 2: Zotero Sync

If the Zotero MCP is not connected, skip this phase (still write the Step 2.3 file with `status: "skipped"`) and proceed to Phase 3.

Step 2.1: Determine project collection

Identify the project from the current working directory or an explicit user override. Reuse a recorded collection key; otherwise check existing Zotero collections for the project and, if none exists, create one with `zotero_create_collection`. Record the collection key, and report it to the user when a new collection is created.

Step 2.2: Dedupe + add

For each entry:

1. Use `zotero_search_items` to search by DOI or title — if already present, skip. This search-first step is what prevents duplicates; `zotero_add_by_doi` does **not** dedupe by itself (it fetches CrossRef and creates the item), so never skip the search. 2. Otherwise call `zotero_add_by_doi` (when a DOI is available) or `zotero_add_by_url` (the PubMed URL, when only a PMID is available). An entry with neither DOI nor PMID is not added: count it as failed and ask the user to add it manually.

• `zotero_add_by_doi` accepts an `attach_mode` argument that governs the **OA child-PDF

attach attempt at add time** (the installed server treats `linked_url` as "bookmark the PDF URL"; other values download/import). Exact accepted values are server-version-specific — verify against the connected server. Do **not** use `zotero_add_from_file` to attach a PDF to an item added here: it has no parent-item argument and would create a duplicate parent item. 3. Use `zotero_manage_collections` to place the item in the project collection.

Step 2.3: Result report

Zotero Sync:
  Added:     8 papers (new)
  Skipped:   3 papers (already in library)
  Failed:    1 paper (no DOI/PMID)
  Collection: RFA-Meta (TZQEP4NH)

Always write `references/zotero_collection.json` in the project workspace:

{
  "schema_version": 1,
  "status": "synced",
  "collection": "RFA-Meta",
  "collection_key": "TZQEP4NH",
  "added": 8,
  "skipped": 3,
  "failed": 1
}

If Zotero is unavailable, write the same file with `status: "skipped"` and a human-readable `reason`.

---

Phase 2.5: refs.bib snapshot refresh

Better BibTeX "Keep updated" auto-export normally refreshes `manuscript/_src/refs.bib` within seconds of a Zotero change. This phase **verifies** the snapshot actually updated before downstream skills consume it.

Step 2.5.1: Resolve path

Read `SSOT.yaml` → `truth.refs_bib`. Default: `manuscript/_src/refs.bib`. If absent (legacy project), fall back to `manuscript/_src/refs.bib` and emit a WARN recommending SSOT migration.

Step 2.5.1b: Precondition assertion (early-exit, do NOT poll)

Before entering the 10s polling loop in Step 2.5.2, verify both preconditions. If **either** fails, abort Phase 2.5 with setup instructions instead of waiting for a timeout that will never resolve.

1. **Better BibTeX is answering.** Probe the running plugin, not a file on disk:

   curl -s -m 5 -o /dev/null -w "%{http_code}" \
     http://127.0.0.1:23119/better-bibtex/json-rpc    # expect 200

A non-200 means Zotero is closed or BBT has not finished starting. Retry once after Zotero's window is up; BBT registers its endpoint a few seconds after the app does.

⚠️ **Do not gate on `~/Zotero/better-bibtex/read-only.json`.** Current BBT r