BBNJ author-site + authorwatch (dogfood)¶

Harden the author_site grey lane and authorwatch on a real library slice. Paperful’s Zotero path is ocean/BBNJ (Ocean → BBNJ). -C BBNJ alone will not resolve that collection.

This is operator dogfood, not a 1.0 blocker. See authorwatch, workflows § field author packs, and research-pack.

Collections¶

Role	`-C` / `--collection`	Notes
Production slice	`ocean/BBNJ`	~1300 items (authors report 2026-10-06). Do not dump authorwatch applies here.
Dogfood slice	`ocean/BBNJ-test`	Sibling under Ocean. Membership copy of a small `ocean/BBNJ` subset, plus optional authorwatch creates. Safe to `--apply`.
Authorwatch landing (optional)	`ocean/BBNJ-test`	Same test collection; tags `paperful-authorwatch` / `from-<list>`.

Pack slug from authors --apply is the collection path with / → -: ocean-bbnj (production) and ocean-bbnj-test (dogfood). Promote the slug you intend the fetch lane to use:

paperful snowball packs promote ocean-bbnj        # production
paperful snowball packs promote ocean-bbnj-test   # dogfood

author_site is not in DEFAULT_SOURCES. The lane is appended when a promoted pack has listing_url / base_host, state/author-contacts/ has a website, or Twenty is ready.

What “hardened” means¶

Lane	Success signal
author_site	On missing-PDF items whose creators match the pack, `run --dry-run` shows `author_site` in Would-hit; a live run may attach with stamp `grey:author_site` (not OA).
authorwatch	List members are `ok` (ORCID or OpenAlex id); first `run` without `--backfill-from` proposes 0; `--backfill-from` proposes works not already in the library fingerprint; `apply` + `run` on `ocean/BBNJ-test` is boring and repeatable.

Phase 0 — Preconditions¶

Confirm the path: paperful collections list must show ocean/BBNJ.
paperful doctor. Refresh the mirror so authors reads out/.
Baseline production (read-only):
```
paperful gaps -C ocean/BBNJ --list-missing
paperful run -C ocean/BBNJ --dry-run --no-browser-agent
```
Prefer --format json if you will diff later. Do not use this as the live fetch target for first experiments.
Optional knobs in config.toml: [twenty].enabled, [searxng].base_url, [snowball].author_site_preflight (off until Phase 2).

Phase 1 — Author-site: corpus → pack → promote¶

Production harvest (already run once: state/reports/ocean-bbnj-authors.json):

paperful authors -C ocean/BBNJ
paperful authors -C ocean/BBNJ --apply

That writes state/reports/ocean-bbnj-authors.json and state/author-packs/ocean-bbnj.proposed.toml. Corporate name-only creators stay report-only.

Human review (critical): edit the proposed pack for the top people who actually host greys/PDFs. Set listing_url or base_host (faculty / institute publications page — not a journal landing, not ResearchGate). The fetcher scrapes listing HTML for PDF links matched by DOI, title similarity, or surname-in-URL (paperful/sources/author_site.py). Common surnames (wright|w, smith|s, wang|w) need a listing URL, not fingerprint-only.

Promote, then doctor should show author packs: N promoted.

paperful snowball packs promote ocean-bbnj
paperful doctor

Dogfood the same loop on the test collection after Phase 0b:

paperful authors -C ocean/BBNJ-test
paperful authors -C ocean/BBNJ-test --apply
# edit listing_url on a few rows in state/author-packs/ocean-bbnj-test.proposed.toml
paperful snowball packs promote ocean-bbnj-test
paperful run -C ocean/BBNJ-test --dry-run --no-browser-agent --retry-failed
paperful run -C ocean/BBNJ-test --no-browser-agent --retry-failed   # small slice only

Failure notes to keep: no pack match, no listing URL, listing fetch failed, no title/DOI pdf on listing. After wins: state/fetch-wins.jsonl, attachment stamp grey:author_site.

Frequent people from the 2026-10-06 production report (not all are good listing targets): Wright, Gjerde, Rochette, Dunn, Harden-Davies, Ardron, Halpin, Currie, Vierros, Cremers, Freestone, Unger, Jaspars, Levin, Mendenhall, Thiele, Jaeckel, Durussel, Tiller, Van Dover.

Phase 0b — Create `ocean/BBNJ-test`¶

Do not copy the whole 1300-item tree. File a small membership subset (missing-PDF + a few with PDFs from high-frequency people). collections add files existing keys; it does not create the collection. Create the path first (ensure_collection_path via ingest/apply, or a one-shot connect).

# keys file: one Zotero item key per line (from ocean/BBNJ)
paperful collections add -C ocean/BBNJ-test --keys-file state/bbnj-test-keys.txt --dry-run
paperful collections add -C ocean/BBNJ-test --keys-file state/bbnj-test-keys.txt --apply

If resolve_collection fails, create ocean/BBNJ-test in Zotero (or via backend ensure_collection_path) then re-run add.

Phase 2 — Optional boosters (one variable at a time)¶

Booster	When	Command
Twenty lookup/sync	CRM listings for ocean people	`paperful twenty lookup -C ocean/BBNJ --apply` then `twenty sync -C ocean/BBNJ --apply`
Write-back	After a real `author_site` attach	`run --twenty-writeback` (opt-in)
Snowball preflight	BBNJ snowball profile	`snowball … --author-site-preflight` (SearXNG caps)

Keep production -C ocean/BBNJ for lookup/sync; keep fetch experiments on ocean/BBNJ-test.

Phase 3 — Authorwatch: `bbnj-test-voices`¶

Seed from people you already follow (ORCID preferred), not every co-author on every BBNJ item.

paperful authorwatch save bbnj-test-voices
paperful authorwatch add bbnj-test-voices --orcid 0000-0002-XXXX-XXXX --name "Display Name"
paperful authorwatch resolve bbnj-test-voices
paperful authorwatch show bbnj-test-voices
paperful doctor   # must not amber “zero ok members” for this list

Cursor baseline (proposes 0, no library open):

paperful authorwatch run bbnj-test-voices

First useful poll (publication date, not OpenAlex index time):

paperful authorwatch run bbnj-test-voices --backfill-from 2024-01-01 --max-authors 10 --per-author-limit 20
paperful authorwatch briefing bbnj-test-voices
paperful authorwatch apply bbnj-test-voices -C ocean/BBNJ-test
paperful authorwatch apply bbnj-test-voices -C ocean/BBNJ-test --apply
paperful run -C ocean/BBNJ-test --dry-run --no-browser-agent

Optional corpus seed (opens the library; does not create parents):

paperful authorwatch suggest bbnj-test-voices -C ocean/BBNJ --method mix --limit 15
paperful authorwatch accept bbnj-test-voices --id sug_…   # or checkboxes in Discover

Cadence: weekly authorwatch run + review state/authorwatch/bbnj-test-voices/inbox.jsonl. Paperful does not schedule.

If authorwatch run exits 2 with OpenAlex daily budget is spent, that is the shared no-key pool (common on a VPN). Set OPENALEX_API_KEY and retry; do not treat it as an empty frontier. Membership copies from ocean/BBNJ were already tried in the production manifest: dogfood fetch needs --retry-failed or the dry-run table stays empty. run --dry-run Would-hit does not yet append author_site (the live pipeline does).

Dogfood log (2026-10-06)¶

Created ocean/BBNJ-test (Zotero key 44FTZZLW); filed 20 keys from ocean/BBNJ (state/bbnj-test-keys.txt).
Promoted pack ocean-bbnj-test with listings (IUCN Gjerde, IDDRI Rochette, Edinburgh Harden-Davies, glenwright.net Wright).
run --retry-failed --sources unpaywall,direct: 2 attached (direct, IDDRI PDFs). author_site ran on 10 leftovers: 8× no title/DOI pdf on listing, 1× no pack match, 1× listing fetch failed. Wright listing did not fire — Wright items in that 20 already had PDFs.
authorwatch list bbnj-test-voices: 5 ok ORCIDs. An early poll hit a spent OpenAlex budget (traceback — now exit 2). Later --backfill-from 2025-01-01 --max-authors 2 proposed 3, exists 7; --apply created 3 parents in ocean/BBNJ-test; one 2025 PDF attached via Unpaywall.

Phase 4 — Engineering follow-ons (from real failures)¶

HTML fixtures for 2–3 listing pages (win + miss) under tests/fixtures/.
Golden pack row (listing_url + fingerprint) in tests.
Tally author_site skip reasons from attempts[] / run JSON.
Same person in pack + authorwatch: exists must skip duplicate creates.
Do not add a nightly “ask everything” or scrape RG/LinkedIn.

Risks (BBNJ-specific)¶

Org authorship (FAO, ISA, UN, IUCN as name-only): no pack row, no author_site. Grey playbooks cover IGO PDFs; author-site is the long tail.
Common surnames: hold or require ORCID / listing URL.
Treaty “canonical” BBNJ: keep authorwatch creates on ocean/BBNJ-test.
Saved profile profiles/bbnj-journal.toml uses collections = ["ocean/BBNJ"].