@xberg-io/opencode-xberg 1.3.8 → 1.4.0

package/.pi/prompts/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:3fca38eb564d0ed9c9194d070fd8dec96de727edc92e82954cb4b9af52cddbaf
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 

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

@@ -1,22 +1,17 @@
 ---
-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.
+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
+    author: xberg-io
+    version: "0.1.0"
+    repository: https://github.com/xberg-io/xberg
+name: xberg
 ---
 
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
-Content-Hash: blake3:8d1ddd2c0fd7b6e9473737826178427138c3fac45cedd5b6c3d0b8a243739deb
-Source-Hash: blake3:3fca38eb564d0ed9c9194d070fd8dec96de727edc92e82954cb4b9af52cddbaf
+Content-Hash: blake3:bdb659ec3959943d7e4b8da0cc3b8fbe51dc3bfec07e27dbbd8f84e190a63e1a
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 
@@ -68,8 +63,8 @@ tokio = { version = "1", features = ["full"] }
 ```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
+npx @xberg-io/xberg-cli@1.3.10 --help
+uvx --from xberg-cli==1.3.8 xberg --help
 # or download a prebuilt binary from the latest GitHub release:
 #   https://github.com/xberg-io/xberg/releases/latest
 # or build from source:
@@ -220,7 +215,7 @@ xberg extract doc.pdf --config-json '{"ocr":{"backend":"tesseract","language":"d
 
 ## 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`.
+`extract_batch` takes a list of `ExtractInput`s and returns one envelope whose `results` array holds documents in discovery order; one input may yield multiple documents. Per-input failures are reported in `result.errors` with an input index.
 
 ### Python
 
@@ -319,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}")
 ```
 
@@ -372,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`.
@@ -416,12 +411,12 @@ Detailed reference files for specific topics:
 
 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.
+- **xberg-extracting-with-ocr** — OCR backends, language packs, force-OCR, tuning.
+- **xberg-extracting-tables** — layout-aware table detection and table models.
+- **xberg-chunking** — chunk size/overlap, markdown/yaml/semantic chunkers, the `chunk` command.
+- **xberg-extracting-keywords** — YAKE/RAKE keywords, language detection, the `embed` command.
+- **xberg-batch-extraction** — the `batch` command, `--file-configs`, parallelism, error recovery.
+- **xberg-picking-a-format** — choosing `--format` / `--content-format` per consumer.
 
 Full documentation: <https://docs.xberg.io>
 GitHub: <https://github.com/xberg-io/xberg>

package/.pi/skills/xberg/index.md

@@ -0,0 +1,10 @@
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+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.

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

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

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

@@ -1,7 +1,7 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
-Content-Hash: blake3:cd55a9d089a4fe188a64803a05bf46b418949673c0b952c381eefdd2416457f5
-Source-Hash: blake3:3fca38eb564d0ed9c9194d070fd8dec96de727edc92e82954cb4b9af52cddbaf
+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:
@@ -422,7 +424,7 @@ xberg batch *.pdf --config extraction-config.toml
 
 ```bash
 # Extract to JSON for downstream processing
-xberg extract file.pdf --format json | jq '.content'
+xberg extract file.pdf --format json | jq '.result.content'
 
 # Batch process with error handling
 xberg batch docs/*.pdf --format json || exit 1

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

@@ -1,7 +1,7 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
-Content-Hash: blake3:a8f2b7b96ef3d33120ab21586c9f7db80c4d17eba727757ff0e94cee6e7d28c0
-Source-Hash: blake3:3fca38eb564d0ed9c9194d070fd8dec96de727edc92e82954cb4b9af52cddbaf
+Content-Hash: blake3:d9846749cb2b57685af6f077cfe2d16d5d7e58768437f14ee12f3c78a260106e
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 
@@ -106,7 +106,7 @@ max_archive_depth = 3
 | `cache_ttl_secs`             | int \| null      | `null`        | Per-request cache TTL in seconds. `0` skips the cache entirely                               |
 | `qr_codes`                   | boolean \| null  | `null`        | Enable QR-code detection in extracted images                                                 |
 
-Nested sections (each `None`/unset by default unless noted): `ocr`, `chunking`, `content_filter`, `images`, `pdf_options`, `token_reduction`, `language_detection`, `pages`, `keywords`, `postprocessor`, `html_output`, `security_limits`, `layout`, `transcription`, `acceleration`, `email`, `tree_sitter`, `structured_extraction`, `ner`, `redaction`, `summarization`, `translation`, `page_classification`, `captioning`, and `url`. The `url` section always has a default (it is not optional). The sections documented below are the ones most commonly set in config files.
+Nested sections (each `None`/unset by default unless noted): `ocr`, `xberg-chunking`, `content_filter`, `images`, `pdf_options`, `token_reduction`, `language_detection`, `pages`, `keywords`, `postprocessor`, `html_output`, `security_limits`, `layout`, `transcription`, `acceleration`, `email`, `tree_sitter`, `structured_extraction`, `ner`, `redaction`, `summarization`, `translation`, `page_classification`, `captioning`, and `url`. The `url` section always has a default (it is not optional). The sections documented below are the ones most commonly set in config files.
 
 ### OCR Configuration
 
@@ -115,7 +115,7 @@ Nested sections (each `None`/unset by default unless noted): `ocr`, `chunking`,
 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                                    |
 
@@ -449,7 +449,7 @@ result = await extract_batch(
 )
 ```
 
-**Overridable fields:** `enable_quality_processing`, `ocr`, `force_ocr`, `force_ocr_pages`, `disable_ocr`, `chunking`, `content_filter`, `images`, `pdf_options`, `token_reduction`, `language_detection`, `pages`, `keywords`, `postprocessor`, `html_output` (and `html_options`), `result_format`, `output_format`, `include_document_structure`, `layout`, `transcription`, `timeout_secs`, `tree_sitter`, `structured_extraction`, `url`, `ner`, `redaction`, `summarization`, `translation`, `page_classification`, `captioning`, `qr_codes`.
+**Overridable fields:** `enable_quality_processing`, `ocr`, `force_ocr`, `force_ocr_pages`, `disable_ocr`, `xberg-chunking`, `content_filter`, `images`, `pdf_options`, `token_reduction`, `language_detection`, `pages`, `keywords`, `postprocessor`, `html_output` (and `html_options`), `result_format`, `output_format`, `include_document_structure`, `layout`, `transcription`, `timeout_secs`, `tree_sitter`, `structured_extraction`, `url`, `ner`, `redaction`, `summarization`, `translation`, `page_classification`, `captioning`, `qr_codes`.
 
 **Batch-level only (not overridable per input):** `max_concurrent_extractions`, `use_cache`, `acceleration`, `security_limits`.
 

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

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

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

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

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

@@ -1,7 +1,7 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
-Content-Hash: blake3:c551708aa62f1b25b1cea8041e8aab5b3101a1622317b7239d3de04d8a375754
-Source-Hash: blake3:3fca38eb564d0ed9c9194d070fd8dec96de727edc92e82954cb4b9af52cddbaf
+Content-Hash: blake3:9250a30997ec851cbb228ddcfd1f538e81e843f81e488e5f3d927ba94af93e4f
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 
@@ -128,7 +128,7 @@ Main extraction configuration. All fields are optional and use sensible defaults
 | `enable_quality_processing` | bool                              | True        | Quality post-processing to clean and normalize extracted text.      |
 | `ocr`                       | OcrConfig \| None                 | None        | OCR configuration. None = OCR disabled.                             |
 | `force_ocr`                 | bool                              | False       | Force OCR even for searchable PDFs that contain extractable text.   |
-| `chunking`                  | ChunkingConfig \| None            | None        | Text chunking configuration. None = disabled.                      |
+| `xberg-chunking`                  | ChunkingConfig \| None            | None        | Text chunking configuration. None = disabled.                      |
 | `images`                    | ImageExtractionConfig \| None     | None        | Extract images FROM documents. None = no image extraction.         |
 | `pdf_options`               | PdfConfig \| None                 | None        | PDF-specific options.                                              |
 | `token_reduction`           | TokenReductionOptions \| None     | None        | Reduce token count in extracted content. None = no reduction.       |
@@ -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/.pi/skills/xberg/references/rust-api.md

@@ -1,7 +1,7 @@
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
-Content-Hash: blake3:a6ececeeda3031d9d84eb780fcb5ecb41b3f4297fa1e6b86f492e0d755b084a9
-Source-Hash: blake3:3fca38eb564d0ed9c9194d070fd8dec96de727edc92e82954cb4b9af52cddbaf
+Content-Hash: blake3:a257c85add0ba02dd9ab63eecac13348152038919a09ba99964261256acf4ee4
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 
@@ -36,7 +36,7 @@ The `tokio-runtime` feature is on by default. Capabilities are gated behind feat
 | `full`               | `formats` + ocr + layout + embeddings + tree-sitter + LLM. |
 | `pdf`                | PDF extraction.                                           |
 | `ocr`                | Tesseract-based OCR.                                      |
-| `chunking`           | Text chunking for RAG pipelines.                         |
+| `xberg-chunking`           | Text chunking for RAG pipelines.                         |
 | `embeddings`         | ONNX embedding generation.                                |
 | `language-detection` | Detect document language(s).                              |
 | `keywords`           | YAKE + RAKE keyword extraction.                          |
@@ -79,7 +79,7 @@ async fn main() -> xberg::Result<()> {
 pub async fn extract_batch(inputs: Vec<ExtractInput>, config: &ExtractionConfig) -> Result<ExtractionResult>
 ```
 
-Extract multiple inputs in parallel. The returned envelope's `results` holds one `ExtractedDocument` per input (in input order), with non-fatal failures in `errors`.
+Extract multiple inputs in parallel. The returned envelope's `results` holds `ExtractedDocument` values in discovery order; one input may yield multiple documents. Non-fatal failures in `errors` carry the original input index.
 
 ```rust
 use xberg::{extract_batch, ExtractInput, ExtractionConfig};
@@ -261,7 +261,7 @@ let config = ExtractionConfig {
 
 ```rust
 pub struct ExtractionResult {
-    pub results: Vec<ExtractedDocument>,       // one per input, in order
+    pub results: Vec<ExtractedDocument>,       // documents in discovery order; multiple per input are possible
     pub errors: Vec<ExtractionErrorItem>,      // non-fatal per-input errors
     pub summary: ExtractionSummary,            // aggregate counts
     pub crawl_final_urls: Vec<String>,

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

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

package/.pi/skills/{batch-extraction → xberg-batch-extraction}/SKILL.md

@@ -1,12 +1,12 @@
 ---
-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.
+name: xberg-batch-extraction
 ---
 
 <!--
 AI-RULEZ :: GENERATED FILE — DO NOT EDIT
-Content-Hash: blake3:3a70b47dd77fcd3f37e83bed3d32b1ad1ea9d6c1642ae8e0ff7b09b55939858a
-Source-Hash: blake3:3fca38eb564d0ed9c9194d070fd8dec96de727edc92e82954cb4b9af52cddbaf
+Content-Hash: blake3:324433f2b10c7c9cdc1c06b98c1e427c8cb0ca9ccf034d336e28d49706add520
+Source-Hash: blake3:ab2bcd453f9c2ded67752f6a9800186d42b6921f4be16f6ab3a773254a9fba00
 Schema-Version: v1
 -->
 
@@ -14,13 +14,13 @@ Schema-Version: v1
 
 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
+extractions concurrently, and returns a JSON envelope — 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)
+# Glob expands to many paths; results come back in a JSON envelope (default)
 xberg batch *.pdf
 
 # Mixed formats, markdown content for LLM ingestion
@@ -31,12 +31,14 @@ 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.
+`extract`). The envelope contains `results`, `total_ms`, `per_file_ms` and, when failures
+occur, `errors`. Each `results` entry is a full extracted document. One input may produce
+multiple documents, so do not pair results with inputs by position. `per_file_ms` is
+aligned with inputs; inspect `errors` for per-input failures.
 
 ```bash
 xberg batch reports/*.pdf \
-  | jq '.[] | {chars: (.content | length), mime: .mime_type}'
+  | jq '.results[] | {chars: (.content | length), mime: .mime_type}'
 ```
 
 ## Parallelism
@@ -146,7 +148,7 @@ for doc in output.results:
 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.
+`references/rust-api.md`.
 
 ## MCP
 

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

@@ -0,0 +1,10 @@
+<!--
+AI-RULEZ :: GENERATED FILE — DO NOT EDIT
+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.