zotkit: Instructions file for Codex

Instructions for AI agents

You (an AI agent) were likely given this repo because your user wants you to manage their Zotero library with zotkit. Here is exactly how to proceed. (Developing zotkit itself instead? Read CLAUDE.md, not this file.)

1. Install

pipx install zotkit    # or: uv tool install zotkit / pip install zotkit

Requires Python 3.11+. Works on macOS, Windows, Linux — no Zotero desktop app needed.

2. Configure (interactive — involve the user)

Create the credentials file from .env.example at ./.env, ~/.config/zotkit/env, or $ZOTKIT_ENV:

• Ask the user to create an API key (with write access) at https://www.zotero.org/settings/keys and tell you the key + the numeric userID shown on that page.
• If they sync attachment files via WebDAV, ask them to open the Zotero desktop app → Settings → Sync → File Syncing and read you the WebDAV URL/username/password; append /zotero/ to the URL. (If they use Zotero Storage, skip the WEBDAV_* lines entirely — attach/fetch automatically use Zotero Storage instead.)
• Never print, cat, echo, or commit the .env or any credential.

After writing the .env, run zotkit doctor — it validates config, API access, and attachment storage, and says what to fix. Don't proceed until it prints "all good". A "⚠ Zotero schema" line is a warning, not a failure: mention it to the user.

Optionally set up tag conventions from conventions.example.toml — do this WITH the user; read docs/organizing-with-agents.md first for the design principles (shallow single-axis collections, namespaced facet tags).

If the user asks you to clean up or reorganize their library — whether it's a mess or already organized — docs/organizing-with-agents.md is the complete playbook: design principles, the backup → read-only proposals → reviewed serial writes loop, and the audit checklist for second passes.