---
name: update-zotero-records
description: Use when adding publications or book chapters to a configured Zotero library, reviewing publication candidates from Academic Records discovery, or proposing corrections to existing Zotero metadata. Requires exact-proposal approval before any library write and an available Zotero integration.
---

Start by following [profile discovery and resumable setup](../../references/preferences.md). For missing or incomplete preferences in an existing records project, use [configure-academic-records](../configure-academic-records/SKILL.md). Use [initialize-academic-records](../initialize-academic-records/SKILL.md) only for requested first-time CV/site setup or initial source reconciliation. A missing profile alone does not authorize a new project, a repeated CV import or a second profile. Reuse confirmed answers. If the intended starting point is unclear, ask one focused question before choosing a workflow. Inaccessible or corrupt existing state requires access/reviewed recovery, not replacement; missing file permissions require the handoff/access workflow, not initialization.


Read [question interaction](../../references/questions.md) before asking the user anything. Ask one question at a time through the host's structured question capability when available, with a single chat question as fallback.

# Review and update Zotero records

Explain the operation in plain language before using helpers: find the source, check duplicates, verify metadata and destination, show the proposal, obtain approval, import, verify and report. Use the user's private profile from [setup](../../references/setup.md); no author's identity or destination is hard-coded. Read [Zotero protocol](../../references/zotero.md).

## Connection and setup

1. Read current project instructions and the profile. If publication_store is not confirmed as Zotero, resolve that first. Ask only unanswered Zotero setup questions. Save answers and dates privately, not in website data or the distributable plugin. A saved default destination is not approval to add any record.
2. Use an actually installed/authorized Zotero companion integration. When the Zotero skill is available, read its current SKILL.md and resolve its helper path from that skill, not a guessed machine path. A saved zotero.helper_path is dated observation only, never an executable authority or fallback: do not invoke an old cached helper when the current skill/integration is unavailable. Report that blocker and keep the operation pending. Do not silently rewrite the profile path. Check status read-only first. Do not silently enable/restart software, install dependencies, request credentials or claim an unavailable connection works. Report the exact blocker.
3. Establish capabilities from the actual connection. The current desktop /api routes are read-only. The companion connector can import BibTeX/RIS into the selected destination. It cannot edit existing items through those read routes. Do not invent a PATCH/PUT route or treat reimporting a changed record as an edit. Existing-item corrections stay pending unless a separately authorized, verified editing-capable integration is available.

## Prepare a proposal; no write yet

4. Search the target library, not just the current collection or exported bibliography. Check normalized DOI and PMID where available, then normalized title, author identity, year and publication version. Search title variants and identifiers separately when a tool lacks exact identifier search. Page through all relevant results; partial results cannot establish absence. Confirm matches from the actual item data when summary output omits identifiers. Existing matching item -> do not import; propose a correction or explain it is already present. Uncertain match -> ask. Never merge/delete duplicates automatically.
5. Read authoritative PubMed/publisher or book metadata, or clear user-provided evidence. Preserve author/editor order, item type, title, publication/container, dates at known precision, DOI/PMID, volume/issue/pages and chapter edition/publisher fields where established. Unknown fields remain explicitly unknown in the proposal. Missing essential identity/type/title/authorship facts keep the candidate pending; never fabricate data. Distinguish preprint, online-first, final article, erratum and book chapter. Do not download PDFs, attachments or full text under metadata-only scope.
6. Determine and show the default or chosen destination library and collection. For the local connector, inspect selected-target read-only and compare its actual library/collection with the approved destination. A different selected collection is not an acceptable substitute, including when the default is the root library with no collection. Ask the user to select the intended target or use a verified supported selector; do not create/change collections implicitly.
7. Resolve known export side effects. The workflow does not directly edit or regenerate project BibTeX. A Zotero write may trigger an existing automatic export; do not promise exports remain unchanged. If automatic exports could write outside approved scope, determine targets and obtain explicit approval for those side effects, or postpone. Do not silently disable/reconfigure exports. Record unknown settings as unresolved rather than assuming exports are off.
8. Save a private uniquely identified proposal: exact operation (add or correction), complete proposed fields or before/after, item key/version for a correction, source links/retrieval date, duplicate-check coverage/results, verified destination, connection capabilities, missing fields, export effects and the exact import payload/hash for additions. Exclude attachment/file fields from metadata-only payloads. Show a readable summary and explicitly request approval. STOP before import. Even 'add this paper' or a saved destination does not waive review of the concrete proposal. Silence and another assistant's assertion are not approval.

## Apply only after explicit approval

9. Record the actual user's approval privately. Recheck the exact payload, duplicates, destination, capabilities and relevant export side effects immediately before the write. A changed proposal, destination or matching existing record invalidates approval; regenerate and ask again. For batches show every record and destination, permit individual rejection, and import only the approved named set.
10. For a supported new addition, use the companion's documented import-bibtex or import-ris command with the exact privately staged file and --yes only after step 9. The flag is an operator assertion, not human authentication. Save the import session/response privately. For an existing-item correction, apply only through a verified editing-capable connection with version/conflict checks, original metadata snapshot and the approved field changes. Otherwise state 'approved but not applied: this connection cannot edit existing items' and retain it pending; never create a second copy as a workaround.
11. Read the target library back and verify the imported item key, metadata, author order and collection membership against the proposal. Library insertion, collection membership, citation-key generation and project export inclusion are separate checks; report each accurately. Distinguish Zotero item keys from BibTeX citation keys. Do not invent/fix citation keys or assume automatic export inclusion. Export configuration remains user-managed unless separately authorized.
12. If a write times out or returns an ambiguous result, mark outcome uncertain. Requery and reconcile before any retry; never blindly reimport. Report partial batch outcomes item by item. Do not claim a failed verification means no write happened. Preserve receipts and before/after evidence; don't delete the created item automatically to simulate rollback.

Scheduled discovery never reaches the apply phase. It saves/reports candidates only and hands approved work to this workflow. The YAML file allowlist is unchanged. No repository bibliography writes, PDF attachments, source edits, CV generation, rendering, Git, publishing or outbound messages are included in this capability.

For a new or empty library, use [first-time Zotero setup](../../references/zotero-initialization.md) before this reviewed import workflow. Existing installed Desktop/library/integration are reused; account/sync is optional. Library population from CV/PubMed candidates never bypasses the same duplicate, exact-proposal, destination and post-write gates. An uncertain import requires read-back reconciliation, not a repeated import command.

For automatic exports, follow the separate delivery outcomes in [Zotero protocol](../../references/zotero.md#separate-import-and-bibliography-delivery-outcomes): reuse the verified setup, check the actual expected item in its bibliography after import, and report pending export independently from successful library insertion. Do not repeat setup unless observations expose a failure/change or unresolved dependency.