@xberg-io/opencode-xberg 1.3.7 → 1.3.8

package/.pi/prompts/xberg-ocr.md

@@ -0,0 +1,14 @@
+---
+description: Extract scanned documents with OCR
+---
+
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:1715ebd3d000212eb2e4dbfa814d6d5990bcc0c636bae67734a503f2c3ae8be4
+Source-Hash: blake3:3fca38eb564d0ed9c9194d070fd8dec96de727edc92e82954cb4b9af52cddbaf
+Schema-Version: v1
+-->
+
+OCR this document: $ARGUMENTS
+
+Read the extracting-with-ocr skill. Confirm the document needs OCR and language packs are installed. Use `xberg extract <file> --force-ocr=true` when forced OCR is appropriate. Preserve paths as separate arguments and report OCR failures.

package/.pi/skills/batch-extraction/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: batch-extraction
+description: Use when extracting from many files at once with shared config, bounded parallelism, per-file overrides, and error recovery. Covers the `batch` command, `--file-configs`, `--max-concurrent`, and output layout.
+---
+
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:3a70b47dd77fcd3f37e83bed3d32b1ad1ea9d6c1642ae8e0ff7b09b55939858a
+Source-Hash: blake3:3fca38eb564d0ed9c9194d070fd8dec96de727edc92e82954cb4b9af52cddbaf
+Schema-Version: v1
+-->
+
+# Batch extraction
+
+Use this when processing a directory or glob of documents in one pass.
+`xberg batch` shares one extraction config across every file, runs
+extractions concurrently, and returns one structured array — failures on
+individual files do not abort the run.
+
+## Basic usage
+
+```bash
+# Glob expands to many paths; results come back as a JSON array (default)
+xberg batch *.pdf
+
+# Mixed formats, markdown content for LLM ingestion
+xberg batch docs/*.docx --content-format markdown
+
+# Recurse with the shell, then extract
+xberg batch $(find ./corpus -name '*.pdf')
+```
+
+`batch` defaults to `--format json` (vs `--format text` for single
+`extract`). Each array entry is a full extraction result, so downstream
+code can index by position into the input path list.
+
+```bash
+xberg batch reports/*.pdf \
+  | jq '.[] | {chars: (.content | length), mime: .mime_type}'
+```
+
+## Parallelism
+
+`--max-concurrent` caps how many files extract at once. When omitted, the scheduler derives document concurrency from the total thread budget. Lower it on memory-constrained hosts or when OCR/ML
+models are active, since each in-flight extraction holds its own buffers.
+Layout-heavy batches are further limited (1 concurrent extraction for
+all-PDF-layout batches, 2 for mixed layout):
+
+```bash
+# Cap at 4 concurrent extractions
+xberg batch scans/*.pdf --ocr true --max-concurrent 4
+```
+
+`--max-threads` additionally caps *total* internal threads (Rayon, ONNX
+intra-op, the batch semaphore) for tightly constrained environments:
+
+```bash
+xberg batch *.pdf --max-concurrent 2 --max-threads 4
+```
+
+## Per-file config overrides
+
+A single shared config does not always fit. `--file-configs` points at a
+JSON file mapping each path to its own override object, merged on top of
+the shared config for that file only:
+
+```json
+{
+  "scan.pdf": { "force_ocr": true },
+  "report.pdf": { "output_format": "markdown" },
+  "data.xlsx": { "output_format": "json" }
+}
+```
+
+```bash
+xberg batch scan.pdf report.pdf data.xlsx --file-configs overrides.json
+```
+
+Keys are file paths (matching the paths passed on the command line);
+values are per-file extraction config objects in snake_case, the same
+shape as a config file.
+
+## Output layout
+
+For text/toon output with image extraction, `--output-dir` controls where
+referenced image files (e.g. `image_0.png`) are written; the directory
+must already exist. JSON output embeds image bytes inline and ignores
+`--output-dir`.
+
+```bash
+mkdir -p out/images
+xberg batch slides/*.pptx --extract-images true --output-dir out/images --format text
+```
+
+## Error recovery
+
+Batch extraction is fault-tolerant per file: one unreadable or corrupt
+document does not stop the rest. Inspect results for partial content and
+surfaced errors rather than relying on the process exit code alone. Pair
+with `--max-concurrent` to avoid exhausting memory when a few large files
+sit in a big batch.
+
+## Shared config
+
+Every `extract` flag also applies to `batch` (OCR, chunking, layout,
+content format, etc.) and is shared across all files unless a
+`--file-configs` entry overrides it:
+
+```bash
+xberg batch invoices/*.pdf \
+  --layout --layout-table-model slanet_wireless \
+  --content-format markdown --max-concurrent 8
+```
+
+A config file works too and auto-discovers from the cwd upward:
+
+```toml
+output_format = "markdown"
+
+[ocr]
+backend = "tesseract"
+language = "eng"
+```
+
+```bash
+xberg batch corpus/*.pdf --config xberg.toml
+```
+
+## Programmatic access
+
+From Python, `extract_batch` takes a list of `ExtractInput`s and returns one
+envelope whose `results` array holds a document per input:
+
+```python
+from xberg import ExtractInput, extract_batch, ExtractionConfig
+
+config = ExtractionConfig(output_format="markdown")
+
+inputs = [ExtractInput(uri=p) for p in ["a.pdf", "b.docx", "c.xlsx"]]
+output = await extract_batch(inputs, config)
+
+for doc in output.results:
+    print(len(doc.content))
+```
+
+Per-input overrides go on `ExtractInput.config` (a `FileExtractionConfig`).
+Node.js mirrors this with `extractBatch`; Rust uses `extract_batch(inputs, &config)`.
+See `references/python-api.md`, `references/nodejs-api.md`, and
+`references/rust-api.md` in the sibling `xberg` skill.
+
+## MCP
+
+When the `xberg` MCP server is registered, prefer the
+`extract_batch` tool over shelling out — it takes an array of input objects
+and a config object and returns structured results directly.
+
+## Common pitfalls
+
+- **Default format differs** — `batch` defaults to `--format json`,
+  `extract` to `--format text`. Set `--format` explicitly if a script
+  depends on one shape.
+- **`--output-dir` must exist** — the CLI does not create it.
+- **Memory blowups** — large batches with OCR/layout active may need an explicit
+  `--max-concurrent` ceiling.
+- **`--file-configs` path keys** — must match the paths as passed on the
+  command line, not absolute-resolved variants.
+
+See `references/cli-reference.md` for the full `batch` flag set.

package/.pi/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/.pi/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/.pi/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.