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.

Execution autonomy and confirmation policy

The 2026-08-15 live test revealed that requiring a human confirmation at every step is unnecessary. Adopt this policy:

• No confirmation needed for: reading, scanning, clustering, planning, Zotero read/visibility checks, manifest/audit/authorization freezing, candidate construction, post-Refresh audits, finalization, and any offline or mocked validation. The agent should execute these autonomously and continue until it either produces the final deliverable or hits a hard blocker.
• One confirmation needed for each distinct live integration family, given up front by the user with explicit scope:
  1. writing to Zotero (create the task collection, add collection membership; never merge/delete items without separate approval);
  2. launching Word and running the Refresh wrapper with exactly one ZoteroRefresh call;
  3. launching Word for the two cancelled disposable dialog checks (ZoteroAddEditCitation, ZoteroAddEditBibliography).
• The user may grant a standing authorization (e.g. continue until success) for a specific task. Under a standing authorization the agent runs each live family at most once per distinct attempt, and if a live attempt fails it stops that family, fixes the root cause offline (with a regression test), creates a fresh attempt id and paths, and only then proceeds. It never re-runs the same authorization.
• If the user grants standing authorization, the agent must still stop for a genuine human-in-the-loop condition: Zotero login/challenge dialogs, Word license/first-run dialogs, ambiguous duplicate-item selection that cannot be resolved by the frozen selection rule, or a structural blocker that no parameterized retry can fix.

Dependencies and setup (tell the user before a live run)

Before any phase that touches live Word/Zotero, state these dependencies and help the user satisfy them:

1. Zotero desktop running, with its Local API on 127.0.0.1:23119.
2. Microsoft Word installed (only the Refresh and UI-evidence steps need COM automation; scan/build/audit are OOXML-only).
3. The zotero_mcp package importable from Python. Locate it (installed package, repository src, or a .venv) and tell the user how it will be invoked (e.g. PYTHONPATH or the interpreter). If it is missing, stop with the exact install/locate step instead of guessing.
4. zotero-mcp hybrid mode configured: ZOTERO_LIBRARY_ID + ZOTERO_API_KEY in ~/.config/zotero-mcp/config.json under client_env (see references/zotero-mcp-configuration.md), followed by a connector restart. If writes fail with "local-only mode", do not retry; re-check this step.
5. Before live execution, show one import check (python -c "import zotero_mcp") and confirm the Local API port.

The agent should proactively point the user to references/zotero-mcp-configuration.md (credentials) and references/live-run-recipe.md (end-to-end run) whenever a dependency check fails or the user asks how to set something up.

Scripts and reproducibility

All reusable scripts live inside this Skill under scripts/ (they are copied into the archive and are usable wherever the Skill is installed):

• scripts/run_live_workflow.py — parameterized offline phases (candidate-build, authorize, post-refresh-audit, finalize).
• scripts/refresh_word_zotero.ps1 — the one-shot live Word/Zotero Refresh wrapper (executed only under authorization).
• scripts/validate_word_zotero_ui.ps1 — cancelled disposable dialog evidence.
• scripts/verify_skill.py — offline structural verification of this tree.

These scripts are generic: they take --run-root, --task-id, --source, --selection, --style-id and read ZOTERO_LIBRARY_ID/ZOTERO_API_KEY from the zotero-mcp configuration. They must never contain machine-specific paths or user identity. See references/live-run-recipe.md for the end-to-end sequence and references/zotero-mcp-configuration.md for connector setup.

Final delivery

• The delivery directory contains exactly two files: the finalized citation DOCX (copied from the finalization-bound destination) and a copy of the user's original DOCX. The user's original file itself is never moved or modified.
• Naming and destination are decided by the user. The agent proposes a name (e.g. <original-stem>_引文完成版.docx) and a delivery directory, then waits for the user to confirm before copying anything. Never invent a final name or path.
• Test/intermediate artifacts (candidates, audits, reports, UI working copies, diagnostics, manifests, run state) never enter the delivery directory. Evidence under the run root is retained by default; deleting it requires an explicit user decision.
• Before delivery, verify the SHA-256 of both files against the finalization record. If the user has since opened and saved the finalized document in Word, the record's hash will differ; in that case deliver the user-confirmed version and record its actual hash with a note that the finalization record applies to the audited bytes.
• No test, audit, or live integration is rerun for delivery itself.

Verification

For implementation or Skill changes, use offline/static verification only:

1. focused tests for touched phase(s);
2. complete tests/word_citations suite;
3. relevant Ruff checks;
4. PowerShell AST parse without running the wrapper;
5. protected-baseline hash test;
6. full project test suite with explicit exit-code propagation when feasible;
7. scripts/verify_skill.py for this Skill tree;
8. bundled skill-creator/scripts/quick_validate.py and packaging utility.

Use references/verification-matrix.md for exact categories and stop conditions. Never report a passing run when pytest output contains failures, a timeout, or KeyboardInterrupt, even if a detached host reports exit code 0.

Output contract

Report:

• requested and completed phase(s);
• source and destination protection status;
• artifacts created or verified, including paths and SHA-256 where material;
• acceptance counts and gate outcomes;
• tests/lint/static checks with exact pass/fail totals;
• any blocked or manual-review condition;
• whether Word, ZoteroRefresh, Zotero Local API, or Zotero writes were executed.

A default offline run must state explicitly: Word not launched; Refresh wrapper not executed; Zotero not modified.