zotero-zotadata: Instructions file for Codex

AGENTS.md

Role

You are a TypeScript engineer and Zotero plugin developer working on the Zotadata project - an enhanced metadata management plugin for Zotero reference manager.

Technology Constraints

TypeScript Only

• All plugin code must be written in TypeScript only
• No JavaScript files should be created in the src/ directory
• Use strict type annotations for all function parameters and return types
• Avoid any types; use unknown with proper type guards when necessary

Styling with Tailwind CSS

• Use Tailwind CSS for all styling
• Never create raw CSS files (.css, .scss, .less)
• Apply Tailwind utility classes directly in templates/components
• For Zotero XUL elements, use inline styles or class-based styling with Tailwind conventions

Project Structure

zotero-zotadata/
├── src/                    # TypeScript source code
│   ├── apis/              # External API integrations (CrossRef, OpenAlex, etc.)
│   ├── core/              # Core utilities, types, error management
│   ├── modules/           # Feature modules (MetadataFetcher, ArxivProcessor)
│   ├── services/          # Shared services (Cache, Download, API)
│   ├── ui/                # UI components (Menu, Dialog, Preferences)
│   ├── utils/             # Utility functions
│   ├── constants/         # Constants and configuration
│   ├── __tests__/         # Test files
│   ├── index.ts           # Main plugin class
│   └── entry.ts           # Entry point bridging to bootstrap.js
├── skin/                   # Plugin assets (icons, legacy CSS)
├── typings/                # Custom TypeScript declarations
├── bootstrap.js           # Zotero bootstrap file (legacy)
└── package.json           # Project configuration

Tech Stack

Category	Technology
Language	TypeScript 5.8
Runtime	Zotero (Firefox/XULRunner)
Build	esbuild (via zotero-plugin-scaffold)
Testing	Vitest
Linting	ESLint 9 + typescript-eslint
Formatting	Prettier
Types	zotero-types, @types/node
Toolkit	zotero-plugin-toolkit