Configuration reference¶

papio loads TOML from ~/.config/papio/config.toml (on Windows, %APPDATA%\papio\config.toml) unless the global --config <path> option selects another file. Configuration is layered over the built-in defaults; unknown TOML fields are rejected. papio init writes a validated user-only config file and papio doctor reports readiness.

The tables below list every decoded key in internal/config. Paths beginning with ~/ are expanded when papio loads them.

Top-level keys¶

[fetch]¶

[captures]¶

The [captures] section is strict-mode configuration: an older daemon rejects a config containing it. Deploy the binary that supports this section together with the configuration change.

[pdf]¶

[browser]¶

papio init can derive openurl_base_url from a pasted library discovery URL (--institution-url) or from the resolver configured in Zotero.

The browser path uses the user's ordinary Chrome session. It is not configured with passwords, MFA, CAPTCHA tokens, or publisher credentials.

papio init collects extension_id and firefox_extension_id during setup (Firefox defaults to the built add-on's papio@orgmentem.com), or set them non-interactively with --extension-id / --firefox-extension-id, so the native messaging host installs on the first run.

[browser.resolvers]¶

Named resolver profiles are per-institution tables keyed by a lowercase alphanumeric name; default is reserved for the implicit top-level institution and is rejected at load if used as a profile key. Each carries its own OpenURL base and, optionally, the same shibboleth_entity_id, proquest_account_id, libkey_mode, and libkey_library_id fields as the default [browser] institution — so a multi-institution user routes each job's login to the right library instead of inheriting the default's identity:

[browser.resolvers.campus]
openurl_base_url = "https://library.example.edu/discovery/openurl?institution=EXAMPLE"
shibboleth_entity_id = "https://idp.example.edu/idp/shibboleth"  # optional
proquest_account_id = "12345"                                     # optional
libkey_mode = "link"                                              # optional
libkey_library_id = 1234                                          # required for link mode

A profile may also be written as a bare string — campus = "https://library.example.edu/discovery/openurl?institution=EXAMPLE" — which is shorthand for a table with only openurl_base_url set. This keeps older single-base configs valid; add the table form when a profile needs its own login identity.

Select one with papio acquire --resolver campus, papio acquire --batch works.json --resolver campus, or the corresponding MCP field. The selected name is snapshotted in the job policy, so re-opened actions cannot silently fall back to another institution.

Set browser.default_resolver to one of these names (or leave it empty) to choose which profile an omitted resolver uses; an explicit --resolver/MCP resolver value always takes precedence, and an unconfigured default_resolver value is rejected at load.

On a tracked Alma/Primo resolver page, the extension may follow the first same-origin resolveService link selected by the institution's Online Services order. This emulates resolver direct linking without accepting provider terms or initiating physical-item, scan, or interlibrary-loan requests. Script access remains constrained by extension/manifest.json host permissions; an unlisted custom resolver origin stays in assisted mode.

[browser.document_delivery]¶

Configures the default institution's document-delivery / interlibrary-loan route (ADR-0017). Omitting the table disables it — a job that exhausts every acquisition candidate falls back to the profile's plain OpenURL route, the same behavior as before this table existed. The identical table nests under [browser.resolvers.<name>.document_delivery] for a named institution profile, alongside that profile's own openurl_base_url, shibboleth_entity_id, proquest_account_id, libkey_mode, and libkey_library_id.

A compiled auto_capable verdict additionally requires one recorded live acceptance — a supervised submit-and-reconcile against the real deployment under the institution's authority — so a compiled adapter plus matching config is necessary but not sufficient. papio init prints the compiled gate class before saving (AUTO-CAPABLE with its evidence, or PREFILL ONLY with the specific blocker) and papio doctor verifies what is verifiable while keeping DECLARED configuration and PASS/OBSERVED facts strictly separate: neither command claims automatic submission for a profile that cannot actually reach it.

[browser.resolvers.campus.document_delivery]
kind = "illiad"
base_url = "https://ill.campus.example.edu/illiadwebplatform"
allowed_hosts = ["ill.campus.example.edu"]
submit_policy = "auto_if_unconditional"      # or "prefill_only" / "never"
request_classes = ["digital_journal_article"]
legal_basis = "institution_policy"           # or "copyright_act_s49"
patron_attestation = "standing_completed"    # or "not_required" / "per_request"
patron_fee_policy = "zero_standard"
monthly_request_cap = 25
status_poll_minutes = 60
api_key = "..."
patron_ref = "configured-non-secret-reference"

[zotio]¶

papio invokes zotio but does not read or store Zotero credentials. Manual mutation remains preview-first: papio zotio plan returns immutable plans and papio zotio apply requires the exact confirmation SHA-256.

[hooks]¶

[[library.sources]]¶

Libraries papio consults to answer "do I already hold this paper?" for users who do not run Zotero. Repeat the table for each source (maximum 8 — every one is read on every search, batch, and discovery acquire-watch pass). Generic library.sources are ignored while zotio.executable is configured; otherwise they are the ownership authority for discovery acquire watches. Alert watches retain their historical zotio ownership path and do not consult generic sources.

Matching is exact on identifiers represented by the source format. No format supports every identifier, and titles are never matched. ISBN is excluded, because an edited volume shares one ISBN with every chapter in it. papio never infers PDF presence from per-manager attachment fields (BibTeX file, papis files) — the source declares it via claim.

A source unreadable to papio is reported as unreadable, not as holding nothing: papio acquire --batch then refuses to create jobs rather than re-downloading the whole batch. Before the fifth consecutive failure, each cadence attempts another run; a successful run resets the failure count. The fifth consecutive failure disables the watch; there is no re-enable command. After fixing the source, you may force-run it once with papio watch run <id>, but scheduled execution resumes only if you recreate the watch. --include-owned is available only for papio acquire --batch, meaning "proceed despite ownership uncertainty". Because a bibliographic export cannot say which manifestation it holds, such a source never satisfies an explicit --desired-version published request. papio doctor performs a fresh one-shot probe of each source and reports that read's record count and outcome; it does not report daemon cached age, count-collapse detection, or retained failure state. See the filing guide.

[notify]¶

The notification router has two independent legs: local desktop interruptions for a human, and webhook delivery for automation. Desktop delivery is best-effort and currently available only through the macOS sender; an unsupported platform is reported by papio doctor and does not consume the desktop rate budget. Webhooks are not subject to quiet hours, focused-surface suppression, or the desktop rate ceiling.

The milestones preset is the default: it sends immediate coalesced standalone outcomes and newly opened decisions, a four-hour pending-decision digest, a bounded batch checkpoint/final summary, discovery as catch-up or digest material, capped integrity notices, and one system-degraded notice per episode. Work that is continuing or scheduled does not produce a desktop interruption. The preset treatment is:

[notify.categories.<name>]¶

Use one table for each category whose routing should differ from the preset:

[notify.categories.decision_opened]
desktop = "immediate"   # off | digest | immediate
webhook = "immediate"   # off | digest | immediate
window_seconds = 300

The valid category names are request_outcome, decision_opened, decision_pending, completion_batch, discovery_new, integrity_notice, and system_degraded. desktop and webhook each accept off, digest, or immediate; an empty value inherits the preset. window_seconds defaults to the preset's window when 0 (or when omitted) and otherwise must be in 0..86400. Webhook mode is independent automation routing: it remains immediate by default and ignores desktop quiet hours, focus suppression, and rate limits. A category may override its webhook mode without changing its desktop mode.

This section is strict-mode configuration. Deploy the binary that understands these fields together with the configuration change; an older daemon rejects unknown [notify] fields.

[updates]¶

[discovery]¶

[actions]¶

This is deliberately not browser.action_expiry_seconds. That one (30 minutes by default) is a reminder cadence — how soon to nudge you again about an open action — so reusing it as a staleness threshold would report a handoff queued over lunch as abandoned. This one answers "has anyone given up on this?", which is measured in days.

[sources.<name>]¶

[sources] is a map of resolver policies. Its keys are whitelisted separately from papio's general strict-unknown-field rejection: the map itself decodes freely, and validate() rejects an unrecognized key at load with the list below. The valid names are arxiv, europepmc, unpaywall, openalex, core, crossref_tdm, crossref_metadata, retraction_watch, semanticscholar, and openaire. One further name, openalex_content, is a removed key: an earlier papio release wrote it into Default() and no adapter for it ever shipped, so a config carrying it loads normally and drops the key silently rather than breaking on upgrade — it is not a valid key to add yourself. For semanticscholar, enabled governs the acquisition resolver (open-access PDF lookup by exact DOI, arXiv id, or PMID); selection as a search backend is separate and lives in [discovery] (which reads this section's api_key). For openaire, candidates come from the OpenAIRE Graph (metadata licensed CC-BY, acknowledged here and in candidate provenance); the keyless public limit is 60 requests/hour — the default rate_per_sec honors it, and a personal-token api_key raises the ceiling. Each named section accepts these keys:

| Source name | enabled | rate_per_sec | burst | | arxiv | true | 1 | 1 | | europepmc | true | 2 | 2 | | unpaywall | true | 1 | 1 | | openalex | false | 2 | 2 | | openaire | true | 0.016 | 1 | | core | false | 0.4 | 1 | | crossref_tdm | false | 1 | 1 | | crossref_metadata | true | 1 | 1 | | retraction_watch | true | 1 | 1 | | semanticscholar | true | 1 | 1 |

openaire's rate_per_sec looks oddly precise because it is pinned to a documented ceiling: OpenAIRE allows 60 requests per hour to unauthenticated callers, and 0.016 × 3600 = 57.6. Do not raise burst to make bursty demand go through — the hourly budget is burst + rate_per_sec × 3600, so at this rate a burst above about 2 would breach the published ceiling.

To get more OpenAIRE throughput, authenticate: 7,200 requests per hour is 120× the keyless allowance, and it is free. OpenAIRE issues two kinds of credential and only one of them can run a daemon:

1. Fill in the personal information form — the newer registration flow gates both credential types behind it.
2. Go to Registered Services, click + New Service, pick the Basic security level, and create it. Copy the Client ID and Client Secret it shows you.
3. Put them in [sources.openaire] as client_id and client_secret.

papio exchanges that pair for an access token as needed and refreshes it before it expires. The alternative credential — a personal access token — is a single string you can paste into api_key, but OpenAIRE expires it one hour after issuing it, so it is only useful for a manual check. papio doctor warns when api_key is carrying one.

Note that OpenAIRE reports x-ratelimit-limit: 7199 in its responses even to unauthenticated requests, so that header is not a safe basis for choosing rate_per_sec. Use the documented ceiling for the tier you are actually in.

Setting client_id/client_secret also raises rate_per_sec to 1.9 and burst to 5 (6,845 requests/hour against the documented 7,200), because a credential that authenticated but changed nothing observable would be two knobs for one intent. An explicit rate_per_sec or burst in your config always wins. A personal access token in api_key does not raise pacing: it authenticates for an hour, and pacing to the authenticated ceiling on a credential that can vanish mid-hour would leave papio running at 120× an unauthenticated allowance.

Watch configuration¶

There is no [watch] section or watch-specific key in papio's TOML config. Watch query, year filters, OA filter, collection, cadence, and per-run cap are stored with each watch created by papio watch add or the corresponding MCP tool. Use papio watch list to inspect them and papio watch remove <id> to remove one.

Validation and file permissions¶

papio validates configuration when loading and saving it. It writes the config file with mode 0600 and its config directory with mode 0700; doctor reports a configuration permission failure when group or other read bits are present. Use papio doctor rather than weakening these permissions to diagnose a setup problem.