Skip to content

docs: add source reconciliation pilot - #1195

Open
DanielleWashington wants to merge 5 commits into
firecrawl:mainfrom
DanielleWashington:docs/doc-detective-reconciliation-pilot
Open

docs: add source reconciliation pilot#1195
DanielleWashington wants to merge 5 commits into
firecrawl:mainfrom
DanielleWashington:docs/doc-detective-reconciliation-pilot

Conversation

@DanielleWashington

@DanielleWashington DanielleWashington commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Why

Documentation drift is continuous across Firecrawl API schemas, SDKs, CLI behavior, MCP behavior, and authored examples. The initial reconciliation found 26 classified candidates, including six high-severity items. This change establishes a repeatable reconciliation pilot and corrects the clearest, highest-impact documentation mismatches.

Summary

  • Correct six source-verified documentation mismatches across Node.js, Python, CLI, and MCP pages.
  • Add a dependency-free static reconciler covering seven registered claims, pinned and latest-source modes, expiring value-pinned exceptions, and seeded drift fixtures.
  • Add read-only pull-request, manual, and weekly GitHub Actions lanes; scheduled lanes compare against current product, CLI, and MCP main branches after merge.
  • Add a bounded Doc Detective Scrape pilot that dry-runs by default. Live HTTP execution remains an explicit workflow_dispatch opt-in with live=true.
  • Add maintainer documentation for operation, source advancement, extensions, exceptions, dependency policy, and failure triage.
  • Repair and regression-test the live workflow's OpenAPI-drift artifact copy step.

Test plan

  • npm test --prefix reconciliation — 5/5 passing, including seeded drift and workflow regression coverage.
  • Pinned and latest static reconciliation — 7/7 claims passing against current source heads.
  • Doc Detective 4.36.0 dry-run — one spec, one test, one context, and one HTTP step resolved; no request executed.
  • Live-workflow preparation, JSON/YAML/JavaScript syntax, and git diff --check — passing.
  • All six edited routes render the corrected text, visible main content, and no horizontal overflow at desktop and 390-pixel mobile widths.
  • mint validate — same 22 pre-existing missing-import warnings as baseline; zero introduced by this branch.
  • Branch rebased onto firecrawl-docs@74685645; pins refreshed to firecrawl@9554ad07, cli@a151277b, and firecrawl-mcp-server@41c25716.

View with [code]smith Autofix with [code]smith
Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.

@DanielleWashington

Copy link
Copy Markdown
Contributor Author

Agent follow-up stack (non-blocking for this PR):

Each follow-up is read-only, updates one advisory PR comment, and depends on this reconciliation baseline reaching docs main. Maintainers still need to approve the workflow and configure OPENAI_API_KEY; automatic edits, branches, pull requests, and merges remain disabled.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant