Releases and stability¶

0.x (including tagged v0.9) is a first usable release. The operator install is clone plus docker compose build. The image is build-local only. There is no docker pull and no pip install paperful.

Required keys on paperful.run_report.v1 from build_report() are frozen (removed or renamed required keys are a break; extra keys may still be added). paperful.item.v1 may still move. This tree is not tagged 1.0.

1.0 (not tagged) still owes a lock on paperful.item.v1 and on snapshot/restore behaviour. Required paperful.run_report.v1 keys and imported-file attach (typed attach_failed, provenance note) are already the contract; extra report keys may still be added.

Schema compatibility (0.9, not frozen as 1.0)¶

Schema	Policy at 0.9	1.0
`paperful.run_report.v1`	Required keys frozen; extra keys may be added	Same
`paperful.item.v1`	Named. 0.x may add keys. Do not tag 1.0 until removal of a required key is a break	Lock
`paperful.snowball.candidate.v1`	Shipped and tested. Additive keys allowed	Revisit with the item lock
`paperful.mirror.v1`	Legacy `*.paperful.json` folds into `record.json`	One write path
Snapshot / restore	Behaviour shipped. Round-trip is not a 1.0 promise yet	Lock

Install claim tested in CI (.github/workflows/ci.yml, job docker): clone, docker compose build, doctor exits 2 when Zotero is absent. That is the release. There is no wheel and no GHCR image.

A second manager is not owed as a finished feature. Mendeley and EndNote adapters are in the tree and seeking testers; Zotero is the well-tested path. Until 1.0, pin a git tag or commit if you script against JSON. See the changelog for known limits. See Why paperful.

Ladder¶

doctor → collections → run --dry-run → run → report / report --json

--dry-run lists each item and a Would-hit column (sources that routing would try, in order). It does not download. Narrow with --collection / --library, plus optional --year-from / --year-to and --type / -T (Commands — Scope filters).

When Zotero is down, collections, run, attach, lint, fix-metadata, dedupe, gaps, recover, summarize, and synthesize exit 2 and print the same next-steps ladder (paperful doctor, enable local API, copy config.example.toml).

Optional LLM at 0.5¶

Off by default and additive: with [llm].enabled = false nothing in the PDF loop changes. Known limits: recover needs Python 3.11+ and a 14B-class local model to be useful; the Docker image does not include the LLM extras; identity/title verbs need a text layer (paperful ocr adds one to scans). summarize and synthesize default to writing both a disk file and a Zotero note (--to disk keeps the library tree clean). Config keys under [llm], [browser_agent], [summarize], [synthesize], [lint], [fix_metadata] may still move before 1.0. See LLM.

What 1.0 still owes operators¶

Outcome	Status at 0.9
Trust inside Zotero (attachment provenance stamp)	Shipped on Zotero attachment notes. A readable parent line follows `[remarks].surface`. Manifest `source` stays the record
One-line end-of-run banner + write-API yes/no	Shipped (`downloaded · attached · deferred · not_found · write-api`)
Locked report JSON schema	Required `paperful.run_report.v1` keys frozen; additive keys still allowed. Not tagged 1.0
Locked item record + snapshot/restore	`paperful.item.v1` named; 0.x may add keys
Mendeley and EndNote adapters	In the tree. Seeking testers. Zotero is the well-tested path
Fresh-clone doctor stays quiet without Scholar	Shipped (0.9): `scholar` opt-in like `scihub`