Library UI: ReadCube, not deep-research

Publish a ReadCube-importable bundle from the registry — RIS bibliography, primary PDFs, manifest, import report.

deep-research does not build or maintain a browser library, an embedded PDF reader, or any in-app annotation UI. You browse and read papers in the ReadCube desktop app; /deep-research:export readcube prepares a local, self-contained import bundle for it on request. It never edits ReadCube's database, uploads anything, or confirms an actual import — every result carries readcube_import_status: "unknown" for exactly that reason.

This replaces an earlier browser-app plan. A custom SQLite-backed local web app with an embedded PDF reader was drafted and partly built, then retired in favor of ReadCube. The SQLite storage layer that work produced (skills/deep-research/scripts/refmgr/) wasn't thrown away — it's the newer of two data sources this export command can read from, described below.

Command

/deep-research:export --repo <research-repo> \
  (--all | --evidence-id <id> [...] | --run-dir <run>) \
  --destination <local-folder> \
  [--name <batch-name>] [--incremental] [--bib] [--require-pdfs] [--dry-run] \
  [--source legacy|refmgr] [--library <path>]

Selection — exactly one of --all, --evidence-id (repeatable), or --run-dir. Unresolved --evidence-ids block publication entirely, listing every one that failed, not just the first. --run-dir selects a run's actually-included records (screening.decision == "include") and rejects a run with no resolvable screening state.
--destination — any locally accessible folder, including an already-downloaded iCloud Drive folder. Always explicit; never guessed.
--incremental — compares each record's metadata + attachment fingerprint against a per-destination ledger. Nothing changed → no batch directory is created at all, a structured no-op. A failed publish attempt never becomes a future baseline.
--bib — also writes references.bib. RIS stays the primary import format; import one bibliography file into ReadCube, not both.
--require-pdfs — blocks publication (nothing written) if any selected record's asset doesn't resolve. Without it, metadata-only records still publish, with a warning.
--dry-run — same selection/resolution/manifest logic, same reported counts, zero filesystem writes.

Two Data Sources, One Command

Real paper data lives today in the original JSONL registry (data/papers/registry.jsonl) — one primary asset pointer per record. The newer refmgr SQLite layer supports multiple attachments per paper (primary, supplement, version) with checksum-verified content-addressed storage, but starts empty until it's populated. --source picks which one the export command reads from — the bundle format, manifest schema, and CLI surface are identical either way:

`--source`	Reads	Selection support	Attachments per record
`legacy` (default)	`--repo`'s `registry.jsonl`	`--all`, `--evidence-id`, `--run-dir`	One (the registry's single asset pointer)
`refmgr`	`--library`'s SQLite database	`--all`, `--evidence-id` (bare paper id, or `scheme:value` identifier lookup) — not `--run-dir`	All of them — primary into `PDFs/`, everything else into `Supplements/`

--run-dir is a deliberate rejection for --source refmgr: a run's evidence_ids use the legacy registry's scheme, and there's no defined way to cross-resolve those against refmgr identifiers yet.

Bundle Layout

Sketch first, exact tree below it:

One published batch. Staged in a temp directory first, then moved into place in one atomic rename.

<destination>/<batch-name>-<unique-id>/
  references.ris
  references.bib             # only with --bib
  PDFs/<safe-label>--<hash-prefix>.pdf
  Supplements/
  manifest.json               # schema/17-export-manifest.md
  import-report.md
  README.md
  COMPLETE.json                # written last; local completion only

Publication is staged and atomic — everything is written into a temporary directory first, then moved into its final location in one filesystem rename, so a crash mid-export never leaves a half-written batch. Every copied file is re-hashed after the copy and compared against the source's checksum before anything is considered complete.

Storage Added

File	Written by	Contents
`data/papers/export_ledger.jsonl`	`export.py` (`--incremental`)	Per-destination, per-record metadata + attachment fingerprint of the last published export — a failed attempt never counts as a baseline.
`<library>/library.sqlite3`	`refmgr/` (`--source refmgr` only)	Papers, identifiers, assets, attachments, organization, an FTS5 search index, and saved searches — a separate store from `registry.jsonl`, not yet the default.

What's Still Manual

Two things can't be automated: verifying the bundle actually imports correctly in the real ReadCube desktop app, and running a real export to a real iCloud (or other) destination folder. A ready-to-import compatibility-trial bundle — seven references covering full metadata, metadata-only, no-identifier, Unicode, a supplement, and a preprint/published version pair, with real viewable PDFs — already exists at skills/deep-research/references/fixtures/compat-trial/, with its own README walking through what to check.

Slash command: commands/export.md. Full agent-facing spec: references/readcube-export.md. Manifest schema: references/schema/17-export-manifest.md. Backlog and standing decisions: REFERENCE_MANAGER_V2_PLAN.md.