docs(bf-698np): verify pdftract CLI exit code and basic output format

notes/bf-698np.md

@@ -0,0 +1,59 @@
+# pdftract CLI Exit Code and Output Format Verification
+
+**Bead ID:** bf-698np  
+**Date:** 2026-07-05  
+**Command tested:** `target/release/pdftract` (17.8 MB binary)
+
+## Exit Codes Discovered
+
+### Exit Code 0 (Success)
+- `pdftract --help` - Help display
+- `pdftract list-diagnostics` - Diagnostic listing (100 codes)
+- `pdftract doctor` - Environment health check
+
+**ANOMALY:** Some error conditions return exit code 0:
+- `pdftract extract --output /tmp/test_output <file>` returns 0 even when extraction fails
+
+### Exit Code 1 (Runtime Errors)
+- `pdftract validate` - JSON validation failures (missing required properties)
+- `pdftract classify` - Missing feature errors (requires `--features profiles`)
+
+### Exit Code 2 (Argument/File Errors)
+- `pdftract --version` - Invalid argument
+- `pdftract -V` - Invalid argument  
+- `pdftract` (no args) - Missing command
+- `pdftract invalid-command` - Unrecognized subcommand
+- `pdftract hash <file>` - File operation failures
+
+## Output Format Analysis
+
+### Text-Based Output
+- **Help text:** Structured command listing with descriptions
+- **Diagnostics:** Hierarchical categorization (STRUCT_*, XREF_*, STREAM_*, etc.)
+- **Doctor:** Table format with status columns
+
+### Validation Output
+- **Error format:** JSON path + error message
+  ```
+  / "schema_version" is a required property
+  / "metadata" is a required property
+  ```
+- **Quiet mode:** `--quiet` suppresses output, exit code only
+
+### Key Observations
+1. **No version flag available** - Neither `--version` nor `-V` work
+2. **Fast execution** - Most commands complete in 0.002-0.004 seconds
+3. **Exit code inconsistency** - Some errors return 0 (should return non-zero)
+4. **Feature gating** - Some commands require specific build features
+
+## Execution Timing
+- Help commands: ~0.002 seconds
+- Diagnostic listing: ~0.002 seconds  
+- Doctor command: ~0.002 seconds
+- Validation: ~0.004-0.013 seconds
+- All commands are very responsive (< 15ms)
+
+## Recommendations
+1. Add proper `--version` flag support
+2. Fix exit code for extract failures (currently returns 0 on error)
+3. Consider consistent exit code 1 for runtime errors vs 2 for argument errors