SF

Help

Full guide

Getting Started

Who
New here and looking at a sidebar full of tabs, wondering which to click first — a brand-new academic user, no technical setup assumed.
What you can do
  • Think of ScholarFlow as an AI second-brain for research: it finds the literature, files it in the places you already keep it, argues with you about it, and helps you write and citation-check — all one connected loop, not a pile of separate tools.
  • (1) DISCOVER — on Search, ask a real question and hit eight free academic providers at once (Semantic Scholar, OpenAlex, PubMed, arXiv, CORE, CrossRef, Europe PMC, and ERIC for education). Or bring records in from any database with "Import RIS/BibTeX", or paste a DOI with "Add by DOI…" — both in the Library toolbar.
  • (2) CHOOSE — tick the checkboxes on the results worth keeping and click "Save selected (N)".
  • (3) YOUR TWO STORES FILL THEMSELVES — each saved paper (and its open-access PDF file) lands in YOUR Zotero, which holds the files on your own storage, while ScholarFlow indexes just the searchable text. ScholarFlow never stores the PDFs itself — that split is deliberate, and it is what keeps the service cheap to run.
  • (4) ENGAGE — take a claim into the War Room and debate it with five expert personas grounded in your own library, by voice if you like, for up to 20 back-and-forth exchanges (the panel can even ask YOU a question).
  • (5) WRITE & VERIFY — draft a paper, enhance an uploaded Word document section by section, and citation-check everything before you share it.
  • (6) AUTOMATE — hand any of the above to your own agent (Hermes/Claude), which drives ScholarFlow through about 30 MCP tools while you approve the checkpoints.
  • Two ways to begin. A — I have a document to improve: upload an outline or a draft (.docx works) at Books → New and let ScholarFlow enhance and citation-check it. B — my papers live in Zotero/Obsidian: connect them, search the academic web or your own library, save the keepers, then Research → Write → Verify. The Start-anywhere cards on the Search landing are the visual version of these choices.
  • Academic-web search in workflow B runs on Perplexity out of the box — you do not have to configure anything; to use your own key, see Settings → Integrations → Perplexity.
Where it lives
Your home base is Search (the app opens here) — its Start-anywhere cards point at each entry. Documents to improve start at Books → New. Zotero/Obsidian connect under Settings → Integrations. Library, Research, Write, Verify, and War Room are all in the left sidebar.
When to use it
The very first time you sign in, or any time the sidebar feels overwhelming and you are not sure what a tab does or in what order to use them.
Why it exists
Every click builds toward the same thing — a finished, citation-checked piece of writing grounded in sources you actually saved — instead of scattered notes. Knowing the loop (discover → choose → file → engage → write → verify) up front means you always know where you are in it and what comes next.

Step-by-step

  1. 1.
    Pick your starting point
    Have a document you want improved and citation-checked — an outline or a draft? That is workflow A: go to Books → New and upload it (.md, .txt, or .docx), plus an optional .bib. Working from a library of papers instead? That is workflow B — start on Search.
  2. 2.
    Workflow B — connect your stores first
    In Settings → Integrations, connect Zotero (paste your API key + user ID) and, if you use it, Obsidian. From then on every Save lands in both your ScholarFlow Library and Zotero automatically.
  3. 3.
    Discover and choose
    On Search, ask a real question. Eight free providers answer at once (web search runs on Perplexity out of the box). Tick the sources worth keeping and click "Save selected (N)" — the paper and its open-access PDF flow to your Library and your Zotero together.
  4. 4.
    Engage the literature
    Take a claim into the War Room to pressure-test it against five expert personas grounded in your own library, or build a whole topic's corpus at once with the Domain corpus builder on Research.
  5. 5.
    Write and verify
    Draft with Research (the guided pipeline) or Write (the hands-on editor), enhance an uploaded document at Books → New → Enhance, then run Verify so every citation holds up before you share it.

Troubleshooting

  • Which of the two starting workflows is mine?
    If you have a document to improve — an outline or a draft — that is workflow A: upload it at Books → New and open it to Enhance and citation-check. If your papers already live in Zotero/Obsidian (or you are starting a fresh literature search), that is workflow B: connect your stores, search, save, then Research → Write → Verify.
  • There are a lot of tabs — do I need all of them to get started?
    No. For your first session you only need a handful: Search (discover + save), Library (keep and organise), War Room (pressure-test a claim), and Write or Research (draft), then Verify (check citations). Inbox, Network, Analyze and Calibration are for later or for automated workflows — you can safely ignore them at first.
  • Where do the papers I save actually go — does ScholarFlow store my PDFs?
    Two places, by design. The PDF file itself goes to YOUR Zotero (Zotero holds files on your storage); ScholarFlow keeps only the searchable text so it can answer questions and ground debates. That is why connecting Zotero first is worth the two minutes — it is what lets one Save fill both stores.
  • Do I have to connect Zotero before I can do anything?
    No — you can search and read cited answers right away. But connecting Zotero first is strongly recommended, because it is what lets "Save selected" send each paper (and its open-access PDF) to both your Library and Zotero in one click. Connect it once and you never think about it again.

Downloading papers & syncing to Zotero

Who
Any researcher building a reading pile — you find papers on the web or in your library, and you want them saved in ScholarFlow AND in Zotero without copying anything by hand.
What you can do
  • Research a topic in Search, then use the one-click "Save" button on any source card to add that paper to your ScholarFlow Library and your connected Zotero at the same time.
  • Search has two modes — "Academic web" (Semantic Scholar + OpenAlex and other providers, best before you have papers uploaded) and "My library" (only your own uploaded PDFs + already-synced Zotero items).
  • Zotero works the other direction too: "Backfill PDFs" pulls attachments from your Zotero account into ScholarFlow, and an auto-sync interval keeps the two aligned over time. For new Zotero connections, automatic PDF backfill now defaults ON, so full text starts flowing in without you touching a checkbox.
  • If you feel like you "get very few papers," that is almost always about which source mode you are in plus your year/database filters — both are adjustable.
Where it lives
Search at /search (source cards with the Save button on the right). Zotero connect + Sync now + Backfill PDFs + Auto-sync interval at /settings/integrations/zotero. Saved papers land in /library.
When to use it
At the very start of a project and whenever you are gathering sources. Connect Zotero once up front (it is step 1 of the Setup Checklist on the Search landing) so that every Save from then on lands in both places automatically.
Why it exists
Manually re-typing citations and re-downloading PDFs into a reference manager is the most tedious part of research. One-click Save collapses "find it, file it in my Library, file it in Zotero" into a single button, and Backfill + auto-sync mean your existing Zotero library and ScholarFlow stay in step instead of drifting apart.

Step-by-step

  1. 1.
    Connect Zotero first (one time)
    Go to Settings → Integrations → Zotero (/settings/integrations/zotero). Paste your Zotero API key and your Zotero user ID, then Save. Until this is connected, the Save button only adds to your ScholarFlow Library.
  2. 2.
    Choose the right Search mode
    On /search, use the mode toggle: pick "Academic web" to discover new papers (best when your Library is still small), or "My library" to search only papers you have already saved/uploaded and Zotero items you have synced.
  3. 3.
    Ask a real question and Save
    Phrase it as a full question. As the answer streams with inline citations, source cards appear on the right; click "Save" on any card to post it to your Library AND (if Zotero is connected) to Zotero in parallel.
  4. 4.
    Pull PDFs the other way with Backfill
    Back in Settings → Integrations → Zotero, click "Backfill PDFs" to fetch PDF attachments already sitting in your Zotero account into ScholarFlow, so "My library" search can read them.
  5. 5.
    Turn on Auto-sync and widen thin results
    Set the auto-sync interval on the same Zotero page so the two libraries stay aligned; automatic PDF backfill defaults ON for new connections, so full text starts arriving without extra setup (you can still turn it off in that same section). If results feel thin, open Research Defaults in Settings and loosen the year range and databases; a Perplexity API key (BYOK, in Settings) widens web results further.

Troubleshooting

  • I only get a handful of papers — why?
    Three usual causes, in order. (1) You are in "My library" mode, which only searches papers you have already saved — switch to "Academic web". (2) Your Research Defaults have a narrow year range or few databases selected — widen both. (3) For broader web coverage, add a Perplexity (Sonar) API key under Settings; it is an optional web-search booster you bring yourself.
  • I clicked Save but the paper is not in Zotero.
    Zotero has to be connected first. Go to Settings → Integrations → Zotero and confirm your API key and user ID are saved. If they were not connected when you clicked Save, the paper still went to your ScholarFlow Library — re-open it there and Save again once Zotero is connected.
  • What is the difference between "Sync now" and "Backfill PDFs"?
    "Sync now" reconciles the item lists between ScholarFlow and Zotero on demand. "Backfill PDFs" specifically pulls the PDF files attached to your Zotero items down into ScholarFlow so they can be read in "My library" mode. Auto-sync just runs the reconcile automatically on the interval you set.

Zotero & Obsidian connections

Who
Academics who already keep their papers in Zotero and/or their notes in Obsidian, and want ScholarFlow to read from and write back to those tools instead of starting a fresh, separate library.
What you can do
  • Connect Zotero so your existing references (and their PDFs) flow into ScholarFlow, and anything you Save here flows back into Zotero.
  • Paste two things in the Zotero connect page: a read-only Zotero API key and your Zotero user ID. That is all Zotero needs to link.
  • Use "Sync now" for an immediate pull, "Backfill PDFs" to pull attachments for papers already synced, and set an auto-sync interval so it stays current on its own — automatic PDF backfill now defaults ON for new connections.
  • Connect Obsidian so your research notes and vault stay in step with ScholarFlow — you generate a revocable token here, then install the ScholarFlow community plugin (v0.4.0) in Obsidian and paste that token in.
  • Revoke the Obsidian token any time to instantly cut the connection, without touching your Zotero key or your papers.
Where it lives
Zotero: Settings → Integrations → Zotero, or go straight to /settings/integrations/zotero. Obsidian: create the token from the 3-step Setup Checklist card on the Search landing (or the integrations area of Settings), then finish inside the Obsidian app via the ScholarFlow community plugin.
When to use it
At the very start, right after you sign in — connecting these is a step of the Setup Checklist alongside running your first search. Connect Zotero if you already have a reference library you do not want to re-upload; connect Obsidian if you write or keep notes there.
Why it exists
These are the two "bring your own knowledge" bridges. Zotero is where most academics already store what they have read; Obsidian is where many keep what they are thinking. Wiring them in means ScholarFlow searches, drafts, and verifies against your real material, and the one-click Save button writes to both your Library and Zotero at once — so your reference manager and notes never drift out of sync with your work here.

Step-by-step

  1. 1.
    Get your Zotero credentials
    Sign in to zotero.org and open Settings → Security → "Feeds & API". Your numeric userID is shown there. Click "Create new private key", give it read access (read-only is all ScholarFlow needs), save it, and copy both the key and the userID.
  2. 2.
    Paste them into ScholarFlow
    Open Settings → Integrations → Zotero (or go to /settings/integrations/zotero). Paste the API key and user ID into the two fields and connect. These are stored server-side against your account — you do not need to enter them again.
  3. 3.
    Pull your library
    Click "Sync now" to import your Zotero items. For the actual PDF files, click "Backfill PDFs". Then set an auto-sync interval so new Zotero additions appear here automatically.
  4. 4.
    Create your Obsidian token
    On the Search landing page, use the Setup Checklist card's "Obsidian" step to generate a token (it is revocable). Copy it.
  5. 5.
    Install the plugin in Obsidian and verify
    Download the plugin (main.js + manifest.json) from the public release at github.com/drmweyers/scholarflow-obsidian/releases/latest, unzip it into <vault>/.obsidian/plugins/scholarflow/, then in Obsidian open Settings → Community plugins, enable ScholarFlow (v0.4.0), open its settings, and paste the token. On sync it organizes your vault into papers/, concepts/, projects/, and decisions/ subfolders plus a router file (CLAUDE.md/AGENTS.md) — non-destructively, so any existing notes are left alone. Check a note appears on both sides. If you ever want to disconnect, revoke the token here and the link stops immediately.

Troubleshooting

  • Where exactly do the keys go, and is it safe to paste them?
    The Zotero API key and user ID go in Settings → Integrations → Zotero; the Obsidian token goes into the ScholarFlow plugin's settings inside Obsidian. Use a read-only Zotero key, and the Obsidian token is revocable, so you can cut either connection at any time.
  • Do I need both?
    No — they are independent. Zotero connects your reference library so you can search and cite what you have collected. Obsidian connects your notes/vault so your writing stays in sync. Connect whichever tools you actually use.
  • I connected Zotero but "My library" search still finds nothing.
    Click "Sync now" after connecting — linking the key does not import papers on its own. For the PDFs themselves, also click "Backfill PDFs". Give a large library a minute, then retry the search in "My library" mode.
  • I cannot find a place to upload a PDF.
    Obsidian syncs through the community plugin, not an upload box — you install the ScholarFlow plugin inside Obsidian and paste your token there. Direct PDF upload in the cloud app is intentionally off; Zotero sync is the way papers come in.

Using Zotero with ScholarFlow effectively

Who
Anyone already connected to Zotero who wants the day-two playbook — the recommended workflow, what each button actually does, and how to fix the two most common surprises (thin results, an unsearchable paper).
What you can do
  • Recommended workflow: treat Zotero as your canonical PDF store. ScholarFlow first SYNCS metadata (titles, authors, collections) from Zotero, then BACKFILLS the actual PDF attachments into your searchable corpus — two separate steps because metadata is cheap and instant, PDFs are larger and slower.
  • "Sync now" reconciles the item lists between Zotero and ScholarFlow on demand — it pulls in new/changed items but does not, by itself, fetch PDF files.
  • "Backfill PDFs" specifically pulls the PDF attachments for items already synced (25 at a time) so they can be parsed, chunked, and embedded for "My library" search. Run it after a sync whenever you see the "Not searchable yet" badge.
  • Auto-sync runs the reconcile step on a schedule you choose — Off, every hour, every 6 hours, or every 24 hours — from the interval dropdown on the Zotero settings page. Automatic PDF backfill defaults ON for new connections, so full text starts arriving without you touching a checkbox; the "Also pull PDFs after each sync" toggle on that same page turns it off if you would rather backfill manually.
  • Zotero collections map to ScholarFlow the same way folders do for direct uploads: each synced item keeps its Zotero collection as a ScholarFlow collection, so the Library sidebar mirrors your existing Zotero folder structure without extra setup.
  • The amber "Not searchable yet" badge on a paper means only metadata synced — no full text has been ingested, so it will not surface in "My library" search results until it does. Fix it by running "Backfill PDFs" on the Zotero settings page (or, if Zotero never had a PDF for that item, ScholarFlow falls back to an open-access fetch where possible).
  • The relationship also runs the other way: on Search, the one-click "Save" button on any source card writes to your ScholarFlow Library AND your connected Zotero library in parallel — so papers you discover here show up back in Zotero too, not just the reverse.
  • Pushing PDFs the other direction: check the boxes on the results you want and click "Save selected" on Search, or use "Archive PDFs → Zotero" in the Library toolbar, to upload each paper's open-access PDF file INTO your Zotero (as an item attachment). ScholarFlow keeps only the searchable text — Zotero holds the actual PDF files, on your Zotero storage. A green "In Zotero" badge appears on Library papers once their PDF has been pushed.
  • A detail worth knowing: when you "Save selected" on Search and the paper is open access, ScholarFlow does not just create a Zotero item — it attaches the actual PDF file to it, so the full text (not merely the citation) lands in your Zotero.
  • A note on Zotero storage quota: uploading PDF files counts against your Zotero account's storage (free tier is 300 MB). If a push hits your quota, ScholarFlow stops attaching the rest of that batch and leaves those papers metadata-only in Zotero — the library copy stays fully searchable regardless. Free up Zotero space (or upgrade its storage) and run the archive again to push the remainder.
  • If you also use Obsidian, the round-trip continues one hop further — papers saved to your Library (from Search or from Zotero sync) are picked up by the Obsidian plugin's next sync into your vault. See "Zotero & Obsidian connections" for setting that up.
  • Capture while you browse: install the free Zotero Connector browser extension (Chrome/Firefox/Edge/Safari) as the manual companion to sync. When you land on a paper anywhere on the web — a journal page, Google Scholar, a PDF — one click on the Connector saves it straight into your Zotero library; ScholarFlow's next Zotero sync then pulls it in automatically, so browsing and your searchable corpus stay in step without copy-pasting DOIs. Pair it with the Unpaywall browser extension, which drops a small green tab on any page when a free, legal open-access PDF exists — handy for grabbing the full text of paywalled results before you save them.
Where it lives
Settings → Integrations → Zotero (/settings/integrations/zotero) has Sync now, Backfill PDFs, and the auto-sync interval + auto-backfill toggle. The "Not searchable yet" badge and per-paper full text live in Library (/library). The one-click Save-to-Zotero button is on every source card in Search (/search).
When to use it
Any time results feel thin, a paper will not show up in "My library" search, or you just want to confirm the sync/backfill/auto-sync loop is actually configured the way you expect.
Why it exists
Zotero and ScholarFlow are two views onto one library, and the two-step sync-then-backfill design exists so a quick metadata reconcile never gets stuck behind slow PDF downloads. Understanding the split (and where the "Not searchable yet" badge points you) turns "why can't I find this paper" into a one-click fix instead of a mystery.

Step-by-step

  1. 1.
    Sync metadata first
    On /settings/integrations/zotero, click "Sync now". This is fast — it reconciles item lists, not PDFs — and is also what runs automatically on your chosen auto-sync interval.
  2. 2.
    Backfill the PDFs
    Click "Backfill PDFs" (or "Check eligible" first to see the count). This pulls attachments 25 at a time so those items become full-text searchable. New connections have auto-backfill ON by default, so this often runs itself after every sync.
  3. 3.
    Set your auto-sync cadence
    Pick an interval — every 6 hours is a good default for an actively-growing library — so new Zotero items keep flowing in without manual clicks.
  4. 4.
    Check for the "Not searchable yet" badge
    In Library, an amber badge on a paper means metadata-only. Run Backfill PDFs again, or re-check after your next auto-sync, and the badge clears once full text lands.
  5. 5.
    Save back to Zotero from Search
    On any source card in Search, click "Save" — it writes to both your Library and Zotero in one click, so your Zotero library grows from your ScholarFlow research too.

Troubleshooting

  • Sync fails with an invalid-key error.
    Your Zotero API key was likely revoked or retyped incorrectly. Go to zotero.org → Settings → Security → Feeds & API, confirm the key still exists (or mint a new read-only one), then re-paste it on the Zotero settings page.
  • A private group library is not showing up.
    ScholarFlow syncs the library tied to the userID you connected with; private GROUP libraries need their own explicit access on that key. If a group is missing, check the key's permissions on zotero.org — read access to that specific group must be granted.
  • Sync or backfill is failing with rate-limit errors.
    Zotero throttles heavy API use. Backfill deliberately runs in batches of 25 for this reason — if you hit a rate limit, wait a few minutes and click "Backfill PDFs" again; it resumes with whatever is still eligible rather than starting over.
  • What is the actual difference between Sync and Backfill again?
    Sync = item lists (titles, authors, collections) — fast, metadata only. Backfill = the PDF files themselves, pulled per item so ScholarFlow can parse and embed them for search. You generally want both: sync to know what exists, backfill to make it searchable.

Search

Who
Researchers and writers with a question — anyone running literature reviews, finding sources, or starting a synthesis paper.
What you can do
  • Type a question in the "Ask a research question..." input and press Enter to submit.
  • Toggle between "Academic web" and "My library" (your uploaded PDFs + synced Zotero). Academic web hits eight free providers at once — Semantic Scholar, OpenAlex, PubMed, arXiv, CORE, CrossRef, Europe PMC, and ERIC (education) — with Perplexity added on top when a key is configured (it works out of the box on the shared key; bring your own under Settings → Integrations → Perplexity).
  • Read the streaming answer as it generates — citations appear inline.
  • Scan the evidence meter to see how many sources support, contradict, or are neutral.
  • Click any source card on the right to open a detail panel with the full abstract, metadata, and DOI.
  • Tick the checkboxes on the cards you want and click "Save selected (N)" — each chosen paper goes to your Library, and (when Zotero is connected) a Zotero item plus its open-access PDF file are pushed there too. "Save all sources" does the same for every collected result at once.
  • Click "Draft a Paper" once sources have loaded to generate a synthesis paper saved to Drafts.
  • Click any suggested follow-up question to rerun search with that prompt.
  • Before your first search, the Start-anywhere cards on the landing page point you at the right entry for your situation — new topic, a document to improve, papers in Zotero, ready to write, or stress-test an idea.
  • To build a whole topic's corpus in one shot (not just answer a single question), use the Domain corpus builder on the Research page.
Where it lives
frontend/src/app/search/page.tsx; components in frontend/src/components/search/. The Start-anywhere cards are components/home/journey-hub.tsx.
When to use it
Any time you have a research question — start of a project, mid-investigation, or when checking specific claims.
Why it exists
Surface answers and the papers behind them in one place, so you can read the source instead of trusting an opaque summary.

Step-by-step

  1. 1.
    Pick your source mode
    Academic web searches eight free providers at once (Semantic Scholar, OpenAlex, PubMed, arXiv, CORE, CrossRef, Europe PMC, ERIC) and is best when you do not yet have papers saved. My library searches your own corpus and is best after Library has a few papers in it.
  2. 2.
    Ask your question
    Phrase it as a complete question — "How does scaled dot-product attention compare to additive attention?" works better than "attention".
  3. 3.
    Read the answer + sources
    Citations like [1], [2] map to the right-rail source cards. Click a card to open a detail panel with the full abstract, authors, DOI, and a link out.
  4. 4.
    Save what you need
    Tick the sources you want and click "Save selected (N)" (or "Save all sources" for the lot) — each goes to your Library, and its open-access PDF is pushed to your Zotero when it is connected.
  5. 5.
    Draft if useful
    If the answer + sources are worth keeping, click "Draft a Paper" — the synthesis is saved to Drafts and you can continue in Write.

Troubleshooting

  • "Library" mode returns nothing
    You probably have not uploaded any papers yet, or the papers do not have embeddings. Go to Library, drop a PDF, wait for the ingest spinner to finish, then retry.
  • Answer streams partially then stops
    Usually the LLM provider hit a rate limit or timed out. Try a shorter question, or check Settings to see if LLM_FALLBACK is configured.
Show backend endpoints
  • POST /api/search (Server-Sent Events stream)

Library

Who
Researchers building a personal corpus of papers to search, synthesise, and graph.
What you can do
  • Drag-and-drop PDFs or entire folders onto the canvas — folder names become collections, breadcrumbs become tags.
  • Click "Upload" in the toolbar for a file picker (multi-select supported).
  • Type in the search bar to filter the list by title (client-side, instant).
  • Click any tag in the sidebar to filter the list; tag counts reflect the filtered set.
  • Tick multiple papers and click "Draft from N" to synthesise a paper from just those.
  • Click a paper row to open the right detail panel; edit tags inline.
  • In a paper's detail panel, click "Read full text" to render its extracted text broken out by section (once full text has been ingested).
  • A "Not searchable yet" amber badge on a paper means it is metadata-only — no full text has been ingested yet, so it will not surface in Library-mode Search until it does.
  • Click "View in Network" in a paper's detail panel to jump straight to that paper's concepts in the graph.
  • Star a paper to bookmark it — stars are saved to your account and survive reloads.
  • "Make searchable" (toolbar) fetches open-access PDFs by DOI for your metadata-only papers — trying OpenAlex, then Semantic Scholar, then Unpaywall — and indexes the text so they finally surface in "My library" search. Papers with no open-access PDF stay metadata-only and keep the "Not searchable yet" badge.
  • "Archive PDFs → Zotero" (toolbar) pushes the open-access PDFs of papers already in your Library into your Zotero as attachments. It is quota-aware — a free Zotero account has 300 MB of storage; if it fills up, the rest of the batch is skipped, so free some space and run it again.
  • "Add by DOI…" (toolbar) is a one-field quick-add: paste a DOI and ScholarFlow resolves the metadata, saves the paper, and fetches its open-access PDF in the background.
  • "Import RIS/BibTeX" (toolbar) brings in an export from any database (ERIC, JSTOR, Scopus, Web of Science…). It shows a preview table so you can uncheck rows before saving, and saves up to 500 entries in chunks.
  • A green "In Zotero" badge appears on a paper once its PDF has been pushed to your Zotero, so you can see at a glance what has already been archived.
  • "Export knowledgebase (OKF)" (toolbar) downloads your whole corpus — papers, concepts, drafts, books — as a portable markdown bundle. See "Your knowledgebase as an open format (OKF)".
Where it lives
frontend/src/app/library/page.tsx; components in frontend/src/components/library/.
When to use it
Early — before Search and Write become useful, you need a corpus here. Add to it any time.
Why it exists
Search and Network are only as good as the corpus they read. Library is where you put the corpus and how you keep it organised.

Step-by-step

  1. 1.
    Drop one PDF to test
    Drag a single PDF onto the canvas. The upload strip at the top shows progress: pending → uploading → done. After "done", Grobid parses sections and references in the background — this can take 30s–3 min.
  2. 2.
    Drop a folder to bulk-import
    For 5+ files or nested folders, a preview modal appears showing what will be uploaded. Confirm and the queue runs sequentially (one at a time) to avoid thrashing the backend.
  3. 3.
    Verify the paper finished ingesting
    Open the paper detail. If the abstract is populated and the chunk count is non-zero, ingest succeeded. If it stays at 0 chunks for more than a few minutes, see troubleshooting.
  4. 4.
    Use the corpus
    Run a Library-mode Search to query it semantically, or open Network to see the concept graph that was extracted.

Troubleshooting

  • PDF says 0 chunks after upload
    Grobid (the PDF parser) timed out. Default timeout is 300s. Large or scanned PDFs may exceed this. Re-upload usually works; if it does not, the PDF may be image-only and need OCR (not yet supported).
  • Chunks are saved but embeddings are NULL
    Nomic API blip during ingest. The paper is fine — chunks have text — but it will not appear in Library-mode Search. Re-uploading triggers fresh embeddings.
  • Upload appears to hang past 100s
    The frontend now uses an async-ingest path (200 returns immediately, Grobid runs in background). If you still see hangs, check the backend logs for the slow path.
  • A paper shows a "Not searchable yet" badge — what do I do?
    That badge means only metadata was ingested, not the full text — usually because it came in via Zotero sync or a reference import without a PDF. Click "Make searchable" in the toolbar to fetch an open-access PDF by DOI and index it, run "Backfill PDFs" on the Zotero settings page, or re-upload the PDF directly; the badge clears once full text lands. If no open-access PDF exists, the paper stays metadata-only.
  • "Archive PDFs → Zotero" stopped partway through.
    You most likely hit your Zotero storage quota — a free Zotero account only gets 300 MB, and PDF attachments count against it. ScholarFlow skips the remaining papers rather than failing the whole batch. Free up space in Zotero (or upgrade its storage) and run "Archive PDFs → Zotero" again to push the rest.
  • My RIS/BibTeX import saved fewer papers than the file had.
    Records missing a title are skipped (the preview flags them with an amber badge), and you may have unticked some rows. Very large files import up to 500 entries in chunks — split a bigger export and import it in parts.
Show backend endpoints
  • POST /api/papers/upload (multipart: file, folder_path?)
  • GET /api/papers?limit=&offset=&tag=&collection=
  • PATCH /api/papers/{id}
  • DELETE /api/papers/{id}
  • POST /api/papers/backfill-oa (Make searchable)
  • POST /api/papers/add-by-id (Add by DOI)
  • POST /api/papers/import-file (RIS/BibTeX preview)
  • POST /api/zotero/archive-pdfs (Archive PDFs → Zotero)
  • GET /api/okf/export (Export knowledgebase)

Library — organizing like Zotero

Who
Academic researchers who already think in Zotero terms — folders and tags — and want their ScholarFlow papers organized the same familiar way, without learning a new mental model.
What you can do
  • The Library is where every paper you save or upload lives, using Zotero's two organizing tools so nothing feels foreign: collections (folders that group papers by project or topic) and tags (flexible labels a paper can carry many of).
  • The left sidebar always shows "All Papers" (everything you have), "Starred" (your bookmarks), and a growing list of your tags you can click to filter.
  • When you drag in a folder of PDFs, ScholarFlow reads the structure: the folder name becomes a collection, and each sub-folder along the path becomes a tag — so your existing filing survives the move.
  • Fuller collection management (create/rename/move) is on the way; a friendlier folders/collections UI is tracked in sub-project C.
Where it lives
The Library tab in the left sidebar (the book icon). Filtering controls — All Papers, Starred, and your tags — sit in the Library's own left-hand panel. Zotero connection lives separately under Settings → Integrations → Zotero.
When to use it
From day one. Before Search's "My library" mode or the Write and Research tools can pull from your own reading, the papers have to be here and findable. Organize as you go.
Why it exists
A pile of PDFs is not a corpus. Collections and tags turn that pile into something you can slice — "just my thesis-chapter-2 papers," "everything tagged methods" — so that when you search, draft, or verify, you are working from the right subset. Keeping it Zotero-shaped means you can move between the two tools without re-learning how your library is laid out.

Step-by-step

  1. 1.
    Open the Library and add papers
    If it is empty, add papers first — click Save on a source card in Search, or connect Zotero under Settings → Integrations to sync your existing library in.
  2. 2.
    Use the left panel
    "All Papers" shows your whole collection; click it any time to clear filters. Click "Starred" to see only bookmarked papers (starring is session-only for now — treat it as a temporary shortlist).
  3. 3.
    Filter by tag
    Click any tag to filter the list to papers carrying that tag. The list updates instantly, and tag counts reflect what is currently shown.
  4. 4.
    Bring in a filed folder
    Drag a whole folder onto the Library. ScholarFlow turns the folder name into a collection and each sub-folder in the path into a tag automatically — your Zotero-style filing carries over untouched.
  5. 5.
    Edit tags per paper
    Click any paper row to open its detail panel on the right, where you can adjust its tags by hand, click "Read full text" to read the extracted sections, or click "View in Network" to see that paper's concepts in the graph.

Troubleshooting

  • What is the difference between a collection and a tag?
    A collection is a folder — a paper lives in one collection, usually tied to a project or chapter. Tags are labels — a paper can have many (e.g. "methods", "to-read", "2024"). It is exactly the Zotero split: collections for structure, tags for cross-cutting themes.
  • I starred some papers and they are gone after I reloaded. Why?
    Starring is interface-only right now and is not yet saved to the server, so it resets between sessions. It is fine as a quick shortlist within a session; for durable grouping, use a tag or collection instead.
  • The "New collection" button does not do anything.
    It is stubbed while collection management is being expanded (sub-project C). The way to create a collection today is to drag in a folder — its name becomes the collection.

Network

Who
Researchers exploring how the concepts in their corpus connect to each other — and want a readable map, not a tangle of dots and lines.
What you can do
  • Click "Build graph from my library" to build a concept graph from your saved papers — nodes are concepts (and papers), edges are the relationships between them.
  • Every edge carries a semantic label — SUPPORTS, CONTRASTS, EXTENDS, or RELATED_TO — so you can read what kind of relationship connects two concepts, not just that one exists.
  • Concepts are auto-classified into 12 academic domains, which is what colours each node; node size scales with how connected (degree) a concept is.
  • A corner legend (bottom-left) shows the domain colour key and the relationship-type key together, so you can read the graph without guessing.
  • Type a domain in the filter input to scope the graph (e.g. "neuroscience").
  • Pick a layout from the dropdown — "Organic (fcose)" is the default; other options (force-directed, circle, grid, hierarchy, concentric) are there for comparing structural views.
  • Use the +/− buttons to zoom; "Fit all" recentres the graph.
  • Click any edge to open a relationship detail card describing that connection; click any node to open a curated concept card on the right.
  • Use "Ask the graph" (right-hand panel) to ask a question about your concept graph and get an answer that highlights the matching concepts.
Where it lives
frontend/src/app/network/page.tsx; components in frontend/src/components/network/ (graph-viewer.tsx uses Cytoscape.js).
When to use it
After you have 3+ papers in Library — fewer than that and the graph is uninformative.
Why it exists
Reveal the hidden structure of your reading — which concepts recur, how they relate (support each other, contrast, extend one another), which papers cluster, and where the gaps are.

Troubleshooting

  • Graph is empty even though I have papers
    Click "Build graph from my library" — the graph is not built automatically on upload. A build can take a minute or two and runs in the background; the page polls for results, so you can leave it running. If it stays empty, add papers with actual abstracts/full text first.
  • Graph is too dense to read
    Use the domain filter to scope to one field at a time — this also narrows the legend to just the domains present. Or switch to a more structured layout (Grid, Hierarchy, Concentric) and zoom into one cluster at a time.
  • What do the node colours and edge labels mean?
    Node colour = the concept's auto-classified academic domain (12 total); node size = how many connections it has. Edge labels name the relationship type: SUPPORTS, CONTRASTS, EXTENDS, or RELATED_TO. The corner legend always shows the current key for both.
Show backend endpoints
  • GET /api/graph/network
  • POST /api/graph/query
  • POST /api/graph/backfill-domains

Research — the guided pipeline

Who
Academics who want a complete, reviewed first draft — not just an answer. If you have a topic and an idea of the paper you wish existed but do not want to assemble the literature, write the synthesis, and self-critique it by hand, this is your starting point.
What you can do
  • Research (the page is labeled "Hermes Research Agent") runs one automated 10-stage pipeline that turns a topic into a full manuscript — drafted, fact-checked against its sources, and critiqued by four reviewer personas.
  • You give it a topic and, ideally, a short abstract of the paper you want; it refines your question, plans a search, searches the literature and synthesizes a draft, runs a citation-integrity gate, has four personas review it, revises accordingly, optionally lengthens it to ~6,000 words, and hands you a final draft you can download as Markdown.
  • This is the "do the whole thing" mode — distinct from Search (quick cited answers to a single question) and Write (hands-on section-by-section editing of an existing draft).
  • At the top of the page, the Domain corpus builder does the opposite of a single search: give it a topic and a size (10, 20, or 50 papers) and, in one background run, it curates research perspectives, searches all the providers, saves the new papers to your Library, fetches their open-access PDFs, and refreshes your concept graph — so a whole area becomes searchable, writable, and debatable at once. Papers whose PDF cannot be fetched stay as metadata with the "Not searchable yet" badge.
Where it lives
The "Research" item in the left sidebar (frontend/src/app/research/page.tsx). The Domain corpus builder panel sits at the top; the Result area below has four tabs: Final draft, Review, Pipeline log, and Run history.
When to use it
When you want a finished, defensible draft rather than a quick lookup — kicking off a new paper, a literature-grounded position piece, or a first synthesis you will then polish. A run typically takes 5–12 minutes, so it is a "start it and step away" task.
Why it exists
A good synthesis paper normally means reading widely, drafting, checking every citation, and inviting critique — days of work. Research compresses that into one supervised pass and does the parts people skip: it verifies each claim is actually supported by its cited source (the integrity gate) and stress-tests the argument from four reviewer viewpoints before you ever see it.

Step-by-step

  1. 1.
    (Optional) Build the corpus first
    If you want the pipeline (and War Room) to draw on a deep, topic-specific library, run the Domain corpus builder at the top of the page first: enter a topic, pick 10/20/50 papers, and click Start. It curates, searches, saves, embeds PDFs, and refreshes your concept graph in the background — then come back and run the pipeline.
  2. 2.
    Open Research and enter your topic
    You will see a "Research brief" card. Enter your Topic / Title — the working title of the paper you want.
  3. 3.
    Fill in your abstract (optional but recommended)
    Whatever you write here becomes the contract for what the paper must deliver: name the specific frameworks, effect sizes, or formats you expect. Leave it blank and you will get a generic paper on the topic.
  4. 4.
    (Optional) Adjust Advanced settings
    Max sources (5–100, default 25), Reviewer mode — strict / balanced / lenient — and the "Length boost" checkbox (~6,000 words). If unsure, leave the defaults.
  5. 5.
    Start research
    Click "Start research". The run typically takes 5–12 minutes; you can leave and come back. When it finishes, read the "Final draft" tab and click "Download .md".
  6. 6.
    Review, then keep working
    Open the "Review" tab for the reviewers' consensus verdict and applied changes. To keep editing, download the Markdown and continue in Write, then confirm citations on the Verify page.

Troubleshooting

  • What is the difference between Research, Search, and Write?
    Search gives a fast, cited answer to one question. Research runs the full pipeline and hands back a complete drafted-and-reviewed paper. Write is the hands-on editor where you refine a draft section by section. Rough order: Research to generate, Write to polish, Verify to fact-check.
  • Why is it taking several minutes / did it freeze?
    That is normal — a run moves through 10 stages and typically takes 5–12 minutes. The button stays on "Running 10-stage pipeline..." until done. If it stops with a red error box, the topic or a provider likely hit a snag; try again with a shorter brief.
  • Where does the finished paper go?
    It appears in the "Final draft" tab and you download it with "Download .md" — it is not automatically saved into Drafts or Library. Past runs stay in the "Run history" tab.
Show backend endpoints
  • POST /api/cil/research
  • POST /api/domain-research (Domain corpus builder)
  • GET /api/domain-research/{id}

Write

Who
Anyone editing a paper — most commonly after generating a draft from Search or Library.
What you can do
  • Click a section in the left outline to load it into the rich text editor.
  • Expand/collapse subsections with the chevron icons.
  • Edit prose in the centre rich text editor (Tiptap-based, supports bold, italic, headings, lists).
  • Click "Chat" in the top-right toolbar to open the side-panel chat for context-aware writing help on the current section.
  • Type a topic into the outline panel's input and click "Generate outline" to have the AI draft a full section outline for that topic — no more starting from the default scaffold every time.
Where it lives
frontend/src/app/write/page.tsx; components in frontend/src/components/write/.
When to use it
After generating a draft from Search or Library — or for editing any existing paper section-by-section.
Why it exists
Drafts coming out of synthesis need cleanup: tightening prose, restructuring, adding original commentary. Write is the place to do that without losing the AI assist.

Troubleshooting

  • "Generate outline" does not seem to do anything
    Make sure you have typed a topic into the field next to the button first — it is disabled until there is text. It calls an LLM, so a slow provider can take a few seconds; a red error line under the field means the request failed, so retry.
  • The "Add section" (+) button does nothing
    That one is still a placeholder — manually adding a single section is on the roadmap. To get a different structure today, change your topic and click "Generate outline" again.

Drafts

Who
Researchers returning to past synthesis work — re-reading, editing, archiving, or deleting.
What you can do
  • Browse the list of every draft you have generated, with title, topic, source mode, source count, and timestamp.
  • Click a row to load the full markdown into the reader pane.
  • Hover a row to reveal the trash icon — click to delete (with confirmation).
  • Click the refresh icon in the top-right to re-fetch the list.
Where it lives
frontend/src/app/drafts/page.tsx.
When to use it
Any time between research sessions — it is the durable history of what you have produced.
Why it exists
Synthesis papers are throwaway by default; Drafts makes them findable, comparable, and prunable over time.
Show backend endpoints
  • GET /api/drafts?limit=
  • GET /api/drafts/{id}
  • DELETE /api/drafts/{id}

Verify & Analyze — checking your citations

Who
Anyone who has finished (or nearly finished) a draft and needs to be sure every citation actually holds up — a researcher tidying a manuscript, a writer preparing to submit, or someone checking an AI-assisted draft before it goes to a supervisor or journal.
What you can do
  • Verify (the Citation Integrity Audit, ShieldCheck icon): upload a finished draft and get EVERY citation checked against its real source, labelled VERIFIED (the source backs the claim), UNVERIFIABLE (the source could not be reached or read), or CONTRADICTED (the source actually says something different).
  • Analyze (Per-section Source Analysis, magnifying-glass icon): upload the SAME kind of draft and walk it section-by-section — for each part, ScholarFlow suggests additional real papers you have not cited yet.
  • Think of it simply: Verify checks the citations you already have; Analyze suggests citations you might be missing.
  • Both run on your uploaded file only — you do not need anything in your Library first, and nothing you upload here changes your Library.
Where it lives
Two separate sidebar pages: Verify at frontend/src/app/verify/page.tsx (POST /api/cil/verify) and Analyze at frontend/src/app/analyze/page.tsx (POST /api/cil/analyze). Both are standalone upload pages.
When to use it
At the very end of your workflow, after writing. Run Verify when a draft is close to done and you need confidence the references are honest. Run Analyze a little earlier, while a section still feels thin or one-sided.
Why it exists
The single most damaging error in academic writing is a citation that does not say what you claim it says — and AI-assisted drafts make this easier to introduce. Verify catches those before a reviewer does, and gives you a downloadable audit trail (including a COPE AI-use log). Analyze does the opposite favour: it stops your argument being one-sided by surfacing the papers you overlooked.

Step-by-step

  1. 1.
    Decide which tool you need
    Checking citations you already wrote? Open Verify. Looking for sources you might be missing? Open Analyze. You can run both on the same file.
  2. 2.
    VERIFY — upload your draft
    Drop your draft onto the dashed upload box. Accepted formats: Markdown (.md), Word (.docx), or LaTeX (.tex). A .tex file also needs its .bib bibliography so references resolve.
  3. 3.
    Run Verify and read the summary
    Click "Verify citations" (~1–3 min per 20 citations). Read the Summary cards: Total, Verified, Unverifiable, Contradicted. A red "Needs attention" banner lists high-confidence CONTRADICTED ones — fix those first.
  4. 4.
    Expand a citation and download evidence
    Click any row to see the claim context, the actual source passage, and the verdict reasoning. Use "Markdown report", "COPE AI-use log", or "Run JSON" to save the audit.
  5. 5.
    ANALYZE — surface missing sources
    Open Analyze, drop your draft (.md or .docx), optionally set "Max sources per section", and click "Analyze draft". Expand any section to see candidate papers with clickable DOI / OpenAlex links.

Troubleshooting

  • Which one do I run first — Verify or Analyze?
    They are independent. A common flow is Analyze while a draft still feels incomplete, then Verify once it is near-final. If you only do one, do Verify — a wrong citation is more damaging than a missing one.
  • What does UNVERIFIABLE actually mean — did I do something wrong?
    Not necessarily. It means the source could not be reached or read automatically — often a paywalled PDF, a missing DOI, or a source with no online full text. It is a "could not check", not a "you are wrong". Expand the row to see which retrieval attempts were made.
  • Why will it not accept my PDF or .tex file on the Analyze page?
    Analyze only accepts Markdown (.md) and Word (.docx). Verify additionally accepts LaTeX (.tex), but a .tex upload also needs its sibling .bib file. PDF is not supported on either page — export as .docx first.
Show backend endpoints
  • POST /api/cil/verify
  • POST /api/cil/analyze

Books — starting & checking a manuscript

Who
Authors and researchers writing something book-length — a monograph, thesis, or multi-chapter manuscript — who want to start from an outline + references and have every reference checked, one citation at a time.
What you can do
  • Open Books to see every manuscript ingested for you, each with a citation-check verdict summary (how many references came back VERIFIED, UNVERIFIABLE, or CONTRADICTED).
  • Click a manuscript to open its per-citation integrity report — each reference gets its own verdict, so you can see exactly which claims are backed by a real, findable source.
  • Start a manuscript three ways: click "New" on the Books page and upload a Word (.docx), markdown, or text file (an optional .bib reference list can ride along); paste markdown directly; or seed one via the Books API / your Hermes agent CLI (see "Hermes agent CLI").
  • The checker prioritises DOI-bearing citations because those resolve against the literature most reliably; re-running a check clears stale verdicts so you never read an out-of-date result.
Where it lives
The Books item in the left sidebar (/books). The list and each manuscript's per-citation report live there. Ingestion happens via the Books API or the Hermes agent CLI (Settings → Integrations → Agent) — there is no separate in-app upload screen yet.
When to use it
When you have an outline + reference list to draft against, or a draft manuscript you want checked before you submit, share, or publish.
Why it exists
A book has far too many references to verify by hand, and a single unverifiable or contradicted citation can undermine an entire argument. Books gives you a reference-by-reference integrity report so you know precisely where to look, instead of trusting that "the citations are probably fine."

Step-by-step

  1. 1.
    Start a manuscript today (outline + references)
    Click "New" on the Books page and upload your .docx/markdown/text manuscript (add a .bib file if you have one) — it appears in the Books list immediately. Agents can seed manuscripts through the Books API / Hermes CLI too.
  2. 2.
    Open its report
    Click a manuscript to read the verdict summary (counts of VERIFIED / UNVERIFIABLE / CONTRADICTED), then scroll the per-citation list to see each reference's individual verdict.
  3. 3.
    Prioritise the problem cases
    Focus on anything marked CONTRADICTED (the source disagrees with how it was cited) and UNVERIFIABLE (no matching source found), especially where a DOI was present — those are the most trustworthy verdicts.
  4. 4.
    Re-run after revising
    If you have since revised the manuscript, re-run the check. Previous verdicts are cleared on a re-run, so what you see always reflects the current version.
  5. 5.
    Need to check just one document?
    Use the Verify page instead: it takes a single markdown or .docx file plus an optional .bib and returns the same verdicts. Books is the multi-chapter, whole-manuscript version of that check.

Troubleshooting

  • How do I start a manuscript right now — I do not see an upload button?
    Use Books → New: upload a Word (.docx), markdown, or text file and it shows up in the Books list right away — then open it and click "Enhance" to improve it section by section, or run the reference check. For a quick one-off citation check without saving a document, use the Verify page.
  • My Books list is empty. Is something broken?
    No — it just means nothing has been ingested for your account yet. If you were expecting one, confirm with whoever ran the ingestion (or your Hermes agent) that it completed.
  • Why are references with a DOI treated differently?
    The checker prioritises DOI-bearing citations because a DOI points to one specific, resolvable record in the literature — that makes the verdict far more reliable than matching by title or author alone.
Show backend endpoints
  • GET /api/books
  • POST /api/books (ingest a manuscript: outline + references)

Improve a document

Who
Anyone with a draft in hand — an outline, a chapter, a report, a whole manuscript — who wants to strengthen the argument and shore up the citations rather than start over. No need to have anything in your Library first.
What you can do
  • Improve a document turns an existing draft into a stronger, better-sourced one — section by section — while keeping your voice, instead of letting an AI regenerate the whole thing.
  • Start by uploading the document: go to Books → New and drop a Word (.docx), Markdown (.md), or plain-text file (plus an optional .bib of references). Open it, then click "Enhance".
  • For any section, "Critique" gives a structured read — strengths, weaknesses, missing evidence, and a clarity score out of 5.
  • "Find better sources" pulls candidate papers for that section from both your own library and a fresh web search, each labelled "Your library" or "Fresh search" so you always know where it came from.
  • Tick the sources you trust, add optional instructions, and "Rewrite with selected sources" produces a grounded rewrite that cites them. You see the original and the rewrite side by side; click "Apply" to keep it, or leave it and move on.
  • Export the finished document as .md or .docx from the header at any time.
  • "Check references" (the header link back to the book) runs the same per-citation integrity verdicts you get in Books and Verify — so a document you enhanced can be citation-checked in the same place.
Where it lives
Upload at Books → New (/books/new). The enhance workspace is at /books/{id}/enhance, reached from the "Enhance" button on a book. "Check references" and the .md / .docx exports sit in its header; the section rail is on the left.
When to use it
When you already have a draft and want to tighten the argument and citations — polishing a chapter before it goes to a supervisor, firming up a thin section, or preparing a report for review.
Why it exists
Most drafts are not wrong so much as thin: an unsupported claim here, a one-sided section there. Enhancing per section — critique, find real sources, rewrite grounded in the ones you pick, then citation-check — fixes exactly those gaps without throwing away what already works.

Step-by-step

  1. 1.
    Upload the document
    Go to Books → New, give it a title, and upload your draft (.docx, .md, or .txt) plus an optional .bib of references. Click "Create book" — the citation check starts automatically.
  2. 2.
    Open Enhance and pick a section
    From the book, click "Enhance". The left rail lists the sections detected from your headings; click one to work on it.
  3. 3.
    Critique, then find sources
    Click "Critique" for the strengths / weaknesses / missing-evidence read-out and a clarity score. Click "Find better sources" for candidate papers, each tagged "Your library" or "Fresh search".
  4. 4.
    Rewrite and apply
    Tick the sources you want, add any instructions, and click "Rewrite with selected sources". Compare the original and rewrite side by side, then click "Apply" to keep the new version.
  5. 5.
    Export and reference-check
    Export the document as .md or .docx from the header. Use "Check references" to run the per-citation VERIFIED / UNVERIFIABLE / CONTRADICTED verdicts over what you have written.

Troubleshooting

  • The section rail says "No sections detected."
    Enhance splits a document on its headings. If nothing shows, the file had no detectable headings — add Markdown headings (## Section) or Word heading styles and re-upload at Books → New.
  • What is the difference between Enhance and Verify?
    Enhance improves the writing and its sourcing section by section (critique → better sources → grounded rewrite). Verify — and "Check references" here — only judges the citations you already have. Enhance to strengthen, Check references to confirm.
  • Can I upload a PDF to enhance?
    No — upload Word (.docx), Markdown (.md), or plain text at Books → New. Export a PDF to .docx first. (PDFs come into your Library through Zotero sync, which is a separate path.)
Show backend endpoints
  • GET /api/docs/{id}/sections
  • POST /api/docs/{id}/sections/{index}/critique
  • POST /api/docs/{id}/sections/{index}/suggest-sources
  • POST /api/docs/{id}/sections/{index}/rewrite
  • POST /api/docs/{id}/sections/{index}/apply
  • GET /api/docs/{id}/export?format=md|docx

Inbox — reviewing agent work

Who
Researchers who run the optional external Hermes agent on their own computer and want to stay in control of it. If you have not set up the Hermes agent, this page is not for you yet — and an empty Inbox is completely normal.
What you can do
  • A human-in-the-loop review queue for the Hermes research agent. When the agent reaches a checkpoint — a drafted section, a citation it judged unverifiable, a finished review pass — it posts a "packet" here describing what it did or wants to do next, then waits.
  • You read the packet, then Approve, Reject, or Pause. Your decision is sent back to the agent, which resumes (or stops) accordingly.
  • Some packets are mandatory (the agent will not proceed until you rule); others are optional/informational (the agent keeps working).
  • Opening a packet's run detail shows a Provenance envelope, a Calibration card (how accurate the automated judgment is), artifact downloads, a before/after Diff, and a Verdict panel.
Where it lives
The "Inbox" item in the left sidebar. Packets are posted to your Inbox by the Hermes agent running on your own machine; each opens into a run detail view.
When to use it
While the Hermes agent is running a research or citation job for you. Mandatory packets block its progress, so the sooner you rule, the sooner it continues. If you are not running the agent, you never need to visit this page.
Why it exists
Automated research is fast but not infallible, and academic work lives or dies on the trustworthiness of its citations. The Inbox keeps a human in the loop at the moments that matter: instead of the agent silently deciding, it shows you its reasoning, evidence, and a measured confidence score, and lets you veto or approve.

Step-by-step

  1. 1.
    Set up the agent first (one time)
    The Inbox only fills up if the Hermes agent is posting to it. Open Settings → Integrations → Agent to generate an agent-scoped access token and follow the setup guide. Your model key stays on your own machine.
  2. 2.
    Start a job, then open the Inbox
    Once your local Hermes agent begins a run, it pauses at its first checkpoint and a packet appears in the list. Until then the list is empty — that is expected, not an error.
  3. 3.
    Open a packet to see what it is asking
    Each packet describes a proposed action or verdict. Mandatory packets are the ones the agent is waiting on; optional packets are informational and do not block it.
  4. 4.
    Read the run detail before deciding
    The Provenance envelope tells you where the work came from; the Diff shows the change; artifact links download the files; the Calibration card tells you how accurate this judge has been ("published" vs "bootstrap").
  5. 5.
    Cast your verdict
    In the Verdict panel choose Approve (apply + continue), Reject (discard + adjust), or Pause (halt and wait). Your choice is delivered back to the agent automatically.

Troubleshooting

  • My Inbox is empty — is something broken?
    Almost certainly not. The Inbox only shows work posted by the external Hermes agent running on your own computer. If you have not installed and started that agent, the empty state is correct. Everything else in ScholarFlow works without it.
  • Do I have to use the Hermes agent to use ScholarFlow?
    No. Hermes is an optional power-user tool for automated, checkpointed research and citation work. Most of ScholarFlow is fully usable without ever touching the Inbox.
  • What is the difference between a mandatory and an optional packet?
    A mandatory packet blocks the agent: it will not continue until you Approve, Reject, or Pause it. An optional packet is informational — the agent keeps working and you can review it whenever it suits you.
Show backend endpoints
  • GET /api/inbox/packets
  • POST /api/inbox/packets/{id}/verdict

Calibration Card — how much to trust a verdict

Who
Any researcher about to accept or reject an automated verdict — for example, when an agent tells you a citation is "VERIFIED" or "CONTRADICTED" and you need to decide whether to trust that call before relying on it.
What you can do
  • The Calibration Card is a small scorecard that tells you how well the automated judge behind a verdict has actually performed on a set of known-correct examples (its "gold set"). It shows four numbers and a status label.
  • FNR (false-negative rate) = how often the judge misses a real problem. FPR (false-positive rate) = how often it raises a false alarm.
  • AUC = a single 0-to-1 overall accuracy score (closer to 1 is better; 0.5 is a coin flip). N = how many gold examples it was tested against — bigger N means a more reliable score.
  • Status is "bootstrap" (N under 200, treat as provisional) or "published" (tested on enough examples to be production-ready).
Where it lives
Two places. The full Calibration page (Calibration in the left sidebar) shows platform-wide metrics for each judge/skill. A Calibration Card also appears inside Inbox run details, next to the verdict panel.
When to use it
Right before you act on an automated verdict — especially the citation-integrity calls from the Hermes agent in your Inbox, or the VERIFIED/UNVERIFIABLE/CONTRADICTED results on the Verify page. Check it whenever the stakes are high or a verdict surprises you.
Why it exists
An automated verdict is only as trustworthy as the judge that produced it. Without the card, "CONTRADICTED" looks equally authoritative whether the judge is 95% accurate or barely better than guessing. The card turns that hidden reliability into plain numbers.

Step-by-step

  1. 1.
    Open the Calibration page
    From the left sidebar, see every judge/skill on the platform and its current scorecard — this is the overview.
  2. 2.
    Read the status label first
    "Published" means the numbers are trustworthy; "bootstrap" means N is under 200 and the numbers are still provisional — treat them as an early signal, not gospel.
  3. 3.
    Read AUC as your at-a-glance trust score
    Near 1.0 is strong, around 0.5 means the judge is essentially guessing. This is the fastest single number to check.
  4. 4.
    Check FNR and N
    If a missed problem costs you more than a false alarm (usually the case for citations), a low FNR means the judge rarely lets a bad citation through. A small N means scores can still shift, so weight your own judgment more heavily.
  5. 5.
    Make your call in Inbox
    Open a packet the agent posted and find the Calibration Card scoped to THIS verdict. If it is "published" with high AUC and low FNR, approve with confidence; if "bootstrap" or the rates look weak, open the source and check the claim yourself.

Troubleshooting

  • What is a "gold set" and why does its size (N) matter?
    A gold set is a batch of examples where the correct answer is already known by humans. The more examples (higher N), the more you can trust the score reflects real performance. Under 200, the platform flags it "bootstrap".
  • Which number should I look at first?
    AUC for a quick overall read (closer to 1 is better), then FNR if you most fear a real problem slipping through — usually the case for citations.
  • The verdict says CONTRADICTED but the card looks weak — what do I do?
    Trust the card over the verdict. A weak scorecard (low AUC, high FNR/FPR, or "bootstrap") means the judge is not yet reliable, so open the actual source and check the claim yourself before you approve, reject, or pause.
Show backend endpoints
  • GET /api/cil/calibration

Hermes agent CLI — automating research

Who
Researchers who want deep, long-running literature or citation-integrity work done on their own computer, autonomously, while keeping final say. It is optional and technical to set up (a one-time command-line install), but day to day you interact with it through the normal ScholarFlow Inbox.
What you can do
  • Hermes is a separate "bring-your-own" command-line agent — it is NOT built into this website. You install it once on your own machine (pip install citation-integrity-agent hermes-skills-runtime), point it at ScholarFlow with a token, and give it your own AI model key.
  • It runs research and citation-checking tasks on your computer, and every time it reaches a decision point it pauses and posts a "packet" to your ScholarFlow Inbox for you to Approve, Reject, or Pause.
  • Your model key stays on your machine and is never sent to ScholarFlow. Think of it as an assistant that does the heavy work locally and checks in with you here.
  • This is the documented, working path that makes workflow A (start a manuscript from an outline + references) actionable today — the Books section links here for the "how do I start a manuscript right now?" answer.
  • Beyond the checkpoint loop, your agent can drive ScholarFlow directly through about 30 MCP tools — the same actions you take by hand: search and save_selected papers, zotero_archive_pdfs, import_reference_file, run and continue a war_room_* debate, the doc_* enhance pipeline, query_corpus, and domain_research_* corpus builds. Mint the agent token at Settings → Integrations → Agent and point your MCP client at it — everything stays scoped to your account.
  • Agents teach themselves the connection: a public "agent manifest" at scholarflowresearch.com/.well-known/scholarflow-agent.md describes the MCP endpoint, the token scheme, and the live tool list. Tell any capable agent "read that file and connect with this token" and it has everything it needs — you never copy technical settings by hand.
Where it lives
Setup lives at Settings → Integrations → Agent (/settings/integrations/agent), where you generate the agent token. Day-to-day, everything the agent sends you appears in the Inbox route. The agent itself runs in a terminal on your own computer.
When to use it
Use it when a task is too big or too long for a single in-app session — a full multi-stage literature review, a from-scratch drafted-and-verified paper, or a whole manuscript's citation integrity run — and you want it to work unattended while still approving each major step.
Why it exists
The in-app Research page runs its 10-stage pipeline live in your browser while you wait. The Hermes CLI is for the same class of work when you want it to run autonomously in the background, on your own hardware, with your own model key and your own costs — and with a human-approval gate at every checkpoint.

Step-by-step

  1. 1.
    Open Settings → Integrations → Agent
    This page holds everything you need to connect the CLI — you do not need to touch it again once set up.
  2. 2.
    Generate an agent token
    Create an agent-scoped personal access token; copy it immediately and keep it safe (you paste it into the agent's config, not into the website).
  3. 3.
    Install the agent on your own computer
    In a terminal, run: pip install citation-integrity-agent hermes-skills-runtime. This is the only technical step — if unsure, ask a technical colleague for five minutes of help.
  4. 4.
    Create the agent's .env config
    Set SF_BACKEND_URL, HERMES_INTERNAL_KEY (the token you generated), and SF_USER_ID (so packets arrive in YOUR Inbox). Add your own model provider key here too — it stays local and never reaches ScholarFlow.
  5. 5.
    Start a task, then approve in the Inbox
    Run a task from your terminal; when it hits a checkpoint it posts a packet to your ScholarFlow Inbox. Click Approve, Reject, or Pause and the verdict flows straight back — no need to restart anything in the terminal.

Troubleshooting

  • I'm not technical — what is the minimum to connect an agent?
    Three things, all point-and-click on your side: (1) create a token at Settings → Integrations → Agent and give it to your agent (or whoever runs it) along with one URL — scholarflowresearch.com/.well-known/scholarflow-agent.md — which tells the agent everything else; (2) connect Zotero at Settings → Integrations → Zotero so papers and PDFs the agent saves land in your own Zotero; (3) optionally install the ScholarFlow Obsidian plugin so your notes vault stays in sync. If someone provisions a Hermes agent for you, step 1 is the only thing they need from you.
  • Do I have to use the command line every day?
    No. Installing and configuring the agent is a one-time terminal setup. After that you start a run occasionally and do all the reviewing right here in the Inbox.
  • Will my AI model key be sent to ScholarFlow?
    No. Your model key lives only in the agent's local .env file. The agent talks to your model provider directly and only sends ScholarFlow the checkpoint packets it wants you to review.
  • I set it up but nothing is showing in my Inbox.
    Check three things in the agent's .env: SF_USER_ID must be YOUR user id, the HERMES_INTERNAL_KEY must be the token you generated (regenerate if unsure), and SF_BACKEND_URL must point at ScholarFlow. A revoked or mistyped token means the agent's posts are rejected.

War Room — debate a claim

Who
Anyone about to publish or rely on a research claim who wants it pressure-tested before a real reviewer finds the hole — a researcher sanity-checking a thesis statement, or a writer deciding whether an argument is ready to build on.
What you can do
  • Enter a research claim and War Room runs a structured debate: five distinct expert personas each give an independent, grounded analysis, then anonymously cross-challenge each other over the rounds you choose.
  • You pick the depth — 2, 3, or 4 rounds. More rounds dig deeper but take longer and cost more; a first pass at 2 rounds is usually plenty.
  • Every debate is grounded twice over: in fresh literature pulled for the claim AND in your OWN library. Evidence the panel drew from your saved papers is labelled [C1], [C2]… in a "From your library" strip under the verdict, and ticking "Deep evidence check" adds an Evidence check strip that reads full source text and marks each supporting passage VERIFIED / CONTRADICTED / UNVERIFIABLE.
  • A confidence-weighted judge weighs every perspective and returns a verdict: overall panel confidence, the claim's strengths, its weaknesses, and an actionable revision checklist.
  • The verdict is not the end — a discussion opens under it. Answer the panel or ask your own question (up to 20 exchanges per debate) and the panel re-examines the debate against your message, grounded in your library again. When only you can supply a missing fact, the panel turns it around: a "The panel asks you:" banner puts a focused question to you.
  • 🎙 Voice mode (the header toggle): dictate your claim and follow-ups by mic, and hear each persona read back in its own distinct voice. It works instantly with your browser's built-in voices; if the operator has added an ElevenLabs key, the toggle switches to premium voices and labels which set you are hearing.
  • Bring your own models: under Settings → Integrations → War Room panel models you can attach up to three LLM keys (DeepSeek, OpenAI, or OpenRouter — Claude and Gemini are reachable through OpenRouter) and map each of the five personas and the judge to a specific key/model, for a genuinely mixed-model panel. Your debates then run on your keys instead of the shared default.
Where it lives
The "War Room" item in the left sidebar (/war-room). Panel model keys live at Settings → Integrations → War Room panel models (/settings/integrations/panel-llm).
When to use it
After you have a claim or thesis statement you want to stand behind — before you build a whole paper or section around it, or right before you submit or share a draft that leans on it.
Why it exists
A claim that only survives one point of view is fragile. Debating it across five independent experts, grounding every round in your own library, then letting you argue back for as long as it takes surfaces the objections a single reviewer would raise — and hands you a concrete checklist for fixing them, instead of a vague "sounds reasonable."

Step-by-step

  1. 1.
    Enter a claim and set the depth
    Type the research claim you want tested — be specific; a precise claim gets a sharper debate. Choose 2, 3, or 4 rounds, and tick "Deep evidence check" if you want the panel to read full source text (slower, more accurate).
  2. 2.
    Start the debate
    Click "Start debate" (about 30–60 seconds). The personas run independent analyses first, then cross-challenge each other across your chosen rounds.
  3. 3.
    Read the verdict and its evidence
    The verdict card shows panel confidence, strengths, weaknesses, and a revision checklist. Below it, the "From your library" strip shows which of YOUR papers ([C1], [C2]…) the panel leaned on, and the Evidence check strip shows the per-passage source verdicts.
  4. 4.
    Keep the discussion going
    Under the verdict, use "Answer the panel or ask your own question…" to push back or dig deeper — up to 20 exchanges. If a "The panel asks you:" banner appears, the panel needs a fact only you have; answer it to move on.
  5. 5.
    Speak and listen, if you like
    Flip on 🎙 Voice mode to dictate your claim and follow-ups and hear each persona in its own voice. Act on the revision checklist, then click "Start a new debate" to test a revised version.

Troubleshooting

  • "War Room not available on this deployment"
    The multi-perspective debate feature is flag-gated and may be off on this deployment. There is nothing to fix on your end — it is coming back in a future update.
  • The "From your library" strip says it used no library evidence.
    That just means none of your saved papers matched this claim closely enough, so the debate was grounded on fresh literature only. Save a few relevant papers (or run the Domain corpus builder on that topic) and debate again to get library-grounded evidence with [C1]-style labels.
  • Can I run more than one debate at once?
    No — one debate at a time per user, by design. Wait for the current run to finish before starting another.
  • Voice mode is silent, or I only get a plain browser voice.
    Voice mode uses your browser's built-in voices out of the box, so distinct per-persona voices depend on what your browser and OS provide. The richer premium voices only appear when the operator has added an ElevenLabs key — the toggle labels which set you are hearing ("Browser voices" vs "Premium voices").
Show backend endpoints
  • POST /api/warroom
  • GET /api/warroom/{id}
  • POST /api/warroom/{id}/continue
  • POST /api/voice/tts
  • GET /api/voice/status
  • GET/PUT /api/integrations/panel-llm

Settings

Who
Operators and power users verifying integrations are wired up. Not a typical research-user destination.
What you can do
  • Read which integrations are configured: AI Models (LLM, fallback, embeddings), External APIs (Semantic Scholar, Perplexity, Zotero), Datastores (Postgres, Neo4j, Redis), Auth (Clerk, MCP).
  • See the env var name and config hint for each unconfigured integration.
  • Click "Refresh" to re-poll the status endpoint.
  • In the Zotero section, trigger a manual Zotero sync if API key + user ID are configured.
Where it lives
frontend/src/app/settings/page.tsx; Zotero section in frontend/src/components/settings/zotero-section.tsx.
When to use it
During initial setup, after editing backend/.env, or when something downstream (Search, Network) stops working.
Why it exists
Most ScholarFlow problems are config problems. This page tells you which knob is wrong without grepping logs.

Troubleshooting

  • Status shows "false" for an integration I configured
    Backend container needs a restart to pick up the new env var. Run `docker compose restart backend` from the repo root, then click Refresh here.
  • Using your own Perplexity API key (academic-web search)
    Academic-web search is powered by Perplexity and works out of the box on a shared key — you do not need to do anything. To use your OWN Perplexity key (higher limits, your own billing), create one at perplexity.ai (Settings → API), then add it yourself at Settings → Integrations → Perplexity (/settings/integrations/perplexity) — no operator or backend change needed. The Settings status page shows whether a key is active.
Show backend endpoints
  • GET /api/settings/status

Your knowledgebase as an open format (OKF)

Who
Anyone who wants their research corpus in a portable, non-proprietary format — for backup, for reading in Obsidian/any markdown tool, or for a Hermes agent that needs to browse your papers/concepts/drafts/books programmatically.
What you can do
  • OKF (Open Knowledge Format) is a read-only, on-demand view of your knowledgebase — papers, concepts (+ relations), drafts, and books — rendered as plain markdown files with YAML frontmatter. Nothing is duplicated or synced; every document is generated fresh from the database on request.
  • Every document carries a `type` field (index/log/paper/concept) and links to related documents as `[[wiki-links]]`, so the whole bundle forms a navigable graph the same way an Obsidian vault does.
  • Endpoints: GET /api/okf/index.md (start here), /log.md (recent activity), /papers/index.md + /papers/{id}.md, /concepts/index.md + /concepts/{id}.md, /drafts/index.md, /books/index.md, /export (a zip of the whole bundle), and /lint (a JSON structural hygiene report — unsearchable papers, orphan concepts, broken links, missing metadata, duplicate titles).
  • A Hermes agent authenticates the same endpoints with its agent token (X-Hermes-Auth header, minted at Settings → Integrations → Agent) and reads exactly your knowledgebase — nothing from any other user. OKF is the read side of the roughly 30 MCP tools an agent uses to work your corpus (query_corpus and the papers/concepts/drafts/books endpoints); the write side — save_selected, import_reference_file, war_room_*, doc_*, domain_research_* — is covered in "Hermes agent CLI".
  • Embeddings/vector columns are never included in any OKF document — only human-readable metadata and text.
Where it lives
The "Export knowledgebase (OKF)" button in the Library toolbar downloads the zip. Individual markdown endpoints live under /api/okf/* for direct or agent access.
When to use it
When you want an offline backup, want to browse your corpus in Obsidian outside ScholarFlow, or are wiring up a Hermes agent (or any other tool) that needs read access to your papers/concepts/drafts/books.
Why it exists
Your knowledgebase living only behind bespoke JSON endpoints locks it to this app. OKF gives you (and any agent you authorize) a standard, portable, link-navigable export — the data stays yours, in a format nothing proprietary gates.

Step-by-step

  1. 1.
    Download the whole bundle
    Click "Export knowledgebase (OKF)" in the Library toolbar — it downloads a zip with index.md, log.md, and per-item markdown files for every paper, concept, draft, and book you own.
  2. 2.
    Browse it like a vault
    Unzip and open index.md first, then follow the [[links]] — it reads like an Obsidian vault because the same link-navigation convention is used.
  3. 3.
    Check hygiene with /lint
    GET /api/okf/lint returns a JSON report flagging papers with no searchable text, orphan concepts, broken links, missing metadata, and likely duplicate titles — a quick health check on your corpus.
  4. 4.
    Point a Hermes agent at it
    An agent with a valid agent token (X-Hermes-Auth header) can read any /api/okf/* endpoint directly — the same per-user scoping applies, so it only ever sees your data.

Troubleshooting

  • The export button did nothing / errored
    The OKF feature can be flag-gated off on some deployments (503). If it is enabled and still fails, check your connection and try again — the export is generated on demand from your current data, so a very large library can take a few seconds.
  • A paper/concept link 404s
    OKF is per-user and read-only — a link only resolves if the item still exists and belongs to you. If a paper or concept was deleted after the bundle was generated, its link will 404 on a fresh fetch.
Show backend endpoints
  • GET /api/okf/index.md
  • GET /api/okf/log.md
  • GET /api/okf/papers/index.md
  • GET /api/okf/papers/{id}.md
  • GET /api/okf/concepts/index.md
  • GET /api/okf/concepts/{id}.md
  • GET /api/okf/drafts/index.md
  • GET /api/okf/books/index.md
  • GET /api/okf/export
  • GET /api/okf/lint