zotlit-citations

ZotLit citations

Start

Complete these steps in order before you answer a citation question.

1. obsidian help zotlit — use only the commands and parameters it reports; commands reject what they do not declare.
2. obsidian zotlit:citations-guide — the installed version's field semantics and workflow.
3. obsidian zotlit:template-status — read identity.source.id from its answer, then pass expect-source=<source-id> on every later call.

Read the guide again after a ZotLit update.

This skill is written against citations CLI Contract version 3 — the contractVersion a cited-by or references answer carries. When an answer reports another number, run zotlit:citations-guide again and follow the live guide over this skill. Step 3 belongs to another namespace: zotlit:template-status reports the Template Workbench's own contract version, which moves on its own.

Target one vault and one Zotero library

Put vault=<vault-name> first when the working directory does not select the vault unambiguously:

obsidian vault=MyVault zotlit:citations-guide

obsidian vault shows the active vault, obsidian vaults lists all known vaults. Confirm identity.vault once, then keep the same prefix.

Keep expect-source= on every call rather than trusting the library to stay connected. A user with more than one Zotero profile gets a wrong answer, not an error, when it is left off.

Choose the selector

Ask the vault, never the filesystem: a text search over the vault misses the citation-key resolution, the user's citation-source choices, and the wikilink rules the index applies. Match the question to one selector:

• A work the user names by its Zotero key — query by key.
• A work the user names by a citation key they saw in text, such as @doe2020 — query by citation key, with no lookup step first.
• A work the user points at through a Literature Note — take the Zotero key from that note, then query by key.
• A work the user names only in prose — ask which item they mean, or ask them to point at the note. Do not guess an item.
• A document — query its references by its vault path. Ask this of the user's own writing as readily as of a Literature Note.

Read context from positions

The answers report where each citation is, not what surrounds it. When the user needs context:

1. Open the reported path.
2. Read the file at the reported position.
3. Widen to the sentence, paragraph, or section the question needs.

Quote the file you read, and name the note it came from. Never present text as something a command returned.

Diagnose broken citations

Run the document's references, then group the entries by kind and turn each broken kind into the one correction its user can make — a citation key to fix in the note, or a work to add to Zotero.

Every such fix edits the user's writing or their Zotero library. Propose each change and wait for the user to accept it.

Report what the answer is worth

Read omittedSyntaxes before you report any answer. An empty list means the answer is whole. When it names a syntax, say the answer is short — this note or work carries citations written that way and the answer leaves them out — and name the setting the guide gives for that syntax. Leave the change to the user.

When the payload reports a degraded index state, give the answer and say plainly that it may be incomplete. When a call fails, follow the recovery action in diagnostic.hint before you retry, and tell the user what you changed.

Tone

Use plain language and name each step in everyday terms ("let me check which notes cite this paper"). Report notes by their path or title and works by their summary; add a Zotero key only when the user needs it for another command. Introduce a term such as citation key once, then use it freely.