@xberg-io/opencode-xberg 1.3.7 → 1.3.11

package/.opencode/skills/xberg-extracting-with-ocr/SKILL.md

@@ -0,0 +1,129 @@
+---
+description: Use when extracting text from scanned PDFs, photographed pages, or images that have no embedded text layer. Covers OCR backends, language packs, force-OCR, and performance tuning.
+name: xberg-extracting-with-ocr
+---
+
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:b1718303d659167ff376b4e1d4baf546d3e74f8f0804698a3486c0a1d2e6c913
+Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Schema-Version: v1
+-->
+
+# Extracting with OCR
+
+Use this when a document is image-based: scanned PDFs, photographed pages,
+screenshots, JPEG/PNG/TIFF with text. Xberg auto-OCRs raster images and
+auto-detects PDFs that lack a text layer. Force it on when extraction
+returned empty/garbled text from a PDF that "looks" textual.
+
+## When to force OCR
+
+- Extraction returned an empty `content` field, but the file opens visually.
+- The PDF text layer is junk (copy-paste from a viewer produces gibberish).
+- You want consistent output across mixed scanned + digital PDFs.
+
+```bash
+xberg extract scan.pdf --force-ocr=true
+xberg extract scan.pdf --ocr=true --ocr-language eng
+```
+
+If a page has an unreliable text layer, `--force-ocr=true` re-rasterizes
+and runs OCR on every page.
+
+## Backends
+
+Tesseract is the default and ships with the CLI — no extra install. Other
+backends are opt-in:
+
+| Backend       | Flag                                  | Install                                          | Notes                                                          |
+| ------------- | ------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------- |
+| Tesseract     | `--ocr-backend tesseract` (default)   | bundled                                          | Best general-purpose, 100+ languages via tessdata.             |
+| PaddleOCR     | `--ocr-backend paddle-ocr`            | bundled (ONNX Runtime)                           | Strong on Asian scripts. Not available on WASM or Windows.     |
+| Candle VLM    | `--ocr-backend candle-trocr` (and other `candle-*`) | bundled (Candle)                  | Local vision OCR models (`candle-trocr`, `candle-paddleocr-vl`, `candle-glm-ocr`, `candle-deepseek-ocr`). |
+| VLM (hosted)  | `--ocr-backend vlm` + `--vlm-model`   | liter-llm provider (`--vlm-api-key`)             | Multimodal LLM via liter-llm. Use when OCR fails on dense or handwritten layouts. |
+
+Pick Tesseract first. Switch only when accuracy is unacceptable.
+
+## Language packs
+
+Tesseract uses ISO 639-2 codes. Default is `eng`. Combine with `+`:
+
+```bash
+xberg extract menu.jpg --ocr=true --ocr-language "eng+deu"
+xberg extract bilingual.pdf --ocr-language "eng+jpn"
+xberg extract any.pdf --ocr-language all   # all installed packs
+```
+
+Install missing packs at the OS level:
+
+```bash
+# macOS
+brew install tesseract-lang
+
+# Debian/Ubuntu
+sudo apt install tesseract-ocr-deu tesseract-ocr-jpn tesseract-ocr-fra
+
+# Specific lang only
+sudo apt install tesseract-ocr-<iso639-2>
+```
+
+Xberg fails fast with a helpful error if you request a language pack
+that is not installed. Read the error — it names the missing file.
+
+## Useful flags
+
+- `--ocr=true` — enable OCR (auto-enabled for images and scanned PDFs).
+- `--force-ocr=true` — OCR every page even if a text layer exists.
+- `--disable-ocr=true` — never OCR; use embedded text where available. Images and image-only pages can return metadata with no recognized text.
+- `--ocr-language <lang>` — single code or `+`-joined list, or `all`.
+- `--ocr-backend <tesseract|paddle-ocr|vlm|candle-trocr|candle-paddleocr-vl|candle-glm-ocr|candle-deepseek-ocr>` — pick backend.
+- `--ocr-auto-rotate=true` — pre-rotate via the auto-rotate model.
+- `--acceleration <cpu|coreml|cuda|tensorrt|auto>` — ONNX accelerator for
+  paddle-ocr / auto-rotate / layout models.
+
+## Performance tips
+
+- Cache is on by default. Repeated extraction of the same file + config is
+  instant. Do not pass `--no-cache=true` unless you have a reason.
+- For batch OCR, use `xberg batch *.pdf --ocr=true` — internal worker
+  pool parallelizes across CPU cores. Cap with `--max-concurrent N` if
+  memory is tight.
+- Raise `--target-dpi` (default 300) only for low-resolution scans. Higher
+  DPI is slower; 200 is usually enough for printed text.
+- Enable `--ocr-auto-rotate=true` only when pages may be rotated; the
+  classifier adds latency.
+- On Apple Silicon, `--acceleration coreml` typically beats CPU for
+  paddle-ocr and layout detection.
+
+## Config file alternative
+
+Long flag chains belong in `xberg.toml` — auto-discovered from cwd
+upward.
+
+```toml
+force_ocr = true
+output_format = "markdown"
+
+[ocr]
+backend = "tesseract"
+language = "eng+deu"
+auto_rotate = true
+```
+
+Then just run:
+
+```bash
+xberg extract document.pdf
+```
+
+## Common failure modes
+
+- **"missing tessdata"** — install the language pack at OS level (see above).
+- **Empty content on a scanned PDF without `--force-ocr`** — the file has a
+  bogus zero-width text layer. Re-run with `--force-ocr=true`.
+- **OCR on a rotated page** — add `--ocr-auto-rotate=true` or pre-rotate.
+- **Garbled CJK output** — ensure the right language pack is installed and
+  passed via `--ocr-language`; consider `paddle-ocr` for Chinese/Japanese.
+
+See `references/cli-reference.md` and `references/configuration.md` for the full flag and config schema.

package/.opencode/skills/xberg-extracting-with-ocr/index.md

@@ -0,0 +1,10 @@
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:cfb8e2093079ae90ce0540c04d204828e6abd297aeabb5a30e4a3c2e31d39032
+Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Schema-Version: v1
+-->
+
+# Concepts
+
+* [Extracting With Ocr](SKILL.md) - Use when extracting text from scanned PDFs, photographed pages, or images that have no embedded text layer. Covers OCR backends, language packs, force-OCR, and performance tuning.