zotero-agent 0.2.0__tar.gz

zotero_agent-0.2.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,37 @@
+name: Bug report
+description: Something isn't working
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: Thanks for the report! Please include the diagnostics below — they resolve most issues quickly.
+  - type: textarea
+    id: ping
+    attributes:
+      label: Output of `zot ping`
+      description: Run `zot ping` and paste the full output.
+      render: text
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: Output of `zot --version`
+      placeholder: zot (zotero-agent) 0.2.0
+    validations:
+      required: true
+  - type: input
+    id: platform
+    attributes:
+      label: Platform + Zotero version
+      placeholder: macOS 14 / Zotero 7.0.15
+    validations:
+      required: true
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened
+      description: What you did (the exact command or agent prompt), what you expected, and what happened instead.
+    validations:
+      required: true

zotero_agent-0.2.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/alex-roc/zotero-agent/security/advisories/new
+    about: Please report security issues privately, not as a public issue.
+  - name: Question / discussion
+    url: https://github.com/alex-roc/zotero-agent/discussions
+    about: Ask a question or share how you use zotero-agent.

zotero_agent-0.2.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,21 @@
+name: Feature request
+description: Suggest an idea or a new command/tool
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem / use case
+      description: What are you trying to do with your Zotero library that's hard today?
+    validations:
+      required: true
+  - type: textarea
+    id: idea
+    attributes:
+      label: Proposed solution
+      description: A command, MCP tool, or behaviour you have in mind (rough is fine).
+  - type: dropdown
+    id: surface
+    attributes:
+      label: Which surface?
+      options: ["CLI", "MCP server", "Claude Code skill", "the bridge plugin", "not sure"]

zotero_agent-0.2.0/.github/pull_request_template.md

@@ -0,0 +1,17 @@
+<!-- Thanks for contributing! Keep the core stdlib-only and writes guarded. -->
+
+## What & why
+
+<!-- What does this change and what problem does it solve? -->
+
+## How I verified
+
+- [ ] `python -m unittest discover -s tests` passes
+- [ ] `uvx ruff check src tests cli/zot` is clean
+- [ ] Rebuilt the XPI (`bash plugin/build.sh`) if the plugin changed
+- [ ] Updated `docs/` / `skill/` / `CHANGELOG.md` (Unreleased) if behaviour changed
+- [ ] (If a live test was relevant) ran `zot ping` / the affected command against a real library
+
+## Notes
+
+<!-- Anything reviewers should know: trade-offs, follow-ups, screenshots. -->

zotero_agent-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,57 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Run tests (stdlib only, no network)
+        run: python -m unittest discover -s tests -v
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/ruff-action@v3
+        with:
+          args: check src tests cli/zot
+
+  build-xpi:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Build the bridge XPI
+        run: bash plugin/build.sh
+      - name: Verify the XPI is a valid zip with a manifest
+        run: |
+          unzip -l dist/zotero-agent-bridge.xpi | grep -q manifest.json
+      - uses: actions/upload-artifact@v4
+        with:
+          name: zotero-agent-bridge-xpi
+          path: dist/zotero-agent-bridge-*.xpi
+
+  build-package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build wheel + sdist
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*.whl

zotero_agent-0.2.0/.github/workflows/pages.yml

@@ -0,0 +1,68 @@
+name: Deploy docs to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'web/**'
+      - '.github/workflows/pages.yml'
+  workflow_dispatch:
+
+# Allow the GITHUB_TOKEN to deploy to Pages.
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment; don't cancel in-progress production deploys.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+defaults:
+  run:
+    working-directory: web
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 11
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: web/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build with Astro
+        run: pnpm build
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: web/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

zotero_agent-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,44 @@
+name: Release
+
+# Tag a version (vX.Y.Z) to build the XPI + wheel, publish a GitHub Release with
+# the XPI attached, and publish the package to PyPI via Trusted Publishing.
+#
+# One-time setup on pypi.org: add a Trusted Publisher for this repo + workflow
+# (Publishing → Add a new pending publisher) so no API token is needed here.
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write        # create the GitHub Release
+  id-token: write        # PyPI Trusted Publishing (OIDC)
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+      - name: Build wheel + sdist (into dist/)
+        run: uv build
+
+      - name: Build the bridge XPI (into release-assets/, keeping dist/ PyPI-only)
+        run: |
+          bash plugin/build.sh
+          mkdir -p release-assets
+          mv dist/zotero-agent-bridge-*.xpi release-assets/
+          rm -f dist/zotero-agent-bridge.xpi   # drop the symlink so dist/ is PyPI-only
+
+      - name: Create GitHub Release with the XPI
+        uses: softprops/action-gh-release@v2
+        with:
+          files: release-assets/zotero-agent-bridge-*.xpi
+          generate_release_notes: true
+
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist          # wheel + sdist only
+          verbose: true

zotero_agent-0.2.0/.gitignore

@@ -0,0 +1,26 @@
+# Built artifacts (produced by plugin/build.sh)
+/dist/
+
+# Self-contained skill bundle (produced by install.sh from cli/ and plugin/)
+/skill/scripts/
+
+# OS / editor cruft
+.DS_Store
+*.swp
+
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+.venv/
+
+# Website (Astro Starlight)
+/web/node_modules/
+/web/dist/
+/web/.astro/
+
+# Release scratch
+/release-assets/
+
+# skill-creator eval workspace (artefactos + backup)
+/zotero-workspace/

zotero_agent-0.2.0/AGENTS.md

@@ -0,0 +1,65 @@
+# AGENTS.md — driving Zotero with the `zot` CLI
+
+This file gives coding/agent tools (Codex CLI, Gemini CLI, Aider, and any agent
+that reads `AGENTS.md`) what they need to control a **local Zotero library**
+through the `zot` command. It mirrors the Claude Code skill in `skill/SKILL.md`.
+
+## Setup check
+
+Run `zot ping`. It must show the local API up, the bridge endpoint answering
+`1+1 == 2`, and a known userID. If it fails, the bridge plugin isn't installed —
+see `docs/install.md`; do **not** work around it.
+
+## Reading (fast, prefer these)
+
+```bash
+zot search "<query>" [--limit N] [--tag T] [--item-type book]   # full-text
+zot get <KEY|@citekey>          # one item's fields
+zot pdf <KEY|@citekey>          # local PDF path(s) — then read the file directly
+zot collections | zot tags      # list
+zot stats                       # analytics
+zot missing abstract|date|doi [--collection C]
+zot author "<name>"  |  zot recent  |  zot lint
+```
+
+Add `--json` to any command for machine-readable output.
+
+## Writing (guarded — pass `--yes` for non-interactive)
+
+```bash
+zot add doi|isbn|arxiv <id> [--pdf] [--collection C]
+zot set <field> <value> <KEY…> --yes
+zot tag add|rm <tag> <KEY…> --yes   |   zot tag rename <old> --new <n> --yes
+zot move <collection> <KEY…> --yes
+zot note <KEY> --file note.html
+zot dedupe [--by title|doi] [--fuzzy] [--merge --yes]
+```
+
+## Batch edits (preferred for anything at scale — undoable)
+
+Write a JSONL file, one edit per line, then apply it:
+
+```jsonl
+{"key":"ABCD1234","set":{"abstract":"…","date":"2021"},"addTags":["review"]}
+{"key":"EFGH5678","addToCollection":"To Read","removeTags":["old"]}
+```
+
+```bash
+zot apply edits.jsonl --dry-run     # preview
+zot apply edits.jsonl               # apply (snapshots first)
+zot undo last                       # roll back the last apply/enrich
+```
+
+**You** decide the values (e.g. cleaned titles, topic tags) and write the JSONL;
+`zot` performs the writes. The CLI never calls an LLM itself.
+
+## Safety rules (follow these)
+
+1. `zot backup` before any bulk or destructive change — always before `dedupe --merge`.
+2. Prefer `--dry-run` and scope with `--collection` before touching the whole library.
+3. Apply to 1–2 items and verify before the full set.
+4. Deletions: prefer trash (`"trash": true` in `apply`), not permanent erase.
+5. Merges are **not** reversible; everything via `zot apply`/`zot enrich` is.
+
+Full JS recipe book: `skill/references/recipes.md`. PDF/notes workflow:
+`skill/references/pdf-and-notes.md`.

zotero_agent-0.2.0/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Fixed
+- **`apply`/`update_items` dry-run no longer executes any JS**, so it can never
+  persist changes (the old monkey-patch-`save()` interception could leak writes
+  on Zotero 7). The preview is reported straight from the parsed edits.
+- `dedupe --fuzzy` is now tractable on large libraries (prefix-blocking instead
+  of O(n²) over the whole library) — seconds instead of timing out.
+- Bridge/read calls that time out now return a clean error instead of an
+  uncaught traceback (`post_code` and `main` handle `TimeoutError`/`OSError`).
+- `exec --dry-run` now states honestly that it executes the script with
+  best-effort interception and may still persist (backup is the guarantee).
+
+## [0.2.0] — 2026-07-23
+
+The project was renamed from `zotero-cli-skill` to **`zotero-agent`** and rebuilt
+into an installable Python package with an MCP server.
+
+### Added
+- **Python package** `zotero-agent` (installable from PyPI; entry point `zot`).
+  The former single-file CLI is now a modular package under `src/zotero_agent/`.
+- **MCP server** (`zot mcp`) exposing ~18 high-level tools to any Model Context
+  Protocol client (Claude Desktop, Codex CLI, Gemini CLI, Cursor). Optional
+  `[mcp]` extra.
+- **`zot apply`** — declarative JSONL batch edits (set fields / add-remove tags /
+  add to collection / trash), with a pre-image snapshot.
+- **`zot undo`** — restore items to their state before an `apply`/`enrich`.
+- **`zot enrich`** — fill missing DOI / date / abstract from Crossref or OpenAlex.
+- **`zot tag normalize`** — fold case- and whitespace-variant tags together.
+- **`zot dedupe --fuzzy`** — group near-identical titles (Levenshtein).
+- **Audit log** of every bridge execution at `~/.local/state/zotero-agent/audit.jsonl`.
+- `--version` flag; `--json` is now a global flag on every command.
+- Fake-Zotero test server; expanded unit + integration tests. CI on GitHub Actions.
+
+### Changed
+- **Rebranding:** endpoint `POST /zotexec` → `POST /zotero-agent`; token header
+  `X-Zotexec-Token` → `X-Zotero-Agent-Token`; pref `extensions.zotexec.token` →
+  `extensions.zotero-agent.token`; config dir `~/.config/zotero-exec` →
+  `~/.config/zotero-agent`; env `ZOTEXEC_*` → `ZOTERO_AGENT_*`; plugin →
+  "Zotero Agent Bridge" (`zotero-agent-bridge-<version>.xpi`).
+- `export`/`bib` no longer silently truncate large collections (paginate fully).
+- Minimum Python is now 3.9.
+
+### Migration
+Single-user project, no back-compat shim: reinstall the bridge XPI and run
+`zot init` to regenerate `~/.config/zotero-agent/config.json`.
+
+## [0.1.0] — 2026-07-23
+- Initial release as `zotero-cli-skill`: `zotexec` plugin + `zot` CLI + Claude
+  Code skill.
+
+[Unreleased]: https://github.com/alex-roc/zotero-agent/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/alex-roc/zotero-agent/releases/tag/v0.2.0
+[0.1.0]: https://github.com/alex-roc/zotero-agent/releases/tag/v0.1.0

zotero_agent-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Contributing to zotero-agent
+
+Thanks for your interest! This is a small, focused project — a CLI + MCP server +
+Zotero bridge plugin for **local** library control. Contributions that keep it
+simple, safe, and dependency-light are very welcome.
+
+## Ground rules
+
+- **Core stays stdlib-only.** The `zotero_agent` core must not add runtime
+  dependencies. Anything heavier goes behind an optional extra (like `[mcp]`).
+- **Writes are guarded.** New write commands must respect `confirm_write` (refuse
+  non-interactive runs without `--yes`) and, where sensible, support `--dry-run`
+  and snapshot for `zot undo`.
+- **Behaviour parity.** MCP tools reuse the CLI command functions — don't fork the
+  logic.
+
+## Dev setup
+
+```bash
+git clone https://github.com/alex-roc/zotero-agent.git && cd zotero-agent
+./install.sh                              # dev shim on PATH + skill + XPI
+python3 -m unittest discover -s tests     # tests (no network, no live Zotero)
+uvx ruff check src tests                  # lint
+uv build                                  # build wheel + sdist
+```
+
+The tests use a fake in-process Zotero server (`tests/fake_zotero.py`), so they
+run without Zotero. For a real end-to-end check against your own library, set
+`ZOT_LIVE=1` and run `zot ping` with Zotero open.
+
+## Making a change
+
+1. Branch from `main`.
+2. Keep commits focused; update `docs/`, the `skill/`, and `CHANGELOG.md` when you
+   change behaviour (see the "Unreleased" section).
+3. Run tests + ruff. Rebuild the XPI (`bash plugin/build.sh`) if you touched the
+   plugin.
+4. Open a PR describing what changed and how you verified it.
+
+## Reporting bugs / requesting features
+
+Use the issue templates. For bugs, include the output of `zot ping` and
+`zot --version`. For anything security-related, see [`SECURITY.md`](SECURITY.md).

zotero_agent-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zotero-cli-skill contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zotero_agent-0.2.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: zotero-agent
+Version: 0.2.0
+Summary: Local read-write control of a Zotero library — from your terminal or your AI agent. No cloud, no API key.
+Project-URL: Homepage, https://github.com/alex-roc/zotero-agent
+Project-URL: Documentation, https://alex-roc.github.io/zotero-agent
+Project-URL: Repository, https://github.com/alex-roc/zotero-agent
+Project-URL: Issues, https://github.com/alex-roc/zotero-agent/issues
+Author: Alex Ojeda Copa
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,bibliography,cli,local-first,mcp,reference-manager,zotero
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# zotero-agent
+
+**Full local control of your Zotero library — from your terminal or your AI agent. No cloud, no API key.**
+
+`zot` is a CLI and AI-agent toolkit that gives you full **read-write** control of
+your *local* Zotero library: search, bulk-edit metadata, tag, deduplicate, import
+by DOI/ISBN/arXiv, export, and summarize PDFs into notes. Zotero's local API is
+read-only, so writes go through a tiny plugin exposing a single token-protected
+endpoint, with a documented [three-layer security model](docs/security.md). No
+zotero.org account, no API key, no cloud — **your library never leaves your machine.**
+
+```
+Agent / user → [ MCP server | agent skill | zot CLI ] ─┬─ read  → Zotero local API /api/…  (GET, fast)
+                                                        └─ write → POST /zotero-agent (bridge plugin, JS)
+```
+
+## Why this exists
+
+The dominant Zotero automation tools (zotero-mcp, pyzotero) can only *write* via
+the zotero.org web API — which needs an account, an API key and sync. Zotero's
+**local** HTTP API returns `501` on every write. The only way to write locally is
+a plugin, and that is exactly what the `zotero-agent` bridge is. That makes this
+the local-first, offline, private option: batch metadata edits, real dedup, and
+tag cleanup that people have asked Zotero for [since 2016](https://forums.zotero.org/discussion/111815/feature-batch-editing-metadata-for-multiple-items) — done on your own machine.
+
+## Three ways to use it
+
+- **AI agents via MCP** — `zot mcp` is a Model Context Protocol server for Claude
+  Desktop, **Codex CLI**, **Gemini CLI**, Cursor, and any MCP client. See
+  [`docs/ai-agents.md`](docs/ai-agents.md).
+- **Claude Code skill** — the `zotero` skill drives `zot` with a safe workflow.
+- **Plain CLI** — script it in bash, pipe it, put it in a Makefile.
+
+## What's inside
+
+| Path | What |
+|------|------|
+| `src/zotero_agent/` | The Python package: CLI, command modules, JS builders, MCP server. Stdlib-only core. |
+| `plugin/zotero-agent-bridge/` | The write endpoint (`POST /zotero-agent`), token-protected, ~200 lines. |
+| `skill/` | The `zotero` skill for Claude Code (SKILL.md + recipe book + evals). |
+| `docs/` | Install, security model, architecture, AI-agent setup. |
+| `web/` | The documentation site (Astro Starlight → GitHub Pages). |
+
+## Install
+
+```bash
+# CLI (+ optional MCP server):
+uv tool install zotero-agent            # or: pipx install zotero-agent
+uv tool install "zotero-agent[mcp]"     # include the MCP server
+
+# then install the bridge plugin in Zotero:
+#   Tools → Plugins → gear → "Install Plugin From File" → the .xpi from Releases
+zot init      # generates a token, writes config, auto-detects your userID
+zot ping      # verify: local API up, bridge answering, userID known
+```
+
+From a checkout, `./install.sh` wires up the skill, a dev `zot`, and builds the
+XPI. Full instructions: [`docs/install.md`](docs/install.md).
+
+## Using the CLI
+
+```bash
+zot search "bolivia" --limit 10               # read (fast API)
+zot get ABCD1234                              # one item (Zotero key or BBT citekey)
+zot missing abstract --collection SS5MVVB6    # items lacking a field
+zot stats                                     # library analytics
+zot add doi 10.1371/journal.pmed.0020124 --pdf   # import by identifier (+ OA PDF)
+zot dedupe --by title --fuzzy                 # find near-duplicate titles
+zot dedupe --merge --yes                      # merge duplicates (oldest = master)
+zot enrich --field doi --dry-run              # fill missing DOIs from Crossref
+zot apply edits.jsonl                         # declarative batch edit (undoable)
+zot undo last                                 # roll it back
+zot tag normalize --dry-run                   # fold case/space tag variants
+zot export "My Collection" --format bibtex --out refs.bib
+zot exec 'return Zotero.version;'             # escape hatch: run privileged JS
+```
+
+Add `--json` to any command for machine-readable output. Writes refuse to run
+non-interactively without `--yes`. The canonical JS recipe book is
+[`skill/references/recipes.md`](skill/references/recipes.md).
+
+## Using with an AI agent
+
+Ask *"tag every abstract-less item #review and merge duplicate titles in
+collection X"*, *"fill in missing DOIs"*, or *"summarize this paper's PDF chapter
+by chapter and save it as a note"*. The agent drives `zot` and follows a safe
+workflow (backup → sync-off → dry-run → small batch) for bulk or destructive edits.
+Batch edits are **undoable** (`zot undo`).
+
+## Requirements
+
+- Zotero 7+ (tested through 9.x) running, local API enabled (default).
+- Python 3.9+ (stdlib-only core; the MCP server needs the `[mcp]` extra).
+- macOS and Linux; Windows paths are noted in `docs/install.md`.
+
+## Security
+
+Arbitrary local JS execution, gated by a required token + browser-origin
+rejection + loopback binding, with an append-only audit log. This is a deliberate
+capability; read [`docs/security.md`](docs/security.md) before installing.
+License: [MIT](LICENSE).
+
+## Development
+
+```bash
+python3 -m unittest discover -s tests   # unit + fake-server tests (no network, no Zotero)
+uvx ruff check src tests                 # lint
+uv build                                 # build wheel + sdist
+bash plugin/build.sh                     # rebuild the bridge XPI
+```
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`CHANGELOG.md`](CHANGELOG.md).