@xberg-io/opencode-xberg 1.3.7 → 1.3.11

package/README.md

@@ -17,6 +17,44 @@ 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:
+
+```bash
+pi install ./plugin
+```
+
+Once a plugin release includes Pi support, use the shared OpenCode/Pi npm package:
+
+```bash
+pi install npm:@xberg-io/opencode-xberg
+```
+
+Pi discovers skills from `.pi/skills` and prompt templates from `.pi/prompts`.
+Use `/xberg-extract` and `/xberg-ocr` to start a task.
+Install the CLI separately using the instructions below. The Pi package does not
+register MCP servers, hooks, or executable extensions. The MCP integration
+sections below apply to clients with MCP support.
+
+Git installs use the repository root's `package.json` resource paths. GitHub
+hosts the checkout resources; the existing npm plugin release publishes the same
+Pi content alongside the OpenCode adapter. No separate Pi release job is needed.
+
 ### Binary requirement
 
 Install the `xberg` CLI:
@@ -52,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):
 
@@ -118,6 +156,22 @@ xberg extract data.xlsx --format json
 
 The plugin version tracks the xberg core release (`Cargo.toml`). See [CHANGELOG.md](../CHANGELOG.md) for release notes.
 
+## Maintaining the plugin
+
+Edit `plugin/.ai-rulez` sources, then run these commands from the repository root
+with a Pi-capable ai-rulez v5 binary installed:
+
+```bash
+task plugin:generate
+task plugin:verify
+task plugin:test
+```
+
+CI builds the generator from a pinned source revision and verifies the generated
+bundles, OpenCode tools, and actual npm archive before publication. The shared
+npm package publishes both OpenCode and Pi resources; Hermes uses its existing
+PyPI release job. GitHub hosts the remaining plugin bundles and marketplace indexes.
+
 ## License
 
 MIT. The skill content uses Elastic-2.0 references to the upstream [xberg](https://github.com/xberg-io/xberg) repository.
@@ -127,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,31 +1,199 @@
 {
-  "name": "@xberg-io/opencode-xberg",
-  "version": "1.3.7",
+  "author": {
+    "email": "contact@xberg.io",
+    "name": "Kreuzberg, Inc.",
+    "url": "https://xberg.io"
+  },
+  "dependencies": {
+    "@opencode/plugin": "^2.0.26"
+  },
   "description": "Local document extraction: text, tables, metadata, images from 107 formats with optional OCR.",
+  "exports": {
+    ".": "./.opencode/plugins/xberg.js"
+  },
+  "files": [
+    ".opencode/ai-rulez-bundle.json",
+    ".opencode/ai-rulez-content.js",
+    ".opencode/commands/xberg-extract.md",
+    ".opencode/commands/xberg-ocr.md",
+    ".opencode/plugins/xberg.js",
+    ".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",
+    ".opencode/skills/xberg/references/nodejs-api.md",
+    ".opencode/skills/xberg/references/other-bindings.md",
+    ".opencode/skills/xberg/references/python-api.md",
+    ".opencode/skills/xberg/references/rust-api.md",
+    ".opencode/skills/xberg/references/supported-formats.md",
+    ".pi/prompts/xberg-extract.md",
+    ".pi/prompts/xberg-ocr.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",
+    ".pi/skills/xberg/references/nodejs-api.md",
+    ".pi/skills/xberg/references/other-bindings.md",
+    ".pi/skills/xberg/references/python-api.md",
+    ".pi/skills/xberg/references/rust-api.md",
+    ".pi/skills/xberg/references/supported-formats.md",
+    "README.md",
+    "assets/",
+    "scripts/"
+  ],
+  "homepage": "https://xberg.io",
   "keywords": [
     "document-intelligence",
     "extraction",
     "ocr",
     "pdf",
+    "pi-package",
     "tables"
   ],
-  "homepage": "https://xberg.io",
+  "license": "MIT",
+  "main": ".opencode/plugins/xberg.js",
+  "name": "@xberg-io/opencode-xberg",
+  "pi": {
+    "prompts": [
+      "./.pi/prompts/xberg-extract.md",
+      "./.pi/prompts/xberg-ocr.md"
+    ],
+    "skills": [
+      "./.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"
+    ]
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/xberg-io/xberg"
   },
-  "license": "MIT",
   "type": "module",
-  "main": ".opencode/plugins/xberg.js",
-  "exports": {
-    ".": "./.opencode/plugins/xberg.js"
-  },
-  "files": [
-    ".opencode/",
-    "assets/",
-    "README.md"
-  ],
-  "dependencies": {
-    "@opencode-ai/plugin": "^1.17.8"
-  }
+  "version": "1.3.11"
 }

package/scripts/mcp-launch.sh

@@ -0,0 +1,189 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+NPM_PKG="@xberg-io/xberg-cli"
+PYPI_PKG="xberg-cli"
+
+log() { printf 'xberg-launch: %s\n' "$*" >&2; }
+die() {
+  log "error: $*"
+  exit 1
+}
+
+LAUNCHER="${XBERG_LAUNCHER:-auto}"
+case "$LAUNCHER" in
+auto | npx | uvx | brew | download) ;;
+*) die "invalid XBERG_LAUNCHER='$LAUNCHER' (expected auto|npx|uvx|brew|download)" ;;
+esac
+
+want() { [ "$LAUNCHER" = "auto" ] || [ "$LAUNCHER" = "$1" ]; }
+
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-}"
+if [ -z "$PLUGIN_ROOT" ]; then
+  PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+fi
+
+BINARY_NAME="xberg"
+case "$(uname -s)" in
+MINGW* | MSYS* | CYGWIN* | Windows_NT) BINARY_NAME="xberg.exe" ;;
+esac
+BIN_DIR="$PLUGIN_ROOT/bin"
+BIN="$BIN_DIR/$BINARY_NAME"
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+runnable() { [ -x "$1" ] && "$1" --version >/dev/null 2>&1; }
+
+if runnable "$BIN"; then
+  log "using cached xberg at $BIN"
+  exec "$BIN" "$@"
+fi
+if have "$BINARY_NAME"; then
+  PATH_BIN="$(command -v "$BINARY_NAME")"
+  if runnable "$PATH_BIN"; then
+    log "using xberg on PATH ($PATH_BIN)"
+    exec "$PATH_BIN" "$@"
+  fi
+fi
+
+if want npx && have npx; then
+  log "resolving npx $NPM_PKG@latest ..."
+  scratch="$(mktemp -d)"
+  # 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"
+fi
+
+if want uvx && have uvx; then
+  log "probing uvx --from $PYPI_PKG $BINARY_NAME ..."
+  if uvx --from "$PYPI_PKG" "$BINARY_NAME" --version >/dev/null 2>&1; then
+    log "launching via uvx --from $PYPI_PKG $BINARY_NAME"
+    exec uvx --from "$PYPI_PKG" "$BINARY_NAME" "$@"
+  fi
+  log "uvx $PYPI_PKG not available (no CLI entry point yet); falling through"
+fi
+
+if want brew && have brew; then
+  log "installing via 'brew install xberg-io/tap/xberg' ..."
+  if brew install xberg-io/tap/xberg >&2; then
+    if have "$BINARY_NAME"; then
+      BREW_BIN="$(command -v "$BINARY_NAME")"
+      runnable "$BREW_BIN" && exec "$BREW_BIN" "$@"
+    fi
+    log "brew install reported success but xberg is not on PATH; falling through"
+  else
+    log "brew install failed; falling through"
+  fi
+fi
+
+try_download() {
+  local arch triple ext base_url asset asset_url tmp ex src_dir
+  arch="$(uname -m)"
+  case "$(uname -s)" in
+  Darwin)
+    case "$arch" in
+    arm64 | aarch64) triple="aarch64-apple-darwin" ;;
+    x86_64 | amd64) triple="x86_64-apple-darwin" ;;
+    *)
+      log "no prebuilt macOS archive for $arch; falling through"
+      return 1
+      ;;
+    esac
+    ;;
+  Linux)
+    case "$arch" in
+    aarch64 | arm64) triple="aarch64-unknown-linux-gnu" ;;
+    x86_64) triple="x86_64-unknown-linux-gnu" ;;
+    *)
+      log "no prebuilt Linux archive for $arch; falling through"
+      return 1
+      ;;
+    esac
+    ;;
+  MINGW* | MSYS* | CYGWIN* | Windows_NT) triple="x86_64-pc-windows-msvc" ;;
+  *)
+    log "no prebuilt archive for $(uname -s)/$arch; falling through"
+    return 1
+    ;;
+  esac
+  case "$triple" in
+  *windows*) ext="zip" ;;
+  *) ext="tar.gz" ;;
+  esac
+
+  base_url="https://github.com/xberg-io/xberg/releases/latest/download"
+  asset="xberg-cli-${triple}.${ext}"
+  asset_url="${base_url}/${asset}"
+
+  if have curl; then
+    fetch() { curl -fsSL --retry 3 -o "$2" "$1"; }
+  elif have wget; then
+    fetch() { wget -q -O "$2" "$1"; }
+  else
+    log "no curl or wget available for download; falling through"
+    return 1
+  fi
+
+  tmp="$(mktemp -d)"
+  # shellcheck disable=SC2064  # expand $tmp now so the trap removes this exact dir
+  trap "rm -rf '$tmp'" RETURN
+
+  log "downloading $asset from latest release ..."
+  if ! fetch "$asset_url" "$tmp/$asset"; then
+    log "download failed or asset not found: $asset_url; falling through"
+    return 1
+  fi
+
+  log "warning: no published checksum for $asset; integrity is verified by HTTPS/TLS only, not a content hash"
+
+  ex="$tmp/extracted"
+  mkdir -p "$ex"
+  case "$ext" in
+  tar.gz) tar -xzf "$tmp/$asset" -C "$ex" || {
+    log "extraction failed; falling through"
+    return 1
+  } ;;
+  zip)
+    if have unzip; then
+      unzip -qo "$tmp/$asset" -d "$ex" || {
+        log "extraction failed; falling through"
+        return 1
+      }
+    else
+      log "need unzip to extract $asset; falling through"
+      return 1
+    fi
+    ;;
+  esac
+
+  src_dir="$ex/xberg-cli-${triple}"
+  [ -d "$src_dir" ] || src_dir="$ex"
+  if [ ! -f "$src_dir/$BINARY_NAME" ]; then
+    log "binary $BINARY_NAME not found inside $asset; falling through"
+    return 1
+  fi
+
+  rm -rf "$BIN_DIR"
+  mkdir -p "$BIN_DIR"
+  mv "$src_dir"/* "$BIN_DIR"/
+  chmod +x "$BIN"
+  log "installed xberg to $BIN"
+  return 0
+}
+
+if want download; then
+  if try_download; then
+    exec "$BIN" "$@"
+  fi
+fi
+
+die "could not locate or install xberg. Install it manually with one of:
+  brew install xberg-io/tap/xberg
+  cargo install xberg-cli
+  or download a prebuilt archive from https://github.com/xberg-io/xberg/releases/latest
+then ensure 'xberg' is on PATH and retry."