# Upgrade Plan

Keep upgrades backward compatible with the current command line.

## Near-term additions

- Add `--collection` to process one Zotero collection by name or key.
- Add `--delete-duplicates` with a dry-run default and explicit confirmation requirement.
- Add `--report-out <path>` to save run summaries without dumping full note HTML to terminal.
- Add retry/backoff for Zotero Web API writes and LLM calls.
- Add `--provider <name>` to select AwesomeGPT providers other than DeepSeek.
- Add incremental audit invalidation based on Zotero item/library version headers, so only changed parents are rescanned after the initial cache build.

## Quality upgrades

- Install or use `pypdf`/`PyMuPDF` when available for better PDF text extraction.
- Add a template variable layer so the script can fill title/key/link before sending to the model.
- Split prompts for article-type classification and note generation when the user wants stronger consistency.
- For review articles, only request representative-work BibTeX when full references are available.

## Safety upgrades

- Never log API keys.
- Do not write keys into `.env` automatically.
- For destructive actions such as duplicate cleanup, require an explicit user request and perform a dry run first.
- Prefer `--skip-existing` for all batch jobs.

## Known constraints

- Zotero Local API is read-only; child-note creation uses Zotero Web API.
- AwesomeGPT's in-Zotero connector may require a session secret and should not be treated as a stable external API.
- Some Zotero child-note list responses may omit full note HTML; duplicate detection should fetch full note items when needed.