diff --git a/README.md b/README.md
index 04a5aa2..a30034a 100644
--- a/README.md
+++ b/README.md
@@ -238,7 +238,7 @@ The converter handles:
 |---|---|
 | Headings (H1-H4) | Font size tiers relative to body text, with 0.5pt clustering |
 | Bold/italic | Font name patterns (Bold, Italic, Oblique) |
-| Bullet lists | `*`, `-`, `*`, `○`, `●`, `◦` prefixes |
+| Bullet lists | `•`, `-`, `*`, `○`, `●`, `◦` prefixes |
 | Numbered lists | `1.`, `1)`, `(1)` patterns |
 | Letter lists | `a.`, `a)`, `(a)` patterns |
 | Code blocks | Monospace fonts (Courier, Consolas, Monaco, Menlo, Fira Code, JetBrains Mono) and keyword detection |
diff --git a/docs/python.md b/docs/python.md
index 04525f1..98e1e6d 100644
--- a/docs/python.md
+++ b/docs/python.md
@@ -111,7 +111,8 @@ class PdfResult:                     # process_pdf / detect_pdf
     markdown: str | None             # extracted Markdown (None for detect_pdf)
     page_count: int
     processing_time_ms: int
-    pages_needing_ocr: list[int]
+    pages_needing_ocr: list[int]     # 1-indexed
+    ocr_reasons_by_page: list[PageOcrReasons]
     title: str | None
     confidence: float                # 0.0 - 1.0
     is_complex_layout: bool
@@ -119,6 +120,10 @@ class PdfResult:                     # process_pdf / detect_pdf
     pages_with_columns: list[int]
     has_encoding_issues: bool        # broken font encodings — consider OCR fallback
 
+class PageOcrReasons:                # per-page OCR diagnostics
+    page: int                        # 1-indexed
+    reasons: list[str]               # machine-readable reason identifiers
+
 class PdfClassification:             # classify_pdf
     pdf_type: str
     page_count: int
@@ -140,14 +145,20 @@ class TextItem:                      # extract_text_with_positions
     is_strikeout: bool
     item_type: str
 
+class RegionText:                    # extract_text_in_regions
+    text: str
+    needs_ocr: bool
+    ocr_reason: str | None           # machine-readable OCR reason
+
 class PageRegionTexts:               # extract_text_in_regions
     page: int                        # 0-indexed
-    regions: list[RegionText]        # RegionText: text: str, needs_ocr: bool
+    regions: list[RegionText]
 
 class PagesExtractionResult:         # extract_pages_markdown
-    pages: list[PageMarkdown]        # PageMarkdown: page (0-indexed), markdown, needs_ocr
+    pages: list[PageMarkdown]        # PageMarkdown: page (0-indexed), markdown, needs_ocr, ocr_reason
     pages_with_tables: list[int]     # 1-indexed
     pages_with_columns: list[int]    # 1-indexed
     pages_needing_ocr: list[int]     # 1-indexed
+    ocr_reasons_by_page: list[PageOcrReasons]
     is_complex: bool                 # any page has tables or multi-column layout
 ```
diff --git a/pdf_inspector.pyi b/pdf_inspector.pyi
index a28b996..aa3689e 100644
--- a/pdf_inspector.pyi
+++ b/pdf_inspector.pyi
@@ -10,6 +10,9 @@ class PdfResult:
     page_count: int
     processing_time_ms: int
     pages_needing_ocr: list[int]
+    """1-indexed page numbers that need OCR."""
+    ocr_reasons_by_page: list["PageOcrReasons"]
+    """Machine-readable OCR reasons by 1-indexed page."""
     title: Optional[str]
     confidence: float
     is_complex_layout: bool
@@ -17,6 +20,13 @@ class PdfResult:
     pages_with_columns: list[int]
     has_encoding_issues: bool
 
+class PageOcrReasons:
+    """OCR reasons for a single 1-indexed page."""
+    page: int
+    """1-indexed page number."""
+    reasons: list[str]
+    """Machine-readable OCR reason identifiers."""
+
 class PdfClassification:
     """Lightweight PDF classification result."""
     pdf_type: str
@@ -47,6 +57,8 @@ class RegionText:
     text: str
     needs_ocr: bool
     """True when the text should not be trusted."""
+    ocr_reason: Optional[str]
+    """Machine-readable OCR reason when the cause is known."""
 
 class PageRegionTexts:
     """Extracted text for one page's regions."""
@@ -62,6 +74,8 @@ class PageMarkdown:
     """Formatted markdown for this page (empty string when needs_ocr is True)."""
     needs_ocr: bool
     """True when text on this page is unreliable and OCR should be used instead."""
+    ocr_reason: Optional[str]
+    """Machine-readable OCR reason when the cause is known."""
 
 class PagesExtractionResult:
     """Per-page markdown output with document-wide layout classification."""
@@ -73,6 +87,8 @@ class PagesExtractionResult:
     """1-indexed pages where multi-column layout was detected."""
     pages_needing_ocr: list[int]
     """1-indexed pages that need OCR."""
+    ocr_reasons_by_page: list[PageOcrReasons]
+    """Machine-readable OCR reasons by 1-indexed page."""
     is_complex: bool
     """True if any page has tables or multi-column layout."""