@trusted-ai/xbot 0.1.0

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guoqing Bao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,214 @@
+# 🤖 xbot: A Minimal AI Agent in Rust for Automation and Development
+
+`xbot` is a Rust-native autonomous bot runtime for persistent chat automation, tool execution, scheduled work, and multi-channel message delivery. 🚀
+
+## ✨ Features
+
+- 🧠 **Persistent Agent Runtime** - Long-running agent runtime with persistent sessions, per-session serialization, and configurable concurrency control
+- 📝 **Permanent Memory Capture** - LLM-driven memory consolidation, automatic task summaries, explicit `/memorize` support, and topic-relevant memory lookup
+- 🛠️ **Rich Toolset** - Filesystem, shell, web fetch, web search, messaging, cron, and background-task tools
+- 🌐 **Provider Integration** - OpenAI-compatible, Anthropic, GitHub Copilot (OAuth), Cursor, and local engines
+- 🧵 **Hybrid Model Routing** - Run the main task on a remote frontier API such as DeepSeek `deepseek-v4-pro`, while background subagents use a local Qwen/vLLM/Ollama model for fast parallel work
+- 🔌 **MCP Support** - MCP stdio tool integration for external tool servers
+- 🧩 **Built-in Skills** - Software engineering, research/reporting, GitHub/CI, scheduled operations, memory management, cron, and clawhub marketplace
+- 📬 **Multi-Channel** - 13 channel backends: `email`, `slack`, `telegram`, `feishu`, `dingtalk`, `discord`, `matrix`, `whatsapp`, `qq`, `wecom`, `weixin`, `mochat`, and extensible plugin channels
+- 🌐 **Gateway Process** - Webhook ingress, health checks, readiness checks, Prometheus metrics, and a web admin UI
+- 🔄 **Streaming** - Stream delta support with per-channel streaming, retry logic with exponential backoff
+- 🪝 **Hook System** - Extensible `AgentHook` trait for lifecycle callbacks without modifying the core agent loop
+
+## Overview (Hybrid Model Routing)
+<img src="docs/xbot.png" alt="xbot terminal" width="600">
+
+The screenshot highlights one of `xbot`'s core advantages: the main agent can use a remote high-capability model, while subagents fan out onto a separate local model. This lets you reserve paid remote tokens for synthesis and hard reasoning, and spend local GPU capacity on parallel exploration, code reading, tests, and report gathering.
+
+## 📚 Documentation
+
+- [🚀 Getting Started](./docs/USAGE.md)
+- [📦 Installation](./docs/INSTALLATION.md)
+- [🧵 Hybrid Remote Main + Local Subagents](./docs/HYBRID_MODELS.md)
+- [🏗️ Architecture](./docs/ARCHITECTURE.md)
+- [⚙️ Operations Guide](./docs/OPERATIONS.md)
+
+## ⚡ Quick Start
+
+### Install xbot:
+
+```bash
+cargo install xbot
+# or install a .deb from GitHub Releases
+# or npm install -g @trusted-ai/xbot
+```
+
+The installed command is `xbot`. See [Installation](./docs/INSTALLATION.md) for details.
+
+### Initialize config and workspace:
+
+```bash
+xbot onboard
+```
+
+This will generate:
+
+```python
+# Global config file
+Config: ~/.xbot/config.json
+# Global workspace
+Workspace: ~/.xbot/workspace
+```
+
+### Config Providers
+
+`xbot` supports both remote and local OpenAI-compatible backends. 🎯
+You can configure them interactively:
+
+```bash
+xbot config --provider
+# cargo run --release -- config --provider
+```
+
+Or manually edit `~/.xbot/config.json`. Refer to: [Getting Started](./docs/USAGE.md)
+
+For the recommended hybrid setup, use a remote main model such as DeepSeek `deepseek-v4-pro` and a local OpenAI-compatible server such as vLLM serving Qwen for subagents. See [Hybrid Remote Main + Local Subagents](./docs/HYBRID_MODELS.md).
+
+### Config Communication Channels
+
+Before starting the backend, you should configure your preferred communication channels (Slack, Telegram, etc.) to enable message ingress and delivery. 📬
+
+Use the interactive configuration tool:
+
+```bash
+xbot config --channel
+# cargo run --release -- config --channel
+```
+
+List, configure, and log in to channels:
+
+```bash
+xbot channels list          # List all available channels
+xbot channels status        # Show enabled/disabled state
+xbot channels setup discord # Setup instructions (how to get tokens)
+xbot channels login weixin  # Interactive login (QR code scan)
+```
+
+Use `channels setup <name>` to see step-by-step instructions for obtaining the required tokens and keys for any channel. For channels that support interactive login (Weixin QR code, WhatsApp bridge), use `channels login`. For manual configuration or detailed channel options, see [Getting Started](./docs/USAGE.md#5-channel-configuration).
+
+> [!TIP]
+> **Slack Users:** Set up Slack App for Agents [Slack Manual](https://www.meta-intelligence.tech/en/insight-openclaw-slack).
+> **Telegram Users:** Set up Telegram App for Agents [Telegram Manual](https://www.meta-intelligence.tech/en/insight-openclaw-telegram).
+
+
+## 🧾Usage
+
+## CLI usage
+
+### One-shot prompt:
+
+```bash
+# this will scan and init the project for following tasks (XBOT.md)
+xbot chat /init
+# this will do one task a time
+xbot chat "find bugs in this project"
+# cargo run --release -- chat /init
+```
+
+### Interactive shell (TUI, rich terminal UI):
+
+```bash
+xbot repl
+# cargo run --release -- repl
+```
+
+The CLI includes:
+- 📡 Streamed responses
+- 📜 Persistent history
+- 💻 Local shell commands such as `/help` and `/clear`
+- 🤖 Agent commands such as `/new`, `/clear`, `/memorize <text>`, `/status`, `/init` and `/stop`
+
+`chat` and `repl` use the current directory as the workspace by default and create `.xbot/` there. Use `xbot repl --global` or `xbot chat --global "..."` for the configured global workspace, or `--workspace <path>` for an explicit workspace.
+
+### Manage skills:
+
+```bash
+xbot skills list
+xbot skills init my-custom-skill
+```
+
+## ⚡ Backend Bot
+### Start the backend (Personal AI Assistant):
+
+```bash
+xbot run
+# cargo run --release -- run
+```
+
+`run` uses the configured global workspace by default. Use `xbot run --workspace .` when the backend should run against the current project workspace.
+
+Sending task(s) to `xbot` using configured channels (such as Slack APP).
+
+### Check runtime configuration and local state:
+
+```bash
+xbot status
+xbot sessions
+xbot jobs
+xbot channels status
+xbot skills list
+```
+
+## 📡 Runtime Surfaces
+
+### Channel Backends
+
+- 📧 **email**: IMAP polling + SMTP send
+- 💬 **slack**: Socket Mode or webhook ingress + send
+- ✈️ **telegram**: webhook ingress + send
+- 🦘 **feishu**: webhook ingress + send, including inbound media/resource handling
+- 🔔 **dingtalk**: Stream gateway WebSocket + REST send
+- 🎮 **discord**: Gateway v10 WebSocket + REST send
+- 🏠 **matrix**: CS API v3 long-poll sync + send
+- 📱 **whatsapp**: WebSocket bridge to Node.js Baileys
+- 🐧 **qq**: QQ Bot API WebSocket gateway + REST send
+- 🏢 **wecom**: Enterprise WeChat AI Bot WebSocket
+- 💬 **weixin**: Personal WeChat via HTTP long-poll
+- 🌐 **mochat**: HTTP polling with session/panel support
+- 🔌 **mcp**: stdio-based external tool servers exposed as native tools
+
+### Channel Commands
+
+When messaging the bot through Slack, Telegram, or other channels, you can send these signals as standalone messages:
+
+- `stop` or `/stop` - Immediately stop the current agent task and cancel running subagents.
+- `clear`, `new`, `/clear`, or `/new` - Start a new session and restore `.xbot/memory/HISTORY.md` to the default template.
+- `memorize <text>` or `/memorize <text>` - Store durable user-directed memory in `.xbot/memory/MEMORY.md` through the `memory-entry-writer` summarization skill.
+- `status` or `/status` - Get the current version and runtime usage stats.
+- `help` or `/help` - Show available commands.
+
+### Gateway Endpoints
+
+The gateway exposes:
+
+- ✅ `GET /healthz` - Health check
+- 🟢 `GET /readyz` - Readiness check
+- 📊 `GET /status` - Runtime status
+- 📈 `GET /metrics` - Prometheus metrics
+- 🎛️ `GET /admin` - Web admin UI
+- 🔧 `GET /api/admin/*` - Admin API
+
+## ✅ Verification
+
+```bash
+cargo fmt
+cargo test
+```
+
+## 🎯 Use Cases
+
+- 🤖 **Personal AI Assistant** - Always-on AI assistant across your communication channels
+- 📊 **Automated Monitoring** - Scheduled tasks and webhook-based monitoring
+- 🔧 **DevOps Automation** - Tool execution, file operations, and system management
+- 📝 **Research & Reporting** - Web search, analysis, and report generation
+- 🔄 **CI/CD Integration** - GitHub/CI automation and status updates
+
+---
+
+**Built with ❤️ in Rust** 🦀

package/bin/xbot.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+function targetTriple() {
+  const platform = process.platform;
+  const arch = process.arch;
+  if ((platform !== "linux" && platform !== "darwin") || (arch !== "x64" && arch !== "arm64")) {
+    throw new Error(`Unsupported platform: ${platform}-${arch}. Supported: linux/darwin x64/arm64.`);
+  }
+  return `${platform}-${arch}`;
+}
+
+function main() {
+  const target = targetTriple();
+  const root = path.resolve(__dirname, "..");
+  const binary = path.join(root, "vendor", target, "xbot");
+  if (!fs.existsSync(binary)) {
+    throw new Error(
+      `xbot native binary is missing for ${target}. Reinstall the package or set XBOT_INSTALL_BASE_URL for a custom release mirror.`
+    );
+  }
+
+  const env = { ...process.env };
+  if (!env.XBOT_BUILTIN_SKILLS_DIR) {
+    env.XBOT_BUILTIN_SKILLS_DIR = path.join(root, "skills");
+  }
+
+  const result = spawnSync(binary, process.argv.slice(2), {
+    stdio: "inherit",
+    env
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.signal) {
+    process.kill(process.pid, result.signal);
+  }
+  process.exit(result.status === null ? 1 : result.status);
+}
+
+try {
+  main();
+} catch (err) {
+  console.error(`xbot: ${err.message}`);
+  process.exit(1);
+}

package/docs/ARCHITECTURE.md

@@ -0,0 +1,161 @@
+# xbot Architecture
+
+## Runtime Model
+
+`xbot` is organized as a message-driven runtime:
+
+1. A channel receives inbound user activity.
+2. The channel publishes an `InboundMessage` onto the bus.
+3. `AgentRuntime` acquires a global semaphore permit and a per-session lock, then invokes `AgentLoop`.
+4. `AgentLoop` builds context, calls the model, executes tools, and persists the turn.
+5. Outbound messages are published back onto the bus.
+6. `ChannelManager` delivers outbound messages through the target transport, with retry logic and stream delta support.
+
+This keeps transport, orchestration, and model execution separate. The global semaphore (`max_concurrent_requests`, default 3) prevents unbounded parallel processing, and the per-session mutex ensures messages for the same session are serialized.
+
+## Main Components
+
+| Module | Responsibility |
+| --- | --- |
+| `src/engine/orchestrator.rs` | Agent turn loop, session commands, tool iteration |
+| `src/engine/context.rs` | Runtime context assembly from workspace files, media, and topic-relevant memory |
+| `src/engine/hook.rs` | `AgentHook` trait for lifecycle callbacks (streaming, iteration, tool execution) |
+| `src/storage/session_store.rs` | JSONL-backed session storage |
+| `src/engine/memory.rs` | Permanent memory storage, LLM-driven consolidation, history reset, relevance filtering |
+| `src/tools.rs` | Tool registry and built-in tool implementations |
+| `src/runtime/worker.rs` | Bus worker with global semaphore and per-session serialization |
+| `src/channels/` | Transport adapters, channel manager, stream delta coalescing, and retry logic |
+| `src/runtime/http.rs` | HTTP ingress plus health/readiness/status endpoints |
+| `src/observability.rs` | Runtime telemetry, metrics, provider instrumentation, and system/provider snapshots |
+| `src/cron.rs` | Scheduled jobs and execution history |
+| `src/runtime/heartbeat.rs` | Periodic task review loop |
+| `src/providers/` | Provider clients, Anthropic native support, and registry metadata |
+| `src/runtime/bootstrap.rs` | Backend startup validation, OAuth handling, and provider construction |
+| `src/integrations/mcp.rs` | MCP stdio client and tool registration |
+| `src/cli/channels_cli.rs` | `xbot channels list/status/login` CLI subcommands |
+| `src/cli/skills_cli.rs` | `xbot skills list/init` CLI subcommands |
+
+## Design Choices
+
+### Domain-first module layout
+
+The crate is organized by runtime domain instead of by a flat file list:
+
+- `engine/` owns reasoning, context construction, memory policy, skills, hook lifecycle, and background subtasks
+- `runtime/` owns process wiring, HTTP ingress, validation, concurrency control, and long-running services
+- `storage/` owns session persistence and the internal message bus
+- `channels/` owns transport adapters, stream delta coalescing, and retry logic
+- `providers/` owns model backends, Anthropic native support, and provider metadata
+- `integrations/` owns external protocol bridges such as MCP
+- `observability.rs` owns metrics and monitoring state shared across the runtime
+- `cli/` owns interactive configuration, channel management, and skill management subcommands
+
+That layout keeps operational concerns separate from agent behavior and avoids coupling transports, storage, and orchestration together.
+
+### Trait-based boundaries
+
+Providers, tools, and channels are all expressed as traits. That keeps the runtime swappable and makes transport-specific logic independent from agent execution.
+
+### Message bus orchestration
+
+The bus is the seam between transport and reasoning. Channels do not call the agent directly, and the agent does not know how messages are physically delivered.
+
+### Persistent workspace state
+
+Sessions, memory files, cron jobs, and skills are stored on disk so the runtime can be restarted without losing state.
+
+`MEMORY.md` is the permanent store for durable facts and structured task summaries, while `HISTORY.md` is a resettable event log. The context builder reads only memory slices relevant to the current task instead of injecting the whole file. Completed tasks and `/memorize` requests are condensed into structured memory entries through the `memory-entry-writer` skill before they are appended.
+
+### LLM-driven memory consolidation
+
+When the session exceeds 75% of the context window, the consolidator attempts LLM-driven summarization first: it sends a chunk of older messages to the provider and parses a structured JSON response containing a history entry and an optional durable memory update. If the LLM call fails 3 consecutive times, the consolidator falls back to raw archive (appending message text directly to `HISTORY.md`). This matches nanobot's consolidation strategy while keeping the implementation idiomatic in Rust.
+
+### Hook-based extensibility
+
+The `AgentHook` trait provides lifecycle callbacks (`before_iteration`, `on_stream`, `on_stream_end`, `before_execute_tools`, `after_iteration`, `finalize_content`) that allow extending the agent loop without modifying its core logic. The `CallbackHook` implementation bridges streaming tokens and progress updates to the existing message bus.
+
+### OpenAI-compatible provider contract
+
+`xbot` uses an OpenAI-compatible chat-completions contract as the common provider interface. That keeps remote APIs and local runtimes behind the same operational path.
+
+## Backend Operation
+
+`xbot run` starts:
+
+- provider client
+- agent runtime
+- cron service
+- heartbeat service
+- enabled channels
+- HTTP gateway
+
+The same process also exposes:
+
+- the admin UI
+- the admin JSON API
+- the Prometheus metrics endpoint
+
+The HTTP gateway is operationally useful even when the main traffic is not HTTP because it exposes:
+
+- `GET /healthz`
+- `GET /readyz`
+- `GET /status`
+
+## Channel Model
+
+The currently supported transport set is:
+
+- `email` - IMAP polling + SMTP send
+- `slack` - Socket Mode WebSocket or webhook + REST send
+- `telegram` - webhook + REST send
+- `feishu` - webhook + REST send with media handling
+- `dingtalk` - Stream gateway WebSocket + REST batch send
+- `discord` - Gateway v10 WebSocket + REST send with mention/typing support
+- `matrix` - CS API v3 long-poll `/sync` + REST send
+- `whatsapp` - WebSocket bridge to Node.js Baileys
+- `qq` - QQ Bot API WebSocket gateway + REST send
+- `wecom` - Enterprise WeChat AI Bot WebSocket
+- `weixin` - Personal WeChat via HTTP long-poll (QR login)
+- `mochat` - HTTP polling with session/panel support
+
+Each channel owns:
+
+- its transport-specific config
+- inbound normalization
+- outbound formatting and delivery
+- any channel-specific file/media handling
+- optional `send_delta` for streaming-capable transports
+
+The `ChannelManager` dispatch loop handles:
+
+- stream delta coalescing (`_stream_delta` / `_stream_end` metadata)
+- configurable retry with exponential backoff (`send_max_retries`, default 3)
+- muted tool hint batching and summary generation
+
+## Local Provider Support
+
+Local providers are treated as normal backends when they expose an OpenAI-style API. The runtime does not require an API key for known local engines such as:
+
+- `ollama`
+- `vllm`
+
+Custom local gateways can also be configured through the `custom` provider entry.
+
+## MCP Integration
+
+Enabled MCP servers are connected during agent startup. Their tool definitions are registered into the same tool registry as the built-in filesystem, shell, web, cron, and messaging tools.
+
+Current transport support:
+
+- `stdio`
+
+The startup path validates MCP configuration before the runtime begins serving traffic.
+
+## Testing Strategy
+
+`xbot` uses both module-local unit tests and integration tests:
+
+- unit tests live next to the code for parsing, config validation, and loader behavior
+- integration tests under `tests/` exercise runtime flow, channel behavior, and backend wiring
+
+The split keeps low-level behavior close to its implementation while preserving end-to-end coverage for the public runtime surfaces.

package/docs/HYBRID_MODELS.md

@@ -0,0 +1,156 @@
+# Hybrid Remote Main + Local Subagents
+
+`xbot` can route the main task and background subagents to different model backends.
+
+A common high-value setup is:
+
+- main agent: remote API model such as DeepSeek `deepseek-v4-pro`
+- subagents: local OpenAI-compatible server such as vLLM/Ollama/LM Studio serving Qwen
+
+This gives the main turn a stronger synthesis model while letting subagents spend local GPU capacity on parallel repository search, file reads, tests, and bounded investigations.
+
+## When To Use This
+
+Use hybrid routing when:
+
+- the main answer needs a stronger remote model
+- subagents mostly do bounded exploration or implementation slices
+- you want lower remote API spend during parallel work
+- you have a local GPU box or LAN inference server available
+
+In the TUI, the header and subagent cards show the active main model and subagent model, matching the screenshot in `docs/xbot.png`.
+
+## Prerequisites
+
+You need:
+
+- a configured remote provider API key, for example DeepSeek
+- a local or LAN OpenAI-compatible endpoint for the subagent model
+- the model name exactly as the local endpoint expects it
+
+Example local endpoint:
+
+```text
+http://127.0.0.1:8000/v1
+```
+
+Example LAN endpoint:
+
+```text
+http://10.0.0.50:9000/v1
+```
+
+## Start A Local Qwen Server
+
+One option is vLLM:
+
+```bash
+python -m vllm.entrypoints.openai.api_server \
+  --host 0.0.0.0 \
+  --port 8000 \
+  --model Qwen/Qwen3.6-27B-FP8
+```
+
+Use the model identifier that your server exposes. If your server exposes `Qwen3.6-27B-FP8`, put that exact value in `agents.subagents.model`.
+
+## Configure Interactively
+
+Run:
+
+```bash
+cargo run --release -- config --provider
+```
+
+Use the prompts to:
+
+1. Configure the main provider as `deepseek`.
+2. Input your deepseek api key and select the main model to `deepseek-v4-pro`.
+3. Configure subagents with a separate `custom` provider.
+4. Point subagents at the local OpenAI-compatible `apiBase`.
+
+## Configure Manually
+
+Edit `~/.xbot/config.json`.
+
+Minimal example:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": "deepseek-v4-pro",
+      "provider": "deepseek",
+      "contextWindowTokens": 262144,
+      "maxTokens": 8192,
+      "maxConcurrentTools": 5
+    },
+    "subagents": {
+      "model": "Qwen3.6-27B-FP8",
+      "provider": "local-qwen",
+      "apiBase": "http://127.0.0.1:8000/v1"
+    }
+  },
+  "providers": {
+    "deepseek": {
+      "apiBase": "https://api.deepseek.com",
+      "apiKey": "sk-your-deepseek-key",
+      "extraHeaders": {}
+    },
+    "local-qwen": {
+      "apiBase": "http://127.0.0.1:8000/v1",
+      "apiKey": "",
+      "extraHeaders": {}
+    }
+  }
+}
+```
+
+Notes:
+
+- `agents.defaults` controls the main agent.
+- `agents.subagents` controls spawned background subagents.
+- `agents.subagents.provider` can be any provider key present under `providers`.
+- `agents.subagents.apiBase` overrides the provider API base for subagents.
+- Local or private-network API bases can use an empty `apiKey`.
+- Do not commit real API keys or private endpoint details.
+
+## Verify The Setup
+
+Check the resolved configuration:
+
+```bash
+cargo run --release -- status
+```
+
+Start the TUI:
+
+```bash
+cargo run --release -- repl
+```
+
+Ask for a task that naturally uses delegation, for example:
+
+```text
+review the recent TUI changes and delegate independent checks to subagents
+```
+
+Expected behavior:
+
+- the main header shows the remote main model, for example `deepseek-v4-pro`
+- subagent cards show the local model, for example `Qwen3.6-27B-FP8`
+- subagent tool work uses the local OpenAI-compatible endpoint
+
+## Troubleshooting
+
+If subagents fail to start:
+
+- confirm the local server responds at `/v1/chat/completions`
+- confirm `agents.subagents.model` matches the model name exposed by your server
+- confirm `providers.<subagent-provider>.apiBase` or `agents.subagents.apiBase` includes `/v1`
+- run `cargo run --release -- status` to inspect the active provider/model resolution
+
+If the main agent uses the wrong model:
+
+- set `agents.defaults.provider` explicitly to `deepseek`
+- set `agents.defaults.model` explicitly to `deepseek-v4-pro`
+- remove stale session model metadata by starting a new session with `/new`

package/docs/INSTALLATION.md

@@ -0,0 +1,78 @@
+# Installation
+
+`xbot` supports direct installation without cloning the repository.
+
+## Debian / Ubuntu
+
+Download the `.deb` for your architecture from the GitHub release page, then install it:
+
+```bash
+sudo apt install ./xbot-linux-x64.deb
+```
+
+or:
+
+```bash
+sudo dpkg -i ./xbot-linux-x64.deb
+sudo apt-get install -f
+```
+
+The Debian package installs:
+
+- `/usr/bin/xbot`
+- `/usr/share/xbot/skills`
+- README and license files under `/usr/share/doc/xbot`
+
+No systemd service or `/etc` config is installed in the v1 package. Run `xbot onboard` after installation to create `~/.xbot/config.json` and the default workspace.
+
+## npm
+
+The npm package is published under the `trusted-ai` organization scope.
+
+```bash
+npm install -g @trusted-ai/xbot
+xbot --help
+```
+
+The npm package installs a small Node.js launcher named `xbot`. During `postinstall`, it downloads the matching prebuilt native binary from GitHub Releases, verifies `SHA256SUMS`, and stores it under the package directory.
+
+Supported npm binary targets:
+
+- `linux-x64`
+- `linux-arm64`
+- `darwin-x64`
+- `darwin-arm64`
+
+Optional install environment variables:
+
+- `XBOT_INSTALL_BASE_URL`: override the release artifact base URL
+- `XBOT_INSTALL_VERSION`: override the package version used for artifact names
+- `XBOT_INSTALL_TAG`: override the GitHub release tag
+
+## Cargo
+
+The crates.io package is published as `xbot`.
+
+```bash
+cargo install xbot
+```
+
+The installed binary is named `xbot`.
+
+Before publishing a release, run:
+
+```bash
+cargo package --list
+cargo publish --dry-run
+```
+
+## Source Checkout
+
+Development installs still work with Cargo:
+
+```bash
+cargo run --release -- --help
+cargo build --release
+```
+
+The source checkout automatically uses the repository `skills/` directory as the built-in skills location.