@xberg-io/opencode-xberg 1.3.11 → 1.4.0

package/.opencode/ai-rulez-content.js

@@ -1,6 +1,6 @@
 // AI-RULEZ :: GENERATED FILE — DO NOT EDIT
 // Content-Hash: blake3:011ec20caa671eb4bd4e886b09e15f720a786de4bf747419efd0690889fc5549
-// Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+// Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 // Schema-Version: v1
 
 // Generated by ai-rulez. Registers the skills, commands, agents, and MCP servers bundled with

package/.opencode/commands/xberg-extract.md

@@ -5,7 +5,7 @@ description: Extract a document locally with Xberg
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
 Content-Hash: blake3:3d695d0525269a1935328e6568418a562cac9ba7a64c6e8121d5136dc93b36e3
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 

package/.opencode/commands/xberg-ocr.md

@@ -5,7 +5,7 @@ description: Extract scanned documents with OCR
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
 Content-Hash: blake3:1715ebd3d000212eb2e4dbfa814d6d5990bcc0c636bae67734a503f2c3ae8be4
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 

package/.opencode/plugins/xberg.js

@@ -1,6 +1,6 @@
 // AI-RULEZ :: GENERATED FILE — DO NOT EDIT
 // Content-Hash: blake3:3fe1a33d721dfa8b49134cbe88659999cf9e481c558eb8e4b5ac81bc672c88db
-// Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+// Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 // Schema-Version: v1
 
 import { spawn } from "node:child_process";

package/.opencode/skills/xberg/SKILL.md

@@ -10,8 +10,8 @@ name: xberg
 
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
-Content-Hash: blake3:5c39696cf46f9dabada4de547cf7b610394f57c4002ed5d2055fc83521fa3141
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Content-Hash: blake3:bdb659ec3959943d7e4b8da0cc3b8fbe51dc3bfec07e27dbbd8f84e190a63e1a
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 
@@ -314,16 +314,16 @@ config = ExtractionConfig(force_ocr=True)  # OCR even if text is extractable
 
 ### 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`.
+`extract` / `extract_batch` raise an exported `XbergError` subclass, such as `ParsingError`, `SecurityError`, or `ValidationError`, including calls with `on_progress`. Catch `XbergError` for extraction failures. Per-input failures during `extract_batch` are reported non-fatally in `result.errors`.
 
 ```python
-from xberg import ExtractInput, extract, ExtractionConfig
+from xberg import ExtractInput, extract, ExtractionConfig, XbergError
 
 try:
     result = await extract(ExtractInput(uri="file.pdf"), ExtractionConfig())
     for err in result.errors:
         print(f"Per-input error: {err}")
-except RuntimeError as e:
+except XbergError as e:
     print(f"Extraction failed: {e}")
 ```
 
@@ -367,7 +367,7 @@ match extract(ExtractInput::from_uri("file.pdf"), &config).await {
 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).
+5. **Python errors**: catch `XbergError` or a specific exported subclass for `extract` / `extract_batch` failures, including calls with `on_progress`. 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`.

package/.opencode/skills/xberg/index.md

@@ -1,10 +1,10 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
-Content-Hash: blake3:995528a20ef3610c2da46cc63052bc232907509eca3477ba3e2decb42fba0146
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Content-Hash: blake3:03f23e46ea452f0a341ed6552d505e85c4d31333aea0862be9ff0774b399c82d
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 
 # Concepts
 
-* [Xberg](SKILL.md) - 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.
+- [Xberg](SKILL.md) - 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.

package/.opencode/skills/xberg/references/advanced-features.md

@@ -1,7 +1,7 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
 Content-Hash: blake3:353a7a05cbe84a2af1d053c8173d2154f418972a2bbfc2846dbb2c17a8a46197
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 

package/.opencode/skills/xberg/references/cli-reference.md

@@ -1,7 +1,7 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
-Content-Hash: blake3:b9281b07af57a10b362019da24d8545036e83015038e2f5902bfe167f165ecec
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Content-Hash: blake3:70bcb43e649e885bb822d41efb7221b365fd6f1870d1e6a5bb4ab3ec10be6acc
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 
@@ -11,11 +11,13 @@ Comprehensive command-line interface for the Xberg document intelligence library
 
 ## Installation
 
+The pinned command below follows this source release (1.4.0); use it once that release is published.
+
 ```bash
 brew install xberg-io/tap/xberg
 # or run without a persistent install (self-installs the binary):
 npx @xberg-io/xberg-cli --help
-uvx --from xberg-cli xberg --help
+uvx --from xberg-cli==1.4.0 xberg --help
 ```
 
 Or download a pre-built binary from the [latest GitHub Release](https://github.com/xberg-io/xberg/releases/latest), or build from source:

package/.opencode/skills/xberg/references/configuration.md

@@ -1,7 +1,7 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
-Content-Hash: blake3:025df7e4b6c9e1dd2a98b81236a46d427816da719521512e3b03bc2ae15ae065
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Content-Hash: blake3:d9846749cb2b57685af6f077cfe2d16d5d7e58768437f14ee12f3c78a260106e
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 
@@ -115,7 +115,7 @@ Nested sections (each `None`/unset by default unless noted): `ocr`, `xberg-chunk
 enabled = true
 backend = "tesseract"
 language = ["eng"]
-auto_rotate = false
+auto_rotate = true
 ```
 
 | Option         | Type             | Default     | Description                                                            |
@@ -123,7 +123,7 @@ auto_rotate = false
 | `enabled`      | boolean          | `true`      | Whether OCR is enabled. Setting `false` is equivalent to `disable_ocr` |
 | `backend`      | string           | `"tesseract"` | OCR backend: `tesseract`, `paddleocr`/`paddle-ocr`, or `vlm`         |
 | `language`     | string or array  | `["eng"]`   | Language code(s). Accepts `"eng"` or `["eng", "deu"]`. Tesseract joins with `+` |
-| `auto_rotate`  | boolean          | `false`     | Enable automatic page rotation based on orientation detection         |
+| `auto_rotate`  | boolean \| null  | `null`      | `true` always rotates, `false` never rotates or retries, unset keeps the orientation retry |
 | `vlm_fallback` | string           | `"disabled"` | VLM fallback policy                                                   |
 | `output_format`| string \| null   | `null`      | Optional OCR output format override                                    |
 

package/.opencode/skills/xberg/references/nodejs-api.md

@@ -1,7 +1,7 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
 Content-Hash: blake3:5dd1dce4a7814ed37c2ea273dda3dd60d7caa18b08b0aff933ce3a8f7717d1a6
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 

package/.opencode/skills/xberg/references/other-bindings.md

@@ -1,7 +1,7 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
 Content-Hash: blake3:dacb4d7def21681b8b237603d2c7b89beaf18b8ee4110175b6ea5593022f3229
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 

package/.opencode/skills/xberg/references/python-api.md

@@ -1,7 +1,7 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
-Content-Hash: blake3:723cd2abd915f92766e2dec9c90922b94ef60ad5ce81c606bd680b055e5c4717
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Content-Hash: blake3:9250a30997ec851cbb228ddcfd1f538e81e843f81e488e5f3d927ba94af93e4f
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 
@@ -485,7 +485,7 @@ for table in result.results[0].tables:
 
 ## Error Classes
 
-The errors raised by `extract()` and `extract_batch()` are plain `RuntimeError` — the typed exception classes below are **not** raised by these entry points, so catch `RuntimeError` (or `Exception`) around an `extract()`/`extract_batch()` call.
+`extract()` and `extract_batch()` raise the exported exception subclass for the underlying Rust error kind, including calls with `on_progress`. Catch `XbergError` for extraction failures, or a specific subclass such as `ParsingError`, `SecurityError`, or `ValidationError`.
 
 Xberg also defines a family of typed exception classes re-exported from `xberg`. The `XbergError`-rooted ones inherit from `XbergError` (base): `ParsingError`, `OcrError`, `ValidationError`, `MissingDependencyError`, `UnsupportedFormatError`, `CacheError`, `ImageProcessingError`, `SerializationError`, `PluginError`, `SecurityError`, `TranscriptionError`, `EmbeddingError`, `RerankingError`, `XbergTimeoutError`, `IoError`, and others. A few classes sit in separate hierarchies rooted at `Exception` rather than `XbergError` — e.g. `ConfigError`/`PdfAnalysisError` and `ParseError`/`SchemaValidationError`.
 
@@ -493,12 +493,12 @@ Xberg also defines a family of typed exception classes re-exported from `xberg`.
 
 ```python
 import asyncio
-from xberg import ExtractInput, extract, ExtractionConfig
+from xberg import ExtractInput, extract, ExtractionConfig, XbergError
 
 async def main() -> None:
     try:
         result = await extract(ExtractInput(uri="document.pdf"), ExtractionConfig())
-    except RuntimeError as e:
+    except XbergError as e:
         print(f"Extraction failed: {e}")
 
 asyncio.run(main())

package/.opencode/skills/xberg/references/rust-api.md

@@ -1,7 +1,7 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
 Content-Hash: blake3:a257c85add0ba02dd9ab63eecac13348152038919a09ba99964261256acf4ee4
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 

package/.opencode/skills/xberg/references/supported-formats.md

@@ -1,7 +1,7 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
 Content-Hash: blake3:e3c1dcb34a4784efc4f7fd868468061c3bd49d41e7e39792086633dcfe029d63
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 

package/.opencode/skills/xberg-batch-extraction/SKILL.md

@@ -6,7 +6,7 @@ name: xberg-batch-extraction
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
 Content-Hash: blake3:324433f2b10c7c9cdc1c06b98c1e427c8cb0ca9ccf034d336e28d49706add520
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 

package/.opencode/skills/xberg-batch-extraction/index.md

@@ -1,10 +1,10 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
-Content-Hash: blake3:16520a5ae77366107136a609dfa4d2479fdc16bc276035e0fef00ae71cfc13ca
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Content-Hash: blake3:3aac352725eacf5cb70a1f994f0a1d4b51eb2f4f30872b388f66d7d47e18c5f2
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 
 # Concepts
 
-* [Batch Extraction](SKILL.md) - 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.
+- [Batch Extraction](SKILL.md) - 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.

package/.opencode/skills/xberg-batch-extraction/references/advanced-features.md

@@ -1,7 +1,7 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
 Content-Hash: blake3:353a7a05cbe84a2af1d053c8173d2154f418972a2bbfc2846dbb2c17a8a46197
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 

package/.opencode/skills/xberg-batch-extraction/references/cli-reference.md

@@ -1,7 +1,7 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
-Content-Hash: blake3:b9281b07af57a10b362019da24d8545036e83015038e2f5902bfe167f165ecec
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Content-Hash: blake3:70bcb43e649e885bb822d41efb7221b365fd6f1870d1e6a5bb4ab3ec10be6acc
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 
@@ -11,11 +11,13 @@ Comprehensive command-line interface for the Xberg document intelligence library
 
 ## Installation
 
+The pinned command below follows this source release (1.4.0); use it once that release is published.
+
 ```bash
 brew install xberg-io/tap/xberg
 # or run without a persistent install (self-installs the binary):
 npx @xberg-io/xberg-cli --help
-uvx --from xberg-cli xberg --help
+uvx --from xberg-cli==1.4.0 xberg --help
 ```
 
 Or download a pre-built binary from the [latest GitHub Release](https://github.com/xberg-io/xberg/releases/latest), or build from source:

package/.opencode/skills/xberg-batch-extraction/references/configuration.md

@@ -1,7 +1,7 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
-Content-Hash: blake3:025df7e4b6c9e1dd2a98b81236a46d427816da719521512e3b03bc2ae15ae065
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Content-Hash: blake3:d9846749cb2b57685af6f077cfe2d16d5d7e58768437f14ee12f3c78a260106e
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 
@@ -115,7 +115,7 @@ Nested sections (each `None`/unset by default unless noted): `ocr`, `xberg-chunk
 enabled = true
 backend = "tesseract"
 language = ["eng"]
-auto_rotate = false
+auto_rotate = true
 ```
 
 | Option         | Type             | Default     | Description                                                            |
@@ -123,7 +123,7 @@ auto_rotate = false
 | `enabled`      | boolean          | `true`      | Whether OCR is enabled. Setting `false` is equivalent to `disable_ocr` |
 | `backend`      | string           | `"tesseract"` | OCR backend: `tesseract`, `paddleocr`/`paddle-ocr`, or `vlm`         |
 | `language`     | string or array  | `["eng"]`   | Language code(s). Accepts `"eng"` or `["eng", "deu"]`. Tesseract joins with `+` |
-| `auto_rotate`  | boolean          | `false`     | Enable automatic page rotation based on orientation detection         |
+| `auto_rotate`  | boolean \| null  | `null`      | `true` always rotates, `false` never rotates or retries, unset keeps the orientation retry |
 | `vlm_fallback` | string           | `"disabled"` | VLM fallback policy                                                   |
 | `output_format`| string \| null   | `null`      | Optional OCR output format override                                    |
 

package/.opencode/skills/xberg-batch-extraction/references/nodejs-api.md

@@ -1,7 +1,7 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
 Content-Hash: blake3:5dd1dce4a7814ed37c2ea273dda3dd60d7caa18b08b0aff933ce3a8f7717d1a6
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 

package/.opencode/skills/xberg-batch-extraction/references/other-bindings.md

@@ -1,7 +1,7 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
 Content-Hash: blake3:dacb4d7def21681b8b237603d2c7b89beaf18b8ee4110175b6ea5593022f3229
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 

package/.opencode/skills/xberg-batch-extraction/references/python-api.md

@@ -1,7 +1,7 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
-Content-Hash: blake3:723cd2abd915f92766e2dec9c90922b94ef60ad5ce81c606bd680b055e5c4717
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Content-Hash: blake3:9250a30997ec851cbb228ddcfd1f538e81e843f81e488e5f3d927ba94af93e4f
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 
@@ -485,7 +485,7 @@ for table in result.results[0].tables:
 
 ## Error Classes
 
-The errors raised by `extract()` and `extract_batch()` are plain `RuntimeError` — the typed exception classes below are **not** raised by these entry points, so catch `RuntimeError` (or `Exception`) around an `extract()`/`extract_batch()` call.
+`extract()` and `extract_batch()` raise the exported exception subclass for the underlying Rust error kind, including calls with `on_progress`. Catch `XbergError` for extraction failures, or a specific subclass such as `ParsingError`, `SecurityError`, or `ValidationError`.
 
 Xberg also defines a family of typed exception classes re-exported from `xberg`. The `XbergError`-rooted ones inherit from `XbergError` (base): `ParsingError`, `OcrError`, `ValidationError`, `MissingDependencyError`, `UnsupportedFormatError`, `CacheError`, `ImageProcessingError`, `SerializationError`, `PluginError`, `SecurityError`, `TranscriptionError`, `EmbeddingError`, `RerankingError`, `XbergTimeoutError`, `IoError`, and others. A few classes sit in separate hierarchies rooted at `Exception` rather than `XbergError` — e.g. `ConfigError`/`PdfAnalysisError` and `ParseError`/`SchemaValidationError`.
 
@@ -493,12 +493,12 @@ Xberg also defines a family of typed exception classes re-exported from `xberg`.
 
 ```python
 import asyncio
-from xberg import ExtractInput, extract, ExtractionConfig
+from xberg import ExtractInput, extract, ExtractionConfig, XbergError
 
 async def main() -> None:
     try:
         result = await extract(ExtractInput(uri="document.pdf"), ExtractionConfig())
-    except RuntimeError as e:
+    except XbergError as e:
         print(f"Extraction failed: {e}")
 
 asyncio.run(main())

package/.opencode/skills/xberg-batch-extraction/references/rust-api.md

@@ -1,7 +1,7 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
 Content-Hash: blake3:a257c85add0ba02dd9ab63eecac13348152038919a09ba99964261256acf4ee4
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 

package/.opencode/skills/xberg-batch-extraction/references/supported-formats.md

@@ -1,7 +1,7 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
 Content-Hash: blake3:e3c1dcb34a4784efc4f7fd868468061c3bd49d41e7e39792086633dcfe029d63
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 

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

@@ -6,7 +6,7 @@ name: xberg-chunking
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
 Content-Hash: blake3:aaaffebaf030b1c214ffc0a869f0a63366360a5a568638f6996b98e75901d121
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 

package/.opencode/skills/xberg-chunking/index.md

@@ -1,10 +1,10 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
-Content-Hash: blake3:300ad773df783b84ad7b4ea64f24ab3a0b853670f28ac74c7d6f9f00a18ac505
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Content-Hash: blake3:1c68a3b266a19383b28a9915e14fda9bce6c6d4668ce923727e86b59a2e34e0e
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 
 # Concepts
 
-* [Chunking](SKILL.md) - 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.
+- [Chunking](SKILL.md) - 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.

package/.opencode/skills/xberg-chunking/references/advanced-features.md

@@ -1,7 +1,7 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
 Content-Hash: blake3:353a7a05cbe84a2af1d053c8173d2154f418972a2bbfc2846dbb2c17a8a46197
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 

package/.opencode/skills/xberg-chunking/references/cli-reference.md

@@ -1,7 +1,7 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
-Content-Hash: blake3:b9281b07af57a10b362019da24d8545036e83015038e2f5902bfe167f165ecec
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Content-Hash: blake3:70bcb43e649e885bb822d41efb7221b365fd6f1870d1e6a5bb4ab3ec10be6acc
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 
@@ -11,11 +11,13 @@ Comprehensive command-line interface for the Xberg document intelligence library
 
 ## Installation
 
+The pinned command below follows this source release (1.4.0); use it once that release is published.
+
 ```bash
 brew install xberg-io/tap/xberg
 # or run without a persistent install (self-installs the binary):
 npx @xberg-io/xberg-cli --help
-uvx --from xberg-cli xberg --help
+uvx --from xberg-cli==1.4.0 xberg --help
 ```
 
 Or download a pre-built binary from the [latest GitHub Release](https://github.com/xberg-io/xberg/releases/latest), or build from source:

package/.opencode/skills/xberg-chunking/references/configuration.md

@@ -1,7 +1,7 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
-Content-Hash: blake3:025df7e4b6c9e1dd2a98b81236a46d427816da719521512e3b03bc2ae15ae065
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Content-Hash: blake3:d9846749cb2b57685af6f077cfe2d16d5d7e58768437f14ee12f3c78a260106e
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 
@@ -115,7 +115,7 @@ Nested sections (each `None`/unset by default unless noted): `ocr`, `xberg-chunk
 enabled = true
 backend = "tesseract"
 language = ["eng"]
-auto_rotate = false
+auto_rotate = true
 ```
 
 | Option         | Type             | Default     | Description                                                            |
@@ -123,7 +123,7 @@ auto_rotate = false
 | `enabled`      | boolean          | `true`      | Whether OCR is enabled. Setting `false` is equivalent to `disable_ocr` |
 | `backend`      | string           | `"tesseract"` | OCR backend: `tesseract`, `paddleocr`/`paddle-ocr`, or `vlm`         |
 | `language`     | string or array  | `["eng"]`   | Language code(s). Accepts `"eng"` or `["eng", "deu"]`. Tesseract joins with `+` |
-| `auto_rotate`  | boolean          | `false`     | Enable automatic page rotation based on orientation detection         |
+| `auto_rotate`  | boolean \| null  | `null`      | `true` always rotates, `false` never rotates or retries, unset keeps the orientation retry |
 | `vlm_fallback` | string           | `"disabled"` | VLM fallback policy                                                   |
 | `output_format`| string \| null   | `null`      | Optional OCR output format override                                    |
 

package/.opencode/skills/xberg-chunking/references/nodejs-api.md

@@ -1,7 +1,7 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
 Content-Hash: blake3:5dd1dce4a7814ed37c2ea273dda3dd60d7caa18b08b0aff933ce3a8f7717d1a6
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 

package/.opencode/skills/xberg-chunking/references/other-bindings.md

@@ -1,7 +1,7 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
 Content-Hash: blake3:dacb4d7def21681b8b237603d2c7b89beaf18b8ee4110175b6ea5593022f3229
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 

package/.opencode/skills/xberg-chunking/references/python-api.md

@@ -1,7 +1,7 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
-Content-Hash: blake3:723cd2abd915f92766e2dec9c90922b94ef60ad5ce81c606bd680b055e5c4717
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Content-Hash: blake3:9250a30997ec851cbb228ddcfd1f538e81e843f81e488e5f3d927ba94af93e4f
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 
@@ -485,7 +485,7 @@ for table in result.results[0].tables:
 
 ## Error Classes
 
-The errors raised by `extract()` and `extract_batch()` are plain `RuntimeError` — the typed exception classes below are **not** raised by these entry points, so catch `RuntimeError` (or `Exception`) around an `extract()`/`extract_batch()` call.
+`extract()` and `extract_batch()` raise the exported exception subclass for the underlying Rust error kind, including calls with `on_progress`. Catch `XbergError` for extraction failures, or a specific subclass such as `ParsingError`, `SecurityError`, or `ValidationError`.
 
 Xberg also defines a family of typed exception classes re-exported from `xberg`. The `XbergError`-rooted ones inherit from `XbergError` (base): `ParsingError`, `OcrError`, `ValidationError`, `MissingDependencyError`, `UnsupportedFormatError`, `CacheError`, `ImageProcessingError`, `SerializationError`, `PluginError`, `SecurityError`, `TranscriptionError`, `EmbeddingError`, `RerankingError`, `XbergTimeoutError`, `IoError`, and others. A few classes sit in separate hierarchies rooted at `Exception` rather than `XbergError` — e.g. `ConfigError`/`PdfAnalysisError` and `ParseError`/`SchemaValidationError`.
 
@@ -493,12 +493,12 @@ Xberg also defines a family of typed exception classes re-exported from `xberg`.
 
 ```python
 import asyncio
-from xberg import ExtractInput, extract, ExtractionConfig
+from xberg import ExtractInput, extract, ExtractionConfig, XbergError
 
 async def main() -> None:
     try:
         result = await extract(ExtractInput(uri="document.pdf"), ExtractionConfig())
-    except RuntimeError as e:
+    except XbergError as e:
         print(f"Extraction failed: {e}")
 
 asyncio.run(main())

package/.opencode/skills/xberg-chunking/references/rust-api.md

@@ -1,7 +1,7 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
 Content-Hash: blake3:a257c85add0ba02dd9ab63eecac13348152038919a09ba99964261256acf4ee4
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 

package/.opencode/skills/xberg-chunking/references/supported-formats.md

@@ -1,7 +1,7 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
 Content-Hash: blake3:e3c1dcb34a4784efc4f7fd868468061c3bd49d41e7e39792086633dcfe029d63
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 

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

@@ -6,7 +6,7 @@ name: xberg-extracting-keywords
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
 Content-Hash: blake3:491d3cbcd4f6128d43e32b39c13d03a023b397f97c71da48ed5a02d6be00ae28
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 

package/.opencode/skills/xberg-extracting-keywords/index.md

@@ -1,10 +1,10 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
-Content-Hash: blake3:95ea1ed670e9f4a1d722e167cb5405aa3b445cb8dc79db95981131bd99e390a5
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Content-Hash: blake3:57fac354e456e8f381c394e954fe4631b559ee89e90d2f2ff4366061ffeac686
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 
 # Concepts
 
-* [Extracting Keywords](SKILL.md) - 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.
+- [Extracting Keywords](SKILL.md) - 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.

package/.opencode/skills/xberg-extracting-keywords/references/advanced-features.md

@@ -1,7 +1,7 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
 Content-Hash: blake3:353a7a05cbe84a2af1d053c8173d2154f418972a2bbfc2846dbb2c17a8a46197
-Source-Hash: blake3:662aa704cf97ad20f02258c9dcd1c73822213a426e27ec7ebc292d3f599fb7c2
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->