@xberg-io/opencode-xberg 1.3.6 → 1.3.8

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

package/.pi/skills/picking-a-format/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: picking-a-format
+description: Use when choosing an output format for extracted documents — plain text, markdown, djot, HTML, JSON, or DocTags. Maps consumer (LLM, parser, archive) to the right `--format` / `--content-format` pair.
+---
+
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:bcdbffe958890e1c589f3ea44540c67c86540196a844e6de5c011faccdd345fc
+Source-Hash: blake3:3fca38eb564d0ed9c9194d070fd8dec96de727edc92e82954cb4b9af52cddbaf
+Schema-Version: v1
+-->
+
+# Picking a format
+
+Xberg has two orthogonal format knobs. Get them right up front and the
+downstream code stays simple.
+
+| Knob                | What it controls                                  | Values                                 | Default          |
+| ------------------- | ------------------------------------------------- | -------------------------------------- | ---------------- |
+| `--format`          | How the CLI prints the result                     | `text`, `json`, `toon`                 | `text` (`extract`), `json` (`batch`) |
+| `--content-format`  | How extracted content is rendered inside `result` | `plain`, `markdown`, `djot`, `html`, `json`, `doctags` | `plain`     |
+| `--token-reduction` | Strip whitespace / boilerplate for LLM contexts   | `off`, `light`, `moderate`, `aggressive`, `maximum` | `off`  |
+
+`--format json` returns an envelope wrapping the `ExtractedDocument` — the
+document lives under `.result` for `extract` and under `.results[]` for
+`batch`, with `content`, `metadata`, `tables`, and `images` as fields of
+that nested document. `--format text` prints just `content`.
+`--content-format` is what shows up inside that `content` field.
+
+## Decision tree
+
+```text
+Who consumes the output?
+├── LLM (Claude, GPT, Gemini, local) — embed/prompt context
+│       --format text --content-format markdown
+├── Vector store / RAG indexer
+│       --format json --content-format markdown
+│       (markdown preserves structure for chunking)
+├── Downstream parser that expects machine-readable JSON
+│       --format json --content-format plain
+│       (cleanest text + structured metadata)
+├── Human review / archival
+│       --format text --content-format markdown
+├── HTML re-rendering / web display
+│       --format json --content-format html
+├── Lossless intermediate for pandoc / academic tooling
+│       --format json --content-format djot
+└── Token-budget-constrained pipeline
+        --format text --content-format plain
+        (drops markup; add --token-reduction moderate for further savings)
+```
+
+## Examples
+
+Feed a PDF directly into an LLM:
+
+```bash
+xberg extract paper.pdf --content-format markdown
+```
+
+Index a corpus into a RAG store with tables and headings preserved:
+
+```bash
+xberg batch docs/*.pdf --format json --content-format markdown \
+  | jq -c '.results[] | {content: .content, tables: .tables}'
+```
+
+Strip a file to bare text for a token-tight summarizer:
+
+```bash
+xberg extract long.pdf \
+  --content-format plain \
+  --token-reduction moderate
+```
+
+Pull metadata only, ignore content:
+
+```bash
+xberg extract file.pdf --format json | jq '.result.metadata'
+```
+
+## When in doubt
+
+- **Default to `markdown`** as the content format. It is the best
+  compromise across LLMs, RAG, and human review, and Xberg has the
+  most faithful renderer for it.
+- Reach for `plain` only when downstream cannot tolerate any markup.
+- Reach for `djot` only if you're already in a djot/pandoc pipeline.
+- Reach for `html` only when re-rendering for the web.
+- Reach for `json` for a heading-driven content tree, or `doctags` for Docling-compatible output.
+
+## Token-reduction (orthogonal)
+
+`--token-reduction` collapses whitespace, strips repeated headers/footers,
+and trims boilerplate. It composes with any `--content-format`:
+
+- `off` (default), `light`, `moderate`, `aggressive`, `maximum`.
+
+Use `moderate` as a safe starting point for LLM context windows. `maximum`
+is lossy — verify before relying on it.
+
+See `references/cli-reference.md` for the full flag set and
+`references/configuration.md` for the equivalent `output_format` and
+`token_reduction` keys in `xberg.toml`.

package/.pi/skills/xberg/SKILL.md

@@ -0,0 +1,427 @@
+---
+name: xberg
+description: >-
+  Extract text, tables, metadata, and images from 107 document formats
+  (PDF, Office, images, HTML, email, archives, academic) using Xberg.
+  Use when writing code that calls Xberg APIs in Python, Node.js/TypeScript,
+  Rust, or CLI. Covers installation, extraction (sync/async), configuration
+  (OCR, chunking, output format), batch processing, error handling, and plugins.
+license: Elastic-2.0
+metadata:
+  author: xberg-io
+  version: "0.1.0"
+  repository: https://github.com/xberg-io/xberg
+---
+
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+Content-Hash: blake3:8d1ddd2c0fd7b6e9473737826178427138c3fac45cedd5b6c3d0b8a243739deb
+Source-Hash: blake3:3fca38eb564d0ed9c9194d070fd8dec96de727edc92e82954cb4b9af52cddbaf
+Schema-Version: v1
+-->
+
+# Xberg Document Extraction
+
+Xberg is a document intelligence library with a Rust core and bindings for Python, TypeScript/Node.js, Ruby, PHP, Go, Java, C#, Elixir, WebAssembly, Dart, Kotlin Android, Swift, Zig, and C. It extracts text, tables, metadata, and images from 107 formats across 140 unique file extensions and accepts 53 compatibility MIME aliases, including PDF, Office documents, images, HTML, email, archives, and academic formats.
+
+Use this skill when writing code that:
+
+- Extracts text or metadata from documents
+- Performs OCR on scanned documents or images
+- Batch-processes multiple files
+- Configures extraction options (output format, chunking, OCR, language detection)
+- Implements custom plugins (post-processors, validators, OCR backends)
+
+> If the `xberg` MCP server is registered in this session, prefer its tools over shelling out to the CLI — they expose the same extraction surface with structured arguments and results.
+
+## Installation
+
+### Python
+
+```bash
+pip install xberg
+```
+
+### Node.js
+
+```bash
+npm install @xberg-io/xberg
+```
+
+### Rust
+
+```bash
+cargo add xberg
+```
+
+```toml
+# Cargo.toml
+[dependencies]
+xberg = { version = "1.1.0", features = ["full"] }
+tokio = { version = "1", features = ["full"] }
+# feature flags: pdf, ocr, chunking, embeddings, language-detection, keywords, api, mcp
+#                (or "formats" / "full" aggregates); tokio-runtime is on by default
+```
+
+### CLI
+
+```bash
+brew install xberg-io/tap/xberg
+# or run without a persistent install (the CLI proxy package self-installs the binary):
+npx @xberg-io/xberg-cli --help
+uvx --from xberg-cli xberg --help
+# or download a prebuilt binary from the latest GitHub release:
+#   https://github.com/xberg-io/xberg/releases/latest
+# or build from source:
+cargo install xberg-cli
+```
+
+## Quick Start
+
+The library entry points are `extract(input, config)` and `extract_batch(inputs, config)`. Both return an `ExtractionResult` **envelope** — the extracted document(s) live in `result.results`, and per-document data (`content`, `tables`, `metadata`, …) is on each `result.results[i]`. Python and Node are async-only.
+
+### Python
+
+```python
+import asyncio
+from xberg import ExtractInput, extract, ExtractionConfig
+
+async def main() -> None:
+    result = await extract(ExtractInput(uri="document.pdf"), ExtractionConfig())
+    doc = result.results[0]
+    print(doc.content)    # extracted text
+    print(doc.metadata)   # document metadata
+    print(doc.tables)     # extracted tables
+
+asyncio.run(main())
+```
+
+### Node.js
+
+```typescript
+import { extract } from "@xberg-io/xberg";
+
+const output = await extract({ kind: "uri", uri: "document.pdf" });
+const doc = output.results[0];
+console.log(doc.content);
+console.log(doc.metadata);
+console.log(doc.tables);
+```
+
+### Rust
+
+```rust
+use xberg::{extract, ExtractInput, ExtractionConfig};
+
+#[tokio::main]
+async fn main() -> xberg::Result<()> {
+    let output = extract(ExtractInput::from_uri("document.pdf"), &ExtractionConfig::default()).await?;
+    println!("{}", output.results[0].content);
+    Ok(())
+}
+```
+
+### CLI
+
+```bash
+xberg extract document.pdf
+xberg extract document.pdf --format json
+xberg extract document.pdf --content-format markdown
+```
+
+## Configuration
+
+All languages use the same configuration structure with language-appropriate naming conventions.
+
+### Python (snake_case)
+
+```python
+from xberg import (
+    ExtractInput, extract,
+    ExtractionConfig, OcrConfig, TesseractConfig, PdfConfig, ChunkingConfig, OutputFormat,
+)
+
+config = ExtractionConfig(
+    ocr=OcrConfig(
+        backend="tesseract",
+        language=["eng"],
+        tesseract_config=TesseractConfig(psm=6, enable_table_detection=True),
+    ),
+    pdf_options=PdfConfig(passwords=["secret123"]),
+    chunking=ChunkingConfig(max_characters=1000, overlap=200),
+    output_format=OutputFormat("markdown"),
+)
+
+result = await extract(ExtractInput(uri="document.pdf"), config)
+```
+
+### Node.js (camelCase)
+
+```typescript
+import { extract, type ExtractionConfig } from "@xberg-io/xberg";
+
+const config: ExtractionConfig = {
+  ocr: { backend: "tesseract", language: ["eng"] },
+  pdfOptions: { passwords: ["secret123"] },
+  chunking: { maxCharacters: 1000, overlap: 200 },
+  outputFormat: "markdown",
+};
+
+const output = await extract({ kind: "uri", uri: "document.pdf" }, config);
+```
+
+### Rust (snake_case)
+
+```rust
+use xberg::{extract, ExtractInput, ExtractionConfig, OcrConfig, ChunkingConfig, OutputFormat};
+
+let config = ExtractionConfig {
+    ocr: Some(OcrConfig {
+        backend: "tesseract".into(),
+        language: vec!["eng".to_string()],
+        ..Default::default()
+    }),
+    chunking: Some(ChunkingConfig {
+        max_characters: 1000,
+        overlap: 200,
+        ..Default::default()
+    }),
+    output_format: OutputFormat::Markdown,
+    ..Default::default()
+};
+
+let output = extract(ExtractInput::from_uri("document.pdf"), &config).await?;
+```
+
+### Config File (TOML)
+
+```toml
+output_format = "markdown"
+
+[ocr]
+backend = "tesseract"
+language = "eng"
+
+[chunking]
+max_characters = 1000
+overlap = 200
+
+[pdf_options]
+passwords = ["secret123"]
+```
+
+```bash
+# CLI: auto-discovers xberg.toml/yaml/yml/json in current/parent directories
+xberg extract doc.pdf
+# or explicit:
+xberg extract doc.pdf --config xberg.toml
+xberg extract doc.pdf --config-json '{"ocr":{"backend":"tesseract","language":"deu"}}'
+```
+
+## Batch Processing
+
+`extract_batch` takes a list of `ExtractInput`s and returns one envelope whose `results` array holds a document per input (in input order); per-input failures are reported in `result.errors`.
+
+### Python
+
+```python
+from xberg import ExtractInput, extract_batch, ExtractionConfig
+
+inputs = [
+    ExtractInput(uri="doc1.pdf"),
+    ExtractInput(uri="doc2.docx"),
+    ExtractInput(uri="doc3.xlsx"),
+]
+output = await extract_batch(inputs, ExtractionConfig())
+
+for doc in output.results:
+    print(f"{len(doc.content)} chars extracted")
+```
+
+### Node.js
+
+```typescript
+import { extractBatch } from "@xberg-io/xberg";
+
+const output = await extractBatch([
+  { kind: "uri", uri: "doc1.pdf" },
+  { kind: "uri", uri: "doc2.docx" },
+]);
+for (const doc of output.results) {
+  console.log(`${doc.content.length} chars`);
+}
+```
+
+### Rust
+
+```rust
+use xberg::{extract_batch, ExtractInput, ExtractionConfig};
+
+let config = ExtractionConfig::default();
+let inputs = vec![ExtractInput::from_uri("doc1.pdf"), ExtractInput::from_uri("doc2.docx")];
+let output = extract_batch(inputs, &config).await?;
+```
+
+### CLI
+
+```bash
+xberg batch *.pdf --format json
+xberg batch docs/*.docx --content-format markdown
+```
+
+## OCR
+
+OCR runs automatically for images and scanned PDFs. Tesseract is the default backend (native binding, no external install required).
+
+### Backends
+
+Select with `OcrConfig.backend`:
+
+- **tesseract** (default): built-in native binding. All Tesseract languages supported.
+- **paddleocr** (`"paddleocr"` / `"paddle-ocr"`): ONNX-based PaddleOCR.
+- **vlm**: Vision-Language-Model OCR (configure via `OcrConfig.vlm_config`).
+
+Custom backends can be registered in Python/Node via `register_ocr_backend` (see [Advanced Features](references/advanced-features.md)).
+
+### Language Codes
+
+```python
+config = ExtractionConfig(ocr=OcrConfig(language=["eng"]))          # English
+config = ExtractionConfig(ocr=OcrConfig(language=["eng", "deu"]))   # Multiple
+# The single-string shorthand ("eng+deu") is only accepted in config files / --config-json,
+# not in the OcrConfig constructor (Python takes a list, Node takes an array).
+```
+
+### Force OCR
+
+```python
+config = ExtractionConfig(force_ocr=True)  # OCR even if text is extractable
+```
+
+## Result Envelope and Document Fields
+
+`extract` / `extract_batch` return an `ExtractionResult` envelope: `results` (list of documents), `errors` (per-input failures), and `summary` (counts). Per-document fields live on each document in `results` — bind `doc = result.results[0]` (Python/Node) or `&output.results[0]` (Rust) first.
+
+| Field        | Python (`doc.`)        | Node.js (`doc.`)      | Rust (`document.`)      | Description                                   |
+| ------------ | ---------------------- | --------------------- | ----------------------- | --------------------------------------------- |
+| Text content | `content`              | `content`             | `content`               | Extracted text (str/String)                   |
+| MIME type    | `mime_type`            | `mimeType`            | `mime_type`             | Input document MIME type                      |
+| Metadata     | `metadata`             | `metadata`            | `metadata`              | Document metadata (flat mapping)              |
+| Tables       | `tables`               | `tables`              | `tables`                | Extracted tables with cells + markdown        |
+| Languages    | `detected_languages`   | `detectedLanguages`   | `detected_languages`    | Detected languages (if enabled)               |
+| Chunks       | `chunks`               | `chunks`              | `chunks`                | Text chunks (if chunking enabled)             |
+| Images       | `images`               | `images`             | `images`                | Extracted images (if enabled)                 |
+| Elements     | `elements`             | `elements`            | `elements`              | Semantic elements (if element_based format)   |
+| Pages        | `pages`                | `pages`               | `pages`                 | Per-page content (if page extraction enabled) |
+| Keywords     | `extracted_keywords`   | `extractedKeywords`   | `extracted_keywords`    | Extracted keywords (if enabled)               |
+
+## Error Handling
+
+### Python
+
+`extract` / `extract_batch` raise a plain `RuntimeError` on failure — the typed `XbergError` subclasses are not raised by these entry points, so catch `RuntimeError`. Per-input failures during `extract_batch` are reported non-fatally in `result.errors`.
+
+```python
+from xberg import ExtractInput, extract, ExtractionConfig
+
+try:
+    result = await extract(ExtractInput(uri="file.pdf"), ExtractionConfig())
+    for err in result.errors:
+        print(f"Per-input error: {err}")
+except RuntimeError as e:
+    print(f"Extraction failed: {e}")
+```
+
+### Node.js
+
+The Node binding throws plain `Error` objects (it does not export typed error subclasses). Catch with `instanceof Error`, and inspect `output.errors` for non-fatal per-input failures.
+
+```typescript
+import { extract } from "@xberg-io/xberg";
+
+try {
+  const output = await extract({ kind: "uri", uri: "file.pdf" });
+  if (output.errors.length > 0) {
+    console.error("Per-input errors:", output.errors);
+  }
+} catch (e) {
+  if (e instanceof Error) {
+    console.error(`Extraction failed: ${e.message}`);
+  }
+}
+```
+
+### Rust
+
+```rust
+use xberg::{extract, ExtractInput, ExtractionConfig, XbergError};
+
+let config = ExtractionConfig::default();
+match extract(ExtractInput::from_uri("file.pdf"), &config).await {
+    Ok(output) => println!("{}", output.results[0].content),
+    Err(XbergError::Parsing { message, .. }) => eprintln!("Parse error: {message}"),
+    Err(XbergError::Ocr { message, .. }) => eprintln!("OCR error: {message}"),
+    Err(XbergError::UnsupportedFormat(mime)) => eprintln!("Unsupported: {mime}"),
+    Err(e) => eprintln!("Error: {e}"),
+}
+```
+
+## Common Pitfalls
+
+1. **Result is an envelope**: `extract` / `extract_batch` return `ExtractionResult` with `results`, `errors`, and `summary`. Per-document fields (`content`, `tables`, `chunks`, …) are on `result.results[i]`, NOT on the top-level return.
+2. **Async-only**: Python and Node have no sync variants — always `await extract(...)`. Rust `extract` is async; use `#[tokio::main]` or an async context.
+3. **Build the input**: pass an `ExtractInput`, not a bare path. Use `ExtractInput(uri=...)` / `ExtractInput::from_uri(...)` (Python/Rust) or `{ kind: "uri", uri: "..." }` (Node); for bytes use `kind="bytes"` with `bytes`/`mime_type`.
+4. **Python ChunkingConfig fields**: construct with `max_characters` and `overlap` (defaults 1000 / 200); these are also the readable attributes. When passing config as a dict/JSON, the `max_chars` / `max_overlap` aliases are also accepted. Node uses `maxCharacters` / `overlap`; Rust struct fields are `max_characters` / `overlap`.
+5. **Python errors**: `extract` / `extract_batch` raise a plain `RuntimeError` on failure, not typed `XbergError` subclasses — catch `RuntimeError`. Node throws plain `Error` (no typed error subclasses).
+6. **Rust extract signature**: `extract(input, &config)` — the config is a reference. Use `&ExtractionConfig::default()` for defaults.
+7. **CLI --format vs --content-format**: `--format` controls CLI output (`text`, `json`, or `toon`). `--content-format` controls content rendering (`plain`, `markdown`, `djot`, `html`, `json`, or `doctags`).
+8. **Config file field names**: Use snake_case in TOML/YAML/JSON config files — `[chunking]` fields are `max_characters` and `overlap`; other fields use names like `output_format`, `pdf_options`.
+
+## Supported Formats (Summary)
+
+| Category          | Extensions                                                                                                                                                  |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **PDF**           | `.pdf`                                                                                                                                                      |
+| **Word**          | `.docx`, `.docm`, `.doc`, `.dotx`, `.dotm`, `.dot`, `.odt`, `.pages`, `.wpd`, `.wp`, `.wp5`, `.wp6`, `.hwp`, `.hwpx`                                       |
+| **Spreadsheets**  | `.xlsx`, `.xlsm`, `.xlsb`, `.xls`, `.xla`, `.xlam`, `.xltm`, `.xltx`, `.xlt`, `.ods`, `.numbers`                                                            |
+| **Presentations** | `.pptx`, `.pptm`, `.ppt`, `.pps`, `.ppsx`, `.potx`, `.potm`, `.pot`, `.odp`, `.key`                                                                         |
+| **eBooks**        | `.epub`, `.fb2`                                                                                                                                             |
+| **Images**        | `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.bmp`, `.tiff`, `.tif`, `.jp2`, `.jpg2`, `.j2c`, `.j2k`, `.jpc`, `.jbig2`, `.jb2`, `.pnm`, `.pbm`, `.pgm`, `.ppm`, `.heic`, `.heics`, `.heif`, `.heifs`, `.hif`, `.avif`, `.avcs`, `.svg` |
+| **Markup**        | `.html`, `.htm`, `.xhtml`, `.xht`, `.xml`, `.kml`                                                                                                           |
+| **Data**          | `.json`, `.geojson`, `.jsonl`, `.ndjson`, `.yaml`, `.yml`, `.toml`, `.csv`, `.tsv`, `.dbf`, `.sqlite`, `.sqlite3`, `.db`, `.gpkg`, `.gpkx`                  |
+| **Text**          | `.txt`, `.adoc`, `.asciidoc`, `.vtt`, `.md`, `.markdown`, `.commonmark`, `.qmd`, `.rmd`, `.mdx`, `.djot`, `.dj`, `.doctags`, `.rst`, `.org`, `.rtf`       |
+| **Email**         | `.eml`, `.msg`, `.pst`                                                                                                                                      |
+| **Archives**      | `.zip`, `.tar`, `.tgz`, `.gz`, `.7z`                                                                                                                        |
+| **Audio/Video**   | `.mp3`, `.mpga`, `.m4a`, `.wav`, `.webm`, `.mp4`, `.mpg4`, `.mp4v`, `.m4v`, `.mpeg`, `.mpg`, `.mpe`, `.m1v`, `.m2v`                                     |
+| **Academic**      | `.bib`, `.ris`, `.nbib`, `.enw`, `.tex`, `.latex`, `.typ`, `.typst`, `.jats`, `.nxml`, `.ipynb`, `.docbook`, `.dbk`, `.docbook4`, `.docbook5`, `.opml`      |
+
+CSL JSON is supported through an explicit MIME type but does not have a registered file extension.
+
+See [references/supported-formats.md](references/supported-formats.md) for the complete format reference with MIME types.
+
+## Additional Resources
+
+Detailed reference files for specific topics:
+
+- **[Python API Reference](references/python-api.md)** — All functions, config classes, plugin protocols, exact signatures
+- **[Node.js API Reference](references/nodejs-api.md)** — All functions, TypeScript interfaces, worker pool APIs
+- **[Rust API Reference](references/rust-api.md)** — All functions with feature gates, structs, Cargo.toml examples
+- **[CLI Reference](references/cli-reference.md)** — All commands, flags, config precedence, exit codes
+- **[Configuration Reference](references/configuration.md)** — TOML/YAML/JSON formats, auto-discovery, env vars, full schema
+- **[Supported Formats](references/supported-formats.md)** — Format families, extensions, capabilities, and authoritative discovery commands
+- **[Advanced Features](references/advanced-features.md)** — Plugins, embeddings, MCP server, API server, security limits
+- **[Other Language Bindings](references/other-bindings.md)** — Go, Ruby, Java, C#, PHP, Elixir, WASM, Dart, Kotlin Android, Swift, Zig, C, and Docker
+
+## Related skills
+
+Task-focused sibling skills go deeper than this overview:
+
+- **extracting-with-ocr** — OCR backends, language packs, force-OCR, tuning.
+- **extracting-tables** — layout-aware table detection and table models.
+- **chunking** — chunk size/overlap, markdown/yaml/semantic chunkers, the `chunk` command.
+- **extracting-keywords** — YAKE/RAKE keywords, language detection, the `embed` command.
+- **batch-extraction** — the `batch` command, `--file-configs`, parallelism, error recovery.
+- **picking-a-format** — choosing `--format` / `--content-format` per consumer.
+
+Full documentation: <https://docs.xberg.io>
+GitHub: <https://github.com/xberg-io/xberg>