doc: update readme to specify the opengl dependency

README.md

@@ -15,6 +15,27 @@ A local-first paper library engine with a CLI for managing academic papers.
 
 ## Installation
 
+### System Dependencies
+
+For PDF conversion functionality, paperlib requires OpenGL support through MinerU. If you are inside a graphical everionment, you are likely fine. On headless systems, install:
+
+```bash
+# Debian based
+sudo apt-get install libglvnd0
+
+# Fedora  
+sudo dnf install libglvnd-glx
+
+# Arch Linux
+sudo pacman -S libglvnd
+
+# Gentoo
+sudo emerge -av media-libs/libglvnd
+# or just add media-libs/libglvnd to your @world or some set
+```
+
+### Python Package
+
 ```bash
 # Install with uv (recommended)
 uv add paperlib
@@ -127,10 +148,36 @@ pip install mineru[core]
 # Convert all pending papers
 paperlib convert
 
+# Retry failed conversions (useful after fixing system dependencies)
+paperlib convert --retry-failed
+
+# Force reconvert all papers
+paperlib convert --force
+
 # Convert specific paper
 paperlib convert --paper-id <paper-id>
 ```
 
+### Troubleshooting PDF Conversion
+
+If conversion fails with OpenGL/display errors on headless systems:
+
+```bash
+# Check if MinerU is properly installed
+uv run mineru --version
+
+# If you get "libxcb.so.1" or similar errors, install OpenGL support:
+sudo apt-get install libglvnd0  # Ubuntu/Debian
+sudo pacman -S libglvnd         # Arch Linux
+sudo dnf install libglvnd-glx   # Fedora
+
+# Test conversion manually
+mineru -p example.pdf -o /tmp/test_output -b pipeline
+
+# Check paperlib conversion logs
+cat path/to/library/papers/.../logs/mineru.log
+```
+
 ## Machine-Readable Output
 
 Most commands support `--json` output for automation:
@@ -185,7 +232,7 @@ paperlib follows clean architecture principles:
 ## Roadmap
 
 - [x] Core paper import (local PDF, arXiv)
-- [x] PDF to Markdown conversion (MinerU integration)
+- [x] PDF to Markdown conversion (MinerU integration)*
 - [x] Metadata management and search indexing
 - [x] CLI with all basic commands
 - [x] Comprehensive test suite
@@ -195,6 +242,8 @@ paperlib follows clean architecture principles:
 - [ ] Configuration file support
 - [ ] Advanced arXiv workflows
 
+**Note**: PDF conversion requires `libglvnd` system dependency for OpenGL support on headless systems.
+
 ## Non-Goals
 
 paperlib is intentionally focused and does NOT include:
@@ -210,4 +259,4 @@ MIT License - see LICENSE file for details.
 
 ## Contributing
 
-Contributions welcome! Please read the development guidelines in AGENTS.md and ensure all tests pass before submitting PRs.
+Contributions welcome! Please read the development guidelines in AGENTS.md and ensure all tests pass before submitting PRs.