Zotero Read

Step 1: Identify the item

The caller should supply a Zotero item key (8-character uppercase, e.g. DFXGQV8D). If the user hasn't named the item precisely, use zotero-find first to resolve it.

Step 2: Gather structure and annotations (in parallel)

Before extracting content, grab abstract + outline + annotations in parallel. These tell you where to look and surface the user's highlighted passages (which are often the fastest path to the answer):

uv run zotero_read.py abstract KEY      # title, creators, year, abstract, tags
uv run zotero_read.py outline KEY       # section headings with page numbers
uv run zotero_read.py annotations KEY   # user highlights and notes

Run these as three parallel tool calls in one turn.

The outline output comes from the PDF's embedded outline when present (common for arxiv preprints, LaTeX/elsarticle papers, books with real TOCs) or from a heuristic scan of the first 20 pages (for older scans, thesis PDFs, or papers without embedded metadata). The JSON includes source: "embedded" | "heuristic" so you know which you got.

Why annotations first: if the user has highlighted relevant passages, those are the fastest path to the answer — no page scanning needed.

Step 2b: Search within the PDF (when you know what but not where)

If the user asks about a specific term/concept and the outline doesn't make it obvious which pages to read, use search to locate it:

uv run zotero_read.py search KEY "vertex-patch"

Returns all pages containing the term (case-insensitive) with surrounding-line context snippets. Use the page numbers from the results to target your pages extraction in Step 3.

This bridges the gap between fulltext (fast but no page numbers) and pages (precise but requires knowing which pages). Especially useful for large documents where scanning the outline isn't enough.

Step 3: Decide extraction strategy

Short papers (~20 pages or fewer)

Use the fulltext subcommand — it returns Zotero's pre-indexed text, no PDF download, no page numbers needed:

uv run zotero_read.py fulltext KEY

Output includes content (the full text) plus indexed_pages and total_pages. Fast and zero-cost.

Large documents (books, long papers) — two-phase

Phase 1: targeted extraction. Scan the full outline (from Step 2) for sections relevant to the user's question. A topic may appear in multiple chapters. Pick the top 3–4 most relevant sections (~30 pages total), and extract them in parallel:

uv run zotero_read.py pages KEY 14-18    # Section 4.2
uv run zotero_read.py pages KEY 19-21    # Section 4.3
uv run zotero_read.py pages KEY 5-7      # Section 2.1 for background

The first call downloads the PDF and caches it; subsequent calls use the cache (~1s vs ~3s).

Present Phase 1 results first. If the user wants more depth, extract additional ranges in Phase 2.

Phase 2: deeper extraction (on request)

If the user says "tell me more" or "what about section X", pull additional page ranges using the same pages subcommand. The outline and Phase 1 results inform where to look next.

Step 4: Page range output format

pages KEY RANGE returns JSON:

{
  "item": "DFXGQV8D",
  "attachment": "4DQ2NUMB",
  "citation": "Wichrowski (2025)",
  "total_pages": 21,
  "requested_range": "1-2",
  "extracted_range": "1-2",
  "text": "\n--- Page 1 ---\n<content>\n\n--- Page 2 ---\n<content>\n"
}

The text field has --- Page N --- markers between pages so you can attribute quotes to specific pages. Use the citation field for short inline references.

Step 5: Present with separation of source and summary

The user must always distinguish between what the document says and your interpretation. Mixing these presents hallucinated content as real.

Structure every finding as:

1. Direct quote — blockquote with exact page reference:

"The exponential filter is applied in the modal space, damping the highest-order modes..." — Hesthaven & Warburton (2008), Section 6.1, p. 134

2. Your summary — clearly labeled:

Summary: The authors use modal filtering to stabilize aliasing-driven instabilities. The filter transfer function (Eq. 6.3, p. 134) controls which modes are damped.

Rules

• Quote first, summarize second. The quote is evidence; the summary is your reading.
• Never fabricate quotes. If you cannot find exact wording, write "The authors discuss [topic] in Section X.Y (pp. N–M)" — don't make up text.
• If uncertain, say so. "I could not find a direct discussion of X in the extracted pages" is better than guessing.
• Page numbers must be verifiable. Only cite pages from content you actually extracted via pages KEY RANGE. Text from fulltext has no page attribution — don't invent page numbers for it.
• Include equation/figure/table numbers when they appear in the text.

Citation format:

• (Author Year, Section X.Y, p. N) for single pages
• (Author Year, Section X.Y, pp. N–M) for ranges

Step 6: Citations on request

uv run zotero_read.py bibtex KEY

Returns the item's BibTeX entry directly from Zotero (includes the citekey Zotero has assigned).

Subcommand reference

Tips

• Embedded outlines vary by PDF source. Arxiv preprints almost always have one; older scanned books may not. The heuristic fallback works but is noisier — expect false-positive headings.
• Annotations are the fastest signal. If the user highlighted something, start there before scanning.
• Prefer fulltext over many pages calls for short papers — one HTTP call instead of downloading the PDF.
• The cache persists across runs in /tmp/zotero-cache/. Repeated reads of the same paper are instant.
• If a Zotero item has no stored PDF (linked file instead of synced attachment), the pages/outline/annotations/fulltext subcommands will exit with code 3 and a clear message. Fall back to abstract or metadata and inform the user.

Exit codes

• 0 success
• 1 HTTP or PDF parse error
• 2 missing env vars, invalid arguments, or invalid page range
• 3 no stored PDF attachment under the item