docs: overhaul docs IA and multilingual navigation

2026-02-18 16:53:26 +08:00 · 2026-02-18 16:53:26 +08:00 · 93e5383cb2
commit 93e5383cb2
parent 5e800c38f1
40 changed files with 2495 additions and 198 deletions
--- a/docs/README.ja.md
+++ b/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)
--- a/docs/README.md
+++ b/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)
--- a/docs/README.ru.md
+++ b/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)
--- a/docs/README.zh-CN.md
+++ b/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)
--- a/docs/SUMMARY.md
+++ b/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)
--- a/docs/adding-boards-and-tools.md
+++ b/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
--- a/docs/agnostic-security.md
+++ b/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)?
--- a/docs/arduino-uno-q-setup.md
+++ b/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 |

 ---
--- a/docs/audit-logging.md
+++ b/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
--- a/docs/channels-reference.md
+++ b/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)
--- a/docs/commands-reference.md
+++ b/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
+```
+
--- a/docs/config-reference.md
+++ b/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)
--- a/docs/contributing/README.md
+++ b/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`
--- a/docs/docs-inventory.md
+++ b/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.
--- a/docs/frictionless-security.md
+++ b/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."**

--- a/docs/getting-started/README.md
+++ b/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)
--- a/docs/hardware/README.md
+++ b/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)
--- a/docs/mattermost-setup.md
+++ b/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"
--- a/docs/network-deployment.md
+++ b/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

--- a/docs/nucleo-setup.md
+++ b/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"` |
--- a/docs/one-click-bootstrap.md
+++ b/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)
--- a/docs/operations-runbook.md
+++ b/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)
--- a/docs/operations/README.md
+++ b/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)
--- a/docs/project-triage-snapshot-2026-02-18.md
+++ b/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.
--- a/docs/project/README.md
+++ b/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).
--- a/docs/providers-reference.md
+++ b/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
+```
+
--- a/docs/reference/README.md
+++ b/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.
--- a/docs/resource-limits.md
+++ b/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
--- a/docs/sandboxing.md
+++ b/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.

--- a/docs/security-roadmap.md
+++ b/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**:
--- a/docs/security/README.md
+++ b/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)
--- a/docs/troubleshooting.md
+++ b/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)