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.

Integration credentials¶

papio config credentials manages TypeSafe, OpenAlex, Semantic Scholar, CORE, Crossref TDM, OpenAIRE, ILLiad and notification-webhook credentials through one service. The default store is macOS Keychain, Windows Credential Manager or Linux Secret Service. Linux needs an unlocked Secret Service; Papio never falls back to a plaintext file when a store is unavailable.

papio config credentials set sources.openalex
papio config credentials status
papio config credentials migrate

set TARGET reads a key at a hidden prompt and creates a fresh record. A secret manager can pipe input with --key-stdin. Never put a real secret in a command argument. Use the global --config <path> to select a profile.

The targets are sources.openalex, sources.semanticscholar, sources.core, sources.crossref_tdm, sources.openaire, agent.typesafe, notify.webhook, browser.document_delivery, and browser.resolvers.<name>.document_delivery. Delivery targets exist when that institution has an ILLiad route configured.

OpenAIRE and webhooks take a typed JSON record through stdin. These examples show the input shape; replace the placeholders through your secret manager, without putting credentials in shell history:

{"version":1,"kind":"openaire_client","client_id":"CLIENT_ID","client_secret":"CLIENT_SECRET"}

{"version":1,"kind":"openaire_token","api_key":"PERSONAL_ACCESS_TOKEN"}

{"version":1,"kind":"webhook","url":"https://hooks.example.org/PRIVATE_ENDPOINT","bearer":"OPTIONAL_BEARER"}

The complete webhook URL is secret storage material: paths and query strings can contain tokens. Omit bearer when the endpoint needs none. Records are limited to 2,048 encoded UTF-8 bytes to fit every supported OS store.

Configuration stores an explicit credential_ref, such as keyring:0123456789abcdef0123456789abcdef, at the consuming integration. Notifications use notify.webhook_credential_ref. Moving the config or data directory preserves this binding. Copying config to another machine does not copy its secrets. To share a record deliberately, use papio config credentials bind TARGET REFERENCE. The record's kind must match the target. Binding TypeSafe also enables cloud decisions for that profile; a key stored for another profile does not enable them.

For headless use, bind env:YOUR_SECRET_VARIABLE. Single-key integrations read the variable as a key; OpenAIRE and webhooks read the JSON shapes above. The variable must be available when binding and when starting the daemon. Papio snapshots selected variables and removes them before launching vault helpers, PDF workers or hooks. References are authoritative: a missing or invalid value never falls back to another credential.

status [TARGET] reports the selected source and whether it resolves locally; it does not test provider authentication. detach TARGET removes the binding without deleting a shared record. delete REFERENCE explicitly deletes an OS record and can affect other configs that refer to it. Restart the daemon after changes with papio daemon stop; the next ordinary command starts it again.

migrate converts this profile's legacy TOML secrets and old TypeSafe record. It validates the inventory, creates and verifies fresh records, rejects observed concurrent config edits, then publishes one atomic config update. A failed save leaves the original config in place and reports any staged references for cleanup. It leaves the old TypeSafe record intact and saves the previous config to config.toml.bak (mode 0600), which can still hold the literal secrets; delete it after you check the result. An active legacy TypeSafe environment override must be removed before migration. Install a compatible daemon and native host first: older strict config parsers cannot read the new reference fields.

Resolved secrets stay in runtime memory, separate from serializable config. Missing keys disable required-key integrations; services with a supported keyless mode continue at that mode's quota. papio doctor explains the selected credential's state. Unrelated acquisition remains available.

Agent acquisition¶

Run papio config agent set to enable TypeSafe/Jev for delegated browser acquisition when packaged and generic routes fail. It reads your key at a hidden prompt and saves it in macOS Keychain, Windows Credential Manager or Linux Secret Service. A secret manager can pipe the key into papio config agent set --key-stdin; avoid literal keys in shell commands. These commands are compatibility entry points to the shared credential service above. New setup writes an explicit reference, so moving the profile preserves its key binding. Existing path-derived records remain readable until migration. On Windows, run setup and start the daemon from your signed-in desktop session. SSH network logons cannot read Windows Credential Manager's user credential set; a daemon started there cannot use the saved key. This is a Windows logon-session constraint, not a missing key. Use a local terminal or let the browser's native host start the daemon.

Supplying the key opts into sending the article DOI, bounded title and sanitized control descriptions to TypeSafe; see Privacy. The credential never enters TOML, the extension or job history. Setup stores backend = "typesafe" and a non-secret credential_ref in the [agent] section. Empty or absent backend disables stored-key lookup; other backend values are currently rejected. This new section requires a compatible daemon and native host before it is added to an older installation's config.

Run papio daemon stop after setup; the next ordinary command starts the daemon with the new setting. papio config agent status reports saved configuration, credential availability and the current command's environment override, without printing a key or claiming the running daemon reloaded. papio config agent remove detaches the key and disables enrollment without deleting the stored record; restart afterward. Use papio config credentials delete REFERENCE --yes for explicit record deletion; without --yes it only describes the deletion, and it refuses a record this configuration still binds. If the OS store is unavailable, agent inference is disabled with a daemon diagnostic, while ordinary acquisition remains available.

PAPIO_TYPESAFE_API_KEY in the daemon's environment remains a legacy override when no agent.credential_ref is configured, and does not require [agent]. An explicitly empty legacy value disables Jev even when an old saved key exists. A new explicit reference takes precedence over this legacy variable. Removing the variable restores the profile's configured behavior after restart. To disable Jev completely, remove both enrollment and any launch environment override. Changing your shell's environment does not change an already running daemon.

Both daemon and extension must support agent_fallback_v1. Effective site access is still required, including for publishers without an adapter. The initial implementation handles controls on a DOI-identified article in a managed tab. Chrome uses its filename-steering download API. Firefox requires both peers to support native_click_adoption_v1. It uses a fresh download with an exact article referrer, then asks the daemon to copy and validate that file. The file must be directly in the parent of the configured adoption root, normally Downloads. Custom browser download directories must match that configuration. Missing referrers, ambiguous downloads, UNC paths and save dialogs remain assisted. With agent_navigation_v1, both browsers can follow a selected same-origin link in the same tab, verify the destination DOI and continue under the original attempt. Firefox transfers its unused reservation without resetting its expiry or download-directory baseline. Unexpected redirects, new tabs and native PDF viewer saving still require assistance. An HTML PDF wrapper can be followed when it exposes one matching file. This is distinct from saving a document already loaded in the native PDF viewer; signed viewer URLs are not replayed to simulate that capability. The daemon and decision contract are shared across operating systems. It allows up to 60 decisions in ten minutes per drive permit and 30 seconds per model call. Failures consume their call reservation; retries do not reset the budget. These limits are implementation defaults, not TOML settings.

The daemon removes the key from its process environment after reading it, before starting PDF workers, hooks or other integrations. The backend interface supports local implementations without a key or network; no local model runtime ships yet. Credential setup is currently a CLI command.

Top-level keys¶

[fetch]¶

[host_suppression]¶

The [host_suppression] 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.

[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. A name that matches a packaged provider route hint (a provider family such as sage-doi-pdf, or an exact route revision) is also rejected at load. Each carries its own OpenURL base and, optionally, the same shibboleth_entity_id, proquest_account_id, openathens_domain, 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
openathens_domain = "example.edu"                                 # 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, openathens_domain, 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
credential_ref = "keyring:0123456789abcdef0123456789abcdef"
patron_ref = "configured-non-secret-reference"

[retraction]¶

The default preserves the earlier job-scoped behavior. An upgrade does not silently disclose a wider DOI corpus. This strict-mode section requires a daemon version that recognizes it.

An empty or sharply reduced library export can indicate an unfinished write. The sweep keeps earlier notices and acknowledgements while it confirms the smaller size. Consecutive complete reads must report the same smaller DOI count over at least 72 hours before the sweep accepts it. A restored export, a different count, or an enumeration failure resets that window. The cache keeps the confirmation state across daemon restarts.

[zotio]¶

papio invokes zotio but does not read or store Zotero credentials. Item and attachment mutation stays preview-first: papio zotio plan returns immutable plans and papio zotio apply requires the exact confirmation SHA-256. papio zotio tags reconcile is the separate exception: it converges papio's own papio:needs-action and papio:unavailable tags with no preview step. papio zotio tags retractions previews by default and writes only with --apply.

[hooks]¶

[filing]¶

See the filing guide for receipt inspection and explicit retry commands.

[[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 watch pass). Generic library.sources are ignored while zotio.executable is configured; otherwise they are the ownership authority for discovery watches: acquire watches, alert watches, and papio acquire --from-digest.

A command source runs at most once per refresh_seconds, never once per paper. Lookups that arrive while it runs share that one run. The command inherits the daemon's environment. Its standard input is empty, and papio never reads or reports its standard error. When the command exits, papio stops every process it started and left running, so do not start background work from it. The command must print only the records its claim covers. For pdf_present, print only the entries whose PDF you hold; papio does not filter the output by attachment fields. A run fails when the command exits non-zero, passes timeout_seconds, prints more than max_output_bytes, or prints output that does not parse. A failed run never counts as an empty library: the source reports as unreadable. The previous successful run can then still mark papio search results, but it never skips an acquisition. After a failure, papio waits up to 30 seconds (or refresh_seconds, if shorter) before it runs the command again. When the last successful run is older than refresh_seconds plus 15 minutes, its results are no longer shown at all.

Both file and command sources keep their last good entry count in data_dir. A drop below one tenth of a previous count of at least 20 entries makes the source incomplete. This protects against truncated exports even after a restart. An intentional reduction becomes complete after consecutive successful reads report the same smaller count over at least 72 hours. A restored export, a different count, or a failed read resets that confirmation window.

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. After fixing the source, force a run with papio watch run <id>; when it succeeds, papio watch resume <id> puts the same watch back on its schedule. --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 daemon claims a webhook before it sends the POST. It does not send that intent again after a crash or a failed response. A later event that arrives after the claim gets a new delivery_key and its own POST. Activity attempts to record a failed attempt, but a logging failure can leave no Activity row. The JSON event carries the key so receivers can check each delivery.

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]¶

[open_books]¶

Configures the open_books source, which finds an open-access copy of a book from its ISBN. [sources.open_books] carries its enabled, rate_per_sec and burst; this table carries where it looks. The source acts only on a work whose sole strong identifier is the ISBN (papio acquire --isbn …): a request that also has a DOI, PMID, arXiv ID or OpenAlex ID is fetched by those, and the ISBN alone is still not a fetchable identifier for any other source. A repository record is a candidate only when its own ISBN field lists the requested ISBN, it carries an open licence statement (or the repository is open access by definition), and its ORIGINAL bundle holds exactly one PDF. See ISBN-only requests.

[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.

[drive]¶

The paced drive opens parked handoffs for you, one paper at a time, oldest first, through the same path papio actions open uses. The extension's own handoff settings still decide where the tab opens (the work window or papio's tab group). The drive never accepts terms, never submits a delivery request, and never resolves an identity review. It only puts the handoff on screen, as an operator's open would.

The drive opens nothing while any of these holds, and papio drive status names each one as a blocker:

• it is disabled, or paused by papio drive pause or because two paced papers in a row stalled at the sign-in;
• the time is inside notify.quiet_hours;
• no browser holds the papio session;
• the hourly bound is spent;
• its previous open is still in flight;
• any browser claim or effect permit is live, including one an operator started;
• a sign-in is open and still inside sign_in_wait_minutes;
• no parked job is eligible.

Eligible jobs are those awaiting a person on one open openurl_handoff, and those on one open manual_download that papio jobs redrive would accept; the drive redrives such a job through the same store function first. When that redrive sends the job back to resolving (a manual download left by an open-access route, or a job whose institution has already reported no entitlement), the drive opens nothing on that pass: resolving offers the open-access handoff again when that route remains. It never opens an openurl_available advisory, because that link opens outside papio's window. It skips a job it opened within job_backoff_hours, and every job behind a provider host that is refusing this browser: a host in a browser.provider_cooldown, or a job with a Cloudflare-style challenge in the last 10 minutes. The skip covers the papers that went to that host and every paper under the same DOI prefix. A paced paper whose sign-in stalled cools its own route the same way.

Every paced open records drive.paced_open on the job and, when it opens a handoff, handoff.opened with principal pacer. Pauses and resumes are the system events drive.paused and drive.resumed. papio drive resume always holds: sign-in evidence recorded before it never pauses the drive again.

This section is strict-mode configuration. Deploy the binary that understands it together with the configuration change; an older daemon rejects the whole file when [drive] is present.

[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, openaire, and open_books. 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 arxiv and semanticscholar, enabled governs the acquisition resolver. Selection as a search backend is separate and lives in [discovery]; Semantic Scholar search also uses this section's resolved credential. 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. A resolved registered-service client pair raises the effective pacing; a short-lived personal token does not. 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 | true | 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 | | open_books | true | 0.5 | 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. Save them as one openaire_client record with papio config credentials set sources.openaire --key-stdin, using the JSON shape in Integration credentials.

papio exchanges that pair for an access token as needed and refreshes it before it expires. The alternative credential — a personal access token — can be stored as an openaire_token record, 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.

Resolving a complete client credential pair 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.