zotio

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-wordmark-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="docs/assets/logo-wordmark.svg">
    <img alt="zotio" src="docs/assets/logo-wordmark.svg" width="200">
  </picture>
</p>

<p align="center">
  <strong>
    The trust-and-automation layer for
    <a href="https://www.zotero.org/">Zotero</a>
  </strong>
</p>

<p align="center">
  <a href="https://github.com/OrgMentem/zotio/actions/workflows/ci.yml"><img
    src="https://github.com/OrgMentem/zotio/actions/workflows/ci.yml/badge.svg"
    alt="CI"
  /></a>
  <a href="https://github.com/OrgMentem/zotio/actions/workflows/docs.yml"><img
    src="https://github.com/OrgMentem/zotio/actions/workflows/docs.yml/badge.svg"
    alt="Docs"
  /></a>
  <a href="https://go.dev/"><img
    src="https://img.shields.io/badge/Go-1.26-00ADD8?logo=go&logoColor=white"
    alt="Go 1.26"
  /></a>
  <a href="LICENSE"><img
    src="https://img.shields.io/badge/license-MIT-blue"
    alt="MIT"
  /></a>
  <a href="https://glama.ai/mcp/servers/OrgMentem/zotio"><img
    src="https://glama.ai/mcp/servers/OrgMentem/zotio/badges/score.svg"
    alt="Glama score"
  /></a>
</p>

<p align="center">
  <strong>Docs:</strong>
  <a href="https://orgmentem.github.io/zotio/guide/install/"><strong>Get started</strong></a>
  &middot;
  <a href="https://orgmentem.github.io/zotio/reference/commands/"><strong>Commands</strong></a>
  &middot;
  <a href="https://orgmentem.github.io/zotio/guide/mcp-server/"><strong>MCP server</strong></a>
  &middot;
  <a href="https://orgmentem.github.io/zotio/concepts/write-safety/"><strong>Safe writes</strong></a>
  &middot;
  <a href="https://orgmentem.github.io/zotio/guide/workflows/"><strong>Workflows</strong></a>
</p>

<p align="center">
  <code>zotio</code> gives humans, scripts, and MCP agents local-first search
  and auditing, preview-first writes, and bounded, provenance-tagged context
  for Zotero libraries.
</p>

**Fast proof:** check a bundled library before trying zotio on your own data.

```bash
brew install orgmentem/tap/zotio        # or grab a signed binary from Releases
zotio demo                              # bundled library: 34 classic papers, one genuinely retracted
ZOTIO_DEMO=1 zotio --data-source local items retract-check  # check every DOI against Retraction Watch data
```

```console
KEY         STATUS      TYPE        NOTICE DOI                     DATE        SOURCE            TITLE
WAKEFLD98   correction  correction  10.1016/s0140-6736(04)15715-2  2004-03-06  retraction-watch  Ileal-Lymphoid-Nodular Hyperplasia, Non-Speci...
WAKEFLD98   retracted   retraction  10.1016/s0140-6736(10)60175-4  2010-02-06  retraction-watch  Ileal-Lymphoid-Nodular Hyperplasia, Non-Speci...
FAIR002016  correction  addendum    10.1038/s41597-019-0009-6      2019-03-19  publisher         The FAIR Guiding Principles for Scientific Da...
Checked 21 DOI-bearing items; 3 update notices flagged; 2 DOI(s) not registered with CrossRef.
```

That is the bundled library catching the retracted Wakefield 1998 MMR paper,
with no Zotero install and no API key (the check queries Crossref live).
`zotio demo --reset` removes it.

Zotero itself red-flags a retracted item when you open it, from the same
Retraction Watch data. `zotio` adds what the desktop app does not: corrections
and expressions of concern, a report across a whole library that scripts can
consume, and an exit code CI can fail on.

**Point it at your real library:**

```bash
zotio init                                         # guided setup: detect Zotero, key, first sync, health check
zotio items retract-check                          # the same check, against your real library
zotio library health --for citation --fail-on high # fit to cite? (exit 11 if not)
zotio items bibcheck thesis.tex --fail-on-unknown  # every \cite{} resolves? (exit 11 if not)
```

<p align="center">
  <img src="docs/assets/demos/demo-tour.gif" alt="zotio demo tour: seeding the bundled sample library, full-text search cards, duplicate detection, library stats with bar charts, and resolving the goal 'retracted papers' to a command" width="740">
</p>

---

## Why zotio

Zotero's GUI is great for reading and citing. It is painful the moment you need to *operate* on a library at scale: find every article missing a PDF, catch duplicate `\cite{}` keys before a submission, export a week of highlights, keep an Obsidian vault in sync, or hand an AI agent trustworthy context. Existing CLIs and `pyzotero` give you raw API access — then you write the glue, and you own the risk.

`zotio` is the glue, hardened:

- **Reads are local and free.** Point at your running desktop app — no API key, no cloud round-trip, works offline against a synced mirror.
- **Writes are preview-first.** Every mutation shows a plan before it touches anything. Gates cap blast radius; irreversible ops require an explicit opt-in; an append-only journal lets you undo the reversible ones.
- **Context is bounded and provenance-tagged.** Every result says where it came from and how fresh it is — so a human or an agent knows whether to trust it. `zotio` **never calls an LLM**; it does the assembly and budgeting a model is bad at, then hands off.

It is the tool you reach for when the GUI gets too manual: **find the problems that bite downstream, fix them safely, ingest with review, and give agents a surface they can trust.**

---

## How it works

Reads stay on your machine. Writes split by intent: **creating a new item (with its attachments/PDFs) prefers the local desktop connector** (`localhost:23119`, no key — the same channel the browser "Save to Zotero" button uses), while **everything else — field edits, deletes, enrichment, tag ops, moves, and `collections` create/update — routes to the Zotero Web API** and needs a configured key. The connector path is a *preference, not a guarantee*: `--via auto` uses it only on a personal library with the desktop running, and falls back to the Web API otherwise (group libraries always go to the cloud). Either way it's preview-first, the version-read happens locally, and the applied change is replayed into your local mirror so a follow-up read sees it without another sync.

![zotio hybrid routing architecture](docs/assets/architecture.svg)

| Plane | Backend | Needs a key? |
|---|---|---|
| **Read** | Local Zotero API (`localhost:23119`) + synced SQLite mirror | No |
| **Write — new item** | Local desktop connector (`localhost:23119`) when personal + desktop up; else Web API. New items, attachments, PDFs. | No (connector path) |
| **Write — everything else** | Zotero Web API (`api.zotero.org`) — edits, deletes, enrich, tags, moves, `collections` create/update | Yes — configured once |
| **External** | CrossRef · OpenAlex · Semantic Scholar · Unpaywall · OpenCitations | No (feeds enrich/import) |
| **Local-only** | Files, desktop launch, vault, introspection | No |

Run `zotio doctor` any time to see connectivity, cache freshness, and a `writes:` line telling you whether write-back is available or read-only.

---

## The flagship: `library health`

One command that answers a real question — *"is this library fit for the next thing I'm going to do with it?"* — instead of making you run six separate audits and eyeball the output.

![library health diagnostic and CI gate](docs/assets/library-health.svg)

`library health` composes the checks that already exist (citekey conflicts, duplicates, missing metadata, tag drift, broken attachments) into **one ranked, finding-typed report**. You pick what "ready" means with `--for`:

| `--for` | Prepares for | Checks |
|---|---|---|
| `quick` *(default)* | anything obviously broken | citekey conflicts, duplicates, broken attachments |
| `citation` | a manuscript bibliography | missing/duplicate citekeys, citation-core fields, duplicates |
| `systematic-review` | a PRISMA screening corpus | duplicates, screenable metadata (title/abstract), full-text PDFs |
| `vault` | a trustworthy Obsidian/PKM vault sync | missing/duplicate citekeys (note filenames), citation-core fields |
| `all` | a full sweep | every registered check |

```console
$ zotio library health --for quick
Health: needs attention
Scope: library · 846 top-level items (2103 mirrored rows) · source local · synced 1d ago · preset quick

High (13)
  [duplicate_candidates] doi="10.1002/bdm.2118" (2 items)
  [duplicate_candidates] title="Social psychology" (3 items)
  ... 11 more

Skipped (precondition unmet)
  broken_attachment_file — live check (needs Zotero desktop running); off by default.
    Fix: zotio library health --for quick --verify-files

Remediation plan (preview-first)
  duplicate_candidates — zotio items duplicates resolve --doi (preview first; add --yes after review)
```

Three things make it trustworthy, not just convenient:

- **It gates CI.** `--fail-on critical|high|info|none` exits **`11`** when the bar isn't met — drop it in a pre-submission hook. `--require-fresh 24h` exits **`12`** if your local mirror is stale.
- **It never lies by omission.** A check that needs the desktop app (broken attachments) doesn't silently vanish — it becomes a **loud skip with a remedy**, and if that skip is gate-relevant the run exits **`9`** (setup required) rather than falsely passing.
- **It points at the real fixer.** Findings carry a `recommended_action` naming the exact existing command (`items enrich`, `items duplicates resolve`, `tags audit fix`) — health *diagnoses*, dedicated commands *treat*.

### CI for your bibliography

`--badge` renders any health run as a [shields.io endpoint](https://shields.io/badges/endpoint-badge) JSON artifact — `healthy` green, findings yellow, gate-failure red, `setup required` orange:

```yaml
# .github/workflows/bibliography.yml (excerpt)
- run: zotio sync
- run: zotio library health --for citation --fail-on high --badge > badge.json
  # exit 11 fails the job when the bar isn't met; badge.json s