doc: doc the --json option

README.md

@@ -180,14 +180,53 @@ cat path/to/library/papers/.../logs/mineru.log
 
 ## Machine-Readable Output
 
-Most commands support `--json` output for automation:
+Most commands support `--json` output for automation and integration:
 
 ```bash
-paperlib list --json
-paperlib show <paper-id> --json
+# Get library configuration in JSON
 paperlib status --json
+
+# List all papers with metadata
+paperlib list --json
+
+# Get detailed paper information  
+paperlib show <paper-id> --json
+
+# Get import results
+paperlib import --arxiv 2212.06340 --json
+
+# Get conversion status and results
+paperlib convert --json
+paperlib convert --paper-id <paper-id> --json
+
+# Get reindexing statistics
+paperlib reindex --json
 ```
 
+### JSON Output Format
+
+All JSON responses follow a consistent envelope format:
+
+```json
+{
+  "success": true,
+  "timestamp": "2024-01-15T10:30:00.000Z",
+  "data": { /* command-specific data */ }
+}
+```
+
+For errors:
+```json
+{
+  "success": false, 
+  "timestamp": "2024-01-15T10:30:00.000Z",
+  "error": "Error message here",
+  "error_code": 1
+}
+```
+
+This structured output enables reliable automation, scripting, and integration with other tools. The JSON format is stable across paperlib versions.
+
 ## Development
 
 paperlib is designed for extensibility and integration with higher-level tools.
@@ -238,7 +277,7 @@ paperlib follows clean architecture principles:
 - [x] Comprehensive test suite
 - [ ] Search command implementation
 - [ ] AI summarization with provider abstraction
-- [ ] JSON output for all commands
+- [x] JSON output for core commands
 - [ ] Configuration file support
 - [ ] Advanced arXiv workflows