feat: v0.1.0 release polish - critical and major fixes

[spignotti]

Summary

This PR implements all critical and major fixes from FEATURE.md to prepare litresearch for v0.1.0 publication.

Critical Fixes

1. JSON parsing error handling - Wrapped json.loads() in both _screen_paper and _analyze_paper with try/except JSONDecodeError. Returns None and prints warning on malformed LLM responses instead of crashing.

2. Semantic Scholar timeout/retry - Added s2_timeout config setting (default 10s). S2 client is now created with timeout=settings.s2_timeout, retry=False in both discovery and enrichment stages to prevent 14-minute hangs.

3. PDF double-download prevention - PDFs are now saved during analysis stage to papers/ directory and marked pdf_downloaded=True. Export stage skips already-downloaded papers.

Major Fixes

4. Immutable Settings construction - Refactored _build_settings() to use Settings(**overrides) pattern instead of post-init mutation.

5. Output directory collision handling - Added --overwrite flag and auto-increment logic. When output directory exists and is populated, automatically uses output-2, output-3, etc.

6. No-abstract paper handling - Papers without abstracts now get a ScreeningResult with relevance_score=0 and rationale="no abstract available" instead of being silently skipped.

7. LLMError handling in query_gen - Wrapped call_llm() in try/except with clear error message on failure.

8. Config file hygiene - Renamed litresearch.toml to litresearch.toml.example (already in .gitignore).

9. HTML entity unescaping - Applied html.unescape() to title, venue, and abstract fields in Paper.from_s2().

10. Stage-level test coverage - Added 3 new test files with comprehensive coverage:

    • test_stages_query_gen.py - query generation and error handling
    • test_stages_screening.py - screening behavior and no-abstract handling
    • test_stages_discovery.py - S2 client config and deduplication

Minor Polish

11. Added BATCH_SIZE comment documenting S2 batch endpoint limit
12. Added run summary block showing timing and counts at pipeline completion
13. Changed screening_threshold default from 40 to 60 with documentation

Validation

All nox sessions pass:

• ✅ lint (ruff check + format)
• ✅ typecheck (pyright, 0 errors)
• ✅ test (23 tests passed)

Commits

• fix: critical issues - JSON parsing, S2 timeout, PDF deduplication
• fix(cli): immutable settings construction and output collision handling
• fix: handle no-abstract papers and LLMError in query_gen
• fix: rename litresearch.toml to example and unescape HTML entities
• test: add stage-level tests for query_gen, screening, discovery
• chore: minor polish - comments, summary output, threshold default