zotcli 0.1.2__tar.gz → 0.2.1__tar.gz

{zotcli-0.1.2 → zotcli-0.2.1}/.gitignore

@@ -4,6 +4,12 @@
 PLAN.md
 Instructions.md
 
+# Research checkout — Zotero upstream sources used only for lookup
+zotero-sources-lookup/
+
+# Self-contained zotcli runtime data (config / cookies / cache / logs)
+.zotcli/
+
 site/
 
 tests/__pycache__/*

zotcli-0.2.1/CHANGELOG.md

@@ -0,0 +1,112 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.2.0] — 2026-05-10
+
+### Added
+
+- **`zot add` command group** — adds items to Zotero via its local connector HTTP server (port 23119). Zotero must be running; `zotero.sqlite` is never modified directly.
+- **Smart auto-detect dispatcher** — bare `zot add "<anything>"` identifies DOI, arXiv ID, PMID, ISBN, IEEE/ScienceDirect URL, citation string, or local file path automatically.
+- **`zot add doi`** — resolve via Crossref, send to Zotero. Supports `--collection`, `--tag`, `--dry-run`, `--with-pdf`, `--on-duplicate`.
+- **`zot add arxiv`** — resolve via arXiv Atom feed → CSL-JSON.
+- **`zot add pmid`** — resolve via NCBI eutils.
+- **`zot add isbn`** — resolve via OpenLibrary (Google Books fallback).
+- **`zot add cite`** — free-text citation string → Crossref bibliographic search → DOI; fallback OpenAlex then Semantic Scholar. Interactive disambiguation table when confidence is low. `--file` for batch citation files.
+- **`zot add url`** — auto-routes arXiv/PubMed/IEEE/ScienceDirect/doi.org URLs to the relevant resolver; generic URLs fall back to `saveSnapshot`.
+- **`zot add file`** — stream a local PDF or EPUB to `/connector/saveStandaloneAttachment`; polls for Zotero's `RecognizeDocument` result (configurable timeout, default 30 s).
+- **`zot add import`** — POST raw RIS / BibTeX / CSL-JSON bytes to `/connector/import`.
+- **`zot add batch`** — process a file of mixed inputs (one per line); summary table at end; non-zero exit if any line failed.
+- **`zot add login`** — manage service credentials: Unpaywall (email), IEEE Xplore (browser SSO), ScienceDirect (browser SSO). `--reset` to clear. `--install-browser` for first-time Playwright Chromium install.
+- **`--with-pdf` flag** on doi/arxiv/pmid/isbn/cite/url — attach an open-access PDF using Unpaywall; fall back to publisher cookies (IEEE/Elsevier) if browser-authenticated.
+- **`zot add status`** — preflight check: reports Zotero reachability, selected collection, and connector URL.
+- **`zot config` command group** — `get`, `set`, `path` subcommands for reading and writing `<zotcli-home>/config.toml`.
+- **Self-contained data directory** (`<zotcli-home>`) — resolved via `ZOTCLI_HOME` env → SKILL.md sibling search → `~/.zotcli`. Holds `config.toml`, `credentials.json`, `cookies/`, `cache/`, `logs/`.
+- **Write gate** — `write.enabled = false` by default. Enable once with `zot config set write.enabled true`, or pass `--allow-write` / set `ZOTCLI_ALLOW_WRITE=1` per command.
+- **Duplicate detection** (report-only by default) — on duplicate DOI/arXiv, prints existing item key + title and exits 0; no mutation.
+- **`--dry-run`** on all add subcommands — resolves metadata and prints the payload that would be sent, without contacting the connector.
+- **`-v` / `--verbose`** — echoes every HTTP request and response to stderr.
+- **`--non-interactive`** — suppresses all prompts; used in scripts and agent contexts.
+- **Rotating log** at `<zotcli-home>/logs/zot.log` (1 MB × 3 backups).
+- **Optional dependency groups**: `write = ["httpx>=0.27"]`, `browser = ["playwright>=1.40"]`, `all` aggregates all extras.
+- **441 unit + integration tests** (up from 40 in v0.1.3). e2e tests are opt-in (`pytest -m e2e`).
+- **`docs/architecture-write.md`** — maintainer-facing overview of the write-path design.
+
+### Changed
+
+- `README.md` and `SKILL.md` updated to document write capability and correct the "never writes" framing. The accurate framing is: default is strictly read-only; writes require opt-in and go through Zotero's connector.
+- `pyproject.toml` description updated; version bumped to 0.2.0.
+- `docs/commands.md` extended with full `zot add` and `zot config` reference.
+- SKILL.md `description:` frontmatter now advertises both reading and writing.
+
+### Fixed
+
+- Click 8.2 `mix_stderr` keyword removal (M5 fix).
+- `RotatingFileHandler` lock-pairing bug in logging setup (M5 fix).
+- `updateSession` target correctly sent as flat string, not nested object (M2 fix).
+
+### Deferred to v0.3
+
+- Edit / delete existing items — blocked on Zotero local API not yet supporting writes, or requires shipping a `.xpi` plugin. Tracked in `PLAN_WRITE.md §12`.
+- Parallel connector calls in `zot add batch` (`--jobs N` accepted but no-op; sequential connector calls are safe; parallel resolver lookups deferred).
+- Group library targeting beyond current-selection default.
+
+### Manual smoke test
+
+Run the following commands against a live Zotero instance before tagging v0.2.0:
+
+```bash
+# Sanity
+zot --version
+zot stats
+
+# Write gate
+zot config set write.enabled true
+zot config get write.enabled        # should print "true"
+zot config path                     # should print <zotcli-home>
+
+# Preflight
+zot add status                      # should report Zotero as reachable
+
+# Add by identifier
+zot add doi 10.1038/s41586-020-2649-2 --collection Inbox --dry-run
+zot add doi 10.1038/s41586-020-2649-2 --collection Inbox --tag smoke-test
+zot add arxiv 2401.12345 --collection Preprints
+zot add pmid 31452104
+zot add isbn 978-0-262-03384-8 --collection Books
+
+# Add by URL
+zot add url https://ieeexplore.ieee.org/document/9876543
+zot add url https://www.sciencedirect.com/science/article/pii/S2352467725000102
+
+# Free-text citation
+zot add cite "Zhang, J., Geth, F., Heidari, R., Verbič, G. (2025) Beyond simplifications: Evaluating assumptions for low-voltage network modelling in the DER era."
+
+# Local file
+zot add file ./paper.pdf --collection Inbox
+
+# Import
+zot add import refs.bib --collection "Imports/test"
+
+# Batch
+printf '10.1109/TPWRS.2023.1234567\n2401.12345\n' > /tmp/papers.txt
+zot add batch /tmp/papers.txt --collection "Batch Test"
+
+# Paywalled PDF (optional: requires prior login)
+zot add login --service unpaywall
+zot add doi 10.1038/s41586-020-2649-2 --with-pdf
+```
+
+---
+
+## [0.1.3] — 2026-04-13
+
+### Added
+
+- Item export command (`zot export`) with JSON, CSV, BibTeX, and Markdown formats.
+- Collection display improvements and recursive collection traversal.
+
+### Fixed
+
+- Removed unsupported schema version warnings from schema validation.
+- Database path auto-detection clarified for Linux, macOS, and Windows.

{zotcli-0.1.2 → zotcli-0.2.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: zotcli
-Version: 0.1.2
-Summary: A read-only CLI for browsing and exporting a Zotero library
+Version: 0.2.1
+Summary: A CLI for browsing, exporting, and adding items to a Zotero library
 Author-email: MohamedNumair <mo7amednumair@gmail.com>
 License: MIT
 Requires-Python: >=3.10
@@ -11,18 +11,29 @@ Requires-Dist: pydantic>=2.0
 Requires-Dist: python-dateutil>=2.9
 Requires-Dist: rich>=13.0
 Provides-Extra: all
+Requires-Dist: httpx>=0.27; extra == 'all'
 Requires-Dist: jinja2>=3.1; extra == 'all'
+Requires-Dist: playwright>=1.40; extra == 'all'
 Requires-Dist: pybtex>=0.24; extra == 'all'
 Provides-Extra: bibtex
 Requires-Dist: pybtex>=0.24; extra == 'bibtex'
+Provides-Extra: browser
+Requires-Dist: playwright>=1.40; extra == 'browser'
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-httpserver; extra == 'dev'
+Requires-Dist: tomli-w; extra == 'dev'
+Requires-Dist: vcrpy; extra == 'dev'
 Provides-Extra: export
 Requires-Dist: jinja2>=3.1; extra == 'export'
+Provides-Extra: write
+Requires-Dist: httpx>=0.27; extra == 'write'
 Description-Content-Type: text/markdown
 
 # zotcli (`zot`)
 ![alt text](zot.png)
 
-A "crazy" good read-only command-line interface for your local [Zotero](https://www.zotero.org/) library. Queries `zotero.sqlite` directly — no Zotero app running, no API key, no internet required. Never writes to the database.
+A command-line interface for your local [Zotero](https://www.zotero.org/) library. **Default: strictly read-only.** Write capabilities are opt-in and route through Zotero's own connector HTTP server — `zotero.sqlite` is **never** modified directly.
 
 **Library stats on this machine:** 3,771 items · 200 collections · 3,201 tags · 6.2 GB storage
 
@@ -31,7 +42,17 @@ A "crazy" good read-only command-line interface for your local [Zotero](https://
 ## Installation
 
 ```bash
+# Read-only (default)
 pip install zotcli
+
+# Adds the write API client (httpx) — required for any zot add … command
+pip install "zotcli[write]"
+
+# Adds Playwright for paywalled-PDF retrieval via browser SSO
+pip install "zotcli[browser]"
+
+# Everything
+pip install "zotcli[all]"
 ```
 
 Verify:
@@ -41,7 +62,7 @@ zot --help
 
 The database at `~/Zotero/zotero.sqlite` is auto-detected on WSL. Override anytime with `--db PATH`.
 
-depending on the operating system the Zotero folder can be in different locations. By default, zotcli looks for the database at `~/Zotero/zotero.sqlite`, which works for most setups. for Windows users, the Zotero folder is typically located in `C:\Users\<YourUsername>\Zotero`. For macOS users, it is usually found in `~/Zotero`. If you have a custom setup or want to specify a different path, you can use the `--db` option to point zotcli to the correct location of your `zotero.sqlite` file. 
+Depending on the operating system the Zotero folder can be in different locations. By default, zotcli looks for the database at `~/Zotero/zotero.sqlite`, which works for most setups. For Windows users, the Zotero folder is typically located in `C:\Users\<YourUsername>\Zotero`. For macOS users, it is usually found in `~/Zotero`. If you have a custom setup or want to specify a different path, you can use the `--db` option to point zotcli to the correct location of your `zotero.sqlite` file.
 
 ---
 
@@ -50,24 +71,47 @@ depending on the operating system the Zotero folder can be in different location
 ```
 zotcli/
 ├── PLAN.md                          # Original design document
+├── PLAN_WRITE.md                    # Write-capability design document
 ├── SKILL.md                         # Agent skill descriptor
 ├── pyproject.toml                   # Package metadata and dependencies
 ├── docs/
-│   └── commands.md                  # Full command reference
+│   ├── commands.md                  # Full command reference
+│   └── architecture-write.md       # Write-path architecture overview
 ├── src/
 │   └── zotcli/
 │       ├── __init__.py
 │       ├── __main__.py              # python -m zotcli entrypoint
 │       ├── db.py                    # Read-only SQLite connection + auto-discovery
-│       ├── config.py                # TOML config (~/.config/zotcli/config.toml)
+│       ├── config.py                # TOML config + [write]/[unpaywall]/[browser] sections
+│       ├── paths.py                 # Cross-platform self-contained path resolution
 │       ├── models.py                # Pydantic v2 models: Item, Collection, Creator, Attachment, Note
 │       ├── queries/
-│       │   ├── items.py             # Core item fetch (_build_items — fields, creators, tags,
-│       │   │                        #   collections, attachments, notes in one go)
+│       │   ├── items.py             # Core item fetch
 │       │   ├── collections.py       # Collection tree queries
 │       │   ├── attachments.py       # Attachment path resolution helpers
 │       │   ├── tags.py              # Tag queries
-│       │   └── search.py           # Field search, author search, DOI, year, fulltext
+│       │   └── search.py            # Field search, author search, DOI, year, fulltext
+│       ├── write/                   # Write-path package (requires zotcli[write])
+│       │   ├── connector_client.py  # httpx client for /connector/*
+│       │   ├── preflight.py         # Zotero liveness check
+│       │   ├── session.py           # Session lifecycle + updateSession
+│       │   ├── csl_json.py          # CSL-JSON ↔ connector item shape
+│       │   ├── identifiers.py       # detect_kind: DOI / arXiv / PMID / ISBN / URL / citation
+│       │   ├── dedup.py             # Read-only duplicate check against DB
+│       │   ├── citation_pipeline.py # Free-text citation → DOI pipeline
+│       │   ├── pdf.py               # MIME sniff + streaming upload
+│       │   ├── browser.py           # Playwright headed window (lazy import; requires zotcli[browser])
+│       │   ├── credentials.py       # File-based credential store (mode 0600)
+│       │   └── resolvers/
+│       │       ├── crossref.py      # DOI → CSL-JSON; bibliographic search
+│       │       ├── arxiv.py         # arXiv ID → CSL-JSON
+│       │       ├── pubmed.py        # PMID → CSL-JSON
+│       │       ├── openlibrary.py   # ISBN → CSL-JSON
+│       │       ├── openalex.py      # Citation/title fallback
+│       │       ├── semantic_scholar.py  # Second fallback (rate-limited)
+│       │       ├── unpaywall.py     # DOI → OA PDF URL (opt-in)
+│       │       ├── ieee.py          # URL → DOI extraction helpers
+│       │       └── sciencedirect.py # URL/PII → DOI extraction helpers
 │       ├── export/
 │       │   ├── json_.py             # Full-fidelity JSON dump
 │       │   ├── csv_.py              # Flat CSV (one row per item)
@@ -76,6 +120,8 @@ zotcli/
 │       └── cli/
 │           ├── main.py              # Root Click group + global options
 │           ├── render.py            # Shared Rich helpers (tables, panels, trees)
+│           ├── add.py               # `zot add` group + auto-detect dispatcher
+│           ├── config_cmd.py        # `zot config` group
 │           ├── collections.py       # `zot collections` subcommands
 │           ├── items.py             # `zot items` subcommands
 │           ├── attachments.py       # `zot attachments` subcommands
@@ -84,10 +130,9 @@ zotcli/
 │           └── export.py            # `zot export` subcommands
 └── tests/
     ├── conftest.py                  # In-memory SQLite fixture with seeded test data
-    ├── test_db.py                   # Database layer tests
-    ├── test_queries.py              # Query layer tests (items, collections, search, tags)
-    ├── test_export.py               # Export format tests (JSON, CSV, BibTeX, Markdown)
-    └── test_cli.py                  # CLI integration tests via CliRunner
+    ├── unit/                        # Unit tests (no network, no Zotero)
+    ├── integration/                 # Integration tests (mocked connector + resolvers)
+    └── e2e/                         # End-to-end (opt-in; requires real Zotero)
 ```
 
 ---
@@ -102,9 +147,18 @@ Query layer  (queries/)
 Database layer  (db.py)       ← read-only URI: file:zotero.sqlite?mode=ro
     ↓
 zotero.sqlite
+
+Write path (opt-in):
+CLI layer  (cli/add.py)
+    ↓  resolve identifiers via external APIs
+Resolver pipeline  (write/resolvers/)
+    ↓  CSL-JSON
+Connector client  (write/connector_client.py)
+    ↓  loopback HTTP
+Zotero desktop app  →  zotero.sqlite + storage/
 ```
 
-Every item fetch runs 6 batched queries in one call — fields, creators, tags, collection memberships, attachments (with resolved absolute paths), and notes — so all data is available everywhere without extra round-trips.
+See [`docs/architecture-write.md`](docs/architecture-write.md) for the full write-path design.
 
 ---
 
@@ -114,6 +168,9 @@ These go **before** the subcommand:
 
 ```
 zot [--db PATH] [--library ID] [--format table|json|csv] [--no-color] <command>
+
+Write-related globals (only relevant when write.enabled=true):
+zot [--allow-write] [--connector-url URL] [--require-zotero/--no-require-zotero] <command>
 ```
 
 ---
@@ -296,68 +353,23 @@ zot search "bayesian" --field title
 │    │           │                 │ for Transformer Tap Position Estimation   │                │        │
 │  2 │ 6BR3CYQA  │ conferencePaper │ Bayesian distribution system state        │ Angioni et al. │ 2016   │
 │    │           │                 │ estimation in presence of non-Gaussian…   │                │        │
-│  3 │ K2YXXPX7  │ journalArticle  │ A Recursive Bayesian Approach for         │ Singh et al.   │ 2010   │
-│    │           │                 │ Identification of Network Configuration…  │                │        │
-│  4 │ CRJWMH2X  │ journalArticle  │ Real-Time Topology Estimation Using       │ Liu et al.     │ 2023   │
-│    │           │                 │ Graph-Bank Transformer…                   │                │        │
-│  5 │ TJH8CGUT  │ conferencePaper │ Bayesian Methods for the Identification   │ Brouillon      │ 2021   │
-│    │           │                 │ of Distribution Networks                  │ et al.         │        │
 └────┴───────────┴─────────────────┴───────────────────────────────────────────┴────────────────┴────────┘
 ```
 
-**By author name** (queries the creators table, partial match):
+**By author name:**
 ```bash
 zot search --author "Numair"
 ```
-```
-                               12 result(s)
-┏━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━┓
-┃  # ┃ Key       ┃ Type            ┃ Title                                     ┃ Authors       ┃ Year   ┃
-┡━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━┩
-│  1 │ MDLX3G4P  │ conferencePaper │ A Proposed IoT Architecture for Effective │ Numair et al. │ 2020   │
-│    │           │                 │ Energy Management in Smart Microgrids     │               │        │
-│  2 │ W3P98AE9  │ conferencePaper │ On the UK smart metering system and value │ Numair et al. │ 2023   │
-│    │           │                 │ of data for distribution system…          │               │        │
-│  3 │ UIMHSHNV  │ journalArticle  │ Fault Detection and Localisation in LV    │ Numair et al. │ 2023   │
-│    │           │                 │ Distribution Networks Using Smart Meter…  │               │        │
-│  4 │ TAVRNAY6  │ bookSection     │ Infrastructure for the 4th Industrial     │ Numair et al. │ 2024   │
-│    │           │                 │ Revolution Technologies                   │               │        │
-│  5 │ 5UFZMSLU  │ journalArticle  │ UNLOCKING DATA CENTRE HOSTING CAPACITY…   │ Numair et al. │ 2026   │
-│  … │ …         │ …               │ …                                         │ …             │ …      │
-└────┴───────────┴─────────────────┴───────────────────────────────────────────┴───────────────┴────────┘
-```
 
 **By DOI:**
 ```bash
 zot search --doi "10.1016/j.epsr.2020.106394"
 ```
-```
-                                1 result(s)
-┏━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━┓
-┃  # ┃ Key       ┃ Type           ┃ Title                                     ┃ Authors          ┃ Year   ┃
-┡━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━┩
-│  1 │ ZGYGL35J  │ journalArticle │ Preventative high impedance fault         │ Langeroudi       │ 2020   │
-│    │           │                │ detection using distribution system…      │ et al.           │        │
-└────┴───────────┴────────────────┴───────────────────────────────────────────┴──────────────────┴────────┘
-```
 
 **By year range:**
 ```bash
 zot search --year 2023 --type conferencePaper
 ```
-```
-361 result(s)  [truncated to first 5 shown]
-┏━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━┓
-┃  # ┃ Key       ┃ Type            ┃ Title                                     ┃ Authors         ┃ Year   ┃
-┡━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━┩
-│  1 │ ZRF8IFPI  │ journalArticle  │ Fault Location Method for an Active       │ Zhao et al.     │ 2023   │
-│    │           │                 │ Distribution Network Based on…            │                 │        │
-│  2 │ G3USAIB9  │ journalArticle  │ PMU Measurements-Based Short-Term         │ Li et al.       │ 2023   │
-│    │           │                 │ Voltage Stability Assessment…             │                 │        │
-│  3 │ RBUU6AM2  │ journalArticle  │ New coordination framework for smart      │ Hussain et al.  │ 2023   │
-│    │           │                 │ home peer-to-peer trading…                │                 │        │
-└────┴───────────┴─────────────────┴───────────────────────────────────────────┴─────────────────┴────────┘
-```
 
 ---
 
@@ -371,20 +383,6 @@ zot attachments path 5UFZMSLU
 ~/Zotero/storage/RIB344FW/Numair et al. - 2026 - UNLOCKING DATA CENTRE HOSTING CAPACITY AND FLEXIBILITY THROUGH DYNAMIC CABLE RATING.pdf
 ```
 
-**List all attachments for an item (with existence check):**
-```bash
-zot items attachments W3P98AE9
-```
-```
-                       Attachments for W3P98AE9
-┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
-┃ Key      ┃ Type            ┃ Mode         ┃ Exists ┃ Path                                      ┃
-┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
-│ GKHSKIP4 │ text/html       │ imported_url │ ✓      │ …/storage/GKHSKIP4/10136487.html          │
-│ 7PZKGWIJ │ application/pdf │ imported_url │ ✓      │ …/storage/7PZKGWIJ/Numair et al. - 2023…  │
-└──────────┴─────────────────┴──────────────┴────────┴───────────────────────────────────────────┘
-```
-
 **Find all missing attachments:**
 ```bash
 zot attachments list --missing
@@ -393,7 +391,6 @@ zot attachments list --missing
 **Open a PDF in the system viewer:**
 ```bash
 zot attachments open 5UFZMSLU
-# Opening: ~/Zotero/storage/RIB344FW/Numair et al. - 2026 - ...pdf
 ```
 
 ---
@@ -403,76 +400,20 @@ zot attachments open 5UFZMSLU
 **BibTeX:**
 ```bash
 zot export bib --collection "Energy Market" --output refs.bib
-```
-```bibtex
-@article{hussain_new_2023,
-  title = {New coordination framework for smart home peer-to-peer trading…},
-  author = {Hussain, Sadam and Azim, M. Imran and Lai, Chunyan and Eicker, Ursula},
-  year = {2023},
-  journal = {Energy},
-  volume = {284},
-  pages = {129297},
-  doi = {10.1016/j.energy.2023.129297},
-}
-
-@article{tsaousoglou_integrating_2023,
-  title = {Integrating Distributed Flexibility into TSO-DSO Coordinated Electricity Markets},
-  author = {Tsaousoglou, Georgios and Junker, Rune and …},
-  year = {2023},
-  doi = {10.1109/TEMPR.2023.3319673},
-}
-…
-```
-
-**CSV:**
-```bash
-zot export csv --collection "Energy Market" --output refs.csv
-```
-```
-item_id,key,item_type,title,year,doi,journal,…,author_1,author_2,…,tags
-10,RBUU6AM2,journalArticle,New coordination framework…,2023,10.1016/…,Energy,…,"Hussain, Sadam","Azim, M. Imran",…,Smart grid;Flexibility
-18,8DE2V7ZZ,journalArticle,Integrating Distributed Flexibility…,2023,10.1109/…,…
+zot export bib --item 5UFZMSLU --output ref.bib
 ```
 
-**JSON** (includes fully resolved attachment paths and notes):
+**CSV / JSON / Markdown:**
 ```bash
-zot export json --collection "Energy Market" --output refs.json
-```
-```json
-[
-  {
-    "item_id": 10,
-    "key": "RBUU6AM2",
-    "item_type": "journalArticle",
-    "title": "New coordination framework for smart home peer-to-peer trading…",
-    "year": "2023",
-    "attachments": [
-      {
-        "key": "PXW7M26P",
-        "content_type": "application/pdf",
-        "file_exists": true,
-        "absolute_path": "~/Zotero/storage/PXW7M26P/Hussain et al. - 2023 - …pdf"
-      }
-    ],
-    "notes": [],
-    "tags": ["Smart grid", "Distribution transformer", "Flexibility"],
-    …
-  }
-]
-```
-
-**Markdown:**
-```bash
-zot export markdown --collection "Energy Market" --output refs.md
-zot export markdown --all --notes --output full-library.md   # include notes sections
+zot export csv      --collection "Energy Market" --output refs.csv
+zot export json     --all --output library.json
+zot export markdown --all --notes --output report.md
 ```
 
 ---
 
 ### Workflow: search → get attachment paths
 
-Find all papers with "bayesian" in the title **or** authored by "Numair", then print the PDF path for each:
-
 ```python
 from zotcli.db import ZoteroDatabase
 from zotcli.queries.search import search_items, search_by_author
@@ -493,13 +434,87 @@ with ZoteroDatabase(DB) as db:
                 print(f"{item.key}\t{att.absolute_path}")
 ```
 
+---
+
+## Writing to your library
+
+> **Default: strictly read-only.** Write capabilities are opt-in and route through Zotero's own connector HTTP server — `zotero.sqlite` is **never** modified directly.
+
+**Zotero must be running** for any `zot add …` command to succeed.
+
+### Enable write capability
+
+```bash
+# One-time setup (persists to config)
+zot config set write.enabled true
+
+# Check current status
+zot config get write.enabled
+
+# Verify Zotero is reachable
+zot add status
 ```
-LVTG4KLQ    ~/Zotero/storage/LVTG4KLQ/Chen2013_BayesianTap.pdf
-5UFZMSLU    ~/Zotero/storage/RIB344FW/Numair et al. - 2026 - UNLOCKING DATA CENTRE…pdf
-W3P98AE9    ~/Zotero/storage/7PZKGWIJ/Numair et al. - 2023 - On the UK smart metering…pdf
-…
+
+### Quick-start: add items
+
+```bash
+# Add by DOI / arXiv / PMID / ISBN
+zot add doi 10.1109/TPWRS.2023.1234567
+zot add arxiv 2401.12345 --collection Preprints
+zot add pmid 31452104
+zot add isbn 978-0-262-03384-8 --collection Books
+
+# IEEE Xplore or ScienceDirect URL (DOI is extracted automatically — no browser needed)
+zot add "https://ieeexplore.ieee.org/document/9876543"
+zot add "https://www.sciencedirect.com/science/article/pii/S2352467725000XYZ"
+
+# Free-text citation string
+zot add "Zhang, J., Geth, F., Heidari, R., Verbič, G. (2025) Beyond simplifications…"
+
+# Local PDF (Zotero auto-recognises the parent reference)
+zot add ~/Downloads/paper.pdf
+
+# Smart auto-detect: zot add figures out the type automatically
+zot add "10.1109/TPWRS.2023.1234567"   # detected as DOI
+zot add "2401.12345"                    # detected as arXiv
+zot add "/home/me/paper.pdf"            # detected as file
+```
+
+### Batch add
+
+```bash
+# papers.txt: one DOI / arXiv / URL / citation per line; # = comment
+zot add batch papers.txt --collection "Smart Grid" --tag imported
+```
+
+### Import from a bibliography file
+
+```bash
+# .bib, .ris, or .json (CSL-JSON)
+zot add import refs.bib --collection "Imports/2026-05"
 ```
 
+### Optional: paywalled-PDF retrieval
+
+```bash
+# Step 1: register for Unpaywall (email only; opt-in)
+zot add login --service unpaywall
+
+# Step 2: add with open-access PDF
+zot add doi 10.1109/X --with-pdf
+
+# For paywalled content: authenticate via browser SSO (requires zotcli[browser])
+zot add login --service ieee           # opens headed Chromium; sign in once
+zot add login --service sciencedirect
+zot add doi 10.1109/X --with-pdf      # re-uses saved cookies
+```
+
+### Architecture summary
+
+All writes go through `POST /connector/saveItems` (and related endpoints) on Zotero's local HTTP server at `127.0.0.1:23119`. Zotero performs every database transaction. `zotero.sqlite` is never opened in write mode by zotcli.
+
+See [`docs/architecture-write.md`](docs/architecture-write.md) for full details.
+
 ---
 
 ## Running tests
@@ -508,33 +523,46 @@ W3P98AE9    ~/Zotero/storage/7PZKGWIJ/Numair et al. - 2023 - On the UK smart met
 python3 -m pytest tests/ -q
 ```
 ```
-........................................
-40 passed in 31s
+441 passed in Xs
 ```
 
-Tests use an in-memory SQLite fixture seeded with synthetic Zotero data. No real database needed.
+Tests use an in-memory SQLite fixture seeded with synthetic Zotero data. No real database needed. e2e tests (requiring a live Zotero) are opt-in:
+
+```bash
+python3 -m pytest tests/e2e -m e2e
+```
 
 ---
 
 ## Configuration
 
-Optional persistent config at `~/.config/zotcli/config.toml`:
+Self-contained config at `<zotcli-home>/config.toml`. Run `zot config path` to find the directory.
 
 ```toml
 [database]
-path = "~/Zotero/zotero.sqlite"
-library_id = 1
+path = ""                        # empty = auto-detect zotero.sqlite
 
-[output]
-default_format = "table"
-color = true
-page_size = 50
+[write]
+enabled = false                  # opt-in; set true once with: zot config set write.enabled true
+connector_url = "http://127.0.0.1:23119"
+require_zotero = true
+
+[unpaywall]
+enabled = false                  # opt-in; set up with: zot add login --service unpaywall
+email = ""
+
+[browser]
+headless = false                 # SSO/captcha needs headed browser
 ```
 
+Override `<zotcli-home>` with the `ZOTCLI_HOME` environment variable.
+
 ---
 
 ## Safety
 
-- Database opened with `sqlite3://…?mode=ro` — the OS-level read-only URI flag makes writes impossible
+- Database opened with `sqlite3://…?mode=ro` — the OS-level read-only URI flag makes direct writes impossible
 - WAL journal detection warns if Zotero is currently open (pending writes may not be visible yet)
-- No network calls, no Zotero API, no authentication
+- Write operations route through Zotero's own connector HTTP server — never via direct SQLite mutation
+- Default is read-only; writes require explicit opt-in (`zot config set write.enabled true`)
+- No Zotero API key required