/word-zotero-citations

name: word-zotero-citations
description: Build, audit, authorize, recover, or finalize dynamic Zotero citations and bibliographies in Microsoft Word DOCX files with a protected-source, digest-bound workflow. Use for Word–Zotero citation conversion, static OOXML citation audits, mocked/offline validation, Refresh authorization/report review, UI-evidence contracts, run recovery, or rollback proposals; never perform live Word/Zotero integration without separate explicit authorization.

Word–Zotero citations

Use the generic `zotero_mcp.word_citations` workflow to replace citation markers in a DOCX with dynamic Zotero fields while keeping the source immutable and every mutating gate explicit, digest-bound, and auditable.

Safety boundary

Default to offline and static work.

Do **not** do any of the following unless the user separately authorizes the exact live integration step:

• launch Microsoft Word or create Word COM automation;
• run `refresh_word_zotero.ps1`;
• invoke `ZoteroRefresh` or another Zotero Word macro;
• write to a Zotero library or staging collection;
• contact a Zotero Local API other than an explicitly approved read-only check on `http://127.0.0.1:23119`;
• overwrite the source DOCX, a frozen manifest, audit, authorization, UI-evidence file, report, or finalization record.

Authorization to create or edit implementation files is not authorization to run Word or Zotero. If live authorization is absent, stop at the offline gate and state exactly which live action remains unexecuted.

Applicability

Use this Skill when the request involves one or more of:

• scanning Word OOXML for DOI, DOI URL, bare DOI, or explicit `PMID: 12345678` markers;
• inferring citation clusters and preserving repeated item occurrences;
• planning or mocking Zotero item resolution and staging;
• constructing or auditing Zotero citation/bibliography fields in DOCX;
• freezing a citation manifest and acceptance counts;
• auditing a candidate before or after Refresh;
• reviewing or producing a digest-bound Refresh authorization contract;
• persisting citation and bibliography UI evidence from an already authorized disposable check;
• finalizing a run, recovering state, or generating a non-destructive rollback proposal;
• implementing, documenting, or testing the generic Word–Zotero package without case-specific historical imports.

Do not use this Skill for ordinary citation-style advice, manual bibliography prose, Zotero library cleanup unrelated to Word fields, or a request that only asks to install Zotero/Word.

Required inputs

Establish before any phase that needs them:

1. source `.docx` path; 2. target CSL style id or `.csl` path; 3. isolated runs root and stable task id; 4. requested phase and whether only offline/static work is authorized; 5. Zotero library identity and collection only when staging or visibility is in scope; 6. explicit destination/report paths for Refresh and finalization; 7. expected acceptance counts from the frozen manifest.

If a required path, identity, count, or authorization is missing, do not infer it. Continue only with phases that can be proven from available artifacts.

Workflow

1. Discover the implementation and freeze boundaries

Locate the repository rather than assuming a machine-specific path. Confirm that it provides:

• package `zotero_mcp.word_citations`;
• entry point `zotero-word-citations` or module CLI;
• offline tests for the requested phase;
• the PowerShell wrapper only as an inspectable artifact.

Read `references/implementation-map.md` when modifying code or locating phase ownership. Read `references/contracts.md` when assembling, loading, or verifying persisted JSON artifacts. Read `references/live-run-recipe.md` when reproducing a live run end to end, and `references/zotero-mcp-configuration.md` when the Zotero MCP connector is in local-only mode or write tools fail.

2. Preflight without mutation

Run the read-only preflight before scanning or creating a run. Treat its status as a gate:

• `blocked`: stop and report failed checks;
• `manual_review`: explain the unresolved condition and do not advance automatically;
• safe/approved read-only result: continue with the requested offline phase.

Preflight must not create run directories, copy the source, connect to Word, or write to Zotero.

3. Scan and cluster the DOCX statically

Use OOXML/ZIP parsing, not Word automation. Preserve source size and SHA-256 and verify the expected digest when one is supplied.

Recognize only supported explicit identifiers. Ordinary numbers are never PMIDs. Inspect all relevant Word stories, surface malformed fields, revisions, static references, and unsupported placements, then infer clusters deterministically. Any ambiguous boundary or unsupported story is a manual-review condition, not permission to guess.

4. Plan Zotero resolution before any write

Resolve identifiers against a read gateway first. Fail closed on missing or ambiguous matches. If new items would be required, create a staging plan and exact authorization; do not execute it under the default offline boundary.

Keep collection identity, library identity, requested identifiers, planned item keys, and occurrence counts stable. Use mocks or synthetic gateways for validation.

5. Build a candidate in an isolated run

Never edit the source in place. Create or verify the isolated run layout, copy to a candidate path, and protect source/candidate digests across every transformation.

Construct valid complex `ADDIN ZOTERO_ITEM CSL_CITATION` fields and one dynamic `ADDIN ZOTERO_BIBL` field with required document preferences and OPC relationships. Preserve repeated occurrences and do not import case-specific scripts from historical projects.

6. Freeze manifest and pre-Refresh audit

Assemble the manifest only from accepted upstream scan, cluster, item visibility/staging, and candidate facts. Freeze it write-once using canonical JSON plus SHA-256.

Run the stati