docs: overhaul docs IA and multilingual navigation

NOTICE

@@ -0,0 +1,19 @@
+ZeroClaw
+Copyright 2025 ZeroClaw Labs
+
+This product includes software developed at ZeroClaw Labs (https://github.com/zeroclaw-labs).
+
+Contributors
+============
+
+This NOTICE file is maintained by repository automation.
+For the latest contributor list, see the repository contributors page:
+https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors
+
+Third-Party Dependencies
+========================
+
+This project uses third-party libraries and components,
+each licensed under their respective terms.
+
+See Cargo.lock for a complete dependency list.

README.ja.md

@@ -0,0 +1,161 @@
+<p align="center">
+  <img src="zeroclaw.png" alt="ZeroClaw" width="200" />
+</p>
+
+<h1 align="center">ZeroClaw 🦀（日本語）</h1>
+
+<p align="center">
+  <strong>Zero overhead. Zero compromise. 100% Rust. 100% Agnostic.</strong>
+</p>
+
+<p align="center">
+  🌐 言語: <a href="README.md">English</a> · <a href="README.zh-CN.md">简体中文</a> · <a href="README.ja.md">日本語</a> · <a href="README.ru.md">Русский</a>
+</p>
+
+<p align="center">
+  <a href="bootstrap.sh">ワンクリック導入</a> |
+  <a href="docs/README.ja.md">ドキュメントハブ</a> |
+  <a href="docs/SUMMARY.md">Docs TOC</a> |
+  <a href="docs/commands-reference.md">コマンド</a> |
+  <a href="docs/config-reference.md">設定リファレンス</a> |
+  <a href="docs/providers-reference.md">Provider 参考</a> |
+  <a href="docs/channels-reference.md">Channel 参考</a> |
+  <a href="docs/operations-runbook.md">運用ガイド</a> |
+  <a href="docs/troubleshooting.md">トラブル対応</a> |
+  <a href="CONTRIBUTING.md">貢献ガイド</a>
+</p>
+
+<p align="center">
+  <strong>クイック分流：</strong>
+  <a href="docs/getting-started/README.md">導入</a> ·
+  <a href="docs/reference/README.md">参照</a> ·
+  <a href="docs/operations/README.md">運用</a> ·
+  <a href="docs/troubleshooting.md">障害対応</a> ·
+  <a href="docs/security/README.md">セキュリティ</a> ·
+  <a href="docs/hardware/README.md">ハードウェア</a> ·
+  <a href="docs/contributing/README.md">貢献・CI</a>
+</p>
+
+> この文書は `README.md` の内容を、正確性と可読性を重視して日本語に整えた版です（逐語訳ではありません）。
+>
+> コマンド名、設定キー、API パス、Trait 名などの技術識別子は英語のまま維持しています。
+>
+> 最終同期日: **2026-02-18**。
+
+## 概要
+
+ZeroClaw は、高速・省リソース・高拡張性を重視した自律エージェント実行基盤です。
+
+- Rust ネイティブ実装、単一バイナリで配布可能
+- Trait ベース設計（`Provider` / `Channel` / `Tool` / `Memory` など）
+- セキュアデフォルト（ペアリング、明示 allowlist、サンドボックス、スコープ制御）
+
+## ZeroClaw が選ばれる理由
+
+- **軽量**: 小さいバイナリ、低メモリ、速い起動
+- **拡張性**: 28+ の built-in provider（エイリアス含む）+ custom endpoint
+- **運用性**: `daemon` / `doctor` / `status` / `service` で保守しやすい
+- **統合性**: 多チャネル + 70+ integrations
+
+## 再現可能な計測（例）
+
+README のサンプル値（macOS arm64, 2026-02-18）:
+
+- Release バイナリ: `8.8M`
+- `zeroclaw --help`: 約 `0.02s`、ピークメモリ 約 `3.9MB`
+- `zeroclaw status`: 約 `0.01s`、ピークメモリ 約 `4.1MB`
+
+環境差があるため、必ず自身の環境で再計測してください。
+
+```bash
+cargo build --release
+ls -lh target/release/zeroclaw
+
+/usr/bin/time -l target/release/zeroclaw --help
+/usr/bin/time -l target/release/zeroclaw status
+```
+
+## ワンクリック導入
+
+```bash
+git clone https://github.com/zeroclaw-labs/zeroclaw.git
+cd zeroclaw
+./bootstrap.sh
+```
+
+環境ごと初期化する場合: `./bootstrap.sh --install-system-deps --install-rust`（システムパッケージで `sudo` が必要な場合があります）。
+
+詳細は [`docs/one-click-bootstrap.md`](docs/one-click-bootstrap.md) を参照してください。
+
+## クイックスタート
+
+```bash
+git clone https://github.com/zeroclaw-labs/zeroclaw.git
+cd zeroclaw
+cargo build --release --locked
+cargo install --path . --force --locked
+
+zeroclaw onboard --api-key sk-... --provider openrouter
+zeroclaw onboard --interactive
+
+zeroclaw agent -m "Hello, ZeroClaw!"
+
+# default: 127.0.0.1:3000
+zeroclaw gateway
+
+zeroclaw daemon
+```
+
+## セキュリティのデフォルト
+
+- Gateway の既定バインド: `127.0.0.1:3000`
+- 既定でペアリング必須: `require_pairing = true`
+- 既定で公開バインド禁止: `allow_public_bind = false`
+- Channel allowlist:
+  - `[]` は deny-by-default
+  - `["*"]` は allow all（意図的に使う場合のみ）
+
+## 設定例
+
+```toml
+api_key = "sk-..."
+default_provider = "openrouter"
+default_model = "anthropic/claude-sonnet-4"
+default_temperature = 0.7
+
+[memory]
+backend = "sqlite"
+auto_save = true
+embedding_provider = "none"
+
+[gateway]
+host = "127.0.0.1"
+port = 3000
+require_pairing = true
+allow_public_bind = false
+```
+
+## ドキュメント入口
+
+- ドキュメントハブ（英語）: [`docs/README.md`](docs/README.md)
+- 統合 TOC: [`docs/SUMMARY.md`](docs/SUMMARY.md)
+- ドキュメントハブ（日本語）: [`docs/README.ja.md`](docs/README.ja.md)
+- コマンドリファレンス: [`docs/commands-reference.md`](docs/commands-reference.md)
+- 設定リファレンス: [`docs/config-reference.md`](docs/config-reference.md)
+- Provider リファレンス: [`docs/providers-reference.md`](docs/providers-reference.md)
+- Channel リファレンス: [`docs/channels-reference.md`](docs/channels-reference.md)
+- 運用ガイド（Runbook）: [`docs/operations-runbook.md`](docs/operations-runbook.md)
+- トラブルシューティング: [`docs/troubleshooting.md`](docs/troubleshooting.md)
+- ドキュメント一覧 / 分類: [`docs/docs-inventory.md`](docs/docs-inventory.md)
+- プロジェクト triage スナップショット: [`docs/project-triage-snapshot-2026-02-18.md`](docs/project-triage-snapshot-2026-02-18.md)
+
+## コントリビュート / ライセンス
+
+- Contributing: [`CONTRIBUTING.md`](CONTRIBUTING.md)
+- PR Workflow: [`docs/pr-workflow.md`](docs/pr-workflow.md)
+- Reviewer Playbook: [`docs/reviewer-playbook.md`](docs/reviewer-playbook.md)
+- License: MIT（[`LICENSE`](LICENSE), [`NOTICE`](NOTICE)）
+
+---
+
+詳細仕様（全コマンド、アーキテクチャ、API 仕様、開発フロー）は英語版の [`README.md`](README.md) を参照してください。

README.md

@@ -18,12 +18,42 @@
 Built by students and members of the Harvard, MIT, and Sundai.Club communities.
 </p>
 
+<p align="center">
+  🌐 <strong>Languages:</strong> <a href="README.md">English</a> · <a href="README.zh-CN.md">简体中文</a> · <a href="README.ja.md">日本語</a> · <a href="README.ru.md">Русский</a>
+</p>
+
+<p align="center">
+  <a href="#quick-start">Getting Started</a> |
+  <a href="bootstrap.sh">One-Click Setup</a> |
+  <a href="docs/README.md">Documentation</a> |
+  <a href="docs/SUMMARY.md">Docs TOC</a> |
+  <a href="docs/commands-reference.md">Commands</a> |
+  <a href="docs/config-reference.md">Config</a> |
+  <a href="docs/providers-reference.md">Providers</a> |
+  <a href="docs/channels-reference.md">Channels</a> |
+  <a href="docs/operations-runbook.md">Runbook</a> |
+  <a href="docs/troubleshooting.md">Troubleshooting</a> |
+  <a href="CONTRIBUTING.md">Contributing</a> |
+  <a href="SECURITY.md">Security</a>
+</p>
+
+<p align="center">
+  <strong>Quick Routes:</strong>
+  <a href="docs/getting-started/README.md">Setup</a> ·
+  <a href="docs/reference/README.md">Reference</a> ·
+  <a href="docs/operations/README.md">Operations</a> ·
+  <a href="docs/troubleshooting.md">Troubleshoot</a> ·
+  <a href="docs/security/README.md">Security</a> ·
+  <a href="docs/hardware/README.md">Hardware</a> ·
+  <a href="docs/contributing/README.md">Contribute</a>
+</p>
+
 <p align="center">
   <strong>Fast, small, and fully autonomous AI assistant infrastructure</strong><br />
   Deploy anywhere. Swap anything.
 </p>
 
-<p align="center"><code>~3.4MB binary · &lt;10ms startup · 1,017 tests · 23+ providers · 8 traits · Pluggable everything</code></p>
+<p align="center"><code>Trait-driven architecture · secure-by-default runtime · provider/channel/tool swappable · pluggable everything</code></p>
 
 ### ✨ Features
 
@@ -39,25 +69,11 @@ Built by students and members of the Harvard, MIT, and Sundai.Club communities.
 - **Fully swappable:** core systems are traits (providers, channels, tools, memory, tunnels).
 - **No lock-in:** OpenAI-compatible provider support + pluggable custom endpoints.
 
-## Benchmark Snapshot (ZeroClaw vs OpenClaw)
+## Benchmark Snapshot (Reproducible)
 
-Local machine quick benchmark (macOS arm64, Feb 2026) normalized for 0.8GHz edge hardware.
+Benchmark claims can drift as code and toolchains evolve, so this section focuses on reproducible local measurement.
 
-| | OpenClaw | NanoBot | PicoClaw | ZeroClaw 🦀 |
-|---|---|---|---|---|
-| **Language** | TypeScript | Python | Go | **Rust** |
-| **RAM** | > 1GB | > 100MB | < 10MB | **< 5MB** |
-| **Startup (0.8GHz core)** | > 500s | > 30s | < 1s | **< 10ms** |
-| **Binary Size** | ~28MB (dist) | N/A (Scripts) | ~8MB | **3.4 MB** |
-| **Cost** | Mac Mini $599 | Linux SBC ~$50 | Linux Board $10 | **Any hardware $10** |
-
-> Notes: ZeroClaw results measured with `/usr/bin/time -l` on release builds. OpenClaw requires Node.js runtime (~390MB overhead). PicoClaw and ZeroClaw are static binaries.
-
-<p align="center">
-  <img src="zero-claw.jpeg" alt="ZeroClaw vs OpenClaw Comparison" width="800" />
-</p>
-
-Reproduce ZeroClaw numbers locally:
+Measure your current build locally:
 
 ```bash
 cargo build --release
@@ -67,6 +83,12 @@ ls -lh target/release/zeroclaw
 /usr/bin/time -l target/release/zeroclaw status
 ```
 
+Example sample (macOS arm64, measured on February 18, 2026):
+
+- Release binary size: `8.8M`
+- `zeroclaw --help`: about `0.02s` real time, ~`3.9MB` peak memory footprint
+- `zeroclaw status`: about `0.01s` real time, ~`4.1MB` peak memory footprint
+
 ## Prerequisites
 
 <details>
@@ -139,6 +161,29 @@ curl -LsSf https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts
 
 ## Quick Start
 
+### One-click bootstrap
+
+```bash
+# Recommended: clone then run local bootstrap script
+git clone https://github.com/zeroclaw-labs/zeroclaw.git
+cd zeroclaw
+./bootstrap.sh
+
+# Optional: bootstrap dependencies + Rust on fresh machines
+./bootstrap.sh --install-system-deps --install-rust
+
+# Optional: run onboarding in the same flow
+./bootstrap.sh --onboard --api-key "sk-..." --provider openrouter
+```
+
+Remote one-liner (review first in security-sensitive environments):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts/bootstrap.sh | bash
+```
+
+Details: [`docs/one-click-bootstrap.md`](docs/one-click-bootstrap.md) (toolchain mode may request `sudo` for system packages).
+
 ```bash
 git clone https://github.com/zeroclaw-labs/zeroclaw.git
 cd zeroclaw
@@ -164,7 +209,7 @@ zeroclaw agent -m "Hello, ZeroClaw!"
 zeroclaw agent
 
 # Start the gateway (webhook server)
-zeroclaw gateway                # default: 127.0.0.1:8080
+zeroclaw gateway                # default: 127.0.0.1:3000
 zeroclaw gateway --port 0       # random port (security hardened)
 
 # Start full autonomous runtime
@@ -255,18 +300,18 @@ Every subsystem is a **trait** — swap implementations with a config change, ze
 
 | Subsystem | Trait | Ships with | Extend |
 |-----------|-------|------------|--------|
-| **AI Models** | `Provider` | 23+ providers (OpenRouter, Anthropic, OpenAI, Ollama, Venice, Groq, Mistral, xAI, DeepSeek, Together, Fireworks, Perplexity, Cohere, Bedrock, Astrai, etc.) | `custom:https://your-api.com` — any OpenAI-compatible API |
-| **Channels** | `Channel` | CLI, Telegram, Discord, Slack, Mattermost, iMessage, Matrix, WhatsApp, Webhook | Any messaging API |
-| **Memory** | `Memory` | SQLite with hybrid search (FTS5 + vector cosine similarity), Lucid bridge (CLI sync + SQLite fallback), Markdown | Any persistence backend |
-| **Tools** | `Tool` | shell, file_read, file_write, memory_store, memory_recall, memory_forget, browser_open (Brave + allowlist), browser (agent-browser / rust-native), composio (optional) | Any capability |
+| **AI Models** | `Provider` | Provider catalog via `zeroclaw providers` (currently 28 built-ins + aliases, plus custom endpoints) | `custom:https://your-api.com` (OpenAI-compatible) or `anthropic-custom:https://your-api.com` |
+| **Channels** | `Channel` | CLI, Telegram, Discord, Slack, Mattermost, iMessage, Matrix, Signal, WhatsApp, Email, IRC, Lark, DingTalk, QQ, Webhook | Any messaging API |
+| **Memory** | `Memory` | SQLite hybrid search, Lucid bridge, Markdown files, explicit `none` backend, snapshot/hydrate, optional response cache | Any persistence backend |
+| **Tools** | `Tool` | shell/file/memory, cron/schedule, git, pushover, browser, http_request, screenshot/image_info, composio (opt-in), delegate, hardware tools | Any capability |
 | **Observability** | `Observer` | Noop, Log, Multi | Prometheus, OTel |
-| **Runtime** | `RuntimeAdapter` | Native, Docker (sandboxed) | WASM (planned; unsupported kinds fail fast) |
+| **Runtime** | `RuntimeAdapter` | Native, Docker (sandboxed) | Additional runtimes can be added via adapter; unsupported kinds fail fast |
 | **Security** | `SecurityPolicy` | Gateway pairing, sandbox, allowlists, rate limits, filesystem scoping, encrypted secrets | — |
 | **Identity** | `IdentityConfig` | OpenClaw (markdown), AIEOS v1.1 (JSON) | Any identity format |
 | **Tunnel** | `Tunnel` | None, Cloudflare, Tailscale, ngrok, Custom | Any tunnel binary |
 | **Heartbeat** | Engine | HEARTBEAT.md periodic tasks | — |
 | **Skills** | Loader | TOML manifests + SKILL.md instructions | Community skill packs |
-| **Integrations** | Registry | 50+ integrations across 9 categories | Plugin system |
+| **Integrations** | Registry | 70+ integrations across 9 categories | Plugin system |
 
 ### Runtime support (current)
 
@@ -295,7 +340,7 @@ The agent automatically recalls, saves, and manages memory via tools.
 [memory]
 backend = "sqlite"          # "sqlite", "lucid", "markdown", "none"
 auto_save = true
-embedding_provider = "openai"
+embedding_provider = "none"  # "none", "openai", "custom:https://..."
 vector_weight = 0.7
 keyword_weight = 0.3
 
@@ -328,7 +373,7 @@ ZeroClaw enforces security at **every layer** — not just the sandbox. It passe
 
 > **Run your own nmap:** `nmap -p 1-65535 <your-host>` — ZeroClaw binds to localhost only, so nothing is exposed unless you explicitly configure a tunnel.
 
-### Channel allowlists (Telegram / Discord / Slack / Mattermost)
+### Channel allowlists (deny-by-default)
 
 Inbound sender policy is now consistent:
 
@@ -412,7 +457,7 @@ WhatsApp uses Meta's Cloud API with webhooks (push-based, not polling):
 
 4. **Start the gateway with a tunnel:**
    ```bash
-   zeroclaw gateway --port 8080
+   zeroclaw gateway --port 3000
    ```
    WhatsApp requires HTTPS, so use a tunnel (ngrok, Cloudflare, Tailscale Funnel).
 
@@ -431,7 +476,7 @@ Config: `~/.zeroclaw/config.toml` (created by `onboard`)
 ```toml
 api_key = "sk-..."
 default_provider = "openrouter"
-default_model = "anthropic/claude-sonnet-4-20250514"
+default_model = "anthropic/claude-sonnet-4"
 default_temperature = 0.7
 
 # Custom OpenAI-compatible endpoint
@@ -443,13 +488,15 @@ default_temperature = 0.7
 [memory]
 backend = "sqlite"              # "sqlite", "lucid", "markdown", "none"
 auto_save = true
-embedding_provider = "openai"   # "openai", "noop"
+embedding_provider = "none"     # "none", "openai", "custom:https://..."
 vector_weight = 0.7
 keyword_weight = 0.3
 
 # backend = "none" disables persistent memory via no-op backend
 
 [gateway]
+port = 3000                      # default
+host = "127.0.0.1"              # default
 require_pairing = true          # require pairing code on first connect
 allow_public_bind = false       # refuse 0.0.0.0 without tunnel
 
@@ -652,28 +699,32 @@ See [aieos.org](https://aieos.org) for the full schema and live examples.
 |----------|--------|------|-------------|
 | `/health` | GET | None | Health check (always public, no secrets leaked) |
 | `/pair` | POST | `X-Pairing-Code` header | Exchange one-time code for bearer token |
-| `/webhook` | POST | `Authorization: Bearer <token>` | Send message: `{"message": "your prompt"}` |
+| `/webhook` | POST | `Authorization: Bearer <token>` | Send message: `{"message": "your prompt"}`; optional `X-Idempotency-Key` |
 | `/whatsapp` | GET | Query params | Meta webhook verification (hub.mode, hub.verify_token, hub.challenge) |
-| `/whatsapp` | POST | None (Meta signature) | WhatsApp incoming message webhook |
+| `/whatsapp` | POST | Meta signature (`X-Hub-Signature-256`) when app secret is configured | WhatsApp incoming message webhook |
 
 ## Commands
 
 | Command | Description |
 |---------|-------------|
 | `onboard` | Quick setup (default) |
-| `onboard --interactive` | Full interactive 7-step wizard |
-| `onboard --channels-only` | Reconfigure channels/allowlists only (fast repair flow) |
-| `agent -m "..."` | Single message mode |
-| `agent` | Interactive chat mode |
-| `gateway` | Start webhook server (default: `127.0.0.1:8080`) |
-| `gateway --port 0` | Random port mode |
+| `agent` | Interactive or single-message chat mode |
+| `gateway` | Start webhook server (default: `127.0.0.1:3000`) |
 | `daemon` | Start long-running autonomous runtime |
-| `service install/start/stop/status/uninstall` | Manage user-level background service |
+| `service` | Manage user-level background service |
 | `doctor` | Diagnose daemon/scheduler/channel freshness |
 | `status` | Show full system status |
-| `channel doctor` | Run health checks for configured channels |
-| `channel bind-telegram <IDENTITY>` | Add one Telegram username/user ID to allowlist |
-| `integrations info <name>` | Show setup/status details for one integration |
+| `cron` | Manage scheduled tasks (`list/add/add-at/add-every/once/remove/pause/resume`) |
+| `models` | Refresh provider model catalogs (`models refresh`) |
+| `providers` | List supported providers and aliases |
+| `channel` | List/start/doctor channels and bind Telegram identities |
+| `integrations` | Inspect integration setup details |
+| `skills` | List/install/remove skills |
+| `migrate` | Import data from other runtimes (`migrate openclaw`) |
+| `hardware` | USB discover/introspect/info commands |
+| `peripheral` | Manage and flash hardware peripherals |
+
+For a task-oriented command guide, see [`docs/commands-reference.md`](docs/commands-reference.md).
 
 ## Development
 
@@ -681,8 +732,8 @@ See [aieos.org](https://aieos.org) for the full schema and live examples.
 cargo build              # Dev build
 cargo build --release    # Release build (codegen-units=1, works on all devices including Raspberry Pi)
 cargo build --profile release-fast    # Faster build (codegen-units=8, requires 16GB+ RAM)
-cargo test               # 1,017 tests
-cargo clippy             # Lint (0 warnings)
+cargo test               # Run full test suite
+cargo clippy --locked --all-targets -- -D clippy::correctness
 cargo fmt                # Format
 
 # Run the SQLite vs Markdown benchmark
@@ -717,7 +768,20 @@ git push --no-verify
 
 ## Collaboration & Docs
 
-For high-throughput collaboration and consistent reviews:
+Start from the docs hub for a task-based map:
+
+- Documentation hub: [`docs/README.md`](docs/README.md)
+- Unified docs TOC: [`docs/SUMMARY.md`](docs/SUMMARY.md)
+- Commands reference: [`docs/commands-reference.md`](docs/commands-reference.md)
+- Config reference: [`docs/config-reference.md`](docs/config-reference.md)
+- Providers reference: [`docs/providers-reference.md`](docs/providers-reference.md)
+- Channels reference: [`docs/channels-reference.md`](docs/channels-reference.md)
+- Operations runbook: [`docs/operations-runbook.md`](docs/operations-runbook.md)
+- Troubleshooting: [`docs/troubleshooting.md`](docs/troubleshooting.md)
+- Docs inventory/classification: [`docs/docs-inventory.md`](docs/docs-inventory.md)
+- PR/Issue triage snapshot (as of February 18, 2026): [`docs/project-triage-snapshot-2026-02-18.md`](docs/project-triage-snapshot-2026-02-18.md)
+
+Core collaboration references:
 
 - Contribution guide: [CONTRIBUTING.md](CONTRIBUTING.md)
 - PR workflow policy: [docs/pr-workflow.md](docs/pr-workflow.md)

README.ru.md

@@ -0,0 +1,161 @@
+<p align="center">
+  <img src="zeroclaw.png" alt="ZeroClaw" width="200" />
+</p>
+
+<h1 align="center">ZeroClaw 🦀（Русский）</h1>
+
+<p align="center">
+  <strong>Zero overhead. Zero compromise. 100% Rust. 100% Agnostic.</strong>
+</p>
+
+<p align="center">
+  🌐 Языки: <a href="README.md">English</a> · <a href="README.zh-CN.md">简体中文</a> · <a href="README.ja.md">日本語</a> · <a href="README.ru.md">Русский</a>
+</p>
+
+<p align="center">
+  <a href="bootstrap.sh">Установка в 1 клик</a> |
+  <a href="docs/README.ru.md">Хаб документации</a> |
+  <a href="docs/SUMMARY.md">TOC docs</a> |
+  <a href="docs/commands-reference.md">Команды</a> |
+  <a href="docs/config-reference.md">Конфиг</a> |
+  <a href="docs/providers-reference.md">Providers</a> |
+  <a href="docs/channels-reference.md">Channels</a> |
+  <a href="docs/operations-runbook.md">Операции</a> |
+  <a href="docs/troubleshooting.md">Диагностика</a> |
+  <a href="CONTRIBUTING.md">Вклад</a>
+</p>
+
+<p align="center">
+  <strong>Быстрые маршруты:</strong>
+  <a href="docs/getting-started/README.md">Старт</a> ·
+  <a href="docs/reference/README.md">Справочники</a> ·
+  <a href="docs/operations/README.md">Операции</a> ·
+  <a href="docs/troubleshooting.md">Диагностика</a> ·
+  <a href="docs/security/README.md">Безопасность</a> ·
+  <a href="docs/hardware/README.md">Аппаратная часть</a> ·
+  <a href="docs/contributing/README.md">Вклад и CI</a>
+</p>
+
+> Этот файл — выверенный перевод `README.md` с акцентом на точность и читаемость (не дословный перевод).
+>
+> Технические идентификаторы (команды, ключи конфигурации, API-пути, имена Trait) сохранены на английском.
+>
+> Последняя синхронизация: **2026-02-18**.
+
+## О проекте
+
+ZeroClaw — это производительная и расширяемая инфраструктура автономного AI-агента:
+
+- Нативно на Rust, единый бинарник, переносимость между ARM / x86 / RISC-V
+- Архитектура на Trait (`Provider`, `Channel`, `Tool`, `Memory` и др.)
+- Безопасные значения по умолчанию: pairing, явные allowlist, sandbox и scope-ограничения
+
+## Почему выбирают ZeroClaw
+
+- **Лёгкий**: небольшой бинарник, низкое потребление памяти, быстрый старт
+- **Расширяемый**: 28+ built-in providers (с алиасами) + custom совместимые endpoint
+- **Удобный в эксплуатации**: `daemon`, `doctor`, `status`, `service`
+- **Интеграции**: много каналов + 70+ integrations
+
+## Воспроизводимые метрики (пример)
+
+Текущие примерные значения из README (macOS arm64, 2026-02-18):
+
+- Размер release-бинарника: `8.8M`
+- `zeroclaw --help`: ~`0.02s`, пик памяти ~`3.9MB`
+- `zeroclaw status`: ~`0.01s`, пик памяти ~`4.1MB`
+
+Проверяйте производительность в своей среде:
+
+```bash
+cargo build --release
+ls -lh target/release/zeroclaw
+
+/usr/bin/time -l target/release/zeroclaw --help
+/usr/bin/time -l target/release/zeroclaw status
+```
+
+## Установка в 1 клик
+
+```bash
+git clone https://github.com/zeroclaw-labs/zeroclaw.git
+cd zeroclaw
+./bootstrap.sh
+```
+
+Для полной инициализации окружения: `./bootstrap.sh --install-system-deps --install-rust` (для системных пакетов может потребоваться `sudo`).
+
+Подробности: [`docs/one-click-bootstrap.md`](docs/one-click-bootstrap.md).
+
+## Быстрый старт
+
+```bash
+git clone https://github.com/zeroclaw-labs/zeroclaw.git
+cd zeroclaw
+cargo build --release --locked
+cargo install --path . --force --locked
+
+zeroclaw onboard --api-key sk-... --provider openrouter
+zeroclaw onboard --interactive
+
+zeroclaw agent -m "Hello, ZeroClaw!"
+
+# default: 127.0.0.1:3000
+zeroclaw gateway
+
+zeroclaw daemon
+```
+
+## Важные security-дефолты
+
+- Gateway по умолчанию: `127.0.0.1:3000`
+- Pairing обязателен по умолчанию: `require_pairing = true`
+- Публичный bind запрещён по умолчанию: `allow_public_bind = false`
+- Семантика allowlist каналов:
+  - `[]` => deny-by-default
+  - `["*"]` => allow all (используйте осознанно)
+
+## Пример конфигурации
+
+```toml
+api_key = "sk-..."
+default_provider = "openrouter"
+default_model = "anthropic/claude-sonnet-4"
+default_temperature = 0.7
+
+[memory]
+backend = "sqlite"
+auto_save = true
+embedding_provider = "none"
+
+[gateway]
+host = "127.0.0.1"
+port = 3000
+require_pairing = true
+allow_public_bind = false
+```
+
+## Навигация по документации
+
+- Хаб документации (English): [`docs/README.md`](docs/README.md)
+- Единый TOC docs: [`docs/SUMMARY.md`](docs/SUMMARY.md)
+- Хаб документации (Русский): [`docs/README.ru.md`](docs/README.ru.md)
+- Справочник команд: [`docs/commands-reference.md`](docs/commands-reference.md)
+- Справочник конфигурации: [`docs/config-reference.md`](docs/config-reference.md)
+- Справочник providers: [`docs/providers-reference.md`](docs/providers-reference.md)
+- Справочник channels: [`docs/channels-reference.md`](docs/channels-reference.md)
+- Операционный runbook: [`docs/operations-runbook.md`](docs/operations-runbook.md)
+- Устранение неполадок: [`docs/troubleshooting.md`](docs/troubleshooting.md)
+- Инвентарь и классификация docs: [`docs/docs-inventory.md`](docs/docs-inventory.md)
+- Снимок triage проекта: [`docs/project-triage-snapshot-2026-02-18.md`](docs/project-triage-snapshot-2026-02-18.md)
+
+## Вклад и лицензия
+
+- Contribution guide: [`CONTRIBUTING.md`](CONTRIBUTING.md)
+- PR workflow: [`docs/pr-workflow.md`](docs/pr-workflow.md)
+- Reviewer playbook: [`docs/reviewer-playbook.md`](docs/reviewer-playbook.md)
+- License: MIT ([`LICENSE`](LICENSE), [`NOTICE`](NOTICE))
+
+---
+
+Для полной и исчерпывающей информации (архитектура, все команды, API, разработка) используйте основной английский документ: [`README.md`](README.md).

README.zh-CN.md

@@ -0,0 +1,166 @@
+<p align="center">
+  <img src="zeroclaw.png" alt="ZeroClaw" width="200" />
+</p>
+
+<h1 align="center">ZeroClaw 🦀（简体中文）</h1>
+
+<p align="center">
+  <strong>Zero overhead. Zero compromise. 100% Rust. 100% Agnostic.</strong>
+</p>
+
+<p align="center">
+  🌐 语言：<a href="README.md">English</a> · <a href="README.zh-CN.md">简体中文</a> · <a href="README.ja.md">日本語</a> · <a href="README.ru.md">Русский</a>
+</p>
+
+<p align="center">
+  <a href="bootstrap.sh">一键部署</a> |
+  <a href="docs/README.zh-CN.md">文档总览</a> |
+  <a href="docs/SUMMARY.md">文档目录</a> |
+  <a href="docs/commands-reference.md">命令参考</a> |
+  <a href="docs/config-reference.md">配置参考</a> |
+  <a href="docs/providers-reference.md">Provider 参考</a> |
+  <a href="docs/channels-reference.md">Channel 参考</a> |
+  <a href="docs/operations-runbook.md">运维手册</a> |
+  <a href="docs/troubleshooting.md">故障排查</a> |
+  <a href="CONTRIBUTING.md">贡献指南</a>
+</p>
+
+<p align="center">
+  <strong>场景分流：</strong>
+  <a href="docs/getting-started/README.md">安装入门</a> ·
+  <a href="docs/reference/README.md">参考手册</a> ·
+  <a href="docs/operations/README.md">运维部署</a> ·
+  <a href="docs/troubleshooting.md">故障排查</a> ·
+  <a href="docs/security/README.md">安全专题</a> ·
+  <a href="docs/hardware/README.md">硬件外设</a> ·
+  <a href="docs/contributing/README.md">贡献与 CI</a>
+</p>
+
+> 本文是对 `README.md` 的人工对齐翻译（强调可读性与准确性，不做逐字直译）。
+> 
+> 技术标识（命令、配置键、API 路径、Trait 名称）保持英文，避免语义漂移。
+> 
+> 最后对齐时间：**2026-02-18**。
+
+## 项目简介
+
+ZeroClaw 是一个高性能、低资源占用、可组合的自主智能体运行时：
+
+- Rust 原生实现，单二进制部署，跨 ARM / x86 / RISC-V。
+- Trait 驱动架构，`Provider` / `Channel` / `Tool` / `Memory` 可替换。
+- 安全默认值优先：配对鉴权、显式 allowlist、沙箱与作用域约束。
+
+## 为什么选择 ZeroClaw
+
+- **轻量**：小体积二进制，低内存占用，启动快。
+- **可扩展**：支持 28+ 内置 provider（含别名）以及自定义兼容端点。
+- **可运维**：具备 `daemon`、`doctor`、`status`、`service` 等运维命令。
+- **可集成**：多渠道（Telegram、Discord、Slack、Matrix、WhatsApp、Email、IRC、Lark、DingTalk、QQ 等）与 70+ integrations。
+
+## 可复现基准（示例）
+
+以下是当前 README 中的样例数据（macOS arm64，2026-02-18）：
+
+- Release 二进制：`8.8M`
+- `zeroclaw --help`：约 `0.02s`，峰值内存约 `3.9MB`
+- `zeroclaw status`：约 `0.01s`，峰值内存约 `4.1MB`
+
+建议始终在你的目标环境自行复测：
+
+```bash
+cargo build --release
+ls -lh target/release/zeroclaw
+
+/usr/bin/time -l target/release/zeroclaw --help
+/usr/bin/time -l target/release/zeroclaw status
+```
+
+## 一键部署
+
+```bash
+git clone https://github.com/zeroclaw-labs/zeroclaw.git
+cd zeroclaw
+./bootstrap.sh
+```
+
+可选环境初始化：`./bootstrap.sh --install-system-deps --install-rust`（可能需要 `sudo`）。
+
+详细说明见：[`docs/one-click-bootstrap.md`](docs/one-click-bootstrap.md)。
+
+## 快速开始
+
+```bash
+git clone https://github.com/zeroclaw-labs/zeroclaw.git
+cd zeroclaw
+cargo build --release --locked
+cargo install --path . --force --locked
+
+# 快速初始化（无交互）
+zeroclaw onboard --api-key sk-... --provider openrouter
+
+# 或使用交互式向导
+zeroclaw onboard --interactive
+
+# 单次对话
+zeroclaw agent -m "Hello, ZeroClaw!"
+
+# 启动网关（默认: 127.0.0.1:3000）
+zeroclaw gateway
+
+# 启动长期运行模式
+zeroclaw daemon
+```
+
+## 安全默认行为（关键）
+
+- Gateway 默认绑定：`127.0.0.1:3000`
+- Gateway 默认要求配对：`require_pairing = true`
+- 默认拒绝公网绑定：`allow_public_bind = false`
+- Channel allowlist 语义：
+  - 空列表 `[]` => deny-by-default
+  - `"*"` => allow all（仅在明确知道风险时使用）
+
+## 常用配置片段
+
+```toml
+api_key = "sk-..."
+default_provider = "openrouter"
+default_model = "anthropic/claude-sonnet-4"
+default_temperature = 0.7
+
+[memory]
+backend = "sqlite"              # sqlite | lucid | markdown | none
+auto_save = true
+embedding_provider = "none"     # none | openai | custom:https://...
+
+[gateway]
+host = "127.0.0.1"
+port = 3000
+require_pairing = true
+allow_public_bind = false
+```
+
+## 文档导航（推荐从这里开始）
+
+- 文档总览（英文）：[`docs/README.md`](docs/README.md)
+- 统一目录（TOC）：[`docs/SUMMARY.md`](docs/SUMMARY.md)
+- 文档总览（简体中文）：[`docs/README.zh-CN.md`](docs/README.zh-CN.md)
+- 命令参考：[`docs/commands-reference.md`](docs/commands-reference.md)
+- 配置参考：[`docs/config-reference.md`](docs/config-reference.md)
+- Provider 参考：[`docs/providers-reference.md`](docs/providers-reference.md)
+- Channel 参考：[`docs/channels-reference.md`](docs/channels-reference.md)
+- 运维手册：[`docs/operations-runbook.md`](docs/operations-runbook.md)
+- 故障排查：[`docs/troubleshooting.md`](docs/troubleshooting.md)
+- 文档清单与分类：[`docs/docs-inventory.md`](docs/docs-inventory.md)
+- 项目 triage 快照（2026-02-18）：[`docs/project-triage-snapshot-2026-02-18.md`](docs/project-triage-snapshot-2026-02-18.md)
+
+## 贡献与许可证
+
+- 贡献指南：[`CONTRIBUTING.md`](CONTRIBUTING.md)
+- PR 工作流：[`docs/pr-workflow.md`](docs/pr-workflow.md)
+- Reviewer 指南：[`docs/reviewer-playbook.md`](docs/reviewer-playbook.md)
+- 许可证：MIT（见 [`LICENSE`](LICENSE) 与 [`NOTICE`](NOTICE)）
+
+---
+
+如果你需要完整实现细节（架构图、全部命令、完整 API、开发流程），请直接阅读英文主文档：[`README.md`](README.md)。

bootstrap.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec "$ROOT_DIR/scripts/bootstrap.sh" "$@"

docs/README.ja.md

@@ -0,0 +1,82 @@
+# ZeroClaw ドキュメントハブ（日本語）
+
+このページは日本語のドキュメント入口です。
+
+最終同期日: **2026-02-18**。
+
+> 注: コマンド名・設定キー・API パスは英語のまま記載します。実装の一次情報は英語版ドキュメントを優先してください。
+
+## すぐに参照したい項目
+
+| やりたいこと | 参照先 |
+|---|---|
+| すぐにセットアップしたい | [../README.ja.md](../README.ja.md) / [../README.md](../README.md) |
+| ワンコマンドで導入したい | [one-click-bootstrap.md](one-click-bootstrap.md) |
+| コマンドを用途別に確認したい | [commands-reference.md](commands-reference.md) |
+| 設定キーと既定値を確認したい | [config-reference.md](config-reference.md) |
+| 日常運用（runbook）を確認したい | [operations-runbook.md](operations-runbook.md) |
+| インストール/実行トラブルを解決したい | [troubleshooting.md](troubleshooting.md) |
+| 統合 TOC から探したい | [SUMMARY.md](SUMMARY.md) |
+| PR/Issue の現状を把握したい | [project-triage-snapshot-2026-02-18.md](project-triage-snapshot-2026-02-18.md) |
+
+## 10秒ルーティング（まずここ）
+
+- 初回セットアップや導入をしたい → [getting-started/README.md](getting-started/README.md)
+- CLI/設定キーを正確に確認したい → [reference/README.md](reference/README.md)
+- 本番運用やサービス管理をしたい → [operations/README.md](operations/README.md)
+- エラーや不具合を解消したい → [troubleshooting.md](troubleshooting.md)
+- セキュリティ方針やロードマップを見たい → [security/README.md](security/README.md)
+- ボード/周辺機器を扱いたい → [hardware/README.md](hardware/README.md)
+- 貢献・レビュー・CIを確認したい → [contributing/README.md](contributing/README.md)
+- 全体マップを見たい → [SUMMARY.md](SUMMARY.md)
+
+## カテゴリ別ナビゲーション（推奨）
+
+- 入門: [getting-started/README.md](getting-started/README.md)
+- リファレンス: [reference/README.md](reference/README.md)
+- 運用 / デプロイ: [operations/README.md](operations/README.md)
+- セキュリティ: [security/README.md](security/README.md)
+- ハードウェア: [hardware/README.md](hardware/README.md)
+- コントリビュート / CI: [contributing/README.md](contributing/README.md)
+- プロジェクトスナップショット: [project/README.md](project/README.md)
+
+## ロール別
+
+### ユーザー / オペレーター
+
+- [commands-reference.md](commands-reference.md)
+- [providers-reference.md](providers-reference.md)
+- [channels-reference.md](channels-reference.md)
+- [config-reference.md](config-reference.md)
+- [operations-runbook.md](operations-runbook.md)
+- [troubleshooting.md](troubleshooting.md)
+
+### コントリビューター / メンテナー
+
+- [../CONTRIBUTING.md](../CONTRIBUTING.md)
+- [pr-workflow.md](pr-workflow.md)
+- [reviewer-playbook.md](reviewer-playbook.md)
+- [ci-map.md](ci-map.md)
+- [actions-source-policy.md](actions-source-policy.md)
+
+### セキュリティ / 信頼性
+
+> 注: このセクションには proposal/roadmap 文書が含まれ、想定段階のコマンドや設定が記載される場合があります。現行動作は [config-reference.md](config-reference.md)、[operations-runbook.md](operations-runbook.md)、[troubleshooting.md](troubleshooting.md) を優先してください。
+
+- [security/README.md](security/README.md)
+- [agnostic-security.md](agnostic-security.md)
+- [sandboxing.md](sandboxing.md)
+- [resource-limits.md](resource-limits.md)
+- [audit-logging.md](audit-logging.md)
+- [security-roadmap.md](security-roadmap.md)
+
+## ドキュメント運用 / 分類
+
+- 統合 TOC: [SUMMARY.md](SUMMARY.md)
+- ドキュメント一覧 / 分類: [docs-inventory.md](docs-inventory.md)
+
+## 他言語
+
+- English: [README.md](README.md)
+- 简体中文: [README.zh-CN.md](README.zh-CN.md)
+- Русский: [README.ru.md](README.ru.md)

docs/README.md

@@ -0,0 +1,78 @@
+# ZeroClaw Documentation Hub
+
+This page is the primary entry point for the documentation system.
+
+Last refreshed: **February 18, 2026**.
+
+Localized hubs: [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [Русский](README.ru.md).
+
+## Start Here
+
+| I want to… | Read this |
+|---|---|
+| Install and run ZeroClaw quickly | [README.md (Quick Start)](../README.md#quick-start) |
+| Bootstrap in one command | [one-click-bootstrap.md](one-click-bootstrap.md) |
+| Find commands by task | [commands-reference.md](commands-reference.md) |
+| Check config defaults and keys quickly | [config-reference.md](config-reference.md) |
+| Operate runtime (day-2 runbook) | [operations-runbook.md](operations-runbook.md) |
+| Troubleshoot install/runtime/channel issues | [troubleshooting.md](troubleshooting.md) |
+| Browse docs by category | [SUMMARY.md](SUMMARY.md) |
+| See project PR/issue docs snapshot | [project-triage-snapshot-2026-02-18.md](project-triage-snapshot-2026-02-18.md) |
+
+## Quick Decision Tree (10 seconds)
+
+- Need first-time setup or install? → [getting-started/README.md](getting-started/README.md)
+- Need exact CLI/config keys? → [reference/README.md](reference/README.md)
+- Need production/service operations? → [operations/README.md](operations/README.md)
+- Seeing failures or regressions? → [troubleshooting.md](troubleshooting.md)
+- Working on security hardening or roadmap? → [security/README.md](security/README.md)
+- Working with boards/peripherals? → [hardware/README.md](hardware/README.md)
+- Contributing/reviewing/CI workflow? → [contributing/README.md](contributing/README.md)
+- Want the full map? → [SUMMARY.md](SUMMARY.md)
+
+## Collections (Recommended)
+
+- Getting started: [getting-started/README.md](getting-started/README.md)
+- Reference catalogs: [reference/README.md](reference/README.md)
+- Operations & deployment: [operations/README.md](operations/README.md)
+- Security docs: [security/README.md](security/README.md)
+- Hardware/peripherals: [hardware/README.md](hardware/README.md)
+- Contributing/CI: [contributing/README.md](contributing/README.md)
+- Project snapshots: [project/README.md](project/README.md)
+
+## By Audience
+
+### Users / Operators
+
+- [commands-reference.md](commands-reference.md) — command lookup by workflow
+- [providers-reference.md](providers-reference.md) — provider IDs, aliases, credential env vars
+- [channels-reference.md](channels-reference.md) — channel capabilities and setup paths
+- [config-reference.md](config-reference.md) — high-signal config keys and secure defaults
+- [operations-runbook.md](operations-runbook.md) — day-2 runtime operations and rollback flow
+- [troubleshooting.md](troubleshooting.md) — common failure signatures and recovery steps
+
+### Contributors / Maintainers
+
+- [../CONTRIBUTING.md](../CONTRIBUTING.md)
+- [pr-workflow.md](pr-workflow.md)
+- [reviewer-playbook.md](reviewer-playbook.md)
+- [ci-map.md](ci-map.md)
+- [actions-source-policy.md](actions-source-policy.md)
+
+### Security / Reliability
+
+> Note: this area includes proposal/roadmap docs. For current behavior, start with [config-reference.md](config-reference.md), [operations-runbook.md](operations-runbook.md), and [troubleshooting.md](troubleshooting.md).
+
+- [security/README.md](security/README.md)
+- [agnostic-security.md](agnostic-security.md)
+- [frictionless-security.md](frictionless-security.md)
+- [sandboxing.md](sandboxing.md)
+- [audit-logging.md](audit-logging.md)
+- [resource-limits.md](resource-limits.md)
+- [security-roadmap.md](security-roadmap.md)
+
+## System Navigation & Governance
+
+- Unified TOC: [SUMMARY.md](SUMMARY.md)
+- Documentation inventory/classification: [docs-inventory.md](docs-inventory.md)
+- Project triage snapshot: [project-triage-snapshot-2026-02-18.md](project-triage-snapshot-2026-02-18.md)

docs/README.ru.md

@@ -0,0 +1,82 @@
+# Документация ZeroClaw (Русский)
+
+Эта страница — русскоязычная точка входа в документацию.
+
+Последняя синхронизация: **2026-02-18**.
+
+> Примечание: команды, ключи конфигурации и API-пути сохраняются на английском. Для первоисточника ориентируйтесь на англоязычные документы.
+
+## Быстрые ссылки
+
+| Что нужно | Куда смотреть |
+|---|---|
+| Быстро установить и запустить | [../README.ru.md](../README.ru.md) / [../README.md](../README.md) |
+| Установить одной командой | [one-click-bootstrap.md](one-click-bootstrap.md) |
+| Найти команды по задаче | [commands-reference.md](commands-reference.md) |
+| Проверить ключи конфигурации и дефолты | [config-reference.md](config-reference.md) |
+| Операционный runbook (day-2) | [operations-runbook.md](operations-runbook.md) |
+| Быстро устранить типовые проблемы | [troubleshooting.md](troubleshooting.md) |
+| Открыть общий TOC docs | [SUMMARY.md](SUMMARY.md) |
+| Посмотреть snapshot PR/Issue | [project-triage-snapshot-2026-02-18.md](project-triage-snapshot-2026-02-18.md) |
+
+## Дерево решений на 10 секунд
+
+- Нужна первая установка и быстрый старт → [getting-started/README.md](getting-started/README.md)
+- Нужны точные команды и ключи конфигурации → [reference/README.md](reference/README.md)
+- Нужны операции/сервисный режим/деплой → [operations/README.md](operations/README.md)
+- Есть ошибки, сбои или регрессии → [troubleshooting.md](troubleshooting.md)
+- Нужны материалы по безопасности и roadmap → [security/README.md](security/README.md)
+- Работаете с платами и периферией → [hardware/README.md](hardware/README.md)
+- Нужны процессы вклада, ревью и CI → [contributing/README.md](contributing/README.md)
+- Нужна полная карта docs → [SUMMARY.md](SUMMARY.md)
+
+## Навигация по категориям (рекомендуется)
+
+- Старт и установка: [getting-started/README.md](getting-started/README.md)
+- Справочники: [reference/README.md](reference/README.md)
+- Операции и деплой: [operations/README.md](operations/README.md)
+- Безопасность: [security/README.md](security/README.md)
+- Аппаратная часть: [hardware/README.md](hardware/README.md)
+- Вклад и CI: [contributing/README.md](contributing/README.md)
+- Снимки проекта: [project/README.md](project/README.md)
+
+## По ролям
+
+### Пользователи / Операторы
+
+- [commands-reference.md](commands-reference.md)
+- [providers-reference.md](providers-reference.md)
+- [channels-reference.md](channels-reference.md)
+- [config-reference.md](config-reference.md)
+- [operations-runbook.md](operations-runbook.md)
+- [troubleshooting.md](troubleshooting.md)
+
+### Контрибьюторы / Мейнтейнеры
+
+- [../CONTRIBUTING.md](../CONTRIBUTING.md)
+- [pr-workflow.md](pr-workflow.md)
+- [reviewer-playbook.md](reviewer-playbook.md)
+- [ci-map.md](ci-map.md)
+- [actions-source-policy.md](actions-source-policy.md)
+
+### Безопасность / Надёжность
+
+> Примечание: часть документов в этом разделе относится к proposal/roadmap и может содержать гипотетические команды/конфигурации. Для текущего поведения сначала смотрите [config-reference.md](config-reference.md), [operations-runbook.md](operations-runbook.md), [troubleshooting.md](troubleshooting.md).
+
+- [security/README.md](security/README.md)
+- [agnostic-security.md](agnostic-security.md)
+- [sandboxing.md](sandboxing.md)
+- [resource-limits.md](resource-limits.md)
+- [audit-logging.md](audit-logging.md)
+- [security-roadmap.md](security-roadmap.md)
+
+## Инвентаризация и структура docs
+
+- Единый TOC: [SUMMARY.md](SUMMARY.md)
+- Инвентарь и классификация docs: [docs-inventory.md](docs-inventory.md)
+
+## Другие языки
+
+- English: [README.md](README.md)
+- 简体中文: [README.zh-CN.md](README.zh-CN.md)
+- 日本語: [README.ja.md](README.ja.md)

docs/README.zh-CN.md

@@ -0,0 +1,82 @@
+# ZeroClaw 文档导航（简体中文）
+
+这是文档系统的中文入口页。
+
+最后对齐：**2026-02-18**。
+
+> 说明：命令、配置键、API 路径保持英文；实现细节以英文文档为准。
+
+## 快速入口
+
+| 我想要… | 建议阅读 |
+|---|---|
+| 快速安装并运行 | [../README.zh-CN.md](../README.zh-CN.md) / [../README.md](../README.md) |
+| 一键安装与初始化 | [one-click-bootstrap.md](one-click-bootstrap.md) |
+| 按任务找命令 | [commands-reference.md](commands-reference.md) |
+| 快速查看配置默认值与关键项 | [config-reference.md](config-reference.md) |
+| 进行日常运维（runbook） | [operations-runbook.md](operations-runbook.md) |
+| 快速排查安装/运行问题 | [troubleshooting.md](troubleshooting.md) |
+| 统一目录导航 | [SUMMARY.md](SUMMARY.md) |
+| 查看 PR/Issue 扫描快照 | [project-triage-snapshot-2026-02-18.md](project-triage-snapshot-2026-02-18.md) |
+
+## 10 秒决策树（先看这个）
+
+- 首次安装或快速启动 → [getting-started/README.md](getting-started/README.md)
+- 需要精确命令或配置键 → [reference/README.md](reference/README.md)
+- 需要部署与服务化运维 → [operations/README.md](operations/README.md)
+- 遇到报错、异常或回归 → [troubleshooting.md](troubleshooting.md)
+- 查看安全现状与路线图 → [security/README.md](security/README.md)
+- 接入板卡与外设 → [hardware/README.md](hardware/README.md)
+- 参与贡献、评审与 CI → [contributing/README.md](contributing/README.md)
+- 查看完整文档地图 → [SUMMARY.md](SUMMARY.md)
+
+## 按目录浏览（推荐）
+
+- 入门文档： [getting-started/README.md](getting-started/README.md)
+- 参考手册： [reference/README.md](reference/README.md)
+- 运维与部署： [operations/README.md](operations/README.md)
+- 安全文档： [security/README.md](security/README.md)
+- 硬件与外设： [hardware/README.md](hardware/README.md)
+- 贡献与 CI： [contributing/README.md](contributing/README.md)
+- 项目快照： [project/README.md](project/README.md)
+
+## 按角色
+
+### 用户 / 运维
+
+- [commands-reference.md](commands-reference.md)
+- [providers-reference.md](providers-reference.md)
+- [channels-reference.md](channels-reference.md)
+- [config-reference.md](config-reference.md)
+- [operations-runbook.md](operations-runbook.md)
+- [troubleshooting.md](troubleshooting.md)
+
+### 贡献者 / 维护者
+
+- [../CONTRIBUTING.md](../CONTRIBUTING.md)
+- [pr-workflow.md](pr-workflow.md)
+- [reviewer-playbook.md](reviewer-playbook.md)
+- [ci-map.md](ci-map.md)
+- [actions-source-policy.md](actions-source-policy.md)
+
+### 安全 / 稳定性
+
+> 说明：本分组内有 proposal/roadmap 文档，可能包含设想中的命令或配置。当前可执行行为请优先阅读 [config-reference.md](config-reference.md)、[operations-runbook.md](operations-runbook.md)、[troubleshooting.md](troubleshooting.md)。
+
+- [security/README.md](security/README.md)
+- [agnostic-security.md](agnostic-security.md)
+- [sandboxing.md](sandboxing.md)
+- [resource-limits.md](resource-limits.md)
+- [audit-logging.md](audit-logging.md)
+- [security-roadmap.md](security-roadmap.md)
+
+## 文档治理与分类
+
+- 统一目录（TOC）：[SUMMARY.md](SUMMARY.md)
+- 文档清单与分类：[docs-inventory.md](docs-inventory.md)
+
+## 其他语言
+
+- English: [README.md](README.md)
+- 日本語: [README.ja.md](README.ja.md)
+- Русский: [README.ru.md](README.ru.md)

docs/SUMMARY.md

@@ -0,0 +1,72 @@
+# ZeroClaw Docs Summary (Unified TOC)
+
+This file is the canonical table of contents for the documentation system.
+
+Last refreshed: **February 18, 2026**.
+
+## Language Entry
+
+- English README: [../README.md](../README.md)
+- Chinese README: [../README.zh-CN.md](../README.zh-CN.md)
+- Japanese README: [../README.ja.md](../README.ja.md)
+- Russian README: [../README.ru.md](../README.ru.md)
+- English Docs Hub: [README.md](README.md)
+- Chinese Docs Hub: [README.zh-CN.md](README.zh-CN.md)
+- Japanese Docs Hub: [README.ja.md](README.ja.md)
+- Russian Docs Hub: [README.ru.md](README.ru.md)
+
+## Collections
+
+### 1) Getting Started
+
+- [getting-started/README.md](getting-started/README.md)
+- [one-click-bootstrap.md](one-click-bootstrap.md)
+
+### 2) Command/Config References
+
+- [reference/README.md](reference/README.md)
+- [commands-reference.md](commands-reference.md)
+- [providers-reference.md](providers-reference.md)
+- [channels-reference.md](channels-reference.md)
+- [config-reference.md](config-reference.md)
+
+### 3) Operations & Deployment
+
+- [operations/README.md](operations/README.md)
+- [operations-runbook.md](operations-runbook.md)
+- [troubleshooting.md](troubleshooting.md)
+- [network-deployment.md](network-deployment.md)
+- [mattermost-setup.md](mattermost-setup.md)
+
+### 4) Security Design & Proposals
+
+- [security/README.md](security/README.md)
+- [agnostic-security.md](agnostic-security.md)
+- [frictionless-security.md](frictionless-security.md)
+- [sandboxing.md](sandboxing.md)
+- [resource-limits.md](resource-limits.md)
+- [audit-logging.md](audit-logging.md)
+- [security-roadmap.md](security-roadmap.md)
+
+### 5) Hardware & Peripherals
+
+- [hardware/README.md](hardware/README.md)
+- [hardware-peripherals-design.md](hardware-peripherals-design.md)
+- [adding-boards-and-tools.md](adding-boards-and-tools.md)
+- [nucleo-setup.md](nucleo-setup.md)
+- [arduino-uno-q-setup.md](arduino-uno-q-setup.md)
+
+### 6) Contribution & CI
+
+- [contributing/README.md](contributing/README.md)
+- [../CONTRIBUTING.md](../CONTRIBUTING.md)
+- [pr-workflow.md](pr-workflow.md)
+- [reviewer-playbook.md](reviewer-playbook.md)
+- [ci-map.md](ci-map.md)
+- [actions-source-policy.md](actions-source-policy.md)
+
+### 7) Project Status & Snapshot
+
+- [project/README.md](project/README.md)
+- [project-triage-snapshot-2026-02-18.md](project-triage-snapshot-2026-02-18.md)
+- [docs-inventory.md](docs-inventory.md)

docs/adding-boards-and-tools.md

@@ -11,7 +11,7 @@ zeroclaw peripheral add arduino-uno /dev/cu.usbmodem12345
 zeroclaw peripheral add rpi-gpio native   # for Raspberry Pi GPIO (Linux)
 
 # Restart daemon to apply
-zeroclaw daemon --host 127.0.0.1 --port 8080
+zeroclaw daemon --host 127.0.0.1 --port 3000
 ```
 
 ## Supported Boards

docs/agnostic-security.md

@@ -1,5 +1,10 @@
 # Agnostic Security: Zero Impact on Portability
 
+> ⚠️ **Status: Proposal / Roadmap**
+>
+> This document describes proposed approaches and may include hypothetical commands or config.
+> For current runtime behavior, see [config-reference.md](config-reference.md), [operations-runbook.md](operations-runbook.md), and [troubleshooting.md](troubleshooting.md).
+
 ## Core Question: Will security features break...
 1. ❓ Fast cross-compilation builds?
 2. ❓ Pluggable architecture (swap anything)?

docs/arduino-uno-q-setup.md

@@ -130,7 +130,7 @@ allowed_users = ["*"]
 
 [gateway]
 host = "127.0.0.1"
-port = 8080
+port = 3000
 allow_public_bind = false
 
 [agent]
@@ -145,7 +145,7 @@ compact_context = true
 ssh arduino@<UNO_Q_IP>
 
 # Run daemon (Telegram polling works over WiFi)
-zeroclaw daemon --host 127.0.0.1 --port 8080
+zeroclaw daemon --host 127.0.0.1 --port 3000
 ```
 
 **At this point:** Telegram chat works. Send messages to your bot — ZeroClaw responds. No GPIO yet.
@@ -184,7 +184,7 @@ transport = "bridge"
 ### 5.3 Run ZeroClaw
 
 ```bash
-zeroclaw daemon --host 127.0.0.1 --port 8080
+zeroclaw daemon --host 127.0.0.1 --port 3000
 ```
 
 Now when you message your Telegram bot *"Turn on the LED"* or *"Set pin 13 high"*, ZeroClaw uses `gpio_write` via the Bridge.
@@ -203,7 +203,7 @@ Now when you message your Telegram bot *"Turn on the LED"* or *"Set pin 13 high"
 | 6 | `cargo build --release --no-default-features` |
 | 7 | `zeroclaw onboard --api-key KEY --provider openrouter` |
 | 8 | Edit `~/.zeroclaw/config.toml` (add Telegram bot_token) |
-| 9 | `zeroclaw daemon --host 127.0.0.1 --port 8080` |
+| 9 | `zeroclaw daemon --host 127.0.0.1 --port 3000` |
 | 10 | Message your Telegram bot — it responds |
 
 ---

docs/audit-logging.md

@@ -1,5 +1,10 @@
 # Audit Logging for ZeroClaw
 
+> ⚠️ **Status: Proposal / Roadmap**
+>
+> This document describes proposed approaches and may include hypothetical commands or config.
+> For current runtime behavior, see [config-reference.md](config-reference.md), [operations-runbook.md](operations-runbook.md), and [troubleshooting.md](troubleshooting.md).
+
 ## Problem
 ZeroClaw logs actions but lacks tamper-evident audit trails for:
 - Who executed what command

docs/channels-reference.md

@@ -0,0 +1,105 @@
+# ZeroClaw Channels Reference
+
+This reference maps channel capabilities, config blocks, allowlist behavior, and setup paths.
+
+Last verified: **February 18, 2026**.
+
+## Quick Commands
+
+```bash
+zeroclaw channel list
+zeroclaw channel start
+zeroclaw channel doctor
+zeroclaw channel bind-telegram <IDENTITY>
+```
+
+## Channel Matrix
+
+| Channel | Config section | Access control field | Setup path |
+|---|---|---|---|
+| `CLI` | n/a (always enabled) | n/a | Built-in |
+| `Telegram` | `[channels_config.telegram]` | `allowed_users` | `zeroclaw onboard` |
+| `Discord` | `[channels_config.discord]` | `allowed_users` | `zeroclaw onboard` |
+| `Slack` | `[channels_config.slack]` | `allowed_users` | `zeroclaw onboard` |
+| `Mattermost` | `[channels_config.mattermost]` | `allowed_users` | Manual config |
+| `Webhook` | `[channels_config.webhook]` | n/a (`secret` optional) | `zeroclaw onboard` or manual |
+| `iMessage` | `[channels_config.imessage]` | `allowed_contacts` | `zeroclaw onboard` (macOS) |
+| `Matrix` | `[channels_config.matrix]` | `allowed_users` | `zeroclaw onboard` |
+| `Signal` | `[channels_config.signal]` | `allowed_from` | Manual config |
+| `WhatsApp` | `[channels_config.whatsapp]` | `allowed_numbers` | `zeroclaw onboard` |
+| `Email` | `[channels_config.email]` | `allowed_senders` | Manual config |
+| `IRC` | `[channels_config.irc]` | `allowed_users` | `zeroclaw onboard` |
+| `Lark` | `[channels_config.lark]` | `allowed_users` | Manual config |
+| `DingTalk` | `[channels_config.dingtalk]` | `allowed_users` | `zeroclaw onboard` |
+| `QQ` | `[channels_config.qq]` | `allowed_users` | `zeroclaw onboard` |
+
+## Deny-by-Default Rules
+
+For channel allowlists, the runtime behavior is intentionally strict:
+
+- Empty allowlist (`[]`) means **deny all**.
+- Wildcard (`["*"]`) means **allow all**.
+- Explicit IDs are exact matches unless channel-specific docs state otherwise.
+
+### Telegram pairing bootstrap
+
+Telegram has a secure bootstrap flow:
+
+- Keep `allowed_users = []` to start in pairing mode.
+- Run `zeroclaw channel bind-telegram <IDENTITY>` to add one identity safely.
+- After binding, restart long-running channel processes if needed (`daemon` / `channel start`).
+
+## Minimal Config Examples
+
+### Telegram
+
+```toml
+[channels_config.telegram]
+bot_token = "123456:ABCDEF"
+allowed_users = []
+```
+
+### WhatsApp
+
+```toml
+[channels_config.whatsapp]
+access_token = "EAABx..."
+phone_number_id = "123456789012345"
+verify_token = "your-verify-token"
+allowed_numbers = ["+1234567890"]
+```
+
+### Signal
+
+```toml
+[channels_config.signal]
+http_url = "http://127.0.0.1:8686"
+account = "+1234567890"
+allowed_from = ["+1987654321"]
+ignore_attachments = true
+ignore_stories = true
+```
+
+### Lark
+
+```toml
+[channels_config.lark]
+app_id = "cli_xxx"
+app_secret = "xxx"
+allowed_users = ["ou_abc"]
+receive_mode = "websocket"   # or "webhook"
+# port = 3100                  # required only when receive_mode = "webhook"
+```
+
+## Operational Notes
+
+- `zeroclaw channel add/remove` is intentionally not a full config mutator yet; use `zeroclaw onboard` or edit `~/.zeroclaw/config.toml`.
+- `zeroclaw channel doctor` validates configured channel health and prints timeout/unhealthy status.
+- If `webhook` is configured, doctor guidance points to gateway health check (`GET /health`).
+
+## Related Docs
+
+- [README.md (Channel allowlists)](../README.md#channel-allowlists-deny-by-default)
+- [network-deployment.md](network-deployment.md)
+- [mattermost-setup.md](mattermost-setup.md)
+- [commands-reference.md](commands-reference.md)

docs/commands-reference.md

@@ -0,0 +1,121 @@
+# ZeroClaw Commands Reference
+
+This reference is derived from the current CLI surface (`zeroclaw --help`).
+
+Last verified: **February 18, 2026**.
+
+## Top-Level Commands
+
+| Command | Purpose |
+|---|---|
+| `onboard` | Initialize workspace/config quickly or interactively |
+| `agent` | Run interactive chat or single-message mode |
+| `gateway` | Start webhook and WhatsApp HTTP gateway |
+| `daemon` | Start supervised runtime (gateway + channels + optional heartbeat/scheduler) |
+| `service` | Manage user-level OS service lifecycle |
+| `doctor` | Run diagnostics and freshness checks |
+| `status` | Print current configuration and system summary |
+| `cron` | Manage scheduled tasks |
+| `models` | Refresh provider model catalogs |
+| `providers` | List provider IDs, aliases, and active provider |
+| `channel` | Manage channels and channel health checks |
+| `integrations` | Inspect integration details |
+| `skills` | List/install/remove skills |
+| `migrate` | Import from external runtimes (currently OpenClaw) |
+| `hardware` | Discover and introspect USB hardware |
+| `peripheral` | Configure and flash peripherals |
+
+## Command Groups
+
+### `onboard`
+
+- `zeroclaw onboard`
+- `zeroclaw onboard --interactive`
+- `zeroclaw onboard --channels-only`
+- `zeroclaw onboard --api-key <KEY> --provider <ID> --memory <sqlite|lucid|markdown|none>`
+
+### `agent`
+
+- `zeroclaw agent`
+- `zeroclaw agent -m "Hello"`
+- `zeroclaw agent --provider <ID> --model <MODEL> --temperature <0.0-2.0>`
+- `zeroclaw agent --peripheral <board:path>`
+
+### `gateway` / `daemon`
+
+- `zeroclaw gateway [--host <HOST>] [--port <PORT>]`
+- `zeroclaw daemon [--host <HOST>] [--port <PORT>]`
+
+### `service`
+
+- `zeroclaw service install`
+- `zeroclaw service start`
+- `zeroclaw service stop`
+- `zeroclaw service status`
+- `zeroclaw service uninstall`
+
+### `cron`
+
+- `zeroclaw cron list`
+- `zeroclaw cron add <expr> [--tz <IANA_TZ>] <command>`
+- `zeroclaw cron add-at <rfc3339_timestamp> <command>`
+- `zeroclaw cron add-every <every_ms> <command>`
+- `zeroclaw cron once <delay> <command>`
+- `zeroclaw cron remove <id>`
+- `zeroclaw cron pause <id>`
+- `zeroclaw cron resume <id>`
+
+### `models`
+
+- `zeroclaw models refresh`
+- `zeroclaw models refresh --provider <ID>`
+- `zeroclaw models refresh --force`
+
+### `channel`
+
+- `zeroclaw channel list`
+- `zeroclaw channel start`
+- `zeroclaw channel doctor`
+- `zeroclaw channel bind-telegram <IDENTITY>`
+- `zeroclaw channel add <type> <json>`
+- `zeroclaw channel remove <name>`
+
+`add/remove` currently route you back to managed setup/manual config paths (not full declarative mutators yet).
+
+### `integrations`
+
+- `zeroclaw integrations info <name>`
+
+### `skills`
+
+- `zeroclaw skills list`
+- `zeroclaw skills install <source>`
+- `zeroclaw skills remove <name>`
+
+### `migrate`
+
+- `zeroclaw migrate openclaw [--source <path>] [--dry-run]`
+
+### `hardware`
+
+- `zeroclaw hardware discover`
+- `zeroclaw hardware introspect <path>`
+- `zeroclaw hardware info [--chip <chip_name>]`
+
+### `peripheral`
+
+- `zeroclaw peripheral list`
+- `zeroclaw peripheral add <board> <path>`
+- `zeroclaw peripheral flash [--port <serial_port>]`
+- `zeroclaw peripheral setup-uno-q [--host <ip_or_host>]`
+- `zeroclaw peripheral flash-nucleo`
+
+## Validation Tip
+
+To verify docs against your current binary quickly:
+
+```bash
+zeroclaw --help
+zeroclaw <command> --help
+```
+

docs/config-reference.md

@@ -0,0 +1,72 @@
+# ZeroClaw Config Reference (Operator-Oriented)
+
+This is a high-signal reference for common config sections and defaults.
+
+Last verified: **February 18, 2026**.
+
+Config file path:
+
+- `~/.zeroclaw/config.toml`
+
+## Core Keys
+
+| Key | Default | Notes |
+|---|---|---|
+| `default_provider` | `openrouter` | provider ID or alias |
+| `default_model` | `anthropic/claude-sonnet-4` | model routed through selected provider |
+| `default_temperature` | `0.7` | model temperature |
+
+## `[gateway]`
+
+| Key | Default | Purpose |
+|---|---|---|
+| `host` | `127.0.0.1` | bind address |
+| `port` | `3000` | gateway listen port |
+| `require_pairing` | `true` | require pairing before bearer auth |
+| `allow_public_bind` | `false` | block accidental public exposure |
+
+## `[memory]`
+
+| Key | Default | Purpose |
+|---|---|---|
+| `backend` | `sqlite` | `sqlite`, `lucid`, `markdown`, `none` |
+| `auto_save` | `true` | automatic persistence |
+| `embedding_provider` | `none` | `none`, `openai`, or custom endpoint |
+| `vector_weight` | `0.7` | hybrid ranking vector weight |
+| `keyword_weight` | `0.3` | hybrid ranking keyword weight |
+
+## `[channels_config]`
+
+Top-level channel options are configured under `channels_config`.
+
+Examples:
+
+- `[channels_config.telegram]`
+- `[channels_config.discord]`
+- `[channels_config.whatsapp]`
+- `[channels_config.email]`
+
+See detailed channel matrix and allowlist behavior in [channels-reference.md](channels-reference.md).
+
+## Security-Relevant Defaults
+
+- deny-by-default channel allowlists (`[]` means deny all)
+- pairing required on gateway by default
+- public bind disabled by default
+
+## Validation Commands
+
+After editing config:
+
+```bash
+zeroclaw status
+zeroclaw doctor
+zeroclaw channel doctor
+```
+
+## Related Docs
+
+- [channels-reference.md](channels-reference.md)
+- [providers-reference.md](providers-reference.md)
+- [operations-runbook.md](operations-runbook.md)
+- [troubleshooting.md](troubleshooting.md)

docs/contributing/README.md

@@ -0,0 +1,18 @@
+# Contributing, Review, and CI Docs
+
+For contributors, reviewers, and maintainers.
+
+## Core Policies
+
+- Contribution guide: [../../CONTRIBUTING.md](../../CONTRIBUTING.md)
+- PR workflow rules: [../pr-workflow.md](../pr-workflow.md)
+- Reviewer playbook: [../reviewer-playbook.md](../reviewer-playbook.md)
+- CI map and ownership: [../ci-map.md](../ci-map.md)
+- Actions source policy: [../actions-source-policy.md](../actions-source-policy.md)
+
+## Suggested Reading Order
+
+1. `CONTRIBUTING.md`
+2. `docs/pr-workflow.md`
+3. `docs/reviewer-playbook.md`
+4. `docs/ci-map.md`

docs/docs-inventory.md

@@ -0,0 +1,95 @@
+# ZeroClaw Documentation Inventory
+
+This inventory classifies docs by intent so readers can quickly distinguish runtime-contract guides from design proposals.
+
+Last reviewed: **February 18, 2026**.
+
+## Classification Legend
+
+- **Current Guide/Reference**: intended to match current runtime behavior
+- **Policy/Process**: collaboration or governance rules
+- **Proposal/Roadmap**: design exploration; may include hypothetical commands
+- **Snapshot**: time-bound operational report
+
+## Documentation Entry Points
+
+| Doc | Type | Audience |
+|---|---|---|
+| `README.md` | Current Guide | all readers |
+| `README.zh-CN.md` | Current Guide (localized) | Chinese readers |
+| `README.ja.md` | Current Guide (localized) | Japanese readers |
+| `README.ru.md` | Current Guide (localized) | Russian readers |
+| `docs/README.md` | Current Guide (hub) | all readers |
+| `docs/README.zh-CN.md` | Current Guide (localized hub) | Chinese readers |
+| `docs/README.ja.md` | Current Guide (localized hub) | Japanese readers |
+| `docs/README.ru.md` | Current Guide (localized hub) | Russian readers |
+| `docs/SUMMARY.md` | Current Guide (unified TOC) | all readers |
+
+## Collection Index Docs
+
+| Doc | Type | Audience |
+|---|---|---|
+| `docs/getting-started/README.md` | Current Guide | new users |
+| `docs/reference/README.md` | Current Guide | users/operators |
+| `docs/operations/README.md` | Current Guide | operators |
+| `docs/security/README.md` | Current Guide | operators/contributors |
+| `docs/hardware/README.md` | Current Guide | hardware builders |
+| `docs/contributing/README.md` | Current Guide | contributors/reviewers |
+| `docs/project/README.md` | Current Guide | maintainers |
+
+## Current Guides & References
+
+| Doc | Type | Audience |
+|---|---|---|
+| `docs/one-click-bootstrap.md` | Current Guide | users/operators |
+| `docs/commands-reference.md` | Current Reference | users/operators |
+| `docs/providers-reference.md` | Current Reference | users/operators |
+| `docs/channels-reference.md` | Current Reference | users/operators |
+| `docs/config-reference.md` | Current Reference | operators |
+| `docs/operations-runbook.md` | Current Guide | operators |
+| `docs/troubleshooting.md` | Current Guide | users/operators |
+| `docs/network-deployment.md` | Current Guide | operators |
+| `docs/mattermost-setup.md` | Current Guide | operators |
+| `docs/adding-boards-and-tools.md` | Current Guide | hardware builders |
+| `docs/arduino-uno-q-setup.md` | Current Guide | hardware builders |
+| `docs/nucleo-setup.md` | Current Guide | hardware builders |
+| `docs/hardware-peripherals-design.md` | Current Design Spec | hardware contributors |
+| `docs/langgraph-integration.md` | Current Integration Guide | integration developers |
+
+## Policy / Process Docs
+
+| Doc | Type |
+|---|---|
+| `docs/pr-workflow.md` | Policy |
+| `docs/reviewer-playbook.md` | Process |
+| `docs/ci-map.md` | Process |
+| `docs/actions-source-policy.md` | Policy |
+
+## Proposal / Roadmap Docs
+
+These are valuable context, but **not strict runtime contracts**.
+
+| Doc | Type |
+|---|---|
+| `docs/sandboxing.md` | Proposal |
+| `docs/resource-limits.md` | Proposal |
+| `docs/audit-logging.md` | Proposal |
+| `docs/agnostic-security.md` | Proposal |
+| `docs/frictionless-security.md` | Proposal |
+| `docs/security-roadmap.md` | Roadmap |
+
+## Snapshot Docs
+
+| Doc | Type |
+|---|---|
+| `docs/project-triage-snapshot-2026-02-18.md` | Snapshot |
+
+## Maintenance Recommendations
+
+1. Update `commands-reference` whenever CLI surface changes.
+2. Update `providers-reference` when provider catalog/aliases/env vars change.
+3. Update `channels-reference` when channel support or allowlist semantics change.
+4. Keep snapshots date-stamped and immutable.
+5. Mark proposal docs clearly to avoid being mistaken for runtime contracts.
+6. Keep localized README/docs-hub links aligned when adding new core docs.
+7. Update `docs/SUMMARY.md` and collection indexes whenever new major docs are added.

docs/frictionless-security.md

@@ -1,5 +1,10 @@
 # Frictionless Security: Zero Impact on Wizard
 
+> ⚠️ **Status: Proposal / Roadmap**
+>
+> This document describes proposed approaches and may include hypothetical commands or config.
+> For current runtime behavior, see [config-reference.md](config-reference.md), [operations-runbook.md](operations-runbook.md), and [troubleshooting.md](troubleshooting.md).
+
 ## Core Principle
 > **"Security features should be like airbags — present, protective, and invisible until needed."**
 

docs/getting-started/README.md

@@ -0,0 +1,20 @@
+# Getting Started Docs
+
+For first-time setup and quick orientation.
+
+## Start Path
+
+1. Main overview and quick start: [../../README.md](../../README.md)
+2. One-click setup and dual bootstrap mode: [../one-click-bootstrap.md](../one-click-bootstrap.md)
+3. Find commands by tasks: [../commands-reference.md](../commands-reference.md)
+
+## Onboarding and Validation
+
+- Quick onboarding: `zeroclaw onboard --api-key "sk-..." --provider openrouter`
+- Interactive onboarding: `zeroclaw onboard --interactive`
+- Validate environment: `zeroclaw status` + `zeroclaw doctor`
+
+## Next
+
+- Runtime operations: [../operations/README.md](../operations/README.md)
+- Reference catalogs: [../reference/README.md](../reference/README.md)

docs/hardware/README.md

@@ -0,0 +1,14 @@
+# Hardware & Peripherals Docs
+
+For board integration, firmware flow, and peripheral architecture.
+
+## Entry Points
+
+- Architecture and peripheral model: [../hardware-peripherals-design.md](../hardware-peripherals-design.md)
+- Add a new board/tool: [../adding-boards-and-tools.md](../adding-boards-and-tools.md)
+- Nucleo setup: [../nucleo-setup.md](../nucleo-setup.md)
+- Arduino Uno R4 WiFi setup: [../arduino-uno-q-setup.md](../arduino-uno-q-setup.md)
+
+## Datasheets
+
+- Board/chip datasheets: [../datasheets](../datasheets)

docs/mattermost-setup.md

@@ -18,10 +18,10 @@ ZeroClaw supports native integration with Mattermost via its REST API v4. This i
 
 ## Configuration
 
-Add the following to your `config.toml` under the `[channels]` section:
+Add the following to your `config.toml` under the `[channels_config]` section:
 
 ```toml
-[channels.mattermost]
+[channels_config.mattermost]
 url = "https://mm.your-domain.com"
 bot_token = "your-bot-access-token"
 channel_id = "your-channel-id"

docs/network-deployment.md

@@ -59,14 +59,14 @@ allowed_users = []
 
 [gateway]
 host = "127.0.0.1"
-port = 8080
+port = 3000
 allow_public_bind = false
 ```
 
 ### 2.4 Run Daemon (Local Only)
 
 ```bash
-zeroclaw daemon --host 127.0.0.1 --port 8080
+zeroclaw daemon --host 127.0.0.1 --port 3000
 ```
 
 - Gateway binds to `127.0.0.1` — not reachable from other machines
@@ -84,12 +84,12 @@ To allow other devices on your LAN to hit the gateway (e.g. for pairing or webho
 ```toml
 [gateway]
 host = "0.0.0.0"
-port = 8080
+port = 3000
 allow_public_bind = true
 ```
 
 ```bash
-zeroclaw daemon --host 0.0.0.0 --port 8080
+zeroclaw daemon --host 0.0.0.0 --port 3000
 ```
 
 **Security:** `allow_public_bind = true` exposes the gateway to your local network. Only use on trusted LANs.
@@ -100,7 +100,7 @@ If you need a **public URL** (e.g. WhatsApp webhook, external clients):
 
 1. Run gateway on localhost:
    ```bash
-   zeroclaw daemon --host 127.0.0.1 --port 8080
+   zeroclaw daemon --host 127.0.0.1 --port 3000
    ```
 
 2. Start a tunnel:
@@ -177,13 +177,13 @@ provider = "ngrok"
 
 Or run ngrok manually:
 ```bash
-ngrok http 8080
+ngrok http 3000
 # Use the HTTPS URL for your webhook
 ```
 
 ### 5.3 Cloudflare Tunnel
 
-Configure Cloudflare Tunnel to forward to `127.0.0.1:8080`, then set your webhook URL to the tunnel's public hostname.
+Configure Cloudflare Tunnel to forward to `127.0.0.1:3000`, then set your webhook URL to the tunnel's public hostname.
 
 ---
 
@@ -191,7 +191,7 @@ Configure Cloudflare Tunnel to forward to `127.0.0.1:8080`, then set your webhoo
 
 - [ ] Build with `--features hardware` (and `peripheral-rpi` if using native GPIO)
 - [ ] Configure `[peripherals]` and `[channels_config.telegram]`
-- [ ] Run `zeroclaw daemon --host 127.0.0.1 --port 8080` (Telegram works without 0.0.0.0)
+- [ ] Run `zeroclaw daemon --host 127.0.0.1 --port 3000` (Telegram works without 0.0.0.0)
 - [ ] For LAN access: `--host 0.0.0.0` + `allow_public_bind = true` in config
 - [ ] For webhooks: use Tailscale, ngrok, or Cloudflare tunnel
 

docs/nucleo-setup.md

@@ -113,7 +113,7 @@ baud = 115200
 ## Phase 4: Run and Test
 
 ```bash
-zeroclaw daemon --host 127.0.0.1 --port 8080
+zeroclaw daemon --host 127.0.0.1 --port 3000
 ```
 
 Or use the agent directly:
@@ -131,7 +131,7 @@ Pin 13 = PA5 = User LED (LD2) on Nucleo-F401RE.
 | Step | Command |
 |------|---------|
 | 1 | Connect Nucleo via USB |
-| 2 | `cargo install probe-rs --locked` |
+| 2 | `cargo install probe-rs-tools --locked` |
 | 3 | `zeroclaw peripheral flash-nucleo` |
 | 4 | Add Nucleo to config.toml (path = your serial port) |
 | 5 | `zeroclaw daemon` or `zeroclaw agent -m "Turn on LED"` |

docs/one-click-bootstrap.md

@@ -0,0 +1,92 @@
+# One-Click Bootstrap
+
+This page defines the fastest supported path to install and initialize ZeroClaw.
+
+Last verified: **February 18, 2026**.
+
+## Option A (Recommended): Clone + local script
+
+```bash
+git clone https://github.com/zeroclaw-labs/zeroclaw.git
+cd zeroclaw
+./bootstrap.sh
+```
+
+What it does by default:
+
+1. `cargo build --release --locked`
+2. `cargo install --path . --force --locked`
+
+## Dual-mode bootstrap
+
+Default behavior is **app-only** (build/install ZeroClaw) and expects existing Rust toolchain.
+
+For fresh machines, enable environment bootstrap explicitly:
+
+```bash
+./bootstrap.sh --install-system-deps --install-rust
+```
+
+Notes:
+
+- `--install-system-deps` installs compiler/build prerequisites (may require `sudo`).
+- `--install-rust` installs Rust via `rustup` when missing.
+
+## Option B: Remote one-liner
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts/bootstrap.sh | bash
+```
+
+For high-security environments, prefer Option A so you can review the script before execution.
+
+Legacy compatibility:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts/install.sh | bash
+```
+
+This legacy endpoint prefers forwarding to `scripts/bootstrap.sh` and falls back to legacy source install if unavailable in that revision.
+
+If you run Option B outside a repository checkout, the bootstrap script automatically clones a temporary workspace, builds, installs, and then cleans it up.
+
+## Optional onboarding modes
+
+### Quick onboarding (non-interactive)
+
+```bash
+./bootstrap.sh --onboard --api-key "sk-..." --provider openrouter
+```
+
+Or with environment variables:
+
+```bash
+ZEROCLAW_API_KEY="sk-..." ZEROCLAW_PROVIDER="openrouter" ./bootstrap.sh --onboard
+```
+
+### Interactive onboarding
+
+```bash
+./bootstrap.sh --interactive-onboard
+```
+
+## Useful flags
+
+- `--install-system-deps`
+- `--install-rust`
+- `--skip-build`
+- `--skip-install`
+- `--provider <id>`
+
+See all options:
+
+```bash
+./bootstrap.sh --help
+```
+
+## Related docs
+
+- [README.md](../README.md)
+- [commands-reference.md](commands-reference.md)
+- [providers-reference.md](providers-reference.md)
+- [channels-reference.md](channels-reference.md)

docs/operations-runbook.md

@@ -0,0 +1,128 @@
+# ZeroClaw Operations Runbook
+
+This runbook is for operators who maintain availability, security posture, and incident response.
+
+Last verified: **February 18, 2026**.
+
+## Scope
+
+Use this document for day-2 operations:
+
+- starting and supervising runtime
+- health checks and diagnostics
+- safe rollout and rollback
+- incident triage and recovery
+
+For first-time installation, start from [one-click-bootstrap.md](one-click-bootstrap.md).
+
+## Runtime Modes
+
+| Mode | Command | When to use |
+|---|---|---|
+| Foreground runtime | `zeroclaw daemon` | local debugging, short-lived sessions |
+| Foreground gateway only | `zeroclaw gateway` | webhook endpoint testing |
+| User service | `zeroclaw service install && zeroclaw service start` | persistent operator-managed runtime |
+
+## Baseline Operator Checklist
+
+1. Validate configuration:
+
+```bash
+zeroclaw status
+```
+
+2. Verify diagnostics:
+
+```bash
+zeroclaw doctor
+zeroclaw channel doctor
+```
+
+3. Start runtime:
+
+```bash
+zeroclaw daemon
+```
+
+4. For persistent user session service:
+
+```bash
+zeroclaw service install
+zeroclaw service start
+zeroclaw service status
+```
+
+## Health and State Signals
+
+| Signal | Command / File | Expected |
+|---|---|---|
+| Config validity | `zeroclaw doctor` | no critical errors |
+| Channel connectivity | `zeroclaw channel doctor` | configured channels healthy |
+| Runtime summary | `zeroclaw status` | expected provider/model/channels |
+| Daemon heartbeat/state | `~/.zeroclaw/daemon_state.json` | file updates periodically |
+
+## Logs and Diagnostics
+
+### macOS / Windows (service wrapper logs)
+
+- `~/.zeroclaw/logs/daemon.stdout.log`
+- `~/.zeroclaw/logs/daemon.stderr.log`
+
+### Linux (systemd user service)
+
+```bash
+journalctl --user -u zeroclaw.service -f
+```
+
+## Incident Triage Flow (Fast Path)
+
+1. Snapshot system state:
+
+```bash
+zeroclaw status
+zeroclaw doctor
+zeroclaw channel doctor
+```
+
+2. Check service state:
+
+```bash
+zeroclaw service status
+```
+
+3. If service is unhealthy, restart cleanly:
+
+```bash
+zeroclaw service stop
+zeroclaw service start
+```
+
+4. If channels still fail, verify allowlists and credentials in `~/.zeroclaw/config.toml`.
+
+5. If gateway is involved, verify bind/auth settings (`[gateway]`) and local reachability.
+
+## Safe Change Procedure
+
+Before applying config changes:
+
+1. backup `~/.zeroclaw/config.toml`
+2. apply one logical change at a time
+3. run `zeroclaw doctor`
+4. restart daemon/service
+5. verify with `status` + `channel doctor`
+
+## Rollback Procedure
+
+If a rollout regresses behavior:
+
+1. restore previous `config.toml`
+2. restart runtime (`daemon` or `service`)
+3. confirm recovery via `doctor` and channel health checks
+4. document incident root cause and mitigation
+
+## Related Docs
+
+- [one-click-bootstrap.md](one-click-bootstrap.md)
+- [troubleshooting.md](troubleshooting.md)
+- [config-reference.md](config-reference.md)
+- [commands-reference.md](commands-reference.md)

docs/operations/README.md

@@ -0,0 +1,23 @@
+# Operations & Deployment Docs
+
+For operators running ZeroClaw in persistent or production-like environments.
+
+## Core Operations
+
+- Day-2 runbook: [../operations-runbook.md](../operations-runbook.md)
+- Troubleshooting matrix: [../troubleshooting.md](../troubleshooting.md)
+- Safe network/gateway deployment: [../network-deployment.md](../network-deployment.md)
+- Mattermost setup (channel-specific): [../mattermost-setup.md](../mattermost-setup.md)
+
+## Common Flow
+
+1. Validate runtime (`status`, `doctor`, `channel doctor`)
+2. Apply one config change at a time
+3. Restart service/daemon
+4. Verify channel and gateway health
+5. Roll back quickly if behavior regresses
+
+## Related
+
+- Config reference: [../config-reference.md](../config-reference.md)
+- Security collection: [../security/README.md](../security/README.md)

docs/project-triage-snapshot-2026-02-18.md

@@ -0,0 +1,94 @@
+# ZeroClaw Project Triage Snapshot (2026-02-18)
+
+As-of date: **February 18, 2026**.
+
+This snapshot captures open PR/issue signals to guide docs and information-architecture work.
+
+## Data Source
+
+Collected via GitHub CLI against `zeroclaw-labs/zeroclaw`:
+
+- `gh repo view ...`
+- `gh pr list --state open --limit 500 ...`
+- `gh issue list --state open --limit 500 ...`
+- `gh pr/issue view <id> ...` for docs-relevant items
+
+## Repository Pulse
+
+- Open PRs: **30**
+- Open Issues: **24**
+- Stars: **11,220**
+- Forks: **1,123**
+- Default branch: `main`
+- License metadata on GitHub API: `Other` (not MIT-detected)
+
+## PR Label Pressure (Open PRs)
+
+Top signals by frequency:
+
+1. `risk: high` — 24
+2. `experienced contributor` — 14
+3. `size: S` — 14
+4. `ci` — 11
+5. `size: XS` — 10
+6. `dependencies` — 7
+7. `principal contributor` — 6
+
+Implication for docs:
+
+- CI/security/service changes remain high-churn areas.
+- Operator-facing docs should prioritize “what changed” visibility and fast troubleshooting paths.
+
+## Issue Label Pressure (Open Issues)
+
+Top signals by frequency:
+
+1. `experienced contributor` — 12
+2. `enhancement` — 8
+3. `bug` — 4
+
+Implication for docs:
+
+- Feature and performance requests still outpace explanatory docs.
+- Troubleshooting and operational references should be kept near the top navigation.
+
+## Docs-Relevant Open PRs
+
+- [#716](https://github.com/zeroclaw-labs/zeroclaw/pull/716) — OpenRC support (service behavior/docs impact)
+- [#725](https://github.com/zeroclaw-labs/zeroclaw/pull/725) — shell completion commands (CLI docs impact)
+- [#732](https://github.com/zeroclaw-labs/zeroclaw/pull/732) — CI action replacement (contributor workflow docs impact)
+- [#759](https://github.com/zeroclaw-labs/zeroclaw/pull/759) — daemon/channel response handling fix (channel troubleshooting impact)
+- [#679](https://github.com/zeroclaw-labs/zeroclaw/pull/679) — pairing lockout accounting change (security behavior docs impact)
+
+## Docs-Relevant Open Issues
+
+- [#426](https://github.com/zeroclaw-labs/zeroclaw/issues/426) — explicit request for clearer capabilities documentation
+- [#666](https://github.com/zeroclaw-labs/zeroclaw/issues/666) — operational runbook and alert/logging guidance request
+- [#745](https://github.com/zeroclaw-labs/zeroclaw/issues/745) — Docker pull failure (`ghcr.io`) suggests deployment troubleshooting demand
+- [#761](https://github.com/zeroclaw-labs/zeroclaw/issues/761) — Armbian compile error highlights platform troubleshooting needs
+- [#758](https://github.com/zeroclaw-labs/zeroclaw/issues/758) — storage backend flexibility request impacts config/reference docs
+
+## Recommended Docs Backlog (Priority Order)
+
+1. **Keep docs IA stable and obvious**
+   - Maintain `docs/SUMMARY.md` + collection indexes as canonical nav.
+   - Keep localized hubs aligned with the same top-level doc map.
+
+2. **Protect operator discoverability**
+   - Keep `operations-runbook` + `troubleshooting` linked in top-level README/hubs.
+   - Add platform-specific troubleshooting snippets when issues repeat.
+
+3. **Track CLI/config drift aggressively**
+   - Update `commands/providers/channels/config` references when PRs touching these surfaces merge.
+
+4. **Separate current behavior from proposals**
+   - Preserve proposal banners in security roadmap docs.
+   - Keep runtime-contract docs (`config/runbook/troubleshooting`) clearly marked.
+
+5. **Maintain snapshot discipline**
+   - Keep snapshots date-stamped and immutable.
+   - Create a new snapshot file for each docs sprint instead of mutating historical snapshots.
+
+## Snapshot Caveat
+
+This is a time-bound snapshot (2026-02-18). Re-run the `gh` queries before planning a new documentation sprint.

docs/project/README.md

@@ -0,0 +1,13 @@
+# Project Snapshot & Triage Docs
+
+Time-bound project status snapshots for planning documentation and operations work.
+
+## Current Snapshot
+
+- [../project-triage-snapshot-2026-02-18.md](../project-triage-snapshot-2026-02-18.md)
+
+## Scope
+
+Use snapshots to understand changing PR/issue pressure and prioritize doc maintenance.
+
+For stable classification of docs intent, use [../docs-inventory.md](../docs-inventory.md).

docs/providers-reference.md

@@ -0,0 +1,89 @@
+# ZeroClaw Providers Reference
+
+This document maps provider IDs, aliases, and credential environment variables.
+
+Last verified: **February 18, 2026**.
+
+## How to List Providers
+
+```bash
+zeroclaw providers
+```
+
+## Credential Resolution Order
+
+Runtime resolution order is:
+
+1. Explicit credential from config/CLI
+2. Provider-specific env var(s)
+3. Generic fallback env vars: `ZEROCLAW_API_KEY` then `API_KEY`
+
+## Provider Catalog
+
+| Canonical ID | Aliases | Local | Provider-specific env var(s) |
+|---|---|---:|---|
+| `openrouter` | — | No | `OPENROUTER_API_KEY` |
+| `anthropic` | — | No | `ANTHROPIC_OAUTH_TOKEN`, `ANTHROPIC_API_KEY` |
+| `openai` | — | No | `OPENAI_API_KEY` |
+| `ollama` | — | Yes | `OLLAMA_API_KEY` (optional) |
+| `gemini` | `google`, `google-gemini` | No | `GEMINI_API_KEY`, `GOOGLE_API_KEY` |
+| `venice` | — | No | `VENICE_API_KEY` |
+| `vercel` | `vercel-ai` | No | `VERCEL_API_KEY` |
+| `cloudflare` | `cloudflare-ai` | No | `CLOUDFLARE_API_KEY` |
+| `moonshot` | `kimi` | No | `MOONSHOT_API_KEY` |
+| `synthetic` | — | No | `SYNTHETIC_API_KEY` |
+| `opencode` | `opencode-zen` | No | `OPENCODE_API_KEY` |
+| `zai` | `z.ai` | No | `ZAI_API_KEY` |
+| `glm` | `zhipu` | No | `GLM_API_KEY` |
+| `minimax` | — | No | `MINIMAX_API_KEY` |
+| `bedrock` | `aws-bedrock` | No | (use config/`API_KEY` fallback) |
+| `qianfan` | `baidu` | No | `QIANFAN_API_KEY` |
+| `qwen` | `dashscope`, `qwen-intl`, `dashscope-intl`, `qwen-us`, `dashscope-us` | No | `DASHSCOPE_API_KEY` |
+| `groq` | — | No | `GROQ_API_KEY` |
+| `mistral` | — | No | `MISTRAL_API_KEY` |
+| `xai` | `grok` | No | `XAI_API_KEY` |
+| `deepseek` | — | No | `DEEPSEEK_API_KEY` |
+| `together` | `together-ai` | No | `TOGETHER_API_KEY` |
+| `fireworks` | `fireworks-ai` | No | `FIREWORKS_API_KEY` |
+| `perplexity` | — | No | `PERPLEXITY_API_KEY` |
+| `cohere` | — | No | `COHERE_API_KEY` |
+| `copilot` | `github-copilot` | No | (use config/`API_KEY` fallback with GitHub token) |
+| `lmstudio` | `lm-studio` | Yes | (optional; local by default) |
+| `nvidia` | `nvidia-nim`, `build.nvidia.com` | No | `NVIDIA_API_KEY` |
+
+## Custom Endpoints
+
+- OpenAI-compatible endpoint:
+
+```toml
+default_provider = "custom:https://your-api.example.com"
+```
+
+- Anthropic-compatible endpoint:
+
+```toml
+default_provider = "anthropic-custom:https://your-api.example.com"
+```
+
+## Model Routing (`hint:<name>`)
+
+You can route model calls by hint using `[[model_routes]]`:
+
+```toml
+[[model_routes]]
+hint = "reasoning"
+provider = "openrouter"
+model = "anthropic/claude-opus-4-20250514"
+
+[[model_routes]]
+hint = "fast"
+provider = "groq"
+model = "llama-3.3-70b-versatile"
+```
+
+Then call with a hint model name (for example from tool or integration paths):
+
+```text
+hint:reasoning
+```
+

docs/reference/README.md

@@ -0,0 +1,14 @@
+# Reference Catalogs
+
+Structured reference index for commands, providers, channels, and config.
+
+## Core References
+
+- Commands by workflow: [../commands-reference.md](../commands-reference.md)
+- Provider IDs / aliases / env vars: [../providers-reference.md](../providers-reference.md)
+- Channel setup + allowlists: [../channels-reference.md](../channels-reference.md)
+- Config defaults and keys: [../config-reference.md](../config-reference.md)
+
+## Usage
+
+Use this collection when you need precise CLI/config details rather than step-by-step tutorials.

docs/resource-limits.md

@@ -1,5 +1,10 @@
 # Resource Limits for ZeroClaw
 
+> ⚠️ **Status: Proposal / Roadmap**
+>
+> This document describes proposed approaches and may include hypothetical commands or config.
+> For current runtime behavior, see [config-reference.md](config-reference.md), [operations-runbook.md](operations-runbook.md), and [troubleshooting.md](troubleshooting.md).
+
 ## Problem
 ZeroClaw has rate limiting (20 actions/hour) but no resource caps. A runaway agent could:
 - Exhaust available memory

docs/sandboxing.md

@@ -1,5 +1,10 @@
 # ZeroClaw Sandboxing Strategies
 
+> ⚠️ **Status: Proposal / Roadmap**
+>
+> This document describes proposed approaches and may include hypothetical commands or config.
+> For current runtime behavior, see [config-reference.md](config-reference.md), [operations-runbook.md](operations-runbook.md), and [troubleshooting.md](troubleshooting.md).
+
 ## Problem
 ZeroClaw currently has application-layer security (allowlists, path blocking, command injection protection) but lacks OS-level containment. If an attacker is on the allowlist, they can run any allowed command with zeroclaw's user permissions.
 

docs/security-roadmap.md

@@ -1,5 +1,10 @@
 # ZeroClaw Security Improvement Roadmap
 
+> ⚠️ **Status: Proposal / Roadmap**
+>
+> This document describes proposed approaches and may include hypothetical commands or config.
+> For current runtime behavior, see [config-reference.md](config-reference.md), [operations-runbook.md](operations-runbook.md), and [troubleshooting.md](troubleshooting.md).
+
 ## Current State: Strong Foundation
 
 ZeroClaw already has **excellent application-layer security**:

docs/security/README.md

@@ -0,0 +1,22 @@
+# Security Docs
+
+This section mixes current hardening guidance and proposal/roadmap documents.
+
+## Current-Behavior First
+
+For current runtime behavior, start here:
+
+- Config reference: [../config-reference.md](../config-reference.md)
+- Operations runbook: [../operations-runbook.md](../operations-runbook.md)
+- Troubleshooting: [../troubleshooting.md](../troubleshooting.md)
+
+## Proposal / Roadmap Docs
+
+The following docs are explicitly proposal-oriented and may include hypothetical CLI/config examples:
+
+- [../agnostic-security.md](../agnostic-security.md)
+- [../frictionless-security.md](../frictionless-security.md)
+- [../sandboxing.md](../sandboxing.md)
+- [../resource-limits.md](../resource-limits.md)
+- [../audit-logging.md](../audit-logging.md)
+- [../security-roadmap.md](../security-roadmap.md)

docs/troubleshooting.md

@@ -0,0 +1,154 @@
+# ZeroClaw Troubleshooting
+
+This guide focuses on common setup/runtime failures and fast resolution paths.
+
+Last verified: **February 18, 2026**.
+
+## Installation / Bootstrap
+
+### `cargo` not found
+
+Symptom:
+
+- bootstrap exits with `cargo is not installed`
+
+Fix:
+
+```bash
+./bootstrap.sh --install-rust
+```
+
+Or install from <https://rustup.rs/>.
+
+### Missing system build dependencies
+
+Symptom:
+
+- build fails due to compiler or `pkg-config` issues
+
+Fix:
+
+```bash
+./bootstrap.sh --install-system-deps
+```
+
+### `zeroclaw` command not found after install
+
+Symptom:
+
+- install succeeds but shell cannot find `zeroclaw`
+
+Fix:
+
+```bash
+export PATH="$HOME/.cargo/bin:$PATH"
+which zeroclaw
+```
+
+Persist in your shell profile if needed.
+
+## Runtime / Gateway
+
+### Gateway unreachable
+
+Checks:
+
+```bash
+zeroclaw status
+zeroclaw doctor
+```
+
+Verify `~/.zeroclaw/config.toml`:
+
+- `[gateway].host` (default `127.0.0.1`)
+- `[gateway].port` (default `3000`)
+- `allow_public_bind` only when intentionally exposing LAN/public interfaces
+
+### Pairing / auth failures on webhook
+
+Checks:
+
+1. Ensure pairing completed (`/pair` flow)
+2. Ensure bearer token is current
+3. Re-run diagnostics:
+
+```bash
+zeroclaw doctor
+```
+
+## Channel Issues
+
+### Telegram conflict: `terminated by other getUpdates request`
+
+Cause:
+
+- multiple pollers using same bot token
+
+Fix:
+
+- keep only one active runtime for that token
+- stop extra `zeroclaw daemon` / `zeroclaw channel start` processes
+
+### Channel unhealthy in `channel doctor`
+
+Checks:
+
+```bash
+zeroclaw channel doctor
+```
+
+Then verify channel-specific credentials + allowlist fields in config.
+
+## Service Mode
+
+### Service installed but not running
+
+Checks:
+
+```bash
+zeroclaw service status
+```
+
+Recovery:
+
+```bash
+zeroclaw service stop
+zeroclaw service start
+```
+
+Linux logs:
+
+```bash
+journalctl --user -u zeroclaw.service -f
+```
+
+## Legacy Installer Compatibility
+
+Both still work:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts/bootstrap.sh | bash
+curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts/install.sh | bash
+```
+
+`install.sh` is a compatibility entry and forwards/falls back to bootstrap behavior.
+
+## Still Stuck?
+
+Collect and include these outputs when filing an issue:
+
+```bash
+zeroclaw --version
+zeroclaw status
+zeroclaw doctor
+zeroclaw channel doctor
+```
+
+Also include OS, install method, and sanitized config snippets (no secrets).
+
+## Related Docs
+
+- [operations-runbook.md](operations-runbook.md)
+- [one-click-bootstrap.md](one-click-bootstrap.md)
+- [channels-reference.md](channels-reference.md)
+- [network-deployment.md](network-deployment.md)

scripts/bootstrap.sh

@@ -0,0 +1,314 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+info() {
+  echo "==> $*"
+}
+
+warn() {
+  echo "warning: $*" >&2
+}
+
+error() {
+  echo "error: $*" >&2
+}
+
+usage() {
+  cat <<'USAGE'
+ZeroClaw one-click bootstrap
+
+Usage:
+  ./bootstrap.sh [options]
+
+Modes:
+  Default mode installs/builds ZeroClaw only (requires existing Rust toolchain).
+  Optional bootstrap mode can also install system dependencies and Rust.
+
+Options:
+  --install-system-deps      Install build dependencies (Linux/macOS)
+  --install-rust             Install Rust via rustup if missing
+  --onboard                  Run onboarding after install
+  --interactive-onboard      Run interactive onboarding (implies --onboard)
+  --api-key <key>            API key for non-interactive onboarding
+  --provider <id>            Provider for non-interactive onboarding (default: openrouter)
+  --skip-build               Skip `cargo build --release --locked`
+  --skip-install             Skip `cargo install --path . --force --locked`
+  -h, --help                 Show help
+
+Examples:
+  ./bootstrap.sh
+  ./bootstrap.sh --install-system-deps --install-rust
+  ./bootstrap.sh --onboard --api-key "sk-..." --provider openrouter
+  ./bootstrap.sh --interactive-onboard
+
+  # Remote one-liner
+  curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts/bootstrap.sh | bash
+
+Environment:
+  ZEROCLAW_API_KEY           Used when --api-key is not provided
+  ZEROCLAW_PROVIDER          Used when --provider is not provided (default: openrouter)
+USAGE
+}
+
+have_cmd() {
+  command -v "$1" >/dev/null 2>&1
+}
+
+run_privileged() {
+  if [[ "$(id -u)" -eq 0 ]]; then
+    "$@"
+  elif have_cmd sudo; then
+    sudo "$@"
+  else
+    error "sudo is required to install system dependencies."
+    return 1
+  fi
+}
+
+install_system_deps() {
+  info "Installing system dependencies"
+
+  case "$(uname -s)" in
+    Linux)
+      if have_cmd apt-get; then
+        run_privileged apt-get update -qq
+        run_privileged apt-get install -y build-essential pkg-config git curl
+      elif have_cmd dnf; then
+        run_privileged dnf groupinstall -y "Development Tools"
+        run_privileged dnf install -y pkg-config git curl
+      else
+        warn "Unsupported Linux distribution. Install compiler toolchain + pkg-config + git + curl manually."
+      fi
+      ;;
+    Darwin)
+      if ! xcode-select -p >/dev/null 2>&1; then
+        info "Installing Xcode Command Line Tools"
+        xcode-select --install || true
+        cat <<'MSG'
+Please complete the Xcode Command Line Tools installation dialog,
+then re-run bootstrap.
+MSG
+        exit 0
+      fi
+      if ! have_cmd git; then
+        warn "git is not available. Install git (e.g., Homebrew) and re-run bootstrap."
+      fi
+      ;;
+    *)
+      warn "Unsupported OS for automatic dependency install. Continuing without changes."
+      ;;
+  esac
+}
+
+install_rust_toolchain() {
+  if have_cmd cargo && have_cmd rustc; then
+    info "Rust already installed: $(rustc --version)"
+    return
+  fi
+
+  if ! have_cmd curl; then
+    error "curl is required to install Rust via rustup."
+    exit 1
+  fi
+
+  info "Installing Rust via rustup"
+  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
+
+  if [[ -f "$HOME/.cargo/env" ]]; then
+    # shellcheck disable=SC1090
+    source "$HOME/.cargo/env"
+  fi
+
+  if ! have_cmd cargo; then
+    error "Rust installation completed but cargo is still unavailable in PATH."
+    error "Run: source \"$HOME/.cargo/env\""
+    exit 1
+  fi
+}
+
+SCRIPT_PATH="${BASH_SOURCE[0]:-$0}"
+SCRIPT_DIR="$(cd "$(dirname "$SCRIPT_PATH")" >/dev/null 2>&1 && pwd || pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/.." >/dev/null 2>&1 && pwd || pwd)"
+REPO_URL="https://github.com/zeroclaw-labs/zeroclaw.git"
+
+INSTALL_SYSTEM_DEPS=false
+INSTALL_RUST=false
+RUN_ONBOARD=false
+INTERACTIVE_ONBOARD=false
+SKIP_BUILD=false
+SKIP_INSTALL=false
+API_KEY="${ZEROCLAW_API_KEY:-}"
+PROVIDER="${ZEROCLAW_PROVIDER:-openrouter}"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --install-system-deps)
+      INSTALL_SYSTEM_DEPS=true
+      shift
+      ;;
+    --install-rust)
+      INSTALL_RUST=true
+      shift
+      ;;
+    --onboard)
+      RUN_ONBOARD=true
+      shift
+      ;;
+    --interactive-onboard)
+      RUN_ONBOARD=true
+      INTERACTIVE_ONBOARD=true
+      shift
+      ;;
+    --api-key)
+      API_KEY="${2:-}"
+      [[ -n "$API_KEY" ]] || {
+        error "--api-key requires a value"
+        exit 1
+      }
+      shift 2
+      ;;
+    --provider)
+      PROVIDER="${2:-}"
+      [[ -n "$PROVIDER" ]] || {
+        error "--provider requires a value"
+        exit 1
+      }
+      shift 2
+      ;;
+    --skip-build)
+      SKIP_BUILD=true
+      shift
+      ;;
+    --skip-install)
+      SKIP_INSTALL=true
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      error "unknown option: $1"
+      echo
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+if [[ "$INSTALL_SYSTEM_DEPS" == true ]]; then
+  install_system_deps
+fi
+
+if [[ "$INSTALL_RUST" == true ]]; then
+  install_rust_toolchain
+fi
+
+if ! have_cmd cargo; then
+  error "cargo is not installed."
+  cat <<'MSG' >&2
+Install Rust first: https://rustup.rs/
+or re-run with:
+  ./bootstrap.sh --install-rust
+MSG
+  exit 1
+fi
+
+WORK_DIR="$ROOT_DIR"
+TEMP_CLONE=false
+TEMP_DIR=""
+
+cleanup() {
+  if [[ "$TEMP_CLONE" == true && -n "$TEMP_DIR" && -d "$TEMP_DIR" ]]; then
+    rm -rf "$TEMP_DIR"
+  fi
+}
+trap cleanup EXIT
+
+# Support three launch modes:
+# 1) ./bootstrap.sh from repo root
+# 2) scripts/bootstrap.sh from repo
+# 3) curl | bash (no local repo => temporary clone)
+if [[ ! -f "$WORK_DIR/Cargo.toml" ]]; then
+  if [[ -f "$(pwd)/Cargo.toml" ]]; then
+    WORK_DIR="$(pwd)"
+  else
+    if ! have_cmd git; then
+      error "git is required when running bootstrap outside a local repository checkout."
+      if [[ "$INSTALL_SYSTEM_DEPS" == false ]]; then
+        error "Re-run with --install-system-deps or install git manually."
+      fi
+      exit 1
+    fi
+
+    TEMP_DIR="$(mktemp -d -t zeroclaw-bootstrap-XXXXXX)"
+    info "No local repository detected; cloning latest main branch"
+    git clone --depth 1 "$REPO_URL" "$TEMP_DIR"
+    WORK_DIR="$TEMP_DIR"
+    TEMP_CLONE=true
+  fi
+fi
+
+info "ZeroClaw bootstrap"
+echo "    workspace: $WORK_DIR"
+
+cd "$WORK_DIR"
+
+if [[ "$SKIP_BUILD" == false ]]; then
+  info "Building release binary"
+  cargo build --release --locked
+else
+  info "Skipping build"
+fi
+
+if [[ "$SKIP_INSTALL" == false ]]; then
+  info "Installing zeroclaw to cargo bin"
+  cargo install --path "$WORK_DIR" --force --locked
+else
+  info "Skipping install"
+fi
+
+ZEROCLAW_BIN=""
+if have_cmd zeroclaw; then
+  ZEROCLAW_BIN="zeroclaw"
+elif [[ -x "$WORK_DIR/target/release/zeroclaw" ]]; then
+  ZEROCLAW_BIN="$WORK_DIR/target/release/zeroclaw"
+fi
+
+if [[ "$RUN_ONBOARD" == true ]]; then
+  if [[ -z "$ZEROCLAW_BIN" ]]; then
+    error "onboarding requested but zeroclaw binary is not available."
+    error "Run without --skip-install, or ensure zeroclaw is in PATH."
+    exit 1
+  fi
+
+  if [[ "$INTERACTIVE_ONBOARD" == true ]]; then
+    info "Running interactive onboarding"
+    "$ZEROCLAW_BIN" onboard --interactive
+  else
+    if [[ -z "$API_KEY" ]]; then
+      cat <<'MSG'
+==> Onboarding requested, but API key not provided.
+Use either:
+  --api-key "sk-..."
+or:
+  ZEROCLAW_API_KEY="sk-..." ./bootstrap.sh --onboard
+or run interactive:
+  ./bootstrap.sh --interactive-onboard
+MSG
+      exit 1
+    fi
+    info "Running quick onboarding (provider: $PROVIDER)"
+    "$ZEROCLAW_BIN" onboard --api-key "$API_KEY" --provider "$PROVIDER"
+  fi
+fi
+
+cat <<'DONE'
+
+✅ Bootstrap complete.
+
+Next steps:
+  zeroclaw status
+  zeroclaw agent -m "Hello, ZeroClaw!"
+  zeroclaw gateway
+DONE

scripts/install.sh

@@ -1,151 +1,58 @@
 #!/usr/bin/env bash
-# install.sh — Build and install ZeroClaw from source.
-# Usage:
-#   curl -LsSf https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts/install.sh | bash
-#   # or
-#   bash scripts/install.sh
-
 set -euo pipefail
 
-# --- Logging --------------------------------------------------------------
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" >/dev/null 2>&1 && pwd || pwd)"
+BOOTSTRAP_LOCAL="$SCRIPT_DIR/bootstrap.sh"
+REPO_URL="https://github.com/zeroclaw-labs/zeroclaw.git"
 
-info()  { printf ">>> %s\n" "$*"; }
-warn()  { printf ">>> [WARN] %s\n" "$*"; }
-error() { printf ">>> [ERROR] %s\n" "$*" >&2; }
-die()   { error "$@"; exit 1; }
+echo "[deprecated] scripts/install.sh -> bootstrap.sh" >&2
 
-# --- Step 1: Detect OS and install system dependencies --------------------
-
-install_system_deps() {
-    info "Detecting operating system..."
-
-    local os
-    os="$(uname -s)"
-
-    case "${os}" in
-        Linux)
-            install_linux_deps
-            ;;
-        Darwin)
-            install_macos_deps
-            ;;
-        *)
-            die "Unsupported operating system: ${os}. Only Linux and macOS are supported."
-            ;;
-    esac
-}
-
-install_linux_deps() {
-    if command -v apt-get >/dev/null 2>&1; then
-        info "Detected Debian/Ubuntu — installing build-essential, pkg-config, git..."
-        sudo apt-get update -qq
-        sudo apt-get install -y build-essential pkg-config git
-    elif command -v dnf >/dev/null 2>&1; then
-        info "Detected Fedora/RHEL — installing Development Tools, pkg-config, git..."
-        sudo dnf groupinstall -y "Development Tools"
-        sudo dnf install -y pkg-config git
-    else
-        die "Unsupported Linux distribution. Please install a C compiler, pkg-config, and git manually, then re-run this script."
-    fi
-}
-
-install_macos_deps() {
-    if ! xcode-select -p >/dev/null 2>&1; then
-        info "Installing Xcode Command Line Tools..."
-        xcode-select --install
-        warn "A dialog may have appeared. Please complete the Xcode CLT installation, then re-run this script."
-        exit 0
-    else
-        info "Xcode Command Line Tools already installed."
+if [[ -f "$BOOTSTRAP_LOCAL" ]]; then
+  exec "$BOOTSTRAP_LOCAL" "$@"
 fi
 
 if ! command -v git >/dev/null 2>&1; then
-        die "git not found. Please install git (e.g. via Homebrew) and re-run this script."
-    fi
-}
-
-# --- Step 2: Install Rust -------------------------------------------------
-
-install_rust() {
-    if command -v rustc >/dev/null 2>&1; then
-        info "Rust already installed ($(rustc --version))."
-    else
-        info "Installing Rust via rustup..."
-        curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
-        # shellcheck source=/dev/null
-        source "${HOME}/.cargo/env"
-        info "Rust installed ($(rustc --version))."
-    fi
-}
-
-# --- Step 3: Clone repository ---------------------------------------------
-
-CLONE_DIR="/tmp/zeroclaw-install"
-
-clone_repo() {
-    if [ -d "${CLONE_DIR}" ]; then
-        info "Removing previous clone at ${CLONE_DIR}..."
-        rm -rf "${CLONE_DIR}"
+  echo "error: git is required for legacy install.sh remote mode" >&2
+  exit 1
 fi
 
-    info "Cloning ZeroClaw repository..."
-    git clone --depth 1 https://github.com/zeroclaw-labs/zeroclaw.git "${CLONE_DIR}"
-}
-
-# --- Step 4: Build and install --------------------------------------------
-
-build_and_install() {
-    info "Building ZeroClaw (release mode)..."
-    cargo build --release --locked --manifest-path "${CLONE_DIR}/Cargo.toml"
-
-    info "Installing ZeroClaw binary..."
-    cargo install --path "${CLONE_DIR}" --force --locked
-}
-
-# --- Step 5: Cleanup ------------------------------------------------------
-
+TEMP_DIR="$(mktemp -d -t zeroclaw-install-XXXXXX)"
 cleanup() {
-    info "Cleaning up build directory..."
-    rm -rf "${CLONE_DIR}"
+  rm -rf "$TEMP_DIR"
 }
+trap cleanup EXIT
 
-# --- Step 6: Success message ----------------------------------------------
+git clone --depth 1 "$REPO_URL" "$TEMP_DIR" >/dev/null 2>&1
 
-print_success() {
-    echo ""
-    info "ZeroClaw installed successfully!"
-    echo ""
-    echo "  To use zeroclaw in your current shell, run:"
-    echo ""
-    echo "    source \"\${HOME}/.cargo/env\""
-    echo ""
-    echo "  To make it permanent, add the line above to your shell profile"
-    echo "  (~/.bashrc, ~/.zshrc, etc.)."
-    echo ""
-    echo "  Then get started:"
-    echo ""
-    echo "    zeroclaw onboard"
-    echo ""
-}
+if [[ -x "$TEMP_DIR/scripts/bootstrap.sh" ]]; then
+  "$TEMP_DIR/scripts/bootstrap.sh" "$@"
+  exit 0
+fi
 
-# --- Main -----------------------------------------------------------------
+echo "[deprecated] cloned revision has no bootstrap.sh; falling back to legacy source install flow" >&2
 
-main() {
-    echo ""
-    info "ZeroClaw — Source Install"
-    echo ""
+if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
+  cat <<'USAGE'
+Legacy install.sh fallback mode
 
-    install_system_deps
-    echo ""
-    install_rust
-    echo ""
-    clone_repo
-    echo ""
-    build_and_install
-    echo ""
-    cleanup
-    echo ""
-    print_success
-}
+Behavior:
+  - Clone repository
+  - cargo build --release --locked
+  - cargo install --path <clone> --force --locked
 
-main
+For the new dual-mode installer, use:
+  ./bootstrap.sh --help
+USAGE
+  exit 0
+fi
+
+if ! command -v cargo >/dev/null 2>&1; then
+  echo "error: cargo is required for legacy install.sh fallback mode" >&2
+  echo "Install Rust first: https://rustup.rs/" >&2
+  exit 1
+fi
+
+cargo build --release --locked --manifest-path "$TEMP_DIR/Cargo.toml"
+cargo install --path "$TEMP_DIR" --force --locked
+
+echo "Legacy source install completed." >&2