@xberg-io/opencode-xberg 1.3.8 → 1.3.11

package/README.md

@@ -17,6 +17,20 @@ Self-host:
 /plugin install xberg@xberg
 ```
 
+### Kimi installation and compatibility
+
+From a checkout of this repository, install with the Python Kimi CLI version used for native
+plugin validation:
+
+```sh
+uvx --from kimi-cli==1.51.0 kimi plugin install ./plugin
+```
+
+Native plugin installation was validated with Python Kimi CLI 1.51.0. The replacement
+`@moonshot-ai/kimi-code` 2.1.1 does not provide a `plugin` CLI subcommand; its interactive
+plugin loading has not been verified. These results do not establish compatibility with
+newer Kimi releases.
+
 ### Pi
 
 From a checkout of this repository, run:
@@ -76,12 +90,12 @@ sudo apt install tesseract-ocr-*   # Debian/Ubuntu
 | Skill | Trigger |
 |-------|---------|
 | **xberg** | 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. |
-| **extracting-with-ocr** | 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. |
-| **extracting-tables** | 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. |
-| **chunking** | 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. |
-| **extracting-keywords** | Use when extracting keywords (YAKE/RAKE), detecting document language, or generating embeddings for RAG and search. Covers the keyword config, `--detect-language`, and the standalone `embed` command. |
-| **batch-extraction** | 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. |
-| **picking-a-format** | Use when choosing an output format for extracted documents — text, markdown, djot, html, or JSON. Maps consumer (LLM, parser, archive) to the right `--format` / `--content-format` pair. |
+| **xberg-extracting-with-ocr** | 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. |
+| **xberg-extracting-tables** | 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. |
+| **xberg-chunking** | 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. |
+| **xberg-extracting-keywords** | Use when extracting keywords (YAKE/RAKE), detecting document language, or generating embeddings for RAG and search. Covers the keyword config, `--detect-language`, and the standalone `embed` command. |
+| **xberg-batch-extraction** | 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. |
+| **xberg-picking-a-format** | Use when choosing an output format for extracted documents — text, markdown, djot, html, or JSON. Maps consumer (LLM, parser, archive) to the right `--format` / `--content-format` pair. |
 
 **Reference materials** (linked from the `xberg` skill):
 
@@ -167,3 +181,55 @@ MIT. The skill content uses Elastic-2.0 references to the upstream [xberg](https
 - **Marketplace**: this repo — `/plugin marketplace add xberg-io/xberg`
 - **Upstream**: [xberg-io/xberg](https://github.com/xberg-io/xberg)
 - **Related plugins**: [crawlberg](https://github.com/xberg-io/crawlberg)
+
+## Generated runtime bundles
+
+`plugin/.ai-rulez/config.toml` loads `config.plugins.toml` through the `plugins` layer;
+skills, commands and runtime adapters are authored alongside it. AI-Rulez 5.3.0 generates
+all eleven supported runtimes: Claude, Cursor, Codex, Gemini, Kimi, OpenCode, Factory,
+Hermes, Pi, Agent Plugins and Copilot. Codex ships both manifest layouts; repository-root
+Claude and Codex marketplace indexes point to the `plugin` bundle. Cursor also has a marketplace index.
+
+Pi packages skills and prompts without MCP integration. Copilot packages skills and MCP configuration, but does not package slash commands or hooks.
+Hermes includes a Python package under `.hermes/package`; OpenCode and Pi share the npm package.
+The Agent Plugins manifest uses the stable 1.0 specification. Runtime capabilities differ;
+install the CLI before using skills in a runtime without MCP registration.
+
+Run `ai-rulez generate --plugin` from the repository root to regenerate and
+`ai-rulez verify --plugin` to compare current source output and provenance.
+The release workflow packages every runtime into a deterministic archive, checksums,
+and marketplace metadata; npm and PyPI retain their existing publishing jobs.
+
+## Hermes runtime setup
+
+Install the product CLI with MCP support and put it on Hermes' PATH before using the plugin.
+The Hermes adapter registers every bundled skill under the product namespace and provides
+`xberg_call`, which calls the selected native MCP tool with `tool_arguments` through a local
+stdio session. Select `tool: "list_tools"` first to inspect the server's exact request schemas. Hermes skills are selected explicitly; they are not automatically appended to the
+system prompt. Enable the plugin in Hermes configuration; project plugins also require
+`HERMES_ENABLE_PROJECT_PLUGINS=true`.
+
+The bridge uses the installed CLI directly. The auto-installing launchers used by other MCP clients
+are not included in the Hermes Python wheel. Provider credentials are inherited from the environment,
+and are needed for provider-backed requests. Missing CLIs, unavailable tools and model preparation
+fail with an actionable request error. CLI result data remains untrusted document content.
+
+## Public Agent Skills
+
+The repository-root `skills/` directory contains the same generated skills and supporting
+resources as `plugin/skills/`. Install them independently of a plugin runtime:
+
+```sh
+npx skills add xberg-io/xberg --skill xberg
+```
+
+Edit `plugin/.ai-rulez/skills`, then run `task plugin:generate` to regenerate runtime
+bundles and synchronize the public export. `task plugin:verify` checks both projections;
+`task plugin:skills:test` verifies resource freshness, ownership and symlink protection.
+The public ownership manifest records SHA-256 hashes of every exported file.
+
+Download integrity: the launcher currently relies on HTTPS for direct binary downloads.
+Verify release checksums separately when available before manually installing an archive.
+
+Launcher and visual assets are authored in `plugin/.ai-rulez/scripts/` and
+`plugin/.ai-rulez/assets/`; `task plugin:generate` copies them into the runtime bundle.

package/package.json

@@ -1,6 +1,11 @@
 {
+  "author": {
+    "email": "contact@xberg.io",
+    "name": "Kreuzberg, Inc.",
+    "url": "https://xberg.io"
+  },
   "dependencies": {
-    "@opencode/plugin": "^2.0.20"
+    "@opencode/plugin": "^2.0.26"
   },
   "description": "Local document extraction: text, tables, metadata, images from 107 formats with optional OCR.",
   "exports": {
@@ -12,13 +17,68 @@
     ".opencode/commands/xberg-extract.md",
     ".opencode/commands/xberg-ocr.md",
     ".opencode/plugins/xberg.js",
-    ".opencode/skills/batch-extraction/SKILL.md",
-    ".opencode/skills/chunking/SKILL.md",
-    ".opencode/skills/extracting-keywords/SKILL.md",
-    ".opencode/skills/extracting-tables/SKILL.md",
-    ".opencode/skills/extracting-with-ocr/SKILL.md",
-    ".opencode/skills/picking-a-format/SKILL.md",
+    ".opencode/skills/xberg-batch-extraction/SKILL.md",
+    ".opencode/skills/xberg-batch-extraction/index.md",
+    ".opencode/skills/xberg-batch-extraction/references/advanced-features.md",
+    ".opencode/skills/xberg-batch-extraction/references/cli-reference.md",
+    ".opencode/skills/xberg-batch-extraction/references/configuration.md",
+    ".opencode/skills/xberg-batch-extraction/references/nodejs-api.md",
+    ".opencode/skills/xberg-batch-extraction/references/other-bindings.md",
+    ".opencode/skills/xberg-batch-extraction/references/python-api.md",
+    ".opencode/skills/xberg-batch-extraction/references/rust-api.md",
+    ".opencode/skills/xberg-batch-extraction/references/supported-formats.md",
+    ".opencode/skills/xberg-chunking/SKILL.md",
+    ".opencode/skills/xberg-chunking/index.md",
+    ".opencode/skills/xberg-chunking/references/advanced-features.md",
+    ".opencode/skills/xberg-chunking/references/cli-reference.md",
+    ".opencode/skills/xberg-chunking/references/configuration.md",
+    ".opencode/skills/xberg-chunking/references/nodejs-api.md",
+    ".opencode/skills/xberg-chunking/references/other-bindings.md",
+    ".opencode/skills/xberg-chunking/references/python-api.md",
+    ".opencode/skills/xberg-chunking/references/rust-api.md",
+    ".opencode/skills/xberg-chunking/references/supported-formats.md",
+    ".opencode/skills/xberg-extracting-keywords/SKILL.md",
+    ".opencode/skills/xberg-extracting-keywords/index.md",
+    ".opencode/skills/xberg-extracting-keywords/references/advanced-features.md",
+    ".opencode/skills/xberg-extracting-keywords/references/cli-reference.md",
+    ".opencode/skills/xberg-extracting-keywords/references/configuration.md",
+    ".opencode/skills/xberg-extracting-keywords/references/nodejs-api.md",
+    ".opencode/skills/xberg-extracting-keywords/references/other-bindings.md",
+    ".opencode/skills/xberg-extracting-keywords/references/python-api.md",
+    ".opencode/skills/xberg-extracting-keywords/references/rust-api.md",
+    ".opencode/skills/xberg-extracting-keywords/references/supported-formats.md",
+    ".opencode/skills/xberg-extracting-tables/SKILL.md",
+    ".opencode/skills/xberg-extracting-tables/index.md",
+    ".opencode/skills/xberg-extracting-tables/references/advanced-features.md",
+    ".opencode/skills/xberg-extracting-tables/references/cli-reference.md",
+    ".opencode/skills/xberg-extracting-tables/references/configuration.md",
+    ".opencode/skills/xberg-extracting-tables/references/nodejs-api.md",
+    ".opencode/skills/xberg-extracting-tables/references/other-bindings.md",
+    ".opencode/skills/xberg-extracting-tables/references/python-api.md",
+    ".opencode/skills/xberg-extracting-tables/references/rust-api.md",
+    ".opencode/skills/xberg-extracting-tables/references/supported-formats.md",
+    ".opencode/skills/xberg-extracting-with-ocr/SKILL.md",
+    ".opencode/skills/xberg-extracting-with-ocr/index.md",
+    ".opencode/skills/xberg-extracting-with-ocr/references/advanced-features.md",
+    ".opencode/skills/xberg-extracting-with-ocr/references/cli-reference.md",
+    ".opencode/skills/xberg-extracting-with-ocr/references/configuration.md",
+    ".opencode/skills/xberg-extracting-with-ocr/references/nodejs-api.md",
+    ".opencode/skills/xberg-extracting-with-ocr/references/other-bindings.md",
+    ".opencode/skills/xberg-extracting-with-ocr/references/python-api.md",
+    ".opencode/skills/xberg-extracting-with-ocr/references/rust-api.md",
+    ".opencode/skills/xberg-extracting-with-ocr/references/supported-formats.md",
+    ".opencode/skills/xberg-picking-a-format/SKILL.md",
+    ".opencode/skills/xberg-picking-a-format/index.md",
+    ".opencode/skills/xberg-picking-a-format/references/advanced-features.md",
+    ".opencode/skills/xberg-picking-a-format/references/cli-reference.md",
+    ".opencode/skills/xberg-picking-a-format/references/configuration.md",
+    ".opencode/skills/xberg-picking-a-format/references/nodejs-api.md",
+    ".opencode/skills/xberg-picking-a-format/references/other-bindings.md",
+    ".opencode/skills/xberg-picking-a-format/references/python-api.md",
+    ".opencode/skills/xberg-picking-a-format/references/rust-api.md",
+    ".opencode/skills/xberg-picking-a-format/references/supported-formats.md",
     ".opencode/skills/xberg/SKILL.md",
+    ".opencode/skills/xberg/index.md",
     ".opencode/skills/xberg/references/advanced-features.md",
     ".opencode/skills/xberg/references/cli-reference.md",
     ".opencode/skills/xberg/references/configuration.md",
@@ -29,13 +89,68 @@
     ".opencode/skills/xberg/references/supported-formats.md",
     ".pi/prompts/xberg-extract.md",
     ".pi/prompts/xberg-ocr.md",
-    ".pi/skills/batch-extraction/SKILL.md",
-    ".pi/skills/chunking/SKILL.md",
-    ".pi/skills/extracting-keywords/SKILL.md",
-    ".pi/skills/extracting-tables/SKILL.md",
-    ".pi/skills/extracting-with-ocr/SKILL.md",
-    ".pi/skills/picking-a-format/SKILL.md",
+    ".pi/skills/xberg-batch-extraction/SKILL.md",
+    ".pi/skills/xberg-batch-extraction/index.md",
+    ".pi/skills/xberg-batch-extraction/references/advanced-features.md",
+    ".pi/skills/xberg-batch-extraction/references/cli-reference.md",
+    ".pi/skills/xberg-batch-extraction/references/configuration.md",
+    ".pi/skills/xberg-batch-extraction/references/nodejs-api.md",
+    ".pi/skills/xberg-batch-extraction/references/other-bindings.md",
+    ".pi/skills/xberg-batch-extraction/references/python-api.md",
+    ".pi/skills/xberg-batch-extraction/references/rust-api.md",
+    ".pi/skills/xberg-batch-extraction/references/supported-formats.md",
+    ".pi/skills/xberg-chunking/SKILL.md",
+    ".pi/skills/xberg-chunking/index.md",
+    ".pi/skills/xberg-chunking/references/advanced-features.md",
+    ".pi/skills/xberg-chunking/references/cli-reference.md",
+    ".pi/skills/xberg-chunking/references/configuration.md",
+    ".pi/skills/xberg-chunking/references/nodejs-api.md",
+    ".pi/skills/xberg-chunking/references/other-bindings.md",
+    ".pi/skills/xberg-chunking/references/python-api.md",
+    ".pi/skills/xberg-chunking/references/rust-api.md",
+    ".pi/skills/xberg-chunking/references/supported-formats.md",
+    ".pi/skills/xberg-extracting-keywords/SKILL.md",
+    ".pi/skills/xberg-extracting-keywords/index.md",
+    ".pi/skills/xberg-extracting-keywords/references/advanced-features.md",
+    ".pi/skills/xberg-extracting-keywords/references/cli-reference.md",
+    ".pi/skills/xberg-extracting-keywords/references/configuration.md",
+    ".pi/skills/xberg-extracting-keywords/references/nodejs-api.md",
+    ".pi/skills/xberg-extracting-keywords/references/other-bindings.md",
+    ".pi/skills/xberg-extracting-keywords/references/python-api.md",
+    ".pi/skills/xberg-extracting-keywords/references/rust-api.md",
+    ".pi/skills/xberg-extracting-keywords/references/supported-formats.md",
+    ".pi/skills/xberg-extracting-tables/SKILL.md",
+    ".pi/skills/xberg-extracting-tables/index.md",
+    ".pi/skills/xberg-extracting-tables/references/advanced-features.md",
+    ".pi/skills/xberg-extracting-tables/references/cli-reference.md",
+    ".pi/skills/xberg-extracting-tables/references/configuration.md",
+    ".pi/skills/xberg-extracting-tables/references/nodejs-api.md",
+    ".pi/skills/xberg-extracting-tables/references/other-bindings.md",
+    ".pi/skills/xberg-extracting-tables/references/python-api.md",
+    ".pi/skills/xberg-extracting-tables/references/rust-api.md",
+    ".pi/skills/xberg-extracting-tables/references/supported-formats.md",
+    ".pi/skills/xberg-extracting-with-ocr/SKILL.md",
+    ".pi/skills/xberg-extracting-with-ocr/index.md",
+    ".pi/skills/xberg-extracting-with-ocr/references/advanced-features.md",
+    ".pi/skills/xberg-extracting-with-ocr/references/cli-reference.md",
+    ".pi/skills/xberg-extracting-with-ocr/references/configuration.md",
+    ".pi/skills/xberg-extracting-with-ocr/references/nodejs-api.md",
+    ".pi/skills/xberg-extracting-with-ocr/references/other-bindings.md",
+    ".pi/skills/xberg-extracting-with-ocr/references/python-api.md",
+    ".pi/skills/xberg-extracting-with-ocr/references/rust-api.md",
+    ".pi/skills/xberg-extracting-with-ocr/references/supported-formats.md",
+    ".pi/skills/xberg-picking-a-format/SKILL.md",
+    ".pi/skills/xberg-picking-a-format/index.md",
+    ".pi/skills/xberg-picking-a-format/references/advanced-features.md",
+    ".pi/skills/xberg-picking-a-format/references/cli-reference.md",
+    ".pi/skills/xberg-picking-a-format/references/configuration.md",
+    ".pi/skills/xberg-picking-a-format/references/nodejs-api.md",
+    ".pi/skills/xberg-picking-a-format/references/other-bindings.md",
+    ".pi/skills/xberg-picking-a-format/references/python-api.md",
+    ".pi/skills/xberg-picking-a-format/references/rust-api.md",
+    ".pi/skills/xberg-picking-a-format/references/supported-formats.md",
     ".pi/skills/xberg/SKILL.md",
+    ".pi/skills/xberg/index.md",
     ".pi/skills/xberg/references/advanced-features.md",
     ".pi/skills/xberg/references/cli-reference.md",
     ".pi/skills/xberg/references/configuration.md",
@@ -66,12 +181,12 @@
       "./.pi/prompts/xberg-ocr.md"
     ],
     "skills": [
-      "./.pi/skills/batch-extraction",
-      "./.pi/skills/chunking",
-      "./.pi/skills/extracting-keywords",
-      "./.pi/skills/extracting-tables",
-      "./.pi/skills/extracting-with-ocr",
-      "./.pi/skills/picking-a-format",
+      "./.pi/skills/xberg-batch-extraction",
+      "./.pi/skills/xberg-chunking",
+      "./.pi/skills/xberg-extracting-keywords",
+      "./.pi/skills/xberg-extracting-tables",
+      "./.pi/skills/xberg-extracting-with-ocr",
+      "./.pi/skills/xberg-picking-a-format",
       "./.pi/skills/xberg"
     ]
   },
@@ -80,5 +195,5 @@
     "url": "https://github.com/xberg-io/xberg"
   },
   "type": "module",
-  "version": "1.3.8"
+  "version": "1.3.11"
 }

package/scripts/mcp-launch.sh

@@ -47,12 +47,13 @@ if have "$BINARY_NAME"; then
 fi
 
 if want npx && have npx; then
-  log "probing npx $NPM_PKG@latest ..."
+  log "resolving npx $NPM_PKG@latest ..."
   scratch="$(mktemp -d)"
-  if (cd "$scratch" && npx -y "$NPM_PKG@latest" --version >/dev/null 2>&1); then
-    log "launching via npx $NPM_PKG@latest"
-    cd "$scratch"
-    exec npx -y "$NPM_PKG@latest" "$@"
+  # Resolve in an empty project, then execute the selected binary in the caller's cwd. ~keep
+  if npm_bin="$(cd "$scratch" && npx -y --package "$NPM_PKG@latest" --call "command -v ${BINARY_NAME%.exe}" 2>/dev/null)" && runnable "$npm_bin"; then
+    rm -rf "$scratch"
+    log "launching npm package binary $npm_bin"
+    exec "$npm_bin" "$@"
   fi
   rm -rf "$scratch"
   log "npx $NPM_PKG not available (no CLI bin yet); falling through"