Metadata-Version: 2.5
Name: zotero-project-manager
Version: 1.1.0
Summary: Export Zotero collections into clean, incremental research workspaces.
Project-URL: Homepage, https://github.com/sbilmis/zotero-project-manager
Project-URL: Documentation, https://github.com/sbilmis/zotero-project-manager#readme
Project-URL: Issues, https://github.com/sbilmis/zotero-project-manager/issues
Project-URL: Changelog, https://github.com/sbilmis/zotero-project-manager/blob/main/CHANGELOG.md
Author: Zotero Project Manager contributors
License: MIT License
        
        Copyright (c) 2026 Zotero Project Manager 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.
License-File: LICENSE
Keywords: annotations,cli,pdf,plugin,research,zotero
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: typer<1,>=0.12
Provides-Extra: dev
Requires-Dist: pytest<9,>=8; extra == 'dev'
Description-Content-Type: text/markdown

# Zotero Project Manager (`zpm`)

Zotero Project Manager exports Zotero collections into clean, ordinary research
folders. Zotero remains the source of truth: the project reads Zotero data and copies
attachments outward without modifying the library, database, or original files.

Use the self-contained Zotero 9 plugin for interactive exports, or the Python CLI for
batch operations, automation, verification, and safe pruning.

## Choose an interface

| Capability | Zotero plugin | Python CLI |
| --- | --- | --- |
| PDFs and optional non-PDF attachments | Yes | Yes |
| Metadata, annotations, notes, and cached annotation images | Yes | Yes |
| Recursive hierarchy, filename presets, and three annotation layouts | Yes | Yes |
| Incremental SHA-256 synchronization and legacy workspace migration | Yes | Yes |
| Multiple root collections in one operation | One at a time | Yes |
| Dry-run, status, pruning, full verification, and workspace adoption | No | Yes |
| Diagnostics, named projects, saved configuration, and automation | No | Yes |
| Runs without Python or direct SQLite access | Yes | No |

Both interfaces produce the same managed workspace format. The plugin stays focused
and conservative; the CLI provides explicit administrative controls.

## Zotero 9 plugin

Exports run inside Zotero and do not require Python, Homebrew, pipx, or an
executable path. Exports create and update local workspaces without launching
other apps, running AppleScript, or uploading files.

Download the XPI from the [latest GitHub release](https://github.com/sbilmis/zotero-project-manager/releases/latest),
then open **Zotero → Tools → Plugins → gear menu → Install Plugin From File…**.
Existing installations can be upgraded in place.

Right-click a collection to use:

```text
Export with zpm
    Export Collection
    Export Collection + Annotations
    Settings…
```

Settings control:

- the default export folder;
- whether non-PDF attachments such as `README.md`, text, images, and data are included;
- attachment filename ordering;
- `separate`, `sidecar`, or `bundle` annotation layout.

The first export asks for a destination if no valid default exists. Zotero can install
future releases automatically when **Update Add-ons Automatically** is enabled in the
Plugins gear menu; **Check for Updates** provides a manual check.

## One workspace, your choice of app

Export a collection once and use its standard folder wherever you need it. For
example, selecting **My-AI → Agentic_AI** exports to **Agentic_AI/** and preserves
its descendants inside that workspace. Re-exporting updates the same workspace.
Choose **Export Collection + Annotations** to include annotations and child notes.

Open the target app yourself and select the exported files you want to use. zpm
has no app-specific Send commands, stored notebook-link UI, automatic app indexing,
uploading, or separate Notebook export format. The hidden `.zpm/` directory is
bookkeeping, not material to upload or import. You choose the files and compatible
types in the destination app.

Stable **1.1.0** keeps the public 1.0.0 feature set and fixes Settings/Choose while
adding concurrent-export protection. The experimental Gemini Notebook/DT4 preview
integrations are not included; standard exports and naming/layout settings remain.
Existing export folders (including old ` - NotebookLM` folders), Google notebooks,
DT4 records, and Zotero originals are not deleted or migrated. Old notebook-link
preferences are left unused; the simplified plugin does not read or clear them.
The earlier implementation remains in Git history.

The CLI no longer accepts `--to`, `--notebook-url`, `--devonthink-group`,
`--prepare-only`, or `--profile`. Existing standard named projects still work.
A saved project with `export_profile = "notebooklm"` is rejected with a migration
message: review its output directory and layout, then remove that setting in its
TOML config only if you want standard export. zpm never silently switches the project
or rewrites the config on load.

See [the Agentic_AI testing guide](docs/TESTING.md) for installation and checks.

## Python CLI

The CLI requires Python 3.11 or newer. Install it on macOS with Homebrew:

```bash
brew install sbilmis/tap/zpm
```

Or install the PyPI package with pipx:

```bash
brew install pipx
pipx install zotero-project-manager
```

Upgrade with `brew upgrade zpm` or `pipx upgrade zotero-project-manager`.

### Quick start

List collections and export one recursively:

```bash
zpm list
zpm export "My-AI" --output ~/ResearchProjects
```

Include annotations and child notes:

```bash
zpm export "My-AI" --output ~/ResearchProjects --annotations
```

Preview changes, then safely prune files removed from Zotero:

```bash
zpm status "My-AI" --output ~/ResearchProjects --prune
zpm export "My-AI" --output ~/ResearchProjects --prune
```

Only manifest-owned files whose SHA-256 still matches are deleted.

### Reusable projects and diagnostics

Save defaults or a named multi-collection project:

```bash
zpm config set --zotero-dir ~/Zotero --output ~/ResearchProjects
zpm project add ai "My-AI" "Claude" --annotations
zpm sync ai
```

Run a read-only readiness audit:

```bash
zpm doctor --output ~/ResearchProjects
```

Use `zpm --help` and `zpm export --help` for every command and option.

## Workspace format

A typical export looks like this:

```text
My-AI/
    Curie - 2024 - Paper title.pdf
    README.md
    Books/
        Author - 2023 - Book.pdf
    Annotations/
        Curie - 2024 - Paper title.md
    .zpm/
        manifest.json
        metadata.json
        INDEX.md
        export-summary.md
```

Generated control data lives under `.zpm/`, leaving ordinary project names such as
`README.md`, `INDEX.md`, and `metadata.json` available for Zotero attachments.

The manifest supports incremental exports:

- unchanged files are left alone;
- new and changed attachments are copied;
- missing or removed attachments are recorded without silently deleting prior copies;
- identical files re-added under a new Zotero key are reconciled;
- root-level manifest v1–v4 workspaces migrate under `.zpm/` after a successful export.

## Annotations and layouts

Annotation export includes highlights, comments, page labels, tags, child notes, and
available cached image or ink previews. It is opt-in because research notes may contain
private material.

Choose one of three layouts:

- `separate` keeps generated Markdown under a parallel `Annotations/` hierarchy;
- `sidecar` places `paper.annotations.md` beside each PDF;
- `bundle` creates one folder per paper containing the attachment and annotations.

The selected filename preset and layout are recorded in the manifest. Existing
workspaces retain those settings to prevent surprising reorganizations.

## Safety model

- Zotero files, attachments, and annotation caches are never modified.
- The CLI opens `zotero.sqlite` read-only with SQLite query-only protection.
- The plugin reads through Zotero's in-process APIs and does not open SQLite directly.
- Output paths inside the Zotero data directory are rejected.
- Unmanaged workspaces and conflicting user files are not adopted silently.
- Generated annotation and control files carry ownership markers.
- Full verification and pruning require explicit CLI options.

Keep independent backups of important research data.

## Development

```bash
git clone https://github.com/sbilmis/zotero-project-manager.git
cd zotero-project-manager
python -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/python -m pytest
node --test zotero-plugin/tests/*.test.cjs
```

Build the release XPI and verify its update-feed entry with:

```bash
.venv/bin/python scripts/build_zotero_plugin.py
```

Install `dist/zpm-zotero-1.1.0.xpi` using Zotero's **Tools → Plugins → gear →
Install Plugin From File…**, or use the XPI from the matching GitHub release.
The installed Homebrew/pipx release does not change when this checkout changes;
use `.venv/bin/python -m zotero_project_manager` to run the CLI from this checkout.
For unpublished development versions only, pass `--development` to build without
a published feed entry. Release builds and CI verify the exact update-feed hash.

See [CONTRIBUTING.md](CONTRIBUTING.md), [PUBLISHING.md](PUBLISHING.md), the
[plugin guide](zotero-plugin/README.md), and [CHANGELOG.md](CHANGELOG.md) for focused
development and release details.

Zotero Project Manager is released under the [MIT License](LICENSE).
