# ScholarFlow — Agent Manifest
<!-- manifest-version: 1.0 -->

ScholarFlow is an academic research and publishing platform: citation-verified
search across 8 scholarly providers, a personal library synced with the user's
own Zotero (Zotero holds the PDFs; ScholarFlow indexes the text), a concept
graph, corpus-grounded multi-persona "War Room" debates, and a manuscript
pipeline (upload, enhance, reference-check, export).

This file is the machine-readable front door. Any agent can connect by
following the four steps below — no human integration work required.

## 1. Discover (you are here)

Fetch this manifest any time: `GET https://backend-production-2eff.up.railway.app/.well-known/scholarflow-agent.md` (public, no auth).

## 2. Authenticate

ScholarFlow uses **agent personal-access tokens** (PATs), prefix `sft_`.
Every token is bound to one ScholarFlow user; everything you do is scoped to
that user's data.

- The user creates a token at: https://scholarflowresearch.com/settings/integrations/agent
- Send it on **every** request as an HTTP header: `X-Hermes-Auth: sft_...`
- Header-only — never put the token in a URL query string.

## 3. Operate — MCP

- Transport: MCP over SSE. Connect your SSE client to
  `https://backend-production-2eff.up.railway.app/mcp/sse` (the stream); the server tells you the message-post
  endpoint (`https://backend-production-2eff.up.railway.app/mcp/messages/...`) in the handshake. Clients that ask
  for a single URL want `https://backend-production-2eff.up.railway.app/mcp/sse`.
- Auth: the `X-Hermes-Auth` header above (sessions are bound to the opening
  token; cross-user access is rejected)
- Surface: **32 tools**, all scoped to the token's user:

- `search_papers` — Search academic papers across Semantic Scholar, OpenAlex, and PubMed.
- `synthesize` — Synthesize an academic answer to a research question with inline citations.
- `analyze_evidence` — Analyze how academic papers support or contradict a specific claim (consensus meter).
- `generate_outline` — Generate an academic paper outline based on concepts and their relationships.
- `draft_section` — Draft a section of an academic paper with citations.
- `suggest_questions` — Generate follow-up research questions based on a query and optional context.
- `chat` — Context-aware research assistant conversation.
- `add_paper` — Add a paper to your library by DOI, URL, or title search.
- `list_papers` — List papers in your library, optionally filtered by search query.
- `backfill_searchable` — Make metadata-only library papers searchable by fetching their
- `get_paper` — Get full details of a specific paper from your library.
- `import_reference_file` — Parse a RIS or BibTeX reference-file export into a save-ready
- `query_graph` — Query the knowledge graph for concepts and their relationships.
- `sync_zotero` — Sync your Zotero library with ScholarFlow.
- `save_selected` — Save a CHOSEN set of search results into your library (metadata +
- `zotero_archive_pdfs` — Push open-access PDFs into your Zotero for library papers that have
- `export_document` — Export a document as LaTeX, BibTeX, or markdown.
- `query_corpus` — Search YOUR OWN ingested paper corpus (pgvector kNN over already-
- `okf_read` — Read one document from the user's OKF (Open Knowledge Format)
- `okf_lint` — Run the structural hygiene lint over the user's OKF knowledgebase
- `domain_research_start` — Start a background domain-research corpus build: curate -> save ->
- `domain_research_status` — Poll a domain-research run's status/stage/stats.
- `war_room_start` — Start a background War Room debate: 5 personas argue a claim over
- `war_room_status` — Poll a War Room debate's status/transcript/verdict.
- `war_room_continue` — Append a "delve deeper" follow-up round to a FINISHED debate.
- `doc_sections` — List a document's sections with word counts + previews.
- `doc_critique` — Run + persist an LLM critique of one section.
- `doc_suggest_sources` — Suggest better sources for one section: user-corpus chunks merged
- `doc_rewrite` — Run + persist an LLM rewrite of one section, grounded on the
- `doc_apply` — Splice a section's persisted rewrite into the document, replacing
- `create_book` — Create a document in the user's Books workspace from markdown.
- `save_draft` — Save a paper draft into the user's Drafts tab.

## 4. Export — OKF markdown

The user's corpus is readable as Google Open Knowledge Format markdown for
carrying context to other tools (same `X-Hermes-Auth` auth):

- `GET https://backend-production-2eff.up.railway.app/api/okf/index.md` — corpus index
- `GET https://backend-production-2eff.up.railway.app/api/okf/papers/{filename}` — one paper as markdown (filename like `42.md`)
- `GET https://backend-production-2eff.up.railway.app/api/okf/export` — full corpus zip bundle
- `GET https://backend-production-2eff.up.railway.app/api/okf/lint` — structural lint report

## One-time human setup (walk your user through this)

Your user does three point-and-click things once; everything else is yours:

1. **Agent token** — https://scholarflowresearch.com/settings/integrations/agent → create token → paste it into your config.
2. **Zotero** — https://scholarflowresearch.com/settings/integrations/zotero:
   their Zotero user ID + API key, so papers/PDFs you save land in THEIR
   Zotero library.
3. **Obsidian (optional)** — install the ScholarFlow Obsidian plugin
   (Settings → Integrations page links the guide) to sync notes/vault.

## Notes for agent authors

- Web app (human side): https://scholarflowresearch.com
- Rate courtesy: long-running work (domain research, War Rooms) is
  job-based — poll status tools instead of re-submitting.
- Users keep PDFs in their own Zotero; `save_selected` / `zotero_archive_pdfs`
  push PDFs there rather than storing them on ScholarFlow.