# PaperForge Agent Guide
This guide is part of the crate through `paperforge::AGENT_GUIDE`. It defines the safe operating sequence for an autonomous agent.
## Operating Sequence
1. Parse user text with `parse_paper_query`. Never construct provider query strings from raw user input and never downgrade a parser error into a broad search.
2. Inspect the resulting `PaperQuery`: report exact identities, required/excluded clauses, date bounds, mode, explicit sort, limit, and provider directive. Ask for clarification if these do not represent the user's intent.
3. Instantiate exactly one `PaperForge` with a descriptive contact-bearing User-Agent. A query `@provider` must match this provider. Provider operation and deduplication are local to that provider in version 0.1.
4. Call `discover_detailed` once to form a dry plan. Present canonical ID, title, provider, date, document format, expected size when known, preflight `PaperRights`, raw `candidate_count`, `eligible_candidate_count`, and candidate-bound evidence. If `candidate_cap_reached` is true, say that ranking covers only the bounded provider page. Do not describe a publicly downloadable paper as public domain or redistributable unless explicit evidence says so.
5. Obtain user direction before archival when the surrounding application requires approval. Choose a controlled output root and a nonzero `max_download_bytes`; the default is 256 MiB.
6. Call `archive_with_progress`. Treat individual entries in `failed` as failures even though the aggregate call returned successfully. Do not retry by changing URLs, disabling caps, following redirects, or accepting a different MIME.
7. Verify success from the returned summary and each `ArchivedPaper.manifest`, or call `inspect_archive`/`verify_archive`; both public functions perform full verification. Europe PMC JATS rights are post-download evidence and may resolve to an explicit license, `Unknown/JATS-unresolved`, or `Unknown/JATS-ambiguous`, independently of retained preflight search metadata. With `skip_existing`, a skip means PaperForge reverified current revision/search-rights evidence, the manifest, document identity, file length, magic, and BLAKE3. It is not a path-existence shortcut.
## Query Examples
```text
graph networks +"molecular property" -survey title:protein author:"Jane Smith" topic:cs.LG after:2022 before:2026 @recent @limit:25
doi:10.1038/s41586-024-00000-0 @provider:europe-pmc
https://arxiv.org/abs/2401.12345v2
pmcid:PMC1234567 @sort:citations
ntrs:20230001234 after:2020 @sort:date
```
Quoted text is contiguous. `+` is required and `-` is excluded. Bare positive terms are optional scoring clauses, but at least one must match when there are no required terms. Provider retrieval uses optional OR candidates when there is no required clause; when required clauses exist, optionals do not restrict retrieval. Field clauses match only that field. Exclusions cannot form an otherwise unbounded query. `after` and `before` are inclusive and accept `YYYY`, `YYYY-MM`, or `YYYY-MM-DD`.
Ranking tiers, highest first, are exact identity, exact title phrase, all positives with title/phrase evidence, all positives, required plus optional, and filter-only. Field weights are title 8, author 5, topic/category 4, abstract 3, and journal 2; phrase evidence outranks token evidence. Ranking is deterministic within a fixed provider-local candidate budget of 100. Default sorting is relevance. `@recent` keeps relevance tiers ahead of date, and Europe PMC `@top` keeps tiers ahead of actual citations. arXiv and NASA reject `@top` and citation sorting because their citation counts are absent rather than fabricated.
## Provider Capabilities
### arXiv
Use `https://export.arxiv.org/api/query`. Landing and PDF hosts are restricted to `arxiv.org` and `export.arxiv.org`. PaperForge preserves an ID's `vN` suffix and uses one process-global gate to prevent overlap and space all request starts by at least three seconds. Multiple processes or machines must coordinate externally. Atom is parsed without external DTD or entity resolution. Metadata is CC0; paper rights are separate. Preserve explicit `arxiv:license`; otherwise record the absent element and exact non-exclusive terms. Archive only to the user's local collection and never infer redistribution rights.
### Europe PMC
Use official core JSON search with `OPEN_ACCESS:Y`. Eligible records require PMCID, `inEPMC:Y`, and open access. Archive `https://www.ebi.ac.uk/europepmc/webservices/rest/{PMCID}/fullTextXML` as JATS XML because record PDF endpoints are unreliable. Search license evidence is preflight-only; final JATS permissions/license text is retained separately and conservatively controls the archived document claim. Never label this document as a PDF. Only `www.ebi.ac.uk` is trusted for API and document traffic.
### NASA NTRS
Use official citation POST search and citation metadata/download GET resources. Keep only `PUBLIC`, `DOCUMENT_AND_METADATA`, overall export control `NO`, ITAR `NO`, EAR `NO`, CUI false, `downloadsAvailable` true records with a non-draft first-party `STI` `application/pdf` on `ntrs.nasa.gov`. NASA DOI exact lookup is rejected in 0.1. Preserve copyright determination and public-use terms. NASA authorship or hosting is not enough to claim public domain.
OpenAlex, Crossref, and Semantic Scholar are metadata sources, not PaperForge providers. Their metadata licensing does not grant rights in linked third-party PDFs.
## Output And Recovery
Each selected paper receives one safe provider/identity-derived directory containing the original `paper.pdf` or `paper.xml` and `paperforge-paper.json`. The manifest stores the complete `PaperSummary`, query evidence, rights evidence, document URL/MIME/format/revision, relative path, byte count, BLAKE3, and a completion marker. No archive is unpacked and no embedded content is executed.
PaperForge refuses symlinked path components, traversal, arbitrary ports, credentials in URLs, non-HTTPS sources, untrusted hosts, redirects, oversized API/error/download bodies, wrong MIME, and wrong file magic. A recognized corrupt PaperForge directory can be repaired through staging and rollback; an unrecognized existing directory is never overwritten.
API calls make at most three attempts for HTTP 429 and 5xx failures, honoring bounded numeric `Retry-After` values up to five seconds. Provider error envelopes are errors, not empty discovery results. Surface bounded diagnostics to the user. If all archive items fail, preserve and report every per-paper failure. Do not bypass a provider security gate or manually substitute a download URL.