## Spec: biblio ↔ Zotero integration model¶

Biblio complements Zotero (collectio

Goal¶

(promoted from note)

Context¶

(see source note)

Prompt¶

Fix the issue described in /storage2/arash/projects/projio/docs/log/issue/issue-arash-20260403-201609-055675.md. Read it first, then implement the proposed fix.

Acceptance Criteria¶

[ ]

Result¶

Completed in 229.4s (1 steps, model: opus)

Session: 9428acf7-cf21-44d1-8fcf-3edcd2d7b6df Result note: /storage2/arash/worklog/workflow/captures/20260403-202019-c70a59/note.md

Output¶

Spec written to `docs/specs/biblio/zotero-integration.md`. It covers:

- **Data flow diagram** (Zotero ↔ biblio ↔ OpenAlex)
- **Authentication** — API key (cloud) and local API (Zotero 7), config model under `zotero:` section in biblio.yml
- **Phase 1 (pull)** — Incremental version-based sync, BibTeX to `srcbib/zotero.bib`, PDF download, sync state in `zotero_sync.yml`, citekey strategy (Zotero vs biblio mode)
- **Phase 2 (push-back)** — Tags with `biblio:` namespace, child notes for summaries, DOI/OpenAlex ID write-back, optimistic concurrency conflict handling
- **Architecture decisions** — pyzotero as optional dep, coexistence with manual srcbib workflow, DataLad/pool interaction, project-level sync (not pool-level)
- **Module layout** — `biblio/zotero.py` with `ZoteroClient`, `SyncState`, orchestrator functions
- **CLI/MCP surface** — `biblio zotero pull/push/status/init` + 3 MCP tools
- **3-phase implementation plan** with dependencies

## Next Steps

1. Implement Phase 1 (read-only pull) in `packages/biblio/src/biblio/zotero.py` — start with `SyncState`, `ZoteroClient.pull_items()`, and the CLI command.
2. Add `pyzotero>=1.6` to biblio's optional dependencies and wire up the `zotero` config section in `packages/biblio/src/biblio/config.py`.
3. Register `biblio_zotero_pull` and `biblio_zotero_status` MCP tools in `src/projio/mcp/biblio.py`.