Add Zotero plugin

.agents/plugins/marketplace.json

@@ -362,6 +362,18 @@
       },
       "category": "Research"
     },
+    {
+      "name": "zotero",
+      "source": {
+        "source": "local",
+        "path": "./plugins/zotero"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Research"
+    },
     {
       "name": "expo",
       "source": {

plugins/zotero/.codex-plugin/plugin.json

@@ -0,0 +1,48 @@
+{
+  "name": "zotero",
+  "version": "0.1.0",
+  "description": "Work with Zotero from Codex: search your library, export BibTeX, insert citations, and import references through the Zotero desktop app.",
+  "author": {
+    "name": "OpenAI",
+    "email": "support@openai.com",
+    "url": "https://openai.com/"
+  },
+  "homepage": "https://openai.com/",
+  "repository": "https://github.com/openai/plugins",
+  "license": "MIT",
+  "keywords": [
+    "zotero",
+    "citations",
+    "bibliography",
+    "bibtex",
+    "references",
+    "research",
+    "papers",
+    "latex"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Zotero",
+    "shortDescription": "Find papers and add citations from Zotero",
+    "longDescription": "Connect Codex to your Zotero desktop library so it can find saved papers, export BibTeX, add citation keys to drafts, read indexed attachment text when you ask, and import new reference records into Zotero with your approval.",
+    "developerName": "OpenAI",
+    "category": "Research",
+    "capabilities": [
+      "Interactive",
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://openai.com/",
+    "privacyPolicyURL": "https://openai.com/policies/privacy-policy/",
+    "termsOfServiceURL": "https://openai.com/policies/terms-of-use/",
+    "composerIcon": "./assets/icon.png",
+    "logo": "./assets/icon.png",
+    "defaultPrompt": [
+      "@Zotero find papers in my library about transformers and add citations to my draft",
+      "@Zotero export my Zotero library to references.bib",
+      "@Zotero search my Zotero library and show the BibTeX keys"
+    ],
+    "brandColor": "#EF4444",
+    "screenshots": []
+  }
+}

plugins/zotero/skills/zotero/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: Zotero
+description: Use Zotero Desktop from Codex to enable/probe the local API, search a local Zotero library, list items/collections/tags, export BibTeX, insert citation keys into LaTeX or Markdown drafts, read indexed full text when requested, and import BibTeX/RIS records into Zotero through the connector server. Use when the user mentions Zotero, citations, references.bib, BibTeX export, local Zotero API, localhost:23119, or adding citations from a Zotero library.
+---
+
+# Zotero
+
+Use this skill to operate a user's local Zotero Desktop library from Codex.
+
+Core helper:
+
+```bash
+python3 <plugin-root>/skills/zotero/scripts/zotero.py <command>
+```
+
+Resolve `<plugin-root>` by going two directories up from this `SKILL.md` file.
+
+The helper is stdlib-only and follows the repo convention of running plugin Python helpers with `python3` / `#!/usr/bin/env python3`; it does not require Codex-specific runtime discovery.
+
+## Fast starts
+
+Check readiness in one command:
+
+```bash
+python3 <plugin-root>/skills/zotero/scripts/zotero.py status --json
+```
+
+Enable the local API and restart Zotero if needed:
+
+```bash
+python3 <plugin-root>/skills/zotero/scripts/zotero.py enable --restart
+```
+
+Search and export citation data:
+
+```bash
+python3 <plugin-root>/skills/zotero/scripts/zotero.py search "transformer" --json
+python3 <plugin-root>/skills/zotero/scripts/zotero.py export-bibtex --out references.bib
+```
+
+Insert a citation from Zotero into a draft and keep `references.bib` in sync:
+
+```bash
+python3 <plugin-root>/skills/zotero/scripts/zotero.py cite --query "Attention Is All You Need" --tex paper.tex --bib references.bib --marker '<cite>'
+```
+
+## Workflow
+
+1. Start with `status --json`. Do not rediscover prefs, ports, or profile paths manually unless the helper fails.
+2. If `local_api_enabled_pref` is false, run `enable --restart` when the user asked you to operate Zotero. This updates Zotero's local preference and restarts Zotero so port `23119` comes up.
+3. Use read-only local API commands for normal work:
+   - `inventory` for item/collection/tag summaries.
+   - `search <query>` for papers/items.
+   - `export-bibtex` or `sync-bib` for `.bib` files.
+   - `cite` for inserting a citation into a draft.
+4. Only retrieve attachment file URLs or full text when the user asks for PDFs, attachment paths, or full-text content.
+5. Treat Zotero library writes as explicit write actions. Before `import-bibtex`, `import-ris`, or connector save commands, confirm the exact record/source and destination unless the user's prompt already explicitly asked to add/import it.
+
+## Common commands
+
+```bash
+# Readiness and route map
+python3 <plugin-root>/skills/zotero/scripts/zotero.py status --json
+python3 <plugin-root>/skills/zotero/scripts/zotero.py probe --json
+
+# Library inventory
+python3 <plugin-root>/skills/zotero/scripts/zotero.py inventory
+python3 <plugin-root>/skills/zotero/scripts/zotero.py collections
+python3 <plugin-root>/skills/zotero/scripts/zotero.py tags
+
+# Search and export
+python3 <plugin-root>/skills/zotero/scripts/zotero.py search "BERT"
+python3 <plugin-root>/skills/zotero/scripts/zotero.py export-bibtex --out references.bib
+python3 <plugin-root>/skills/zotero/scripts/zotero.py export-bibtex --item-key PXW99EKT
+python3 <plugin-root>/skills/zotero/scripts/zotero.py citations --style apa --json
+
+# Draft editing
+python3 <plugin-root>/skills/zotero/scripts/zotero.py cite --item-key PXW99EKT --tex paper.tex --bib references.bib --marker '<cite>'
+python3 <plugin-root>/skills/zotero/scripts/zotero.py cite --query "BERT" --markdown notes.md --bib references.bib --marker '<cite>'
+
+# Attachments and full text; use only on request
+python3 <plugin-root>/skills/zotero/scripts/zotero.py children PXW99EKT --json
+python3 <plugin-root>/skills/zotero/scripts/zotero.py fulltext 2JAZS9U8 --out attention-fulltext.txt
+python3 <plugin-root>/skills/zotero/scripts/zotero.py file-url 2JAZS9U8
+
+# Writes to Zotero; confirm first unless explicitly requested
+python3 <plugin-root>/skills/zotero/scripts/zotero.py selected-target --json
+python3 <plugin-root>/skills/zotero/scripts/zotero.py import-bibtex --file new-reference.bib --yes
+python3 <plugin-root>/skills/zotero/scripts/zotero.py import-ris --file new-reference.ris --yes
+```
+
+## Output standards
+
+- For inventory/search, return title, creators, year, Zotero item key, and BibTeX key when available.
+- Explain the two-key distinction when relevant: Zotero item keys like `PXW99EKT` are not the same as exported BibTeX keys like `vaswani_attention_2023`.
+- For `.bib` export, return the absolute output path and entry count.
+- For draft citation insertion, report the edited file, inserted citation key, and updated `.bib` path.
+- For blockers, name the exact gate: Zotero app missing, local API disabled, port closed, connector unavailable, no matching item, or write not confirmed.
+
+## Route details
+
+Read `references/local-api-routes.md` only when you need endpoint details beyond the helper commands.

plugins/zotero/skills/zotero/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Zotero"
+  short_description: "Search Zotero and add citations"
+  icon_small: "./assets/icon.png"
+  icon_large: "./assets/icon.png"
+  default_prompt: "Use $Zotero to search my Zotero library, export BibTeX, and add citations to my draft."

plugins/zotero/skills/zotero/references/local-api-routes.md

@@ -0,0 +1,63 @@
+# Zotero local API and connector routes
+
+Base URL: `http://127.0.0.1:23119`.
+
+## Desktop local API
+
+The local API is under `/api/`. It implements Zotero Web API v3 for the local logged-in desktop user.
+
+Important constraints:
+
+- Use `/api/users/0/...` for the local user by default.
+- Local API reads do not require an API key.
+- The local API is read-only; write requests are not supported there.
+- Atom output is not supported locally.
+- Attachment file URLs and full text can expose local file paths or document text; only retrieve them when the user asks.
+
+Safe read routes:
+
+```text
+/api/
+/api/schema
+/api/itemTypes
+/api/itemFields
+/api/itemTypeFields?itemType=journalArticle
+/api/itemTypeCreatorTypes?itemType=journalArticle
+/api/creatorFields
+/api/users/0/collections
+/api/users/0/collections/top
+/api/users/0/items
+/api/users/0/items/top
+/api/users/0/items/trash
+/api/users/0/items/<itemKey>
+/api/users/0/items/<itemKey>/children
+/api/users/0/items?format=keys
+/api/users/0/items?format=versions
+/api/users/0/items?format=bibtex
+/api/users/0/items?include=data,citation&style=apa
+/api/users/0/items?q=<query>
+/api/users/0/tags
+/api/users/0/searches
+/api/users/0/searches/<searchKey>/items
+/api/users/0/groups
+/api/users/0/fulltext?since=0
+/api/users/0/items/<attachmentKey>/fulltext
+/api/users/0/items/<attachmentKey>/file/view/url
+```
+
+## Connector server
+
+The Zotero Connector server shares port `23119` and is used for desktop writes/imports.
+
+Useful routes:
+
+```text
+GET  /connector/ping
+POST /connector/ping
+POST /connector/getSelectedCollection
+POST /connector/import?session=<uuid>
+POST /connector/saveItems
+POST /connector/saveSnapshot
+```
+
+Use `/connector/import` for importing BibTeX/RIS strings into the currently selected Zotero library or collection. Treat connector writes as Zotero library modifications and confirm with the user before doing them.