zotkit 0.4.0__tar.gz → 0.4.2__tar.gz

{zotkit-0.4.0/zotkit.egg-info → zotkit-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zotkit
-Version: 0.4.0
+Version: 0.4.2
 Summary: Headless Zotero library management: Web API CRUD plus direct WebDAV attachment upload/download — no desktop app required
 Author: Shawn
 License-Expression: MIT
@@ -104,6 +104,8 @@ zotkit find --tag status:to-read
 
 zotkit create --arxiv 2401.12345            # fetch arXiv metadata, dry-run preview
 zotkit create --arxiv 2401.12345 --apply --tags field:ai   # create + download & attach the PDF
+zotkit create --arxiv 2401.12345 1706.03762 math/0211159 --apply   # batch: one metadata
+                                            #   request, PDFs politely spaced ≥3 s apart
 zotkit create --doi 10.1038/nature14539     # fetch CrossRef metadata by DOI (no PDF —
                                             #   usually paywalled; attach manually after)
 
@@ -122,12 +124,27 @@ zotkit backup                               # full JSON snapshot -> backups/
 zotkit lint field:physics topic:new-idea    # offline tag check
 ```
 
-`--arxiv` takes an id or an abs/pdf URL and maps the full record (all authors,
-abstract, date, DOI, `preprint` item type); `--doi` maps CrossRef records
-(journal articles, conference papers, books, chapters, …) and refuses to guess
-on CrossRef types it doesn't know. Both accept `--collection` and `--tags`, and
-`--no-pdf` skips the arXiv PDF. Fetching metadata from arbitrary web pages is
-out of scope (zotkit stays a daemon-free CLI — no translation-server).
+`--arxiv` takes ids or abs/pdf URLs (several, space- or comma-separated) and maps
+the full record (all authors, abstract, date, DOI); `--doi`
+maps CrossRef records (journal articles, conference papers, books, chapters, …)
+and refuses to guess on CrossRef types it doesn't know.
+
+**Version of record**: when arXiv reports a *journal* DOI (the paper was formally
+published — as opposed to arXiv's own `10.48550/*` DataCite DOI), `--arxiv`
+builds the journal record from CrossRef instead of a `preprint`: proper item
+type, venue, volume/pages, formal date. The arXiv identity is kept — `arXiv: <id>`
+goes in Extra, the `url` stays the open-access abs page (the journal link lives in
+the DOI field), the arXiv abstract fills in when CrossRef has none, and the PDF
+still comes from arXiv. If the CrossRef lookup fails, the item falls back to the
+preprint record with a warning rather than failing. Items whose abstract zotkit
+wrote also carry an `abstract-source: arxiv|crossref` line in Extra, naming where
+it actually came from. Both accept `--collection`
+and `--tags`, and `--no-pdf` skips the arXiv PDFs. Rate limiting is built into the
+request layer — batches use one arXiv metadata request and space PDF downloads
+per arXiv's terms of use, so callers (humans or agents) never pace themselves. A
+bad id fails alone, not the batch; the exit code is non-zero only if something
+failed. Fetching metadata from arbitrary web pages is out of scope (zotkit stays
+a daemon-free CLI — no translation-server).
 
 Item JSON for `zotkit create --file` (a list, one object per reference):
 

{zotkit-0.4.0 → zotkit-0.4.2}/README.md

@@ -84,6 +84,8 @@ zotkit find --tag status:to-read
 
 zotkit create --arxiv 2401.12345            # fetch arXiv metadata, dry-run preview
 zotkit create --arxiv 2401.12345 --apply --tags field:ai   # create + download & attach the PDF
+zotkit create --arxiv 2401.12345 1706.03762 math/0211159 --apply   # batch: one metadata
+                                            #   request, PDFs politely spaced ≥3 s apart
 zotkit create --doi 10.1038/nature14539     # fetch CrossRef metadata by DOI (no PDF —
                                             #   usually paywalled; attach manually after)
 
@@ -102,12 +104,27 @@ zotkit backup                               # full JSON snapshot -> backups/
 zotkit lint field:physics topic:new-idea    # offline tag check
 ```
 
-`--arxiv` takes an id or an abs/pdf URL and maps the full record (all authors,
-abstract, date, DOI, `preprint` item type); `--doi` maps CrossRef records
-(journal articles, conference papers, books, chapters, …) and refuses to guess
-on CrossRef types it doesn't know. Both accept `--collection` and `--tags`, and
-`--no-pdf` skips the arXiv PDF. Fetching metadata from arbitrary web pages is
-out of scope (zotkit stays a daemon-free CLI — no translation-server).
+`--arxiv` takes ids or abs/pdf URLs (several, space- or comma-separated) and maps
+the full record (all authors, abstract, date, DOI); `--doi`
+maps CrossRef records (journal articles, conference papers, books, chapters, …)
+and refuses to guess on CrossRef types it doesn't know.
+
+**Version of record**: when arXiv reports a *journal* DOI (the paper was formally
+published — as opposed to arXiv's own `10.48550/*` DataCite DOI), `--arxiv`
+builds the journal record from CrossRef instead of a `preprint`: proper item
+type, venue, volume/pages, formal date. The arXiv identity is kept — `arXiv: <id>`
+goes in Extra, the `url` stays the open-access abs page (the journal link lives in
+the DOI field), the arXiv abstract fills in when CrossRef has none, and the PDF
+still comes from arXiv. If the CrossRef lookup fails, the item falls back to the
+preprint record with a warning rather than failing. Items whose abstract zotkit
+wrote also carry an `abstract-source: arxiv|crossref` line in Extra, naming where
+it actually came from. Both accept `--collection`
+and `--tags`, and `--no-pdf` skips the arXiv PDFs. Rate limiting is built into the
+request layer — batches use one arXiv metadata request and space PDF downloads
+per arXiv's terms of use, so callers (humans or agents) never pace themselves. A
+bad id fails alone, not the batch; the exit code is non-zero only if something
+failed. Fetching metadata from arbitrary web pages is out of scope (zotkit stays
+a daemon-free CLI — no translation-server).
 
 Item JSON for `zotkit create --file` (a list, one object per reference):
 

{zotkit-0.4.0 → zotkit-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "zotkit"
-version = "0.4.0"
+version = "0.4.2"
 description = "Headless Zotero library management: Web API CRUD plus direct WebDAV attachment upload/download — no desktop app required"
 readme = "README.md"
 license = "MIT"

{zotkit-0.4.0 → zotkit-0.4.2}/zotkit/__init__.py

@@ -2,4 +2,4 @@
 from .core import Conventions, TagConventionError, Zot, lint_tags, load_conventions
 
 __all__ = ["Zot", "lint_tags", "load_conventions", "Conventions", "TagConventionError"]
-__version__ = "0.4.0"
+__version__ = "0.4.2"

{zotkit-0.4.0 → zotkit-0.4.2}/zotkit/cli.py

@@ -81,11 +81,13 @@ def main(argv=None):
                                       "or a DOI (dry unless --apply)")
     src = p.add_mutually_exclusive_group(required=True)
     src.add_argument("--file")
-    src.add_argument("--arxiv", metavar="ID_OR_URL",
-                     help="arXiv id (2401.12345) or abs/pdf URL; fetches metadata, "
-                          "and with --apply also downloads + attaches the PDF")
-    src.add_argument("--doi", metavar="DOI",
-                     help="DOI (or doi.org URL); fetches metadata from CrossRef")
+    src.add_argument("--arxiv", metavar="ID_OR_URL", nargs="+",
+                     help="arXiv ids (2401.12345) or abs/pdf URLs — several allowed, "
+                          "space- or comma-separated; fetches metadata in one batched "
+                          "request, and with --apply also downloads + attaches the PDFs")
+    src.add_argument("--doi", metavar="DOI", nargs="+",
+                     help="DOIs (or doi.org URLs) — several allowed, space- or "
+                          "comma-separated; fetches metadata from CrossRef")
     p.add_argument("--apply", action="store_true")
     p.add_argument("--no-dedup", action="store_true")
     p.add_argument("--loose-tags", action="store_true", help="warn instead of error on tag violations")
@@ -141,25 +143,47 @@ def main(argv=None):
         _print_items(zot.find(a.title, a.tag, a.collection))
 
     elif a.cmd == "create":
-        pdf_url = None
+        pdfs: dict[str, tuple[str, str]] = {}  # title -> (arXiv id, pdf url)
+        failures: list[tuple[str, str]] = []   # (identifier, why)
         if a.file:
             data = json.load(open(a.file, encoding="utf-8"))
             items = data["items"] if isinstance(data, dict) else data
         else:
-            from .metadata import MetadataError, fetch_arxiv, fetch_doi
+            from .metadata import MetadataError, fetch_arxiv_batch, fetch_doi
+            wanted = [w.strip() for arg in (a.arxiv or a.doi)
+                      for w in arg.split(",") if w.strip()]
+            items = []
             try:
                 if a.arxiv:
-                    item, pdf_url = fetch_arxiv(a.arxiv)
+                    for r in fetch_arxiv_batch(wanted):
+                        if r.get("error"):
+                            failures.append((r["id"], r["error"]))
+                            continue
+                        if r.get("note"):  # version-of-record upgrade happened
+                            print(r["note"])
+                        if r.get("warning"):
+                            print(f"warning: {r['warning']}", file=sys.stderr)
+                        items.append(r["item"])
+                        pdfs[r["item"]["title"]] = (r["id"], r["pdf_url"])
                 else:
-                    item = fetch_doi(a.doi)
+                    for d in wanted:
+                        try:
+                            items.append(fetch_doi(d))
+                        except MetadataError as e:
+                            failures.append((d, str(e)))
             except MetadataError as e:
                 print(f"error: {e}", file=sys.stderr)
                 return 1
-            if a.collection:
-                item["collection"] = a.collection
-            if a.tags:
-                item["tags"] = [t.strip() for t in a.tags.split(",") if t.strip()]
-            items = [item]
+            for ident, why in failures:
+                prefix = f"{ident}: " if len(wanted) > 1 else ""
+                print(f"error: {prefix}{why}", file=sys.stderr)
+            for item in items:
+                if a.collection:
+                    item["collection"] = a.collection
+                if a.tags:
+                    item["tags"] = [t.strip() for t in a.tags.split(",") if t.strip()]
+            if not items:
+                return 1
         if not a.apply:
             for d in items:
                 problems = lint_tags(d.get("tags", []), conventions=zot.conventions,
@@ -171,42 +195,51 @@ def main(argv=None):
                     continue
                 flag = ("  !! " + "; ".join(problems)) if problems else ""
                 print(f"  [dry] {d.get('collection')} | {d.get('title','')[:60]}{flag}")
-            print(f"{len(items)} item(s). DRY — add --apply to create.")
-            return 0
+            tail = f", {len(failures)} failed to fetch" if failures else ""
+            print(f"{len(items)} item(s){tail}. DRY — add --apply to create.")
+            return 1 if failures else 0
         created = zot.create_items(items, dedup=not a.no_dedup, strict_tags=not a.loose_tags)
         new = [c for c in created if c.get("key")]
+        dup = len(created) - len(new)
         if a.file:
             out = Path(a.file).with_suffix(".created.json")
             json.dump(new, open(out, "w", encoding="utf-8"), ensure_ascii=False, indent=2)
-            print(f"created {len(new)} (skipped {len(created)-len(new)} dup) -> {out}")
+            print(f"created {len(new)} (skipped {dup} dup) -> {out}")
             if any(c.get("file_path") for c in new):
                 print(f"attach PDFs: zotkit attach --from {out} --all")
             return 0
-        # identifier mode: one item
-        if not new:
+        # identifier mode
+        if not new and not failures:
             print("skipped: an item with this DOI/title already exists (use --no-dedup "
                   "to force)")
             return 0
-        key = new[0]["key"]
-        print(f"created {key}  {items[0].get('title', '')[:70]}")
-        if pdf_url and not a.no_pdf:
-            from .metadata import download_pdf
-            import tempfile
-            with tempfile.TemporaryDirectory() as td:
-                pdf = Path(td) / (items[0]["archiveID"].replace("arXiv:", "arXiv-")
-                                  .replace("/", "_") + ".pdf")
-                try:
-                    download_pdf(pdf_url, pdf)
-                except MetadataError as e:
-                    print(f"item created, but PDF failed: {e}\n"
-                          f"  attach manually: zotkit attach --key {key} --pdf <file>",
-                          file=sys.stderr)
-                    return 1
-                info = zot.attach(key, pdf)
-            print(f"attached {info['filename']} ({info['storage']})")
-        elif a.doi:
+        for c in new:
+            key = c["key"]
+            print(f"created {key}  {str(c.get('title', ''))[:70]}")
+            aid_pdf = pdfs.get(c.get("title"))
+            if aid_pdf and not a.no_pdf:
+                from .metadata import download_pdf
+                import tempfile
+                aid, pdf_url = aid_pdf
+                with tempfile.TemporaryDirectory() as td:
+                    pdf = Path(td) / f"arXiv-{aid.replace('/', '_')}.pdf"
+                    try:
+                        download_pdf(pdf_url, pdf)  # spaced ≥3 s apart by metadata._get
+                    except MetadataError as e:
+                        failures.append((aid, f"item {key} created, but PDF failed: {e}"))
+                        print(f"error: item {key} created, but PDF failed: {e}\n"
+                              f"  attach manually: zotkit attach --key {key} --pdf <file>",
+                              file=sys.stderr)
+                        continue
+                    info = zot.attach(key, pdf)
+                print(f"attached {info['filename']} ({info['storage']})")
+        if a.doi and new:
+            hint = new[0]["key"] if len(new) == 1 else "<key>"
             print("no PDF downloaded (publisher PDFs are usually paywalled) — "
-                  f"attach one with: zotkit attach --key {key} --pdf <file>")
+                  f"attach one with: zotkit attach --key {hint} --pdf <file>")
+        if len(wanted) > 1:
+            print(f"batch: created {len(new)}, skipped {dup} dup, failed {len(failures)}")
+        return 1 if failures else 0
 
     elif a.cmd == "attach":
         if a.key and a.pdf:

{zotkit-0.4.0 → zotkit-0.4.2}/zotkit/metadata.py

@@ -6,6 +6,11 @@ Scope is deliberately narrow: stable JSON/Atom APIs only — no translation-serv
 no arbitrary-URL scraping (zotkit stays a daemon-free CLI).
 
 Abstracts are stored verbatim (line breaks, LaTeX, JATS markup untouched).
+
+Rate limiting lives here, in the request layer: every request through `_get`
+waits out the per-host minimum interval (arXiv's terms: 1 request / 3 s on a
+single connection; CrossRef polite pool: 1 s). Callers — CLI users, agents,
+batch loops — never need to pace themselves.
 """
 from __future__ import annotations
 
@@ -56,7 +61,17 @@ class MetadataError(RuntimeError):
     unknown record, unsupported type, network trouble)."""
 
 
+# minimum seconds between requests to the same host (arXiv terms of use: 3 s,
+# covering the export API and PDF downloads; CrossRef polite pool: 1 s)
+_MIN_INTERVAL = {"export.arxiv.org": 3.0, "arxiv.org": 3.0, "api.crossref.org": 1.0}
+_next_ok: dict[str, float] = {}
+
+
 def _get(url: str, **kw) -> httpx.Response:
+    host = httpx.URL(url).host
+    wait = _next_ok.get(host, 0.0) - time.monotonic()
+    if wait > 0:
+        time.sleep(wait)
     try:
         r = httpx.get(url, headers={"User-Agent": USER_AGENT}, timeout=30,
                       follow_redirects=True, **kw)
@@ -67,10 +82,11 @@ def _get(url: str, **kw) -> httpx.Response:
                           follow_redirects=True, **kw)
             if r.status_code == 429:
                 raise MetadataError(
-                    f"{httpx.URL(url).host} is rate-limiting (HTTP 429) — "
-                    "wait a minute and retry")
+                    f"{host} is rate-limiting (HTTP 429) — wait a minute and retry")
     except httpx.HTTPError as e:
-        raise MetadataError(f"network error talking to {httpx.URL(url).host}: {e}") from e
+        raise MetadataError(f"network error talking to {host}: {e}") from e
+    finally:
+        _next_ok[host] = time.monotonic() + _MIN_INTERVAL.get(host, 0.0)
     return r
 
 
@@ -79,6 +95,11 @@ def _squash(s: str) -> str:
     return re.sub(r"\s+", " ", s or "").strip()
 
 
+def _add_extra(item: dict, line: str) -> None:
+    """Append a line to the item's Extra field, never overwriting what's there."""
+    item["extra"] = f"{item['extra']}\n{line}" if item.get("extra") else line
+
+
 def _person(name: str) -> dict:
     """Split a display name into first/last on the final space; single-token
     names go in lastName alone (matches Zotero's single-field mode)."""
@@ -106,29 +127,19 @@ def arxiv_id(id_or_url: str) -> str:
     return m.group(1)
 
 
-def fetch_arxiv(id_or_url: str) -> tuple[dict, str]:
-    """arXiv export API → (item dict, pdf url)."""
-    aid = arxiv_id(id_or_url)
-    r = _get("https://export.arxiv.org/api/query", params={"id_list": aid})
-    if r.status_code != 200:
-        raise MetadataError(f"arXiv API returned HTTP {r.status_code} for '{aid}'")
-    try:
-        feed = ET.fromstring(r.text)
-    except ET.ParseError as e:
-        raise MetadataError(f"arXiv API returned unparseable XML: {e}") from e
-    entry = feed.find(f"{_ATOM}entry")
-    title = _squash(entry.findtext(f"{_ATOM}title", "")) if entry is not None else ""
-    if entry is None or not title:
-        raise MetadataError(f"arXiv has no record for '{aid}' — check the id")
-    if title == "Error":
-        raise MetadataError(f"arXiv API error for '{aid}': "
-                            f"{_squash(entry.findtext(f'{_ATOM}summary', ''))}")
-
-    bare = re.sub(r"v\d+$", "", aid)
-    doi = _squash(entry.findtext(f"{_ARXIV}doi", "")) or f"10.48550/arXiv.{bare}"
+_ARXIV_CHUNK = 50  # ids per id_list request; chunks are spaced out by _get
+
+
+def _bare(aid: str) -> str:
+    return re.sub(r"v\d+$", "", aid, flags=re.IGNORECASE)
+
+
+def _arxiv_item(entry, aid: str) -> tuple[dict, str]:
+    doi = (_squash(entry.findtext(f"{_ARXIV}doi", ""))
+           or f"10.48550/arXiv.{_bare(aid)}")
     item = {
         "itemType": "preprint",
-        "title": title,
+        "title": _squash(entry.findtext(f"{_ATOM}title", "")),
         "creators": [_person(n.text or "")
                      for n in entry.findall(f"{_ATOM}author/{_ATOM}name")],
         "abstractNote": (entry.findtext(f"{_ATOM}summary", "") or "").strip("\n "),
@@ -139,9 +150,99 @@ def fetch_arxiv(id_or_url: str) -> tuple[dict, str]:
         "archiveID": f"arXiv:{aid}",
         "libraryCatalog": "arXiv.org",
     }
+    if item["abstractNote"]:
+        _add_extra(item, "abstract-source: arxiv")
     return item, f"https://arxiv.org/pdf/{aid}"
 
 
+_DATACITE_PREFIX = "10.48550/"  # arXiv's own DOIs; anything else is a journal DOI
+
+
+def _journal_record(pre: dict, aid: str) -> dict:
+    """Version-of-record upgrade: the arXiv record carries a journal DOI, so
+    build the item from CrossRef instead (venue/volume/pages/formal date),
+    keeping the arXiv identity: abstract fallback when CrossRef has none,
+    `arXiv: <id>` in Extra, and the open-access abs page as url (the journal
+    link is carried by the DOI field). Raises MetadataError on lookup failure —
+    the caller falls back to the preprint record."""
+    j = fetch_doi(pre["DOI"])
+    if not j.get("abstractNote") and pre.get("abstractNote"):
+        j["abstractNote"] = pre["abstractNote"]
+        _add_extra(j, "abstract-source: arxiv")
+    j["url"] = pre["url"]
+    _add_extra(j, f"arXiv: {aid}")
+    return j
+
+
+def fetch_arxiv_batch(ids_or_urls: list[str]) -> list[dict]:
+    """arXiv export API, one id_list request per ≤50 ids → results in input
+    order, each {"id", "item", "pdf_url"} or {"id", "error"}. A bad id never
+    fails the batch; only transport-level trouble raises MetadataError.
+
+    Version of record: when arXiv reports a journal DOI (not its own
+    10.48550/* DataCite DOI) the item is rebuilt from CrossRef ("note" key
+    says so); if that lookup fails the preprint record stands ("warning" key).
+
+    The response can't be trusted positionally: entries come back in arbitrary
+    order (and with resolved version numbers), so they are mapped back to the
+    requested ids by version-stripped id.
+    """
+    results: list[dict] = []
+    valid: list[dict] = []  # results entries still awaiting an API answer
+    for s in ids_or_urls:
+        try:
+            results.append({"id": arxiv_id(s)})
+            valid.append(results[-1])
+        except MetadataError as e:
+            results.append({"id": s, "error": str(e)})
+
+    for i in range(0, len(valid), _ARXIV_CHUNK):
+        chunk = valid[i:i + _ARXIV_CHUNK]
+        # max_results defaults to 10 — without it, batches >10 silently truncate
+        r = _get("https://export.arxiv.org/api/query",
+                 params={"id_list": ",".join(c["id"] for c in chunk),
+                         "max_results": len(chunk)})
+        if r.status_code != 200:
+            raise MetadataError(f"arXiv API returned HTTP {r.status_code}")
+        try:
+            feed = ET.fromstring(r.text)
+        except ET.ParseError as e:
+            raise MetadataError(f"arXiv API returned unparseable XML: {e}") from e
+        emap = {}
+        for entry in feed.findall(f"{_ATOM}entry"):
+            title = _squash(entry.findtext(f"{_ATOM}title", ""))
+            if not title or title == "Error":  # error/placeholder entries: unmappable
+                continue
+            try:
+                emap[_bare(arxiv_id(entry.findtext(f"{_ATOM}id", "")))] = entry
+            except MetadataError:
+                continue
+        for c in chunk:
+            entry = emap.get(_bare(c["id"]))
+            if entry is None:
+                c["error"] = f"arXiv has no record for '{c['id']}' — check the id"
+                continue
+            c["item"], c["pdf_url"] = _arxiv_item(entry, c["id"])
+            doi = c["item"]["DOI"]
+            if not doi.startswith(_DATACITE_PREFIX):
+                try:
+                    c["item"] = _journal_record(c["item"], c["id"])
+                    c["note"] = (f"{c['id']} → journal DOI {doi}, "
+                                 "building journal record")
+                except MetadataError as e:
+                    c["warning"] = (f"{c['id']}: journal DOI {doi} lookup failed "
+                                    f"({e}) — keeping preprint record")
+    return results
+
+
+def fetch_arxiv(id_or_url: str) -> tuple[dict, str]:
+    """arXiv export API → (item dict, pdf url); raises on any failure."""
+    res = fetch_arxiv_batch([id_or_url])[0]
+    if res.get("error"):
+        raise MetadataError(res["error"])
+    return res["item"], res["pdf_url"]
+
+
 def download_pdf(url: str, dest) -> None:
     """Download a PDF to `dest`, refusing anything that isn't actually a PDF."""
     r = _get(url)
@@ -206,7 +307,7 @@ def fetch_doi(doi: str) -> dict:
         "url": msg.get("URL") or f"https://doi.org/{doi}",
         "volume": msg.get("volume", ""),
         "issue": msg.get("issue", ""),
-        "pages": msg.get("page", ""),
+        "pages": msg.get("page") or msg.get("article-number", ""),
         "publisher": _squash(msg.get("publisher", "")),
         "language": msg.get("language", ""),
         "ISSN": (msg.get("ISSN") or [""])[0],
@@ -220,4 +321,7 @@ def fetch_doi(doi: str) -> dict:
     if not item["title"]:
         raise MetadataError(f"CrossRef record for '{doi}' has no title — refusing to "
                             "create an empty item")
-    return {k: v for k, v in item.items() if v not in ("", [])}
+    item = {k: v for k, v in item.items() if v not in ("", [])}
+    if item.get("abstractNote"):
+        _add_extra(item, "abstract-source: crossref")
+    return item

{zotkit-0.4.0 → zotkit-0.4.2/zotkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zotkit
-Version: 0.4.0
+Version: 0.4.2
 Summary: Headless Zotero library management: Web API CRUD plus direct WebDAV attachment upload/download — no desktop app required
 Author: Shawn
 License-Expression: MIT
@@ -104,6 +104,8 @@ zotkit find --tag status:to-read
 
 zotkit create --arxiv 2401.12345            # fetch arXiv metadata, dry-run preview
 zotkit create --arxiv 2401.12345 --apply --tags field:ai   # create + download & attach the PDF
+zotkit create --arxiv 2401.12345 1706.03762 math/0211159 --apply   # batch: one metadata
+                                            #   request, PDFs politely spaced ≥3 s apart
 zotkit create --doi 10.1038/nature14539     # fetch CrossRef metadata by DOI (no PDF —
                                             #   usually paywalled; attach manually after)
 
@@ -122,12 +124,27 @@ zotkit backup                               # full JSON snapshot -> backups/
 zotkit lint field:physics topic:new-idea    # offline tag check
 ```
 
-`--arxiv` takes an id or an abs/pdf URL and maps the full record (all authors,
-abstract, date, DOI, `preprint` item type); `--doi` maps CrossRef records
-(journal articles, conference papers, books, chapters, …) and refuses to guess
-on CrossRef types it doesn't know. Both accept `--collection` and `--tags`, and
-`--no-pdf` skips the arXiv PDF. Fetching metadata from arbitrary web pages is
-out of scope (zotkit stays a daemon-free CLI — no translation-server).
+`--arxiv` takes ids or abs/pdf URLs (several, space- or comma-separated) and maps
+the full record (all authors, abstract, date, DOI); `--doi`
+maps CrossRef records (journal articles, conference papers, books, chapters, …)
+and refuses to guess on CrossRef types it doesn't know.
+
+**Version of record**: when arXiv reports a *journal* DOI (the paper was formally
+published — as opposed to arXiv's own `10.48550/*` DataCite DOI), `--arxiv`
+builds the journal record from CrossRef instead of a `preprint`: proper item
+type, venue, volume/pages, formal date. The arXiv identity is kept — `arXiv: <id>`
+goes in Extra, the `url` stays the open-access abs page (the journal link lives in
+the DOI field), the arXiv abstract fills in when CrossRef has none, and the PDF
+still comes from arXiv. If the CrossRef lookup fails, the item falls back to the
+preprint record with a warning rather than failing. Items whose abstract zotkit
+wrote also carry an `abstract-source: arxiv|crossref` line in Extra, naming where
+it actually came from. Both accept `--collection`
+and `--tags`, and `--no-pdf` skips the arXiv PDFs. Rate limiting is built into the
+request layer — batches use one arXiv metadata request and space PDF downloads
+per arXiv's terms of use, so callers (humans or agents) never pace themselves. A
+bad id fails alone, not the batch; the exit code is non-zero only if something
+failed. Fetching metadata from arbitrary web pages is out of scope (zotkit stays
+a daemon-free CLI — no translation-server).
 
 Item JSON for `zotkit create --file` (a list, one object per reference):