Word Zotero Citations

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 static DOCX audit and compare its observation with manifest acceptance counts. A failed audit blocks authorization. Existing bytes may be accepted only when identical; conflicting bytes or digest drift must fail closed.

7. Authorize Refresh, but do not execute it by default

Bind authorization to the exact manifest file/content digests, static audit, protected source, candidate, destination, report, diagnostic path, attempt id, and acceptance counts. Re-verify all paths and digests immediately before any live operation.

The optional Zotero Local API check is read-only and restricted to IPv4 loopback port 23119. Reject other hosts, ports, credentials, queries, or fragments.

If the user has not separately authorized live integration, finish here with an offline-blocked result and instructions for what would need explicit approval. If live execution is authorized, read references/live-refresh-protocol.md in full before any action.

8. Audit post-Refresh evidence

After an externally authorized Refresh has produced a destination and report, load and verify those artifacts; never synthesize a successful report. Run a post-Refresh static audit against the frozen manifest and bind it to the destination bytes.

Citation and bibliography UI evidence must come from separate disposable, cancelled checks. Persist each strict evidence record write-once. Require unchanged destination, source, and working-copy digests and stable before/open/after field snapshots.

9. Finalize write-once

Assemble finalization only when all required artifacts exist and verify:

• manifest;
• Refresh authorization;
• Refresh report;
• post-Refresh static audit;
• citation UI evidence;
• bibliography UI evidence;
• protected source;
• final destination and acceptance counts.

Freeze the finalization record write-once. Never treat a directory name, a success message, or an unbound screenshot as proof.

10. Recover or propose rollback non-destructively

Use the run journal and artifact lineage to recover only to the highest phase whose required files, hashes, parents, and state transitions still verify. Acquire the run lock before state mutation and use stale-lock recovery rules; never break a live lock.

Rollback is a proposal, not an automatic deletion or overwrite. Generate copy-only steps to a new destination and retain every source, candidate, diagnostic, audit, and journal artifact.

Read references/recovery-and-rollback.md for transition and lineage details.