@xberg-io/opencode-xberg 1.3.7 → 1.3.8

package/.opencode/skills/chunking/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: chunking
+description: Use when splitting extracted text into chunks for LLM context windows or RAG ingestion. Covers chunk size, overlap, markdown/yaml/semantic chunkers, tokenizer-based sizing, and the standalone `chunk` command.
+---
+
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:0b5cd4bec9d2a8f3452e07139ef56d6b87f9f7990714d15483a03435e751af59
+Source-Hash: blake3:3fca38eb564d0ed9c9194d070fd8dec96de727edc92e82954cb4b9af52cddbaf
+Schema-Version: v1
+-->
+
+# Chunking
+
+Use this when feeding documents into an LLM context window or a vector
+store. Xberg chunks two ways: inline during extraction (chunks land on
+each document's `chunks` field), or standalone via the `chunk` command for text you
+already have. Sizing is character-based by default, or token-based when a
+tokenizer model is supplied.
+
+## Inline during extraction
+
+Turn on chunking with `--chunk` and the chunks appear on the structured
+result under `chunks`:
+
+```bash
+# 1000-char chunks, 200-char overlap (defaults when --chunk is on)
+xberg extract report.pdf --chunk --format json | jq '.chunks | length'
+
+# Explicit size + overlap
+xberg extract report.pdf --chunk --chunk-size 1500 --chunk-overlap 300 --format json
+```
+
+Overlap must be smaller than chunk size — the CLI rejects
+`--chunk-overlap >= --chunk-size`. When you set only `--chunk-overlap`
+against an existing config, an overlap that exceeds the size is clamped to
+`chunk_size / 4`.
+
+## Standalone `chunk` command
+
+Chunk text you already have, from `--text` or stdin. Output defaults to
+JSON:
+
+```bash
+# From a flag
+xberg chunk --text "long document text ..." --chunk-size 800 --chunk-overlap 100
+
+# From stdin (pipe extracted content straight in)
+xberg extract notes.md | xberg chunk --chunk-size 500 --format json
+```
+
+JSON output carries `chunks` (array of strings), `chunk_count`, the
+resolved `config` (`max_characters`, `overlap`, `chunker_type`), and
+`input_size_bytes`. Use `--format text` for a human-readable dump with
+`--- chunk N ---` separators.
+
+> Note: in the JSON output, `chunker_type` is rendered capitalized (`"Text"`,
+> `"Markdown"`, `"Yaml"`, `"Semantic"`) because it is emitted via Rust's Debug
+> formatting, whereas the `--chunker-type` input flag is lowercase
+> (`text`, `markdown`, `yaml`, `semantic`). Lowercase the value before
+> comparing if you parse it back.
+
+## Chunker types
+
+`--chunker-type` selects the splitting strategy (standalone `chunk`
+command):
+
+| Type       | Behavior                                                            |
+| ---------- | ------------------------------------------------------------------- |
+| `text`     | **Default.** Plain character-window splitting with overlap.         |
+| `markdown` | Markdown-aware — splits on structure (headings, blocks) where possible. |
+| `yaml`     | YAML-aware splitting for structured config/data documents.          |
+| `semantic` | Topic-boundary splitting driven by `--topic-threshold` (0.0–1.0, default 0.75). |
+
+```bash
+# Markdown-aware chunking keeps headings and blocks intact
+xberg chunk --text "$(cat README.md)" --chunker-type markdown
+
+# Semantic chunking — lower threshold = more, smaller topic chunks
+xberg chunk --text "$(cat transcript.txt)" --chunker-type semantic --topic-threshold 0.6
+```
+
+## Token-based sizing
+
+By default `--chunk-size` counts characters. To size chunks by tokens for
+a specific model, pass `--chunking-tokenizer` with a HuggingFace tokenizer
+id. On the `extract` command this implicitly enables chunking. Requires the
+`chunking-tokenizers` feature (present in the default CLI build).
+
+```bash
+# Size chunks by GPT-4o tokens during extraction
+xberg extract report.pdf --chunking-tokenizer Xenova/gpt-4o --format json
+
+# Or on the standalone command
+xberg chunk --text "$(cat doc.txt)" --chunking-tokenizer Xenova/gpt-4o --chunk-size 512
+```
+
+With a tokenizer set, `--chunk-size` is interpreted in tokens, not
+characters.
+
+## Config file alternative
+
+Field names in config files are snake_case under `[chunking]`:
+
+```toml
+[chunking]
+max_characters = 1000
+overlap = 200
+chunker_type = "markdown"
+```
+
+```bash
+xberg extract report.pdf --config xberg.toml --format json
+```
+
+> CLI flags map to config fields as `--chunk-size` → `max_characters` and
+> `--chunk-overlap` → `overlap`. In config files use the snake_case names.
+
+## Programmatic access
+
+From Python, enable chunking on the config and read the chunks off the
+document in the result envelope (`result.results[0].chunks`):
+
+```python
+from xberg import ExtractInput, extract, ExtractionConfig, ChunkingConfig
+
+config = ExtractionConfig(
+    chunking=ChunkingConfig(max_characters=1000, overlap=200),
+)
+result = await extract(ExtractInput(uri="report.pdf"), config)
+for chunk in result.results[0].chunks or []:
+    print(len(chunk.content))
+```
+
+> The public Python `ChunkingConfig` (a dataclass) uses constructor kwargs
+> `max_characters` / `overlap`; the Rust core struct fields are also
+> `max_characters` / `overlap`. TOML/JSON config keys are `max_chars` /
+> `max_overlap` (with `max_characters` / `overlap` accepted as serde aliases),
+> and dict-form config passed to `ExtractionConfig` likewise accepts the
+> `max_chars` / `max_overlap` aliases; Node's `ChunkingConfig` interface uses
+> `maxCharacters` / `overlap`. See `references/python-api.md` and
+> `references/rust-api.md` in the sibling `xberg` skill.
+
+## Picking parameters
+
+- **RAG / vector store** — 500–1000 chars (or 256–512 tokens) with
+  10–20% overlap. Use `markdown` chunking for docs to keep sections whole.
+- **LLM summarization** — larger chunks (1500–4000 chars) with small
+  overlap; size by tokens to stay under the model window.
+- **Topic segmentation** — `semantic` chunker; tune `--topic-threshold`
+  down for finer splits, up for coarser ones.
+
+## Common pitfalls
+
+- **Overlap ≥ size** — rejected on `extract`; clamped to `size / 4` when
+  only overlap is changed against an existing config.
+- **Tokenizer without the feature** — `--chunking-tokenizer` errors if the
+  CLI was built without `chunking-tokenizers`. The default build includes it.
+- **Empty input** — the standalone `chunk` command bails on empty text;
+  provide `--text` or pipe non-empty stdin.
+
+See `references/configuration.md` for the full `[chunking]` schema and
+`references/cli-reference.md` for every chunk flag.

package/.opencode/skills/extracting-keywords/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: extracting-keywords
+description: Use when extracting keywords (YAKE/RAKE) from documents — and, secondarily, when detecting document language or generating embeddings for RAG and search. Covers the keyword config (and its feature gating), `--detect-language`, and the standalone `embed` command with real flags.
+---
+
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:0da13ce50f1fef8c192e912e7c2b0d039209a7b676829abe13f4fc86b5ea20bc
+Source-Hash: blake3:3fca38eb564d0ed9c9194d070fd8dec96de727edc92e82954cb4b9af52cddbaf
+Schema-Version: v1
+-->
+
+# Extracting keywords, language, and embeddings
+
+Use this for the enrichment surface around extraction: statistical keyword
+extraction, language detection, and vector embeddings. Keywords and
+language detection ride along with extraction and land on the result;
+embeddings are produced by a dedicated `embed` command.
+
+## Keywords (YAKE / RAKE)
+
+Keyword extraction is configured via the `[keywords]` config block (or
+inline JSON) — there is no single `--keywords` CLI flag. When enabled,
+extracted keywords appear on `result.extracted_keywords` (`extractedKeywords`
+in Node.js; the CLI JSON field is `extracted_keywords`). Two algorithms are
+available:
+
+- **YAKE** (`"yake"`) — statistical, unsupervised single-document
+  extraction. Good general default.
+- **RAKE** (`"rake"`) — co-occurrence / phrase-based. Favors multi-word
+  key phrases.
+
+> Feature-gated: keyword extraction requires the CLI to be built with the
+> `keywords-yake` and/or `keywords-rake` Cargo features (both are in the
+> default/`full` build). If the CLI was built without them, the `[keywords]`
+> config block is silently ignored — `result.extracted_keywords` simply stays empty
+> rather than erroring. The `"yake"` algorithm needs `keywords-yake`; `"rake"`
+> needs `keywords-rake`.
+
+Enable via inline JSON on the CLI:
+
+```bash
+xberg extract paper.pdf --format json \
+  --config-json '{"keywords":{"algorithm":"yake","max_keywords":15,"language":"en"}}' \
+  | jq '.extracted_keywords'
+```
+
+Or in a config file:
+
+```toml
+[keywords]
+algorithm = "rake"       # "yake" or "rake"
+max_keywords = 10        # default 10
+min_score = 0.0          # filter below this score (normalized 0.0-1.0 for both algorithms)
+ngram_range = [1, 3]     # unigrams..trigrams (default); config-file only
+language = "en"          # stopword language; omit to skip stopword filtering
+```
+
+```bash
+xberg extract report.pdf --config xberg.toml --format json | jq '.extracted_keywords'
+```
+
+Field notes:
+
+- `max_keywords` caps how many keywords are returned (default 10).
+- `min_score` filters low-scoring keywords. Both YAKE and RAKE normalize
+  their scores to the `0.0`-`1.0` range with *higher-is-better*, so
+  `min_score` retains keywords with `score >= min_score` identically for
+  either algorithm.
+- `ngram_range` is `[min, max]`: `[1,1]` unigrams only, `[1,2]` adds
+  bigrams, `[1,3]` (default) adds trigrams. Config-file only — it is not a
+  field on the language bindings' `KeywordConfig`.
+- `language` enables stopword filtering for that language; omit it to
+  disable stopword filtering entirely.
+
+## Language detection
+
+Language detection is a real CLI flag: `--detect-language`. Detected
+languages appear on `result.detected_languages`:
+
+```bash
+xberg extract multilingual.pdf --detect-language true --format json \
+  | jq '.detected_languages'
+```
+
+In a config file it lives under `[language_detection]`:
+
+```toml
+[language_detection]
+enabled = true
+min_confidence = 0.8
+detect_multiple = false
+```
+
+The CLI flag enables detection with `min_confidence = 0.8` and
+single-language mode; use the config block to detect multiple languages or
+tune confidence.
+
+## Embeddings (`embed` command)
+
+The standalone `embed` command produces vector embeddings for text from
+`--text` (repeatable) or stdin. It does not run extraction — pipe
+extracted content in if you want document embeddings.
+
+```bash
+# Local ONNX preset model (default provider)
+xberg embed --text "first passage" --text "second passage" --preset balanced
+
+# Embed extracted document text
+xberg extract report.pdf | xberg embed --preset quality
+```
+
+Presets for the local provider: `fast`, `balanced` (default), `quality`,
+`multilingual`. Output defaults to JSON (`--format json`).
+
+`--provider` selects the embedding source:
+
+| Provider | Flag                                  | Notes                                         |
+| -------- | ------------------------------------- | --------------------------------------------- |
+| `local`  | `--preset <fast\|balanced\|quality\|multilingual>` | **Default.** ONNX model, no API key. |
+| `llm`    | `--model <id>` `--api-key <key>`      | liter-llm routing, e.g. `openai/text-embedding-3-small`. |
+| `plugin` | `--plugin <name>`                     | A backend pre-registered in-process via the plugin API. |
+
+```bash
+# Provider-hosted embeddings via an LLM
+xberg embed --text "query text" \
+  --provider llm --model openai/text-embedding-3-small --api-key "$OPENAI_API_KEY"
+```
+
+Local embedding presets must be downloaded first if not cached. Pre-warm
+them with the cache command:
+
+```bash
+xberg cache warm --embedding-model balanced   # one preset
+xberg cache warm --all-embeddings             # all available presets (currently 8)
+```
+
+## Programmatic access
+
+Keywords and detected languages live on the document in the result envelope:
+
+```python
+from xberg import ExtractInput, extract, ExtractionConfig, KeywordConfig, KeywordAlgorithm
+
+config = ExtractionConfig(
+    keywords=KeywordConfig(algorithm=KeywordAlgorithm.YAKE, max_keywords=15, language="en"),
+)
+result = await extract(ExtractInput(uri="paper.pdf"), config)
+doc = result.results[0]
+print(doc.extracted_keywords)   # extracted keywords (when enabled)
+print(doc.detected_languages)   # detected languages (when enabled)
+```
+
+See `references/python-api.md` and `references/configuration.md` in the
+sibling `xberg` skill for the keyword / language-detection config
+classes and the embedding presets.
+
+## Common pitfalls
+
+- **No `--keywords` flag** — keyword extraction is config-only. Use
+  `--config-json '{"keywords":{...}}'` or a `[keywords]` config block.
+- **`min_score` direction** — scores are normalized to `0.0`-`1.0` with
+  higher-is-better for both YAKE and RAKE, so the same threshold behaves
+  identically for either algorithm.
+- **Embeddings ≠ extraction** — `embed` only takes raw text. Pipe
+  `xberg extract` output into it for document vectors.
+- **Cold embedding models** — first local run downloads the preset; run
+  `xberg cache warm --all-embeddings` to pre-populate.
+
+See `references/advanced-features.md` for the embeddings pipeline and
+`references/cli-reference.md` for the `embed` and `cache warm` flag sets.

package/.opencode/skills/extracting-tables/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: extracting-tables
+description: Use when extracting tabular data from PDFs, spreadsheets, or images. Covers layout-aware table detection, table model selection, output formats (markdown / JSON cells), and known limits.
+---
+
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:7667a52a8674605a45cc61b67e7879a0104d5e86c0d82b4bde5ced9e6e3463a8
+Source-Hash: blake3:3fca38eb564d0ed9c9194d070fd8dec96de727edc92e82954cb4b9af52cddbaf
+Schema-Version: v1
+-->
+
+# Extracting tables
+
+Use this when the user wants structured tabular data — financial
+statements, scientific tables, invoices, spreadsheet-style PDFs. Xberg
+detects tables via a layout model (RT-DETR v2) and reconstructs cell
+structure with a configurable table model.
+
+## Basic usage
+
+```bash
+# Markdown tables embedded in the content stream
+xberg extract report.pdf --layout --content-format markdown
+
+# Structured JSON output, tables appear under result.tables
+xberg extract report.pdf --layout --format json
+```
+
+`--layout` turns on layout-aware extraction; without it, tables fall back
+to plain text reflow and you lose cell boundaries.
+
+## Output shapes
+
+Two surfaces, picked via `--format` (CLI shape) and `--content-format`
+(content rendering):
+
+- **Markdown tables in `content`** — `--content-format markdown`. Tables
+  appear inline as `| col | col |` blocks. Good for LLM ingestion.
+- **Structured `tables` array** — `--format json`. Each entry has
+  `cells[][]` (rows × cols), `markdown` (pre-rendered), `page_number`,
+  `bounding_box`. Use this when downstream code needs exact cell access.
+  (`bounding_box` is omitted when no position data is available.)
+
+Both are populated at once when `--layout` is on. The `tables` array is
+always structured; the `content` stream switches representation.
+
+```bash
+xberg extract financials.pdf --layout --format json \
+  | jq '.result.tables[] | {page: .page_number, rows: (.cells | length)}'
+```
+
+## Table models
+
+`--layout-table-model` picks the reconstruction backend:
+
+| Model              | Best for                                              | Notes                                       |
+| ------------------ | ----------------------------------------------------- | ------------------------------------------- |
+| `tatr`             | dense complex tables (academic, financial)            | **Default.** Heaviest, highest accuracy.    |
+| `slanet_auto`      | dispatches per-table to wired/wireless                | Good when table styles are mixed.           |
+| `slanet_wired`     | tables with visible borders                           | Faster than tatr.                           |
+| `slanet_wireless`  | tables without borders (whitespace-separated)         | For invoices, simple grids.                 |
+| `slanet_plus`      | hybrid wired / wireless                               | Lighter than `slanet_auto`.                 |
+| `disabled`         | layout detection only, no table structure             | Use to skip table model cost.               |
+
+```bash
+xberg extract bank-statement.pdf \
+  --layout --layout-table-model tatr --content-format markdown
+```
+
+Drop `--layout-confidence` when the layout model misses tables (default
+threshold ~0.5):
+
+```bash
+xberg extract noisy-scan.pdf --layout --layout-confidence 0.3
+```
+
+## Spreadsheets
+
+`.xlsx`, `.ods`, `.csv`, `.tsv` are extracted by dedicated parsers — no
+layout model needed. Each sheet becomes a markdown table (or structured
+table) automatically:
+
+```bash
+xberg extract workbook.xlsx --content-format markdown
+xberg extract data.csv --format json
+```
+
+Pass `--no-cache=true` only when iterating on the same file with different
+configs.
+
+## Config file alternative
+
+```toml
+# `output_format` in config files equals `--content-format` on the CLI.
+output_format = "markdown"
+
+[layout]
+confidence_threshold = 0.5
+table_model = "tatr"
+```
+
+Then:
+
+```bash
+xberg extract report.pdf --format json
+```
+
+## Programmatic access
+
+From Python, structured tables live on the document in the result envelope
+(`result.results[0].tables`):
+
+```python
+from xberg import ExtractInput, extract, ExtractionConfig, LayoutDetectionConfig
+
+config = ExtractionConfig(
+    layout=LayoutDetectionConfig(table_model="tatr"),
+    output_format="markdown",
+)
+result = await extract(ExtractInput(uri="report.pdf"), config)
+for table in result.results[0].tables:
+    print(table.markdown)        # rendered markdown
+    print(table.cells[0][0])     # cell access
+```
+
+Node.js mirrors this (`extract`, `output.results[0].tables`, camelCase fields).
+See `references/python-api.md` and `references/nodejs-api.md` in the
+sibling `xberg` skill for full type signatures.
+
+## Known limitations
+
+- **Merged cells** — reconstructed as repeated values across the spanned
+  region; the merge is not preserved as metadata.
+- **Rotated tables** — enable `--ocr-auto-rotate true` for image-based
+  PDFs before extraction.
+- **Nested tables** — flattened. Detection succeeds; structural nesting is
+  lost.
+- **Multi-page tables** — each page yields a separate `tables[]` entry.
+  Stitch by matching column headers if needed.
+- **ONNX Runtime required** — layout and table models are unavailable in
+  WASM builds and on the Android x86_64 emulator; native targets ship
+  full support.
+
+## Common failure modes
+
+- **Empty `tables` with `--layout` on** — confidence threshold too high or
+  table model mismatched. Drop `--layout-confidence` to 0.3, try
+  `--layout-table-model tatr`.
+- **Markdown tables look ragged** — switch `--layout-table-model` to
+  `slanet_wired` for bordered grids or `slanet_wireless` for invoices.
+- **Slow extraction** — `tatr` is heavy. Use `slanet_auto` or
+  `slanet_plus` as a default; reach for `tatr` only when accuracy matters.
+
+See `references/cli-reference.md` for the full layout flag set and
+`references/advanced-features.md` for the layout pipeline internals.

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

@@ -0,0 +1,130 @@
+---
+name: extracting-with-ocr
+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.
+---
+
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:3ec8b7cf60f56cbe5cc15a5a0b29d0c2f8e3cf4c3823503eb1128fb7f9ee11db
+Source-Hash: blake3:3fca38eb564d0ed9c9194d070fd8dec96de727edc92e82954cb4b9af52cddbaf
+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 (extract embedded text only or fail).
+- `--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` in the
+sibling `xberg` skill for the full flag and config schema.