fix: describe the research paper index accurately across CLI surfaces - #186
Merged
Conversation
Why: over 40 agent traces, 8/8 biomedical CLI runs read the root-help
research line ("Research arXiv papers and GitHub history"), concluded the
index was arXiv-only, and hand-scraped PubMed instead of ever running
`firecrawl research`. The index is ~43M abstracts, ~90% biomedical. The
group description is the single highest-leverage string: it renders both
in `firecrawl --help` and as the `firecrawl research --help` header.
Summary:
- research group description now names the corpus (PubMed/bioRxiv/medRxiv
plus arXiv), its scale, and routes agents away from hand-scraping.
- search-papers description drops the three "arXiv" claims and names the
multi-source id forms it actually returns; keeps the load-bearing
"run several distinct framings" guidance verbatim.
- search-papers --categories only claims what is true: arXiv-style
taxonomy labels, not applicable to biomedical records.
- search --categories disambiguates `research` (a ~web-domain filter)
from the paper index, pointing at `research search-papers`. The wire
value 'research' is unchanged.
- related-papers accepts pmid:/pmcid:/doi:/arxiv: forms in its docs, in
line with inspect-paper and read-paper.
- research examples now include biomedical ids, not arXiv only.
- cli-argv tests gain the research pair that mirrored `developer`, plus a
regression guard that root help names the biomedical corpus.
Why: the README taught the wrong tool. "# Find research papers" was followed by `firecrawl search --categories research`, which is only a website filter over ordinary web results, not the paper index. README also had a `###` section for every command except `research`, so the index had no documentation surface at all, and the tagline omitted both `research` and `developer`. Summary: - the "Find research papers" example now leads with `research search-papers`; the `--categories research` example stays but is labelled as the website filter it is. - same disambiguation added to the category example block and the search options table. - new `### research` section beside `developer`: corpus and scale, the explicit "not the same as --categories research" note, all five subcommands, search-papers options, and workflow tips. - line-3 tagline now mentions research papers and developer sources.
Why: npm search and package listings carried no research, paper, or biomedical vocabulary, so the paper index was undiscoverable from outside the CLI too. Behavioural metadata change across help text, docs, and skills -> minor bump. Summary: - package.json description names the paper index and its sources. - keywords gain research, paper/literature search, biomedical, pubmed, biorxiv, medrxiv, arxiv, life sciences. - 1.19.31 -> 1.20.0. - nfpm.yaml and homebrew/firecrawl-cli.rb carry the same one-line description; both updated. The brew `desc` is kept under the 80-char audit limit. Note: homebrew/firecrawl-cli.rb `version` is 1.10.0 and is not written by any release tooling in this repo; left as found rather than guessed at.
Why: agents load skills before they load `--help`. firecrawl-search had a full "Developer search" section and nothing for research; its options table listed `research` with no elaboration, so the naming collision with the paper index was invisible. firecrawl-cli's routing table and "When to Load References" omitted research entirely, so nothing ever pointed an agent at `firecrawl research`. Summary: - firecrawl-search: new "## Paper search" section parallel to "## Developer search" — states plainly that `--categories research` is not the paper index, routes to `research search-papers`, and shows the find/expand/verify loop with real id forms. - firecrawl-search: `--categories` options row and "When to use" now disambiguate the two; frontmatter description gains literature triggers so the skill actually loads on a biomedical task. - firecrawl-cli: research rows added to the routing table and to "When to Load References", both stating the anti-pattern (hand-scraping PubMed).
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
All reported issues were addressed across 8 files
Reply with feedback, questions, or to request a fix.
Fix all with cubic | Re-trigger cubic
Why: cubic flagged the README install example pinning firecrawl-cli@1.19.6 while this PR ships 1.20.0. The pin was already 25 patches behind npm's published 1.19.31, and the same stale pin appeared in five more places in the bundled skills rules. Summary: install and run commands now use @latest, matching the convention the public docs already use in all 30 of their occurrences. That removes the drift permanently rather than trading one stale pin for another — and avoids pinning 1.20.0, which is not published yet and would break the documented one-shot install until release. The illustrative `--status` sample output now shows the version this PR ships. Test Plan: pnpm test 422/422, prettier clean, no hard-pinned versions remain in any markdown file.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The CLI's research command group was branded arXiv-only ("Research arXiv papers and GitHub history") while the index it fronts is mostly biomedical (PubMed, bioRxiv, medRxiv). In 8/8 measured agent traces on biomedical tasks, agents read
firecrawl --help, concluded the command was not relevant, and hand-scraped PubMed instead. The README also taughtfirecrawl search --categories research(a website filter) as the way to "Find research papers" and never mentionedfirecrawl researchat all.Summary
--helpline and all five research subcommand descriptions now name the real corpus; multi-source id examples (pmid:,pmcid:,doi:) used throughoutsearch --categorieshelp disambiguatesresearch(website filter) fromfirecrawl research(paper index); the wire valueresearchis untouched### researchcommand section added (it was the only command without one); tagline updatedfirecrawl-searchSKILL gains a Paper search section (parity with its Developer search section);firecrawl-clirouting table gains research rowsTest Plan
pnpm test422/422 (incl. 3 new argv guards),pnpm run build+type-check+format:checkcleanfirecrawl --help/firecrawl research --helpverified from the built binary🤖 Generated with Claude Code
Summary by cubic
Clarifies and correctly brands the research paper index across the CLI, docs, and skills so users run
firecrawl researchfor papers (PubMed, bioRxiv, medRxiv, arXiv) instead of the web category filter or hand-scraping. This fixes arXiv-only wording that led users to skip the paper index.--helpand allresearchsubcommands name the real corpus and showpmid:,pmcid:, anddoi:examples;search-papers/related-papersdocs note arXiv taxonomy limits and accept multi-source ids.search --categories research(website filter) from the paper index; help now points tofirecrawl research search-papers(wire value unchanged).researchsection, corrected examples, routed paper workflows throughresearch, and added a Paper search section tofirecrawl-search.@latestinstead of pinned versions; sample--statusreflectsv1.20.0.firecrawl-clito1.20.0.Written for commit ab0f63a. Summary will update on new commits.