formatferry 1.0.27 → 1.0.29

package/README.md

@@ -27,6 +27,33 @@ formatferry -i paper.pdf -o paper.md
 formatferry -i data.xlsx -o data.md
 ```
 
+## Scanned PDFs
+
+The CLI extracts a PDF's existing text layer. It does **not** run OCR, so a
+scanned or image-only PDF has no text to extract and the conversion fails:
+
+```
+$ formatferry -i scan.pdf
+Error [IMAGE_ONLY]: PDF contains only images — no text layer available. OCR is not enabled in this environment.
+```
+
+OCR is a browser-only feature: it runs on-device via Tesseract at
+[formatferry.vibingfun.com](https://formatferry.vibingfun.com), where scanned
+pages inside a PDF are recognized page by page and merged with the pages that
+already have real text. It is deliberately absent here — the CLI ships no WASM
+OCR engine, which keeps the install small and the conversion fully offline.
+
+For a PDF that mixes real text pages with scanned inserts, the conversion
+**succeeds** and the scanned pages come through empty. The document has enough
+text elsewhere to avoid the `IMAGE_ONLY` error above, so the exit code is 0 and
+the only sign is a page heading with nothing under it. Check the output when a
+PDF may contain scans — for this case the CLI cannot tell you which pages it
+could not read, because no OCR ran and so nothing reported a per-page failure.
+
+Conversion warnings that *are* produced (for example unusual table structures)
+are written to stderr, never stdout, so `formatferry -i doc.pdf > out.md` keeps
+the Markdown clean while still showing you the warnings.
+
 ## Commands
 
 ### Convert (default)