Research pack playbook¶

Narrative spine for a named -C topic build. Each verb stays honest: dry-run first, --apply writes, PDFs come from run / handoff / inbox, not from ingest. This is not paperful all and not a grey-lit playbook.

Seed greys and seed papers live in the collection before you start. After the ledger is honest, optional snowball watch or authorwatch (including suggest -C → accept), then the frontier digest (thin briefing is still there), then summarize / ask.

Workbench path (Advanced on Discover): refs gap → ingest-dois Preview → Apply, then First fill on Wanted. Click-by-click siblings: Walkthroughs.

Sequence¶

# 1. Cited in PDFs, not in the library. Always dry-run.
# Writes state/refs-gaps/<stamp>-<scope>/ (paperful.refs_gap.pack.v1).
# Exit 0 with a pack; 1 unknown collection / bad flags; 2 no manager and no mirror.
docker compose run --rm paperful refs gap -C COLLECTION
# read state/refs-gaps/*/pack.md and dois.txt

# 2. Classify DOIs against the library fingerprint. Still dry-run.
# Exit 0 even when some rows are exists / unresolved / held.
docker compose run --rm paperful ingest-dois --from-pack state/refs-gaps/<stamp> -C COLLECTION

# 3. Create metadata parents. Provenance tags: --tag, [ingest].default_tags, from-<stem>.
docker compose run --rm paperful ingest-dois \
  --from-file state/refs-gaps/<stamp>/dois.txt \
  -C COLLECTION --apply --tag TOPIC

# 4. PDFs for items already in -C (including the new parents).
docker compose run --rm paperful run -C COLLECTION --dry-run
docker compose run --rm paperful run -C COLLECTION
# remaining misses: system browser, then drop PDFs into [inbox].dir
docker compose run --rm paperful gaps -C COLLECTION --list-missing --handoff walk
docker compose run --rm paperful inbox drain
# optional: ask authors instead of fetching remaining misses
docker compose run --rm paperful reachout -C COLLECTION --to reachout.csv

# 5. Hygiene after creates and attaches.
docker compose run --rm paperful dedupe -C COLLECTION
docker compose run --rm paperful dedupe -C COLLECTION --apply

# 6. Optional frontier (no scheduler; no silent creates).
docker compose run --rm paperful snowball watch run NAME --digest
docker compose run --rm paperful snowball watch digest NAME
docker compose run --rm paperful snowball digest --run-id <run-id>

Contributors: the same verbs with uv run paperful …. On the workbench, Advanced Discover runs refs gap and ingest-dois with the same Preview → Apply tokens as Wanted Grab.

Sibling — briefing ↔ collection coverage: when the gap is “named in a frontier briefing or note but not under -C”, use paperful coverage (--from-file or --from-note) instead of refs gap. Pack under state/coverage/<stamp>/; then ingest-dois as above. See ROADMAP — Briefing ↔ collection coverage.

What to read on disk¶

Path	Schema / role
`state/refs-gaps/<stamp>/pack.json`	`paperful.refs_gap.pack.v1` — cited, missing, `ingest-dois` vs skip
`state/refs-gaps/<stamp>/dois.txt`	Missing DOIs for ingest
`state/coverage/<stamp>/pack.json`	`paperful.coverage.pack.v1` — briefing/note/file vs `-C` (`coverage`)
`state/coverage/<stamp>/dois.txt`	Missing DOIs from coverage rows
`state/runs/<stamp>-ingest-dois.json`	Created / exists / unresolved / held
`state/last-run.json`	`paperful.run_report.v1` after `run`
`state/snowball/<run-id>/digest.md`	Frontier digest for that queue
`state/snowball/watches/<name>/digest.md`	Frontier digest for that watch
`state/snowball/<run-id>/briefing.md`	Thin queue export
`state/snowball/watches/<name>/briefing.md`	Thin watch inbox export
`state/reports/<scope>-authors.json`	`paperful.authors_report.v1` from `authors --apply`
`state/author-packs/<slug>.proposed.toml`	Field pack until `snowball packs promote`

summarize and ask wait until dedupe and attach are boring. Harvest collection acronyms (paperful acronyms -C COLLECTION --apply) before a large fix-metadata recase if titles are ALL CAPS with corpus tokens (BBNJ, FAO, OECD). For frequent creators and institutional authors in the same slice, paperful authors -C COLLECTION --apply writes state/reports/<scope>-authors.json and a proposed field author pack; then snowball packs promote before relying on author_site. Optional CRM lookup is Twenty and SearXNG.

Exits (same table as commands)¶

Code	When
0	Success, including an empty dry-run or a classify with held rows
1	User error (unknown collection, missing `--from-file`, `--apply` without `-C` on a briefing or digest note)
2	Manager unreachable on a write, or no mirror yet on a read that needs the library
3	Partial batch (`inbox drain` mixed attach/errors; `run` mixed attach)

Out of this playbook¶

Silent parent create from inbox (default stays DOI attach)
Newsletter / Scholar-alert ingest
Firefox extension
Newsletter-scale ingest beyond a one-shot coverage --from-file check