build-research-context

Step 4 — Monitor progress

Use the Monitor tool on "${BUILD_LOG}" to stream progress as lines appear. Report key markers to the user:

Continue monitoring until the background bash notification fires (build process exits). Then proceed to Step 5.

Step 5 — Activate MCP tools

Call mcp__paper-compiler__bind_research_dir with research_dir="${RESEARCH_DIR}".

This tells the running MCP server to reload from the freshly written research/. After this call, all 26 MCP tools (query_chunks, find_atom, get_evidence, graph_sql, etc.) are live against the new research.

If the call returns an error, note it in the report but continue — the user can restart the MCP server manually.

Step 6 — Validate

Run the validator script:

${CLAUDE_PLUGIN_ROOT}/scripts/validate-build-manifest.sh "${RESEARCH_DIR}"

Exit codes: 0 = all pass; 1 = soft warnings (coverage low / atoms low / single-source); 2 = hard fail (manifest missing / evidence provenance regressed / expansion failed). The script prints PASS/SOFT/HARD per invariant on stderr and a JSON summary on stdout.

Read ${RESEARCH_DIR}/build-manifest.json for real coverage numbers.

Acceptance invariants (v2.0):

• papers_in_neighborhood ≥ 5 (HARD)
• coverage_pct ≥ 70
• atoms_extracted ≥ 30
• evidence_provenance.resolved_pct == 100.0 (HARD)
• papers_by_source has ≥ 2 distinct sources
• papers-with-atoms / papers-acquired ≥ 0.6

If any hard-fails, report the failure and the likely cause from the Failure modes table. Do not silently report success.

Step 7 — Report

Compiled <paper title> (<paper-id>).

Outputs:
- research/research.md          (~<N> KB human-readable brief)
- research/SCHEMA.md            (Claude-readable DB reference)
- research/research.db          (sqlite + sqlite-vec + FTS5 Graph RAG store)
- research/wiki/                (Obsidian-style cross-linked articles)
- research/missing-details.md   (<K> open questions)
- research/graph.json           (full atom graph, also in DB)
- research/evidence/            (<E> per-atom verbatim spans)

Compile stats:
- Wall time:           <S>s
- References resolved: <X>/<Y>  (<pct>%)
- Neighborhood:        <P> papers (<acquired> with full text)
- Sources used:        <e.g. arxiv_tex: 80, openalex_pdf: 50, unavailable: 96>
- Atoms extracted:     <A>
- Evidence provenance: <E>/<T> (<pct>%)   ← must be 100%
- Edges classified:    <E>  (contradicts: <K>)
- Communities:         <C>
- Wiki answers re-indexed: <W>
- LLM backend used:    <claude_cli | anthropic | none>

MCP status: bind_research_dir called — all 26 MCP tools now queryable.
Next: /paper-compiler:wiki-query "<question>" or /paper-compiler:use-research-context to start implementing.

Failure modes

Rules

• Never run build without first running resolve and surfacing the canonical paper.
• Always use ${CLAUDE_PROJECT_DIR}/research as the absolute output path — never research/ (relative).
• Never edit research/ files yourself. The CLI is the only writer.
• If build exits non-zero, do not retry blindly. Read the error, surface it, ask the user.
• Do not summarize the paper's contents in your report. The summary lives in research.md. Your job is to confirm the compile produced real numbers.

Setup notes

The CLI at ${CLAUDE_PLUGIN_ROOT}/cli/bin/paper-compiler is a Python entrypoint. The base install handles TeX papers + heuristic classification + BM25 search. Optional extras:

pip install -e "${CLAUDE_PLUGIN_ROOT}/cli[pdf]"      # Marker for PDF papers
pip install -e "${CLAUDE_PLUGIN_ROOT}/cli[indexes]"  # SPECTER2 vector search

For LLM-based classification + atom extraction, in order of preference:

1. Run inside a Claude Code session → the CLI auto-detects the claude CLI on PATH and reuses your subscription auth via claude -p. No API key required.
2. Or set ANTHROPIC_API_KEY in .env (cwd) or shell env → CLI uses the Anthropic SDK directly.
3. Or pass --no-llm → heuristics only.

SEMANTIC_SCHOLAR_API_KEY is strongly recommended either way (1 RPS dedicated vs. shared anonymous pool). Put it in .env so it survives shell restarts.