docs(bf-5kafx): document pdftract CLI command execution and results

notes/bf-5kafx.md

@@ -0,0 +1,132 @@
+# pdftract CLI Command Execution Documentation
+
+**Bead ID:** bf-5kafx  
+**Date:** 2026-07-05  
+**Task:** Document command and execution results
+
+## Commands Executed
+
+### 1. Binary Location and Version
+```bash
+# Binary path
+target/release/pdftract
+
+# Version info (from doctor output)
+pdftract version: 0.1.0 (git: f95f38009fe7a58d1a35127eadd...)
+Binary size: 17.8 MB
+```
+
+### 2. Help Command
+```bash
+pdftract --help
+```
+**Exit Code:** 0 (success)  
+**Execution Time:** ~0.002 seconds  
+**Output Format:** Structured text with command listings and descriptions  
+**File Path:** `/home/coding/pdftract/target/release/pdftract`
+
+### 3. Diagnostic Listing
+```bash
+pdftract list-diagnostics
+```
+**Exit Code:** 0 (success)  
+**Execution Time:** ~0.002 seconds  
+**Output Format:** Hierarchical diagnostic codes (100 codes)
+- STRUCT_*: Structure-related diagnostics
+- XREF_*: Cross-reference diagnostics  
+- STREAM_*: Stream diagnostics
+
+### 4. Environment Health Check
+```bash
+pdftract doctor
+```
+**Exit Code:** 0 (success)  
+**Execution Time:** ~0.002 seconds  
+**Output Format:** Table format with status columns
+
+### 5. Extraction Commands
+
+#### Valid PDF (base_hello.pdf)
+```bash
+pdftract extract tests/document_model/fixtures/base_hello.pdf --json -
+```
+**Exit Code:** 0 (success)  
+**Execution Time:** 0.002 seconds  
+**Output Format:** Valid JSON to stdout  
+**File Paths:** 
+- Input: `tests/document_model/fixtures/base_hello.pdf`
+- Output: stdout
+
+#### Malformed PDF (js_in_openaction.pdf)
+```bash
+pdftract extract tests/document_model/fixtures/js_in_openaction.pdf --json -
+```
+**Exit Code:** 0 (ANOMALY - should be non-zero on error)  
+**Error:** "No /Root reference in trailer"  
+**Note:** This is expected behavior for this intentionally malformed test fixture
+
+### 6. Validation Commands
+```bash
+pdftract validate <schema_file>
+```
+**Exit Code:** 1 (on validation errors)  
+**Execution Time:** ~0.004-0.013 seconds  
+**Output Format:** JSON path + error message
+```
+/ "schema_version" is a required property
+/ "metadata" is a required property
+```
+
+### 7. Classify Command
+```bash
+pdftract classify <pdf_file>
+```
+**Exit Code:** 1 (when missing required features)  
+**Error:** Requires `--features profiles`  
+**Note:** Feature-gated command
+
+## Exit Code Summary
+
+| Exit Code | Meaning | Examples |
+|-----------|---------|----------|
+| 0 | Success | --help, list-diagnostics, doctor, successful extraction |
+| 1 | Runtime Errors | Validation failures, missing features |
+| 2 | Argument/File Errors | Invalid arguments, file not found, missing command |
+
+## Performance Metrics
+
+All commands executed in **excellent timing**:
+- Help/diagnostics: ~0.002 seconds
+- Doctor command: ~0.002 seconds
+- Validation: ~0.004-0.013 seconds
+- Extraction: ~0.002 seconds (valid PDFs)
+
+**All commands < 30 seconds requirement** ✅
+
+## Output Formats Observed
+
+1. **Structured Text:** Help listings, diagnostic codes
+2. **JSON Data:** Extraction output with schema_version 1.0
+3. **Error Messages:** Path-based validation errors
+4. **Tabular Data:** Doctor command health checks
+
+## Warnings and Anomalies
+
+1. **Exit Code Inconsistency:** Extract failures return exit code 0 (should return non-zero)
+2. **Missing Version Flag:** Neither `--version` nor `-V` work correctly
+3. **Feature Gating:** Some commands require specific build features
+
+## File Paths Referenced
+
+- Binary: `/home/coding/pdftract/target/release/pdftract`
+- Test fixtures: `/home/coding/pdftract/tests/document_model/fixtures/`
+- Valid PDF: `base_hello.pdf`
+- Malformed test PDF: `js_in_openaction.pdf`
+- Expected outputs: `*.expected.json` files in fixtures directory
+
+## Environment Details
+
+- **System:** Linux 6.12.63
+- **Available RAM:** 59915 MiB
+- **Binary location:** Also symlinked to `/home/coding/.local/bin/pdftract`
+- **Cache status:** Directory does not exist (non-blocking)