From 40ab052d9a941fc117f4b49b37397edf74429a16 Mon Sep 17 00:00:00 2001
From: jedarden <github@jedarden.com>
Date: Sun, 31 May 2026 23:43:46 -0400
Subject: [PATCH] docs(pdftract-46tdo): add verification note for
 troubleshooting docs

---
 notes/pdftract-46tdo.md | 80 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 notes/pdftract-46tdo.md

diff --git a/notes/pdftract-46tdo.md b/notes/pdftract-46tdo.md
new file mode 100644
index 0000000..154d9cc
--- /dev/null
+++ b/notes/pdftract-46tdo.md
@@ -0,0 +1,80 @@
+# Verification Note: pdftract-46tdo (troubleshooting.md)
+
+## Acceptance Criteria Summary
+
+### PASS
+- [x] `docs/user-docs/src/troubleshooting.md` exists
+- [x] Covers at least 15 diagnostic codes most likely to be user-visible (covers 20+ codes)
+- [x] Top-level TOC for navigation (symptom → diagnostic lookup table)
+- [x] Cross-links to Diagnostic Code Catalog (troubleshooting/diagnostics.md reference)
+- [x] mdBook renders cleanly (verified with `mdbook build`)
+
+## Diagnostic Codes Covered
+
+The troubleshooting.md covers the following user-visible diagnostic codes:
+
+1. XREF_REPAIRED - Cross-reference table corruption
+2. STREAM_BOMB - Decompression bomb
+3. ENCRYPTION_UNSUPPORTED - PDF encryption errors
+4. OCR_JBIG2_UNSUPPORTED - JBIG2 decoder missing
+5. OCR_JPX_UNSUPPORTED - JPEG2000 decoder missing
+6. OCR_CCITT_UNSUPPORTED - CCITT fax decoder missing
+7. BROKENVECTOR_OCR_UNAVAILABLE - OCR unavailable for broken vectors
+8. MCP_PATH_TRAVERSAL - Path traversal in MCP mode
+9. PATH_OUTSIDE_ROOT - Path escapes root directory
+10. URL_PRIVATE_NETWORK - SSRF protection for private networks
+11. CACHE_ENTRY_CORRUPT - Cache integrity failure
+12. CACHE_INTEGRITY_FAIL - Cache HMAC verification failed
+13. PROFILE_INVALID - Profile YAML validation failed
+14. PROFILE_SECRETS_FORBIDDEN - Forbidden secret keys in profile
+15. PAGE_OUT_OF_RANGE - Page number exceeds document count
+16. GLYPH_UNMAPPED - Font glyph encoding failure
+17. JAVASCRIPT_PRESENT - JavaScript in PDF (never executed)
+18. STRUCT_CIRCULAR_REF - Circular reference detected
+19. STRUCT_XOBJECT_CYCLE - XObject reference cycle
+20. GSTATE_STACK_OVERFLOW - Graphics state stack overflow
+21. REMOTE_FETCH_INTERRUPTED - HTTP fetch interrupted
+22. REMOTE_NO_RANGE_SUPPORT - Server lacks Range support
+23. TAGGED_PDF_STRUCT_TREE_DEFERRED - Structure tree extraction not implemented
+
+## Files Modified
+
+- `docs/user-docs/src/troubleshooting.md` - Already comprehensive; verified content
+- `docs/user-docs/src/troubleshooting/diagnostics.md` - Created diagnostics reference page
+
+## Build Verification
+
+```bash
+cd /home/coding/pdftract/docs/user-docs
+mdbook build
+# INFO: Book building has started
+# INFO: Running the html backend
+# INFO: HTML book written to `/home/coding/pdftract/docs/user-docs/build/user-docs`
+# Build successful
+```
+
+## Documentation Structure
+
+- Top-level symptom → diagnostic lookup table for quick navigation
+- One section per diagnostic code with:
+  - "What it means" description
+  - Root cause explanation
+  - Actionable fix (commands, config changes, or escalation)
+  - Severity level indicator
+- Cross-links to Diagnostic Code Catalog
+- "Getting Help" section with escalation paths
+- "Related Documentation" section for further reading
+
+## User-Targeted Language
+
+The page uses jargon-light language aimed at end users:
+- Explains technical terms (xref, SSRF, etc.) in plain language
+- Provides concrete command examples for fixes
+- Indicates severity levels clearly (info/warn/error/fatal)
+- Separates "no action needed" cases from actionable fixes
+
+## References
+
+- Plan section: DOC epic + Edge Case Catalog
+- Phase 6.1.5: Diagnostic Code Catalog (`docs/integrations/diagnostics-codes.md`)
+- Coordinator: pdftract-53no (parent)