git:20260929.640e778 to git:20260930.c83ad00

- Takes the `.bib` output of `/search-lit` (or any user-specified .bib file) and

- synchronizes the references into the Zotero library and Obsidian literature notes.

- When enough literature notes accumulate, extracts cross-cutting concept notes.

-

- ## Communication Rules

-

- - Communicate with the user in their preferred language.

- - **Vault layout — honor what exists, default to English.** Before creating notes, detect the

- vault's existing layout: if the vault already uses a particular folder structure (including a

- Korean one such as `02 연구/문헌/` and `02 연구/개념노트/`), **honor it — never silently

- rename a user's folders**. For a new or unclear vault, default to the English folders

- `Literature/` and `Concepts/` with the English note templates below.

- - A Korean opt-in variant (Korean folder layout + Korean-heading templates) lives in

- `references/locale/ko/note_templates.md` — use it when the vault is Korean-structured or the

- user prefers Korean notes.

-

- ## When to Use

-

- - After `/search-lit` completes — sync the produced .bib into Zotero + Obsidian.

- - Bulk-register references from an existing .bib into Zotero + Obsidian.

- - Tidy the `references/` folder inside a project workspace.

- - On explicit concept-extraction request → extract cross-cutting concepts from existing literature notes.

- - **Project owner only** — `/lit-sync` is an owner-scoped operation per `docs/zotero_policy.md`. Collaborators consume the committed `manuscript/_src/refs.bib` snapshot read-only.

- - Zotero desktop 7.x + Better BibTeX plugin installed.

- - Better BibTeX "Keep updated" auto-export configured to `<project>/manuscript/_src/refs.bib` (owner setup checklist in `docs/zotero_policy.md` §Setup).

- - Zotero MCP server available (skip the Zotero phase if not connected; auto-export refresh still fires once Zotero is reopened).

- - Obsidian CLI or direct file writing to the Obsidian vault.

- - Obsidian vault path: configured in user's environment (e.g., `$OBSIDIAN_VAULT`).

- Per `docs/artifact_contract.md`, `/lit-sync` is the **sole writer** of:

-

- | Artifact | Writer | Readers |

- |---|---|---|

- | `manuscript/_src/refs.bib` | `/lit-sync` (via Better BibTeX auto-export trigger) | `/write-paper`, `/verify-refs`, `/manage-refs` |

- | `references/zotero_collection.json` | `/lit-sync` | `/verify-refs`, `/sync-submission` |

-

- Direct hand edits to `refs.bib` are drift — revert on sight.

-

- ## Pipeline Overview

-

- ```

- .bib file (or /search-lit output)

- │

- ▼ Phase 1: Parse

- Extract DOI, PMID, title, authors, journal, year

- │

- ▼ Phase 2: Zotero Sync (owner)

- Dedupe → zotero_add_by_doi → place in collection → pin citekey

- │

- ▼ Phase 2.5: refs.bib snapshot refresh

- Trigger Better BibTeX auto-export → verify manuscript/_src/refs.bib mtime updated

- │

- ▼ Phase 2.7: Fulltext Retrieval (opt-in)

- Disk OA PDFs via /fulltext-retrieval + in-library via find_available_pdf.js → reconcile report

- │

- ▼ Phase 3: Obsidian Literature Notes

- Create Literature/{citekey}.md (empty note OK — fill later with highlights)

- │

- ▼ Phase 4: Concept Extraction (conditional)

- ≥10 literature notes → scan for cross-cutting concepts → propose concept notes

- ```

- ### Input

-

- The user-specified .bib file path, or the .bib just produced by `/search-lit`.

-

- ### Process

-

- ```python

- # Parse .bib entries with regex.

- # Extract per entry:

- # - citekey — read it from the entry, never compose one.

- # Better BibTeX keys look like `smithDeepLearningRadiology2024`

- # (author + title words + year). A key shaped like `Smith_2024_Validation`

- # or `smith2024validation` was almost certainly invented rather than read,

- # and will not resolve against the library. See Step 3.2 §Citekey provenance.

- # - doi

- # - pmid

- # - title

- # - authors (first + last minimum)

- # - journal

- # - year

- # - volume, number, pages (if present)

- ```

- Log any parse failures and skip those entries.

- ### Step 2.1: Determine project collection

- Identify the project from the current working directory or from an explicit user

- override. Reuse an existing collection key if one is recorded; otherwise create a

- new collection.

- **Collection mapping**: Check existing Zotero collections for the current project.

- If no collection exists, create one with `zotero_create_collection`. Record the

- collection key for future use.

- 2. Otherwise call `zotero_add_by_doi` (when a DOI is available) or

- `zotero_add_by_url` (falling back to the PubMed URL when no DOI is available).

- PDF URL"; other values download/import). Set it when you want a PDF attached during the

- add. 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.

- If the Zotero MCP is not connected, skip this entire phase and proceed to Phase 3.

-

- 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.

- 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.

- auto-export registrations in their own store, so that file is routinely `[]` on a

- perfectly healthy install. Treating an empty list as "not configured" skips this phase

- on working setups — and a skipped Phase 2.5 is how a stale `refs.bib` and an invented

- citekey reach a manuscript.

- In either early-exit, set `refs_bib_refreshed: false` + `reason: "precondition:<which>"` in the Step 2.5.3 JSON and return control to the caller. Record it and tell the user; nothing downstream enforces it. `verify_refs.py` has never read this flag, and the sentence that said it did was the only thing standing between a stale `refs.bib` and a manuscript.

- - If BBT auto-export path is wrong, print the expected path (`<project>/manuscript/_src/refs.bib`) and refer to `docs/zotero_policy.md` §Setup.

- If refresh failed, set `refs_bib_refreshed: false` and include `reason`. The flag records whether the export ran. It is a note to the reader, not a gate.

- There are two complementary retrieval routes; offer both and reconcile them in one report:

- import its code; invoke it by path). Resolve the engine as:

- `<worklist>` is the DOI/PMID(/Title) list — the Phase-1 `.bib` DOIs, the worklist supplied

- in the standalone mode below, or the project collection's DOIs. Output: `pdfs/*.pdf` for

- `/meta-analysis` and `pdf_to_md.py`, plus

- `pdfs/retrieval_report.json` (schema 2: retrieval `status`/`source`, `source_identity`,

- and `file_sha256`). Keep the distinction between having a file and assessing its identity.

- no-code equivalent is right-click → "Find Available PDF". This route is user-initiated and

- session-dependent; record its `{attached, missing}` summary from the printed JSON.

- `references/fulltext_retrieval.json` (owner of this file is `/lit-sync`):

-

- ```json

- {

- "schema_version": 2,

- "retrieved_oa_disk": [{"doi": "...", "source": "unpaywall", "file": "...",

- "file_sha256": "...", "title_match": "match",

- "source_identity": {"status": "unresolved", "reason": "identifier_not_found"}}],

- "retrieved_zotero_native": [{"doi": "...", "via": "addAvailablePDF"}],

- "not_retrieved": [{"doi": "...", "journal": "..."}],

- "institutional_fallback": ["<DOIs needing institutional access / ILL / author contact>"],

- "title_mismatch_flagged": ["<DOIs whose downloaded PDF title did not match>"],

- "identity_review_needed": ["<DOIs with conflict, unresolved, unavailable, or absent identity evidence>"]

- }

- ```

-

- Also append a short `fulltext` block (counts) to `references/zotero_collection.json`.

- Copy each Route A `source_identity` object in full (abbreviated above), its file hash,

- and the identity-status counts. `retrieved_oa_disk` counts file retrieval, not verified

- papers. A `consistent` status is advisory corroboration, not claim verification; a

- changed file hash needs re-assessment. Route B attachments and legacy reports without

- identity evidence remain unassessed and appear in `identity_review_needed` until reviewed.

- `not_retrieved` DOIs are candidates for institutional access, interlibrary loan, or author

- contact — never bypass paywalls or access controls from this skill.

- **Skip if the file already exists** (never overwrite).

- A literature note's filename and its `citekey:` field assert that an entry with that key

- exists in Zotero. Every downstream use depends on it: `[@key]` in a manuscript, `[[key]]`

- between notes, the Zotero Integration plugin writing `{{citekey}}.md` into the same folder.

- A key that resolves to nothing turns all three into dead ends at once — and the note still

- looks correct, which is why this goes unnoticed for months.

-

- So the key is **read, never composed**:

- 1. Take it from the `.bib` entry, or ask Better BibTeX

- (`item.search` over json-rpc — see `references/bbt_lookup.md`).

- python3 scripts/check_citekey_provenance.py --vault "$VAULT" --bib "$REFS_BIB"

- `INVENTED` means the key exists nowhere; fix it here. Match notes to papers by DOI, never by key (`AMBIGUOUS`, `UNUSABLE`,

- `NO_IDENTIFIER`: see the script's `--help`), and search the full library (`--live`) before importing anything it reports missing.

- (For a Korean-structured vault, use the Korean-heading template in `references/locale/ko/note_templates.md` and the vault's own hub-note names.)

-

- Run this phase only when there are **≥10** literature notes in the vault.

- If fewer exist, print a status message like "N literature notes — concept extraction

- unlocks at ≥10" and stop.

- Read all files under `Literature/*.md` (or the vault's existing literature folder):

- 1. Extract keywords from each paper's title, journal, and tags.

- 2. Extract major concepts from the .bib entry titles.

- 3. Identify **concepts that co-occur across ≥3 literature notes**.

- Exclude from concept candidates:

- - Model names (GPT-4, Claude, etc.).

- - Dataset names (MedQA, ImageNet, etc.).

- - Journal names.

- - Institution names.

- - Generic technique names (too unspecific).

-

- Create `Concepts/{concept name}.md` (or the vault's existing concept-note folder):

-

- ```markdown

- ---

- title: "{concept name}"

- type: concept

- tags:

- - concept

- - {domain tag}

- aliases:

- - {alternative name}

- related_papers:

- - "[[{lit-note-1}]]"

- - "[[{lit-note-2}]]"

- - "[[{lit-note-3}]]"

- status: 🌱Seedling

- ---

-

- # {concept name}

-

- ## Definition (My Understanding)

- > TODO: write in your own words

-

- ## Why it matters

- {why the concept matters in this domain — AI supplies a draft}

-

- ## Per-paper perspectives

- - **[[{lit-note-1}]]**: {this paper's angle}

- - **[[{lit-note-2}]]**: {a different angle}

- - **[[{lit-note-3}]]**: {comparison / complement}

-

- ## Related concepts

- - [[{another concept}]]

-

- ## Open questions

- - {open question 1}

- - {open question 2}

-

- ## Related notes

- - [[Research Hub]]

- - [[{related project hub}]]

- - [[{lit-note-1}]]

- - [[{lit-note-2}]]

- ```

-

- (For a Korean-structured vault, use the Korean-heading concept template in `references/locale/ko/note_templates.md`.)

- - Keep the `## Definition` section as a `> TODO` marker — the 2nd-layer note only becomes

- Create only after user confirmation. **Auto-draft but always confirm.**

- On an explicit concept-extraction request, scan existing

- `Literature/*.md` (or the vault's existing literature folder) and run only Phase 4.

- On a "tidy this project's references" request, locate `.bib` files inside the

- workspace and run Phase 1–3.

- On a "sync Zotero" request, diff the Zotero collection against the `.bib` file

- and add whatever is missing.

- When the user supplies a list of PMIDs (e.g., from a HANDOFF or a colleague), resolve

- PMIDs to DOIs via PubMed esummary first, then enter Phase 2 with the DOIs:

- For each resolved DOI, search-first with `zotero_search_items`, then call

- `zotero_add_by_doi` — the search is what dedupes (add-by-doi alone does not). For items

- already in the library (detected via `zotero_search_items` by DOI), use

- `zotero_manage_collections` to attach them to the project collection **without re-adding** —

- re-adding by URL/PubMed-URL would bypass the search dedup and create duplicates. Record both

- `added` and `existing` items in `references/zotero_collection.json`.

-

- If a PMID has no DOI in PubMed (rare; older papers, non-indexed), fall back to

- `zotero_add_by_url` with the PubMed URL and mark the entry as `no_doi: true`.

-

- ---

-

- ## Safety Rules

-

- 1. **Never overwrite literature notes** — the user may have added highlights or

- personal notes.

- 2. **Never auto-fill `## Definition` of a concept note** — keep the TODO marker; the

- essence of the 2nd-layer note is the user's own wording.

- 3. **Skip Zotero for entries without a DOI** — ask the user to add those manually.

- 4. **Gracefully skip Zotero when the MCP is not connected** — Obsidian notes are

- created independently; but do NOT hand-edit `refs.bib` to compensate (violates artifact contract).

- 5. **Always record the collection key** — report the key to the user when a new

- collection is created.

- 6. **Never write `refs.bib` directly.** Only Better BibTeX auto-export may write that file. If auto-export is broken, fix the Zotero setup rather than writing the file from this skill.

- 7. **Owner-only execution.** 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.

- 8. **Fulltext boundary (Phase 2.7).** Retrieve full text only via OA APIs (the

- `/fulltext-retrieval` engine) and the user-run Zotero "Find Available PDF" snippet

- (which uses the user's own proxy config). Never automate authenticated browser sessions,

- never bypass paywalls/access controls, and never hard-code institutional proxies,

- credentials, or hosts into this skill. `not_retrieved` items are routed to institutional

- access / ILL / author contact, not worked around.

-

- ## Anti-Hallucination

-

- - **Never fabricate DOIs, PMIDs, or citation metadata.** All bibliographic data must come from the .bib file or API responses.

- - **Never auto-fill the "Definition (My Understanding)" section** of concept notes. This must be written by the user.

- - **Never overwrite existing literature notes.** User highlights and annotations may be present.

- - If a DOI lookup fails, report the failure rather than guessing the metadata.