Onecite

OneCite

Use this skill to turn raw references, DOI lists, arXiv IDs, PMID/ISBN-like identifiers, GitHub URLs, Zenodo/DataCite DOIs, or existing BibTeX into verified BibTeX output through the OneCite pipeline.

When To Use

• A manuscript, README, paper, package, or dataset has references that need canonical metadata lookup.
• A citation list has been generated or edited and needs a deterministic API-layer check before being trusted.
• A repository needs reproducible citation regression checks.
• A user asks for a clean .bib file, reference audit, or template discovery.

Ground Rules

• Do not fabricate bibliographic fields. Missing metadata should stay missing or be reported as a failure.
• Treat formatting success as different from truth. OneCite checks metadata against academic APIs; it does not prove that a citation supports a claim.
• Keep raw references separated by blank lines when using plain text input.
• Run onecite benchmark --json first for deterministic offline regression checks; it uses bundled fixtures and does not require network access.
• Use onecite process ... for citation metadata lookup; unless test fixtures or mocks are explicitly configured, process mode may contact upstream APIs.
• Use onecite benchmark --live --json only when the user explicitly wants current upstream source behavior.
• OneCite performs deterministic source lookups and formatting at runtime.

Setup

From the repository root:

python -m pip install -e ".[dev]"

Use the repository's virtual environment when one exists:

.venv/bin/python -m onecite.cli --help

Common Commands

Process a plain-text reference file:

onecite process references.txt -o references.bib --quiet

Process an existing BibTeX file:

onecite process references.bib -o cleaned.bib --quiet

Process a direct identifier:

onecite process "10.1038/nature14539"

List available fallback templates:

onecite templates --json

Run the deterministic benchmark regression check:

onecite benchmark --json

Check the local install, bundled resources, skill package, and offline benchmark gate:

onecite doctor --json

Produce an automation-friendly validation envelope:

onecite process references.txt --json --fail-on-unresolved

Stream newline-delimited events:

onecite process references.txt --ndjson

Use live APIs for an upstream spot check:

onecite benchmark --live --json

Automation Workflow

1. Read the user's source reference material and preserve original text for traceability.
2. Put one reference per blank-separated block in references.txt, or use the user's existing .bib file directly.
3. Run onecite process ... --quiet to generate BibTeX.
4. Run onecite process ... --json --fail-on-unresolved when a script needs a strict machine-readable gate.
5. Run onecite benchmark --json before reporting regression-check results.
6. Run onecite doctor --json before reporting that the local installation has the expected automation or CI resources.
7. Inspect failed_entries in the process report, benchmark case failures, and doctor failed checks.
8. Report unresolved entries explicitly instead of inventing replacements.

Repository Validation Checks

1. Start from the Roadmap section in README.md; choose one scoped Roadmap item or one explicit maintenance follow-up.

2. Implement the change locally and keep unrelated edits out of the diff.

3. Run local validation before release or handoff:

   python -m pytest
   flake8 onecite tests --statistics --count
   onecite benchmark --json
   onecite doctor --json
   python -m build --wheel
   

4. Summarize the changed files, exact commands, pass/fail status, and any generated archive or wheel hashes.

5. Do not report local verification evidence until the local checks pass and references or failed checks are reported explicitly.

Output Expectations

For automation handoff, include:

• the command used,
• the output .bib path when one was written,
• the benchmark status from onecite benchmark --json,
• the doctor status from onecite doctor --json,
• the onecite process --json status when strict validation was used,
• unresolved entry IDs and error messages,
• whether live APIs were used.

Release and Review Checks

For repository changes to OneCite itself, do not mark the Roadmap done unless these checks pass from the repository root:

python -m pytest
flake8 onecite tests
onecite benchmark --json
onecite doctor --json
python -m build --wheel

For handoff, include the exact commands run, the pass/fail summary, the commit or diff reference, and any ZIP/wheel hash. Do not use live APIs for the default gate unless the user explicitly requests upstream-current behavior.

Troubleshooting

• If a .bib file is being treated as text, pass --input-type bib.
• If plain text merges separate references, add blank lines between entries.
• If Google Scholar is needed, install the optional dependency and pass --google-scholar; otherwise leave it off for deterministic runs.
• If a benchmark must be reproducible in CI, do not pass --live.
• If onecite doctor --json fails, fix the missing resource or failing benchmark before relying on package-level results.