Guides

Getting in, the one concept that explains the rest of the app, and the deliberate refusals that read like faults.

The quick way in

Sign in on this site. That is the whole setup — the hosted service is maintained by Dhrubojyoti Saha, and you get a project in about a minute. Skip to “choose the project kind carefully” below; it is the part that actually matters.

Running your own copy

Worth doing when the corpus itself is sensitive, or when your institution requires research data to stay on its own infrastructure. The source is on GitHub and the README is the authoritative install; this is the short version. You need Docker Desktop running and Node 24, and everything else is in the repository.

pnpm install — the workspace, once.
pnpm db:start — the database in containers. The first run pulls images and takes a few minutes. Every confusing failure below this line traces back to Docker not being up.
pnpm db:reset — apply the schema. This also wipes data, so it is how you start over later.
pnpm dev — the app, on localhost:3000.

An empty app is hard to judge. pnpm db:seed fills it with a 300-paper systematic review and a small thesis — a 20-question protocol, a half-screened library, papers waiting in reconciliation and around five and a half thousand answers. That is the shape these screens are designed for, and nothing like what four rows of test data looks like.

Signing in — the thing that catches everyone

There is no password anywhere, hosted or local. You type an email address and the app sends a six-digit code. On the hosted service that arrives in your inbox. Running locally it never leaves your machine at all: it goes to Mailpit at localhost:54324. If you have been watching your real inbox, that is why nothing arrived.

Any address works on your own copy and nothing is verified there, so me@test.dev is fine. On the hosted service it has to be an address you can actually read, since the code goes to it.

Choose the project kind carefully

This is the one concept that explains the rest of the app. When you create a project you pick a kind, and the kind changes which features exist — not cosmetically, but whole screens appearing or refusing to work. A student reading forty books should not be made to run a clinical review process, and a review team wants every guardrail.

Systematic review — a protocol is required before extracting, an exclusion needs a reason from a controlled list, PRISMA is complete, and dual extraction with Cohen’s κ is available.
Thesis, lab paper, general — the protocol is optional, exclusions need no reason, PRISMA is shown with a note that the reasons were optional, and reconciliation is hidden rather than offered and then refused.

The kind cannot be changed afterwards. If a screen tells you a feature is for systematic reviews, your project is a thesis; make a new one. To see everything the app can do, create a systematic review.

The workflow, in order

Questions — what the review asks. Everything after is ranked against these.
Find papers or Import — five databases at once, or paste BibTeX and RIS. Both land papers in the library.
Screen — include or exclude, one paper at a time, from the keyboard.
Protocol — the questions you will ask of every included paper. Agree it before extracting, not during.
Read and Extract — the paper on one side, the questions on the other.
Evidence, PRISMA, Reconcile — the outputs, built from what you already recorded.

There is no wizard and you do not need one: the project overview names one next action based on what the project actually needs. An empty library asks you to find papers; unscreened papers ask you to screen.

Things it does on purpose that look like bugs

“κ is undefined” instead of a number. If both extractors gave the same answer to every paper for a question, Cohen’s κ genuinely cannot be computed — chance alone predicts complete agreement. Printing 1.00 there would be a confident number the data does not support, so it shows the reason and the raw agreement percentage instead.
90% agreement but a poor κ. Not a contradiction. It means one answer dominates that question, so someone answering the same thing every time without reading would score nearly as well. Both numbers are shown for that reason.
“You already have your own extraction of this paper.” You cannot reconcile a paper you extracted yourself — that would make you a third reader rather than a neutral one.
A question you cannot rename or delete. It has answers. Renaming its key would silently change what a column in an old export meant. Make a new protocol version instead.
An exclusion that will not save. Systematic reviews require a reason, and the rule lives in the database rather than the form.
No column picker on a phone. Choosing among twenty columns is a desktop-shaped problem, and on a narrow layout that control made a link elsewhere in the table unclickable. The ?cols= link still works on any screen; only the button is desktop-only.
An error where you expected an empty list. Deliberate. A broken query and a genuinely empty table used to look identical, so failures are loud now and the message names what failed to load.

When something goes wrong

Everything fails, nothing loads. On your own copy, this is Docker not running: start Docker Desktop, then pnpm db:start.
Search returns nothing. The providers are real external APIs and need internet. The page names any that failed.
One provider failed and the rest worked. Normal, and the design point — four sets of results beat an error page. Semantic Scholar is the usual one; it rate-limits unauthenticated callers hard. Search again in a minute.
Every provider failed. Five independent APIs do not fail together, so that one is ours. Please report it.

For what each screen is for rather than how to run it, read how it works. For what the server can and cannot read, security.

Running your own copy

pnpm install — the workspace, once.

pnpm db:start — the database in containers. The first run pulls images and takes a few minutes. Every confusing failure below this line traces back to Docker not being up.

pnpm db:reset — apply the schema. This also wipes data, so it is how you start over later.

pnpm dev — the app, on localhost:3000.

Signing in — the thing that catches everyone

Any address works on your own copy and nothing is verified there, so me@test.dev is fine. On the hosted service it has to be an address you can actually read, since the code goes to it.

Choose the project kind carefully

Systematic review — a protocol is required before extracting, an exclusion needs a reason from a controlled list, PRISMA is complete, and dual extraction with Cohen’s κ is available.

Thesis, lab paper, general — the protocol is optional, exclusions need no reason, PRISMA is shown with a note that the reasons were optional, and reconciliation is hidden rather than offered and then refused.

The workflow, in order

Questions — what the review asks. Everything after is ranked against these.

Find papers or Import — five databases at once, or paste BibTeX and RIS. Both land papers in the library.

Screen — include or exclude, one paper at a time, from the keyboard.

Protocol — the questions you will ask of every included paper. Agree it before extracting, not during.

Read and Extract — the paper on one side, the questions on the other.

Evidence, PRISMA, Reconcile — the outputs, built from what you already recorded.

Things it does on purpose that look like bugs

“κ is undefined” instead of a number. If both extractors gave the same answer to every paper for a question, Cohen’s κ genuinely cannot be computed — chance alone predicts complete agreement. Printing 1.00 there would be a confident number the data does not support, so it shows the reason and the raw agreement percentage instead.

90% agreement but a poor κ. Not a contradiction. It means one answer dominates that question, so someone answering the same thing every time without reading would score nearly as well. Both numbers are shown for that reason.

“You already have your own extraction of this paper.” You cannot reconcile a paper you extracted yourself — that would make you a third reader rather than a neutral one.

A question you cannot rename or delete. It has answers. Renaming its key would silently change what a column in an old export meant. Make a new protocol version instead.

An exclusion that will not save. Systematic reviews require a reason, and the rule lives in the database rather than the form.

No column picker on a phone. Choosing among twenty columns is a desktop-shaped problem, and on a narrow layout that control made a link elsewhere in the table unclickable. The ?cols= link still works on any screen; only the button is desktop-only.

An error where you expected an empty list. Deliberate. A broken query and a genuinely empty table used to look identical, so failures are loud now and the message names what failed to load.

When something goes wrong

Everything fails, nothing loads. On your own copy, this is Docker not running: start Docker Desktop, then pnpm db:start.

Search returns nothing. The providers are real external APIs and need internet. The page names any that failed.

One provider failed and the rest worked. Normal, and the design point — four sets of results beat an error page. Semantic Scholar is the usual one; it rate-limits unauthenticated callers hard. Search again in a minute.

Every provider failed. Five independent APIs do not fail together, so that one is ours. Please report it.