ResearchFlow Agent Guide

ResearchFlow is an agent-ready research knowledge base, not just a paper folder.

Core loop:

Zotero sync / collect paper list -> paper analysis -> build index -> research assist

Download sits inside the intake path between collection and analysis.

What This Repository Is For

Build a local literature knowledge base from web pages, GitHub awesome lists, Zotero libraries, and PDFs
Convert papers into structured notes that can be queried by agents
Reuse the knowledge base for comparison, idea generation, question banks, reviewer-style critique, and code-grounded implementation planning

paperAnalysis/: authoritative structured evidence and the primary retrieval layer for agents
paperCollection/: generated index and navigation layer — index.jsonl for agent retrieval after build, Obsidian pages for human browsing
paperPDFs/: local PDF storage
paperIDEAs/: idea outputs
scripts/: maintenance and automation helpers

For broad research questions, start from paperCollection/index.jsonl to narrow candidates when it has been generated; otherwise search paperAnalysis/ directly and read matching notes as the main evidence source
Use paperCollection/ Obsidian pages only when you want navigation, graph view, or backlink exploration
When analysis notes are added or updated, run papers-build-collection-index to generate or refresh both paperCollection/index.jsonl (agent index) and Obsidian navigation pages
Prefer answers grounded in local note structure such as tags, venue, year, core_operator, and primary_logic
Treat this repository as shared memory that can support Claude Code, Codex CLI, and other agents
When code and KB need to work together, keep ResearchFlow as the active workspace and link external repositories under linkedCodebases/ instead of linking ResearchFlow into a code repo

Use the following repo-level default unless the user explicitly asks for a different language in the current request:

analysis_language: zh

Supported values: zh, en
This default controls new notes generated by papers-analyze-pdf
zh: analysis prose in Chinese; section headings use Part I：问题与挑战, Part II：方法与洞察, Part III：证据与局限, and ### 核心直觉
en: analysis prose in English; section headings use Part I: Problem & Challenge, Part II: Method & Insight, Part III: Evidence & Limits, and ### The "Aha!" Moment
YAML frontmatter keys always stay in English
tags, category, file names, pdf_ref, and wiki links remain English-compatible regardless of analysis language
core_operator and primary_logic values should follow the selected analysis language
An explicit user request for a specific output language overrides this default for that run

AGENTS.md is the stable repo-level entry for Codex
The canonical skill library lives in .claude/skills/
Run python3 scripts/setup_shared_skills.py on macOS/Linux or py -3 scripts\setup_shared_skills.py on Windows to create .agents/skills and .codex/skills compatibility aliases without copying
When a task matches a workflow, Codex should:
1. open .claude/skills/User_README.md or .claude/skills/User_README_CN.md for quick routing
2. open the matching .claude/skills/<skill>/SKILL.md
3. follow that skill file as the workflow definition
Use .claude/skills/User_README.md for the English quick skill map or .claude/skills/User_README_CN.md for the Chinese version
Main workflow families:
- Zotero sync and local PDF folder import
- paper collection
- PDF download and repair
- paper analysis
- index rebuild (agent index + Obsidian navigation)
- knowledge-base query and code-context retrieval
- idea generation and focus coaching
- reviewer-style stress testing
- metadata audit and share export

Build or refresh a topic-specific knowledge base
Compare multiple papers and extract transferable operators or design patterns
Generate question banks and idea notes grounded in the current literature
In a codebase linked under linkedCodebases/, retrieve relevant papers before editing model- or method-related code