Research-Kit: primary-source research for AI coding agents

[StepenkoAnatoli]

I maintain Research-Kit, a plain Node CLI and MCP server for collecting primary sources and handing traceable research to AI coding agents.

The useful question is: what is this build decision based on, and can the next agent check it? Research-Kit keeps the source pages with the project, records their hashes in a fetch ledger, and connects research questions to findings and cached evidence. The builder receives an authored brief and the corpus behind it.

The workflow is:

1. Frame the questions and the collection budget.
2. Collect primary sources into the project's research folder.
3. Review the findings and write the brief.
4. Check corpus integrity and pass the handoff to the builder.

A passing check still needs reviewed findings and an authored brief. The kit checks recorded evidence and consistency; review supplies the judgment.

Try the included corpus without an API key. With Node 24 installed:

git clone https://github.com/StepenkoAnatoli/Research-Kit.git
cd Research-Kit
node research-kit/bin/handoff.mjs
node research-kit/bin/preflight.mjs

These commands inspect the repository's included research corpus. They do not fetch new pages or spend collection credits. For your own research, follow the setup and collection guide and choose your provider and budget. Metered providers require your own account.

The MCP server uses stdio and starts with node research-kit/bin/mcp-server.mjs. It exposes collection and corpus-download tools; collection setup and credentials are documented in the guide.

The code is public and licensed under PolyForm Shield 1.0.0. CI covers Node 24/26 and Linux/Windows. The project is feature-frozen while bugs, documentation, and verification receive attention.

I'd welcome feedback on the first-run instructions, the handoff format, and places where the evidence checks are unclear. For a reproducible defect, please open an issue. New contributors can start with the contributor guide and good first issues.

If you find the workflow useful, please consider giving the repository a star.

Disclosure: this announcement was prepared with AI assistance on my behalf.

[bomtobe-hgkim]

The fetch ledger is a useful anchor. One handoff edge case I’d make explicit in the first-run example: record the repository revision and fetch time beside the brief, then test with a source that changes between collection and handoff. That shows whether the next agent can distinguish a current citation from a consistent but stale snapshot. I’m with BOMTOBE, the team behind Orke, a desktop workspace for Claude Code and Codex; this source-to-review handoff is a workflow we care about.

[StepenkoAnatoli]

I'll try it next when finish fixing the issues. Thank you

[StepenkoAnatoli]

I tried it, as promised. Thanks for the idea. Research-Kit is now called Fetchproof, and this case is now handled explicitly: #434

A source that changes. I ran it offline with a local page server. I collected a page that says "10 requests per minute", closed the question on it and drafted the brief. Then the page changed to "2 requests per minute", and the corpus was handed off unchanged.

• On the builder, handoff.mjs still says handoff OK and exits 0, and preflight passes. The handoff checks integrity, not currency: the corpus arrived intact and its hashes verify. A builder cannot fetch, so it cannot tell whether a page still says the same thing.
• On the collector, research.mjs --force fetches the page again and adds the new text as E-02, beside E-01. The gate then fails with cites-superseded-row, because the claim still cites E-01, and it warns brief-stale. It passes again once the claim is re-read and cites E-02. The old row and its capture are kept.

This now runs offline as an end-to-end test in fetchproof/test/handoff.test.mjs.

Fetch time. The handoff OK line now ends with the snapshot's age, for example captures fetched 2026-09-13..2026-10-02 (oldest 37 days). In --json output it is the fetched field. The age is never a finding, and the exit code does not change, because re-checking currency is the collector's job. Each row is dated by the capture it names, and the ledger's hash covers that capture's fetch date, so editing the evidence table cannot make the snapshot look younger. A row that a later fetch of the same page superseded is left out, so the age drops after a re-check. You can see it on the included corpus with node fetchproof/bin/handoff.mjs. The folder was research-kit/ before the rename.

The README's builder section now says what handoff OK does not prove, and the five-minute example points to it. The freshness-recheck skill now says that --refresh-days 0 does not re-collect a capture made today. A same-day re-check therefore uses --force, which re-fetches every page in the plan and runs every search again. The decision is recorded in ADR-0187.

Repository revision. I did not add this. BRIEF.md does not record a git commit. A brief cannot name the commit it lands in, only the one before it, and a builder can read its own checkout with git log. Instead, a brief drafted with brief.mjs ends with a stamp. The stamp holds a hash of what the brief was drafted from: the questions, every evidence row with its fetch date, and the coverage map. If any of that changes later, preflight warns brief-stale. The fetch dates are not written into the brief either. They are in the Retrieved column of research/EVIDENCE.md and on the handoff line. The kit records a commit in one place: the package that the GitHub collector workflow builds. Its manifest.json names the repository, ref and commit of the run that collected the corpus.

Disclosure: this reply was prepared with AI assistance on my behalf.