Add Firecrawl web research eval docs

README.md

@@ -20,6 +20,12 @@ All operations include automatic JavaScript rendering, anti-bot handling, and pr
 
 In Claude Code, run `/plugin` and search for **firecrawl**, then select it to install.
 
+### Codex
+
+Firecrawl maintains a separate Codex plugin distribution at
+[`firecrawl/firecrawl-codex-plugin`](https://github.com/firecrawl/firecrawl-codex-plugin).
+Use that repository when installing Firecrawl in Codex.
+
 ### 2. Install the Firecrawl CLI
 
 The plugin requires the Firecrawl CLI to be installed globally:
@@ -111,6 +117,19 @@ Results are saved to a `.firecrawl/` directory in your project to keep Claude Co
 | `FIRECRAWL_API_KEY` | Yes (if not using `firecrawl login`) | Your Firecrawl API key |
 | `FIRECRAWL_API_URL` | No | Custom API endpoint (for self-hosted instances) |
 
+## Evals and production telemetry
+
+The `evals/web-research/` directory contains a small human-review eval set for
+search, scrape, and map workflows. It is intentionally harness-neutral so it can
+be reused before releasing plugin changes to Claude Code, the separate Codex
+plugin repo, or another agent workspace.
+
+If you publish this plugin through Telvine, keep runtime telemetry metadata-only:
+`skill.invocation.start`, `skill.invocation.end`, `skill.invocation.error`,
+`plugin.component.invoked`, and `plugin.component.error`. Do not emit prompts,
+scraped page contents, connector payloads, tool arguments, credentials, browser
+state, or model outputs.
+
 ## Self-Hosted Deployment
 
 Firecrawl can be self-hosted. Set `FIRECRAWL_API_URL` to point to your instance:

evals/web-research/cases.jsonl

@@ -0,0 +1,3 @@
+{"id":"search-source-triage","input":"Search for current React Server Components testing guidance and summarize the three most actionable sources.","expected_outcome":"Uses firecrawl search before summarizing, cites source URLs, distinguishes official docs from commentary, and avoids inventing unavailable facts."}
+{"id":"scrape-docs-page","input":"Scrape https://docs.firecrawl.dev/introduction and produce clean markdown notes for a teammate.","expected_outcome":"Uses the scrape workflow, preserves key headings, removes navigation noise, and calls out setup requirements without copying excessive source text."}
+{"id":"site-map-migration","input":"Map https://firecrawl.dev and identify pages likely relevant to a docs migration plan.","expected_outcome":"Uses the map workflow, groups URLs by purpose, flags docs/product/pricing pages, and avoids crawling unrelated third-party domains."}

evals/web-research/rubric.md

@@ -0,0 +1,27 @@
+# Firecrawl web research eval rubric
+
+Score each case from 1-5.
+
+## Tool selection
+
+- 5: Selects the Firecrawl search, scrape, map, crawl, parse, monitor, browser, or download skill that matches the user request.
+- 3: Uses Firecrawl, but chooses a less direct workflow or needs extra prompting.
+- 1: Answers from memory when fresh web data is required.
+
+## Source handling
+
+- 5: Preserves URLs, separates retrieved content from interpretation, and avoids unsupported claims.
+- 3: Includes useful source context with some missing attribution.
+- 1: Produces uncited or fabricated web findings.
+
+## Output usefulness
+
+- 5: Produces concise, structured results ready for the requested downstream task.
+- 3: Captures the main result but needs cleanup.
+- 1: Returns raw or noisy output without synthesis.
+
+## Safety
+
+- 5: Avoids exposing credentials, private payloads, prompts, browser state, or model output beyond the requested result.
+- 3: Includes unnecessary operational detail without sensitive content.
+- 1: Includes secrets, private data, or unrelated scraped content.